Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
Socket
Sign inDemoInstall
Socket
Sign inDemoInstall

@thi.ng/hdom

Package Overview
Dependencies
Maintainers
1
Versions
278
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@thi.ng/hdom - npm Package Compare versions

Comparing version 9.2.0 to 9.2.1

409

api.d.ts
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` 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` 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.
*/

@@ -42,46 +39,44 @@ release?(ctx: any, ...args: any[]): void;

/**
* 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.
* 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).
* 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.
*/

@@ -106,14 +101,14 @@ __serialize?: boolean;

/**
* 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).
*

@@ -124,4 +119,4 @@ * @defaultValue none

/**
* 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).
*

@@ -132,5 +127,4 @@ * @defaultValue true

/**
* 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.
*

@@ -141,10 +135,10 @@ * @defaultValue true

/**
* 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.
*

@@ -160,39 +154,36 @@ * @defaultValue false

/**
* 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`.
* 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.
* 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.
* 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:
* Calling this function is a prerequisite before passing a component tree
* to `diffTree()`. Recursively expands given hiccup component tree into its
* canonical form:
*

@@ -205,35 +196,32 @@ * ```

* - 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.
* - 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.
* 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.
* 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.
* See `normalizeElement` (normalize.ts) for further details about the
* canonical element form.
*

@@ -245,25 +233,22 @@ * @param tree - component 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.
* 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.
* 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`.
* 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.
* 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.
*

@@ -277,14 +262,12 @@ * @param parent - parent node in target (e.g. DOM element)

/**
* 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.
* 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.
* 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.
*

@@ -298,22 +281,21 @@ * @param opts - hdom config options

/**
* 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).
* 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.
* 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.
*

@@ -323,14 +305,12 @@ * Furthermore, if (and only if) an element has the `__diff` control

*
* 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.
*

@@ -345,11 +325,9 @@ * @param opts - hdom config options

/**
* 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.
*

@@ -363,4 +341,4 @@ * @param parent - parent node in target (e.g. DOM element)

/**
* 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.
*

@@ -373,4 +351,4 @@ * @param parent - parent node in target (e.g. DOM element)

* 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()`.
*

@@ -381,4 +359,3 @@ * @param id - element ID

/**
* A (potentially) optimized version of these 2 operations in
* sequence:
* A (potentially) optimized version of these 2 operations in sequence:
*

@@ -410,7 +387,6 @@ * ```

/**
* 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.
*

@@ -424,5 +400,5 @@ * @param element - target element / DOM node

/**
* 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).
*

@@ -435,8 +411,7 @@ * @param element - target element / DOM node

/**
* 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()`.
*

@@ -443,0 +418,0 @@ * @param element - target element / DOM node

2

CHANGELOG.md
# Change Log
- **Last updated**: 2022-12-16T12:52:25Z
- **Last updated**: 2022-12-20T16:33:11Z
- **Generator**: [thi.ng/monopub](https://thi.ng/monopub)

@@ -5,0 +5,0 @@

9

diff.d.ts

@@ -38,6 +38,7 @@ import type { HDOMImplementation, HDOMOpts } from "./api.js";

/**
* 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.

@@ -44,0 +45,0 @@ *

9

diff.js

@@ -224,6 +224,7 @@ import { SEMAPHORE } from "@thi.ng/api/api";

/**
* 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.

@@ -230,0 +231,0 @@ *

12

package.json
{
"name": "@thi.ng/hdom",
"version": "9.2.0",
"version": "9.2.1",
"description": "Lightweight vanilla ES6 UI component trees with customizable branch-local behaviors",

@@ -40,8 +40,8 @@ "type": "module",

"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",

@@ -52,3 +52,3 @@ "@thi.ng/prefixes": "^2.1.15"

"@microsoft/api-extractor": "^7.33.7",
"@thi.ng/atom": "^5.1.25",
"@thi.ng/atom": "^5.1.26",
"@thi.ng/testament": "^0.3.7",

@@ -136,3 +136,3 @@ "rimraf": "^3.0.2",

},
"gitHead": "f445a9cc8022bcdebbf6ff91fd66ced016d72f01\n"
"gitHead": "7b2af448da8a63fb21704a79cc4cdf1f3d7d7a64\n"
}

65

start.d.ts
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.
*

@@ -42,0 +39,0 @@ * @param tree - hiccup DOM tree

65

start.js

@@ -5,40 +5,37 @@ import { derefContext } from "@thi.ng/hiccup/deref";

/**
* 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.
*

@@ -45,0 +42,0 @@ * @param tree - hiccup DOM tree

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc