@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.
- package/CHANGELOG.md +484 -0
- package/dist/core/NiceUserPreferences.d.ts +9 -2
- package/dist/core/a11y.d.ts +42 -5
- package/dist/core/hooks.d.ts +4 -0
- package/dist/core/spatialNav.d.ts +31 -8
- package/dist/core/useGamepad.d.ts +17 -4
- package/dist/index.cjs +25 -25
- package/dist/index.d.ts +1 -0
- package/dist/index.mjs +3655 -4412
- package/dist/input/bindings.d.ts +35 -0
- package/dist/input/elements.d.ts +71 -0
- package/dist/input/engine.d.ts +153 -0
- package/dist/input/focus/candidates.d.ts +18 -0
- package/dist/input/focus/navigator.d.ts +24 -0
- package/dist/input/focus/scopes.d.ts +44 -0
- package/dist/input/focus/spatial.d.ts +13 -0
- package/dist/input/gamepadFamily.d.ts +30 -0
- package/dist/input/gamepadPoller.d.ts +57 -0
- package/dist/input/index.d.ts +33 -0
- package/dist/input/osk/editing.d.ts +15 -0
- package/dist/input/osk/layouts.d.ts +47 -0
- package/dist/input/prompts/NiceButtonPrompt.d.ts +35 -0
- package/dist/input/prompts/NiceControlHint.d.ts +21 -0
- package/dist/input/prompts/NiceInputHintBar.d.ts +31 -0
- package/dist/input/prompts/NiceKeyCap.d.ts +18 -0
- package/dist/input/prompts/keys.d.ts +23 -0
- package/dist/input/react/NiceFocusScope.d.ts +14 -0
- package/dist/input/react/NiceInputProvider.d.ts +42 -0
- package/dist/input/react/actions.d.ts +48 -0
- package/dist/input/react/hints.d.ts +34 -0
- package/dist/input/react/hooks.d.ts +52 -0
- package/dist/input/react/useElementEffect.d.ts +7 -0
- package/dist/input/react/useGridFocus.d.ts +26 -0
- package/dist/input/react/useMenuButton.d.ts +29 -0
- package/dist/input/react/useOverlayFocus.d.ts +33 -0
- package/dist/input/react/useRovingFocus.d.ts +46 -0
- package/dist/input/react/useTreeFocus.d.ts +30 -0
- package/dist/input/tabEscape.d.ts +20 -0
- package/dist/input/types.d.ts +98 -0
- package/dist/input-layer-Hyi3G0IM.js +3911 -0
- package/dist/input-layer-Kez0PkmN.cjs +1 -0
- package/dist/input.cjs +1 -0
- package/dist/input.mjs +94 -0
- package/package.json +8 -2
package/dist/core/a11y.d.ts
CHANGED
|
@@ -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
|
|
246
|
-
*
|
|
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 {
|
package/dist/core/hooks.d.ts
CHANGED
|
@@ -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:
|
|
7
|
-
*
|
|
8
|
-
*
|
|
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
|
-
/**
|
|
45
|
+
/** Handle gamepad input (default true). */
|
|
42
46
|
gamepad?: boolean;
|
|
43
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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.
|
|
7
|
-
*
|
|
8
|
-
*
|
|
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
|
-
/**
|
|
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>;
|