@sheetxl/utils-react 0.8.0-beta.10 → 0.8.0-beta.12

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 (34) hide show
  1. package/browser/esm/{c6p-JLuLHZbSS4lS.mjs → BRSmfawI3Q6E-zEp.mjs} +2 -2
  2. package/browser/esm/{MX1mB0lFgdtW9vqX.mjs → CgZsWqv--yJ6E3Od.mjs} +1 -1
  3. package/browser/esm/Cxre-SkPvvodNriU.mjs +100 -0
  4. package/browser/esm/index.mjs +1681 -1555
  5. package/node/esm/DFqqRMnmEo_UAEFa.mjs +100 -0
  6. package/node/esm/{DluzVx_97eND2sL7.mjs → DFsKZrWF_hSPLITK.mjs} +1 -1
  7. package/node/esm/index.mjs +2053 -1923
  8. package/package.json +2 -2
  9. package/types/src/components/RenderSlot.d.ts +32 -0
  10. package/types/src/components/index.d.ts +1 -0
  11. package/types/src/float/FloatPanel.d.ts +7 -5
  12. package/types/src/float/FloatPopup.d.ts +1 -1
  13. package/types/src/float/FloatProvider.d.ts +3 -2
  14. package/types/src/float/FloatUtils.d.ts +3 -2
  15. package/types/src/float/useFloatStack.d.ts +6 -5
  16. package/types/src/hooks/useEditMode.d.ts +21 -3
  17. package/types/src/hooks/useNotifier.d.ts +35 -34
  18. package/types/src/icons/packs/Base.json.d.ts +3434 -0
  19. package/types/src/index.d.ts +2 -0
  20. package/types/src/lazy/lazyComponent.d.ts +9 -2
  21. package/types/src/render/PendingRender.d.ts +43 -0
  22. package/types/src/render/index.d.ts +2 -0
  23. package/types/src/scroll/IScrollPane.d.ts +7 -3
  24. package/types/src/scroll/IScrollbar.d.ts +5 -2
  25. package/types/src/scroll/ScrollButton.d.ts +3 -3
  26. package/types/src/scroll/VirtualScrollbar.d.ts +2 -1
  27. package/types/src/scroller/Scroller.d.ts +1 -1
  28. package/types/src/splitPane/SplitPane.d.ts +3 -1
  29. package/types/src/utils/index.d.ts +1 -0
  30. package/types/src/utils/measureUIText.d.ts +24 -0
  31. package/types/src/virtualKeyboard/VirtualKeyboard.d.ts +122 -0
  32. package/types/src/virtualKeyboard/index.d.ts +2 -0
  33. package/browser/esm/C61KRGJ5SxolPzsV.mjs +0 -2352
  34. package/node/esm/DgX4rJhtPuZxWvt5.mjs +0 -2352
@@ -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,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,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
  /**
@@ -55,9 +56,12 @@ export interface ScrollPaneProps extends React.HTMLAttributes<HTMLDivElement> {
55
56
  zoomable?: boolean;
56
57
  showHorizontalScrollbar?: boolean;
57
58
  showVerticalScrollbar?: boolean;
58
- renderScrollCorner?: (props: ScrollCornerProps) => React.ReactNode;
59
- renderScrollbarHorizontal?: (props: ScrollbarProps) => React.ReactNode;
60
- 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;
61
65
  /**
62
66
  * If touch is disabled.
63
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 { 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.
@@ -3,7 +3,7 @@ export interface ScrollerCallback {
3
3
  }
4
4
  /**
5
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 `ISheetView.zoomIn` takes — and a touchpad pinch's
6
+ * Chrome on Windows) is ≈ 15 % — the step `IWorksheetView.zoomIn` takes — and a touchpad pinch's
7
7
  * fractional deltas ramp smoothly.
8
8
  */
9
9
  export declare const WHEEL_ZOOM_K: number;
@@ -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
  */
@@ -2,4 +2,5 @@ export * as ReactUtils from './ReactUtils';
2
2
  export * from './useFullScreen';
3
3
  export * from './FullScreenPortal';
4
4
  export * from './textSelectionDrag';
5
+ export * from './measureUIText';
5
6
  //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,24 @@
1
+ /**
2
+ * The font a piece of UI text is set in, as CSS has it.
3
+ */
4
+ export interface UIFont {
5
+ /** Font size in px. */
6
+ size: number;
7
+ /** The CSS font-family list, as the theme names it. */
8
+ family: string;
9
+ /** CSS font-weight; `normal` when unset. */
10
+ weight?: string | number;
11
+ /** CSS font-style; `normal` when unset. */
12
+ style?: 'normal' | 'italic' | 'oblique';
13
+ }
14
+ /**
15
+ * The width in px the browser paints `text` at in a UI font: for sizing a control to a sample
16
+ * label (a toolbar button to its widest value). Nothing to do with cells: spreadsheet text is
17
+ * measured by the sdk's font collection, with Excel's numbers.
18
+ *
19
+ * @remarks
20
+ * A cached canvas measures with the browser's own advances. Where there is no canvas (jsdom, a
21
+ * server) the width is estimated from the character count, which is enough to size a control.
22
+ */
23
+ export declare function measureUIText(text: string, font: UIFont): number;
24
+ //# sourceMappingURL=measureUIText.d.ts.map
@@ -0,0 +1,122 @@
1
+ import { default as React } from 'react';
2
+ /** The virtual keyboard a text field asks for (its `inputmode`). */
3
+ export type VirtualKeyboardInputMode = 'text' | 'decimal' | 'numeric' | 'tel' | 'email' | 'url' | 'search';
4
+ /**
5
+ * Configuration for a {@link VirtualKeyboardStore}.
6
+ */
7
+ export interface VirtualKeyboardOptions {
8
+ /**
9
+ * Never enter keyboard mode: the grid takes focus itself, and the keyboard comes and goes with
10
+ * each text field as the browser decides. `false` turns keyboard mode on where the device was not
11
+ * detected to have one.
12
+ *
13
+ * @defaultValue `true` on a device with no touch input (no virtual keyboard), else `false`
14
+ */
15
+ disabled?: boolean;
16
+ /** Leave the grid scrolled where it is when the keyboard rises over the active cell. */
17
+ disableScrollIntoView?: boolean;
18
+ /**
19
+ * A tap on the grid keeps keyboard mode, as Excel keeps its keyboard, rather than putting the
20
+ * keyboard away.
21
+ */
22
+ keepOnTap?: boolean;
23
+ }
24
+ /**
25
+ * The keyboard-mode state.
26
+ */
27
+ export interface VirtualKeyboardState {
28
+ /**
29
+ * Whether the sheet is in keyboard mode: a virtual keyboard is up for typing into the sheet, and
30
+ * focusing the sheet lands on its typing input so the keyboard stays.
31
+ */
32
+ readonly active: boolean;
33
+ /** The keyboard every sheet text field asks for. */
34
+ readonly inputMode: VirtualKeyboardInputMode;
35
+ }
36
+ /**
37
+ * The imperative handle {@link useVirtualKeyboard} returns.
38
+ */
39
+ export interface VirtualKeyboardHandler {
40
+ /** The current state. A new object on each change. */
41
+ getState(): VirtualKeyboardState;
42
+ /**
43
+ * Whether keyboard mode is available: the device has a virtual keyboard, and the store is not
44
+ * {@link VirtualKeyboardOptions.disabled}. The counterpart of `document.fullscreenEnabled`; a host
45
+ * leaves keyboard-mode parts (the sheet's keyboard layer) out when it is `false`.
46
+ */
47
+ isEnabled(): boolean;
48
+ /** Shorthand for `getState().active`. */
49
+ isActive(): boolean;
50
+ /** Shorthand for `getState().inputMode`. */
51
+ getInputMode(): VirtualKeyboardInputMode;
52
+ /** Ask for a different keyboard on the sheet's text fields. */
53
+ setInputMode(inputMode: VirtualKeyboardInputMode): void;
54
+ /**
55
+ * Enter keyboard mode. A sheet whose focus is not already in a text field focuses its typing
56
+ * input, which raises the keyboard; browsers raise one only inside a user gesture, so call this
57
+ * from a tap.
58
+ *
59
+ * @returns Whether keyboard mode is on: `false` when it is not {@link isEnabled | enabled}, as
60
+ * `requestFullscreen` refuses where fullscreen is not.
61
+ */
62
+ show(): boolean;
63
+ /**
64
+ * Leave keyboard mode, and go back to the letters keyboard: a field opened later (a double-click
65
+ * into a cell) asks for letters, so the next keyboard does too. A sheet whose typing input has focus
66
+ * hands it to the grid, which lowers the keyboard; an editor that has focus keeps it.
67
+ */
68
+ hide(): void;
69
+ /**
70
+ * Name the editor that typing opens in while in keyboard mode, by the id it parks on the edit
71
+ * session (`EditSession.setActiveEditorId`); a phone's formula bar names itself so a typed key
72
+ * opens the edit there rather than in the cell. The latest registration wins.
73
+ *
74
+ * @returns Removes this registration.
75
+ */
76
+ registerEditor(editorId: string): () => void;
77
+ /** The editor typing opens in while in keyboard mode, or `null` for the cell. */
78
+ getEditorId(): string | null;
79
+ /** The options the store was created with. */
80
+ getOptions(): Readonly<VirtualKeyboardOptions>;
81
+ }
82
+ /**
83
+ * A virtual keyboard **bus instance**: one keyboard mode shared by the sheet, its editors, and any
84
+ * control that shows or hides the keyboard.
85
+ */
86
+ export interface VirtualKeyboardStore extends VirtualKeyboardHandler {
87
+ /** Subscribe to any state change. Returns the remover. */
88
+ subscribe(listener: () => void): () => void;
89
+ }
90
+ /**
91
+ * Whether a virtual keyboard is up, read from the visual viewport (the part of the page the keyboard
92
+ * leaves visible). Pinch zoom shrinks the visual viewport too, so its scale is undone first.
93
+ */
94
+ export declare const isVirtualKeyboardUp: () => boolean;
95
+ /**
96
+ * Create an isolated virtual keyboard store.
97
+ */
98
+ export declare const createVirtualKeyboardStore: (options?: VirtualKeyboardOptions) => VirtualKeyboardStore;
99
+ export interface VirtualKeyboardProviderProps extends VirtualKeyboardOptions {
100
+ /** The bus instance to share. Omit to create one for this subtree from the options. */
101
+ store?: VirtualKeyboardStore;
102
+ children?: React.ReactNode;
103
+ }
104
+ /**
105
+ * Share one virtual keyboard bus with a subtree: the sheet, its editors, and any keyboard control an
106
+ * app adds (a "show keyboard" button calls `useVirtualKeyboard().show()`). With no `store` a fresh one
107
+ * is created from the options, stable while they are unchanged.
108
+ */
109
+ export declare const VirtualKeyboardProvider: (props: VirtualKeyboardProviderProps) => React.ReactElement;
110
+ /**
111
+ * Resolve the enclosing bus **instance**: the nearest {@link VirtualKeyboardProvider}'s store, else
112
+ * the app-wide default, enabled on a device with touch input. Never `null`: where there is no
113
+ * virtual keyboard the store reports `isEnabled() === false` and `show()` refuses, as the
114
+ * fullscreen API does where fullscreen is unavailable. Non-reactive; use {@link useVirtualKeyboard}
115
+ * to also re-render.
116
+ */
117
+ export declare const useVirtualKeyboardStore: () => VirtualKeyboardStore;
118
+ /**
119
+ * Access the enclosing virtual keyboard bus. Reading re-renders on change.
120
+ */
121
+ export declare const useVirtualKeyboard: () => VirtualKeyboardHandler;
122
+ //# sourceMappingURL=VirtualKeyboard.d.ts.map
@@ -0,0 +1,2 @@
1
+ export * from './VirtualKeyboard';
2
+ //# sourceMappingURL=index.d.ts.map