@danxbot/ui 11.1.0 → 12.1.0

package/dist/types/components/EditGutter.d.ts

@@ -1,10 +1,6 @@
 import { type ReactNode } from "react";
-/** The controlled activation pair every pencil-activated field takes. */
-export interface EditActivation {
-    editing: boolean;
-    onEditingChange: (editing: boolean) => void;
-}
-export interface EditGutterProps {
+import { type EditActivation } from "./edit/activation";
+interface EditGutterFieldProps {
     /**
      * The pencil's accessible name — say WHAT it edits ("Edit title"), because
      * a screen reader lists it among every other pencil on the page.
@@ -15,6 +11,20 @@ export interface EditGutterProps {
      * `{(edit) => <InlineEdit {...edit} … />}`.
      */
     children: (activation: EditActivation) => ReactNode;
+    /** Render no pencil — the field cannot be edited here. */
+    disabled?: boolean;
     className?: string;
 }
-export declare function EditGutter({ label, children, className }: EditGutterProps): import("react").JSX.Element;
+/**
+ * The gutter keeps `editing` itself (omit both), or the caller owns it: pass
+ * `editing` AND `onEditingChange` (`EditActivation`) — the pencil then asks
+ * through `onEditingChange(true)` and the field's close arrives through
+ * `onEditingChange(false)`. One without the other is a type error and throws
+ * at render, for the reason `assertActivationPair` gives.
+ */
+export type EditGutterProps = EditGutterFieldProps & ({
+    editing?: undefined;
+    onEditingChange?: (editing: boolean) => void;
+} | EditActivation);
+export declare function EditGutter({ label, children, editing: editingProp, onEditingChange, disabled, className }: EditGutterProps): import("react").JSX.Element;
+export {};

package/dist/types/components/InlineEdit.d.ts

@@ -1,16 +1,19 @@
 import { type Ref } from "react";
 import { useRender } from "@base-ui/react/use-render";
-import { type InlineEditCommit } from "./edit/outcome";
-export type { InlineEditCommit, InlineEditOutcome, InlineEditRefusal } from "./edit/outcome";
-export interface InlineEditProps {
+import { type EditActivation } from "./edit/activation";
+import { type EditCommit } from "./edit/outcome";
+interface InlineEditFieldProps {
     /**
      * The committed value. Controlled — this component never holds the truth,
      * only the draft while somebody is typing one.
      */
     value: string;
     /**
-     * Commit a new value. Called ONLY when the live text actually differs from
-     * `value`.
+     * Commit a new value. Called ONLY when the live text differs both from
+     * `value` and from the value editing began from — text the reader did not
+     * change is never written back, even if `value` moved underneath the open
+     * field (with `autosaveMs`, "unchanged" is measured against the last value
+     * this edit committed instead — see "AUTOSAVE").
      *
      * `base` is the `value` this control saw at the moment editing BEGAN —
      * captured once and handed back unchanged regardless of how long the edit or
@@ -23,7 +26,7 @@ export interface InlineEditProps {
      * it settles. Resolve/return `{ refusal }` to reject the value with a
      * reason; throw or reject to report that the save itself failed.
      */
-    onCommit: InlineEditCommit;
+    onCommit: EditCommit;
     /**
      * The refusals that are knowable WITHOUT a request. Return the reason, or
      * `null` to accept. Runs after the unchanged check and before `onCommit`.
@@ -93,7 +96,10 @@ export interface InlineEditProps {
     /**
      * This value cannot be edited at all, AND WHY. `{ reason }`, matching
      * `SettingRow.readOnly` — a control that refuses in silence is
-     * indistinguishable from one that is broken.
+     * indistinguishable from one that is broken. Under controlled activation a
+     * request to open (`editing` true) is declined by handing the closed state
+     * straight back through `onEditingChange(false)`, so a pencil driving it
+     * returns instead of waiting on a field that will never open (DX-3372 H3).
      */
     readOnly?: {
         reason: string;
@@ -102,33 +108,13 @@ export interface InlineEditProps {
      * What is shown when the commit REJECTS (a thrown error or a rejected
      * promise — never a `{ refusal }`, which renders its own text).
      *
-     * @default "Could not save. Your text is still here — press Enter to try again."
+     * @default "Could not save. Your text is still here — press <key> to try again.",
+     * where <key> is the key that commits in this configuration: Enter, or
+     * Ctrl+Enter for a `multiline` field without `autosaveMs`.
      */
     failureMessage?: string;
     /** The rejected error, handed on so it can be logged or reported. */
     onError?: (error: unknown) => void;
-    /**
-     * CONTROLLED ACTIVATION (DX-3372). Pass it and the control never opens
-     * ITSELF — no click, Enter or F2 — because something else (the pencil of an
-     * `EditGutter`, a menu item, a shortcut) is the way in. Setting it `true`
-     * opens the field, focused, caret at the end; the control asks to close
-     * through `onEditingChange(false)` once a commit lands or Escape cancels.
-     * Setting it `false` yourself while it is open abandons the draft exactly as
-     * Escape would — nothing is written. At rest the element leaves the tab
-     * order and drops its hover affordance, so the trigger is the one stop.
-     *
-     * Omit it for the self-opening control (click, Enter or F2).
-     */
-    editing?: boolean;
-    /**
-     * Fires exactly when the control itself starts or ends editing — never while
-     * a read-only control merely declines to open, and never for a change the
-     * caller made through `editing`. Use it to suspend any re-render-from-server
-     * logic of your own for as long as someone is actually looking at the
-     * field; see the module comment. With `editing` controlled, this is how the
-     * control hands the closed state back.
-     */
-    onEditingChange?: (editing: boolean) => void;
     /** Render as a different element — see `Button`'s own `render` for the shape. */
     render?: useRender.RenderProp;
     /**
@@ -143,4 +129,31 @@ export interface InlineEditProps {
     messageClassName?: string;
     ref?: Ref<HTMLElement>;
 }
-export declare function InlineEdit({ value, onCommit, validate, liveValidate, label, placeholder, size, multiline, autosaveMs, readOnly, failureMessage, onError, editing: editingProp, onEditingChange, render, className, messageClassName, inputMode, ref, }: InlineEditProps): import("react").JSX.Element;
+/**
+ * SELF-ACTIVATED: omit `editing` and the control opens itself on click, Enter
+ * or F2. `onEditingChange` then only observes — it fires when the control
+ * starts editing and when it stops, so a caller can suspend its own
+ * re-render-from-server logic for exactly as long as someone is typing.
+ */
+interface InlineEditSelfActivated {
+    editing?: undefined;
+    onEditingChange?: (editing: boolean) => void;
+}
+/**
+ * The props. `editing` + `onEditingChange` are a discriminated pair
+ * (DX-3372 review P0): either omit `editing` (self-activated, above) or pass
+ * BOTH (`EditActivation` — controlled). Controlled, the control never opens
+ * itself; `true` opens it focused with the caret at the end; it hands the
+ * closed state back through `onEditingChange(false)` after a landed commit,
+ * Escape, or a refused opening (read-only). Setting `editing` false yourself
+ * ends the edit exactly as Escape does — nothing more is written. A save that
+ * is already out when you do cannot be recalled: it still reaches your
+ * `onCommit` promise, but its outcome no longer touches the field — no
+ * message, no focus move, no second `onEditingChange(false)` — and a commit
+ * from the next opening waits for it before starting (see
+ * `edit/use-edit-session.ts`). At rest a controlled control leaves the tab
+ * order and drops its hover affordance, so the trigger is the one stop.
+ */
+export type InlineEditProps = InlineEditFieldProps & (InlineEditSelfActivated | EditActivation);
+export declare function InlineEdit(props: InlineEditProps): import("react").JSX.Element;
+export {};

package/dist/types/components/InlineMarkdownEdit.d.ts

@@ -1,7 +1,8 @@
 import { type ReactNode } from "react";
 import type { ImageUploader } from "../lib/markdown/image-pipeline";
-import { type InlineEditCommit } from "./edit/outcome";
-export interface InlineMarkdownEditProps {
+import { type EditActivation } from "./edit/activation";
+import { type EditCommit } from "./edit/outcome";
+export interface InlineMarkdownEditProps extends EditActivation {
     /** The committed markdown. Controlled — the field only ever holds a draft. */
     value: string;
     /**
@@ -10,11 +11,18 @@ export interface InlineMarkdownEditProps {
      * began from; return/resolve `{ refusal }` to refuse with a reason, throw or
      * reject to report a failed save.
      */
-    onCommit: InlineEditCommit;
-    /** Whether the editor is open. REQUIRED — see the module comment. */
+    onCommit: EditCommit;
+    /**
+     * Whether the editor is open — REQUIRED, see the module comment. The field
+     * hands the closed state back through `onEditingChange(false)` once a commit
+     * lands, on Escape, and when asked to open while `readOnly`. Setting it
+     * `false` yourself drops the draft exactly as Escape does. A save already
+     * out when you do cannot be recalled: your `onCommit` promise still settles,
+     * but its outcome no longer touches the field — no message, no focus move,
+     * no `onEditingChange(false)` — and a commit from the next opening waits for
+     * it before starting.
+     */
     editing: boolean;
-    /** The field asks to close through this, once a commit lands or Escape cancels. */
-    onEditingChange: (editing: boolean) => void;
     /** The accessible name of the field and of its editor. */
     label: string;
     /** Shown at rest and in the editor when the value is empty. @default "Empty" */
@@ -25,13 +33,23 @@ export interface InlineMarkdownEditProps {
     toolbar?: ReactNode;
     /** Stores a pasted/dropped/picked image — see `MarkdownEditorProps.uploadImage`. */
     uploadImage?: ImageUploader;
+    /**
+     * This value cannot be edited at all, AND WHY — `InlineEdit.readOnly`'s
+     * shape and rule: asked to open, the field hands `onEditingChange(false)`
+     * straight back, and the reason is the rest view's accessible description.
+     */
+    readOnly?: {
+        reason: string;
+    };
     /**
      * What is shown when the commit REJECTS (never a `{ refusal }`, which
      * renders its own text).
+     *
+     * @default "Could not save. Your text is still here — press Ctrl+Enter to try again."
      */
     failureMessage?: string;
     /** The rejected error, handed on so it can be logged or reported. */
     onError?: (error: unknown) => void;
     className?: string;
 }
-export declare function InlineMarkdownEdit({ value, onCommit, editing, onEditingChange, label, placeholder, collapsedLines, toolbar, uploadImage, failureMessage, onError, className, }: InlineMarkdownEditProps): import("react").JSX.Element;
+export declare function InlineMarkdownEdit(props: InlineMarkdownEditProps): import("react").JSX.Element;

package/dist/types/components/MarkdownEditor.d.ts

@@ -15,6 +15,13 @@ export interface MarkdownEditorHandle {
      * `"end"` (snapped to a real caret stop); omit it to leave the caret wherever
      * the browser puts it. DX-3372: `InlineMarkdownEdit` opens with the caret at
      * the end, the same place `InlineEdit` puts it.
+     *
+     * THROWS rather than returning quietly (DX-3372 review P0) when it cannot do
+     * what it was asked: the surface is not built yet (it is created in an
+     * effect, so a render or a layout effect is too early), the editor is
+     * read-only, focus did not land on the surface, or the caret could not be
+     * placed. A caller that goes on to assume focus is inside would otherwise
+     * wait for a blur that never comes.
      */
     focus: (caret?: "start" | "end") => void;
 }

package/dist/types/components/edit/activation.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The controlled activation pair every pencil-activated field takes, and the
+ * pair `EditGutter` hands out — so wiring a pencil to a field is one spread.
+ *
+ * `editing` says whether the field is open. The field calls
+ * `onEditingChange(false)` when it closes itself (a landed commit, Escape) and
+ * when it declines to open (read-only); it never calls `onEditingChange(true)`
+ * for an opening the caller made. The pair is all-or-nothing: a controlled
+ * `editing` with no way to hand the closed state back would leave the field
+ * shut after its first commit while the caller still believes it is open.
+ */
+export interface EditActivation {
+    editing: boolean;
+    onEditingChange: (editing: boolean) => void;
+}
+/**
+ * Throws when a caller controls `editing` without `onEditingChange`. The
+ * types already forbid it; this covers a caller that got past them (a cast,
+ * a spread of `any`, plain JavaScript). DX-3372 review P0.
+ */
+export declare function assertActivationPair(component: string, editing: boolean | undefined, onEditingChange: ((editing: boolean) => void) | undefined): void;

package/dist/types/components/edit/outcome.d.ts

@@ -1,16 +1,27 @@
 /**
  * The caller's refusal of a value, with the reason that will be shown.
  */
-export interface InlineEditRefusal {
+export interface EditRefusal {
     refusal: string;
 }
 /** What `onCommit` may report. Returning nothing accepts the value. */
-export type InlineEditOutcome = void | InlineEditRefusal;
+export type EditOutcome = void | EditRefusal;
 /** Every in-place editor's `onCommit`: the new value and the value editing began from. */
-export type InlineEditCommit = (value: string, base: string) => InlineEditOutcome | Promise<InlineEditOutcome>;
-export declare function isRefusal(outcome: InlineEditOutcome): outcome is InlineEditRefusal;
-export declare function isPromise(outcome: InlineEditOutcome | Promise<InlineEditOutcome>): outcome is Promise<InlineEditOutcome>;
-export declare const DEFAULT_FAILURE = "Could not save. Your text is still here \u2014 press Enter to try again.";
+export type EditCommit = (value: string, base: string) => EditOutcome | Promise<EditOutcome>;
+export declare function isRefusal(outcome: EditOutcome): outcome is EditRefusal;
+export declare function isPromise(outcome: EditOutcome | Promise<EditOutcome>): outcome is Promise<EditOutcome>;
+/**
+ * The key that retries a failed save in a given field: Enter where Enter
+ * commits, Ctrl+Enter where Enter inserts a newline. (Both fields accept
+ * Cmd+Enter as well as Ctrl+Enter, so "Ctrl+Enter" is true on every platform.)
+ */
+export type RetryKey = "Enter" | "Ctrl+Enter";
+/**
+ * The default failure message. It names the retry key because blur never
+ * re-attempts a failed value — DX-3372 review L1: the single shared sentence
+ * said "press Enter" in fields where Enter inserts a newline.
+ */
+export declare function defaultFailureMessage(retryKey: RetryKey): string;
 /**
  * A refusal nobody can read leaves the field open with nothing beside it — the
  * exact silent failure the outcome contract exists to rule out — so an empty

package/dist/types/components/edit/use-edit-session.d.ts

@@ -0,0 +1,55 @@
+import { type EditCommit, type EditOutcome } from "./outcome";
+export type SaveResult = {
+    outcome: EditOutcome;
+} | {
+    error: unknown;
+};
+export interface EditSessionOptions {
+    /** Named in the thrown message when a refusal carries an empty reason. */
+    component: string;
+    /** The committed value — "unchanged" is measured against it. Read live. */
+    value: string;
+    onCommit: EditCommit;
+    onError?: (error: unknown) => void;
+    failureMessage: string;
+    /** End editing after a commit that landed (or had nothing to write). */
+    close: () => void;
+    /** Put focus back on the field after a refusal or a failure. */
+    refocus: () => void;
+}
+export interface EditSession {
+    pending: boolean;
+    refusal: string | null;
+    failure: string | null;
+    /** The message on screen, if any — a refusal or a failure. */
+    blocked: string | null;
+    /** The value this session began from — `onCommit`'s `base`. */
+    readonly base: string;
+    /** Start a new session. `refusal` seeds the message slot (live validation). */
+    begin: (base: string, refusal?: string | null) => void;
+    /** Finish the current session: every save still out becomes stale. */
+    end: () => void;
+    /** Commit `next` — unchanged check (see the module comment), `validate`, `onCommit`, outcome. */
+    commit: (next: string, validate?: (next: string) => string | null) => void;
+    refuse: (reason: string, source: "validate" | "onCommit") => void;
+    fail: (error: unknown) => void;
+    setPending: (pending: boolean) => void;
+    isPending: () => boolean;
+    setRefusal: (refusal: string | null) => void;
+    clearFailure: () => void;
+    /** The current session's token, for a caller that tracks its own save. */
+    token: () => number;
+    /** Whether a save from any session is still out. */
+    busy: () => boolean;
+    /** The in-flight save, settled or not — chain after it to stay in order. */
+    inFlight: () => Promise<void> | null;
+    /**
+     * Track a save sent under `token`. `onResult` runs only if that session is
+     * still current when it settles; otherwise `onStale` does (after a stale
+     * rejection has reached `onError`).
+     */
+    track: (save: Promise<EditOutcome>, token: number, onResult: (result: SaveResult) => void, onStale?: (result: SaveResult) => void) => void;
+    /** Run `fn` once no save is out — dropped if this session ends first. */
+    whenIdle: (fn: () => void) => void;
+}
+export declare function useEditSession(options: EditSessionOptions): EditSession;

package/dist/types/components/graph-explorer/GraphExplorer.d.ts

@@ -0,0 +1,35 @@
+import type { CanvasNode } from "../node-canvas/types";
+import type { CrossLink, ExplorerNodeRenderer, ExplorerTree, GraphExplorerVariant } from "./types";
+export interface GraphExplorerProps<Extra = unknown> {
+    tree: ExplorerTree<Extra>;
+    /** Secondary relationships drawn over the fixed layout. Never affects positions. */
+    crossLinks?: readonly CrossLink[];
+    /** The accessible name of the whole structure. Required — see `NodeCanvasProps.label`. */
+    label: string;
+    /** The node body. Defaults to the label, wrapped, never truncated. */
+    renderNode?: ExplorerNodeRenderer<Extra>;
+    /** @default "explorer" */
+    variant?: GraphExplorerVariant;
+    /** Which node the camera centres on, with a "you are here" highlight. Controlled. */
+    focusId?: string | null;
+    /** Initial `focusId` for uncontrolled use. */
+    defaultFocusId?: string | null;
+    /** Fired when the controlled `focusId` would change — a node click, or `flyTo` via the keyboard. Never fired with `null`: nothing in this component ever clears focus, only moves it. */
+    onFocusIdChange?: (id: string) => void;
+    /** Nodes styled as already seen. */
+    visitedIds?: ReadonlySet<string> | readonly string[];
+    /** Fired when an ordinary node is clicked or activated by keyboard. */
+    onNodeClick?: (node: CanvasNode<Extra>) => void;
+    /** `variant="minimap"` only: the expand affordance's handler. Defaults to an in-place full-screen dialog. */
+    onExpand?: () => void;
+    /** Along-axis extent of a node that does not need more, in px. @default LAYOUT_DEFAULTS.nodeWidth */
+    nodeWidth?: number;
+    /** Cross-axis extent BEFORE a taller node's own content grows it. @default LAYOUT_DEFAULTS.nodeHeight */
+    nodeHeight?: number;
+    /** `variant="explorer"` only: height of the viewport. @default "32rem" */
+    height?: string;
+    /** Nothing pans, zooms or clicks. Reading is unaffected. */
+    disabled?: boolean;
+    className?: string;
+}
+export declare function GraphExplorer<Extra = unknown>({ tree, crossLinks, label, renderNode, variant, focusId: controlledFocusId, defaultFocusId, onFocusIdChange, visitedIds, onNodeClick, onExpand, nodeWidth, nodeHeight, height, disabled, className, }: GraphExplorerProps<Extra>): import("react").JSX.Element;

package/dist/types/components/graph-explorer/camera-math.d.ts

@@ -0,0 +1,50 @@
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface Box {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface Size {
+    width: number;
+    height: number;
+}
+export interface CameraState {
+    x: number;
+    y: number;
+    scale: number;
+}
+export interface ScaleBounds {
+    minScale?: number;
+    maxScale?: number;
+}
+export declare const CAMERA_DEFAULTS: {
+    readonly minScale: 0.15;
+    readonly maxScale: 3;
+    readonly fitMaxScale: 1;
+    readonly fitPadding: 64;
+};
+export declare function clampScale(scale: number, bounds?: ScaleBounds): number;
+/** Screen point → the content point currently sitting under it. */
+export declare function toContentPoint(camera: CameraState, screenPoint: Point): Point;
+/** Content point → where it currently sits on screen. */
+export declare function toScreenPoint(camera: CameraState, contentPoint: Point): Point;
+/**
+ * Zoom by `factor`, holding `screenPoint` fixed over the same content point it
+ * covered before — the standard "zoom toward the cursor" behaviour a wheel or
+ * a pinch both want. `factor` > 1 zooms in.
+ */
+export declare function zoomAtPoint(camera: CameraState, screenPoint: Point, factor: number, bounds?: ScaleBounds): CameraState;
+/** A camera that puts `target`'s centre in the middle of `viewport`, at `scale`. */
+export declare function centerOn(target: Box | Point, viewport: Size, scale: number): CameraState;
+export interface FitOptions extends ScaleBounds {
+    /** @default CAMERA_DEFAULTS.fitPadding */
+    padding?: number;
+    /** @default CAMERA_DEFAULTS.fitMaxScale — never zoom IN past this to fit a small box. */
+    maxScale?: number;
+}
+/** A camera that fits the whole of `box` inside `viewport`, centred, padded. */
+export declare function fitBox(box: Box, viewport: Size, options?: FitOptions): CameraState;

package/dist/types/components/graph-explorer/index.d.ts

@@ -0,0 +1,5 @@
+export { GraphExplorer, type GraphExplorerProps } from "./GraphExplorer";
+export { layoutExplorerTree, neighbourhoodTree, edgePath } from "./tree-layout";
+export { CAMERA_DEFAULTS, centerOn, clampScale, fitBox, toContentPoint, toScreenPoint, zoomAtPoint } from "./camera-math";
+export type { Box, CameraState, FitOptions, Point, ScaleBounds, Size } from "./camera-math";
+export type { CrossLink, ExplorerLayout, ExplorerNodeRenderContext, ExplorerNodeRenderer, ExplorerTree, GraphExplorerVariant, TreeNode, } from "./types";

package/dist/types/components/graph-explorer/tree-layout.d.ts

@@ -0,0 +1,29 @@
+import { edgePath } from "../node-canvas/layout";
+import type { LayoutOptions } from "../node-canvas/types";
+import type { CrossLink, ExplorerLayout, ExplorerTree } from "./types";
+/** Re-exported for a consumer drawing `edges`/`crossLinks` into an SVG. */
+export { edgePath };
+/**
+ * Lay out a tree, left to right, from a parent backbone alone.
+ *
+ * `crossLinks` are resolved against the ALREADY-FIXED node positions and
+ * returned separately (`ExplorerLayout.crossLinks`) — they never reach
+ * `layoutGraph`, so they can never move a node and can never close a cycle
+ * for the layout engine to condense. A cross-link naming an id not in the
+ * tree, or naming a node as linked to itself, draws nothing — the same
+ * "dangling edge draws nothing" rule `node-canvas/layout.ts#resolveScope`
+ * uses for a group boundary.
+ */
+export declare function layoutExplorerTree<Extra>(tree: ExplorerTree<Extra>, crossLinks?: readonly CrossLink[], options?: LayoutOptions): ExplorerLayout<Extra>;
+/**
+ * The subtree a minimap draws: `focusId`'s ancestor chain up to its root,
+ * `focusId`'s immediate siblings, and `focusId`'s immediate children — "the
+ * focused node's ancestors, siblings and children" the card asks for, kept
+ * small enough to read at the minimap's compact size. `focusId` itself is
+ * always included. Parent links are REWRITTEN to stay inside this subset: the
+ * topmost ancestor kept becomes a root (`parentId: null`) here even if its
+ * real parent exists outside the shown set, so `layoutExplorerTree` never
+ * sees a dangling parent reference. Returns `null` when `focusId` is not in
+ * `tree` at all — nothing sensible to show.
+ */
+export declare function neighbourhoodTree<Extra>(tree: ExplorerTree<Extra>, focusId: string): ExplorerTree<Extra> | null;

package/dist/types/components/graph-explorer/types.d.ts

@@ -0,0 +1,62 @@
+import type { ReactNode } from "react";
+import type { CanvasEdge, CanvasNode, CanvasPlacedEdge, LayoutOptions, PlacedNode } from "../node-canvas/types";
+/**
+ * One node of the tree. Same `Extra`-carrying shape as `CanvasNode` — a
+ * consumer's own fields come back untouched through `renderNode` — plus the
+ * one thing a tree node has that a general graph node does not: its parent.
+ */
+export type TreeNode<Extra = unknown> = CanvasNode<Extra> & {
+    /** The node this one hangs from. `null` for a root — a tree may have more than one. */
+    parentId: string | null;
+};
+/**
+ * A secondary relationship drawn OVER the fixed tree layout — never fed to
+ * the layout engine, so it can never move a node and can never close a cycle
+ * for dagre to condense. `kind` carries no meaning the library assigns, same
+ * rule as `CanvasEdge.kind`.
+ */
+export interface CrossLink {
+    from: string;
+    to: string;
+    kind?: string;
+}
+/** The whole tree. Never mutated by the component. */
+export interface ExplorerTree<Extra = unknown> {
+    nodes: readonly TreeNode<Extra>[];
+}
+/** What `layoutExplorerTree` hands back: the fixed layout, ready to draw. */
+export interface ExplorerLayout<Extra = unknown> {
+    nodes: PlacedNode<Extra>[];
+    /** The parent → child backbone, drawn as the primary edges. */
+    edges: CanvasPlacedEdge[];
+    /** `CrossLink`s resolved to drawn curves. Never affects `nodes`' positions. */
+    crossLinks: CanvasPlacedEdge[];
+    /** Extent of the laid-out tree — the plane the camera's `fitAll` fits to. */
+    width: number;
+    height: number;
+}
+export type { CanvasEdge, CanvasNode, LayoutOptions, PlacedNode, CanvasPlacedEdge };
+/** Which surface this render is: the full pannable explorer, or the compact strip. */
+export type GraphExplorerVariant = "explorer" | "minimap";
+/**
+ * What `renderNode` is told about the node it is drawing — the explorer's own
+ * facts (camera focus, visited, hover neighbourhood), analogous to
+ * `NodeRenderContext` in `node-canvas/types.ts` but keyed on the camera's
+ * `focusId` rather than a drilled-into scope.
+ */
+export interface ExplorerNodeRenderContext {
+    /** This node carries the canvas's single roving tab stop. */
+    isTabStop: boolean;
+    /** This IS the controlled `focusId` — the "you are here" node. */
+    isFocused: boolean;
+    /** In the caller-supplied `visitedIds`. */
+    isVisited: boolean;
+    /**
+     * Hops from whichever node is currently the reference point — the hovered
+     * node while one is hovered, else the focused node — along either edge
+     * direction (backbone or cross-link). `null` when nothing is being
+     * referenced, or this node is further away than the explorer tracks.
+     */
+    distance: number | null;
+}
+export type ExplorerNodeRenderer<Extra = unknown> = (node: CanvasNode<Extra>, context: ExplorerNodeRenderContext) => ReactNode;

package/dist/types/components/graph-explorer/use-camera.d.ts

@@ -0,0 +1,31 @@
+import { type Box, type CameraState } from "./camera-math";
+export interface CameraClickEvent {
+    /** Client coordinates, for the caller to hit-test against its own elements. */
+    target: HTMLElement;
+}
+export interface UseCameraOptions {
+    /** Content-space bounding box of the whole drawing. Drives `fitAll`. */
+    contentBox: Box;
+    /** A node's content-space box, for `flyTo`. `null` for an id not laid out. */
+    boxOf: (id: string) => Box | null;
+    /** A press that released without travelling past `CLICK_DISTANCE`. */
+    onClick?: (event: CameraClickEvent) => void;
+    /** Nothing pans, zooms or clicks. Reading the plane still works. */
+    disabled?: boolean;
+    /** Changing this value re-fits the camera to `contentBox` — a new tree. */
+    resetKey?: unknown;
+}
+export interface UseCameraResult {
+    camera: CameraState;
+    /** A pointer is actively panning or pinching right now. */
+    panning: boolean;
+    /** True for the duration of a programmatic move — see the module doc. */
+    animating: boolean;
+    bindViewport: (node: HTMLDivElement | null) => void;
+    zoomIn: () => void;
+    zoomOut: () => void;
+    fitAll: () => void;
+    /** Animate the camera to centre node `id`. No-op if `id` isn't laid out yet. */
+    flyTo: (id: string, scale?: number) => void;
+}
+export declare function useCamera(options: UseCameraOptions): UseCameraResult;

package/dist/types/icons/data.d.ts

@@ -630,6 +630,31 @@ export declare const coreIcons: {
     }], readonly ["path", {
         readonly d: "M15 3v18";
     }]];
+    readonly crosshair: readonly [readonly ["circle", {
+        readonly cx: "12";
+        readonly cy: "12";
+        readonly r: "10";
+    }], readonly ["line", {
+        readonly x1: "22";
+        readonly x2: "18";
+        readonly y1: "12";
+        readonly y2: "12";
+    }], readonly ["line", {
+        readonly x1: "6";
+        readonly x2: "2";
+        readonly y1: "12";
+        readonly y2: "12";
+    }], readonly ["line", {
+        readonly x1: "12";
+        readonly x2: "12";
+        readonly y1: "6";
+        readonly y2: "2";
+    }], readonly ["line", {
+        readonly x1: "12";
+        readonly x2: "12";
+        readonly y1: "22";
+        readonly y2: "18";
+    }]];
     readonly "delete-column": readonly [readonly ["path", {
         readonly d: "M2 12h6";
     }], readonly ["path", {

package/dist/types/index.d.ts

@@ -21,9 +21,11 @@ export { Skeleton, SkeletonText, LoadingOverlay, type SkeletonProps, type Skelet
 export { ErrorBoundary, type ErrorBoundaryProps } from "./components/ErrorBoundary";
 export { Field, FieldSet, type FieldProps, type FieldSetProps } from "./components/Field";
 export { Input, Textarea, type InputProps, type TextareaProps } from "./components/Input";
-export { InlineEdit, type InlineEditProps, type InlineEditRefusal, type InlineEditOutcome, type InlineEditCommit, } from "./components/InlineEdit";
-export { EditGutter, type EditGutterProps, type EditActivation } from "./components/EditGutter";
+export { InlineEdit, type InlineEditProps } from "./components/InlineEdit";
+export { EditGutter, type EditGutterProps } from "./components/EditGutter";
 export { InlineMarkdownEdit, type InlineMarkdownEditProps } from "./components/InlineMarkdownEdit";
+export type { EditActivation } from "./components/edit/activation";
+export type { EditCommit, EditOutcome, EditRefusal } from "./components/edit/outcome";
 export { SecretField, type SecretFieldProps, type SecretValue } from "./components/SecretField";
 export { SettingRow, SettingGroup, type SettingRowProps, type SettingGroupProps, type SettingRowControlRenderProps, } from "./components/SettingRow";
 export { DescriptionList, DescriptionListItem, type DescriptionListProps, type DescriptionListItemProps, type DescriptionListEntry, } from "./components/DescriptionList";
@@ -127,6 +129,7 @@ export { ProvenanceDisclosure, ProvenanceDetail, ProvenanceBadge, ConfidenceRead
 export { confidenceLevel, CONFIDENCE_LEVEL_LABELS, type ConfidenceLevel } from "./lib/confidence";
 export { createSimStore, resetSimStores, useSimSettings, setSimSettings, getNetworkSpeed, getDataSource, simulateLatency, SimNetworkError, type SimStore, type SimStoreOptions, type SimSettings, type NetworkSpeed, type DataSource, type SimNamespace, } from "./lib/sim";
 export { NodeCanvas, LAYOUT_DEFAULTS, edgePath, layoutGraph, neighbourhood, type NodeCanvasProps, type CanvasCycleScope, type CanvasEdge, type CanvasGraph, type CanvasGroup, type CanvasLayout, type CanvasNode, type CanvasOrientation, type CanvasPlacedEdge, type CanvasScope, type LayoutOptions, type NodeRenderContext, type NodeRenderer, type PlacedNode, } from "./components/node-canvas";
+export { GraphExplorer, layoutExplorerTree, neighbourhoodTree, CAMERA_DEFAULTS, centerOn, clampScale, fitBox, toContentPoint, toScreenPoint, zoomAtPoint, type GraphExplorerProps, type Box, type CameraState, type FitOptions, type Point, type ScaleBounds, type Size, type CrossLink, type ExplorerLayout, type ExplorerNodeRenderContext, type ExplorerNodeRenderer, type ExplorerTree, type GraphExplorerVariant, type TreeNode as ExplorerTreeNode, } from "./components/graph-explorer";
 export { defineRecordType, resetRecordTypes, useRecord, useRecords, useStaleness, write, writeAll, peekRecord, readState, readStaleness, subscribeToKey, subscribeToStaleness, retainKeys, sweepRecords, setRecordStoreTenant, getRecordStoreTenant, flushRecordNotifications, resetRecordStore, recordStoreStats, UNKNOWN_STATE, normalizeTypeName, normalizeTimestamp, recordKey, isRecordRef, type RecordRef, type ReadOptions, type RecordPayload, type RecordState, type RecordTypeOptions, type RecordTypeToken, type StalenessEntry, type WriteAllResult, type WriteOptions, type WriteResult, type WriteSource, type WriteVerdict, } from "./lib/records";
 export { RealtimeProvider, useRealtime, useRealtimeEpoch, useRealtimeHealth, useRealtimeRegistry, SubscriptionRegistry, normalizeScope, scopeKey, subscriptionKey, readRealtimeEpoch, subscribeToRealtimeEpoch, subscribeToRealtimeEvents, resetRealtimeSignals, type RealtimeChannel, type RealtimeConnectionState, type RealtimeDiagnostic, type RealtimeEvent, type RealtimeHealth, type RealtimeProviderProps, type RealtimeScope, type RealtimeScopeInput, type RealtimeStatus, type RealtimeTransport, type RegistryOptions, type SubscriptionHealth, type SubscriptionLease, type SubscriptionRequest, } from "./lib/realtime";
 export { useRecordRead, useRecordListRead, useRecordStoreSweep, applyMutationResult, optimisticWrite, beginOptimisticWrite, resetOptimisticWrites, type OptimisticHandle, type OptimisticWriteOptions, type OptimisticWriteSpec, type SlotDescriptor, acquireSlot, appendCreated, emptySlotSnapshot, readSlot, resetSlots, slotKeys, subscribeToSlot, writeSlot, RefetchRunner, registerActiveRead, resetActiveReads, type ActiveRead, type ListFetch, type ListFetchResult, type ListReadOptions, type ListReadResult, type ReadError, type RecordFetch, type RecordReadOptions, type RecordReadResult, type RunnerOptions, type SlotSnapshot, } from "./lib/reads";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danxbot/ui",
-  "version": "11.1.0",
+  "version": "12.1.0",
   "type": "module",
   "description": "Danxbot — a domain-agnostic React design system with motion as a first-class primitive.",
   "license": "MIT",