@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.
Files changed (80) hide show
  1. package/LICENSE.md +17 -7
  2. package/browser/esm/{BNQpxuZLRMIfP-UV.mjs → B40op1SaLNqvFHlg.mjs} +2 -2
  3. package/browser/esm/{BJGQ68VgzFVsTPdQ.mjs → BIiHroifM2tesCns.mjs} +22 -21
  4. package/browser/esm/DKfTbMgV21FBnNOl.mjs +100 -0
  5. package/browser/esm/index.mjs +2668 -2134
  6. package/licenses/dependencies.txt +1 -39
  7. package/node/esm/DGnB_ajTnvY63CO9.mjs +100 -0
  8. package/node/esm/{CLe03cReuKaGdquW.mjs → DmRJGz37SB1KXyjc.mjs} +2 -2
  9. package/node/esm/index.mjs +2352 -1826
  10. package/package.json +9 -12
  11. package/types/src/animation/useAnimatedMeasure.d.ts +2 -3
  12. package/types/src/command/CommandButtonRegistry.d.ts +3 -1
  13. package/types/src/command/CommandScope.d.ts +23 -2
  14. package/types/src/components/RenderSlot.d.ts +32 -0
  15. package/types/src/components/index.d.ts +1 -1
  16. package/types/src/float/FloatPanel.d.ts +7 -6
  17. package/types/src/float/FloatPopper.d.ts +84 -10
  18. package/types/src/float/FloatPopup.d.ts +1 -1
  19. package/types/src/float/FloatProvider.d.ts +3 -2
  20. package/types/src/float/FloatStackContext.d.ts +8 -0
  21. package/types/src/float/FloatUtils.d.ts +3 -2
  22. package/types/src/float/_FloatTheme.d.ts +16 -0
  23. package/types/src/float/_FloatUtils.d.ts +6 -0
  24. package/types/src/float/index.d.ts +0 -1
  25. package/types/src/float/useFloatStack.d.ts +6 -5
  26. package/types/src/hooks/index.d.ts +4 -0
  27. package/types/src/hooks/useCallbackRef.d.ts +19 -6
  28. package/types/src/hooks/useEditMode.d.ts +26 -6
  29. package/types/src/hooks/useInputModality.d.ts +26 -0
  30. package/types/src/hooks/useLocationSearch.d.ts +9 -0
  31. package/types/src/hooks/useMeasure.d.ts +32 -0
  32. package/types/src/hooks/useNotifier.d.ts +35 -34
  33. package/types/src/hooks/useSynchronizedPointerHandler.d.ts +3 -7
  34. package/types/src/hooks/useVisualViewportRect.d.ts +40 -0
  35. package/types/src/icons/packs/Base.json.d.ts +3624 -0
  36. package/types/src/index.d.ts +2 -0
  37. package/types/src/lazy/lazyComponent.d.ts +9 -2
  38. package/types/src/persistence/Types.d.ts +4 -2
  39. package/types/src/persistence/usePersistentState.d.ts +3 -0
  40. package/types/src/render/PendingRender.d.ts +43 -0
  41. package/types/src/render/index.d.ts +2 -0
  42. package/types/src/scroll/AxisViewport.d.ts +6 -2
  43. package/types/src/scroll/IScrollPane.d.ts +17 -4
  44. package/types/src/scroll/IScrollbar.d.ts +5 -2
  45. package/types/src/scroll/ScrollButton.d.ts +3 -3
  46. package/types/src/scroll/Utils.d.ts +1 -0
  47. package/types/src/scroll/Viewport.d.ts +50 -2
  48. package/types/src/scroll/VirtualScrollbar.d.ts +2 -1
  49. package/types/src/scroll/scrollbarTheming.d.ts +2 -23
  50. package/types/src/scroll/touchOwner.d.ts +19 -0
  51. package/types/src/scroll/useWheelScroll.d.ts +15 -2
  52. package/types/src/scroll/wheelOwner.d.ts +18 -0
  53. package/types/src/scroller/Scroller.d.ts +44 -5
  54. package/types/src/splitPane/SplitPane.d.ts +3 -1
  55. package/types/src/theme/ThemeStyle.d.ts +22 -0
  56. package/types/src/theme/TokenTheme.d.ts +10 -1
  57. package/types/src/theme/buildThemeCSS.d.ts +9 -0
  58. package/types/src/theme/defaultTheme.d.ts +6 -0
  59. package/types/src/theme/index.d.ts +3 -1
  60. package/types/src/theme/themeAttrs.d.ts +5 -4
  61. package/types/src/theme/tokenVar.d.ts +20 -0
  62. package/types/src/theme/useResolvedThemeMode.d.ts +27 -5
  63. package/types/src/theme/zIndex.d.ts +24 -0
  64. package/types/src/utils/index.d.ts +1 -0
  65. package/types/src/utils/measureUIText.d.ts +24 -0
  66. package/types/src/virtualKeyboard/KeyboardAccessory.d.ts +73 -0
  67. package/types/src/virtualKeyboard/VirtualKeyboard.d.ts +128 -0
  68. package/types/src/virtualKeyboard/_keyboardApi.d.ts +13 -0
  69. package/types/src/virtualKeyboard/index.d.ts +4 -0
  70. package/types/src/virtualKeyboard/useKeyboardResize.d.ts +41 -0
  71. package/browser/cjs/Bvkp0pA34e-C2acX.cjs +0 -1
  72. package/browser/cjs/DKOBBbAJUJuh1jaM.cjs +0 -1
  73. package/browser/cjs/DZSvmqU8nRas1uz6.cjs +0 -1
  74. package/browser/cjs/index.cjs +0 -5
  75. package/browser/esm/DQUMyLxk3DoqrFlU.mjs +0 -2261
  76. package/node/esm/n9EBgZ7u36nsO1cF.mjs +0 -2261
  77. package/types/src/components/ITooltip.d.ts +0 -38
  78. package/types/src/float/FloatTooltip.d.ts +0 -22
  79. package/types/src/theme/TokenThemeProvider.d.ts +0 -97
  80. 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.8.0-beta.9",
5
- "license": "SEE LICENSE IN <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
- "import": "./browser/esm/index.mjs",
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/cjs/index.cjs",
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.9",
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.0",
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.2.17",
59
- "@types/react-dom": "^19.2.3"
55
+ "@types/react": "^19.3.0",
56
+ "@types/react-dom": "^19.3.0"
60
57
  }
61
58
  }
@@ -1,4 +1,4 @@
1
- declare type UseMeasureRect = Pick<DOMRectReadOnly, 'x' | 'y' | 'top' | 'left' | 'right' | 'bottom' | 'height' | 'width'>;
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, UseMeasureRect | null];
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* keys only; it doesn't touch other contributions to this scope.
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,4 @@
1
- export * from './ITooltip';
2
1
  export * from './FocusKeyNavigation';
2
+ export * from './RenderSlot';
3
3
  export * from './RoundedTab';
4
4
  //# sourceMappingURL=index.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
- createPopupPanel?: (props: FloatPopupPanelProps) => React.ReactElement | null;
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
- createPopupPanel?: (props: FloatPopupPanelProps) => React.ReactElement | null;
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
- * `createPopupPanel`, not set on the card.
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.createPopupPanel}.
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
- * createPopupPanel={() => <MyMenu />}
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
- * Virtual or real element used to anchor the popper.
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 type FloatPopperAnchor = HTMLElement | {
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
- * compatibility). `skidding` shifts along the anchor edge, `distance` pushes
50
- * away from it.
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 defaultCreateFloatPopupPanel: (props: FloatPopupPanelProps) => React.ReactElement;
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
- /** Default panel-content factory for descendants. Inherited when omitted. */
15
- createPopupPanel?: (props: FloatPopupPanelProps) => any;
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
- /** Default panel-content factory, used when a float doesn't supply its own. */
32
- createPopupPanel?: (props: FloatPopupPanelProps) => any;
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
@@ -2,7 +2,6 @@ export * from './FloatUtils';
2
2
  export * from './FloatPopper';
3
3
  export * from './FloatPopup';
4
4
  export * from './FloatPanel';
5
- export * from './FloatTooltip';
6
5
  export * from './useFloatStack';
7
6
  export * from './FloatStackContext';
8
7
  export * from './FloatProvider';
@@ -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 = (props: FloatPanelProps) => React.ReactElement;
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
- * If this returns `null` then will create a registered movable stacking.
35
- * This is done for toolbars and other permanent visible components that are integrated into the movable stack.
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
- createPopupPanel?: (props: FloatPopupPanelProps) => any;
38
+ renderPopupPanel?: RenderSlotFn<FloatPopupPanelProps> | null;
38
39
  /**
39
40
  * Passed to the underlying popup panel. `children` is excluded — content comes
40
- * from `createPopupPanel`, and this keeps the option compatible with richer
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
- * This is a callback hook that is similar to useCallback except in
4
- * one important way. When it's dependencies change it does
5
- * NOT update the callback handler itself. Useful
6
- * in the instance where you want to pass a callback and
7
- * want to avoid have stale values do to closure but don't
8
- * want a re-render to occur.
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. Requires the bus singleton
11
- * to be mounted (a `SingletonHooksContainer` in the tree), exactly like the hook.
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? }`), and every part of
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