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

add-merged-state clj/s

(add-merged-state initial item)

Adds new map or record fields that the given item sees as it's state, by merging the the given initial record or hash-map with the state of the resulting item. The given item can then update any field, but the fields from initial are 'removed' from the outer state. Note that any fields not in theinitial` value are put in the outer state. If there are duplicate fields, the inner state 'wins'.

add-state clj/s

(add-state initial lens item)

Adds new state that the given item 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 item has only outer as its state.

cleanup clj/s

(cleanup f)

Returns an item that evaluates (f state) when it is being removed from the item tree, and emits the return value that that must return.

comp clj/s

(comp & fs)

Like [[clojure.core/comp]], but the returned function is equal (=), when the arguments are equal.

constantly clj/s

(constantly v)

Like [[clojure.core/constantly]], but the returned function is equal (=), when the argument is equal.

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 item. For example, given

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

then current-state is an item 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 item)

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

def-static clj/s macro

(def-static name item)

Defines name to be a static item that is always like item, independant of the state.

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 item. For example, given

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

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

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

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

defn-effect clj/s≠ macro

clj

(defn-effect name args & body)

cljs

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

A macro similar to defn, that defines a new effect.

(defn-effect my-effect [arg]
  (change-the-world! args))

Calling it returns an effect action, which can be returned by an item as an action. The body of the effect then executed later, when side effects on some external entity are safe.

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 item. This is the same as Clojures defn, but in addition assigns its name to the returned item which can be used by testing and debugging utilities.

defn-static clj/s≠ macro

clj

(defn-static name args & body)

cljs

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

Defines name to a function, returning a static item like the item define by the function body. The static item is independant of the outside state, and depends only on the argument values. Compared to an ordinary function, this can greatly increase performance, as the body is only evaluated when the arguments change.

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 item in your application. That item 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 item is mounted into your application, and that it must result in a function with no arguments, which is called when the item 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.

dynamic clj/s

(dynamic f & args)

Returns a dynamic item, which looks and behaves like the item returned from (f state & args), which is evaluated each time the state changes.

effect clj/s

(effect f & args)

Return an effect action, which, when run, calls the given function with the given arguments. The result of that function is ignored, unless you use handle-effect-result.

embed-state clj/s

(embed-state item lens)

Embeds the state of the given item into a part of the state of the resulting item, via the given lens.

empty clj/s

An invisible item with no behavior.

error-boundary clj/s

(error-boundary item f)

Creates an error boundary around the given item. 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 item of a vector.

focus clj/s

(focus lens item)

Returns an item that focuses the outer state, to the part of it that item shall see, via the given lens. Otherwise behaves and looks the same.

fragment clj/s

(fragment & children)

Returns a container item consisting of the given child items.

handle-action clj/s

(handle-action item f)

Handles actions emitted by given item, by evaluating (f state 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-effect-result clj/s

(handle-effect-result f eff)

handle-message clj/s

(handle-message f item)

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

handle-state-change clj/s

(handle-state-change item f)

Returns an item like the given item, but when a state change is emitted by item, then (f prev-state new-state) is evaluated, which must return a return value. By careful with this, as item usually expect that their changes to the state are eventually successful.

hide-state clj/s

(hide-state item initial lens)

Hides a part of the state of the given item, via a lens that reduces the the tuple of states [outer inner], where the initial value for inner state is initial. The resulting item 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 item)

Hides the state of the given item as a local state, resulting in an item with an arbitrary state that is inaccessible for it.

keyed clj/s

(keyed item key)

Adds an arbitrary identifier to the given item, which will be used to optimize rendering of it in a list of children of a container item.

local-state clj/s

(local-state initial item)

Returns an item which looks like the given item, with state outer, where the given item must take a tuple state [outer inner], and initial is an intial value for the inner state, which can then be changed by the item independantly from the outer state.

map-actions clj/s

(map-actions item f)

Returns an item that emits actions (f action), for each action emitted by item, and otherwise looks an behaves exacly the same.

map-messages clj/s

(map-messages f item)

Returns an item like the given one, that transforms all messages sent to it though (f msg), before they are forwarded to item.

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 item 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 the item changes its state 'by itself', not if the state was changed somewhere upwards in the item tree an is only passed down to the resulting item.

name-id clj/s

(name-id s)

Generates a fresh unique value that can be used to generate named items via named. Note that calling this twice with the same name returns different values.

named clj/s

(named name-id item)

Returns an item that looks and works exactly like the given item, but with has a user defined name, that appears and can be used in testing and debugging utilities. Use name-id to generate a unique name object. See def-named and defn-named for more convenient ways to create named items.

once clj/s

(once f & [cleanup-f])

Returns an item that evaluates (f state) and emits the return value that it must return initially. On subsequent state updates, f is called too, but the returned return value is only emitted if it different than last time. In other words, the same return value is emitted only once. The optional (cleanup-f state) is evaluated, when the item is removed from the item tree afterwards.

Note that if you return a modified state, you must be careful to not cause an endless loop of updates.

partial clj/s

(partial f & args)

Like [[clojure.core/partial]], but the returned function is equal (=), when the arguments are equal.

redirect-messages clj/s

(redirect-messages ref item)

Return an item like the given one, but that handles all messages sent to it by redirecting them to the item specified by the given reference.

ref-let clj/s≠ macro

clj

(ref-let bindings & body)

cljs

(ref-let &form &env bindings & body)

A macro that defines some names to refer to the given items, which allows the names to be used as message target in the body.

For example, to create an item that redirects messages to one of its children based on some criteria, you can write:

(ref-let [child-1 (my-item-1 ...)
          child-2 (my-item-2 ...)]
  (handle-message (fn [_ msg]
                     (if (is-for-child-1? msg)
                       (return :message [child-1 msg])
                       (return :message [child-2 msg])))
    (div child-1 child-2)))

ref-let* clj/s

(ref-let* items f & args)

Returns an item, that calls f with a list and the given arguments, where the list consists of the given items, but modified in a way that makes them usable as message targets.

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:

• :state means that the item changes its state to the given value
• :action means that the given action is emitted by the item
• :message means that the given message is sent to the given target (a reference or a item with a reference assigned).

If no :state option is used, the state of the item will not change. :state must occur at most once, :message and :action can be specified multiple times.

second-lens clj/s

A lens over the second item 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 item ref)

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

static clj/s

(static f & args)

Returns an item that is always like (f & args), independant of state changes. The item returned by f must not access state nor change it.

subscription clj/s

(subscription f & args)

Returns an item that asynchronously emits actions according to the given function f. For that f will be called with a side-effectful deliver! function which takes the action to emit, and f must return a stop function of no arguments. You may do some kind of registration at an asynchronous library or native browser api, and use deliver! to inform your application about the results, once or multiple times. But when the stop function is called, you must prevent any more calls to deliver!.

try-catch clj/s

(try-catch try-item catch-item)

Returns an item that looks an works the same as the item try-item, until an error is thrown during its rendering. After that catch-item is rendered instead, with a state of the combined outer state and the error - [state-of-e error]. The catch-item 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-item is showed again.

validation-boundary clj/s

(validation-boundary item validate!)

Returns an item that forms a state validation boundary around the given item, where (validate! state :up) is evaluated for side effects when a state change is flowing out of then item upwards, and (validate! state :down) is evaluated for side effects when a new state is being pushed down.

with-message-target clj/s

(with-message-target handle-msg f & args)

Returns an item like ´(f target & args), wheretargetis a reference that can be used as a message target, which are then handled by a call to(handle-msg state msg)`, which must return a return value.

with-ref clj/s

(with-ref f & args)

Creates an item identical to the one returned from (f ref & args), where ref is a fresh reference. A reference should be assigned to one of the items below via set-ref. You can use it as the target of a (return :message [target msg]) for example.

with-refs clj/s

(with-refs n f & args)

Returns an item that calls f with a list of n references and any remaining args. See with-ref.