nimbus-docs 0.1.6 → 0.1.7

package/dist/react.d.ts

@@ -0,0 +1,205 @@
+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): any;
+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;
+  toggle: () => void;
+}
+declare class DiagramRegistry {
+  private entries;
+  private listeners;
+  /** Bumped on every membership change — useSyncExternalStore snapshot key. */
+  private version;
+  register(entry: RegistryEntry): () => void;
+  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>> 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;
+}
+interface UsePhaseOptions<C extends Record<string, unknown> = Record<string, never>> {
+  steps: UsePhaseStep<C>[];
+  /** Values made available to each step's `when` predicate. */
+  context?: C;
+  /** When true (default), the sequence restarts after the last step. */
+  loop?: boolean;
+}
+interface UsePhaseReturn {
+  /** Id of the currently-active step. Empty string if `steps` is empty. */
+  current: string;
+  /** Index into the *filtered* sequence for the current cycle. */
+  index: number;
+  /** How many times the sequence has fully completed. Starts at 0. */
+  cycle: number;
+  /** 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. */
+  goto: (id: string) => void;
+  /** Reset cycle and index to 0. */
+  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. Mode toggles, branches, alternating loops — anything
+ * cycle-dependent — composes via the predicate plus user-supplied
+ * `context`.
+ */
+declare function usePhase<C extends Record<string, unknown> = Record<string, never>>({
+  steps,
+  context,
+  loop
+}: UsePhaseOptions<C>): UsePhaseReturn;
+//#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.). Subsumes momito's
+ * `useWeldedMeasure` pattern.
+ *
+ * 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/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 ReducedMotionMode, type UseMeasureOptions, type UsePhaseOptions, type UsePhaseReturn, type UsePhaseStep, type UseTabIndicatorReturn, cn, diagramRegistry, useDiagram, useDiagramOrDefault, useMeasure, usePhase, 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/cn.ts"],"mappings":";;;;KAuBY,KAAA;AAAA,KACA,iBAAA;AAAA,KACA,YAAA;AAAA,UAEK,mBAAA;EAJA;EAMf,EAAA;EANe;EAQf,KAAA,EAAO,YAAA;EAPG;EASV,OAAA;;EAEA,OAAA;EAX2B;EAa3B,UAAA;EAZsB;EActB,aAAA;EAdsB;EAgBtB,KAAA,EAAO,KAAA;EAdQ;EAgBf,KAAA;IAAS,EAAA;EAAA;EAdT;EAgBA,KAAA;EAdO;EAgBP,MAAA;AAAA;AAAA,iBA6Dc,UAAA,CAAA,GAAc,mBAAA;;;;;;iBAwBd,mBAAA,CAAoB,QAAA,WAAmB,mBAAA;AAAA,UAkCtC,YAAA;EACf,QAAA,EAAU,SAAA;EACV,QAAA;EACA,kBAAA;EACA,aAAA,GAAgB,iBAAA;;EAEhB,SAAA;EAhE+C;EAkE/C,aAAA;EA1CiC;EA4CjC,QAAA;EA5CkC;EA8ClC,KAAA;EACA,SAAA;AAAA;AAAA,iBA0FO,WAAA,CAAY,KAAA,EAAO,YAAA;AAAA,cAuMf,OAAA,SAAO,WAAA;;;;;;;AA7bpB;;;;;AACA;UCbU,aAAA;EACR,EAAA;EACA,MAAA;AAAA;AAAA,cAGI,eAAA;EAAA,QACI,OAAA;EAAA,QACA,SAAA;EDOc;EAAA,QCLd,OAAA;EAER,QAAA,CAAS,KAAA,EAAO,aAAA;EAWhB,SAAA,CAAA;EAOA,KAAA;EAEA,UAAA;EAEA,SAAA,GAAa,QAAA;EAAA,QAOL,MAAA;AAAA;AAAA,cAKG,eAAA,EAAe,eAAA;;;UCnDX,gBAAA;;EAEf,EAAA;;EAEA,IAAA;AAAA;AAAA,UAGe,YAAA,WAAuB,MAAA,oBAA0B,MAAA,yBACxD,gBAAA;EFUO;;AACjB;;;;EEJE,IAAA,IAAQ,GAAA;IAAO,KAAA;IAAe,OAAA;EAAA,IAAoB,CAAA;AAAA;AAAA,UAGnC,eAAA,WAA0B,MAAA,oBAA0B,MAAA;EACnE,KAAA,EAAO,YAAA,CAAa,CAAA;EFGc;EEDlC,OAAA,GAAU,CAAA;EFeE;EEbZ,IAAA;AAAA;AAAA,UAGe,cAAA;EFEf;EEAA,OAAA;EFIA;EEFA,KAAA;EFMA;EEJA,KAAA;EFMA;EEJA,OAAA;EFMA;EEJA,IAAA,GAAO,EAAA;EFMD;EEJN,KAAA;AAAA;;;;;AFyFF;;;;;AAkCA;iBE9GgB,QAAA,WAAmB,MAAA,oBAA0B,MAAA,gBAAA,CAAA;EAC3D,KAAA;EACA,OAAA;EACA;AAAA,GACC,eAAA,CAAgB,CAAA,IAAK,cAAA;;;UClDP,iBAAA;;;AHajB;;;;;EGLE,IAAA;AAAA;;;;AHOF;;;;;AAEA;;;;;;iBGQgB,UAAA,WAAqB,WAAA,GAAc,UAAA,MAAgB,eAAA,CAAA,CACjE,GAAA,EAAK,SAAA,CAAU,CAAA,UACf,QAAA,IAAY,EAAA,EAAI,CAAA,EAAG,IAAA,EAAM,eAAA,KAAoB,CAAA,EAC7C,OAAA,GAAS,iBAAA;EACN,IAAA,EAAM,eAAA;EAAwB,QAAA,EAAU,CAAA;AAAA;;;UC7B5B,qBAAA;;EAEf,KAAA;IAAS,GAAA;IAAa,IAAA;IAAc,KAAA;IAAe,MAAA;EAAA;AAAA;;;;;AJarD;;;;;AAEA;;;iBIAgB,eAAA,CACd,YAAA,EAAc,SAAA,CAAU,WAAA,UACxB,MAAA,GAAS,EAAA,aAAe,WAAA,SACxB,QAAA,kBACC,qBAAA;;;;;;AJRH;;iBKfgB,EAAA,CAAA,GAAM,MAAA,EAAQ,UAAA"}