@magicx-eng/ai-autocomplete-vanilla 0.13.0 → 0.14.0

package/README.md

@@ -14,6 +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 as `MONTH DAY YEAR` (e.g. `March 23 2026`). Tapping a committed date re-opens the calendar on the month it holds.
 - **Option overrides** — inject or dynamically generate client-side options per suggestion type
 - **Product strip (opt-in)** — plug in any platform's product search and the dropdown renders a horizontal row of product cards below the options; the SDK owns the UI, your integration owns only `fetch` and `transform`
 - **Controlled & uncontrolled** — works out of the box or integrates with external state
@@ -76,7 +77,6 @@ const ac = new AIAutocomplete(container, {
   columns: 2,
   maskCompletedText: false, // when true, omits completed params' text from API requests (PII masking)
   additionalContext: { tier: "gold" }, // optional user context, to personalize suggestions and options
-  generateStartingStateOptions: false, // true = each time the query is empty, generate fresh initial suggestions (personalized when additionalContext is set) instead of the fixed defaults
 
   // Appearance
   mode: "auto",               // "light" | "dark" | "auto"
@@ -261,6 +261,72 @@ new AIAutocomplete(container, {
 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.
+
+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
+the calendar for you; in Tier 3 the same data reaches your own renderer (see
+[Tier 3](#tier-3-headless)).
+
+**What the user can do**
+
+| Input | Result |
+|---|---|
+| Click a day | Commits that date |
+| <kbd>↓</kbd> | Moves into the calendar, starting on today |
+| <kbd>←</kbd> / <kbd>→</kbd> | Previous / next day, crossing week boundaries |
+| <kbd>↑</kbd> / <kbd>↓</kbd> | Previous / next week. Past either end of the month, focus returns to the input |
+| <kbd>Enter</kbd> | Commits the highlighted day |
+| Month arrows | Page the calendar. Paging never commits anything |
+| <kbd>→</kbd> at the end of the input | Skips the parameter, same as any other pill |
+
+**The committed value** is always `MONTH DAY YEAR` in English — `March 23 2026`
+— regardless of the visitor's locale, so the value you receive has one shape
+everywhere. It arrives as an ordinary completed parameter: bold in the input,
+and present in `completed_params` on submit like any other answer.
+
+**Re-editing** a committed date re-opens the calendar on that date's month with
+the day marked, so changing an answer takes one click.
+
+**Reading the value back.** The date arrives as text, so if you need a `Date`
+object, `parseDate` is exported for it:
+
+```ts
+import { parseDate } from "@magicx-eng/ai-autocomplete-vanilla";
+
+const due = parseDate("March 23 2026"); // Date, or null if the text isn't one of ours
+```
+
+`parseLooseDate` is exported too, for the looser shapes a person types into a
+query — it reads `september 5th`, `5th September`, `Sept 5` and `2026-09-05`,
+and answers `null` for anything ambiguous rather than guessing.
+
+**Dates the user writes themselves.** When someone types a date into their query
+— "fly to vegas on september 5th" — the parameter it answers is recognised in
+place and the date becomes tappable. Tapping it opens the calendar on that
+month with the day already marked, so confirming or changing it takes one tap,
+and the picked date replaces their words with the canonical form.
+
+The written date is read where it can be: `september 5th`, `5th September`,
+`Sept 5`, `September 5, 2026` and `2026-09-05` all resolve, in any of those
+orders and with or without the year (a date with no year means its next
+occurrence). Two cases deliberately don't pre-select — a numeric date like
+`09/05`, which is September 5th in the US and May 9th elsewhere with nothing to
+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.
+
+**Typing** while the calendar is open does not filter it. The text is treated as
+a new query, so suggestions refresh as the user types — useful when someone
+would rather describe what they want than pick a day.
+
 ---
 
 ## Tier 2: Dropdown Only
@@ -345,6 +411,8 @@ unsub();
 
 > **Custom (rich-text) editors:** the wiring above assumes `myInput` is a `<textarea>`/`<input>`, whose caret the library reads directly. If you're driving a contentEditable or rich-text editor instead, also call `ac.handleCaretMove(offset)` on selection changes (with the caret as a plain-text offset) so arrow keys can move from the input into the dropdown.
 
+
+> **Datepicker in a custom UI.** For a date parameter, `state.activeFormatType` is `"date"` and `state.filteredOptions` holds that month's day cells. Each cell's `text` is the date it commits (`"March 23 2026"`), so rendering them as a plain list already works — `selectOption(cell)` behaves exactly as it does for an option. To draw an actual calendar, read `state.dateView` for the month on show, `cellDay(cell)` for the number to paint, and call `showPreviousMonth()` / `showNextMonth()` to page. Cells that pad the start and end of the month have `is_tappable: false`.
 ### State shape (`CoreState`)
 
 | Field | Type | Description |
@@ -353,7 +421,9 @@ unsub();
 | `completedParams` | `CompletedParamState[]` | Filled parameters |
 | `suggestions` | `Suggestion[]` | All suggestions from server (including placeholder type) |
 | `actionableSuggestions` | `Suggestion[]` | Non-placeholder suggestions (the pills) |
-| `filteredOptions` | `SuggestionOption[]` | Options for the active suggestion, filtered by current query |
+| `filteredOptions` | `SuggestionOption[]` | Options for the active suggestion, filtered by current query. For a date parameter these are the visible month's day cells instead — each cell's `text` is the date it commits (`"March 23 2026"`), and cells padding the start/end of the month have `is_tappable: false`. |
+| `activeFormatType` | `"options" \| "date"` | How the active parameter is answered: pick an option, or pick a date. `"date"` shows a calendar instead of the option list. Typing does not filter it — the text is treated as a new query. |
+| `dateView` | `DateMonthView \| null` | The month the calendar is showing (`{ year, month }`, 0-based month). Null unless `activeFormatType` is `"date"`. |
 | `segments` | `Segment[]` | Input text split into typed text vs completed params — completed segments render as bold `<strong>` runs inside the editor |
 | `placeholderText` | `string` | Placeholder text from server suggestions (joined `placeholder`-type suggestion texts) |
 | `activeDropdownIndex` | `number` | Highlighted option index (-1 = none) |
@@ -371,6 +441,7 @@ unsub();
 | Method | Description |
 |---|---|
 | `handleTextChange(value)` | Call when user types. Handles capitalization, param reconciliation, filter updates. |
+| `showPreviousMonth()` / `showNextMonth()` | Page the calendar a month at a time; paging never commits anything. Tier 1 and Tier 2 wire the built-in month arrows to these, so you only need them for a hand-rolled calendar. No-ops unless the active parameter is a date. Moving on to a different parameter resets the calendar to the current month. |
 | `handleKeyDown(event)` | Forward keyboard events. Handles arrow nav, Enter, Tab, Escape. |
 | `setFocused(focused)` | Notify the library that the input has focus. Required for `dropdownTrigger: "auto"` in Tier 2/3 — the dropdown only opens while focused. |
 | `handleCaretMove(offset)` | Report the caret position (plain-text offset). For a **custom editor** that isn't a `<textarea>`/`<input>` (e.g. contentEditable / rich-text), this is what lets arrow keys move into the dropdown. The library reads a `<textarea>`/`<input>`'s caret directly, so you only need this for custom editors. |
@@ -528,6 +599,13 @@ Override these on the container element. All built-in defaults use `:where()` (z
 | `--aia-product-price-font-size` | `11px` | `11px` | Product price font size. |
 | `--aia-product-vendor-font-size` | `10px` | `10px` | Product vendor font size. |
 | `--aia-products-label-font-size` | `11px` | `11px` | Section label font size. |
+| `--aia-date-cell-size` | `36px` | `36px` | Size of a day's square — the box that carries the highlight, the today ring and the selected fill. |
+| `--aia-date-row-height` | `40px` | `40px` | Height of one week row. Lower it to fit a 6-week month in a shorter dropdown. |
+| `--aia-date-cell-font-size` | `14px` | `14px` | Day-number font size. |
+| `--aia-date-month-font-size` | `14px` | `14px` | Font size of the "March 2026" header. |
+| `--aia-date-weekday-font-size` | `11px` | `11px` | Font size of the S/M/T/W/T/F/S column letters. |
+| `--aia-date-today-ring` | `--aia-option-color` | `--aia-option-color` | Outline drawn around today's date. |
+| `--aia-date-selected-bg` | white at 12% | white at 12% | Fill behind the date a re-edited parameter already holds. |
 | `--aia-skeleton-bg` | `rgba(189, 189, 189, 0.25)` | `#1a1b1d` | Fill color for the loading skeleton bars and the masked text in cached pills/options. |
 
 ### Per-mode Overrides
@@ -564,6 +642,11 @@ For styling beyond the CSS variables, target these stable `data-aia-*` attribute
 | `[data-aia-skip]` | The pill bar's trailing "skip" button. Tune via `--aia-skip-font-size` / `--aia-skip-color` / `--aia-skip-color-hover` / `--aia-skip-hover-bg` |
 | `[data-aia-option]` | Each suggestion option |
 | `[data-aia-dropdown]` | The dropdown root (listbox). Carries `data-aia-has-products` while the product strip has cards. |
+| `[data-aia-datepicker]` | The calendar, rendered in place of the option list for a date parameter |
+| `[data-aia-date-month]` | The "March 2026" header label |
+| `[data-aia-date-prev]` / `[data-aia-date-next]` | The month arrows |
+| `[data-aia-date-grid]` | The 7-column grid of day cells |
+| `[data-aia-date-cell]` | Each day cell. Also carries `[data-aia-option]`, so option-level styling applies to both bodies |
 | `[data-aia-products]` | Product strip section (label + row) |
 | `[data-aia-products-row]` | The horizontally scrolling row of cards |
 | `[data-aia-product]` | Each product card |
@@ -591,7 +674,20 @@ Every `/api/suggest` request carries a `meta.session_id` UUID. A session runs fr
 - **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 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:** the server uses `session_id` to track each session's history — what the user has been typing sequentially, which options they've selected, and how the query evolved. That context lets the model produce better, more relevant suggestions on subsequent requests within the same session. Calling `reset()` at the right moment (when the user actually submits) keeps that history accurate, so your users get higher-quality results.
+> **Why it matters:** suggestions get sharper as a query develops. Each one
+> takes account of what the user has already answered, so the parameters offered
+> late in a query are shaped by the choices made early in it — that is what makes
+> the experience feel guided rather than like a static list. `session_id` is what
+> ties those requests together into one query.
+>
+> So `reset()` is not bookkeeping: it is how you say "that query is finished".
+> Skip it and the next query is treated as a continuation of the last one, and
+> its suggestions keep being shaped by answers the user has already moved on
+> from — the failure is quiet, and shows up as steadily less relevant options
+> rather than as an error.
+
+The id is a plain UUID. Log it next to your own request logs if you want to
+correlate a user's report with the query that produced it.
 
 ```ts
 // Tier 2/3 — call reset() yourself

package/dist/index.d.mts

@@ -47,12 +47,6 @@ interface AutocompleteRequest {
         recently_suggested?: RecentlySuggested[];
         contact_account_count?: number;
         additional_context?: Record<string, unknown>;
-        /**
-         * When true, an empty `raw_query`'s initial suggestions are generated
-         * fresh instead of the fixed defaults. Absent or false keeps the default
-         * behavior.
-         */
-        generate_starting_state_options?: boolean;
     };
     meta: {
         request_id: string;
@@ -220,6 +214,91 @@ interface AutocompleteResult {
     completed_params: CompletedParam[];
 }
 
+/** A calendar month on screen. `month` is 0-based, matching `Date#getMonth`. */
+interface DateMonthView {
+    year: number;
+    month: number;
+}
+/** Sunday-first, matching `Date#getDay`. */
+declare const WEEKDAY_LABELS: string[];
+/**
+ * `YYYY-MM-DD` from the date's LOCAL components.
+ *
+ * Not `toISOString()`, which converts to UTC first: for any user behind UTC
+ * that shifts the calendar date back a day, so clicking "March 23" west of
+ * Greenwich would produce `2026-03-22`.
+ */
+declare function isoDate(d: Date): string;
+/** The committed form of a date: "March 23 2026". */
+declare function formatDate(d: Date): string;
+/**
+ * Inverse of {@link formatDate}, for re-opening the calendar on the month a
+ * completed date param already holds. Returns null for anything else — the
+ * caller falls back to the current month.
+ */
+declare function parseDate(text: string | undefined | null): Date | null;
+/** "March 2026" — the calendar header. */
+declare function monthLabel(view: DateMonthView): string;
+/** Step the view by whole months, rolling the year over at either end. */
+declare function addMonths(view: DateMonthView, delta: number): DateMonthView;
+/**
+ * A month laid out as `SuggestionOption`s — leading blanks, one cell per day,
+ * trailing blanks to complete the last week. Always a whole number of 7-cell
+ * rows.
+ *
+ * Modelling calendar cells as options is what makes the datepicker cheap: they
+ * flow through `filteredOptions`, so the existing keyboard controller, the
+ * `${listboxId}-option-${i}` id scheme, `aria-activedescendant` and — above all
+ * — `selectOption`'s entire commit path work on them unchanged. At 7 columns
+ * the grid's own column-major traversal already *is* calendar navigation
+ * (→ = +1 day, ↓ = +7 days).
+ *
+ * Each day cell's `text` is the committed value ("March 23 2026"), NOT its
+ * label: `computeSelectionPatch` commits `option.text` verbatim, so the value
+ * has to live there. The renderer reads `metadata.aiaDay` for the "23" it
+ * paints. Padding cells are non-tappable, which is what stops arrow navigation
+ * from landing on them.
+ */
+declare function buildDateOptions(view: DateMonthView): SuggestionOption[];
+/**
+ * The `YYYY-MM-DD` a completed date param already holds, so the calendar can
+ * mark that cell as the current answer while it is being re-edited. Null for
+ * text that isn't one of our dates.
+ */
+declare function selectedIsoFromText(text: string | undefined | null): string | null;
+/** A cell's `YYYY-MM-DD`, or null if it's padding. */
+declare function cellIso(option: SuggestionOption | undefined): string | null;
+/** A cell's day-of-month, or null if it's padding. */
+declare function cellDay(option: SuggestionOption | undefined): number | null;
+
+/**
+ * How the dropdown lets the user answer a suggestion.
+ *
+ * `"options"` is every suggestion the server has ever sent: pick one of its
+ * options, or type to filter them. `"date"` ignores the options entirely and
+ * renders a calendar instead.
+ */
+type FormatType = "options" | "date";
+/**
+ * Decide how a suggestion should be answered.
+ *
+ * The server cannot send a `formatType` yet, so a suggestion whose `type` names
+ * a date is detected here by its name and rendered as a calendar with its
+ * options ignored.
+ *
+ * That name check 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 line deleted — the datepicker itself, and every gate that
+ * consults this, keep working untouched.
+ *
+ * Accepts anything with a `type`, not a `Suggestion`, so re-edit can ask the
+ * same question about a completed param via its `suggestionType`.
+ */
+declare function resolveFormatType(source: {
+    type: string;
+    options?: SuggestionOption[];
+} | undefined | null): FormatType;
+
 /**
  * Raw, user/network/internal-driven fields. The store holds *only* these —
  * derived state is recomputed lazily on read. See {@link CoreDerivedState}.
@@ -292,6 +371,48 @@ interface CoreInputState {
      * Set by selectOption / ReEditManager.selectOption, cleared by a timer.
      */
     inSelectionAnimation: boolean;
+    /**
+     * Which month the datepicker is showing, when one is showing at all.
+     *
+     * `key` scopes the view to the pill it was opened for (see `dateViewKey` in
+     * `derive/state.ts`). A stale key is ignored rather than cleared, so moving
+     * to a different date pill starts at the default month without any of the
+     * flows that change the active pill — selection, skip, a landing response,
+     * re-edit — having to remember to reset this.
+     */
+    dateViewMonth: (DateMonthView & {
+        key: string;
+    }) | null;
+    /**
+     * Set while the user is picking a date for a span the server identified as
+     * one — "september 5th" in "fly to vegas on september 5th".
+     *
+     * Held apart from `editingParam` rather than folded into it. An identified
+     * span is not a completed param: it has no cached options, it lives in
+     * `identifiedParams`, and the re-edit paths that read `editingParam` all
+     * assume otherwise. Reusing that field would have meant auditing every one
+     * of them for a shape they were never written for.
+     *
+     * `iso` is the date the span's text was read as, or null when it could not be
+     * read with confidence (see `parseLooseDate`). Null costs only the
+     * pre-selection — the calendar still opens.
+     */
+    editingIdentified: {
+        id: string;
+        /** The identified param's type, which the committed param inherits. */
+        type: string;
+        /** Plain-text offsets bounding the span being replaced. */
+        anchor: number;
+        tail: number;
+        /**
+         * The span's text when the picker opened. Re-checked against those offsets
+         * before anything is spliced — if the input changed underneath, they no
+         * longer bound the span and writing at them would corrupt an unrelated
+         * part of the query.
+         */
+        text: string;
+        iso: string | null;
+    } | null;
 }
 /**
  * Derived fields recomputed from {@link CoreInputState} + {@link CoreOptions}.
@@ -301,7 +422,23 @@ interface CoreInputState {
 interface CoreDerivedState {
     segments: Segment[];
     actionableSuggestions: Suggestion[];
+    /**
+     * What the dropdown renders. Options for the active pill, filtered by what
+     * the user typed — EXCEPT when `activeFormatType` is `"date"`, where these
+     * are the visible month's calendar cells and the server's own options for
+     * that suggestion are ignored. See {@link buildDateOptions}.
+     */
     filteredOptions: SuggestionOption[];
+    /**
+     * How the active pill is answered: pick an option, or pick a date. Anything
+     * that reasons about options has to consult this — the server still *sends*
+     * options for a date suggestion, so code that only looks at `filteredOptions`
+     * would keep acting on options the user can't see (see the filter-zone and
+     * exact-match gates in `fetchController`).
+     */
+    activeFormatType: FormatType;
+    /** The month the datepicker is showing. Null unless `activeFormatType` is `"date"`. */
+    dateView: DateMonthView | null;
     placeholderText: string;
     isDropdownOpen: boolean;
     /**
@@ -340,13 +477,6 @@ interface CoreOptions {
      * parameters and options to them.
      */
     additionalContext?: Record<string, unknown>;
-    /**
-     * When true, each time the query is empty, the initial suggestions are
-     * generated fresh — personalized to `additionalContext` when set —
-     * instead of the fixed defaults. The initial placeholder text itself is
-     * unchanged. Default: false.
-     */
-    generateStartingStateOptions?: boolean;
     columns?: number;
     /** Where pills render in "full" mode. Default: "dropdown". Ignored in "dropdown" mode (always in dropdown). */
     pillPlacement?: "inline" | "dropdown" | "hidden";
@@ -532,6 +662,28 @@ declare class AIAutocomplete {
      */
     private scheduleSetCursor;
     clearNewParamId(): void;
+    /**
+     * 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.
+     *
+     * 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
+     * whatever the user picks replaces the span with the SDK's canonical form. So
+     * an unparseable "sometime next week" still ends up a clean answer.
+     */
+    startEditingIdentified(paramId: string): boolean;
+    /** Close the calendar opened for an identified span, leaving its text untouched. */
+    exitEditingIdentified(): void;
+    /**
+     * Open whatever the chip at `paramId` is answered with.
+     *
+     * Takes an id from either array so the DOM layers stay dumb: they report
+     * which chip was tapped and the core decides what that means. A completed
+     * param re-opens its cached options; a span the server identified as a date
+     * opens the calendar; anything else is inert, as it has always been.
+     */
     startEditingParam(paramId: string): void;
     replaceEditingRange(replacement: string): boolean;
     exitEditMode(): void;
@@ -548,6 +700,17 @@ declare class AIAutocomplete {
      */
     selectProduct(product: Product): void;
     handleTextChange(value: string): void;
+    /** Page the datepicker back one month. No-op unless a date pill is active. */
+    showPreviousMonth(): void;
+    /** Page the datepicker forward one month. No-op unless a date pill is active. */
+    showNextMonth(): void;
+    /**
+     * Move the visible month, stamping it with the current pill's key so the
+     * derive layer keeps honouring it. Once the active pill changes the key stops
+     * matching and the stored view is ignored — a new date pill therefore opens on
+     * its own default month with nothing having to clear this.
+     */
+    private pageDateView;
     /**
      * Skip the currently active pill (always index 0 of the actionable
      * suggestions) and promote the next pill to active. Invoked by ArrowRight at
@@ -660,9 +823,74 @@ declare class AIAutocomplete {
      * lands; doing it instantly here means bold styling appears as soon as the
      * option is fully typed, without waiting 100–300ms for the round-trip.
      */
+    /**
+     * Replace an identified date span with the day the user picked.
+     *
+     * The span becomes an ordinary completed param, so from here on it is
+     * indistinguishable from a date answered through a pill — same bold
+     * rendering, same `{{TYPE_N}}` token in `raw_query`, same `completed_params`
+     * entry. The identified param it came from is dropped: its text no longer
+     * exists in the input, and leaving it would have the reconciler drop it a
+     * beat later anyway.
+     */
+    private commitIdentifiedDate;
     private maybePromoteExactMatch;
 }
 
+/**
+ * Best-effort parse of a date the user typed in their own words.
+ *
+ * The server identifies a span of the query as a date and returns the literal
+ * text the user wrote — not a normalized value — so "september 5th", "5 Sep"
+ * and "09/05" all arrive as-is. This turns what it can into a `YYYY-MM-DD` so
+ * the calendar can open on the right month with that day already marked.
+ *
+ * **Returning null is a normal outcome, not a failure.** It only costs the
+ * pre-selection: the calendar still opens, on the current month with nothing
+ * marked, and whatever the user picks replaces the span with the SDK's own
+ * canonical text either way. So the committed answer is correct whether or not
+ * the original text could be read.
+ *
+ * Deliberately conservative — it answers null rather than guess, because a
+ * wrong date sitting pre-selected is worse than no pre-selection. A user who
+ * doesn't notice it commits the wrong answer; an empty calendar just asks them
+ * to pick.
+ */
+interface LooseDateOptions {
+    /** Reference point for resolving a date written without a year. Defaults to now. */
+    today?: Date;
+}
+/**
+ * `YYYY-MM-DD` for a date the user typed however they liked, or null when it
+ * can't be read with confidence.
+ *
+ * Handles, in order: ISO; a month name with a day either side of it, with or
+ * without an ordinal suffix or a year; and a numeric pair where only one
+ * reading is possible (`13/05` can only be day-first, since 13 is not a month).
+ *
+ * Deliberately NOT handled:
+ *  - A numeric pair where both numbers are 12 or under. `09/05` is September
+ *    5th to an American and May 9th to everyone else, and nothing in the
+ *    response says which — so it answers null rather than pick a side.
+ *  - Relative phrases ("tomorrow", "next friday"). Readable in principle, but
+ *    they depend on a reference the user may not share with the server, and
+ *    getting them subtly wrong is the expensive kind of wrong.
+ */
+declare function parseLooseDate(text: string | undefined | null, opts?: LooseDateOptions): string | null;
+/**
+ * The `YYYY-MM-DD` for an identified date param.
+ *
+ * Reads a normalized value off the param first, if one is ever there. The
+ * server sends only the user's literal text today, so in practice this always
+ * falls through to {@link parseLooseDate} — but normalizing server-side is the
+ * real fix for the ambiguous cases the parser refuses, and when it lands this
+ * is the one place that has to change.
+ */
+declare function resolveIdentifiedDate(param: {
+    text: string;
+    isoDate?: unknown;
+}, opts?: LooseDateOptions): string | null;
+
 /**
  * Rows/columns policy for the dropdown's options grid.
  *
@@ -864,4 +1092,4 @@ declare function withSkippedParams(completed: CompletedParam[], skipped: Skipped
  */
 declare function buildSubmitResult(text: string, completedParams: CompletedParamState[], skippedParams?: SkippedParamState[]): AutocompleteResult;
 
-export { AIAutocomplete, type APIConfig, type APIKeyConfig, ATTRIBUTION_URL, type AccessTokenConfig, type AccessTokenResult, type AppearanceMode, type AutocompleteRequest, type AutocompleteResponse, type AutocompleteResult, type CompletedParam, type CompletedParamState, type CoreOptions, type CoreState, type IdentifiedParam, type IdentifiedParamState, type InputItem, ModeController, OPTIONS_GRID_MOBILE_QUERY, type OptionOverrides, type OptionsGridLayout, type Product, type ProductsConfig, type RecentlySuggested, type RenderMode, SKIPPED_PARAM_TEXT, type Segment, type SkippedParamState, type Store, type Suggestion, type SuggestionOption, type TaskKind, buildAttributionUrl, buildQuery, buildSubmitResult, computeOptionsGridLayout, createStore, cursorIsAtEnd, extractPlainText, getCursorOffset, getFooterHint, isOptionsGridMobileViewport, optionsGridTemplateColumns, plainTextLength, previousGraphemeBoundary, renderEditableContent, setCursorOffset, withSkippedParams };
+export { AIAutocomplete, type APIConfig, type APIKeyConfig, ATTRIBUTION_URL, type AccessTokenConfig, type AccessTokenResult, type AppearanceMode, type AutocompleteRequest, type AutocompleteResponse, type AutocompleteResult, type CompletedParam, type CompletedParamState, type CoreOptions, type CoreState, type DateMonthView, type FormatType, type IdentifiedParam, type IdentifiedParamState, type InputItem, type LooseDateOptions, ModeController, OPTIONS_GRID_MOBILE_QUERY, type OptionOverrides, type OptionsGridLayout, type Product, type ProductsConfig, type RecentlySuggested, type RenderMode, SKIPPED_PARAM_TEXT, type Segment, type SkippedParamState, type Store, type Suggestion, type SuggestionOption, type TaskKind, WEEKDAY_LABELS, addMonths, buildAttributionUrl, buildDateOptions, buildQuery, buildSubmitResult, cellDay, cellIso, computeOptionsGridLayout, createStore, cursorIsAtEnd, extractPlainText, formatDate, getCursorOffset, getFooterHint, isOptionsGridMobileViewport, isoDate, monthLabel, optionsGridTemplateColumns, parseDate, parseLooseDate, plainTextLength, previousGraphemeBoundary, renderEditableContent, resolveFormatType, resolveIdentifiedDate, selectedIsoFromText, setCursorOffset, withSkippedParams };