@nice2dev/ui-core 1.2.1 → 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 +484 -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 +25 -25
  8. package/dist/index.d.ts +1 -0
  9. package/dist/index.mjs +3655 -4412
  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,18 @@
1
+ /**
2
+ * NiceKeyCap — a key or a key combination drawn as keycaps (ADR-005 § 8): `Ctrl+K`, `Shift+F10`,
3
+ * `Enter`. Several keys separated by spaces are alternatives (`ArrowUp ArrowDown`). macOS shows
4
+ * ⌘ ⌥ ⇧ as glyphs; arrows are glyphs everywhere. Screen readers get the keys in words.
5
+ */
6
+ import React from 'react';
7
+ export interface NiceKeyCapProps {
8
+ /** A key or chord (`'Ctrl+K'`); space-separated keys are alternatives. */
9
+ keys: string;
10
+ size?: 'sm' | 'md' | 'lg';
11
+ /** Key symbols of a platform (default: the one the page runs on). */
12
+ platform?: 'auto' | 'mac' | 'other';
13
+ className?: string;
14
+ style?: React.CSSProperties;
15
+ }
16
+ export declare const NiceKeyCap: (({ keys, size, platform, className, style, }: NiceKeyCapProps) => React.JSX.Element) & {
17
+ displayName: string;
18
+ };
@@ -0,0 +1,23 @@
1
+ /**
2
+ * How keys show on a keycap (ADR-005 § 8): words are translated, arrows and the macOS modifiers
3
+ * are NiceIcon glyphs (never characters used as icons), everything else as typed.
4
+ */
5
+ import type { NiceKeyChord } from '../bindings';
6
+ export interface NiceKeyFace {
7
+ /** Text on the cap (translated with `textKey` when it has one). */
8
+ text?: string;
9
+ textKey?: string;
10
+ /** NiceIcon glyph instead of text. */
11
+ icon?: string;
12
+ /** What a screen reader says (translated with `spokenKey`). */
13
+ spoken: string;
14
+ spokenKey?: string;
15
+ }
16
+ /** Whether the page runs on macOS / iOS (keycaps show ⌘ ⌥ ⇧ there). */
17
+ export declare function isMacPlatform(): boolean;
18
+ /** `'Ctrl+Shift+F10'` → `['Ctrl', 'Shift', 'F10']` (a trailing `+` is the plus key). */
19
+ export declare function splitChord(chord: string): string[];
20
+ /** A parsed binding back to its written form, modifiers first. */
21
+ export declare function chordToString(chord: NiceKeyChord): string;
22
+ /** The face of one key on a cap. */
23
+ export declare function keyFace(key: string, mac: boolean): NiceKeyFace;
@@ -0,0 +1,14 @@
1
+ /**
2
+ * `<NiceFocusScope>` — an element that is a focus scope (ADR-005 § 5), for layouts that have no
3
+ * component of their own to call `useFocusScope` in.
4
+ */
5
+ import React from 'react';
6
+ import type { NiceFocusScopeOptions } from '../focus/scopes';
7
+ export interface NiceFocusScopeProps extends NiceFocusScopeOptions, Omit<React.HTMLAttributes<HTMLElement>, 'children'> {
8
+ /** Element to render (default `div`). */
9
+ as?: React.ElementType;
10
+ children?: React.ReactNode;
11
+ }
12
+ export declare const NiceFocusScope: React.ForwardRefExoticComponent<NiceFocusScopeProps & React.RefAttributes<HTMLElement>> & {
13
+ displayName: string;
14
+ };
@@ -0,0 +1,42 @@
1
+ /**
2
+ * React bindings of the input engine: the optional provider (preferences, translator, persistence
3
+ * in NiceUserPreferences) and the state hooks. The engine works without the provider — every hook
4
+ * starts it — with the default preferences.
5
+ */
6
+ import React from 'react';
7
+ import { type NiceInputEngine, type NiceInputState } from '../engine';
8
+ import { type NiceGamepadFamily, type NiceGamepadInfo, type NiceInputMethod, type NiceInputPreferences } from '../types';
9
+ /** The window's input engine (`null` during server rendering); started after mount. */
10
+ export declare function useInputEngine(): NiceInputEngine | null;
11
+ /** The whole input state (method, pad family, pads, preferences, hint visibility). */
12
+ export declare function useInputState(): NiceInputState;
13
+ /** The device used last: `pointer`, `touch`, `keyboard`, `gamepad` or `remote`. */
14
+ export declare function useInputMethod(): NiceInputMethod;
15
+ /** The family of the pad used last, or `null` before any pad. */
16
+ export declare function useGamepadFamily(): NiceGamepadFamily | null;
17
+ /** The connected pads (index, id, family, mapping), as the engine sees them. */
18
+ export declare function useConnectedGamepads(): readonly NiceGamepadInfo[];
19
+ /** Whether button and key hints should show now. */
20
+ export declare function useHintsVisible(): boolean;
21
+ /** Current preferences and their setter (persisted when a `NiceInputProvider` persists them). */
22
+ export declare function useInputPreferences(): [
23
+ NiceInputPreferences,
24
+ (prefs: Partial<NiceInputPreferences>) => void
25
+ ];
26
+ export interface NiceInputProviderProps {
27
+ /** Preferences the application fixes (they win over the user's). */
28
+ preferences?: Partial<NiceInputPreferences>;
29
+ /** The application's defaults, below what the user chose. */
30
+ defaultPreferences?: Partial<NiceInputPreferences>;
31
+ /** Every change made through `useInputPreferences` / `NiceInputSettings`. */
32
+ onPreferencesChange?: (prefs: NiceInputPreferences) => void;
33
+ /** Keep the user's choices in `NiceUserPreferences` when its provider is present (default true). */
34
+ persist?: boolean;
35
+ children?: React.ReactNode;
36
+ }
37
+ /**
38
+ * Configures the page's input engine: preferences, the translator of its announcements, and
39
+ * persistence of the user's choices. Optional — without it the engine runs with the defaults.
40
+ * One per application; a second one overrides the first.
41
+ */
42
+ export declare function NiceInputProvider({ preferences, defaultPreferences, onPreferencesChange, persist, children, }: NiceInputProviderProps): React.JSX.Element;
@@ -0,0 +1,48 @@
1
+ /**
2
+ * Application actions (ADR-005 § 8, REQUIREMENTS § 6.3.10): an app declares what it can do — a
3
+ * key, a pad intent, where it applies — and gets the bindings, the hint, the command palette entry
4
+ * and the conflict check without any device code.
5
+ *
6
+ * ```tsx
7
+ * useNiceAction({
8
+ * id: 'document.save', label: t('actions.save', 'Save'),
9
+ * keyboard: 'Ctrl+S', gamepad: 'tertiary', when: () => isDirty, onTrigger: save,
10
+ * });
11
+ * ```
12
+ */
13
+ import { type RefObject } from 'react';
14
+ import type { NiceInputSource, NiceIntent } from '../types';
15
+ export interface NiceAction {
16
+ /** Unique id (`'document.save'`). */
17
+ id: string;
18
+ /** The action in words (already translated). */
19
+ label: string;
20
+ /** A longer description for the command palette. */
21
+ description?: string;
22
+ /** Keyboard binding(s): `'Ctrl+S'`, or several (`['Ctrl+S', 'F2']`). */
23
+ keyboard?: string | readonly string[];
24
+ /** Pad (and remote) trigger: an intent, so it follows the user's bindings. */
25
+ gamepad?: NiceIntent;
26
+ /** `global` (default) — anywhere; `local` — while focus is inside `ref`. */
27
+ scope?: 'global' | 'local';
28
+ ref?: RefObject<Element | null>;
29
+ /** The action applies only while this returns true. */
30
+ when?: () => boolean;
31
+ onTrigger: (source: NiceInputSource) => void;
32
+ /** Show in the hint bar (default true, when it has a pad trigger). */
33
+ hint?: boolean;
34
+ /** Offer in the command palette (default true). */
35
+ palette?: boolean;
36
+ /** Group of the command palette. */
37
+ group?: string;
38
+ /** The element the shortcut activates — gets `aria-keyshortcuts`. */
39
+ shortcutTarget?: RefObject<Element | null>;
40
+ }
41
+ /** `'Ctrl+Shift+S'` → `'Control+Shift+S'` — the ARIA spelling of a shortcut. */
42
+ export declare function toAriaKeyShortcuts(chord: string): string;
43
+ /** Declares an application action; it lives as long as the component that declares it. */
44
+ export declare function useNiceAction(action: NiceAction): void;
45
+ /** Every declared action (for the command palette and the bindings screen). */
46
+ export declare function useNiceActions(): readonly NiceAction[];
47
+ /** Runs a declared action by id (the command palette); returns whether it ran. */
48
+ export declare function triggerNiceAction(id: string, source?: NiceInputSource): boolean;
@@ -0,0 +1,34 @@
1
+ /**
2
+ * Input hints (ADR-005 § 8): elements publish the actions they offer; the hint bar shows those
3
+ * on the focus path, the innermost first. Hints of an element apply while focus is inside it;
4
+ * hints without an element apply everywhere.
5
+ */
6
+ import { type RefObject } from 'react';
7
+ import type { NiceGamepadButton, NiceGamepadButtonAlias, NiceIntent, NiceNavDirection } from '../types';
8
+ export interface NiceInputHint {
9
+ intent: NiceIntent;
10
+ /** The action in words (already translated, or translated with `labelKey`). */
11
+ label: string;
12
+ labelKey?: string;
13
+ direction?: NiceNavDirection;
14
+ /** Show this pad button instead of the intent's binding. */
15
+ button?: NiceGamepadButton | NiceGamepadButtonAlias;
16
+ /** Show these keys instead of the intent's binding. */
17
+ keys?: string;
18
+ }
19
+ /** Publishes (or with `null` withdraws) the hints of an element, or of the page (`document`). */
20
+ export declare function setInputHints(target: EventTarget, hints: NiceInputHint[] | null): void;
21
+ /** The hints that apply with focus on `active`: innermost element first, the page's last. */
22
+ export declare function hintsForFocus(active: Element | null, doc: Document): NiceInputHint[];
23
+ /**
24
+ * Publishes the actions an element offers while focus is inside it (`ref`), or on the whole page
25
+ * (`ref` = `null`). The hint bar shows them in the glyphs of the device in use. Several hooks may
26
+ * publish on one element; `fallback` hints (a hook's defaults) come after the others and give way
27
+ * to a hint of the same intent.
28
+ */
29
+ export declare function useInputHints(ref: RefObject<Element | null> | null, hints: NiceInputHint[], options?: {
30
+ enabled?: boolean;
31
+ fallback?: boolean;
32
+ }): void;
33
+ /** Re-renders when focus moves or hints change; returns the focused element. */
34
+ export declare function useFocusedElement(): Element | null;
@@ -0,0 +1,52 @@
1
+ /**
2
+ * Element-level hooks of the input layer: intent handlers, focus scopes and engaging. Hooks that
3
+ * take a ref follow the element behind it (`useElementEffect`), so an element rendered later or
4
+ * conditionally is still bound.
5
+ */
6
+ import { useEffect, type RefObject } from 'react';
7
+ import { type NiceFocusScopeOptions } from '../focus/scopes';
8
+ import { type NiceEngageKind, type NiceIntent, type NiceIntentDetail } from '../types';
9
+ /** `useLayoutEffect` in the browser, `useEffect` on the server (no warning there). */
10
+ export declare const useIsomorphicLayoutEffect: typeof useEffect;
11
+ export interface UseIntentOptions {
12
+ /** Listen on this element (intents dispatched while focus is inside it); default: the document. */
13
+ ref?: RefObject<Element | null>;
14
+ enabled?: boolean;
15
+ }
16
+ /**
17
+ * Handles intents from any device. The handler consumes the intent — the engine stops, the key
18
+ * event is `preventDefault()`ed — unless it returns `false`, which lets the intent go on (to the
19
+ * next handler up the tree and then to the engine's default action: escalation at an edge).
20
+ *
21
+ * ```tsx
22
+ * useIntent(['sectionPrev', 'sectionNext'], (d) => selectTab(d.intent === 'sectionNext' ? +1 : -1), { ref });
23
+ * ```
24
+ */
25
+ export declare function useIntent(intents: NiceIntent | readonly NiceIntent[], handler: (detail: NiceIntentDetail, event: CustomEvent<NiceIntentDetail>) => boolean | void, options?: UseIntentOptions): void;
26
+ /**
27
+ * Makes the element a focus scope (ADR-005 § 5): its own navigation, wrapping, trap, entry rule,
28
+ * arrow policy and region name. Elements inside need no registration.
29
+ */
30
+ export declare function useFocusScope(ref: RefObject<HTMLElement | null>, options?: NiceFocusScopeOptions): void;
31
+ export interface UseEngageOptions {
32
+ /** How the control is engaged (default `value`). */
33
+ kind?: NiceEngageKind;
34
+ /** Not engage-first (the d-pad acts on the control at once). */
35
+ disabled?: boolean;
36
+ onEngage?: () => void;
37
+ /** `cancelled` when the user left with `back`. */
38
+ onRelease?: (cancelled: boolean) => void;
39
+ /**
40
+ * `back` puts the value from before back, as a number field does (R 6.3.4) — restore it in
41
+ * `onRelease(true)`. The hint bar then names `back` "Cancel" instead of "Done".
42
+ */
43
+ restoreOnCancel?: boolean;
44
+ }
45
+ /**
46
+ * Engage-first for a custom control (ADR-005 § 6): on a pad the d-pad moves focus past it until the
47
+ * user presses confirm; then the d-pad reaches its key handler, and back releases it. Native value
48
+ * inputs, `role="slider"`, `role="spinbutton"` and `role="combobox"` are engage-first without it.
49
+ */
50
+ export declare function useEngage(ref: RefObject<HTMLElement | null>, options?: UseEngageOptions): {
51
+ engaged: boolean;
52
+ };
@@ -0,0 +1,7 @@
1
+ /**
2
+ * An effect bound to the element behind a ref: it runs when the element appears or is replaced
3
+ * (a conditionally rendered tab strip, a popup), and when the dependencies change — not only on
4
+ * mount, as an effect keyed by the ref object would.
5
+ */
6
+ import { type DependencyList, type RefObject } from 'react';
7
+ export declare function useElementEffect<T extends Element>(ref: RefObject<T | null> | null | undefined, effect: (el: T) => void | (() => void), deps: DependencyList): void;
@@ -0,0 +1,26 @@
1
+ /**
2
+ * Data grid (WAI-ARIA APG, 1.3.0 C10): the grid is one tab stop; the arrows move between cells by
3
+ * row and column, Home / End to the first / last cell of the row, Ctrl+Home / Ctrl+End to the
4
+ * first / last cell of the grid, PageUp / PageDown by `pageSize` rows. A cell holding exactly
5
+ * one control (a button, a checkbox, a link) is reached on that control, which keeps its own
6
+ * Enter / Space; on any other cell Enter, Space and a pad's A click the cell, where the
7
+ * components keep their click handlers.
8
+ *
9
+ * Rows are `[role="row"]` or `<tr>` elements of this grid, cells their `gridcell` /
10
+ * `columnheader` / `rowheader` children (`<td>` / `<th>` of a table with `role="grid"`). At the
11
+ * edges the key is not consumed, so the engine moves focus out of the grid spatially. Arrows in a
12
+ * text field inside a cell stay the field's.
13
+ */
14
+ import { type RefObject } from 'react';
15
+ export interface UseGridFocusOptions {
16
+ /** The grid's rows (default `[role="row"]` and `<tr>`). */
17
+ rowSelector?: string;
18
+ /** The cells of a row, among its children (default the grid cell roles, `<td>` and `<th>`). */
19
+ cellSelector?: string;
20
+ /** PageUp / PageDown move this many rows (default 10). */
21
+ pageSize?: number;
22
+ /** Called when a key moves focus to a cell (selection follows focus). */
23
+ onMove?: (cell: HTMLElement, row: number, column: number) => void;
24
+ enabled?: boolean;
25
+ }
26
+ export declare function useGridFocus(ref: RefObject<HTMLElement | null>, options?: UseGridFocusOptions): void;
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Menu button (WAI-ARIA APG, 1.3.0 C7): a trigger that opens a menu. On the trigger ↓ opens the
3
+ * menu on its first item and ↑ on its last (Enter / Space / A click it as the component already
4
+ * handles); in the menu ↑ ↓ Home End and letters move (`useRovingFocus`), Escape / B close it and
5
+ * focus returns to the trigger (`useOverlayFocus`), and moving focus out of both — or pressing
6
+ * the pointer outside them — closes it.
7
+ *
8
+ * Pads keep the d-pad for moving past the trigger: only the keyboard's arrows open the menu.
9
+ * The component keeps its own open state, `aria-haspopup` / `aria-expanded` and click handling.
10
+ */
11
+ import { type RefObject } from 'react';
12
+ import { type NiceRovingOrientation } from './useRovingFocus';
13
+ export interface UseMenuButtonOptions {
14
+ /** Whether the menu is shown. */
15
+ open: boolean;
16
+ /** Asks the component to open or close the menu. */
17
+ onOpenChange: (open: boolean) => void;
18
+ /** Arrows inside the menu (default `vertical`). */
19
+ orientation?: NiceRovingOrientation;
20
+ /** The menu's items (default: the ARIA item roles). */
21
+ itemSelector?: string;
22
+ /** Letters jump to the item starting with them (default true). */
23
+ typeahead?: boolean;
24
+ /** Close when focus leaves the trigger and the menu (default true). */
25
+ closeOnFocusOut?: boolean;
26
+ /** Close on a pointer press outside the trigger and the menu (default true). */
27
+ closeOnOutsidePress?: boolean;
28
+ }
29
+ export declare function useMenuButton(triggerRef: RefObject<HTMLElement | null>, menuRef: RefObject<HTMLElement | null>, options: UseMenuButtonOptions): void;
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Focus in overlays (ADR-005 § 7, REQUIREMENTS § 6.3.6): focus moves in when the overlay opens, a
3
+ * modal keeps Tab and directional moves inside, the overlay stack makes Escape / B / remote Back
4
+ * close only the top one, and on close focus returns to the element that opened it. An overlay
5
+ * that can be closed publishes the "B Close" hint.
6
+ */
7
+ import { type RefObject } from 'react';
8
+ import type { NiceInputSource } from '../types';
9
+ export interface UseOverlayFocusOptions {
10
+ /** Whether the overlay is shown. */
11
+ open: boolean;
12
+ /** Keep focus inside (default true). */
13
+ modal?: boolean;
14
+ /**
15
+ * Where focus goes on open: an element, a selector inside the overlay, `'container'` (the
16
+ * overlay itself), `'first'` (default — the first focusable element, else the container) or
17
+ * `'none'` — focus stays where it is (a select's list, driven from its trigger).
18
+ */
19
+ initialFocus?: RefObject<HTMLElement | null> | string;
20
+ /** Return focus to the opener on close (default true). */
21
+ restoreFocus?: boolean;
22
+ /** Close request from Escape, B or remote Back. Without it the overlay cannot be dismissed. */
23
+ onClose?: (source: NiceInputSource) => void;
24
+ /** Close on Escape / B (default true when `onClose` is given). */
25
+ closeOnEscape?: boolean;
26
+ /**
27
+ * The words of the "close" hint the overlay publishes while it can be closed (default "Close");
28
+ * `false` publishes none. A hint of the `back` intent published by the component wins.
29
+ */
30
+ closeHint?: string | false;
31
+ }
32
+ /** Focus management of an overlay; attach `ref` to the overlay's root element. */
33
+ export declare function useOverlayFocus(ref: RefObject<HTMLElement | null>, options: UseOverlayFocusOptions): void;
@@ -0,0 +1,46 @@
1
+ /**
2
+ * Roving focus (WAI-ARIA APG, ADR-005 § 9): one item of a composite carries `tabindex="0"`, the
3
+ * others `-1`, and the arrow keys move between them — linearly (tabs, toolbars, menus, lists,
4
+ * radio groups) or in two dimensions by geometry (icon grids, calendars, galleries). Home / End,
5
+ * PageUp / PageDown and typeahead are options.
6
+ *
7
+ * At an edge without wrapping the key is **not** consumed, so the engine moves focus out of the
8
+ * composite spatially (escalation). The hook works on the DOM: items need no props, and pads get
9
+ * the same behaviour through the engine's key emulation.
10
+ */
11
+ import { type RefObject } from 'react';
12
+ export type NiceRovingOrientation = 'horizontal' | 'vertical' | 'both' | 'grid';
13
+ export interface UseRovingFocusOptions {
14
+ /** Which arrows move (default `horizontal`); `grid` moves in 2-D by geometry. */
15
+ orientation?: NiceRovingOrientation;
16
+ /** Items of the composite (default: the ARIA item roles and `[data-nice-roving-item]`). */
17
+ itemSelector?: string;
18
+ /** From the last item to the first and back (default false — escalate instead). */
19
+ wrap?: boolean;
20
+ /** Home / End to the first / last item (default true). */
21
+ homeEnd?: boolean;
22
+ /** PageUp / PageDown move this many items (default 0 — off). */
23
+ pageSize?: number;
24
+ /** Typing letters jumps to the next item starting with them (default false). */
25
+ typeahead?: boolean;
26
+ /** Skip `disabled` / `aria-disabled` items (default true). */
27
+ skipDisabled?: boolean;
28
+ /** Called when a key moves to an item (automatic tab activation, selection follows focus). */
29
+ onMove?: (item: HTMLElement, index: number) => void;
30
+ /**
31
+ * Activate the item a key moves to by clicking it — or its first button or link, for items that
32
+ * wrap one (automatic tab activation without an `onMove`).
33
+ */
34
+ activateOnMove?: boolean;
35
+ enabled?: boolean;
36
+ }
37
+ export declare const NICE_ROVING_ITEMS: string;
38
+ export interface RovingFocusControls {
39
+ /** The items in document order. */
40
+ items: () => HTMLElement[];
41
+ /** Moves the roving stop to an item and focuses it. */
42
+ focusItem: (index: number) => void;
43
+ /** Re-reads the items (after a change the observer cannot see). */
44
+ refresh: () => void;
45
+ }
46
+ export declare function useRovingFocus(ref: RefObject<HTMLElement | null>, options?: UseRovingFocusOptions): RovingFocusControls;
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Tree view (WAI-ARIA APG, 1.3.0 C9): the tree is one tab stop; ↑ ↓ move between the visible
3
+ * items, → opens a closed item or moves to its first child, ← closes an open item or moves to its
4
+ * parent, Home / End go to the first / last visible item, `*` opens the item's closed siblings and
5
+ * letters jump to the next item starting with them. Enter, Space and a pad's A activate the item.
6
+ *
7
+ * The component keeps the open state and draws `aria-expanded` on `[role="treeitem"]` elements
8
+ * whose children sit in a nested `[role="group"]` — or, in a flat tree, follow them in the DOM
9
+ * with an `aria-level` one deeper; `onToggle` asks it to open or close one. When
10
+ * the click handler sits on a row inside the item (`rowSelector`), a click on the item itself — a
11
+ * pad's A, Enter, Space — is passed to the row, and so is its context menu (a pad's X,
12
+ * Shift+F10). At the first / last item and on a root leaf the key is not consumed, so the engine
13
+ * moves focus out of the tree spatially, as at the edge of any composite.
14
+ */
15
+ import { type RefObject } from 'react';
16
+ export interface UseTreeFocusOptions {
17
+ /** Open (`true`) or close (`false`) an item — the component keeps the state. */
18
+ onToggle: (item: HTMLElement, open: boolean) => void;
19
+ /** The tree's items (default `[role="treeitem"]`). */
20
+ itemSelector?: string;
21
+ /**
22
+ * The element of an item — outside its children — that holds its click and context-menu
23
+ * handlers (its row, or the row's label button). Without it the item itself is clicked.
24
+ */
25
+ rowSelector?: string;
26
+ /** Letters jump to the next visible item starting with them (default true). */
27
+ typeahead?: boolean;
28
+ enabled?: boolean;
29
+ }
30
+ export declare function useTreeFocus(ref: RefObject<HTMLElement | null>, options: UseTreeFocusOptions): void;
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Tab in an editor that indents with it must still let the keyboard out (WCAG 2.1.2, no
3
+ * keyboard trap; TODO_1.3.0 I4 found three that did not). The convention of CodeMirror and of
4
+ * GitHub's editors: Escape, then Tab (or Shift+Tab), moves focus on as usual.
5
+ */
6
+ /**
7
+ * A tracker fed with every keydown of one editor. It answers `true` for the Tab that follows an
8
+ * Escape: let that one through to the browser — no `preventDefault`, no indent.
9
+ *
10
+ * ```tsx
11
+ * const [tabEscape] = useState(createTabEscape);
12
+ * const onKeyDown = (e: React.KeyboardEvent) => {
13
+ * if (tabEscape(e)) return; // Escape, then Tab: focus moves on
14
+ * if (e.key === 'Tab') { e.preventDefault(); indent(e.shiftKey); }
15
+ * };
16
+ * ```
17
+ */
18
+ export declare function createTabEscape(): (e: {
19
+ key: string;
20
+ }) => boolean;
@@ -0,0 +1,98 @@
1
+ /**
2
+ * Input layer — public types (ADR-005, REQUIREMENTS § 6.3).
3
+ *
4
+ * Framework-free: nothing here imports React, so the adapters can use the same engine.
5
+ */
6
+ /** What an input means, independent of the device that produced it. */
7
+ export type NiceIntent = 'navigate' | 'activate' | 'back' | 'secondary' | 'tertiary' | 'menu' | 'view' | 'sectionPrev' | 'sectionNext' | 'pagePrev' | 'pageNext' | 'first' | 'last' | 'scroll' | 'toggleHints';
8
+ /** Every intent, in the order the binding screens list them. */
9
+ export declare const NICE_INTENTS: readonly NiceIntent[];
10
+ export type NiceNavDirection = 'up' | 'down' | 'left' | 'right';
11
+ /** The device used last; drives focus visibility, glyphs and hover behaviour. */
12
+ export type NiceInputMethod = 'pointer' | 'touch' | 'keyboard' | 'gamepad' | 'remote';
13
+ /** Where an intent came from. */
14
+ export type NiceInputSource = 'keyboard' | 'gamepad' | 'remote';
15
+ /** Decides the glyphs and the default confirm button. */
16
+ export type NiceGamepadFamily = 'xbox' | 'playstation' | 'nintendo' | 'steam' | 'generic';
17
+ /**
18
+ * Gamepad buttons by **position** — indices 0–16 of the W3C standard mapping. The label printed on
19
+ * the button depends on the family (south is A on Xbox, Cross on PlayStation, B on Nintendo).
20
+ */
21
+ export type NiceGamepadButton = 'south' | 'east' | 'west' | 'north' | 'leftBumper' | 'rightBumper' | 'leftTrigger' | 'rightTrigger' | 'select' | 'start' | 'leftStick' | 'rightStick' | 'dpadUp' | 'dpadDown' | 'dpadLeft' | 'dpadRight' | 'home';
22
+ /** Xbox button names, accepted wherever a position is expected (A = south, B = east, …). */
23
+ export type NiceGamepadButtonAlias = 'A' | 'B' | 'X' | 'Y' | 'LB' | 'RB' | 'LT' | 'RT' | 'View' | 'Menu' | 'LS' | 'RS';
24
+ /** Standard-mapping index → position. */
25
+ export declare const NICE_GAMEPAD_BUTTONS: readonly NiceGamepadButton[];
26
+ export interface NiceGamepadInfo {
27
+ /** `Gamepad.index` */
28
+ index: number;
29
+ /** `Gamepad.id` */
30
+ id: string;
31
+ family: NiceGamepadFamily;
32
+ /** `Gamepad.mapping` — `'standard'` for pads the browser maps to the standard layout. */
33
+ mapping: string;
34
+ }
35
+ /** `detail` of the `nice-intent` DOM event. */
36
+ export interface NiceIntentDetail {
37
+ intent: NiceIntent;
38
+ /** `navigate`, `scroll` and `view` (next region = `down`, previous = `up`). */
39
+ direction?: NiceNavDirection;
40
+ /** `scroll`: how far the stick is pushed, 0–1. */
41
+ amount?: number;
42
+ source: NiceInputSource;
43
+ /** An automatic repeat of a held key, button or stick. */
44
+ repeat: boolean;
45
+ /** The pad, for gamepad intents. */
46
+ gamepad?: NiceGamepadInfo;
47
+ /** The key event behind a keyboard or remote intent. */
48
+ keyEvent?: KeyboardEvent;
49
+ }
50
+ /** Name of the DOM event the engine dispatches on the focused element. */
51
+ export declare const NICE_INTENT_EVENT = "nice-intent";
52
+ /** Name of the DOM event fired on an element when it is engaged or released (ADR-005 § 6). */
53
+ export declare const NICE_ENGAGE_EVENT = "nice-engagechange";
54
+ export interface NiceEngageDetail {
55
+ engaged: boolean;
56
+ /** Released with `back` (cancel) rather than confirmed. */
57
+ cancelled: boolean;
58
+ source: NiceInputSource;
59
+ }
60
+ /** How a control has to be engaged before the d-pad changes it (ADR-005 § 6). */
61
+ export type NiceEngageKind = 'value' | 'text' | 'popup' | 'canvas';
62
+ /** A key event the engine synthesized for a gamepad or remote intent. */
63
+ export interface NiceEmulatedKeyboardEvent extends KeyboardEvent {
64
+ readonly niceSource: NiceInputSource;
65
+ }
66
+ /** User preferences of the input layer (persisted in NiceUserPreferences when present). */
67
+ export interface NiceInputPreferences {
68
+ /** `auto` — south, or east on a Nintendo pad. */
69
+ confirmButton: 'auto' | 'south' | 'east';
70
+ /** Gamepad buttons per intent, replacing the defaults of that intent. */
71
+ gamepadBindings: Partial<Record<NiceIntent, NiceGamepadButton[]>>;
72
+ /** Keys per intent (`'Ctrl+K'`, `'Shift+F10'`), replacing the defaults of that intent. */
73
+ keyboardBindings: Partial<Record<NiceIntent, string[]>>;
74
+ /** Left stick: how far it has to be pushed to move focus (0.2–0.9). */
75
+ stickThreshold: number;
76
+ /** Right stick: dead zone of scrolling (0–0.5). */
77
+ stickDeadzone: number;
78
+ /** Scroll the other way with the right stick. */
79
+ invertScroll: boolean;
80
+ /** Hold time before a held direction repeats, in ms. */
81
+ repeatDelay: number;
82
+ /** First repeat interval in ms; repeats speed up from here. */
83
+ repeatInterval: number;
84
+ /** Fastest repeat interval in ms. */
85
+ repeatIntervalMin: number;
86
+ /** The hint bar: in keyboard / pad modes only, always, or never. */
87
+ hints: 'auto' | 'always' | 'never';
88
+ /** Hints in the bar only, or next to the controls too. */
89
+ hintDensity: 'bar' | 'bar-and-controls';
90
+ /** Glyph family of the prompts: the pad in use, or a chosen one. */
91
+ glyphFamily: 'auto' | NiceGamepadFamily;
92
+ vibration: boolean;
93
+ /** Unhandled arrow keys outside composite controls: by region (`auto`), always spatial, never. */
94
+ arrowNavigation: 'auto' | 'spatial' | 'native';
95
+ /** On-screen keyboard for text fields in pad mode. */
96
+ onScreenKeyboard: 'auto' | 'always' | 'never';
97
+ }
98
+ export declare const NICE_INPUT_DEFAULTS: NiceInputPreferences;