@danxbot/ui 13.0.1 → 13.0.3

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

@@ -26,10 +26,17 @@ export interface GraphExplorerProps<Extra = unknown> {
     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, disabled, className, }: GraphExplorerProps<Extra>): import("react").JSX.Element;
+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

@@ -55,3 +55,55 @@ export interface FitOptions extends ScaleBounds {
 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;
+/**
+ * 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

@@ -1,5 +1,5 @@
 export { GraphExplorer, type GraphExplorerProps } from "./GraphExplorer";
 export { frameBoxFor, layoutExplorerTree, neighbourhoodTree, edgePath } from "./tree-layout";
-export { CAMERA_DEFAULTS, centerOn, clampScale, fitBox, toContentPoint, toScreenPoint, unionBox, zoomAtPoint } from "./camera-math";
-export type { Box, CameraState, FitOptions, Point, ScaleBounds, Size } from "./camera-math";
+export { CAMERA_DEFAULTS, centerOn, clampScale, fitBox, fitBoxWithFloor, 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

@@ -26,14 +26,31 @@ export { edgePath };
 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, its parent (one rank up) and every one of its direct children (one
- * rank down) — "the minimap always frames the current node, its parent and
- * its children" (DX-3401's fix for the minimap shrinking an entire tree to
+ * 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;
 /**

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

@@ -1,4 +1,4 @@
-import { type Box, type CameraState } from "./camera-math";
+import { type Box, type CameraState, type FrameOverflow } from "./camera-math";
 export interface CameraClickEvent {
     /** Client coordinates, for the caller to hit-test against its own elements. */
     target: HTMLElement;
@@ -29,6 +29,27 @@ export interface UseCameraOptions {
         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`. */
@@ -44,6 +65,14 @@ export interface UseCameraResult {
     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: HTMLDivElement | null) => void;
     zoomIn: () => void;
     zoomOut: () => void;

package/dist/types/index.d.ts

@@ -129,7 +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, frameBoxFor, layoutExplorerTree, neighbourhoodTree, CAMERA_DEFAULTS, centerOn, clampScale, fitBox, toContentPoint, toScreenPoint, unionBox, 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 { GraphExplorer, frameBoxFor, layoutExplorerTree, neighbourhoodTree, CAMERA_DEFAULTS, centerOn, clampScale, fitBox, fitBoxWithFloor, toContentPoint, toScreenPoint, unionBox, zoomAtPoint, type GraphExplorerProps, type Box, type CameraState, type FitOptions, type FitWithFloorOptions, type FitWithFloorResult, type FrameOverflow, 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": "13.0.1",
+  "version": "13.0.3",
   "type": "module",
   "description": "Danxbot — a domain-agnostic React design system with motion as a first-class primitive.",
   "license": "MIT",