rum.core — rum 0.12.8

*render-js-component* clj

(*render-js-component* type-sym attrs children)

Takes JS component name as a symbol, attributes map and a collection of child elements. Should return a string.

adapt-class clj/s macro

(adapt-class type attrs & children)

Adapts JavaScript React component for usage in Rum components.

[:div (rum/adapt-class js/Button {:on-click f} "press me")]

When using in Clojure JVM calls render-js-component to render a fallback. See example in rum.examples.js-components ns

adapt-class-helper cljs

(adapt-class-helper type attrs children)

bind-context clj/s macro

(bind-context [context value] & body)

(bind-context [context value] ...)

create-context cljs

(create-context default-value)

create-ref clj/s

(create-ref)

cursor clj/s

(cursor ref key & options)

Same as cursor-in but accepts single key instead of path vector.

cursor-in clj/s

(cursor-in ref path & {:as options})

Given atom with deep nested value and path inside it, creates an atom-like structure that can be used separately from main atom, but will sync changes both ways:

(def db (atom { :users { "Ivan" { :age 30 }}}))

(def ivan (rum/cursor db [:users "Ivan"]))
(deref ivan) ;; => { :age 30 }

(swap! ivan update :age inc) ;; => { :age 31 }
(deref db) ;; => { :users { "Ivan" { :age 31 }}}

(swap! db update-in [:users "Ivan" :age] inc)
;; => { :users { "Ivan" { :age 32 }}}

(deref ivan) ;; => { :age 32 }

Returned value supports deref, swap!, reset!, watches and metadata.

The only supported option is :meta

defc clj/s macro

(defc & body)

(defc name doc-string? (< mixins+)? [ params* ] render-body+)

Defc does couple of things:

1. Wraps body into daiquiri/compile-html
2. Generates render function from that
3. Takes render function and mixins, builds React class from them
4. Using that class, generates constructor fn [args]->ReactElement
5. Defines top-level var with provided name and assigns ctor to it

Usage:

(rum/defc label < rum/static [t]
  [:div t])

;; creates React class
;; adds mixin rum/static
;; defines ctor fn (defn label [t] ...) => element

(label "text") ;; => returns React element built with label class

defcc clj/s macro

(defcc & body)

(defcc name doc-string? (< mixins+)? [ comp-arg params* ] render-body+)

Same as defc, but render will take additional first argument: react component.

defcontext clj/s macro

(defcontext name)

(defcontext name value)

cljs: Creates React context with initial value set to value. clj: Create dynamic var bound to value.

defcs clj/s macro

(defcs & body)

(defcs name doc-string? (< mixins+)? [ state-arg params* ] render-body+)

Same as defc, but render will take additional first argument: component state.

deref clj/s≠

(deref ref)

cljs

Takes a ref returned from use-ref and returns its current value.

derived-atom clj/s

(derived-atom refs key f)

(derived-atom refs key f opts)

Use this to create “chains” and acyclic graphs of dependent atoms.

derived-atom will:

• Take N “source” refs.
• Set up a watch on each of them.
• Create “sink” atom.
• When any of source refs changes:
  • re-run function f, passing N dereferenced values of source refs.
  • reset! result of f to the sink atom.
• Return sink atom.

Example:

(def *a (atom 0))
(def *b (atom 1))
(def *x (derived-atom [*a *b] ::key
          (fn [a b]
            (str a ":" b))))

(type *x)  ;; => clojure.lang.Atom
(deref *x) ;; => "0:1"

(swap! *a inc)
(deref *x) ;; => "1:1"

(reset! *b 7)
(deref *x) ;; => "1:7"

Arguments:

• refs - sequence of source refs,
• key - unique key to register watcher, same as in clojure.core/add-watch,
• f - function that must accept N arguments (same as number of source refs) and return a value to be written to the sink ref. Note: f will be called with already dereferenced values,
• opts - optional. Map of:
  • :ref - use this as sink ref. By default creates new atom,
  • :check-equals? - Defaults to true. If equality check should be run on each source update: (= @sink (f new-vals)). When result of recalculating f equals to the old value, reset! won’t be called. Set to false if checking for equality can be expensive.

dom-node cljs

(dom-node state)

Usage of this function is discouraged. Use :ref callback instead. Given state, returns top-level DOM node of component. Call it during lifecycle callbacks. Can’t be called during render.

fragment clj/s macro

(fragment attrs & children)

(rum/fragment [button] [input] ...)

hydrate cljs

(hydrate element node)

Same as mount but must be called on DOM tree already rendered by a server via render-html.

lazy-build cljs

(lazy-build ctor render mixins display-name)

Wraps component construction in a way so that Google Closure Compiler can properly recognize and elide unused components. The extra set-meta fn is needed so that the compiler can properly detect that all functions are side effect free.

local clj/s

(local initial)

(local initial key)

Mixin constructor. Adds an atom to component’s state that can be used to keep stuff during component’s lifecycle. Component will be re-rendered if atom’s value changes. Atom is stored under user-provided key or under :rum/local by default.

(rum/defcs counter < (rum/local 0 :cnt)
  [state label]
  (let [*cnt (:cnt state)]
    [:div {:on-click (fn [_] (swap! *cnt inc))}
      label @*cnt]))

(rum/mount (counter "Click count: "))

mark-sync-update cljs

(mark-sync-update f)

mount cljs

(mount element node)

Add element to the DOM tree. Idempotent. Subsequent mounts will just update element.

portal cljs

(portal element node)

Render element in a DOM node that is ouside of current DOM hierarchy.

react clj/s≠

(react ref)

clj

Supported as simple deref.

cljs

Works in conjunction with reactive mixin. Use this function instead of deref inside render, and your component will subscribe to changes happening to the derefed atom.

react-memo cljs

(react-memo f)

reactive clj/s≠

clj

Supported, does nothing.

cljs

Mixin. Works in conjunction with react.

(rum/defc comp < rum/reactive
  [*counter]
  [:div (rum/react counter)])

(def *counter (atom 0))
(rum/mount (comp *counter) js/document.body)
(swap! *counter inc) ;; will force comp to re-render

ref cljs

(ref state key)

DEPRECATED: Use :ref (fn [dom-or-nil]) callback instead. See rum issue #124 Given state and ref handle, returns React component.

ref-node cljs

(ref-node state key)

DEPRECATED: Use :ref (fn [dom-or-nil]) callback instead. See rum issue #124 Given state and ref handle, returns DOM node associated with ref.

render-html clj/s≠

(render-html element)

(render-html element opts)

clj

Main server-side rendering method. Given component, returns HTML string with static markup of that component. Serve that string to the browser and hydrate same Rum component over it. React will be able to reuse already existing DOM and will initialize much faster. No opts are supported at the moment.

cljs

Main server-side rendering method. Given component, returns HTML string with static markup of that component. Serve that string to the browser and hydrate same Rum component over it. React will be able to reuse already existing DOM and will initialize much faster. No opts are supported at the moment.

render-static-markup clj/s≠

clj

(render-static-markup element)

Same as render-html but returned string has nothing React-specific. This allows Rum to be used as traditional server-side templating engine.

cljs

(render-static-markup src)

Same as render-html but returned string has nothing React-specific. This allows Rum to be used as traditional server-side templating engine.

request-render cljs

(request-render component)

Schedules react component to be rendered on next animation frame, unless the requested update happens to be in a sync-update phase.

set-ref! clj/s

(set-ref! ref value)

set-warn-on-interpretation! clj/s macro

(set-warn-on-interpretation! v)

state cljs

(state comp)

Given React component, returns Rum state associated with it.

static clj/s≠

clj

Supported, does nothing.

cljs

Mixin. Will avoid re-render if none of component’s arguments have changed. Does equality check (=) on all arguments.

(rum/defc label < rum/static
  [text]
  [:div text])
  
(rum/mount (label "abc") js/document.body)

;; def != abc, will re-render
(rum/mount (label "def") js/document.body)

;; def == def, won’t re-render
(rum/mount (label "def") js/document.body)

suspense clj/s macro

(suspense {:keys [fallback]} child)

(rum/require-lazy '[app.components :refer [alert]])

(rum/defc root [] (suspense {:fallback "Hello!"} (alert "ARGUMENT")))

See a complete example here https://github.com/roman01la/rum-code-splitting

unmount cljs

(unmount node)

Removes component from the DOM tree.

use-callback clj/s≠

(use-callback callback)

(use-callback callback deps)

cljs

Takes callback function and returns memoized variant, memoization is done based on provided deps collection.

(rum/defc button < rum/static [{:keys [on-click]} text] [:button {:on-click on-click} text])

(rum/defc app [v] (let [on-click (rum/use-callback #(do-stuff v) [v])] ;; because on-click callback is memoized here based on v argument ;; the callback won't be re-created on every render, unless v changes ;; which means that underlying button component won't re-render wastefully [button {:on-click on-click} "press me"]))

Read more at https://reactjs.org/docs/hooks-reference.html#usecallback

use-effect! clj/s≠

(use-effect! setup-fn)

(use-effect! setup-fn deps)

cljs

Takes setup-fn that executes either on the first render or after every update. The function may return cleanup-fn to cleanup the effect, either before unmount or before every next update. Calling behavior is controlled by deps argument.

(rum/use-effect! (fn [] (.addEventListener js/window "load" handler) #(.removeEventListener js/window "load" handler)) []) ;; empty deps collection instructs React to run setup-fn only once on initial render ;; and cleanup-fn only once before unmounting

Read more at https://reactjs.org/docs/hooks-effect.html

use-layout-effect! clj/s≠

(use-layout-effect! setup-fn)

(use-layout-effect! setup-fn deps)

cljs

(rum/use-layout-effect! (fn [] (.addEventListener js/window "load" handler) #(.removeEventListener js/window "load" handler)) []) ;; empty deps collection instructs React to run setup-fn only once on initial render ;; and cleanup-fn only once before unmounting

Read more at https://reactjs.org/docs/hooks-effect.html

use-memo clj/s≠

(use-memo f)

(use-memo f deps)

cljs

Takes a function, memoizes it based on provided deps collection and executes immediately returning a result. Read more at https://reactjs.org/docs/hooks-reference.html#usememo

use-reducer clj/s≠

(use-reducer reducer-fn initial-value)

cljs

Takes reducing function and initial state value. Returns a tuple of [value dispatch!], where value is current state value and dispatch is a function that schedules re-render.

(defmulti value-reducer (fn [value event] event))

(defmethod value-reducer :inc [value _] (inc value))

(let [[value dispatch!] (rum/use-reducer value-reducer 0)] [:button {:on-click #(dispatch! :inc)} value])

Read more at https://reactjs.org/docs/hooks-reference.html#usereducer

use-ref clj/s≠

(use-ref initial-value)

cljs

Takes a value and puts it into a mutable container which is persisted for the full lifetime of the component. https://reactjs.org/docs/hooks-reference.html#useref

use-state clj/s≠

(use-state value-or-fn)

cljs

Takes initial value or value returning fn and returns a tuple of [value set-value!], where value is current state value and set-value! is a function that schedules re-render.

(let [[value set-state!] (rum/use-state 0)] [:button {:on-click #(set-state! (inc value))} value])

with-context clj/s macro

(with-context [sym context] & body)

(with-context [value ctx] [:div value])

with-key clj/s

(with-key element key)

Adds React key to element.

(rum/defc label [text] [:div text])

(-> (label)
    (rum/with-key "abc")
    (rum/mount js/document.body))

with-ref clj/s≠

(with-ref element ref)

clj

Supported, does nothing.

cljs

Adds React ref (string or callback) to element.

(rum/defc label [text] [:div text])

(-> (label)
    (rum/with-ref "abc")
    (rum/mount js/document.body))