@sheetxl/utils-react 0.8.0-beta.2 → 0.8.0-beta.20

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 (78) hide show
  1. package/LICENSE.md +17 -7
  2. package/browser/esm/{C0YaChjA6T3amxUK.mjs → BkN0y4Hrj2g5dSIG.mjs} +2 -2
  3. package/browser/esm/{DaDIU3EpB96qbvar.mjs → C_Ask1OF1UxIDB6Z.mjs} +20 -19
  4. package/browser/esm/DakbiWfgAxYtLuB9.mjs +100 -0
  5. package/browser/esm/index.mjs +2375 -1776
  6. package/licenses/dependencies.txt +1 -39
  7. package/node/esm/{ab6S2ZLIze6opqOt.mjs → BILf4bRupmxScC5R.mjs} +2 -2
  8. package/node/esm/Dmps0ZIoLh14qvGI.mjs +100 -0
  9. package/node/esm/index.mjs +2266 -1676
  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 +17 -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/LanguageState.d.ts +1 -1
  27. package/types/src/hooks/index.d.ts +4 -0
  28. package/types/src/hooks/useCallbackRef.d.ts +19 -6
  29. package/types/src/hooks/useEditMode.d.ts +24 -4
  30. package/types/src/hooks/useInputModality.d.ts +26 -0
  31. package/types/src/hooks/useLocationSearch.d.ts +9 -0
  32. package/types/src/hooks/useMeasure.d.ts +32 -0
  33. package/types/src/hooks/useNotifier.d.ts +35 -34
  34. package/types/src/hooks/useSynchronizedPointerHandler.d.ts +3 -7
  35. package/types/src/hooks/useVisualViewportRect.d.ts +40 -0
  36. package/types/src/icons/packs/Base.json.d.ts +3624 -0
  37. package/types/src/index.d.ts +2 -0
  38. package/types/src/lazy/lazyComponent.d.ts +9 -2
  39. package/types/src/persistence/PersistentStateProvider.d.ts +3 -0
  40. package/types/src/persistence/Types.d.ts +22 -6
  41. package/types/src/persistence/_Context.d.ts +3 -2
  42. package/types/src/persistence/index.d.ts +2 -2
  43. package/types/src/persistence/{usePersistenceState.d.ts → usePersistentState.d.ts} +13 -8
  44. package/types/src/render/PendingRender.d.ts +43 -0
  45. package/types/src/render/index.d.ts +2 -0
  46. package/types/src/scroll/AxisViewport.d.ts +6 -2
  47. package/types/src/scroll/IScrollPane.d.ts +17 -4
  48. package/types/src/scroll/IScrollbar.d.ts +5 -2
  49. package/types/src/scroll/ScrollButton.d.ts +3 -3
  50. package/types/src/scroll/Utils.d.ts +1 -0
  51. package/types/src/scroll/Viewport.d.ts +50 -2
  52. package/types/src/scroll/VirtualScrollbar.d.ts +2 -1
  53. package/types/src/scroll/touchOwner.d.ts +19 -0
  54. package/types/src/scroll/useWheelScroll.d.ts +15 -2
  55. package/types/src/scroll/wheelOwner.d.ts +18 -0
  56. package/types/src/scroller/Scroller.d.ts +44 -5
  57. package/types/src/splitPane/SplitPane.d.ts +3 -1
  58. package/types/src/theme/TokenTheme.d.ts +8 -0
  59. package/types/src/theme/index.d.ts +1 -0
  60. package/types/src/theme/useResolvedThemeMode.d.ts +22 -4
  61. package/types/src/theme/zIndex.d.ts +24 -0
  62. package/types/src/utils/index.d.ts +1 -0
  63. package/types/src/utils/measureUIText.d.ts +24 -0
  64. package/types/src/virtualKeyboard/KeyboardAccessory.d.ts +73 -0
  65. package/types/src/virtualKeyboard/VirtualKeyboard.d.ts +128 -0
  66. package/types/src/virtualKeyboard/_keyboardApi.d.ts +13 -0
  67. package/types/src/virtualKeyboard/index.d.ts +4 -0
  68. package/types/src/virtualKeyboard/useKeyboardResize.d.ts +41 -0
  69. package/browser/cjs/DO0nIGKXa_DxYcn6.cjs +0 -1
  70. package/browser/cjs/DZSvmqU8nRas1uz6.cjs +0 -1
  71. package/browser/cjs/fw5WNnhzqSBOfVql.cjs +0 -1
  72. package/browser/cjs/index.cjs +0 -5
  73. package/browser/esm/DKup4mMzT8WdXz0e.mjs +0 -2217
  74. package/node/esm/ErznqJafEjYJ3e0H.mjs +0 -2217
  75. package/types/src/components/ITooltip.d.ts +0 -38
  76. package/types/src/float/FloatTooltip.d.ts +0 -22
  77. package/types/src/persistence/PersistenceStateProvider.d.ts +0 -3
  78. package/types/src/utils/PinchZoom.d.ts +0 -3
@@ -11,9 +11,11 @@ export * from './splitPane';
11
11
  export * from './hooks';
12
12
  export * from './icons';
13
13
  export * from './persistence';
14
+ export * from './render';
14
15
  export * from './scroll';
15
16
  export * from './theme';
16
17
  export * from './utils';
18
+ export * from './virtualKeyboard';
17
19
  export { Resizable, ResizableBox } from './react-resizable';
18
20
  export type { ResizeCallbackData, ResizeHandleAxis } from './react-resizable';
19
21
  //# sourceMappingURL=index.d.ts.map
@@ -10,7 +10,14 @@ export interface LazyComponentOptions<P> {
10
10
  * When omitted, the error is thrown to the nearest error boundary.
11
11
  * Call {@link useLazyRetry} from inside the rendered content to try again.
12
12
  */
13
- renderError?: (error: unknown, props: P) => React.ReactNode;
13
+ renderError?: (props: LazyErrorRenderProps<P>) => React.ReactNode;
14
+ }
15
+ /** What {@link LazyComponentOptions.renderError} is handed. */
16
+ export interface LazyErrorRenderProps<P> {
17
+ /** Why the load failed. */
18
+ error: unknown;
19
+ /** The props the lazy component was rendered with. */
20
+ props: P;
14
21
  }
15
22
  /**
16
23
  * Returns a function that retries loading the nearest {@link lazyComponent}, or `null` when there
@@ -33,7 +40,7 @@ export declare function useLazyRetry(): (() => void) | null;
33
40
  * @example
34
41
  * ```tsx
35
42
  * const CustomColorPanel = lazyComponent(() => import('./CustomColorPanel'), {
36
- * renderError: (error) => <LoadError error={error} />
43
+ * renderError: ({ error }) => <LoadError error={error} />
37
44
  * });
38
45
  * ```
39
46
  */
@@ -0,0 +1,3 @@
1
+ import { PersistentStateProviderProps } from './Types';
2
+ export declare function PersistentStateProvider(props: PersistentStateProviderProps): import("react").JSX.Element;
3
+ //# sourceMappingURL=PersistentStateProvider.d.ts.map
@@ -45,7 +45,7 @@ export type PersistenceSerializer<T = any> = {
45
45
  parse: (raw: string | null) => T;
46
46
  stringify: (val: T) => string;
47
47
  };
48
- export type PersistenceStateOptions<T = any> = {
48
+ export type PersistentStateOptions<T = any> = {
49
49
  /**
50
50
  * Convert the value to/from a string for storage
51
51
  *
@@ -54,14 +54,15 @@ export type PersistenceStateOptions<T = any> = {
54
54
  serializer?: PersistenceSerializer<T>;
55
55
  version?: number;
56
56
  migrate?: (oldValue: unknown, oldVersion: number | undefined) => T;
57
- lazy?: boolean;
58
57
  };
59
- export type PersistenceStateSetter<T> = (next: T | ((prev: T) => T)) => void;
60
- export type PersistenceProviderProps = {
58
+ export type PersistentStateSetter<T> = (next: T | ((prev: T) => T)) => void;
59
+ export type PersistentStateProviderProps = {
61
60
  /**
62
- * Storage backend to use
61
+ * Storage backend to use.
62
+ *
63
+ * @defaultValue an in-memory store, also used when there is no `window`
63
64
  */
64
- store: PersistenceStore;
65
+ store?: PersistenceStore;
65
66
  /**
66
67
  * Namespace prefix for all keys
67
68
  *
@@ -84,6 +85,21 @@ export type PersistenceProviderProps = {
84
85
  * @defaultValue `150`
85
86
  */
86
87
  debounceMs?: number;
88
+ /**
89
+ * Default values by key, used for any key with no stored value.
90
+ *
91
+ * @remarks
92
+ * Lets a host change the starting value of user-adjustable state without taking the choice away from
93
+ * the user — for example, enabling the dark grid by default while the user can still turn it off.
94
+ *
95
+ * Keys are the same logical keys passed to `usePersistentState` (without the namespace). Values are
96
+ * the typed values, not serialized strings. A value here wins over the default passed to
97
+ * `usePersistentState`; a stored value wins over both. Defaults are never written to the store, so
98
+ * changing one later applies to every user who has not made a choice.
99
+ *
100
+ * @defaultValue none
101
+ */
102
+ defaultValues?: Readonly<Record<string, unknown>>;
87
103
  /**
88
104
  * Children elements that will have access to the persistence context.
89
105
  *
@@ -1,9 +1,10 @@
1
- import { PersistenceProviderProps, PersistenceSerializer } from './Types';
2
- export type Ctx = Required<Omit<PersistenceProviderProps, 'children'>> & {
1
+ import { PersistentStateProviderProps, PersistenceSerializer } from './Types';
2
+ export type Ctx = Required<Omit<PersistentStateProviderProps, 'children'>> & {
3
3
  notify(key: string, value?: string): void;
4
4
  subscribeKey(key: string, fn: (value?: string) => void): () => void;
5
5
  };
6
6
  export declare const PersistenceContext: import('react').Context<Ctx | null>;
7
+ export declare const EmptyDefaultValues: Readonly<Record<string, unknown>>;
7
8
  export declare const DefaultSerializer: PersistenceSerializer;
8
9
  export declare function usePersistenceContext(): Ctx;
9
10
  //# sourceMappingURL=_Context.d.ts.map
@@ -1,6 +1,6 @@
1
1
  export * from './Types';
2
- export * from './usePersistenceState';
3
- export * from './PersistenceStateProvider';
2
+ export * from './usePersistentState';
3
+ export * from './PersistentStateProvider';
4
4
  export * from './InMemoryStore';
5
5
  export * from './LocalStorageStore';
6
6
  //# sourceMappingURL=index.d.ts.map
@@ -1,11 +1,12 @@
1
- import { PersistenceStateOptions, PersistenceStateSetter } from './Types';
1
+ import { PersistentStateOptions, PersistentStateSetter } from './Types';
2
2
  /**
3
3
  * Persisted state hook backed by the current persistence context.
4
4
  *
5
5
  * This works like `useState`, but:
6
6
  *
7
7
  * - The value is persisted under `namespace:key` using the current store.
8
- * - On first render, it initializes from `defaultValue`.
8
+ * - With no stored value, it uses the provider's `defaultValues[key]` if present, otherwise `defaultValue`.
9
+ * Defaults are never written to the store; only values passed to `setState` are.
9
10
  * - Then it **hydrates asynchronously** from the configured store
10
11
  * (memory, localStorage, IndexedDB, remote, etc.). Hydration is *seeding*: a value written with
11
12
  * `setState` while the read is still in flight is newer, so it wins and the read is discarded.
@@ -19,16 +20,20 @@ import { PersistenceStateOptions, PersistenceStateSetter } from './Types';
19
20
  *
20
21
  * - No reads or writes go to the persistence store.
21
22
  * - No cross-tab / cross-hook subscription is set up.
22
- * - `clear()` simply resets back to the default value (or `undefined`).
23
+ * - `clear()` simply resets back to `defaultValue` (or `undefined`).
23
24
  *
24
25
  * @typeParam T - Type of the stored value.
25
26
  * @param key - Logical storage key; use `null` to disable persistence entirely.
26
- * @param defaultValue - Initial value or lazy initializer function.
27
- * @param opts - Options controlling serialization, versioning, migration, and laziness.
27
+ * @param defaultValue - Value used when nothing is stored and the provider has no default for `key`; a
28
+ * function is called lazily to produce it.
29
+ * @param opts - Options controlling serialization, versioning, and migration.
28
30
  * @returns A tuple of `[state, setState, clear]`:
29
31
  * - `state` – The current value.
30
32
  * - `setState(next)` – Updates the value and persists it (unless `key === null`).
31
- * - `clear()` – Removes the persisted value and resets to `defaultValue`.
33
+ * - `clear()` – Removes the persisted value and resets to the default.
34
+ *
35
+ * Like `useState`'s setter, `setState` and `clear` keep a stable identity across renders, so they are
36
+ * safe in dependency lists.
32
37
  */
33
- export declare function usePersistenceState<T = unknown>(key: string | null, defaultValue?: T | (() => T), opts?: PersistenceStateOptions<T>): [T, PersistenceStateSetter<T>, () => void];
34
- //# sourceMappingURL=usePersistenceState.d.ts.map
38
+ export declare function usePersistentState<T = unknown>(key: string | null, defaultValue?: T | (() => T), opts?: PersistentStateOptions<T>): [T, PersistentStateSetter<T>, () => void];
39
+ //# sourceMappingURL=usePersistentState.d.ts.map
@@ -0,0 +1,43 @@
1
+ import { default as React } from 'react';
2
+ /**
3
+ * Drawing that finishes after its first paint: a picture whose bytes are still coming, a chart
4
+ * still laying out. A view holds its scope open while it draws; a capture of the scope (a
5
+ * screenshot, an export) waits on {@link whenRenderSettled} before it reads the screen.
6
+ *
7
+ * @remarks
8
+ * A scope is any object the work belongs to, usually the workbook. A view finds it from the
9
+ * nearest {@link PendingRenderScope}, so it need not know what it belongs to. Only views that have
10
+ * rendered can hold it open: render what is to be captured first.
11
+ */
12
+ export declare namespace PendingRender {
13
+ /**
14
+ * Holds `scope` open until the returned release is called. Releasing twice is harmless.
15
+ *
16
+ * @returns The release.
17
+ */
18
+ function begin(scope: object): () => void;
19
+ /** Whether anything holds `scope` open. */
20
+ function isPending(scope: object): boolean;
21
+ }
22
+ /**
23
+ * Resolves once nothing holds `scope` open, including drawing that starts while it waits. Wait for
24
+ * the next paint after it before reading the screen.
25
+ */
26
+ export declare const whenRenderSettled: (scope: object) => Promise<void>;
27
+ /** Props for {@link PendingRenderScope}. */
28
+ export interface PendingRenderScopeProps {
29
+ /** What the drawing below belongs to, usually the workbook; `null` for none. */
30
+ scope: object | null;
31
+ children?: React.ReactNode;
32
+ }
33
+ /** Names the scope the drawing below holds open with {@link usePendingRender}. */
34
+ export declare const PendingRenderScope: (props: PendingRenderScopeProps) => React.ReactElement;
35
+ /**
36
+ * Holds the scope open while `pending` is `true`, for {@link whenRenderSettled}; released when it
37
+ * turns `false` or the component unmounts.
38
+ *
39
+ * @param scope The scope; the nearest {@link PendingRenderScope}'s when omitted. With neither,
40
+ * nothing is held.
41
+ */
42
+ export declare const usePendingRender: (pending: boolean, scope?: object | null) => void;
43
+ //# sourceMappingURL=PendingRender.d.ts.map
@@ -0,0 +1,2 @@
1
+ export * from './PendingRender';
2
+ //# sourceMappingURL=index.d.ts.map
@@ -1,5 +1,5 @@
1
1
  import { TopLeft, Size } from '@sheetxl/utils';
2
- import { IViewport, Viewport, ViewportMetrics, ClampBounds } from './Viewport';
2
+ import { IViewport, Viewport, ViewportMetrics, ClampBounds, ViewportZoomStep } from './Viewport';
3
3
  /**
4
4
  * Per-axis routing over (up to) two {@link Viewport}s so one viewport can bind its horizontal and
5
5
  * vertical axes to different controllers. Implements {@link IViewport}, so it is interchangeable with a
@@ -59,7 +59,11 @@ export declare class AxisViewport implements IViewport {
59
59
  /** @inheritdoc IViewport.setTarget */
60
60
  setTarget(left: number, top: number, animate?: boolean): boolean;
61
61
  /** @inheritdoc IViewport.setZoom */
62
- setZoom(zoom: number): void;
62
+ setZoom(zoom: number, left?: number, top?: number): void;
63
+ /** @inheritdoc IViewport.requestZoom — zoom is whole-grid state, so the relay is the zoom controller's. */
64
+ requestZoom(step: ViewportZoomStep): void;
65
+ /** @inheritdoc IViewport.subscribeZoom */
66
+ subscribeZoom(listener: (step: ViewportZoomStep) => void): () => void;
63
67
  /**
64
68
  * @inheritdoc IViewport.observe
65
69
  * Route the observed element to each OWNED axis only. A followed axis is driven by its owner (the main
@@ -1,4 +1,5 @@
1
1
  import { Size } from '@sheetxl/utils';
2
+ import { RenderSlotFn } from '../components';
2
3
  import { IViewport } from './Viewport';
3
4
  import { ScrollbarProps } from './IScrollbar';
4
5
  /**
@@ -41,14 +42,26 @@ export interface ScrollPaneProps extends React.HTMLAttributes<HTMLDivElement> {
41
42
  */
42
43
  disableMouseWheel?: boolean;
43
44
  /**
44
- * Wheel intercept. Return `false` to consume the event (skip scrolling) — e.g. ctrl/⌘+wheel zoom.
45
+ * Wheel intercept. Return `false` to consume the event (skip scrolling).
45
46
  */
46
47
  onWheelScroll?: (event: globalThis.WheelEvent) => boolean | void;
48
+ /**
49
+ * Enable the zoom gesture (ctrl/⌘+wheel; pinch). The ScrollPane's scroller owns the gesture — the
50
+ * proportional factor, the clamp, the continuous level — and requests each step on the
51
+ * {@link ScrollPaneProps.viewport} (`requestZoom`), exactly as it drives scroll into it; whoever owns
52
+ * the zoom's model listens there (`subscribeZoom`) and commits.
53
+ *
54
+ * @defaultValue false
55
+ */
56
+ zoomable?: boolean;
47
57
  showHorizontalScrollbar?: boolean;
48
58
  showVerticalScrollbar?: boolean;
49
- renderScrollCorner?: (props: ScrollCornerProps) => React.ReactNode;
50
- renderScrollbarHorizontal?: (props: ScrollbarProps) => React.ReactNode;
51
- renderScrollbarVertical?: (props: ScrollbarProps) => React.ReactNode;
59
+ /** The corner where the two scrollbars meet. `null` leaves it empty. */
60
+ renderScrollCorner?: RenderSlotFn<ScrollCornerProps> | null;
61
+ /** `null` for no horizontal scrollbar, the gutter kept. */
62
+ renderScrollbarHorizontal?: RenderSlotFn<ScrollbarProps> | null;
63
+ /** `null` for no vertical scrollbar, the gutter kept. */
64
+ renderScrollbarVertical?: RenderSlotFn<ScrollbarProps> | null;
52
65
  /**
53
66
  * If touch is disabled.
54
67
  *
@@ -1,4 +1,5 @@
1
1
  import { default as React } from 'react';
2
+ import { RenderSlotFn } from '../components';
2
3
  import { TouchThumbHandleProps } from './TouchThumbHandle';
3
4
  import { ScrollButtonProps } from './ScrollButton';
4
5
  import { TrackEdgeTick } from './TrackDrag';
@@ -60,8 +61,10 @@ export interface ScrollbarProps extends React.HTMLAttributes<HTMLElement> {
60
61
  scrollButtonIncrement?: number | ((offset: number, viewport: number, totalSize: number) => number);
61
62
  scrollButtonInitialRepeatDelay?: number;
62
63
  scrollButtonAdditionalRepeatDelay?: number;
63
- renderScrollButtonStart?: (props: ScrollButtonProps) => React.ReactElement;
64
- renderScrollButtonEnd?: (props: ScrollButtonProps) => React.ReactElement;
64
+ /** The button at the track's start. `null` for none. */
65
+ renderScrollButtonStart?: RenderSlotFn<ScrollButtonProps> | null;
66
+ /** The button at the track's end. `null` for none. */
67
+ renderScrollButtonEnd?: RenderSlotFn<ScrollButtonProps> | null;
65
68
  propsTouchThumb?: Partial<TouchThumbHandleProps>;
66
69
  /**
67
70
  * Called on a repeating tick while the thumb is dragged past a track end and held there. Advance the
@@ -14,16 +14,16 @@ export interface ScrollButtonProps extends React.HTMLAttributes<any> {
14
14
  * Relies on external styling. Follows the styling of scrollbars pattern. @see https://css-tricks.com/custom-scrollbars-in-webkit/
15
15
  * class of scrollbar-button, vertical or horizontal, end
16
16
  */
17
- export declare const defaultCreateScrollStartButton: (props: ScrollButtonProps) => React.ReactElement;
17
+ export declare const defaultRenderScrollButtonStart: (props: ScrollButtonProps) => React.ReactElement;
18
18
  /**
19
19
  * Relies on external styling. Follows the styling of scrollbars pattern.
20
20
  *
21
21
  * @see https://css-tricks.com/custom-scrollbars-in-webkit/
22
22
  * class of scrollbar-button, vertical or horizontal, end
23
23
  */
24
- export declare const defaultCreateScrollEndButton: (props: ScrollButtonProps) => React.ReactElement;
24
+ export declare const defaultRenderScrollButtonEnd: (props: ScrollButtonProps) => React.ReactElement;
25
25
  /**
26
26
  * TODO - implement styling support similar to other scroll buttons. Currently hardcoded
27
27
  */
28
- export declare const defaultCreateScrollEdgeButton: (props: ScrollButtonProps) => React.ReactElement;
28
+ export declare const defaultRenderScrollButtonEdge: (props: ScrollButtonProps) => React.ReactElement;
29
29
  //# sourceMappingURL=ScrollButton.d.ts.map
@@ -1,4 +1,5 @@
1
1
  import { ScrollbarProps } from './IScrollbar';
2
+ export { getWheelOwner, PANE_SCROLLER_ATTRIBUTE } from './wheelOwner';
2
3
  /**
3
4
  * scan all elements until we find one in the given direction
4
5
  * Note - only horizontal at the moment
@@ -28,6 +28,34 @@ export interface ViewportMetrics extends TopLeft, Size {
28
28
  */
29
29
  totalHeight: number;
30
30
  }
31
+ /**
32
+ * One step of a zoom gesture (ctrl/⌘+wheel; pinch), requested on the viewport by the ScrollPane that
33
+ * owns the gesture and applied by whoever owns the zoom's model (a sheet element) — the viewport itself
34
+ * only relays it (see {@link IViewport.requestZoom}).
35
+ */
36
+ export interface ViewportZoomStep {
37
+ /** The new zoom factor (`1` = 100 %), continuous and already clamped to the gesture's range. */
38
+ zoom: number;
39
+ /** The gesture's own scroll position for this level, in screen (zoomed) px. */
40
+ left: number;
41
+ top: number;
42
+ /** The focal point (cursor, or finger midpoint) in viewport client coordinates. */
43
+ clientX: number;
44
+ clientY: number;
45
+ /**
46
+ * The pan that rode along with this step — how far the fingers' midpoint moved on screen since the
47
+ * previous step, in px, positive toward the right/bottom (so the content follows and scroll
48
+ * decreases). `0` for a wheel, and on `end`.
49
+ */
50
+ panX: number;
51
+ panY: number;
52
+ /**
53
+ * `start` on the first change of a gesture, `move` while it runs, `end` once it is over — for a
54
+ * wheel, after the stream has been quiet for a moment; for touch, on the fingers lifting. `end`
55
+ * repeats the final level so the owner can round, snap and settle.
56
+ */
57
+ phase: 'start' | 'move' | 'end';
58
+ }
31
59
  /**
32
60
  * Read-only view of the scroll store. Layers/panes read the current scroll here and subscribe for
33
61
  * changes.
@@ -100,8 +128,23 @@ export interface IViewport extends ViewportStore {
100
128
  * (the zoom-independent base position) is preserved. Because zoom and scroll are mutated together
101
129
  * before the single emit, a listener that reads scroll on this emit sees screen px already consistent
102
130
  * with the new zoom.
131
+ *
132
+ * With `left`/`top` (screen px for the NEW zoom) the position is set to them instead of the
133
+ * ratio-rescale, current and target alike, in the same single emit — a focal-point zoom lands zoom
134
+ * and scroll together, with no frame painted at the top-left-anchored position in between.
135
+ */
136
+ setZoom(zoom: number, left?: number, top?: number): void;
137
+ /**
138
+ * Relay a zoom-gesture step to the zoom's owner. The ScrollPane that runs the gesture calls this (as
139
+ * it calls {@link setTarget} for a scroll); the viewport does NOT apply it — zoom is a whole percent
140
+ * owned by a model the viewport knows nothing about — it hands the step to {@link subscribeZoom}
141
+ * listeners, who commit it and push the result back in through {@link setZoom}.
142
+ */
143
+ requestZoom(step: ViewportZoomStep): void;
144
+ /**
145
+ * Listen for zoom-gesture steps ({@link requestZoom}). Returns the unsubscribe.
103
146
  */
104
- setZoom(zoom: number): void;
147
+ subscribeZoom(listener: (step: ViewportZoomStep) => void): () => void;
105
148
  /**
106
149
  * Push the measured viewport sizes (the grid measures them where it pushes {@link setBounds}; a
107
150
  * subscribed ScrollPane reads them via {@link getViewport} to size its scrollbar thumbs). Emits on
@@ -194,6 +237,11 @@ export declare class Viewport implements IViewport {
194
237
  isSettled(): boolean;
195
238
  /** @inheritdoc ViewportStore.getZoom */
196
239
  getZoom(): number;
240
+ private readonly _zoomListeners;
241
+ /** @inheritdoc IViewport.requestZoom */
242
+ requestZoom(step: ViewportZoomStep): void;
243
+ /** @inheritdoc IViewport.subscribeZoom */
244
+ subscribeZoom(listener: (step: ViewportZoomStep) => void): () => void;
197
245
  /** @inheritdoc ViewportStore.getMetrics */
198
246
  getMetrics(): ViewportMetrics;
199
247
  /** @inheritdoc ViewportStore.getClient */
@@ -254,7 +302,7 @@ export declare class Viewport implements IViewport {
254
302
  */
255
303
  private _startAnimation;
256
304
  /** @inheritdoc IViewport.setZoom */
257
- setZoom(zoom: number): void;
305
+ setZoom(zoom: number, left?: number, top?: number): void;
258
306
  private _emit;
259
307
  private _ensureTicking;
260
308
  private _tick;
@@ -1,4 +1,5 @@
1
1
  import { default as React } from 'react';
2
+ import { RenderSlotFn } from '../components';
2
3
  import { IScrollbarElement, ScrollbarProps } from './IScrollbar';
3
4
  export interface VirtualScrollbarProps extends Omit<ScrollbarProps, "onScroll"> {
4
5
  /**
@@ -32,7 +33,7 @@ export interface VirtualScrollbarProps extends Omit<ScrollbarProps, "onScroll">
32
33
  * @defaultValue 50
33
34
  */
34
35
  precisionFactor?: number;
35
- renderScrollbar?: (props: ScrollbarProps) => React.ReactNode;
36
+ renderScrollbar?: RenderSlotFn<ScrollbarProps>;
36
37
  }
37
38
  /**
38
39
  * The virtual scrollbar is for very large scroll area.
@@ -0,0 +1,19 @@
1
+ /**
2
+ * Whether a touch that landed on `target` belongs to the content rather than to the pane's own
3
+ * touch scroller: the same rule the browser's native pan follows for `touch-action`.
4
+ *
5
+ * @remarks
6
+ * The browser pans only when every element from the touch target up to the scrolling element allows
7
+ * it. A `touch-action` that permits no panning on any of them (`none`, or `pinch-zoom` alone) means
8
+ * the element handles the touch itself. The pane's JavaScript scroller is a stand-in for that native
9
+ * pan, so it honors the same declaration: a resize handle, a drag grip, or a selected drawing says
10
+ * `touch-action: none` once, for the browser and for the scroller alike.
11
+ *
12
+ * Only the chain strictly below `root` is read; `root` is the scroller's own element.
13
+ *
14
+ * @param target The element the touch started on.
15
+ * @param root The scrolling element; the walk stops before it.
16
+ * @param touchActionOf Reads an element's computed `touch-action`. Defaults to the DOM's.
17
+ */
18
+ export declare const isTouchOwned: (target: EventTarget | null, root: Element | null, touchActionOf?: (element: Element) => string) => boolean;
19
+ //# sourceMappingURL=touchOwner.d.ts.map
@@ -11,17 +11,30 @@ export interface UseWheelScrollOptions {
11
11
  */
12
12
  onScrollBy: (delta: Partial<TopLeft>) => void;
13
13
  /**
14
- * Intercept hook. Return `false` to consume the event (skip scrolling) — e.g. ctrl/⌘+wheel zoom.
14
+ * Intercept hook. Return `false` to consume the event (skip scrolling).
15
15
  */
16
16
  onWheelScroll?: (event: globalThis.WheelEvent) => boolean | void;
17
+ /**
18
+ * ctrl/⌘+wheel ⇒ zoom. Receives the frame's accumulated `deltaY` in PIXELS (`deltaMode` lines and
19
+ * pages are normalized) and the last event's client focal point. Coalesced to one call per
20
+ * animation frame — a touchpad pinch arrives as dozens of ctrl+wheel events a second. When not
21
+ * provided, a ctrl+wheel falls through to {@link onWheelScroll} and scrolling as any other wheel.
22
+ */
23
+ onZoomBy?: (deltaY: number, clientX: number, clientY: number) => void;
17
24
  }
18
25
  /**
19
26
  * Attach a non-passive `wheel` listener to `ref` that translates wheel deltas into single-axis
20
27
  * scroll deltas (shift ⇒ horizontal, rAF-coalesced to one per frame) and applies them via
21
- * `onScrollBy`. Returns the handler (for imperative reuse).
28
+ * `onScrollBy`; a ctrl/⌘+wheel goes to `onZoomBy` instead (also one per frame). Returns the handler
29
+ * (for imperative reuse).
22
30
  *
23
31
  * @remarks
24
32
  * Lives here (not in the grid) so the ScrollPane owns wheel alongside touch.
33
+ *
34
+ * A wheel over an element inside `ref` that can still scroll that way (`overflow: auto` or `scroll`)
35
+ * is left to the browser, which scrolls that element. At its end the wheel passes on to the pane,
36
+ * unless the element sets `overscroll-behavior: contain`, which keeps it. Mark an element that
37
+ * scrolls on the pane's behalf with `PANE_SCROLLER_ATTRIBUTE` (`ScrollUtils`).
25
38
  */
26
39
  export declare const useWheelScroll: (ref: RefObject<HTMLElement | null>, options: UseWheelScrollOptions) => ((event: globalThis.WheelEvent) => void);
27
40
  //# sourceMappingURL=useWheelScroll.d.ts.map
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Marks an element inside a scroll pane that scrolls on the pane's behalf (its own native scrollbar),
3
+ * so a wheel over it scrolls the pane rather than being left to the element.
4
+ */
5
+ export declare const PANE_SCROLLER_ATTRIBUTE = "data-sxl-pane-scroller";
6
+ /**
7
+ * Who a wheel belongs to when it lands inside `root`: a scrolling element between the target and
8
+ * `root` takes it, as the browser would give it to that element. The wheel scrolls across when
9
+ * Shift is held or its horizontal delta is the larger.
10
+ *
11
+ * @returns
12
+ * - `'native'`: an element can still scroll that way; the browser scrolls it.
13
+ * - `'contained'`: an element scrolls on that axis and is at its end, but its `overscroll-behavior`
14
+ * is `contain` or `none`, so the wheel stops there and scrolls nothing.
15
+ * - `null`: nothing inside takes it; `root` scrolls.
16
+ */
17
+ export declare const getWheelOwner: (event: globalThis.WheelEvent, root: HTMLElement) => "native" | "contained" | null;
18
+ //# sourceMappingURL=wheelOwner.d.ts.map
@@ -1,6 +1,12 @@
1
1
  export interface ScrollerCallback {
2
2
  (left: number, top: number, zoom: number): void;
3
3
  }
4
+ /**
5
+ * Wheel-to-zoom gain: `level *= exp(-deltaY * K)`. Tuned so one mouse notch (`deltaY` = 100 in
6
+ * Chrome on Windows) is ≈ 15 % — the step `IWorksheetView.zoomIn` takes — and a touchpad pinch's
7
+ * fractional deltas ramp smoothly.
8
+ */
9
+ export declare const WHEEL_ZOOM_K: number;
4
10
  export interface ScrollerOptions {
5
11
  /** Enable scrolling on x-axis */
6
12
  scrollingX?: boolean;
@@ -50,6 +56,25 @@ export declare class Scroller {
50
56
  * a gestureStart event happens. This has higher priority than dragging.
51
57
  */
52
58
  __isGesturing: boolean;
59
+ /**
60
+ * {Boolean} True for the duration of a zoom publish (`zoomTo` / `zoomBy` / `doMouseZoom`), so an
61
+ * owner that otherwise admits only live touch publishes (tracking / decelerating) can tell a zoom
62
+ * from a re-clamp echo (`setDimensions`) and let it through.
63
+ */
64
+ __isZooming: boolean;
65
+ /**
66
+ * {Number} Distance between the two fingers at `doTouchStart` (0 with one finger). The pinch level is
67
+ * `__zoomLevelStart × (current distance / this)`.
68
+ */
69
+ __pinchStartDistance: number;
70
+ /**
71
+ * {Number} The pan of the LAST published touch move — how far the finger (or the two-finger midpoint)
72
+ * moved on screen since the previous move, in px, positive toward the right/bottom. `0` for any publish
73
+ * that is not a touch move (a wheel zoom, a sync). An owner that applies a pinch to its own model
74
+ * reads these so the pan that rode along with the zoom is not lost.
75
+ */
76
+ __gestureMoveX: number;
77
+ __gestureMoveY: number;
53
78
  /**
54
79
  * {Boolean} Whether the user has moved by such a distance that we have enabled
55
80
  * dragging mode. Hint: It's only enabled after some pixels of movement to
@@ -189,6 +214,12 @@ export declare class Scroller {
189
214
  * @param callback {Function ? null} A callback that gets fired when the zoom is complete.
190
215
  */
191
216
  zoomTo(level: number, isAnimated?: boolean, fixedLeft?: number, fixedTop?: number, callback?: () => void): void;
217
+ /**
218
+ * Sets the zoom level WITHOUT publishing — the owner is telling the scroller where the zoom
219
+ * already is (the sync direction, the mirror of `scrollTo(left, top, false)` for position), so the
220
+ * next gesture starts from the right level and the scroll maximums are right for it.
221
+ */
222
+ setZoomLevel(level: number): void;
192
223
  /**
193
224
  * Zooms the content by the given factor.
194
225
  *
@@ -205,7 +236,8 @@ export declare class Scroller {
205
236
  * @param left {Number?null} Horizontal scroll position, keeps current if value is <code>null</code>
206
237
  * @param top {Number?null} Vertical scroll position, keeps current if value is <code>null</code>
207
238
  * @param isAnimated {Boolean?false} Whether the scrolling should happen using an animation
208
- * @param zoom {Number} [1.0] Zoom level to go to
239
+ * @param zoom {Number?} Zoom level to go to; `left`/`top` are then content (base, zoom-independent) px. Keeps the
240
+ * current level when omitted.
209
241
  */
210
242
  scrollTo(left: number, top: number, isAnimated?: boolean, zoom?: number): void;
211
243
  /**
@@ -217,7 +249,13 @@ export declare class Scroller {
217
249
  */
218
250
  scrollBy(left?: number, top?: number, isAnimated?: boolean): void;
219
251
  /**
220
- * Mouse wheel handler for zooming support
252
+ * Mouse wheel handler for zooming support. Proportional: the level is multiplied by
253
+ * `exp(-wheelDelta * WHEEL_ZOOM_K)`, so a mouse notch (`deltaY` ≈ 100) is one zoom step and a
254
+ * touchpad pinch (many small fractional deltas, delivered as ctrl+wheel) is a smooth ramp instead
255
+ * of a burst of steps. Positive delta (wheel toward the user) zooms out.
256
+ *
257
+ * @param wheelDelta `deltaY` in PIXELS (the caller normalizes `deltaMode`), accumulated per frame.
258
+ * @param pageX Focal point, in the same client space as `setPosition`.
221
259
  */
222
260
  doMouseZoom(wheelDelta: number, timeStamp: number, pageX: number, pageY: number): void;
223
261
  /**
@@ -225,10 +263,11 @@ export declare class Scroller {
225
263
  */
226
264
  doTouchStart(touches: TouchList, timeStamp: number | Date): void;
227
265
  /**
228
- * Touch move handler for scrolling support
229
- * @param {Number} [1.0] scale - ....
266
+ * Touch move handler for scrolling and pinch-zoom support. With two fingers the pinch scale is
267
+ * measured here (current distance over the `doTouchStart` distance) and the midpoint pan rides along
268
+ * in the same move; see `__gestureMoveX`.
230
269
  */
231
- doTouchMove(touches: TouchList, timeStamp: number | Date, scale?: number): void;
270
+ doTouchMove(touches: TouchList, timeStamp: number | Date): void;
232
271
  /**
233
272
  * Touch end handler for scrolling support
234
273
  */
@@ -1,4 +1,5 @@
1
1
  import { default as React } from 'react';
2
+ import { RenderSlotFn } from '../components';
2
3
  import { SplitPaneResizerProps } from './SplitPaneResizer';
3
4
  export interface SplitPaneAttributes {
4
5
  /**
@@ -73,7 +74,8 @@ export interface SplitPaneProps extends React.HTMLAttributes<HTMLDivElement> {
73
74
  onDragStart?: () => void;
74
75
  onDragResize?: (position: number) => void;
75
76
  onDragFinish?: (position: number) => void;
76
- renderResizer?: (props: SplitPaneResizerProps) => React.ReactElement;
77
+ /** The bar between the panes. `null` for none. */
78
+ renderResizer?: RenderSlotFn<SplitPaneResizerProps> | null;
77
79
  /**
78
80
  * A ref that points to the HTMLDivElement.
79
81
  */
@@ -180,6 +180,14 @@ export interface TokenTheme {
180
180
  'radius-field'?: string;
181
181
  'radius-box'?: string;
182
182
  'border'?: string;
183
+ /**
184
+ * The stacking bands floating UI sits in (`--sxl-z-grid` / `-popup` / `-tooltip`): grid-anchored floats,
185
+ * popups + menus + modals, tooltips. See `zIndex.ts` for the order and the defaults; consumers read a
186
+ * band through `zIndexVar` and never write a number. Mode-independent, so both modes carry the same values.
187
+ */
188
+ 'z-grid'?: string;
189
+ 'z-popup'?: string;
190
+ 'z-tooltip'?: string;
183
191
  /**
184
192
  * The `background-image` painted behind image-bearing placeholders/frames (charts, shapes, slicers, the
185
193
  * column button) — a faint light wash over a dark surface, `none` in light. Mode-driven, so consumers just
@@ -3,6 +3,7 @@ export * from './defaultTheme';
3
3
  export * from './createThemeVars';
4
4
  export * from './buildThemeCSS';
5
5
  export * from './themeAttrs';
6
+ export * from './zIndex';
6
7
  export * from './TokenThemeProvider';
7
8
  export * from './useResolvedThemeMode';
8
9
  export * from './resolveTokens';