reacl-c.core — de.active-group/reacl-c 0.2.0

add-state clj/s

(add-state initial lens e)

Adds new state that the element e can access, via a lens on the the tuple of states [outer inner], where the initial value for inner state is initial. Note that the resulting element has only outer as its state.

constantly clj/s

def-dynamic clj/s≠ macro

clj

(def-dynamic name state & body)

cljs

(def-dynamic &form &env name state & body)

A macro to define a new dynamic element. For example, given

(def-dynamic current-state state
  (dom/span "Current state is: " (pr-str state)))

then current-state is an element that shows the current state as it changes over time. This is similar to defn-dynamic but without the arguments.

def-named clj/s macro

(def-named name element)

A macro to define a named element. This is the same as Clojures def, but in addition assigns its name to the element which can be used by testing and debugging utilities.

defn-dynamic clj/s≠ macro

clj

(defn-dynamic name state args & body)

cljs

(defn-dynamic &form &env name state args & body)

A macro to define a new abstract dynamic element. For example, given

(defn-dynamic greeting state [arg]
  (dom/div (str arg " " state)))

You can create a new dynamic element by calling (greeting "Hello"), which looks exactly like

(dom/div (str "Hello" " " "world")

when the current state of the element is state, and changes whenever the state changes.

defn-named clj/s≠ macro

clj

(defn-named name args & body)

cljs

(defn-named &form &env name args & body)

A macro to define an abstract element. This is the same as Clojures defn, but in addition assigns its name to the returned element which can be used by testing and debugging utilities.

defn-subscription clj/s≠ macro

clj

(defn-subscription name deliver! args & body)

cljs

(defn-subscription &form &env name deliver! args & body)

A macro to define the integration of an external source of actions, that needs an imperative way to 'inject' actions into an application. This could be an interval timer, for example:

(defn-subscription interval-timer deliver! [ms]
  (let [id (.setInterval js/window (fn [] (deliver! (js/Date.))) ms)]
    (fn []
      (.clearInterval js/window id))))

With this definition, you can use (interval-timer 1000) as an element in your application. That element will be invisible, but will emit a JavaScript Date object as an action every second.

Note that deliver! must never be called directly in the body of defn-subscription, but only later, from an asynchronous context. Also note that the body is evaluated as soon as the subscription element is mounted into your application, and that it must result in a function with no arguments, which is called when the element is removed from the application afterwards.

deref clj/s

(deref ref)

Returns an implementation specific value, usable as a target in messages sending or to access the native dom elements. See with-ref for a description of references.

did-mount clj/s

(did-mount return)

(did-mount e return)

An element like e, or an invisible element, which emits the state change or action as specified by the given return value when mounted.

did-update clj/s

(did-update e f)

When the mounted element e changes between the did-mount and will-unmount points in the livecycle, (f prev-state prev-e) is called, which must return a return value.

error-boundary clj/s

(error-boundary e f)

Creates an error boundary around the element e. When the rendering of e throws an exception, then (f error) is evaluated, and must result in an return value. Note that exceptions in functions like handle-action, are not catched by this. See try-catch for a higher level construct to handle errors.

first-lens clj/s

A lens over the first element of a vector.

focus clj/s

(focus e lens)

Restricts the state of e to a part of the state of the resulting element, or translates it into a different form, via the given lens.

fragment clj/s

(fragment & children)

Creates an element with a number of child elements, that is otherwise invisible, i.e. the child elements are 'propagated' to the parent element.

handle-action clj/s

(handle-action e f)

Handles actions emitted by e, by evaluating (f action) for each of them. That must return the result of calling return with either a new state, and maybe one or more other actions (or the given action unchanged).

handle-message clj/s

(handle-message e f)

Handles the messages sent to the the resulting element (either via send-message! or return), by calling (f message), which must return a return value. The resulting element otherwise looks and behaves exactly like e.

hide-merged-state clj/s

(hide-merged-state e initial)

Hides a part of the state of an element, which must be a map or record. The hidden part is specified by the given initial value, which can also be a map or record type. The resulting element has the same state as e, except that the keys in initial are removed.

hide-state clj/s

(hide-state e initial lens)

Hides a part of the state of an element e, via a lens that reduces the the tuple of states [outer inner], where the initial value for inner state is initial. The resulting element has only outer as its state.

id-lens clj/s

The identity lens that does not modify the yanked of shoved values.

isolate-state clj/s

(isolate-state initial-state e)

Hides the state of the element e completely, resulting in an element with an arbitrary state that is inaccessible for e.

keyed clj/s

(keyed e key)

Adds an arbitrary identifier for e, which will be used to optimize rendering of it in a list of children of a container element.

map-actions clj/s

(map-actions e f)

Returns an element that emits actions (f action), for each action emitted by e, and otherwise looks an behaves exacly like e.

merge-lens clj/s

A lens over a tuple of maps or records, that yields a merged map of both. If both maps or records have fields of the same name, only the value of the second part of the tuple is used and updated on a change.

monitor-state clj/s

(monitor-state e f & args)

When e changes its state, (f old-state new-state & args) is evaluted for side effects. Note that this is only called when e changes its self 'by itself', not if the state was changed somewhere upwards in the element tree an is only passed down to the resulting element.

named clj/s

(named e name)

Returns an element that looks and works exactly like the element e, but with has the given name, that appears and can be used in testing and debugging utilities.

partial clj/s

return clj/s

(return :state state :action action :message [target message])

Creates a value to be used for example in the function passed to handle-action. All arguments are optional, and :action and :message may be specified more than one, but :state only once. At some points where such a return value is expected, not all options may be valid, but if they are, then

• :state means that the element changes its state to the given value
• :action means that the given action is emitted by the element
• :message means that the given message is sent to the element.

If not :state option is used, the state of the element will not change.

second-lens clj/s

A lens over the second element of a vector.

send-message! clj/s

(send-message! app msg)

Sends a message to a running application, i.e. app must be the value returned from reacl-c.browser/run for example. This can be used together with handle-message in situations where the application is not running standalone, but integrated in a different framework.

set-ref clj/s

(set-ref e ref)

Returns an element identical to e, but with the given reference assigned. Replaces the reference previously assigned to it. See with-ref for a description of references.

try-catch clj/s

(try-catch try-e catch-e)

Returns an element that looks an works the same as the element try-e, until an error is thrown during its rendering. After that catch-e is rendered instead, with a state of the combined outer state and the error - [state-of-e error]. The element catch-e will usually be interactive, for example, displaying the error (and the relevant part of the state) to the user, and offer a button to reset the error to nil and maybe fix the state, after which try-e is showed again.

validation-boundary clj/s

(validation-boundary e validate!)

Creates a state validation boundary around the element e, where (validate! state :up) is evaluated for side effects when a state change is flowing out of e upwards, and (validate! state :down) is evaluated for side effects when a new state is being pushed down to e.

will-unmount clj/s

(will-unmount return)

(will-unmount e return)

An element like e, or an invisible element, which emits the state change or action as specified by the given return value.

with-ref clj/s

(with-ref f & args)

Creates an element for which (f ref & args) is called when it is renderd, which should return an element, and where ref is a fresh reference. A reference should be assigned to one of the elements below via set-ref. You can then deref a refernce, and use it as the target of a (return :message [target msg]) for example. If the returned element is a dom element, then deref will return the native dom node.