@sheetxl/utils-react 0.7.27 → 0.7.28-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/browser/cjs/C7jPCqFJNiWyD2pr.cjs +1 -0
- package/browser/cjs/CyWMySHsu-RvsIGs.cjs +1 -0
- package/browser/cjs/DZSvmqU8nRas1uz6.cjs +1 -0
- package/browser/cjs/index.cjs +5 -7
- package/browser/esm/7-_IBNtjW6k90P9e.mjs +390 -0
- package/browser/esm/BgV0nMxx2V13JMAV.mjs +2171 -0
- package/browser/esm/index.mjs +6128 -1806
- package/browser/esm/sLI7RooaRwVJN8R1.mjs +139 -0
- package/licenses/dependencies.txt +246 -39
- package/node/esm/DxhVj6bgjkjclg0J.mjs +139 -0
- package/node/esm/index.mjs +5141 -1774
- package/node/esm/k3zNlJ7uOn8Nfx4T.mjs +2171 -0
- package/package.json +8 -5
- package/types/index.d.ts +2 -2043
- package/types/src/animation/AnimationModeContext.d.ts +10 -0
- package/types/src/animation/index.d.ts +3 -0
- package/types/src/animation/useAnimatedMeasure.d.ts +39 -0
- package/types/src/command/ActivationTracker.d.ts +53 -0
- package/types/src/command/CommandAnchorProvider.d.ts +64 -0
- package/types/src/command/CommandButtonEntryLabel.d.ts +25 -0
- package/types/src/command/CommandButtonRegistry.d.ts +159 -0
- package/types/src/command/CommandButtonRegistryContext.d.ts +35 -0
- package/types/src/command/CommandCatalog.d.ts +155 -0
- package/types/src/command/CommandCatalogResource.d.ts +7 -0
- package/types/src/command/CommandCatalogService.d.ts +61 -0
- package/types/src/command/CommandChainContext.d.ts +32 -0
- package/types/src/command/CommandFallbackContext.d.ts +30 -0
- package/types/src/command/CommandFocusContext.d.ts +21 -0
- package/types/src/command/CommandRegistry.d.ts +164 -0
- package/types/src/command/CommandRegistryContext.d.ts +16 -0
- package/types/src/command/CommandResolver.d.ts +162 -0
- package/types/src/command/CommandScope.d.ts +343 -0
- package/types/src/command/CommandScopeContext.d.ts +205 -0
- package/types/src/command/FocusActivation.d.ts +140 -0
- package/types/src/command/ICommand.d.ts +31 -0
- package/types/src/command/ICommandDefinition.d.ts +82 -0
- package/types/src/command/KeyBindingDispatcher.d.ts +150 -0
- package/types/src/command/LayerActivation.d.ts +45 -0
- package/types/src/command/Types.d.ts +80 -0
- package/types/src/command/createResolvedCommand.d.ts +91 -0
- package/types/src/command/index.d.ts +26 -0
- package/types/src/command/reduceDefinitions.d.ts +33 -0
- package/types/src/command/useCommands.d.ts +22 -0
- package/types/src/command/useContributeCommands.d.ts +18 -0
- package/types/src/components/FocusKeyNavigation.d.ts +22 -0
- package/types/src/components/ITooltip.d.ts +38 -0
- package/types/src/components/RoundedTab.d.ts +26 -0
- package/types/src/components/index.d.ts +4 -0
- package/types/src/error/ErrorPanel.d.ts +14 -0
- package/types/src/error/ReactErrorBoundary.d.ts +7 -0
- package/types/src/error/UncaughtErrorBoundary.d.ts +5 -0
- package/types/src/error/index.d.ts +4 -0
- package/types/src/float/FloatPanel.d.ts +57 -0
- package/types/src/float/FloatPopper.d.ts +85 -0
- package/types/src/float/FloatPopup.d.ts +19 -0
- package/types/src/float/FloatProvider.d.ts +60 -0
- package/types/src/float/FloatStackContext.d.ts +25 -0
- package/types/src/float/FloatTooltip.d.ts +22 -0
- package/types/src/float/FloatUtils.d.ts +55 -0
- package/types/src/float/_FloatUtils.d.ts +51 -0
- package/types/src/float/index.d.ts +9 -0
- package/types/src/float/useFloatStack.d.ts +92 -0
- package/types/src/hooks/LanguageState.d.ts +15 -0
- package/types/src/hooks/index.d.ts +19 -0
- package/types/src/hooks/useBoundSyncExternalStore.d.ts +23 -0
- package/types/src/hooks/useCallbackRef.d.ts +11 -0
- package/types/src/hooks/useDevicePixelRatio.d.ts +37 -0
- package/types/src/hooks/useEditMode.d.ts +66 -0
- package/types/src/hooks/useGlobalClipboard.d.ts +7 -0
- package/types/src/hooks/useId.d.ts +9 -0
- package/types/src/hooks/useImperativeElement.d.ts +3 -0
- package/types/src/hooks/useLanguage.d.ts +13 -0
- package/types/src/hooks/useMouseDownAndHoldListener.d.ts +13 -0
- package/types/src/hooks/useNotifier.d.ts +330 -0
- package/types/src/hooks/useOnClickOrFocusAway.d.ts +8 -0
- package/types/src/hooks/useOptionalBoundSyncExternalStore.d.ts +20 -0
- package/types/src/hooks/useOptionalSyncExternalStore.d.ts +18 -0
- package/types/src/hooks/useSynchronizedPointerHandler.d.ts +54 -0
- package/types/src/hooks/useTextareaCaretRect.d.ts +85 -0
- package/types/src/hooks/useTraceUpdate.d.ts +2 -0
- package/types/src/hooks/useTranslator.d.ts +32 -0
- package/types/src/icons/DynamicIcon.d.ts +17 -0
- package/types/src/icons/DynamicIconService.d.ts +39 -0
- package/types/src/icons/ErrorIcon.d.ts +6 -0
- package/types/src/icons/Types.d.ts +81 -0
- package/types/src/icons/WalkingIcon.d.ts +27 -0
- package/types/src/icons/_Utils.d.ts +3 -0
- package/types/src/icons/index.d.ts +5 -0
- package/types/src/icons/packs/Base.d.ts +4 -0
- package/types/src/icons/packs/Conditional.d.ts +4 -0
- package/types/src/index.d.ts +18 -0
- package/types/src/loading/LoadingPanel.d.ts +31 -0
- package/types/src/loading/index.d.ts +2 -0
- package/types/src/persistence/InMemoryStore.d.ts +12 -0
- package/types/src/persistence/LocalStorageStore.d.ts +15 -0
- package/types/src/persistence/PersistenceStateProvider.d.ts +3 -0
- package/types/src/persistence/Types.d.ts +95 -0
- package/types/src/persistence/_Context.d.ts +9 -0
- package/types/src/persistence/index.d.ts +6 -0
- package/types/src/persistence/usePersistenceState.d.ts +33 -0
- package/types/src/react-resizable/Resizable.d.ts +30 -0
- package/types/src/react-resizable/ResizableBox.d.ts +18 -0
- package/types/src/react-resizable/index.d.ts +11 -0
- package/types/src/react-resizable/propTypes.d.ts +56 -0
- package/types/src/react-resizable/utils.d.ts +3 -0
- package/types/src/scroll/AxisViewport.d.ts +73 -0
- package/types/src/scroll/IScrollPane.d.ts +63 -0
- package/types/src/scroll/IScrollbar.d.ts +94 -0
- package/types/src/scroll/NativeScrollbar.d.ts +7 -0
- package/types/src/scroll/ScrollButton.d.ts +29 -0
- package/types/src/scroll/ScrollPane.d.ts +4 -0
- package/types/src/scroll/Scrollbar.d.ts +4 -0
- package/types/src/scroll/TouchThumbContext.d.ts +93 -0
- package/types/src/scroll/TouchThumbHandle.d.ts +64 -0
- package/types/src/scroll/TrackDrag.d.ts +107 -0
- package/types/src/scroll/Utils.d.ts +8 -0
- package/types/src/scroll/Viewport.d.ts +285 -0
- package/types/src/scroll/VirtualScrollbar.d.ts +49 -0
- package/types/src/scroll/index.d.ts +14 -0
- package/types/src/scroll/scrollbarTheming.d.ts +27 -0
- package/types/src/scroll/useWheelScroll.d.ts +27 -0
- package/types/src/scroller/Scroller.d.ts +260 -0
- package/types/src/scroller/animate.d.ts +30 -0
- package/types/src/scroller/index.d.ts +2 -0
- package/types/src/singletonHook/components/SingleItemContainer.d.ts +6 -0
- package/types/src/singletonHook/components/SingletonHooksContainer.d.ts +7 -0
- package/types/src/singletonHook/index.d.ts +11 -0
- package/types/src/singletonHook/singletonHook.d.ts +6 -0
- package/types/src/singletonHook/utils/env.d.ts +4 -0
- package/types/src/singletonHook/utils/env.native.d.ts +1 -0
- package/types/src/singletonHook/utils/warning.d.ts +2 -0
- package/types/src/splitPane/SplitPane.d.ts +91 -0
- package/types/src/splitPane/SplitPaneResizer.d.ts +11 -0
- package/types/src/splitPane/index.d.ts +3 -0
- package/types/src/theme/TokenTheme.d.ts +196 -0
- package/types/src/theme/TokenThemeProvider.d.ts +97 -0
- package/types/src/theme/buildThemeCSS.d.ts +54 -0
- package/types/src/theme/createThemeVars.d.ts +15 -0
- package/types/src/theme/defaultTheme.d.ts +15 -0
- package/types/src/theme/index.d.ts +9 -0
- package/types/src/theme/resolveTokens.d.ts +21 -0
- package/types/src/theme/themeAttrs.d.ts +32 -0
- package/types/src/theme/useResolvedThemeMode.d.ts +17 -0
- package/types/src/types/Types.d.ts +71 -0
- package/types/src/types/index.d.ts +2 -0
- package/types/src/utils/FullScreenPortal.d.ts +6 -0
- package/types/src/utils/PinchZoom.d.ts +3 -0
- package/types/src/utils/ReactUtils.d.ts +134 -0
- package/types/src/utils/index.d.ts +4 -0
- package/types/src/utils/useFullScreen.d.ts +47 -0
- package/browser/cjs/DJJQOl0dYYJgXfru.cjs +0 -6
- package/browser/esm/Bh0xih0ZamA4MXkt.mjs +0 -12
- package/node/assets/style.css +0 -1
- package/node/esm/DdwriRgF582bPBWP.mjs +0 -12
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
import { RemoveListener, MaybePromise } from '@sheetxl/utils';
|
|
2
|
+
import { CommandScope, AnchorSource } from './CommandScope';
|
|
3
|
+
import { ActivationTracker } from './ActivationTracker';
|
|
4
|
+
/**
|
|
5
|
+
* A **recallable default-anchor provider** — the function form of {@link FocusActivation}'s initial
|
|
6
|
+
* anchor. Returns a fresh default anchor (an `Element` resolved through the region walk, a fixed
|
|
7
|
+
* {@link AnchorSource}, or `null`), synchronously or as a `Promise`. Invoked at cold-start and re-invoked
|
|
8
|
+
* whenever the live anchor's element is destroyed (the destruction fallback — see the class doc).
|
|
9
|
+
*/
|
|
10
|
+
export type DefaultAnchorProvider = () => MaybePromise<Element | AnchorSource | null>;
|
|
11
|
+
/** The initial-anchor argument: a one-shot value/`Promise` seed, or a recallable {@link DefaultAnchorProvider}. */
|
|
12
|
+
export type FocusActivationInitial = MaybePromise<Element | AnchorSource | null> | DefaultAnchorProvider;
|
|
13
|
+
/**
|
|
14
|
+
* A focus-driven {@link ActivationTracker}: the anchor follows DOM focus **within the region
|
|
15
|
+
* it's attached to**. The new-model counterpart of `CommandGroup._activate` — the element
|
|
16
|
+
* walk and de-dupe guard are kept (the `relatedTarget === null` "just for testing" bail is
|
|
17
|
+
* dropped, so a first focus-in still activates).
|
|
18
|
+
*
|
|
19
|
+
* It is **region-scoped**: `findScope` is bounded by the attached root, so focus *outside*
|
|
20
|
+
* that root never changes the anchor. That's how "main toolbar tracks focus anywhere"
|
|
21
|
+
* (attach to the app root) and "scripting toolbar tracks focus only in the editor" (attach to
|
|
22
|
+
* the editor element) are the *same* class with different attach points — focus leaving the
|
|
23
|
+
* editor simply leaves the scripting tracker's anchor untouched.
|
|
24
|
+
*
|
|
25
|
+
* **The anchor starts `null` and there is no standing "default" slot.** A consumer that wants a
|
|
26
|
+
* live anchor before the user ever focuses supplies an **initial anchor** to the constructor — a
|
|
27
|
+
* value or a `Promise` it resolves at its own lifecycle moment (the studio: the loaded grid's
|
|
28
|
+
* center pane, right before the loading reveal). The initial anchor is a *synthetic first focus*:
|
|
29
|
+
* it lands in the same single slot real focus writes to (an `Element` is resolved through the same
|
|
30
|
+
* region walk a `focusin` takes), does nothing if focus got there first, and is advanced by later
|
|
31
|
+
* focus like any other anchor. Grids never steal real focus for this.
|
|
32
|
+
*
|
|
33
|
+
* **Destruction fallback — a recallable provider (COMMAND-DESIGN.md open-Q5).** If the initial
|
|
34
|
+
* anchor is supplied as a **function**, it is a *default-anchor provider*: invoked once for
|
|
35
|
+
* cold-start AND **re-invoked whenever the live anchor's element is destroyed** — e.g. a resize
|
|
36
|
+
* that shrinks the grid past its min unmounts the focused pane, dropping DOM focus to `<body>`
|
|
37
|
+
* with no `focusin` to observe. Left alone, `getAnchor()` would keep resolving through the now-
|
|
38
|
+
* detached region (the "anchor out of the root" symptom). Instead {@link getAnchor} notices the
|
|
39
|
+
* anchored element is no longer connected, drops it, and asks the provider for a fresh default
|
|
40
|
+
* (the studio: the pane focus *would* land on — last-focused, else center). The consumer owns
|
|
41
|
+
* that policy; the tracker only owns *when* to ask. A one-shot value/`Promise` cannot be re-run,
|
|
42
|
+
* so it seeds once with no recall — pass a function to opt into the fallback.
|
|
43
|
+
*
|
|
44
|
+
* **Leaf-only, two producers (design/COMMAND-DESIGN.md §"resolution model").** This is the `Focus`
|
|
45
|
+
* producer; {@link ManualActivation} is the other. A chain change bumps the root version, so a {@link CommandResolver} — which also
|
|
46
|
+
* subscribes to scope changes — re-resolves and re-reads the live top; no effective-region subscription
|
|
47
|
+
* is needed here.
|
|
48
|
+
*/
|
|
49
|
+
export declare class FocusActivation implements ActivationTracker {
|
|
50
|
+
protected _scopes: Map<Element, AnchorSource>;
|
|
51
|
+
/**
|
|
52
|
+
* The **command tree root** this tracker also *reads* on its focus walk (pull-model discovery —
|
|
53
|
+
* design/COMMAND-DESIGN.md §"Fold the region bridge into the tree"). Focus regions record their element →
|
|
54
|
+
* region on the tree via {@link CommandScope.attachElement}; every consumer's `FocusActivation`
|
|
55
|
+
* (constructed with the same root) discovers them. `findSource` consults this tracker's own `register`ed
|
|
56
|
+
* sources first, then the tree's shared region index (`root.getRegion`). Omit for the standalone case
|
|
57
|
+
* (tests/stories that `register` directly into the tracker).
|
|
58
|
+
*/
|
|
59
|
+
protected readonly _root: CommandScope | null;
|
|
60
|
+
protected _rootElement: Element | null;
|
|
61
|
+
protected _lastFocusEvent: FocusEvent | null;
|
|
62
|
+
protected _current: AnchorSource | null;
|
|
63
|
+
/**
|
|
64
|
+
* The **region-owner element** `_current` was resolved through (the pane's `Stage`, the editor
|
|
65
|
+
* leaf — NOT the deepest focused node, which the grid virtualizes/recycles). Watched for
|
|
66
|
+
* destruction: {@link getAnchor} drops the anchor and recalls when this goes `!isConnected`.
|
|
67
|
+
* `null` when the anchor was seeded from a bare {@link AnchorSource} (no element to watch).
|
|
68
|
+
*/
|
|
69
|
+
protected _currentElement: Element | null;
|
|
70
|
+
/** The recallable default-anchor provider (function-form initial anchor), or `null`. See the class doc. */
|
|
71
|
+
protected _recall: DefaultAnchorProvider | null;
|
|
72
|
+
/** Guards against scheduling/running more than one recall at a time (getAnchor is a hot read). */
|
|
73
|
+
protected _recallPending: boolean;
|
|
74
|
+
protected _listeners: Set<() => void>;
|
|
75
|
+
/**
|
|
76
|
+
* @param root The command tree **root** to read on the focus walk (pull discovery — regions record via
|
|
77
|
+
* {@link CommandScope.attachElement}). Omit for a standalone tracker whose regions {@link register}
|
|
78
|
+
* directly into it (tests/stories).
|
|
79
|
+
* @param initialAnchor Optional initial anchor. Two forms:
|
|
80
|
+
* - a **one-shot seed** — a fixed {@link AnchorSource} (scope or live getter), an `Element` resolved
|
|
81
|
+
* through the same region walk a real focus takes (retried a few frames — the region may register
|
|
82
|
+
* just after the consumer resolves, e.g. a first-paint callback racing the registration effect), or a
|
|
83
|
+
* `Promise` the consumer settles at its own moment (the studio: post-load, pre-reveal). Seeds once;
|
|
84
|
+
* inert if real focus set the anchor first.
|
|
85
|
+
* - a **{@link DefaultAnchorProvider}** (a function) — the same synthetic first focus, but *recallable*:
|
|
86
|
+
* re-invoked whenever the live anchor's element is destroyed (the destruction fallback, class doc).
|
|
87
|
+
*/
|
|
88
|
+
constructor(root?: CommandScope | null, initialAnchor?: FocusActivationInitial);
|
|
89
|
+
/**
|
|
90
|
+
* Invoke the {@link DefaultAnchorProvider} and seed its result (an `Element` goes through the region
|
|
91
|
+
* walk, a source lands directly; a `Promise` seeds on settle). No-op if there's no provider or focus
|
|
92
|
+
* has already produced an anchor since the recall was scheduled — the seed is inert either way, but
|
|
93
|
+
* skipping avoids a needless provider call. Clears the pending guard.
|
|
94
|
+
*/
|
|
95
|
+
protected _invokeRecall(): void;
|
|
96
|
+
/**
|
|
97
|
+
* Apply the one-shot initial anchor: first real focus wins; an `Element` resolves via the region
|
|
98
|
+
* walk (retrying across a few frames — see the constructor doc), a source lands directly.
|
|
99
|
+
*/
|
|
100
|
+
protected _seed(value: Element | AnchorSource, attempts?: number): void;
|
|
101
|
+
/**
|
|
102
|
+
* The focus-driven anchor (`null` until the initial anchor / first focus lands). A dynamic-leaf
|
|
103
|
+
* source (a getter) is evaluated **live** each call, so a pane always anchors at its *current* chain top.
|
|
104
|
+
*/
|
|
105
|
+
getAnchor(): CommandScope | null;
|
|
106
|
+
/** The attached region (or `null` before {@link attach}). Keystroke handling binds here. */
|
|
107
|
+
getElement(): Element | null;
|
|
108
|
+
subscribe(listener: () => void): RemoveListener;
|
|
109
|
+
/**
|
|
110
|
+
* Associate a DOM element with an {@link AnchorSource} (a provider calls this with its element ref).
|
|
111
|
+
* Pass a **getter** for a dynamic leaf (a pane's `Stage` → its live chain top); a fixed scope for an
|
|
112
|
+
* ordinary region (the editor's own element).
|
|
113
|
+
*/
|
|
114
|
+
register(element: Element, source: AnchorSource): RemoveListener;
|
|
115
|
+
/**
|
|
116
|
+
* The nearest registered anchor **source** at or above `element`, bounded by the attached root.
|
|
117
|
+
* Pure DOM-tree walk; `undefined` if none, or if `element` is outside the attached root.
|
|
118
|
+
*/
|
|
119
|
+
findSource(element: Element | null): AnchorSource | undefined;
|
|
120
|
+
/**
|
|
121
|
+
* Like {@link findSource}, but also returns the **element the source was matched at** (the region
|
|
122
|
+
* owner — the `Stage`/editor element that registered it, NOT the deeper focused node). The anchor
|
|
123
|
+
* watches that owner element for destruction (see {@link getAnchor}); the grid recycles the deep
|
|
124
|
+
* focused node during virtualization, so watching it would false-trigger the recall.
|
|
125
|
+
*/
|
|
126
|
+
protected _findSourceEntry(element: Element | null): {
|
|
127
|
+
source: AnchorSource;
|
|
128
|
+
element: Element;
|
|
129
|
+
} | undefined;
|
|
130
|
+
/**
|
|
131
|
+
* The nearest registered **scope** at or above `element` (a dynamic-leaf source is resolved to its
|
|
132
|
+
* current value). `undefined` if none is registered on the bounded walk.
|
|
133
|
+
*/
|
|
134
|
+
findScope(element: Element | null): CommandScope | undefined;
|
|
135
|
+
/** Start tracking focus within `rootElement` (its region of interest). */
|
|
136
|
+
attach(rootElement: Element): RemoveListener;
|
|
137
|
+
protected _handleFocus(event: FocusEvent): void;
|
|
138
|
+
protected _notify(): void;
|
|
139
|
+
}
|
|
140
|
+
//# sourceMappingURL=FocusActivation.d.ts.map
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shared command value types.
|
|
3
|
+
*/
|
|
4
|
+
export declare namespace ICommand {
|
|
5
|
+
/**
|
|
6
|
+
* Used to interact with a dom element.
|
|
7
|
+
*
|
|
8
|
+
* @remarks
|
|
9
|
+
* * When dispatching keystrokes the target is used to determine if the keystroke
|
|
10
|
+
* can be consumed by the element.
|
|
11
|
+
* * Many commands will refocus the target after they have completed. The target focus will be called.
|
|
12
|
+
*/
|
|
13
|
+
interface ITarget extends HTMLElement {
|
|
14
|
+
/**
|
|
15
|
+
* Used to determine if a dom element is contained with the group.
|
|
16
|
+
*
|
|
17
|
+
* @param element
|
|
18
|
+
*
|
|
19
|
+
* @remarks
|
|
20
|
+
* This is used for validating keystrokes and focus traversal.
|
|
21
|
+
*/
|
|
22
|
+
contains(element: Node | null): boolean;
|
|
23
|
+
/**
|
|
24
|
+
* Called after a command is executed.
|
|
25
|
+
*/
|
|
26
|
+
focus(): void;
|
|
27
|
+
}
|
|
28
|
+
type DynamicContext<CONTEXT> = CONTEXT | (() => CONTEXT);
|
|
29
|
+
type DynamicValue<T, CONTEXT> = T | ((context?: DynamicContext<CONTEXT>) => T);
|
|
30
|
+
}
|
|
31
|
+
//# sourceMappingURL=ICommand.d.ts.map
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
import { IKeyStroke } from '../types';
|
|
2
|
+
import { ICommand } from './ICommand';
|
|
3
|
+
import { CommandCallback } from './createResolvedCommand';
|
|
4
|
+
/**
|
|
5
|
+
* A **contributed, partial** command definition — the *authoring* side of the command
|
|
6
|
+
* system. Scopes/providers contribute these; the registry **reduces** all contributions
|
|
7
|
+
* for a given `key` (along the active scope chain) per-property into a derived, read-only
|
|
8
|
+
* {@link ResolvedCommand}. Authors never build or mutate a resolved instance directly
|
|
9
|
+
* (no more `instance.updateCallback(...)`); they contribute/merge definitions via the
|
|
10
|
+
* provider.
|
|
11
|
+
*
|
|
12
|
+
* Every field except `key` is optional and merged **per-property** (see
|
|
13
|
+
* {@link MERGE_STRATEGY}). Canonical example — `copy`:
|
|
14
|
+
* - a root scope contributes `{ key, icon, label }` (stable chrome),
|
|
15
|
+
* - the focused component contributes `{ callback }` (what's actually copied),
|
|
16
|
+
* - an intermediate scope contributes `{ disabledReason: 'Sheet is protected' }`.
|
|
17
|
+
*
|
|
18
|
+
* Reuses the shared sub-types from {@link ICommand} (`DynamicValue`, `Callback`,
|
|
19
|
+
* `DynamicContext`, `ITarget`) so the resolved read surface stays byte-compatible with the
|
|
20
|
+
* existing `command/` package during the port. See `design/COMMAND-DESIGN.md`.
|
|
21
|
+
*/
|
|
22
|
+
export interface ICommandDefinition<STATE = any, CONTEXT = any, ARGS = void> {
|
|
23
|
+
/** Immutable identity. Every contribution for the same command shares this key. */
|
|
24
|
+
key: string;
|
|
25
|
+
/**
|
|
26
|
+
* The action (delegates to the SDK / an ephemeral UI store). Strategy: `override`.
|
|
27
|
+
* Takes the per-invocation input `ARGS` — **distinct from `state`** (the value the command
|
|
28
|
+
* reflects). See {@link CommandCallback} and design/COMMAND-DESIGN.md "arg vs state".
|
|
29
|
+
*/
|
|
30
|
+
callback?: CommandCallback<STATE, CONTEXT, ARGS>;
|
|
31
|
+
/**
|
|
32
|
+
* Reasons the command is unavailable. **Array-valued ⇒ accumulates** (concat,
|
|
33
|
+
* most-specific first): every contributing scope may add reasons, and the command is
|
|
34
|
+
* disabled if ANY reason is present (resolved `disabled()` derives from this for
|
|
35
|
+
* read-compat). Dynamic reasons are expressed by **re-contributing** (the contributor
|
|
36
|
+
* re-runs when its inputs change) rather than storing a function — that's the definitions
|
|
37
|
+
* model. Note: a child scope cannot yet *clear* a parent's reason (a "fancier type"
|
|
38
|
+
* later — see design/COMMAND-DESIGN.md).
|
|
39
|
+
*/
|
|
40
|
+
disabledReasons?: string[];
|
|
41
|
+
/** Hidden from surfaces entirely (e.g. macro recording). Scalar ⇒ overrides. */
|
|
42
|
+
hidden?: ICommand.DynamicValue<boolean, CONTEXT>;
|
|
43
|
+
label?: ICommand.DynamicValue<string, CONTEXT>;
|
|
44
|
+
/** Per-surface label overrides (e.g. "Rename Sheet" → "Rename" in a context menu). */
|
|
45
|
+
groupLabels?: Record<string, ICommand.DynamicValue<string, CONTEXT>>;
|
|
46
|
+
/**
|
|
47
|
+
* **Message parameters** for ICU-subset `label`/`groupLabels`/`description` messages
|
|
48
|
+
* (`formatMessage` — `{count, plural, …}` / `{mode, select, …}`). The catalog authors the
|
|
49
|
+
* localized MESSAGE (with the parameter *defaults* — `ChromeRecord.params`); a dynamic
|
|
50
|
+
* contributor keeps the live values current (e.g. the sheet's selection reducer contributes
|
|
51
|
+
* `{ count, mode }` for the insert/delete/hide labels). Strategy: `override` — contribute the
|
|
52
|
+
* COMPLETE parameter set for the command's messages, not a delta.
|
|
53
|
+
*/
|
|
54
|
+
params?: Record<string, unknown>;
|
|
55
|
+
description?: ICommand.DynamicValue<string, CONTEXT>;
|
|
56
|
+
/**
|
|
57
|
+
* Per-surface description overrides keyed by groupKey — the `description` twin of
|
|
58
|
+
* {@link groupLabels} (a compact tooltip in a dense menu vs. the full ribbon text). Falls back to
|
|
59
|
+
* {@link description} when the surface has no entry.
|
|
60
|
+
*/
|
|
61
|
+
groupDescriptions?: Record<string, ICommand.DynamicValue<string, CONTEXT>>;
|
|
62
|
+
icon?: ICommand.DynamicValue<React.ReactElement | string, CONTEXT>;
|
|
63
|
+
/**
|
|
64
|
+
* Per-surface icon overrides keyed by groupKey — the `icon` twin of {@link groupLabels} (e.g. a
|
|
65
|
+
* glyph in a toolbar, a check mark in a menu). Falls back to {@link icon}.
|
|
66
|
+
*/
|
|
67
|
+
groupIcons?: Record<string, ICommand.DynamicValue<React.ReactElement | string, CONTEXT>>;
|
|
68
|
+
/**
|
|
69
|
+
* Accumulated metadata (like `disabledReasons`): scopes' tags concatenate. Cross-cutting
|
|
70
|
+
* rules keyed on a tag (e.g. "`mutator` commands disable when the sheet is protected") are
|
|
71
|
+
* **contributor** logic, not a registry feature — see design/COMMAND-DESIGN.md.
|
|
72
|
+
*/
|
|
73
|
+
tags?: string[];
|
|
74
|
+
shortcut?: ICommand.DynamicValue<IKeyStroke | IKeyStroke[] | null, CONTEXT>;
|
|
75
|
+
/** Model state. Strategy: `override`. */
|
|
76
|
+
state?: STATE;
|
|
77
|
+
/** View-specific context. Strategy: `override`. */
|
|
78
|
+
context?: ICommand.DynamicContext<CONTEXT>;
|
|
79
|
+
/** Focus/contains target (commands refocus this after execute). Strategy: `override`. */
|
|
80
|
+
target?: ICommand.ITarget | (() => ICommand.ITarget);
|
|
81
|
+
}
|
|
82
|
+
//# sourceMappingURL=ICommandDefinition.d.ts.map
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
import { RemoveListener } from '@sheetxl/utils';
|
|
2
|
+
import { IKeyStroke } from '../types';
|
|
3
|
+
import { CommandResolver } from './CommandResolver';
|
|
4
|
+
/**
|
|
5
|
+
* The minimal keyboard-event shape {@link KeyBindingDispatcher.dispatch} needs. Satisfied by BOTH a
|
|
6
|
+
* native `KeyboardEvent` (the {@link KeyBindingDispatcher.attach} path, for generic regions) and a
|
|
7
|
+
* React `KeyboardEvent` (the grid's synthetic terminal-tap path) — so the grid can stay on
|
|
8
|
+
* one event system instead of mixing a native listener into its synthetic Stage dispatch.
|
|
9
|
+
*/
|
|
10
|
+
export interface DispatchKeyEvent {
|
|
11
|
+
readonly key: string;
|
|
12
|
+
readonly code: string;
|
|
13
|
+
readonly ctrlKey: boolean;
|
|
14
|
+
readonly metaKey: boolean;
|
|
15
|
+
readonly altKey: boolean;
|
|
16
|
+
readonly shiftKey: boolean;
|
|
17
|
+
/**
|
|
18
|
+
* The event's **origin** (the focused element the keystroke was delivered to) — read by the
|
|
19
|
+
* origin-containment rule (see {@link KeyBindingDispatcher.dispatch}). Optional: a caller that
|
|
20
|
+
* can't supply one (a hand-built test event) is treated as unrestricted.
|
|
21
|
+
*/
|
|
22
|
+
readonly target?: EventTarget | null;
|
|
23
|
+
preventDefault(): void;
|
|
24
|
+
stopPropagation(): void;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* Whether the keystroke is one a **caret** owns: deletion or caret motion — `Delete`, `Backspace`,
|
|
28
|
+
* `Insert`, `Home`/`End`, `PageUp`/`PageDown`, the arrows — in every modifier variant, since
|
|
29
|
+
* `ctrl+Backspace` deletes a word and `shift+ArrowLeft` extends a selection.
|
|
30
|
+
*
|
|
31
|
+
* The **shared** definition of what a focused text widget consumes with `stopPropagation`
|
|
32
|
+
* (`useEditCommit`'s `handleTextKeys`; the grid's `useEditorKeymap` consumes the same set per mode).
|
|
33
|
+
*
|
|
34
|
+
* Two deliberate exclusions:
|
|
35
|
+
* - `Enter` / `Tab` / `Escape` and the function keys — commit/traverse keys the command tree must keep
|
|
36
|
+
* seeing, even from inside an editor;
|
|
37
|
+
* - the native text chords (`mod` + `a`/`c`/`x`/`v`/`z`/`y`) — those SHOULD reach the dispatcher, where
|
|
38
|
+
* the **input-clipboard injector** answers them for an editable origin with a leaf contribution that
|
|
39
|
+
* acts on the focused element. Consuming them at the widget would route copy through the browser
|
|
40
|
+
* clipboard instead of the app's, so the grid and an input would no longer share one.
|
|
41
|
+
*
|
|
42
|
+
* There is no dispatcher-side counterpart on purpose: a widget consuming its OWN caret keys is
|
|
43
|
+
* unambiguous, whereas the dispatcher second-guessing the target's TYPE is the banned defer (Core law,
|
|
44
|
+
* consequence 1). What keeps a grid command off a key born in a task pane is **origin containment**,
|
|
45
|
+
* not this — see {@link CommandScope.contains}.
|
|
46
|
+
*/
|
|
47
|
+
export declare function isCaretKey(event: Pick<DispatchKeyEvent, 'key'>): boolean;
|
|
48
|
+
/**
|
|
49
|
+
* Maps a keyboard **event → command key**, then dispatches through a {@link CommandResolver}
|
|
50
|
+
* (so a shortcut resolves against the resolver's *anchor* exactly like a button — the same
|
|
51
|
+
* cascade/override). Ctrl/meta are treated alike, with an `e.code` → `e.key` fallback and
|
|
52
|
+
* `Key*`/`Digit*` prefix stripping. See design/COMMAND-DESIGN.md "key dispatching".
|
|
53
|
+
*
|
|
54
|
+
* **The dispatch law (design/COMMAND-DESIGN.md "Core law — one keystroke bubble"):** this is the
|
|
55
|
+
* **terminal handler of one bubble**. A keystroke goes *down the z-stack first* (every layer is
|
|
56
|
+
* offered it via the Stage responder chain; a layer that handles it calls `stopPropagation()`),
|
|
57
|
+
* and only what **no layer consumed** bubbles up to this dispatcher (attached at the region root),
|
|
58
|
+
* which resolves it *up the command scope hierarchy*. So `stopPropagation` is the **only** consume
|
|
59
|
+
* signal — a stopped key never reaches us — and there is **no** competing target-type defer.
|
|
60
|
+
*
|
|
61
|
+
* **Origin containment (the second half of the law):** dispatch resolves **origin-filtered** — the
|
|
62
|
+
* event's origin (`event.target`) is passed into `CommandScope.resolve`, whose gather loop omits
|
|
63
|
+
* every contribution from a node whose **`CommandScope.contains(origin)`** rejects it (the scope
|
|
64
|
+
* OWNS the decision: any of its own `attachElement`ed elements DOM-contains the origin, else its
|
|
65
|
+
* parent decides, none up the chain ⇒ unrestricted — and a region owner can attach a portaled
|
|
66
|
+
* container as an additional element). Per **contribution**, not per command: a key born in a task pane omits a sheet-layer's
|
|
67
|
+
* portion but keeps a `workbook`-level portion of the *same* command — the cascade falls through to
|
|
68
|
+
* the permitted callback — and a command whose every contribution is omitted doesn't resolve at all
|
|
69
|
+
* (the binding doesn't exist for that origin; the key stays with the input). This is what keeps a
|
|
70
|
+
* *pane-layer* command (selection nav, clipboard) from firing off a keystroke born in an
|
|
71
|
+
* **orthogonal** subtree — a task-pane input's ArrowDown moves its caret, not the grid selection —
|
|
72
|
+
* while a keystroke a layer deliberately *lets propagate* (the cell editor's commit Enter) still
|
|
73
|
+
* dispatches, because it originates inside the pane's Stage. NOT a target-*type* rule: it never asks
|
|
74
|
+
* "is the target an input?", only "is the origin inside the contributor's region?" — so it cannot
|
|
75
|
+
* re-introduce the editable-defer that broke edit-mode commits.
|
|
76
|
+
*
|
|
77
|
+
* **Containment only works for scopes that BOUND themselves.** An element-less scope is unrestricted
|
|
78
|
+
* by design (consequence 3) — right for `app`-tier commands (`ctrl+S` must save while the caret is in
|
|
79
|
+
* a task-pane field), wrong for anything acting on the grid. A `sheet`-scope binding left unbounded is
|
|
80
|
+
* how `Delete` came to run `clearContents` from a comment box (clearing cells and dirtying the
|
|
81
|
+
* workbook mid-keystroke). The rule for authors: **if a command needs a UI region, bound its scope**
|
|
82
|
+
* (`CommandScope.attachBounds`); leave a scope element-less only when its commands are genuinely
|
|
83
|
+
* app-global.
|
|
84
|
+
*
|
|
85
|
+
* **Anchor-dependent by construction:** because it asks the resolver, the *same* dispatcher
|
|
86
|
+
* yields different commands as the anchor moves — the app root owns one over the main
|
|
87
|
+
* resolver; a region (e.g. the scripting editor) can own its own over its resolver, so its
|
|
88
|
+
* bindings win only while focused there.
|
|
89
|
+
*
|
|
90
|
+
* Not built yet (seams left): multi-stroke **chords** (a pending-stroke state) and a **user
|
|
91
|
+
* keybinding override** map consulted before the contributed defaults.
|
|
92
|
+
*/
|
|
93
|
+
export declare class KeyBindingDispatcher {
|
|
94
|
+
protected readonly _resolver: CommandResolver;
|
|
95
|
+
protected _lastEvent: DispatchKeyEvent | null;
|
|
96
|
+
constructor(resolver: CommandResolver);
|
|
97
|
+
/**
|
|
98
|
+
* The command key bound to `event` at the resolver's current anchor, or `undefined`.
|
|
99
|
+
* Enumerates the keys reachable from the anchor, resolves each **origin-filtered** (see the class
|
|
100
|
+
* doc — resolution omits every contribution whose region doesn't contain the event's origin), and
|
|
101
|
+
* matches its shortcut(s) — so an overridden shortcut resolves through the cascade like any other
|
|
102
|
+
* property, and a fully-omitted command simply doesn't resolve (the binding doesn't exist for this
|
|
103
|
+
* origin; another command on the same shortcut may still match).
|
|
104
|
+
*/
|
|
105
|
+
findKey(event: DispatchKeyEvent): string | undefined;
|
|
106
|
+
/** The event's origin as a containment-checkable node, or `null` (unverifiable ⇒ unfiltered). */
|
|
107
|
+
protected _eventOrigin(event: DispatchKeyEvent): Node | null;
|
|
108
|
+
/**
|
|
109
|
+
* Match `event` and, if it maps to an enabled command, `preventDefault()` +
|
|
110
|
+
* `stopPropagation()` + dispatch it (the resolver's `execute` fires the ripple/observers).
|
|
111
|
+
* Returns whether the event was consumed.
|
|
112
|
+
*
|
|
113
|
+
* **Responder chain:** dispatchers attach to their region's element, so DOM bubbling makes
|
|
114
|
+
* the innermost region fire first; consuming (`stopPropagation`) keeps a parent region's
|
|
115
|
+
* dispatcher from re-handling it, while an unmatched key is left to bubble up to the next
|
|
116
|
+
* region and ultimately the Studio-level backstop.
|
|
117
|
+
*
|
|
118
|
+
* **No target-type defer (the dispatch law).** A key that *reaches* `dispatch` is one the
|
|
119
|
+
* z-stack did not consume, so it is dispatched on its own merit — there is no "is the focus an
|
|
120
|
+
* input?" second-guess. A widget that wants a key (a focused text input, the cell editor in edit
|
|
121
|
+
* mode) opts out by `stopPropagation`-ing it, so `dispatch` is never called for it. This is what
|
|
122
|
+
* keeps consumption to a single signal (design/COMMAND-DESIGN.md "Core law — one keystroke
|
|
123
|
+
* bubble"); the editable-target heuristic that used to live here was a competing rule and is gone.
|
|
124
|
+
* The one *structural* gate is **origin containment** (see the class doc): resolution itself omits
|
|
125
|
+
* every contribution whose region doesn't contain the event's origin — about *where the key was
|
|
126
|
+
* born*, never *what kind of element* it was born on.
|
|
127
|
+
*/
|
|
128
|
+
dispatch(event: DispatchKeyEvent): boolean;
|
|
129
|
+
/** Attach a `keydown` listener to `target` (document, or a region element to scope it). */
|
|
130
|
+
attach(target: Document | Element): RemoveListener;
|
|
131
|
+
/** Introspection/testing: the current `shortcutString → commandKey` map at the anchor. */
|
|
132
|
+
getBindings(): Map<string, string>;
|
|
133
|
+
/** Both candidate canonical strings for an event: from `e.code` and from `e.key`. */
|
|
134
|
+
protected _eventCandidates(event: DispatchKeyEvent): Set<string>;
|
|
135
|
+
protected _shortcutString(ks: IKeyStroke): string;
|
|
136
|
+
}
|
|
137
|
+
/**
|
|
138
|
+
* The canonical, match-stable string for a contributed shortcut — the exact form the dispatcher
|
|
139
|
+
* compares against at dispatch time (ctrl/meta collapsed to `mod`, key token normalized). Exposed
|
|
140
|
+
* so UI (e.g. the shortcut reference's "press a key" capture mode) can match a live keystroke
|
|
141
|
+
* against contributed bindings identically to how they actually fire.
|
|
142
|
+
*/
|
|
143
|
+
export declare function keyStrokeToCanonical(ks: IKeyStroke): string;
|
|
144
|
+
/**
|
|
145
|
+
* Both canonical strings a keyboard event could match (from `e.code` and from `e.key`) — the
|
|
146
|
+
* counterpart to {@link keyStrokeToCanonical}. A shortcut matches the event when its canonical
|
|
147
|
+
* form is in this set.
|
|
148
|
+
*/
|
|
149
|
+
export declare function keyEventCanonicals(event: DispatchKeyEvent): Set<string>;
|
|
150
|
+
//# sourceMappingURL=KeyBindingDispatcher.d.ts.map
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import { RemoveListener } from '@sheetxl/utils';
|
|
2
|
+
import { CommandScope } from './CommandScope';
|
|
3
|
+
import { ActivationTracker } from './ActivationTracker';
|
|
4
|
+
/**
|
|
5
|
+
* The **z-ordered layer→scope registry** — the anchor source for a *region* whose behavior is composed
|
|
6
|
+
* from stacked layers (selection, clipboard, format painter, the cell editor, …). Each command-bearing
|
|
7
|
+
* layer `register`s its {@link CommandScope} at a z; this chains them (via {@link CommandScope.setParent})
|
|
8
|
+
* into a stack ordered by z — **higher z → deeper → wins** — atop the region's `base`, and reports the
|
|
9
|
+
* **top** as {@link getAnchor}. The unchanged {@link CommandScope.resolve} (which walks `_parent` from
|
|
10
|
+
* the anchor) then resolves **top-of-stack first**: a stacked layer overrides a command by **stacking**,
|
|
11
|
+
* not by focus, and unstacking it restores the layer/base below.
|
|
12
|
+
*
|
|
13
|
+
* This is what makes a feature a *composable* layer — one that both draws and injects commands — and it
|
|
14
|
+
* is the same mechanism whether the layer is ours or a third party's. `LayerActivation` implements
|
|
15
|
+
* {@link ActivationTracker}, so it drops into `CommandResolver` / {@link FocusActivation} (as an
|
|
16
|
+
* {@link AnchorSource}, read live) with no other changes. It has no DOM element of its own — the **region**
|
|
17
|
+
* owns focus/keys (a pane maps its `Stage` element to this stack; see {@link FocusActivation}).
|
|
18
|
+
*
|
|
19
|
+
* @remarks
|
|
20
|
+
* Ties (equal z) keep insertion order. Reusing the same scope twice is not supported (register each
|
|
21
|
+
* layer's scope once). The base is never removed; it's the region's always-present floor.
|
|
22
|
+
*/
|
|
23
|
+
export declare class LayerActivation implements ActivationTracker {
|
|
24
|
+
protected readonly _base: CommandScope;
|
|
25
|
+
protected _layers: Array<{
|
|
26
|
+
scope: CommandScope;
|
|
27
|
+
z: number;
|
|
28
|
+
}>;
|
|
29
|
+
protected _top: CommandScope;
|
|
30
|
+
protected readonly _listeners: Set<() => void>;
|
|
31
|
+
constructor(base: CommandScope);
|
|
32
|
+
/**
|
|
33
|
+
* Add a layer's scope at priority `z` and re-chain. Returns an unregister that removes it and
|
|
34
|
+
* re-chains the rest (restoring whatever was below). The caller owns the scope's own teardown
|
|
35
|
+
* (`contribution.remove()` / `scope.dispose()`); this only manages stack membership.
|
|
36
|
+
*/
|
|
37
|
+
register(scope: CommandScope, z: number): RemoveListener;
|
|
38
|
+
/** Re-link the registered scopes into a chain ordered by z: base → lowest → … → highest (= anchor). */
|
|
39
|
+
protected _rechain(): void;
|
|
40
|
+
/** The region's floor scope (always present, below every layer). */
|
|
41
|
+
getBase(): CommandScope;
|
|
42
|
+
getAnchor(): CommandScope;
|
|
43
|
+
subscribe(listener: () => void): RemoveListener;
|
|
44
|
+
}
|
|
45
|
+
//# sourceMappingURL=LayerActivation.d.ts.map
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
import { IKeyStroke } from '../types';
|
|
2
|
+
import { ResolvedCommand } from './createResolvedCommand';
|
|
3
|
+
/**
|
|
4
|
+
* Follow useCommandsButtons. pattern createCommandButtonSet
|
|
5
|
+
*
|
|
6
|
+
* Use ProviderContext or just set a singleton. (research why/which)
|
|
7
|
+
*
|
|
8
|
+
* Register icon, label, description
|
|
9
|
+
* { commandManager.createButton( commands.getCommand('formatAlignLeftToggle'), CommandButtonType.TOOLBAR ) }
|
|
10
|
+
*
|
|
11
|
+
* Register factory for each type of Command
|
|
12
|
+
* Register configuration for each key
|
|
13
|
+
*
|
|
14
|
+
* When registering to a component also
|
|
15
|
+
*
|
|
16
|
+
*/
|
|
17
|
+
export declare const CommandButtonType: {
|
|
18
|
+
/**
|
|
19
|
+
* Suitable for toolbars. Click to open, click to close, generally disabled as icon
|
|
20
|
+
*/
|
|
21
|
+
readonly Toolbar: "toolbar";
|
|
22
|
+
/**
|
|
23
|
+
* Suitable for menus. HoverIn to open, hover leave to close, generally disabled as icon and text
|
|
24
|
+
*/
|
|
25
|
+
readonly Menuitem: "menuitem";
|
|
26
|
+
};
|
|
27
|
+
export type CommandButtonType = typeof CommandButtonType[keyof typeof CommandButtonType];
|
|
28
|
+
export type CommandButtonRefAttribute = {
|
|
29
|
+
ref?: React.Ref<HTMLDivElement>;
|
|
30
|
+
};
|
|
31
|
+
export interface CommandButtonOptions<STATE = any, CONTEXT = any, ARGS = void> extends Omit<React.HTMLAttributes<HTMLElement>, "color" | "label"> {
|
|
32
|
+
/**
|
|
33
|
+
* The panel/group the button renders in (e.g. `'contextMenu'`, `'cellStyle'`) — selects the
|
|
34
|
+
* command's matching `groupLabels` variant. Omit for the full label. (Named `groupKey`, NOT
|
|
35
|
+
* "scope" — command *scopes* are contributors; this is purely a presentation surface.)
|
|
36
|
+
*/
|
|
37
|
+
groupKey?: string;
|
|
38
|
+
icon?: React.ReactNode | ((command: ResolvedCommand<STATE, CONTEXT, ARGS>) => React.ReactNode);
|
|
39
|
+
label?: React.ReactNode | ((command: ResolvedCommand<STATE, CONTEXT, ARGS>) => React.ReactNode);
|
|
40
|
+
/**
|
|
41
|
+
* Render the `label` as visible button content (alongside the icon) rather than tooltip-only.
|
|
42
|
+
* Toolbar buttons are icon-only by default; menu items always show their label. See
|
|
43
|
+
* {@link CommandButtonEntry.showLabel} for the entry-level equivalent.
|
|
44
|
+
* @defaultValue false
|
|
45
|
+
*/
|
|
46
|
+
showLabel?: boolean;
|
|
47
|
+
/**
|
|
48
|
+
* The shortcut to display.
|
|
49
|
+
*
|
|
50
|
+
* @remarks
|
|
51
|
+
* This is display only and doesn't actually track the shortcut.
|
|
52
|
+
* Override the display for the shortcut on the command (if available).
|
|
53
|
+
*/
|
|
54
|
+
shortcut?: IKeyStroke | IKeyStroke[];
|
|
55
|
+
selected?: boolean;
|
|
56
|
+
disabled?: boolean;
|
|
57
|
+
disableHover?: boolean;
|
|
58
|
+
/**
|
|
59
|
+
* Tooltip properties. If this is specified then the tooltips are used.
|
|
60
|
+
* Do not provide a child as this component will be the child.
|
|
61
|
+
*/
|
|
62
|
+
propsTooltip?: any;
|
|
63
|
+
/**
|
|
64
|
+
* How the button will be styles.
|
|
65
|
+
*
|
|
66
|
+
* @defaultValue CommandButtonType.Toolbar
|
|
67
|
+
*/
|
|
68
|
+
variant?: CommandButtonType;
|
|
69
|
+
/**
|
|
70
|
+
* Optional state for this specific command button.
|
|
71
|
+
*
|
|
72
|
+
* @defaultValue to undefined
|
|
73
|
+
*/
|
|
74
|
+
commandState?: STATE;
|
|
75
|
+
}
|
|
76
|
+
export interface CommandButtonProps<STATE = any, CONTEXT = any, ARGS = void> extends CommandButtonOptions<STATE, CONTEXT, ARGS> {
|
|
77
|
+
commandKey?: string;
|
|
78
|
+
command?: ResolvedCommand<STATE, CONTEXT, ARGS>;
|
|
79
|
+
}
|
|
80
|
+
//# sourceMappingURL=Types.d.ts.map
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
import { IKeyStroke } from '../types';
|
|
2
|
+
import { ICommand } from './ICommand';
|
|
3
|
+
import { ReducedDefinition } from './reduceDefinitions';
|
|
4
|
+
/**
|
|
5
|
+
* The action a command runs. **`ARGS` is the per-invocation input** (`execute(args)`) —
|
|
6
|
+
* deliberately a *separate* type from `STATE` (the current model value the command
|
|
7
|
+
* *reflects*, read via `getState()`). They flow in opposite directions — `STATE` is output
|
|
8
|
+
* (command → UI, for display/enablement), `args` is input (UI → command) — and only
|
|
9
|
+
* coincidentally share a type (a font picker is `STATE = string` *and* `ARGS = string`). A
|
|
10
|
+
* toggle is `STATE = boolean, ARGS = void` (it just toggles). See design/COMMAND-DESIGN.md
|
|
11
|
+
* "arg vs state".
|
|
12
|
+
*/
|
|
13
|
+
export interface CommandCallback<STATE = any, CONTEXT = any, ARGS = void> {
|
|
14
|
+
(args?: ARGS, command?: ResolvedCommand<STATE, CONTEXT, ARGS>): void | boolean | Promise<void | boolean>;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* Dispatch **middleware** registered on a scope via `CommandScope.use`. Onion-style: it
|
|
18
|
+
* receives the `next` callback and returns a wrapping callback, so the contributor's inner
|
|
19
|
+
* callback stays *pure* while cross-cutting infra (transaction batching / busy / edit-mode)
|
|
20
|
+
* lives in the wrapper. **Bound to the scope that authors the
|
|
21
|
+
* callback — not inherited** down the tree (see design/COMMAND-DESIGN.md "Dispatch middleware").
|
|
22
|
+
* First-registered is outermost. `next` (and `command`) carry through so a layer can read
|
|
23
|
+
* `command.getLabel()` etc.
|
|
24
|
+
*/
|
|
25
|
+
export type CommandMiddleware<STATE = any, CONTEXT = any, ARGS = void> = (next: CommandCallback<STATE, CONTEXT, ARGS>) => CommandCallback<STATE, CONTEXT, ARGS>;
|
|
26
|
+
/**
|
|
27
|
+
* The **read** surface of a resolved command — the *derived*, immutable view that
|
|
28
|
+
* `CommandButton`/toolbars/menus consume. Deliberately the read subset of the retired
|
|
29
|
+
* mutable `ICommand` interface (same `getLabel`/`getIcon`/`getShortcut`/`disabled`/`execute`
|
|
30
|
+
* signatures) so consumers didn't change during the port — the **one-sided-change**
|
|
31
|
+
* invariant (see design/COMMAND-DESIGN.md). The *authoring* side (mutation, listeners) is
|
|
32
|
+
* gone: you contribute {@link ICommandDefinition}s and re-derive, you don't mutate.
|
|
33
|
+
*
|
|
34
|
+
* Adds `disabledReasons()`; `disabled()` is derived from it (+ "no callback") for compat.
|
|
35
|
+
* Carries `contributedBy` for cascade introspection. `ARGS` (the `execute` payload) is split
|
|
36
|
+
* from `STATE` (the value the command reflects) — see {@link CommandCallback}.
|
|
37
|
+
*/
|
|
38
|
+
export interface ResolvedCommand<STATE = any, CONTEXT = any, ARGS = void> {
|
|
39
|
+
getKey(): string;
|
|
40
|
+
/**
|
|
41
|
+
* @param groupKey Where the command is being rendered (the parent panel/group key, e.g.
|
|
42
|
+
* `'contextMenu'`, `'cellStyle'`) — selects the matching `groupLabels` variant. Omit for
|
|
43
|
+
* the full label. This is the ONLY per-call flavor: dynamic (function) values evaluate
|
|
44
|
+
* against the definition's own `context` (where the model data lives), never a caller's.
|
|
45
|
+
*/
|
|
46
|
+
getLabel(groupKey?: string): string;
|
|
47
|
+
/** `groupKey` selects a pack's `desc@<groupKey>` variant, if any (no inline scoped field yet). */
|
|
48
|
+
getDescription(groupKey?: string): string;
|
|
49
|
+
getTags(): string[];
|
|
50
|
+
/** `groupKey` is accepted for signature symmetry — reserved for scoped icons. */
|
|
51
|
+
getIcon(groupKey?: string): React.ReactElement | string;
|
|
52
|
+
getShortcut(): IKeyStroke | readonly IKeyStroke[] | null;
|
|
53
|
+
/** The current model value the command reflects (output, for display/enablement). */
|
|
54
|
+
getState(): STATE;
|
|
55
|
+
getContext(): CONTEXT;
|
|
56
|
+
getTarget(): ICommand.ITarget;
|
|
57
|
+
/** Reasons the command is unavailable (empty when available). */
|
|
58
|
+
disabledReasons(): string[];
|
|
59
|
+
/** Derived: disabled if any reason is present OR there is no callback. */
|
|
60
|
+
disabled(): boolean;
|
|
61
|
+
/**
|
|
62
|
+
* **Dispatch** the command: fire the per-key {@link ExecuteHook}s (the registry injects a
|
|
63
|
+
* live accessor at creation) then run the callback. disabled / no-callback /
|
|
64
|
+
* `beforeExecute`-returns-false ⇒ `false`. This is what buttons and keystrokes call
|
|
65
|
+
* directly — it's the ripple/close path, no separate registry call needed. `args` is the
|
|
66
|
+
* per-invocation input (`ARGS`), distinct from `getState()`.
|
|
67
|
+
*/
|
|
68
|
+
execute(args?: ARGS): Promise<boolean>;
|
|
69
|
+
/** Cascade introspection: property name → contribution index that supplied it. */
|
|
70
|
+
readonly contributedBy: Readonly<Record<string, number>>;
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* Observe/intercept command execution. Registered on the registry **per command key** —
|
|
74
|
+
* because resolved commands are re-derived, the stable anchor is the registry, not the
|
|
75
|
+
* instance. Executions route through the registry, so this fires for keystrokes, clicks,
|
|
76
|
+
* and programmatic calls alike (the ripple/close + middleware path). `beforeExecute`
|
|
77
|
+
* returning `false` cancels. `args` is the invocation input (`ARGS`).
|
|
78
|
+
*/
|
|
79
|
+
export interface ExecuteHook<STATE = any, CONTEXT = any, ARGS = void> {
|
|
80
|
+
beforeExecute?(command: ResolvedCommand<STATE, CONTEXT, ARGS>, args?: ARGS): boolean | void | Promise<boolean | void>;
|
|
81
|
+
onExecute?(command: ResolvedCommand<STATE, CONTEXT, ARGS>, args?: ARGS): void;
|
|
82
|
+
onError?(command: ResolvedCommand<STATE, CONTEXT, ARGS>, error: unknown, args?: ARGS): void;
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* Build the read-only {@link ResolvedCommand} from a {@link ReducedDefinition}. Pure: the
|
|
86
|
+
* same reduction always yields the same command. Re-derivation (not mutation) is how the
|
|
87
|
+
* command "changes" — the registry re-reduces and re-creates when contributions or the
|
|
88
|
+
* active scope change.
|
|
89
|
+
*/
|
|
90
|
+
export declare function createResolvedCommand<STATE = any, CONTEXT = any, ARGS = void>(reduced: ReducedDefinition<STATE, CONTEXT, ARGS>, getExecuteHooks?: () => Iterable<ExecuteHook<any, any, any>> | undefined): ResolvedCommand<STATE, CONTEXT, ARGS>;
|
|
91
|
+
//# sourceMappingURL=createResolvedCommand.d.ts.map
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
export * from './ICommand';
|
|
2
|
+
export * from './Types';
|
|
3
|
+
export * from './CommandButtonRegistry';
|
|
4
|
+
export * from './CommandButtonRegistryContext';
|
|
5
|
+
export * from './CommandButtonEntryLabel';
|
|
6
|
+
export * from './ICommandDefinition';
|
|
7
|
+
export * from './reduceDefinitions';
|
|
8
|
+
export * from './createResolvedCommand';
|
|
9
|
+
export * from './CommandCatalog';
|
|
10
|
+
export * from './CommandCatalogService';
|
|
11
|
+
export * from './CommandRegistry';
|
|
12
|
+
export * from './CommandRegistryContext';
|
|
13
|
+
export * from './CommandScope';
|
|
14
|
+
export * from './ActivationTracker';
|
|
15
|
+
export * from './FocusActivation';
|
|
16
|
+
export * from './LayerActivation';
|
|
17
|
+
export * from './CommandResolver';
|
|
18
|
+
export * from './KeyBindingDispatcher';
|
|
19
|
+
export * from './CommandScopeContext';
|
|
20
|
+
export * from './CommandChainContext';
|
|
21
|
+
export * from './CommandAnchorProvider';
|
|
22
|
+
export * from './CommandFallbackContext';
|
|
23
|
+
export * from './CommandFocusContext';
|
|
24
|
+
export * from './useCommands';
|
|
25
|
+
export * from './useContributeCommands';
|
|
26
|
+
//# sourceMappingURL=index.d.ts.map
|