@docentjs/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,582 @@
+//#region src/schema/tour.d.ts
+/**
+ * Tour schema — the JSON contract shared by the core engine, every renderer,
+ * the visual builder and the hosted service.
+ *
+ * Everything in this file must stay JSON-serialisable. Functions (hooks) live
+ * in `hooks.ts` and are attached at runtime, keyed by step id.
+ */
+/** Current schema version. Bump only on breaking changes to this file. */
+export declare const SCHEMA_VERSION: 1;
+type SchemaVersion = typeof SCHEMA_VERSION;
+/**
+ * Where a step points.
+ *
+ * - A bare string is a CSS selector (web only). Convenient for hand-written tours.
+ * - A {@link TargetSpec} is the portable, self-healing form the builder produces.
+ *
+ * Prefer `{ name }` over raw selectors: on the web it resolves to
+ * `[data-docent="<name>"]`, on native to a `testID`, so one tour works everywhere.
+ */
+type Target = string | TargetSpec;
+interface TargetSpec {
+  /**
+   * Logical name. Web: `[data-docent="<name>"]`. Native: `testID` / `nativeID`.
+   * The most robust anchor; survives refactors and works cross-platform.
+   */
+  name?: string;
+  /**
+   * Ordered CSS selector fallbacks (web only). Tried in order until one matches.
+   * The builder fills several so a tour keeps working after markup changes.
+   */
+  selectors?: string[];
+  /** Explicit native identifier when it differs from `name`. */
+  native?: string;
+  /** Restrict the search to a container matched by this selector. */
+  within?: string;
+  /** When a selector matches several elements, pick this index (default 0). */
+  nth?: number;
+}
+type Side = 'top' | 'right' | 'bottom' | 'left';
+type Alignment = 'start' | 'center' | 'end';
+/**
+ * Preferred popover position relative to the target. `auto` lets the renderer
+ * pick the side with the most room. Any placement flips or shifts when it
+ * would overflow the viewport.
+ */
+type Placement = 'auto' | Side | `${Side}-${Exclude<Alignment, 'center'>}`;
+interface SpotlightOptions {
+  /** Space between the target's edge and the cutout, in px. */
+  padding?: number;
+  /** Corner radius of the cutout, in px. */
+  radius?: number;
+  /** Animate the cutout moving between targets. */
+  animate?: boolean;
+}
+interface OverlayOptions {
+  /** Backdrop colour, any CSS colour. */
+  color?: string;
+  /** Backdrop opacity, 0–1. */
+  opacity?: number;
+}
+interface ScrollOptions {
+  /** Scroll the target into view before showing the step. */
+  enabled?: boolean;
+  behavior?: 'auto' | 'smooth';
+  block?: 'start' | 'center' | 'end' | 'nearest';
+}
+interface Media {
+  type: 'image' | 'video';
+  src: string;
+  alt?: string;
+}
+/**
+ * How a step completes.
+ *
+ * - `'button'` (default): the user presses Next.
+ * - `click` / `input`: the user interacts with the target (or another element).
+ * - `event`: a named event is emitted through the runtime.
+ * - `element`: an element appears (e.g. a menu the user was asked to open).
+ * - `delay`: automatically after `ms`.
+ */
+type Advance = 'button' | {
+  on: 'click';
+  target?: Target;
+} | {
+  on: 'input';
+  target?: Target;
+  match?: string;
+} | {
+  on: 'event';
+  name: string;
+} | {
+  on: 'element';
+  target: Target;
+} | {
+  on: 'delay';
+  ms: number;
+};
+/** Whether the user can interact with the spotlighted target. */
+type Interaction = 'block' | 'allow';
+/** What to do when a step's target cannot be found. */
+type OnMissing = 'skip' | 'wait' | 'abort';
+interface StepButtons {
+  back?: boolean;
+  next?: boolean;
+  skip?: boolean;
+  close?: boolean;
+}
+type TraitValue = string | number | boolean | null | string[];
+type TraitOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'contains' | 'exists' | 'missing';
+/**
+ * Serialisable predicate evaluated by the core at runtime.
+ * `custom` predicates are registered by name on the runtime.
+ */
+type Condition = {
+  type: 'trait';
+  key: string;
+  op: TraitOperator;
+  value?: TraitValue;
+} | {
+  type: 'route';
+  pattern: string;
+} | {
+  type: 'element';
+  target: Target;
+  exists?: boolean;
+} | {
+  type: 'tour';
+  id: string;
+  state: TourProgressState;
+} | {
+  type: 'all';
+  conditions: Condition[];
+} | {
+  type: 'any';
+  conditions: Condition[];
+} | {
+  type: 'not';
+  condition: Condition;
+} | {
+  type: 'custom';
+  name: string;
+  args?: Record<string, TraitValue>;
+};
+type TourProgressState = 'not-started' | 'in-progress' | 'completed' | 'skipped';
+/** What starts a tour. `manual` means only through the runtime API. */
+type Trigger = {
+  type: 'manual';
+} | {
+  type: 'auto';
+  delay?: number;
+} | {
+  type: 'route';
+  pattern: string;
+  delay?: number;
+} | {
+  type: 'element';
+  target: Target;
+  delay?: number;
+} | {
+  type: 'event';
+  name: string;
+};
+/**
+ * How often an eligible user sees the tour.
+ * - `once`: show once per {@link Tour.version}, however it ended.
+ * - `until-completed`: keep offering it until the user finishes it.
+ * - `always`: every time the trigger fires.
+ */
+type Frequency = 'once' | 'until-completed' | 'always';
+/**
+ * Visual tokens, serialisable so a builder or customizer can produce them.
+ * Each maps to a CSS custom property in the renderer (`--docent-*`).
+ * Values are CSS strings, e.g. `'#111'`, `'12px'`, `'0 4px 12px rgba(0,0,0,.2)'`.
+ */
+interface Theme {
+  background?: string;
+  foreground?: string;
+  muted?: string;
+  accent?: string;
+  accentForeground?: string;
+  radius?: string;
+  shadow?: string;
+  font?: string;
+  width?: string;
+  overlay?: string;
+  overlayOpacity?: string;
+  duration?: string;
+  zIndex?: string;
+}
+interface Labels {
+  next?: string;
+  back?: string;
+  skip?: string;
+  done?: string;
+  close?: string;
+  /** Supports `{current}` and `{total}` placeholders. */
+  progress?: string;
+}
+interface Step {
+  /** Unique within the tour. Used for persistence, hooks and analytics. */
+  id: string;
+  /** Omit for a centred modal step (welcome / finish screens). */
+  target?: Target;
+  title?: string;
+  body?: string;
+  /** How `body` is interpreted. Renderers never inject raw HTML. */
+  format?: 'text' | 'markdown';
+  media?: Media;
+  placement?: Placement;
+  /** Per-step override of the tour's spotlight options. */
+  spotlight?: SpotlightOptions;
+  advance?: Advance;
+  interaction?: Interaction;
+  /** Skip this step when the condition is false. */
+  condition?: Condition;
+  onMissing?: OnMissing;
+  /** How long to wait for the target when `onMissing` is `wait`, in ms. */
+  waitFor?: number;
+  /** URL pattern this step belongs to. Enables multi-page tours. */
+  route?: string;
+  buttons?: StepButtons;
+  scroll?: ScrollOptions;
+  /** Free-form extension bag for the builder or integrations. */
+  meta?: Record<string, unknown>;
+}
+interface TourOptions {
+  /** Persist progress so the tour survives navigation and reloads. */
+  persist?: boolean;
+  frequency?: Frequency;
+  showProgress?: boolean;
+  /** Allow closing with Escape or the close button. */
+  allowClose?: boolean;
+  closeOnOverlayClick?: boolean;
+  keyboard?: boolean;
+  spotlight?: SpotlightOptions;
+  overlay?: OverlayOptions;
+  scroll?: ScrollOptions;
+  labels?: Labels;
+  /** Visual tokens applied on top of the renderer's theme. */
+  theme?: Theme;
+  /** Name of a template registered on the renderer (slots, css, theme). */
+  template?: string;
+}
+interface Tour {
+  schemaVersion: SchemaVersion;
+  /** Stable identifier. Used for persistence, targeting and analytics. */
+  id: string;
+  /** Bump to re-show the tour to users who already saw an older version. */
+  version?: number;
+  /** Human-readable name, mainly for the builder and dashboards. */
+  name?: string;
+  description?: string;
+  steps: Step[];
+  trigger?: Trigger;
+  /** All must hold for the tour to be eligible. */
+  conditions?: Condition[];
+  options?: TourOptions;
+  /** Free-form extension bag for the builder or integrations. */
+  meta?: Record<string, unknown>;
+}
+//#endregion
+//#region src/define.d.ts
+/**
+ * Identity helper that gives hand-written tours full type inference and
+ * fills in the schema version. Returns the same object.
+ */
+export declare function defineTour(tour: Omit<Tour, 'schemaVersion'> & {
+  schemaVersion?: SchemaVersion;
+}): Tour;
+//#endregion
+//#region src/seams.d.ts
+type MaybePromise<T> = T | Promise<T>;
+interface TourSource {
+  /** Return every tour this source knows about. */
+  load(): MaybePromise<Tour[]>;
+  /**
+   * Optional live updates. Return an unsubscribe function.
+   * Lets a hosted source push tour changes without a page reload.
+   */
+  subscribe?(listener: (tours: Tour[]) => void): () => void;
+}
+interface Identity {
+  /** Stable user id. Omit for anonymous visitors. */
+  id?: string;
+  /** Attributes that `trait` conditions evaluate against. */
+  traits: Record<string, TraitValue>;
+}
+export declare const ANONYMOUS_IDENTITY: Identity;
+/**
+ * Key/value storage for progress and seen-state. Shape matches `localStorage`
+ * but every method may be async so React Native's AsyncStorage fits too.
+ */
+interface StorageAdapter {
+  get(key: string): MaybePromise<string | null>;
+  set(key: string, value: string): MaybePromise<void>;
+  remove(key: string): MaybePromise<void>;
+}
+type DocentEventType = 'tour:started' | 'tour:completed' | 'tour:skipped' | 'tour:aborted' | 'step:shown' | 'step:completed' | 'step:skipped' | 'step:missing';
+interface DocentEvent {
+  type: DocentEventType;
+  tourId: string;
+  tourVersion: number;
+  stepId?: string;
+  stepIndex?: number;
+  /** Unix epoch milliseconds. */
+  timestamp: number;
+  identity: Identity;
+}
+/** Receives every lifecycle event. Wire it to console, your analytics, or a hosted endpoint. */
+interface EventSink {
+  emit(event: DocentEvent): void;
+}
+//#endregion
+//#region src/engine/conditions.d.ts
+type CustomPredicate = (args?: Record<string, TraitValue>) => boolean;
+interface ConditionEnv {
+  identity: Identity;
+  /** Current path, e.g. `/invoices/new`. */
+  route?: string;
+  elementExists?: (target: Target) => boolean;
+  tourState?: (tourId: string) => TourProgressState;
+  custom?: Record<string, CustomPredicate>;
+}
+export declare function evaluateTrait(actual: TraitValue | undefined, op: Extract<Condition, {
+  type: 'trait';
+}>['op'], expected: TraitValue | undefined): boolean;
+export declare function evaluateCondition(condition: Condition, env: ConditionEnv): boolean;
+/** All conditions must hold. An empty or missing list holds. */
+export declare function evaluateAll(conditions: Condition[] | undefined, env: ConditionEnv): boolean;
+//#endregion
+//#region src/hooks.d.ts
+interface StepContext {
+  tour: Tour;
+  step: Step;
+  index: number;
+  total: number;
+}
+interface StepHooks {
+  /**
+   * Runs before the step renders. Open a menu, navigate, fetch data.
+   * Return `false` to skip the step; return nothing to continue.
+   */
+  beforeShow?(ctx: StepContext): MaybePromise<undefined | false>;
+  afterShow?(ctx: StepContext): MaybePromise<void>;
+  beforeHide?(ctx: StepContext): MaybePromise<void>;
+}
+interface TourHooks {
+  onStart?(tour: Tour): void;
+  onStepChange?(ctx: StepContext): void;
+  onComplete?(tour: Tour): void;
+  onSkip?(ctx: StepContext): void;
+  onAbort?(tour: Tour, reason: string): void;
+  /** Per-step hooks, keyed by step id. */
+  steps?: Record<string, StepHooks>;
+}
+//#endregion
+//#region src/engine/reducer.d.ts
+type TourStatus = 'idle' | 'running' | 'paused' | 'completed' | 'skipped' | 'aborted';
+interface EngineState {
+  status: TourStatus;
+  /** Index into `tour.steps`, or -1 when not running. */
+  index: number;
+  /** Indices of previously shown steps, oldest first. Drives `back`. */
+  history: number[];
+  /** Set when status is `aborted` or `paused`. */
+  reason?: string;
+}
+type EngineAction = {
+  type: 'start';
+  at?: number | string;
+} | {
+  type: 'next';
+} | {
+  type: 'back';
+} | {
+  type: 'go';
+  to: number | string;
+} | {
+  type: 'skip';
+} | {
+  type: 'complete';
+} | {
+  type: 'abort';
+  reason: string;
+} | {
+  type: 'pause';
+  reason: string;
+} | {
+  type: 'resume';
+} | {
+  type: 'stepMissing';
+} | {
+  type: 'stepSkipped';
+};
+interface EngineContext {
+  tour: Tour;
+  /** Whether the step at `index` may be shown right now. */
+  isEligible: (index: number) => boolean;
+}
+export declare const IDLE_STATE: EngineState;
+export declare function resolveStepIndex(tour: Tour, ref: number | string): number;
+/** First eligible index at or after `from` (or at or before, when `dir` is -1). -1 if none. */
+export declare function findEligible(ctx: EngineContext, from: number, dir?: 1 | -1): number;
+export declare function reduce(state: EngineState, action: EngineAction, ctx: EngineContext): EngineState;
+export declare function isActive(state: EngineState): boolean;
+export declare function isFinished(state: EngineState): boolean;
+export declare function canGoBack(state: EngineState, ctx: EngineContext): boolean;
+/** True when another eligible step follows. False on the last step. */
+export declare function hasNext(state: EngineState, ctx: EngineContext): boolean;
+interface Progress {
+  /** 1-based position of the current step. */
+  current: number;
+  total: number;
+}
+/** Position over all steps, ineligible ones included, so numbers stay stable. */
+export declare function progress(state: EngineState, ctx: EngineContext): Progress;
+//#endregion
+//#region src/engine/renderer.d.ts
+interface RenderActions {
+  next(): void;
+  back(): void;
+  skip(): void;
+  /** Jump to a step by id or index. */
+  goTo(step: number | string): void;
+}
+interface RenderContext {
+  tour: Tour;
+  step: Step;
+  index: number;
+  progress: Progress;
+  isFirst: boolean;
+  isLast: boolean;
+  canGoBack: boolean;
+  actions: RenderActions;
+}
+interface Renderer {
+  /** Synchronous presence check. Used for `element` conditions and missing-target handling. */
+  hasTarget(target: Target): boolean;
+  /**
+   * Wait up to `timeoutMs` for the target to appear. Resolve `true` when it does.
+   * Must resolve promptly (with `false`) when `signal` aborts.
+   */
+  waitForTarget(target: Target, timeoutMs: number, signal: AbortSignal): Promise<boolean>;
+  /** Render the step. The renderer wires user gestures to `ctx.actions`. */
+  show(ctx: RenderContext): MaybePromise<void>;
+  /** Remove everything from screen. Called on finish and before each new step. */
+  hide(): MaybePromise<void>;
+  /** Current route path, when the platform has one. */
+  currentRoute?(): string;
+}
+//#endregion
+//#region src/engine/controller.d.ts
+interface ControllerOptions {
+  tour: Tour;
+  renderer: Renderer;
+  identity?: Identity;
+  storage?: StorageAdapter;
+  sink?: EventSink;
+  hooks?: TourHooks;
+  /** Predicates for `custom` conditions, by name. */
+  custom?: Record<string, CustomPredicate>;
+  /** Progress of other tours, for `tour` conditions. */
+  tourState?: (tourId: string) => TourProgressState;
+  /** How long `onMissing: 'wait'` waits when the step sets no `waitFor`. */
+  defaultWaitMs?: number;
+  now?: () => number;
+}
+type StateListener = (state: EngineState) => void;
+export declare class TourController {
+  readonly tour: Tour;
+  private state;
+  private readonly renderer;
+  private readonly identity;
+  private readonly store;
+  private readonly sink;
+  private readonly hooks;
+  private readonly custom;
+  private readonly tourStateOf;
+  private readonly defaultWaitMs;
+  private readonly now;
+  private readonly listeners;
+  /** Bumped whenever an async flow must be abandoned. */
+  private generation;
+  private pendingAbort;
+  private pendingTimer;
+  constructor(options: ControllerOptions);
+  getState(): EngineState;
+  subscribe(listener: StateListener): () => void;
+  /** Start from the first eligible step, or from `at` (step id or index). */
+  start(at?: number | string): Promise<void>;
+  /** Start where the user left off, according to persisted progress. */
+  resume(): Promise<void>;
+  next(): Promise<void>;
+  back(): Promise<void>;
+  goTo(step: number | string): Promise<void>;
+  /** The user gave up on the tour (Skip button, close, Escape). */
+  skip(): Promise<void>;
+  abort(reason: string): Promise<void>;
+  /** Report a named application event. Advances a step waiting on it. */
+  notify(eventName: string): void;
+  /** Tell the controller the route changed. Pauses or resumes route-bound steps. */
+  routeChanged(): Promise<void>;
+  /** Stop everything and clear the screen without recording an outcome. */
+  destroy(): Promise<void>;
+  private isActive;
+  private currentStep;
+  private conditionEnv;
+  private context;
+  private stepOnRoute;
+  private dispatch;
+  private setState;
+  private stepContext;
+  private emit;
+  private persist;
+  private cancelPending;
+  /** Run `beforeHide` for the step being left, if any. */
+  private leaveCurrent;
+  private afterTransition;
+  private finish;
+  private showCurrent;
+  /** Resolve `true` when the target is present, waiting if the step allows it. */
+  private ensureTarget;
+  /** Set up automatic advancement for `delay` and `element` steps. */
+  private armAdvance;
+  private renderContext;
+}
+//#endregion
+//#region src/engine/events.d.ts
+interface EventInput {
+  tour: Tour;
+  identity: Identity;
+  stepIndex?: number;
+  now?: () => number;
+}
+export declare function createEvent(type: DocentEventType, input: EventInput): DocentEvent;
+/** Sink that drops everything. Default when none is configured. */
+export declare const NOOP_SINK: EventSink;
+/** Fan out to several sinks. */
+export declare function combineSinks(...sinks: EventSink[]): EventSink;
+//#endregion
+//#region src/engine/progress.d.ts
+interface TourRecord {
+  tourId: string;
+  version: number;
+  state: TourProgressState;
+  /** Step to resume from when the tour was interrupted. */
+  stepId?: string;
+  /** Unix epoch milliseconds. */
+  updatedAt: number;
+}
+export declare const STORAGE_PREFIX = "docent:";
+export declare function storageKey(tourId: string): string;
+export declare function tourVersion(tour: Tour): number;
+/** Whether a tour should be offered given what the user has already done. */
+export declare function shouldShow(tour: Tour, record: TourRecord | null): boolean;
+export declare class ProgressStore {
+  private readonly storage;
+  constructor(storage: StorageAdapter);
+  get(tourId: string): Promise<TourRecord | null>;
+  set(record: TourRecord): Promise<void>;
+  clear(tourId: string): Promise<void>;
+}
+/** In-memory adapter. Default when no storage is configured, and handy in tests. */
+export declare function createMemoryStorage(): StorageAdapter;
+//#endregion
+//#region src/engine/route.d.ts
+/**
+ * Route pattern matching for `route` triggers, conditions and step routes.
+ *
+ * Patterns are path globs:
+ * - `/settings`          exact
+ * - `/users/:id`         one segment (named for readability, value ignored)
+ * - `/users/*`           one segment
+ * - `/docs/**`           zero or more segments
+ *
+ * Query strings and hashes are ignored. Trailing slashes are tolerated.
+ */
+export declare function matchRoute(pattern: string, path: string): boolean;
+//#endregion
+export type { Advance, Alignment, Condition, ConditionEnv, ControllerOptions, CustomPredicate, DocentEvent, DocentEventType, EngineAction, EngineContext, EngineState, EventInput, EventSink, Frequency, Identity, Interaction, Labels, MaybePromise, Media, OnMissing, OverlayOptions, Placement, Progress, RenderActions, RenderContext, Renderer, SchemaVersion, ScrollOptions, Side, SpotlightOptions, StateListener, Step, StepButtons, StepContext, StepHooks, StorageAdapter, Target, TargetSpec, Theme, Tour, TourHooks, TourOptions, TourProgressState, TourRecord, TourSource, TourStatus, TraitOperator, TraitValue, Trigger };
+//# sourceMappingURL=index.d.ts.map