@50arms/ui 0.0.0-stage → 35.2.0

package/dist/types/components/file-viewer/types.d.ts

@@ -0,0 +1,70 @@
+import type { ReactNode } from "react";
+import type { ChatFile } from "../chat/types";
+/** One already-rendered page image of a multi-page document. */
+export interface ViewerPage {
+    /** Stable identity: the consumer's own id for the page, never an index. */
+    id: string;
+    /** The full-size rendered page image. */
+    url: string;
+    /** A smaller render for the rail. Falls back to `url`. */
+    thumbUrl?: string | null;
+    /** The number as printed in the document. Null or absent when none was recorded. */
+    number?: number | null;
+    /** Draw this page as one of the ones worth looking at (see `markLabel`). */
+    marked?: boolean;
+}
+/** A file the viewer can show. Every ChatFile is a valid ViewerFile. */
+export interface ViewerFile extends ChatFile {
+    /**
+     * Already-rendered page images, in document order. One or more entries make
+     * the file a paged document: one frame per page. Absent or empty: the file is
+     * ONE frame, shown by kind (image, video, anything else).
+     */
+    pages?: ViewerPage[];
+}
+/** What is on the stage. Handed to every render slot and to `onFrameChange`. */
+export interface ViewerFrame {
+    file: ViewerFile;
+    /** The page of `file` on the stage; null when `file` has no pages. */
+    page: ViewerPage | null;
+    /** Zero-based position among all frames. */
+    index: number;
+    /** How many frames there are. */
+    total: number;
+}
+export interface FileViewerProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** Every file the reader may step through, in order. */
+    files: ViewerFile[];
+    /**
+     * Where to open. Read each time `open` turns true, never afterwards: the
+     * frame whose page id is `initialPageId` (inside `initialFileId` when given),
+     * else the first marked frame (inside `initialFileId` when given), else the
+     * first frame (of `initialFileId` when given).
+     */
+    initialFileId?: string | null;
+    initialPageId?: string | null;
+    /** Told when the frame on the stage changes. Observes; the viewer owns the position. */
+    onFrameChange?: (frame: ViewerFrame) => void;
+    /** The heading. Defaults to the current file's name. */
+    title?: ReactNode;
+    /** A quieter second line. Defaults to the current file's size, when known. */
+    subtitle?: ReactNode;
+    /** Offers Download for the current file. Omitted: no Download anywhere. */
+    onDownload?: (file: ViewerFile) => void;
+    /** What a mark means, as an adjective: "cited", "flagged". Default "marked". */
+    markLabel?: string;
+    /**
+     * The host's own header controls for the current frame. Mounted in exactly one
+     * place: inline from `lg` up, inside the overflow popover below it. A control
+     * with its own state therefore remounts, and starts over, when the layout
+     * crosses `lg` or the overflow popover closes: state a host needs to keep
+     * belongs above the viewer.
+     */
+    headerActions?: (frame: ViewerFrame) => ReactNode;
+    /** A host panel floating over the stage for the current frame (gpt-manager's quote panel). */
+    overlay?: (frame: ViewerFrame) => ReactNode;
+    /** Replaces the built-in stage for a file without pages. Null or undefined keeps the built-in. */
+    renderBody?: (file: ViewerFile) => ReactNode;
+}

package/dist/types/components/file-viewer/use-frame-cursor.d.ts

@@ -0,0 +1,13 @@
+import type { ViewerFile, ViewerFrame } from "./types";
+export interface UseFrameCursorOptions {
+    open: boolean;
+    files: ViewerFile[];
+    initialFileId?: string | null;
+    initialPageId?: string | null;
+    onFrameChange?: (frame: ViewerFrame) => void;
+}
+export declare function useFrameCursor({ open, files, initialFileId, initialPageId, onFrameChange }: UseFrameCursorOptions): {
+    frames: ViewerFrame[];
+    frame: ViewerFrame | null;
+    go: (next: number) => void;
+};

package/dist/types/components/file-viewer/use-viewer-keys.d.ts

@@ -0,0 +1,24 @@
+export interface ViewerKeyActions {
+    go: (index: number) => void;
+    index: number;
+    total: number;
+    /** Null when the frame is not zoomable: the zoom keys are then not handled. */
+    zoom: {
+        zoomIn: () => void;
+        zoomOut: () => void;
+        reset: () => void;
+    } | null;
+}
+/**
+ * The viewer's keyboard (DX-4398): Arrow, PageUp/PageDown, Home and End step
+ * frames; `+`, `-` and `0` zoom. Returns the callback ref for the Dialog popup.
+ *
+ * A NATIVE listener on the popup element, not a document one and not a React
+ * `onKeyDown`: Base UI's popup stops propagation of the arrow, Home, End and Page
+ * keys (they belong to composite widgets), so by the time a key reached
+ * `document` it was gone. On the popup itself it runs first. It only ever sees
+ * keys aimed at the viewer's own DOM: a key inside a portalled Popover (the
+ * overflow menu) has a target outside the popup, so it never gets here. Escape is
+ * not handled: it is the Dialog's.
+ */
+export declare function useViewerKeys(actions: ViewerKeyActions): import("react").Dispatch<import("react").SetStateAction<HTMLDivElement | null>>;

package/dist/types/components/file-viewer/use-viewer-zoom.d.ts

@@ -0,0 +1,29 @@
+import { type CameraState, type ScaleBounds, type Size } from "../graph-explorer/camera-math";
+/** The zoom range of the viewer: far enough out to see a wide page whole, far
+    enough in to read a signature. */
+export declare const VIEWER_ZOOM_BOUNDS: ScaleBounds;
+export type ViewerFit = "width" | "contain";
+export interface UseViewerZoomOptions {
+    /** Changing this is a different frame: refit. */
+    frameKey: string;
+    /** How the frame opens. Null: the frame is not zoomable (video, a plain file). */
+    fit: ViewerFit | null;
+}
+export declare function useViewerZoom({ frameKey, fit }: UseViewerZoomOptions): {
+    camera: CameraState;
+    /** Whole-number percent, null until the frame has been measured. */
+    percent: number | null;
+    measured: boolean;
+    atFit: boolean;
+    canToggle: boolean;
+    panning: boolean;
+    bindViewport: (node: HTMLElement | null) => (() => void) | undefined;
+    setContentSize: (next: Size) => void;
+    zoomIn: () => void;
+    zoomOut: () => void;
+    reset: () => void;
+    toggleActual: (point?: {
+        x: number;
+        y: number;
+    }) => void;
+};

package/dist/types/components/focus-web/FocusWeb.d.ts

@@ -0,0 +1,3 @@
+import type { FocusWebProps } from "./types";
+export type { FocusWebProps } from "./types";
+export declare function FocusWeb<Extra = unknown>({ center, ring, parent, onSelect, onUp, selectedId, onSelectCenter, renderNode, label, className, }: FocusWebProps<Extra>): import("react").JSX.Element;

package/dist/types/components/focus-web/index.d.ts

@@ -0,0 +1,4 @@
+export { FocusWeb } from "./FocusWeb";
+export { CENTER_POSITION, PARENT_POSITION, WIDE_RING_THRESHOLD, layoutRing } from "./layout";
+export type { PlacedRingNode } from "./layout";
+export type { FocusNodeRenderContext, FocusNodeRenderer, FocusNodeRole, FocusWebNode, FocusWebNodeLook, FocusWebProps, } from "./types";

package/dist/types/components/focus-web/layout.d.ts

@@ -0,0 +1,55 @@
+/** Ids at or below this count get ONE ring; more get two concentric ones. */
+export declare const WIDE_RING_THRESHOLD = 10;
+/** Fixed corner slot for the "up" affordance, never part of the ring itself.
+    DX-3451: this is the slot's LEFT edge (the parent node is anchored by its
+    left side, not its centre — FocusWeb.tsx), so a long parent title grows
+    rightward into the plane instead of hanging off the left edge the way the
+    legacy page's centre-anchored `left: 7%` button did. */
+export declare const PARENT_POSITION: {
+    leftPct: number;
+    topPct: number;
+};
+export declare const CENTER_POSITION: {
+    leftPct: number;
+    topPct: number;
+};
+export interface PlacedRingNode {
+    id: string;
+    leftPct: number;
+    topPct: number;
+    /** Which concentric ring this sits on. `0` (outer) for every node while the
+        ring is at or below `WIDE_RING_THRESHOLD`. */
+    tier: 0 | 1;
+}
+/**
+ * Places `ids` (already in the caller's desired order — see `types.ts`'s
+ * module doc) evenly around the centre: one ring at or below `threshold`,
+ * otherwise the same even angles with the radius alternating outer/inner.
+ * Pure and total: an empty array places nothing, and the result is always
+ * the same length as `ids`, in the SAME order, so a caller can zip it back
+ * against its own node array by index without a lookup.
+ */
+export declare function layoutRing(ids: readonly string[], threshold?: number): PlacedRingNode[];
+/** One slot's measured vertical box, for `labelOverhang`. `height` is the slot body's own layout height (disc plus
+    label), `disc` the disc's diameter: both in px, both read untransformed so a glide in flight cannot skew them. */
+export interface SlotBox {
+    topPct: number;
+    height: number;
+    disc: number;
+    placement: "above" | "below" | "beside";
+    /** A caller's own body: centred whole on its point (see `slotTranslate` in FocusWeb.tsx). */
+    custom: boolean;
+}
+/**
+ * DX-4219: how far the slots' boxes run above and below the plane's own `planeHeight`-px box. The plane is a fixed
+ * aspect ratio and the ring sits at fixed percentages of it, so a top node's label (it grows UP from its disc) or a
+ * bottom node's (it grows DOWN) leaves the plane by however many lines it wraps to — into whatever sits above or
+ * below the web. The component pads the web by exactly this, so every label sits inside the web's own area.
+ *
+ * The vertical placement mirrors `slotTranslate` in FocusWeb.tsx: that function is the one place the slot's
+ * `translate` is decided, and this is its arithmetic on measured sizes.
+ */
+export declare function labelOverhang(boxes: readonly SlotBox[], planeHeight: number): {
+    top: number;
+    bottom: number;
+};

package/dist/types/components/focus-web/types.d.ts

@@ -0,0 +1,131 @@
+import type { ReactNode } from "react";
+import type { IconName } from "../Icon";
+import type { CanvasNode } from "../node-canvas/types";
+/**
+ * DX-3451: the two optional LOOK fields the default node body draws — an
+ * icon in the disc, and a colour identity. Both are optional because a
+ * consumer with a `renderNode` of its own never needs either.
+ */
+export interface FocusWebNodeLook {
+    /** Drawn inside the node's disc. Omitted → the label's first letter. */
+    icon?: IconName;
+    /**
+     * A key into the library's curated swatch palette (`EVENT_PALETTE` —
+     * `iris`, `aqua`, `mint`, `amber`, `rose`, `azure`, `orchid`, `slate`). Never a raw
+     * colour, for the same reason the calendar refuses one (`PaletteEntry`):
+     * every fill/text/edge pair in that palette is contrast-audited in both
+     * themes, and a caller-supplied hex is not. Omitted → the accent colour.
+     */
+    paletteKey?: string;
+    /**
+     * DX-4041: a small marker drawn at the disc's top-right corner — a count, a
+     * change tag, an unread dot — typically a `Badge` (or a few stacked). It is
+     * decoration for the eye: the default body hides it from assistive tech, so
+     * say what it MEANS in `badgeLabel`. Ignored by a custom `renderNode`, which
+     * draws whatever it likes from the node's own fields.
+     */
+    badge?: ReactNode;
+    /**
+     * What `badge` means, in words ("contains 2 added, 1 changed"). Appended to a
+     * clickable node's accessible name after its label, and read in place beside
+     * a plain (non-clickable) centre. Meaningless without `badge`.
+     */
+    badgeLabel?: string;
+}
+/**
+ * One node FocusWeb draws — the centre, a ring member, or the "up" parent.
+ * Same `Extra`-carrying shape as `CanvasNode` everywhere else in this library:
+ * a consumer's own fields come back untouched through `renderNode`.
+ */
+export type FocusWebNode<Extra = unknown> = CanvasNode<Extra> & FocusWebNodeLook;
+/** Which of the three roles a rendered node is playing this frame. */
+export type FocusNodeRole = "center" | "ring" | "parent";
+/**
+ * What `renderNode` is told about the node it is drawing — structural facts
+ * about the node's place in THIS frame's layout.
+ */
+export interface FocusNodeRenderContext {
+    role: FocusNodeRole;
+    /** 0-based position in `ring`, in the order the caller supplied. `null` for `center`/`parent`. */
+    index: number | null;
+    /** Which of the (possibly two) concentric rings this ring node sits on — see `layoutRing`. `null` off the ring. */
+    tier: 0 | 1 | null;
+    /** This ring node currently carries the roving tab stop. Always `false` for `center`/`parent`. */
+    isTabStop: boolean;
+    /**
+     * DX-3451: the pointer is over this node, or it has keyboard focus — the
+     * state the default body lights up in its own colour, and the state its
+     * spoke highlights for. Always `false` for `center`.
+     */
+    active: boolean;
+    /**
+     * DX-3451: this ring node is the caller's `selectedId` — lit in its own
+     * colour with a pill label, the way the legacy docs page showed a selected
+     * leaf beside its siblings. Always `false` off the ring.
+     */
+    selected: boolean;
+    /**
+     * DX-3451: where this node's label goes relative to its disc. A ring node
+     * in the upper half of the web puts its label ABOVE the disc, so the spoke
+     * arriving from the centre below never runs through the text; everything
+     * else puts it below, and the parent beside it. The default body follows
+     * this; a custom body should too.
+     */
+    labelPlacement: "below" | "above" | "beside";
+    /**
+     * The viewport is narrow enough (< 640px) that FocusWeb has switched to its
+     * compact layout (a taller plane and smaller bodies — "works at 375px").
+     */
+    compact: boolean;
+}
+export type FocusNodeRenderer<Extra = unknown> = (node: FocusWebNode<Extra>, context: FocusNodeRenderContext) => ReactNode;
+export interface FocusWebProps<Extra = unknown> {
+    /** The node currently centred. Controlled — FocusWeb never picks its own centre.
+        Every id across `center`, `parent` and `ring` must be unique; FocusWeb
+        throws on a repeat (see FocusWeb.tsx's module doc). */
+    center: FocusWebNode<Extra>;
+    /**
+     * The centre's one-hop neighbours, already in the exact order to draw.
+     * FocusWeb does not sort, dedupe or reorder this — see the module doc.
+     */
+    ring: readonly FocusWebNode<Extra>[];
+    /** The "up" affordance's target. `null`/`undefined` at the root — no parent, no up button. */
+    parent?: FocusWebNode<Extra> | null;
+    /**
+     * Fired when a ring node is activated (click, or Enter/Space while it
+     * carries the roving tab stop). FocusWeb does not recentre itself — the
+     * caller responds by changing `center`/`ring`/`parent`, which is what makes
+     * the nodes glide.
+     */
+    onSelect: (id: string) => void;
+    /** Fired when the "up" affordance is activated. Ignored while `parent` is absent. */
+    onUp?: () => void;
+    /**
+     * DX-3451: one ring node to show as SELECTED without recentring on it —
+     * for a leaf (a node with no children of its own), where recentring would
+     * leave a lone node in an empty web. The legacy docs page did exactly this:
+     * clicking a leaf lit it in place among its siblings, and the page below
+     * switched to it. An id not in `ring` is ignored.
+     */
+    selectedId?: string | null;
+    /**
+     * DX-3451: makes the centre itself clickable. Given only when clicking the
+     * centre has something to do — typically, while `selectedId` is set, to go
+     * back from the selected leaf to the centre's own page. Omitted, the centre
+     * is a plain labelled region, not a button that does nothing.
+     */
+    onSelectCenter?: () => void;
+    /**
+     * Custom node body. Omit for the built-in disc-and-label body (which reads
+     * `icon`/`paletteKey`). A custom body is drawn inside the same positioned,
+     * animated slot, so it glides and fans out exactly like the default one —
+     * but it lays ITSELF out (the slot is an unstyled box), should follow
+     * `labelPlacement`, and is centred on the node's point as a whole (the
+     * default body is anchored by its disc instead, because only its disc
+     * size is known).
+     */
+    renderNode?: FocusNodeRenderer<Extra>;
+    /** Accessible name for the whole widget (an `aria-label`, `role="group"`). */
+    label: string;
+    className?: string;
+}

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

@@ -0,0 +1,42 @@
+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;
+    /** Cross-axis extent of a node that does not need more, in px — the rank's OWN axis (ranks spread along y, DX-3401's vertical default) unless `orientation` is overridden. @default LAYOUT_DEFAULTS.nodeWidth */
+    nodeWidth?: number;
+    /** Along-axis extent BEFORE a taller node's own content grows it — the axis ranks advance along. @default LAYOUT_DEFAULTS.nodeHeight */
+    nodeHeight?: number;
+    /** Floor on the automatic frame-fit's scale (mount / focus change, both
+        `variant`s) — below this, the camera holds the floor and centres on the
+        focused node instead of shrinking the whole frame to fit; `fitAll`
+        stays unaffected (DX-3404). See `MIN_READABLE_TITLE_SCALE`'s own
+        comment for the derivation; override when `renderNode` uses a
+        different title font size. @default MIN_READABLE_TITLE_SCALE */
+    minReadableScale?: 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, minReadableScale, disabled, className, }: GraphExplorerProps<Extra>): import("react").JSX.Element;

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

@@ -0,0 +1,119 @@
+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;
+}
+/**
+ * The smallest box containing every one of `boxes` — how a camera "frame"
+ * (e.g. a focused node plus its parent and children, DX-3401) is built from
+ * several already-placed boxes without re-deriving a bounding-box formula at
+ * every call site. `null` for an empty list — nothing to union.
+ */
+export declare function unionBox(boxes: readonly Box[]): Box | null;
+/** A camera that fits the whole of `box` inside `viewport`, centred, padded. */
+export declare function fitBox(box: Box, viewport: Size, options?: FitOptions): CameraState;
+/**
+ * A camera that makes `content` exactly as wide as `viewport` and starts at its
+ * top (DX-4398) — how a document page is read: the width fits, the length
+ * scrolls, and the top is where a page starts. Horizontally centred, which only
+ * shows once `bounds` clamp the page narrower than the viewport. Never an
+ * unbounded scale: a 10px-wide page stops at `maxScale`, a 100000px-wide one at
+ * `minScale`. Zero-size content (an image not measured yet) is a finite 100%
+ * camera at the origin, never NaN.
+ */
+export declare function fitWidth(content: Size, viewport: Size, bounds?: ScaleBounds): CameraState;
+/**
+ * Which viewport edges have `box`'s content extending past them at `camera`'s
+ * current position/scale — the input `fitBoxWithFloor` (below) needs to
+ * report an overflow cue, factored out because a caller re-deriving it from
+ * raw camera state would be a second, easily-drifting copy of this same
+ * arithmetic (DX-3404). A small epsilon absorbs floating-point noise at an
+ * edge that lands (by construction) exactly on the viewport boundary.
+ */
+export interface FrameOverflow {
+    left: boolean;
+    right: boolean;
+    top: boolean;
+    bottom: boolean;
+}
+export interface FitWithFloorOptions extends FitOptions {
+    /**
+     * A SECOND, stricter lower bound on top of `minScale`/`fitBounds` (DX-3404)
+     * — readability-driven ("titles at least ~13px on screen"), not
+     * graph-legibility-driven the way `CAMERA_DEFAULTS.minScale` (0.15) is.
+     * `undefined` (the default) makes this behave exactly like `fitBox` — the
+     * floor is opt-in per call site, so `fitAll` (which never passes it) stays
+     * a manual control that may zoom out past readable text on purpose.
+     * When the ordinary fit-to-`box` scale would land BELOW this floor, the
+     * camera clamps to the floor and centres on `focusBox` instead of `box` —
+     * showing the focused target at a readable size and reaching the rest of
+     * `box` by panning, rather than shrinking everything to fit.
+     */
+    minReadableScale?: number;
+    /**
+     * What to centre on once `minReadableScale` clamps the scale — normally
+     * the focused node's own (small) box, not the whole (wide) `box` being
+     * framed. Defaults to `box` itself (so an omitted `focusBox` degrades to
+     * "clamp the scale but still centre the frame", never a crash).
+     */
+    focusBox?: Box;
+}
+export interface FitWithFloorResult {
+    camera: CameraState;
+    /** Which sides of `box` extend past the viewport at the returned camera's
+        scale/position — all `false` whenever the floor didn't clamp, since an
+        ordinary `fitBox` result always contains the whole of `box` by
+        construction. */
+    overflow: FrameOverflow;
+}
+/**
+ * `fitBox`, with an optional readable-text floor (DX-3404) — see
+ * `FitWithFloorOptions.minReadableScale`'s own doc for the behaviour. Used
+ * ONLY by `use-camera.ts`'s automatic frame-fit effect; `fitAll` keeps
+ * calling `fitBox` directly so the manual "fit everything" control is never
+ * affected by this floor (AC #2).
+ */
+export declare function fitBoxWithFloor(box: Box, viewport: Size, options?: FitWithFloorOptions): FitWithFloorResult;

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

@@ -0,0 +1,5 @@
+export { GraphExplorer, type GraphExplorerProps } from "./GraphExplorer";
+export { frameBoxFor, layoutExplorerTree, neighbourhoodTree, edgePath } from "./tree-layout";
+export { CAMERA_DEFAULTS, centerOn, clampScale, fitBox, fitBoxWithFloor, fitWidth, toContentPoint, toScreenPoint, unionBox, zoomAtPoint, } from "./camera-math";
+export type { Box, CameraState, FitOptions, FitWithFloorOptions, FitWithFloorResult, FrameOverflow, 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,67 @@
+import { edgePath } from "../node-canvas/layout";
+import type { LayoutOptions } from "../node-canvas/types";
+import { type Box } from "./camera-math";
+import type { CrossLink, ExplorerLayout, ExplorerTree } from "./types";
+/** Re-exported for a consumer drawing `edges`/`crossLinks` into an SVG. */
+export { edgePath };
+/**
+ * Lay out a tree, top to bottom, from a parent backbone alone. Ranked
+ * vertically (dagre `rankdir: "TB"`) so SIBLINGS spread horizontally within a
+ * rank — the sprawl DX-3401's card asks for. A tree this shallow-but-wide (a
+ * handful of levels, many children per level) stacked its siblings into one
+ * tall column under the previous `"horizontal"` (`LR`) default, which is
+ * exactly backwards for that shape: `"horizontal"` ranks left to right, so
+ * within-rank siblings stack along the CROSS axis (vertically) instead.
+ * `options.orientation` still overrides this default for a caller with the
+ * opposite shape (deep and narrow).
+ *
+ * `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 box a camera should keep in frame around `focusId`: the focused node
+ * itself and every one of its direct children (one rank down), with the
+ * frame's vertical extent alone stretched to reach its parent's rank (one
+ * rank up) — "the minimap always frames the current node, its parent and its
+ * children" (DX-3401's fix for the minimap shrinking an entire tree to
+ * specks, and for the full-screen explorer's initial view not opening
+ * focused). Computed from an ALREADY-LAID-OUT tree, so it can never disagree
+ * with what is actually on screen the way fitting a separately-computed
+ * bounding box could. `null` when `focusId` isn't laid out at all — nothing
+ * to frame (a stale id, or data still loading).
+ *
+ * THE PARENT'S X/WIDTH ARE DELIBERATELY NEVER UNIONED IN (DX-3401 follow-up).
+ * An earlier version unioned the parent's whole box in, same as a child's.
+ * dagre centres a parent horizontally over the barycenter of ALL its
+ * children, not just the focused one — so a parent with many other children
+ * spread wide (exactly the "one system, ~15 areas" shape this card exists to
+ * fix) can sit far to one side of the union of `focus` + its own children.
+ * Pulling that parent's x/width into the frame then stretches it to cover the
+ * real horizontal gap between the parent and this one child, reproducing a
+ * milder version of the original "whole tree crushed to a strip" bug for
+ * this specific shape (confirmed live against the Ringlet demo: a `frameBox`
+ * nearly as wide as the entire tree's `contentBox`). Only the parent's Y
+ * range is folded in, so the frame reaches up far enough for the connecting
+ * edge into the parent to be visible — a parent off to the side is reached by
+ * panning, the same trade-off this function already makes for siblings
+ * (drawn by `neighbourhoodTree` but never pulled into the frame's own box).
+ */
+export declare function frameBoxFor<Extra>(layout: ExplorerLayout<Extra>, focusId: string): Box | null;
+/**
+ * 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;