@magicx-eng/ai-autocomplete-vanilla 0.13.1 → 0.15.0

package/dist/index.d.mts

@@ -214,6 +214,118 @@ interface AutocompleteResult {
     completed_params: CompletedParam[];
 }
 
+/** A calendar month on screen. `month` is 0-based, matching `Date#getMonth`. */
+interface DateMonthView {
+    year: number;
+    month: number;
+}
+/** Sunday-first, matching `Date#getDay`. */
+declare const WEEKDAY_LABELS: string[];
+/**
+ * `YYYY-MM-DD` from the date's LOCAL components.
+ *
+ * Not `toISOString()`, which converts to UTC first: for any user behind UTC
+ * that shifts the calendar date back a day, so clicking "March 23" west of
+ * Greenwich would produce `2026-03-22`.
+ */
+declare function isoDate(d: Date): string;
+/**
+ * The committed form of a date — written the way a person would, since the
+ * text lands verbatim in the user's own sentence:
+ *
+ *  - today through six days out: the weekday alone, "Tuesday". The window
+ *    stops before day seven so every weekday name still means exactly one
+ *    date when read back.
+ *  - further out, same year: "March 23" — the year restates what "this year"
+ *    already says.
+ *  - a different year: "March 23 2027".
+ */
+declare function formatDate(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
+ * weekday name resolves to its one date in the next seven days, and a
+ * yearless month-day to the current year, mirroring how they were written.
+ * Returns null for anything else — the caller falls back to the current
+ * month.
+ *
+ * Deliberately RELATIVE, like the sentence it reads: the committed text is
+ * the single source of truth, and "Schedule a campaign Tuesday" means the
+ * next Tuesday to everyone who reads it — the user re-reading their own
+ * sentence, this parser, and the server parsing the submitted query alike.
+ * So once the originally-picked Tuesday has gone by, re-editing marks the
+ * date the sentence NOW names, a week later — not the stale pick. Anchoring
+ * to the pick would make the calendar disagree with the sentence above it
+ * (and with what the server will act on), which is the worse wrong. Pinned
+ * by the clock-advance test in datepicker.test.ts.
+ */
+declare function parseDate(text: string | undefined | null): Date | null;
+/** "March 2026" — the calendar header. */
+declare function monthLabel(view: DateMonthView): string;
+/** Step the view by whole months, rolling the year over at either end. */
+declare function addMonths(view: DateMonthView, delta: number): DateMonthView;
+/**
+ * A month laid out as `SuggestionOption`s — leading blanks, one cell per day,
+ * trailing blanks to complete the last week. Always a whole number of 7-cell
+ * rows.
+ *
+ * Modelling calendar cells as options is what makes the datepicker cheap: they
+ * flow through `filteredOptions`, so the existing keyboard controller, the
+ * `${listboxId}-option-${i}` id scheme, `aria-activedescendant` and — above all
+ * — `selectOption`'s entire commit path work on them unchanged. At 7 columns
+ * the grid's own column-major traversal already *is* calendar navigation
+ * (→ = +1 day, ↓ = +7 days).
+ *
+ * Each day cell's `text` is the committed value ("March 23", or "Tuesday"
+ * inside the next week — see {@link formatDate}), NOT its label:
+ * `computeSelectionPatch` commits `option.text` verbatim, so the value has to
+ * live there. The renderer reads `metadata.aiaDay` for the "23" it paints. Padding cells are non-tappable, which is what stops arrow navigation
+ * from landing on them.
+ *
+ * Days before today stay tappable — the calendar de-emphasizes the past, it
+ * does not forbid it. The renderers compare each cell's ISO date against
+ * today's and paint past days dimmed; picking one still commits normally.
+ */
+declare function buildDateOptions(view: DateMonthView): SuggestionOption[];
+/**
+ * The `YYYY-MM-DD` a completed date param already holds, so the calendar can
+ * mark that cell as the current answer while it is being re-edited. Null for
+ * text that isn't one of our dates.
+ */
+declare function selectedIsoFromText(text: string | undefined | null): string | null;
+/** A cell's `YYYY-MM-DD`, or null if it's padding. */
+declare function cellIso(option: SuggestionOption | undefined): string | null;
+/** A cell's day-of-month, or null if it's padding. */
+declare function cellDay(option: SuggestionOption | undefined): number | null;
+
+/**
+ * How the dropdown lets the user answer a suggestion.
+ *
+ * `"options"` is every suggestion the server has ever sent: pick one of its
+ * options, or type to filter them. `"date"` ignores the options entirely and
+ * renders a calendar instead.
+ */
+type FormatType = "options" | "date";
+/**
+ * Decide how a suggestion should be answered.
+ *
+ * The server cannot send a `formatType` yet, so a suggestion whose `type` names
+ * a date is detected here by its name and rendered as a calendar with its
+ * options ignored.
+ *
+ * That name check is deliberately the LAST resort. A `formatType` that *is* on
+ * the wire always wins, so the day the server starts sending one this function
+ * needs a single line deleted — the datepicker itself, and every gate that
+ * consults this, keep working untouched.
+ *
+ * Accepts anything with a `type`, not a `Suggestion`, so re-edit can ask the
+ * same question about a completed param via its `suggestionType`.
+ */
+declare function resolveFormatType(source: {
+    type: string;
+    options?: SuggestionOption[];
+} | undefined | null): FormatType;
+
 /**
  * Raw, user/network/internal-driven fields. The store holds *only* these —
  * derived state is recomputed lazily on read. See {@link CoreDerivedState}.
@@ -281,11 +393,53 @@ 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 streak
+     * True for ~500ms 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.
      */
     inSelectionAnimation: boolean;
+    /**
+     * Which month the datepicker is showing, when one is showing at all.
+     *
+     * `key` scopes the view to the pill it was opened for (see `dateViewKey` in
+     * `derive/state.ts`). A stale key is ignored rather than cleared, so moving
+     * to a different date pill starts at the default month without any of the
+     * flows that change the active pill — selection, skip, a landing response,
+     * re-edit — having to remember to reset this.
+     */
+    dateViewMonth: (DateMonthView & {
+        key: string;
+    }) | null;
+    /**
+     * Set while the user is picking a date for a span the server identified as
+     * one — "september 5th" in "fly to vegas on september 5th".
+     *
+     * Held apart from `editingParam` rather than folded into it. An identified
+     * span is not a completed param: it has no cached options, it lives in
+     * `identifiedParams`, and the re-edit paths that read `editingParam` all
+     * assume otherwise. Reusing that field would have meant auditing every one
+     * of them for a shape they were never written for.
+     *
+     * `iso` is the date the span's text was read as, or null when it could not be
+     * read with confidence (see `parseLooseDate`). Null costs only the
+     * pre-selection — the calendar still opens.
+     */
+    editingIdentified: {
+        id: string;
+        /** The identified param's type, which the committed param inherits. */
+        type: string;
+        /** Plain-text offsets bounding the span being replaced. */
+        anchor: number;
+        tail: number;
+        /**
+         * The span's text when the picker opened. Re-checked against those offsets
+         * before anything is spliced — if the input changed underneath, they no
+         * longer bound the span and writing at them would corrupt an unrelated
+         * part of the query.
+         */
+        text: string;
+        iso: string | null;
+    } | null;
 }
 /**
  * Derived fields recomputed from {@link CoreInputState} + {@link CoreOptions}.
@@ -295,7 +449,23 @@ interface CoreInputState {
 interface CoreDerivedState {
     segments: Segment[];
     actionableSuggestions: Suggestion[];
+    /**
+     * What the dropdown renders. Options for the active pill, filtered by what
+     * the user typed — EXCEPT when `activeFormatType` is `"date"`, where these
+     * are the visible month's calendar cells and the server's own options for
+     * that suggestion are ignored. See {@link buildDateOptions}.
+     */
     filteredOptions: SuggestionOption[];
+    /**
+     * How the active pill is answered: pick an option, or pick a date. Anything
+     * that reasons about options has to consult this — the server still *sends*
+     * options for a date suggestion, so code that only looks at `filteredOptions`
+     * would keep acting on options the user can't see (see the filter-zone and
+     * exact-match gates in `fetchController`).
+     */
+    activeFormatType: FormatType;
+    /** The month the datepicker is showing. Null unless `activeFormatType` is `"date"`. */
+    dateView: DateMonthView | null;
     placeholderText: string;
     isDropdownOpen: boolean;
     /**
@@ -519,6 +689,28 @@ declare class AIAutocomplete {
      */
     private scheduleSetCursor;
     clearNewParamId(): void;
+    /**
+     * Open the calendar for a span the server identified as a date.
+     *
+     * Returns false for anything else — an identified span whose type isn't a
+     * date stays inert, exactly as every identified span did before.
+     *
+     * The span's own text is read for a starting month (`parseLooseDate`), but
+     * failing to read it is not a failure: the calendar opens either way, and
+     * whatever the user picks replaces the span with the SDK's canonical form. So
+     * an unparseable "sometime next week" still ends up a clean answer.
+     */
+    startEditingIdentified(paramId: string): boolean;
+    /** Close the calendar opened for an identified span, leaving its text untouched. */
+    exitEditingIdentified(): void;
+    /**
+     * Open whatever the chip at `paramId` is answered with.
+     *
+     * Takes an id from either array so the DOM layers stay dumb: they report
+     * which chip was tapped and the core decides what that means. A completed
+     * param re-opens its cached options; a span the server identified as a date
+     * opens the calendar; anything else is inert, as it has always been.
+     */
     startEditingParam(paramId: string): void;
     replaceEditingRange(replacement: string): boolean;
     exitEditMode(): void;
@@ -535,6 +727,17 @@ declare class AIAutocomplete {
      */
     selectProduct(product: Product): void;
     handleTextChange(value: string): void;
+    /** Page the datepicker back one month. No-op unless a date pill is active. */
+    showPreviousMonth(): void;
+    /** Page the datepicker forward one month. No-op unless a date pill is active. */
+    showNextMonth(): void;
+    /**
+     * Move the visible month, stamping it with the current pill's key so the
+     * derive layer keeps honouring it. Once the active pill changes the key stops
+     * matching and the stored view is ignored — a new date pill therefore opens on
+     * its own default month with nothing having to clear this.
+     */
+    private pageDateView;
     /**
      * Skip the currently active pill (always index 0 of the actionable
      * suggestions) and promote the next pill to active. Invoked by ArrowRight at
@@ -647,9 +850,117 @@ declare class AIAutocomplete {
      * lands; doing it instantly here means bold styling appears as soon as the
      * option is fully typed, without waiting 100–300ms for the round-trip.
      */
+    /**
+     * Replace an identified date span with the day the user picked.
+     *
+     * The span becomes an ordinary completed param, so from here on it is
+     * indistinguishable from a date answered through a pill — same bold
+     * rendering, same `{{TYPE_N}}` token in `raw_query`, same `completed_params`
+     * entry. The identified param it came from is dropped: its text no longer
+     * exists in the input, and leaving it would have the reconciler drop it a
+     * beat later anyway.
+     */
+    private commitIdentifiedDate;
     private maybePromoteExactMatch;
 }
 
+/**
+ * Best-effort parse of a date the user typed in their own words.
+ *
+ * The server identifies a span of the query as a date and returns the literal
+ * text the user wrote — not a normalized value — so "september 5th", "5 Sep"
+ * and "09/05" all arrive as-is. This turns what it can into a `YYYY-MM-DD` so
+ * the calendar can open on the right month with that day already marked.
+ *
+ * **Returning null is a normal outcome, not a failure.** It only costs the
+ * pre-selection: the calendar still opens, on the current month with nothing
+ * marked, and whatever the user picks replaces the span with the SDK's own
+ * canonical text either way. So the committed answer is correct whether or not
+ * the original text could be read.
+ *
+ * Deliberately conservative — it answers null rather than guess, because a
+ * wrong date sitting pre-selected is worse than no pre-selection. A user who
+ * doesn't notice it commits the wrong answer; an empty calendar just asks them
+ * to pick.
+ */
+interface LooseDateOptions {
+    /** Reference point for resolving a date written without a year. Defaults to now. */
+    today?: Date;
+}
+/**
+ * `YYYY-MM-DD` for a date the user typed however they liked, or null when it
+ * can't be read with confidence.
+ *
+ * Handles, in order: ISO; a month name with a day either side of it, with or
+ * without an ordinal suffix or a year; and a numeric pair where only one
+ * reading is possible (`13/05` can only be day-first, since 13 is not a month).
+ *
+ * Deliberately NOT handled:
+ *  - A numeric pair where both numbers are 12 or under. `09/05` is September
+ *    5th to an American and May 9th to everyone else, and nothing in the
+ *    response says which — so it answers null rather than pick a side.
+ *  - Relative phrases ("tomorrow", "next friday"). Readable in principle, but
+ *    they depend on a reference the user may not share with the server, and
+ *    getting them subtly wrong is the expensive kind of wrong.
+ */
+declare function parseLooseDate(text: string | undefined | null, opts?: LooseDateOptions): string | null;
+/**
+ * The `YYYY-MM-DD` for an identified date param.
+ *
+ * Reads a normalized value off the param first, if one is ever there. The
+ * server sends only the user's literal text today, so in practice this always
+ * falls through to {@link parseLooseDate} — but normalizing server-side is the
+ * real fix for the ambiguous cases the parser refuses, and when it lands this
+ * is the one place that has to change.
+ */
+declare function resolveIdentifiedDate(param: {
+    text: string;
+    isoDate?: unknown;
+}, opts?: LooseDateOptions): string | null;
+
+/**
+ * Entrance choreography for the dropdown's option rows.
+ *
+ * When a new set of options lands, each row fades in while rising into place,
+ * and the rows start one after another from the input's side outward — the
+ * row nearest the input first. The reference (the RB2B support box's
+ * suggestion bubbles, 2026-08-19): opacity 0→1 over ~150 ms, a ~16 px rise
+ * easing out over ~280 ms, consecutive rows ~80–110 ms apart.
+ *
+ * The per-row motion is CSS (the option rule in each package's stylesheet —
+ * keep the three copies identical; the parity test compares them). This module
+ * owns the *timing numbers* and the per-row delay, so vanilla, React and
+ * Angular can't drift onto three different cascades. `OPTION_ENTER_RISE_MS` and
+ * `OPTION_ENTER_FADE_MS` must match the durations declared in those rules.
+ */
+/** Gap between consecutive rows starting their entrance. */
+declare const OPTION_ENTER_STAGGER_MS = 80;
+/** Duration of a row's opacity fade — mirrors the stylesheets' entrance rule. */
+declare const OPTION_ENTER_FADE_MS = 150;
+/** Duration of a row's rise into place — mirrors the stylesheets' entrance rule. */
+declare const OPTION_ENTER_RISE_MS = 280;
+/** Distance a row rises from, in CSS px — mirrors the stylesheets' entrance rule. */
+declare const OPTION_ENTER_RISE_PX = 16;
+/** Inline custom property each option carries with its own start delay. */
+declare const OPTION_ENTER_DELAY_VAR = "--aia-option-enter-delay";
+/**
+ * Start delay (ms) for the option at `index` in a grid of `count` options laid
+ * out in `cols` columns, when the dropdown sits `optionsPosition` the input.
+ *
+ * Rows, not cells, are the unit: the cells of one row share a start so a
+ * two-column layout reads as rows appearing, not as a zig-zag. "below" starts
+ * at the top row (the one against the input); "above" starts at the bottom row
+ * for the same reason — the stack is reversed there and the last row is the
+ * one nearest the input.
+ */
+declare function optionEnterDelayMs(index: number, cols: number, count: number, optionsPosition?: "above" | "below"): number;
+/**
+ * How long after the options render until the last row has settled — the
+ * moment anything that measures the grid (the scroll arrow) can trust its
+ * geometry again, since a row mid-rise still extends the scrollable area.
+ */
+declare function optionsEntranceDurationMs(count: number, cols: number): number;
+
 /**
  * Rows/columns policy for the dropdown's options grid.
  *
@@ -671,11 +982,61 @@ interface OptionsGridLayout {
 }
 /**
  * - Mobile: one column, five rows visible (scroll past five).
- * - Web: one column, four rows visible by default — but when there are exactly
- *   five or six options, two balanced columns (so 5/6 fit without scrolling).
- *   Columns fill row-major, so the two columns end up 3/2 (five) or 3/3 (six).
+ * - Web: one column, four rows visible (scroll past four).
+ *
+ * This is the measurement-free baseline (and the only layout mobile ever
+ * uses). On web, `planOptionsGrid` upgrades five-plus options to two columns
+ * when the rendered rows prove they fit — the upgrade needs the DOM, so it
+ * can't live here.
  */
 declare function computeOptionsGridLayout(count: number, isMobile: boolean): OptionsGridLayout;
+interface OptionsGridPlan extends OptionsGridLayout {
+    /**
+     * Value for `grid-template-columns`. Tracks carry no inner spaces (the
+     * keyboard controller counts tracks by splitting on spaces).
+     */
+    template: string;
+    /**
+     * Indices of the options on the last visible row of a scrollable web grid —
+     * their text gets the fade that signals more options below. Empty on mobile
+     * and whenever everything is already visible.
+     */
+    scrollHintIndices: number[];
+}
+/**
+ * Whether measuring the rendered rows could change the plan at all. Measuring
+ * clones every row and forces a layout, and renders happen per keystroke —
+ * so the callers skip it whenever `planOptionsGrid` would ignore the result
+ * anyway (mobile, or fewer options than the two-column minimum).
+ */
+declare function needsOptionsGridMeasurement(count: number, isMobile: boolean): 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), 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.
+ *
+ * `rowWidths` are single-line pixel widths of the rendered rows (see
+ * `measureOptionsGrid`); `gridWidth` is the grid's content width.
+ */
+declare function planOptionsGrid(count: number, isMobile: boolean, rowWidths: number[] | null, gridWidth: number | null): OptionsGridPlan;
+/**
+ * Measure the rendered option rows for `planOptionsGrid`: each row's
+ * single-line width (a hidden `max-content` + `nowrap` clone, so real classes,
+ * fonts, icons, tags and padding are all in the number), and the width the
+ * columns have to share — the grid's content box less its column gap.
+ * Returns null when there's nothing to measure.
+ */
+declare function measureOptionsGrid(grid: HTMLElement): {
+    rowWidths: number[];
+    gridWidth: number;
+} | null;
 /**
  * `grid-template-columns` for a fixed column count. Space-separated
  * `minmax(0,1fr)` tracks (no `repeat()`, no inner spaces) so rows fill
@@ -711,6 +1072,10 @@ declare function getCursorOffset(root: HTMLElement): number | null;
  * with no following text node, we use `setStartAfter(strong)` so the caret
  * sits OUTSIDE the bold subtree — otherwise a caret at the end of a strong's
  * text is still "inside" the strong, which would falsely trigger re-edit mode.
+ *
+ * Also scrolls the caret back into view (see `scrollCaretIntoView`) — this is
+ * the single caret-placement choke point, and a scripted caret move does not
+ * get the browser's own scroll-to-caret behaviour.
  */
 declare function setCursorOffset(root: HTMLElement, offset: number): void;
 /**
@@ -725,6 +1090,66 @@ declare function cursorIsAtEnd(root: HTMLElement): boolean;
  */
 declare function previousGraphemeBoundary(text: string, offset: number): number;
 
+/**
+ * Scroll-to-caret for the editor's own scroll container.
+ *
+ * The editor is a scroll container (`overflow-y: auto` under a height cap in
+ * the core stylesheet; a consumer holding it to one line adds `overflow-x`).
+ * Browsers scroll such a box to the caret as the user types, but not when the
+ * caret is moved by script — which the SDK does on every render that actually
+ * rewrites the editable's content (`renderEditable` early-returns on an
+ * unchanged segment key, and restores the caret only while focused).
+ * Everything here exists to close that gap.
+ */
+/**
+ * Scroll the caret back into view inside the editor's own scroll container.
+ *
+ * Browsers do this themselves while the user types, but not when the caret is
+ * moved by script — so every programmatic caret placement (option selection,
+ * caret restore after a re-render, controlled-mode `setValue`) would otherwise
+ * leave the caret, and everything typed next, outside the visible box.
+ *
+ * Exactly one box is scrolled, by writing its own `scrollLeft` / `scrollTop`:
+ * the nearest scrollable ancestor of the editable, which inside the widget's
+ * own markup is the editor. `scrollIntoView` is deliberately not used — it
+ * would walk the whole ancestor chain and the page with it. When the widget
+ * does not own the editable's ancestry (a consumer-rendered editor in
+ * `"dropdown"` / `"headless"` mode) that nearest box may be one of the
+ * consumer's, which is what the browser would scroll for typed input anyway;
+ * nothing above it moves either way. A no-op when nothing overflows, when the
+ * caret is already visible, or when the caret has no measurable box.
+ */
+declare function scrollCaretIntoView(root: HTMLElement): void;
+
+/**
+ * Types the starting-state placeholder into the input one character at a
+ * time instead of popping it in whole.
+ *
+ * The reference (the RB2B support box, 2026-08-19): ~33 ms per character, no
+ * caret, a brief hold on word boundaries; when the phrase changes the old
+ * one fades out (~120 ms), the field sits empty for a beat (~50 ms), then the
+ * new phrase types in from nothing. Characters appear at full opacity — the
+ * only fade is the outgoing phrase.
+ *
+ * Shared by every package: vanilla, React and Angular all render the
+ * placeholder through `renderEditableContent`, which hands the target text
+ * to `syncPlaceholder` below. The typed prefix lives in `data-placeholder`
+ * (the stylesheets render it via `::before`), so nothing enters the
+ * contentEditable's DOM and the core's notion of the placeholder — which
+ * drives Tab-to-accept and prefix-typing suppression — stays the full phrase
+ * at all times.
+ */
+/** Delay between characters. */
+declare const PLACEHOLDER_TYPE_MS = 33;
+/** Extra hold after a word boundary (space / hyphen). */
+declare const PLACEHOLDER_WORD_PAUSE_MS = 70;
+/** Fade-out of the outgoing phrase — must match `--aia-placeholder-fade` in the stylesheets. */
+declare const PLACEHOLDER_FADE_OUT_MS = 120;
+/** Empty beat between the fade-out and the next phrase typing in. */
+declare const PLACEHOLDER_SWAP_GAP_MS = 50;
+/** Set on the input while the outgoing phrase fades; the stylesheets fade `::before` on it. */
+declare const PLACEHOLDER_LEAVING_ATTR = "data-aia-placeholder-leaving";
+
 interface RenderEditableArgs {
     input: HTMLElement;
     segments: Segment[];
@@ -749,6 +1174,56 @@ interface RenderEditableArgs {
  */
 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, 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.
+ *
+ * The DOM differs per package (vanilla builds the button here; React and
+ * Angular render their own markup with the same classes and data attributes),
+ * so the *behaviour* lives in this one controller and each package hands it
+ * its dropdown, grid and button elements:
+ *
+ * - `update()` after every render — re-measures where the grid's bottom edge
+ *   is and re-evaluates visibility. The disc seats itself in the grid's
+ *   reserved fade band when there is one (below-mode with the footer), and
+ *   floats a small gap above the grid's edge in layouts that zero the band
+ *   (`optionsPosition="above"`, product strip). A new
+ *   option group (`data-aia-group` on the grid changed) keeps the arrow hidden
+ *   until the rows' entrance animation has settled, because a row mid-rise
+ *   still extends the scrollable area and would flash the arrow on.
+ * - The controller listens for the grid's own `scroll` and size changes itself.
+ * - `destroy()` when the grid or dropdown goes away.
+ */
+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. */
+declare const SCROLL_ARROW_VISIBLE_ATTR = "data-aia-visible";
+/** 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";
+interface ScrollArrowController {
+    /** Re-measure and re-evaluate. Call after every render of the dropdown. */
+    update(): void;
+    destroy(): void;
+}
+interface ScrollArrowArgs {
+    /** The dropdown panel — the button's containing block; its lower edge clips the hidden button. */
+    dropdown: HTMLElement;
+    /** The options grid (the scroll box). */
+    grid: HTMLElement;
+    /** The arrow button, already in the dropdown. */
+    button: HTMLElement;
+}
+declare function attachScrollArrow({ dropdown, grid, button, }: ScrollArrowArgs): ScrollArrowController;
+
 type Listener<S> = (next: S, prev: S) => void;
 interface Store<S> {
     get: () => S;
@@ -819,6 +1294,23 @@ declare class ModeController {
     private detachListener;
 }
 
+/**
+ * The dropdown pill-bar label for a parameter that has no suggestion behind it.
+ *
+ * Every pill normally shows its suggestion's `text` — a phrase written to be
+ * read, "Due date". A date the server identified in the user's own words
+ * ("september 5th") has no suggestion to borrow one from, only the wire `type`,
+ * so the type is read back into words instead: `travel_date` and `travelDate`
+ * both become "travel date". Without this the raw type is the label, both while
+ * the calendar is open over the span and again if that parameter is re-edited
+ * after being answered.
+ *
+ * Lower-casing costs nothing here — every package's pill CSS sets
+ * `text-transform: uppercase`, so a label's original case never reaches the
+ * screen either way.
+ */
+declare function identifiedParamLabel(type: string): string;
+
 /**
  * Sentinel `text` marking a `completed_params` entry the user skipped (→)
  * rather than filled. Sent regardless of `maskCompletedText` — it's a fixed
@@ -851,4 +1343,4 @@ declare function withSkippedParams(completed: CompletedParam[], skipped: Skipped
  */
 declare function buildSubmitResult(text: string, completedParams: CompletedParamState[], skippedParams?: SkippedParamState[]): AutocompleteResult;
 
-export { AIAutocomplete, type APIConfig, type APIKeyConfig, ATTRIBUTION_URL, type AccessTokenConfig, type AccessTokenResult, type AppearanceMode, type AutocompleteRequest, type AutocompleteResponse, type AutocompleteResult, type CompletedParam, type CompletedParamState, type CoreOptions, type CoreState, type IdentifiedParam, type IdentifiedParamState, type InputItem, ModeController, OPTIONS_GRID_MOBILE_QUERY, type OptionOverrides, type OptionsGridLayout, type Product, type ProductsConfig, type RecentlySuggested, type RenderMode, SKIPPED_PARAM_TEXT, type Segment, type SkippedParamState, type Store, type Suggestion, type SuggestionOption, type TaskKind, buildAttributionUrl, buildQuery, buildSubmitResult, computeOptionsGridLayout, createStore, cursorIsAtEnd, extractPlainText, getCursorOffset, getFooterHint, isOptionsGridMobileViewport, optionsGridTemplateColumns, plainTextLength, previousGraphemeBoundary, renderEditableContent, setCursorOffset, withSkippedParams };
+export { AIAutocomplete, type APIConfig, type APIKeyConfig, ATTRIBUTION_URL, type AccessTokenConfig, type AccessTokenResult, type AppearanceMode, type AutocompleteRequest, type AutocompleteResponse, type AutocompleteResult, type CompletedParam, type CompletedParamState, type CoreOptions, type CoreState, type DateMonthView, type FormatType, type IdentifiedParam, type IdentifiedParamState, type InputItem, type LooseDateOptions, ModeController, OPTIONS_GRID_MOBILE_QUERY, 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 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, withSkippedParams };