@pablo2410/shared-ui 0.23.0 → 0.25.0

package/dist/tour/index.d.ts

@@ -208,4 +208,200 @@ interface UseSpotlightResult {
  */
 declare function useSpotlight(selector: string | null): UseSpotlightResult;
 
-export { type PanelPosition, type Placement, type Rect, type Size, type SpotlightFrame, type TourProgress, TourShell, type TourShellProps, type TourShellSkin, type TourSpotlightTarget, type TourStatus, type TourStep, type TourStepKind, type UseSpotlightResult, type UseTourOptions, type UseTourResult, computePanelPosition, computeSpotlightFrame, useSpotlight, useTour };
+/**
+ * The tour registry + launcher store — the one place a module's tour
+ * definition and the "is a tour open right now" flag live, so the header's
+ * "Take the tour" trigger, the tour host, and the module's own page code
+ * never talk to each other directly.
+ *
+ * A module's whole integration is a definition object (see
+ * TourDefinition) passed to `useRegisterTour`, plus `data-tour-target`
+ * attributes on the elements its spotlight steps point at. Everything else
+ * — progress storage, the header trigger, the overlay, narration — is shared.
+ *
+ * Plain functions, no React import: testable in a Node environment (this
+ * package has no jsdom set up — see tour.test.ts), same split as
+ * tourMachine.ts. TourProvider.tsx is the React binding.
+ */
+
+interface TourDefinition {
+    /** Stable, lowercase-kebab id, e.g. "policy-deployment". It is the key
+     *  progress is stored under in Portal, so never rename a shipped tour's
+     *  id — users' progress and "done" state would reset. */
+    id: string;
+    /** The steps, in order. A step that should highlight a live element sets
+     *  `spotlight.selector` to the value of a `data-tour-target` attribute in
+     *  the module's DOM. */
+    steps: TourStep[];
+    /** Open the tour by itself for a user who has never seen it or left it
+     *  part-way (resuming at their last step). Off by default. Never fires
+     *  when the user's progress couldn't be read, and never for a tour they
+     *  finished or dismissed — those only reopen from "Take the tour". */
+    autoStart?: boolean;
+}
+declare class InvalidTourDefinitionError extends Error {
+    readonly problems: string[];
+    constructor(tourId: string, problems: string[]);
+}
+/** Returns a list of problems; empty means the definition is usable. */
+declare function validateTourDefinition(def: TourDefinition): string[];
+interface TourSession {
+    /** True = start at step 1 regardless of saved progress (the header's
+     *  "Take the tour" replay). False = resume from the saved step. */
+    restart: boolean;
+}
+interface TourStoreState {
+    /** The tour the header trigger and host act on: the most recently
+     *  registered one still mounted (a page-level tour wins over a
+     *  module-level one while its page is open). */
+    active: TourDefinition | null;
+    /** Non-null while the tour overlay is open. */
+    session: TourSession | null;
+}
+interface TourStore {
+    /** Registers (or replaces, by id) a tour. Throws InvalidTourDefinitionError
+     *  for an unusable definition. Returns the unregister function. */
+    register(def: TourDefinition): () => void;
+    /** Opens the active tour. No-op when none is registered. */
+    open(session?: TourSession): void;
+    close(): void;
+    getState(): TourStoreState;
+    subscribe(listener: () => void): () => void;
+}
+declare function createTourStore(): TourStore;
+/** The store modules share by default. `TourProvider` can swap in another
+ *  (tests, or an app that wants isolation). */
+declare const defaultTourStore: TourStore;
+
+/** The id Portal's existing, tour-id-less state belongs to. */
+declare const SERVICE_HUB_TOUR_ID = "service-hub";
+interface TourProgressUpdate {
+    status: Exclude<TourStatus, "unseen">;
+    lastStepId: string | null;
+}
+interface TourProgressTransport {
+    read(tourId: string): Promise<TourProgress>;
+    write(tourId: string, update: TourProgressUpdate): Promise<void>;
+}
+declare class TourProgressError extends Error {
+    readonly status?: number;
+    constructor(message: string, status?: number);
+}
+interface PortalTransportOptions {
+    /** Portal origin. Defaults to the platform Portal (`localhost:3000` on the
+     *  local sandbox) — see services/platformDomain. */
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+}
+declare function createPortalTourProgressTransport(opts?: PortalTransportOptions): TourProgressTransport;
+interface TourProgressSnapshot {
+    /** "loading" until the first read settles. A failed read is "error" with
+     *  `progress` falling back to unseen, so the tour is still usable. */
+    phase: "loading" | "ready" | "error";
+    progress: TourProgress;
+    error: Error | null;
+}
+interface TourProgressController {
+    getSnapshot(): TourProgressSnapshot;
+    subscribe(listener: () => void): () => void;
+    load(): Promise<void>;
+    /** Updates local state at once, then persists. Writes go out in the order
+     *  they were recorded, so rapid Next clicks can't land reversed. A failed
+     *  write never throws — the tour must not block on storage. */
+    record(update: TourProgressUpdate): Promise<void>;
+}
+declare function createTourProgressController(transport: TourProgressTransport, tourId: string): TourProgressController;
+/** Whether to open the tour on its own when the module loads: only for a
+ *  user who has never seen it or left it part-way. Done and dismissed tours
+ *  only reopen from the header's "Take the tour". */
+declare function shouldAutoOpen(status: TourStatus): boolean;
+/** The full auto-open decision, made once when the first read settles.
+ *  A failed read ("error") never auto-opens: its fallback "unseen" is not
+ *  real, and opening on every page load for progress that can't be saved
+ *  would nag. */
+declare function decideAutoOpen(autoStart: boolean | undefined, snapshot: Pick<TourProgressSnapshot, "phase" | "progress">): boolean;
+
+/** Reserved `service` value that makes Portal use the onboarding persona. */
+declare const ONBOARDING_NARRATION_SERVICE = "onboarding";
+declare const NARRATION_PROMPT = "Narrate this onboarding step for me in 2-3 sentences.";
+interface NarrationRequestInput {
+    service: typeof ONBOARDING_NARRATION_SERVICE;
+    insights: {
+        hook: string;
+        highlights?: string[];
+        features?: {
+            name: string;
+            detail: string;
+        }[];
+    };
+    messages: {
+        role: "user";
+        content: string;
+    }[];
+}
+declare function buildNarrationInput(step: TourStep): NarrationRequestInput;
+/** Resolves with Opi's narration for the step, or rejects. */
+type TourNarrator = (step: TourStep) => Promise<string>;
+interface PortalNarratorOptions {
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+}
+declare function createPortalNarrator(opts?: PortalNarratorOptions): TourNarrator;
+
+interface TourProviderProps {
+    store?: TourStore;
+    transport?: TourProgressTransport;
+    narrator?: TourNarrator;
+    children: ReactNode;
+}
+declare function TourProvider({ store, transport, narrator, children, }: TourProviderProps): React.JSX.Element;
+/**
+ * Registers the module's tour for as long as the calling component is
+ * mounted. That is all a module does to get the header's "Take the tour"
+ * trigger, the overlay, saved progress and narration.
+ *
+ * Pass a definition that is stable across renders (module scope, or
+ * useMemo) — a new object every render re-registers every render. Pass
+ * null/undefined to register nothing (e.g. while data is loading). An
+ * invalid definition is logged and ignored rather than thrown: a broken
+ * tour must never take down the page it sits on.
+ */
+declare function useRegisterTour(def: TourDefinition | null | undefined): void;
+declare function useTourState(): TourStoreState;
+/** The tour the header trigger would open now, or null when the current
+ *  module has registered none. */
+declare function useActiveTour(): TourDefinition | null;
+/** Imperative open/close for the active tour — what the header trigger uses. */
+declare function useTourLauncher(): {
+    /** Opens from step 1, regardless of saved progress. */
+    start: () => void;
+    /** Opens with an explicit session (e.g. resume from saved progress). */
+    open: (session: TourSession) => void;
+    close: () => void;
+    available: boolean;
+};
+interface UseTourProgressResult extends TourProgressSnapshot {
+    record: (update: TourProgressUpdate) => Promise<void>;
+}
+/** The user's saved progress through one tour, read from and written to
+ *  Portal (see tourProgress.ts). */
+declare function useTourProgress(tourId: string): UseTourProgressResult;
+/** The narrator the tour host uses — exposed so a module's own tour UI can
+ *  narrate in the same voice. */
+declare function useTourNarrator(): TourNarrator;
+
+interface TakeTheTourButtonProps {
+    /** Defaults to "Take the tour". */
+    label?: string;
+    className?: string;
+}
+declare function TakeTheTourButton({ label, className, }: TakeTheTourButtonProps): React.JSX.Element | null;
+
+interface OpiTourHostProps {
+    /** Orb/avatar shown in the tour header. Defaults to a plain mark. */
+    orb?: ReactNode;
+    skin?: TourShellSkin;
+}
+declare function OpiTourHost(props: OpiTourHostProps): React.JSX.Element | null;
+
+export { InvalidTourDefinitionError, NARRATION_PROMPT, type NarrationRequestInput, ONBOARDING_NARRATION_SERVICE, OpiTourHost, type OpiTourHostProps, type PanelPosition, type Placement, type PortalNarratorOptions, type PortalTransportOptions, type Rect, SERVICE_HUB_TOUR_ID, type Size, type SpotlightFrame, TakeTheTourButton, type TakeTheTourButtonProps, type TourDefinition, type TourNarrator, type TourProgress, type TourProgressController, TourProgressError, type TourProgressSnapshot, type TourProgressTransport, type TourProgressUpdate, TourProvider, type TourProviderProps, type TourSession, TourShell, type TourShellProps, type TourShellSkin, type TourSpotlightTarget, type TourStatus, type TourStep, type TourStepKind, type TourStore, type TourStoreState, type UseSpotlightResult, type UseTourOptions, type UseTourProgressResult, type UseTourResult, buildNarrationInput, computePanelPosition, computeSpotlightFrame, createPortalNarrator, createPortalTourProgressTransport, createTourProgressController, createTourStore, decideAutoOpen, defaultTourStore, shouldAutoOpen, useActiveTour, useRegisterTour, useSpotlight, useTour, useTourLauncher, useTourNarrator, useTourProgress, useTourState, validateTourDefinition };