@sheetxl/utils-react 0.7.27 → 0.7.28-beta.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/browser/cjs/C7jPCqFJNiWyD2pr.cjs +1 -0
- package/browser/cjs/CyWMySHsu-RvsIGs.cjs +1 -0
- package/browser/cjs/DZSvmqU8nRas1uz6.cjs +1 -0
- package/browser/cjs/index.cjs +5 -7
- package/browser/esm/CD4Q4NRTfHSJirLz.mjs +139 -0
- package/browser/esm/DAwEWkKjQCR-nguL.mjs +2171 -0
- package/browser/esm/DUF3Ugd4Z1SDNXPb.mjs +390 -0
- package/browser/esm/index.mjs +6128 -1806
- package/licenses/dependencies.txt +246 -39
- package/node/esm/DA8vLJ8AED3TYoSo.mjs +2171 -0
- package/node/esm/DKS7p6NraAuZKdCC.mjs +139 -0
- package/node/esm/index.mjs +5141 -1774
- package/package.json +8 -5
- package/types/index.d.ts +2 -2043
- package/types/src/animation/AnimationModeContext.d.ts +10 -0
- package/types/src/animation/index.d.ts +3 -0
- package/types/src/animation/useAnimatedMeasure.d.ts +39 -0
- package/types/src/command/ActivationTracker.d.ts +53 -0
- package/types/src/command/CommandAnchorProvider.d.ts +64 -0
- package/types/src/command/CommandButtonEntryLabel.d.ts +25 -0
- package/types/src/command/CommandButtonRegistry.d.ts +159 -0
- package/types/src/command/CommandButtonRegistryContext.d.ts +35 -0
- package/types/src/command/CommandCatalog.d.ts +155 -0
- package/types/src/command/CommandCatalogResource.d.ts +7 -0
- package/types/src/command/CommandCatalogService.d.ts +61 -0
- package/types/src/command/CommandChainContext.d.ts +32 -0
- package/types/src/command/CommandFallbackContext.d.ts +30 -0
- package/types/src/command/CommandFocusContext.d.ts +21 -0
- package/types/src/command/CommandRegistry.d.ts +164 -0
- package/types/src/command/CommandRegistryContext.d.ts +16 -0
- package/types/src/command/CommandResolver.d.ts +162 -0
- package/types/src/command/CommandScope.d.ts +343 -0
- package/types/src/command/CommandScopeContext.d.ts +205 -0
- package/types/src/command/FocusActivation.d.ts +140 -0
- package/types/src/command/ICommand.d.ts +31 -0
- package/types/src/command/ICommandDefinition.d.ts +82 -0
- package/types/src/command/KeyBindingDispatcher.d.ts +150 -0
- package/types/src/command/LayerActivation.d.ts +45 -0
- package/types/src/command/Types.d.ts +80 -0
- package/types/src/command/createResolvedCommand.d.ts +91 -0
- package/types/src/command/index.d.ts +26 -0
- package/types/src/command/reduceDefinitions.d.ts +33 -0
- package/types/src/command/useCommands.d.ts +22 -0
- package/types/src/command/useContributeCommands.d.ts +18 -0
- package/types/src/components/FocusKeyNavigation.d.ts +22 -0
- package/types/src/components/ITooltip.d.ts +38 -0
- package/types/src/components/RoundedTab.d.ts +26 -0
- package/types/src/components/index.d.ts +4 -0
- package/types/src/error/ErrorPanel.d.ts +14 -0
- package/types/src/error/ReactErrorBoundary.d.ts +7 -0
- package/types/src/error/UncaughtErrorBoundary.d.ts +5 -0
- package/types/src/error/index.d.ts +4 -0
- package/types/src/float/FloatPanel.d.ts +57 -0
- package/types/src/float/FloatPopper.d.ts +85 -0
- package/types/src/float/FloatPopup.d.ts +19 -0
- package/types/src/float/FloatProvider.d.ts +60 -0
- package/types/src/float/FloatStackContext.d.ts +25 -0
- package/types/src/float/FloatTooltip.d.ts +22 -0
- package/types/src/float/FloatUtils.d.ts +55 -0
- package/types/src/float/_FloatUtils.d.ts +51 -0
- package/types/src/float/index.d.ts +9 -0
- package/types/src/float/useFloatStack.d.ts +92 -0
- package/types/src/hooks/LanguageState.d.ts +15 -0
- package/types/src/hooks/index.d.ts +19 -0
- package/types/src/hooks/useBoundSyncExternalStore.d.ts +23 -0
- package/types/src/hooks/useCallbackRef.d.ts +11 -0
- package/types/src/hooks/useDevicePixelRatio.d.ts +37 -0
- package/types/src/hooks/useEditMode.d.ts +66 -0
- package/types/src/hooks/useGlobalClipboard.d.ts +7 -0
- package/types/src/hooks/useId.d.ts +9 -0
- package/types/src/hooks/useImperativeElement.d.ts +3 -0
- package/types/src/hooks/useLanguage.d.ts +13 -0
- package/types/src/hooks/useMouseDownAndHoldListener.d.ts +13 -0
- package/types/src/hooks/useNotifier.d.ts +330 -0
- package/types/src/hooks/useOnClickOrFocusAway.d.ts +8 -0
- package/types/src/hooks/useOptionalBoundSyncExternalStore.d.ts +20 -0
- package/types/src/hooks/useOptionalSyncExternalStore.d.ts +18 -0
- package/types/src/hooks/useSynchronizedPointerHandler.d.ts +54 -0
- package/types/src/hooks/useTextareaCaretRect.d.ts +85 -0
- package/types/src/hooks/useTraceUpdate.d.ts +2 -0
- package/types/src/hooks/useTranslator.d.ts +32 -0
- package/types/src/icons/DynamicIcon.d.ts +17 -0
- package/types/src/icons/DynamicIconService.d.ts +39 -0
- package/types/src/icons/ErrorIcon.d.ts +6 -0
- package/types/src/icons/Types.d.ts +81 -0
- package/types/src/icons/WalkingIcon.d.ts +27 -0
- package/types/src/icons/_Utils.d.ts +3 -0
- package/types/src/icons/index.d.ts +5 -0
- package/types/src/icons/packs/Base.d.ts +4 -0
- package/types/src/icons/packs/Conditional.d.ts +4 -0
- package/types/src/index.d.ts +18 -0
- package/types/src/loading/LoadingPanel.d.ts +31 -0
- package/types/src/loading/index.d.ts +2 -0
- package/types/src/persistence/InMemoryStore.d.ts +12 -0
- package/types/src/persistence/LocalStorageStore.d.ts +15 -0
- package/types/src/persistence/PersistenceStateProvider.d.ts +3 -0
- package/types/src/persistence/Types.d.ts +95 -0
- package/types/src/persistence/_Context.d.ts +9 -0
- package/types/src/persistence/index.d.ts +6 -0
- package/types/src/persistence/usePersistenceState.d.ts +33 -0
- package/types/src/react-resizable/Resizable.d.ts +30 -0
- package/types/src/react-resizable/ResizableBox.d.ts +18 -0
- package/types/src/react-resizable/index.d.ts +11 -0
- package/types/src/react-resizable/propTypes.d.ts +56 -0
- package/types/src/react-resizable/utils.d.ts +3 -0
- package/types/src/scroll/AxisViewport.d.ts +73 -0
- package/types/src/scroll/IScrollPane.d.ts +63 -0
- package/types/src/scroll/IScrollbar.d.ts +94 -0
- package/types/src/scroll/NativeScrollbar.d.ts +7 -0
- package/types/src/scroll/ScrollButton.d.ts +29 -0
- package/types/src/scroll/ScrollPane.d.ts +4 -0
- package/types/src/scroll/Scrollbar.d.ts +4 -0
- package/types/src/scroll/TouchThumbContext.d.ts +93 -0
- package/types/src/scroll/TouchThumbHandle.d.ts +64 -0
- package/types/src/scroll/TrackDrag.d.ts +107 -0
- package/types/src/scroll/Utils.d.ts +8 -0
- package/types/src/scroll/Viewport.d.ts +285 -0
- package/types/src/scroll/VirtualScrollbar.d.ts +49 -0
- package/types/src/scroll/index.d.ts +14 -0
- package/types/src/scroll/scrollbarTheming.d.ts +27 -0
- package/types/src/scroll/useWheelScroll.d.ts +27 -0
- package/types/src/scroller/Scroller.d.ts +260 -0
- package/types/src/scroller/animate.d.ts +30 -0
- package/types/src/scroller/index.d.ts +2 -0
- package/types/src/singletonHook/components/SingleItemContainer.d.ts +6 -0
- package/types/src/singletonHook/components/SingletonHooksContainer.d.ts +7 -0
- package/types/src/singletonHook/index.d.ts +11 -0
- package/types/src/singletonHook/singletonHook.d.ts +6 -0
- package/types/src/singletonHook/utils/env.d.ts +4 -0
- package/types/src/singletonHook/utils/env.native.d.ts +1 -0
- package/types/src/singletonHook/utils/warning.d.ts +2 -0
- package/types/src/splitPane/SplitPane.d.ts +91 -0
- package/types/src/splitPane/SplitPaneResizer.d.ts +11 -0
- package/types/src/splitPane/index.d.ts +3 -0
- package/types/src/theme/TokenTheme.d.ts +196 -0
- package/types/src/theme/TokenThemeProvider.d.ts +97 -0
- package/types/src/theme/buildThemeCSS.d.ts +54 -0
- package/types/src/theme/createThemeVars.d.ts +15 -0
- package/types/src/theme/defaultTheme.d.ts +15 -0
- package/types/src/theme/index.d.ts +9 -0
- package/types/src/theme/resolveTokens.d.ts +21 -0
- package/types/src/theme/themeAttrs.d.ts +32 -0
- package/types/src/theme/useResolvedThemeMode.d.ts +17 -0
- package/types/src/types/Types.d.ts +71 -0
- package/types/src/types/index.d.ts +2 -0
- package/types/src/utils/FullScreenPortal.d.ts +6 -0
- package/types/src/utils/PinchZoom.d.ts +3 -0
- package/types/src/utils/ReactUtils.d.ts +134 -0
- package/types/src/utils/index.d.ts +4 -0
- package/types/src/utils/useFullScreen.d.ts +47 -0
- package/browser/cjs/DJJQOl0dYYJgXfru.cjs +0 -6
- package/browser/esm/Bh0xih0ZamA4MXkt.mjs +0 -12
- package/node/assets/style.css +0 -1
- package/node/esm/DdwriRgF582bPBWP.mjs +0 -12
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
import { default as React } from 'react';
|
|
2
|
+
/**
|
|
3
|
+
* Repeat interval (ms) for the parked-at-edge hold: while the thumb is dragged past the track end no
|
|
4
|
+
* pointer-move events fire, so the engine ticks the session's `edgeHold` at this cadence instead.
|
|
5
|
+
*/
|
|
6
|
+
export declare const EDGE_HOLD_INTERVAL_MS = 60;
|
|
7
|
+
/** Delay (ms) before the first page repeat when pressing and holding the track. */
|
|
8
|
+
export declare const PAGE_INITIAL_DELAY_MS = 260;
|
|
9
|
+
/** Interval (ms) between page repeats while holding the track. */
|
|
10
|
+
export declare const PAGE_REPEAT_DELAY_MS = 120;
|
|
11
|
+
/** Where a scrollbar press landed: on the thumb, or on the track before/after it. */
|
|
12
|
+
export type TrackDragZone = 'thumb' | 'track-before' | 'track-after';
|
|
13
|
+
/**
|
|
14
|
+
* Metadata for one parked-at-edge tick. The engine supplies the *heartbeat*; what a tick does — and how
|
|
15
|
+
* it accelerates — is entirely the session's policy (the engine knows nothing about elastic regions).
|
|
16
|
+
*/
|
|
17
|
+
export interface TrackEdgeTick {
|
|
18
|
+
/** 1-based tick number of the current uninterrupted hold. */
|
|
19
|
+
count: number;
|
|
20
|
+
/** Milliseconds since this hold engaged (an acceleration policy can key off this). */
|
|
21
|
+
heldMs: number;
|
|
22
|
+
/** How far (px) the pointer sits past the track end (0 when exactly at it). */
|
|
23
|
+
overshootPx: number;
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* The in-flight gesture returned by {@link TrackDragOptions.onStart}. It carries the *policy* — how the
|
|
27
|
+
* scrollbar maps the gesture to scroll — while the engine owns the *mechanics* (pointer capture, zone
|
|
28
|
+
* hit-testing, the hold timers, and the `dragMode` signal). The 1-D analog of `DragCellsSession`.
|
|
29
|
+
*/
|
|
30
|
+
export interface TrackDragSession {
|
|
31
|
+
/**
|
|
32
|
+
* Thumb drag: position the thumb's leading edge at `trackPx` (the engine keeps the grab point under
|
|
33
|
+
* the pointer). Values may exceed the track bounds; the policy clamps.
|
|
34
|
+
*/
|
|
35
|
+
apply?: (trackPx: number) => void;
|
|
36
|
+
/**
|
|
37
|
+
* Thumb parked past a track end. Advance the scroll one step (policy decides the step — e.g. a
|
|
38
|
+
* virtual scrollbar extends its elastic region, accelerating with `tick.heldMs`) and return whether
|
|
39
|
+
* to keep ticking. Omit for a linear scrollbar: its thumb at the end IS the end.
|
|
40
|
+
*/
|
|
41
|
+
edgeHold?: (edge: -1 | 1, tick: TrackEdgeTick) => boolean;
|
|
42
|
+
/**
|
|
43
|
+
* Track press/hold: scroll one page toward `direction`. The engine pages once on press, then repeats
|
|
44
|
+
* — pausing while the thumb has reached the pointer and resuming if the pointer moves further away.
|
|
45
|
+
*/
|
|
46
|
+
page?: (direction: -1 | 1) => void;
|
|
47
|
+
/** Finalize on pointer-up. */
|
|
48
|
+
end?: (e: React.PointerEvent) => void;
|
|
49
|
+
/** Public label surfaced as {@link TrackDragResult.dragMode} between down and up. */
|
|
50
|
+
dragMode?: string;
|
|
51
|
+
}
|
|
52
|
+
export interface TrackDragOptions {
|
|
53
|
+
/** Axis of the track. (Recreate the controller when this changes — the hook keys its memo on it.) */
|
|
54
|
+
vertical: boolean;
|
|
55
|
+
/** Live track rect (screen coords) for pointer → track-px mapping and end detection. */
|
|
56
|
+
getTrackRect: () => DOMRect | null;
|
|
57
|
+
/** Live thumb placement in track px, or `null` when there is no thumb (disabled — no gesture starts). */
|
|
58
|
+
getThumb: () => {
|
|
59
|
+
offset: number;
|
|
60
|
+
length: number;
|
|
61
|
+
} | null;
|
|
62
|
+
/**
|
|
63
|
+
* Begin a gesture in `zone`. Return the {@link TrackDragSession} policy — or `null` to decline
|
|
64
|
+
* (disabled, non-primary button already filtered by the engine).
|
|
65
|
+
*/
|
|
66
|
+
onStart: (zone: TrackDragZone, e: React.PointerEvent) => TrackDragSession | null;
|
|
67
|
+
/** Notified when the active session's `dragMode` changes (the hook turns this into React state). */
|
|
68
|
+
onDragModeChange?: (mode: string | null) => void;
|
|
69
|
+
edgeHoldIntervalMs?: number;
|
|
70
|
+
pageInitialDelayMs?: number;
|
|
71
|
+
pageRepeatDelayMs?: number;
|
|
72
|
+
}
|
|
73
|
+
/** The headless controller behind {@link useTrackDrag}. */
|
|
74
|
+
export interface TrackDragController {
|
|
75
|
+
onPointerDown: (e: React.PointerEvent) => void;
|
|
76
|
+
onPointerMove: (e: React.PointerEvent) => void;
|
|
77
|
+
onPointerUp: (e: React.PointerEvent) => void;
|
|
78
|
+
/** Stop any hold timer. Call on unmount (the hook wires this). */
|
|
79
|
+
dispose: () => void;
|
|
80
|
+
}
|
|
81
|
+
/** {@link useTrackDrag}'s result: the three spreadable handlers + the public `dragMode`. */
|
|
82
|
+
export interface TrackDragResult {
|
|
83
|
+
onPointerDown: (e: React.PointerEvent) => void;
|
|
84
|
+
onPointerMove: (e: React.PointerEvent) => void;
|
|
85
|
+
onPointerUp: (e: React.PointerEvent) => void;
|
|
86
|
+
/** The in-flight session's {@link TrackDragSession.dragMode}, or `null` between gestures. */
|
|
87
|
+
dragMode: string | null;
|
|
88
|
+
}
|
|
89
|
+
/**
|
|
90
|
+
* The **scrollbar drag engine** — the 1-D analog of `createDragCells`. One pointer surface (the track)
|
|
91
|
+
* serves all three gestures: thumb drag, track page-and-hold, and the parked-at-edge hold. The engine
|
|
92
|
+
* owns the mechanics — pointer capture, zone hit-testing, one hold timer, last-point re-apply — and has
|
|
93
|
+
* NO scroll policy: an {@link TrackDragOptions.onStart} adapter supplies it as a
|
|
94
|
+
* {@link TrackDragSession}, so a linear and a virtual/elastic scrollbar differ only in the session.
|
|
95
|
+
*
|
|
96
|
+
* @remarks
|
|
97
|
+
* A plain (non-hook) factory so it can be unit-tested with a fake track. The React hook is
|
|
98
|
+
* {@link useTrackDrag}.
|
|
99
|
+
*/
|
|
100
|
+
export declare const createTrackDrag: (options: TrackDragOptions) => TrackDragController;
|
|
101
|
+
/**
|
|
102
|
+
* The React hook over {@link createTrackDrag}: owns the `dragMode` state and stops the hold timer on
|
|
103
|
+
* unmount. The getters and `onStart` are read live through a ref, so consumers' closures over changing
|
|
104
|
+
* values (thumb state, offsets) need no handler rebuild.
|
|
105
|
+
*/
|
|
106
|
+
export declare const useTrackDrag: (options: TrackDragOptions) => TrackDragResult;
|
|
107
|
+
//# sourceMappingURL=TrackDrag.d.ts.map
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import { ScrollbarProps } from './IScrollbar';
|
|
2
|
+
/**
|
|
3
|
+
* scan all elements until we find one in the given direction
|
|
4
|
+
* Note - only horizontal at the moment
|
|
5
|
+
*/
|
|
6
|
+
export declare const getScrollTo: (currentLocation: number, boundary: number, children: any, isLeft: boolean, defaultValue?: number) => number;
|
|
7
|
+
export declare const defaultRenderScrollbar: (props: ScrollbarProps) => import("react").JSX.Element;
|
|
8
|
+
//# sourceMappingURL=Utils.d.ts.map
|
|
@@ -0,0 +1,285 @@
|
|
|
1
|
+
import { TopLeft, Size } from '@sheetxl/utils';
|
|
2
|
+
/**
|
|
3
|
+
* View ports are useful for scrolling.
|
|
4
|
+
*/
|
|
5
|
+
export interface ViewportMetrics extends TopLeft, Size {
|
|
6
|
+
/**
|
|
7
|
+
* The x coordinate of the top-left corner.
|
|
8
|
+
*/
|
|
9
|
+
left: number;
|
|
10
|
+
/**
|
|
11
|
+
* The y coordinate of the top-left corner.
|
|
12
|
+
*/
|
|
13
|
+
top: number;
|
|
14
|
+
/**
|
|
15
|
+
* The width of the viewport.
|
|
16
|
+
*/
|
|
17
|
+
width: number;
|
|
18
|
+
/**
|
|
19
|
+
* The height of the viewport.
|
|
20
|
+
*/
|
|
21
|
+
height: number;
|
|
22
|
+
/**
|
|
23
|
+
* The total width of the content within the viewport.
|
|
24
|
+
*/
|
|
25
|
+
totalWidth: number;
|
|
26
|
+
/**
|
|
27
|
+
* The total height of the content within the viewport.
|
|
28
|
+
*/
|
|
29
|
+
totalHeight: number;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* Read-only view of the scroll store. Layers/panes read the current scroll here and subscribe for
|
|
33
|
+
* changes.
|
|
34
|
+
*/
|
|
35
|
+
export interface ViewportStore {
|
|
36
|
+
/**
|
|
37
|
+
* The current (rendered) scroll snapshot. The returned object is identity-stable until the scroll
|
|
38
|
+
* changes, so it is safe as a `useSyncExternalStore` snapshot.
|
|
39
|
+
*/
|
|
40
|
+
getSnapshot(): TopLeft;
|
|
41
|
+
/** Convenience `{ left, top }` of the current (rendered) scroll. */
|
|
42
|
+
getScroll(): TopLeft;
|
|
43
|
+
/** The scroll TARGET the ticker is easing toward (equals current when settled). */
|
|
44
|
+
getTarget(): TopLeft;
|
|
45
|
+
/** Whether the current (rendered) position has reached the target — no easing in progress. */
|
|
46
|
+
isSettled(): boolean;
|
|
47
|
+
/** The zoom factor (`1` = none). Part of the viewport shape so a shared/synced viewport carries it. */
|
|
48
|
+
getZoom(): number;
|
|
49
|
+
/**
|
|
50
|
+
* The raw cell-area client size = the measured client (uncapped by content). The grid reads this
|
|
51
|
+
* for its own pane layout (`min(client, content)`); {@link getMetrics} caps it at content.
|
|
52
|
+
*/
|
|
53
|
+
getClient(): Size;
|
|
54
|
+
/**
|
|
55
|
+
* Whether the viewport has everything it needs to clamp + emit: a measured client (observer fired or
|
|
56
|
+
* manual sizes pushed) AND real content AND a positive client. The shared readiness signal that
|
|
57
|
+
* replaces each grid's "pending until ready" gate.
|
|
58
|
+
*/
|
|
59
|
+
isReady(): boolean;
|
|
60
|
+
/**
|
|
61
|
+
* The combined viewport (position + measured sizes) as one identity-stable object — what a
|
|
62
|
+
* subscribed ScrollPane reads to size and place its scrollbars.
|
|
63
|
+
*/
|
|
64
|
+
getMetrics(): ViewportMetrics;
|
|
65
|
+
/**
|
|
66
|
+
* Subscribe to scroll changes. Driven by the rAF ticker, so the listener fires at most once per
|
|
67
|
+
* animation frame (and only while current is advancing toward target). Returns a remover.
|
|
68
|
+
*/
|
|
69
|
+
subscribe(listener: () => void): () => void;
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* A drivable viewport: the read {@link ViewportStore} plus the write methods the grid and ScrollPane
|
|
73
|
+
* call. Implemented by {@link Viewport} (a single store) and `AxisViewport` (a per-axis
|
|
74
|
+
* composition of two controllers). This is the single object type that flows between a ScrollPane and
|
|
75
|
+
* its content — pass the SAME instance to both and they stay in sync through it.
|
|
76
|
+
*/
|
|
77
|
+
export interface IViewport extends ViewportStore {
|
|
78
|
+
/**
|
|
79
|
+
* Set the scroll TARGET (clamped) and start the ticker if needed.
|
|
80
|
+
*
|
|
81
|
+
* @param animate Animation is a property of the REQUEST, not a global policy: `true` glides to the
|
|
82
|
+
* target (fixed ~{@link SCROLL_ANIMATION_MS} ease-out, long jumps clamped to animate only the
|
|
83
|
+
* arrival — a wheel notch, PageDown, or goto). Omit/`false` for position control (a thumb drag, the
|
|
84
|
+
* touch scroller's per-frame writes, a model restore) — the classic immediate scroll.
|
|
85
|
+
*
|
|
86
|
+
* @returns `true` if the target changed (caller fires its immediate-scroll side effects), else
|
|
87
|
+
* `false` (a no-op move — caller bails).
|
|
88
|
+
*/
|
|
89
|
+
setTarget(left: number, top: number, animate?: boolean): boolean;
|
|
90
|
+
/**
|
|
91
|
+
* Set the clamp bounds (structural — total size, viewport size, frozen floors). Re-clamps the
|
|
92
|
+
* current target into the new bounds (e.g. the viewport shrank) and eases to it. Pushed by the grid;
|
|
93
|
+
* the controller, not the grid, owns the clamp.
|
|
94
|
+
*/
|
|
95
|
+
setBounds(bounds: ClampBounds): void;
|
|
96
|
+
/**
|
|
97
|
+
* Set the zoom factor and notify subscribers on a change. Zoom is structural (it changes every
|
|
98
|
+
* pane's geometry), so the grid re-renders when this emits. The scroll position (current + target) is
|
|
99
|
+
* rescaled by the zoom ratio so the same cell stays anchored at the top-left and so `scroll / zoom`
|
|
100
|
+
* (the zoom-independent base position) is preserved. Because zoom and scroll are mutated together
|
|
101
|
+
* before the single emit, a listener that reads scroll on this emit sees screen px already consistent
|
|
102
|
+
* with the new zoom.
|
|
103
|
+
*/
|
|
104
|
+
setZoom(zoom: number): void;
|
|
105
|
+
/**
|
|
106
|
+
* Push the measured viewport sizes (the grid measures them where it pushes {@link setBounds}; a
|
|
107
|
+
* subscribed ScrollPane reads them via {@link getViewport} to size its scrollbar thumbs). Emits on
|
|
108
|
+
* change.
|
|
109
|
+
*
|
|
110
|
+
* @remarks
|
|
111
|
+
* This is the MANUAL input path — used by a standalone ScrollPane driving arbitrary content (no grid
|
|
112
|
+
* to declare {@link setContent}). Calling it marks the viewport "manual provenance": the manually
|
|
113
|
+
* pushed sizes/bounds win over anything {@link observe}/{@link setContent} would derive.
|
|
114
|
+
*/
|
|
115
|
+
setSizes(width: number, height: number, totalWidth: number, totalHeight: number): void;
|
|
116
|
+
/**
|
|
117
|
+
* START measuring: attach a `ResizeObserver` to `el` (the scroll-client box) so the viewport owns its
|
|
118
|
+
* own client-size measurement and derives its clamp bounds internally. Returns an unobserve fn —
|
|
119
|
+
* symmetric with {@link subscribe}/unsubscribe, and the ONLY teardown the viewport has (there is no
|
|
120
|
+
* `dispose`; the rAF ticker is self-terminating and listeners each remove themselves).
|
|
121
|
+
*
|
|
122
|
+
* @remarks
|
|
123
|
+
* Each call is SELF-CONTAINED (its own observer, its own detach), so multiple elements can observe the
|
|
124
|
+
* same viewport concurrently — e.g. split peers each reporting the shared axis (they report the same
|
|
125
|
+
* value by construction; last write wins). A caller tears down exactly what it set up, nothing else —
|
|
126
|
+
* StrictMode mount→cleanup→mount is naturally symmetric. Guarded for absence exactly like the rAF
|
|
127
|
+
* ticker: with no `ResizeObserver` (SSR / non-DOM tests) it resolves an immediate default client so
|
|
128
|
+
* {@link isReady} still becomes true. `null` is a no-op (returns a no-op detach).
|
|
129
|
+
*/
|
|
130
|
+
observe(el: Element | null): () => void;
|
|
131
|
+
/**
|
|
132
|
+
* Declare the content geometry (the host — a grid — pushes this): the total scroll extent plus the
|
|
133
|
+
* frozen-pane floors (`min*`, the same `minLeft`/`minTop` a manual {@link setBounds} carries). Calling
|
|
134
|
+
* it switches the viewport into DERIVED-bounds mode — it computes its own bounds from
|
|
135
|
+
* `content − client` and no longer needs the host to push {@link setBounds}. Emits + re-derives.
|
|
136
|
+
*/
|
|
137
|
+
setContent(totalWidth: number, totalHeight: number, minLeft?: number, minTop?: number): void;
|
|
138
|
+
}
|
|
139
|
+
/**
|
|
140
|
+
* The scroll store + writer + frame loop. Owns scroll position as a plain external store (not React
|
|
141
|
+
* state): one synchronous source of truth that React reads via `useSyncExternalStore`.
|
|
142
|
+
*
|
|
143
|
+
* @remarks
|
|
144
|
+
* Input sets a **target** ({@link setTarget}); a single rAF **ticker** advances **current**
|
|
145
|
+
* toward target each frame, emits to subscribers when current moves, and self-stops when settled.
|
|
146
|
+
* Input never triggers a render directly (it only writes a number),
|
|
147
|
+
* so input rate is decoupled from render rate and bursts/jank can't flood.
|
|
148
|
+
*
|
|
149
|
+
* Animation is per-request (`setTarget(l, t, true)`), standard smooth-scroll semantics:
|
|
150
|
+
* **fixed-duration, time-based ease-out** — every animated scroll takes the same wall-clock time
|
|
151
|
+
* ({@link SCROLL_ANIMATION_MS}) whether it's a PageDown or a goto across 1M rows, because long jumps
|
|
152
|
+
* are **clamped**: the glide starts within {@link ANIMATION_CLAMP_VIEWPORTS} viewports of the target
|
|
153
|
+
* (the rows in between are never painted). Deltas smaller than the ramp finish proportionally sooner.
|
|
154
|
+
* Time-based ⇒ frame-rate independent (identical feel at 60/120Hz). Un-animated targets apply in one
|
|
155
|
+
* step (the classic immediate scroll).
|
|
156
|
+
*
|
|
157
|
+
* Owns clamping too: {@link setBounds} takes the structural bounds (the grid pushes them) and
|
|
158
|
+
* {@link setTarget} clamps every target into them — the grid no longer clamps.
|
|
159
|
+
*/
|
|
160
|
+
export declare class Viewport implements IViewport {
|
|
161
|
+
/** The rendered position — what subscribers read. */
|
|
162
|
+
private _current;
|
|
163
|
+
/** Where we're easing toward. */
|
|
164
|
+
private _target;
|
|
165
|
+
/** Clamp bounds for the target; unbounded until the grid pushes structural bounds via setBounds. */
|
|
166
|
+
private _bounds;
|
|
167
|
+
/** The in-flight animation (`null` = instant mode: current jumps to target next tick). */
|
|
168
|
+
private _anim;
|
|
169
|
+
/** Zoom factor (1 = none). Viewport state for sharing/sync; the grid drives its metrics. */
|
|
170
|
+
private _zoom;
|
|
171
|
+
/** Cached combined viewport (position + sizes); invalidated when either changes. */
|
|
172
|
+
private _viewport;
|
|
173
|
+
private readonly _listeners;
|
|
174
|
+
private _rafId;
|
|
175
|
+
/** The ResizeObserver-measured client box (the observed element). `null` until the observer fires. */
|
|
176
|
+
private _measuredClient;
|
|
177
|
+
/** Content geometry the host declares (see {@link setContent}) — total extent + frozen floors. */
|
|
178
|
+
private _content;
|
|
179
|
+
/** True once {@link setContent} was called → derive bounds internally (vs manual {@link setBounds}). */
|
|
180
|
+
private _hasContent;
|
|
181
|
+
/** MANUAL provenance: sizes pushed via {@link setSizes} (the standalone story). Wins over measured. */
|
|
182
|
+
private _manualSizes;
|
|
183
|
+
/** MANUAL provenance: bounds pushed via {@link setBounds}. Wins over derived. */
|
|
184
|
+
private _manualBounds;
|
|
185
|
+
constructor(options?: ViewportOptions);
|
|
186
|
+
subscribe(listener: () => void): () => void;
|
|
187
|
+
/** @inheritdoc ViewportStore.getSnapshot */
|
|
188
|
+
getSnapshot(): TopLeft;
|
|
189
|
+
/** @inheritdoc ViewportStore.getScroll */
|
|
190
|
+
getScroll(): TopLeft;
|
|
191
|
+
/** @inheritdoc ViewportStore.getTarget */
|
|
192
|
+
getTarget(): TopLeft;
|
|
193
|
+
/** @inheritdoc ViewportStore.isSettled */
|
|
194
|
+
isSettled(): boolean;
|
|
195
|
+
/** @inheritdoc ViewportStore.getZoom */
|
|
196
|
+
getZoom(): number;
|
|
197
|
+
/** @inheritdoc ViewportStore.getMetrics */
|
|
198
|
+
getMetrics(): ViewportMetrics;
|
|
199
|
+
/** @inheritdoc ViewportStore.getClient */
|
|
200
|
+
getClient(): Size;
|
|
201
|
+
/** @inheritdoc ViewportStore.isReady */
|
|
202
|
+
isReady(): boolean;
|
|
203
|
+
/**
|
|
204
|
+
* The effective cell-area client: manual sizes win (the standalone story); otherwise the measured
|
|
205
|
+
* client (the host observes the cell-area element directly, so there is nothing to subtract).
|
|
206
|
+
*/
|
|
207
|
+
private _effClient;
|
|
208
|
+
/** The effective content extent: manual sizes win; otherwise the host-declared content. */
|
|
209
|
+
private _effTotal;
|
|
210
|
+
/**
|
|
211
|
+
* Derive the clamp bounds from client + content + frozen floors and re-clamp the target into them.
|
|
212
|
+
* This is the single internal path that used to live in the grid's `setBounds` layoutEffect + its two
|
|
213
|
+
* resize re-clamp effects — now self-healing: any measure/content change funnels through here.
|
|
214
|
+
*/
|
|
215
|
+
private _deriveBounds;
|
|
216
|
+
/** Set `_bounds` + re-clamp the current target into them (shared by derived + manual paths). */
|
|
217
|
+
private _applyBounds;
|
|
218
|
+
/** @inheritdoc IViewport.setBounds */
|
|
219
|
+
setBounds(bounds: ClampBounds): void;
|
|
220
|
+
/** @inheritdoc IViewport.setSizes */
|
|
221
|
+
setSizes(width: number, height: number, totalWidth: number, totalHeight: number): void;
|
|
222
|
+
/** @inheritdoc IViewport.observe */
|
|
223
|
+
observe(el: Element | null): () => void;
|
|
224
|
+
/**
|
|
225
|
+
* The one observer implementation. Each call is SELF-CONTAINED — it creates its own
|
|
226
|
+
* `ResizeObserver` and returns a detach that tears down exactly that observer, nothing else (no
|
|
227
|
+
* store-level "current observer" slot). So N observers coexist on one store (split peers sharing an
|
|
228
|
+
* axis; a StrictMode remount overlapping its own cleanup) and last write wins on the measurement —
|
|
229
|
+
* concurrent observers of a shared axis report the same value by construction.
|
|
230
|
+
*/
|
|
231
|
+
private _observe;
|
|
232
|
+
private _setMeasuredClient;
|
|
233
|
+
/** @inheritdoc IViewport.setContent */
|
|
234
|
+
setContent(totalWidth: number, totalHeight: number, minLeft?: number, minTop?: number): void;
|
|
235
|
+
/**
|
|
236
|
+
* Observe `el` but update ONLY the given axis of the measured client (the other axis is left as-is).
|
|
237
|
+
* Self-contained per call like {@link observe}. Returns an unobserve fn.
|
|
238
|
+
*/
|
|
239
|
+
observeAxis(el: Element | null, axis: 'width' | 'height'): () => void;
|
|
240
|
+
/** Declare content for ONE axis only (the other axis's content is left untouched). */
|
|
241
|
+
setContentAxis(axis: 'width' | 'height', total: number, min?: number): void;
|
|
242
|
+
/**
|
|
243
|
+
* Readiness for a SINGLE axis — measured client + real content along that axis only. A composed
|
|
244
|
+
* viewport is ready when each of its two source controllers is ready on the axis it contributes, so
|
|
245
|
+
* an own/throwaway controller with only one meaningful axis doesn't block on the other.
|
|
246
|
+
*/
|
|
247
|
+
isReadyAxis(axis: 'width' | 'height'): boolean;
|
|
248
|
+
/** @inheritdoc IViewport.setTarget */
|
|
249
|
+
setTarget(left: number, top: number, animate?: boolean): boolean;
|
|
250
|
+
/**
|
|
251
|
+
* Arm the fixed-duration glide toward the (just-set) target. A retarget mid-flight restarts from the
|
|
252
|
+
* CURRENT position with a fresh clock — with an ease-out curve a stream of requests (wheel notches, a
|
|
253
|
+
* held PageDown) reads as one continuous motion.
|
|
254
|
+
*/
|
|
255
|
+
private _startAnimation;
|
|
256
|
+
/** @inheritdoc IViewport.setZoom */
|
|
257
|
+
setZoom(zoom: number): void;
|
|
258
|
+
private _emit;
|
|
259
|
+
private _ensureTicking;
|
|
260
|
+
private _tick;
|
|
261
|
+
/**
|
|
262
|
+
* Advance current one frame toward target; emit if it moved. Returns `true` while more frames are
|
|
263
|
+
* needed (an animation in flight), `false` once current has reached target.
|
|
264
|
+
*/
|
|
265
|
+
private _advance;
|
|
266
|
+
}
|
|
267
|
+
export interface ViewportOptions {
|
|
268
|
+
topLeft?: Partial<TopLeft>;
|
|
269
|
+
zoom?: number;
|
|
270
|
+
}
|
|
271
|
+
/** Scroll clamp bounds (in scroll px). `min*` are the frozen-region floors; `max*` are total − view. */
|
|
272
|
+
export interface ClampBounds {
|
|
273
|
+
minLeft: number;
|
|
274
|
+
maxLeft: number;
|
|
275
|
+
minTop: number;
|
|
276
|
+
maxTop: number;
|
|
277
|
+
}
|
|
278
|
+
/**
|
|
279
|
+
* Fixed duration (ms) of an animated scroll. Every animated request takes this long regardless of
|
|
280
|
+
* distance — a PageDown and a goto across 1M rows read identically (long jumps are clamped by
|
|
281
|
+
* {@link ANIMATION_CLAMP_VIEWPORTS}); only sub-ramp deltas finish sooner (see
|
|
282
|
+
* {@link ANIMATION_MS_PER_PX}).
|
|
283
|
+
*/
|
|
284
|
+
export declare const SCROLL_ANIMATION_MS = 200;
|
|
285
|
+
//# sourceMappingURL=Viewport.d.ts.map
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import { default as React } from 'react';
|
|
2
|
+
import { IScrollbarElement, ScrollbarProps } from './IScrollbar';
|
|
3
|
+
export interface VirtualScrollbarProps extends Omit<ScrollbarProps, "onScroll"> {
|
|
4
|
+
/**
|
|
5
|
+
* Amount of scrollbar between minSize and totalSize. This is mean to show that there is more scroll area.
|
|
6
|
+
* @defaultValue 100
|
|
7
|
+
*/
|
|
8
|
+
endGap?: number;
|
|
9
|
+
/**
|
|
10
|
+
* If this is the minimum scrollbar size.
|
|
11
|
+
* By default this is the bottom of the viewport but can be extended.
|
|
12
|
+
* @defaultValue 0
|
|
13
|
+
*/
|
|
14
|
+
minSize?: number;
|
|
15
|
+
/**
|
|
16
|
+
* Determines the increment amount when the scrollbar has been dragged to the end but is not scrolled to total size.
|
|
17
|
+
* @defaultValue 100;
|
|
18
|
+
*/
|
|
19
|
+
endScrollIncrement?: number;
|
|
20
|
+
/**
|
|
21
|
+
* The max size of the area before scaling is implemented.
|
|
22
|
+
* @defaultValue 1000000
|
|
23
|
+
*/
|
|
24
|
+
scaleLimit?: number;
|
|
25
|
+
/**
|
|
26
|
+
* The factor amount for physical scaling
|
|
27
|
+
* @defaultValue 100
|
|
28
|
+
*/
|
|
29
|
+
scaleFactor?: number;
|
|
30
|
+
/**
|
|
31
|
+
* The default precision. This is a factor of the scale factor.
|
|
32
|
+
* @defaultValue 50
|
|
33
|
+
*/
|
|
34
|
+
precisionFactor?: number;
|
|
35
|
+
renderScrollbar?: (props: ScrollbarProps) => React.ReactNode;
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* The virtual scrollbar is for very large scroll area.
|
|
39
|
+
* Browsers have issues with more than divs more than 6m pixels width/height (which by most account is reasonable).
|
|
40
|
+
*
|
|
41
|
+
* This virtualScrollbar also has an elastic component that allows the scrollbar to shrink to its minSize
|
|
42
|
+
* for easier scrolling for large virtual areas with small content areas. (Similar to excel desktop)
|
|
43
|
+
*
|
|
44
|
+
* Note -
|
|
45
|
+
* Because of the virtual nature of the scrollbar the onScroll method is disabled
|
|
46
|
+
* and onScrollOffset must be used.
|
|
47
|
+
*/
|
|
48
|
+
export declare const VirtualScrollbar: React.NamedExoticComponent<Omit<VirtualScrollbarProps, "ref"> & React.RefAttributes<IScrollbarElement>>;
|
|
49
|
+
//# sourceMappingURL=VirtualScrollbar.d.ts.map
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
export * from './IScrollbar';
|
|
2
|
+
export * from './Scrollbar';
|
|
3
|
+
export * from './TrackDrag';
|
|
4
|
+
export * from './TouchThumbContext';
|
|
5
|
+
export * from './TouchThumbHandle';
|
|
6
|
+
export * from './IScrollPane';
|
|
7
|
+
export * from './ScrollPane';
|
|
8
|
+
export * from './Viewport';
|
|
9
|
+
export * from './AxisViewport';
|
|
10
|
+
export * from './ScrollButton';
|
|
11
|
+
export * from './VirtualScrollbar';
|
|
12
|
+
export * from './scrollbarTheming';
|
|
13
|
+
export * as ScrollUtils from './Utils';
|
|
14
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Class to apply native scrollbar theming. Drives off the
|
|
3
|
+
* `--scrollbar-*` CSS variables produced by {@link getScrollbarCssVariables}.
|
|
4
|
+
*/
|
|
5
|
+
export declare const scrollbarThemedClassName: string;
|
|
6
|
+
/**
|
|
7
|
+
* Final (already resolved) colors for the scrollbar CSS variables.
|
|
8
|
+
*
|
|
9
|
+
* Color derivation (elevate/alpha) is intentionally left to the caller so this
|
|
10
|
+
* can be overridden.
|
|
11
|
+
*/
|
|
12
|
+
export interface ScrollbarCssVariableColors {
|
|
13
|
+
/** Track background (typically a low-alpha color). */
|
|
14
|
+
track: string;
|
|
15
|
+
thumb: string;
|
|
16
|
+
button?: string;
|
|
17
|
+
active: string;
|
|
18
|
+
corner?: string;
|
|
19
|
+
/** Thumb border color. @defaultValue `track` */
|
|
20
|
+
border?: string;
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Maps resolved scrollbar colors to the `--scrollbar-*` CSS variable contract
|
|
24
|
+
* (plus the static size variables). Apply alongside {@link scrollbarThemedClassName}.
|
|
25
|
+
*/
|
|
26
|
+
export declare const getScrollbarCssVariables: (colors: ScrollbarCssVariableColors) => Record<string, string>;
|
|
27
|
+
//# sourceMappingURL=scrollbarTheming.d.ts.map
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import { RefObject } from 'react';
|
|
2
|
+
import { TopLeft } from '@sheetxl/utils';
|
|
3
|
+
export interface UseWheelScrollOptions {
|
|
4
|
+
/**
|
|
5
|
+
* When `false`, the listener is not attached.
|
|
6
|
+
* @defaultValue true
|
|
7
|
+
*/
|
|
8
|
+
enabled?: boolean;
|
|
9
|
+
/**
|
|
10
|
+
* Apply a scroll delta — one axis at a time, matching the wheel's dominant direction.
|
|
11
|
+
*/
|
|
12
|
+
onScrollBy: (delta: Partial<TopLeft>) => void;
|
|
13
|
+
/**
|
|
14
|
+
* Intercept hook. Return `false` to consume the event (skip scrolling) — e.g. ctrl/⌘+wheel zoom.
|
|
15
|
+
*/
|
|
16
|
+
onWheelScroll?: (event: globalThis.WheelEvent) => boolean | void;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Attach a non-passive `wheel` listener to `ref` that translates wheel deltas into single-axis
|
|
20
|
+
* scroll deltas (shift ⇒ horizontal, rAF-coalesced to one per frame) and applies them via
|
|
21
|
+
* `onScrollBy`. Returns the handler (for imperative reuse).
|
|
22
|
+
*
|
|
23
|
+
* @remarks
|
|
24
|
+
* Lives here (not in the grid) so the ScrollPane owns wheel alongside touch.
|
|
25
|
+
*/
|
|
26
|
+
export declare const useWheelScroll: (ref: RefObject<HTMLElement | null>, options: UseWheelScrollOptions) => ((event: globalThis.WheelEvent) => void);
|
|
27
|
+
//# sourceMappingURL=useWheelScroll.d.ts.map
|