<commit_before># Quiescent

A lightweight ClojureScript abstraction over ReactJS, emphasizing its
ability to (re)render immutable values efficiently.

An obligatory [TodoMVC implementation](https://github.com/levand/todomvc/tree/gh-pages/architecture-examples/quiescent) is available.

See the [documentation](docs.md) for instructions and examples of how
to use Quiescent.

Quiescent is still alpha/experiental software, use at your own risk,
etc.

## Rationale

ReactJS is an extremely interesting approach to UI rendering for
HTML-based web applications. Its core value proposition is to make it
possible to write one set of UI rendering code that works for both
initial creation, and any future updates. Updates are extremely
efficient, because only the minimal set of necessary deltas are
actually sent to the DOM.

In other words, React lets you write your UI code *once*, and still
have a dynamic, data-driven application. Ideally, it eliminates any
need to write explicit UI manipulation code. Instead, you are
responsible only for supplying a specification of what the UI should
look like, given certain data. The ReactJS implementation takes care
of all the details of how to morph the existing DOM to correspond to
changes in the input data.

Quiescent is intended to expose this feature and *only* this feature
in a way that is convenient and idiomatic to ClojureScript, while
remaining highly efficient.

It has the following design goals:

* **single concern:** Quiescent is designed to do one thing: render and
   re-render HTML from immutable values. It does not attempt to
   participate in state management, inform how you organize your
   application, or force the use of any specific technique for
   managing state updates. Feel free to use atoms, watchers,
   core.async, compilation-based models, message-passing, etc. The
   only requierment is that values passed to Quiescent components are
   immutable value types.
* **avoid OO idioms:** ReactJS is itself highly object-oriented, with
   stateful objects that may implement a variety of
   behaviors. Quiescent provides a purely functional interface,
   allowing users to construct a ReactJS component tree using only the
   basic tools of functional programming: function definition and
   composition.
* **top-down rendering:** All renders and updates are initiated by
   instructing Quiescent to render a particular value to a particular
   location in the DOM. Individual tree components do not maintain
   their own state and do not re-render themselves unless explicitly
   directed to do so.

   This is intended to emulate classical 'rendering' semantics for 2D
   or 3D bitmapped applications, where the entirety of a scene is
   re-drawn from scratch for every frame. Of course, React/Quiescent
   does not actually do this, for performance reasons, but the fact
   that it does not is an implementation detail; the conceptual model
   is the same.
* **leverage immutability:** By assuming that any value provided to a
   rendered component is immutable, Quiescent can prevent ReactJS from
   even calculating if it needs to render sub-trees that have not
   changed from the last time the application was updated. Since
   equality checks are highly efficient in ClojureScript, large
   application structures can be re-rendered frequently with almost no
   performance hit apart from that necessary to re-render leaf nodes
   that actually did change.
* **compatibility:** Although you will hopefully be able to write the
   vast majority of your application using Quiescent's model, if
   absolutely necessary, you can always fall back and use a raw
   ReactJS component (or, for that matter, a ReactJS component<commit_msg>spelling<commit_after># Quiescent

A lightweight ClojureScript abstraction over ReactJS, emphasizing its
ability to (re)render immutable values efficiently.

An obligatory [TodoMVC implementation](https://github.com/levand/todomvc/tree/gh-pages/architecture-examples/quiescent) is available.

See the [documentation](docs.md) for instructions and examples of how
to use Quiescent.

Quiescent is still alpha/experiental software, use at your own risk,
etc.

## Rationale

ReactJS is an extremely interesting approach to UI rendering for
HTML-based web applications. Its core value proposition is to make it
possible to write one set of UI rendering code that works for both
initial creation, and any future updates. Updates are extremely
efficient, because only the minimal set of necessary deltas are
actually sent to the DOM.

In other words, React lets you write your UI code *once*, and still
have a dynamic, data-driven application. Ideally, it eliminates any
need to write explicit UI manipulation code. Instead, you are
responsible only for supplying a specification of what the UI should
look like, given certain data. The ReactJS implementation takes care
of all the details of how to morph the existing DOM to correspond to
changes in the input data.

Quiescent is intended to expose this feature and *only* this feature
in a way that is convenient and idiomatic to ClojureScript, while
remaining highly efficient.

It has the following design goals:

* **single concern:** Quiescent is designed to do one thing: render and
   re-render HTML from immutable values. It does not attempt to
   participate in state management, inform how you organize your
   application, or force the use of any specific technique for
   managing state updates. Feel free to use atoms, watchers,
   core.async, compilation-based models, message-passing, etc. The
   only requirement is that values passed to Quiescent components are
   immutable value types.
* **avoid OO idioms:** ReactJS is itself highly object-oriented, with
   stateful objects that may implement a variety of
   behaviors. Quiescent provides a purely functional interface,
   allowing users to construct a ReactJS component tree using only the
   basic tools of functional programming: function definition and
   composition.
* **top-down rendering:** All renders and updates are initiated by
   instructing Quiescent to render a particular value to a particular
   location in the DOM. Individual tree components do not maintain
   their own state and do not re-render themselves unless explicitly
   directed to do so.

   This is intended to emulate classical 'rendering' semantics for 2D
   or 3D bitmapped applications, where the entirety of a scene is
   re-drawn from scratch for every frame. Of course, React/Quiescent
   does not actually do this, for performance reasons, but the fact
   that it does not is an implementation detail; the conceptual model
   is the same.
* **leverage immutability:** By assuming that any value provided to a
   rendered component is immutable, Quiescent can prevent ReactJS from
   even calculating if it needs to render sub-trees that have not
   changed from the last time the application was updated. Since
   equality checks are highly efficient in ClojureScript, large
   application structures can be re-rendered frequently with almost no
   performance hit apart from that necessary to re-render leaf nodes
   that actually did change.
* **compatibility:** Although you will hopefully be able to write the
   vast majority of your application using Quiescent's model, if
   absolutely necessary, you can always fall back and use a raw
   ReactJS component (or, for that matter, a ReactJS component
{'fraction_non_alphanumeric': 0.037990030984777046, 'fraction_numerical': 0.000538865687727334, 'mean_word_length': 4.375814627081825, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '842935', 'n_tokens_mistral': 1792, 'n_tokens_neox': 1749, 'n_words': 1053}