Interface CommandScopeProviderProps

The subtree the scope covers. As a function it is handed the ref for elementRef — attach it to whichever node is the scope's element and the provider binds it, with no ref declaration at the call site:

<CommandScopeProvider scope={workbookScope}>
  {(ref) => <div ref={ref} className="status-bar">…</div>}
</CommandScopeProvider>
Copy

An explicit elementRef wins when both are given (the element already has an owner) — the function still receives it, so the same child code works either way.

The created scope's element — the DOM node this scope's commands belong to. Attaching one bounds the scope's region for origin containment: its shortcuts then only dispatch for keystrokes born inside the element (the sheet scope names the sheet element, so Delete → clearContents cannot fire from a studio task pane). Leaving it off makes the scope unrestricted, which is only right for genuinely app-global commands (ctrl+S). See CommandScope.attachBounds.

Pair with region when the element is also a focus leaf. Bounds alone is the default because most scopes are not: the sheet scope owns the grid's commands, but focus inside the grid anchors at the pane's z-stack, one level deeper.

Typed with a readonly current (covariant), so any element ref fits — a useRef<HTMLDivElement>, or a typed imperative handle (RefObject<IFormulaBarElement>) — with no cast at the call site.

The z order to join the ambient CommandChain at (a layer's useLayer().zIndex). Used only for a declarative spec inside a pane's chain (mechanism 1, design/COMMAND-DESIGN.md §"Layered resolver"); ignored otherwise. Falls back to the ambient useCommandOrder (default 0). This is the one grid-aware value a layer passes — everything else about being a "layer" is ambient.

Also make elementRef a focus region: record it in the tree's region index (CommandScope.attachElement) so a consumer's FocusActivation anchors here when focus lands inside it. true ⇒ the created scope is the anchor (a formula bar, a script editor — fixed leaves); an AnchorSource ⇒ a live leaf whose current value tracks something that moves (a pane passes its LayerActivation, whose anchor is the z-stack top).

Ignored without an elementRef — "the element only names the leaf" (design/COMMAND-DESIGN.md §Guardrail).

An already-built scope to provide, instead of creating one from a spec. Not created and not disposed here — its owner keeps the lifecycle; this only provides it to descendants and, with an elementRef, adds that element to its region.

This is how chrome declares that it belongs to a scope it does not own: a host rendering a status bar, a formula bar or a custom toolbar OUTSIDE the workbook element wraps it in <CommandScopeProvider scope={workbookScope} elementRef={…}>, and both halves follow — its buttons resolve workbook commands, and a keystroke born there reaches them too (see CommandScope.attachBounds: a region is a set of containers, not one subtree). Provide with no elementRef for resolution alone.

Hand the created scope back up to this provider's own parent (populated on mount, cleared on unmount). The output counterpart of elementRef: it lets a single component provide a scope AND hold its handle — e.g. to resolve/execute a command directly on it — without the provide-above / consume-below split (a parent can't useCommandScope() its own child's scope). null while there's no created scope (a null spec, or a bare grid with no ambient parent).

The command contribution — a CommandScopeSpec { scopeName, contributor, data }. The provider createChilds it off the ambient scope, runs the contributor's dynamic half for the scope's lifetime, joins the ambient pane CommandChain (if any) at order, and disposes it on unmount. This is the one way a feature, plugin, or grid layer contributes commands (design/COMMAND-DESIGN.md §"How a layer contributes commands") — one component, no layer-specific API. null ⇒ a pass-through (degrade on a bare grid). Mutually exclusive with scope.

Dispatch CommandMiddleware to register on the effective scope (via CommandScope.use) for this provider's lifetime — so a feature provider can declare its tx wrapper without reaching for the scope handle. Wraps the callbacks this scope authors (not inherited). Pass a stable reference (memoize/const) — a new array each render re-registers.