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.
@@ -1,6 +1,8 @@
1
1
  import { RendererOptions } from '@vue/runtime-core';
2
- import { IncaCore } from '../rendererCore.mts';
3
- import { NodeId } from '../types.mts';
2
+ import { IncaCore, IncaEventTarget, NodeId } from '../rendererCore.mts';
3
+ import { RectLike } from './rectOf.mts';
4
+ import { ScrollIntoViewOptions } from './scrollIntoViewArgs.mts';
5
+ import { ScrollOptions } from './scrollPosition.mts';
4
6
  /**
5
7
  * A container host node: either a real element or the hidden stand-in
6
8
  * {@link NodeOps.createComment} uses. Also `@vue/runtime-core`'s
@@ -10,8 +12,11 @@ import { NodeId } from '../types.mts';
10
12
  * node's children, so `parent`/`children` are maintained here as a
11
13
  * JS-side shadow of the tree, kept in sync by {@link NodeOps.insert}/
12
14
  * {@link NodeOps.remove}.
15
+ *
16
+ * After the node is removed, `addEventListener()` and `removeEventListener()`
17
+ * ignore the call, and `dispatchEvent()` returns `true`.
13
18
  */
14
- export interface IncaElement {
19
+ export interface IncaElement extends IncaEventTarget {
15
20
  /**
16
21
  * The underlying native node's id — the only part of this object the native
17
22
  * tree itself knows about.
@@ -27,16 +32,77 @@ export interface IncaElement {
27
32
  parent: IncaElement | null;
28
33
  /** This node's children, in render order. */
29
34
  children: IncaNode[];
30
- /** Focuses this node next frame. The node needs a `tabindex` attribute. */
31
- focus(): void;
35
+ /**
36
+ * Focuses this node next frame. The node needs a `tabindex` attribute. A
37
+ * `true` `preventScroll` keeps every scroll container where it is. After
38
+ * the node is removed, the call does nothing.
39
+ */
40
+ focus(options?: {
41
+ preventScroll?: boolean;
42
+ }): void;
32
43
  /** Unfocuses this node next frame, if it is the focused one. */
33
44
  blur(): void;
34
45
  /**
35
- * Assigning sets the `tabindex` attribute to the integer part of the
36
- * value. Reading returns the last value assigned, or `-1` (`0` for a
37
- * `button`).
46
+ * Fires an untrusted `click` at this node. A disabled `button`, a node whose
47
+ * own click is still running and an unknown node ignore the call.
48
+ */
49
+ click(): void;
50
+ /**
51
+ * Assigning sets the `tabindex` attribute to the value's integer part,
52
+ * wrapped to 32 bits. Reading returns the `tabindex` attribute as an
53
+ * integer, or `-1` (`0` for a `button`) when it is unset or invalid.
54
+ * After the node is removed, reading gives that default and assigning does
55
+ * nothing.
38
56
  */
39
57
  tabIndex: number;
58
+ /**
59
+ * The box this node was drawn at in the last frame, in window logical
60
+ * pixels. A node created in the same task reads all zeros.
61
+ */
62
+ getBoundingClientRect(): RectLike;
63
+ /** The box width from the last frame, rounded. `0` until a frame draws the node. */
64
+ readonly offsetWidth: number;
65
+ /** The box height from the last frame, rounded. `0` until a frame draws the node. */
66
+ readonly offsetHeight: number;
67
+ /** The box's left edge from the last frame, relative to {@link offsetParent}. Stays fixed while the parent scrolls. */
68
+ readonly offsetLeft: number;
69
+ /** The box's top edge from the last frame, relative to {@link offsetParent}. Stays fixed while the parent scrolls. */
70
+ readonly offsetTop: number;
71
+ /**
72
+ * The parent, when this node and the parent both have a box from the last frame.
73
+ * `null` when either lacks a box or there is no parent.
74
+ */
75
+ readonly offsetParent: IncaElement | null;
76
+ /** The box width less both borders, rounded, at least `0`. */
77
+ readonly clientWidth: number;
78
+ /** The box height less both borders, rounded, at least `0`. */
79
+ readonly clientHeight: number;
80
+ /** The border width, rounded. */
81
+ readonly clientLeft: number;
82
+ /** The border width, rounded. */
83
+ readonly clientTop: number;
84
+ /** The horizontal scroll offset. Assigning moves it at once, and reads are clamped to the last frame's maximum. */
85
+ scrollLeft: number;
86
+ /** The vertical scroll offset. Assigning moves it at once, and reads are clamped to the last frame's maximum. */
87
+ scrollTop: number;
88
+ /** The content width: {@link clientWidth} plus the largest horizontal offset. */
89
+ readonly scrollWidth: number;
90
+ /** The content height: {@link clientHeight} plus the largest vertical offset. */
91
+ readonly scrollHeight: number;
92
+ /** Sets the offset to `(left, top)`, or to the options object's `left` and `top`. */
93
+ scrollTo(left?: number, top?: number): void;
94
+ scrollTo(options: ScrollOptions): void;
95
+ /** Adds `(left, top)` to the offset, or the options object's `left` and `top`. */
96
+ scrollBy(left?: number, top?: number): void;
97
+ scrollBy(options: ScrollOptions): void;
98
+ /**
99
+ * Scrolls each scroll container around this node so the node shows. `true`
100
+ * or no argument aligns to the start and `false` to the end. An options
101
+ * object sets `block` (default `"start"`) and `inline` (default `"nearest"`);
102
+ * `behavior` is accepted and ignored. After the node is removed, the call
103
+ * does nothing.
104
+ */
105
+ scrollIntoView(arg?: boolean | ScrollIntoViewOptions): void;
40
106
  }
41
107
  /** A text leaf host node — `@vue/runtime-core`'s `HostNode` for text. */
42
108
  export interface IncaText {
@@ -0,0 +1,14 @@
1
+ import { IncaCore } from '../rendererCore.mts';
2
+ import { IncaElement } from './nodeOps.mts';
3
+ /**
4
+ * Where a node sits inside the padding edge of its offset parent, rounded to
5
+ * whole pixels. A node with no offset parent is measured from the window
6
+ * origin.
7
+ * @param core - the incajs bindings to read through
8
+ * @param el - the node to measure
9
+ * @returns `left` and `top`; both `0` when the node has no recorded box
10
+ */
11
+ export declare function offsetOf(core: IncaCore, el: IncaElement): {
12
+ left: number;
13
+ top: number;
14
+ };
@@ -0,0 +1,10 @@
1
+ import { IncaCore } from '../rendererCore.mts';
2
+ import { IncaElement } from './nodeOps.mts';
3
+ /**
4
+ * The parent a node's offsets are measured from. It is the parent when both
5
+ * the node and the parent have a recorded box.
6
+ * @param core - the incajs bindings to read through
7
+ * @param el - the node to query
8
+ * @returns the parent, or `null`
9
+ */
10
+ export declare function offsetParentOf(core: IncaCore, el: IncaElement): IncaElement | null;
@@ -24,20 +24,26 @@ import { IncaElement } from './nodeOps.mts';
24
24
  * The key registers `nextValue` as a listener for `xxx`, taking a function
25
25
  * or an array of them, and unbinds that key's listener for anything else.
26
26
  * - Order: each distinct key (`onClick`, `onClickOnce`) is its own listener.
27
- * They run in the order first registered, a re-patch keeps its place, and
28
- * the host sees one registration per element and event.
27
+ * Keys that share the event, phase and passivity run in the order first
28
+ * registered, a re-patch keeps its place, and the host sees one registration
29
+ * per element, event, phase and passivity. Capture registrations run before
30
+ * every bubble registration, also on the target. Within a pass,
31
+ * registrations run in the order the host registered them.
29
32
  * - Propagation: `stopImmediatePropagation()` stops the listeners after it.
30
33
  * - Timing: a listener attached while an event is being handled first runs
31
34
  * for the next event; events are told apart by the `eventId` the host puts
32
35
  * on each one.
33
36
  * - Modifiers: a trailing `Once`/`Passive`/`Capture` suffix (from Vue's
34
37
  * `.once`/`.passive`/`.capture` modifiers) is stripped first. `.once`
35
- * really removes the listener after it fires once, and a listener that has
36
- * fired stays spent until its key is removed. `.passive`/`.capture` bind
37
- * as an ordinary listener with no native passive/capture-phase support
38
- * yet.
39
- * - Event names: see {@link EventListener} for which names are wired to real
40
- * input by the native host today; other names are accepted but never fire.
38
+ * removes the listener after it fires once, and a listener that has fired
39
+ * stays spent until its key is removed. `.capture` registers the listener
40
+ * for the phase in which the event travels down to the target, and
41
+ * `.passive` ignores `preventDefault()` calls inside it.
42
+ * - Event names: `onXxx` listens for the hyphenated name (`onMyEvent` listens
43
+ * for `my-event`), and `on:xxx` listens for the name after the colon as
44
+ * 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.
41
47
  * - Errors: an error a handler throws, or a rejection of an async handler,
42
48
  * goes to the `onErrorCaptured` hooks and the app's `errorHandler`. Every
43
49
  * handler of an event runs even when an earlier one fails, until one calls
@@ -0,0 +1,25 @@
1
+ import { LayoutBox } from './layoutBox.mts';
2
+ /** The plain values of a {@link RectLike}, as `toJSON` returns them. */
3
+ export interface RectValues {
4
+ readonly x: number;
5
+ readonly y: number;
6
+ readonly width: number;
7
+ readonly height: number;
8
+ readonly top: number;
9
+ readonly left: number;
10
+ readonly right: number;
11
+ readonly bottom: number;
12
+ }
13
+ /**
14
+ * A rectangle with its position, its size and its four edges. `toJSON()` returns
15
+ * the plain values.
16
+ */
17
+ export interface RectLike extends RectValues {
18
+ toJSON(): RectValues;
19
+ }
20
+ /**
21
+ * Builds a rect from a node's box. Values stay unrounded.
22
+ * @param layout - the box from {@link LayoutBox}, or `null` for no record
23
+ * @returns the rect; all zeros for `null`
24
+ */
25
+ export declare function rectOf(layout: LayoutBox | null): RectLike;
@@ -0,0 +1,22 @@
1
+ import { ScrollAlignment } from '../types.mts';
2
+ /** The options form of `scrollIntoView()`. `behavior` is accepted and ignored. */
3
+ export interface ScrollIntoViewOptions {
4
+ /** The vertical alignment. Defaults to `"start"`. */
5
+ block?: ScrollAlignment;
6
+ /** The horizontal alignment. Defaults to `"nearest"`. */
7
+ inline?: ScrollAlignment;
8
+ /** `behavior` is ignored; every scroll applies at once. */
9
+ behavior?: "auto" | "instant" | "smooth";
10
+ }
11
+ /**
12
+ * Turns `scrollIntoView()`'s argument into the alignment pair. `true` or no
13
+ * argument aligns to the start, `false` to the end, and an options object
14
+ * takes each axis from its own key. An unknown string falls back to that
15
+ * axis's default.
16
+ * @param arg - the boolean or options object the caller passed
17
+ * @returns the `block` and `inline` alignments to send to the host
18
+ */
19
+ export declare function scrollIntoViewArgs(arg?: boolean | ScrollIntoViewOptions): {
20
+ block: ScrollAlignment;
21
+ inline: ScrollAlignment;
22
+ };
@@ -0,0 +1,22 @@
1
+ import { IncaCore } from '../rendererCore.mts';
2
+ import { IncaElement } from './nodeOps.mts';
3
+ /** The options form of `scrollTo()` and `scrollBy()`. `behavior` is accepted and ignored. */
4
+ export interface ScrollOptions {
5
+ /** The horizontal offset. Omit to keep the current one. */
6
+ left?: number;
7
+ /** The vertical offset. Omit to keep the current one. */
8
+ top?: number;
9
+ /** `behavior` is ignored; every scroll applies at once. */
10
+ behavior?: "auto" | "instant" | "smooth";
11
+ }
12
+ /** Either `(left, top)` or an options object. */
13
+ export type ScrollArgs = [left?: number, top?: number] | [options?: ScrollOptions];
14
+ /**
15
+ * Moves a node's scroll offset. An omitted axis keeps its offset, and a
16
+ * non-finite value counts as `0`. A destroyed node ignores the call.
17
+ * @param core - the incajs bindings to write through
18
+ * @param el - the node to scroll
19
+ * @param args - `(left, top)` or `{ left, top }`
20
+ * @param relative - `true` adds the values to the current offset
21
+ */
22
+ export declare function scrollPosition(core: IncaCore, el: IncaElement, args: ScrollArgs, relative: boolean): void;
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Marks `handle` so that Vue's `reactive()` and `ref()` keep the object itself.
3
+ * A template ref then holds the same object the application receives from
4
+ * `activeElement()`.
5
+ * @param handle - the node handle to mark
6
+ * @returns `handle`
7
+ */
8
+ export declare function skipReactive<T extends object>(handle: T): T;
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Reads a `tabindex` attribute value as the element's tab index. A value that
3
+ * is missing, not a string or number, has no leading integer, or falls outside
4
+ * the 32-bit signed range yields the default.
5
+ * @param value - the stored `tabindex` attribute, or `null` if unset
6
+ * @param kind - the element kind; `"button"` defaults to `0`, any other kind to `-1`
7
+ * @returns the parsed tab index, or the default
8
+ */
9
+ export declare function tabIndexOf(value: string | number | boolean | null, kind: string): number;