@nice2dev/ui-core 1.2.2 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/CHANGELOG.md +445 -0
  2. package/dist/core/NiceUserPreferences.d.ts +9 -2
  3. package/dist/core/a11y.d.ts +42 -5
  4. package/dist/core/hooks.d.ts +4 -0
  5. package/dist/core/spatialNav.d.ts +31 -8
  6. package/dist/core/useGamepad.d.ts +17 -4
  7. package/dist/index.cjs +21 -21
  8. package/dist/index.d.ts +1 -0
  9. package/dist/index.mjs +3965 -4756
  10. package/dist/input/bindings.d.ts +35 -0
  11. package/dist/input/elements.d.ts +71 -0
  12. package/dist/input/engine.d.ts +153 -0
  13. package/dist/input/focus/candidates.d.ts +18 -0
  14. package/dist/input/focus/navigator.d.ts +24 -0
  15. package/dist/input/focus/scopes.d.ts +44 -0
  16. package/dist/input/focus/spatial.d.ts +13 -0
  17. package/dist/input/gamepadFamily.d.ts +30 -0
  18. package/dist/input/gamepadPoller.d.ts +57 -0
  19. package/dist/input/index.d.ts +33 -0
  20. package/dist/input/osk/editing.d.ts +15 -0
  21. package/dist/input/osk/layouts.d.ts +47 -0
  22. package/dist/input/prompts/NiceButtonPrompt.d.ts +35 -0
  23. package/dist/input/prompts/NiceControlHint.d.ts +21 -0
  24. package/dist/input/prompts/NiceInputHintBar.d.ts +31 -0
  25. package/dist/input/prompts/NiceKeyCap.d.ts +18 -0
  26. package/dist/input/prompts/keys.d.ts +23 -0
  27. package/dist/input/react/NiceFocusScope.d.ts +14 -0
  28. package/dist/input/react/NiceInputProvider.d.ts +42 -0
  29. package/dist/input/react/actions.d.ts +48 -0
  30. package/dist/input/react/hints.d.ts +34 -0
  31. package/dist/input/react/hooks.d.ts +52 -0
  32. package/dist/input/react/useElementEffect.d.ts +7 -0
  33. package/dist/input/react/useGridFocus.d.ts +26 -0
  34. package/dist/input/react/useMenuButton.d.ts +29 -0
  35. package/dist/input/react/useOverlayFocus.d.ts +33 -0
  36. package/dist/input/react/useRovingFocus.d.ts +46 -0
  37. package/dist/input/react/useTreeFocus.d.ts +30 -0
  38. package/dist/input/tabEscape.d.ts +20 -0
  39. package/dist/input/types.d.ts +98 -0
  40. package/dist/input-layer-Hyi3G0IM.js +3911 -0
  41. package/dist/input-layer-Kez0PkmN.cjs +1 -0
  42. package/dist/input.cjs +1 -0
  43. package/dist/input.mjs +94 -0
  44. package/package.json +8 -2
@@ -0,0 +1,35 @@
1
+ import type { NiceNavDirection, NiceGamepadButton, NiceGamepadFamily, NiceInputPreferences, NiceIntent } from './types';
2
+ /** An intent with its direction, as a key or a button produces it. */
3
+ export interface NiceIntentHit {
4
+ intent: NiceIntent;
5
+ direction?: NiceNavDirection;
6
+ }
7
+ /** Default keys per intent. `navigate` lists up, down, left, right in that order. */
8
+ export declare const NICE_DEFAULT_KEYBOARD_BINDINGS: Readonly<Record<NiceIntent, readonly string[]>>;
9
+ /**
10
+ * Default buttons per intent. `activate` / `back` hold the confirm / cancel pair for south-confirm
11
+ * pads; `confirmButtonFor` swaps them for Nintendo. `navigate` lists up, down, left, right.
12
+ */
13
+ export declare const NICE_DEFAULT_GAMEPAD_BINDINGS: Readonly<Record<NiceIntent, readonly NiceGamepadButton[]>>;
14
+ /** A parsed key binding. `primary` is Ctrl, or ⌘ on macOS. */
15
+ export interface NiceKeyChord {
16
+ key: string;
17
+ primary: boolean;
18
+ alt: boolean;
19
+ shift: boolean;
20
+ }
21
+ /** `KeyboardEvent.key` in the names the bindings use (`Space`, `Escape`, …). */
22
+ export declare function normalizeKey(key: string): string;
23
+ /** `'Ctrl+Shift+F10'` → chord. `Ctrl`, `Cmd`, `Meta` and `Mod` all mean the primary modifier. */
24
+ export declare function parseKeyChord(chord: string): NiceKeyChord;
25
+ export declare function chordMatches(chord: NiceKeyChord, e: Pick<KeyboardEvent, 'key' | 'ctrlKey' | 'metaKey' | 'altKey' | 'shiftKey'>): boolean;
26
+ /** The keyboard table with the user's overrides, parsed once per preference change. */
27
+ export declare function resolveKeyboardBindings(prefs: Pick<NiceInputPreferences, 'keyboardBindings'>): Record<NiceIntent, NiceKeyChord[]>;
28
+ /** The intent a key event means, if any. */
29
+ export declare function intentFromKey(e: Pick<KeyboardEvent, 'key' | 'ctrlKey' | 'metaKey' | 'altKey' | 'shiftKey'>, table: Record<NiceIntent, NiceKeyChord[]>): NiceIntentHit | null;
30
+ /** Keys a TV remote has and a keyboard does not. */
31
+ export declare function remoteIntent(e: Pick<KeyboardEvent, 'key' | 'keyCode'>): NiceIntentHit | null;
32
+ /** Buttons per intent for a pad of the family, with the confirm rule and the user's overrides. */
33
+ export declare function resolveGamepadBindings(prefs: Pick<NiceInputPreferences, 'gamepadBindings' | 'confirmButton'>, family: NiceGamepadFamily | null): Record<NiceIntent, NiceGamepadButton[]>;
34
+ /** Button → intent, the first binding in intent order winning. */
35
+ export declare function gamepadIntentMap(table: Record<NiceIntent, NiceGamepadButton[]>): Map<NiceGamepadButton, NiceIntentHit>;
@@ -0,0 +1,71 @@
1
+ /**
2
+ * What the engine needs to know about the focused element (ADR-005 §§ 4, 6): whether a key belongs
3
+ * to an editable field, whether the element activates by click, and whether it has to be engaged
4
+ * before the d-pad may change it.
5
+ */
6
+ import type { NiceIntentHit } from './bindings';
7
+ import type { NiceNavDirection, NiceEngageKind } from './types';
8
+ export declare const isTextInput: (el: Element) => el is HTMLInputElement;
9
+ /**
10
+ * A key the field uses itself, which the engine must not take: carets (← →, Home, End), typing
11
+ * (Space, `?`), lines and pages of a multi-line field, the value keys of native value inputs and
12
+ * selects. ↑ / ↓ of a single-line text field are left to the arrow policy.
13
+ */
14
+ export declare function keyBelongsToField(el: Element, hit: NiceIntentHit): boolean;
15
+ /** Elements whose activation is a click — the pad's confirm button clicks them. */
16
+ export declare function isClickActivatable(el: Element): el is HTMLElement;
17
+ /**
18
+ * Clicks an element. An SVG one — a `<g role="button">` of a diagram — has no `click()` of its
19
+ * own, so it gets a dispatched click event.
20
+ */
21
+ export declare function clickElement(el: Element): void;
22
+ /** What {@link clickOnActivationKey} reads of a key event — a React one or a DOM one. */
23
+ export interface NiceActivationKeyEvent {
24
+ key: string;
25
+ repeat?: boolean;
26
+ defaultPrevented?: boolean;
27
+ ctrlKey?: boolean;
28
+ shiftKey?: boolean;
29
+ altKey?: boolean;
30
+ metaKey?: boolean;
31
+ target: EventTarget | null;
32
+ currentTarget: EventTarget | null;
33
+ preventDefault(): void;
34
+ }
35
+ /**
36
+ * `onKeyDown` of an element that acts on a click but is no button — a row, card or tile given
37
+ * `role="button"` and `tabIndex={0}`: Enter and Space click it, as they press a button, once per
38
+ * press (TODO_1.3.0 C1). The click carries the modifiers, so Ctrl+Enter selects as Ctrl+click
39
+ * does. A key pressed in a control inside the element is that control's.
40
+ */
41
+ export declare function clickOnActivationKey(e: NiceActivationKeyEvent): void;
42
+ /** How the element has to be engaged before the d-pad changes it, or `null` when it does not. */
43
+ export declare function engageKindOf(el: Element): NiceEngageKind | null;
44
+ /** A popup control is engaged while its popup is open; the others carry `data-nice-engaged`. */
45
+ export declare function isEngaged(el: Element, kind: NiceEngageKind): boolean;
46
+ /** Native value inputs and selects ignore synthetic keys; the engine steps them itself. */
47
+ export declare function isNativeValueControl(el: Element): el is HTMLInputElement | HTMLSelectElement;
48
+ /** Set by `useEngage({ restoreOnCancel })`: the control puts its value back on `back`. */
49
+ export declare const ENGAGE_RESTORE_ATTR = "data-nice-engage-restore";
50
+ /** A native number field — the engine puts its value from before back on `back`. */
51
+ export declare const isNativeNumberField: (el: Element) => el is HTMLInputElement;
52
+ /**
53
+ * Whether `back` on the engaged control puts its value from before back, as number fields do
54
+ * (R 6.3.4): natively, or the control itself (`useEngage` with `restoreOnCancel`).
55
+ */
56
+ export declare function restoresOnCancel(el: Element): boolean;
57
+ /**
58
+ * Writes the text of a field the way typing does — for the on-screen keyboard (H2): past
59
+ * React's value tracker (a controlled field hears it in `onChange`), with an `input` event, and
60
+ * the caret where it belongs.
61
+ */
62
+ export declare function setFieldText(el: HTMLInputElement | HTMLTextAreaElement, text: string, caret?: number): void;
63
+ /** Puts a native control's earlier value back, with the events a user's edit fires. */
64
+ export declare function restoreNativeValue(el: HTMLInputElement | HTMLSelectElement, value: string): void;
65
+ /**
66
+ * One step of a native value control: arrows ±1, `big` ×10 (bumpers), `edge` to the minimum or
67
+ * maximum (triggers). Returns whether the value changed.
68
+ */
69
+ export declare function stepNativeControl(el: HTMLInputElement | HTMLSelectElement, direction: NiceNavDirection, mode?: 'step' | 'big' | 'edge'): boolean;
70
+ /** Moves the caret of a text field by one character. */
71
+ export declare function moveCaret(el: Element, direction: NiceNavDirection): boolean;
@@ -0,0 +1,153 @@
1
+ /**
2
+ * NiceInputEngine — one per window (ADR-005 § 4). Turns keyboard, gamepad and remote events into
3
+ * intents, dispatches them as the `nice-intent` DOM event on the focused element and runs the
4
+ * default action when nobody consumed them: spatial focus moves, clicks, closing the top overlay,
5
+ * scrolling. For pads it also emulates the equivalent key on the focused element first, so every
6
+ * control with a keyboard pattern works with a pad without knowing about pads.
7
+ *
8
+ * Framework-free. Without a pad it costs one keydown, one pointerdown and one focusin listener —
9
+ * no animation frame.
10
+ */
11
+ import { type NiceKeyChord } from './bindings';
12
+ import { type NiceNavDirection, type NiceGamepadButton, type NiceGamepadFamily, type NiceGamepadInfo, type NiceInputMethod, type NiceInputPreferences, type NiceInputSource, type NiceIntent, type NiceIntentDetail } from './types';
13
+ export interface NiceInputState {
14
+ method: NiceInputMethod;
15
+ /** Family of the pad used last; `null` until a pad is used. */
16
+ family: NiceGamepadFamily | null;
17
+ pads: readonly NiceGamepadInfo[];
18
+ preferences: NiceInputPreferences;
19
+ /** Whether hints show now: the `hints` preference, the input method and the toggle intent. */
20
+ hintsVisible: boolean;
21
+ }
22
+ export interface NiceOverlayEntry {
23
+ element: HTMLElement;
24
+ /** Modal overlays keep directional moves inside. */
25
+ modal: boolean;
26
+ /** Called by `back` (B, Escape, remote Back) when the overlay is the top one. */
27
+ onClose?: (source: NiceInputSource) => void;
28
+ }
29
+ /** Raw pads every polled frame, for games and the device tester. */
30
+ export type NiceGamepadFrameListener = (pads: readonly Gamepad[], now: number) => void;
31
+ export type NiceTranslate = (key: string, fallback: string) => string;
32
+ /** What `captureNextInput` caught: a pad button, or a key chord (`'Ctrl+Shift+K'`). */
33
+ export interface NiceCapturedInput {
34
+ button?: NiceGamepadButton;
35
+ keys?: string;
36
+ }
37
+ export declare class NiceInputEngine {
38
+ readonly win: Window;
39
+ private readonly doc;
40
+ private started;
41
+ private state;
42
+ private readonly listeners;
43
+ private readonly frameListeners;
44
+ private keyTable;
45
+ private readonly padMaps;
46
+ private readonly poller;
47
+ private readonly memory;
48
+ /** Values of engaged native number fields from before, put back when left with `back`. */
49
+ private readonly engagedValues;
50
+ private readonly overlays;
51
+ private hintsToggled;
52
+ private activePad;
53
+ private lastFocus;
54
+ private observer;
55
+ private live;
56
+ private snapshot;
57
+ private capture;
58
+ private translate;
59
+ private readonly tv;
60
+ constructor(win: Window);
61
+ get isStarted(): boolean;
62
+ /** Whether the page runs in a TV browser (webOS, Tizen, Android TV, …): remote and 10-foot. */
63
+ get isTv(): boolean;
64
+ start(): void;
65
+ stop(): void;
66
+ /** Whether the gamepad loop is scheduled (false without a pad). */
67
+ get polling(): boolean;
68
+ /** Same object until something changes (fit for `useSyncExternalStore`). */
69
+ getState(): NiceInputState;
70
+ subscribe(listener: () => void): () => void;
71
+ setPreferences(prefs: Partial<NiceInputPreferences>): void;
72
+ /** Words of announcements and labels; the React provider passes the app's translator. */
73
+ setTranslator(translate: NiceTranslate): void;
74
+ /** Pad family of the prompts: the preference, else the pad used last. */
75
+ get glyphFamily(): NiceGamepadFamily;
76
+ /** The buttons bound to an intent on a pad of the family (for prompts). */
77
+ gamepadBinding(intent: NiceIntent, family?: NiceGamepadFamily): NiceGamepadButton[];
78
+ /** The keys bound to an intent (for prompts), as written in the preferences. */
79
+ keyboardBinding(intent: NiceIntent): NiceKeyChord[];
80
+ toggleHints(): void;
81
+ /**
82
+ * Hands the next pad button or key press to `onInput` instead of acting on it (a bindings
83
+ * screen); returns what cancels the capture.
84
+ */
85
+ captureNextInput(onInput: (input: NiceCapturedInput) => void): () => void;
86
+ private update;
87
+ private setMethod;
88
+ /** Raw pads every polled frame while a pad is connected. */
89
+ subscribeGamepadFrames(listener: NiceGamepadFrameListener): () => void;
90
+ /**
91
+ * The pads as read in the last polled frame — empty without a pad. For code that runs its own
92
+ * animation loop (games, particle effects) instead of a second `getGamepads()` reader.
93
+ */
94
+ get gamepadSnapshot(): readonly Gamepad[];
95
+ /** Feedback rumble on the pad used last, when the user allows vibration. */
96
+ vibrate(duration: number, strength?: number): void;
97
+ /** Rumble a given pad regardless of the preference (a game's own effect). */
98
+ rumble(index: number, duration: number, weak?: number, strong?: number): void;
99
+ /** Puts an overlay on the stack; returns what takes it off. */
100
+ pushOverlay(entry: NiceOverlayEntry): () => void;
101
+ topOverlay(): NiceOverlayEntry | undefined;
102
+ /** Closes the top overlay that can be closed; returns whether one was. */
103
+ closeTopOverlay(source: NiceInputSource): boolean;
104
+ /** Dispatches `nice-intent` on the target; returns whether a handler consumed it. */
105
+ dispatchIntent(detail: NiceIntentDetail, target?: Element): boolean;
106
+ /** Moves focus in a direction through the scope tree; returns whether it moved. */
107
+ moveFocus(direction: NiceNavDirection, from?: Element): boolean;
108
+ /** The `view` intent: next (`down`) or previous (`up`) region. */
109
+ focusRegion(direction: NiceNavDirection, from?: Element): boolean;
110
+ /** Focuses the element and brings it into view (scroll-padding respected). */
111
+ focusElement(el: HTMLElement): void;
112
+ /** Engages a control (ADR-005 § 6); popup controls open instead. */
113
+ engage(el: HTMLElement, source: NiceInputSource, kind?: import("./types").NiceEngageKind | null): void;
114
+ /**
115
+ * Releases an engaged control; `cancelled` when left with `back`. A native number field gets
116
+ * its value from before back; custom controls do that in `useEngage`'s `onRelease`.
117
+ */
118
+ release(el: HTMLElement, source: NiceInputSource, cancelled: boolean): void;
119
+ private readonly onKeyDown;
120
+ /** Defaults of trusted keys: the browser already clicks, types and scrolls. */
121
+ private keyDefault;
122
+ private arrowPolicy;
123
+ private padMap;
124
+ private readonly onPadButton;
125
+ private readonly onPadStick;
126
+ private readonly onPadScroll;
127
+ /** A pad intent: the intent event, then engage rules, key emulation and the default action. */
128
+ private deviceIntent;
129
+ /** A synthetic key on the element; returns whether a handler consumed it. */
130
+ private emulateKey;
131
+ /** `secondary` on a pad: the context menu of the element, as a right click would open it. */
132
+ private contextMenu;
133
+ private readonly onPointerDown;
134
+ private readonly onFocusIn;
135
+ private readonly onFocusOut;
136
+ private watchRecovery;
137
+ /** Focus never gets lost: a removed focused element hands focus to its nearest neighbour. */
138
+ private readonly recover;
139
+ private focused;
140
+ private targetOf;
141
+ /** Moves stay inside the top modal overlay. */
142
+ private navigationRoot;
143
+ /** Nothing focused yet: the remembered element, else the first one of the main region. */
144
+ private focusInitial;
145
+ private fireEngage;
146
+ /** Polite announcement through the engine's own live region. */
147
+ announce(message: string): void;
148
+ }
149
+ /**
150
+ * The engine of the window, created on first use and started unless `start` is false (React reads
151
+ * its state during render and starts it from an effect).
152
+ */
153
+ export declare function getInputEngine(win?: Window, start?: boolean): NiceInputEngine;
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Focus candidates — found in the DOM, never registered (ADR-005 § 5): the tabbable elements plus
3
+ * `[data-nice-focusable]`, minus disabled, inert, aria-hidden and invisible ones. A composite with
4
+ * a roving tabindex shows one tabbable item, so it is one stop, entered on its active item.
5
+ */
6
+ export interface NiceRect {
7
+ left: number;
8
+ top: number;
9
+ right: number;
10
+ bottom: number;
11
+ width: number;
12
+ height: number;
13
+ }
14
+ export declare function rectOf(el: Element): NiceRect;
15
+ /** Whether directional navigation and recovery may land on the element. */
16
+ export declare function isFocusCandidate(el: Element): el is HTMLElement;
17
+ /** Candidates inside `root` (the root itself excluded), in document order, minus the subtrees of `exclude`. */
18
+ export declare function focusCandidates(root: ParentNode, exclude?: readonly (Element | null | undefined)[]): HTMLElement[];
@@ -0,0 +1,24 @@
1
+ /**
2
+ * Moving focus by direction through the scope tree (ADR-005 § 5): candidates of the innermost
3
+ * scope first; nothing there → wrap (linear scopes that wrap) or escalate to the parent scope,
4
+ * never out of a trap or the root. A target inside a scope that is being entered is redirected by
5
+ * that scope's enter rule (focus memory by default).
6
+ */
7
+ import type { NiceNavDirection } from '../types';
8
+ import { type NiceRect } from './candidates';
9
+ export interface NiceFocusMoveContext {
10
+ /** Where moves end: the document body, or the top modal overlay. */
11
+ root: Element;
12
+ /** Last focused element per scope. */
13
+ memory: WeakMap<Element, HTMLElement>;
14
+ }
15
+ /** The element focus lands on when a move enters scopes `from` is not in. */
16
+ export declare function applyEnterRule(target: HTMLElement, from: Element, memory: WeakMap<Element, HTMLElement>): HTMLElement;
17
+ /** The element a move from `from` in direction `d` lands on, or `null`. */
18
+ export declare function findFocusTarget(from: Element, d: NiceNavDirection, ctx: NiceFocusMoveContext): HTMLElement | null;
19
+ /** The candidate closest to a point where a focused element used to be (focus recovery). */
20
+ export declare function nearestCandidate(root: Element, near: NiceRect): HTMLElement | null;
21
+ /** Stops of the `view` intent: marked regions and landmarks. */
22
+ export declare const REGION_SELECTOR: string;
23
+ /** The `view` intent: focus into the next (`down`) or previous (`up`) region with candidates. */
24
+ export declare function findRegionTarget(from: Element, d: NiceNavDirection, ctx: NiceFocusMoveContext): HTMLElement | null;
@@ -0,0 +1,44 @@
1
+ /**
2
+ * Focus scopes (ADR-005 § 5) — marked on containers with data attributes, so any element can be a
3
+ * scope and the engine finds them with `closest()`:
4
+ *
5
+ * data-nice-focus-scope="spatial|vertical|horizontal|grid|none" navigation inside the scope
6
+ * data-nice-scope-wrap linear scopes wrap around
7
+ * data-nice-scope-trap never escalate out (overlays)
8
+ * data-nice-scope-enter="last|selected|first" where focus lands on entry
9
+ * data-nice-arrows="spatial|native" arrow policy of a region
10
+ * data-nice-region="Label" a stop of the `view` intent
11
+ */
12
+ export type NiceScopeNav = 'spatial' | 'vertical' | 'horizontal' | 'grid' | 'none';
13
+ export type NiceScopeEnter = 'last' | 'selected' | 'first';
14
+ export type NiceArrowPolicy = 'spatial' | 'native';
15
+ export interface NiceFocusScopeOptions {
16
+ /** Navigation inside the scope (default `spatial`). */
17
+ nav?: NiceScopeNav;
18
+ /** Linear scopes wrap from the last item to the first. */
19
+ wrap?: boolean;
20
+ /** Focus never leaves the scope directionally (modal overlays). */
21
+ trap?: boolean;
22
+ /** Where focus lands when it enters the scope (default `last` — focus memory). */
23
+ enter?: NiceScopeEnter;
24
+ /** Unhandled arrow keys inside: move focus (`spatial`) or scroll (`native`). */
25
+ arrows?: NiceArrowPolicy;
26
+ /** Makes the scope a stop of the `view` intent (F6 / Select); the value is its name. */
27
+ region?: string;
28
+ }
29
+ export declare const SCOPE_ATTR = "data-nice-focus-scope";
30
+ /** Sets the scope attributes on the element; returns what puts the previous values back. */
31
+ export declare function applyFocusScope(el: HTMLElement, opts: NiceFocusScopeOptions): () => void;
32
+ export interface NiceScopeInfo {
33
+ nav: NiceScopeNav;
34
+ wrap: boolean;
35
+ trap: boolean;
36
+ enter: NiceScopeEnter;
37
+ }
38
+ export declare function readScope(el: Element): NiceScopeInfo;
39
+ /** The scope around `el` (not `el` itself), or `root` when there is none inside it. */
40
+ export declare function scopeAround(el: Element, root: Element): Element;
41
+ /** Every scope `el` is inside, innermost first. */
42
+ export declare function scopesAround(el: Element): Element[];
43
+ /** The arrow policy of the region around `el`, if one says. */
44
+ export declare function arrowPolicyAt(el: Element): NiceArrowPolicy | null;
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Directional choice between focus candidates (ADR-005 § 5): the candidates beyond the current
3
+ * element's edge in the direction of the move, scored by the gap along the axis plus a weighted gap
4
+ * across it (zero when the projections overlap), so the same row or column wins. When nothing lies
5
+ * fully beyond the edge — overlapping layouts — candidates whose centre is beyond the current
6
+ * centre are scored the same way.
7
+ */
8
+ import type { NiceNavDirection } from '../types';
9
+ import type { NiceRect } from './candidates';
10
+ /** Lower is better. */
11
+ export declare function spatialScore(from: NiceRect, to: NiceRect, d: NiceNavDirection): number;
12
+ /** The best candidate in the direction, or `null`. */
13
+ export declare function pickInDirection<T>(from: NiceRect, candidates: readonly T[], rect: (c: T) => NiceRect, d: NiceNavDirection): T | null;
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Gamepad family detection and the labels printed on the buttons (ADR-005 § 3).
3
+ */
4
+ import type { NiceGamepadButton, NiceGamepadButtonAlias, NiceGamepadFamily, NiceInputPreferences } from './types';
5
+ /**
6
+ * Family from `Gamepad.id`. Chrome writes `… (STANDARD GAMEPAD Vendor: 054c Product: 0ce6)`,
7
+ * Firefox `054c-0ce6-DualSense Wireless Controller`; Safari and XInput give a name only.
8
+ */
9
+ export declare function detectGamepadFamily(id: string): NiceGamepadFamily;
10
+ /** The position that confirms: south, or east on a Nintendo pad (A is on the right there). */
11
+ export declare function confirmButtonFor(family: NiceGamepadFamily | null, preference: NiceInputPreferences['confirmButton']): 'south' | 'east';
12
+ /** A position, or an Xbox name of one. */
13
+ export declare function toGamepadButton(button: NiceGamepadButton | NiceGamepadButtonAlias): NiceGamepadButton;
14
+ /** A button label: dictionary key and its English default. */
15
+ /**
16
+ * A button label. Proper names printed on pads (A, LB, L1, ZR, View) are the same in every
17
+ * language and have no `key`; words (Cross, Left bumper, D-pad up) carry their dictionary key.
18
+ */
19
+ export interface NiceButtonLabel {
20
+ label: string;
21
+ key?: string;
22
+ }
23
+ /** The label of a button on a pad of the family (translate it with `t(key, label)` when it has a key). */
24
+ export declare function gamepadButtonLabel(family: NiceGamepadFamily, button: NiceGamepadButton): NiceButtonLabel;
25
+ /**
26
+ * NiceIcon name of a button glyph (ADR-005 § 8): `pad-<family>-<label>` for the face buttons
27
+ * (`pad-xbox-a`, `pad-playstation-cross`, `pad-nintendo-b`, `pad-generic-south`), `pad-<button>`
28
+ * for the rest.
29
+ */
30
+ export declare function gamepadGlyphName(family: NiceGamepadFamily, button: NiceGamepadButton): string;
@@ -0,0 +1,57 @@
1
+ import type { NiceNavDirection, NiceGamepadButton, NiceGamepadInfo, NiceInputPreferences } from './types';
2
+ export interface NiceGamepadButtonChange {
3
+ pad: NiceGamepadInfo;
4
+ button: NiceGamepadButton;
5
+ pressed: boolean;
6
+ /** A repeat of a held button (d-pad, bumpers, triggers). */
7
+ repeat: boolean;
8
+ }
9
+ export interface NiceGamepadStickMove {
10
+ pad: NiceGamepadInfo;
11
+ direction: NiceNavDirection;
12
+ repeat: boolean;
13
+ }
14
+ export interface NiceGamepadScroll {
15
+ pad: NiceGamepadInfo;
16
+ /** Right stick past its dead zone, rescaled to 0–1 per axis (y down positive). */
17
+ x: number;
18
+ y: number;
19
+ }
20
+ export type NiceGamepadTiming = Pick<NiceInputPreferences, 'stickThreshold' | 'stickDeadzone' | 'repeatDelay' | 'repeatInterval' | 'repeatIntervalMin'>;
21
+ export interface NiceGamepadPollerOptions {
22
+ timing: () => NiceGamepadTiming;
23
+ onButton: (change: NiceGamepadButtonChange) => void;
24
+ onStick: (move: NiceGamepadStickMove) => void;
25
+ onScroll: (scroll: NiceGamepadScroll) => void;
26
+ onPadsChange?: (pads: NiceGamepadInfo[]) => void;
27
+ /** Every polled frame with the raw pads (games, device testers). */
28
+ onFrame?: (pads: readonly Gamepad[], now: number) => void;
29
+ }
30
+ export declare class NiceGamepadPoller {
31
+ private readonly win;
32
+ private readonly opts;
33
+ private readonly states;
34
+ private readonly connected;
35
+ private readonly warned;
36
+ private started;
37
+ private frameId;
38
+ constructor(win: Window, opts: NiceGamepadPollerOptions);
39
+ /** Whether an animation frame is scheduled (false without a pad or on a hidden page). */
40
+ get running(): boolean;
41
+ get pads(): NiceGamepadInfo[];
42
+ start(): void;
43
+ stop(): void;
44
+ /** Read every pad once; public so tests can drive a frame. */
45
+ poll(now: number): void;
46
+ private readButtons;
47
+ private readSticks;
48
+ private repeats;
49
+ private read;
50
+ private warnMapping;
51
+ private readonly onConnected;
52
+ private readonly onDisconnected;
53
+ private readonly onVisibility;
54
+ private readonly frame;
55
+ private schedule;
56
+ private cancel;
57
+ }
@@ -0,0 +1,33 @@
1
+ /**
2
+ * @nice2dev/ui-core/input — keyboard, gamepad and remote input for every Nice control (ADR-005,
3
+ * REQUIREMENTS § 6). Also re-exported from the main `@nice2dev/ui-core` entry.
4
+ */
5
+ export * from './types';
6
+ export { confirmButtonFor, detectGamepadFamily, gamepadButtonLabel, gamepadGlyphName, toGamepadButton, type NiceButtonLabel, } from './gamepadFamily';
7
+ export { chordMatches, gamepadIntentMap, intentFromKey, NICE_DEFAULT_GAMEPAD_BINDINGS, NICE_DEFAULT_KEYBOARD_BINDINGS, normalizeKey, parseKeyChord, remoteIntent, resolveGamepadBindings, resolveKeyboardBindings, type NiceIntentHit, type NiceKeyChord, } from './bindings';
8
+ export { NiceGamepadPoller, type NiceGamepadButtonChange, type NiceGamepadPollerOptions, type NiceGamepadScroll, type NiceGamepadStickMove, type NiceGamepadTiming, } from './gamepadPoller';
9
+ export { getInputEngine, NiceInputEngine, type NiceCapturedInput, type NiceGamepadFrameListener, type NiceInputState, type NiceOverlayEntry, type NiceTranslate, } from './engine';
10
+ export { clickElement, clickOnActivationKey, engageKindOf, isClickActivatable, isEngaged, type NiceActivationKeyEvent, } from './elements';
11
+ export { focusCandidates, isFocusCandidate, rectOf, type NiceRect } from './focus/candidates';
12
+ export { pickInDirection, spatialScore } from './focus/spatial';
13
+ export { applyFocusScope, readScope, type NiceArrowPolicy, type NiceFocusScopeOptions, type NiceScopeEnter, type NiceScopeInfo, type NiceScopeNav, } from './focus/scopes';
14
+ export { findFocusTarget, findRegionTarget, type NiceFocusMoveContext } from './focus/navigator';
15
+ export * from './react/NiceInputProvider';
16
+ export { useEngage, useFocusScope, useIntent, type UseEngageOptions, type UseIntentOptions, } from './react/hooks';
17
+ export * from './react/useOverlayFocus';
18
+ export * from './react/useRovingFocus';
19
+ export * from './react/useMenuButton';
20
+ export * from './react/useTreeFocus';
21
+ export * from './react/useGridFocus';
22
+ export * from './react/NiceFocusScope';
23
+ export { hintsForFocus, setInputHints, useFocusedElement, useInputHints, type NiceInputHint, } from './react/hints';
24
+ export { toAriaKeyShortcuts, triggerNiceAction, useNiceAction, useNiceActions, type NiceAction, } from './react/actions';
25
+ export { chordToString, isMacPlatform, keyFace, splitChord, type NiceKeyFace, } from './prompts/keys';
26
+ export * from './prompts/NiceKeyCap';
27
+ export * from './prompts/NiceButtonPrompt';
28
+ export * from './prompts/NiceInputHintBar';
29
+ export * from './prompts/NiceControlHint';
30
+ export * from './osk/layouts';
31
+ export * from './osk/editing';
32
+ export { isTextInput, restoresOnCancel, setFieldText } from './elements';
33
+ export { createTabEscape } from './tabEscape';
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Text editing of the on-screen keyboards (1.3.0 H1): what a key does to a text with a caret —
3
+ * type at the caret, delete before it, move it. Framework-free; the keyboards keep the state.
4
+ */
5
+ /** A text and the caret in it (0 … text.length). */
6
+ export interface NiceTextEdit {
7
+ text: string;
8
+ caret: number;
9
+ }
10
+ /** Types `chars` at the caret; `maxLength` stops a text from growing past it. */
11
+ export declare function insertAtCaret(edit: NiceTextEdit, chars: string, maxLength?: number): NiceTextEdit;
12
+ /** Deletes the character before the caret (Backspace). */
13
+ export declare function deleteBeforeCaret(edit: NiceTextEdit): NiceTextEdit;
14
+ /** Moves the caret by `by` characters, or to the start / end. */
15
+ export declare function moveTextCaret(edit: NiceTextEdit, by: number | 'start' | 'end'): NiceTextEdit;
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Keyboard layouts of the on-screen keyboards (1.3.0 H1, decision § 0.4): the core both
3
+ * `NiceOnScreenKeyboard` (`@nice2dev/ui`, typing with a pad or a remote) and `NiceTouchKeyboard`
4
+ * (`@nice2dev/ui-mobile`, touch) are built on. Letter rows per language, accents, the number,
5
+ * symbol and function rows, and the fixed numeric / numpad / phone / PIN pads. Framework-free.
6
+ */
7
+ /** Languages with a letter layout. */
8
+ export type NiceKeyboardLanguage = 'en' | 'pl' | 'de' | 'fr' | 'es' | 'it' | 'pt' | 'ru' | 'uk' | 'cs' | 'tr' | 'nl' | 'sv' | 'no' | 'da' | 'fi' | 'ro' | 'hr' | 'el' | 'hu' | 'sk' | 'bg' | 'sr' | 'ja' | 'ko' | 'zh' | 'ar' | 'he';
9
+ /** From minimal (numbers only) to full (function row, number row, letters, symbols). */
10
+ export type NiceKeyboardMode = 'minimal' | 'compact' | 'standard' | 'full';
11
+ export type NiceKeyboardKeyType = 'char' | 'space' | 'backspace' | 'enter' | 'shift' | 'special' | 'fn' | 'tab' | 'caps' | 'lang';
12
+ export interface NiceKeyboardKey {
13
+ value: string;
14
+ label?: string;
15
+ /** Relative width (flex grow), default 1. */
16
+ width?: number;
17
+ type?: NiceKeyboardKeyType;
18
+ }
19
+ export type NiceKeyboardRow = NiceKeyboardKey[];
20
+ export interface NiceKeyboardLanguageLayout {
21
+ code: NiceKeyboardLanguage;
22
+ name: string;
23
+ nativeName: string;
24
+ /** The three letter rows (QWERTY-like). */
25
+ rows: [string[], string[], string[]];
26
+ /** Accented letters per base letter (long press, accent row). */
27
+ accents?: Record<string, string[]>;
28
+ }
29
+ export declare const NICE_KEYBOARD_LAYOUTS: Readonly<Record<NiceKeyboardLanguage, NiceKeyboardLanguageLayout>>;
30
+ /** Whether a language reads right to left. */
31
+ export declare const isRtlKeyboardLanguage: (lang: NiceKeyboardLanguage) => boolean;
32
+ export declare const NICE_KEY_BACKSPACE: NiceKeyboardKey;
33
+ export declare const NICE_KEY_ENTER: NiceKeyboardKey;
34
+ export declare const NICE_KEY_SPACE: NiceKeyboardKey;
35
+ export declare const NICE_KEY_SHIFT: NiceKeyboardKey;
36
+ export declare const NICE_KEY_CAPS: NiceKeyboardKey;
37
+ export declare const NICE_KEY_TAB: NiceKeyboardKey;
38
+ export declare const NICE_KEYBOARD_NUMERIC: NiceKeyboardRow[];
39
+ export declare const NICE_KEYBOARD_NUMPAD: NiceKeyboardRow[];
40
+ export declare const NICE_KEYBOARD_PHONE: NiceKeyboardRow[];
41
+ export declare const NICE_KEYBOARD_PIN: NiceKeyboardRow[];
42
+ /**
43
+ * The rows of a language layout in a mode: letters (or the symbol layer), the bottom row with
44
+ * the layer switch, the language key, space and Enter; `full` adds the function and number rows
45
+ * and an accent row.
46
+ */
47
+ export declare function buildKeyboardRows(lang: NiceKeyboardLanguage, mode: NiceKeyboardMode, symbolMode: boolean, showLangSwitcher: boolean, enterLabel?: string): NiceKeyboardRow[];
@@ -0,0 +1,35 @@
1
+ /**
2
+ * NiceButtonPrompt — which button or key triggers an action, in the glyphs of the device in use
3
+ * (ADR-005 § 8): a pad button of the user's family (Xbox A, PlayStation Cross, Nintendo B), a
4
+ * keycap (`Enter`), a remote key. Follows the user's bindings when given an intent.
5
+ *
6
+ * ```tsx
7
+ * <NiceButtonPrompt intent="activate" label={t('input.intent.activate', 'Select')} />
8
+ * <NiceButtonPrompt button="RB" />
9
+ * ```
10
+ */
11
+ import React from 'react';
12
+ import type { NiceGamepadButton, NiceGamepadButtonAlias, NiceGamepadFamily, NiceIntent, NiceNavDirection } from '../types';
13
+ export type NicePromptDevice = 'auto' | 'keyboard' | 'gamepad' | 'remote';
14
+ export interface NiceButtonPromptProps {
15
+ /** The intent whose binding to show — follows the user's bindings. */
16
+ intent?: NiceIntent;
17
+ /** `navigate`: one direction (default: the whole d-pad / all arrows). */
18
+ direction?: NiceNavDirection;
19
+ /** A pad button instead of an intent (position, or its Xbox name). */
20
+ button?: NiceGamepadButton | NiceGamepadButtonAlias;
21
+ /** A key or chord instead of an intent (`'Ctrl+S'`). */
22
+ keys?: string;
23
+ /** The action, shown next to the glyph. */
24
+ label?: React.ReactNode;
25
+ /** Which device to show: the one in use (default) or a fixed one. */
26
+ device?: NicePromptDevice;
27
+ /** Glyph family (default: the preference, else the pad used last, else Xbox). */
28
+ family?: NiceGamepadFamily;
29
+ size?: 'sm' | 'md' | 'lg';
30
+ className?: string;
31
+ style?: React.CSSProperties;
32
+ }
33
+ export declare const NiceButtonPrompt: (({ intent, direction, button, keys, label, device, family, size, className, style, }: NiceButtonPromptProps) => React.JSX.Element | null) & {
34
+ displayName: string;
35
+ };
@@ -0,0 +1,21 @@
1
+ /**
2
+ * NiceControlHint — the button or key of an action shown next to a control (1.3.0 B5): the Y
3
+ * prompt on a "Search" button, LB / RB at the ends of tabs, LT / RT by a pager. Visible while hints are, and only
4
+ * when the user wants hints next to controls (preference `hintDensity`), unless `always`.
5
+ * Decorative (`aria-hidden`): `aria-keyshortcuts` and labels carry the same information.
6
+ */
7
+ import React from 'react';
8
+ import type { NiceGamepadButton, NiceGamepadButtonAlias, NiceIntent, NiceNavDirection } from '../types';
9
+ export interface NiceControlHintProps {
10
+ intent?: NiceIntent;
11
+ direction?: NiceNavDirection;
12
+ button?: NiceGamepadButton | NiceGamepadButtonAlias;
13
+ keys?: string;
14
+ /** Show whenever hints are visible, whatever the "next to controls" preference. */
15
+ always?: boolean;
16
+ size?: 'sm' | 'md' | 'lg';
17
+ className?: string;
18
+ }
19
+ export declare const NiceControlHint: (({ intent, direction, button, keys, always, size, className, }: NiceControlHintProps) => React.JSX.Element | null) & {
20
+ displayName: string;
21
+ };
@@ -0,0 +1,31 @@
1
+ /**
2
+ * NiceInputHintBar — a console-style bar of what the buttons do right now (ADR-005 § 8):
3
+ * "Ⓐ Select Ⓑ Back Ⓨ Search", in the glyphs of the device in use. It shows the hints published
4
+ * on the focus path (`useInputHints`, `useNiceAction`) and, unless turned off, the basic ones the
5
+ * focused element implies: move, select or edit, done, close. Hidden in pointer mode (preference),
6
+ * and from screen readers — `aria-keyshortcuts` and labels carry the same information.
7
+ */
8
+ import React from 'react';
9
+ import { type NiceInputHint } from '../react/hints';
10
+ export interface NiceInputHintBarProps {
11
+ /** Where the bar sits; the shell places it, this only picks the border side. */
12
+ position?: 'bottom' | 'top';
13
+ /**
14
+ * `auto` follows the hints preference and the input method (keyboard, pad, remote); `pad` the
15
+ * same for pads and remotes only (shells — keyboard users see it with the "always" preference);
16
+ * `always` shows it regardless.
17
+ */
18
+ visibility?: 'auto' | 'pad' | 'always';
19
+ /** Add the hints the focused element implies (default true). */
20
+ automatic?: boolean;
21
+ /** Hints shown in addition to the published ones. */
22
+ hints?: NiceInputHint[];
23
+ /** At most this many hints (default 6). */
24
+ max?: number;
25
+ size?: 'sm' | 'md' | 'lg';
26
+ className?: string;
27
+ style?: React.CSSProperties;
28
+ }
29
+ export declare const NiceInputHintBar: (({ position, visibility, automatic, hints, max, size, className, style, }: NiceInputHintBarProps) => React.JSX.Element | null) & {
30
+ displayName: string;
31
+ };