@sheetxl/utils-react 0.7.26 → 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.
Files changed (154) hide show
  1. package/browser/cjs/C7jPCqFJNiWyD2pr.cjs +1 -0
  2. package/browser/cjs/CyWMySHsu-RvsIGs.cjs +1 -0
  3. package/browser/cjs/DZSvmqU8nRas1uz6.cjs +1 -0
  4. package/browser/cjs/index.cjs +5 -7
  5. package/browser/esm/CD4Q4NRTfHSJirLz.mjs +139 -0
  6. package/browser/esm/DAwEWkKjQCR-nguL.mjs +2171 -0
  7. package/browser/esm/DUF3Ugd4Z1SDNXPb.mjs +390 -0
  8. package/browser/esm/index.mjs +6128 -1806
  9. package/licenses/dependencies.txt +246 -39
  10. package/node/esm/DA8vLJ8AED3TYoSo.mjs +2171 -0
  11. package/node/esm/DKS7p6NraAuZKdCC.mjs +139 -0
  12. package/node/esm/index.mjs +5141 -1774
  13. package/package.json +8 -5
  14. package/types/index.d.ts +2 -2043
  15. package/types/src/animation/AnimationModeContext.d.ts +10 -0
  16. package/types/src/animation/index.d.ts +3 -0
  17. package/types/src/animation/useAnimatedMeasure.d.ts +39 -0
  18. package/types/src/command/ActivationTracker.d.ts +53 -0
  19. package/types/src/command/CommandAnchorProvider.d.ts +64 -0
  20. package/types/src/command/CommandButtonEntryLabel.d.ts +25 -0
  21. package/types/src/command/CommandButtonRegistry.d.ts +159 -0
  22. package/types/src/command/CommandButtonRegistryContext.d.ts +35 -0
  23. package/types/src/command/CommandCatalog.d.ts +155 -0
  24. package/types/src/command/CommandCatalogResource.d.ts +7 -0
  25. package/types/src/command/CommandCatalogService.d.ts +61 -0
  26. package/types/src/command/CommandChainContext.d.ts +32 -0
  27. package/types/src/command/CommandFallbackContext.d.ts +30 -0
  28. package/types/src/command/CommandFocusContext.d.ts +21 -0
  29. package/types/src/command/CommandRegistry.d.ts +164 -0
  30. package/types/src/command/CommandRegistryContext.d.ts +16 -0
  31. package/types/src/command/CommandResolver.d.ts +162 -0
  32. package/types/src/command/CommandScope.d.ts +343 -0
  33. package/types/src/command/CommandScopeContext.d.ts +205 -0
  34. package/types/src/command/FocusActivation.d.ts +140 -0
  35. package/types/src/command/ICommand.d.ts +31 -0
  36. package/types/src/command/ICommandDefinition.d.ts +82 -0
  37. package/types/src/command/KeyBindingDispatcher.d.ts +150 -0
  38. package/types/src/command/LayerActivation.d.ts +45 -0
  39. package/types/src/command/Types.d.ts +80 -0
  40. package/types/src/command/createResolvedCommand.d.ts +91 -0
  41. package/types/src/command/index.d.ts +26 -0
  42. package/types/src/command/reduceDefinitions.d.ts +33 -0
  43. package/types/src/command/useCommands.d.ts +22 -0
  44. package/types/src/command/useContributeCommands.d.ts +18 -0
  45. package/types/src/components/FocusKeyNavigation.d.ts +22 -0
  46. package/types/src/components/ITooltip.d.ts +38 -0
  47. package/types/src/components/RoundedTab.d.ts +26 -0
  48. package/types/src/components/index.d.ts +4 -0
  49. package/types/src/error/ErrorPanel.d.ts +14 -0
  50. package/types/src/error/ReactErrorBoundary.d.ts +7 -0
  51. package/types/src/error/UncaughtErrorBoundary.d.ts +5 -0
  52. package/types/src/error/index.d.ts +4 -0
  53. package/types/src/float/FloatPanel.d.ts +57 -0
  54. package/types/src/float/FloatPopper.d.ts +85 -0
  55. package/types/src/float/FloatPopup.d.ts +19 -0
  56. package/types/src/float/FloatProvider.d.ts +60 -0
  57. package/types/src/float/FloatStackContext.d.ts +25 -0
  58. package/types/src/float/FloatTooltip.d.ts +22 -0
  59. package/types/src/float/FloatUtils.d.ts +55 -0
  60. package/types/src/float/_FloatUtils.d.ts +51 -0
  61. package/types/src/float/index.d.ts +9 -0
  62. package/types/src/float/useFloatStack.d.ts +92 -0
  63. package/types/src/hooks/LanguageState.d.ts +15 -0
  64. package/types/src/hooks/index.d.ts +19 -0
  65. package/types/src/hooks/useBoundSyncExternalStore.d.ts +23 -0
  66. package/types/src/hooks/useCallbackRef.d.ts +11 -0
  67. package/types/src/hooks/useDevicePixelRatio.d.ts +37 -0
  68. package/types/src/hooks/useEditMode.d.ts +66 -0
  69. package/types/src/hooks/useGlobalClipboard.d.ts +7 -0
  70. package/types/src/hooks/useId.d.ts +9 -0
  71. package/types/src/hooks/useImperativeElement.d.ts +3 -0
  72. package/types/src/hooks/useLanguage.d.ts +13 -0
  73. package/types/src/hooks/useMouseDownAndHoldListener.d.ts +13 -0
  74. package/types/src/hooks/useNotifier.d.ts +330 -0
  75. package/types/src/hooks/useOnClickOrFocusAway.d.ts +8 -0
  76. package/types/src/hooks/useOptionalBoundSyncExternalStore.d.ts +20 -0
  77. package/types/src/hooks/useOptionalSyncExternalStore.d.ts +18 -0
  78. package/types/src/hooks/useSynchronizedPointerHandler.d.ts +54 -0
  79. package/types/src/hooks/useTextareaCaretRect.d.ts +85 -0
  80. package/types/src/hooks/useTraceUpdate.d.ts +2 -0
  81. package/types/src/hooks/useTranslator.d.ts +32 -0
  82. package/types/src/icons/DynamicIcon.d.ts +17 -0
  83. package/types/src/icons/DynamicIconService.d.ts +39 -0
  84. package/types/src/icons/ErrorIcon.d.ts +6 -0
  85. package/types/src/icons/Types.d.ts +81 -0
  86. package/types/src/icons/WalkingIcon.d.ts +27 -0
  87. package/types/src/icons/_Utils.d.ts +3 -0
  88. package/types/src/icons/index.d.ts +5 -0
  89. package/types/src/icons/packs/Base.d.ts +4 -0
  90. package/types/src/icons/packs/Conditional.d.ts +4 -0
  91. package/types/src/index.d.ts +18 -0
  92. package/types/src/loading/LoadingPanel.d.ts +31 -0
  93. package/types/src/loading/index.d.ts +2 -0
  94. package/types/src/persistence/InMemoryStore.d.ts +12 -0
  95. package/types/src/persistence/LocalStorageStore.d.ts +15 -0
  96. package/types/src/persistence/PersistenceStateProvider.d.ts +3 -0
  97. package/types/src/persistence/Types.d.ts +95 -0
  98. package/types/src/persistence/_Context.d.ts +9 -0
  99. package/types/src/persistence/index.d.ts +6 -0
  100. package/types/src/persistence/usePersistenceState.d.ts +33 -0
  101. package/types/src/react-resizable/Resizable.d.ts +30 -0
  102. package/types/src/react-resizable/ResizableBox.d.ts +18 -0
  103. package/types/src/react-resizable/index.d.ts +11 -0
  104. package/types/src/react-resizable/propTypes.d.ts +56 -0
  105. package/types/src/react-resizable/utils.d.ts +3 -0
  106. package/types/src/scroll/AxisViewport.d.ts +73 -0
  107. package/types/src/scroll/IScrollPane.d.ts +63 -0
  108. package/types/src/scroll/IScrollbar.d.ts +94 -0
  109. package/types/src/scroll/NativeScrollbar.d.ts +7 -0
  110. package/types/src/scroll/ScrollButton.d.ts +29 -0
  111. package/types/src/scroll/ScrollPane.d.ts +4 -0
  112. package/types/src/scroll/Scrollbar.d.ts +4 -0
  113. package/types/src/scroll/TouchThumbContext.d.ts +93 -0
  114. package/types/src/scroll/TouchThumbHandle.d.ts +64 -0
  115. package/types/src/scroll/TrackDrag.d.ts +107 -0
  116. package/types/src/scroll/Utils.d.ts +8 -0
  117. package/types/src/scroll/Viewport.d.ts +285 -0
  118. package/types/src/scroll/VirtualScrollbar.d.ts +49 -0
  119. package/types/src/scroll/index.d.ts +14 -0
  120. package/types/src/scroll/scrollbarTheming.d.ts +27 -0
  121. package/types/src/scroll/useWheelScroll.d.ts +27 -0
  122. package/types/src/scroller/Scroller.d.ts +260 -0
  123. package/types/src/scroller/animate.d.ts +30 -0
  124. package/types/src/scroller/index.d.ts +2 -0
  125. package/types/src/singletonHook/components/SingleItemContainer.d.ts +6 -0
  126. package/types/src/singletonHook/components/SingletonHooksContainer.d.ts +7 -0
  127. package/types/src/singletonHook/index.d.ts +11 -0
  128. package/types/src/singletonHook/singletonHook.d.ts +6 -0
  129. package/types/src/singletonHook/utils/env.d.ts +4 -0
  130. package/types/src/singletonHook/utils/env.native.d.ts +1 -0
  131. package/types/src/singletonHook/utils/warning.d.ts +2 -0
  132. package/types/src/splitPane/SplitPane.d.ts +91 -0
  133. package/types/src/splitPane/SplitPaneResizer.d.ts +11 -0
  134. package/types/src/splitPane/index.d.ts +3 -0
  135. package/types/src/theme/TokenTheme.d.ts +196 -0
  136. package/types/src/theme/TokenThemeProvider.d.ts +97 -0
  137. package/types/src/theme/buildThemeCSS.d.ts +54 -0
  138. package/types/src/theme/createThemeVars.d.ts +15 -0
  139. package/types/src/theme/defaultTheme.d.ts +15 -0
  140. package/types/src/theme/index.d.ts +9 -0
  141. package/types/src/theme/resolveTokens.d.ts +21 -0
  142. package/types/src/theme/themeAttrs.d.ts +32 -0
  143. package/types/src/theme/useResolvedThemeMode.d.ts +17 -0
  144. package/types/src/types/Types.d.ts +71 -0
  145. package/types/src/types/index.d.ts +2 -0
  146. package/types/src/utils/FullScreenPortal.d.ts +6 -0
  147. package/types/src/utils/PinchZoom.d.ts +3 -0
  148. package/types/src/utils/ReactUtils.d.ts +134 -0
  149. package/types/src/utils/index.d.ts +4 -0
  150. package/types/src/utils/useFullScreen.d.ts +47 -0
  151. package/browser/cjs/CPBtiUesoF7a_blY.cjs +0 -6
  152. package/browser/esm/B3-sQiNCaM33P0MK.mjs +0 -12
  153. package/node/assets/style.css +0 -1
  154. package/node/esm/C-L_tZzbahpe6TAI.mjs +0 -12
@@ -0,0 +1,32 @@
1
+ import { RemoveListener } from '@sheetxl/utils';
2
+ import { CommandScope } from './CommandScope';
3
+ /**
4
+ * A **z-ordered command-parent chain** a declarative scope can join — the *mechanism 1* seam for **#5**
5
+ * (design/COMMAND-DESIGN.md §"Layered resolver"): grid layers are DOM siblings but must resolve as a
6
+ * command-parent chain ordered by z. `register` slots `scope` into the chain at `order` (higher = deeper =
7
+ * wins the cascade) with **reparent-on-insert**, and returns an unregister. A pane's {@link LayerActivation}
8
+ * is the concrete implementation; this interface is what a chain-aware {@link CommandScopeProvider} needs,
9
+ * so `utils-react` stays free of any grid dependency.
10
+ */
11
+ export interface CommandChain {
12
+ /** Join `scope` to the chain at `order` (reparent-on-insert). Returns an unregister that re-chains the rest. */
13
+ register(scope: CommandScope, order: number): RemoveListener;
14
+ }
15
+ /**
16
+ * The ambient z-chain a layer's {@link CommandScopeProvider} joins, or `null` **outside** a chain — the
17
+ * ordinary case where a provider parents to its React ancestor scope. Provided **per pane** (by the grid's
18
+ * `wrapPane` seam). A `CommandScopeProvider` that joins a chain provides `null` to its own descendants, so
19
+ * nested features parent normally rather than re-joining.
20
+ */
21
+ export declare const CommandChainContext: import('react').Context<CommandChain | null>;
22
+ /** The ambient {@link CommandChain}, or `null` outside a chain-providing region (a pane). */
23
+ export declare function useCommandChain(): CommandChain | null;
24
+ /**
25
+ * The ambient **order** (a layer's z) a {@link CommandScopeProvider} joins the {@link CommandChain} at. `0`
26
+ * outside a stacking context. A layer supplies its own z via the `order` prop (its `useLayer().zIndex`) which
27
+ * takes precedence over this context — the one grid-aware value, kept out of `utils-react`.
28
+ */
29
+ export declare const CommandOrderContext: import('react').Context<number>;
30
+ /** The ambient join order (a layer's z), or `0` outside a stacking context. */
31
+ export declare function useCommandOrder(): number;
32
+ //# sourceMappingURL=CommandChainContext.d.ts.map
@@ -0,0 +1,30 @@
1
+ import { ReactNode } from 'react';
2
+ /**
3
+ * A container's **not-in-context fallback** prefer-list — the priority names a consumer (a toolbar / menu)
4
+ * uses to show a command whose scope isn't currently contributing (design/COMMAND-DESIGN.md §"Named
5
+ * scopes"). `null` ⇒ this subtree does **no** fallback (a bare `useCommands` returns `undefined` for a
6
+ * not-in-context key). An empty array ⇒ fallback is on, but with no preference — straight to "search all".
7
+ *
8
+ * This is purely a **consumer** concern: it never touches the resolver/dispatcher/registry core. The
9
+ * keyboard dispatcher, which reads none of this, stays a pure context resolver (an inert static never
10
+ * binds a shortcut — an idle editor's F4 falls to `redo`).
11
+ */
12
+ export declare const CommandFallbackContext: import('react').Context<readonly string[] | null>;
13
+ /** The nearest container's fallback prefer-list, or `null` if this subtree has no fallback. */
14
+ export declare function useCommandFallback(): readonly string[] | null;
15
+ export interface CommandFallbackProviderProps {
16
+ /**
17
+ * Priority names searched first on a not-in-context miss (then **all** names). Omit ⇒ fallback on with no
18
+ * preference (straight to "search all"). Pass a **stable** reference (memoize/const) — a new array each
19
+ * render re-runs consumers.
20
+ */
21
+ prefer?: readonly string[];
22
+ children: ReactNode;
23
+ }
24
+ /**
25
+ * Turn on the not-in-context fallback for descendant {@link useCommands} consumers — so a toolbar under it
26
+ * shows a not-currently-contributed command **disabled** (from its static default) instead of blank. See
27
+ * {@link CommandScope.resolveStatic} for the resolution primitive it drives.
28
+ */
29
+ export declare function CommandFallbackProvider({ prefer, children }: CommandFallbackProviderProps): ReactNode;
30
+ //# sourceMappingURL=CommandFallbackContext.d.ts.map
@@ -0,0 +1,21 @@
1
+ /**
2
+ * A "restore focus after a command runs" callback, published by a container (e.g. a toolbar) and
3
+ * invoked by descendant {@link useCommands} consumers on execute.
4
+ *
5
+ * This is the focus analogue of the enclosing-float close-on-execute (see `useFloat`): behavior
6
+ * belongs to the **consumer/container**, discovered through context, never threaded per-button.
7
+ * A toolbar captures the element that was focused before the toolbar took focus and, after a button
8
+ * runs a command, returns focus there (so the grid keeps the caret). `null` ⇒ no restore.
9
+ *
10
+ * The callback is expected to be a stable reference (e.g. `useCallbackRef`) and to no-op when focus
11
+ * has already left the container — so a *remote* dispatch (a keystroke from the grid) never steals it.
12
+ */
13
+ export type CommandFocusRestore = () => void;
14
+ /**
15
+ * Provides a {@link CommandFocusRestore} to descendant {@link useCommands} consumers. A container
16
+ * that wants focus returned after its buttons execute wraps them with this.
17
+ */
18
+ export declare const CommandFocusProvider: import('react').Provider<CommandFocusRestore | null>;
19
+ /** The nearest container's focus-restore callback, or `null` when none is provided. */
20
+ export declare function useCommandFocusRestore(): CommandFocusRestore | null;
21
+ //# sourceMappingURL=CommandFocusContext.d.ts.map
@@ -0,0 +1,164 @@
1
+ import { RemoveListener } from '@sheetxl/utils';
2
+ import { ICommandDefinition } from './ICommandDefinition';
3
+ import { StaticCommandContributor, CommandContributionComponent } from './CommandScopeContext';
4
+ /**
5
+ * One contributor's **layer** in a `(name, key)` stack. Instance-**independent** presentation
6
+ * (icon/label/shortcut/description/tags) plus any model-free stub/default — never a model-closured
7
+ * callback (that lives on the instance scope, not the shared name; see design/COMMAND-DESIGN.md
8
+ * §"Named scopes"). `contributor` is the layer's identity: re-registering the **same** contributor
9
+ * **replaces** its layer (idempotent re-seed); a **different** contributor **pushes** a new one
10
+ * (last-registered wins the reduce).
11
+ */
12
+ interface RegistryLayer {
13
+ contributor: unknown;
14
+ def: Omit<ICommandDefinition<any, any, any>, 'key'>;
15
+ }
16
+ /**
17
+ * A tracked contribution **session** on a registry name (see {@link CommandRegistry.contribution}) —
18
+ * the registry counterpart of {@link CommandContribution}. Every {@link updateCommand} records the key
19
+ * under this contributor's identity; {@link remove} tears down exactly those layers. Shaped so the
20
+ * existing `register*Definitions(target)` seeders write into a name with no change beyond the target.
21
+ */
22
+ export interface CommandRegistryContribution {
23
+ updateCommand<STATE = any, CONTEXT = any, ARGS = void>(commandKey: string, partial: Omit<ICommandDefinition<STATE, CONTEXT, ARGS>, 'key'>): void;
24
+ /** Remove this contributor's layer from every key it touched on this name. Idempotent. */
25
+ remove(): void;
26
+ }
27
+ /** Fires whenever the registry's contents change (so a bound scope can bump its resolve version). */
28
+ export interface CommandRegistryListener {
29
+ onChange?(): void;
30
+ }
31
+ /**
32
+ * The **flat named registry** — `Map<name, Map<key, layer-stack>>`, **parent-less** (NOT a tree). It
33
+ * holds only **instance-independent, STATIC** command definitions (default presentation + any model-free
34
+ * stub) and **is the catalog**: fully enumerable, seedable at app-init with zero instances mounted.
35
+ *
36
+ * It is the **static** half of "static contribution + dynamic contribution" (design/COMMAND-DESIGN.md
37
+ * §"Named scopes"): a {@link CommandScope} instance carries a `name`, and {@link CommandScope.resolve}
38
+ * folds `registry[name]` in as the least-specific defaults — **but only for a command that also has a
39
+ * live dynamic contribution** (a scope's own def). A static entry with no dynamic contributor stays in
40
+ * the catalog (discoverable) yet does not resolve, so its shortcut never binds. This is why there is **no
41
+ * `catalogOnly`**: an inactive scope simply isn't contributing dynamically, so its statics aren't pulled
42
+ * — the editor's idle F4 falls to `redo` for free, and a `table` command is dormant until a table is
43
+ * active. Element lifecycle ≠ command lifecycle; a mounted scope that stops contributing a key looks, to
44
+ * resolution, exactly like one that unmounted.
45
+ *
46
+ * Names have **no hierarchy** — `app/workbook/movable/sheet/selection/editor` etc. is just typical
47
+ * mounting plus a catalog display-order hint; which name wins at resolve is decided entirely by live
48
+ * instance-tree position, never by the registry.
49
+ *
50
+ * A `(name, key)` is a **layer stack**, not one merged def, so multiple contributors (the core catalog +
51
+ * N plugins) coexist and **remove independently**. Layers reduce by the same {@link reduceDefinitions}
52
+ * policy as the scope chain (override per property; accumulate `disabledReasons`/`tags`), keyed by
53
+ * contributor identity (same → replace, other → push).
54
+ */
55
+ export declare class CommandRegistry {
56
+ /** name → (key → ordered layer stack, least→most specific = push order). */
57
+ protected _byName: Map<string, Map<string, RegistryLayer[]>>;
58
+ /** name → plugin dynamic contribution components (rendered per live instance; see {@link registerDynamic}). */
59
+ protected _dynamicByName: Map<string, Set<CommandContributionComponent>>;
60
+ protected _listeners: Set<CommandRegistryListener>;
61
+ /** Open {@link batch} windows; while > 0 the listener fan-out is suspended (version still bumps). */
62
+ protected _batchDepth: number;
63
+ protected _batchDirty: boolean;
64
+ /**
65
+ * Run `fn` with the listener fan-out suspended, firing ONE notify at close iff anything changed
66
+ * inside. `getVersion()` still bumps per change, so synchronous readers (the resolve caches key on
67
+ * it) are never stale — only the fan-out is coalesced. Nestable: inner batches fold into the
68
+ * outermost. The bulk paths ({@link registerStatic}, a contribution's `remove()`, catalog seeding)
69
+ * run through this so a K-command seed wakes each subscriber once, not K times — per-key fan-out
70
+ * during load-time seeding was a main-thread stall (design/COMMAND-EMIT-PERFORMANCE.md).
71
+ */
72
+ batch(fn: () => void): void;
73
+ /**
74
+ * Trigger a re-resolution **without** changing any registration (mirrors
75
+ * {@link CommandScope.invalidate}) — e.g. the active language changed, so
76
+ * translator-resolved chrome must re-derive.
77
+ */
78
+ invalidate(): void;
79
+ /**
80
+ * Contribute/replace `partial` for `(name, commandKey)` under `contributor`. Same contributor +
81
+ * key **replaces** the existing layer wholesale (idempotent re-seed — no double-accumulation of
82
+ * `tags`/`disabledReasons`); a new contributor **pushes** a most-specific layer. Bumps listeners.
83
+ */
84
+ register(name: string, commandKey: string, partial: Omit<ICommandDefinition<any, any, any>, 'key'>, contributor?: unknown): void;
85
+ /** Remove `contributor`'s layer from `(name, commandKey)`. Bumps listeners iff something changed. */
86
+ removeCommand(name: string, commandKey: string, contributor: unknown): void;
87
+ /**
88
+ * Remove **every** layer `contributor` seeded on `name`, across all command keys. The bulk twin of
89
+ * {@link removeCommand} — used when a whole source drops out of a name (e.g. the catalog service
90
+ * clearing a source that has no pack for the newly-active language, so a bundled-`en` floor leaves no
91
+ * stale chrome behind). Bumps listeners iff something changed.
92
+ */
93
+ removeContributor(name: string, contributor: unknown): void;
94
+ /**
95
+ * Open a tracked {@link CommandRegistryContribution} on `name` under `contributor` — the registry
96
+ * twin of {@link CommandScope.contribution}. The `register*Definitions(target)` seeders take this as
97
+ * their `target`, so moving a seed from `register(root)` onto a name is a one-argument change.
98
+ * `contributor` defaults to the `name` (one core catalog layer per name); pass a distinct token for a
99
+ * plugin that must coexist with / override the base.
100
+ */
101
+ contribution(name: string, contributor?: unknown): CommandRegistryContribution;
102
+ /**
103
+ * Seed a **static** contributor for `name` — instance-independent presentation into the catalog, idempotent
104
+ * by the contributor fn's identity (re-register replaces its layer). The app-load counterpart of a feature
105
+ * provider seeding its chrome; a plugin calls this to inject static into an existing name.
106
+ */
107
+ registerStatic(name: string, contributor: StaticCommandContributor): void;
108
+ /**
109
+ * Register a plugin's **dynamic** contribution {@link CommandContributionComponent} for `name` — a React
110
+ * component {@link CommandScopeProvider} renders at **every live instance** of that named scope (so it
111
+ * inherits the React context there and contributes via `props.scope.contribution()`). Returns a remover.
112
+ */
113
+ registerDynamic(name: string, component: CommandContributionComponent): RemoveListener;
114
+ /** The registered dynamic contribution components for `name` (registration order). */
115
+ getDynamic(name: string): CommandContributionComponent[];
116
+ /**
117
+ * The reduced, instance-independent definition for `(name, commandKey)` — the whole layer stack
118
+ * folded by {@link reduceDefinitions} (least→most specific). Read by {@link CommandScope.resolve} as
119
+ * a node's static defaults AND by the catalog (shortcut dialog / palette). `undefined` if nothing is
120
+ * registered.
121
+ */
122
+ resolveDefinition(name: string, commandKey: string): ICommandDefinition | undefined;
123
+ /**
124
+ * Find a key's static definition by searching names in `prefer` order first, then **all** names — the
125
+ * lookup a *consumer's* not-in-context fallback composes (design/COMMAND-DESIGN.md §"Named scopes"): a
126
+ * toolbar prefers the names it represents, then falls back to any name (so a plugin's command registered
127
+ * under an unforeseen name still shows). Returns the first match's `name` + reduced def, or `undefined`
128
+ * if no name has the key. This is a pure search — the *policy* (whether to fall back, the `prefer` list)
129
+ * lives in the consumer, never in resolution/dispatch.
130
+ */
131
+ findByKey(commandKey: string, prefer?: readonly string[]): {
132
+ name: string;
133
+ def: ICommandDefinition;
134
+ } | undefined;
135
+ /** All names with at least one registered command. */
136
+ names(): string[];
137
+ /** All command keys registered on `name` (deduped; order unspecified). */
138
+ keys(name: string): string[];
139
+ /**
140
+ * Command keys on `name` whose **reduced** definition carries `tag`. The registry counterpart of
141
+ * {@link CommandScope.collectKeysByTag}, so a tag authored in the catalog (e.g. `mutator`) is still
142
+ * found by a contributor's cross-cutting rule after the chrome moved off the scope and into the
143
+ * registry. Order unspecified; deduped.
144
+ */
145
+ collectKeysByTag(name: string, tag: string): string[];
146
+ /** Subscribe to registry changes (a bound {@link CommandScope} re-resolves on fire). */
147
+ addListener(listener: CommandRegistryListener): RemoveListener;
148
+ /**
149
+ * Monotonic change counter — a `useSyncExternalStore` snapshot for consumers that read registry
150
+ * chrome directly (e.g. command-button entries). Bumps whenever the catalog changes, including the
151
+ * async re-seed after a language switch (which a language-tag snapshot alone would miss).
152
+ */
153
+ getVersion(): number;
154
+ protected _version: number;
155
+ protected _notify(): void;
156
+ }
157
+ /**
158
+ * The shared **singleton** command registry — the catalog + plugin static/dynamic registrations, mirroring
159
+ * {@link DefaultCommandButtonRegistry}. `CommandRootProvider` uses this as its registry, so a plugin's
160
+ * `registerStatic` / `registerDynamic` at app-init reaches resolution and the per-instance mount machinery.
161
+ */
162
+ export declare const DefaultCommandRegistry: CommandRegistry;
163
+ export {};
164
+ //# sourceMappingURL=CommandRegistry.d.ts.map
@@ -0,0 +1,16 @@
1
+ import { CommandRegistry } from './CommandRegistry';
2
+ /**
3
+ * The flat named {@link CommandRegistry} (the static catalog) for one mounted command host, provided
4
+ * near the command root. The counterpart of the scope tree's *dynamic* contributions: the registry
5
+ * holds the instance-independent presentation (icon/label/shortcut/tags) every feature seeds.
6
+ */
7
+ export declare const CommandRegistryContext: import('react').Context<CommandRegistry | null>;
8
+ /**
9
+ * The ambient {@link CommandRegistry}, or `null` outside a provider.
10
+ *
11
+ * Prefer this over `scope.getRoot().getRegistry()`: the registry is a **container** concern, reached
12
+ * by context like {@link useCommandButtonRegistry}, not by walking the scope tree to its root. A
13
+ * feature provider reads it to seed its static chrome; it never needs the root scope to do so.
14
+ */
15
+ export declare function useCommandRegistry(): CommandRegistry | null;
16
+ //# sourceMappingURL=CommandRegistryContext.d.ts.map
@@ -0,0 +1,162 @@
1
+ import { RemoveListener } from '@sheetxl/utils';
2
+ import { CommandScope } from './CommandScope';
3
+ import { ICommandDefinition } from './ICommandDefinition';
4
+ import { ActivationTracker } from './ActivationTracker';
5
+ import { ResolvedCommand } from './createResolvedCommand';
6
+ import { KeyBindingDispatcher, DispatchKeyEvent } from './KeyBindingDispatcher';
7
+ /**
8
+ * A hook that lets a feature **inject a contribution into resolution, given the active DOM element** —
9
+ * consulted per key by {@link CommandResolver.resolve} and spliced as the **most-specific** (leaf)
10
+ * contribution, so it wins the cascade over the scope chain (but loses to the element's own scope, if
11
+ * it authored the key — ordinary `override`). Return `undefined` to contribute nothing for this
12
+ * `(key, element)`.
13
+ *
14
+ * The mechanism is generic — it knows nothing about clipboard or inputs. Its first consumer is the
15
+ * input-clipboard set (`copy`/`cut`/`paste`/`selectAll` acting on a focused text input): the injector
16
+ * gates on "is `element` an editable" and returns the callback + enablement, so a focused input's copy
17
+ * out-resolves the grid's cell copy, and a region with no `copy` (the script editor) gains one — both
18
+ * with no scope-tree surgery. See design/COMMAND-INPUT-CLIPBOARD-PLAN.md.
19
+ */
20
+ export type ResolveInjector = (commandKey: string, element: Element | null) => Partial<ICommandDefinition> | undefined;
21
+ export interface CommandResolverOptions {
22
+ /**
23
+ * Display cadence (ms): coalesce re-emits — covering **both** anchor changes (rapid focus)
24
+ * and scope contribution changes (the tab-spin / `invalidate` case). `0` ⇒ immediate.
25
+ */
26
+ debounce?: number;
27
+ /**
28
+ * Auto-attach **native** keystroke handling to the tracker's region element (default `true`).
29
+ * Set `false` when the host delivers keys to {@link CommandResolver.dispatchKey} itself — e.g. the
30
+ * grid routes them through its (synthetic) Stage responder chain as a terminal `Layer` tap, so it
31
+ * stays on **one** event system instead of mixing a native listener into synthetic dispatch (see
32
+ * design/COMMAND-DESIGN.md "Core law — one keystroke bubble"). The dispatch *logic* is identical
33
+ * either way; only delivery differs.
34
+ */
35
+ keyBindings?: boolean;
36
+ /**
37
+ * The **terminal** node the bounded `(anchor → root)` walk stops at (design/COMMAND-DESIGN.md
38
+ * §"resolution model") — this container's topmost node (e.g. `sheet` for a context menu, the app
39
+ * root for the studio). Omit ⇒ walk to the true tree root (unbounded — the studio default). A
40
+ * container that wants commands defined *above* its `root` **re-anchors**; the engine only offers
41
+ * the bounded walk.
42
+ */
43
+ root?: CommandScope;
44
+ }
45
+ /**
46
+ * The per-container resolution authority — the second non-React core, paired with
47
+ * {@link CommandScope}. It binds a registry `scope` to an {@link ActivationTracker} (its
48
+ * **anchor** source) and answers `resolve(key)` / `execute(key)` **from the tracker's current
49
+ * anchor**. A single {@link subscribe} coalesces *both* anchor changes and scope contribution
50
+ * changes at the {@link CommandResolverOptions.debounce} cadence, so a consumer subscribes to
51
+ * one thing.
52
+ *
53
+ * `scope` is fixed for the resolver's life; a React provider recreates + {@link dispose}s the
54
+ * resolver when the scope changes (see design/COMMAND-DESIGN.md).
55
+ */
56
+ export declare class CommandResolver {
57
+ readonly scope: CommandScope;
58
+ protected readonly _tracker: ActivationTracker;
59
+ /** The bounded-walk terminal (this container's topmost node); `undefined` ⇒ the true tree root. */
60
+ protected readonly _root?: CommandScope;
61
+ protected readonly _debounceMs: number;
62
+ protected _version: number;
63
+ protected _listeners: Set<() => void>;
64
+ protected _timer: ReturnType<typeof setTimeout> | undefined;
65
+ /** Emits arrived while the debounce window was open (⇒ ONE trailing notify when it closes). */
66
+ protected _dirty: boolean;
67
+ /** Whether the tracker has ever yielded an anchor — the first one flushes undebounced (see {@link _emitAnchorChange}). */
68
+ protected _hadAnchor: boolean;
69
+ /** Scope + tracker subscriptions; (re)established by {@link connect}, torn down by {@link dispose}. */
70
+ protected _unsubs: RemoveListener[];
71
+ protected _connected: boolean;
72
+ /** Resolve-time injectors (see {@link addResolveInjector}); consulted per key in {@link resolve}. */
73
+ protected _injectors: Set<ResolveInjector>;
74
+ protected readonly _keyBindings: KeyBindingDispatcher;
75
+ protected readonly _autoKeyBindings: boolean;
76
+ protected _keyBindsEl: Element | null;
77
+ protected _keyBindsDetach: RemoveListener | undefined;
78
+ constructor(scope: CommandScope, tracker: ActivationTracker, options?: CommandResolverOptions);
79
+ /**
80
+ * (Re)establish this resolver's subscriptions to its scope + tracker. Idempotent. Called by the
81
+ * owning provider's mount effect — so a resolver that was
82
+ * {@link dispose}d on an effect *cleanup* (e.g. React StrictMode's mount→unmount→remount, or a
83
+ * transient parent unmount) comes back to life on remount instead of staying permanently deaf.
84
+ * Without this, the useMemo'd instance survives the cleanup but its scope subscription doesn't,
85
+ * so contributions stop reaching `_emit` and consumers freeze.
86
+ */
87
+ connect(): void;
88
+ /**
89
+ * Anchor/region notifications: the tracker's FIRST anchor (`null` → the consumer's one-shot initial
90
+ * anchor, or a first real focus) flushes **immediately**, bypassing any open debounce window — the
91
+ * studio resolves its initial anchor right before the loading reveal, and the reveal must paint
92
+ * enabled commands (a coalesced window here read as a disabled-toolbar flash). Later anchor moves
93
+ * (focus) coalesce through the normal debounce.
94
+ */
95
+ protected _emitAnchorChange(): void;
96
+ /**
97
+ * Dispatch a keyboard event through this resolver's bindings (event → command at the current
98
+ * anchor). The host's keystroke entry when it delivers keys itself (`keyBindings: false`) — e.g. a
99
+ * grid terminal `Layer` tap calls this with the (synthetic) event, keeping the grid on one event
100
+ * system. Accepts a native or React keyboard event. Returns whether it was consumed.
101
+ */
102
+ dispatchKey(event: DispatchKeyEvent): boolean;
103
+ /**
104
+ * Resolve a command from the tracker's current anchor, bounded by this resolver's `root` terminal.
105
+ * `origin` (keystroke dispatch only) applies per-contribution **origin containment** — see
106
+ * {@link CommandScope.resolve}; buttons/display omit it.
107
+ */
108
+ resolve<STATE = any, CONTEXT = any, ARGS = void>(commandKey: string, origin?: Node | null): ResolvedCommand<STATE, CONTEXT, ARGS> | undefined;
109
+ /**
110
+ * The command keys reachable from the current anchor, **bounded by this resolver's `root`** — the
111
+ * enumeration the {@link KeyBindingDispatcher} matches an event against. Bounding it here (not at
112
+ * `scope.collectKeys`) keeps a container from binding shortcuts for commands above its terminal.
113
+ */
114
+ collectKeys(): string[];
115
+ /**
116
+ * Register a {@link ResolveInjector} — a hook that may contribute a leaf (most-specific) definition
117
+ * for a key, given the active DOM element, on every {@link resolve}. Returns a remover. Re-emits so
118
+ * consumers re-resolve immediately (and again on removal). Both buttons and keystrokes funnel through
119
+ * {@link resolve}, so one registration covers both paths. See design/COMMAND-INPUT-CLIPBOARD-PLAN.md.
120
+ */
121
+ addResolveInjector(injector: ResolveInjector): RemoveListener;
122
+ /**
123
+ * Gather the injected leaf contributions for `commandKey` from the registered injectors, each fed the
124
+ * **active DOM element** (`document.activeElement` — the resolver's leaf; focus/activation is handled
125
+ * elsewhere). `undefined` when nothing is contributed, so the common path stays fully cached. Each
126
+ * def is normalized to carry `key` so it reduces cleanly.
127
+ */
128
+ protected _collectInjected(commandKey: string): ICommandDefinition[] | undefined;
129
+ /** The tracker's current anchor (or the registry root if none) — used by the dispatcher. */
130
+ getAnchor(): CommandScope;
131
+ /** Resolve + dispatch by key (the imperative / keystroke entry point). */
132
+ execute<ARGS = void>(commandKey: string, args?: ARGS): Promise<boolean>;
133
+ /** Monotonic version; bumps on each (debounced) re-emit — a stable `useSyncExternalStore` snapshot. */
134
+ getVersion(): number;
135
+ /**
136
+ * Force a re-resolution emit. For an {@link addResolveInjector injector} whose result depends on
137
+ * **live DOM state** that changed without a scope/anchor change — e.g. the caret selection in a
138
+ * focused input (a `selectionchange` doesn't touch the scope tree, yet a selection-gated `copy`
139
+ * enablement must re-evaluate). Coalesced by the resolver's debounce like any other emit.
140
+ */
141
+ invalidate(): void;
142
+ /** Subscribe to re-resolution (anchor OR contribution changed), at the debounce cadence. */
143
+ subscribe(listener: () => void): RemoveListener;
144
+ /**
145
+ * Detach from scope + tracker + keybinds. Called on the provider effect's cleanup (unmount / scope
146
+ * change). Leaves the instance **reusable**: a following {@link connect} re-establishes everything
147
+ * (the StrictMode remount path). `_listeners` is cleared here, but consumers re-subscribe via their
148
+ * own `useSyncExternalStore` on remount, so no listener is lost.
149
+ */
150
+ dispose(): void;
151
+ /**
152
+ * Bind/rebind keystroke handling to the tracker's current region element. Called on
153
+ * construction and whenever the tracker notifies (the region may attach after mount). A
154
+ * tracker with no element ({@link ManualActivation}) ⇒ no keybinds — the natural opt-out.
155
+ * Region-scoped + bubble-phase, so nested resolvers form a responder chain and multiple
156
+ * app instances stay DOM-isolated.
157
+ */
158
+ protected _syncKeyBinds(): void;
159
+ protected _emit(): void;
160
+ protected _notify(): void;
161
+ }
162
+ //# sourceMappingURL=CommandResolver.d.ts.map