@sheetxl/utils-react 0.8.0-beta.9 → 1.0.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/LICENSE.md +17 -7
- package/browser/esm/{BNQpxuZLRMIfP-UV.mjs → B40op1SaLNqvFHlg.mjs} +2 -2
- package/browser/esm/{BJGQ68VgzFVsTPdQ.mjs → BIiHroifM2tesCns.mjs} +22 -21
- package/browser/esm/DKfTbMgV21FBnNOl.mjs +100 -0
- package/browser/esm/index.mjs +2668 -2134
- package/licenses/dependencies.txt +1 -39
- package/node/esm/DGnB_ajTnvY63CO9.mjs +100 -0
- package/node/esm/{CLe03cReuKaGdquW.mjs → DmRJGz37SB1KXyjc.mjs} +2 -2
- package/node/esm/index.mjs +2352 -1826
- package/package.json +9 -12
- package/types/src/animation/useAnimatedMeasure.d.ts +2 -3
- package/types/src/command/CommandButtonRegistry.d.ts +3 -1
- package/types/src/command/CommandScope.d.ts +23 -2
- package/types/src/components/RenderSlot.d.ts +32 -0
- package/types/src/components/index.d.ts +1 -1
- package/types/src/float/FloatPanel.d.ts +7 -6
- package/types/src/float/FloatPopper.d.ts +84 -10
- package/types/src/float/FloatPopup.d.ts +1 -1
- package/types/src/float/FloatProvider.d.ts +3 -2
- package/types/src/float/FloatStackContext.d.ts +8 -0
- package/types/src/float/FloatUtils.d.ts +3 -2
- package/types/src/float/_FloatTheme.d.ts +16 -0
- package/types/src/float/_FloatUtils.d.ts +6 -0
- package/types/src/float/index.d.ts +0 -1
- package/types/src/float/useFloatStack.d.ts +6 -5
- 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 +26 -6
- 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 +35 -34
- package/types/src/hooks/useSynchronizedPointerHandler.d.ts +3 -7
- package/types/src/hooks/useVisualViewportRect.d.ts +40 -0
- package/types/src/icons/packs/Base.json.d.ts +3624 -0
- package/types/src/index.d.ts +2 -0
- package/types/src/lazy/lazyComponent.d.ts +9 -2
- package/types/src/persistence/Types.d.ts +4 -2
- package/types/src/persistence/usePersistentState.d.ts +3 -0
- package/types/src/render/PendingRender.d.ts +43 -0
- package/types/src/render/index.d.ts +2 -0
- package/types/src/scroll/AxisViewport.d.ts +6 -2
- package/types/src/scroll/IScrollPane.d.ts +17 -4
- package/types/src/scroll/IScrollbar.d.ts +5 -2
- package/types/src/scroll/ScrollButton.d.ts +3 -3
- package/types/src/scroll/Utils.d.ts +1 -0
- package/types/src/scroll/Viewport.d.ts +50 -2
- package/types/src/scroll/VirtualScrollbar.d.ts +2 -1
- package/types/src/scroll/scrollbarTheming.d.ts +2 -23
- 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/splitPane/SplitPane.d.ts +3 -1
- package/types/src/theme/ThemeStyle.d.ts +22 -0
- package/types/src/theme/TokenTheme.d.ts +10 -1
- package/types/src/theme/buildThemeCSS.d.ts +9 -0
- package/types/src/theme/defaultTheme.d.ts +6 -0
- package/types/src/theme/index.d.ts +3 -1
- package/types/src/theme/themeAttrs.d.ts +5 -4
- package/types/src/theme/tokenVar.d.ts +20 -0
- package/types/src/theme/useResolvedThemeMode.d.ts +27 -5
- package/types/src/theme/zIndex.d.ts +24 -0
- package/types/src/utils/index.d.ts +1 -0
- package/types/src/utils/measureUIText.d.ts +24 -0
- package/types/src/virtualKeyboard/KeyboardAccessory.d.ts +73 -0
- package/types/src/virtualKeyboard/VirtualKeyboard.d.ts +128 -0
- package/types/src/virtualKeyboard/_keyboardApi.d.ts +13 -0
- package/types/src/virtualKeyboard/index.d.ts +4 -0
- package/types/src/virtualKeyboard/useKeyboardResize.d.ts +41 -0
- package/browser/cjs/Bvkp0pA34e-C2acX.cjs +0 -1
- package/browser/cjs/DKOBBbAJUJuh1jaM.cjs +0 -1
- package/browser/cjs/DZSvmqU8nRas1uz6.cjs +0 -1
- package/browser/cjs/index.cjs +0 -5
- package/browser/esm/DQUMyLxk3DoqrFlU.mjs +0 -2261
- package/node/esm/n9EBgZ7u36nsO1cF.mjs +0 -2261
- package/types/src/components/ITooltip.d.ts +0 -38
- package/types/src/float/FloatTooltip.d.ts +0 -22
- package/types/src/theme/TokenThemeProvider.d.ts +0 -97
- package/types/src/utils/PinchZoom.d.ts +0 -3
package/package.json
CHANGED
|
@@ -1,21 +1,20 @@
|
|
|
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.
|
|
5
|
-
"license": "
|
|
4
|
+
"version": "1.0.0",
|
|
5
|
+
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"exports": {
|
|
8
8
|
".": {
|
|
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": "^1.0.0",
|
|
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
|
|
@@ -81,10 +81,12 @@ export interface ICommandButtonRegistry {
|
|
|
81
81
|
* an entry names via `defaultKey`, not an arbitrary command key. Suppressed when `replace` is true.
|
|
82
82
|
* @param entry The entry (must have a `key`).
|
|
83
83
|
* @param replace Whether to replace an existing entry with the same key. Default is false.
|
|
84
|
+
* @returns A function that removes this registration. It does nothing once the key is unregistered
|
|
85
|
+
* or registered again by someone else.
|
|
84
86
|
*/
|
|
85
87
|
register(entry: CommandButtonEntry & {
|
|
86
88
|
key: string;
|
|
87
|
-
}, replace?: boolean): void;
|
|
89
|
+
}, replace?: boolean): () => void;
|
|
88
90
|
/**
|
|
89
91
|
* Unregister an item.
|
|
90
92
|
* @param key The unique key for the item.
|
|
@@ -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
|
/**
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import { default as React } from 'react';
|
|
2
|
+
/**
|
|
3
|
+
* A render slot: given its props, returns what to draw. Hooks are allowed — a host mounts the slot through
|
|
4
|
+
* {@link RenderSlot}, so they belong to that component.
|
|
5
|
+
*/
|
|
6
|
+
export type RenderSlotFn<P> = (props: P) => React.ReactNode;
|
|
7
|
+
export interface RenderSlotProps<P> {
|
|
8
|
+
/** The slot's renderer. `null` or `undefined` renders nothing. */
|
|
9
|
+
render: RenderSlotFn<P> | null | undefined;
|
|
10
|
+
/** Handed to `render`. */
|
|
11
|
+
props: P;
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Mounts a render slot as its own component, so a renderer may call hooks however (and wherever) the host
|
|
15
|
+
* renders it — inside a `useMemo`, a conditional, or a portal built in an effect.
|
|
16
|
+
*
|
|
17
|
+
* @remarks
|
|
18
|
+
* Its type never changes, so an inline arrow passed as `render` does not remount it. A renderer's hooks
|
|
19
|
+
* therefore persist across renderers: swapping between two renderers that call different hooks breaks the
|
|
20
|
+
* hook order, the same as a component that changes the hooks it calls. Give the slot a `key` per renderer
|
|
21
|
+
* if a host must swap them.
|
|
22
|
+
*
|
|
23
|
+
* Draw functions on a hot path (`renderCell`) are called directly, not through a slot, and must not call
|
|
24
|
+
* hooks.
|
|
25
|
+
*
|
|
26
|
+
* @example
|
|
27
|
+
* ```tsx
|
|
28
|
+
* <RenderSlot render={renderCommentCard} props={{ sheet, coords, comment }} />
|
|
29
|
+
* ```
|
|
30
|
+
*/
|
|
31
|
+
export declare const RenderSlot: <P>(slot: RenderSlotProps<P>) => React.ReactNode;
|
|
32
|
+
//# sourceMappingURL=RenderSlot.d.ts.map
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { default as React } from 'react';
|
|
2
|
+
import { RenderSlotFn } from '../components';
|
|
2
3
|
import { FloatPopperProps, FloatPopperPosition, FloatPopperAnchor } from './FloatPopper';
|
|
3
4
|
import { FloatPopupPanelProps } from './FloatPopup';
|
|
4
5
|
import { FloatReference } from './useFloatStack';
|
|
@@ -12,7 +13,8 @@ export interface FloatPanelProps extends Omit<React.HTMLAttributes<HTMLDivElemen
|
|
|
12
13
|
anchorPosition?: FloatPopperPosition;
|
|
13
14
|
label?: string;
|
|
14
15
|
children?: React.ReactNode;
|
|
15
|
-
|
|
16
|
+
/** The float's content. `null` renders the card empty. */
|
|
17
|
+
renderPopupPanel?: RenderSlotFn<FloatPopupPanelProps> | null;
|
|
16
18
|
propsPopper?: Partial<FloatPopperProps>;
|
|
17
19
|
onClosing?: () => void;
|
|
18
20
|
onClose?: () => void;
|
|
@@ -28,7 +30,7 @@ export interface FloatPanelSurfaceProps extends Omit<React.HTMLAttributes<HTMLDi
|
|
|
28
30
|
floatReference?: FloatReference;
|
|
29
31
|
/** The element the float is positioned in, handed on to the content. */
|
|
30
32
|
popupContainer?: HTMLElement;
|
|
31
|
-
|
|
33
|
+
renderPopupPanel?: RenderSlotFn<FloatPopupPanelProps> | null;
|
|
32
34
|
children?: React.ReactNode;
|
|
33
35
|
ref?: React.Ref<HTMLDivElement>;
|
|
34
36
|
}
|
|
@@ -38,7 +40,7 @@ export interface FloatPanelSurfaceProps extends Omit<React.HTMLAttributes<HTMLDi
|
|
|
38
40
|
* @remarks
|
|
39
41
|
* Separate from the positioning so a float positioned by something other than {@link FloatPopper}
|
|
40
42
|
* (a grid float that follows its cell) wears the same card. Other attributes are handed to
|
|
41
|
-
* `
|
|
43
|
+
* `renderPopupPanel`, not set on the card.
|
|
42
44
|
*/
|
|
43
45
|
export declare const FloatPanelSurface: React.NamedExoticComponent<Omit<FloatPanelSurfaceProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
|
|
44
46
|
/**
|
|
@@ -48,7 +50,7 @@ export declare const FloatPanelSurface: React.NamedExoticComponent<Omit<FloatPan
|
|
|
48
50
|
* `FloatPanel` pairs a {@link FloatPopper} (which positions content next to an
|
|
49
51
|
* anchor element or point, renders it in a portal, flips it to stay on screen
|
|
50
52
|
* and animates it in) with a styled, scrollable "card" surface. The content of
|
|
51
|
-
* that card is supplied by {@link FloatPanelProps.
|
|
53
|
+
* that card is supplied by {@link FloatPanelProps.renderPopupPanel}.
|
|
52
54
|
*
|
|
53
55
|
* @remarks
|
|
54
56
|
* Most consumers do not render `FloatPanel` directly — {@link useFloatStack}
|
|
@@ -58,7 +60,6 @@ export declare const FloatPanelSurface: React.NamedExoticComponent<Omit<FloatPan
|
|
|
58
60
|
*
|
|
59
61
|
* When to use which:
|
|
60
62
|
* - {@link FloatPopper} — you only need raw positioning + portal (no card chrome).
|
|
61
|
-
* - {@link FloatTooltip} — a small, controlled hint anchored to a point.
|
|
62
63
|
* - `FloatPanel` / {@link useFloatStack} — interactive floating content (menus, popovers).
|
|
63
64
|
*
|
|
64
65
|
* The surface is theme-aware via CSS variables (e.g. `--sxl-color-base-100`),
|
|
@@ -69,7 +70,7 @@ export declare const FloatPanelSurface: React.NamedExoticComponent<Omit<FloatPan
|
|
|
69
70
|
* <FloatPanel
|
|
70
71
|
* open={open}
|
|
71
72
|
* anchorEl={anchorRef.current}
|
|
72
|
-
*
|
|
73
|
+
* renderPopupPanel={() => <MyMenu />}
|
|
73
74
|
* />
|
|
74
75
|
* ```
|
|
75
76
|
*/
|
|
@@ -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
|
|
@@ -15,5 +15,5 @@ export interface FloatPopupPanelProps extends React.HTMLAttributes<HTMLDivElemen
|
|
|
15
15
|
/**
|
|
16
16
|
* Default popup panel (a simple flex column container).
|
|
17
17
|
*/
|
|
18
|
-
export declare const
|
|
18
|
+
export declare const defaultRenderFloatPopupPanel: (props: FloatPopupPanelProps) => React.ReactElement;
|
|
19
19
|
//# sourceMappingURL=FloatPopup.d.ts.map
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { default as React } from 'react';
|
|
2
|
+
import { RenderSlotFn } from '../components';
|
|
2
3
|
import { ThemeMode } from '../theme';
|
|
3
4
|
import { FloatReference, RenderFloatPanel } from './useFloatStack';
|
|
4
5
|
import { FloatPanelProps } from './FloatPanel';
|
|
@@ -11,8 +12,8 @@ export interface FloatProviderProps {
|
|
|
11
12
|
* inherited from an outer provider (and ultimately the neutral `FloatPanel`).
|
|
12
13
|
*/
|
|
13
14
|
renderFloatPanel?: RenderFloatPanel;
|
|
14
|
-
/**
|
|
15
|
-
|
|
15
|
+
/** The default float content for descendants. Inherited when omitted. */
|
|
16
|
+
renderPopupPanel?: RenderSlotFn<FloatPopupPanelProps>;
|
|
16
17
|
/** Extra props merged into the rendered panel. Inherited when omitted. */
|
|
17
18
|
propsFloatPanel?: Partial<FloatPanelProps>;
|
|
18
19
|
/**
|
|
@@ -22,4 +22,12 @@ export declare const FloatStackProvider: import('react').Provider<FloatReference
|
|
|
22
22
|
* submenu. Such components are not reached by props, only by context.
|
|
23
23
|
*/
|
|
24
24
|
export declare const useFloat: () => FloatReference | null;
|
|
25
|
+
/**
|
|
26
|
+
* Whether a popup (a menu, a picker, a panel) is showing that this component is not inside (reactive).
|
|
27
|
+
*
|
|
28
|
+
* @remarks
|
|
29
|
+
* For transient UI that stands aside while the user is in a popup. Content of the popup itself reads
|
|
30
|
+
* `false`, so a tooltip belonging to the menu still shows. A float with no popup (a toolbar) does not count.
|
|
31
|
+
*/
|
|
32
|
+
export declare const useFloatPopupOpen: () => boolean;
|
|
25
33
|
//# sourceMappingURL=FloatStackContext.d.ts.map
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { RenderSlotFn } from '../components';
|
|
1
2
|
import { FloatPanelProps } from './FloatPanel';
|
|
2
3
|
import { FloatPopupPanelProps } from './FloatPopup';
|
|
3
4
|
import { RenderFloatPanel } from './useFloatStack';
|
|
@@ -28,8 +29,8 @@ export interface FloatThemeScope {
|
|
|
28
29
|
*/
|
|
29
30
|
export interface FloatSurface {
|
|
30
31
|
renderFloatPanel?: RenderFloatPanel;
|
|
31
|
-
/**
|
|
32
|
-
|
|
32
|
+
/** The default float content, used when a float doesn't supply its own. */
|
|
33
|
+
renderPopupPanel?: RenderSlotFn<FloatPopupPanelProps>;
|
|
33
34
|
propsFloatPanel?: Partial<FloatPanelProps>;
|
|
34
35
|
/**
|
|
35
36
|
* The theme floats in this subtree open with (scope class(es) + surface + mode). Carried onto the float
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { ThemeAttrs } from '../theme';
|
|
2
|
+
import { FloatThemeScope } from './FloatUtils';
|
|
3
|
+
/**
|
|
4
|
+
* The nearest `data-sxl-theme-mode` / `-surface` above an element. Read as an **external store**, not at
|
|
5
|
+
* render: the attrs live on an ANCESTOR's DOM, stamped in the same commit that re-renders the caller, so a
|
|
6
|
+
* render-time read sees the previous theme and nothing re-renders the caller afterwards. The store is
|
|
7
|
+
* re-checked after commit and on any later attribute change.
|
|
8
|
+
*/
|
|
9
|
+
export declare const useElementThemeAttrs: (el: Element | null) => ThemeAttrs;
|
|
10
|
+
/**
|
|
11
|
+
* The theme an element portaled out of its themed subtree opens with (THEMING-DESIGN §7): the nearest
|
|
12
|
+
* `FloatProvider`'s theme scope, a React-inherited context that crosses the portal even though the cascade
|
|
13
|
+
* can't.
|
|
14
|
+
*/
|
|
15
|
+
export declare const useFloatThemeScope: () => FloatThemeScope | undefined;
|
|
16
|
+
//# sourceMappingURL=_FloatTheme.d.ts.map
|
|
@@ -41,6 +41,12 @@ export interface FloatRoot extends FloatReference {
|
|
|
41
41
|
getChildRef(reference: FloatReference): FloatReference | null;
|
|
42
42
|
/** `reference` plus its full open-child chain. */
|
|
43
43
|
descendants(reference: FloatReference | null): Set<FloatReference>;
|
|
44
|
+
/** Record `reference` as showing a popup; the result records that it stopped. */
|
|
45
|
+
addOpenPopup(reference: FloatReference): () => void;
|
|
46
|
+
/** Whether a popup is showing that `enclosing` is not inside (`null` is inside none). */
|
|
47
|
+
isPopupOpenOutside(enclosing: FloatReference | null): boolean;
|
|
48
|
+
/** Called as popups show and stop showing. */
|
|
49
|
+
subscribeOpenPopups(listener: () => void): () => void;
|
|
44
50
|
}
|
|
45
51
|
/**
|
|
46
52
|
* Creates an isolated root float (a {@link FloatReference} that also holds the
|
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
import { default as React } from 'react';
|
|
2
|
+
import { RenderSlotFn } from '../components';
|
|
2
3
|
import { FloatPopupPanelProps } from './FloatPopup';
|
|
3
4
|
import { FloatPanelProps } from './FloatPanel';
|
|
4
5
|
import { FloatPopperProps } from './FloatPopper';
|
|
5
6
|
/**
|
|
6
7
|
* Renders the floating panel for an open float.
|
|
7
8
|
*/
|
|
8
|
-
export type RenderFloatPanel =
|
|
9
|
+
export type RenderFloatPanel = RenderSlotFn<FloatPanelProps>;
|
|
9
10
|
export interface FloatStackOptions {
|
|
10
11
|
/**
|
|
11
12
|
* Whether the panel grabs focus when it opens. @defaultValue `true` (menus / dialogs / anything the
|
|
@@ -31,13 +32,13 @@ export interface FloatStackOptions {
|
|
|
31
32
|
onOpen?: () => void;
|
|
32
33
|
onClose?: () => void;
|
|
33
34
|
/**
|
|
34
|
-
*
|
|
35
|
-
*
|
|
35
|
+
* The float's content. `null` shows no popup but keeps the float in the stack — for toolbars and other
|
|
36
|
+
* always-visible components that take part in the movable stacking.
|
|
36
37
|
*/
|
|
37
|
-
|
|
38
|
+
renderPopupPanel?: RenderSlotFn<FloatPopupPanelProps> | null;
|
|
38
39
|
/**
|
|
39
40
|
* Passed to the underlying popup panel. `children` is excluded — content comes
|
|
40
|
-
* from `
|
|
41
|
+
* from `renderPopupPanel`, and this keeps the option compatible with richer
|
|
41
42
|
* surface popper types (e.g. MUI's render-prop `children`).
|
|
42
43
|
*/
|
|
43
44
|
propsPopper?: Partial<Omit<FloatPopperProps, 'children' | 'ref'>>;
|
|
@@ -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
|
|
@@ -7,10 +7,29 @@ import { EditModeHandler, SetEditMode } from '@sheetxl/utils';
|
|
|
7
7
|
* @remarks
|
|
8
8
|
* Exists so a non-component owner — e.g. the cell {@link IEditable} publishing its active session —
|
|
9
9
|
* can drive the bus from anywhere, not only where a hook happens to be mounted. Reads (and the React
|
|
10
|
-
* subscription) still go through {@link useEditMode}; this is write-only.
|
|
11
|
-
*
|
|
10
|
+
* subscription) still go through {@link useEditMode}; this is write-only. Before any component has
|
|
11
|
+
* called {@link useEditMode} there is no bus, and the write is dropped.
|
|
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}.
|
|
@@ -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
|