@richardmcquiston01/chat-and-react-core 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -1,3 +1,9 @@
+import { StorageAdapter } from '@richardmcquiston01/storage-adapters';
+export { StorageAdapter, StoreErrorCode, StoreResult, StoredValue } from '@richardmcquiston01/storage-adapters';
+export { LocalStorageAdapterOptions, StorageChangeEvent, StorageEventTarget, WebStorageLike, localStorageAdapter } from '@richardmcquiston01/storage-adapters/browser';
+import { ErrorLogEntry, ErrorLogAdapter as ErrorLogAdapter$1, ConsoleErrorAdapter as ConsoleErrorAdapter$1, ConsoleErrorOptions } from '@richardmcquiston01/error-log-adapter';
+export { ErrorLogEntry, ErrorLogResult } from '@richardmcquiston01/error-log-adapter';
+
 type AnswerMap = Record<string, string | string[]>;
 type ChatInputType = 'text' | 'textarea' | 'dropdown' | 'radio' | 'checkbox';
 type JsonLogicRule = Record<string, unknown>;
@@ -11,6 +17,16 @@ interface ChatQuestion {
     title: string;
     'x-chat-placeholder'?: string;
     'x-chat-condition'?: JsonLogicRule | ChatConditionRef;
+    /**
+     * Shows a "thinking" bubble before this question appears, so the conversation
+     * feels less abrupt. A number is the delay in milliseconds (0 turns it off for
+     * this question). An object can also set the text shown instead of the dots.
+     * Overrides the `thinkingDelay` and `thinkingText` options.
+     */
+    'x-chat-thinking'?: number | {
+        delay?: number;
+        text?: string;
+    };
     enum?: string[];
     items?: {
         enum: string[];
@@ -33,13 +49,31 @@ interface ChatPage {
     questions: ChatQuestion[];
     branching: BranchingRule[];
 }
+/** How a bubble leaves the screen when it is hidden: fade out, shrink away ("pop"), or vanish at once. */
+type HideAnimation = 'fade' | 'pop' | 'none';
 interface ChatOptions {
     userResumable: boolean;
     localStorage: boolean;
     autoComplete: boolean;
+    /** Show an Edit icon on answered questions so users can change their answers. */
+    allowEdit: boolean;
+    /** Milliseconds to wait before hiding an answered question bubble. 0 keeps them visible. */
+    autoHideQuestions: number;
+    /** Milliseconds to wait before hiding an answer bubble once its question is answered. 0 keeps them visible. */
+    autoHideAnswers: number;
+    /** How hidden bubbles leave the screen. */
+    hideAnimation: HideAnimation;
+    /** Milliseconds per character when question text is "typed" onto the screen. 0 shows it at once. */
+    typingSpeed: number;
+    /** Milliseconds to show a "thinking" bubble before each question. 0 turns it off. */
+    thinkingDelay: number;
+    /** Text for the thinking bubble. Empty shows animated dots. */
+    thinkingText: string;
+    /** Show an icon on the Continue button. */
+    showContinueIcon: boolean;
 }
 interface ChatSchema {
-    '$schema'?: string;
+    $schema?: string;
     'x-chat-version': '1';
     'x-chat-options'?: Partial<ChatOptions>;
     'x-chat-pages': ChatPage[];
@@ -51,7 +85,23 @@ interface PageSubmitEvent {
     pageId: string;
     visitIndex: number;
     answers: AnswerMap;
+    /** Present and true when the user re-submitted a page they had already answered. */
+    edited?: boolean;
+}
+/** One page the user has submitted, in the order they visited it. */
+interface RouteEntry {
+    pageId: string;
+    answers: AnswerMap;
 }
+/**
+ * What happened to the form after `submitPage`:
+ * - `advanced`: a normal submit; the form moved to the next page or completed.
+ * - `edit-resumed`: an earlier page was edited and the route is unchanged, so the
+ *   form is back on the page the user was on.
+ * - `edit-rerouted`: an earlier page was edited and its branching now leads
+ *   somewhere else. Later pages were dropped and the form moved to the new page.
+ */
+type SubmitOutcome = 'advanced' | 'edit-resumed' | 'edit-rerouted';
 interface FormCompleteEvent {
     type: 'form:complete';
     sessionId: string;
@@ -59,49 +109,42 @@ interface FormCompleteEvent {
 }
 type ChatEvent = PageSubmitEvent | FormCompleteEvent;
 type ChatErrorCode = 'SCHEMA_INVALID' | 'RULE_EVAL_FAILED' | 'ADAPTER_ERROR' | 'STORAGE_UNAVAILABLE';
-interface ChatError {
-    code: ChatErrorCode;
-    message: string;
-    cause?: unknown;
-}
+type ChatError = ErrorLogEntry<ChatErrorCode>;
 interface InputAdapter {
     transform(raw: unknown): unknown;
 }
 interface OutputAdapter {
     emit(event: ChatEvent): void;
 }
-interface ErrorLogAdapter {
-    log(error: ChatError): void;
-}
+/**
+ * Routes `ChatError`s to a sink. `log` returns a result instead of throwing, so the
+ * caller can check `ok`. See `@richardmcquiston01/error-log-adapter`.
+ */
+type ErrorLogAdapter = ErrorLogAdapter$1<ChatErrorCode>;
+
 interface ChatControllerConfig {
     schema: unknown;
     inputAdapter?: InputAdapter;
     outputAdapter?: OutputAdapter;
     errorAdapter?: ErrorLogAdapter;
+    /**
+     * Option values that win over the schema's `x-chat-options`, for example ones
+     * read from element attributes.
+     */
+    options?: Partial<ChatOptions>;
 }
 
-/**
- * Parses and validates an unknown input as a {@link ChatSchema}.
- *
- * @param raw - The raw input to validate.
- * @returns The typed {@link ChatSchema} if valid.
- * @throws `{ code: 'SCHEMA_INVALID', message: string }` on any validation failure.
- */
-declare function parseSchema(raw: unknown): ChatSchema;
+declare class BrowserEventAdapter implements OutputAdapter {
+    emit(event: ChatEvent): void;
+}
 
-/**
- * Evaluates JSON Logic rules against provided answers.
- * Wraps json-logic-js to provide type-safe rule evaluation.
- */
-declare class RuleEngine {
-    /**
-     * Evaluates a JSON Logic rule against an answer map.
-     * @param rule The JSON Logic rule to evaluate
-     * @param answers The answer map to evaluate the rule against
-     * @returns The boolean result of the rule evaluation
-     * @throws {{ code: 'RULE_EVAL_FAILED', message: string, cause: unknown }} if rule evaluation fails
-     */
-    evaluate(rule: JsonLogicRule, answers: AnswerMap): boolean;
+/** Writes errors to `console.error`, prefixed with `[chat-and-react]` unless overridden. */
+declare class ConsoleErrorAdapter extends ConsoleErrorAdapter$1<ChatErrorCode> {
+    constructor(options?: ConsoleErrorOptions);
+}
+
+declare class IdentityInputAdapter implements InputAdapter {
+    transform(raw: unknown): unknown;
 }
 
 interface StorageBackend {
@@ -115,7 +158,22 @@ interface SessionProgress {
     currentPageId: string;
     answers: AnswerMap;
 }
-declare class SessionManager {
+/**
+ * What `ChatController` needs from session storage. `SessionManager` keeps it in a
+ * synchronous Web Storage object; `AdapterSessionManager` keeps it in a `StorageAdapter`.
+ */
+interface SessionStore {
+    readonly isStorageAvailable: boolean;
+    getSessionId(): string;
+    saveProgress(currentPageId: string, answers: AnswerMap): void;
+    loadProgress(): SessionProgress | null;
+    saveInput(questionId: string, value: string | string[]): void;
+    loadInput(questionId: string): string | string[] | null;
+    clearAll(): void;
+    /** Stops listening for changes made elsewhere. Called when the controller is destroyed. */
+    dispose?(): void;
+}
+declare class SessionManager implements SessionStore {
     private readonly storage;
     private readonly sessionId;
     private readonly available;
@@ -146,12 +204,18 @@ declare class ChatController {
     private currentPage;
     private allAnswers;
     private visitIndex;
+    /** Pages submitted in this session, in visit order. Used for editing earlier answers. */
+    private route;
+    /** Index in `route` of the page being edited, or null when not editing. */
+    private editIndex;
+    /** The page the user was on before they started editing an earlier one. */
+    private resumePageId;
     private readonly listeners;
     /**
      * @param config - Controller configuration including schema and optional adapters.
      * @param sessionManager - Optional session manager for test injection.
      */
-    constructor(config: ChatControllerConfig, sessionManager?: SessionManager);
+    constructor(config: ChatControllerConfig, sessionManager?: SessionStore);
     /**
      * Initialises the controller: parses the schema, resolves options,
      * restores any saved session, and positions to the first page.
@@ -170,6 +234,24 @@ declare class ChatController {
      * Returns the resolved options for the current session (schema options merged with defaults).
      */
     getOptions(): ChatOptions;
+    /**
+     * Returns the pages the user has submitted in this session, in visit order.
+     * A session restored from storage starts with an empty route.
+     */
+    getRoute(): RouteEntry[];
+    /**
+     * Returns every answer given so far, for pre-filling inputs.
+     */
+    getAnswers(): AnswerMap;
+    /**
+     * Re-opens a page the user already submitted so its answers can be changed.
+     * Call `submitPage` afterwards to save the new answers. Not available once the
+     * form is complete.
+     *
+     * @param routeIndex - Position of the page in `getRoute()`.
+     * @returns true when the page was re-opened.
+     */
+    reopenPage(routeIndex: number): boolean;
     /**
      * Submits the answers for the current page and advances the session.
      * - Accumulates answers into `allAnswers`.
@@ -177,9 +259,15 @@ declare class ChatController {
      * - Resolves branching to find the next page.
      * - Emits `form:complete` and clears session when `**FORM_COMPLETED**` is reached.
      *
+     * When the page was re-opened with `reopenPage`, the new answers replace the
+     * old ones and `page:submit` is emitted with `edited: true`. If the page's
+     * branching still leads to the same next page, the form returns to the page the
+     * user was on. If it leads somewhere else, the pages that followed it are
+     * dropped, along with their answers, and the form continues from the new page.
+     *
      * @param pageAnswers - Answers collected for the current page.
      */
-    submitPage(pageAnswers: AnswerMap): void;
+    submitPage(pageAnswers: AnswerMap): SubmitOutcome;
     /**
      * Registers an event listener for the given event type.
      *
@@ -203,6 +291,12 @@ declare class ChatController {
      * Returns true when no condition is present. On evaluation failure, logs and returns false.
      */
     private isQuestionVisible;
+    /**
+     * The answers question conditions are checked against. While an earlier page is
+     * being edited, that page's own answers are left out, so its questions are
+     * shown exactly as they were the first time the page was asked.
+     */
+    private answersForRules;
     /**
      * Walks the branching rules top-to-bottom. Returns the first match's destination_id.
      * Falls back to `**FORM_COMPLETED**` if nothing matches (should not happen with valid schemas).
@@ -221,18 +315,91 @@ declare class ChatController {
      * Used for unrecoverable errors (schema invalid, adapter failure on start).
      */
     private handleFatal;
+    /**
+     * Sends the error to the error adapter without waiting for it. If the adapter
+     * reports a failure, rejects, or throws, that is written to `console.error` so
+     * the original error is never lost and the form keeps running.
+     */
+    private logError;
 }
 
-declare class IdentityInputAdapter implements InputAdapter {
-    transform(raw: unknown): unknown;
+/**
+ * Evaluates JSON Logic rules against provided answers.
+ * Wraps json-logic-js to provide type-safe rule evaluation.
+ */
+declare class RuleEngine {
+    /**
+     * Evaluates a JSON Logic rule against an answer map.
+     * @param rule The JSON Logic rule to evaluate
+     * @param answers The answer map to evaluate the rule against
+     * @returns The boolean result of the rule evaluation
+     * @throws {{ code: 'RULE_EVAL_FAILED', message: string, cause: unknown }} if rule evaluation fails
+     */
+    evaluate(rule: JsonLogicRule, answers: AnswerMap): boolean;
 }
 
-declare class BrowserEventAdapter implements OutputAdapter {
-    emit(event: ChatEvent): void;
-}
+/**
+ * Parses and validates an unknown input as a {@link ChatSchema}.
+ *
+ * @param raw - The raw input to validate.
+ * @returns The typed {@link ChatSchema} if valid.
+ * @throws `{ code: 'SCHEMA_INVALID', message: string }` on any validation failure.
+ */
+declare function parseSchema(raw: unknown): ChatSchema;
 
-declare class ConsoleErrorAdapter implements ErrorLogAdapter {
-    log(error: ChatError): void;
+type InputValue = string | string[];
+interface AdapterSessionManagerOptions {
+    /** Called when the adapter fails. The session keeps working from memory. */
+    onError?: (error: ChatError) => void;
+    /**
+     * Called when saved progress changes because of a write made elsewhere, such as
+     * another tab. `null` means the session was cleared there.
+     */
+    onExternalChange?: (progress: SessionProgress | null) => void;
+}
+/**
+ * A session store backed by a `StorageAdapter`. `ChatController` is synchronous, so
+ * the saved session is loaded into memory by `create()`, reads come from memory, and
+ * writes are saved in the background. Failures are reported through `onError`.
+ *
+ * Saves carry the revision they were based on. If another tab wrote first, the two
+ * are merged: inputs per question, and progress only when this tab saved progress
+ * itself, so a tab that only typed cannot overwrite another tab's progress.
+ */
+declare class AdapterSessionManager implements SessionStore {
+    private readonly adapter;
+    private readonly sessionId;
+    private readonly available;
+    private readonly options;
+    private record;
+    private revision;
+    private readonly dirtyInputs;
+    private dirtyProgress;
+    private pending;
+    private persisting;
+    private readonly signal;
+    private unsubscribe;
+    private constructor();
+    /** Loads (or creates) the session id and its saved record, then returns the manager. */
+    static create(adapter: StorageAdapter, options?: AdapterSessionManagerOptions): Promise<AdapterSessionManager>;
+    getSessionId(): string;
+    get isStorageAvailable(): boolean;
+    saveProgress(currentPageId: string, answers: AnswerMap): void;
+    loadProgress(): SessionProgress | null;
+    saveInput(questionId: string, value: InputValue): void;
+    loadInput(questionId: string): InputValue | null;
+    clearAll(): void;
+    dispose(): void;
+    /** Resolves when every save made so far has finished. Mostly for tests. */
+    flush(): Promise<void>;
+    private report;
+    private schedulePersist;
+    /** Saves until nothing is left to save. Never rejects. */
+    private drain;
+    private persistOnce;
+    /** Merges a version written elsewhere with this tab's unsaved changes. */
+    private applyRemote;
+    private removeRecord;
 }
 
-export { type AnswerMap, type BranchingAlways, type BranchingIf, type BranchingRule, BrowserEventAdapter, type ChatConditionRef, ChatController, type ChatControllerConfig, type ChatError, type ChatErrorCode, type ChatEvent, type ChatInputType, type ChatOptions, type ChatPage, type ChatQuestion, type ChatSchema, ConsoleErrorAdapter, type ErrorLogAdapter, type FormCompleteEvent, IdentityInputAdapter, type InputAdapter, type JsonLogicRule, type OutputAdapter, type PageSubmitEvent, RuleEngine, SessionManager, type SessionProgress, type StorageBackend, parseSchema };
+export { AdapterSessionManager, type AdapterSessionManagerOptions, type AnswerMap, type BranchingAlways, type BranchingIf, type BranchingRule, BrowserEventAdapter, type ChatConditionRef, ChatController, type ChatControllerConfig, type ChatError, type ChatErrorCode, type ChatEvent, type ChatInputType, type ChatOptions, type ChatPage, type ChatQuestion, type ChatSchema, ConsoleErrorAdapter, type ErrorLogAdapter, type FormCompleteEvent, type HideAnimation, IdentityInputAdapter, type InputAdapter, type JsonLogicRule, type OutputAdapter, type PageSubmitEvent, type RouteEntry, RuleEngine, SessionManager, type SessionProgress, type SessionStore, type StorageBackend, type SubmitOutcome, parseSchema };