@sheetxl/utils-react 0.7.28-beta.4 → 0.8.0-beta.10
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/{BHhuMHMaojWvosqS.mjs → C61KRGJ5SxolPzsV.mjs} +182 -9
- package/browser/esm/{CmVNzL-ngYHToTGc.mjs → MX1mB0lFgdtW9vqX.mjs} +1 -1
- package/browser/esm/{51Pip02D-3A0Z061.mjs → c6p-JLuLHZbSS4lS.mjs} +19 -18
- package/browser/esm/index.mjs +2379 -1930
- package/licenses/dependencies.txt +1 -39
- package/node/esm/{DE0Lw6aGWWnFHy-j.mjs → DgX4rJhtPuZxWvt5.mjs} +181 -8
- package/node/esm/{CAC_eUuPPsAz7M27.mjs → DluzVx_97eND2sL7.mjs} +1 -1
- package/node/esm/index.mjs +2101 -1663
- 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 +88 -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 +5 -3
- 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 +7 -4
- package/types/src/hooks/useSynchronizedPointerHandler.d.ts +3 -7
- package/types/src/hooks/useVisualViewportRect.d.ts +39 -0
- package/types/src/index.d.ts +1 -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 +1 -0
- package/types/src/utils/textSelectionDrag.d.ts +52 -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/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.
|
|
4
|
+
"version": "0.8.0-beta.10",
|
|
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.
|
|
43
|
+
"@sheetxl/utils": "^0.8.0-beta.10",
|
|
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,23 +68,78 @@ 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
|
|
62
136
|
* scroll/resize event to observe — e.g. a caret-following formula hint whose rect changes as the caret
|
|
63
137
|
* moves by click or arrow. Off by default: the per-frame poll has a cost, so only anchors that track a
|
|
64
138
|
* moving point should enable it (a normal element/point anchor repositions fine on scroll/resize alone).
|
|
139
|
+
*
|
|
140
|
+
* A virtual anchor that exposes its own `contextElement` (the element it moves WITH — a grid range
|
|
141
|
+
* anchor names its pane) does not need this: that element's scroll / resize / layout-shift triggers
|
|
142
|
+
* are observed normally.
|
|
65
143
|
* @defaultValue false
|
|
66
144
|
*/
|
|
67
145
|
followAnchor?: boolean;
|
|
@@ -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
|
|
@@ -19,8 +19,8 @@ export declare const setEditMode: SetEditMode;
|
|
|
19
19
|
*
|
|
20
20
|
* @remarks
|
|
21
21
|
* 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.
|
|
22
|
+
* single {@link EditMode} (`{ key, description?, args?, cursor?, cancel?, done?, onModeChange? }`),
|
|
23
|
+
* and every part of the app reads from and writes to that one value.
|
|
24
24
|
*
|
|
25
25
|
* It exists so unrelated features can coordinate **without depending on one another**. A feature
|
|
26
26
|
* announces that its interaction has started by publishing a mode, and clears it when finished;
|
|
@@ -36,7 +36,9 @@ export declare const setEditMode: SetEditMode;
|
|
|
36
36
|
* - the format painter.
|
|
37
37
|
*
|
|
38
38
|
* Typical **consumers** (read the active mode):
|
|
39
|
-
* - the status bar, which shows {@link EditMode.description} (and its idle label when there is none)
|
|
39
|
+
* - the status bar, which shows {@link EditMode.description} (and its idle label when there is none),
|
|
40
|
+
* with a ✕ that runs {@link EditMode.cancel} and a ✓ that runs {@link EditMode.done} when the
|
|
41
|
+
* mode carries them;
|
|
40
42
|
* - the grid, which applies {@link EditMode.cursor};
|
|
41
43
|
* - features that must defer to another interaction — e.g. fill is suppressed while a cell is being
|
|
42
44
|
* 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
|
|
@@ -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
|
/**
|
|
@@ -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
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The part of the layout viewport that is actually visible, in CSS px.
|
|
3
|
+
*
|
|
4
|
+
* @remarks
|
|
5
|
+
* On a phone the visual viewport is what shrinks when the virtual keyboard rises (iOS Safari never
|
|
6
|
+
* resizes the layout viewport for it) and what moves when the page is pinch-zoomed or scrolled
|
|
7
|
+
* under a pinned chrome. `offsetTop` / `offsetLeft` are its position within the layout viewport.
|
|
8
|
+
*/
|
|
9
|
+
export interface VisualViewportRect {
|
|
10
|
+
width: number;
|
|
11
|
+
height: number;
|
|
12
|
+
offsetTop: number;
|
|
13
|
+
offsetLeft: number;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* The current {@link VisualViewportRect}, or `null` where `window.visualViewport` is unavailable.
|
|
17
|
+
* Returns the same object until a value changes.
|
|
18
|
+
*/
|
|
19
|
+
export declare const getVisualViewportRect: () => VisualViewportRect | null;
|
|
20
|
+
/**
|
|
21
|
+
* Listen for the visual viewport resizing or scrolling.
|
|
22
|
+
*
|
|
23
|
+
* @returns Stops listening.
|
|
24
|
+
*/
|
|
25
|
+
export declare const subscribeVisualViewport: (listener: () => void) => (() => void);
|
|
26
|
+
/**
|
|
27
|
+
* The visual viewport's size and offset, re-rendering as it changes. `null` on the server, in a
|
|
28
|
+
* browser without `window.visualViewport`, or while `enabled` is `false`.
|
|
29
|
+
*
|
|
30
|
+
* @param enabled Subscribe only while `true`; a component that needs the rect in one configuration
|
|
31
|
+
* (the studio with its formula bar at the bottom) pays nothing in the others.
|
|
32
|
+
*
|
|
33
|
+
* @remarks
|
|
34
|
+
* The signal behind a chrome that must stay above the virtual keyboard: the rect's `height` is the
|
|
35
|
+
* room left once the keyboard is up, and `offsetTop` is how far the browser has moved the visible
|
|
36
|
+
* part under a layout that did not shrink.
|
|
37
|
+
*/
|
|
38
|
+
export declare const useVisualViewportRect: (enabled?: boolean) => VisualViewportRect | null;
|
|
39
|
+
//# sourceMappingURL=useVisualViewportRect.d.ts.map
|
package/types/src/index.d.ts
CHANGED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import { default as React } from 'react';
|
|
2
|
+
/**
|
|
3
|
+
* Options for {@link lazyComponent}.
|
|
4
|
+
*/
|
|
5
|
+
export interface LazyComponentOptions<P> {
|
|
6
|
+
/**
|
|
7
|
+
* Rendered in place of the component when its module fails to load.
|
|
8
|
+
*
|
|
9
|
+
* @remarks
|
|
10
|
+
* When omitted, the error is thrown to the nearest error boundary.
|
|
11
|
+
* Call {@link useLazyRetry} from inside the rendered content to try again.
|
|
12
|
+
*/
|
|
13
|
+
renderError?: (error: unknown, props: P) => React.ReactNode;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Returns a function that retries loading the nearest {@link lazyComponent}, or `null` when there
|
|
17
|
+
* is none.
|
|
18
|
+
*
|
|
19
|
+
* @remarks
|
|
20
|
+
* Intended for the content rendered by {@link LazyComponentOptions.renderError}.
|
|
21
|
+
*/
|
|
22
|
+
export declare function useLazyRetry(): (() => void) | null;
|
|
23
|
+
/**
|
|
24
|
+
* Like `React.lazy`, but a module that fails to load is not a permanent failure.
|
|
25
|
+
*
|
|
26
|
+
* @param loader Loads a module whose default export is the component.
|
|
27
|
+
* @param options How a failure is rendered.
|
|
28
|
+
*
|
|
29
|
+
* @remarks
|
|
30
|
+
* A mounted instance keeps showing the failure until {@link useLazyRetry} is called. A new mount
|
|
31
|
+
* after a failure loads the module again. Render inside a `Suspense` boundary, as with `React.lazy`.
|
|
32
|
+
*
|
|
33
|
+
* @example
|
|
34
|
+
* ```tsx
|
|
35
|
+
* const CustomColorPanel = lazyComponent(() => import('./CustomColorPanel'), {
|
|
36
|
+
* renderError: (error) => <LoadError error={error} />
|
|
37
|
+
* });
|
|
38
|
+
* ```
|
|
39
|
+
*/
|
|
40
|
+
export declare function lazyComponent<C extends React.ComponentType<any>>(loader: () => Promise<{
|
|
41
|
+
default: C;
|
|
42
|
+
}>, options?: LazyComponentOptions<React.ComponentProps<C>>): React.FC<React.ComponentProps<C>>;
|
|
43
|
+
//# sourceMappingURL=lazyComponent.d.ts.map
|