@magicx-eng/ai-autocomplete-vanilla 0.18.0 → 0.19.1

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) |
@@ -687,7 +707,7 @@ Override these on the container element. All built-in defaults use `:where()` (z
 | `--aia-product-bg` | `transparent` | `transparent` | Product card background. |
 | `--aia-product-bg-active` | `--aia-option-bg` | `--aia-option-bg` | Product card background on hover. |
 | `--aia-product-media-bg` | `--aia-skeleton-bg` | `--aia-skeleton-bg` | Fill behind the product image, and of the placeholder tile when a product has no image. |
-| `--aia-scroll-arrow-bg` | `--aia-surface` | `--aia-surface` | Fill of the "more below" arrow — the round button that rises at the bottom of the option list while there is more to scroll to. |
+| `--aia-scroll-arrow-bg` | `--aia-surface` | `--aia-surface` | Fill of the "more below" arrow — the round button that fades in at the bottom of the option list while there is more to scroll to, and out while it scrolls. |
 | `--aia-scroll-arrow-color` | `--aia-option-color` | `--aia-option-color` | Chevron color of the arrow (`--aia-scroll-arrow-color-hover` on hover). |
 | `--aia-scroll-arrow-border` | `--aia-dropdown-border` | `--aia-dropdown-border` | Hairline around the arrow. |
 | `--aia-scroll-arrow-shadow` | `0 2px 8px rgba(0,0,0,0.12)` | `0 2px 8px rgba(0,0,0,0.12)` | Elevation of the arrow. |
@@ -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.
  *
@@ -1114,19 +1317,15 @@ declare function needsOptionsGridMeasurement(count: number, isMobile: boolean):
  * The full layout decision, measurements included.
  *
  * 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). 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.
+ * every option provably fits on one line in half the grid. Rows fill
+ * row-major (even indices left, odd right) and the two columns are always the
+ * same width, a plain 50/50 split, so the fit check is that the widest option
+ * fits in half of `gridWidth`. Content-sized tracks were tried twice (split in
+ * proportion to the column maxima, then left column to its content) and both
+ * read as columns of "weird widths" (2026-09-04); an even split is what the
+ * eye expects. When the widest option doesn't fit in half — 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.
@@ -1284,19 +1483,22 @@ declare function renderEditableContent(args: RenderEditableArgs): void;
  * The "more below" arrow for the options grid.
  *
  * 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, 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.
+ * with a down chevron sits at the bottom-centre of the list and scrolls it a
+ * page on click. It never moves — every appearance is an opacity fade in
+ * place, SCROLL_ARROW_FADE_MS long (the stylesheets own the curve):
+ *
+ * - At rest with more below (the list just opened, or scrolling has stopped
+ *   short of the end), it fades in.
+ * - The moment the list scrolls, it fades out, and stays out while scroll
+ *   events keep coming.
+ * - Once scrolling has been quiet for SCROLL_ARROW_SCROLL_IDLE_MS it fades
+ *   back in — unless the list is now at its bottom, where it stays out.
+ *
+ * Earlier versions rose from behind the footer and slid or shrank away; each
+ * read as the disc travelling with the scroll (2026-09-03/04), hence the
+ * fade-only rule. The stylesheets key everything off one attribute,
+ * `data-aia-visible`: present → opacity 1, absent → opacity 0, both
+ * transitioned.
  *
  * The DOM differs per package (vanilla builds the button here; React and
  * Angular render their own markup with the same classes and data attributes),
@@ -1317,18 +1519,22 @@ declare function renderEditableContent(args: RenderEditableArgs): void;
 declare const SCROLL_ARROW_CLASS = "magicx-aia-scroll-arrow";
 /** Stable styling hook (module class names aren't part of the API). */
 declare const SCROLL_ARROW_ATTR = "data-aia-scroll-arrow";
-/** Present on the button while it is shown. The stylesheets slide it in on this. */
+/**
+ * Present on the button while it is shown. The stylesheets fade it in on this
+ * and back out when it is removed.
+ */
 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.
+ * Length of the fade, either way. Documents the `opacity` transition in each
+ * package's stylesheet, which is what actually runs it — change both together.
  */
-declare const SCROLL_ARROW_LEAVING_ATTR = "data-aia-leaving";
+declare const SCROLL_ARROW_FADE_MS = 1000;
 /**
- * Length of the fade-out. Mirrors the `[data-aia-leaving]` transition in each
- * package's stylesheet — change both together.
+ * Quiet time after the last scroll event before the list counts as "stopped"
+ * and the arrow may come back. Wheel and trackpad scrolls deliver events a
+ * frame or so apart, so this only has to outlast a frame with some slack.
  */
-declare const SCROLL_ARROW_LEAVE_MS = 240;
+declare const SCROLL_ARROW_SCROLL_IDLE_MS = 160;
 /** 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";
@@ -1338,7 +1544,7 @@ interface ScrollArrowController {
     destroy(): void;
 }
 interface ScrollArrowArgs {
-    /** The dropdown panel — the button's containing block; its lower edge clips the hidden button. */
+    /** The dropdown panel — the button's containing block. */
     dropdown: HTMLElement;
     /** The options grid (the scroll box). */
     grid: HTMLElement;
@@ -1487,4 +1693,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_FADE_MS, SCROLL_ARROW_LABEL, SCROLL_ARROW_SCROLL_IDLE_MS, 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 };