incajs 0.0.13 → 0.0.15

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.
package/README.md CHANGED
@@ -12,7 +12,7 @@ framework. No Chromium, no DOM: UI renders directly on the GPU via
12
12
 
13
13
  ## How it works
14
14
 
15
- - The root `incajs` export is types only.
15
+ - The root `incajs` export is the `window` event target and the public types.
16
16
  - `incajs/vue` is a custom renderer mapping Vue 3's `createRenderer`
17
17
  lifecycle onto the native host bridge. `createIncaApp(rootComponent,
18
18
  rootProps?)` creates a Vue app whose root mounts against the host's
@@ -0,0 +1,143 @@
1
+ //#region src/native.mts
2
+ function e() {
3
+ return globalThis.__inca_native__;
4
+ }
5
+ //#endregion
6
+ //#region src/events.mts
7
+ function t() {
8
+ let e = /* @__PURE__ */ new Map(), t = /* @__PURE__ */ new Map(), n = 0, r = () => globalThis.__inca_callbacks__ ??= {};
9
+ return {
10
+ add(i, a, o) {
11
+ let s = n++;
12
+ r()[s] = o;
13
+ let c = e.get(i);
14
+ return c || e.set(i, c = /* @__PURE__ */ new Map()), c.set(a, s), t.set(s, {
15
+ group: i,
16
+ listener: a
17
+ }), s;
18
+ },
19
+ idFor(t, n) {
20
+ return e.get(t)?.get(n);
21
+ },
22
+ release(n) {
23
+ delete r()[n];
24
+ let i = t.get(n);
25
+ if (i === void 0) return;
26
+ t.delete(n);
27
+ let a = e.get(i.group);
28
+ a?.delete(i.listener), a?.size === 0 && e.delete(i.group);
29
+ },
30
+ groupCount: () => e.size
31
+ };
32
+ }
33
+ var n = t(), r = (e, t, n) => `${e}:${t}:${n === !0}`, i = 0;
34
+ function a() {
35
+ return i;
36
+ }
37
+ function o(e) {
38
+ return (...t) => {
39
+ let n = t[0]?.eventId;
40
+ return typeof n == "number" && n > i && (i = n), e(...t);
41
+ };
42
+ }
43
+ function s(e) {
44
+ for (let t of e) n.release(t);
45
+ }
46
+ function c(t, i, a, s = {}) {
47
+ if (a == null) return;
48
+ let c = r(t, i, s.capture);
49
+ if (n.idFor(c, a) !== void 0) return;
50
+ let u = (...e) => typeof a == "function" ? a(...e) : a.handleEvent.apply(a, e), d = s.once ? (...e) => (l(t, i, a, s), u(...e)) : u, f = n.add(c, a, o(d));
51
+ try {
52
+ e().addEventListener(t, i, f, s.capture === !0, s.passive === !0);
53
+ } catch (e) {
54
+ throw n.release(f), e;
55
+ }
56
+ }
57
+ function l(t, i, a, o = {}) {
58
+ if (a == null) return;
59
+ let s = n.idFor(r(t, i, o.capture), a);
60
+ s !== void 0 && (e().removeEventListener(t, i, s), n.release(s));
61
+ }
62
+ function u(t, n) {
63
+ return e().dispatchEvent(t, n);
64
+ }
65
+ function d(t) {
66
+ e().click(t);
67
+ }
68
+ function f(t, n) {
69
+ n === void 0 ? e().focusNode(t) : e().focusNode(t, n);
70
+ }
71
+ function p(t) {
72
+ e().blurNode(t);
73
+ }
74
+ function m() {
75
+ return e().focusedNode();
76
+ }
77
+ //#endregion
78
+ //#region src/createEventTarget.mts
79
+ function h(e, t = []) {
80
+ return {
81
+ addEventListener(n, r, i) {
82
+ let a = typeof i == "boolean" ? { capture: i } : i ?? {};
83
+ c(e(), n, r, {
84
+ ...a,
85
+ passive: a.passive ?? t.includes(n)
86
+ });
87
+ },
88
+ removeEventListener(t, n, r) {
89
+ let i = typeof r == "boolean" ? r : r?.capture;
90
+ l(e(), t, n, { capture: i });
91
+ },
92
+ dispatchEvent: (t) => u(e(), t)
93
+ };
94
+ }
95
+ //#endregion
96
+ //#region src/tree.mts
97
+ function g() {
98
+ return e().rootNodeId();
99
+ }
100
+ function _(t) {
101
+ return e().createNode(t);
102
+ }
103
+ function v(t, n) {
104
+ e().appendChild(t, n);
105
+ }
106
+ function y(t, n, r) {
107
+ e().insertBefore(t, n, r);
108
+ }
109
+ function b(t, n) {
110
+ e().removeChild(t, n);
111
+ }
112
+ function x(t) {
113
+ s(e().destroyNode(t));
114
+ }
115
+ function S(t, n, r) {
116
+ e().setAttribute(t, n, r);
117
+ }
118
+ function C(t, n) {
119
+ return e().getAttribute(t, n);
120
+ }
121
+ function w(t) {
122
+ return e().layoutOf(t);
123
+ }
124
+ function T(t) {
125
+ return e().scrollOf(t);
126
+ }
127
+ function E(t, n, r) {
128
+ e().scrollNode(t, n, r);
129
+ }
130
+ function D(t, n, r) {
131
+ e().scrollIntoViewNode(t, n, r);
132
+ }
133
+ function O(t, n) {
134
+ e().removeAttribute(t, n);
135
+ }
136
+ function k(t, n, r) {
137
+ e().setStyle(t, n, r);
138
+ }
139
+ function A(t, n) {
140
+ e().removeStyle(t, n);
141
+ }
142
+ //#endregion
143
+ export { a as C, m as S, c as _, y as a, u as b, b as c, D as d, E as f, h as g, k as h, C as i, A as l, S as m, _ as n, w as o, T as p, x as r, O as s, v as t, g as u, p as v, l as w, f as x, d as y };
@@ -0,0 +1,10 @@
1
+ import { IncaEventTarget, NodeId } from './types.mts';
2
+ /**
3
+ * Builds the listener methods of an event target that stands for one node.
4
+ * @param nodeId - resolves the node when a method runs
5
+ * @param passiveByDefault - event names whose listeners are passive unless
6
+ * their options say `passive: false`
7
+ * @returns the target's `addEventListener`, `removeEventListener` and
8
+ * `dispatchEvent`
9
+ */
10
+ export declare function createEventTarget(nodeId: () => NodeId, passiveByDefault?: readonly string[]): IncaEventTarget;
package/dist/events.d.mts CHANGED
@@ -1,8 +1,13 @@
1
- import { CallbackId, EventListener, NodeId } from './types.mts';
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;
2
7
  /**
3
8
  * @returns the `eventId` of the newest event any registered listener has
4
- * received, or 0 before the first. Ids grow with each input event, and every
5
- * node dispatch of one event carries the same id.
9
+ * received, or 0 before the first. Ids grow with each event, and every
10
+ * listener of one event receives the same id.
6
11
  */
7
12
  export declare function latestEventId(): number;
8
13
  /**
@@ -13,36 +18,59 @@ export declare function latestEventId(): number;
13
18
  */
14
19
  export declare function releaseCallbacks(callbackIds: readonly CallbackId[]): void;
15
20
  /**
16
- * Makes `listener` the one thing that runs when `event` fires on `nodeId`,
17
- * replacing whatever was registered for that pair before.
21
+ * Registers `listener` for `event` on `nodeId`. Registering the same listener
22
+ * for the same node, event and `capture` again changes nothing, and the first
23
+ * registration keeps its other options. A `null` listener is ignored.
18
24
  *
19
- * The host holds a list per `(nodeId, event)` and dispatches to all of it;
20
- * this wrapper keeps one, the way a framework adapter composes its own
21
- * handlers into a single callback. See {@link EventListener} for which
22
- * event names are wired to real native input today; other names are
23
- * accepted but never fire.
25
+ * Any event name is accepted, and it fires when the host dispatches that name.
26
+ * See the `EventListener` type for the fields an event carries.
24
27
  * @param nodeId - the node to listen on
25
28
  * @param event - the event name (e.g. `"click"`)
26
- * @param listener - called when the event fires
29
+ * @param listener - a function, or an object whose `handleEvent` method is
30
+ * called with the object as `this` when the event fires
31
+ * @param options - `capture` listens while the event travels down to the
32
+ * target, `passive` ignores `preventDefault()` calls in `listener`, and
33
+ * `once` removes the listener before it first runs
34
+ * @throws TypeError when `nodeId` is malformed
35
+ * @throws TypeError when `nodeId` names no node
27
36
  */
28
- export declare function setEventListener(nodeId: NodeId, event: string, listener: EventListener): void;
37
+ export declare function addEventListener(nodeId: NodeId, event: string, listener: EventListenerOrObject | null, options?: ListenerOptions): void;
29
38
  /**
30
- * Drops whatever {@link setEventListener} registered for `(nodeId, event)`,
31
- * on both the native and the JS side. A no-op if nothing is registered.
39
+ * Drops the registration {@link addEventListener} made for `listener` on
40
+ * `nodeId` with the same `event` and `capture`. A no-op if there is none.
32
41
  * @param nodeId - the node to stop listening on
33
42
  * @param event - the event name
43
+ * @param listener - the listener that was registered
44
+ * @param options - `capture` of the registration to drop
45
+ */
46
+ export declare function removeEventListener(nodeId: NodeId, event: string, listener: EventListenerOrObject | null, options?: Pick<ListenerOptions, "capture">): void;
47
+ /**
48
+ * Dispatches `event` at `nodeId` along the path to the root.
49
+ * @param nodeId - the node to dispatch at
50
+ * @param event - the event to dispatch
51
+ * @returns `false` when a listener canceled a cancelable event, else `true`
52
+ * @throws TypeError when `nodeId` is malformed
53
+ * @throws TypeError when `nodeId` names no node
54
+ * @throws TypeError when `event` is not an `Event` or `CustomEvent`
55
+ * @throws DOMException named `InvalidStateError` when `event` is being dispatched
34
56
  */
35
- export declare function removeEventListener(nodeId: NodeId, event: string): void;
57
+ export declare function dispatchEvent(nodeId: NodeId, event: EventLike): boolean;
58
+ /**
59
+ * Fires an untrusted `click` at `nodeId`. A disabled `button`, a node whose
60
+ * own click is still running and an unknown node ignore the call.
61
+ * @param nodeId - the node to click
62
+ * @throws TypeError when `nodeId` is malformed
63
+ */
64
+ export declare function click(nodeId: NodeId): void;
36
65
  /**
37
66
  * Requests that `nodeId` become focused. Takes effect on the next frame,
38
- * dispatching `"blur"`/`"focus"` for whatever actually changed — `nodeId`
39
- * doesn't need a `"focus"`/`"blur"` listener registered for this to work,
40
- * the same way `element.focus()` works on any focusable DOM element
41
- * regardless of whether it's being listened to. The node needs a `tabindex`
42
- * attribute to take focus.
67
+ * dispatching `"blur"`/`"focus"` for whatever actually changed. The node
68
+ * needs a `tabindex` attribute to take focus, and a listener for either event
69
+ * is optional. The scroll containers around the node scroll it into view.
43
70
  * @param nodeId - the node to focus
71
+ * @param preventScroll - `true` to leave the scroll containers in place; omitted or `false` scrolls the node into view
44
72
  */
45
- export declare function focus(nodeId: NodeId): void;
73
+ export declare function focus(nodeId: NodeId, preventScroll?: boolean): void;
46
74
  /**
47
75
  * Requests that `nodeId` become unfocused, the way `element.blur()` does.
48
76
  * Takes effect on the next frame; a no-op if `nodeId` isn't the focused node
@@ -50,3 +78,8 @@ export declare function focus(nodeId: NodeId): void;
50
78
  * @param nodeId - the node to unfocus
51
79
  */
52
80
  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 +1,2 @@
1
- export type { AttributeValue, CallbackId, EventListener, NodeId, StyleProps, TagName, } from './types.mts';
1
+ export { window } from './window.mts';
2
+ export type { AttributeValue, CallbackId, EventLike, EventListener, EventListenerObject, EventListenerOrObject, IncaEventTarget, ListenerOptions, NodeId, StyleProps, TagName, } from './types.mts';
package/dist/index.js CHANGED
@@ -0,0 +1,5 @@
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 };
package/dist/native.d.mts CHANGED
@@ -1,4 +1,4 @@
1
- import { AttributeValue, CallbackId, EventListener, NodeId } from './types.mts';
1
+ import { AttributeValue, CallbackId, EventLike, NodeId, ScrollAlignment } from './types.mts';
2
2
  /** The host-injected object every wrapper in this package forwards to. Not part of the public surface — reach it through the wrappers instead. */
3
3
  interface IncaNative {
4
4
  rootNodeId(): NodeId;
@@ -7,18 +7,28 @@ interface IncaNative {
7
7
  insertBefore(parentId: NodeId, childId: NodeId, anchorId: NodeId | null): void;
8
8
  removeChild(parentId: NodeId, childId: NodeId): void;
9
9
  setAttribute(nodeId: NodeId, key: string, value: AttributeValue): void;
10
+ getAttribute(nodeId: NodeId, key: string): AttributeValue | null;
10
11
  removeAttribute(nodeId: NodeId, key: string): void;
11
12
  setStyle(nodeId: NodeId, key: string, value: AttributeValue): void;
12
13
  removeStyle(nodeId: NodeId, key: string): void;
13
- addEventListener(nodeId: NodeId, event: string, callbackId: CallbackId): void;
14
+ addEventListener(nodeId: NodeId, event: string, callbackId: CallbackId, capture?: boolean, passive?: boolean): void;
14
15
  removeEventListener(nodeId: NodeId, event: string, callbackId: CallbackId): boolean;
15
16
  destroyNode(nodeId: NodeId): CallbackId[];
16
- focusNode(nodeId: NodeId): void;
17
+ focusNode(nodeId: NodeId, preventScroll?: boolean): void;
17
18
  blurNode(nodeId: NodeId): void;
19
+ focusedNode(): NodeId | null;
20
+ layoutOf(nodeId: NodeId): readonly [number, number, number, number, number, number, number] | null;
21
+ scrollOf(nodeId: NodeId): readonly [number, number, number, number] | null;
22
+ scrollNode(nodeId: NodeId, left: number | null, top: number | null): void;
23
+ scrollIntoViewNode(nodeId: NodeId, block: ScrollAlignment, inline: ScrollAlignment): void;
24
+ dispatchEvent(nodeId: NodeId, event: EventLike): boolean;
25
+ click(nodeId: NodeId): void;
18
26
  }
27
+ /** What the host calls: it passes the event object as the first argument. */
28
+ export type HostCallback = (...args: unknown[]) => void;
19
29
  declare global {
20
30
  var __inca_native__: IncaNative;
21
- var __inca_callbacks__: Record<CallbackId, EventListener>;
31
+ var __inca_callbacks__: Record<CallbackId, HostCallback>;
22
32
  }
23
33
  export declare function native(): IncaNative;
24
34
  export {};
@@ -1,5 +1,7 @@
1
- export { setEventListener, removeEventListener, latestEventId, focus, blur } from './events.mts';
2
- export { appendChild, createNode, destroyNode, insertBefore, removeChild, rootNodeId, setAttribute, removeAttribute, setStyle, removeStyle, } from './tree.mts';
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';
4
+ export type * from './types.mts';
3
5
  /**
4
6
  * The tree/event primitives a custom renderer (`incajs/vue`) drives the
5
7
  * native tree through.
@@ -1 +1,37 @@
1
- export { n as appendChild, f as blur, r as createNode, i as destroyNode, p as focus, a as insertBefore, m as latestEventId, o as removeAttribute, s as removeChild, h as removeEventListener, c as removeStyle, l as rootNodeId, u as setAttribute, g as setEventListener, d as setStyle } from "./chunks/rendererCore-vR5RIa7d.js";
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 };
package/dist/tree.d.mts CHANGED
@@ -1,4 +1,4 @@
1
- import { AttributeValue, NodeId, StyleProps, TagName } from './types.mts';
1
+ import { AttributeValue, NodeId, ScrollAlignment, StyleProps, TagName } from './types.mts';
2
2
  /**
3
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
@@ -57,6 +57,54 @@ export declare function destroyNode(nodeId: NodeId): void;
57
57
  * @param value - the attribute value
58
58
  */
59
59
  export declare function setAttribute(nodeId: NodeId, key: string, value: AttributeValue): void;
60
+ /**
61
+ * Returns the attribute/prop stored on `nodeId` under `key`, or `null` when unset.
62
+ * @param nodeId - the node to read
63
+ * @param key - the attribute name
64
+ * @returns the stored value, or `null`
65
+ * @throws {TypeError} when `nodeId` names no node
66
+ */
67
+ export declare function getAttribute(nodeId: NodeId, key: string): AttributeValue | null;
68
+ /**
69
+ * Returns the box `nodeId` was drawn at in the last frame, in window logical
70
+ * pixels, or `null` if the node has no recorded box.
71
+ * @param nodeId - the node to read
72
+ * @returns `[x, y, width, height, border, scrollX, scrollY]`, or `null`. `border` is one uniform
73
+ * width on all sides. `scrollX` and `scrollY` are the positive scroll offset the parent applied
74
+ * to the box.
75
+ * @throws {TypeError} when `nodeId` names no node
76
+ */
77
+ export declare function layoutOf(nodeId: NodeId): readonly [number, number, number, number, number, number, number] | null;
78
+ /**
79
+ * Returns the scroll offset of `nodeId` in window logical pixels. A write made
80
+ * since the last draw is included, clamped to the maximum of the last drawn
81
+ * frame.
82
+ * @param nodeId - the node to read
83
+ * @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
85
+ * of the last drawn frame.
86
+ * @throws {TypeError} when `nodeId` names no node
87
+ */
88
+ export declare function scrollOf(nodeId: NodeId): readonly [number, number, number, number] | null;
89
+ /**
90
+ * Sets the scroll offset of `nodeId` on one or both axes. A `null` axis keeps
91
+ * 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.
93
+ * @param nodeId - the node to scroll
94
+ * @param left - the horizontal offset, or `null` to keep it
95
+ * @param top - the vertical offset, or `null` to keep it
96
+ * @throws {TypeError} when `nodeId` names no node
97
+ */
98
+ export declare function scrollNode(nodeId: NodeId, left: number | null, top: number | null): void;
99
+ /**
100
+ * Scrolls each scroll container around `nodeId` so the node shows.
101
+ * @param nodeId - the node to bring into view
102
+ * @param block - the vertical alignment: `"start"`, `"center"`, `"end"` or `"nearest"`
103
+ * @param inline - the horizontal alignment: `"start"`, `"center"`, `"end"` or `"nearest"`
104
+ * @throws {TypeError} when `nodeId` names no node
105
+ * @throws {TypeError} when `block` or `inline` is not an alignment name
106
+ */
107
+ export declare function scrollIntoViewNode(nodeId: NodeId, block: ScrollAlignment, inline: ScrollAlignment): void;
60
108
  /**
61
109
  * Removes a non-style attribute/prop from `nodeId`. Removing an attribute
62
110
  * that isn't set does nothing.
package/dist/types.d.mts CHANGED
@@ -5,7 +5,7 @@
5
5
  export type NodeId = number;
6
6
  /**
7
7
  * Id assigned to one registered event listener. Managed internally by
8
- * `setEventListener`/`removeEventListener`/`destroyNode` — callers never see or
8
+ * `addEventListener`/`removeEventListener`/`destroyNode` — callers never see or
9
9
  * pass one directly.
10
10
  */
11
11
  export type CallbackId = number;
@@ -22,6 +22,8 @@ export type AttributeValue = string | number | boolean;
22
22
  * autocomplete while still accepting an arbitrary tag name.
23
23
  */
24
24
  export type TagName = "text" | (string & {});
25
+ /** Where `scrollIntoView` aligns a node on one axis. */
26
+ export type ScrollAlignment = "start" | "center" | "end" | "nearest";
25
27
  /**
26
28
  * Style properties, in their snake_case spelling, that `setStyle`'s typed
27
29
  * overload checks. A deliberately incomplete, v1 layout/paint vocabulary. The
@@ -106,7 +108,60 @@ export interface StyleProps {
106
108
  max_height?: number | "auto";
107
109
  }
108
110
  /**
109
- * Signature of a callback registered via `setEventListener`.
111
+ * An `Event` or `CustomEvent` built in this runtime. The host throws a
112
+ * `TypeError` for any other value.
113
+ */
114
+ export interface EventLike {
115
+ readonly type: string;
116
+ }
117
+ /**
118
+ * How a listener registered via `addEventListener` takes part in an event.
119
+ */
120
+ export interface ListenerOptions {
121
+ /** Listen while the event travels from the root down to the target. The default listens while it travels back up. */
122
+ capture?: boolean;
123
+ /** `preventDefault()` calls inside the listener are ignored. */
124
+ passive?: boolean;
125
+ /** The listener is removed before it first runs. */
126
+ once?: boolean;
127
+ }
128
+ /**
129
+ * The listener methods of an object that receives events, such as the
130
+ * `window` export and a template `ref`. A registration is identified by the
131
+ * event name, the listener and `capture`. `removeEventListener` takes the
132
+ * same listener that `addEventListener` received.
133
+ */
134
+ export interface IncaEventTarget {
135
+ /**
136
+ * Registers `listener` for `type`. Registering the same listener for the
137
+ * same `type` and `capture` again changes nothing. A `null` listener is
138
+ * ignored.
139
+ * @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
142
+ * @param options - a {@link ListenerOptions}, or a boolean for `capture`
143
+ */
144
+ addEventListener(type: string, listener: EventListenerOrObject | null, options?: boolean | ListenerOptions): void;
145
+ /**
146
+ * Drops the registration of `listener` for `type` with the same `capture`.
147
+ * A call that matches no registration changes nothing.
148
+ * @param type - the event name
149
+ * @param listener - the listener that was registered
150
+ * @param options - an object with `capture`, or a boolean for `capture`
151
+ */
152
+ removeEventListener(type: string, listener: EventListenerOrObject | null, options?: boolean | Pick<ListenerOptions, "capture">): void;
153
+ /**
154
+ * Dispatches an `Event` or `CustomEvent` at the target.
155
+ * @param event - the event to dispatch
156
+ * @returns `false` when a listener canceled a cancelable event, else `true`
157
+ * @throws TypeError when `event` is not an `Event` or `CustomEvent`
158
+ * @throws DOMException named `InvalidStateError` when `event` is being dispatched
159
+ */
160
+ dispatchEvent(event: EventLike): boolean;
161
+ }
162
+ /**
163
+ * Signature of a callback registered via `addEventListener`. Declare its
164
+ * parameter as the event object, such as `(event: { key: string }) => void`.
110
165
  *
111
166
  * The native host calls it with one argument, an object with:
112
167
  * - `type`: the event's name.
@@ -114,19 +169,35 @@ export interface StyleProps {
114
169
  * under the pointer for pointer events, the nearest common ancestor of the
115
170
  * press and the release for `click`, `dblclick` and `auxclick`, and the
116
171
  * focused node (the root when nothing is focused) for key events.
117
- * - `currentTarget`: the {@link NodeId} whose listener is running.
172
+ * - `currentTarget`: the {@link NodeId} whose listener is running, and
173
+ * `null` once the event has been handled.
118
174
  * - `bubbles`, `cancelable` and `composed`: fixed per event name.
119
175
  * - `defaultPrevented`: `true` once a listener called `preventDefault()` on a
120
176
  * cancelable event.
121
- * - `eventPhase`: 2 where `currentTarget` is `target`, 3 on its ancestors.
122
- * - `isTrusted`: always `true`.
177
+ * - `eventPhase`: 1 on the ancestors of `target` while the event travels
178
+ * down, 2 where `currentTarget` is `target`, 3 on the ancestors while it
179
+ * travels up, and 0 once the event has been handled.
180
+ * - `isTrusted`: `true` for events the host dispatches and `false` for events a
181
+ * script dispatches.
123
182
  * - `timeStamp`: milliseconds since the host started, as a number.
124
183
  * - `eventId`: a number that grows with each event and is the same on every
125
184
  * node that event reaches.
126
185
  * - `stopPropagation()`, `stopImmediatePropagation()` and `preventDefault()`.
127
186
  * - the fields that event kind carries.
128
187
  *
129
- * See https://incajs.tom96da.com/reference/events for the full list of wired
130
- * event names and their fields.
188
+ * See https://incajs.tom96da.com/reference/events for the event names the
189
+ * host dispatches and their fields.
190
+ */
191
+ export type EventListener = (...args: never[]) => void;
192
+ /**
193
+ * An object whose `handleEvent` method receives the events, called with the
194
+ * object as `this`. It takes the arguments of an {@link EventListener}.
195
+ */
196
+ export interface EventListenerObject {
197
+ handleEvent: EventListener;
198
+ }
199
+ /**
200
+ * What `addEventListener` accepts as a listener: an {@link EventListener} or
201
+ * an {@link EventListenerObject}.
131
202
  */
132
- export type EventListener = (...args: unknown[]) => void;
203
+ export type EventListenerOrObject = EventListener | EventListenerObject;
@@ -0,0 +1,7 @@
1
+ import { IncaElement } from './nodeOps.mts';
2
+ /**
3
+ * Returns the element that currently has focus. A `focus()` or `blur()` call
4
+ * takes effect for this function at once.
5
+ * @returns the focused element, or `null` when no element has focus
6
+ */
7
+ export declare function activeElement(): IncaElement | null;
@@ -1,13 +1,13 @@
1
- import { IncaCore } from '../rendererCore.mts';
2
- import { NodeId, TagName } from '../types.mts';
1
+ import { IncaCore, NodeId, TagName } from '../rendererCore.mts';
3
2
  import { IncaElement } from './nodeOps.mts';
4
3
  /**
5
4
  * Builds the {@link IncaElement} handle for a native node: parentless,
6
- * childless, with `focus()`, `blur()` and `tabIndex` wired to `core`.
5
+ * childless, with `focus()`, `blur()`, `click()`, the listener methods of an
6
+ * event target, `tabIndex` and the layout members, all driven through `core`.
7
7
  * @param core - the incajs bindings the handle drives
8
8
  * @param id - the native node's id
9
9
  * @param kind - whether the node is an element or a comment stand-in
10
- * @param tag - the node's element kind, if it has one; a `button` starts at tab index `0`
10
+ * @param tag - the node's element kind, if it has one; a `button` defaults to tab index `0`
11
11
  * @returns the new handle
12
12
  */
13
13
  export declare function createIncaElement(core: IncaCore, id: NodeId, kind: IncaElement["kind"], tag?: TagName): IncaElement;
@@ -0,0 +1,13 @@
1
+ import { IncaNode } from './nodeOps.mts';
2
+ /**
3
+ * Whether the host freed `node` with its subtree.
4
+ * @param node - the handle to check
5
+ * @returns `true` after {@link markDestroyed} reached `node`
6
+ */
7
+ export declare function isDestroyed(node: IncaNode): boolean;
8
+ /**
9
+ * Records that the host freed `node` and every descendant of it, and drops
10
+ * their element handles from the registry.
11
+ * @param node - the root of the freed subtree
12
+ */
13
+ export declare function markDestroyed(node: IncaNode): void;
@@ -0,0 +1,24 @@
1
+ import { NodeId } from '../rendererCore.mts';
2
+ import { IncaElement } from './nodeOps.mts';
3
+ /**
4
+ * Records `element` under its id.
5
+ * @param element - the handle to record
6
+ */
7
+ export declare function registerElement(element: IncaElement): void;
8
+ /**
9
+ * Drops the record of a native node.
10
+ * @param id - the native node's id
11
+ */
12
+ export declare function unregisterElement(id: NodeId): void;
13
+ /**
14
+ * Counts the recorded nodes, including those whose handle is already collected
15
+ * and waits for the registry to drop it.
16
+ * @returns the number of records
17
+ */
18
+ export declare function recordedCount(): number;
19
+ /**
20
+ * Looks up the live handle of a native node.
21
+ * @param id - the native node's id
22
+ * @returns the handle, or `undefined` when none is live
23
+ */
24
+ export declare function elementOf(id: NodeId): IncaElement | undefined;
@@ -1,4 +1,8 @@
1
1
  export { createIncaApp } from './createApp.mts';
2
+ export { activeElement } from './activeElement.mts';
2
3
  export type { IncaApp } from './createApp.mts';
3
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';
4
8
  export type { IncaElement, IncaNode } from './nodeOps.mts';
@@ -0,0 +1,12 @@
1
+ import { IncaCore } from '../rendererCore.mts';
2
+ import { IncaElement } from './nodeOps.mts';
3
+ /** `[x, y, width, height, border, scrollX, scrollY]` of a node's last drawn frame. */
4
+ export type LayoutBox = readonly [number, number, number, number, number, number, number];
5
+ /**
6
+ * Reads the box a node was last drawn at. A destroyed node, or one with no
7
+ * recorded box, yields `null`.
8
+ * @param core - the incajs bindings to read through
9
+ * @param el - the node to read
10
+ * @returns the box, or `null`
11
+ */
12
+ export declare function layoutBox(core: IncaCore, el: IncaElement): LayoutBox | null;