@thi.ng/rdom

This project is part of the @thi.ng/umbrella monorepo.

• About
  • Status
    • HIC SUNT DRACONES
    • @thi.ng/atom integration
  • Support packages
• Installation
• Dependencies
• Usage examples
• API
• Authors
• License

About

Lightweight, reactive, VDOM-less UI/DOM components with async lifecycle and @thi.ng/hiccup compatible.

Status

ALPHA - bleeding edge / work-in-progress

HIC SUNT DRACONES

This is still a young project. Even though most of the overall approach, component lifecycle and API are fairly stable by now (after ~70 commits over several months), so far there's only sparing documentation and only a handful of public examples. After some more user feedback, there's likely going to be further refactoring required here and there, none of which is expected to cause breaking changes in this core package and will likely come in the form of additions or alternatives to existing control structures (unless they would be entirely subsuming current features/approaches)...

@thi.ng/atom integration

For the sake of deduplication of functionality and to keep the number of dependencies to a minimum, direct @thi.ng/atom integration has been removed in favor of using relevant @thi.ng/rstream constructs, which can be used as lightweight adapters, i.e.:

• fromAtom()
• fromView()

Support packages

• @thi.ng/rdom-canvas - @thi.ng/rdom component wrapper for @thi.ng/hiccup-canvas and declarative canvas drawing
• @thi.ng/rdom-components - Collection of unstyled, customizable components for @thi.ng/rdom

Installation

yarn add @thi.ng/rdom

// ES module
<script type="module" src="https://unpkg.com/@thi.ng/rdom?module" crossorigin></script>

// UMD
<script src="https://unpkg.com/@thi.ng/rdom/lib/index.umd.js" crossorigin></script>

Package sizes (gzipped, pre-treeshake): ESM: 3.75 KB / CJS: 3.89 KB / UMD: 3.86 KB

Dependencies

• @thi.ng/api
• @thi.ng/checks
• @thi.ng/errors
• @thi.ng/hiccup
• @thi.ng/paths
• @thi.ng/prefixes
• @thi.ng/rstream
• @thi.ng/strings

Usage examples

Several demos in this repo's /examples directory are using this package.

A selection:

Screenshot	Description	Live demo	Source
	Parser grammar livecoding editor/playground & codegen	Demo	Source
	Demonstates various rdom usage patterns	Demo	Source
	rdom drag & drop example	Demo	Source
	rdom & hiccup-canvas interop test	Demo	Source
	Full umbrella repo doc string search w/ paginated results	Demo	Source

API

Generated API docs

TODO

Currently, documentation only exists in the form of small examples and various doc strings (incomplete). I'm working to alleviate this situation ASAP... In that respect, PRs are welcome as well!

import { $compile } from "@thi.ng/rdom";
import { reactive } from "@thi.ng/rstream";
import { cycle, map } from "@thi.ng/transducers";

// reactive value
const bg = reactive("gray");

// color options (infinite iterable)
const colors = cycle(["magenta", "yellow", "cyan"]);

// event handler
const nextColor = () => bg.next(<string>colors.next().value);

// define component tree in hiccup syntax, compile & mount component.
// each time `bg` value changes, only subscribed bits will be updated
// i.e. title, the button's `style.background` and its label

// Note: instead of direct hiccup syntax, you could also use the
// element functions provided by https://thi.ng/hiccup-html
$compile([
    "div",
    {},
    // transformed color as title (aka derived view)
    ["h1", {}, bg.transform(map((col) => `Hello, ${col}!`))],
    [
        // tag with Emmet-style ID & classes
        "button#foo.w4.pa3.bn",
        {
            // reactive CSS background property
            style: { background: bg },
            onclick: nextColor,
        },
        // reactive button label
        bg,
    ],
]).mount(document.body);

Authors

Karsten Schmidt

License

© 2020 Karsten Schmidt // Apache Software License 2.0