@sheetxl/utils-react 0.8.0-beta.1 → 0.8.0-beta.11
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/browser/esm/{CKvLZo8keTi4hdRr.mjs → 3j_xcvx6bFQsulwT.mjs} +1 -1
- package/browser/esm/{BIb3Fag4wDs4Gro1.mjs → DmyXYEmBOLQfUC3S.mjs} +19 -18
- package/browser/esm/IqQLdwJk1VA8hpDI.mjs +100 -0
- package/browser/esm/index.mjs +2572 -2057
- package/licenses/dependencies.txt +1 -39
- package/node/esm/{TlOKuBGsozMYzzBC.mjs → B7T-c_PH7rtDuiLF.mjs} +1 -1
- package/node/esm/DHJ2cDJlYQ1rBfYF.mjs +100 -0
- package/node/esm/index.mjs +2294 -1788
- package/package.json +8 -11
- package/types/src/animation/useAnimatedMeasure.d.ts +2 -3
- package/types/src/command/CommandCatalog.d.ts +2 -2
- package/types/src/command/CommandScope.d.ts +23 -2
- package/types/src/command/index.d.ts +1 -0
- package/types/src/command/tags.d.ts +19 -0
- package/types/src/components/index.d.ts +0 -1
- package/types/src/float/FloatPanel.d.ts +20 -1
- package/types/src/float/FloatPopper.d.ts +84 -10
- package/types/src/float/index.d.ts +0 -1
- package/types/src/hooks/LanguageState.d.ts +1 -1
- package/types/src/hooks/index.d.ts +4 -0
- package/types/src/hooks/useCallbackRef.d.ts +19 -6
- package/types/src/hooks/useEditMode.d.ts +24 -4
- package/types/src/hooks/useImperativeElement.d.ts +1 -1
- package/types/src/hooks/useInputModality.d.ts +26 -0
- package/types/src/hooks/useLocationSearch.d.ts +9 -0
- package/types/src/hooks/useMeasure.d.ts +32 -0
- package/types/src/hooks/useNotifier.d.ts +32 -36
- package/types/src/hooks/useSynchronizedPointerHandler.d.ts +3 -7
- package/types/src/hooks/useVisualViewportRect.d.ts +39 -0
- package/types/src/icons/packs/Base.json.d.ts +3406 -0
- package/types/src/index.d.ts +2 -0
- package/types/src/lazy/index.d.ts +2 -0
- package/types/src/lazy/lazyComponent.d.ts +43 -0
- package/types/src/persistence/PersistentStateProvider.d.ts +3 -0
- package/types/src/persistence/Types.d.ts +18 -4
- package/types/src/persistence/_Context.d.ts +3 -2
- package/types/src/persistence/index.d.ts +2 -2
- package/types/src/persistence/usePersistentState.d.ts +39 -0
- package/types/src/scroll/AxisViewport.d.ts +6 -2
- package/types/src/scroll/IScrollPane.d.ts +10 -1
- package/types/src/scroll/Utils.d.ts +1 -0
- package/types/src/scroll/Viewport.d.ts +50 -2
- package/types/src/scroll/touchOwner.d.ts +19 -0
- package/types/src/scroll/useWheelScroll.d.ts +15 -2
- package/types/src/scroll/wheelOwner.d.ts +18 -0
- package/types/src/scroller/Scroller.d.ts +44 -5
- package/types/src/theme/TokenTheme.d.ts +14 -5
- package/types/src/theme/index.d.ts +1 -0
- package/types/src/theme/zIndex.d.ts +24 -0
- package/types/src/utils/index.d.ts +2 -0
- package/types/src/utils/measureUIText.d.ts +24 -0
- package/types/src/utils/textSelectionDrag.d.ts +52 -0
- package/types/src/virtualKeyboard/VirtualKeyboard.d.ts +122 -0
- package/types/src/virtualKeyboard/index.d.ts +2 -0
- package/browser/cjs/D02anPwyfYZxlZmG.cjs +0 -1
- package/browser/cjs/DZSvmqU8nRas1uz6.cjs +0 -1
- package/browser/cjs/Dc-AA0ooFLVdAhbT.cjs +0 -1
- package/browser/cjs/index.cjs +0 -5
- package/browser/esm/BT6JG-bEtM8ou0Xr.mjs +0 -2179
- package/node/esm/CdJ0O_khlsS4DqVj.mjs +0 -2179
- package/types/src/components/ITooltip.d.ts +0 -38
- package/types/src/float/FloatTooltip.d.ts +0 -22
- package/types/src/persistence/PersistenceStateProvider.d.ts +0 -3
- package/types/src/persistence/usePersistenceState.d.ts +0 -33
- package/types/src/utils/PinchZoom.d.ts +0 -3
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sheetxl/utils-react",
|
|
3
3
|
"description": "Utils React - Utilities for React capabilities needed for all SheetXL components.",
|
|
4
|
-
"version": "0.8.0-beta.
|
|
4
|
+
"version": "0.8.0-beta.11",
|
|
5
5
|
"license": "SEE LICENSE IN <LICENSE>",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"exports": {
|
|
@@ -9,13 +9,12 @@
|
|
|
9
9
|
"types": "./types/index.d.ts",
|
|
10
10
|
"browser": "./browser/esm/index.mjs",
|
|
11
11
|
"node": "./node/esm/index.mjs",
|
|
12
|
-
"
|
|
13
|
-
"require": "./browser/cjs/index.cjs"
|
|
12
|
+
"default": "./browser/esm/index.mjs"
|
|
14
13
|
}
|
|
15
14
|
},
|
|
16
15
|
"types": "./types/index.d.ts",
|
|
17
16
|
"module": "./browser/esm/index.mjs",
|
|
18
|
-
"main": "./browser/
|
|
17
|
+
"main": "./browser/esm/index.mjs",
|
|
19
18
|
"sideEffects": [
|
|
20
19
|
"*.css",
|
|
21
20
|
"**/*.css"
|
|
@@ -41,21 +40,19 @@
|
|
|
41
40
|
],
|
|
42
41
|
"dependencies": {
|
|
43
42
|
"@floating-ui/react-dom": "^2.1.9",
|
|
44
|
-
"@sheetxl/utils": "^0.8.0-beta.
|
|
43
|
+
"@sheetxl/utils": "^0.8.0-beta.11",
|
|
45
44
|
"clsx": "^2.1.1",
|
|
46
45
|
"detect-it": "^4.0.1",
|
|
47
46
|
"prop-types": "^15.8.1",
|
|
48
|
-
"react-draggable": "^4.7.
|
|
49
|
-
"react-merge-refs": "^3.0.2"
|
|
50
|
-
"react-use": "^17.6.1",
|
|
51
|
-
"tiny-invariant": "^1.3.3"
|
|
47
|
+
"react-draggable": "^4.7.2",
|
|
48
|
+
"react-merge-refs": "^3.0.2"
|
|
52
49
|
},
|
|
53
50
|
"peerDependencies": {
|
|
54
51
|
"react": "^19.2.0",
|
|
55
52
|
"react-dom": "^19.2.0"
|
|
56
53
|
},
|
|
57
54
|
"devDependencies": {
|
|
58
|
-
"@types/react": "^19.
|
|
59
|
-
"@types/react-dom": "^19.
|
|
55
|
+
"@types/react": "^19.3.0",
|
|
56
|
+
"@types/react-dom": "^19.3.0"
|
|
60
57
|
}
|
|
61
58
|
}
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
|
|
1
|
+
import { MeasureRect } from '../hooks';
|
|
2
2
|
export interface UseAnimatedMeasureOptions {
|
|
3
3
|
/** Threshold in pixels for detecting bounds changes (default: 0.1) */
|
|
4
4
|
threshold?: number;
|
|
@@ -34,6 +34,5 @@ export interface UseAnimatedMeasureOptions {
|
|
|
34
34
|
* );
|
|
35
35
|
* ```
|
|
36
36
|
*/
|
|
37
|
-
export declare function useAnimatedMeasure<T extends Element = HTMLDivElement>(options?: UseAnimatedMeasureOptions): readonly [(node: T | null) => void,
|
|
38
|
-
export {};
|
|
37
|
+
export declare function useAnimatedMeasure<T extends Element = HTMLDivElement>(options?: UseAnimatedMeasureOptions): readonly [(node: T | null) => void, MeasureRect | null];
|
|
39
38
|
//# sourceMappingURL=useAnimatedMeasure.d.ts.map
|
|
@@ -54,8 +54,8 @@ export interface ChromeRecord {
|
|
|
54
54
|
* `null` means **explicitly unbound in this locale** (the usual convention: `undefined` = take
|
|
55
55
|
* the default, `null` = exclude it). A locale pack inherits English shortcuts by *absence*, so
|
|
56
56
|
* `null` is the only way for a locale to drop one — needed when a localized mnemonic claims a
|
|
57
|
-
* chord English gives to some other command (de Bold takes `ctrl+shift+F`, so de
|
|
58
|
-
* must give it up). See `config/i18n-catalog-build.mjs`.
|
|
57
|
+
* chord English gives to some other command (de Bold takes `ctrl+shift+F`, so de
|
|
58
|
+
* `formatCellsFont` must give it up). See `config/i18n-catalog-build.mjs`.
|
|
59
59
|
*/
|
|
60
60
|
shortcut?: string | string[] | null;
|
|
61
61
|
/** Accumulated metadata tags (e.g. `'mutator'`, `'quickAction'`). */
|
|
@@ -65,6 +65,15 @@ export declare class CommandScope {
|
|
|
65
65
|
protected _children: Map<string, CommandScope>;
|
|
66
66
|
/** This scope's own within-scope merged definitions, by command key. */
|
|
67
67
|
protected _defs: Map<string, ICommandDefinition<any, any, void>>;
|
|
68
|
+
/**
|
|
69
|
+
* What each live {@link contribution} wrote per key, so removing one re-merges the others instead
|
|
70
|
+
* of dropping the key: key → contribution → each field it wrote, with when it wrote it.
|
|
71
|
+
*/
|
|
72
|
+
protected _layers: Map<string, Map<object, Map<string, {
|
|
73
|
+
value: unknown;
|
|
74
|
+
seq: number;
|
|
75
|
+
}>>>;
|
|
76
|
+
protected _layerSeq: number;
|
|
68
77
|
/** Dispatch middleware authored on THIS scope (wraps callbacks this scope contributes). */
|
|
69
78
|
protected _middleware: CommandMiddleware<any, any, any>[];
|
|
70
79
|
/** Teardown for a contribution bound at {@link createChild} (its `setup`'s returned disposer). */
|
|
@@ -76,6 +85,10 @@ export declare class CommandScope {
|
|
|
76
85
|
protected _resolveCacheVersion: number;
|
|
77
86
|
/** root-only: coarse change listeners (fired on any version bump). */
|
|
78
87
|
protected _listeners: Set<CommandScopeListener>;
|
|
88
|
+
/** root-only: a fan-out window is open for this tick (see {@link _bump}). */
|
|
89
|
+
protected _notifyPending: boolean;
|
|
90
|
+
/** root-only: bumps arrived while the window was open ⇒ ONE trailing notify when it closes. */
|
|
91
|
+
protected _notifyDirty: boolean;
|
|
79
92
|
/** root-only: per-command-key execute observers (ripple/close, middleware). `any` ARGS so
|
|
80
93
|
* observers for differently-parameterized commands coexist in one registry map. */
|
|
81
94
|
protected _executeListeners: Map<string, Set<ExecuteHook<any, any, any>>>;
|
|
@@ -246,13 +259,21 @@ export declare class CommandScope {
|
|
|
246
259
|
* clear). The cross-scope cascade happens later, in {@link resolve}.
|
|
247
260
|
*/
|
|
248
261
|
updateCommand<STATE = any, CONTEXT = any, ARGS = void>(commandKey: string, partial: Omit<ICommandDefinition<STATE, CONTEXT, ARGS>, 'key'>): void;
|
|
249
|
-
/** Remove this scope's contribution for `commandKey
|
|
262
|
+
/** Remove this scope's contribution for `commandKey`, every contribution's part of it included. */
|
|
250
263
|
removeCommand(commandKey: string): void;
|
|
264
|
+
/** Record what `owner` (a {@link contribution}) wrote for `commandKey`, merged with its earlier writes. */
|
|
265
|
+
protected _recordLayer(commandKey: string, owner: object, partial: object): void;
|
|
266
|
+
/**
|
|
267
|
+
* Drop what `owner` wrote for `commandKey`. The key goes when nothing else wrote it; otherwise it
|
|
268
|
+
* is rebuilt from the remaining contributions, each field taking its most recent write.
|
|
269
|
+
*/
|
|
270
|
+
protected _removeLayer(commandKey: string, owner: object): void;
|
|
251
271
|
/**
|
|
252
272
|
* Open a tracked {@link CommandContribution} on THIS scope: `updateCommand` through the handle
|
|
253
273
|
* records each key, and `remove()` removes exactly those — so a contributor (esp. a large one)
|
|
254
274
|
* cleans up with a single call rather than a per-key `removeCommand` list that's easy to fall out
|
|
255
|
-
* of sync. The handle owns *its*
|
|
275
|
+
* of sync. The handle owns *its* part of each key only: when another contribution to this scope
|
|
276
|
+
* wrote the same key, removing this one leaves the other's fields in place.
|
|
256
277
|
*/
|
|
257
278
|
contribution(): CommandContribution;
|
|
258
279
|
/**
|
|
@@ -3,6 +3,7 @@ export * from './Types';
|
|
|
3
3
|
export * from './CommandButtonRegistry';
|
|
4
4
|
export * from './CommandButtonRegistryContext';
|
|
5
5
|
export * from './CommandButtonEntryLabel';
|
|
6
|
+
export * from './tags';
|
|
6
7
|
export * from './ICommandDefinition';
|
|
7
8
|
export * from './reduceDefinitions';
|
|
8
9
|
export * from './createResolvedCommand';
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Well-known command tag hints honored by the command surfaces.
|
|
3
|
+
*
|
|
4
|
+
* Tags are free-form strings on a command definition (e.g. `'mutator'` drives format-protection
|
|
5
|
+
* disabling). These constants name the ones the shared UI layer reacts to, so definitions and the
|
|
6
|
+
* consumers that read them agree without stringly-typed drift.
|
|
7
|
+
*/
|
|
8
|
+
/**
|
|
9
|
+
* A command that applies **in place** and must NOT dismiss its enclosing popup on execute — font-size
|
|
10
|
+
* increase/decrease, indent increase/decrease, decimal places, the number-format quick styles. These
|
|
11
|
+
* are the "quick button" rows a popup leads with, and they exist to be pressed repeatedly.
|
|
12
|
+
*
|
|
13
|
+
* The auto-dismiss observer in `useCommands` reads this off the RESOLVED command, so it holds for
|
|
14
|
+
* **every** observer of the key. A per-surface opt-out cannot: an execute notifies every mounted
|
|
15
|
+
* observer of that key, so a co-observer with no hook (the same command on the toolbar, whose
|
|
16
|
+
* enclosing float is the popup's ancestor) would still close the popup out from under the quick button.
|
|
17
|
+
*/
|
|
18
|
+
export declare const QUICK_ACTION_TAG = "quickAction";
|
|
19
|
+
//# sourceMappingURL=tags.d.ts.map
|
|
@@ -21,6 +21,26 @@ export interface FloatPanelProps extends Omit<React.HTMLAttributes<HTMLDivElemen
|
|
|
21
21
|
onOpen?: () => void;
|
|
22
22
|
ref?: React.Ref<any>;
|
|
23
23
|
}
|
|
24
|
+
/**
|
|
25
|
+
* Props for {@link FloatPanelSurface}.
|
|
26
|
+
*/
|
|
27
|
+
export interface FloatPanelSurfaceProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
|
|
28
|
+
floatReference?: FloatReference;
|
|
29
|
+
/** The element the float is positioned in, handed on to the content. */
|
|
30
|
+
popupContainer?: HTMLElement;
|
|
31
|
+
createPopupPanel?: (props: FloatPopupPanelProps) => React.ReactElement | null;
|
|
32
|
+
children?: React.ReactNode;
|
|
33
|
+
ref?: React.Ref<HTMLDivElement>;
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* The card a {@link FloatPanel} shows: the themed, scrollable surface its content is created in.
|
|
37
|
+
*
|
|
38
|
+
* @remarks
|
|
39
|
+
* Separate from the positioning so a float positioned by something other than {@link FloatPopper}
|
|
40
|
+
* (a grid float that follows its cell) wears the same card. Other attributes are handed to
|
|
41
|
+
* `createPopupPanel`, not set on the card.
|
|
42
|
+
*/
|
|
43
|
+
export declare const FloatPanelSurface: React.NamedExoticComponent<Omit<FloatPanelSurfaceProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
|
|
24
44
|
/**
|
|
25
45
|
* A floating, anchored surface for transient content such as menus, dropdowns,
|
|
26
46
|
* popovers and context menus.
|
|
@@ -38,7 +58,6 @@ export interface FloatPanelProps extends Omit<React.HTMLAttributes<HTMLDivElemen
|
|
|
38
58
|
*
|
|
39
59
|
* When to use which:
|
|
40
60
|
* - {@link FloatPopper} — you only need raw positioning + portal (no card chrome).
|
|
41
|
-
* - {@link FloatTooltip} — a small, controlled hint anchored to a point.
|
|
42
61
|
* - `FloatPanel` / {@link useFloatStack} — interactive floating content (menus, popovers).
|
|
43
62
|
*
|
|
44
63
|
* The surface is theme-aware via CSS variables (e.g. `--sxl-color-base-100`),
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { default as React } from 'react';
|
|
2
|
-
import { Placement } from '@floating-ui/react-dom';
|
|
2
|
+
import { Placement, Strategy } from '@floating-ui/react-dom';
|
|
3
3
|
export interface FloatPopperPosition {
|
|
4
4
|
top: number;
|
|
5
5
|
left: number;
|
|
@@ -20,13 +20,36 @@ export interface FloatPopperRef {
|
|
|
20
20
|
element: () => HTMLElement | null;
|
|
21
21
|
}
|
|
22
22
|
/**
|
|
23
|
-
*
|
|
23
|
+
* A virtual anchor: anything with a live client rect. It may name the element it moves **with**
|
|
24
|
+
* (`contextElement`) — a grid range anchor names its pane — which restores Floating UI's DOM-side
|
|
25
|
+
* triggers (ancestor scroll, layout shift, resize) for an anchor that has no element of its own, and
|
|
26
|
+
* is where the popper reads the anchor's theme from (see {@link FloatPopperProps.themeFrom}).
|
|
24
27
|
*/
|
|
25
|
-
export
|
|
26
|
-
getBoundingClientRect: () => DOMRect;
|
|
27
|
-
} | (() => HTMLElement) | (() => {
|
|
28
|
+
export interface FloatPopperVirtualAnchor {
|
|
28
29
|
getBoundingClientRect: () => DOMRect;
|
|
29
|
-
|
|
30
|
+
readonly contextElement?: Element;
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Virtual or real element used to anchor the popper.
|
|
34
|
+
*/
|
|
35
|
+
export type FloatPopperAnchor = HTMLElement | FloatPopperVirtualAnchor | (() => HTMLElement) | (() => FloatPopperVirtualAnchor);
|
|
36
|
+
/** A client rect (what Floating UI collides against); a `DOMRect` is one. */
|
|
37
|
+
export interface FloatPopperRect {
|
|
38
|
+
x: number;
|
|
39
|
+
y: number;
|
|
40
|
+
width: number;
|
|
41
|
+
height: number;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Offsets by axis (Floating UI's `offset` options): `mainAxis` pushes away from the anchor edge,
|
|
45
|
+
* `crossAxis` slides along it, `alignmentAxis` slides along it for an aligned (`-start` / `-end`)
|
|
46
|
+
* placement only, measured inward from the corner — so it survives a flip to the opposite corner.
|
|
47
|
+
*/
|
|
48
|
+
export interface FloatPopperOffsets {
|
|
49
|
+
mainAxis?: number;
|
|
50
|
+
crossAxis?: number;
|
|
51
|
+
alignmentAxis?: number;
|
|
52
|
+
}
|
|
30
53
|
export interface FloatPopperProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
|
|
31
54
|
/**
|
|
32
55
|
* Whether the popper should be shown (drives the enter/exit transition).
|
|
@@ -45,17 +68,68 @@ export interface FloatPopperProps extends Omit<React.HTMLAttributes<HTMLDivEleme
|
|
|
45
68
|
*/
|
|
46
69
|
placement?: Placement;
|
|
47
70
|
/**
|
|
48
|
-
* `[skidding, distance]` offset (popper.js convention, preserved for
|
|
49
|
-
*
|
|
50
|
-
*
|
|
71
|
+
* `[skidding, distance]` offset (popper.js convention, preserved for compatibility): `skidding`
|
|
72
|
+
* shifts along the anchor edge, `distance` pushes away from it. Or the per-axis object form
|
|
73
|
+
* ({@link FloatPopperOffsets}) when the alignment axis matters.
|
|
51
74
|
* @defaultValue [0, 2]
|
|
52
75
|
*/
|
|
53
|
-
offsets?: number[];
|
|
76
|
+
offsets?: number[] | FloatPopperOffsets;
|
|
54
77
|
/**
|
|
55
78
|
* If the panel can resize on overflow. Otherwise it will try to fit.
|
|
56
79
|
* @defaultValue true
|
|
57
80
|
*/
|
|
58
81
|
resizeOnOverflow?: boolean;
|
|
82
|
+
/**
|
|
83
|
+
* Where the popper may **live**: a live client rect, read on every reposition, that `flip` (and
|
|
84
|
+
* `size`, when it resizes) collide against instead of the document — so a popup can be held inside a
|
|
85
|
+
* region (a grid's data area) rather than the page. Floating UI still intersects it with the browser
|
|
86
|
+
* viewport, so the popper never leaves the screen either.
|
|
87
|
+
* @defaultValue none — the document
|
|
88
|
+
*/
|
|
89
|
+
boundary?: () => FloatPopperRect;
|
|
90
|
+
/**
|
|
91
|
+
* Slide the popper back inside the boundary along the alignment axis when it would overflow (Floating UI
|
|
92
|
+
* `shift`), keeping `padding` px from the edge. Off by default: for a panel larger than the viewport it
|
|
93
|
+
* clamps to the boundary origin instead of staying anchored (add a `limitShift` limiter before turning
|
|
94
|
+
* it on for such panels).
|
|
95
|
+
* @defaultValue false
|
|
96
|
+
*/
|
|
97
|
+
shift?: boolean | {
|
|
98
|
+
padding?: number;
|
|
99
|
+
};
|
|
100
|
+
/**
|
|
101
|
+
* The enter transition (the grow-in). `false` renders the content positioned on its first frame,
|
|
102
|
+
* with no transition wrapper — for a label that must track a gesture, not open like a menu.
|
|
103
|
+
* @defaultValue true
|
|
104
|
+
*/
|
|
105
|
+
transition?: boolean;
|
|
106
|
+
/**
|
|
107
|
+
* The portal container.
|
|
108
|
+
* @defaultValue the fullscreen-aware root ({@link useFullscreenPortal})
|
|
109
|
+
*/
|
|
110
|
+
container?: Element;
|
|
111
|
+
/**
|
|
112
|
+
* The stacking band. A number, or a `z-index` expression from {@link zIndexVar}.
|
|
113
|
+
* @defaultValue `zIndexVar('popup')`
|
|
114
|
+
*/
|
|
115
|
+
zIndex?: number | string;
|
|
116
|
+
/**
|
|
117
|
+
* Floating UI positioning strategy. `'fixed'` positions in client space — for a virtual anchor that
|
|
118
|
+
* reports client rects and must not be offset by a positioned ancestor of the container.
|
|
119
|
+
* @defaultValue 'absolute'
|
|
120
|
+
*/
|
|
121
|
+
strategy?: Strategy;
|
|
122
|
+
/**
|
|
123
|
+
* Whose theme the popper carries across the portal (THEMING-DESIGN §7):
|
|
124
|
+
* - `'provider'` — the nearest {@link FloatProvider}'s theme scope: the app's surface and mode, so a
|
|
125
|
+
* menu opened from a light grid in a dark app opens dark, following the app. When no provider supplies
|
|
126
|
+
* a theme, the anchor's is copied instead.
|
|
127
|
+
* - `'anchor'` — the anchor element's own `data-sxl-theme-*` (for a virtual anchor, its
|
|
128
|
+
* `contextElement`'s), kept live: a label that belongs to the grid themes with the grid, even where the
|
|
129
|
+
* grid's mode differs from the app's. The provider's scope classes still apply.
|
|
130
|
+
* @defaultValue 'provider'
|
|
131
|
+
*/
|
|
132
|
+
themeFrom?: 'provider' | 'anchor';
|
|
59
133
|
/**
|
|
60
134
|
* Poll the anchor's position every animation frame while open (Floating UI
|
|
61
135
|
* `autoUpdate({ animationFrame: true })`). Needed when the anchor is a VIRTUAL element that MOVES with no
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* Persistence key for the user's UI-language preference.
|
|
3
3
|
*
|
|
4
4
|
* @remarks
|
|
5
|
-
* Owned via `
|
|
5
|
+
* Owned via `usePersistentState` against the surrounding `PersistentStateProvider` (Studio, or a
|
|
6
6
|
* standalone host) — the mirror of `ThemeStateKey` in `@sheetxl/react`. A host that wants to read
|
|
7
7
|
* or seed it (e.g. the VS Code extension, whose store bridges to the extension host's state) does
|
|
8
8
|
* so with the same key, or by supplying its own provider/store. The value is a BCP 47 tag; absent
|
|
@@ -7,6 +7,7 @@ export * from './useDevicePixelRatio';
|
|
|
7
7
|
export * from './useOnClickOrFocusAway';
|
|
8
8
|
export * from './useMouseDownAndHoldListener';
|
|
9
9
|
export * from './useSynchronizedPointerHandler';
|
|
10
|
+
export * from './useInputModality';
|
|
10
11
|
export * from './useEditMode';
|
|
11
12
|
export * from './LanguageState';
|
|
12
13
|
export * from './useLanguage';
|
|
@@ -16,4 +17,7 @@ export * from './useGlobalClipboard';
|
|
|
16
17
|
export * from './useTraceUpdate';
|
|
17
18
|
export * from './useId';
|
|
18
19
|
export * from './useImperativeElement';
|
|
20
|
+
export * from './useVisualViewportRect';
|
|
21
|
+
export * from './useMeasure';
|
|
22
|
+
export * from './useLocationSearch';
|
|
19
23
|
//# sourceMappingURL=index.d.ts.map
|
|
@@ -1,11 +1,24 @@
|
|
|
1
1
|
import { DependencyList } from 'react';
|
|
2
2
|
/**
|
|
3
|
-
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
3
|
+
* A callback with a **stable identity** that always runs the latest closure — like `useCallback`,
|
|
4
|
+
* except that a change in `deps` does NOT change the returned function. Pass it to memoized
|
|
5
|
+
* children, effect dependency lists or long-lived subscriptions (a command contribution's `data`,
|
|
6
|
+
* a model listener) without re-running them whenever the closure's inputs change.
|
|
7
|
+
*
|
|
8
|
+
* This is the "latest ref" pattern (React's `useEvent` RFC; ahooks' `useMemoizedFn`; Radix's
|
|
9
|
+
* `useCallbackRef`).
|
|
10
|
+
*
|
|
11
|
+
* Usage notes:
|
|
12
|
+
* - **List every value the callback reads in `deps`.** The closure is only refreshed when `deps`
|
|
13
|
+
* change, so a missing dependency means the stable function calls a stale closure.
|
|
14
|
+
* - **Call it from events and deferred work, not during render.** Its identity never changes, so
|
|
15
|
+
* a component that reads its result while rendering is not re-rendered when the inputs change.
|
|
16
|
+
* - **For logic called only from an effect,** React's own `useEffectEvent` (React 19.2+) is the
|
|
17
|
+
* standard alternative. It cannot be passed to children or called during render, which this hook
|
|
18
|
+
* allows.
|
|
19
|
+
*
|
|
20
|
+
* @param callback - The function to wrap; `null`/`undefined` yields a function returning `undefined`.
|
|
21
|
+
* @param deps - Every value `callback` closes over.
|
|
9
22
|
*/
|
|
10
23
|
export declare const useCallbackRef: <T extends (...args: any[]) => any>(callback: T | null | undefined, deps: DependencyList) => T;
|
|
11
24
|
//# sourceMappingURL=useCallbackRef.d.ts.map
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { EditModeHandler, SetEditMode } from '@sheetxl/utils';
|
|
1
|
+
import { EditMode, EditModeHandler, SetEditMode } from '@sheetxl/utils';
|
|
2
2
|
/**
|
|
3
3
|
* Publish (or clear) the active {@link EditMode} on the app-wide bus **without a hook** — the same
|
|
4
4
|
* write {@link useEditMode}'s `setMode` performs (fires the superseded mode's
|
|
@@ -11,6 +11,25 @@ import { EditModeHandler, SetEditMode } from '@sheetxl/utils';
|
|
|
11
11
|
* to be mounted (a `SingletonHooksContainer` in the tree), exactly like the hook.
|
|
12
12
|
*/
|
|
13
13
|
export declare const setEditMode: SetEditMode;
|
|
14
|
+
/** A way out of a mode: {@link EditMode.done} or {@link EditMode.cancel}. */
|
|
15
|
+
export type EditModeExit = 'done' | 'cancel';
|
|
16
|
+
/**
|
|
17
|
+
* Take a way out of a mode from chrome (the status bar's ✓ / ✕): tells the
|
|
18
|
+
* {@link subscribeEditModeExit} listeners, then runs the mode's own `done` or `cancel`.
|
|
19
|
+
*
|
|
20
|
+
* @remarks
|
|
21
|
+
* A way out is the user finishing the interaction, which is more than the mode ending: an edit also
|
|
22
|
+
* ends when Enter moves on to the next cell. A feature that follows the user rather than the mode (the
|
|
23
|
+
* virtual keyboard going down) listens here, so the chrome needs no knowledge of it.
|
|
24
|
+
*/
|
|
25
|
+
export declare const exitEditMode: (mode: EditMode, exit: EditModeExit) => void;
|
|
26
|
+
/**
|
|
27
|
+
* Listen for a way out of a mode taken from chrome (see {@link exitEditMode}). Called before the
|
|
28
|
+
* mode's own `done` or `cancel` runs.
|
|
29
|
+
*
|
|
30
|
+
* @returns Stops listening.
|
|
31
|
+
*/
|
|
32
|
+
export declare const subscribeEditModeExit: (listener: (mode: EditMode, exit: EditModeExit) => void) => (() => void);
|
|
14
33
|
/**
|
|
15
34
|
* Access the application's **edit-mode bus** — the single, app-wide signal describing the
|
|
16
35
|
* interaction currently in effect.
|
|
@@ -19,8 +38,8 @@ export declare const setEditMode: SetEditMode;
|
|
|
19
38
|
*
|
|
20
39
|
* @remarks
|
|
21
40
|
* At any moment the application is in exactly one interaction mode, or none (idle). The bus holds a
|
|
22
|
-
* single {@link EditMode} (`{ key, description?, args?, cursor?, onModeChange? }`),
|
|
23
|
-
* the app reads from and writes to that one value.
|
|
41
|
+
* single {@link EditMode} (`{ key, description?, args?, cursor?, cancel?, done?, onModeChange? }`),
|
|
42
|
+
* and every part of the app reads from and writes to that one value.
|
|
24
43
|
*
|
|
25
44
|
* It exists so unrelated features can coordinate **without depending on one another**. A feature
|
|
26
45
|
* announces that its interaction has started by publishing a mode, and clears it when finished;
|
|
@@ -36,7 +55,8 @@ export declare const setEditMode: SetEditMode;
|
|
|
36
55
|
* - the format painter.
|
|
37
56
|
*
|
|
38
57
|
* Typical **consumers** (read the active mode):
|
|
39
|
-
* - the status bar, which shows {@link EditMode.description} (and its idle label when there is none)
|
|
58
|
+
* - the status bar, which shows {@link EditMode.description} (and its idle label when there is none),
|
|
59
|
+
* with a ✕ and a ✓ that take the mode's ways out ({@link exitEditMode}) when the mode carries them;
|
|
40
60
|
* - the grid, which applies {@link EditMode.cursor};
|
|
41
61
|
* - features that must defer to another interaction — e.g. fill is suppressed while a cell is being
|
|
42
62
|
* edited — by inspecting the active {@link EditMode.key}.
|
|
@@ -1,3 +1,3 @@
|
|
|
1
1
|
import { DependencyList } from 'react';
|
|
2
|
-
export declare function useImperativeElement<R extends T, A = any, T = HTMLElement & A>(refForwarded: React.Ref<R>, attributeFn?: () => Partial<A>, deps?: DependencyList): React.RefObject<R>;
|
|
2
|
+
export declare function useImperativeElement<R extends T, A = any, T = HTMLElement & A>(refForwarded: React.Ref<R>, attributeFn?: () => Partial<A>, deps?: DependencyList, element?: HTMLElement | null): React.RefObject<R>;
|
|
3
3
|
//# sourceMappingURL=useImperativeElement.d.ts.map
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* How the person is pointing right now: with a finger, or with something precise (a mouse, a
|
|
3
|
+
* trackpad, a pen).
|
|
4
|
+
*/
|
|
5
|
+
export type InputModality = 'touch' | 'mouse';
|
|
6
|
+
/**
|
|
7
|
+
* The current input modality: `'touch'` on a touch-first device, or anywhere the last press was a
|
|
8
|
+
* finger; `'mouse'` once a mouse or pen presses on a mouse-first device.
|
|
9
|
+
*
|
|
10
|
+
* @remarks
|
|
11
|
+
* Touch affordances (selection grips, large handles, touch scroll thumbs) key off this rather than
|
|
12
|
+
* off a static device test, so a laptop with a touchscreen shows them after a tap and hides them
|
|
13
|
+
* after a click. A touch-first device keeps them even when a mouse is plugged in.
|
|
14
|
+
*/
|
|
15
|
+
export declare const getInputModality: () => InputModality;
|
|
16
|
+
/**
|
|
17
|
+
* Listen for the modality changing. The document listener is attached while anyone listens.
|
|
18
|
+
*
|
|
19
|
+
* @returns Stops listening.
|
|
20
|
+
*/
|
|
21
|
+
export declare const subscribeInputModality: (listener: () => void) => (() => void);
|
|
22
|
+
/**
|
|
23
|
+
* The current {@link InputModality}, re-rendering when it changes. See {@link getInputModality}.
|
|
24
|
+
*/
|
|
25
|
+
export declare const useInputModality: () => InputModality;
|
|
26
|
+
//# sourceMappingURL=useInputModality.d.ts.map
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The page URL's query string (`window.location.search`, including the leading `?`, or `''`).
|
|
3
|
+
*
|
|
4
|
+
* @remarks
|
|
5
|
+
* Re-renders on back/forward navigation and on `history.pushState` / `replaceState`. Always `''` when
|
|
6
|
+
* rendered on a server.
|
|
7
|
+
*/
|
|
8
|
+
export declare function useLocationSearch(): string;
|
|
9
|
+
//# sourceMappingURL=useLocationSearch.d.ts.map
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import { useEffect } from 'react';
|
|
2
|
+
/**
|
|
3
|
+
* `useLayoutEffect` in the browser, `useEffect` where there is no DOM (so server rendering doesn't warn).
|
|
4
|
+
*/
|
|
5
|
+
export declare const useIsomorphicLayoutEffect: typeof useEffect;
|
|
6
|
+
/**
|
|
7
|
+
* The content box of a measured element, in CSS px. Same fields as a ResizeObserver `contentRect`:
|
|
8
|
+
* `x`/`y` (and `left`/`top`) are the padding offsets, not a page position.
|
|
9
|
+
*/
|
|
10
|
+
export type MeasureRect = Pick<DOMRectReadOnly, 'x' | 'y' | 'top' | 'left' | 'right' | 'bottom' | 'height' | 'width'>;
|
|
11
|
+
/**
|
|
12
|
+
* A callback ref; attach it to the element to measure.
|
|
13
|
+
*/
|
|
14
|
+
export type MeasureRef<E extends Element> = (element: E | null) => void;
|
|
15
|
+
/**
|
|
16
|
+
* Tracks the content-box size of an element.
|
|
17
|
+
*
|
|
18
|
+
* @remarks
|
|
19
|
+
* Returns all zeros until the ref is attached; the element is measured as soon as it is attached
|
|
20
|
+
* (before paint) and again whenever a ResizeObserver reports a change. The returned rect keeps its
|
|
21
|
+
* identity while the size is unchanged. Where `ResizeObserver` is unavailable the rect stays zero.
|
|
22
|
+
*
|
|
23
|
+
* Changes from CSS transforms are not observed; see `useAnimatedMeasure`.
|
|
24
|
+
*
|
|
25
|
+
* @example
|
|
26
|
+
* ```tsx
|
|
27
|
+
* const [refMeasure, { width }] = useMeasure<HTMLDivElement>();
|
|
28
|
+
* return <div ref={refMeasure}>{width}px wide</div>;
|
|
29
|
+
* ```
|
|
30
|
+
*/
|
|
31
|
+
export declare function useMeasure<E extends Element = Element>(): [MeasureRef<E>, MeasureRect];
|
|
32
|
+
//# sourceMappingURL=useMeasure.d.ts.map
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { default as React } from 'react';
|
|
2
|
-
import {
|
|
2
|
+
import { NotifierOptions, INotifier } from '@sheetxl/utils';
|
|
3
3
|
/**
|
|
4
4
|
* Indicates the type of notification.
|
|
5
5
|
*/
|
|
@@ -75,10 +75,13 @@ export interface ShowOptionsOptions<T = any, C = any> extends ShowWindowOptions<
|
|
|
75
75
|
*/
|
|
76
76
|
description?: string;
|
|
77
77
|
/**
|
|
78
|
-
*
|
|
79
|
-
*
|
|
80
|
-
|
|
81
|
-
|
|
78
|
+
* What kind of message this is. `info`, `warning`, `error` and `success` show the matching icon
|
|
79
|
+
* beside the description; `default` (or omitted) shows none.
|
|
80
|
+
*/
|
|
81
|
+
type?: NotifierType;
|
|
82
|
+
/**
|
|
83
|
+
* An icon beside the description, in place of the one {@link type} implies. A `string` is an icon
|
|
84
|
+
* key.
|
|
82
85
|
*/
|
|
83
86
|
icon?: React.ReactNode | string;
|
|
84
87
|
/**
|
|
@@ -266,52 +269,45 @@ export interface IReactNotifier extends INotifier {
|
|
|
266
269
|
*/
|
|
267
270
|
showInput: (options: ShowInputOptions) => Promise<InputResults>;
|
|
268
271
|
}
|
|
269
|
-
export
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
/** @inheritdoc IReactNotifier.showBusy */
|
|
277
|
-
showBusy(message: string | React.ReactNode, options?: ShowBusyOptions): (Promise<BusyHandle>) | BusyHandle;
|
|
278
|
-
/** @inheritdoc IReactNotifier.showWindow */
|
|
279
|
-
showWindow(type: string, options?: ShowWindowOptions): Promise<HTMLElement>;
|
|
280
|
-
/** @inheritdoc IReactNotifier.showError */
|
|
281
|
-
showError(error: any): void;
|
|
282
|
-
/** @inheritdoc IReactNotifier.showOptions */
|
|
283
|
-
showOptions(options: ShowOptionsOptions): Promise<OptionInput>;
|
|
284
|
-
/** @inheritdoc IReactNotifier.showInput */
|
|
285
|
-
showInput(options: ShowInputOptions): Promise<InputResults>;
|
|
272
|
+
export interface ReactNotifierProviderProps {
|
|
273
|
+
children: React.ReactNode;
|
|
274
|
+
/**
|
|
275
|
+
* The methods this provider implements. The ones it leaves out come from a provider further out,
|
|
276
|
+
* or do what {@link useNotifier} does with no provider.
|
|
277
|
+
*/
|
|
278
|
+
notifier: Partial<IReactNotifier>;
|
|
286
279
|
}
|
|
287
280
|
/**
|
|
288
|
-
*
|
|
289
|
-
*
|
|
281
|
+
* Shows the messages, dialogs and busy indicators that components below it ask for through
|
|
282
|
+
* {@link useNotifier}.
|
|
283
|
+
*
|
|
284
|
+
* @remarks
|
|
285
|
+
* Providers stack **per method, and the outermost wins**. An app that wraps a studio in a provider
|
|
286
|
+
* with only `showMessage` replaces the studio's toasts and keeps its dialogs.
|
|
287
|
+
*
|
|
288
|
+
* The provider affects React components only. To redirect the SDK's own messages, override the
|
|
289
|
+
* global {@link Notifier}.
|
|
290
290
|
*
|
|
291
291
|
* @example
|
|
292
292
|
* ```tsx
|
|
293
|
-
* const
|
|
293
|
+
* const notifier = {
|
|
294
294
|
* showMessage: (message) => toast(message),
|
|
295
|
-
* showError: (error) => toast.error(error)
|
|
296
|
-
* // ... other methods
|
|
295
|
+
* showError: (error) => toast.error(String(error))
|
|
297
296
|
* };
|
|
298
297
|
*
|
|
299
|
-
* <ReactNotifierProvider notifier={
|
|
298
|
+
* <ReactNotifierProvider notifier={notifier}>
|
|
300
299
|
* <App />
|
|
301
300
|
* </ReactNotifierProvider>
|
|
302
301
|
* ```
|
|
303
302
|
*/
|
|
304
|
-
export interface ReactNotifierProviderProps {
|
|
305
|
-
children: React.ReactNode;
|
|
306
|
-
notifier: IReactNotifier;
|
|
307
|
-
}
|
|
308
303
|
export declare const ReactNotifierProvider: React.FC<ReactNotifierProviderProps>;
|
|
309
304
|
/**
|
|
310
|
-
*
|
|
311
|
-
* NotifierProvider, or falls back to the default ReactNotifier singleton if
|
|
312
|
-
* no provider is found.
|
|
305
|
+
* Returns the notifier for showing the user messages, dialogs and busy indicators.
|
|
313
306
|
*
|
|
314
|
-
* @
|
|
307
|
+
* @remarks
|
|
308
|
+
* Every method is always present. With no {@link ReactNotifierProvider} above, messages, dialogs and
|
|
309
|
+
* busy indicators show nothing (a dialog resolves as if cancelled), and `log`, `warn`, `error` and
|
|
310
|
+
* `showError` go to the global {@link Notifier}.
|
|
315
311
|
*
|
|
316
312
|
* @example
|
|
317
313
|
* ```tsx
|
|
@@ -28,16 +28,12 @@ export interface PointerHandlerOptions<T extends Element = Element> {
|
|
|
28
28
|
timerInitial?: number;
|
|
29
29
|
timerContinuous?: number;
|
|
30
30
|
/**
|
|
31
|
-
*
|
|
32
|
-
*
|
|
31
|
+
* Track the gesture through pointer events rather than mouse events, so a finger or a pen drives
|
|
32
|
+
* it too. The element pressed declares `touch-action: none` to keep the browser's pan, and the
|
|
33
|
+
* scroll pane's touch scroller, off the gesture.
|
|
33
34
|
* @default false
|
|
34
35
|
*/
|
|
35
36
|
processTouch?: boolean;
|
|
36
|
-
/**
|
|
37
|
-
* If true the touch events will be consumed and not propagated.
|
|
38
|
-
* @default true
|
|
39
|
-
*/
|
|
40
|
-
consumeTouch?: boolean;
|
|
41
37
|
}
|
|
42
38
|
/**
|
|
43
39
|
* If returns false don't setup the other listeners
|