@thi.ng/hdom 9.2.0 → 9.2.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-12-16T12:52:25Z
+- **Last updated**: 2022-12-20T16:33:11Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.

package/api.d.ts

@@ -1,88 +1,83 @@
 import type { IObjectOf } from "@thi.ng/api";
 export interface ILifecycle {
     /**
-     * Component init method. Called with the actual DOM element, hdom
-     * user context and any other args when the component is first used,
-     * but **after** `render()` has been called once already AND all of
-     * the components children have been realized. Therefore, if any
-     * children have their own `init` lifecycle method, these hooks will
-     * be executed before that of the parent.
+     * Component init method. Called with the actual DOM element, hdom user
+     * context and any other args when the component is first used, but
+     * **after** `render()` has been called once already AND all of the
+     * components children have been realized. Therefore, if any children have
+     * their own `init` lifecycle method, these hooks will be executed before
+     * that of the parent.
      */
     init?(el: Element, ctx: any, ...args: any[]): void;
     /**
-     * Returns the hdom tree of this component.
-     * Note: Always will be called first (prior to `init`/`release`)
-     * to obtain the actual component definition used for diffing.
-     * Therefore might have to include checks if any local state
-     * has already been initialized via `init`. This is the only
+     * Returns the hdom tree of this component. Note: Always will be called
+     * first (prior to `init`/`release`) to obtain the actual component
+     * definition used for diffing. Therefore might have to include checks if
+     * any local state has already been initialized via `init`. This is the only
      * mandatory method which MUST be implemented.
      *
-     * `render` is executed before `init` because `normalizeTree()`
-     * must obtain the component's hdom tree first before it can
-     * determine if an `init` is necessary. `init` itself will be
-     * called from `diffTree`, `createDOM` or `hydrateDOM()` in a later
-     * phase of processing.
-     *
-     * `render` should ALWAYS return an array or another function,
-     * else the component's `init` or `release` fns will NOT be able
-     * to be called later. E.g. If the return value of `render`
-     * evaluates as a string or number, the return value should be
-     * wrapped as `["span", "foo"]`. If no `init` or `release` are
-     * used, this requirement is relaxed.
+     * `render` is executed before `init` because `normalizeTree()` must obtain
+     * the component's hdom tree first before it can determine if an `init` is
+     * necessary. `init` itself will be called from `diffTree`, `createDOM` or
+     * `hydrateDOM()` in a later phase of processing.
+     *
+     * `render` should ALWAYS return an array or another function, else the
+     * component's `init` or `release` fns will NOT be able to be called later.
+     * E.g. If the return value of `render` evaluates as a string or number, the
+     * return value should be wrapped as `["span", "foo"]`. If no `init` or
+     * `release` are used, this requirement is relaxed.
      */
     render(ctx: any, ...args: any[]): any;
     /**
-     * Called when the underlying DOM of this component is removed
-     * (or replaced). Intended for cleanup tasks.
+     * Called when the underlying DOM of this component is removed (or
+     * replaced). Intended for cleanup tasks.
      */
     release?(ctx: any, ...args: any[]): void;
 }
 export interface HDOMBehaviorAttribs {
     /**
-     * HDOM behavior control attribute. If true (default), the element
-     * will be fully processed by `diffTree()`. If false, no diff will
-     * be computed and the `replaceChild()` operation will be called in
-     * the currently active hdom target implementation.
+     * HDOM behavior control attribute. If true (default), the element will be
+     * fully processed by `diffTree()`. If false, no diff will be computed and
+     * the `replaceChild()` operation will be called in the currently active
+     * hdom target implementation.
      */
     __diff?: boolean;
     /**
-     * HDOM behavior control attribute. If true, the element will not be
-     * diffed and simply skipped. IMPORTANT: This attribute is only
-     * intended for cases when a component / tree branch should not be
-     * updated, but MUST NEVER be enabled when that component is first
-     * included in the tree. Doing so will result in undefined future
-     * behavior.
-     *
-     * Note, skipped elements and their children are being normalized,
-     * but are ignored during diffing. Therefore, if this attribute is
-     * enabled the element should either have no children OR the
-     * children are the same (type) as when the attribute is disabled
-     * (i.e. when `__skip` is falsy).
+     * HDOM behavior control attribute. If true, the element will not be diffed
+     * and simply skipped. IMPORTANT: This attribute is only intended for cases
+     * when a component / tree branch should not be updated, but MUST NEVER be
+     * enabled when that component is first included in the tree. Doing so will
+     * result in undefined future behavior.
+     *
+     * Note, skipped elements and their children are being normalized, but are
+     * ignored during diffing. Therefore, if this attribute is enabled the
+     * element should either have no children OR the children are the same
+     * (type) as when the attribute is disabled (i.e. when `__skip` is falsy).
      */
     __skip?: boolean;
     /**
-     * HDOM behavior control attribute. If present, the element and all
-     * of its children will be processed by the given
-     * `HDOMImplementation` instead of the default implementation.
+     * HDOM behavior control attribute. If present, the element and all of its
+     * children will be processed by the given `HDOMImplementation` instead of
+     * the default implementation.
      */
     __impl?: HDOMImplementation<any>;
     /**
-     * HDOM behavior control attribute. If `false`, the current
-     * element's children will not be normalized. Use this when you're
-     * sure that all children are already in canonical format (incl.
-     * `key` attributes). See `normalizeTree()` for details.
+     * HDOM behavior control attribute. If `false`, the current element's
+     * children will not be normalized. Use this when you're sure that all
+     * children are already in canonical format (incl. `key` attributes). See
+     * `normalizeTree()` for details.
      */
     __normalize?: boolean;
     /**
-     * HDOM behavior control attribute. If `false`, hdom will not
-     * attempt to call `release()` lifecycle methods on this element or
-     * any of its children.
+     * HDOM behavior control attribute. If `false`, hdom will not attempt to
+     * call `release()` lifecycle methods on this element or any of its
+     * children.
      */
     __release?: boolean;
     /**
-     * Currently only used by {@link @thi.ng/hiccup# | @thi.ng/hiccup}. No relevance for hdom. If
-     * `false`, the element and its children will be omitted from the
-     * serialized result.
+     * Currently only used by [`thi.ng/hiccup`](https://thi.ng/hiccup). No
+     * relevance for hdom. If `false`, the element and its children will be
+     * omitted from the serialized result.
      */
     __serialize?: boolean;
 }
@@ -102,46 +97,45 @@ export interface HDOMOpts {
      */
     root?: Element | string;
     /**
-     * Arbitrary user context object, passed to all component functions
-     * embedded in the tree.
+     * Arbitrary user context object, passed to all component functions embedded
+     * in the tree.
      */
     ctx?: any;
     /**
-     * Attempts to auto-expand/deref the given keys in the user supplied
-     * context object (`ctx` option) prior to *each* tree normalization.
-     * All of these values should implement the
-     * {@link @thi.ng/api#IDeref} interface (e.g. atoms, cursors, views,
-     * rstreams etc.). This feature can be used to define dynamic
-     * contexts linked to the main app state, e.g. using derived views
-     * provided by {@link @thi.ng/atom# | @thi.ng/atom}.
+     * Attempts to auto-expand/deref the given keys in the user supplied context
+     * object (`ctx` option) prior to *each* tree normalization. All of these
+     * values should implement the
+     * [`IDeref`](https://docs.thi.ng/umbrella/api/interfaces/IDeref.html)
+     * interface (e.g. atoms, cursors, views, rstreams etc.). This feature can
+     * be used to define dynamic contexts linked to the main app state, e.g.
+     * using derived views provided by [`thi.ng/atom`](https://thi.ng/atom).
      *
      * @defaultValue none
      */
     autoDerefKeys: PropertyKey[];
     /**
-     * If true, each elements will receive an auto-generated
-     * `key` attribute (unless one already exists).
+     * If true, each elements will receive an auto-generated `key` attribute
+     * (unless one already exists).
      *
      * @defaultValue true
      */
     keys?: boolean;
     /**
-     * If true, all text content will be wrapped in `<span>`
-     * elements. Spans will never be created inside <option>, <textarea>
-     * or <text> elements.
+     * If true, all text content will be wrapped in `<span>` elements. Spans
+     * will never be created inside <option>, <textarea> or <text> elements.
      *
      * @defaultValue true
      */
     span?: boolean;
     /**
-     * If true, the first frame will only be used to inject event
-     * listeners, using the `hydrateDOM()` function.
+     * If true, the first frame will only be used to inject event listeners,
+     * using the `hydrateDOM()` function.
      *
-     * *Important:* Enabling this option assumes that an equivalent DOM
-     * (minus event listeners) already exists (e.g. generated via SSR /
-     * hiccup's `serialize()`) when hdom's `start()` function is called.
-     * Any other discrepancies between the pre-existing DOM and the hdom
-     * trees will cause undefined behavior.
+     * *Important:* Enabling this option assumes that an equivalent DOM (minus
+     * event listeners) already exists (e.g. generated via SSR / hiccup's
+     * `serialize()`) when hdom's `start()` function is called. Any other
+     * discrepancies between the pre-existing DOM and the hdom trees will cause
+     * undefined behavior.
      *
      * @defaultValue false
      */
@@ -152,43 +146,40 @@ export interface HDOMOpts {
     [id: string]: any;
 }
 /**
- * This interface defines the underlying target update operations used
- * by `diffTree()` and `createDOM()`. It allows {@link @thi.ng/hdom# | @thi.ng/hdom} to
- * be used as general purpose tree definition & differential update
- * mechanism, rather than being restricted to only work with an HTML
- * DOM. See {@link DEFAULT_IMPL} for the default implementations dealing
- * with the latter. Note: Depending on use case and tree configuration,
- * not all of these methods are required.
+ * This interface defines the underlying target update operations used by
+ * `diffTree()` and `createDOM()`. It allows
+ * [`thi.ng/hdom`](https://thi.ng/hdom) to be used as general purpose tree
+ * definition & differential update mechanism, rather than being restricted to
+ * only work with an HTML DOM. See {@link DEFAULT_IMPL} for the default
+ * implementations dealing with the latter. Note: Depending on use case and tree
+ * configuration, not all of these methods are required.
  *
- * Custom element-local implementations can also be provided via the
- * special `__impl` hdom element/component attribute. In this case the
- * element itself and all of its children will be processed with those
- * custom operations.
+ * Custom element-local implementations can also be provided via the special
+ * `__impl` hdom element/component attribute. In this case the element itself
+ * and all of its children will be processed with those custom operations.
  */
 export interface HDOMImplementation<T> {
     /**
-     * Normalizes given hdom tree, expands Emmet-style tags, embedded
-     * iterables, component functions, component objects with life cycle
-     * methods and injects `key` attributes for `diffTree()` to later
-     * identify changes in nesting order. During normalization any
-     * embedded component functions are called with the given (optional)
-     * user `ctx` object as first argument. For further details of the
-     * default implementation, please see `normalizeTree()` in
-     * `normalize.ts`.
-     *
-     * Implementations MUST check for the presence of the `__impl`
-     * control attribute on each branch. If given, the current
-     * implementation MUST delegate to the `normalizeTree()` method of
-     * the specified implementation and not descent into that branch
-     * further itself.
-     *
-     * Furthermore, if (and only if) an element has the `__normalize`
-     * control attrib set to `false`, the normalization of that
-     * element's children MUST be skipped.
-     *
-     * Calling this function is a prerequisite before passing a
-     * component tree to `diffTree()`. Recursively expands given hiccup
-     * component tree into its canonical form:
+     * Normalizes given hdom tree, expands Emmet-style tags, embedded iterables,
+     * component functions, component objects with life cycle methods and
+     * injects `key` attributes for `diffTree()` to later identify changes in
+     * nesting order. During normalization any embedded component functions are
+     * called with the given (optional) user `ctx` object as first argument. For
+     * further details of the default implementation, please see
+     * `normalizeTree()` in `normalize.ts`.
+     *
+     * Implementations MUST check for the presence of the `__impl` control
+     * attribute on each branch. If given, the current implementation MUST
+     * delegate to the `normalizeTree()` method of the specified implementation
+     * and not descent into that branch further itself.
+     *
+     * Furthermore, if (and only if) an element has the `__normalize` control
+     * attrib set to `false`, the normalization of that element's children MUST
+     * be skipped.
+     *
+     * Calling this function is a prerequisite before passing a component tree
+     * to `diffTree()`. Recursively expands given hiccup component tree into its
+     * canonical form:
      *
      * ```
      * ["tag", { attribs }, ...body]
@@ -196,68 +187,62 @@ export interface HDOMImplementation<T> {
      *
      * - resolves Emmet-style tags (e.g. from `div#id.foo.bar`)
      * - adds missing attribute objects (and `key` attribs)
-     * - merges Emmet-style classes with additional `class` attrib
-     *   values (if given), e.g. `["div.foo", { class: "bar" }]` =>
-     *   `["div", {class: "bar foo" }]`
-     * - evaluates embedded functions and replaces them with their
+     * - merges Emmet-style classes with additional `class` attrib values (if
+     *   given), e.g. `["div.foo", { class: "bar" }]` => `["div", {class: "bar
+     *   foo" }]`
+     * - evaluates embedded functions and replaces them with their result
+     * - calls the `render` life cycle method on component objects and uses
      *   result
-     * - calls the `render` life cycle method on component objects and
-     *   uses result
      * - consumes iterables and normalizes their individual values
-     * - calls `deref()` on elements implementing the `IDeref` interface
+     * - calls `deref()` on elements implementing the `IDeref` interface and
+     *   uses returned results
+     * - calls `toHiccup()` on elements implementing the `IToHiccup` interface
      *   and uses returned results
-     * - calls `toHiccup()` on elements implementing the `IToHiccup`
-     *   interface and uses returned results
-     * - calls `.toString()` on any other non-component value and by
-     *   default wraps it in `["span", x]`. The only exceptions to this
-     *   are: `button`, `option`, `textarea` and SVG `text` elements,
-     *   for which spans are never created.
-     *
-     * Additionally, unless the `keys` option is explicitly set to
-     * false, an unique `key` attribute is created for each node in the
-     * tree. This attribute is used by `diffTree` to determine if a
-     * changed node can be patched or will need to be moved, replaced or
-     * removed.
-     *
-     * In terms of life cycle methods: `render` should ALWAYS return an
-     * array or another function, else the component's `init` or
-     * `release` fns will NOT be able to be called. E.g. If the return
-     * value of `render` evaluates as a string or number, it should be
-     * wrapped as `["span", "foo"]` or an equivalent wrapper node. If no
-     * `init` or `release` methods are used, this requirement is
-     * relaxed.
-     *
-     * See `normalizeElement` (normalize.ts) for further details about
-     * the canonical element form.
+     * - calls `.toString()` on any other non-component value and by default
+     *   wraps it in `["span", x]`. The only exceptions to this are: `button`,
+     *   `option`, `textarea` and SVG `text` elements, for which spans are never
+     *   created.
+     *
+     * Additionally, unless the `keys` option is explicitly set to false, an
+     * unique `key` attribute is created for each node in the tree. This
+     * attribute is used by `diffTree` to determine if a changed node can be
+     * patched or will need to be moved, replaced or removed.
+     *
+     * In terms of life cycle methods: `render` should ALWAYS return an array or
+     * another function, else the component's `init` or `release` fns will NOT
+     * be able to be called. E.g. If the return value of `render` evaluates as a
+     * string or number, it should be wrapped as `["span", "foo"]` or an
+     * equivalent wrapper node. If no `init` or `release` methods are used, this
+     * requirement is relaxed.
+     *
+     * See `normalizeElement` (normalize.ts) for further details about the
+     * canonical element form.
      *
      * @param tree - component tree
      * @param opts - hdom config options
      */
     normalizeTree(opts: Partial<HDOMOpts>, tree: any): any[];
     /**
-     * Realizes the given hdom tree in the target below the `parent`
-     * node, e.g. in the case of the browser DOM, creates all required
-     * DOM elements encoded by the given hdom tree.
+     * Realizes the given hdom tree in the target below the `parent` node, e.g.
+     * in the case of the browser DOM, creates all required DOM elements encoded
+     * by the given hdom tree.
      *
      * @remarks
-     * If `parent` is null the result tree won't be attached to any
-     * parent. If `child` is given, the new elements will be inserted at
-     * given child index.
-     *
-     * For any components with `init` life cycle methods, the
-     * implementation MUST call `init` with the created element, the
-     * user provided context (obtained from `opts`) and any other args.
-     * `createTree()` returns the created root element(s) - usually only
-     * a single one, but can be an array of elements, if the provided
-     * tree is an iterable of multiple roots. The default implementation
-     * creates text nodes for non-component values. Returns `parent` if
-     * tree is `null` or `undefined`.
-     *
-     * Implementations MUST check for the presence of the `__impl`
-     * control attribute on each branch. If given, the current
-     * implementation MUST delegate to the `createTree()` method of the
-     * specified implementation and not descent into that branch further
-     * itself.
+     * If `parent` is null the result tree won't be attached to any parent. If
+     * `child` is given, the new elements will be inserted at given child index.
+     *
+     * For any components with `init` life cycle methods, the implementation
+     * MUST call `init` with the created element, the user provided context
+     * (obtained from `opts`) and any other args. `createTree()` returns the
+     * created root element(s) - usually only a single one, but can be an array
+     * of elements, if the provided tree is an iterable of multiple roots. The
+     * default implementation creates text nodes for non-component values.
+     * Returns `parent` if tree is `null` or `undefined`.
+     *
+     * Implementations MUST check for the presence of the `__impl` control
+     * attribute on each branch. If given, the current implementation MUST
+     * delegate to the `createTree()` method of the specified implementation and
+     * not descent into that branch further itself.
      *
      * @param parent - parent node in target (e.g. DOM element)
      * @param tree - component tree
@@ -266,18 +251,16 @@ export interface HDOMImplementation<T> {
      */
     createTree(opts: Partial<HDOMOpts>, parent: T, tree: any, child?: number, init?: boolean): T | T[];
     /**
-     * Takes a target root element and normalized hdom tree, then walks
-     * tree and initializes any event listeners and components with life
-     * cycle `init` methods. Assumes that an equivalent "DOM" (minus
-     * listeners) already exists when this function is called. Any other
-     * discrepancies between the pre-existing DOM and the hdom tree
-     * might cause undefined behavior.
-     *
-     * Implementations MUST check for the presence of the `__impl`
-     * control attribute on each branch. If given, the current
-     * implementation MUST delegate to the `hydrateTree()` method of the
-     * specified implementation and not descent into that branch further
-     * itself.
+     * Takes a target root element and normalized hdom tree, then walks tree and
+     * initializes any event listeners and components with life cycle `init`
+     * methods. Assumes that an equivalent "DOM" (minus listeners) already
+     * exists when this function is called. Any other discrepancies between the
+     * pre-existing DOM and the hdom tree might cause undefined behavior.
+     *
+     * Implementations MUST check for the presence of the `__impl` control
+     * attribute on each branch. If given, the current implementation MUST
+     * delegate to the `hydrateTree()` method of the specified implementation
+     * and not descent into that branch further itself.
      *
      * @param opts - hdom config options
      * @param parent - parent node in target (e.g. DOM element)
@@ -286,42 +269,39 @@ export interface HDOMImplementation<T> {
      */
     hydrateTree(opts: Partial<HDOMOpts>, parent: T, tree: any, child?: number): void;
     /**
-     * Takes an `HDOMOpts` options object, a `parent` element and two
-     * normalized hiccup trees, `prev` and `curr`. Recursively computes
-     * diff between both trees and applies any necessary changes to
-     * reflect `curr` tree, based on the differences to `prev`, in
-     * target (browser DOM when using the `DEFAULT_IMPL`
-     * implementation).
+     * Takes an `HDOMOpts` options object, a `parent` element and two normalized
+     * hiccup trees, `prev` and `curr`. Recursively computes diff between both
+     * trees and applies any necessary changes to reflect `curr` tree, based on
+     * the differences to `prev`, in target (browser DOM when using the
+     * `DEFAULT_IMPL` implementation).
      *
      * All target modification operations are delegated to the given
-     * implementation. `diffTree()` merely manages which elements or
-     * attributes need to be created, updated or removed and this NEVER
-     * involves any form of tracking of the actual underlying target
-     * data structure (e.g. the real browser DOM). hdom in general and
-     * `diffTree()` specifically are stateless. The only state available
-     * is implicitly defined by the two trees given (prev / curr).
-     *
-     * Implementations MUST check for the presence of the `__impl`
-     * control attribute on each branch. If present AND different than
-     * the current implementation, the latter MUST delegate to the
-     * `diffTree()` method of the specified implementation and not
-     * descent into that branch further itself.
+     * implementation. `diffTree()` merely manages which elements or attributes
+     * need to be created, updated or removed and this NEVER involves any form
+     * of tracking of the actual underlying target data structure (e.g. the real
+     * browser DOM). hdom in general and `diffTree()` specifically are
+     * stateless. The only state available is implicitly defined by the two
+     * trees given (prev / curr).
+     *
+     * Implementations MUST check for the presence of the `__impl` control
+     * attribute on each branch. If present AND different than the current
+     * implementation, the latter MUST delegate to the `diffTree()` method of
+     * the specified implementation and not descent into that branch further
+     * itself.
      *
      * Furthermore, if (and only if) an element has the `__diff` control
      * attribute set to `false`, then:
      *
-     * 1) Computing the difference between old & new branch MUST be
-     *    skipped
-     * 2) The implementation MUST recursively call any `release` life
-     *    cycle methods present anywhere in the current `prev` tree
-     *    (branch). The recursive release process itself is implemented
-     *    by the exported `releaseDeep()` function in `diff.ts`. Custom
-     *    implementations are encouraged to reuse this, since that
-     *    function also takes care of handling the `__release` attrib:
-     *    if the attrib is present and set to false, `releaseDeep()`
-     *    will not descend into the branch any further.
-     * 3) Call the current implementation's `replaceChild()` method to
-     *    replace the old element / branch with the new one.
+     * 1) Computing the difference between old & new branch MUST be skipped
+     * 2) The implementation MUST recursively call any `release` life cycle
+     *    methods present anywhere in the current `prev` tree (branch). The
+     *    recursive release process itself is implemented by the exported
+     *    `releaseDeep()` function in `diff.ts`. Custom implementations are
+     *    encouraged to reuse this, since that function also takes care of
+     *    handling the `__release` attrib: if the attrib is present and set to
+     *    false, `releaseDeep()` will not descend into the branch any further.
+     * 3) Call the current implementation's `replaceChild()` method to replace
+     *    the old element / branch with the new one.
      *
      * @param opts - hdom config options
      * @param parent - parent node in target (e.g. DOM element)
@@ -331,15 +311,13 @@ export interface HDOMImplementation<T> {
      */
     diffTree(opts: Partial<HDOMOpts>, parent: T, prev: any[], curr: any[], child?: number): void;
     /**
-     * Creates a new element of type `tag` with optional `attribs`. If
-     * `parent` is not `null`, the new element will be inserted as child
-     * at given `insert` index. If `child` is missing, the element will
-     * be appended to the `parent`'s list of children. Returns new
-     * target DOM node.
+     * Creates a new element of type `tag` with optional `attribs`. If `parent`
+     * is not `null`, the new element will be inserted as child at given
+     * `insert` index. If `child` is missing, the element will be appended to
+     * the `parent`'s list of children. Returns new target DOM node.
      *
-     * In the default implementation, if `tag` is a known SVG element
-     * name, the new element will be created with the proper SVG XML
-     * namespace.
+     * In the default implementation, if `tag` is a known SVG element name, the
+     * new element will be created with the proper SVG XML namespace.
      *
      * @param parent - parent node in target (e.g. DOM element)
      * @param tag - element tag name
@@ -348,8 +326,8 @@ export interface HDOMImplementation<T> {
      */
     createElement(parent: T, tag: string, attribs?: any, child?: number): T;
     /**
-     * Creates and appends the given `content` as text child node to
-     * `parent` in the target.
+     * Creates and appends the given `content` as text child node to `parent` in
+     * the target.
      *
      * @param parent - parent node in target (e.g. DOM element)
      * @param content - content
@@ -357,15 +335,14 @@ export interface HDOMImplementation<T> {
     createTextElement(parent: T, content: string): T;
     /**
      * Attempts to find an element with the given `id` attribute in the
-     * implementation's tree. In the default implementation this is
-     * merely delegated to `document.getElementById()`.
+     * implementation's tree. In the default implementation this is merely
+     * delegated to `document.getElementById()`.
      *
      * @param id - element ID
      */
     getElementById(id: string): T | null;
     /**
-     * A (potentially) optimized version of these 2 operations in
-     * sequence:
+     * A (potentially) optimized version of these 2 operations in sequence:
      *
      * ```
      * impl.removeChild(parent, child);
@@ -392,11 +369,10 @@ export interface HDOMImplementation<T> {
      */
     removeChild(parent: T, i: number): void;
     /**
-     * Sets the given attribute `id` to new `value`. Note: `value`
-     * itself can be a function and if so, the default behavior is to
-     * call this function with the also provided `attribs` object to
-     * allow it to produce a derived value. See `setAttrib()` (dom.ts)
-     * for details.
+     * Sets the given attribute `id` to new `value`. Note: `value` itself can be
+     * a function and if so, the default behavior is to call this function with
+     * the also provided `attribs` object to allow it to produce a derived
+     * value. See `setAttrib()` (dom.ts) for details.
      *
      * @param element - target element / DOM node
      * @param id - attribute name
@@ -405,9 +381,9 @@ export interface HDOMImplementation<T> {
      */
     setAttrib(element: T, id: string, value: any, attribs?: any): void;
     /**
-     * Removes given `attribs` from target `element`. The attributes
-     * from the previous tree are provided for reference (e.g. to be
-     * able to remove DOM event listeners).
+     * Removes given `attribs` from target `element`. The attributes from the
+     * previous tree are provided for reference (e.g. to be able to remove DOM
+     * event listeners).
      *
      * @param element - target element / DOM node
      * @param attribs - element attributes
@@ -415,12 +391,11 @@ export interface HDOMImplementation<T> {
      */
     removeAttribs(element: T, attribs: string[], prevAttribs: any): void;
     /**
-     * Sets target `element`'s text / body content. Note: In the default
-     * browser DOM implementation, this will implicitly remove any
-     * existing child elements in the target. In practice this function
-     * is only applied to `["span"]` elements, since (by default) any
-     * body content is automatically wrapped in such by
-     * `normalizeTree()`.
+     * Sets target `element`'s text / body content. Note: In the default browser
+     * DOM implementation, this will implicitly remove any existing child
+     * elements in the target. In practice this function is only applied to
+     * `["span"]` elements, since (by default) any body content is automatically
+     * wrapped in such by `normalizeTree()`.
      *
      * @param element - target element / DOM node
      * @param value - new content

package/diff.d.ts

@@ -35,10 +35,11 @@ export declare const diffAttributes: <T>(impl: HDOMImplementation<T>, el: T, pre
  */
 export declare const releaseTree: (tree: any) => void;
 /**
- * Customized version {@link @thi.ng/equiv#equiv} which takes `__diff`
- * attributes into account (at any nesting level). If an hdom element's
- * attribute object contains `__diff: false`, the object will ALWAYS be
- * considered unequal, even if all other attributes in the object are
+ * Customized version
+ * [`equiv()`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html) which
+ * takes `__diff` attributes into account (at any nesting level). If an hdom
+ * element's attribute object contains `__diff: false`, the object will ALWAYS
+ * be considered unequal, even if all other attributes in the object are
  * equivalent.
  *
  * @param a -

package/diff.js

@@ -221,10 +221,11 @@ const extractEquivElements = (edits) => {
     return equiv;
 };
 /**
- * Customized version {@link @thi.ng/equiv#equiv} which takes `__diff`
- * attributes into account (at any nesting level). If an hdom element's
- * attribute object contains `__diff: false`, the object will ALWAYS be
- * considered unequal, even if all other attributes in the object are
+ * Customized version
+ * [`equiv()`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html) which
+ * takes `__diff` attributes into account (at any nesting level). If an hdom
+ * element's attribute object contains `__diff: false`, the object will ALWAYS
+ * be considered unequal, even if all other attributes in the object are
  * equivalent.
  *
  * @param a -

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/hdom",
-  "version": "9.2.0",
+  "version": "9.2.1",
   "description": "Lightweight vanilla ES6 UI component trees with customizable branch-local behaviors",
   "type": "module",
   "module": "./index.js",
@@ -37,18 +37,18 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.6.0",
+    "@thi.ng/api": "^8.6.1",
     "@thi.ng/checks": "^3.3.5",
-    "@thi.ng/diff": "^5.1.19",
+    "@thi.ng/diff": "^5.1.20",
     "@thi.ng/equiv": "^2.1.15",
     "@thi.ng/errors": "^2.2.6",
-    "@thi.ng/hiccup": "^4.2.26",
+    "@thi.ng/hiccup": "^4.2.27",
     "@thi.ng/logger": "^1.4.5",
     "@thi.ng/prefixes": "^2.1.15"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.33.7",
-    "@thi.ng/atom": "^5.1.25",
+    "@thi.ng/atom": "^5.1.26",
     "@thi.ng/testament": "^0.3.7",
     "rimraf": "^3.0.2",
     "tools": "^0.0.1",
@@ -131,5 +131,5 @@
     "status": "completed",
     "year": 2015
   },
-  "gitHead": "f445a9cc8022bcdebbf6ff91fd66ced016d72f01\n"
+  "gitHead": "7b2af448da8a63fb21704a79cc4cdf1f3d7d7a64\n"
 }

package/start.d.ts

@@ -1,43 +1,40 @@
 import type { HDOMImplementation, HDOMOpts } from "./api.js";
 /**
- * Takes an hiccup tree (array, function or component object w/ life
- * cycle methods) and an optional object of DOM update options. Starts
- * RAF update loop, in each iteration first normalizing given tree, then
- * computing diff to previous frame's tree and applying any changes to
- * the real DOM. The `ctx` option can be used for passing arbitrary
- * config data or state down into the hiccup component tree. Any
- * embedded component function in the tree will receive this context
- * object (shallow copy) as first argument, as will life cycle methods
- * in component objects. If the `autoDerefKeys` option is given,
- * attempts to auto-expand/deref the given keys in the user supplied
- * context object (`ctx` option) prior to *each* tree normalization. All
- * of these values should implement the {@link @thi.ng/api#IDeref}
- * interface (e.g. atoms, cursors, views, rstreams etc.). This feature
- * can be used to define dynamic contexts linked to the main app state,
- * e.g. using derived views provided by {@link @thi.ng/atom# | @thi.ng/atom}.
+ * Takes an hiccup tree (array, function or component object w/ life cycle
+ * methods) and an optional object of DOM update options. Starts RAF update
+ * loop, in each iteration first normalizing given tree, then computing diff to
+ * previous frame's tree and applying any changes to the real DOM. The `ctx`
+ * option can be used for passing arbitrary config data or state down into the
+ * hiccup component tree. Any embedded component function in the tree will
+ * receive this context object (shallow copy) as first argument, as will life
+ * cycle methods in component objects. If the `autoDerefKeys` option is given,
+ * attempts to auto-expand/deref the given keys in the user supplied context
+ * object (`ctx` option) prior to *each* tree normalization. All of these values
+ * should implement the
+ * [`IDeref`](https://docs.thi.ng/umbrella/api/interfaces/IDeref.html) interface
+ * (e.g. atoms, cursors, views, rstreams etc.). This feature can be used to
+ * define dynamic contexts linked to the main app state, e.g. using derived
+ * views provided by [`thi.ng/atom`](https://thi.ng/atom).
  *
- * **Selective updates**: No updates will be applied if the given hiccup
- * tree is `undefined` or `null` or a root component function returns no
- * value. This way a given root function can do some state handling of
- * its own and implement fail-fast checks to determine no DOM updates
- * are necessary, save effort re-creating a new hiccup tree and request
- * skipping DOM updates via this function. In this case, the previous
- * DOM tree is kept around until the root function returns a tree again,
- * which then is diffed and applied against the previous tree kept as
- * usual. Any number of frames may be skipped this way.
+ * **Selective updates**: No updates will be applied if the given hiccup tree is
+ * `undefined` or `null` or a root component function returns no value. This way
+ * a given root function can do some state handling of its own and implement
+ * fail-fast checks to determine no DOM updates are necessary, save effort
+ * re-creating a new hiccup tree and request skipping DOM updates via this
+ * function. In this case, the previous DOM tree is kept around until the root
+ * function returns a tree again, which then is diffed and applied against the
+ * previous tree kept as usual. Any number of frames may be skipped this way.
  *
- * **Important:** Unless the `hydrate` option is enabled, the parent
- * element given is assumed to have NO children at the time when
- * `start()` is called. Since hdom does NOT track the real DOM, the
- * resulting changes will result in potentially undefined behavior if
- * the parent element wasn't empty. Likewise, if `hydrate` is enabled,
- * it is assumed that an equivalent DOM (minus listeners) already exists
- * (i.e. generated via SSR) when `start()` is called. Any other
- * discrepancies between the pre-existing DOM and the hdom trees will
+ * **Important:** Unless the `hydrate` option is enabled, the parent element
+ * given is assumed to have NO children at the time when `start()` is called.
+ * Since hdom does NOT track the real DOM, the resulting changes will result in
+ * potentially undefined behavior if the parent element wasn't empty. Likewise,
+ * if `hydrate` is enabled, it is assumed that an equivalent DOM (minus
+ * listeners) already exists (i.e. generated via SSR) when `start()` is called.
+ * Any other discrepancies between the pre-existing DOM and the hdom trees will
  * cause undefined behavior.
  *
- * Returns a function, which when called, immediately cancels the update
- * loop.
+ * Returns a function, which when called, immediately cancels the update loop.
  *
  * @param tree - hiccup DOM tree
  * @param opts - options

package/start.js

@@ -2,44 +2,41 @@ import { derefContext } from "@thi.ng/hiccup/deref";
 import { DEFAULT_IMPL } from "./default.js";
 import { resolveRoot } from "./resolve.js";
 /**
- * Takes an hiccup tree (array, function or component object w/ life
- * cycle methods) and an optional object of DOM update options. Starts
- * RAF update loop, in each iteration first normalizing given tree, then
- * computing diff to previous frame's tree and applying any changes to
- * the real DOM. The `ctx` option can be used for passing arbitrary
- * config data or state down into the hiccup component tree. Any
- * embedded component function in the tree will receive this context
- * object (shallow copy) as first argument, as will life cycle methods
- * in component objects. If the `autoDerefKeys` option is given,
- * attempts to auto-expand/deref the given keys in the user supplied
- * context object (`ctx` option) prior to *each* tree normalization. All
- * of these values should implement the {@link @thi.ng/api#IDeref}
- * interface (e.g. atoms, cursors, views, rstreams etc.). This feature
- * can be used to define dynamic contexts linked to the main app state,
- * e.g. using derived views provided by {@link @thi.ng/atom# | @thi.ng/atom}.
+ * Takes an hiccup tree (array, function or component object w/ life cycle
+ * methods) and an optional object of DOM update options. Starts RAF update
+ * loop, in each iteration first normalizing given tree, then computing diff to
+ * previous frame's tree and applying any changes to the real DOM. The `ctx`
+ * option can be used for passing arbitrary config data or state down into the
+ * hiccup component tree. Any embedded component function in the tree will
+ * receive this context object (shallow copy) as first argument, as will life
+ * cycle methods in component objects. If the `autoDerefKeys` option is given,
+ * attempts to auto-expand/deref the given keys in the user supplied context
+ * object (`ctx` option) prior to *each* tree normalization. All of these values
+ * should implement the
+ * [`IDeref`](https://docs.thi.ng/umbrella/api/interfaces/IDeref.html) interface
+ * (e.g. atoms, cursors, views, rstreams etc.). This feature can be used to
+ * define dynamic contexts linked to the main app state, e.g. using derived
+ * views provided by [`thi.ng/atom`](https://thi.ng/atom).
  *
- * **Selective updates**: No updates will be applied if the given hiccup
- * tree is `undefined` or `null` or a root component function returns no
- * value. This way a given root function can do some state handling of
- * its own and implement fail-fast checks to determine no DOM updates
- * are necessary, save effort re-creating a new hiccup tree and request
- * skipping DOM updates via this function. In this case, the previous
- * DOM tree is kept around until the root function returns a tree again,
- * which then is diffed and applied against the previous tree kept as
- * usual. Any number of frames may be skipped this way.
+ * **Selective updates**: No updates will be applied if the given hiccup tree is
+ * `undefined` or `null` or a root component function returns no value. This way
+ * a given root function can do some state handling of its own and implement
+ * fail-fast checks to determine no DOM updates are necessary, save effort
+ * re-creating a new hiccup tree and request skipping DOM updates via this
+ * function. In this case, the previous DOM tree is kept around until the root
+ * function returns a tree again, which then is diffed and applied against the
+ * previous tree kept as usual. Any number of frames may be skipped this way.
  *
- * **Important:** Unless the `hydrate` option is enabled, the parent
- * element given is assumed to have NO children at the time when
- * `start()` is called. Since hdom does NOT track the real DOM, the
- * resulting changes will result in potentially undefined behavior if
- * the parent element wasn't empty. Likewise, if `hydrate` is enabled,
- * it is assumed that an equivalent DOM (minus listeners) already exists
- * (i.e. generated via SSR) when `start()` is called. Any other
- * discrepancies between the pre-existing DOM and the hdom trees will
+ * **Important:** Unless the `hydrate` option is enabled, the parent element
+ * given is assumed to have NO children at the time when `start()` is called.
+ * Since hdom does NOT track the real DOM, the resulting changes will result in
+ * potentially undefined behavior if the parent element wasn't empty. Likewise,
+ * if `hydrate` is enabled, it is assumed that an equivalent DOM (minus
+ * listeners) already exists (i.e. generated via SSR) when `start()` is called.
+ * Any other discrepancies between the pre-existing DOM and the hdom trees will
  * cause undefined behavior.
  *
- * Returns a function, which when called, immediately cancels the update
- * loop.
+ * Returns a function, which when called, immediately cancels the update loop.
  *
  * @param tree - hiccup DOM tree
  * @param opts - options