nimbus-docs 0.1.6 → 0.1.8

package/dist/react.d.ts

@@ -0,0 +1,350 @@
+import * as react from "react";
+import { ReactNode, RefObject } from "react";
+import { ClassValue } from "clsx";
+
+//#region src/react/diagram.d.ts
+type Depth = "intuition" | "working" | "mechanism";
+type ReducedMotionMode = "respect" | "ignore";
+type DiagramPhase = "idle" | "ready" | "playing" | "paused";
+interface DiagramContextValue {
+  /** Stable per-instance id from useId. */
+  id: string;
+  /** Derived lifecycle state. */
+  phase: DiagramPhase;
+  /** True when the diagram should be advancing animation. */
+  playing: boolean;
+  /** Element intersects the viewport (direct IntersectionObserver). */
+  visible: boolean;
+  /** Browser tab is visible (Page Visibility API). */
+  tabVisible: boolean;
+  /** Reduced-motion is in effect (OS + reducedMotion="respect" mode). */
+  reducedMotion: boolean;
+  /** Reader's depth setting. Stub until the depth dial ships. */
+  depth: Depth;
+  /** Theme tokens. Stub until row 4 wires real values. */
+  theme: {
+    id: string;
+  };
+  /** Trigger a reset — bumps the subtree key; children's useState resets. */
+  reset: () => void;
+  /** Toggle play/pause from user action. */
+  toggle: () => void;
+}
+declare function useDiagram(): DiagramContextValue | null;
+/**
+ * Returns the wrapper context, or a default + one-time dev warning when
+ * called outside a `<Diagram>`. Used by every hook in nimbus-docs/react
+ * so authors can prototype without forgetting the wrapper.
+ */
+declare function useDiagramOrDefault(hookName: string): DiagramContextValue;
+interface DiagramProps {
+  children: ReactNode;
+  fallback?: string;
+  pauseWhenOffscreen?: boolean;
+  reducedMotion?: ReducedMotionMode;
+  /** Forwarded; Astro's client:* directive dictates the actual hydration timing. */
+  hydration?: "visible" | "idle" | "load";
+  /** Wrap children in an error boundary that exposes a Reset button on render failure. Default: true. */
+  errorBoundary?: boolean;
+  /** Listen for space (toggle) / r (reset) keypresses bubbling from inside the region. Skipped when target is an interactive element. Default: true. */
+  keyboard?: boolean;
+  /** ARIA region label. */
+  label?: string;
+  className?: string;
+}
+declare function DiagramRoot(props: DiagramProps): react.JSX.Element;
+declare const Diagram: typeof DiagramRoot;
+//#endregion
+//#region src/react/registry.d.ts
+/**
+ * Page-scoped Diagram registry.
+ *
+ * Module-level singleton — shared across Astro islands because Vite
+ * de-duplicates module imports per page (both in dev HMR and in prod
+ * via shared chunks). React Context cannot bridge separate islands;
+ * a plain singleton can.
+ *
+ * Subscribed via useSyncExternalStore from <DiagramPauseAll>.
+ */
+interface RegistryEntry {
+  id: string;
+  /** Set the user-paused flag directly (idempotent). */
+  setPaused: (paused: boolean) => void;
+  /** Read the current user-paused flag at call time. */
+  userPaused: () => boolean;
+}
+declare class DiagramRegistry {
+  private entries;
+  private listeners;
+  /** Bumped on every membership change — useSyncExternalStore snapshot key. */
+  private version;
+  register(entry: RegistryEntry): () => void;
+  /**
+   * Pause everything when at least one diagram is unpaused; resume
+   * everything otherwise. A naive per-entry toggle would *invert* mixed
+   * states — resuming the diagrams a reader had deliberately paused.
+   */
+  toggleAll(): void;
+  count: () => number;
+  getVersion: () => number;
+  subscribe: (listener: () => void) => (() => void);
+  private notify;
+}
+declare const diagramRegistry: DiagramRegistry;
+//#endregion
+//#region src/react/hooks/use-phase.d.ts
+interface UsePhaseStepBase {
+  /** Stable step id; appears as `current`. */
+  id: string;
+  /** Milliseconds to hold this step before advancing. */
+  hold: number;
+}
+interface UsePhaseStep<C extends Record<string, unknown> = Record<string, never>, D = unknown> extends UsePhaseStepBase {
+  /**
+   * Predicate gate. When false, this step is skipped for the current cycle.
+   * Receives `{ cycle, current, ...context }` where `current` is the id of
+   * the previous step that survived the predicate pass (empty string at
+   * cycle start).
+   */
+  when?: (ctx: {
+    cycle: number;
+    current: string;
+  } & C) => boolean;
+  /**
+   * Arbitrary payload surfaced as `data` while this step holds — e.g.
+   * which node/edge lights up. Replaces per-card `ACTIVE_MAP` lookup
+   * tables; `data` is `null` when idle or when an autoplaying walker is
+   * frozen by reduced motion.
+   */
+  data?: D;
+}
+interface UsePhaseOptions<C extends Record<string, unknown> = Record<string, never>, D = unknown> {
+  steps: UsePhaseStep<C, D>[];
+  /** Values made available to each step's `when` predicate. */
+  context?: C;
+  /** When true (default), the sequence restarts after the last step. */
+  loop?: boolean;
+  /**
+   * When true (default) the walker runs as soon as the diagram plays.
+   * When false it starts idle (`current === ""`) and runs once per
+   * `start()` call — the shape for click-triggered one-shot sequences.
+   */
+  autoplay?: boolean;
+}
+interface UsePhaseReturn<D = unknown> {
+  /** Id of the currently-active step. Empty string when idle or `steps` is empty. */
+  current: string;
+  /** Index into the *filtered* sequence for the current cycle. */
+  index: number;
+  /** Completed passes through the sequence. Starts at 0. */
+  cycle: number;
+  /** The active step's `data` payload. `null` when idle or motion-frozen. */
+  data: D | null;
+  /** True while the walker is active. Always true when `autoplay`. */
+  running: boolean;
+  /** Begin a run from the first step. No-op while already running. */
+  start: () => void;
+  /** Advance one step (or wrap to next cycle if at the end). */
+  advance: () => void;
+  /** Jump to a named step in the current cycle's sequence. Wakes an idle walker. */
+  goto: (id: string) => void;
+  /** Reset cycle and index to 0 (and return to idle when `autoplay: false`). */
+  reset: () => void;
+}
+/**
+ * Predicate-gated phase walker. Reads `playing` / `visible` / `tabVisible`
+ * / `reducedMotion` from the surrounding `<Diagram>` and pauses
+ * automatically when any gate fails.
+ *
+ * Steps may carry a `when(ctx)` predicate that filters them out for a
+ * given cycle, and a `data` payload surfaced while the step holds. Mode
+ * toggles, branches, alternating loops — anything cycle-dependent —
+ * composes via the predicate plus user-supplied `context`.
+ *
+ * Two run modes:
+ * - `autoplay: true` (default) — ambient looping animation. Freezes under
+ *   reduced motion (`data` reads `null`).
+ * - `autoplay: false` — idle until `start()`. Started runs are
+ *   user-initiated *function*, not decoration: they keep advancing under
+ *   reduced motion (gate your CSS transition durations card-side), and a
+ *   `start()` while the page is paused arms as soon as play resumes.
+ *
+ * The scheduler depends on the current step's *values* (id, hold), not
+ * on `steps` / `context` identity — inline literals are safe and won't
+ * re-arm the hold timer under frequent re-renders.
+ */
+declare function usePhase<C extends Record<string, unknown> = Record<string, never>, D = unknown>({
+  steps,
+  context,
+  loop,
+  autoplay
+}: UsePhaseOptions<C, D>): UsePhaseReturn<D>;
+//#endregion
+//#region src/react/hooks/use-measure.d.ts
+interface UseMeasureOptions {
+  /**
+   * Additional dependencies that should re-trigger measurement when they
+   * change. Use when component state changes the layout in a way the
+   * container's ResizeObserver might miss — e.g. an animated CSS `gap`
+   * that grows the container only as the transition progresses, or a
+   * state-driven layout swap that doesn't change the container's size.
+   */
+  deps?: unknown[];
+}
+/**
+ * DOM rect + optional selector callback. The selector receives the
+ * observed element and its rect, and returns whatever derived geometry
+ * the author needs (NodeRect, EdgeData, etc.).
+ *
+ * For multi-element measurements (e.g. measuring a container plus 5
+ * child nodes), pass the container ref and read the other refs from
+ * closure inside the selector. The selector recomputes when the
+ * container resizes — which it typically does when children grow
+ * because the container's intrinsic size is content-derived. For
+ * state-driven re-layouts that the ResizeObserver might miss, pass
+ * `options.deps`.
+ */
+declare function useMeasure<T extends HTMLElement | SVGElement, R = DOMRectReadOnly>(ref: RefObject<T | null>, selector?: (el: T, rect: DOMRectReadOnly) => R, options?: UseMeasureOptions): {
+  rect: DOMRectReadOnly | null;
+  selected: R | null;
+};
+//#endregion
+//#region src/react/hooks/use-tab-indicator.d.ts
+interface UseTabIndicatorReturn {
+  /** Inline rect of the active tab, relative to the container. Null until first measure. */
+  style: {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+  } | null;
+}
+/**
+ * Headless sliding-indicator measurement for a tab group.
+ *
+ * Pure state + lifecycle — no DOM produced, no styling assumed. The
+ * consumer renders the indicator however it wants, applying `style`
+ * positionally.
+ *
+ * Re-measures on `activeId` change and on container resize. Returns
+ * `null` style when `activeId` is null or its tab ref isn't mounted —
+ * consumer renders nothing in that case, which also prevents a
+ * "mount-from-zero" transition the first time the indicator appears.
+ */
+declare function useTabIndicator(containerRef: RefObject<HTMLElement | null>, getTab: (id: string) => HTMLElement | null, activeId: string | null): UseTabIndicatorReturn;
+//#endregion
+//#region src/react/hooks/use-ref-setters.d.ts
+/**
+ * Stable per-id ref callbacks for a refs map — the ergonomic half of the
+ * "refs map + setter factory" pattern. Instead of N individual `useRef`s
+ * and N inline `ref={(el) => …}` arrows (which churn refs every render),
+ * keep one map and hand each element a cached callback:
+ *
+ * ```tsx
+ * const nodeRefs = useRef<Partial<Record<NodeId, HTMLDivElement | null>>>({});
+ * const setNode = useRefSetters(nodeRefs);
+ *
+ * <div ref={setNode("prompt")}>Prompt</div>
+ * <div ref={setNode("model")}>Model</div>
+ * ```
+ *
+ * Measurement stays caller-side (read `refs.current` inside a `useMeasure`
+ * selector) — this hook owns only the ref plumbing.
+ */
+declare function useRefSetters<K extends string, E extends Element = HTMLDivElement>(refs: RefObject<Partial<Record<K, E | null>>>): (id: K) => (el: E | null) => void;
+//#endregion
+//#region src/react/hooks/use-media-query.d.ts
+/**
+ * Reactive `window.matchMedia` subscription, SSR-safe.
+ *
+ * The server snapshot returns `defaultValue` (default `false`), so static
+ * builds render the no-match branch and hydrate without mismatch warnings;
+ * the first client render corrects it if the query matches.
+ *
+ * ```ts
+ * const isMobile = useMediaQuery("(max-width: 640px)");
+ * ```
+ */
+declare function useMediaQuery(query: string, defaultValue?: boolean): boolean;
+//#endregion
+//#region src/react/geometry.d.ts
+/**
+ * Pure edge-routing math for diagram cards. No React, no DOM — every
+ * function maps numbers to numbers (or an SVG path string). Colors,
+ * stroke widths, markers, and node outlines stay user-side.
+ */
+interface Point {
+  x: number;
+  y: number;
+}
+type RectSide = "top" | "right" | "bottom" | "left";
+/**
+ * Minimal rect shape consumed by `edgePoint`: left/top origin plus size,
+ * relative to whatever container the SVG layer is positioned against.
+ * Richer rect types (with `r`/`b`/`cx`/`cy`) are structurally compatible.
+ */
+interface EdgeRect {
+  l: number;
+  t: number;
+  w: number;
+  h: number;
+}
+/** Anchor point on a rect edge. `frac` runs 0→1 from top/left. */
+declare function edgePoint(rect: EdgeRect, side: RectSide, frac?: number): Point;
+/**
+ * - `straight` — direct line; axis-aligned lines are shortened by
+ *   `arrowOffset` at the destination so an arrowhead marker doesn't
+ *   overlap the target.
+ * - `elbow`    — one right-angle corner with a quadratic rounding,
+ *   radius clamped to half of each segment; end shortened by
+ *   `arrowOffset`.
+ * - `vSplit`   — vertical S-path through the midpoint Y (drop, run,
+ *   drop), corners rounded; no arrow offset (designed for marker-less
+ *   connectors).
+ * - `auto`     — `straight` when endpoints are axis-aligned within 2px,
+ *   else `elbow`.
+ */
+type EdgeRoute = "straight" | "elbow" | "vSplit" | "auto";
+interface RouteOptions {
+  /** End-shortening so arrowheads sit flush. Default 6. */
+  arrowOffset?: number;
+  /** Corner radius. Defaults: elbow 10, vSplit 6. */
+  radius?: number;
+}
+/** Build an SVG path string between two points using the given route. */
+declare function routeEdge(from: Point, to: Point, route?: EdgeRoute, options?: RouteOptions): string;
+/** Anchor: `[nodeId, side]` with an optional frac (default 0.5). */
+type EdgeAnchor<NodeId extends string = string> = readonly [NodeId, RectSide] | readonly [NodeId, RectSide, number];
+interface EdgeSpec<NodeId extends string = string, EdgeId extends string = string> {
+  id: EdgeId;
+  from: EdgeAnchor<NodeId>;
+  to: EdgeAnchor<NodeId>;
+  route?: EdgeRoute;
+  /** Carried through to the resolved edge for styling decisions. */
+  ghost?: boolean;
+}
+interface ResolvedEdge<EdgeId extends string = string> {
+  id: EdgeId;
+  from: Point;
+  to: Point;
+  /** Ready-to-render SVG path string. */
+  d: string;
+  ghost?: boolean;
+}
+/**
+ * Resolve declarative edge specs against a map of measured rects.
+ * Specs whose endpoints aren't in `rects` yet (unmounted nodes,
+ * first-paint gaps) are skipped rather than rendered degenerate.
+ */
+declare function resolveEdges<NodeId extends string = string, EdgeId extends string = string>(specs: readonly EdgeSpec<NodeId, EdgeId>[], rects: Partial<Record<NodeId, EdgeRect>>, options?: RouteOptions): ResolvedEdge<EdgeId>[];
+//#endregion
+//#region src/react/cn.d.ts
+/**
+ * Compose class names with Tailwind conflict resolution. Vendored into
+ * lab/diagram so the framework-surface files don't depend on apps/www's
+ * `@/lib/cn` alias — keeps the lift to `nimbus-docs/react` verbatim.
+ */
+declare function cn(...inputs: ClassValue[]): string;
+//#endregion
+export { type Depth, Diagram, type DiagramContextValue, type DiagramPhase, type DiagramProps, type EdgeAnchor, type EdgeRect, type EdgeRoute, type EdgeSpec, type Point, type RectSide, type ReducedMotionMode, type ResolvedEdge, type RouteOptions, type UseMeasureOptions, type UsePhaseOptions, type UsePhaseReturn, type UsePhaseStep, type UseTabIndicatorReturn, cn, diagramRegistry, edgePoint, resolveEdges, routeEdge, useDiagram, useDiagramOrDefault, useMeasure, useMediaQuery, usePhase, useRefSetters, useTabIndicator };
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","names":[],"sources":["../src/react/diagram.tsx","../src/react/registry.ts","../src/react/hooks/use-phase.ts","../src/react/hooks/use-measure.ts","../src/react/hooks/use-tab-indicator.ts","../src/react/hooks/use-ref-setters.ts","../src/react/hooks/use-media-query.ts","../src/react/geometry.ts","../src/react/cn.ts"],"mappings":"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"}