incajs 0.0.15 → 0.0.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/README.md +3 -2
  2. package/dist/callbacks.d.mts +31 -0
  3. package/dist/chunks/handle-SWQTonXe.js +180 -0
  4. package/dist/chunks/hooks-BgB7lzTv.js +201 -0
  5. package/dist/chunks/rendererCore-BWT8KFVJ.js +110 -0
  6. package/dist/element/geometry.d.mts +61 -0
  7. package/dist/element/handle.d.mts +19 -0
  8. package/dist/element/lifecycle.d.mts +51 -0
  9. package/dist/{vue/scrollIntoViewArgs.d.mts → element/scroll.d.mts} +20 -0
  10. package/dist/element/shadowTree.d.mts +64 -0
  11. package/dist/element/types.d.mts +120 -0
  12. package/dist/events.d.mts +5 -20
  13. package/dist/index.d.mts +4 -0
  14. package/dist/index.js +3 -5
  15. package/dist/native.d.mts +9 -2
  16. package/dist/rendererCore.d.mts +10 -8
  17. package/dist/rendererCore.js +4 -37
  18. package/dist/targets.d.mts +1 -0
  19. package/dist/tree.d.mts +28 -9
  20. package/dist/types.d.mts +18 -15
  21. package/dist/vue/createApp.d.mts +8 -9
  22. package/dist/vue/index.d.mts +0 -6
  23. package/dist/vue/nodeOps.d.mts +19 -122
  24. package/dist/vue/patchProp.d.mts +2 -3
  25. package/dist/vue.js +69 -301
  26. package/dist/window.d.mts +7 -5
  27. package/package.json +6 -2
  28. package/dist/chunks/tree-Ds0zSuJO.js +0 -143
  29. package/dist/vue/activeElement.d.mts +0 -7
  30. package/dist/vue/createElement.d.mts +0 -13
  31. package/dist/vue/destroyedNodes.d.mts +0 -13
  32. package/dist/vue/elements.d.mts +0 -24
  33. package/dist/vue/layoutBox.d.mts +0 -12
  34. package/dist/vue/offsetOf.d.mts +0 -14
  35. package/dist/vue/offsetParent.d.mts +0 -10
  36. package/dist/vue/rectOf.d.mts +0 -25
  37. package/dist/vue/scrollPosition.d.mts +0 -22
  38. package/dist/vue/skipReactive.d.mts +0 -8
  39. package/dist/vue/tabIndexOf.d.mts +0 -9
  40. /package/dist/{createEventTarget.d.mts → eventTarget.d.mts} +0 -0
@@ -0,0 +1,64 @@
1
+ import { TagName } from '../types.mts';
2
+ import { IncaElement, IncaNode, IncaText } from './types.mts';
3
+ /**
4
+ * Allocates a new element node for `tag`.
5
+ * @param tag - the node's element kind
6
+ * @returns the new, parentless, childless element
7
+ */
8
+ export declare function createElementNode(tag: TagName): IncaElement;
9
+ /**
10
+ * Creates a text leaf.
11
+ * @param text - the initial text content
12
+ * @returns the new text leaf
13
+ */
14
+ export declare function createTextNode(text: string): IncaText;
15
+ /**
16
+ * Creates the hidden container that stands in for a comment node, such as a
17
+ * placeholder for conditional content.
18
+ * @returns the new hidden element
19
+ */
20
+ export declare function createCommentNode(): IncaElement;
21
+ /**
22
+ * Updates a text leaf's content in place.
23
+ * @param node - the text leaf to update
24
+ * @param text - the new text content
25
+ */
26
+ export declare function setText(node: IncaText, text: string): void;
27
+ /**
28
+ * Replaces all of `el`'s children with at most a single text child holding
29
+ * `text`. An empty string leaves `el` childless.
30
+ * @param el - the container whose children are replaced
31
+ * @param text - the new text content
32
+ */
33
+ export declare function setElementText(el: IncaElement, text: string): void;
34
+ /**
35
+ * Attaches `child` to `parent`, before `anchor` or at the end when `anchor` is
36
+ * omitted or `null`. If `anchor` is `child` itself and `child` is already in
37
+ * `parent`, nothing changes. A `child` attached elsewhere is detached first,
38
+ * so a move keeps the node alive.
39
+ * @param child - the node being attached
40
+ * @param parent - the new container
41
+ * @param anchor - the sibling to insert before, or omitted/`null` to append at the end
42
+ */
43
+ export declare function insert(child: IncaNode, parent: IncaElement, anchor?: IncaNode | null): void;
44
+ /**
45
+ * Removes `child` for good: the native node, its whole subtree, and every
46
+ * event listener registered in it.
47
+ *
48
+ * A caller that removes a subtree calls this on its root alone, and the host
49
+ * frees the descendants with it.
50
+ * @param child - the node being removed
51
+ */
52
+ export declare function remove(child: IncaNode): void;
53
+ /**
54
+ * Looks up the current parent.
55
+ * @param node - the node to query
56
+ * @returns the current parent, or `null` if it isn't attached
57
+ */
58
+ export declare function parentNode(node: IncaNode): IncaElement | null;
59
+ /**
60
+ * Looks up the next sibling.
61
+ * @param node - the node to query
62
+ * @returns the sibling immediately after `node` in its parent's children, or `null` if there is none (or `node` isn't attached)
63
+ */
64
+ export declare function nextSibling(node: IncaNode): IncaNode | null;
@@ -0,0 +1,120 @@
1
+ import { IncaEventTarget } from '../types.mts';
2
+ import { RectLike } from './geometry.mts';
3
+ import { ScrollIntoViewOptions, ScrollOptions } from './scroll.mts';
4
+ /**
5
+ * A container node: either a real element or the hidden stand-in that
6
+ * `createCommentNode` makes. It is the only node type that can act as a
7
+ * parent. `parent` and `children` read the node's current position in the
8
+ * tree.
9
+ *
10
+ * After the node is removed, `addEventListener()` and `removeEventListener()`
11
+ * ignore the call, and `dispatchEvent()` returns `true`.
12
+ */
13
+ export interface IncaElement extends IncaEventTarget {
14
+ /**
15
+ * The `id` attribute, or an empty string when it is unset. Assigning sets
16
+ * the attribute to the value as a string. After the node is removed,
17
+ * reading gives an empty string and assigning does nothing.
18
+ */
19
+ id: string;
20
+ /**
21
+ * `"comment"` for the hidden stand-in `createCommentNode` makes;
22
+ * `"element"` for every other container.
23
+ */
24
+ readonly kind: "element" | "comment";
25
+ /** The current parent, or `null` if this node isn't attached to the tree. */
26
+ parent: IncaElement | null;
27
+ /** This node's children, in render order. */
28
+ children: IncaNode[];
29
+ /**
30
+ * Focuses this node next frame. The node needs a `tabindex` attribute. A
31
+ * `true` `preventScroll` keeps every scroll container where it is. After
32
+ * the node is removed, the call does nothing.
33
+ */
34
+ focus(options?: {
35
+ preventScroll?: boolean;
36
+ }): void;
37
+ /** Unfocuses this node next frame, if it is the focused one. */
38
+ blur(): void;
39
+ /**
40
+ * Fires an untrusted `click` at this node. A disabled `button`, a node whose
41
+ * own click is still running and an unknown node ignore the call.
42
+ */
43
+ click(): void;
44
+ /**
45
+ * Whether `other` is this node or one of its descendants in the tree as
46
+ * rendered. `null` and `undefined` give `false`, and any other value that is
47
+ * not a node throws a `TypeError`. After the node is removed, it still answers
48
+ * for the subtree it keeps.
49
+ */
50
+ contains(other: IncaNode | null): boolean;
51
+ /**
52
+ * Assigning sets the `tabindex` attribute to the value's integer part,
53
+ * wrapped to 32 bits. Reading returns the `tabindex` attribute as an
54
+ * integer, or `-1` (`0` for a `button`) when it is unset or invalid.
55
+ * After the node is removed, reading gives that default and assigning does
56
+ * nothing.
57
+ */
58
+ tabIndex: number;
59
+ /**
60
+ * The box this node was drawn at in the last frame, in window logical
61
+ * pixels. A node created in the same task reads all zeros.
62
+ */
63
+ getBoundingClientRect(): RectLike;
64
+ /** The box width from the last frame, rounded. `0` until a frame draws the node. */
65
+ readonly offsetWidth: number;
66
+ /** The box height from the last frame, rounded. `0` until a frame draws the node. */
67
+ readonly offsetHeight: number;
68
+ /** The box's left edge from the last frame, relative to {@link offsetParent}. Stays fixed while the parent scrolls. */
69
+ readonly offsetLeft: number;
70
+ /** The box's top edge from the last frame, relative to {@link offsetParent}. Stays fixed while the parent scrolls. */
71
+ readonly offsetTop: number;
72
+ /**
73
+ * The parent, when this node and the parent both have a box from the last frame.
74
+ * `null` when either lacks a box or there is no parent.
75
+ */
76
+ readonly offsetParent: IncaElement | null;
77
+ /** The box width less both borders, rounded, at least `0`. */
78
+ readonly clientWidth: number;
79
+ /** The box height less both borders, rounded, at least `0`. */
80
+ readonly clientHeight: number;
81
+ /** The border width, rounded. */
82
+ readonly clientLeft: number;
83
+ /** The border width, rounded. */
84
+ readonly clientTop: number;
85
+ /** The horizontal scroll offset. Assigning moves it at once, and reads are clamped to the last frame's maximum. */
86
+ scrollLeft: number;
87
+ /** The vertical scroll offset. Assigning moves it at once, and reads are clamped to the last frame's maximum. */
88
+ scrollTop: number;
89
+ /** The content width: {@link clientWidth} plus the largest horizontal offset. */
90
+ readonly scrollWidth: number;
91
+ /** The content height: {@link clientHeight} plus the largest vertical offset. */
92
+ readonly scrollHeight: number;
93
+ /** Sets the offset to `(left, top)`, or to the options object's `left` and `top`. */
94
+ scrollTo(left?: number, top?: number): void;
95
+ scrollTo(options: ScrollOptions): void;
96
+ /** Adds `(left, top)` to the offset, or the options object's `left` and `top`. */
97
+ scrollBy(left?: number, top?: number): void;
98
+ scrollBy(options: ScrollOptions): void;
99
+ /**
100
+ * Scrolls each scroll container around this node so the node shows. `true`
101
+ * or no argument aligns to the start and `false` to the end. An options
102
+ * object sets `block` (default `"start"`) and `inline` (default `"nearest"`);
103
+ * `behavior` is accepted and ignored. After the node is removed, the call
104
+ * does nothing.
105
+ */
106
+ scrollIntoView(arg?: boolean | ScrollIntoViewOptions): void;
107
+ }
108
+ /** A text leaf node. */
109
+ export interface IncaText {
110
+ /** Discriminates this node within the {@link IncaNode} union. */
111
+ readonly kind: "text";
112
+ /** The current parent, or `null` if this node isn't attached to the tree. */
113
+ parent: IncaElement | null;
114
+ /**
115
+ * The text content, mirroring the value pushed to the native node.
116
+ */
117
+ text: string;
118
+ }
119
+ /** Any node the shadow tree holds: an element, comment, or text leaf. */
120
+ export type IncaNode = IncaElement | IncaText;
package/dist/events.d.mts CHANGED
@@ -1,22 +1,10 @@
1
- import { CallbackId, EventLike, EventListenerOrObject, ListenerOptions, NodeId } from './types.mts';
2
- /**
3
- * @returns how many `(nodeId, event, capture)` groups hold a registration
4
- * @internal
5
- */
6
- export declare function registeredGroupCount(): number;
1
+ import { EventLike, EventListenerOrObject, ListenerOptions, NodeId } from './types.mts';
7
2
  /**
8
3
  * @returns the `eventId` of the newest event any registered listener has
9
4
  * received, or 0 before the first. Ids grow with each event, and every
10
5
  * listener of one event receives the same id.
11
6
  */
12
7
  export declare function latestEventId(): number;
13
- /**
14
- * Drops the JS half of every registration in `callbackIds`. The native half
15
- * is already gone by the time this runs — `destroyNode` takes both.
16
- * @param callbackIds - ids the host reported as released
17
- * @internal
18
- */
19
- export declare function releaseCallbacks(callbackIds: readonly CallbackId[]): void;
20
8
  /**
21
9
  * Registers `listener` for `event` on `nodeId`. Registering the same listener
22
10
  * for the same node, event and `capture` again changes nothing, and the first
@@ -26,13 +14,15 @@ export declare function releaseCallbacks(callbackIds: readonly CallbackId[]): vo
26
14
  * See the `EventListener` type for the fields an event carries.
27
15
  * @param nodeId - the node to listen on
28
16
  * @param event - the event name (e.g. `"click"`)
29
- * @param listener - a function, or an object whose `handleEvent` method is
30
- * called with the object as `this` when the event fires
17
+ * @param listener - a function, called with the event's `currentTarget` as
18
+ * `this`, or an object whose `handleEvent` method is called with the object
19
+ * as `this` when the event fires
31
20
  * @param options - `capture` listens while the event travels down to the
32
21
  * target, `passive` ignores `preventDefault()` calls in `listener`, and
33
22
  * `once` removes the listener before it first runs
34
23
  * @throws TypeError when `nodeId` is malformed
35
24
  * @throws TypeError when `nodeId` names no node
25
+ * @throws RangeError when the host has issued its last callback id
36
26
  */
37
27
  export declare function addEventListener(nodeId: NodeId, event: string, listener: EventListenerOrObject | null, options?: ListenerOptions): void;
38
28
  /**
@@ -78,8 +68,3 @@ export declare function focus(nodeId: NodeId, preventScroll?: boolean): void;
78
68
  * @param nodeId - the node to unfocus
79
69
  */
80
70
  export declare function blur(nodeId: NodeId): void;
81
- /**
82
- * Returns the id of the focused node.
83
- * @returns the focused node's id, or `null` when no node has focus
84
- */
85
- export declare function focusedNode(): NodeId | null;
package/dist/index.d.mts CHANGED
@@ -1,2 +1,6 @@
1
+ export { activeElement } from './element/handle.mts';
1
2
  export { window } from './window.mts';
3
+ export type { RectLike, RectValues } from './element/geometry.mts';
4
+ export type { ScrollIntoViewOptions, ScrollOptions } from './element/scroll.mts';
5
+ export type { IncaElement, IncaNode } from './element/types.mts';
2
6
  export type { AttributeValue, CallbackId, EventLike, EventListener, EventListenerObject, EventListenerOrObject, IncaEventTarget, ListenerOptions, NodeId, StyleProps, TagName, } from './types.mts';
package/dist/index.js CHANGED
@@ -1,5 +1,3 @@
1
- import { g as e, u as t } from "./chunks/tree-Ds0zSuJO.js";
2
- //#region src/window.mts
3
- var n = /* @__PURE__ */ e(t, ["wheel"]);
4
- //#endregion
5
- export { n as window };
1
+ import { t as e } from "./chunks/hooks-BgB7lzTv.js";
2
+ import { t } from "./chunks/handle-SWQTonXe.js";
3
+ export { t as activeElement, e as window };
package/dist/native.d.mts CHANGED
@@ -1,5 +1,8 @@
1
1
  import { AttributeValue, CallbackId, EventLike, NodeId, ScrollAlignment } from './types.mts';
2
- /** The host-injected object every wrapper in this package forwards to. Not part of the public surface — reach it through the wrappers instead. */
2
+ /**
3
+ * The host-injected object every wrapper in this package forwards to. Not part of the public
4
+ * surface.
5
+ */
3
6
  interface IncaNative {
4
7
  rootNodeId(): NodeId;
5
8
  createNode(tag: string): NodeId;
@@ -11,9 +14,11 @@ interface IncaNative {
11
14
  removeAttribute(nodeId: NodeId, key: string): void;
12
15
  setStyle(nodeId: NodeId, key: string, value: AttributeValue): void;
13
16
  removeStyle(nodeId: NodeId, key: string): void;
14
- addEventListener(nodeId: NodeId, event: string, callbackId: CallbackId, capture?: boolean, passive?: boolean): void;
17
+ addEventListener(nodeId: NodeId, event: string, capture?: boolean, passive?: boolean): CallbackId;
15
18
  removeEventListener(nodeId: NodeId, event: string, callbackId: CallbackId): boolean;
16
19
  destroyNode(nodeId: NodeId): CallbackId[];
20
+ holdNode(nodeId: NodeId): void;
21
+ releaseNode(nodeId: NodeId): void;
17
22
  focusNode(nodeId: NodeId, preventScroll?: boolean): void;
18
23
  blurNode(nodeId: NodeId): void;
19
24
  focusedNode(): NodeId | null;
@@ -29,6 +34,8 @@ export type HostCallback = (...args: unknown[]) => void;
29
34
  declare global {
30
35
  var __inca_native__: IncaNative;
31
36
  var __inca_callbacks__: Record<CallbackId, HostCallback>;
37
+ var __inca_released__: (nodeIds: NodeId[], callbackIds: CallbackId[]) => void;
38
+ var __inca_targets__: (nodeIds: NodeId[]) => unknown[];
32
39
  }
33
40
  export declare function native(): IncaNative;
34
41
  export {};
@@ -1,12 +1,14 @@
1
- export { createEventTarget } from './createEventTarget.mts';
2
- export { addEventListener, removeEventListener, latestEventId, focus, blur, focusedNode, dispatchEvent, click, } from './events.mts';
3
- export { appendChild, createNode, destroyNode, insertBefore, removeChild, rootNodeId, setAttribute, getAttribute, layoutOf, scrollOf, scrollNode, scrollIntoViewNode, removeAttribute, setStyle, removeStyle, } from './tree.mts';
1
+ export { createEventTarget } from './eventTarget.mts';
2
+ export { window } from './window.mts';
3
+ export { addEventListener, removeEventListener, latestEventId, focus, blur, dispatchEvent, click, } from './events.mts';
4
+ export { focusedNode, appendChild, createNode, destroyNode, holdNode, releaseNode, insertBefore, removeChild, rootNodeId, setAttribute, getAttribute, layoutOf, scrollOf, scrollNode, scrollIntoViewNode, removeAttribute, setStyle, removeStyle, } from './tree.mts';
5
+ export { createIncaElement } from './element/handle.mts';
6
+ export { isDestroyed } from './element/lifecycle.mts';
7
+ export { createCommentNode, createElementNode, createTextNode, insert, nextSibling, parentNode, remove, setElementText, setText, } from './element/shadowTree.mts';
4
8
  export type * from './types.mts';
9
+ export type * from './element/types.mts';
5
10
  /**
6
- * The tree/event primitives a custom renderer (`incajs/vue`) drives the
7
- * native tree through.
8
- *
9
- * Also the seam a renderer's own tests mock against, in place of a real
10
- * `globalThis.__inca_native__`.
11
+ * What a custom renderer (`incajs/vue`) drives the host through: the tree and
12
+ * event calls, the element handles and the shadow tree.
11
13
  */
12
14
  export type IncaCore = typeof import('./rendererCore.mts');
@@ -1,37 +1,4 @@
1
- import { C as e, S as t, _ as n, a as r, b as i, c as a, d as o, f as s, g as c, h as l, i as u, l as d, m as f, n as p, o as m, p as h, r as g, s as _, t as v, u as y, v as b, w as x, x as S, y as C } from "./chunks/tree-Ds0zSuJO.js";
2
- //#region \0rolldown/runtime.js
3
- var w = Object.defineProperty, T = /* @__PURE__ */ ((e, t) => {
4
- let n = {};
5
- for (var r in e) w(n, r, {
6
- get: e[r],
7
- enumerable: !0
8
- });
9
- return t || w(n, Symbol.toStringTag, { value: "Module" }), n;
10
- })({
11
- addEventListener: () => n,
12
- appendChild: () => v,
13
- blur: () => b,
14
- click: () => C,
15
- createEventTarget: () => c,
16
- createNode: () => p,
17
- destroyNode: () => g,
18
- dispatchEvent: () => i,
19
- focus: () => S,
20
- focusedNode: () => t,
21
- getAttribute: () => u,
22
- insertBefore: () => r,
23
- latestEventId: () => e,
24
- layoutOf: () => m,
25
- removeAttribute: () => _,
26
- removeChild: () => a,
27
- removeEventListener: () => x,
28
- removeStyle: () => d,
29
- rootNodeId: () => y,
30
- scrollIntoViewNode: () => o,
31
- scrollNode: () => s,
32
- scrollOf: () => h,
33
- setAttribute: () => f,
34
- setStyle: () => l
35
- });
36
- //#endregion
37
- export { n as addEventListener, v as appendChild, b as blur, C as click, c as createEventTarget, p as createNode, g as destroyNode, i as dispatchEvent, S as focus, t as focusedNode, u as getAttribute, r as insertBefore, e as latestEventId, m as layoutOf, _ as removeAttribute, a as removeChild, x as removeEventListener, d as removeStyle, y as rootNodeId, o as scrollIntoViewNode, s as scrollNode, h as scrollOf, f as setAttribute, l as setStyle, T as t };
1
+ import { a as e, c as t, i as n, l as r, n as i, o as a, r as o, s, u as c } from "./chunks/rendererCore-BWT8KFVJ.js";
2
+ import { C as l, D as u, E as d, N as f, S as p, T as m, _ as h, a as g, b as _, c as v, d as y, f as b, g as x, h as S, i as C, k as w, l as T, m as E, n as D, o as O, p as k, r as A, s as j, t as M, u as N, v as P, w as F, x as I, y as L } from "./chunks/hooks-BgB7lzTv.js";
3
+ import { n as R } from "./chunks/handle-SWQTonXe.js";
4
+ export { I as addEventListener, D as appendChild, p as blur, l as click, i as createCommentNode, o as createElementNode, _ as createEventTarget, R as createIncaElement, A as createNode, n as createTextNode, C as destroyNode, F as dispatchEvent, m as focus, g as focusedNode, O as getAttribute, j as holdNode, e as insert, v as insertBefore, w as isDestroyed, d as latestEventId, T as layoutOf, a as nextSibling, s as parentNode, N as releaseNode, f as releaseWhenCollected, t as remove, y as removeAttribute, b as removeChild, u as removeEventListener, k as removeStyle, E as rootNodeId, S as scrollIntoViewNode, x as scrollNode, h as scrollOf, P as setAttribute, r as setElementText, L as setStyle, c as setText, M as window };
@@ -0,0 +1 @@
1
+ export {};
package/dist/tree.d.mts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { AttributeValue, NodeId, ScrollAlignment, StyleProps, TagName } from './types.mts';
2
2
  /**
3
- * Returns the host-allocated root container's id — the node an app attaches
3
+ * Returns the host-allocated root container's id, the node an app attaches
4
4
  * itself under. The host allocates it with the tree, so this resolves from
5
5
  * the first call and names the same node for the engine's lifetime.
6
6
  * @returns the root node's id
@@ -8,7 +8,9 @@ import { AttributeValue, NodeId, ScrollAlignment, StyleProps, TagName } from './
8
8
  export declare function rootNodeId(): NodeId;
9
9
  /**
10
10
  * Allocates a new node of kind `tag` in the native tree. The node starts out
11
- * detached — attach it with {@link appendChild}/{@link insertBefore}.
11
+ * detached. Attach it with {@link appendChild}/{@link insertBefore}. The host
12
+ * frees the node at the start of the next frame unless it is inserted or held
13
+ * with {@link holdNode} by then.
12
14
  * @param tag - the node's element kind
13
15
  * @returns the new node's id
14
16
  */
@@ -24,17 +26,16 @@ export declare function appendChild(parentId: NodeId, childId: NodeId): void;
24
26
  * Attaches `childId` as a child of `parentId`, positioned before `anchorId`
25
27
  * (or at the end, if `anchorId` is `null`). If `anchorId` names a real node
26
28
  * that just isn't currently a child of `parentId`, this falls back to
27
- * appending at the end instead of throwing — only a wholly unknown
28
- * `anchorId` raises.
29
+ * appending at the end. Only a wholly unknown `anchorId` raises.
29
30
  * @param parentId - the container to attach to
30
31
  * @param childId - the node being attached
31
32
  * @param anchorId - the sibling to insert before, or `null` to append at the end
32
33
  */
33
34
  export declare function insertBefore(parentId: NodeId, childId: NodeId, anchorId: NodeId | null): void;
34
35
  /**
35
- * Detaches `childId` from `parentId`. The detached node stays alive (and
36
- * keeps its own children) — it isn't freed, so it can be re-attached
37
- * elsewhere. Use {@link destroyNode} for a node that isn't coming back.
36
+ * Detaches `childId` from `parentId`. The detached node keeps its own children
37
+ * and is freed at the start of the next frame unless it is inserted or held
38
+ * with {@link holdNode} by then. Use {@link destroyNode} to free it at once.
38
39
  * @param parentId - the current container
39
40
  * @param childId - the node being detached
40
41
  */
@@ -44,11 +45,24 @@ export declare function removeChild(parentId: NodeId, childId: NodeId): void;
44
45
  * event listener registered anywhere in it. Destroying an already-destroyed
45
46
  * node does nothing. The host's own root cannot be destroyed and raises.
46
47
  *
47
- * Nothing else frees a node: a subtree dropped with {@link removeChild}
48
- * alone stays allocated for the life of the engine.
48
+ * Also drops the hold of {@link holdNode}.
49
49
  * @param nodeId - the node that isn't coming back
50
50
  */
51
51
  export declare function destroyNode(nodeId: NodeId): void;
52
+ /**
53
+ * Keeps `nodeId` and its subtree alive while it has no parent. The host frees
54
+ * a parentless node that is neither held nor inserted by the start of the next
55
+ * frame. Holding a held or attached node changes nothing visible.
56
+ * @param nodeId - the node to keep
57
+ * @throws {TypeError} when `nodeId` names no node
58
+ */
59
+ export declare function holdNode(nodeId: NodeId): void;
60
+ /**
61
+ * Ends the hold of {@link holdNode}. A node with no parent is freed at the
62
+ * start of the next frame. An unknown id does nothing.
63
+ * @param nodeId - the node to let go
64
+ */
65
+ export declare function releaseNode(nodeId: NodeId): void;
52
66
  /**
53
67
  * Sets a non-style attribute/prop on `nodeId`. See {@link setStyle} for
54
68
  * layout/paint properties, which live in a separate map.
@@ -136,3 +150,8 @@ export declare function setStyle(nodeId: NodeId, key: string, value: AttributeVa
136
150
  * @param key - the style property name in any of the three spellings
137
151
  */
138
152
  export declare function removeStyle(nodeId: NodeId, key: string): void;
153
+ /**
154
+ * Returns the id of the focused node.
155
+ * @returns the focused node's id, or `null` when no node has focus
156
+ */
157
+ export declare function focusedNode(): NodeId | null;
package/dist/types.d.mts CHANGED
@@ -5,18 +5,17 @@
5
5
  export type NodeId = number;
6
6
  /**
7
7
  * Id assigned to one registered event listener. Managed internally by
8
- * `addEventListener`/`removeEventListener`/`destroyNode` — callers never see or
9
- * pass one directly.
8
+ * `addEventListener`/`removeEventListener`/`destroyNode`.
10
9
  */
11
10
  export type CallbackId = number;
12
11
  /**
13
- * A value `setAttribute`/`setStyle` can take. Anything else raises a catchable
14
- * exception rather than being silently coerced.
12
+ * A value `setAttribute`/`setStyle` can take. Any other value raises a catchable
13
+ * exception.
15
14
  */
16
15
  export type AttributeValue = string | number | boolean;
17
16
  /**
18
17
  * Element kind passed to `createNode`. `"text"` is the only tag with
19
- * dedicated rendering behavior — it renders its `"value"` attribute followed
18
+ * dedicated rendering behavior: it renders its `"value"` attribute followed
20
19
  * by its descendants' text. Any other string is a generic styled
21
20
  * container; the `string & {}` half of this type keeps `"text"`'s
22
21
  * autocomplete while still accepting an arbitrary tag name.
@@ -29,7 +28,7 @@ export type ScrollAlignment = "start" | "center" | "end" | "nearest";
29
28
  * overload checks. A deliberately incomplete, v1 layout/paint vocabulary. The
30
29
  * renderer also reads the camelCase and kebab-case spellings. An unrecognized
31
30
  * key or a value shape that doesn't parse (e.g. a malformed enum string) is
32
- * ignored by the renderer rather than applied or thrown.
31
+ * ignored by the renderer.
33
32
  */
34
33
  export interface StyleProps {
35
34
  /** Layout mode for this node's children. `"none"` skips both layout and rendering for the whole subtree. */
@@ -40,7 +39,7 @@ export interface StyleProps {
40
39
  justify_content?: "start" | "end" | "center" | "stretch";
41
40
  /** Cross-axis alignment of children within this container. */
42
41
  align_items?: "start" | "end" | "center" | "stretch";
43
- /** Uniform spacing, in px, between children — applied on both axes. */
42
+ /** Uniform spacing, in px, between children, applied on both axes. */
44
43
  gap?: number;
45
44
  /** Fixed width in px, or `"auto"` to size to content. */
46
45
  width?: number | "auto";
@@ -137,8 +136,9 @@ export interface IncaEventTarget {
137
136
  * same `type` and `capture` again changes nothing. A `null` listener is
138
137
  * ignored.
139
138
  * @param type - the event name (e.g. `"keydown"`)
140
- * @param listener - a function, or an object whose `handleEvent` method is
141
- * called when the event fires
139
+ * @param listener - a function, called with the event's `currentTarget` as
140
+ * `this`, or an object whose `handleEvent` method is called with the object
141
+ * as `this` when the event fires
142
142
  * @param options - a {@link ListenerOptions}, or a boolean for `capture`
143
143
  */
144
144
  addEventListener(type: string, listener: EventListenerOrObject | null, options?: boolean | ListenerOptions): void;
@@ -165,12 +165,15 @@ export interface IncaEventTarget {
165
165
  *
166
166
  * The native host calls it with one argument, an object with:
167
167
  * - `type`: the event's name.
168
- * - `target`: the {@link NodeId} the event is about. It is the deepest node
169
- * under the pointer for pointer events, the nearest common ancestor of the
170
- * press and the release for `click`, `dblclick` and `auxclick`, and the
171
- * focused node (the root when nothing is focused) for key events.
172
- * - `currentTarget`: the {@link NodeId} whose listener is running, and
173
- * `null` once the event has been handled.
168
+ * - `target`: the element the event is about, or `window`. It is the deepest
169
+ * element under the pointer for pointer events, the nearest common ancestor
170
+ * of the press and the release for `click`, `dblclick` and `auxclick`, and
171
+ * the focused element for key events. With no such element it is `window`.
172
+ * - `currentTarget`: the element or `window` whose listener is running, and
173
+ * `null` once the event has been handled. A listener function runs with it
174
+ * as `this`.
175
+ * - `composedPath()`: `target` and its ancestors, ending with `window`, and an
176
+ * empty array once the event has been handled.
174
177
  * - `bubbles`, `cancelable` and `composed`: fixed per event name.
175
178
  * - `defaultPrevented`: `true` once a listener called `preventDefault()` on a
176
179
  * cancelable event.
@@ -1,19 +1,18 @@
1
1
  import { App, Component, ComponentPublicInstance } from '@vue/runtime-core';
2
- import { IncaElement } from './nodeOps.mts';
2
+ import { IncaElement } from '../rendererCore.mts';
3
3
  /**
4
- * `@vue/runtime-core`'s `App`, with `mount` additionally callable with no
5
- * argument to target the host's own root container. An intersection rather
6
- * than an `Omit`: `App`'s `this`-returning methods (`use`, `mixin`,
7
- * `component`, `directive`) have to keep this wider `mount` when chained.
4
+ * `@vue/runtime-core`'s `App`, with `mount` also callable with no argument
5
+ * to target the host's own root container. `use`, `mixin`, `component` and
6
+ * `directive` return an `IncaApp`.
8
7
  */
9
8
  export type IncaApp = App<IncaElement> & {
10
9
  mount: (rootContainer?: IncaElement) => ComponentPublicInstance;
11
10
  };
12
11
  /**
13
- * Creates a Vue app whose root mounts against a {@link IncaElement} host
14
- * handle instead of a DOM element. `app.mount()` with no argument targets
15
- * the host's root container; `app.unmount`, `app.use`, etc. all behave
16
- * exactly as `@vue/runtime-core` itself documents them.
12
+ * Creates a Vue app whose root mounts on an {@link IncaElement} host
13
+ * handle. `app.mount()` with no argument targets the host's root
14
+ * container and returns the root component instance. `app.unmount`,
15
+ * `app.use` and the rest behave as `@vue/runtime-core` documents them.
17
16
  * @param rootComponent - the component to mount as the app's root
18
17
  * @param rootProps - props to pass to that root component
19
18
  * @returns the created app
@@ -1,8 +1,2 @@
1
1
  export { createIncaApp } from './createApp.mts';
2
- export { activeElement } from './activeElement.mts';
3
2
  export type { IncaApp } from './createApp.mts';
4
- export type { IncaCore } from '../rendererCore.mts';
5
- export type { RectLike, RectValues } from './rectOf.mts';
6
- export type { ScrollOptions } from './scrollPosition.mts';
7
- export type { ScrollIntoViewOptions } from './scrollIntoViewArgs.mts';
8
- export type { IncaElement, IncaNode } from './nodeOps.mts';