@magicx-eng/ai-autocomplete-vanilla 0.18.0 → 0.19.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.
+- **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
@@ -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,8 +464,9 @@ 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) |
@@ -710,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

package/dist/index.d.mts

@@ -299,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
@@ -361,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`.
  */
@@ -482,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".
@@ -511,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;
 }
 /**
@@ -523,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[];
@@ -536,8 +589,15 @@ 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
@@ -1018,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.
  *
@@ -1487,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 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, 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, 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 };

package/dist/index.d.ts

@@ -299,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
@@ -361,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`.
  */
@@ -482,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".
@@ -511,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;
 }
 /**
@@ -523,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[];
@@ -536,8 +589,15 @@ 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
@@ -1018,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.
  *
@@ -1487,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 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, 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, 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 };