@weasel-js/routing 1.9.4 → 1.10.0

package/dist/react.d.ts

@@ -1,24 +1,23 @@
-import { U as UseGestureDispatcherOptions } from './internal-B0SsznMG.js';
-export { D as DispatcherChannels } from './internal-B0SsznMG.js';
+import { U as UseGestureDispatcherOptions } from './internal-D0rDmi7t.js';
+export { D as DispatcherChannels } from './internal-D0rDmi7t.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, K as KernelOverlay, C as Contribution, e as AnyToolOf, O as OverlayPosition } from './index-gArM2tbt.js';
-export { f as ActiveToolContextProvider, g as ActiveToolContextProviderIfRoot, h as ActiveToolContextProviderProps, i as ActiveToolContextValue, u as useActiveToolContext, j as useOptionalActiveToolContext } from './index-gArM2tbt.js';
+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-Bm2QEV09.js';
+export { f as ActiveToolContextProvider, g as ActiveToolContextProviderIfRoot, h as ActiveToolContextProviderProps, i as ActiveToolContextValue, u as useActiveToolContext, j as useOptionalActiveToolContext } from './index-Bm2QEV09.js';
 import { ModeRegistry } from '@weasel-js/modes';
 import '@weasel-js/gestures';
 import '@weasel-js/cursor';
 import '@weasel-js/geom';
-import '@weasel-js/history';
+import '@weasel-js/registry';
 import '@weasel-js/select';
 
 /**
- * Attach the input pipeline to a canvas: DOM pointer, wheel, keyboard and
+ * Attach the input pipeline to a canvas: DOM pointer, wheel, keyboard, and
  * multitouch listeners in, normalized input events out, routed through the
  * dispatcher to whichever action a binding names.
  *
- * Everything it needs beyond its options — the active tool, the dep registry —
- * comes from context, so it must be mounted inside `<SceneCanvas>`'s
- * providers.
+ * The active tool and the dep registry come from context, so it must be
+ * mounted inside `<SceneCanvas>`'s providers.
  */
 declare function useGestureDispatcher(opts: UseGestureDispatcherOptions): void;
 
@@ -125,11 +124,10 @@ interface YokeProps {
 /**
  * @experimental
  * Canvases that share input on purpose: the active tool, the gesture in
- * flight, history and yoke-wide actions. Made once with `useYoke()` where the
- * sharing is decided, and passed to each canvas that joins it (`yoke={yoke}`)
- * and to `<Yoke value={yoke}>` around anything else that should reach it — a
- * toolbar, say. The members can sit anywhere in the tree: the handle, not the
- * tree, says who shares.
+ * flight, history, and yoke-wide actions. Made once with `useYoke()`, and
+ * passed to each canvas that joins it (`yoke={yoke}`) and to
+ * `<Yoke value={yoke}>` around anything else that should reach it — a
+ * toolbar, say. The members can sit anywhere in the tree.
  */
 interface Yoke {
     /** @internal */
@@ -180,6 +178,101 @@ interface OngoingAction {
  */
 declare function useOngoingAction(actionId: string): OngoingAction;
 
+/** @experimental 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 = {
+    worldX: number;
+    worldY: number;
+    viewId: string | null;
+} | null;
+/** @experimental */
+interface PointerContextValue {
+    /** The latest position. */
+    get(): PointerWorldPos;
+    /** Publish a position. Subscribers hear only a changed value. */
+    set(next: PointerWorldPos): void;
+    /** Called after every change; returns the unsubscribe. */
+    subscribe(fn: () => void): () => void;
+    /** Bumps on every change. */
+    getVersion(): number;
+    /** `get()` as a stable thunk, for hooks taking a drop-point option. */
+    readonly getDropPoint: () => PointerWorldPos;
+}
+/** @experimental 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
+ * you hold elsewhere (`createPointerStore()`).
+ */
+declare function PointerContextProvider({ children, store }: {
+    children: ReactNode;
+    store?: PointerContextValue;
+}): ReactNode;
+/** @experimental 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.
+ *  `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.
+ *
+ * **Single slot:** the context holds one selection array. Whichever publisher
+ * calls `publishSelection` most recently owns it, so a multi-canvas page gets
+ * last-writer-wins. `<SceneCanvas>` publishes automatically.
+ */
+
+/** @experimental */
+interface SelectionContextValue {
+    /** The most-recently-published selection. Empty array when no canvas
+     *  has published or when the active canvas's selection is empty. */
+    readonly selection: readonly NodeId[];
+    /** Optional per-id kind label, parallel to `selection` (e.g. `'rectangle'`,
+     *  `'path'`, `'group'`). Sparse entries (`undefined`) are allowed; treat it
+     *  as best-effort. */
+    readonly kinds?: readonly (string | undefined)[];
+    /** Publish the calling canvas's selection. Calling with the same content
+     *  does not re-render the consumer tree. */
+    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>`.
+ */
+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.
+ */
+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.
+ */
+declare function usePublishSelection(ids: readonly NodeId[], kinds?: readonly (string | undefined)[]): void;
+
 /** Options for `useTools`: which tools exist, which one starts active, and
  *  which run continuously regardless of the active one. */
 interface UseToolsOptions<TOverlay = KernelOverlay> {
@@ -189,7 +282,7 @@ interface UseToolsOptions<TOverlay = KernelOverlay> {
     /** Tools eligible for the active slot or hotkey slot. The keys are the
      *  tool ids; the values are the tool records. A tool with `hotkey` set
      *  is wired into the hotkey slot whenever the engagement state matches. */
-    registry: Record<string, AnyToolOf<TOverlay>>;
+    registry: Record<string, Tool<TOverlay>>;
     /** Always-on entries — tools or other contributions, live regardless of
      *  the active slot. */
     ambient?: readonly Contribution<TOverlay>[];
@@ -205,8 +298,7 @@ interface ToolsApi<TOverlay = KernelOverlay> {
     /** Set the active-slot tool, or `null` to clear it. The gesture dispatcher
      *  watches the active tool and cancels any in-flight handle itself. */
     setActive: (id: string | null) => void;
-    /** Currently hotkey-engaged tool id (or `null`). Derived as the top of
-     *  the hotkey stack for backwards compat with the pre-stack API. */
+    /** Currently hotkey-engaged tool id (or `null`): the top of the hotkey stack. */
     hotkeyEngaged: string | null;
     /** Engage a hotkey-slot tool by id. */
     engageHotkey: (id: string) => void;
@@ -215,31 +307,24 @@ interface ToolsApi<TOverlay = KernelOverlay> {
     /** All always-on entries, in registration order. */
     ambient: readonly Contribution<TOverlay>[];
     /** Full registry — for userland UI (palette buttons, etc.). */
-    registry: Readonly<Record<string, AnyToolOf<TOverlay>>>;
+    registry: Readonly<Record<string, Tool<TOverlay>>>;
     /** Returns true if a tool with the given id is in the registry or ambient list. */
     has(id: string): boolean;
-    /** All overlay layers from currently-engaged tools (active slot, hotkey
-     *  slot if engaged, all ambient slot tools) that declare `position`.
-     *  Filters out tools with no `overlay` field. Order: active, then hotkey
-     *  (if engaged), then ambient (registration order). */
+    /** Overlay layers from currently-engaged tools that declare `position`.
+     *  Order: active, then hotkey (if engaged), then ambient (registration order). */
     getActiveOverlays(position?: OverlayPosition): TOverlay[];
 }
 /**
- * Manages the active tool and hotkey slot.
- *
- * A thin shim over {@link useContributions}: the `registry` / `ambient`
- * arguments are restated as declared eligibility (`focus` / `always`), and
- * assembly happens in one place for tools and non-tool contributions alike.
+ * Manages the active tool and hotkey slot; a thin shim over
+ * {@link useContributions}.
  *
  * Requires `<ActiveToolContextProvider>` (or `<WeaselProvider>` /
  * `<SceneCanvas>`, which mount one internally) in scope: active/hotkey state
- * lives in the context so the gesture dispatcher and any sibling
- * `useTools` calls all read the same source of truth.
+ * lives in the context.
  *
- * **First-mount-wins semantics**: if the context's slot is unseeded (no
- * `initialActive`, nothing set yet) on first mount, `useTools` pushes
- * `opts.active` to the context. Subsequent mounts respect whatever the
- * context currently holds (the first caller wins).
+ * **First mount wins**: if the context's slot is unseeded on first mount,
+ * `useTools` pushes `opts.active` to the context. Subsequent mounts respect
+ * whatever the context currently holds.
  */
 declare function useTools<TOverlay = KernelOverlay>(opts: UseToolsOptions<TOverlay>): ToolsApi<TOverlay>;
 
@@ -291,4 +376,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, type ToolsApi, type UseContributionsOptions, UseGestureDispatcherOptions, type UseToolsOptions, Yoke, type YokeProps, useAction, useActionsRegistry, useContributions, useDepRegistry, useDepSource, useGestureDispatcher, useOffhandAction, useOngoingAction, useOptionalDepRegistry, useTools, useYoke };
+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 };