@sheetxl/utils-react 0.8.0-beta.1 → 0.8.0-beta.3
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/DO0nIGKXa_DxYcn6.cjs +1 -0
- package/browser/cjs/{D02anPwyfYZxlZmG.cjs → fw5WNnhzqSBOfVql.cjs} +1 -1
- package/browser/cjs/index.cjs +4 -4
- package/browser/esm/{CKvLZo8keTi4hdRr.mjs → BVSCLFr35t9aj9Tb.mjs} +1 -1
- package/browser/esm/{BIb3Fag4wDs4Gro1.mjs → CIIBEEXB3gcJPfdI.mjs} +3 -3
- package/browser/esm/index.mjs +1353 -1250
- package/browser/esm/{BT6JG-bEtM8ou0Xr.mjs → p0HsxM37dp6ewDyw.mjs} +40 -2
- package/node/esm/{CdJ0O_khlsS4DqVj.mjs → B-FM_8r9Y-QUf82k.mjs} +39 -1
- package/node/esm/{TlOKuBGsozMYzzBC.mjs → DSvJ69_AiNh6hzvs.mjs} +1 -1
- package/node/esm/index.mjs +1080 -971
- package/package.json +2 -2
- package/types/src/command/CommandCatalog.d.ts +2 -2
- package/types/src/command/index.d.ts +1 -0
- package/types/src/command/tags.d.ts +19 -0
- package/types/src/float/FloatPanel.d.ts +20 -0
- package/types/src/hooks/useImperativeElement.d.ts +1 -1
- package/types/src/hooks/useNotifier.d.ts +7 -4
- package/types/src/index.d.ts +1 -0
- package/types/src/lazy/index.d.ts +2 -0
- package/types/src/lazy/lazyComponent.d.ts +43 -0
- package/types/src/persistence/usePersistenceState.d.ts +2 -1
- package/types/src/theme/TokenTheme.d.ts +6 -5
- package/types/src/utils/index.d.ts +1 -0
- package/types/src/utils/textSelectionDrag.d.ts +52 -0
- package/browser/cjs/Dc-AA0ooFLVdAhbT.cjs +0 -1
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.
|
|
4
|
+
"version": "0.8.0-beta.3",
|
|
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.
|
|
44
|
+
"@sheetxl/utils": "^0.8.0-beta.3",
|
|
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
|
|
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
|
-
*
|
|
79
|
-
*
|
|
80
|
-
|
|
81
|
-
|
|
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
|
/**
|
package/types/src/index.d.ts
CHANGED
|
@@ -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
|
|
152
|
-
* carry no border. A flat design language
|
|
153
|
-
*
|
|
154
|
-
*
|
|
155
|
-
* Defaults to `transparent`, so the Material presentation is
|
|
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;
|
|
@@ -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
|