@50arms/ui 0.0.0-stage → 35.2.0

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

@@ -0,0 +1,81 @@
+import { type Box, type CameraState, type FrameOverflow } from "./camera-math";
+import { type ViewportClickEvent } from "./viewport-gesture";
+export type CameraClickEvent = ViewportClickEvent;
+export interface UseCameraOptions {
+    /** Content-space bounding box of the whole drawing. Drives `fitAll`. */
+    contentBox: Box;
+    /**
+     * The box the camera AUTOMATICALLY keeps in frame — on mount, and again
+     * whenever `frameKey` changes (DX-3401). Typically the focused node plus
+     * its parent and children, so the camera never zooms out further than the
+     * relevant neighbourhood just because the whole tree is big. `null`/
+     * `undefined` falls back to `contentBox` (fit the whole drawing) — the
+     * ordinary case when there is no focus yet.
+     */
+    frameBox?: Box | null;
+    /**
+     * A caller-chosen, STABLE value (e.g. the focused node's id) that changing
+     * re-runs the automatic frame fit even when `resetKey` hasn't changed —
+     * `frameBox` itself is deliberately NOT a dependency (see the frame-fit
+     * effect below for why), so this is the only reliable "the frame target
+     * moved" signal for a caller whose `resetKey` tracks something else (e.g.
+     * the explorer's own `resetKey` is the tree, not the focused node).
+     */
+    frameKey?: unknown;
+    /** Padding around the auto-fit target (`frameBox ?? contentBox`) — distinct
+        from `fitAll`'s always-`CAMERA_DEFAULTS.fitPadding`, since a compact
+        minimap strip wants much less breathing room than the full explorer.
+        @default CAMERA_DEFAULTS.fitPadding */
+    framePadding?: number;
+    /**
+     * A THIRD, stricter lower bound layered on top of `fitBounds`'s own
+     * `minScale`, applied ONLY to the automatic frame-fit effect below — NEVER
+     * to `fitAll` (which keeps calling `fitBox` directly with `fitBounds`) and
+     * NEVER to `zoomBounds` (wheel/pinch/+/-, which stay `CAMERA_DEFAULTS
+     * .minScale`..`maxScale`) (DX-3404). See `camera-math.ts`'s
+     * `FitWithFloorOptions.minReadableScale` for the full behaviour: below
+     * this scale, the automatic fit clamps here and centres on `focusBox`
+     * instead of shrinking `frameBox ?? contentBox` to fit — the rest is
+     * reached by panning. `undefined` (the default) reproduces the pre-DX-3404
+     * behaviour exactly (plain `fitBox`, no floor).
+     */
+    minReadableScale?: number;
+    /**
+     * What the automatic fit centres on once `minReadableScale` clamps the
+     * scale — normally the focused node's own (small) box, distinct from the
+     * wider `frameBox` (focus + parent + children) being framed. Defaults to
+     * `frameBox ?? contentBox` when omitted, matching `fitBoxWithFloor`'s own
+     * default. Ignored when `minReadableScale` is unset.
+     */
+    focusBox?: Box | null;
+    /** 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;
+    /**
+     * Which sides of the automatic frame target (`frameBox ?? contentBox`)
+     * extend past the viewport at the CURRENT camera — all `false` unless
+     * `minReadableScale` actually clamped the last automatic fit (DX-3404).
+     * The one source of truth for an "edge cue" overlay, so a caller never
+     * re-derives this from raw `camera` state itself.
+     */
+    frameOverflow: FrameOverflow;
+    bindViewport: (node: HTMLElement | null) => (() => void) | undefined;
+    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/components/graph-explorer/viewport-gesture.d.ts

@@ -0,0 +1,32 @@
+import { type CameraState, type ScaleBounds, type Size } from "./camera-math";
+/** How far a pointer may travel and still resolve to a click on release — below
+    the jitter of a resting hand, above the travel of a deliberate press. */
+export declare const CLICK_DISTANCE = 5;
+export interface ViewportClickEvent {
+    /** The element under the pointer at release, for the caller to hit-test. */
+    target: HTMLElement;
+}
+export interface UseViewportGestureOptions {
+    /** The camera right now. Read at the start of a pan and on every resume. */
+    camera: CameraState;
+    /** Wheel, pan and pinch write the camera through this. Wheel and pinch use
+        the updater form: they compound on whatever is current. */
+    setCamera: (next: CameraState | ((current: CameraState) => CameraState)) => void;
+    /** Wheel and pinch never leave these. */
+    zoomBounds: ScaleBounds;
+    /** A new gesture is starting: stop any programmatic move in flight. */
+    onGestureStart?: () => void;
+    /** A press that released without travelling past `CLICK_DISTANCE`. */
+    onClick?: (event: ViewportClickEvent) => void;
+    /** The viewport's content-box size, on observe and on every change. */
+    onResize?: (size: Size) => void;
+    /** Nothing pans, zooms or clicks. */
+    disabled?: boolean;
+}
+export interface UseViewportGestureResult {
+    /** A pointer is actively panning or pinching right now. */
+    panning: boolean;
+    /** Callback ref for the clipping viewport element. */
+    bindViewport: (node: HTMLElement | null) => (() => void) | undefined;
+}
+export declare function useViewportGesture(options: UseViewportGestureOptions): UseViewportGestureResult;

package/dist/types/components/kanban/KanbanBoard.d.ts

@@ -0,0 +1,72 @@
+import { type ReactNode } from "react";
+import type { DragSessionCallbacks } from "../../lib/dnd";
+import type { KanbanLane, KanbanMove, KanbanRefusal } from "./types";
+export type { KanbanLane, KanbanMove, KanbanRefusal };
+export interface KanbanBoardProps<T> extends Omit<DragSessionCallbacks, "onDragEnd"> {
+    /**
+     * What this board is a board OF — "Case pipeline", "Release queue".
+     *
+     * It names the horizontal scroller, which is a tab stop because a board wider
+     * than the screen is otherwise unreachable by keyboard. An unlabelled stop
+     * announces as "group" and gives nobody a reason to be there, which is why
+     * this is required rather than optional.
+     */
+    label: string;
+    lanes: readonly KanbanLane<T>[];
+    getItemId: (item: T) => string;
+    /**
+     * A speakable name for one record — "SS-2026-0412, M.R.".
+     *
+     * Required rather than optional. It is what every announcement says, and the
+     * fallback for a missing one is the id, which is speakable and never right.
+     */
+    itemLabel: (item: T) => string;
+    renderItem: (item: T) => ReactNode;
+    /**
+     * The card while it is being carried. Defaults to `renderItem`.
+     *
+     * Worth overriding when the resting card is dense: the clone is moving, often
+     * under a cursor, and the two or three fields that identify the record are
+     * the only ones anybody reads off it.
+     *
+     * It changes what the carried card SHOWS and nothing else. Whether a card is
+     * carried, and how, is not a board's decision — `DragDrop` lifts every card
+     * into a portalled clone, and a board that omitted the piece that did the
+     * carrying used to get cards that could not leave their own lane.
+     */
+    renderDragging?: (item: T) => ReactNode;
+    onMove: (move: KanbanMove) => void;
+    /** Called INSTEAD of `onMove` when the destination lane carries a `refusal`. */
+    onRefuse?: (refusal: KanbanRefusal) => void;
+    /** Shown in a lane with no cards. Omitted, the provider's `kanban.empty`. */
+    emptyLane?: ReactNode;
+    /**
+     * Fill the space between the board's own top and the bottom of whatever
+     * scrolls it, so the lanes are the only thing that scrolls down.
+     *
+     * `true` — the default, and what a board IS. It was not the default until
+     * 3.7.0, and the reason is worth keeping: the height was expressed purely as
+     * a `flex-1 min-h-0` chain, which is correct and is correct only while every
+     * ancestor cooperates. One ordinary page wrapper above the board — a bare
+     * `<div className="flex flex-col gap-10">`, which is this package's own demo
+     * layout — makes `flex-1` inert, the board sizes to its tallest lane, and the
+     * PAGE takes the scrollbar that was supposed to belong to a column. Reported
+     * from a running board: "the columns should fill to the full remaining height
+     * of the page. No scroll bar vertically. Only scroll vertically per column."
+     *
+     * The height is MEASURED (`lib/use-fill-height`), not computed from a token,
+     * and re-measured whenever anything above the board changes size. It is
+     * paired with `max-h-full`, so an ancestor that genuinely does bound the board
+     * still wins and a board in a short box does not overflow it.
+     *
+     * `false` — the board is as tall as the box it is given, or as its tallest
+     * lane if nothing gives it one. For a board deliberately sized by its
+     * container (`h-[60dvh]`, a fixed-height card) or embedded in a page that is
+     * meant to scroll as a document.
+     *
+     * @default true
+     */
+    fill?: boolean;
+    className?: string;
+}
+export declare function KanbanBoard<T>({ label, lanes, getItemId, itemLabel, renderItem, renderDragging, onMove, onRefuse, emptyLane, fill, className, ...callbacks }: KanbanBoardProps<T>): import("react").JSX.Element;

package/dist/types/components/kanban/recipe.d.ts

@@ -0,0 +1,73 @@
+export declare const kanban: import("tailwind-variants").TVReturnType<{
+    refusing: {
+        true: {
+            lane: string;
+        };
+        false: {};
+    };
+    fill: {
+        true: {
+            root: string;
+        };
+        false: {
+            root: string;
+        };
+    };
+}, {
+    root: string;
+    lane: string;
+    laneHeader: string;
+    laneLabel: string;
+    laneHint: string;
+    laneItems: string;
+    card: string;
+    laneEmpty: string;
+}, undefined, {
+    refusing: {
+        true: {
+            lane: string;
+        };
+        false: {};
+    };
+    fill: {
+        true: {
+            root: string;
+        };
+        false: {
+            root: string;
+        };
+    };
+}, {
+    root: string;
+    lane: string;
+    laneHeader: string;
+    laneLabel: string;
+    laneHint: string;
+    laneItems: string;
+    card: string;
+    laneEmpty: string;
+}, import("tailwind-variants").TVReturnTypeLike<{
+    refusing: {
+        true: {
+            lane: string;
+        };
+        false: {};
+    };
+    fill: {
+        true: {
+            root: string;
+        };
+        false: {
+            root: string;
+        };
+    };
+}, {
+    root: string;
+    lane: string;
+    laneHeader: string;
+    laneLabel: string;
+    laneHint: string;
+    laneItems: string;
+    card: string;
+    laneEmpty: string;
+}>>;

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

@@ -0,0 +1,55 @@
+import type { ReactNode } from "react";
+export interface KanbanLane<T> {
+    id: string;
+    /** Spoken in every announcement about this lane, and shown on it. */
+    label: string;
+    /** What the lane means. One line, under the label. */
+    hint?: ReactNode;
+    /**
+     * Work-in-progress ceiling.
+     *
+     * ABSENT MEANS NO CEILING. Not a large number standing in for one: a lane
+     * whose limit is 99 renders "3 / 99", which asks the reader to work out that
+     * 99 was never a real ceiling. Omit the prop and the lane shows a plain
+     * count.
+     */
+    limit?: number;
+    /** In the order they should appear. Their index is what a move reports. */
+    items: readonly T[];
+    /**
+     * Shown in THIS lane when it has no cards, overriding the board's own
+     * `emptyLane`.
+     *
+     * One message for a whole board is right until one lane means something
+     * different from the others — an empty backlog reads "nothing waiting" and an
+     * empty released column reads "nothing shipped yet", and a single string has
+     * to be vague enough to be true of both, which makes it useless for either.
+     */
+    empty?: ReactNode;
+    /**
+     * Why a card may not be dropped here. Absent means the lane accepts drops.
+     *
+     * Written for the person who would have tried — "needs the case.decide
+     * permission", not "forbidden". It is shown on the lane before anyone drags,
+     * and passed back verbatim through `onRefuse`.
+     */
+    refusal?: string;
+}
+export interface KanbanMove {
+    id: string;
+    from: {
+        lane: string;
+        index: number;
+    };
+    /** `index` is the position in the destination lane WITHOUT the moved card. */
+    to: {
+        lane: string;
+        index: number;
+    };
+}
+export interface KanbanRefusal {
+    id: string;
+    lane: string;
+    /** The sentence shown: the lane's `refusal` verbatim, or the provider's `moveRejected` wording of the core's refusal. */
+    reason: string;
+}

package/dist/types/components/markdown/Affordances.d.ts

@@ -0,0 +1,105 @@
+import { type UiStrings } from "../../lib/i18n";
+import { type BlockInfo, type BlockKind, type ConstructInfo, type InlineMark } from "../../lib/markdown/convert";
+import { type Command } from "../../lib/markdown/commands";
+import type { MarkdownSurface } from "../../lib/markdown/surface";
+export interface EditorState {
+    source: string;
+    /** Collapsed caret offset, or null when there is no selection in the host. */
+    caret: number | null;
+    /** True when the selection covers something. */
+    ranged: boolean;
+    block: BlockInfo | null;
+    construct: ConstructInfo | null;
+    /**
+     * Inline marks (bold, italic, inline code, strikethrough) surrounding the
+     * caret's own position — the header toolbar's only source for "is bold
+     * currently active", so a toggle button never re-derives it from the
+     * source text a second time. Empty, never null, when there is nothing to
+     * report, which is the harder-to-misuse shape for a caller that only ever
+     * does `marks.has(...)`.
+     */
+    marks: Set<InlineMark>;
+}
+/**
+ * Tracks source and selection, and derives what is under the caret.
+ *
+ * `selectionchange` is a DOCUMENT event and the only signal for a caret the
+ * browser moved on its own — a click, a drag, an arrow key. It fires for the
+ * surface's own restore too, which is harmless here because this only reads.
+ */
+export declare function useEditorState(surface: MarkdownSurface | null, version: number): EditorState;
+interface TypeChoice {
+    kind: BlockKind;
+    level?: number;
+    /** Which of the active provider's `markdownAffordances.blockTypes` words names this choice. */
+    name: keyof UiStrings["markdownAffordances"]["blockTypes"];
+    icon: string;
+}
+export interface LineHandleProps {
+    surface: MarkdownSurface | null;
+    state: EditorState;
+    run: (command: Command) => void;
+    /** The container the handle is positioned inside. */
+    container: HTMLElement | null;
+    /**
+     * DX-3374: render in the EXTERNAL gutter (`right-full`, the same slot
+     * `EditGutter`'s pencil sits in — see `MarkdownEditor`'s `chrome="flush"`)
+     * rather than the INTERNAL one (`left-0`, inset into the editable's own
+     * padding). Both are still positioned relative to the same `container`; only
+     * which side of its left edge the handle renders on changes. Default
+     * (omitted/false) is the original inset gutter, unchanged for every
+     * `chrome="panel"` consumer.
+     */
+    external?: boolean;
+}
+/**
+ * A type control beside the line under the pointer, or under the caret.
+ *
+ * ON HOVER AND ON THE CARET'S LINE, never on every line at once: a permanent
+ * gutter of forty identical buttons is noise, and one that follows the pointer
+ * is discoverable the moment a pointer moves. The caret's line is included so
+ * the control exists for someone who is not using a pointer at all.
+ */
+export declare function LineHandle({ surface, state, run, container, external }: LineHandleProps): import("react").JSX.Element | null;
+export interface ConstructBarProps {
+    surface: MarkdownSurface | null;
+    state: EditorState;
+    run: (command: Command) => void;
+    container: HTMLElement | null;
+    /**
+     * Rendered as a SIBLING of `container` (under the same positioned root), not inside it: the container is
+     * `overflow-x-auto`, which clips the bar when the field is one line tall (`chrome="flush"`, see `LineHandle`'s
+     * `external`). Offsets are then taken from the container's own position in that root, with no scroll term.
+     */
+    external?: boolean;
+    /** Which links are stored files (the editor's `isFileUrl`, `blob:` included). A reference to a file gets no bar. */
+    isFileUrl?: (url: string) => boolean;
+}
+/**
+ * The controls for whatever the caret is inside — a link, an image, a fence or
+ * a table.
+ *
+ * IT APPEARS BY ITSELF rather than waiting for a click, and that is a decision
+ * the always-hidden markup forces. A destination the caret cannot enter and a
+ * control that has to be found are the same thing as no control at all; a small
+ * bar anchored to the construct you are already standing in is the shortest
+ * path from "I want to change this URL" to changing it.
+ */
+export declare function ConstructBar({ surface, state, run, container, external, isFileUrl }: ConstructBarProps): import("react").JSX.Element | null;
+export interface ConversionMenuProps {
+    surface: MarkdownSurface | null;
+    state: EditorState;
+    run: (command: Command) => void;
+    container: HTMLElement | null;
+}
+/**
+ * Right-click conversions for a selection.
+ *
+ * OURS ONLY WHEN THERE IS SOMETHING TO CONVERT. Swallowing every right-click
+ * costs the browser's own spellcheck suggestions, which is a worse trade than
+ * this menu is worth — so with no selection and nothing under the pointer, the
+ * native menu is left alone.
+ */
+export declare function ConversionMenu({ surface, state, run, container }: ConversionMenuProps): import("react").JSX.Element | null;
+export declare const AFFORDANCE_TYPES: TypeChoice[];
+export {};

package/dist/types/components/markdown/AttachmentStrip.d.ts

@@ -0,0 +1,25 @@
+import type { LocalFileInfo } from "../../lib/markdown/image-pipeline";
+import type { Projection } from "../../lib/markdown/project";
+export interface AttachmentStripProps {
+    /** The parse of the markdown the strip is computed from: the one the editor's surface already holds. */
+    projection: Projection;
+    /** Whether a link's destination is a stored file (an image construct always is). */
+    isFileUrl: (url: string) => boolean;
+    /** What the editor knows about an object URL it minted; null for any other URL. */
+    resolve: (url: string) => LocalFileInfo | null;
+    /** A name for the file at `url` that does not change when its upload finishes and its object URL is swapped for the stored one: the tile is keyed on it, so an open menu or rename survives the swap. */
+    identify: (url: string) => string;
+    /** A read-only editor offers a tile's preview and download only. */
+    readOnly?: boolean;
+    /** Inset the row from the editor's frame; the padding belongs to the strip so an editor with no files has none. */
+    padded?: boolean;
+    /** The editor's text surface: where focus goes after a tile is removed. */
+    textFocus: () => HTMLElement | null;
+    /** Gives every construct pointing at `url` a new reference name. */
+    onRename: (url: string, name: string) => void;
+    /** Deletes every construct pointing at `url`. */
+    onRemove: (url: string) => void;
+    /** Uploads a failed file again. */
+    onRetry: (url: string) => void;
+}
+export declare function AttachmentStrip({ projection, isFileUrl, resolve, identify, textFocus, readOnly, padded, onRename, onRemove, onRetry }: AttachmentStripProps): import("react").JSX.Element | null;

package/dist/types/components/markdown/ImageUpload.d.ts

@@ -0,0 +1,56 @@
+import { type ReactNode } from "react";
+import type { ImagePipelineSnapshot, ImageUploader } from "../../lib/markdown/image-pipeline";
+/** What a `MarkdownEditor` stores files with, and how it tells which links are files. */
+export interface MarkdownFileStorage {
+    uploadImage: ImageUploader | null;
+    uploadFile: ImageUploader | null;
+    imageTypes: readonly string[] | undefined;
+    isFileUrl: ((url: string) => boolean) | undefined;
+}
+export interface MarkdownImageUploadProviderProps {
+    /**
+     * Stores one picture and resolves with the URL it can be loaded from. Every
+     * `MarkdownEditor` below this provider uses it unless it passes its own
+     * `uploadImage`. It should honour `signal`, which aborts when the editor
+     * unmounts.
+     */
+    uploadImage: ImageUploader;
+    /**
+     * Stores any other file (same contract as `uploadImage`). With it, an editor takes every file type and writes a
+     * non-picture as a link, `[PDF 2](url)`; without it, a file that is not a picture is ignored. SET IT WITH
+     * `isFileUrl`: a stored file's tile is found by `isFileUrl` accepting its link, so without it the tile vanishes
+     * when the upload finishes.
+     */
+    uploadFile?: ImageUploader;
+    /**
+     * The picture types `uploadImage` stores (MIME types, e.g. `["image/png", "image/jpeg"]`); default every `image/*`.
+     * A picture of another type (an SVG, say) goes to `uploadFile` as a link, or is ignored when there is none.
+     */
+    imageTypes?: readonly string[];
+    /**
+     * Whether a link's destination is a file this app stores, so the link is an attachment tile in the strip under
+     * the text. An image construct is always an attachment; an ordinary link someone typed is never one. Default: no link is.
+     * Required alongside `uploadFile`.
+     */
+    isFileUrl?: (url: string) => boolean;
+    children?: ReactNode;
+}
+/** Makes one file storage available to every `MarkdownEditor` beneath it. */
+export declare function MarkdownImageUploadProvider({ uploadImage, uploadFile, imageTypes, isFileUrl, children }: MarkdownImageUploadProviderProps): import("react").JSX.Element;
+/**
+ * The storage an editor uses: each of its own props when given, otherwise the nearest provider's, otherwise none -
+ * in which case pasted pictures are local-only and the editor says so.
+ */
+export declare function useMarkdownFileStorage(own: Partial<MarkdownFileStorage>): MarkdownFileStorage;
+export interface ImageUploadStripProps {
+    state: ImagePipelineSnapshot;
+}
+/**
+ * The editor-chrome warning for files that cannot be stored (PLN-10 R-1): shown whenever the document holds a
+ * reference to a file that exists only in this tab. A file uploading or failed is on its own tile in the attachment
+ * strip; this is the one state no tile can explain, because the cause is the app's configuration.
+ *
+ * `aria-live="polite"` on the container, never `role="alert"` on the row: a file being pasted is news the author
+ * should hear about without being interrupted mid-sentence.
+ */
+export declare function ImageUploadStrip({ state }: ImageUploadStripProps): import("react").JSX.Element;

package/dist/types/components/media-error.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A ref callback that reports a media element which had ALREADY failed when
+ * React committed it. DX-3982.
+ *
+ * A source the browser rejects at once fails BEFORE React commits the element,
+ * and React drops an event for an uncommitted node — so `onError` never runs
+ * and the element sits at 0:00 forever. The element's own `error` is the
+ * record of that, read at commit. Pair it with `onError` for failures that
+ * arrive after.
+ */
+export declare const reportCommittedError: (onFailed: () => void) => (el: HTMLMediaElement | null) => void;

package/dist/types/components/nav-sections.d.ts

@@ -0,0 +1,10 @@
+import type { NavSection } from "./AppShell";
+export interface NavSectionsProps {
+    sections: NavSection[];
+    activeId?: string;
+    /** Icon-only rows with the label moved into a tooltip. The shell's rail. */
+    collapsed?: boolean;
+    /** Runs after the item's own `onClick`, on every row click. */
+    onNavigate?: () => void;
+}
+export declare function NavSections({ sections, activeId, collapsed, onNavigate }: NavSectionsProps): import("react").JSX.Element;

package/dist/types/components/node-canvas/NodeCanvas.d.ts

@@ -0,0 +1,66 @@
+import type { CanvasGraph, CanvasGroup, CanvasNode, CanvasOrientation, CanvasPlacedEdge, NodeRenderer } from "./types";
+export interface NodeCanvasProps<Extra = unknown> {
+    /** The whole graph — every node and edge, however many scopes it spans. Never mutated. */
+    graph: CanvasGraph<Extra>;
+    /** Named clusters nodes can belong to via `CanvasNode.groupId`. Flat — see `CanvasGroup`. */
+    groups?: readonly CanvasGroup[];
+    /**
+     * What this canvas IS — "Import graph for the docs map", "Service dependency graph".
+     *
+     * Required for the same reason `StatusChecklist.label` and `KanbanBoard.label`
+     * are: it is the accessible name of the whole structure, and somebody landing
+     * on it by keyboard or in the list view has nothing else to tell them what
+     * they are inside.
+     */
+    label: string;
+    /**
+     * The node body. Receives the consumer's own node type and a context of
+     * purely structural facts — see `NodeRenderContext`.
+     *
+     * A RENDER PROP RATHER THAN CHILDREN-AS-A-FUNCTION, for the same reason
+     * `ProvenanceDisclosure` takes `actions` and `Chat` takes a `components` map:
+     * a canvas draws MANY nodes and `children` reads as one. Optional: the
+     * default draws the label, and a member count when this box stands in for a
+     * group or a condensed cycle.
+     *
+     * Called with a SYNTHETIC node for a collapsed group or cycle — `{id, label}`
+     * only, `Extra`'s own fields absent — since no single real node's `Extra`
+     * would be honest to hand back for a box standing in for several.
+     */
+    renderNode?: NodeRenderer<Extra>;
+    /**
+     * The hover summary's content. Defaults to the node's `label`. Return
+     * `null`/`undefined` to suppress the tooltip for a particular node.
+     */
+    renderSummary?: (node: CanvasNode<Extra>) => React.ReactNode;
+    /** A class name for one drawn edge, keyed on its (possibly aggregated) `kind`. */
+    edgeClassName?: (edge: CanvasPlacedEdge) => string | undefined;
+    /** Which way the chart grows. See `CanvasOrientation`. */
+    orientation?: CanvasOrientation;
+    /** Along-axis extent of a node that does not declare its own, in px. */
+    nodeWidth?: number;
+    /** Cross-axis extent of a node that does not declare its own, in px. */
+    nodeHeight?: number;
+    /** Height of the scrolling viewport. Any CSS length. */
+    height?: string;
+    /** Which group is currently drilled into. `null` is the top level. Controlled. */
+    expandedGroupId?: string | null;
+    /** Initial drilled-into group for uncontrolled use. Default `null` (top level). */
+    defaultExpandedGroupId?: string | null;
+    /** Fired whenever the drilled-into group changes, from either a click or the keyboard. */
+    onExpandedGroupIdChange?: (groupId: string | null) => void;
+    /** Fired when an ORDINARY node (not a group, not a cycle) is clicked. Navigation is the consumer's. */
+    onNodeClick?: (node: CanvasNode<Extra>) => void;
+    /** Fired when a node drag commits. The offset is from its laid-out position. */
+    onNodeDragEnd?: (event: {
+        id: string;
+        offset: {
+            x: number;
+            y: number;
+        };
+    }) => void;
+    /** Nothing pans, drags or descends. Reading still works, including by keyboard. */
+    disabled?: boolean;
+    className?: string;
+}
+export declare function NodeCanvas<Extra = unknown>({ graph, groups, label, renderNode, renderSummary, edgeClassName, orientation, nodeWidth, nodeHeight, height, expandedGroupId, defaultExpandedGroupId, onExpandedGroupIdChange, onNodeClick, onNodeDragEnd, disabled, className, }: NodeCanvasProps<Extra>): import("react").JSX.Element;

package/dist/types/components/node-canvas/index.d.ts

@@ -0,0 +1,3 @@
+export { NodeCanvas, type NodeCanvasProps } from "./NodeCanvas";
+export { LAYOUT_DEFAULTS, edgePath, layoutGraph, neighbourhood } from "./layout";
+export type { CanvasCycleScope, CanvasEdge, CanvasGraph, CanvasGroup, CanvasLayout, CanvasNode, CanvasOrientation, CanvasPlacedEdge, CanvasScope, LayoutOptions, NodeRenderContext, NodeRenderer, PlacedNode, } from "./types";

package/dist/types/components/node-canvas/layout.d.ts

@@ -0,0 +1,29 @@
+import type { CanvasGraph, CanvasGroup, CanvasLayout, CanvasPlacedEdge, CanvasScope, LayoutOptions } from "./types";
+export declare const LAYOUT_DEFAULTS: Required<LayoutOptions>;
+/**
+ * Lay out one scope of a graph.
+ *
+ * `scope` is `null` for the top level, a `CanvasGroup.id` to draw that
+ * group's own members, or a `CanvasCycleScope` to draw a condensed cycle's
+ * own members (see that type's doc for why it is not just "another group
+ * id" — it skips this function's own condensing pre-pass on purpose).
+ * Coordinates are plane-local and start at 0 on both axes: the caller
+ * decides where the plane sits and how much padding surrounds it.
+ */
+export declare function layoutGraph<Extra>(graph: CanvasGraph<Extra>, groups: readonly CanvasGroup[], scope: CanvasScope, options?: LayoutOptions): CanvasLayout<Extra>;
+/** The SVG `d` attribute for one drawn edge. See `smoothPath` above. */
+export declare function edgePath(edge: CanvasPlacedEdge): string;
+/**
+ * Every real node id reachable from `id` within `hops` steps, along either
+ * edge direction — the "1–2-hop neighbourhood" `NodeRenderContext.focusDistance`
+ * reports. Undirected on purpose: a node's neighbourhood, for the purpose of
+ * "what should stay legible while I'm reading this one", is what points at it
+ * as much as what it points at.
+ *
+ * Keyed by the drawn (possibly condensed) ids, not raw graph node ids — the
+ * canvas calls this with whatever `CanvasPlacedEdge` already uses.
+ */
+export declare function neighbourhood(id: string, edges: readonly {
+    from: string;
+    to: string;
+}[], hops: number): Map<string, number>;