@sphynxoid/stepwise 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,441 @@
+import { P as PlayerEngine, a as TourStepInput, T as TourDriver, C as Chapter, S as StepTone, b as ShortcutItem } from './types-CPf9ZD_Z.js';
+export { c as PlayerEngineApi, d as PlayerEngineHandle, e as StepwiseStep, f as TourContext } from './types-CPf9ZD_Z.js';
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+interface UseStepsOptions {
+    /** Initial focus. Clamped. Defaults to 0. */
+    initialIndex?: number;
+    /** Fired whenever the focus index changes. */
+    onChange?: (index: number) => void;
+}
+interface StepsCore {
+    /** Number of steps in the sequence. */
+    count: number;
+    /** Clamped focus: 0..count-1, or -1 when the sequence is empty. */
+    index: number;
+    atStart: boolean;
+    atEnd: boolean;
+    canNext: boolean;
+    canPrev: boolean;
+    /** Clamped jump. No-op on an empty sequence. */
+    go: (index: number) => void;
+    /** Clamped forward step. */
+    next: () => void;
+    /** Clamped backward step. */
+    prev: () => void;
+    /** Jump to the first step. */
+    first: () => void;
+}
+/**
+ * The core primitive every stepwise machine composes: a clamped cursor over an
+ * ordered sequence. Frames in a trace, chapters in a lesson, lessons in a
+ * notebook, and tour steps are all the same thing at this layer — timers,
+ * effects, and scroll-tracking are policies layered on top by consumers.
+ *
+ * All callbacks are referentially stable; `count` may change dynamically (a
+ * new timeline, a mounted window) and the cursor re-clamps automatically.
+ */
+declare function useSteps<T>(items: readonly T[] | number, opts?: UseStepsOptions): StepsCore;
+
+interface StepPlayerOptions {
+    /** Number of frames in the current timeline (0 = no timeline loaded). */
+    total: number;
+    /** Delay per frame at 1× speed (built-in timer engine). */
+    baseDelayMs?: number;
+    /** Start playing immediately (used when a timeline exists on first render). */
+    autoPlay?: boolean;
+    /**
+     * Alternate frame source (GSAP timeline, scroll progress, …). Replaces the
+     * built-in timer. Memoize the engine per timeline — identity changes
+     * reconnect it.
+     */
+    engine?: PlayerEngine;
+    /**
+     * Deep-link the current frame into the URL hash (`#<key>=<index>`), opt-in.
+     * The initial hash is honored once on mount.
+     */
+    syncHash?: string;
+    /**
+     * Fired once when playback runs to the final frame on its own (built-in
+     * timer or engine `onEnd`). Cleared by any cursor movement (seek/step/
+     * reset/new timeline) — the next full playthrough fires it again.
+     */
+    onEnd?: () => void;
+}
+interface StepPlayer {
+    /** Total frames in the current timeline. */
+    total: number;
+    /** Raw frame counter; -1 means "no timeline / before first frame". */
+    frame: number;
+    /** Frame clamped into [0, total-1]; -1 when there is nothing to show. */
+    index: number;
+    playing: boolean;
+    speed: number;
+    /** Position flag: the cursor is parked on the final frame (seek counts too). */
+    atEnd: boolean;
+    /**
+     * Completion state: playback ran to the final frame on its own and nothing
+     * has moved the cursor since. Unlike `atEnd`, a seek to the last frame does
+     * not set it — `toggle()` at `ended` replays from frame 0.
+     */
+    ended: boolean;
+    /** Jump to frame 0 and play. */
+    start: () => void;
+    /** Clear the player (frame = -1, paused). */
+    reset: () => void;
+    seek: (frame: number) => void;
+    /** Step forward; pauses first. `onEmpty` fires when there is no timeline. */
+    next: (onEmpty?: () => void) => void;
+    /** Step backward; pauses first. */
+    prev: () => void;
+    /** Play/pause; replays from 0 at the end. `onEmpty` fires when there is no timeline. */
+    toggle: (onEmpty?: () => void) => void;
+    setPlaying: (playing: boolean) => void;
+    setSpeed: (speed: number) => void;
+}
+declare function useStepPlayer({ total, baseDelayMs, autoPlay, engine, syncHash, onEnd }: StepPlayerOptions): StepPlayer;
+
+interface GuidedTour {
+    /** Active step index, or null when the tour is not running. */
+    index: number | null;
+    current: TourStepInput | null;
+    active: boolean;
+    /**
+     * True while the active step's `gate` returns false: `next()` is a no-op
+     * until the gate opens. Present the `blocked` state (disable Next, pulse
+     * the waitHint) so the user knows what is being waited on.
+     */
+    blocked: boolean;
+    start: () => void;
+    end: () => void;
+    next: () => void;
+    back: () => void;
+    goto: (index: number) => void;
+    /** Jump to the step with this id. No-op when the id is unknown. */
+    gotoId: (id: string) => void;
+}
+interface GuidedTourOptions {
+    /**
+     * Alternate presenter (driver.js, Shepherd, …). When set, the hook drives it
+     * imperatively — show/hide per step, with transition controls wired — and
+     * the app should not render the built-in TourSpotlight/TourCard. Without a
+     * driver, the app renders the built-in presentation itself.
+     */
+    driver?: TourDriver;
+}
+/**
+ * Tour state whose steps are effects over app state: `onEnter` fires whenever
+ * the active step changes, reading the latest `steps` via ref so closures stay
+ * fresh without re-triggering the effect on every render. Composed on
+ * useSteps — a tour is a step sequence whose `next` past the end exits.
+ *
+ * On top of the linear cursor, steps may declare `when` (skip on arrival),
+ * `gate` (block `next` until true), and `next` (edge override by step id) —
+ * a small state machine where states are steps, edges are `next` functions,
+ * and guards are gates. The cursor itself stays a cursor: skipped steps are
+ * never landed on, and skipped/gated behavior is evaluated at transition
+ * time, not on every render.
+ */
+declare function useGuidedTour(steps: TourStepInput[], opts?: GuidedTourOptions): GuidedTour;
+
+interface FlatChapter {
+    chapter: Chapter;
+    depth: number;
+    /** Index of this entry's top-level ancestor within the flat list (itself at depth 0). */
+    rootIndex: number;
+    /** Index of the immediate parent within the flat list; -1 at depth 0. */
+    parentIndex: number;
+}
+/** Depth-first flattening — reading order for prev/next and scroll tracking. */
+declare function flattenChapters(chapters: Chapter[], depth?: number): FlatChapter[];
+
+interface ChaptersApi {
+    /** Index of the chapter currently in view (flattened order). */
+    active: number;
+    goTo: (index: number) => void;
+    next: () => void;
+    prev: () => void;
+}
+
+/**
+ * Scroll-tracked chapter navigation for multi-section pages. Active = the
+ * section containing the viewport center: a chapter becomes active when it
+ * reaches the middle of the screen, not the moment its top scrolls past an
+ * offset. Sections are resolved by DOM id; give each section CSS scroll-mt
+ * so `goTo`'s scrollIntoView clears any sticky header. Composed on useSteps —
+ * the scroll position is an external input driving the cursor.
+ */
+declare function useChapters(chapters: Chapter[]): ChaptersApi;
+
+type KeyMap = Record<string, (e: KeyboardEvent) => void>;
+interface GlobalKeysOptions {
+    /** Element tags that swallow keys (except Escape). Defaults to form controls and buttons. */
+    ignoreTags?: string[];
+    /** Gate: bindings fire only while enabled. Boolean or function — checked per event. */
+    enabled?: boolean | (() => boolean);
+}
+/**
+ * Bind global keyboard shortcuts. Keys are matched against `event.key`
+ * (exact first, then lowercase). Handlers fire with preventDefault applied;
+ * Escape always fires, even from ignored targets, and is never prevented.
+ */
+declare function useGlobalKeys(map: KeyMap, opts?: GlobalKeysOptions): void;
+
+interface DiscoveryStore {
+    /** All discovered ids (best-effort; corrupted/absent storage reads as empty). */
+    read(): string[];
+    /** Persist the full set (write-through, not a delta). */
+    write(ids: string[]): void;
+}
+/** localStorage-backed store — the default. Survives reloads, per-browser. */
+declare function localStorageStore(key?: string): DiscoveryStore;
+/**
+ * Cookie-backed store — only when the SERVER must know during SSR (e.g. to
+ * render "NEW" badges without a hydration flash). Costs request bytes; prefer
+ * localStorage otherwise. Values are JSON-encoded and URI-escaped.
+ */
+declare function cookieStore(key?: string): DiscoveryStore;
+/** In-memory store — tests, storybook, SSR fallbacks, "always show" previews. */
+declare function memoryStore(seed?: string[]): DiscoveryStore;
+interface DiscoveriesOptions {
+    /**
+     * Storage seam. Defaults to localStorage. Swap in cookieStore when SSR
+     * markup must know, or your own store (backend sync for cross-device).
+     */
+    store?: DiscoveryStore;
+    /** Storage key used by the built-in stores. */
+    key?: string;
+}
+interface Discoveries {
+    /** Discovered ids. Empty until hydration — gate triggers on `ready`. */
+    discovered: Set<string>;
+    /** False during SSR and before the first client hydration pass. */
+    ready: boolean;
+    /** Ref-backed check for event handlers; prefer `discovered.has` in render. */
+    isDiscovered: (id: string) => boolean;
+    /** Record ids as discovered and persist the merged set. */
+    markDiscovered: (id: string | string[]) => void;
+    /** Forget everything (debug / "show me the tour again"). */
+    reset: () => void;
+}
+/**
+ * A persisted set of discovered ids, hydrated after mount (SSR-safe: the
+ * server renders the undiscovered state, the client corrects it in an
+ * effect — same pattern as usePrefersReducedMotion). Compose with
+ * useGuidedTour: `pending = features.filter(f => !discovered.has(f.id))`,
+ * auto-start the first pending tour, `markDiscovered` on completion.
+ */
+declare function useDiscoveries(opts?: DiscoveriesOptions): Discoveries;
+
+/**
+ * Traps Tab focus inside `ref.current` while `active`, focuses the container
+ * on activation, and restores the previously focused element on release.
+ * Returns a ref to attach to the focusable container (tabIndex={-1}).
+ */
+declare function useFocusTrap(active: boolean): react.RefObject<HTMLDivElement | null>;
+
+/**
+ * True when the user asks the OS to reduce motion. Consumers should disable
+ * transitions, smooth scrolls, and entry animations when this is true.
+ * SSR-safe: false on the server, corrected after mount.
+ */
+declare function usePrefersReducedMotion(): boolean;
+
+interface StepwiseTheme {
+    /** Timeline-segment styling per tone. */
+    toneSegment: Record<StepTone, string>;
+    /** Step-kind chip styling per tone. */
+    toneChip: Record<StepTone, string>;
+    /** Shared structural classes for internal buttons. */
+    buttonBase: string;
+    /** Per-variant appearance for internal buttons. */
+    buttonVariants: Record<"ghost" | "outline" | "primary", string>;
+    /**
+     * Panel chrome for nav bars, cards, dialogs, and tooltip popovers.
+     * Components pass their own border/background overrides after this token,
+     * so it stays a base, not a contract.
+     */
+    surface: string;
+    /** Full-screen dimmed backdrop behind modal surfaces. */
+    overlay: string;
+    /** Code block frame — its own background, border, and type scale. */
+    codeBlock: string;
+    /** Comment / dimmed lines inside the code block. */
+    codeMuted: string;
+    /** Keyboard chip (ShortcutsDialog). */
+    kbd: string;
+    /** Ring + rounding around the tour spotlight target. */
+    spotlight: string;
+    /** Dimmed meta text — counters, hints, empty states. */
+    muted: string;
+}
+declare const defaultTheme: StepwiseTheme;
+
+interface GlossaryEntry {
+    id: string;
+    /** Display name, shown as the tooltip's heading. */
+    term: string;
+    /** Body — may embed <Term> references for nested tooltips. */
+    definition: ReactNode;
+}
+declare function GlossaryProvider({ entries, theme, children, }: {
+    entries: GlossaryEntry[];
+    /** Styling for tooltip cards (see StepwiseTheme). */
+    theme?: StepwiseTheme;
+    children: ReactNode;
+}): react.JSX.Element;
+declare function Term({ id, children, className }: {
+    id: string;
+    children?: ReactNode;
+    className?: string;
+}): react.JSX.Element;
+/**
+ * The glossary appendix: every entry rendered as an anchored row, placed
+ * after the last chapter. Entries default to the provider's declarations —
+ * define them once and the appendix follows automatically; pass `entries`
+ * explicitly to override or to render without a provider. Inside it, <Term>
+ * references resolve to in-page anchor links instead of tooltips.
+ *
+ * Customization hooks: `intro`/`footer` render arbitrary nodes around the
+ * grid, `renderEntry` replaces the whole row renderer, `className` and
+ * `entryClassName` style the section and each row. Opt out of the appendix
+ * entirely by not rendering it.
+ */
+declare function GlossaryAppendix({ entries, title, intro, footer, columns, bare, className, entryClassName, renderEntry, }: {
+    /** Override the row list; defaults to the provider's entries. */
+    entries?: GlossaryEntry[];
+    title?: string;
+    /** Rendered between the title and the grid — an introduction, usage notes, scope, … */
+    intro?: ReactNode;
+    /** Rendered after the grid. */
+    footer?: ReactNode;
+    columns?: 1 | 2;
+    /** Omit the section chrome (title/border) — the host provides its own. */
+    bare?: boolean;
+    className?: string;
+    entryClassName?: string;
+    /** Replace the default row renderer entirely. */
+    renderEntry?: (entry: GlossaryEntry) => ReactNode;
+}): react.JSX.Element | null;
+
+declare const TONE_SEGMENT_CLASS: Record<StepTone, string>;
+declare const TONE_CHIP_CLASS: Record<StepTone, string>;
+declare function CodeBlock({ lines, theme, className, }: {
+    lines: string[];
+    theme?: StepwiseTheme;
+    className?: string;
+}): react.JSX.Element;
+interface ScrubberLabels {
+    /** aria-label for the slider. */
+    scrubber?: string;
+    /** aria-valuetext for the current position. Receives the frame index. */
+    frame?: (i: number) => string;
+}
+declare function StepScrubber({ count, index, toneAt, titleAt, onSeek, emptyHint, className, theme, labels, groupOf, }: {
+    count: number;
+    index: number;
+    toneAt?: (i: number) => StepTone;
+    titleAt?: (i: number) => string;
+    onSeek: (i: number) => void;
+    emptyHint?: string;
+    className?: string;
+    theme?: StepwiseTheme;
+    labels?: ScrubberLabels;
+    /**
+     * Groups consecutive segments into one proportional wrapper — a chapter
+     * with sub-chapters spans the width of its whole subtree and only the
+     * active inner segment fills, so a chapter reads as "halfway" while its
+     * children play. Segments must be group-contiguous (flattenChapters order).
+     */
+    groupOf?: (i: number) => number;
+}): react.JSX.Element;
+declare function PlayerBar({ player, toneAt, titleAt, leading, onEmpty, emptyHint, className, theme, groupOf, labels, }: {
+    player: {
+        total: number;
+        index: number;
+        playing: boolean;
+        atEnd: boolean;
+        next: (onEmpty?: () => void) => void;
+        prev: () => void;
+        toggle: (onEmpty?: () => void) => void;
+        seek: (frame: number) => void;
+    };
+    toneAt?: (i: number) => StepTone;
+    titleAt?: (i: number) => string;
+    leading?: ReactNode;
+    /** Fired when the user plays/steps with no timeline loaded. */
+    onEmpty?: () => void;
+    emptyHint?: string;
+    className?: string;
+    theme?: StepwiseTheme;
+    /**
+     * Forwarded to the scrubber — group consecutive segments into one
+     * proportional wrapper (see StepScrubber).
+     */
+    groupOf?: (i: number) => number;
+    labels?: {
+        previous?: string;
+        play?: string;
+        pause?: string;
+        replay?: string;
+        next?: string;
+    };
+}): react.JSX.Element;
+declare function ChapterNav({ chapters, active, onNavigate, hint, className, theme, }: {
+    chapters: Chapter[];
+    active: number;
+    onNavigate: (i: number) => void;
+    hint?: string;
+    className?: string;
+    theme?: StepwiseTheme;
+}): react.JSX.Element;
+declare function LessonPager({ prev, next, onNavigate, className, labels, }: {
+    prev?: {
+        label: string;
+        hint?: string;
+    };
+    next?: {
+        label: string;
+        hint?: string;
+    };
+    onNavigate: (dir: "prev" | "next") => void;
+    className?: string;
+    labels?: {
+        previous?: string;
+        next?: string;
+    };
+}): react.JSX.Element;
+declare function TourSpotlight({ target, theme, }: {
+    target: string | null;
+    theme?: StepwiseTheme;
+}): react.JSX.Element | null;
+declare function TourCard({ step, index, total, onNext, onBack, onEnd, labels, className, theme, nextDisabled, }: {
+    step: TourStepInput;
+    index: number;
+    total: number;
+    onNext: () => void;
+    onBack: () => void;
+    onEnd: () => void;
+    labels?: {
+        title?: string;
+        back?: string;
+        next?: string;
+        finish?: string;
+        end?: string;
+    };
+    className?: string;
+    theme?: StepwiseTheme;
+    /** Disable the primary (Next/Finish) button — pair with tour.blocked. */
+    nextDisabled?: boolean;
+}): react.JSX.Element;
+declare function ShortcutsDialog({ open, onClose, items, title, className, theme, }: {
+    open: boolean;
+    onClose: () => void;
+    items: ShortcutItem[];
+    title?: string;
+    className?: string;
+    theme?: StepwiseTheme;
+}): react.ReactPortal | null;
+
+export { Chapter, ChapterNav, type ChaptersApi, CodeBlock, type Discoveries, type DiscoveriesOptions, type DiscoveryStore, type FlatChapter, type GlobalKeysOptions, GlossaryAppendix, type GlossaryEntry, GlossaryProvider, type GuidedTour, type GuidedTourOptions, type KeyMap, LessonPager, PlayerBar, PlayerEngine, ShortcutItem, ShortcutsDialog, type StepPlayer, type StepPlayerOptions, StepScrubber, StepTone, type StepsCore, type StepwiseTheme, TONE_CHIP_CLASS, TONE_SEGMENT_CLASS, Term, TourCard, TourDriver, TourSpotlight, TourStepInput, type UseStepsOptions, cookieStore, defaultTheme, flattenChapters, localStorageStore, memoryStore, useChapters, useDiscoveries, useFocusTrap, useGlobalKeys, useGuidedTour, usePrefersReducedMotion, useStepPlayer, useSteps };