incajs 0.0.16 → 0.0.18

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.
@@ -1,62 +1,55 @@
1
- import { IncaCore, TagName } from '../rendererCore.mts';
1
+ import { TagName } from '../types.mts';
2
2
  import { IncaElement, IncaNode, IncaText } from './types.mts';
3
3
  /**
4
4
  * Allocates a new element node for `tag`.
5
- * @param core - the incajs bindings to drive the native tree through
6
5
  * @param tag - the node's element kind
7
6
  * @returns the new, parentless, childless element
8
7
  */
9
- export declare function createElementNode(core: IncaCore, tag: TagName): IncaElement;
8
+ export declare function createElementNode(tag: TagName): IncaElement;
10
9
  /**
11
10
  * Creates a text leaf.
12
- * @param core - the incajs bindings to drive the native tree through
13
11
  * @param text - the initial text content
14
12
  * @returns the new text leaf
15
13
  */
16
- export declare function createTextNode(core: IncaCore, text: string): IncaText;
14
+ export declare function createTextNode(text: string): IncaText;
17
15
  /**
18
16
  * Creates the hidden container that stands in for a comment node, such as a
19
17
  * placeholder for conditional content.
20
- * @param core - the incajs bindings to drive the native tree through
21
18
  * @returns the new hidden element
22
19
  */
23
- export declare function createCommentNode(core: IncaCore): IncaElement;
20
+ export declare function createCommentNode(): IncaElement;
24
21
  /**
25
22
  * Updates a text leaf's content in place.
26
- * @param core - the incajs bindings to drive the native tree through
27
23
  * @param node - the text leaf to update
28
24
  * @param text - the new text content
29
25
  */
30
- export declare function setText(core: IncaCore, node: IncaText, text: string): void;
26
+ export declare function setText(node: IncaText, text: string): void;
31
27
  /**
32
28
  * Replaces all of `el`'s children with at most a single text child holding
33
29
  * `text`. An empty string leaves `el` childless.
34
- * @param core - the incajs bindings to drive the native tree through
35
30
  * @param el - the container whose children are replaced
36
31
  * @param text - the new text content
37
32
  */
38
- export declare function setElementText(core: IncaCore, el: IncaElement, text: string): void;
33
+ export declare function setElementText(el: IncaElement, text: string): void;
39
34
  /**
40
35
  * Attaches `child` to `parent`, before `anchor` or at the end when `anchor` is
41
36
  * omitted or `null`. If `anchor` is `child` itself and `child` is already in
42
37
  * `parent`, nothing changes. A `child` attached elsewhere is detached first,
43
38
  * so a move keeps the node alive.
44
- * @param core - the incajs bindings to drive the native tree through
45
39
  * @param child - the node being attached
46
40
  * @param parent - the new container
47
41
  * @param anchor - the sibling to insert before, or omitted/`null` to append at the end
48
42
  */
49
- export declare function insert(core: IncaCore, child: IncaNode, parent: IncaElement, anchor?: IncaNode | null): void;
43
+ export declare function insert(child: IncaNode, parent: IncaElement, anchor?: IncaNode | null): void;
50
44
  /**
51
45
  * Removes `child` for good: the native node, its whole subtree, and every
52
46
  * event listener registered in it.
53
47
  *
54
- * A caller that removes a subtree calls this on its root alone, so a node's
55
- * descendants are freed here or nowhere.
56
- * @param core - the incajs bindings to drive the native tree through
48
+ * A caller that removes a subtree calls this on its root alone, and the host
49
+ * frees the descendants with it.
57
50
  * @param child - the node being removed
58
51
  */
59
- export declare function remove(core: IncaCore, child: IncaNode): void;
52
+ export declare function remove(child: IncaNode): void;
60
53
  /**
61
54
  * Looks up the current parent.
62
55
  * @param node - the node to query
@@ -1,29 +1,36 @@
1
- import { IncaEventTarget, NodeId } from '../rendererCore.mts';
1
+ import { IncaEvent, IncaEventTarget } from '../types.mts';
2
+ import { HANDLER_EVENTS } from './eventHandlers.mts';
2
3
  import { RectLike } from './geometry.mts';
3
4
  import { ScrollIntoViewOptions, ScrollOptions } from './scroll.mts';
5
+ /** A function an event handler property holds, called with the element as `this` and the event. */
6
+ export type EventHandler = (this: IncaElement, event: IncaEvent) => unknown;
7
+ /**
8
+ * The event handler properties, such as `onclick`, of the events the host dispatches, `focusin` and
9
+ * `focusout` excepted.
10
+ */
11
+ export type EventHandlers = {
12
+ [K in (typeof HANDLER_EVENTS)[number] as `on${K}`]: EventHandler | object | null;
13
+ };
4
14
  /**
5
15
  * A container node: either a real element or the hidden stand-in that
6
16
  * `createCommentNode` makes. It is the only node type that can act as a
7
- * parent.
8
- *
9
- * `inca`'s native tree has no parent pointers and no way to list a
10
- * node's children, so `parent`/`children` are maintained here as a
11
- * JS-side shadow of the tree, kept in sync by `insert` and
12
- * `remove`.
17
+ * parent. `parent` and `children` read the node's current position in the
18
+ * tree.
13
19
  *
14
20
  * After the node is removed, `addEventListener()` and `removeEventListener()`
15
- * ignore the call, and `dispatchEvent()` returns `true`.
21
+ * ignore the call, an assignment to a handler property does nothing, and
22
+ * `dispatchEvent()` returns `true`.
16
23
  */
17
- export interface IncaElement extends IncaEventTarget {
24
+ export interface IncaElement extends IncaEventTarget, EventHandlers {
18
25
  /**
19
- * The underlying native node's id, the only part of this object the native
20
- * tree itself knows about.
26
+ * The `id` attribute, or an empty string when it is unset. Assigning sets
27
+ * the attribute to the value as a string. After the node is removed,
28
+ * reading gives an empty string and assigning does nothing.
21
29
  */
22
- readonly id: NodeId;
30
+ id: string;
23
31
  /**
24
- * `"comment"` for the hidden stand-in `createCommentNode`
25
- * makes; `"element"` for every other container. Purely
26
- * informational: both render identically once created.
32
+ * `"comment"` for the hidden stand-in `createCommentNode` makes;
33
+ * `"element"` for every other container.
27
34
  */
28
35
  readonly kind: "element" | "comment";
29
36
  /** The current parent, or `null` if this node isn't attached to the tree. */
@@ -45,6 +52,13 @@ export interface IncaElement extends IncaEventTarget {
45
52
  * own click is still running and an unknown node ignore the call.
46
53
  */
47
54
  click(): void;
55
+ /**
56
+ * Whether `other` is this node or one of its descendants in the tree as
57
+ * rendered. `null` and `undefined` give `false`, and any other value that is
58
+ * not a node throws a `TypeError`. After the node is removed, it still answers
59
+ * for the subtree it keeps.
60
+ */
61
+ contains(other: IncaNode | null): boolean;
48
62
  /**
49
63
  * Assigning sets the `tabindex` attribute to the value's integer part,
50
64
  * wrapped to 32 bits. Reading returns the `tabindex` attribute as an
@@ -104,8 +118,6 @@ export interface IncaElement extends IncaEventTarget {
104
118
  }
105
119
  /** A text leaf node. */
106
120
  export interface IncaText {
107
- /** The underlying native node's id. */
108
- readonly id: NodeId;
109
121
  /** Discriminates this node within the {@link IncaNode} union. */
110
122
  readonly kind: "text";
111
123
  /** The current parent, or `null` if this node isn't attached to the tree. */
package/dist/events.d.mts CHANGED
@@ -11,11 +11,12 @@ export declare function latestEventId(): number;
11
11
  * registration keeps its other options. A `null` listener is ignored.
12
12
  *
13
13
  * Any event name is accepted, and it fires when the host dispatches that name.
14
- * See the `EventListener` type for the fields an event carries.
14
+ * See the `IncaEvent` type for the fields an event carries.
15
15
  * @param nodeId - the node to listen on
16
16
  * @param event - the event name (e.g. `"click"`)
17
- * @param listener - a function, or an object whose `handleEvent` method is
18
- * 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
19
20
  * @param options - `capture` listens while the event travels down to the
20
21
  * target, `passive` ignores `preventDefault()` calls in `listener`, and
21
22
  * `once` removes the listener before it first runs
@@ -23,7 +24,7 @@ export declare function latestEventId(): number;
23
24
  * @throws TypeError when `nodeId` names no node
24
25
  * @throws RangeError when the host has issued its last callback id
25
26
  */
26
- export declare function addEventListener(nodeId: NodeId, event: string, listener: EventListenerOrObject | null, options?: ListenerOptions): void;
27
+ export declare function addEventListener(nodeId: NodeId, event: string, listener: EventListenerOrObject<never> | null, options?: ListenerOptions): void;
27
28
  /**
28
29
  * Drops the registration {@link addEventListener} made for `listener` on
29
30
  * `nodeId` with the same `event` and `capture`. A no-op if there is none.
@@ -32,7 +33,7 @@ export declare function addEventListener(nodeId: NodeId, event: string, listener
32
33
  * @param listener - the listener that was registered
33
34
  * @param options - `capture` of the registration to drop
34
35
  */
35
- export declare function removeEventListener(nodeId: NodeId, event: string, listener: EventListenerOrObject | null, options?: Pick<ListenerOptions, "capture">): void;
36
+ export declare function removeEventListener(nodeId: NodeId, event: string, listener: EventListenerOrObject<never> | null, options?: Pick<ListenerOptions, "capture">): void;
36
37
  /**
37
38
  * Dispatches `event` at `nodeId` along the path to the root.
38
39
  * @param nodeId - the node to dispatch at
package/dist/index.d.mts CHANGED
@@ -3,4 +3,4 @@ export { window } from './window.mts';
3
3
  export type { RectLike, RectValues } from './element/geometry.mts';
4
4
  export type { ScrollIntoViewOptions, ScrollOptions } from './element/scroll.mts';
5
5
  export type { IncaElement, IncaNode } from './element/types.mts';
6
- export type { AttributeValue, CallbackId, EventLike, EventListener, EventListenerObject, EventListenerOrObject, IncaEventTarget, ListenerOptions, NodeId, StyleProps, TagName, } from './types.mts';
6
+ export type { AttributeValue, CallbackId, EventLike, EventListener, EventListenerObject, EventListenerOrObject, IncaEvent, IncaEventTarget, ListenerOptions, NodeId, StyleProps, TagName, } from './types.mts';
package/dist/index.js CHANGED
@@ -1,6 +1,3 @@
1
- import { f as e, v as t } from "./chunks/rendererCore-U_s1R1v7.js";
2
- import { t as n } from "./chunks/handle-B1h0qxex.js";
3
- //#region src/window.mts
4
- var r = /* @__PURE__ */ t(e, ["wheel"]);
5
- //#endregion
6
- export { n as activeElement, r as window };
1
+ import { t as e } from "./chunks/hooks-BgB7lzTv.js";
2
+ import { t } from "./chunks/handle-6SBsiUWz.js";
3
+ export { t as activeElement, e as window };
package/dist/native.d.mts CHANGED
@@ -17,6 +17,8 @@ interface IncaNative {
17
17
  addEventListener(nodeId: NodeId, event: string, capture?: boolean, passive?: boolean): CallbackId;
18
18
  removeEventListener(nodeId: NodeId, event: string, callbackId: CallbackId): boolean;
19
19
  destroyNode(nodeId: NodeId): CallbackId[];
20
+ holdNode(nodeId: NodeId): void;
21
+ releaseNode(nodeId: NodeId): void;
20
22
  focusNode(nodeId: NodeId, preventScroll?: boolean): void;
21
23
  blurNode(nodeId: NodeId): void;
22
24
  focusedNode(): NodeId | null;
@@ -32,6 +34,8 @@ export type HostCallback = (...args: unknown[]) => void;
32
34
  declare global {
33
35
  var __inca_native__: IncaNative;
34
36
  var __inca_callbacks__: Record<CallbackId, HostCallback>;
37
+ var __inca_released__: (nodeIds: NodeId[], callbackIds: CallbackId[]) => void;
38
+ var __inca_targets__: (nodeIds: NodeId[]) => unknown[];
35
39
  }
36
40
  export declare function native(): IncaNative;
37
41
  export {};
@@ -1,12 +1,14 @@
1
1
  export { createEventTarget } from './eventTarget.mts';
2
+ export { window } from './window.mts';
2
3
  export { addEventListener, removeEventListener, latestEventId, focus, blur, dispatchEvent, click, } from './events.mts';
3
- export { focusedNode, appendChild, createNode, destroyNode, insertBefore, removeChild, rootNodeId, setAttribute, getAttribute, layoutOf, scrollOf, scrollNode, scrollIntoViewNode, removeAttribute, setStyle, removeStyle, } from './tree.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 +1,4 @@
1
- export { y as addEventListener, n as appendChild, b as blur, x as click, v as createEventTarget, r as createNode, i as destroyNode, S as dispatchEvent, C as focus, a as focusedNode, o as getAttribute, s as insertBefore, w as latestEventId, c as layoutOf, l as removeAttribute, u as removeChild, T as removeEventListener, d as removeStyle, f as rootNodeId, p as scrollIntoViewNode, m as scrollNode, h as scrollOf, g as setAttribute, _ as setStyle } from "./chunks/rendererCore-U_s1R1v7.js";
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-DEtME8eI.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-6SBsiUWz.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
@@ -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 keeps
36
- * its own children, so it can be re-attached elsewhere. Use
37
- * {@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.
@@ -81,7 +95,7 @@ export declare function layoutOf(nodeId: NodeId): readonly [number, number, numb
81
95
  * frame.
82
96
  * @param nodeId - the node to read
83
97
  * @returns `[left, top, maxLeft, maxTop]`, or `null` for a node whose `overflow` is
84
- * `visible` on both axes. The maxima are the largest offsets the node can take, as
98
+ * `visible` or `clip` on both axes. The maxima are the largest offsets the node can take, as
85
99
  * of the last drawn frame.
86
100
  * @throws {TypeError} when `nodeId` names no node
87
101
  */
@@ -89,7 +103,7 @@ export declare function scrollOf(nodeId: NodeId): readonly [number, number, numb
89
103
  /**
90
104
  * Sets the scroll offset of `nodeId` on one or both axes. A `null` axis keeps
91
105
  * its current offset. The host clamps each value to the scrollable range on
92
- * the next frame. A node with `overflow: visible` on both axes ignores the call.
106
+ * the next frame. A node whose `overflow` is `visible` or `clip` on both axes ignores the call.
93
107
  * @param nodeId - the node to scroll
94
108
  * @param left - the horizontal offset, or `null` to keep it
95
109
  * @param top - the vertical offset, or `null` to keep it
package/dist/types.d.mts CHANGED
@@ -9,8 +9,8 @@ export type NodeId = number;
9
9
  */
10
10
  export type CallbackId = number;
11
11
  /**
12
- * A value `setAttribute`/`setStyle` can take. Anything else raises a catchable
13
- * exception rather than being silently coerced.
12
+ * A value `setAttribute`/`setStyle` can take. Any other value raises a catchable
13
+ * exception.
14
14
  */
15
15
  export type AttributeValue = string | number | boolean;
16
16
  /**
@@ -23,12 +23,14 @@ export type AttributeValue = string | number | boolean;
23
23
  export type TagName = "text" | (string & {});
24
24
  /** Where `scrollIntoView` aligns a node on one axis. */
25
25
  export type ScrollAlignment = "start" | "center" | "end" | "nearest";
26
+ /** One overflow value; `"auto"` is an alias of `"scroll"`. */
27
+ export type Overflow = "visible" | "hidden" | "clip" | "scroll" | "auto";
26
28
  /**
27
29
  * Style properties, in their snake_case spelling, that `setStyle`'s typed
28
30
  * overload checks. A deliberately incomplete, v1 layout/paint vocabulary. The
29
31
  * renderer also reads the camelCase and kebab-case spellings. An unrecognized
30
32
  * key or a value shape that doesn't parse (e.g. a malformed enum string) is
31
- * ignored by the renderer rather than applied or thrown.
33
+ * ignored by the renderer.
32
34
  */
33
35
  export interface StyleProps {
34
36
  /** Layout mode for this node's children. `"none"` skips both layout and rendering for the whole subtree. */
@@ -57,12 +59,12 @@ export interface StyleProps {
57
59
  corner_radius?: number;
58
60
  /** Font size in px for this container's own text. Cascades to descendant text leaves, same as {@link StyleProps.text_color}. */
59
61
  text_size?: number;
60
- /** Overflow on both axes; `"scroll"` (alias `"auto"`) makes the container scroll with the wheel. Overridden per axis by {@link StyleProps.overflow_x}/{@link StyleProps.overflow_y}. */
61
- overflow?: "visible" | "hidden" | "scroll" | "auto";
62
+ /** Overflow on both axes, or `"<x> <y>"` per axis; `"scroll"` (alias `"auto"`) makes the container scroll with the wheel. Overridden per axis by {@link StyleProps.overflow_x}/{@link StyleProps.overflow_y}. */
63
+ overflow?: Overflow | `${Overflow} ${Overflow}`;
62
64
  /** Horizontal overflow; wins over {@link StyleProps.overflow}. */
63
- overflow_x?: "visible" | "hidden" | "scroll" | "auto";
65
+ overflow_x?: Overflow;
64
66
  /** Vertical overflow; wins over {@link StyleProps.overflow}. */
65
- overflow_y?: "visible" | "hidden" | "scroll" | "auto";
67
+ overflow_y?: Overflow;
66
68
  /** Inner spacing in px (`>= 0`) on all four sides. Overridden per axis by {@link StyleProps.padding_x}/{@link StyleProps.padding_y} and per side by the `padding_*` side keys. */
67
69
  padding?: number;
68
70
  /** Horizontal inner spacing in px (`>= 0`); wins over {@link StyleProps.padding}. */
@@ -136,11 +138,12 @@ export interface IncaEventTarget {
136
138
  * same `type` and `capture` again changes nothing. A `null` listener is
137
139
  * ignored.
138
140
  * @param type - the event name (e.g. `"keydown"`)
139
- * @param listener - a function, or an object whose `handleEvent` method is
140
- * called when the event fires
141
+ * @param listener - a function, called with the event's `currentTarget` as
142
+ * `this`, or an object whose `handleEvent` method is called with the object
143
+ * as `this` when the event fires
141
144
  * @param options - a {@link ListenerOptions}, or a boolean for `capture`
142
145
  */
143
- addEventListener(type: string, listener: EventListenerOrObject | null, options?: boolean | ListenerOptions): void;
146
+ addEventListener<E = IncaEvent>(type: string, listener: EventListenerOrObject<E> | null, options?: boolean | ListenerOptions): void;
144
147
  /**
145
148
  * Drops the registration of `listener` for `type` with the same `capture`.
146
149
  * A call that matches no registration changes nothing.
@@ -148,7 +151,7 @@ export interface IncaEventTarget {
148
151
  * @param listener - the listener that was registered
149
152
  * @param options - an object with `capture`, or a boolean for `capture`
150
153
  */
151
- removeEventListener(type: string, listener: EventListenerOrObject | null, options?: boolean | Pick<ListenerOptions, "capture">): void;
154
+ removeEventListener<E = IncaEvent>(type: string, listener: EventListenerOrObject<E> | null, options?: boolean | Pick<ListenerOptions, "capture">): void;
152
155
  /**
153
156
  * Dispatches an `Event` or `CustomEvent` at the target.
154
157
  * @param event - the event to dispatch
@@ -159,44 +162,82 @@ export interface IncaEventTarget {
159
162
  dispatchEvent(event: EventLike): boolean;
160
163
  }
161
164
  /**
162
- * Signature of a callback registered via `addEventListener`. Declare its
163
- * parameter as the event object, such as `(event: { key: string }) => void`.
164
- *
165
- * The native host calls it with one argument, an object with:
166
- * - `type`: the event's name.
167
- * - `target`: the {@link NodeId} the event is about. It is the deepest node
168
- * under the pointer for pointer events, the nearest common ancestor of the
169
- * press and the release for `click`, `dblclick` and `auxclick`, and the
170
- * focused node (the root when nothing is focused) for key events.
171
- * - `currentTarget`: the {@link NodeId} whose listener is running, and
172
- * `null` once the event has been handled.
173
- * - `bubbles`, `cancelable` and `composed`: fixed per event name.
174
- * - `defaultPrevented`: `true` once a listener called `preventDefault()` on a
175
- * cancelable event.
176
- * - `eventPhase`: 1 on the ancestors of `target` while the event travels
177
- * down, 2 where `currentTarget` is `target`, 3 on the ancestors while it
178
- * travels up, and 0 once the event has been handled.
179
- * - `isTrusted`: `true` for events the host dispatches and `false` for events a
180
- * script dispatches.
181
- * - `timeStamp`: milliseconds since the host started, as a number.
182
- * - `eventId`: a number that grows with each event and is the same on every
183
- * node that event reaches.
184
- * - `stopPropagation()`, `stopImmediatePropagation()` and `preventDefault()`.
185
- * - the fields that event kind carries.
165
+ * The event object a listener receives. It carries these fields and the
166
+ * fields of its event kind, which this type leaves out. A listener that reads
167
+ * them declares its parameter with them, such as
168
+ * `(event: IncaEvent & { key: string }) => void`.
186
169
  *
187
170
  * See https://incajs.tom96da.com/reference/events for the event names the
188
171
  * host dispatches and their fields.
189
172
  */
190
- export type EventListener = (...args: never[]) => void;
173
+ export interface IncaEvent {
174
+ /** The event's name. */
175
+ readonly type: string;
176
+ /**
177
+ * The element the event is about, or `window`. It is the deepest element
178
+ * under the pointer for pointer events, the nearest common ancestor of the
179
+ * press and the release for `click`, `dblclick` and `auxclick`, and the
180
+ * focused element for key events. With no such element it is `window`.
181
+ */
182
+ readonly target: IncaEventTarget;
183
+ /** The same object as {@link IncaEvent.target}. */
184
+ readonly srcElement: IncaEventTarget;
185
+ /**
186
+ * The element or `window` whose listener is running, and `null` once the
187
+ * event has been handled. A listener function runs with it as `this`.
188
+ */
189
+ readonly currentTarget: IncaEventTarget | null;
190
+ /** Whether the event travels up from `target`. Fixed per event name. */
191
+ readonly bubbles: boolean;
192
+ /** Whether `preventDefault()` can cancel the event. Fixed per event name. */
193
+ readonly cancelable: boolean;
194
+ /** Fixed per event name. */
195
+ readonly composed: boolean;
196
+ /**
197
+ * 1 on the ancestors of `target` while the event travels down, 2 where
198
+ * `currentTarget` is `target`, 3 on the ancestors while it travels up, and 0
199
+ * once the event has been handled.
200
+ */
201
+ readonly eventPhase: 0 | 1 | 2 | 3;
202
+ /** `true` once a listener called `preventDefault()` on a cancelable event. */
203
+ readonly defaultPrevented: boolean;
204
+ /** `true` for events the host dispatches and `false` for events a script dispatches. */
205
+ readonly isTrusted: boolean;
206
+ /** Milliseconds since the host started. */
207
+ readonly timeStamp: number;
208
+ /** A number that grows with each event and is the same on every node that event reaches. */
209
+ readonly eventId: number;
210
+ /** Assigning `true` while the event is dispatched stops it like `stopPropagation()`. */
211
+ cancelBubble: boolean;
212
+ /** The opposite of `defaultPrevented`. Assigning `false` cancels a cancelable event like `preventDefault()`. */
213
+ returnValue: boolean;
214
+ /** Stops the event from reaching the listeners of later nodes on its path. */
215
+ stopPropagation(): void;
216
+ /** Stops the event from reaching any later listener. */
217
+ stopImmediatePropagation(): void;
218
+ /** Cancels the event when it is cancelable and the listener is not passive. */
219
+ preventDefault(): void;
220
+ /**
221
+ * `target` and its ancestors, ending with `window`, and an empty array once
222
+ * the event has been handled.
223
+ */
224
+ composedPath(): IncaEventTarget[];
225
+ }
226
+ /**
227
+ * Signature of a callback registered via `addEventListener`. It receives the
228
+ * event, an {@link IncaEvent} unless the parameter declares another type, and
229
+ * runs with the event's `currentTarget` as `this`.
230
+ */
231
+ export type EventListener<E = IncaEvent> = (this: IncaEventTarget, event: E) => void;
191
232
  /**
192
233
  * An object whose `handleEvent` method receives the events, called with the
193
- * object as `this`. It takes the arguments of an {@link EventListener}.
234
+ * object as `this`. It takes the event an {@link EventListener} takes.
194
235
  */
195
- export interface EventListenerObject {
196
- handleEvent: EventListener;
236
+ export interface EventListenerObject<E = IncaEvent> {
237
+ handleEvent(event: E): void;
197
238
  }
198
239
  /**
199
240
  * What `addEventListener` accepts as a listener: an {@link EventListener} or
200
241
  * an {@link EventListenerObject}.
201
242
  */
202
- export type EventListenerOrObject = EventListener | EventListenerObject;
243
+ export type EventListenerOrObject<E = IncaEvent> = EventListener<E> | EventListenerObject<E>;
@@ -1,19 +1,18 @@
1
1
  import { App, Component, ComponentPublicInstance } from '@vue/runtime-core';
2
- import { IncaElement } from '../element/types.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,6 +1,5 @@
1
1
  import { RendererOptions } from '@vue/runtime-core';
2
- import { IncaElement, IncaNode } from '../element/types.mts';
3
- import { IncaCore } from '../rendererCore.mts';
2
+ import { IncaCore, IncaElement, IncaNode } from '../rendererCore.mts';
4
3
  /**
5
4
  * Marks `handle` so that Vue's `reactive()` and `ref()` keep the object itself.
6
5
  * A template ref then holds the same object the application receives from
@@ -18,3 +17,13 @@ export type NodeOps = Omit<RendererOptions<IncaNode, IncaElement>, "patchProp">;
18
17
  * @param core - the incajs bindings to drive the native tree through
19
18
  */
20
19
  export declare function createNodeOps(core: IncaCore): NodeOps;
20
+ type Creators = Pick<NodeOps, "createElement" | "createText">;
21
+ /**
22
+ * The creators of `ops` that hold the node they create and release the hold
23
+ * once the returned handle is collected.
24
+ * @param core - the incajs bindings the holds go through
25
+ * @param ops - the creators to wrap
26
+ * @returns held versions of `createElement` and `createText`
27
+ */
28
+ export declare function createHeldNodeOps(core: IncaCore, ops: Creators): Creators;
29
+ export {};
@@ -1,6 +1,5 @@
1
1
  import { RendererOptions } from '@vue/runtime-core';
2
- import { IncaElement } from '../element/types.mts';
3
- import { IncaCore } from '../rendererCore.mts';
2
+ import { IncaCore, IncaElement } from '../rendererCore.mts';
4
3
  /**
5
4
  * {@link RendererOptions.patchProp} applies one changed `v-bind`/
6
5
  * attribute/event prop to a host element.
@@ -22,7 +21,12 @@ import { IncaCore } from '../rendererCore.mts';
22
21
  * ### `onXxx`
23
22
  *
24
23
  * The key registers `nextValue` as a listener for `xxx`, taking a function
25
- * or an array of them, and unbinds that key's listener for anything else.
24
+ * or an array of them. A falsy `nextValue` unbinds that key's listener. Any
25
+ * other value keeps a listener that runs nothing, and a development build
26
+ * warns about it. A nested array runs its functions. Any other entry that is
27
+ * not a function runs nothing, and a development build warns about it when
28
+ * the event fires. A falsy entry of the array itself is skipped without a
29
+ * warning.
26
30
  * - Order: each distinct key (`onClick`, `onClickOnce`) is its own listener.
27
31
  * Keys that share the event, phase and passivity run in the order first
28
32
  * registered, a re-patch keeps its place, and the host sees one registration
@@ -42,8 +46,8 @@ import { IncaCore } from '../rendererCore.mts';
42
46
  * - Event names: `onXxx` listens for the hyphenated name (`onMyEvent` listens
43
47
  * for `my-event`), and `on:xxx` listens for the name after the colon as
44
48
  * written (`on:myEvent` listens for `myEvent`). The listener runs when the
45
- * host dispatches that name. See {@link EventListener} for the fields an
46
- * event carries.
49
+ * host dispatches that name. See `IncaEvent` for the fields an event
50
+ * carries.
47
51
  * - Errors: an error a handler throws, or a rejection of an async handler,
48
52
  * goes to the `onErrorCaptured` hooks and the app's `errorHandler`. Every
49
53
  * handler of an event runs even when an earlier one fails, until one calls
@@ -53,6 +57,12 @@ import { IncaCore } from '../rendererCore.mts';
53
57
  * development build warns and raises it to the host's error report, once
54
58
  * per failing handler.
55
59
  *
60
+ * ### `onxxx`
61
+ *
62
+ * A lowercase key that names a handler property of the element, such as
63
+ * `onclick`, assigns `nextValue` to that property. A string `nextValue`
64
+ * clears the property and goes to `core.setAttribute` like other props.
65
+ *
56
66
  * ### Other props
57
67
  *
58
68
  * A string, number or boolean `nextValue` goes to `core.setAttribute` as it