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

package/dist/index.mjs

@@ -1,3 +1,53 @@
+// src/index.ts
+import { localStorageAdapter } from "@richardmcquiston01/storage-adapters/browser";
+
+// src/adapters/browser-event-adapter.ts
+var BrowserEventAdapter = class {
+  emit(event) {
+    if (typeof document === "undefined") return;
+    const name = event.type === "page:submit" ? "chat-page-submit" : "chat-form-complete";
+    document.dispatchEvent(new CustomEvent(name, { detail: event, bubbles: true }));
+  }
+};
+
+// src/adapters/console-error-adapter.ts
+import {
+  ConsoleErrorAdapter as BaseConsoleErrorAdapter
+} from "@richardmcquiston01/error-log-adapter";
+var ConsoleErrorAdapter = class extends BaseConsoleErrorAdapter {
+  constructor(options = {}) {
+    super({ prefix: "[chat-and-react]", ...options });
+  }
+};
+
+// src/adapters/identity-input-adapter.ts
+var IdentityInputAdapter = class {
+  transform(raw) {
+    return raw;
+  }
+};
+
+// src/rule-engine.ts
+import jsonLogic from "json-logic-js";
+var RuleEngine = class {
+  /**
+   * 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, answers) {
+    try {
+      return Boolean(
+        jsonLogic.apply(rule, answers)
+      );
+    } catch (cause) {
+      throw { code: "RULE_EVAL_FAILED", message: "Rule evaluation failed", cause };
+    }
+  }
+};
+
 // src/schema-parser.ts
 var VALID_INPUTS = /* @__PURE__ */ new Set(["text", "textarea", "dropdown", "radio", "checkbox"]);
 var FORM_COMPLETED = "**FORM_COMPLETED**";
@@ -85,9 +135,7 @@ function validateQuestion(raw, pageId, questionIds, rules) {
     const c = condition;
     if ("ref" in c && typeof c["ref"] === "string") {
       if (!(c["ref"] in rules)) {
-        throw makeError(
-          `Question "${q["id"]}" x-chat-condition refs unknown rule "${c["ref"]}"`
-        );
+        throw makeError(`Question "${q["id"]}" x-chat-condition refs unknown rule "${c["ref"]}"`);
       }
     }
   }
@@ -96,25 +144,6 @@ function makeError(message) {
   return { code: "SCHEMA_INVALID", message };
 }
 
-// src/rule-engine.ts
-import jsonLogic from "json-logic-js";
-var RuleEngine = class {
-  /**
-   * 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, answers) {
-    try {
-      return Boolean(jsonLogic.apply(rule, answers));
-    } catch (cause) {
-      throw { code: "RULE_EVAL_FAILED", message: "Rule evaluation failed", cause };
-    }
-  }
-};
-
 // src/session-manager.ts
 var KEY_SESSION = "car:session-id";
 var keyProgress = (id) => `car:progress:${id}`;
@@ -133,10 +162,7 @@ var SessionManager = class {
   }
   saveProgress(currentPageId, answers) {
     if (!this.available) return;
-    this.storage.setItem(
-      keyProgress(this.sessionId),
-      JSON.stringify({ currentPageId, answers })
-    );
+    this.storage.setItem(keyProgress(this.sessionId), JSON.stringify({ currentPageId, answers }));
   }
   loadProgress() {
     if (!this.available) return null;
@@ -150,10 +176,7 @@ var SessionManager = class {
   }
   saveInput(questionId, value) {
     if (!this.available) return;
-    this.storage.setItem(
-      keyInput(this.sessionId, questionId),
-      JSON.stringify(value)
-    );
+    this.storage.setItem(keyInput(this.sessionId, questionId), JSON.stringify(value));
   }
   loadInput(questionId) {
     if (!this.available) return null;
@@ -198,35 +221,25 @@ var SessionManager = class {
   }
 };
 
-// src/adapters/identity-input-adapter.ts
-var IdentityInputAdapter = class {
-  transform(raw) {
-    return raw;
-  }
-};
-
-// src/adapters/browser-event-adapter.ts
-var BrowserEventAdapter = class {
-  emit(event) {
-    if (typeof document === "undefined") return;
-    const name = event.type === "page:submit" ? "chat-page-submit" : "chat-form-complete";
-    document.dispatchEvent(new CustomEvent(name, { detail: event, bubbles: true }));
-  }
-};
-
-// src/adapters/console-error-adapter.ts
-var ConsoleErrorAdapter = class {
-  log(error) {
-    console.error("[chat-and-react]", error);
-  }
-};
-
 // src/chat-controller.ts
 var DEFAULT_OPTIONS = {
   userResumable: true,
   localStorage: true,
-  autoComplete: true
+  autoComplete: true,
+  allowEdit: false,
+  autoHideQuestions: 0,
+  autoHideAnswers: 0,
+  hideAnimation: "fade",
+  typingSpeed: 0,
+  thinkingDelay: 0,
+  thinkingText: "",
+  showContinueIcon: true
 };
+function stripUndefined(source) {
+  return Object.fromEntries(
+    Object.entries(source).filter(([, value]) => value !== void 0)
+  );
+}
 var ChatController = class {
   /**
    * @param config - Controller configuration including schema and optional adapters.
@@ -239,12 +252,19 @@ var ChatController = class {
     this.currentPage = null;
     this.allAnswers = {};
     this.visitIndex = 0;
+    /** Pages submitted in this session, in visit order. Used for editing earlier answers. */
+    this.route = [];
+    /** Index in `route` of the page being edited, or null when not editing. */
+    this.editIndex = null;
+    /** The page the user was on before they started editing an earlier one. */
+    this.resumePageId = null;
     this.listeners = /* @__PURE__ */ new Map();
     this.config = {
       inputAdapter: config.inputAdapter ?? new IdentityInputAdapter(),
       outputAdapter: config.outputAdapter ?? new BrowserEventAdapter(),
       errorAdapter: config.errorAdapter ?? new ConsoleErrorAdapter(),
-      schema: config.schema
+      schema: config.schema,
+      options: config.options ?? {}
     };
     this.session = sessionManager ?? new SessionManager();
   }
@@ -259,27 +279,29 @@ var ChatController = class {
     } catch (cause) {
       this.handleFatal({ code: "ADAPTER_ERROR", message: "InputAdapter.transform() threw", cause });
     }
+    let schema;
     try {
-      this.schema = parseSchema(raw);
+      schema = parseSchema(raw);
     } catch (e) {
       this.handleFatal(e);
     }
+    this.schema = schema;
     if (!this.session.isStorageAvailable) {
-      this.config.errorAdapter.log({
+      this.logError({
         code: "STORAGE_UNAVAILABLE",
         message: "localStorage unavailable; running in memory-only mode"
       });
     }
-    const schemaOpts = this.schema["x-chat-options"] ?? {};
+    const schemaOpts = schema["x-chat-options"] ?? {};
     this.options = {
-      userResumable: schemaOpts.userResumable ?? DEFAULT_OPTIONS.userResumable,
-      localStorage: schemaOpts.localStorage ?? DEFAULT_OPTIONS.localStorage,
-      autoComplete: schemaOpts.autoComplete ?? DEFAULT_OPTIONS.autoComplete
+      ...DEFAULT_OPTIONS,
+      ...stripUndefined(schemaOpts),
+      ...stripUndefined(this.config.options)
     };
     if (this.options.userResumable) {
       const saved = this.session.loadProgress();
       if (saved) {
-        const page = this.schema["x-chat-pages"].find((p) => p.id === saved.currentPageId);
+        const page = schema["x-chat-pages"].find((p) => p.id === saved.currentPageId);
         if (page) {
           this.allAnswers = saved.answers;
           this.currentPage = page;
@@ -287,7 +309,7 @@ var ChatController = class {
         }
       }
     }
-    this.currentPage = this.schema["x-chat-pages"][0];
+    this.currentPage = schema["x-chat-pages"][0];
   }
   /**
    * Returns the page currently being presented to the user, or null if complete.
@@ -309,6 +331,38 @@ var ChatController = class {
   getOptions() {
     return { ...this.options };
   }
+  /**
+   * Returns the pages the user has submitted in this session, in visit order.
+   * A session restored from storage starts with an empty route.
+   */
+  getRoute() {
+    return this.route.map((entry) => ({ pageId: entry.pageId, answers: { ...entry.answers } }));
+  }
+  /**
+   * Returns every answer given so far, for pre-filling inputs.
+   */
+  getAnswers() {
+    return { ...this.allAnswers };
+  }
+  /**
+   * 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) {
+    if (!this.schema || !this.currentPage) return false;
+    const entry = this.route[routeIndex];
+    if (!entry) return false;
+    const page = this.schema["x-chat-pages"].find((p) => p.id === entry.pageId);
+    if (!page) return false;
+    if (this.editIndex === null) this.resumePageId = this.currentPage.id;
+    this.editIndex = routeIndex;
+    this.currentPage = page;
+    return true;
+  }
   /**
    * Submits the answers for the current page and advances the session.
    * - Accumulates answers into `allAnswers`.
@@ -316,28 +370,67 @@ var ChatController = class {
    * - 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) {
-    if (!this.currentPage || !this.schema) return;
-    this.allAnswers = { ...this.allAnswers, ...pageAnswers };
+    if (!this.currentPage || !this.schema) return "advanced";
     const pageId = this.currentPage.id;
     const currentVisitIndex = this.visitIndex;
-    const nextPageId = this.resolveBranching(this.currentPage, this.allAnswers);
+    const editedIndex = this.editIndex;
+    const isEdit = editedIndex !== null;
+    let outcome = "advanced";
+    let nextPageId;
+    let resumePageId = null;
+    if (isEdit) {
+      const entry = this.route[editedIndex];
+      const remaining = { ...this.allAnswers };
+      for (const questionId of Object.keys(entry.answers)) delete remaining[questionId];
+      this.allAnswers = { ...remaining, ...pageAnswers };
+      entry.answers = { ...pageAnswers };
+      nextPageId = this.resolveBranching(this.currentPage, this.allAnswers);
+      const expectedNextPageId = this.route[editedIndex + 1]?.pageId ?? this.resumePageId;
+      if (nextPageId === expectedNextPageId) {
+        outcome = "edit-resumed";
+        resumePageId = this.resumePageId;
+      } else {
+        outcome = "edit-rerouted";
+        for (const later of this.route.slice(editedIndex + 1)) {
+          for (const questionId of Object.keys(later.answers)) delete this.allAnswers[questionId];
+        }
+        this.route.length = editedIndex + 1;
+      }
+      this.editIndex = null;
+      this.resumePageId = null;
+    } else {
+      this.allAnswers = { ...this.allAnswers, ...pageAnswers };
+      this.route.push({ pageId, answers: { ...pageAnswers } });
+      nextPageId = this.resolveBranching(this.currentPage, this.allAnswers);
+    }
     if (this.options.userResumable) {
-      const progressPageId = nextPageId === "**FORM_COMPLETED**" ? pageId : nextPageId;
+      const progressPageId = outcome === "edit-resumed" && resumePageId ? resumePageId : nextPageId === "**FORM_COMPLETED**" ? pageId : nextPageId;
       this.session.saveProgress(progressPageId, this.allAnswers);
       const submitEvent = {
         type: "page:submit",
         sessionId: this.session.getSessionId(),
         pageId,
         visitIndex: currentVisitIndex,
-        answers: pageAnswers
+        answers: pageAnswers,
+        ...isEdit ? { edited: true } : {}
       };
       this.safeEmit(submitEvent);
       this.emit("page:submit", submitEvent);
     }
     this.visitIndex++;
+    if (outcome === "edit-resumed" && resumePageId) {
+      this.currentPage = this.schema["x-chat-pages"].find((p) => p.id === resumePageId) ?? null;
+      return outcome;
+    }
     if (nextPageId === "**FORM_COMPLETED**") {
       this.session.clearAll();
       const completeEvent = {
@@ -351,6 +444,7 @@ var ChatController = class {
     } else {
       this.currentPage = this.schema["x-chat-pages"].find((p) => p.id === nextPageId) ?? null;
     }
+    return outcome;
   }
   /**
    * Registers an event listener for the given event type.
@@ -359,8 +453,12 @@ var ChatController = class {
    * @param listener - The callback to invoke when the event fires.
    */
   on(event, listener) {
-    if (!this.listeners.has(event)) this.listeners.set(event, /* @__PURE__ */ new Set());
-    this.listeners.get(event).add(listener);
+    let listenersForEvent = this.listeners.get(event);
+    if (!listenersForEvent) {
+      listenersForEvent = /* @__PURE__ */ new Set();
+      this.listeners.set(event, listenersForEvent);
+    }
+    listenersForEvent.add(listener);
   }
   /**
    * Removes a previously registered event listener.
@@ -375,6 +473,7 @@ var ChatController = class {
    * Tears down the controller: removes all listeners and nulls internal state.
    */
   destroy() {
+    this.session.dispose?.();
     this.listeners.clear();
     this.currentPage = null;
     this.schema = null;
@@ -396,12 +495,24 @@ var ChatController = class {
       rule = condition;
     }
     try {
-      return this.ruleEngine.evaluate(rule, this.allAnswers);
+      return this.ruleEngine.evaluate(rule, this.answersForRules());
     } catch (e) {
-      this.config.errorAdapter.log(e);
+      this.logError(e);
       return false;
     }
   }
+  /**
+   * 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.
+   */
+  answersForRules() {
+    if (this.editIndex === null) return this.allAnswers;
+    const rest = { ...this.allAnswers };
+    for (const questionId of Object.keys(this.route[this.editIndex].answers))
+      delete rest[questionId];
+    return rest;
+  }
   /**
    * 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).
@@ -422,7 +533,7 @@ var ChatController = class {
     try {
       this.config.outputAdapter.emit(event);
     } catch (cause) {
-      this.config.errorAdapter.log({
+      this.logError({
         code: "ADAPTER_ERROR",
         message: `OutputAdapter.emit() threw for ${event.type}`,
         cause
@@ -433,24 +544,274 @@ var ChatController = class {
    * Notifies all registered listeners for the given event.
    */
   emit(event, payload) {
-    this.listeners.get(event)?.forEach((l) => l(payload));
+    this.listeners.get(event)?.forEach((l) => {
+      l(payload);
+    });
   }
   /**
    * Logs the error via the error adapter and then throws it.
    * Used for unrecoverable errors (schema invalid, adapter failure on start).
    */
   handleFatal(error) {
-    this.config.errorAdapter.log(error);
+    this.logError(error);
     throw error;
   }
+  /**
+   * 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.
+   */
+  logError(entry) {
+    const reportFailure = (reason) => {
+      console.error("[chat-and-react] ErrorLogAdapter failed to record an error:", reason, entry);
+    };
+    try {
+      void Promise.resolve(this.config.errorAdapter.log(entry)).then(
+        (result) => {
+          if (result?.ok === false) {
+            reportFailure(result.error);
+          }
+        },
+        reportFailure
+      );
+    } catch (cause) {
+      reportFailure(cause);
+    }
+  }
+};
+
+// src/storage/adapter-session-manager.ts
+var KEY_SESSION2 = "car:session-id";
+var keyRecord = (sessionId) => `car:session:${sessionId}`;
+var MAX_CONFLICT_RETRIES = 3;
+var emptyRecord = () => ({ progress: null, inputs: {} });
+function parseRecord(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    return {
+      progress: parsed.progress ?? null,
+      inputs: parsed.inputs && typeof parsed.inputs === "object" ? parsed.inputs : {}
+    };
+  } catch {
+    return null;
+  }
+}
+var AdapterSessionManager = class _AdapterSessionManager {
+  constructor(adapter, sessionId, available, initial, options) {
+    this.adapter = adapter;
+    this.sessionId = sessionId;
+    this.available = available;
+    this.options = options;
+    this.dirtyInputs = /* @__PURE__ */ new Set();
+    this.dirtyProgress = false;
+    this.pending = false;
+    this.persisting = null;
+    this.signal = new AbortController().signal;
+    this.unsubscribe = null;
+    const parsed = initial ? parseRecord(initial.value) : null;
+    this.record = parsed ?? emptyRecord();
+    this.revision = initial?.revision;
+    if (initial && !parsed) {
+      this.report(
+        `Saved session ${sessionId} could not be read as JSON; starting with an empty session`
+      );
+    }
+    if (available) {
+      this.unsubscribe = adapter.subscribe?.(keyRecord(sessionId), (stored) => this.applyRemote(stored)) ?? null;
+    }
+  }
+  /** Loads (or creates) the session id and its saved record, then returns the manager. */
+  static async create(adapter, options = {}) {
+    const signal = new AbortController().signal;
+    const fail = (message) => options.onError?.({ code: "STORAGE_UNAVAILABLE", message });
+    let sessionId = null;
+    let available = true;
+    const idResult = await adapter.get(KEY_SESSION2, { signal });
+    if (idResult.ok) {
+      sessionId = idResult.value?.value ?? null;
+    } else {
+      available = false;
+      fail(`Could not read the session id: ${idResult.error}. Running in memory-only mode`);
+    }
+    if (available && sessionId === null) {
+      sessionId = crypto.randomUUID();
+      const saved = await adapter.set(KEY_SESSION2, sessionId, {
+        signal
+      });
+      if (!saved.ok) {
+        available = false;
+        fail(`Could not save the session id: ${saved.error}. Running in memory-only mode`);
+      }
+    }
+    const id = sessionId ?? crypto.randomUUID();
+    let initial = null;
+    if (available) {
+      const recordResult = await adapter.get(keyRecord(id), {
+        signal
+      });
+      if (recordResult.ok) {
+        initial = recordResult.value;
+      } else {
+        available = false;
+        fail(`Could not read saved progress: ${recordResult.error}. Running in memory-only mode`);
+      }
+    }
+    return new _AdapterSessionManager(adapter, id, available, initial, options);
+  }
+  getSessionId() {
+    return this.sessionId;
+  }
+  get isStorageAvailable() {
+    return this.available;
+  }
+  saveProgress(currentPageId, answers) {
+    this.record.progress = { currentPageId, answers };
+    this.dirtyProgress = true;
+    this.schedulePersist();
+  }
+  loadProgress() {
+    return this.record.progress;
+  }
+  saveInput(questionId, value) {
+    this.record.inputs[questionId] = value;
+    this.dirtyInputs.add(questionId);
+    this.schedulePersist();
+  }
+  loadInput(questionId) {
+    return this.record.inputs[questionId] ?? null;
+  }
+  clearAll() {
+    this.record = emptyRecord();
+    this.dirtyInputs.clear();
+    this.dirtyProgress = false;
+    this.pending = false;
+    if (!this.available) return;
+    void this.removeRecord();
+  }
+  dispose() {
+    this.unsubscribe?.();
+    this.unsubscribe = null;
+  }
+  /** Resolves when every save made so far has finished. Mostly for tests. */
+  async flush() {
+    while (this.persisting) {
+      await this.persisting;
+    }
+  }
+  report(message, cause) {
+    this.options.onError?.({ code: "STORAGE_UNAVAILABLE", message, cause });
+  }
+  schedulePersist() {
+    if (!this.available) return;
+    this.pending = true;
+    this.persisting ?? (this.persisting = this.drain());
+  }
+  /** Saves until nothing is left to save. Never rejects. */
+  async drain() {
+    let conflicts = 0;
+    try {
+      while (this.pending) {
+        this.pending = false;
+        const outcome = await this.persistOnce();
+        conflicts = outcome === "conflict" ? conflicts + 1 : 0;
+        if (outcome === "conflict") {
+          if (conflicts >= MAX_CONFLICT_RETRIES) {
+            this.report(
+              `Gave up saving session ${this.sessionId} after ${conflicts} revision conflicts in a row`
+            );
+            break;
+          }
+          this.pending = true;
+        }
+      }
+    } finally {
+      this.persisting = null;
+    }
+  }
+  async persistOnce() {
+    const sentInputs = new Set(this.dirtyInputs);
+    const sentProgress = this.dirtyProgress;
+    this.dirtyInputs.clear();
+    this.dirtyProgress = false;
+    const result = await this.adapter.set(
+      keyRecord(this.sessionId),
+      JSON.stringify(this.record),
+      { signal: this.signal, ifRevision: this.revision }
+    );
+    if (result.ok) {
+      this.revision = result.value.revision;
+      return "saved";
+    }
+    for (const questionId of sentInputs) this.dirtyInputs.add(questionId);
+    this.dirtyProgress = this.dirtyProgress || sentProgress;
+    if (result.code !== "conflict") {
+      this.report(`Could not save session ${this.sessionId}: ${result.error}`);
+      return "failed";
+    }
+    const latest = await this.adapter.get(
+      keyRecord(this.sessionId),
+      { signal: this.signal }
+    );
+    if (!latest.ok) {
+      this.report(
+        `Session ${this.sessionId} changed elsewhere, but the new version could not be read: ${latest.error}`
+      );
+      return "failed";
+    }
+    this.applyRemote(latest.value);
+    return "conflict";
+  }
+  /** Merges a version written elsewhere with this tab's unsaved changes. */
+  applyRemote(stored) {
+    const before = JSON.stringify(this.record.progress);
+    if (!stored) {
+      if (!this.dirtyProgress && this.dirtyInputs.size === 0) {
+        this.record = emptyRecord();
+      }
+      this.revision = void 0;
+    } else {
+      const remote = parseRecord(stored.value);
+      if (!remote) {
+        this.report(
+          `Session ${this.sessionId} was changed elsewhere to a value that is not valid JSON; ignoring it`
+        );
+        this.revision = stored.revision;
+        return;
+      }
+      const inputs = { ...remote.inputs };
+      for (const questionId of this.dirtyInputs) {
+        const mine = this.record.inputs[questionId];
+        if (mine !== void 0) inputs[questionId] = mine;
+      }
+      this.record = {
+        progress: this.dirtyProgress ? this.record.progress : remote.progress,
+        inputs
+      };
+      this.revision = stored.revision;
+    }
+    if (JSON.stringify(this.record.progress) !== before) {
+      this.options.onExternalChange?.(this.record.progress);
+    }
+  }
+  async removeRecord() {
+    const key = keyRecord(this.sessionId);
+    const result = this.adapter.remove ? await this.adapter.remove(key, { signal: this.signal }) : await this.adapter.set(key, JSON.stringify(emptyRecord()), { signal: this.signal });
+    if (result.ok) {
+      this.revision = void 0;
+    } else {
+      this.report(`Could not clear session ${this.sessionId}: ${result.error}`);
+    }
+  }
 };
 export {
+  AdapterSessionManager,
   BrowserEventAdapter,
   ChatController,
   ConsoleErrorAdapter,
   IdentityInputAdapter,
   RuleEngine,
   SessionManager,
+  localStorageAdapter,
   parseSchema
 };
 //# sourceMappingURL=index.mjs.map