@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
@@ -1,4 +1,5 @@
1
1
  import React from 'react';
2
+ import type { NiceIntent, NiceNavDirection } from '../input/types';
2
3
  export interface NiceA11yConfig {
3
4
  /** Announce state changes to screen readers (default: true) */
4
5
  announceChanges: boolean;
@@ -52,6 +53,10 @@ export interface UseRovingTabIndexOptions {
52
53
  *
53
54
  * Only one item has tabIndex=0 (the active one); others have tabIndex=-1.
54
55
  * Arrow keys move focus between items.
56
+ *
57
+ * @deprecated since 1.3.0 — use `useRovingFocus` (ADR-005): it moves in two dimensions in a
58
+ * `grid` (this hook moved linearly there), has typeahead and PageUp / PageDown, and hands focus on
59
+ * at an edge instead of swallowing the key. This hook is now a layer over it.
55
60
  */
56
61
  export declare function useRovingTabIndex(containerRef: React.RefObject<HTMLElement | null>, options: UseRovingTabIndexOptions): void;
57
62
  /** Return focus to the element that was focused before the component mounted */
@@ -64,7 +69,7 @@ export declare const NiceVisuallyHidden: React.FC<{
64
69
  export interface NiceSkipLinkProps {
65
70
  /** Target element id (without #) */
66
71
  targetId: string;
67
- /** Link text (default: 'Skip to main content') */
72
+ /** Link text (default: 'Skip to main content', translated) */
68
73
  children?: React.ReactNode;
69
74
  }
70
75
  export declare const NiceSkipLink: React.FC<NiceSkipLinkProps>;
@@ -77,16 +82,25 @@ export interface KeyboardShortcut {
77
82
  /** i18n key for the description */
78
83
  descriptionKey?: string;
79
84
  /** Modifier keys required */
80
- modifiers?: ('ctrl' | 'alt' | 'shift' | 'meta')[];
85
+ modifiers?: readonly ('ctrl' | 'alt' | 'shift' | 'meta')[];
86
+ /**
87
+ * The same action as an intent (1.3.0): `NiceKeyboardHint` shows the pad button bound to it
88
+ * when a pad is in use.
89
+ */
90
+ intent?: NiceIntent;
91
+ /** Direction of a `navigate` intent. */
92
+ direction?: NiceNavDirection;
81
93
  }
82
94
  /** Common keyboard shortcuts used across controls */
83
95
  export declare const COMMON_SHORTCUTS: {
84
96
  readonly submit: {
97
+ readonly intent: "activate";
85
98
  readonly key: "Enter";
86
99
  readonly description: "Submit / Confirm";
87
100
  readonly descriptionKey: "shortcuts.submit";
88
101
  };
89
102
  readonly cancel: {
103
+ readonly intent: "back";
90
104
  readonly key: "Escape";
91
105
  readonly description: "Cancel / Close";
92
106
  readonly descriptionKey: "shortcuts.cancel";
@@ -98,41 +112,53 @@ export declare const COMMON_SHORTCUTS: {
98
112
  readonly modifiers: readonly ["ctrl"];
99
113
  };
100
114
  readonly moveUp: {
115
+ readonly intent: "navigate";
116
+ readonly direction: "up";
101
117
  readonly key: "ArrowUp";
102
118
  readonly description: "Move up";
103
119
  readonly descriptionKey: "shortcuts.moveUp";
104
120
  };
105
121
  readonly moveDown: {
122
+ readonly intent: "navigate";
123
+ readonly direction: "down";
106
124
  readonly key: "ArrowDown";
107
125
  readonly description: "Move down";
108
126
  readonly descriptionKey: "shortcuts.moveDown";
109
127
  };
110
128
  readonly moveLeft: {
129
+ readonly intent: "navigate";
130
+ readonly direction: "left";
111
131
  readonly key: "ArrowLeft";
112
132
  readonly description: "Move left";
113
133
  readonly descriptionKey: "shortcuts.moveLeft";
114
134
  };
115
135
  readonly moveRight: {
136
+ readonly intent: "navigate";
137
+ readonly direction: "right";
116
138
  readonly key: "ArrowRight";
117
139
  readonly description: "Move right";
118
140
  readonly descriptionKey: "shortcuts.moveRight";
119
141
  };
120
142
  readonly first: {
143
+ readonly intent: "first";
121
144
  readonly key: "Home";
122
145
  readonly description: "Go to first";
123
146
  readonly descriptionKey: "shortcuts.first";
124
147
  };
125
148
  readonly last: {
149
+ readonly intent: "last";
126
150
  readonly key: "End";
127
151
  readonly description: "Go to last";
128
152
  readonly descriptionKey: "shortcuts.last";
129
153
  };
130
154
  readonly pageUp: {
155
+ readonly intent: "pagePrev";
131
156
  readonly key: "PageUp";
132
157
  readonly description: "Page up";
133
158
  readonly descriptionKey: "shortcuts.pageUp";
134
159
  };
135
160
  readonly pageDown: {
161
+ readonly intent: "pageNext";
136
162
  readonly key: "PageDown";
137
163
  readonly description: "Page down";
138
164
  readonly descriptionKey: "shortcuts.pageDown";
@@ -144,6 +170,7 @@ export declare const COMMON_SHORTCUTS: {
144
170
  readonly modifiers: readonly ["ctrl"];
145
171
  };
146
172
  readonly toggleSelect: {
173
+ readonly intent: "activate";
147
174
  readonly key: "Space";
148
175
  readonly description: "Toggle selection";
149
176
  readonly descriptionKey: "shortcuts.toggleSelect";
@@ -179,6 +206,7 @@ export declare const COMMON_SHORTCUTS: {
179
206
  readonly modifiers: readonly ["ctrl"];
180
207
  };
181
208
  readonly edit: {
209
+ readonly intent: "activate";
182
210
  readonly key: "Enter";
183
211
  readonly description: "Edit cell";
184
212
  readonly descriptionKey: "shortcuts.edit";
@@ -195,31 +223,39 @@ export declare const COMMON_SHORTCUTS: {
195
223
  readonly modifiers: readonly ["shift"];
196
224
  };
197
225
  readonly open: {
226
+ readonly intent: "activate";
198
227
  readonly key: "ArrowDown";
199
228
  readonly description: "Open dropdown";
200
229
  readonly descriptionKey: "shortcuts.open";
201
230
  };
202
231
  readonly close: {
232
+ readonly intent: "back";
203
233
  readonly key: "Escape";
204
234
  readonly description: "Close popup";
205
235
  readonly descriptionKey: "shortcuts.close";
206
236
  };
207
237
  readonly increment: {
238
+ readonly intent: "navigate";
239
+ readonly direction: "up";
208
240
  readonly key: "ArrowUp";
209
241
  readonly description: "Increase value";
210
242
  readonly descriptionKey: "shortcuts.increment";
211
243
  };
212
244
  readonly decrement: {
245
+ readonly intent: "navigate";
246
+ readonly direction: "down";
213
247
  readonly key: "ArrowDown";
214
248
  readonly description: "Decrease value";
215
249
  readonly descriptionKey: "shortcuts.decrement";
216
250
  };
217
251
  readonly incrementBig: {
252
+ readonly intent: "sectionNext";
218
253
  readonly key: "PageUp";
219
254
  readonly description: "Increase by 10";
220
255
  readonly descriptionKey: "shortcuts.incrementBig";
221
256
  };
222
257
  readonly decrementBig: {
258
+ readonly intent: "sectionPrev";
223
259
  readonly key: "PageDown";
224
260
  readonly description: "Decrease by 10";
225
261
  readonly descriptionKey: "shortcuts.decrementBig";
@@ -234,7 +270,7 @@ export interface NiceKeyboardHintProps {
234
270
  shortcuts?: KeyboardShortcut[];
235
271
  /** Position of the tooltip */
236
272
  position?: 'top' | 'bottom' | 'left' | 'right';
237
- /** Custom trigger icon (default: ?) */
273
+ /** Custom trigger icon (default: the `keyboard` NiceIcon) */
238
274
  icon?: React.ReactNode;
239
275
  /** Size of the hint trigger */
240
276
  size?: 'sm' | 'md';
@@ -242,8 +278,9 @@ export interface NiceKeyboardHintProps {
242
278
  className?: string;
243
279
  }
244
280
  /**
245
- * A small question mark icon that shows keyboard shortcuts on hover.
246
- * Use this to inform users about available keyboard interactions.
281
+ * A small keyboard icon that shows keyboard shortcuts on hover and on focus — it is reachable with
282
+ * Tab (1.3.0). Keys are drawn as keycaps; while a pad is in use, shortcuts with an `intent` show
283
+ * the pad button bound to it.
247
284
  */
248
285
  export declare const NiceKeyboardHint: React.FC<NiceKeyboardHintProps>;
249
286
  export interface UseSubmitOnEnterOptions {
@@ -54,6 +54,10 @@ export declare function useClickOutside(ref: React.RefObject<HTMLElement | null>
54
54
  * Traps keyboard focus within the referenced container while `active` is `true`.
55
55
  * On activation the first focusable element receives focus.
56
56
  * `Tab` / `Shift+Tab` cycle through focusable children without leaving the container.
57
+ *
58
+ * Since 1.3.0 a modal {@link useOverlayFocus} without a close request: the trap also holds the
59
+ * d-pad, sees elements added after it opened, takes part in the overlay stack and returns focus
60
+ * to the opener. Overlays that close on Escape / B should call `useOverlayFocus` with `onClose`.
57
61
  * @param ref - Container element ref.
58
62
  * @param active - Enable/disable the trap.
59
63
  */
@@ -3,12 +3,16 @@
3
3
  *
4
4
  * Headless mechanism (lives in ui-core so any package can use it): a provider
5
5
  * tracks registered focusable elements and moves focus by direction using a
6
- * dot-product gate + nearest-by-distance heuristic. Inputs: keyboard arrows
7
- * (+ Enter to activate, Escape to dismiss a focus trap) and a gamepad d-pad /
8
- * left-stick (A = activate, B = dismiss trap) via {@link useGamepad}.
6
+ * dot-product gate + nearest-by-distance heuristic. Inputs: the `navigate`,
7
+ * `activate` and `back` intents of the input engine — arrow keys, Enter / Space,
8
+ * Escape, the d-pad, the left stick, A and B.
9
9
  *
10
10
  * Wrap a subtree in `NiceSpatialNavProvider`; register controls with
11
11
  * `useSpatialFocusable(ref, { id })` or the `<NiceFocusable>` wrapper.
12
+ *
13
+ * Since 1.3.0 the input engine (ADR-005) moves focus between every focusable element without
14
+ * registration, and this provider is a layer over it: it no longer listens to `window` keydown
15
+ * (so it leaves the arrow keys of text fields alone) and no longer polls a pad of its own.
12
16
  */
13
17
  import React from 'react';
14
18
  import type { NiceBaseProps } from './types';
@@ -38,16 +42,30 @@ export interface NiceSpatialNavContextValue {
38
42
  export interface NiceSpatialNavProviderProps extends NiceBaseProps {
39
43
  /** Handle keyboard arrow keys (default true). */
40
44
  keyboard?: boolean;
41
- /** Poll a gamepad for navigation (default true). */
45
+ /** Handle gamepad input (default true). */
42
46
  gamepad?: boolean;
43
- /** Gamepad index forwarded to useGamepad (default 0). */
47
+ /**
48
+ * Gamepad index (default 0).
49
+ * @deprecated since 1.3.0 — the input engine reads every pad; the one used last drives focus.
50
+ */
44
51
  gamepadIndex?: number;
45
52
  children: React.ReactNode;
46
53
  }
54
+ /**
55
+ * @deprecated since 1.3.0 — the input engine moves focus between all focusable elements without
56
+ * registration (ADR-005); group elements with `useFocusScope` / `<NiceFocusScope>` and trap them
57
+ * in overlays with `useOverlayFocus`. This provider keeps working as a layer over the engine.
58
+ */
47
59
  export declare const NiceSpatialNavProvider: React.FC<NiceSpatialNavProviderProps>;
48
- /** Access the spatial-nav context. Returns `null` outside a provider. */
60
+ /**
61
+ * Access the spatial-nav context. Returns `null` outside a provider.
62
+ * @deprecated since 1.3.0 — see {@link NiceSpatialNavProvider}.
63
+ */
49
64
  export declare function useSpatialNavOptional(): NiceSpatialNavContextValue | null;
50
- /** Access the spatial-nav context. Throws outside a provider. */
65
+ /**
66
+ * Access the spatial-nav context. Throws outside a provider.
67
+ * @deprecated since 1.3.0 — see {@link NiceSpatialNavProvider}.
68
+ */
51
69
  export declare function useSpatialNav(): NiceSpatialNavContextValue;
52
70
  export interface UseSpatialFocusableOptions {
53
71
  id: string;
@@ -58,6 +76,8 @@ export interface UseSpatialFocusableOptions {
58
76
  * Register `ref`'s element as a spatial-nav focusable. No-op (returns
59
77
  * `{ active: false }`) when used outside a provider. Sets `data-active` on the
60
78
  * element while it is the active focusable.
79
+ *
80
+ * @deprecated since 1.3.0 — focusable elements need no registration with the input engine.
61
81
  */
62
82
  export declare function useSpatialFocusable(ref: React.RefObject<HTMLElement | null>, opts: UseSpatialFocusableOptions): {
63
83
  active: boolean;
@@ -70,5 +90,8 @@ export interface NiceFocusableProps extends NiceBaseProps {
70
90
  as?: React.ElementType;
71
91
  children: React.ReactNode;
72
92
  }
73
- /** Thin wrapper that registers its element with the spatial-nav provider. */
93
+ /**
94
+ * Thin wrapper that registers its element with the spatial-nav provider.
95
+ * @deprecated since 1.3.0 — any focusable element takes part in directional navigation.
96
+ */
74
97
  export declare const NiceFocusable: React.FC<NiceFocusableProps>;
@@ -3,9 +3,12 @@
3
3
  *
4
4
  * Supports Xbox, PlayStation and generic controllers via the standard Gamepad
5
5
  * API: button mapping, axis input with deadzone, rumble, action binding and
6
- * rising/falling button-edge callbacks. This is the canonical, dependency-free
7
- * implementation; `@nice2dev/ui-graphics` and `@nice2dev/game-engine` re-export
8
- * it (and add their own game-specific UI on top).
6
+ * rising/falling button-edge callbacks. `@nice2dev/ui-graphics` and
7
+ * `@nice2dev/game-engine` re-export it (and add their own game-specific UI on top).
8
+ *
9
+ * Since 1.3.0 it is a layer over the input engine (ADR-005): it reads the frames the engine polls
10
+ * — none without a pad — instead of running an animation loop of its own, and re-renders only
11
+ * when the state changes, not every frame.
9
12
  */
10
13
  export type GamepadButton = 'A' | 'B' | 'X' | 'Y' | 'LB' | 'RB' | 'LT' | 'RT' | 'Back' | 'Start' | 'LS' | 'RS' | 'DpadUp' | 'DpadDown' | 'DpadLeft' | 'DpadRight' | 'Home';
11
14
  export type GamepadAxis = 'LeftX' | 'LeftY' | 'RightX' | 'RightY';
@@ -53,6 +56,11 @@ export interface UseGamepadOptions {
53
56
  export declare const PS_BUTTON_ALIASES: Record<string, GamepadButton>;
54
57
  /** All gamepad button names, in Gamepad-API index order. */
55
58
  export declare const GAMEPAD_BUTTONS: GamepadButton[];
59
+ /**
60
+ * @deprecated since 1.3.0 — for UI input use intents (`useIntent`, ADR-005): they come from every
61
+ * device and follow the user's bindings. For raw pad state per frame (games) use
62
+ * `getInputEngine().subscribeGamepadFrames()`. This hook stays as a layer over the engine.
63
+ */
56
64
  export declare function useGamepad(options?: UseGamepadOptions): GamepadState;
57
65
  export interface NavigationActions {
58
66
  onNavigateUp?: () => void;
@@ -65,5 +73,10 @@ export interface NavigationActions {
65
73
  onTabPrev?: () => void;
66
74
  onMenu?: () => void;
67
75
  }
68
- /** Create a standard UI-navigation action map for {@link useGamepad}. */
76
+ /**
77
+ * Create a standard UI-navigation action map for {@link useGamepad}.
78
+ *
79
+ * @deprecated since 1.3.0 — the input engine maps the pad to intents itself (`useIntent`,
80
+ * ADR-005). Since 1.3.0 the stick fires once per push instead of on every frame past 0.8.
81
+ */
69
82
  export declare function createNavigationActions(handlers: NavigationActions): Record<string, GamepadAction>;