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

package/dist/index.d.ts

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