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

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/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.1",
4
+ "version": "0.8.0-beta.2",
5
5
  "license": "SEE LICENSE IN <LICENSE>",
6
6
  "type": "module",
7
7
  "exports": {
@@ -41,7 +41,7 @@
41
41
  ],
42
42
  "dependencies": {
43
43
  "@floating-ui/react-dom": "^2.1.9",
44
- "@sheetxl/utils": "^0.8.0-beta.1",
44
+ "@sheetxl/utils": "^0.8.0-beta.2",
45
45
  "clsx": "^2.1.1",
46
46
  "detect-it": "^4.0.1",
47
47
  "prop-types": "^15.8.1",
@@ -54,8 +54,8 @@ export interface ChromeRecord {
54
54
  * `null` means **explicitly unbound in this locale** (the usual convention: `undefined` = take
55
55
  * the default, `null` = exclude it). A locale pack inherits English shortcuts by *absence*, so
56
56
  * `null` is the only way for a locale to drop one — needed when a localized mnemonic claims a
57
- * chord English gives to some other command (de Bold takes `ctrl+shift+F`, so de `showFormat`
58
- * must give it up). See `config/i18n-catalog-build.mjs`.
57
+ * chord English gives to some other command (de Bold takes `ctrl+shift+F`, so de
58
+ * `formatCellsFont` must give it up). See `config/i18n-catalog-build.mjs`.
59
59
  */
60
60
  shortcut?: string | string[] | null;
61
61
  /** Accumulated metadata tags (e.g. `'mutator'`, `'quickAction'`). */
@@ -3,6 +3,7 @@ export * from './Types';
3
3
  export * from './CommandButtonRegistry';
4
4
  export * from './CommandButtonRegistryContext';
5
5
  export * from './CommandButtonEntryLabel';
6
+ export * from './tags';
6
7
  export * from './ICommandDefinition';
7
8
  export * from './reduceDefinitions';
8
9
  export * from './createResolvedCommand';
@@ -0,0 +1,19 @@
1
+ /**
2
+ * Well-known command tag hints honored by the command surfaces.
3
+ *
4
+ * Tags are free-form strings on a command definition (e.g. `'mutator'` drives format-protection
5
+ * disabling). These constants name the ones the shared UI layer reacts to, so definitions and the
6
+ * consumers that read them agree without stringly-typed drift.
7
+ */
8
+ /**
9
+ * A command that applies **in place** and must NOT dismiss its enclosing popup on execute — font-size
10
+ * increase/decrease, indent increase/decrease, decimal places, the number-format quick styles. These
11
+ * are the "quick button" rows a popup leads with, and they exist to be pressed repeatedly.
12
+ *
13
+ * The auto-dismiss observer in `useCommands` reads this off the RESOLVED command, so it holds for
14
+ * **every** observer of the key. A per-surface opt-out cannot: an execute notifies every mounted
15
+ * observer of that key, so a co-observer with no hook (the same command on the toolbar, whose
16
+ * enclosing float is the popup's ancestor) would still close the popup out from under the quick button.
17
+ */
18
+ export declare const QUICK_ACTION_TAG = "quickAction";
19
+ //# sourceMappingURL=tags.d.ts.map
@@ -21,6 +21,26 @@ export interface FloatPanelProps extends Omit<React.HTMLAttributes<HTMLDivElemen
21
21
  onOpen?: () => void;
22
22
  ref?: React.Ref<any>;
23
23
  }
24
+ /**
25
+ * Props for {@link FloatPanelSurface}.
26
+ */
27
+ export interface FloatPanelSurfaceProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
28
+ floatReference?: FloatReference;
29
+ /** The element the float is positioned in, handed on to the content. */
30
+ popupContainer?: HTMLElement;
31
+ createPopupPanel?: (props: FloatPopupPanelProps) => React.ReactElement | null;
32
+ children?: React.ReactNode;
33
+ ref?: React.Ref<HTMLDivElement>;
34
+ }
35
+ /**
36
+ * The card a {@link FloatPanel} shows: the themed, scrollable surface its content is created in.
37
+ *
38
+ * @remarks
39
+ * Separate from the positioning so a float positioned by something other than {@link FloatPopper}
40
+ * (a grid float that follows its cell) wears the same card. Other attributes are handed to
41
+ * `createPopupPanel`, not set on the card.
42
+ */
43
+ export declare const FloatPanelSurface: React.NamedExoticComponent<Omit<FloatPanelSurfaceProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
24
44
  /**
25
45
  * A floating, anchored surface for transient content such as menus, dropdowns,
26
46
  * popovers and context menus.
@@ -1,3 +1,3 @@
1
1
  import { DependencyList } from 'react';
2
- export declare function useImperativeElement<R extends T, A = any, T = HTMLElement & A>(refForwarded: React.Ref<R>, attributeFn?: () => Partial<A>, deps?: DependencyList): React.RefObject<R>;
2
+ export declare function useImperativeElement<R extends T, A = any, T = HTMLElement & A>(refForwarded: React.Ref<R>, attributeFn?: () => Partial<A>, deps?: DependencyList, element?: HTMLElement | null): React.RefObject<R>;
3
3
  //# sourceMappingURL=useImperativeElement.d.ts.map
@@ -75,10 +75,13 @@ export interface ShowOptionsOptions<T = any, C = any> extends ShowWindowOptions<
75
75
  */
76
76
  description?: string;
77
77
  /**
78
- * Display an icon next to the description for additional context
79
- *
80
- * @remarks
81
- * Not yet implemented
78
+ * What kind of message this is. `info`, `warning`, `error` and `success` show the matching icon
79
+ * beside the description; `default` (or omitted) shows none.
80
+ */
81
+ type?: NotifierType;
82
+ /**
83
+ * An icon beside the description, in place of the one {@link type} implies. A `string` is an icon
84
+ * key.
82
85
  */
83
86
  icon?: React.ReactNode | string;
84
87
  /**
@@ -3,6 +3,7 @@ export * from './command';
3
3
  export * as Command from './command';
4
4
  export * from './animation';
5
5
  export * from './components';
6
+ export * from './lazy';
6
7
  export * from './loading';
7
8
  export * from './error';
8
9
  export * from './float';
@@ -0,0 +1,2 @@
1
+ export * from './lazyComponent';
2
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,43 @@
1
+ import { default as React } from 'react';
2
+ /**
3
+ * Options for {@link lazyComponent}.
4
+ */
5
+ export interface LazyComponentOptions<P> {
6
+ /**
7
+ * Rendered in place of the component when its module fails to load.
8
+ *
9
+ * @remarks
10
+ * When omitted, the error is thrown to the nearest error boundary.
11
+ * Call {@link useLazyRetry} from inside the rendered content to try again.
12
+ */
13
+ renderError?: (error: unknown, props: P) => React.ReactNode;
14
+ }
15
+ /**
16
+ * Returns a function that retries loading the nearest {@link lazyComponent}, or `null` when there
17
+ * is none.
18
+ *
19
+ * @remarks
20
+ * Intended for the content rendered by {@link LazyComponentOptions.renderError}.
21
+ */
22
+ export declare function useLazyRetry(): (() => void) | null;
23
+ /**
24
+ * Like `React.lazy`, but a module that fails to load is not a permanent failure.
25
+ *
26
+ * @param loader Loads a module whose default export is the component.
27
+ * @param options How a failure is rendered.
28
+ *
29
+ * @remarks
30
+ * A mounted instance keeps showing the failure until {@link useLazyRetry} is called. A new mount
31
+ * after a failure loads the module again. Render inside a `Suspense` boundary, as with `React.lazy`.
32
+ *
33
+ * @example
34
+ * ```tsx
35
+ * const CustomColorPanel = lazyComponent(() => import('./CustomColorPanel'), {
36
+ * renderError: (error) => <LoadError error={error} />
37
+ * });
38
+ * ```
39
+ */
40
+ export declare function lazyComponent<C extends React.ComponentType<any>>(loader: () => Promise<{
41
+ default: C;
42
+ }>, options?: LazyComponentOptions<React.ComponentProps<C>>): React.FC<React.ComponentProps<C>>;
43
+ //# sourceMappingURL=lazyComponent.d.ts.map
@@ -7,7 +7,8 @@ import { PersistenceStateOptions, PersistenceStateSetter } from './Types';
7
7
  * - The value is persisted under `namespace:key` using the current store.
8
8
  * - On first render, it initializes from `defaultValue`.
9
9
  * - Then it **hydrates asynchronously** from the configured store
10
- * (memory, localStorage, IndexedDB, remote, etc.).
10
+ * (memory, localStorage, IndexedDB, remote, etc.). Hydration is *seeding*: a value written with
11
+ * `setState` while the read is still in flight is newer, so it wins and the read is discarded.
11
12
  * - Writes are **debounced** according to `debounceMs` from the context.
12
13
  * - Optional **versioning + migration** lets you evolve stored shapes over time.
13
14
  *
@@ -148,11 +148,12 @@ export interface TokenTheme {
148
148
  * The border on a **raised container** — popup panels, menus, the toolbar palette.
149
149
  *
150
150
  * @remarks
151
- * In Material, "raised" is expressed as *lightness*: these surfaces take the `raisedSurface` wash and
152
- * carry no border. A flat design language expresses it as **border + shadow** with the fill held nearly
153
- * constant (VS Code's own find widget and menus do exactly this). A host that flattens the wash — see
154
- * `--sxl-surface-raised` — therefore has to put the structure back somewhere, and this is it.
155
- * Defaults to `transparent`, so the Material presentation is unchanged unless a host opts in.
151
+ * In Material, "raised" is expressed as *lightness*: these surfaces take a lighter fill
152
+ * ({@link TokenTheme['color-elevated'] color-elevated}) and carry no border. A flat design language holds
153
+ * the fill nearly constant and expresses it as **border + shadow** instead (VS Code's own find widget
154
+ * and menus do exactly this), so a host whose float fill sits within a shade of the ground has to put the
155
+ * structure back somewhere — and this is it. Defaults to `transparent`, so the Material presentation is
156
+ * unchanged unless a host opts in.
156
157
  */
157
158
  'color-elevated-border'?: string;
158
159
  'color-accent'?: string;
@@ -1,4 +1,5 @@
1
1
  export * as ReactUtils from './ReactUtils';
2
2
  export * from './useFullScreen';
3
3
  export * from './FullScreenPortal';
4
+ export * from './textSelectionDrag';
4
5
  //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,52 @@
1
+ /** The press {@link TextSelectionDrag.onPointerDown} reads — a React pointer event satisfies it. */
2
+ export interface TextSelectionPress {
3
+ button?: number;
4
+ shiftKey?: boolean;
5
+ clientX?: number;
6
+ clientY?: number;
7
+ target?: EventTarget | null;
8
+ }
9
+ /** {@link useTextSelectionDrag}'s handle — spread onto the field, or wire each handler by name. */
10
+ export interface TextSelectionDrag {
11
+ /** Call from the field's `pointerdown` — non-primary buttons are ignored. */
12
+ onPointerDown: (e?: TextSelectionPress) => void;
13
+ /**
14
+ * Refuses the browser's text DRAG-AND-DROP, so a press on the field always means "select".
15
+ *
16
+ * Once a field holds a selection, pressing ON that selection starts a drag of the text instead of a
17
+ * new one — which in app chrome has nowhere to land, so it reads as the no-drop cursor and eats the
18
+ * gesture. It costs most where a click selects the whole value (the font size and name boxes): the
19
+ * next drag, the one meant to pick out part of it, is the one that can't happen.
20
+ */
21
+ onDragStart: (e: {
22
+ preventDefault: () => void;
23
+ }) => void;
24
+ }
25
+ /**
26
+ * Keeps a text-selection drag alive once the pointer leaves the field, by two mechanisms.
27
+ *
28
+ * **Driving the selection.** From the press, each move re-reads the character under the pointer
29
+ * (clamped into the field) and sets the selection itself. This is what makes the gesture behave the
30
+ * same wherever the field is: the browser's own drag-extension resolves against the pointer's raw
31
+ * position, which comes out wrong for a field inside a transformed ancestor — the in-grid cell editor
32
+ * is placed by a `transform: translate(…)`, and its selection tracked an x offset by that translate.
33
+ * Asking for the offset explicitly goes through the same hit-test a click does, which is correct there.
34
+ *
35
+ * **Suspending the chrome's veto,** for the presses the first mechanism does not take: a `number` input
36
+ * (the selection API throws on one), a double/triple press (word and line granularity are the browser's),
37
+ * or a shift-press (it extends an existing selection from its own far end). App chrome is
38
+ * `user-select: none` — legitimately, since a drag over a toolbar
39
+ * or the grid means something other than selecting their text — and a browser abandons a drag-selection
40
+ * the moment the node under the pointer can't start one. That `none` states an intent that only holds
41
+ * BETWEEN gestures, and CSS has no way to say "except while a drag is in flight", so the class says it
42
+ * for exactly one. Nothing else becomes selectable in practice: a text control confines its own
43
+ * selection, so the selection cannot leave the field.
44
+ *
45
+ * Wire it to any field whose text is worth dragging across:
46
+ * ```tsx
47
+ * const textDrag = useTextSelectionDrag();
48
+ * <input onPointerDown={textDrag.onPointerDown} onDragStart={textDrag.onDragStart} />
49
+ * ```
50
+ */
51
+ export declare const useTextSelectionDrag: () => TextSelectionDrag;
52
+ //# sourceMappingURL=textSelectionDrag.d.ts.map