incajs 0.0.20 → 0.0.22

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/dist/events.d.mts CHANGED
@@ -1,3 +1,4 @@
1
+ import { EventTargetId } from './native.mts';
1
2
  import { EventLike, EventListenerOrObject, ListenerOptions, NodeId } from './types.mts';
2
3
  /**
3
4
  * @returns the `eventId` of the newest event any registered listener has
@@ -6,13 +7,14 @@ import { EventLike, EventListenerOrObject, ListenerOptions, NodeId } from './typ
6
7
  */
7
8
  export declare function latestEventId(): number;
8
9
  /**
9
- * Registers `listener` for `event` on `nodeId`. Registering the same listener
10
- * for the same node, event and `capture` again changes nothing, and the first
11
- * registration keeps its other options. A `null` listener is ignored.
10
+ * Registers `listener` for `event` on the target (node, document or window).
11
+ * Registering the same listener for the same target, event and `capture`
12
+ * again changes nothing, and the first registration keeps its other options.
13
+ * A `null` listener is ignored.
12
14
  *
13
15
  * Any event name is accepted, and it fires when the host dispatches that name.
14
- * See the `IncaEvent` type for the fields an event carries.
15
- * @param nodeId - the node to listen on
16
+ * `IncaEventMap` gives the event type of each name the host dispatches.
17
+ * @param target - the event target (node id, "$document" or "$window")
16
18
  * @param event - the event name (e.g. `"click"`)
17
19
  * @param listener - a function, called with the event's `currentTarget` as
18
20
  * `this`, or an object whose `handleEvent` method is called with the object
@@ -20,31 +22,33 @@ export declare function latestEventId(): number;
20
22
  * @param options - `capture` listens while the event travels down to the
21
23
  * target, `passive` ignores `preventDefault()` calls in `listener`, and
22
24
  * `once` removes the listener before it first runs
23
- * @throws TypeError when `nodeId` is malformed
24
- * @throws TypeError when `nodeId` names no node
25
+ * @throws TypeError when `target` is malformed or is an unknown target tag
26
+ * @throws TypeError when a node target names no node
25
27
  * @throws RangeError when the host has issued its last callback id
26
28
  */
27
- export declare function addEventListener(nodeId: NodeId, event: string, listener: EventListenerOrObject<never> | null, options?: ListenerOptions): void;
29
+ export declare function addEventListener(target: EventTargetId, event: string, listener: EventListenerOrObject<never, never> | null, options?: ListenerOptions): void;
28
30
  /**
29
31
  * Drops the registration {@link addEventListener} made for `listener` on
30
- * `nodeId` with the same `event` and `capture`. A no-op if there is none.
31
- * @param nodeId - the node to stop listening on
32
+ * the target with the same `event` and `capture`. A no-op if there is none.
33
+ * @param target - the event target (node, document or window)
32
34
  * @param event - the event name
33
35
  * @param listener - the listener that was registered
34
36
  * @param options - `capture` of the registration to drop
35
37
  */
36
- export declare function removeEventListener(nodeId: NodeId, event: string, listener: EventListenerOrObject<never> | null, options?: Pick<ListenerOptions, "capture">): void;
38
+ export declare function removeEventListener(target: EventTargetId, event: string, listener: EventListenerOrObject<never, never> | null, options?: Pick<ListenerOptions, "capture">): void;
37
39
  /**
38
- * Dispatches `event` at `nodeId` along the path to the root.
39
- * @param nodeId - the node to dispatch at
40
+ * Dispatches `event` at a target along its path. Dispatching at an element
41
+ * reaches its ancestors, `document` and `window`. Dispatching at `document`
42
+ * reaches `window`, and dispatching at `window` reaches only `window`.
43
+ * @param target - the target to dispatch at (node id, "$document" or "$window")
40
44
  * @param event - the event to dispatch
41
45
  * @returns `false` when a listener canceled a cancelable event, else `true`
42
- * @throws TypeError when `nodeId` is malformed
43
- * @throws TypeError when `nodeId` names no node
44
- * @throws TypeError when `event` is not an `Event` or `CustomEvent`
46
+ * @throws TypeError when `target` is malformed or is an unknown target tag
47
+ * @throws TypeError when `target` is a node id that names no node
48
+ * @throws TypeError when `event` is not an event built with an event constructor
45
49
  * @throws DOMException named `InvalidStateError` when `event` is being dispatched
46
50
  */
47
- export declare function dispatchEvent(nodeId: NodeId, event: EventLike): boolean;
51
+ export declare function dispatchEvent(target: EventTargetId, event: EventLike): boolean;
48
52
  /**
49
53
  * Fires an untrusted `click` at `nodeId`. A disabled `button` and a node whose
50
54
  * own click is still running ignore the call.
@@ -71,3 +75,31 @@ export declare function focus(nodeId: NodeId, preventScroll?: boolean): void;
71
75
  * @param nodeId - the node to unfocus
72
76
  */
73
77
  export declare function blur(nodeId: NodeId): void;
78
+ /**
79
+ * Captures the mouse pointer for `nodeId` while a button is held. The pointer events and the
80
+ * mouse events that follow go to the node until the last button is released, and
81
+ * `gotpointercapture` fires before the next pointer event. With no button held the call does
82
+ * nothing.
83
+ * @param nodeId - the node to capture the pointer for
84
+ * @param pointerId - the pointer to capture; only `1`, the mouse, exists
85
+ * @throws DOMException named `NotFoundError` when `pointerId` is not `1`
86
+ * @throws DOMException named `InvalidStateError` when `nodeId` names no node or a node outside
87
+ * the mounted tree
88
+ */
89
+ export declare function setPointerCapture(nodeId: NodeId, pointerId: number): void;
90
+ /**
91
+ * Releases the pointer capture `nodeId` requested. `lostpointercapture` fires before the next
92
+ * pointer event. The call does nothing for a node that has no capture.
93
+ * @param nodeId - the node that holds the capture
94
+ * @param pointerId - the pointer to release; only `1`, the mouse, exists
95
+ * @throws DOMException named `NotFoundError` when `pointerId` is not `1`
96
+ */
97
+ export declare function releasePointerCapture(nodeId: NodeId, pointerId: number): void;
98
+ /**
99
+ * Whether `nodeId` requested the pointer capture and has not released it.
100
+ * @param nodeId - the node to ask about
101
+ * @param pointerId - the pointer to ask about
102
+ * @returns `false` for a pointer other than `1`, for a node outside the mounted tree and for a
103
+ * node that holds no capture
104
+ */
105
+ export declare function hasPointerCapture(nodeId: NodeId, pointerId: number): boolean;
package/dist/index.d.mts CHANGED
@@ -1,6 +1,6 @@
1
- export { activeElement } from './element/handle.mts';
1
+ export { document } from './document.mts';
2
2
  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, IncaEvent, IncaEventTarget, ListenerOptions, NodeId, StyleProps, TagName, } from './types.mts';
6
+ export type { AttributeValue, CallbackId, EventLike, EventListener, EventListenerObject, EventListenerOrObject, IncaDocument, IncaEvent, IncaEventMap, IncaEventTarget, IncaFocusEvent, IncaKeyboardEvent, IncaMouseEvent, IncaPointerEvent, IncaUIEvent, IncaWheelEvent, IncaWindow, ListenerOptions, NodeId, StyleProps, TagName, } from './types.mts';
package/dist/index.js CHANGED
@@ -1,3 +1 @@
1
- import { t as e } from "./chunks/hooks-D1NFQN8Q.js";
2
- import { t } from "./chunks/handle-DdYIkUcm.js";
3
- export { t as activeElement, e as window };
1
+ export { n as document, t as window } from "./chunks/hooks-TbLjfN0c.js";
package/dist/native.d.mts CHANGED
@@ -1,4 +1,6 @@
1
1
  import { AttributeValue, CallbackId, EventLike, NodeId, ScrollAlignment } from './types.mts';
2
+ /** What a listener or a dispatch names: a node id, or the tag of `document` or `window`. */
3
+ export type EventTargetId = NodeId | "$document" | "$window";
2
4
  /**
3
5
  * The host-injected object every wrapper in this package forwards to. Not part of the public
4
6
  * surface.
@@ -14,8 +16,8 @@ interface IncaNative {
14
16
  removeAttribute(nodeId: NodeId, key: string): void;
15
17
  setStyle(nodeId: NodeId, key: string, value: AttributeValue): void;
16
18
  removeStyle(nodeId: NodeId, key: string): void;
17
- addEventListener(nodeId: NodeId, event: string, capture?: boolean, passive?: boolean): CallbackId;
18
- removeEventListener(nodeId: NodeId, event: string, callbackId: CallbackId): boolean;
19
+ addEventListener(target: EventTargetId, event: string, capture?: boolean, passive?: boolean): CallbackId;
20
+ removeEventListener(target: EventTargetId, event: string, callbackId: CallbackId): boolean;
19
21
  destroyNode(nodeId: NodeId): CallbackId[];
20
22
  holdNode(nodeId: NodeId): void;
21
23
  releaseNode(nodeId: NodeId): void;
@@ -26,8 +28,11 @@ interface IncaNative {
26
28
  scrollOf(nodeId: NodeId): readonly [number, number, number, number] | null;
27
29
  scrollNode(nodeId: NodeId, left: number | null, top: number | null): void;
28
30
  scrollIntoViewNode(nodeId: NodeId, block: ScrollAlignment, inline: ScrollAlignment): void;
29
- dispatchEvent(nodeId: NodeId, event: EventLike): boolean;
31
+ dispatchEvent(target: EventTargetId, event: EventLike): boolean;
30
32
  click(nodeId: NodeId): void;
33
+ setPointerCapture(nodeId: NodeId, pointerId: number): void;
34
+ releasePointerCapture(nodeId: NodeId, pointerId: number): void;
35
+ hasPointerCapture(nodeId: NodeId, pointerId: number): boolean;
31
36
  }
32
37
  /** What the host calls: it passes the event object as the first argument. */
33
38
  export type HostCallback = (...args: unknown[]) => void;
@@ -35,7 +40,7 @@ declare global {
35
40
  var __inca_native__: IncaNative;
36
41
  var __inca_callbacks__: Record<CallbackId, HostCallback>;
37
42
  var __inca_released__: (nodeIds: NodeId[], callbackIds: CallbackId[]) => void;
38
- var __inca_targets__: (nodeIds: NodeId[]) => unknown[];
43
+ var __inca_targets__: (targets: EventTargetId[]) => unknown[];
39
44
  }
40
45
  export declare function native(): IncaNative;
41
46
  export {};
@@ -2,7 +2,7 @@ export { createEventTarget } from './eventTarget.mts';
2
2
  export { window } from './window.mts';
3
3
  export { addEventListener, removeEventListener, latestEventId, focus, blur, dispatchEvent, click, } from './events.mts';
4
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';
5
+ export { createIncaElement, rootElement } from './element/handle.mts';
6
6
  export { isDestroyed } from './element/lifecycle.mts';
7
7
  export { createCommentNode, createElementNode, createTextNode, insert, nextSibling, parentNode, remove, setElementText, setText, } from './element/shadowTree.mts';
8
8
  export type * from './types.mts';
@@ -1,4 +1,3 @@
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-NnTAUL80.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-D1NFQN8Q.js";
3
- import { n as R } from "./chunks/handle-DdYIkUcm.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 };
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-BUNTDvYu.js";
2
+ import { A as l, C as u, D as d, E as f, N as p, O as m, S as h, T as g, _, a as v, b as y, c as b, d as x, f as S, g as C, h as w, i as T, j as E, k as D, l as O, m as k, o as A, p as j, r as M, s as N, t as P, u as F, v as I, w as L, x as R, y as z } from "./chunks/hooks-TbLjfN0c.js";
3
+ export { L as addEventListener, v as appendChild, g as blur, f as click, i as createCommentNode, o as createElementNode, u as createEventTarget, M as createIncaElement, A as createNode, n as createTextNode, N as destroyNode, d as dispatchEvent, m as focus, b as focusedNode, O as getAttribute, F as holdNode, e as insert, x as insertBefore, E as isDestroyed, D as latestEventId, S as layoutOf, a as nextSibling, s as parentNode, j as releaseNode, p as releaseWhenCollected, t as remove, k as removeAttribute, w as removeChild, l as removeEventListener, C as removeStyle, T as rootElement, _ as rootNodeId, I as scrollIntoViewNode, z as scrollNode, y as scrollOf, R as setAttribute, r as setElementText, h as setStyle, c as setText, P as window };
package/dist/types.d.mts CHANGED
@@ -1,3 +1,4 @@
1
+ import { EventHandlers, IncaElement } from './element/types.mts';
1
2
  /**
2
3
  * Stable handle to a node in the native retained tree, returned by `createNode`
3
4
  * and used in every later call that touches that node.
@@ -110,8 +111,8 @@ export interface StyleProps {
110
111
  max_height?: number | "auto";
111
112
  }
112
113
  /**
113
- * An `Event` or `CustomEvent` built in this runtime. The host throws a
114
- * `TypeError` for any other value.
114
+ * An event built in this runtime with `Event`, `CustomEvent` or another
115
+ * event constructor. The host throws a `TypeError` for any other value.
115
116
  */
116
117
  export interface EventLike {
117
118
  readonly type: string;
@@ -120,7 +121,10 @@ export interface EventLike {
120
121
  * How a listener registered via `addEventListener` takes part in an event.
121
122
  */
122
123
  export interface ListenerOptions {
123
- /** Listen while the event travels from the root down to the target. The default listens while it travels back up. */
124
+ /**
125
+ * Listen while the event travels from `window` down to the target. The default listens while it
126
+ * travels back up.
127
+ */
124
128
  capture?: boolean;
125
129
  /** `preventDefault()` calls inside the listener are ignored. */
126
130
  passive?: boolean;
@@ -129,7 +133,7 @@ export interface ListenerOptions {
129
133
  }
130
134
  /**
131
135
  * The listener methods of an object that receives events, such as the
132
- * `window` export and a template `ref`. A registration is identified by the
136
+ * `window` and `document` exports and a template `ref`. A registration is identified by the
133
137
  * event name, the listener and `capture`. `removeEventListener` takes the
134
138
  * same listener that `addEventListener` received.
135
139
  */
@@ -144,7 +148,8 @@ export interface IncaEventTarget {
144
148
  * as `this` when the event fires
145
149
  * @param options - a {@link ListenerOptions}, or a boolean for `capture`
146
150
  */
147
- addEventListener<E = IncaEvent>(type: string, listener: EventListenerOrObject<E> | null, options?: boolean | ListenerOptions): void;
151
+ addEventListener<K extends keyof IncaEventMap>(type: K, listener: EventListenerOrObject<IncaEventMap[K], this> | null, options?: boolean | ListenerOptions): void;
152
+ addEventListener<E = IncaEvent>(type: string, listener: EventListenerOrObject<E, this> | null, options?: boolean | ListenerOptions): void;
148
153
  /**
149
154
  * Drops the registration of `listener` for `type` with the same `capture`.
150
155
  * A call that matches no registration changes nothing.
@@ -152,21 +157,33 @@ export interface IncaEventTarget {
152
157
  * @param listener - the listener that was registered
153
158
  * @param options - an object with `capture`, or a boolean for `capture`
154
159
  */
155
- removeEventListener<E = IncaEvent>(type: string, listener: EventListenerOrObject<E> | null, options?: boolean | Pick<ListenerOptions, "capture">): void;
160
+ removeEventListener<K extends keyof IncaEventMap>(type: K, listener: EventListenerOrObject<IncaEventMap[K], this> | null, options?: boolean | Pick<ListenerOptions, "capture">): void;
161
+ removeEventListener<E = IncaEvent>(type: string, listener: EventListenerOrObject<E, this> | null, options?: boolean | Pick<ListenerOptions, "capture">): void;
156
162
  /**
157
- * Dispatches an `Event` or `CustomEvent` at the target.
163
+ * Dispatches an event built with an event constructor at the target.
158
164
  * @param event - the event to dispatch
159
165
  * @returns `false` when a listener canceled a cancelable event, else `true`
160
- * @throws TypeError when `event` is not an `Event` or `CustomEvent`
166
+ * @throws TypeError when `event` is not an event built with an event constructor
161
167
  * @throws DOMException named `InvalidStateError` when `event` is being dispatched
162
168
  */
163
169
  dispatchEvent(event: EventLike): boolean;
164
170
  }
165
171
  /**
166
- * The event object a listener receives. It carries these fields and the
167
- * fields of its event kind, which this type leaves out. A listener that reads
168
- * them declares its parameter with them, such as
169
- * `(event: IncaEvent & { key: string }) => void`.
172
+ * The event target between the elements and `window`.
173
+ */
174
+ export interface IncaDocument extends IncaEventTarget, EventHandlers<IncaDocument> {
175
+ /** The element that has focus, or `null` when no element has focus. */
176
+ readonly activeElement: IncaElement | null;
177
+ }
178
+ /**
179
+ * The event target at the top of every event path.
180
+ */
181
+ export interface IncaWindow extends IncaEventTarget, EventHandlers<IncaWindow> {
182
+ }
183
+ /**
184
+ * The fields every event carries. {@link IncaEventMap} gives the event type of
185
+ * each name the host dispatches, and a listener for any other name receives
186
+ * this type.
170
187
  *
171
188
  * See https://incajs.tom96da.com/reference/events for the event names the
172
189
  * host dispatches and their fields.
@@ -174,25 +191,40 @@ export interface IncaEventTarget {
174
191
  export interface IncaEvent {
175
192
  /** The event's name. */
176
193
  readonly type: string;
194
+ /** `0`, the {@link IncaEvent.eventPhase} outside a dispatch. */
195
+ readonly NONE: 0;
196
+ /** `1`, the {@link IncaEvent.eventPhase} on an ancestor while the event travels down. */
197
+ readonly CAPTURING_PHASE: 1;
198
+ /** `2`, the {@link IncaEvent.eventPhase} on the target. */
199
+ readonly AT_TARGET: 2;
200
+ /** `3`, the {@link IncaEvent.eventPhase} on an ancestor while the event travels up. */
201
+ readonly BUBBLING_PHASE: 3;
177
202
  /**
178
- * The element the event is about, or `window`. It is the deepest element
179
- * under the pointer for pointer events, the nearest common ancestor of the
180
- * press and the release for `click`, `dblclick` and `auxclick`, and the
181
- * focused element for key events. With no such element it is `window`.
203
+ * The element the event is about. It is the deepest element under the pointer for pointer
204
+ * events (the capturing element while the pointer is captured), the nearest common ancestor of
205
+ * the press and the release for `click`, `dblclick` and `auxclick`, and the focused element for
206
+ * key events. With no such element it is the mount container's element. A script dispatch at
207
+ * `document` or `window` gives that object.
182
208
  */
183
209
  readonly target: IncaEventTarget;
184
210
  /** The same object as {@link IncaEvent.target}. */
185
211
  readonly srcElement: IncaEventTarget;
186
212
  /**
187
- * The element or `window` whose listener is running, and `null` once the
213
+ * The element, `document` or `window` whose listener is running, and `null` once the
188
214
  * event has been handled. A listener function runs with it as `this`.
189
215
  */
190
216
  readonly currentTarget: IncaEventTarget | null;
191
- /** Whether the event travels up from `target`. Fixed per event name. */
217
+ /**
218
+ * Whether the event travels up from `target`. Fixed per event name for the
219
+ * events the host dispatches.
220
+ */
192
221
  readonly bubbles: boolean;
193
- /** Whether `preventDefault()` can cancel the event. Fixed per event name. */
222
+ /**
223
+ * Whether `preventDefault()` can cancel the event. Fixed per event name for
224
+ * the events the host dispatches.
225
+ */
194
226
  readonly cancelable: boolean;
195
- /** Fixed per event name. */
227
+ /** Fixed per event name for the events the host dispatches. */
196
228
  readonly composed: boolean;
197
229
  /**
198
230
  * 1 on the ancestors of `target` while the event travels down, 2 where
@@ -219,17 +251,195 @@ export interface IncaEvent {
219
251
  /** Cancels the event when it is cancelable and the listener is not passive. */
220
252
  preventDefault(): void;
221
253
  /**
222
- * `target` and its ancestors, ending with `window`, and an empty array once
223
- * the event has been handled.
254
+ * `target` and its ancestors, then `document` and `window`, and an empty
255
+ * array once the event has been handled.
224
256
  */
225
257
  composedPath(): IncaEventTarget[];
258
+ /**
259
+ * Sets the type, `bubbles` and `cancelable` of an event that is not being
260
+ * dispatched, clears its stop and cancel flags and makes it untrusted. While
261
+ * the event is dispatched it does nothing.
262
+ */
263
+ initEvent(type: string, bubbles?: boolean, cancelable?: boolean): void;
264
+ }
265
+ /**
266
+ * The event object of a mouse, wheel, keyboard or focus event.
267
+ */
268
+ export interface IncaUIEvent extends IncaEvent {
269
+ /**
270
+ * On the events the host dispatches, the click count of `mousedown`,
271
+ * `mouseup`, `click`, `dblclick` and `auxclick`, and `0` on the others.
272
+ */
273
+ readonly detail: number;
274
+ /** Always `null`. */
275
+ readonly view: null;
276
+ /**
277
+ * On the events the host dispatches: for `mousedown`, `mouseup`, `click`,
278
+ * `dblclick`, `auxclick` and `contextmenu`, `button + 1`. For `wheel`, `0`.
279
+ * For the other mouse events, the lowest held button plus 1, or `0` with no
280
+ * button held. For the pointer events, `button + 1`, so `0` when `button` is `-1`. For a
281
+ * keyboard event, `keyCode`. For a focus event, `0`.
282
+ */
283
+ readonly which: number;
284
+ }
285
+ /** The event object of `focus`, `blur`, `focusin` and `focusout`. */
286
+ export interface IncaFocusEvent extends IncaUIEvent {
287
+ /**
288
+ * The element gaining focus for `blur` and `focusout`, the element losing
289
+ * it for `focus` and `focusin`, or `null`.
290
+ */
291
+ readonly relatedTarget: IncaEventTarget | null;
292
+ }
293
+ /** The event object of the mouse events. */
294
+ export interface IncaMouseEvent extends IncaUIEvent {
295
+ readonly screenX: number;
296
+ readonly screenY: number;
297
+ /** The pointer's position in the window. */
298
+ readonly clientX: number;
299
+ /** The pointer's position in the window. */
300
+ readonly clientY: number;
301
+ /** The same as {@link IncaMouseEvent.clientX}. */
302
+ readonly pageX: number;
303
+ /** The same as {@link IncaMouseEvent.clientY}. */
304
+ readonly pageY: number;
305
+ /** The same as {@link IncaMouseEvent.clientX}. */
306
+ readonly x: number;
307
+ /** The same as {@link IncaMouseEvent.clientY}. */
308
+ readonly y: number;
309
+ /** On the events the host dispatches, the pointer's position from the padding edge of `target`. */
310
+ readonly offsetX: number;
311
+ /** On the events the host dispatches, the pointer's position from the padding edge of `target`. */
312
+ readonly offsetY: number;
313
+ /** On the events the host dispatches, the pointer's travel since the previous `mousemove`, and `0` on other events. */
314
+ readonly movementX: number;
315
+ /** On the events the host dispatches, the pointer's travel since the previous `mousemove`, and `0` on other events. */
316
+ readonly movementY: number;
317
+ /**
318
+ * The button the event is about: `0` left, `1` middle, `2` right, `3` back, `4` forward. `-1` on
319
+ * a pointer event that is about no button.
320
+ */
321
+ readonly button: number;
322
+ /** Every button held, as a bitmask: `1` left, `2` right, `4` middle, `8` back, `16` forward. */
323
+ readonly buttons: number;
324
+ readonly ctrlKey: boolean;
325
+ readonly shiftKey: boolean;
326
+ readonly altKey: boolean;
327
+ readonly metaKey: boolean;
328
+ /**
329
+ * The element the pointer came from for `mouseover` and `mouseenter`, the
330
+ * element it went to for `mouseout` and `mouseleave`, or `null`.
331
+ */
332
+ readonly relatedTarget: IncaEventTarget | null;
333
+ /**
334
+ * Whether the modifier `key` is held: `"Control"`, `"Shift"`, `"Alt"`,
335
+ * `"Meta"`, or `"Accel"` (Meta on macOS, Control elsewhere). Any other name
336
+ * gives `false`.
337
+ */
338
+ getModifierState(key: string): boolean;
339
+ }
340
+ /**
341
+ * The event object of the `pointer*` events, `gotpointercapture`, `lostpointercapture`, `click`,
342
+ * `auxclick` and `contextmenu`.
343
+ */
344
+ export interface IncaPointerEvent extends IncaMouseEvent {
345
+ /**
346
+ * On the events the host dispatches, `1` for the mouse and for the `contextmenu` of a key, and
347
+ * `-1` for the click of a key.
348
+ */
349
+ readonly pointerId: number;
350
+ readonly width: number;
351
+ readonly height: number;
352
+ /** On the pointer events the host dispatches, `0.5` while a button is held, else `0`. */
353
+ readonly pressure: number;
354
+ /** On the events the host dispatches, `"mouse"`, or `""` for the click of a key. */
355
+ readonly pointerType: string;
356
+ /**
357
+ * On the events the host dispatches, `true` on the pointer events and `false` on `click`,
358
+ * `auxclick` and `contextmenu`.
359
+ */
360
+ readonly isPrimary: boolean;
361
+ }
362
+ /** The event object of `wheel`. */
363
+ export interface IncaWheelEvent extends IncaMouseEvent {
364
+ readonly deltaX: number;
365
+ readonly deltaY: number;
366
+ /** `0` on the events the host dispatches. */
367
+ readonly deltaZ: number;
368
+ /** `0` for pixels, `1` for lines. */
369
+ readonly deltaMode: number;
370
+ readonly DOM_DELTA_PIXEL: 0;
371
+ readonly DOM_DELTA_LINE: 1;
372
+ readonly DOM_DELTA_PAGE: 2;
373
+ }
374
+ /** The event object of `keydown` and `keyup`. */
375
+ export interface IncaKeyboardEvent extends IncaUIEvent {
376
+ /** The key's name, such as `"Enter"`, `"F5"` or the typed character. */
377
+ readonly key: string;
378
+ /** `""` on the events the host dispatches. */
379
+ readonly code: string;
380
+ /** `0` on the events the host dispatches. */
381
+ readonly location: number;
382
+ /** Whether the key press is an auto-repeat. */
383
+ readonly repeat: boolean;
384
+ /** `false` on the events the host dispatches. */
385
+ readonly isComposing: boolean;
386
+ /** The key's code on a US keyboard layout, and `0` for a key outside it. */
387
+ readonly keyCode: number;
388
+ /** `0` on the events the host dispatches. */
389
+ readonly charCode: number;
390
+ readonly ctrlKey: boolean;
391
+ readonly shiftKey: boolean;
392
+ readonly altKey: boolean;
393
+ readonly metaKey: boolean;
394
+ readonly DOM_KEY_LOCATION_STANDARD: 0;
395
+ readonly DOM_KEY_LOCATION_LEFT: 1;
396
+ readonly DOM_KEY_LOCATION_RIGHT: 2;
397
+ readonly DOM_KEY_LOCATION_NUMPAD: 3;
398
+ /**
399
+ * Whether the modifier `key` is held: `"Control"`, `"Shift"`, `"Alt"`,
400
+ * `"Meta"`, or `"Accel"` (Meta on macOS, Control elsewhere). Any other name
401
+ * gives `false`.
402
+ */
403
+ getModifierState(key: string): boolean;
404
+ }
405
+ /** The event object of each event name the host dispatches. */
406
+ export interface IncaEventMap {
407
+ auxclick: IncaPointerEvent;
408
+ blur: IncaFocusEvent;
409
+ click: IncaPointerEvent;
410
+ contextmenu: IncaPointerEvent;
411
+ dblclick: IncaMouseEvent;
412
+ focus: IncaFocusEvent;
413
+ focusin: IncaFocusEvent;
414
+ focusout: IncaFocusEvent;
415
+ gotpointercapture: IncaPointerEvent;
416
+ keydown: IncaKeyboardEvent;
417
+ keyup: IncaKeyboardEvent;
418
+ lostpointercapture: IncaPointerEvent;
419
+ mousedown: IncaMouseEvent;
420
+ mouseenter: IncaMouseEvent;
421
+ mouseleave: IncaMouseEvent;
422
+ mousemove: IncaMouseEvent;
423
+ mouseout: IncaMouseEvent;
424
+ mouseover: IncaMouseEvent;
425
+ mouseup: IncaMouseEvent;
426
+ pointerdown: IncaPointerEvent;
427
+ pointerenter: IncaPointerEvent;
428
+ pointerleave: IncaPointerEvent;
429
+ pointermove: IncaPointerEvent;
430
+ pointerout: IncaPointerEvent;
431
+ pointerover: IncaPointerEvent;
432
+ pointerup: IncaPointerEvent;
433
+ scroll: IncaEvent;
434
+ wheel: IncaWheelEvent;
226
435
  }
227
436
  /**
228
437
  * Signature of a callback registered via `addEventListener`. It receives the
229
438
  * event, an {@link IncaEvent} unless the parameter declares another type, and
230
- * runs with the event's `currentTarget` as `this`.
439
+ * runs with the event's `currentTarget`, the target it was registered on, as
440
+ * `this`.
231
441
  */
232
- export type EventListener<E = IncaEvent> = (this: IncaEventTarget, event: E) => void;
442
+ export type EventListener<E = IncaEvent, T = IncaEventTarget> = (this: T, event: E) => void;
233
443
  /**
234
444
  * An object whose `handleEvent` method receives the events, called with the
235
445
  * object as `this`. It takes the event an {@link EventListener} takes.
@@ -241,4 +451,4 @@ export interface EventListenerObject<E = IncaEvent> {
241
451
  * What `addEventListener` accepts as a listener: an {@link EventListener} or
242
452
  * an {@link EventListenerObject}.
243
453
  */
244
- export type EventListenerOrObject<E = IncaEvent> = EventListener<E> | EventListenerObject<E>;
454
+ export type EventListenerOrObject<E = IncaEvent, T = IncaEventTarget> = EventListener<E, T> | EventListenerObject<E>;
@@ -3,7 +3,7 @@ import { IncaCore, IncaElement, IncaNode } from '../rendererCore.mts';
3
3
  /**
4
4
  * Marks `handle` so that Vue's `reactive()` and `ref()` keep the object itself.
5
5
  * A template ref then holds the same object the application receives from
6
- * `activeElement()`.
6
+ * `document.activeElement`.
7
7
  * @param handle - the node handle to mark
8
8
  * @returns `handle`
9
9
  */
@@ -46,8 +46,8 @@ import { IncaCore, IncaElement } from '../rendererCore.mts';
46
46
  * - Event names: `onXxx` listens for the hyphenated name (`onMyEvent` listens
47
47
  * for `my-event`), and `on:xxx` listens for the name after the colon as
48
48
  * written (`on:myEvent` listens for `myEvent`). The listener runs when the
49
- * host dispatches that name. See `IncaEvent` for the fields an event
50
- * carries.
49
+ * host dispatches that name. `IncaEventMap` gives the event type of each
50
+ * name the host dispatches.
51
51
  * - Errors: an error a handler throws, or a rejection of an async handler,
52
52
  * goes to the `onErrorCaptured` hooks and the app's `errorHandler`. Every
53
53
  * handler of an event runs even when an earlier one fails, until one calls