@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
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@sheetxl/utils-react",
3
3
  "description": "Utils React - Utilities for React capabilities needed for all SheetXL components.",
4
- "version": "0.8.0-beta.10",
4
+ "version": "0.8.0-beta.12",
5
5
  "license": "SEE LICENSE IN <LICENSE>",
6
6
  "type": "module",
7
7
  "exports": {
@@ -40,7 +40,7 @@
40
40
  ],
41
41
  "dependencies": {
42
42
  "@floating-ui/react-dom": "^2.1.9",
43
- "@sheetxl/utils": "^0.8.0-beta.10",
43
+ "@sheetxl/utils": "^0.8.0-beta.12",
44
44
  "clsx": "^2.1.1",
45
45
  "detect-it": "^4.0.1",
46
46
  "prop-types": "^15.8.1",
@@ -0,0 +1,32 @@
1
+ import { default as React } from 'react';
2
+ /**
3
+ * A render slot: given its props, returns what to draw. Hooks are allowed — a host mounts the slot through
4
+ * {@link RenderSlot}, so they belong to that component.
5
+ */
6
+ export type RenderSlotFn<P> = (props: P) => React.ReactNode;
7
+ export interface RenderSlotProps<P> {
8
+ /** The slot's renderer. `null` or `undefined` renders nothing. */
9
+ render: RenderSlotFn<P> | null | undefined;
10
+ /** Handed to `render`. */
11
+ props: P;
12
+ }
13
+ /**
14
+ * Mounts a render slot as its own component, so a renderer may call hooks however (and wherever) the host
15
+ * renders it — inside a `useMemo`, a conditional, or a portal built in an effect.
16
+ *
17
+ * @remarks
18
+ * Its type never changes, so an inline arrow passed as `render` does not remount it. A renderer's hooks
19
+ * therefore persist across renderers: swapping between two renderers that call different hooks breaks the
20
+ * hook order, the same as a component that changes the hooks it calls. Give the slot a `key` per renderer
21
+ * if a host must swap them.
22
+ *
23
+ * Draw functions on a hot path (`renderCell`) are called directly, not through a slot, and must not call
24
+ * hooks.
25
+ *
26
+ * @example
27
+ * ```tsx
28
+ * <RenderSlot render={renderCommentCard} props={{ sheet, coords, comment }} />
29
+ * ```
30
+ */
31
+ export declare const RenderSlot: <P>(slot: RenderSlotProps<P>) => React.ReactNode;
32
+ //# sourceMappingURL=RenderSlot.d.ts.map
@@ -1,3 +1,4 @@
1
1
  export * from './FocusKeyNavigation';
2
+ export * from './RenderSlot';
2
3
  export * from './RoundedTab';
3
4
  //# sourceMappingURL=index.d.ts.map
@@ -1,4 +1,5 @@
1
1
  import { default as React } from 'react';
2
+ import { RenderSlotFn } from '../components';
2
3
  import { FloatPopperProps, FloatPopperPosition, FloatPopperAnchor } from './FloatPopper';
3
4
  import { FloatPopupPanelProps } from './FloatPopup';
4
5
  import { FloatReference } from './useFloatStack';
@@ -12,7 +13,8 @@ export interface FloatPanelProps extends Omit<React.HTMLAttributes<HTMLDivElemen
12
13
  anchorPosition?: FloatPopperPosition;
13
14
  label?: string;
14
15
  children?: React.ReactNode;
15
- createPopupPanel?: (props: FloatPopupPanelProps) => React.ReactElement | null;
16
+ /** The float's content. `null` renders the card empty. */
17
+ renderPopupPanel?: RenderSlotFn<FloatPopupPanelProps> | null;
16
18
  propsPopper?: Partial<FloatPopperProps>;
17
19
  onClosing?: () => void;
18
20
  onClose?: () => void;
@@ -28,7 +30,7 @@ export interface FloatPanelSurfaceProps extends Omit<React.HTMLAttributes<HTMLDi
28
30
  floatReference?: FloatReference;
29
31
  /** The element the float is positioned in, handed on to the content. */
30
32
  popupContainer?: HTMLElement;
31
- createPopupPanel?: (props: FloatPopupPanelProps) => React.ReactElement | null;
33
+ renderPopupPanel?: RenderSlotFn<FloatPopupPanelProps> | null;
32
34
  children?: React.ReactNode;
33
35
  ref?: React.Ref<HTMLDivElement>;
34
36
  }
@@ -38,7 +40,7 @@ export interface FloatPanelSurfaceProps extends Omit<React.HTMLAttributes<HTMLDi
38
40
  * @remarks
39
41
  * Separate from the positioning so a float positioned by something other than {@link FloatPopper}
40
42
  * (a grid float that follows its cell) wears the same card. Other attributes are handed to
41
- * `createPopupPanel`, not set on the card.
43
+ * `renderPopupPanel`, not set on the card.
42
44
  */
43
45
  export declare const FloatPanelSurface: React.NamedExoticComponent<Omit<FloatPanelSurfaceProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
44
46
  /**
@@ -48,7 +50,7 @@ export declare const FloatPanelSurface: React.NamedExoticComponent<Omit<FloatPan
48
50
  * `FloatPanel` pairs a {@link FloatPopper} (which positions content next to an
49
51
  * anchor element or point, renders it in a portal, flips it to stay on screen
50
52
  * and animates it in) with a styled, scrollable "card" surface. The content of
51
- * that card is supplied by {@link FloatPanelProps.createPopupPanel}.
53
+ * that card is supplied by {@link FloatPanelProps.renderPopupPanel}.
52
54
  *
53
55
  * @remarks
54
56
  * Most consumers do not render `FloatPanel` directly — {@link useFloatStack}
@@ -68,7 +70,7 @@ export declare const FloatPanelSurface: React.NamedExoticComponent<Omit<FloatPan
68
70
  * <FloatPanel
69
71
  * open={open}
70
72
  * anchorEl={anchorRef.current}
71
- * createPopupPanel={() => <MyMenu />}
73
+ * renderPopupPanel={() => <MyMenu />}
72
74
  * />
73
75
  * ```
74
76
  */
@@ -15,5 +15,5 @@ export interface FloatPopupPanelProps extends React.HTMLAttributes<HTMLDivElemen
15
15
  /**
16
16
  * Default popup panel (a simple flex column container).
17
17
  */
18
- export declare const defaultCreateFloatPopupPanel: (props: FloatPopupPanelProps) => React.ReactElement;
18
+ export declare const defaultRenderFloatPopupPanel: (props: FloatPopupPanelProps) => React.ReactElement;
19
19
  //# sourceMappingURL=FloatPopup.d.ts.map
@@ -1,4 +1,5 @@
1
1
  import { default as React } from 'react';
2
+ import { RenderSlotFn } from '../components';
2
3
  import { ThemeMode } from '../theme';
3
4
  import { FloatReference, RenderFloatPanel } from './useFloatStack';
4
5
  import { FloatPanelProps } from './FloatPanel';
@@ -11,8 +12,8 @@ export interface FloatProviderProps {
11
12
  * inherited from an outer provider (and ultimately the neutral `FloatPanel`).
12
13
  */
13
14
  renderFloatPanel?: RenderFloatPanel;
14
- /** Default panel-content factory for descendants. Inherited when omitted. */
15
- createPopupPanel?: (props: FloatPopupPanelProps) => any;
15
+ /** The default float content for descendants. Inherited when omitted. */
16
+ renderPopupPanel?: RenderSlotFn<FloatPopupPanelProps>;
16
17
  /** Extra props merged into the rendered panel. Inherited when omitted. */
17
18
  propsFloatPanel?: Partial<FloatPanelProps>;
18
19
  /**
@@ -1,3 +1,4 @@
1
+ import { RenderSlotFn } from '../components';
1
2
  import { FloatPanelProps } from './FloatPanel';
2
3
  import { FloatPopupPanelProps } from './FloatPopup';
3
4
  import { RenderFloatPanel } from './useFloatStack';
@@ -28,8 +29,8 @@ export interface FloatThemeScope {
28
29
  */
29
30
  export interface FloatSurface {
30
31
  renderFloatPanel?: RenderFloatPanel;
31
- /** Default panel-content factory, used when a float doesn't supply its own. */
32
- createPopupPanel?: (props: FloatPopupPanelProps) => any;
32
+ /** The default float content, used when a float doesn't supply its own. */
33
+ renderPopupPanel?: RenderSlotFn<FloatPopupPanelProps>;
33
34
  propsFloatPanel?: Partial<FloatPanelProps>;
34
35
  /**
35
36
  * The theme floats in this subtree open with (scope class(es) + surface + mode). Carried onto the float
@@ -1,11 +1,12 @@
1
1
  import { default as React } from 'react';
2
+ import { RenderSlotFn } from '../components';
2
3
  import { FloatPopupPanelProps } from './FloatPopup';
3
4
  import { FloatPanelProps } from './FloatPanel';
4
5
  import { FloatPopperProps } from './FloatPopper';
5
6
  /**
6
7
  * Renders the floating panel for an open float.
7
8
  */
8
- export type RenderFloatPanel = (props: FloatPanelProps) => React.ReactElement;
9
+ export type RenderFloatPanel = RenderSlotFn<FloatPanelProps>;
9
10
  export interface FloatStackOptions {
10
11
  /**
11
12
  * Whether the panel grabs focus when it opens. @defaultValue `true` (menus / dialogs / anything the
@@ -31,13 +32,13 @@ export interface FloatStackOptions {
31
32
  onOpen?: () => void;
32
33
  onClose?: () => void;
33
34
  /**
34
- * If this returns `null` then will create a registered movable stacking.
35
- * This is done for toolbars and other permanent visible components that are integrated into the movable stack.
35
+ * The float's content. `null` shows no popup but keeps the float in the stack — for toolbars and other
36
+ * always-visible components that take part in the movable stacking.
36
37
  */
37
- createPopupPanel?: (props: FloatPopupPanelProps) => any;
38
+ renderPopupPanel?: RenderSlotFn<FloatPopupPanelProps> | null;
38
39
  /**
39
40
  * Passed to the underlying popup panel. `children` is excluded — content comes
40
- * from `createPopupPanel`, and this keeps the option compatible with richer
41
+ * from `renderPopupPanel`, and this keeps the option compatible with richer
41
42
  * surface popper types (e.g. MUI's render-prop `children`).
42
43
  */
43
44
  propsPopper?: Partial<Omit<FloatPopperProps, 'children' | 'ref'>>;
@@ -1,4 +1,4 @@
1
- import { EditModeHandler, SetEditMode } from '@sheetxl/utils';
1
+ import { EditMode, EditModeHandler, SetEditMode } from '@sheetxl/utils';
2
2
  /**
3
3
  * Publish (or clear) the active {@link EditMode} on the app-wide bus **without a hook** — the same
4
4
  * write {@link useEditMode}'s `setMode` performs (fires the superseded mode's
@@ -11,6 +11,25 @@ import { EditModeHandler, SetEditMode } from '@sheetxl/utils';
11
11
  * to be mounted (a `SingletonHooksContainer` in the tree), exactly like the hook.
12
12
  */
13
13
  export declare const setEditMode: SetEditMode;
14
+ /** A way out of a mode: {@link EditMode.done} or {@link EditMode.cancel}. */
15
+ export type EditModeExit = 'done' | 'cancel';
16
+ /**
17
+ * Take a way out of a mode from chrome (the status bar's ✓ / ✕): tells the
18
+ * {@link subscribeEditModeExit} listeners, then runs the mode's own `done` or `cancel`.
19
+ *
20
+ * @remarks
21
+ * A way out is the user finishing the interaction, which is more than the mode ending: an edit also
22
+ * ends when Enter moves on to the next cell. A feature that follows the user rather than the mode (the
23
+ * virtual keyboard going down) listens here, so the chrome needs no knowledge of it.
24
+ */
25
+ export declare const exitEditMode: (mode: EditMode, exit: EditModeExit) => void;
26
+ /**
27
+ * Listen for a way out of a mode taken from chrome (see {@link exitEditMode}). Called before the
28
+ * mode's own `done` or `cancel` runs.
29
+ *
30
+ * @returns Stops listening.
31
+ */
32
+ export declare const subscribeEditModeExit: (listener: (mode: EditMode, exit: EditModeExit) => void) => (() => void);
14
33
  /**
15
34
  * Access the application's **edit-mode bus** — the single, app-wide signal describing the
16
35
  * interaction currently in effect.
@@ -37,8 +56,7 @@ export declare const setEditMode: SetEditMode;
37
56
  *
38
57
  * Typical **consumers** (read the active mode):
39
58
  * - the status bar, which shows {@link EditMode.description} (and its idle label when there is none),
40
- * with a ✕ that runs {@link EditMode.cancel} and a ✓ that runs {@link EditMode.done} when the
41
- * mode carries them;
59
+ * with a ✕ and a ✓ that take the mode's ways out ({@link exitEditMode}) when the mode carries them;
42
60
  * - the grid, which applies {@link EditMode.cursor};
43
61
  * - features that must defer to another interaction — e.g. fill is suppressed while a cell is being
44
62
  * edited — by inspecting the active {@link EditMode.key}.
@@ -1,5 +1,6 @@
1
1
  import { default as React } from 'react';
2
- import { DefaultNotifier, NotifierOptions, INotifier } from '@sheetxl/utils';
2
+ import { RenderSlotFn } from '../components';
3
+ import { NotifierOptions, INotifier } from '@sheetxl/utils';
3
4
  /**
4
5
  * Indicates the type of notification.
5
6
  */
@@ -53,8 +54,15 @@ export interface InputOption {
53
54
  * close; use that when the reason only emerges from the attempt (a rejected password).
54
55
  */
55
56
  disabled?: boolean | (() => boolean);
56
- /** Per-option custom button render (replaces the former dialog-level `createOptionsButton`). */
57
- renderButton?: (props: React.HTMLAttributes<HTMLButtonElement> & React.Attributes, isDefaultOption: boolean) => React.ReactNode;
57
+ /** Render this option's button. Spread `buttonProps` on it. */
58
+ renderButton?: RenderSlotFn<OptionButtonRenderProps>;
59
+ }
60
+ /** What {@link InputOption.renderButton} is handed. */
61
+ export interface OptionButtonRenderProps {
62
+ /** The dialog's wiring for the button: its click, `type` and class. */
63
+ buttonProps: React.ButtonHTMLAttributes<HTMLButtonElement>;
64
+ /** The option is the dialog's default (its submit). */
65
+ isDefaultOption: boolean;
58
66
  }
59
67
  /** A dialog option: a plain label/identity `string`, or a rich {@link InputOption}. */
60
68
  export type OptionInput = string | InputOption;
@@ -269,52 +277,45 @@ export interface IReactNotifier extends INotifier {
269
277
  */
270
278
  showInput: (options: ShowInputOptions) => Promise<InputResults>;
271
279
  }
272
- export declare class DefaultReactNotifier extends DefaultNotifier implements IReactNotifier {
273
- /** @inheritdoc IReactNotifier.setOverrides */
274
- setOverrides(overrides: Partial<IReactNotifier> | null): void;
275
- /** @inheritdoc IReactNotifier.getDelegate */
276
- getDelegate(): Partial<IReactNotifier> | null;
277
- /** @inheritdoc IReactNotifier.showMessage */
278
- showMessage(message: string | React.ReactNode, options?: EnqueueNotifierOptions): void;
279
- /** @inheritdoc IReactNotifier.showBusy */
280
- showBusy(message: string | React.ReactNode, options?: ShowBusyOptions): (Promise<BusyHandle>) | BusyHandle;
281
- /** @inheritdoc IReactNotifier.showWindow */
282
- showWindow(type: string, options?: ShowWindowOptions): Promise<HTMLElement>;
283
- /** @inheritdoc IReactNotifier.showError */
284
- showError(error: any): void;
285
- /** @inheritdoc IReactNotifier.showOptions */
286
- showOptions(options: ShowOptionsOptions): Promise<OptionInput>;
287
- /** @inheritdoc IReactNotifier.showInput */
288
- showInput(options: ShowInputOptions): Promise<InputResults>;
280
+ export interface ReactNotifierProviderProps {
281
+ children: React.ReactNode;
282
+ /**
283
+ * The methods this provider implements. The ones it leaves out come from a provider further out,
284
+ * or do what {@link useNotifier} does with no provider.
285
+ */
286
+ notifier: Partial<IReactNotifier>;
289
287
  }
290
288
  /**
291
- * Context provider for notifications. Allows custom notification implementations
292
- * to be provided to components within the provider tree.
289
+ * Shows the messages, dialogs and busy indicators that components below it ask for through
290
+ * {@link useNotifier}.
291
+ *
292
+ * @remarks
293
+ * Providers stack **per method, and the outermost wins**. An app that wraps a studio in a provider
294
+ * with only `showMessage` replaces the studio's toasts and keeps its dialogs.
295
+ *
296
+ * The provider affects React components only. To redirect the SDK's own messages, override the
297
+ * global {@link Notifier}.
293
298
  *
294
299
  * @example
295
300
  * ```tsx
296
- * const customNotifier = {
301
+ * const notifier = {
297
302
  * showMessage: (message) => toast(message),
298
- * showError: (error) => toast.error(error),
299
- * // ... other methods
303
+ * showError: (error) => toast.error(String(error))
300
304
  * };
301
305
  *
302
- * <ReactNotifierProvider notifier={customNotifier}>
306
+ * <ReactNotifierProvider notifier={notifier}>
303
307
  * <App />
304
308
  * </ReactNotifierProvider>
305
309
  * ```
306
310
  */
307
- export interface ReactNotifierProviderProps {
308
- children: React.ReactNode;
309
- notifier: IReactNotifier;
310
- }
311
311
  export declare const ReactNotifierProvider: React.FC<ReactNotifierProviderProps>;
312
312
  /**
313
- * Hook to access the notification system. Uses the notifier from the nearest
314
- * NotifierProvider, or falls back to the default ReactNotifier singleton if
315
- * no provider is found.
313
+ * Returns the notifier for showing the user messages, dialogs and busy indicators.
316
314
  *
317
- * @returns The notification interface
315
+ * @remarks
316
+ * Every method is always present. With no {@link ReactNotifierProvider} above, messages, dialogs and
317
+ * busy indicators show nothing (a dialog resolves as if cancelled), and `log`, `warn`, `error` and
318
+ * `showError` go to the global {@link Notifier}.
318
319
  *
319
320
  * @example
320
321
  * ```tsx