@weasel-js/routing 1.10.1 → 1.11.1

package/dist/react.d.ts

@@ -1,13 +1,16 @@
-import { U as UseGestureDispatcherOptions } from './internal-Boc2I3zn.js';
-export { D as DispatcherChannels } from './internal-Boc2I3zn.js';
+import { U as UseGestureDispatcherOptions } from './internal-Dcyz_cJv.js';
+export { D as DispatcherChannels } from './internal-Dcyz_cJv.js';
 import * as react from 'react';
 import { ReactNode, ReactElement } from 'react';
-import { D as DepRegistry, a as DepName, b as DepSchema, S as ScopeNode, A as ActionsRegistry, c as Action, d as DepNode, T as ToolNode, N as NodeId, K as KernelOverlay, C as Contribution, e as Tool, O as OverlayPosition } from './index-DkOqUxow.js';
-export { f as ActiveToolContextProvider, g as ActiveToolContextProviderIfRoot, h as ActiveToolContextProviderProps, i as ActiveToolContextValue, u as useActiveToolContext, j as useOptionalActiveToolContext } from './index-DkOqUxow.js';
+import { D as DepRegistry, a as DepName, b as DepSource, S as ScopeNode, A as Action, c as ActionDeps, M as MenuHost, d as ActionsRegistry, e as ActionDisabledReason, B as BoundGesture, f as ActionVariant, g as MenuDef, h as DepNode, T as ToolNode, N as NodeId, K as KernelOverlay, C as Contribution, i as Tool, O as OverlayPosition } from './index-Cb7ehEks.js';
+export { j as ActiveToolContextProvider, k as ActiveToolContextProviderIfRoot, l as ActiveToolContextProviderProps, m as ActiveToolContextValue, u as useActiveToolContext, n as useOptionalActiveToolContext } from './index-Cb7ehEks.js';
+import { IconRef } from '@weasel-js/icons';
 import { ModeRegistry } from '@weasel-js/modes';
 import '@weasel-js/gestures';
 import '@weasel-js/cursor';
 import '@weasel-js/geom';
+import '@weasel-js/menu';
+import '@weasel-js/prefs';
 import '@weasel-js/registry';
 import '@weasel-js/select';
 
@@ -36,8 +39,8 @@ declare function useDepRegistry(): DepRegistry;
 declare function useOptionalDepRegistry(): DepRegistry | null;
 /** Register a live source for `name` for the lifetime of the calling
  *  component. The `source` thunk is called at dispatch time and should
- *  return the latest value. */
-declare function useDepSource<K extends DepName>(name: K, source: () => DepSchema[K]): void;
+ *  return the latest value; its `below` reads the source it displaced. */
+declare function useDepSource<K extends DepName>(name: K, source: DepSource<K>): void;
 
 /**
  * One node of the actions tree: the actions registered at it, over its
@@ -52,20 +55,31 @@ declare class ActionsNode extends ScopeNode<ActionsNode> {
     private readonly tunings;
     private readonly dispatchers;
     private cache;
+    private host;
     /** Called on `activate`, so a scope's dep and tool nodes move with it. */
     readonly onActivate: (() => void)[];
     constructor(parent: ActionsNode | null, descends: boolean, contextDeps: () => DepRegistry | null);
     private resolve;
+    /** Every tuning for `id` from the root down to here, root first. */
+    private tuningsOf;
     /** `a` under every tuning for its id from the root down to here. */
     private tuned;
     private snapshot;
     private deps;
+    /** The actions registered at this node itself, live, unmuted and tuned —
+     *  none from the scopes below it. */
+    ownActions(): readonly Action[];
+    /** The deps `a` is invoked with from here: the active scope's, which is
+     *  what `trigger` and `begin` run it with. */
+    depsOf(a: Action): ActionDeps;
+    /** The menu host of this node's tree, made by its root on first ask. Rows
+     *  resolve and run against the active scope, as chrome's `trigger` does. */
+    menuHost(): MenuHost;
     private dispatcher;
     activate(): void;
     readonly registry: ActionsRegistry;
 }
 /**
- * @experimental
  * Mounts a root `ActionsRegistry` for its lifetime. Children call
  * `useActionsRegistry()` or `useAction()` to participate. Mounts no input
  * listener of its own — the gesture dispatcher owns input.
@@ -74,12 +88,10 @@ declare function ActionsProvider({ children }: {
     children: ReactNode;
 }): ReactElement;
 /**
- * @experimental
  * Returns the `ActionsRegistry` in scope, or `null` when there is none.
  */
 declare function useActionsRegistry(): ActionsRegistry | null;
 /**
- * @experimental
  * Register an `Action` for the lifetime of the calling component. No-op (with
  * a dev-only warning) when no `ActionsProvider` is in scope. Re-registers on
  * `action` reference change (consumers should memoize stable identities to
@@ -87,8 +99,37 @@ declare function useActionsRegistry(): ActionsRegistry | null;
  */
 declare function useAction(action: Action): void;
 
+/** What a command offers besides its id, label and callback. */
+interface CommandOptions {
+    /** True when the command can run, else why not. Read each time it is asked. */
+    enabled?: () => true | ActionDisabledReason;
+    /** Whether it reads as held down. Read each time it is asked. */
+    active?: () => boolean;
+    /** The gestures that run it. The `{ spec, opts: { params } }` form gives one variant its own key. */
+    keys?: BoundGesture | readonly BoundGesture[];
+    /** Shown beside the label. */
+    icon?: IconRef;
+    /** Words a palette finds it by and a tagged bar or menu gathers it under. */
+    tags?: readonly string[];
+    /** One entry each in a bar, menu or palette; `run` receives the chosen one's params. */
+    variants?: readonly ActionVariant[];
+}
+/**
+ * Register `run` as an action under `id` on the nearest `<ActionsProvider>`
+ * for the calling component's lifetime, so a menu, toolbar, palette or key
+ * can run it. Callbacks and option functions may be new on every render: the
+ * latest are read when used, and the action is replaced only when `id`,
+ * `label`, `icon`, `keys`, `tags` or `variants` change by value.
+ */
+declare function useCommand(id: string, label: string, run: (params?: Readonly<Record<string, unknown>>) => void, options?: CommandOptions): void;
+
+/** The menu host in scope: the nearest `<ActionsProvider>`'s, else the one a
+ *  canvas with no provider above it makes. Null outside both. */
+declare function useMenuHost(): MenuHost | null;
+/** Declare menus for the calling component's lifetime. Memoize `defs`. */
+declare function useMenus(defs: readonly MenuDef[], owner?: string | null): void;
+
 /**
- * @experimental
  * Input scopes and yokes: the tiers between a root registry and a canvas.
  */
 
@@ -100,21 +141,20 @@ interface InputScopeProps {
     children: ReactNode;
 }
 /**
- * @experimental
  * One canvas's input: actions, deps and a tool of its own, under whichever
  * registries are in scope (or its yoke's). What the canvas registers stays
  * here; what it looks up is answered here first, then by the tiers above.
- * With nothing in scope it is a root.
+ * With nothing in scope it is a root, and makes the menu host
+ * `<ActionsProvider>` would have.
  *
  * Chrome above calls `trigger` / `begin` / `useActiveToolContext` on its own
  * registries, and those reach the active scope: the one last activated — by a
- * pointerdown or wheel — or the newest where none has been. Keys are stricter:
+ * pointerdown, wheel or contextmenu — or the newest where none has been. Keys are stricter:
  * one that reaches the page goes to the canvas last pressed or scrolled in,
  * across every root on the page, and to none before the first.
  */
 declare function InputScope({ yoke, children }: InputScopeProps): ReactElement;
 /**
- * @experimental
  * Make a yoke for canvases to join, under the registries in scope where it is
  * called. It lives as long as the calling component.
  */
@@ -125,7 +165,6 @@ interface YokeProps {
     children: ReactNode;
 }
 /**
- * @experimental
  * Canvases that share input on purpose: the active tool, the gesture in
  * flight, history, and yoke-wide actions. Made once with `useYoke()`, and
  * passed to each canvas that joins it (`yoke={yoke}`) and to
@@ -141,7 +180,6 @@ interface Yoke {
     readonly tools: ToolNode;
 }
 /**
- * @experimental
  * Put `value` in scope for what is not a canvas — a toolbar, a status bar — so
  * its actions, deps and tool reads reach the yoke and, through it, the member
  * canvas last used.
@@ -182,7 +220,7 @@ interface OngoingAction {
  */
 declare function useOngoingAction(actionId: string): OngoingAction;
 
-/** @experimental World-space pointer position and the view it is over — a
+/** World-space pointer position and the view it is over — a
  *  view id, or `null` for a surface's own camera. `null` as a whole when the
  *  pointer is over no publishing surface. */
 type PointerWorldPos = {
@@ -190,7 +228,7 @@ type PointerWorldPos = {
     worldY: number;
     viewId: string | null;
 } | null;
-/** @experimental */
+/** A pointer store: the latest position, a way to publish one, and change notification. */
 interface PointerContextValue {
     /** The latest position. */
     get(): PointerWorldPos;
@@ -203,10 +241,9 @@ interface PointerContextValue {
     /** `get()` as a stable thunk, for hooks taking a drop-point option. */
     readonly getDropPoint: () => PointerWorldPos;
 }
-/** @experimental A pointer store with no provider around it. */
+/** A pointer store with no provider around it. */
 declare function createPointerStore(): PointerContextValue;
 /**
- * @experimental
  * Wrap the part of the React tree that should share one pointer.
  * `<SceneCanvas>` mounts one when none is in scope, so mount it yourself only
  * when two surfaces should share a pointer. Pass `store` to publish into one
@@ -216,15 +253,14 @@ declare function PointerContextProvider({ children, store }: {
     children: ReactNode;
     store?: PointerContextValue;
 }): ReactNode;
-/** @experimental The surrounding pointer store, or `null` when no provider is
+/** The surrounding pointer store, or `null` when no provider is
  *  in scope. */
 declare function usePointerContext(): PointerContextValue | null;
-/** @experimental The pointer, re-rendering the caller whenever it changes.
+/** The pointer, re-rendering the caller whenever it changes.
  *  `null` outside a provider. */
 declare function usePointerPosition(): PointerWorldPos;
 
 /**
- * @experimental
  * SelectionContext — an ambient context that publishes "what's currently
  * selected" so non-canvas UI (command palette, status bar) can read it without
  * threading a selection prop through the tree.
@@ -234,7 +270,7 @@ declare function usePointerPosition(): PointerWorldPos;
  * last-writer-wins. `<SceneCanvas>` publishes automatically.
  */
 
-/** @experimental */
+/** The ambient selection store a canvas publishes into and non-canvas UI reads. */
 interface SelectionContextValue {
     /** The most-recently-published selection. Empty array when no canvas
      *  has published or when the active canvas's selection is empty. */
@@ -248,7 +284,6 @@ interface SelectionContextValue {
     publishSelection(ids: readonly NodeId[], kinds?: readonly (string | undefined)[]): void;
 }
 /**
- * @experimental
  * Wrap the part of the React tree that should share a selection context.
  * Usually placed at the demo / app root, alongside `<ActionsProvider>`.
  */
@@ -256,13 +291,11 @@ declare function SelectionContextProvider({ children }: {
     children: ReactNode;
 }): ReactNode;
 /**
- * @experimental
  * The current selection-context value, or `null` when no
  * `<SelectionContextProvider>` is in scope.
  */
 declare function useSelectionContext(): SelectionContextValue | null;
 /**
- * @experimental
  * Mounts a `<SelectionContextProvider>` only when no parent provider is in
  * scope; otherwise renders children unwrapped.
  */
@@ -270,7 +303,6 @@ declare function SelectionContextProviderIfRoot({ children, }: {
     children: ReactNode;
 }): ReactNode;
 /**
- * @experimental
  * Publishes `ids` into the surrounding `<SelectionContextProvider>` whenever
  * their content changes, and clears the slot on unmount unless another
  * publisher has written it since. No-op when there's no provider in scope.
@@ -380,4 +412,4 @@ declare function useContributions<TOverlay = KernelOverlay>(opts: UseContributio
  */
 declare function useOffhandAction(entries: readonly Contribution<unknown>[]): void;
 
-export { ActionsProvider, type ContributionsApi, DepRegistry, DepRegistryProvider, InputScope, type InputScopeProps, type OngoingAction, PointerContextProvider, type PointerContextValue, type PointerWorldPos, SelectionContextProvider, SelectionContextProviderIfRoot, type SelectionContextValue, type ToolsApi, type UseContributionsOptions, UseGestureDispatcherOptions, type UseToolsOptions, Yoke, type YokeProps, createPointerStore, useAction, useActionsRegistry, useContributions, useDepRegistry, useDepSource, useGestureDispatcher, useOffhandAction, useOngoingAction, useOptionalDepRegistry, usePointerContext, usePointerPosition, usePublishSelection, useSelectionContext, useTools, useYoke };
+export { ActionsProvider, type CommandOptions, type ContributionsApi, DepRegistry, DepRegistryProvider, InputScope, type InputScopeProps, type OngoingAction, PointerContextProvider, type PointerContextValue, type PointerWorldPos, SelectionContextProvider, SelectionContextProviderIfRoot, type SelectionContextValue, type ToolsApi, type UseContributionsOptions, UseGestureDispatcherOptions, type UseToolsOptions, Yoke, type YokeProps, createPointerStore, useAction, useActionsRegistry, useCommand, useContributions, useDepRegistry, useDepSource, useGestureDispatcher, useMenuHost, useMenus, useOffhandAction, useOngoingAction, useOptionalDepRegistry, usePointerContext, usePointerPosition, usePublishSelection, useSelectionContext, useTools, useYoke };