@magicx-eng/ai-autocomplete-vanilla 0.36.1 → 0.37.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`
@@ -431,11 +431,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 +501,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.
+ * Decide how a parameter should be answered — from the value type the server
+ * names on it, and nothing else.
  *
- * 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.
+ * 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.
  *
- * 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.
- *
- * 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;
 
@@ -1231,8 +1229,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

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.
+ * Decide how a parameter should be answered — from the value type the server
+ * names on it, and nothing else.
  *
- * 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.
+ * 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.
  *
- * 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.
- *
- * 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;
 
@@ -1231,8 +1229,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