@magicx-eng/ai-autocomplete-vanilla 0.36.1 → 0.38.0

package/README.md

@@ -14,7 +14,7 @@ A framework-agnostic vanilla JS/TypeScript library that provides a guided AI-pow
 - **Access token auth** — short-lived tokens with automatic refresh, single-flight deduplication, and 401 retry
 - **Keyboard navigation** — arrow keys, enter to submit, tab to autocomplete, backspace to un-bold the last completed param
 - **Client-side filtering** — instant substring filtering on every keystroke
-- **Datepicker** — date parameters are answered with a calendar instead of an option list. Click a day or navigate with the arrow keys; the date is committed the way it would be written — `Tuesday` for a date inside the next week, `March 23` for one later this year, `March 23 2027` for another year. Tapping a committed date re-opens the calendar on the month that text names now — for a weekday name, that is the next such day, not the one originally picked. A parameter whose options are written as spans (`September 11 - October 13`) gets the same calendar answered in two clicks, committed as one range.
+- **Datepicker** — date parameters are answered with a calendar instead of an option list. Click a day or navigate with the arrow keys; the date is committed the way it would be written — `Tuesday` for a date inside the next week, `March 23` for one later this year, `March 23 2027` for another year. Tapping a committed date re-opens the calendar on the month that text names now — for a weekday name, that is the next such day, not the one originally picked. A date-range parameter gets the same calendar answered in two clicks, committed as one range.
 - **Option overrides** — supply the options for a parameter yourself: a fixed list, a computed one, or one fetched from your own search endpoint as the user types
 - **Product strip** — the dropdown renders a horizontal row of product cards below the options, filled by default with the items the `/suggest` response reports as matching the query; plug in your own product search instead with `products`, or turn the strip off with `showProducts: false`
 - **Catalog report** — every response says which of the query's constraints the catalog applied, which it had to drop, and how many items are left, on `customFields` / `custom_fields`
@@ -78,6 +78,7 @@ const ac = new AIAutocomplete(container, {
   optionOverrides: { location: async (query, signal) => [...] }, // see "Option Overrides"
   columns: 2,
   maskCompletedText: false, // when true, omits completed params' text from API requests (PII masking)
+  commitOnWordEnd: false,   // true = a word still being typed never becomes a chip until a space, Enter, or Tab ends it (exact matches and server identified params). Picking an option is unchanged.
   additionalContext: { tier: "gold" }, // optional user context, to personalize suggestions and options
 
   // Appearance
@@ -431,11 +432,9 @@ new AIAutocomplete(container, { ..., submitButton: null });
 ### Datepicker
 
 When the next parameter is a date, the dropdown shows a calendar instead of a
-list of options. A parameter counts as a date when its name says so, or when at
-least three of the options it offers are themselves written as dates — so a
-parameter called `when` or `arrival` still gets a calendar. Options written as
-relative phrases (`today`, `next week`) are not read as dates; a parameter
-offering those needs a name that says date.
+list of options. Which parameters are dates is the server's call: one whose
+`type` is `date` gets a calendar, and one without a date type keeps its option
+list, however date-like its name or options look.
 
 Nothing is required to switch it on — a date parameter renders this way
 automatically, and every other parameter is unaffected. Tier 1 and Tier 2 render
@@ -503,19 +502,15 @@ say which, and phrases like `next friday`. Those still open the calendar, just
 on the current month with nothing marked, so the user picks rather than being
 shown a guess that might be wrong.
 
-**Date ranges.** A parameter whose options are written as spans — `September 11
-- October 13`, `September 11 to November 16` — is answered by the same calendar
-in two clicks: the first sets the start, the second the end, and the pair
+**Date ranges.** A parameter whose `type` is `date_range` is answered by the
+same calendar in two clicks: the first sets the start, the second the end, and the pair
 commits as one answer. The days between them band as the user moves across the
 calendar, so the span being chosen is visible before it is committed. Paging the
 month between the two clicks is expected — that is how a span crosses months —
 and <kbd>Esc</kbd> drops the start and lets them begin again. Clicking the end
 before the start is fine; the two are ordered on the way in.
 
-The span is read off the options the same way a single date is read off its own:
-either separator (`-`, `–`, `—`, `to`, `through`, `until`), either half in any
-date format the SDK reads, and a name that says so (`date_range`, `dateRange`)
-counts too. It commits as one parameter, written the way it was offered —
+It commits as one parameter, written as a span —
 `September 11 - October 13`, with the year on whichever end needs it — and both
 ends are also recorded on the completed parameter's `metadata` as `YYYY-MM-DD`,
 under the `DATE_RANGE_META_START` / `DATE_RANGE_META_END` keys this package

package/dist/index.d.mts

@@ -57,8 +57,9 @@ interface SuggestionOption {
     parameter?: string;
 }
 /**
- * The value type of a suggestion's parameter — which picker it needs. Present
- * only for a date or date-range parameter.
+ * The value type of a parameter — which picker it needs. The server sends it
+ * for every date or date-range parameter; a parameter without one is answered
+ * from its options.
  */
 interface SuggestionType {
     kind: "string" | "numeric" | "date" | "date_range" | "boolean";
@@ -81,6 +82,11 @@ interface InputItem {
     state: "completed" | "in_progress";
     /** Absent or "selected" = echo of client params; "identified" = LLM-inferred. */
     source?: "selected" | "identified";
+    /**
+     * The value type of the parameter this span was identified as. A span whose
+     * type names a date or date range opens a calendar when tapped.
+     */
+    type?: SuggestionType;
 }
 /** Wire shape for an LLM-identified param echoed back to the server. */
 interface IdentifiedParam {
@@ -295,6 +301,8 @@ interface IdentifiedParamState {
     id: string;
     parameter: string;
     text: string;
+    /** The span's value type, from its `input` item. */
+    type?: SuggestionType;
 }
 type Segment = {
     type: "text";
@@ -592,30 +600,20 @@ type FormatType = "options" | "date" | "date-range";
 /** Whether this format is answered by a calendar rather than by a list. */
 declare function isCalendarFormat(format: FormatType): boolean;
 /**
- * Decide how a suggestion should be answered.
- *
- * The server cannot send a `formatType` yet, so a suggestion that holds a date
- * is detected here — by the options it offers, and failing that by its name —
- * and rendered as a calendar with those options ignored.
+ * Decide how a parameter should be answered — from the value type the server
+ * names on it, and nothing else.
  *
- * The detection is deliberately the LAST resort. A `formatType` that *is* on
- * the wire always wins, so the day the server starts sending one this function
- * needs a single block deleted — the datepicker itself, and every gate that
- * consults this, keep working untouched.
+ * The server sets `type` on every date and date-range parameter, so one
+ * without it is an option list, whatever its name, options or text look like.
+ * The SDK never guesses: guessing from options read a "Ring size" offering
+ * "4.75", "7.25" and "8.5" as three dates and replaced its sizes with a
+ * calendar.
  *
- * Options are read before the name because they are the stronger evidence:
- * they are the values themselves, while a name is what someone chose to call
- * them. A parameter called `travel_date` whose options are all spans is a span
- * parameter, whatever its name says.
- *
- * Accepts anything with a `parameter`, not a `Suggestion`, so re-edit can ask
- * the same question about a completed param via its `suggestionParameter`.
- * A suggestion whose `type` names a date or date-range parameter is that,
- * whatever its options and name say.
+ * Accepts anything with a `type`, not a `Suggestion`, so re-edit can ask the
+ * same question about a completed param via its `suggestionValueType`, and an
+ * identified span via its own `type`.
  */
 declare function resolveFormatType(source: {
-    parameter: string;
-    options?: SuggestionOption[];
     type?: SuggestionType;
 } | undefined | null): FormatType;
 
@@ -925,6 +923,8 @@ interface CoreOptions {
     apiConfig?: APIConfig;
     optionOverrides?: OptionOverrides;
     maskCompletedText?: boolean;
+    /** When true, a word the user is still typing never becomes a chip. The word becomes a chip when it ends: a space, Enter, or Tab. Default: false. */
+    commitOnWordEnd?: boolean;
     /**
      * Optional user context. Include whatever you know about the user — a
      * profile, preferences, workspace, anything — to personalize suggested
@@ -1136,6 +1136,10 @@ declare class AIAutocomplete {
     private funnelTelemetry;
     /** A `search_started` that happened before any response said whether to send it. */
     private pendingSearchStarted;
+    /** The text at the last user keystroke, while its last word is still open. */
+    private openWordText;
+    /** Identified params held back until the word they end ends. */
+    private heldIdentified;
     /** What the last `impression` showed, so an identical response doesn't resend it. */
     private lastImpressionKey;
     private readonly emitSubmit;
@@ -1231,8 +1235,8 @@ declare class AIAutocomplete {
     /**
      * Open the calendar for a span the server identified as a date.
      *
-     * Returns false for anything else — an identified span whose type isn't a
-     * date stays inert, exactly as every identified span did before.
+     * Returns false for anything else — an identified span whose `type` the
+     * server didn't name as a date or date range stays inert.
      *
      * The span's own text is read for a starting month (`parseLooseDate`), but
      * failing to read it is not a failure: the calendar opens either way, and
@@ -1382,6 +1386,14 @@ declare class AIAutocomplete {
     private subscribeSkeletonMirror;
     private subscribeNewParamTimer;
     private handleChange;
+    /** True while commitOnWordEnd is on and the user still types the last word. */
+    private isWordOpen;
+    private admitIdentified;
+    /**
+     * Ends the word the user is typing. Makes the chip for an exact match and
+     * admits the held identified params. Returns true when it changed anything.
+     */
+    private endTypedWord;
     /**
      * Opens the pending span on the first keystroke past covered text: there is
      * unresolved trailing text beyond the covered offset (filterBase / last pill

package/dist/index.d.ts

@@ -57,8 +57,9 @@ interface SuggestionOption {
     parameter?: string;
 }
 /**
- * The value type of a suggestion's parameter — which picker it needs. Present
- * only for a date or date-range parameter.
+ * The value type of a parameter — which picker it needs. The server sends it
+ * for every date or date-range parameter; a parameter without one is answered
+ * from its options.
  */
 interface SuggestionType {
     kind: "string" | "numeric" | "date" | "date_range" | "boolean";
@@ -81,6 +82,11 @@ interface InputItem {
     state: "completed" | "in_progress";
     /** Absent or "selected" = echo of client params; "identified" = LLM-inferred. */
     source?: "selected" | "identified";
+    /**
+     * The value type of the parameter this span was identified as. A span whose
+     * type names a date or date range opens a calendar when tapped.
+     */
+    type?: SuggestionType;
 }
 /** Wire shape for an LLM-identified param echoed back to the server. */
 interface IdentifiedParam {
@@ -295,6 +301,8 @@ interface IdentifiedParamState {
     id: string;
     parameter: string;
     text: string;
+    /** The span's value type, from its `input` item. */
+    type?: SuggestionType;
 }
 type Segment = {
     type: "text";
@@ -592,30 +600,20 @@ type FormatType = "options" | "date" | "date-range";
 /** Whether this format is answered by a calendar rather than by a list. */
 declare function isCalendarFormat(format: FormatType): boolean;
 /**
- * Decide how a suggestion should be answered.
- *
- * The server cannot send a `formatType` yet, so a suggestion that holds a date
- * is detected here — by the options it offers, and failing that by its name —
- * and rendered as a calendar with those options ignored.
+ * Decide how a parameter should be answered — from the value type the server
+ * names on it, and nothing else.
  *
- * The detection is deliberately the LAST resort. A `formatType` that *is* on
- * the wire always wins, so the day the server starts sending one this function
- * needs a single block deleted — the datepicker itself, and every gate that
- * consults this, keep working untouched.
+ * The server sets `type` on every date and date-range parameter, so one
+ * without it is an option list, whatever its name, options or text look like.
+ * The SDK never guesses: guessing from options read a "Ring size" offering
+ * "4.75", "7.25" and "8.5" as three dates and replaced its sizes with a
+ * calendar.
  *
- * Options are read before the name because they are the stronger evidence:
- * they are the values themselves, while a name is what someone chose to call
- * them. A parameter called `travel_date` whose options are all spans is a span
- * parameter, whatever its name says.
- *
- * Accepts anything with a `parameter`, not a `Suggestion`, so re-edit can ask
- * the same question about a completed param via its `suggestionParameter`.
- * A suggestion whose `type` names a date or date-range parameter is that,
- * whatever its options and name say.
+ * Accepts anything with a `type`, not a `Suggestion`, so re-edit can ask the
+ * same question about a completed param via its `suggestionValueType`, and an
+ * identified span via its own `type`.
  */
 declare function resolveFormatType(source: {
-    parameter: string;
-    options?: SuggestionOption[];
     type?: SuggestionType;
 } | undefined | null): FormatType;
 
@@ -925,6 +923,8 @@ interface CoreOptions {
     apiConfig?: APIConfig;
     optionOverrides?: OptionOverrides;
     maskCompletedText?: boolean;
+    /** When true, a word the user is still typing never becomes a chip. The word becomes a chip when it ends: a space, Enter, or Tab. Default: false. */
+    commitOnWordEnd?: boolean;
     /**
      * Optional user context. Include whatever you know about the user — a
      * profile, preferences, workspace, anything — to personalize suggested
@@ -1136,6 +1136,10 @@ declare class AIAutocomplete {
     private funnelTelemetry;
     /** A `search_started` that happened before any response said whether to send it. */
     private pendingSearchStarted;
+    /** The text at the last user keystroke, while its last word is still open. */
+    private openWordText;
+    /** Identified params held back until the word they end ends. */
+    private heldIdentified;
     /** What the last `impression` showed, so an identical response doesn't resend it. */
     private lastImpressionKey;
     private readonly emitSubmit;
@@ -1231,8 +1235,8 @@ declare class AIAutocomplete {
     /**
      * Open the calendar for a span the server identified as a date.
      *
-     * Returns false for anything else — an identified span whose type isn't a
-     * date stays inert, exactly as every identified span did before.
+     * Returns false for anything else — an identified span whose `type` the
+     * server didn't name as a date or date range stays inert.
      *
      * The span's own text is read for a starting month (`parseLooseDate`), but
      * failing to read it is not a failure: the calendar opens either way, and
@@ -1382,6 +1386,14 @@ declare class AIAutocomplete {
     private subscribeSkeletonMirror;
     private subscribeNewParamTimer;
     private handleChange;
+    /** True while commitOnWordEnd is on and the user still types the last word. */
+    private isWordOpen;
+    private admitIdentified;
+    /**
+     * Ends the word the user is typing. Makes the chip for an exact match and
+     * admits the held identified params. Returns true when it changed anything.
+     */
+    private endTypedWord;
     /**
      * Opens the pending span on the first keystroke past covered text: there is
      * unresolved trailing text beyond the covered offset (filterBase / last pill