@magicx-eng/ai-autocomplete-vanilla 0.29.0 → 0.31.0

package/README.md

@@ -124,6 +124,10 @@ const ac = new AIAutocomplete(container, {
   // - HTMLElement: replaces the default button. Click events bubble up and trigger submit.
   submitButton: undefined,
 
+  // Clear the input and start a new session after onSubmit (Tier 1 only).
+  // false keeps the query in place — e.g. when onSubmit navigates away.
+  resetOnSubmit: true,
+
   // Events
   onSubmit: (result) => { ... },
   onResult: (result) => { ... },           // after every successful round-trip — see "Reading the query as it's built"
@@ -162,7 +166,7 @@ ac.selectProduct(product);     // Emit onProductSelect (Tier 3 / custom strips)
 ac.getResult();                // The AutocompleteResult as it stands right now
 ```
 
-> **Tier 1 auto-resets** after both Enter key and built-in submit-button clicks — your `onSubmit` runs, then the SDK clears the input and starts a new session. You don't need to call `ac.reset()` yourself in Tier 1.
+> **Tier 1 auto-resets** after both Enter key and built-in submit-button clicks — your `onSubmit` runs, then the SDK clears the input and starts a new session. You don't need to call `ac.reset()` yourself in Tier 1. Pass `resetOnSubmit: false` to keep the query in place instead — useful when `onSubmit` navigates to a results page, where a cleared field would flash empty until the next page paints — and call `ac.reset()` yourself when you want a fresh session.
 
 > `autoFocus`, `focus()`, and `blur()` only operate on the contentEditable editor the library owns (Tier 1 / `renderMode: "full"`). In Tier 2/3, the consumer owns the input and calls `.focus()` / `.blur()` on their own element; the `onFocus` / `onBlur` callbacks still fire whenever `setFocused()` is called.
 
@@ -948,7 +952,7 @@ The vanilla core also exposes stable BEM class names (`magicx-aia-*`); both can
 
 Every `/api/suggest` request carries a `meta.session_id` UUID. A session runs from instance construction (or the last `reset()`) until the next `reset()`. All requests in one session share the same `session_id`; calling `reset()` starts a new one.
 
-- **Tier 1 (`renderMode: "full"`)** — the SDK auto-resets after both Enter key and built-in submit-button clicks. Your `onSubmit` runs first, then the SDK clears the input and starts a new session.
+- **Tier 1 (`renderMode: "full"`)** — the SDK auto-resets after both Enter key and built-in submit-button clicks. Your `onSubmit` runs first, then the SDK clears the input and starts a new session. With `resetOnSubmit: false` it doesn't, and the session continues until you call `reset()`.
 - **Tier 2/3 (`renderMode: "dropdown" | "headless"`)** — you own the input and submit flow, so you must call `ac.reset()` yourself from your `onSubmit` handler (or from your custom submit button after firing `onSubmit`).
 
 > **Why it matters:** suggestions get sharper as a query develops. Each one

package/dist/index.d.mts

@@ -941,6 +941,14 @@ interface CoreOptions {
      * arrow button. Clicks on the provided element bubble up and trigger submit.
      */
     submitButton?: HTMLElement | null;
+    /**
+     * Tier 1 ("full") only. When true (default), the input is cleared and a new
+     * session starts after `onSubmit` runs — on Enter and on the submit button.
+     * Set to false to leave the query in place: when `onSubmit` navigates away,
+     * a cleared field flashes empty until the next page paints. Call `reset()`
+     * yourself when you want a fresh session. Tiers 2/3 never auto-reset.
+     */
+    resetOnSubmit?: boolean;
     /**
      * When true (default), the dropdown renders a horizontal row of product
      * cards below the options grid whenever it has products to show: by default
@@ -1062,6 +1070,8 @@ declare class AIAutocomplete {
     focus(): void;
     blur(): void;
     reset(): void;
+    /** Tier 1's post-submit reset. Read at call time so `update()` can flip it. */
+    private resetAfterSubmit;
     destroy(): void;
     setMode(mode: AppearanceMode): void;
     setValue(text: string): void;
@@ -1157,6 +1167,13 @@ declare class AIAutocomplete {
     handleCaretAfterInput(offset: number | null): void;
     handleCaretMove(offset: number | null): void;
     setActiveDropdownIndex(index: number): void;
+    /**
+     * The pointer left option `index`: clear the highlight if it is still on
+     * that option. A hover highlight that outlived the hover made Enter pick an
+     * option the pointer was no longer on instead of submitting the search. A
+     * highlight the keyboard has since moved elsewhere is left alone.
+     */
+    clearHighlight(index: number): void;
     /**
      * Announce a product selection. The rendered cards call this on activation;
      * headless consumers rendering their own strip call it themselves.

package/dist/index.d.ts

@@ -941,6 +941,14 @@ interface CoreOptions {
      * arrow button. Clicks on the provided element bubble up and trigger submit.
      */
     submitButton?: HTMLElement | null;
+    /**
+     * Tier 1 ("full") only. When true (default), the input is cleared and a new
+     * session starts after `onSubmit` runs — on Enter and on the submit button.
+     * Set to false to leave the query in place: when `onSubmit` navigates away,
+     * a cleared field flashes empty until the next page paints. Call `reset()`
+     * yourself when you want a fresh session. Tiers 2/3 never auto-reset.
+     */
+    resetOnSubmit?: boolean;
     /**
      * When true (default), the dropdown renders a horizontal row of product
      * cards below the options grid whenever it has products to show: by default
@@ -1062,6 +1070,8 @@ declare class AIAutocomplete {
     focus(): void;
     blur(): void;
     reset(): void;
+    /** Tier 1's post-submit reset. Read at call time so `update()` can flip it. */
+    private resetAfterSubmit;
     destroy(): void;
     setMode(mode: AppearanceMode): void;
     setValue(text: string): void;
@@ -1157,6 +1167,13 @@ declare class AIAutocomplete {
     handleCaretAfterInput(offset: number | null): void;
     handleCaretMove(offset: number | null): void;
     setActiveDropdownIndex(index: number): void;
+    /**
+     * The pointer left option `index`: clear the highlight if it is still on
+     * that option. A hover highlight that outlived the hover made Enter pick an
+     * option the pointer was no longer on instead of submitting the search. A
+     * highlight the keyboard has since moved elsewhere is left alone.
+     */
+    clearHighlight(index: number): void;
     /**
      * Announce a product selection. The rendered cards call this on activation;
      * headless consumers rendering their own strip call it themselves.