@magicx-eng/ai-autocomplete-vanilla 0.17.0 → 0.19.0

package/README.md

@@ -14,8 +14,8 @@ 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.
-- **Option overrides** — inject or dynamically generate client-side options per suggestion type
+- **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.
+- **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 (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
 - **Accessible** — ARIA combobox 1.2 pattern with `role="listbox"`, `aria-activedescendant`
@@ -74,7 +74,7 @@ const ac = new AIAutocomplete(container, {
 
   // API
   apiConfig: { apiKey: "...", authScheme: "Bearer", endpoint: "https://api.ai-autocomplete.com/api/suggest" },
-  optionOverrides: { account: (query) => [...] },
+  optionOverrides: { location: async (query, signal) => [...] }, // see "Option Overrides"
   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
@@ -344,6 +344,25 @@ 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
+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 —
+`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
+exports (`aiaDateRangeStart` / `aiaDateRangeEnd`), so you never have to parse
+the prose. Re-editing one re-opens the calendar with both ends marked.
+
 **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.
@@ -435,7 +454,7 @@ 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"`, or `"Tuesday"` inside the next week), 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`.
+> **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"`, or `"Tuesday"` inside the next week), 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`. For a **range** parameter `activeFormatType` is `"date-range"` and the same `selectOption(cell)` is called twice: the first records the start (`state.dateRangeStart` holds it, and nothing is committed yet), the second commits the span. `dateCellMarks` and `visibleDateRange` are exported to paint the two ends and the band between them the way the built-in calendars do.
 ### State shape (`CoreState`)
 
 | Field | Type | Description |
@@ -445,14 +464,17 @@ unsub();
 | `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. For a date parameter these are the visible month's day cells instead — each cell's `text` is the date it commits (`"March 23"`, or `"Tuesday"` inside the next week), 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"`. |
+| `activeFormatType` | `"options" \| "date" \| "date-range"` | How the active parameter is answered: pick an option, pick a date, or pick a span of dates. Both date formats show a calendar instead of the option list; `"date-range"` takes two clicks, a start and an end. 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 a calendar one. |
+| `dateRangeStart` | `string \| null` | While a range is half-picked, the start already chosen, as `YYYY-MM-DD`. Null at every other moment, including for every non-range parameter. |
 | `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) |
 | `isDropdownOpen` | `boolean` | Whether the dropdown should be visible |
 | `newParamId` | `string \| null` | ID of the most recently added param (for shimmer animation) |
 | `isLoading` | `boolean` | Fetch in progress. The Tier 1 / Tier 2 renderers gate the loading skeleton additionally on `!inSelectionAnimation` and `!editingParam`. |
+| `optionQuery` | `string` | The phrase the active parameter's options are filtered by — what the user has typed for it, trimmed — or the replacement typed so far during a re-edit. This is what an [option override](#option-overrides) is asked with. |
+| `isSearchingOptions` | `boolean` | True while an [option override](#option-overrides) for the parameter on screen has been asked and hasn't answered. Render the same skeleton you render for `isLoading`; the built-in dropdowns do. |
 | `inSelectionAnimation` | `boolean` | True for the 500 ms after a user-initiated option tap so the press animation can finish before the dropdown switches to the loading skeleton. |
 | `editingParam` | `CompletedParamState \| null` | When non-null, the user is re-editing a bold completed param; cached options remain visible and the loading skeleton is suppressed. |
 | `products` | `Product[]` | Results of the latest product search (empty unless `products` is configured). See [Product strip](#product-strip) — Tier 3 consumers render their own cards and call `selectProduct(product)` to emit `onProductSelect`. |
@@ -620,7 +642,7 @@ Events: `submit`, `result`, `error`, `change`, `paramsChange`, `stateChange`, `f
 
 `result` carries an `AutocompleteResult` after every successful round-trip — see [Reading the query as it's built](#reading-the-query-as-its-built). Prefer it over `stateChange` when what you want is the structured query: `stateChange` fires on every internal update (focus, highlight, keystroke) and hands you raw state you would have to assemble yourself.
 
-**Errors in your callbacks are contained.** A listener that throws is logged to the console (once per event per instance) and the remaining listeners still run — the SDK's own state is unaffected, so a bug in one handler can't stall the widget. The same holds for `subscribe()` listeners and `optionOverrides` functions; an override that throws falls back to that suggestion's existing options rather than blanking the list. One exception is deliberate: if an `onSubmit` handler throws, Tier 1 skips its auto-reset so the user's typed query isn't cleared out from under a failed submit.
+**Errors in your callbacks are contained.** A listener that throws is logged to the console (once per event per instance) and the remaining listeners still run — the SDK's own state is unaffected, so a bug in one handler can't stall the widget. The same holds for `subscribe()` listeners and `optionOverrides` functions; an override that throws or rejects is logged once per instance and treated as an empty answer, never as a fetch error. One exception is deliberate: if an `onSubmit` handler throws, Tier 1 skips its auto-reset so the user's typed query isn't cleared out from under a failed submit.
 
 Constructor callbacks (`onSubmit`, `onChange`, etc.) are registered once at construction as the initial listener for that event. Use `on()` for any additional or replacement listeners. **`update()` does not swap event listeners** — use `on()` for dynamic listener management.
 
@@ -708,6 +730,7 @@ Override these on the container element. All built-in defaults use `:where()` (z
 | `--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-date-range-bg` | white at 6% | white at 6% | Band across the days between the two ends of a picked date range. The ends themselves use `--aia-date-selected-bg`. |
 | `--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
@@ -806,24 +829,36 @@ const ac = new AIAutocomplete(container, {
 
 ## Option Overrides
 
+Supply the options for a parameter yourself instead of taking the server's. Each entry is keyed by the suggestion `type` and is a function of the phrase the user has typed for that parameter:
+
 ```ts
 new AIAutocomplete(el, {
   optionOverrides: {
+    // A fixed list — a plain array is applied at once, no loading state.
     account: () => [
       { text: "Savings", is_tappable: true, kind: null },
       { text: "Checking", is_tappable: true, kind: null },
     ],
-    value: (query) => {
-      const digits = query.replace(/\D/g, "");
-      if (!digits) return [{ text: "$100", is_tappable: true, kind: null }];
-      return [{ text: `$${digits}`, is_tappable: true, kind: null }];
+    // A list that lives behind a request — return a promise. The dropdown
+    // shows its loading skeleton until it settles.
+    location: async (query, signal) => {
+      const res = await fetch(`/api/locations?q=${encodeURIComponent(query)}`, { signal });
+      const places = await res.json();
+      return places.map((p) => ({ text: p.name, is_tappable: true, kind: null }));
     },
   },
-  onSubmit: handleSubmit,
 });
 ```
 
----
+**When it's called.** Once the moment the parameter becomes active — a response suggests it, a skip or a selection moves it to the front, or the user taps a completed value of that type to change it — with whatever they have already typed for it (usually `""`, the request for the default list). Then again on the SDK's typing debounce with each new phrase, so you can run a search or page through a larger list. If a phrase is already covered by what you last returned, return that list again. The third argument is the `Suggestion` being answered, for the rare override that serves more than one type.
+
+**What's shown.** Your answer, as-is: it is not filtered again by the phrase it was produced for, so a fuzzy or synonym match survives. Between two calls the previous answer is filtered locally by what the user types, so the list reacts to every keystroke. Typing the full text of an option in the answer completes the parameter, exactly as it does for a server option.
+
+**The server's role.** The server's own options for an overridden type are never shown. While an override owns the active parameter the server is not asked for suggestions; it is asked again when the parameter is answered or skipped. Return an empty list for a typed phrase and the SDK falls back to the server for that phrase — the typed text goes out the way it does for a parameter with no matching options — and won't ask you the same phrase twice. An empty list for `""` leaves the parameter on screen with no options.
+
+**Cancellation and errors.** Honour `signal`: it is aborted when a newer phrase supersedes the call, when the parameter stops being active, and on `destroy()`. A throw or a rejection is logged once per instance and treated as an empty answer, never as a fetch error.
+
+Tier 3 exposes the pieces: `state.optionQuery` is the phrase, and `state.isSearchingOptions` is true while an answer is pending.
 
 ## License
 

package/dist/index.d.mts

@@ -147,7 +147,42 @@ interface AccessTokenResult {
     expiresAt?: number;
 }
 type APIConfig = APIKeyConfig | AccessTokenConfig;
-type OptionOverrides = Record<string, (query: string) => SuggestionOption[]>;
+/**
+ * Supplies the options for one suggestion type in place of the server's,
+ * which are never shown for an overridden type.
+ *
+ * Called
+ * - the moment a pill of this type becomes active (a response suggests it, a
+ *   skip or a selection moves it to the front, a completed param of this type
+ *   is tapped to re-edit), with whatever the user has already typed for it —
+ *   usually `""`, the request for the default list;
+ * - again on the SDK's typing debounce with each new phrase, so a consumer
+ *   whose options live behind a request can run a second search or page
+ *   through a larger list. Return the same list early if the phrase is
+ *   already covered by what was last returned.
+ *
+ * A plain array is applied synchronously — the right shape for a fixed or
+ * locally computed list. A promise shows the dropdown's loading state until it
+ * settles. Either way the answer is listed as-is, never filtered again by the
+ * phrase it was produced for, so a fuzzy or synonym match survives. Between
+ * two calls the previous answer is filtered locally by what the user types,
+ * for instant feedback.
+ *
+ * The server is not asked for suggestions while an override owns the active
+ * pill. It is asked again when the user answers or skips the pill, and as a
+ * fallback when the override returns an empty list for a non-empty phrase —
+ * the typed text then goes to the server the way it does for a pill with no
+ * matching options. An empty answer for `""` leaves the pill with no options,
+ * and the override is not re-asked for a phrase it has already answered empty.
+ *
+ * Honour `signal` in anything asynchronous: it is aborted when a newer phrase
+ * supersedes this call, when the pill stops being active, and on `destroy()`.
+ * A rejected promise or a throw is contained — logged once per instance and
+ * treated as an empty answer.
+ */
+type OptionOverride = (query: string, signal: AbortSignal, suggestion: Suggestion) => Promise<SuggestionOption[]> | SuggestionOption[];
+/** Per-suggestion-type option overrides, keyed by the suggestion's `type`. */
+type OptionOverrides = Record<string, OptionOverride>;
 /**
  * A single product card in the dropdown's product strip.
  *
@@ -264,6 +299,17 @@ declare function isoDate(d: Date): string;
  *  - a different year: "March 23 2027".
  */
 declare function formatDate(d: Date): string;
+/**
+ * A date written as month and day, with the year only when it isn't this one —
+ * {@link formatDate} without the weekday shorthand.
+ *
+ * The shorthand is what a range must not use. "Tuesday - Friday" names four
+ * possible spans depending on when it is read, and the two ends of a range are
+ * read against each other rather than against today, so the one thing the
+ * weekday form is good at — naming a day inside this week unambiguously —
+ * stops being true the moment it is half of a span. See `formatDateRange`.
+ */
+declare function formatAbsoluteDate(d: Date): string;
 /**
  * Inverse of {@link formatDate}, for re-opening the calendar on the month a
  * completed date param already holds. Reads all three committed shapes — a
@@ -326,21 +372,29 @@ declare function cellDay(option: SuggestionOption | undefined): number | null;
  *
  * `"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.
+ * renders a calendar instead. `"date-range"` renders the same calendar,
+ * answered in two taps — a start and an end — and committed as one span.
  */
-type FormatType = "options" | "date";
+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 whose `type` names
- * a date is detected here by its name and rendered as a calendar with its
- * options ignored.
+ * 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.
  *
- * That name check is deliberately the LAST resort. A `formatType` that *is* on
+ * 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 line deleted — the datepicker itself, and every gate that
+ * 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 `type`, not a `Suggestion`, so re-edit can ask the
  * same question about a completed param via its `suggestionType`.
  */
@@ -391,6 +445,20 @@ interface CoreInputState {
      * never shows results belonging to an older query.
      */
     products: Product[];
+    /**
+     * The consumer's {@link OptionSource} request for the pill on screen — the
+     * active suggestion, or the completed param being re-edited. `type` is the
+     * suggestion type it was asked for and `query` the phrase it was asked with;
+     * the answer itself is written into that suggestion's (or param's) `options`
+     * so every reader of those — filtering, exact-match promotion, the re-edit
+     * cache — sees it without knowing where it came from. Null when no source
+     * owns the pill on screen. Owned by `OptionSourceController`.
+     */
+    optionSearch: {
+        type: string;
+        query: string;
+        status: "loading" | "done";
+    } | null;
     activeDropdownIndex: number;
     newParamId: string | null;
     isLoading: boolean;
@@ -416,7 +484,7 @@ interface CoreInputState {
     /** Current caret offset within the editor. Tracked via DOM `selectionchange`. */
     caretOffset: number | null;
     /**
-     * True for ~500ms after a user-initiated option selection so the press
+     * True for ~170ms after a user-initiated option selection so the press
      * animation can finish before the dropdown switches to its loading skeleton.
      * Set by selectOption / ReEditManager.selectOption, cleared by a timer.
      */
@@ -433,6 +501,25 @@ interface CoreInputState {
     dateViewMonth: (DateMonthView & {
         key: string;
     }) | null;
+    /**
+     * The first end of a range the user is part-way through picking, as
+     * `YYYY-MM-DD`, or null when no pick is in progress. Surfaces to readers as
+     * the derived `dateRangeStart`, the way `dateViewMonth` surfaces as
+     * `dateView`.
+     *
+     * Only meaningful while `activeFormatType` is `"date-range"`, where a date is
+     * answered in two taps. `key` names the parameter the pick belongs to (see
+     * `dateViewKey`), and unlike `dateViewMonth` a stale one is not merely
+     * ignored — it is cleared, by the invariant in `AIAutocomplete`'s
+     * constructor. Scoping alone would only HIDE it, and every key it can carry
+     * reproduces exactly later in a session: the same pill type re-suggested, the
+     * same param re-edited, the same span re-tapped. A resurrected start would
+     * then pair with an unrelated tap and commit a span nobody chose.
+     */
+    pendingRangeStart: {
+        iso: string;
+        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".
@@ -462,6 +549,20 @@ interface CoreInputState {
          */
         text: string;
         iso: string | null;
+        /**
+         * The other end, when the span reads as a range ("september 11 to november
+         * 16") rather than as one day. Null for a single date, and null for a range
+         * whose text couldn't be read — which costs the pre-selection only.
+         */
+        isoEnd: string | null;
+        /**
+         * How this span is answered — a calendar, or a calendar in two taps.
+         *
+         * Resolved once when the picker opens and carried here rather than
+         * re-derived, because it depends on the span's own text (a `travel_date`
+         * written as a span is a range) and the derive layer only sees its type.
+         */
+        format: FormatType;
     } | null;
 }
 /**
@@ -474,8 +575,9 @@ interface CoreDerivedState {
     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
+     * the user typed — EXCEPT when `activeFormatType` is a calendar one
+     * (`"date"` / `"date-range"`), 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[];
@@ -487,9 +589,30 @@ interface CoreDerivedState {
      * exact-match gates in `fetchController`).
      */
     activeFormatType: FormatType;
-    /** The month the datepicker is showing. Null unless `activeFormatType` is `"date"`. */
+    /** The month the datepicker is showing. Null unless `activeFormatType` is a calendar one. */
     dateView: DateMonthView | null;
+    /**
+     * The first end of a range already picked, as `YYYY-MM-DD`, while the user is
+     * choosing the second. Null whenever no pick is in progress — including for
+     * every non-range format, so a UI can read it without checking the format
+     * first. The calendars paint the span between it and the highlighted cell.
+     */
+    dateRangeStart: string | null;
     placeholderText: string;
+    /**
+     * The phrase the active pill's options are filtered by — what the user has
+     * typed for it, trimmed — or, during a re-edit, the replacement typed so
+     * far. `""` when nothing has been typed for the pill yet. This is the query
+     * an {@link OptionSource} is asked with.
+     */
+    optionQuery: string;
+    /**
+     * True while the consumer's {@link OptionSource} for the pill on screen has
+     * been asked and hasn't answered yet. The built-in dropdowns show their
+     * loading skeleton for it exactly as they do for `isLoading`; a custom UI
+     * should treat it the same way. Never true for a pill without a source.
+     */
+    isSearchingOptions: boolean;
     isDropdownOpen: boolean;
     /**
      * Whether the active (leading) pill should render in its `selected` state
@@ -648,6 +771,7 @@ declare class AIAutocomplete {
     private keyboardController;
     private pillsController;
     private productsController;
+    private optionSource;
     private reEdit;
     private modeController;
     private container;
@@ -656,11 +780,9 @@ declare class AIAutocomplete {
     private domRefs;
     private dropdownRefs;
     private timers;
-    /** One per instance — see {@link ConsumerBoundary}. Shared by the emitter, `subscribe()` and `optionOverrides`. */
+    /** One per instance — see {@link ConsumerBoundary}. Shared by the emitter and `subscribe()`. */
     private boundary;
     /** Identity of the raw override record the wrapped copy below was built from. */
-    private rawOverrides;
-    private wrappedOverrides;
     private subscriberCount;
     private emitter;
     private sessionId;
@@ -844,24 +966,6 @@ declare class AIAutocomplete {
     selectOption(option: SuggestionOption): void;
     private startSelectionAnimationTimer;
     private fireTelemetry;
-    /**
-     * `this.opts` with every `optionOverrides` entry wrapped in the instance's
-     * {@link ConsumerBoundary}.
-     *
-     * The derive layer calls these functions on the SDK's stack — from
-     * `getState()`, and from inside the store's notification drain — so an
-     * un-wrapped throw would unwind whatever internal operation triggered the
-     * derive and abort delivery of every queued notification with it, taking the
-     * instance down rather than just the override. Wrapped, a failed override
-     * answers `undefined` and each call site falls back to the server's options.
-     *
-     * Memoized on the raw record's identity so a swapped integration is
-     * re-wrapped while a stable one isn't re-wrapped on every derive. Note
-     * `update({ optionOverrides })` only becomes visible on the next store write
-     * — the derived layer memoizes on inputs identity, and `update` doesn't
-     * invalidate it for this key. Pre-existing, and unchanged by the wrapping.
-     */
-    private deriveOpts;
     private setupContainer;
     private buildAndRenderFull;
     private buildAndRenderDropdown;
@@ -974,6 +1078,149 @@ declare function resolveIdentifiedDate(param: {
     isoDate?: unknown;
 }, opts?: LooseDateOptions): string | null;
 
+/**
+ * A span of days, both ends inclusive, as `YYYY-MM-DD`. `start <= end` always —
+ * every producer here orders the two.
+ */
+interface DateRange {
+    start: string;
+    end: string;
+}
+/**
+ * What joins the two ends of a committed range.
+ *
+ * A spaced hyphen, because the committed text lands verbatim in the user's own
+ * sentence and is what the server parses back. `parseLooseDateRange` reads far
+ * more separators than this one — it has to, since it is also what reads a
+ * server's option text and the user's own words — but the SDK only ever writes
+ * this one.
+ */
+declare const RANGE_SEPARATOR = " - ";
+/** Metadata key holding a committed range's start, as `YYYY-MM-DD`. */
+declare const DATE_RANGE_META_START = "aiaDateRangeStart";
+/** Metadata key holding a committed range's end, as `YYYY-MM-DD`. */
+declare const DATE_RANGE_META_END = "aiaDateRangeEnd";
+/**
+ * Best-effort parse of a span of days written in the user's (or the server's)
+ * own words — "September 11 - October 13", "September 11 to November 16",
+ * "13/05/2026 - 20/05/2026".
+ *
+ * Each half goes through {@link parseLooseDate}, so a range reads exactly the
+ * date formats a single date does, and refuses exactly what it refuses. Same
+ * trade as everywhere in this corner of the SDK: **null is a normal outcome**.
+ * It costs the range picker's pre-selection, or keeps a suggestion rendering as
+ * a plain option list — never correctness.
+ *
+ * Refused on purpose:
+ *  - A backwards span ("October 13 - September 11"). Nothing here can tell a
+ *    typo from a year boundary the writer left implicit, and silently swapping
+ *    the ends would answer a question the user didn't ask.
+ *  - A shared-month shorthand ("September 11 - 13"). The right half alone is
+ *    not a date, and inferring the month from the left half is the kind of
+ *    guess this file exists not to make.
+ *  - Anything where two different splits both read as a range — the text is
+ *    then genuinely ambiguous about where its own separator is.
+ *
+ * A yearless half resolves the way {@link parseLooseDate} resolves one: to its
+ * next occurrence. That is what makes "December 30 - January 5" read as the
+ * turn of the year rather than as a backwards span.
+ */
+declare function parseLooseDateRange(text: string | undefined | null, opts?: LooseDateOptions): DateRange | null;
+/**
+ * The committed text for a range — "September 11 - October 13".
+ *
+ * Each end is written by {@link formatAbsoluteDate}, never by `formatDate`:
+ * the weekday shorthand it would use for a nearby day ("Tuesday") names a
+ * different date every week it is read, which a single answer can carry and a
+ * span cannot.
+ *
+ * A span of one day commits as that day alone. "September 11 - September 11"
+ * is not how anyone writes it, and the range is still recoverable from the
+ * option's metadata when the answer is re-edited.
+ */
+declare function formatDateRange(range: DateRange): string;
+/**
+ * The range an already-answered param holds, so both its ends can be marked
+ * when it is re-opened.
+ *
+ * Metadata first — it is what the SDK itself wrote, exact and free of the
+ * yearless-date resolution the text form needs. Text second, which is what a
+ * range that reached the input any other way (a server-identified span, a
+ * consumer's controlled value) has.
+ */
+declare function selectedRangeFor(param: {
+    text?: string;
+    metadata?: Record<string, unknown>;
+} | undefined | null, opts?: LooseDateOptions): DateRange | null;
+
+/**
+ * What a calendar paints as answered.
+ *
+ * Three fields rather than one because they answer three different questions,
+ * and a range picker shows two of them at once: what is already committed
+ * (`selectedIso` for a day, `selectedRange` for a span) and what the user is
+ * half-way through picking (`rangeStart`). {@link visibleDateRange} folds the
+ * last two into the span actually drawn.
+ */
+interface DateSelection {
+    /** `YYYY-MM-DD` a re-edited single-date param already holds, or null. */
+    selectedIso: string | null;
+    /** Both ends of a re-edited range param, or null. */
+    selectedRange: DateRange | null;
+    /** The first end of a range being picked right now, or null. */
+    rangeStart: string | null;
+}
+/**
+ * The calendar's selection, read off core state.
+ *
+ * Every package's dropdown needs exactly this, and computing it four times
+ * over — vanilla Tier 1, vanilla Tier 2, the React hook, the Angular
+ * controller — is how the four copies would come to disagree about which cells
+ * a re-edited range fills. Typed structurally so each of them can hand it the
+ * state object it already has.
+ */
+declare function dateSelectionFor(state: {
+    activeFormatType: FormatType;
+    editingIdentified: {
+        iso: string | null;
+        isoEnd: string | null;
+    } | null;
+    editingParam: {
+        text: string;
+        metadata?: Record<string, unknown>;
+    } | null;
+    dateRangeStart: string | null;
+}): DateSelection;
+/**
+ * The span the calendar should paint right now.
+ *
+ * While a first end is pending, that is the live span between it and whatever
+ * the user is pointing at — the preview every range picker shows, which is also
+ * what tells them the first tap registered. Otherwise it is the answer already
+ * committed, if there is one.
+ */
+declare function visibleDateRange(args: {
+    pendingStart: string | null;
+    highlightedIso: string | null;
+    selected: DateRange | null;
+}): DateRange | null;
+/**
+ * How one cell renders against the current selection: filled at either end of
+ * the span, banded in between.
+ *
+ * Shared by all three packages' calendars so a range can't be painted three
+ * subtly different ways. `selectedIso` is the single-date answer, which is
+ * mutually exclusive with `range` in practice but costs nothing to fold in
+ * here — it keeps every cell's appearance one function call at every call site.
+ */
+declare function dateCellMarks(iso: string | null, args: {
+    selectedIso: string | null;
+    range: DateRange | null;
+}): {
+    selected: boolean;
+    inRange: boolean;
+};
+
 /**
  * Entrance choreography for the dropdown's option rows.
  *
@@ -1071,12 +1318,18 @@ declare function needsOptionsGridMeasurement(count: number, isMobile: boolean):
  *
  * Web, five-plus options: two columns of three visible rows — but only when
  * every option provably fits on one line. Rows fill row-major (even indices
- * left, odd right), each column is as wide as its widest option, and the
- * columns may be unequal: the template splits the width in proportion to the
- * two column maxima, so whenever `left + right <= gridWidth`, each column gets
- * at least what its widest row needs. When the pair doesn't fit — or there are
- * no usable measurements (SSR, hidden grid, loading skeletons) — the layout
- * stays one scrollable column.
+ * left, odd right). The left track is exactly as wide as its widest option
+ * (a fixed pixel width from the measurement) and the right track takes the
+ * rest of the grid — which is at least its own widest option, because
+ * `left + right <= gridWidth` is the fit check. So the second column starts
+ * right where the first column's longest text ends, and short options such as
+ * sizes sit beside each other. (Splitting the width in proportion to the two
+ * maxima, as this used to, handed ALL the slack out in that ratio too: one
+ * long option in the left column and "34"-length options on the right gave
+ * the left column ~85% of the box and pushed the right column to the far
+ * edge, 2026-09-03.) When the pair doesn't fit — or there are no usable
+ * measurements (SSR, hidden grid, loading skeletons) — the layout stays one
+ * scrollable column.
  *
  * `rowWidths` are single-line pixel widths of the rendered rows (see
  * `measureOptionsGrid`); `gridWidth` is the grid's content width.
@@ -1236,10 +1489,17 @@ declare function renderEditableContent(args: RenderEditableArgs): void;
  * When the option list is taller than its scroll box, a small round button
  * with a down chevron sits at the bottom-centre of the list. It slides up into
  * view from behind the dropdown's lower edge (the footer, when the dropdown
- * opens below the input) the moment there is more to scroll to, slides back
- * down once the list is scrolled to its end, and scrolls the list a page on
- * click. The reference (the RB2B support panel, 2026-08-19): a white 32 px
- * disc that rises from behind the composer over ~150–180 ms, no fade.
+ * opens below the input) the moment there is more to scroll to, dissolves in
+ * place once the list is scrolled to its end, and scrolls the list a page on
+ * click. The entrance follows the reference (the RB2B support panel,
+ * 2026-08-19): a white 32 px disc that rises from behind the composer over
+ * ~150–180 ms, no fade. The exit deliberately does not mirror it — sliding
+ * back down read as the disc "falling" into the footer (2026-09-03), so
+ * instead it fades out where it stands, with a slight shrink, over
+ * SCROLL_ARROW_LEAVE_MS. The stylesheets key the two moves off two attributes:
+ * `data-aia-visible` (rise, stay) and `data-aia-leaving` (dissolve), which
+ * this controller holds for the fade's length and then clears, so the disc
+ * re-parks below the edge — invisibly — ready to rise again.
  *
  * The DOM differs per package (vanilla builds the button here; React and
  * Angular render their own markup with the same classes and data attributes),
@@ -1262,6 +1522,16 @@ declare const SCROLL_ARROW_CLASS = "magicx-aia-scroll-arrow";
 declare const SCROLL_ARROW_ATTR = "data-aia-scroll-arrow";
 /** Present on the button while it is shown. The stylesheets slide it in on this. */
 declare const SCROLL_ARROW_VISIBLE_ATTR = "data-aia-visible";
+/**
+ * Present on the button while it fades out. The stylesheets dissolve it in
+ * place on this; the controller clears it after SCROLL_ARROW_LEAVE_MS.
+ */
+declare const SCROLL_ARROW_LEAVING_ATTR = "data-aia-leaving";
+/**
+ * Length of the fade-out. Mirrors the `[data-aia-leaving]` transition in each
+ * package's stylesheet — change both together.
+ */
+declare const SCROLL_ARROW_LEAVE_MS = 240;
 /** Inline custom property: how far the button's bottom edge sits above the dropdown's padding edge. */
 declare const SCROLL_ARROW_BOTTOM_VAR = "--aia-scroll-arrow-bottom";
 declare const SCROLL_ARROW_LABEL = "Scroll down for more options";
@@ -1420,4 +1690,4 @@ interface SubmitResultExtras {
  */
 declare function buildSubmitResult(text: string, completedParams: CompletedParamState[], skippedParams?: SkippedParamState[], extras?: SubmitResultExtras): 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 DateMonthView, type FormatType, type IdentifiedParam, type IdentifiedParamState, type InputItem, type LooseDateOptions, ModeController, OPTIONS_GRID_MOBILE_QUERY, OPTION_ENTER_DELAY_VAR, OPTION_ENTER_FADE_MS, OPTION_ENTER_RISE_MS, OPTION_ENTER_RISE_PX, OPTION_ENTER_STAGGER_MS, type OptionOverrides, type OptionsGridLayout, type OptionsGridPlan, PLACEHOLDER_FADE_OUT_MS, PLACEHOLDER_LEAVING_ATTR, PLACEHOLDER_SWAP_GAP_MS, PLACEHOLDER_TYPE_MS, PLACEHOLDER_WORD_PAUSE_MS, type Product, type ProductsConfig, type RecentlySuggested, type RenderMode, SCROLL_ARROW_ATTR, SCROLL_ARROW_BOTTOM_VAR, SCROLL_ARROW_CLASS, SCROLL_ARROW_LABEL, SCROLL_ARROW_VISIBLE_ATTR, SKIPPED_PARAM_TEXT, type ScrollArrowArgs, type ScrollArrowController, type Segment, type SkippedParamState, type Store, type SubmitResultExtras, type Suggestion, type SuggestionOption, type TaskKind, WEEKDAY_LABELS, addMonths, attachScrollArrow, buildAttributionUrl, buildDateOptions, buildQuery, buildSubmitResult, cellDay, cellIso, computeOptionsGridLayout, createStore, cursorIsAtEnd, extractPlainText, formatDate, getCursorOffset, getFooterHint, identifiedParamLabel, isOptionsGridMobileViewport, isoDate, measureOptionsGrid, monthLabel, needsOptionsGridMeasurement, optionEnterDelayMs, optionsEntranceDurationMs, optionsGridTemplateColumns, parseDate, parseLooseDate, plainTextLength, planOptionsGrid, previousGraphemeBoundary, renderEditableContent, resolveFormatType, resolveIdentifiedDate, scrollCaretIntoView, selectedIsoFromText, setCursorOffset, toWireIdentifiedParams, 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, DATE_RANGE_META_END, DATE_RANGE_META_START, type DateMonthView, type DateRange, type DateSelection, type FormatType, type IdentifiedParam, type IdentifiedParamState, type InputItem, type LooseDateOptions, ModeController, OPTIONS_GRID_MOBILE_QUERY, OPTION_ENTER_DELAY_VAR, OPTION_ENTER_FADE_MS, OPTION_ENTER_RISE_MS, OPTION_ENTER_RISE_PX, OPTION_ENTER_STAGGER_MS, type OptionOverride, type OptionOverrides, type OptionsGridLayout, type OptionsGridPlan, PLACEHOLDER_FADE_OUT_MS, PLACEHOLDER_LEAVING_ATTR, PLACEHOLDER_SWAP_GAP_MS, PLACEHOLDER_TYPE_MS, PLACEHOLDER_WORD_PAUSE_MS, type Product, type ProductsConfig, RANGE_SEPARATOR, type RecentlySuggested, type RenderMode, SCROLL_ARROW_ATTR, SCROLL_ARROW_BOTTOM_VAR, SCROLL_ARROW_CLASS, SCROLL_ARROW_LABEL, SCROLL_ARROW_LEAVE_MS, SCROLL_ARROW_LEAVING_ATTR, SCROLL_ARROW_VISIBLE_ATTR, SKIPPED_PARAM_TEXT, type ScrollArrowArgs, type ScrollArrowController, type Segment, type SkippedParamState, type Store, type SubmitResultExtras, type Suggestion, type SuggestionOption, type TaskKind, WEEKDAY_LABELS, addMonths, attachScrollArrow, buildAttributionUrl, buildDateOptions, buildQuery, buildSubmitResult, cellDay, cellIso, computeOptionsGridLayout, createStore, cursorIsAtEnd, dateCellMarks, dateSelectionFor, extractPlainText, formatAbsoluteDate, formatDate, formatDateRange, getCursorOffset, getFooterHint, identifiedParamLabel, isCalendarFormat, isOptionsGridMobileViewport, isoDate, measureOptionsGrid, monthLabel, needsOptionsGridMeasurement, optionEnterDelayMs, optionsEntranceDurationMs, optionsGridTemplateColumns, parseDate, parseLooseDate, parseLooseDateRange, plainTextLength, planOptionsGrid, previousGraphemeBoundary, renderEditableContent, resolveFormatType, resolveIdentifiedDate, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, toWireIdentifiedParams, visibleDateRange, withSkippedParams };