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

package/dist/index.d.ts

@@ -147,7 +147,42 @@ interface AccessTokenResult {
     expiresAt?: number;
 }
 type APIConfig = APIKeyConfig | AccessTokenConfig;
-type OptionOverrides = Record<string, (query: string) => SuggestionOption[]>;
+/**
+ * Supplies the options for one suggestion type in place of the server's,
+ * which are never shown for an overridden type.
+ *
+ * Called
+ * - the moment a pill of this type becomes active (a response suggests it, a
+ *   skip or a selection moves it to the front, a completed param of this type
+ *   is tapped to re-edit), with whatever the user has already typed for it —
+ *   usually `""`, the request for the default list;
+ * - again on the SDK's typing debounce with each new phrase, so a consumer
+ *   whose options live behind a request can run a second search or page
+ *   through a larger list. Return the same list early if the phrase is
+ *   already covered by what was last returned.
+ *
+ * A plain array is applied synchronously — the right shape for a fixed or
+ * locally computed list. A promise shows the dropdown's loading state until it
+ * settles. Either way the answer is listed as-is, never filtered again by the
+ * phrase it was produced for, so a fuzzy or synonym match survives. Between
+ * two calls the previous answer is filtered locally by what the user types,
+ * for instant feedback.
+ *
+ * The server is not asked for suggestions while an override owns the active
+ * pill. It is asked again when the user answers or skips the pill, and as a
+ * fallback when the override returns an empty list for a non-empty phrase —
+ * the typed text then goes to the server the way it does for a pill with no
+ * matching options. An empty answer for `""` leaves the pill with no options,
+ * and the override is not re-asked for a phrase it has already answered empty.
+ *
+ * Honour `signal` in anything asynchronous: it is aborted when a newer phrase
+ * supersedes this call, when the pill stops being active, and on `destroy()`.
+ * A rejected promise or a throw is contained — logged once per instance and
+ * treated as an empty answer.
+ */
+type OptionOverride = (query: string, signal: AbortSignal, suggestion: Suggestion) => Promise<SuggestionOption[]> | SuggestionOption[];
+/** Per-suggestion-type option overrides, keyed by the suggestion's `type`. */
+type OptionOverrides = Record<string, OptionOverride>;
 /**
  * A single product card in the dropdown's product strip.
  *
@@ -208,10 +243,33 @@ interface ProductsConfig {
     /** Optional cap the SDK applies after `transform`. */
     limit?: number;
 }
+/**
+ * The structured query as the SDK currently understands it.
+ *
+ * Delivered to `onResult` after every successful suggestion round-trip and to
+ * `onSubmit` when the user submits. Both are built by `buildSubmitResult`, so
+ * a submit is just the last result the consumer already saw — plus whatever
+ * the user typed in between.
+ */
 interface AutocompleteResult {
+    /** Plain text as the user sees it, trimmed. */
     query: string;
+    /** `query` with each completed param replaced by its `{{PLACEHOLDER}}` token. */
     raw_query: string;
+    /**
+     * Params the user filled (in query order), followed by any they skipped
+     * (`text: "skipped"`, no placeholder). See `withSkippedParams`.
+     */
     completed_params: CompletedParam[];
+    /**
+     * Params the server identified in the user's own words — spans it matched to
+     * a parameter type without the user picking an option. Tentative: replaced
+     * wholesale by every response and dropped as soon as the text no longer
+     * matches. Never tokenized in `raw_query`.
+     */
+    identified_params: IdentifiedParam[];
+    /** Whether the server considers the query complete enough to act on. */
+    is_ready: boolean;
 }
 
 /** A calendar month on screen. `month` is 0-based, matching `Date#getMonth`. */
@@ -368,6 +426,20 @@ interface CoreInputState {
      * never shows results belonging to an older query.
      */
     products: Product[];
+    /**
+     * The consumer's {@link OptionSource} request for the pill on screen — the
+     * active suggestion, or the completed param being re-edited. `type` is the
+     * suggestion type it was asked for and `query` the phrase it was asked with;
+     * the answer itself is written into that suggestion's (or param's) `options`
+     * so every reader of those — filtering, exact-match promotion, the re-edit
+     * cache — sees it without knowing where it came from. Null when no source
+     * owns the pill on screen. Owned by `OptionSourceController`.
+     */
+    optionSearch: {
+        type: string;
+        query: string;
+        status: "loading" | "done";
+    } | null;
     activeDropdownIndex: number;
     newParamId: string | null;
     isLoading: boolean;
@@ -393,7 +465,7 @@ interface CoreInputState {
     /** Current caret offset within the editor. Tracked via DOM `selectionchange`. */
     caretOffset: number | null;
     /**
-     * True for ~500ms after a user-initiated option selection so the press
+     * True for ~170ms after a user-initiated option selection so the press
      * animation can finish before the dropdown switches to its loading skeleton.
      * Set by selectOption / ReEditManager.selectOption, cleared by a timer.
      */
@@ -467,6 +539,20 @@ interface CoreDerivedState {
     /** The month the datepicker is showing. Null unless `activeFormatType` is `"date"`. */
     dateView: DateMonthView | null;
     placeholderText: string;
+    /**
+     * The phrase the active pill's options are filtered by — what the user has
+     * typed for it, trimmed — or, during a re-edit, the replacement typed so
+     * far. `""` when nothing has been typed for the pill yet. This is the query
+     * an {@link OptionSource} is asked with.
+     */
+    optionQuery: string;
+    /**
+     * True while the consumer's {@link OptionSource} for the pill on screen has
+     * been asked and hasn't answered yet. The built-in dropdowns show their
+     * loading skeleton for it exactly as they do for `isLoading`; a custom UI
+     * should treat it the same way. Never true for a pill without a source.
+     */
+    isSearchingOptions: boolean;
     isDropdownOpen: boolean;
     /**
      * Whether the active (leading) pill should render in its `selected` state
@@ -561,7 +647,22 @@ interface CoreOptions {
      * the dropdown changes — no request, no markup, no layout shift.
      */
     products?: ProductsConfig;
+    /** Called when the user submits (Enter, or the submit button in Tier 1). */
     onSubmit?: (result: AutocompleteResult) => void;
+    /**
+     * Called after every successful suggestion round-trip with the structured
+     * query as the SDK now understands it — the same `AutocompleteResult` shape
+     * `onSubmit` delivers, so a consumer can mirror the query as it is built
+     * (a live preview, a draft, analytics) without waiting for submit.
+     *
+     * Fires once per response that was applied, including the initial request
+     * on mount (an empty result) and after a response that promoted typed text
+     * into a completed param. Does not fire for a request that failed, was
+     * aborted, or was superseded by a newer one before it returned. Nothing
+     * fires for a keystroke that hasn't been sent yet — read `getResult()` for
+     * the current value on demand.
+     */
+    onResult?: (result: AutocompleteResult) => void;
     onError?: (error: Error) => void;
     onChange?: (text: string) => void;
     onParamsChange?: (params: CompletedParamState[]) => void;
@@ -591,6 +692,7 @@ interface CoreOptions {
 
 type AIAutocompleteEvents = {
     submit: [result: AutocompleteResult];
+    result: [result: AutocompleteResult];
     error: [error: Error];
     change: [text: string];
     paramsChange: [params: CompletedParamState[]];
@@ -599,7 +701,7 @@ type AIAutocompleteEvents = {
     blur: [];
     productSelect: [product: Product];
 };
-type CoreUpdateOptions = Partial<Omit<CoreOptions, "onSubmit" | "onError" | "onChange" | "onParamsChange" | "onStateChange" | "onFocus" | "onBlur" | "onProductSelect" | "styleRoot">>;
+type CoreUpdateOptions = Partial<Omit<CoreOptions, "onSubmit" | "onResult" | "onError" | "onChange" | "onParamsChange" | "onStateChange" | "onFocus" | "onBlur" | "onProductSelect" | "styleRoot">>;
 declare class AIAutocomplete {
     private inputStore;
     private store;
@@ -609,6 +711,7 @@ declare class AIAutocomplete {
     private keyboardController;
     private pillsController;
     private productsController;
+    private optionSource;
     private reEdit;
     private modeController;
     private container;
@@ -617,11 +720,9 @@ declare class AIAutocomplete {
     private domRefs;
     private dropdownRefs;
     private timers;
-    /** One per instance — see {@link ConsumerBoundary}. Shared by the emitter, `subscribe()` and `optionOverrides`. */
+    /** One per instance — see {@link ConsumerBoundary}. Shared by the emitter and `subscribe()`. */
     private boundary;
     /** Identity of the raw override record the wrapped copy below was built from. */
-    private rawOverrides;
-    private wrappedOverrides;
     private subscriberCount;
     private emitter;
     private sessionId;
@@ -782,6 +883,14 @@ declare class AIAutocomplete {
      */
     subscribe(listener: (state: CoreState) => void): () => void;
     getState(): CoreState;
+    /**
+     * The structured query as the SDK understands it right now — the same
+     * object `onResult` delivers after each response and `onSubmit` delivers
+     * on submit. Read it on demand from a place that has no event handy (a
+     * custom submit button, a "save draft" action).
+     */
+    getResult(): AutocompleteResult;
+    private buildResult;
     get listboxId(): string;
     get isReady(): boolean;
     /**
@@ -797,24 +906,6 @@ declare class AIAutocomplete {
     selectOption(option: SuggestionOption): void;
     private startSelectionAnimationTimer;
     private fireTelemetry;
-    /**
-     * `this.opts` with every `optionOverrides` entry wrapped in the instance's
-     * {@link ConsumerBoundary}.
-     *
-     * The derive layer calls these functions on the SDK's stack — from
-     * `getState()`, and from inside the store's notification drain — so an
-     * un-wrapped throw would unwind whatever internal operation triggered the
-     * derive and abort delivery of every queued notification with it, taking the
-     * instance down rather than just the override. Wrapped, a failed override
-     * answers `undefined` and each call site falls back to the server's options.
-     *
-     * Memoized on the raw record's identity so a swapped integration is
-     * re-wrapped while a stable one isn't re-wrapped on every derive. Note
-     * `update({ optionOverrides })` only becomes visible on the next store write
-     * — the derived layer memoizes on inputs identity, and `update` doesn't
-     * invalidate it for this key. Pre-existing, and unchanged by the wrapping.
-     */
-    private deriveOpts;
     private setupContainer;
     private buildAndRenderFull;
     private buildAndRenderDropdown;
@@ -1024,12 +1115,18 @@ declare function needsOptionsGridMeasurement(count: number, isMobile: boolean):
  *
  * Web, five-plus options: two columns of three visible rows — but only when
  * every option provably fits on one line. Rows fill row-major (even indices
- * left, odd right), each column is as wide as its widest option, and the
- * columns may be unequal: the template splits the width in proportion to the
- * two column maxima, so whenever `left + right <= gridWidth`, each column gets
- * at least what its widest row needs. When the pair doesn't fit — or there are
- * no usable measurements (SSR, hidden grid, loading skeletons) — the layout
- * stays one scrollable column.
+ * left, odd right). The left track is exactly as wide as its widest option
+ * (a fixed pixel width from the measurement) and the right track takes the
+ * rest of the grid — which is at least its own widest option, because
+ * `left + right <= gridWidth` is the fit check. So the second column starts
+ * right where the first column's longest text ends, and short options such as
+ * sizes sit beside each other. (Splitting the width in proportion to the two
+ * maxima, as this used to, handed ALL the slack out in that ratio too: one
+ * long option in the left column and "34"-length options on the right gave
+ * the left column ~85% of the box and pushed the right column to the far
+ * edge, 2026-09-03.) When the pair doesn't fit — or there are no usable
+ * measurements (SSR, hidden grid, loading skeletons) — the layout stays one
+ * scrollable column.
  *
  * `rowWidths` are single-line pixel widths of the rendered rows (see
  * `measureOptionsGrid`); `gridWidth` is the grid's content width.
@@ -1189,10 +1286,17 @@ declare function renderEditableContent(args: RenderEditableArgs): void;
  * When the option list is taller than its scroll box, a small round button
  * with a down chevron sits at the bottom-centre of the list. It slides up into
  * view from behind the dropdown's lower edge (the footer, when the dropdown
- * opens below the input) the moment there is more to scroll to, slides back
- * down once the list is scrolled to its end, and scrolls the list a page on
- * click. The reference (the RB2B support panel, 2026-08-19): a white 32 px
- * disc that rises from behind the composer over ~150–180 ms, no fade.
+ * opens below the input) the moment there is more to scroll to, dissolves in
+ * place once the list is scrolled to its end, and scrolls the list a page on
+ * click. The entrance follows the reference (the RB2B support panel,
+ * 2026-08-19): a white 32 px disc that rises from behind the composer over
+ * ~150–180 ms, no fade. The exit deliberately does not mirror it — sliding
+ * back down read as the disc "falling" into the footer (2026-09-03), so
+ * instead it fades out where it stands, with a slight shrink, over
+ * SCROLL_ARROW_LEAVE_MS. The stylesheets key the two moves off two attributes:
+ * `data-aia-visible` (rise, stay) and `data-aia-leaving` (dissolve), which
+ * this controller holds for the fade's length and then clears, so the disc
+ * re-parks below the edge — invisibly — ready to rise again.
  *
  * The DOM differs per package (vanilla builds the button here; React and
  * Angular render their own markup with the same classes and data attributes),
@@ -1215,6 +1319,16 @@ declare const SCROLL_ARROW_CLASS = "magicx-aia-scroll-arrow";
 declare const SCROLL_ARROW_ATTR = "data-aia-scroll-arrow";
 /** Present on the button while it is shown. The stylesheets slide it in on this. */
 declare const SCROLL_ARROW_VISIBLE_ATTR = "data-aia-visible";
+/**
+ * Present on the button while it fades out. The stylesheets dissolve it in
+ * place on this; the controller clears it after SCROLL_ARROW_LEAVE_MS.
+ */
+declare const SCROLL_ARROW_LEAVING_ATTR = "data-aia-leaving";
+/**
+ * Length of the fade-out. Mirrors the `[data-aia-leaving]` transition in each
+ * package's stylesheet — change both together.
+ */
+declare const SCROLL_ARROW_LEAVE_MS = 240;
 /** Inline custom property: how far the button's bottom edge sits above the dropdown's padding edge. */
 declare const SCROLL_ARROW_BOTTOM_VAR = "--aia-scroll-arrow-bottom";
 declare const SCROLL_ARROW_LABEL = "Scroll down for more options";
@@ -1289,6 +1403,16 @@ declare function getFooterHint(optionHighlighted: boolean, isInputEmpty: boolean
     hint: string;
 };
 
+/**
+ * Projects client-side identified-param state onto its wire shape.
+ *
+ * The one place the `{ type, value }` form is spelled out. Both the request
+ * body (`api.ts`) and the `AutocompleteResult` handed to `onResult` /
+ * `onSubmit` go through it, so the params the consumer receives are exactly
+ * the ones the server was told about.
+ */
+declare function toWireIdentifiedParams(params: IdentifiedParamState[]): IdentifiedParam[];
+
 declare class ModeController {
     private container;
     private mode;
@@ -1342,14 +1466,25 @@ declare const SKIPPED_PARAM_TEXT = "skipped";
 declare function withSkippedParams(completed: CompletedParam[], skipped: SkippedParamState[]): CompletedParam[];
 
 /**
- * Builds the `AutocompleteResult` handed to `onSubmit`: the placeholder-
- * tokenized raw query plus the completed params, with skipped suggestions
- * folded in (see {@link withSkippedParams}).
+ * Fields of an {@link AutocompleteResult} that come from the latest server
+ * response rather than from the input. Both default to "nothing yet".
+ */
+interface SubmitResultExtras {
+    /** Server-identified params (`state.identifiedParams`). Default: none. */
+    identifiedParams?: IdentifiedParamState[];
+    /** Server's "query is complete" verdict (`state.isReady`). Default: false. */
+    isReady?: boolean;
+}
+/**
+ * Builds the `AutocompleteResult` handed to `onSubmit` and `onResult`: the
+ * placeholder-tokenized raw query plus the completed params, with skipped
+ * suggestions folded in (see {@link withSkippedParams}), the server-identified
+ * params in their wire shape, and the server's readiness verdict.
  *
  * Shared by every submit path — vanilla Enter / submit button, the React Tier 1
- * component, the Angular Tier 1 component — so they can't drift on what a
- * result contains.
+ * component, the Angular Tier 1 component — and by the core's per-response
+ * `result` event, so none of them can drift on what a result contains.
  */
-declare function buildSubmitResult(text: string, completedParams: CompletedParamState[], skippedParams?: SkippedParamState[]): AutocompleteResult;
+declare function buildSubmitResult(text: string, completedParams: CompletedParamState[], skippedParams?: SkippedParamState[], extras?: SubmitResultExtras): AutocompleteResult;
 
-export { AIAutocomplete, type APIConfig, type APIKeyConfig, ATTRIBUTION_URL, type AccessTokenConfig, type AccessTokenResult, type AppearanceMode, type AutocompleteRequest, type AutocompleteResponse, type AutocompleteResult, type CompletedParam, type CompletedParamState, type CoreOptions, type CoreState, type DateMonthView, type FormatType, type IdentifiedParam, type IdentifiedParamState, type InputItem, type LooseDateOptions, ModeController, OPTIONS_GRID_MOBILE_QUERY, OPTION_ENTER_DELAY_VAR, OPTION_ENTER_FADE_MS, OPTION_ENTER_RISE_MS, OPTION_ENTER_RISE_PX, OPTION_ENTER_STAGGER_MS, type OptionOverrides, type OptionsGridLayout, type OptionsGridPlan, PLACEHOLDER_FADE_OUT_MS, PLACEHOLDER_LEAVING_ATTR, PLACEHOLDER_SWAP_GAP_MS, PLACEHOLDER_TYPE_MS, PLACEHOLDER_WORD_PAUSE_MS, type Product, type ProductsConfig, type RecentlySuggested, type RenderMode, SCROLL_ARROW_ATTR, SCROLL_ARROW_BOTTOM_VAR, SCROLL_ARROW_CLASS, SCROLL_ARROW_LABEL, SCROLL_ARROW_VISIBLE_ATTR, SKIPPED_PARAM_TEXT, type ScrollArrowArgs, type ScrollArrowController, type Segment, type SkippedParamState, type Store, type 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 };
+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 };