@magicx-eng/ai-autocomplete-vanilla 0.33.0 → 0.34.0

package/README.md

@@ -648,7 +648,8 @@ unsub();
 | `clearNewParamId()` | Clear shimmer animation state. |
 | `reset()` | Clear all state, re-fetch initial suggestions, and start a new session (rotates `session_id`). Call this after handling submit. |
 | `recordSubmit(result)` | Record a submit from a button you render. Enter and the built-in button are recorded for you; call this once per submit from your own button. |
-| `setValue(text)` | Set text (controlled mode). |
+| `setValue(text)` | Set text (controlled mode). Text set this way is not reported as the user starting a search. |
+| `prefillText(text)` | Fill the field with text the user did not type — e.g. a query carried over from the previous page — and handle it like typing: suggestions are fetched and the text is recognized. Not reported as the user starting a search. |
 | `setCompletedParams(params)` | Set completed params (controlled mode). |
 | `setMode(mode)` | Switch color mode at runtime. |
 | `update(opts)` | Update multiple options at once (e.g. `animations`, `pillPlacement`, `dropdownTrigger`, `optionsPosition`). |

package/dist/index.d.mts

@@ -1099,6 +1099,21 @@ declare class AIAutocomplete {
     private resetAfterSubmit;
     destroy(): void;
     setMode(mode: AppearanceMode): void;
+    /**
+     * Fill the field with text the shopper did not type — a query carried over
+     * from the previous page, say — and handle it as if typed: suggestions are
+     * fetched and the text is re-identified. Unlike typing, it does not count as
+     * the shopper starting a search.
+     */
+    prefillText(text: string): void;
+    /**
+     * Reports `search_started` once per session, when the shopper (not the
+     * consumer) first puts something in an empty field: typing, or picking an
+     * option. Decided at the call, not in a store subscriber: a consumer write
+     * made from inside a listener is delivered after its call returns, so a
+     * subscriber cannot tell whose write it is.
+     */
+    private noteSearchStarted;
     setValue(text: string): void;
     setCompletedParams(params: CompletedParamState[]): void;
     setActivePill(index: number): void;
@@ -1215,6 +1230,7 @@ declare class AIAutocomplete {
      */
     selectProduct(product: Product): void;
     handleTextChange(value: string): void;
+    private applyTextChange;
     /** 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. */
@@ -1282,6 +1298,7 @@ declare class AIAutocomplete {
     on<E extends keyof AIAutocompleteEvents>(event: E, callback: (...args: AIAutocompleteEvents[E]) => void): () => void;
     update(opts: CoreUpdateOptions): void;
     selectOption(option: SuggestionOption): void;
+    private applyOption;
     private startSelectionAnimationTimer;
     private resolveVisitorId;
     private resolveSource;
@@ -1737,6 +1754,36 @@ declare function getCursorOffset(root: HTMLElement): number | null;
  * get the browser's own scroll-to-caret behaviour.
  */
 declare function setCursorOffset(root: HTMLElement, offset: number): void;
+/**
+ * The chip a tap or click landed on, or null.
+ *
+ * Re-edit otherwise starts only from `selectionchange`, i.e. from wherever
+ * the browser put the caret — which on touch devices is frequently not the
+ * chip the finger was on. iOS Safari snaps a tap's caret to a word boundary
+ * and, on the tap that focuses the field, commonly parks it at the end of the
+ * text: inside the last chip when the input ends with one. The event target
+ * is the element actually hit, so a tap anywhere on the chip, edges and
+ * padding included, selects it.
+ *
+ * Both chip kinds report, matching the selectionchange path: the core decides
+ * what a tap means (a completed param re-opens its options, an identified date
+ * opens the calendar, anything else is inert).
+ *
+ * Returns null when the gesture left a range selection (a drag-select that
+ * ends on a chip is a selection, not a tap).
+ */
+declare function chipIdFromTap(root: HTMLElement, target: EventTarget | null): string | null;
+/**
+ * After a tap on a chip, make sure the caret is on that chip.
+ *
+ * The browser may have put the tap's caret somewhere else entirely (see
+ * `chipIdFromTap`). Left there, the next `selectionchange` reads it as the
+ * caret leaving the chip — or entering a different one — and closes or
+ * redirects what the tap just opened. A caret already within the chip's
+ * bounds (edges included) is left alone; otherwise it moves to the chip's
+ * start, which every edit range includes.
+ */
+declare function keepCaretOnChip(root: HTMLElement, paramId: string): void;
 /**
  * True when the caret offset equals the editable's plain-text length —
  * meaning the only content to the right is non-editable (e.g. trailing pills).
@@ -2252,4 +2299,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 CustomFieldsReport, DATE_RANGE_META_END, DATE_RANGE_META_START, DEFAULT_OPTION_COUNT_UNIT, type DateMonthView, type DateRange, type DateSelection, type ExpressedFilter, type FilterOp, type FormatType, type IdentifiedParam, type IdentifiedParamState, type InputItem, type LooseDateOptions, type MatchedItem, type MatchedItems, 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, PRODUCT_PATH_PREFIX, PRODUCT_ROW_PX_PER_LINE, type Product, type ProductImageFallback, type ProductRowMetrics, type ProductRowWheel, type ProductsConfig, type ProductsLayout, 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, attachProductRowWheel, attachScrollArrow, buildAttributionUrl, buildDateOptions, buildQuery, buildSubmitResult, cellDay, cellIso, computeOptionsGridLayout, containScroll, createStore, cursorIsAtEnd, dateCellMarks, dateSelectionFor, extractPlainText, formatAbsoluteDate, formatDate, formatDateRange, formatOptionCount, getCursorOffset, getFooterHint, identifiedParamLabel, isCalendarFormat, isOptionsGridMobileViewport, isoDate, measureOptionsGrid, monthLabel, needsOptionsGridMeasurement, optionCountLabel, optionEnterDelayMs, optionHasImage, optionImageSrc, optionLabel, optionsEntranceDurationMs, optionsGridTemplateColumns, parseDate, parseLooseDate, parseLooseDateRange, plainTextLength, planOptionsGrid, previousGraphemeBoundary, productFromMatchedItem, productInitial, productRowWheelTarget, productsFromCustomFields, renderEditableContent, resolveFormatType, resolveIdentifiedDate, sameOptionRows, sanitizeOptionIconSvg, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, toWireIdentifiedParams, visibleDateRange, 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 CustomFieldsReport, DATE_RANGE_META_END, DATE_RANGE_META_START, DEFAULT_OPTION_COUNT_UNIT, type DateMonthView, type DateRange, type DateSelection, type ExpressedFilter, type FilterOp, type FormatType, type IdentifiedParam, type IdentifiedParamState, type InputItem, type LooseDateOptions, type MatchedItem, type MatchedItems, 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, PRODUCT_PATH_PREFIX, PRODUCT_ROW_PX_PER_LINE, type Product, type ProductImageFallback, type ProductRowMetrics, type ProductRowWheel, type ProductsConfig, type ProductsLayout, 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, attachProductRowWheel, attachScrollArrow, buildAttributionUrl, buildDateOptions, buildQuery, buildSubmitResult, cellDay, cellIso, chipIdFromTap, computeOptionsGridLayout, containScroll, createStore, cursorIsAtEnd, dateCellMarks, dateSelectionFor, extractPlainText, formatAbsoluteDate, formatDate, formatDateRange, formatOptionCount, getCursorOffset, getFooterHint, identifiedParamLabel, isCalendarFormat, isOptionsGridMobileViewport, isoDate, keepCaretOnChip, measureOptionsGrid, monthLabel, needsOptionsGridMeasurement, optionCountLabel, optionEnterDelayMs, optionHasImage, optionImageSrc, optionLabel, optionsEntranceDurationMs, optionsGridTemplateColumns, parseDate, parseLooseDate, parseLooseDateRange, plainTextLength, planOptionsGrid, previousGraphemeBoundary, productFromMatchedItem, productInitial, productRowWheelTarget, productsFromCustomFields, renderEditableContent, resolveFormatType, resolveIdentifiedDate, sameOptionRows, sanitizeOptionIconSvg, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, toWireIdentifiedParams, visibleDateRange, withSkippedParams };

package/dist/index.d.ts

@@ -1099,6 +1099,21 @@ declare class AIAutocomplete {
     private resetAfterSubmit;
     destroy(): void;
     setMode(mode: AppearanceMode): void;
+    /**
+     * Fill the field with text the shopper did not type — a query carried over
+     * from the previous page, say — and handle it as if typed: suggestions are
+     * fetched and the text is re-identified. Unlike typing, it does not count as
+     * the shopper starting a search.
+     */
+    prefillText(text: string): void;
+    /**
+     * Reports `search_started` once per session, when the shopper (not the
+     * consumer) first puts something in an empty field: typing, or picking an
+     * option. Decided at the call, not in a store subscriber: a consumer write
+     * made from inside a listener is delivered after its call returns, so a
+     * subscriber cannot tell whose write it is.
+     */
+    private noteSearchStarted;
     setValue(text: string): void;
     setCompletedParams(params: CompletedParamState[]): void;
     setActivePill(index: number): void;
@@ -1215,6 +1230,7 @@ declare class AIAutocomplete {
      */
     selectProduct(product: Product): void;
     handleTextChange(value: string): void;
+    private applyTextChange;
     /** 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. */
@@ -1282,6 +1298,7 @@ declare class AIAutocomplete {
     on<E extends keyof AIAutocompleteEvents>(event: E, callback: (...args: AIAutocompleteEvents[E]) => void): () => void;
     update(opts: CoreUpdateOptions): void;
     selectOption(option: SuggestionOption): void;
+    private applyOption;
     private startSelectionAnimationTimer;
     private resolveVisitorId;
     private resolveSource;
@@ -1737,6 +1754,36 @@ declare function getCursorOffset(root: HTMLElement): number | null;
  * get the browser's own scroll-to-caret behaviour.
  */
 declare function setCursorOffset(root: HTMLElement, offset: number): void;
+/**
+ * The chip a tap or click landed on, or null.
+ *
+ * Re-edit otherwise starts only from `selectionchange`, i.e. from wherever
+ * the browser put the caret — which on touch devices is frequently not the
+ * chip the finger was on. iOS Safari snaps a tap's caret to a word boundary
+ * and, on the tap that focuses the field, commonly parks it at the end of the
+ * text: inside the last chip when the input ends with one. The event target
+ * is the element actually hit, so a tap anywhere on the chip, edges and
+ * padding included, selects it.
+ *
+ * Both chip kinds report, matching the selectionchange path: the core decides
+ * what a tap means (a completed param re-opens its options, an identified date
+ * opens the calendar, anything else is inert).
+ *
+ * Returns null when the gesture left a range selection (a drag-select that
+ * ends on a chip is a selection, not a tap).
+ */
+declare function chipIdFromTap(root: HTMLElement, target: EventTarget | null): string | null;
+/**
+ * After a tap on a chip, make sure the caret is on that chip.
+ *
+ * The browser may have put the tap's caret somewhere else entirely (see
+ * `chipIdFromTap`). Left there, the next `selectionchange` reads it as the
+ * caret leaving the chip — or entering a different one — and closes or
+ * redirects what the tap just opened. A caret already within the chip's
+ * bounds (edges included) is left alone; otherwise it moves to the chip's
+ * start, which every edit range includes.
+ */
+declare function keepCaretOnChip(root: HTMLElement, paramId: string): void;
 /**
  * True when the caret offset equals the editable's plain-text length —
  * meaning the only content to the right is non-editable (e.g. trailing pills).
@@ -2252,4 +2299,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 CustomFieldsReport, DATE_RANGE_META_END, DATE_RANGE_META_START, DEFAULT_OPTION_COUNT_UNIT, type DateMonthView, type DateRange, type DateSelection, type ExpressedFilter, type FilterOp, type FormatType, type IdentifiedParam, type IdentifiedParamState, type InputItem, type LooseDateOptions, type MatchedItem, type MatchedItems, 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, PRODUCT_PATH_PREFIX, PRODUCT_ROW_PX_PER_LINE, type Product, type ProductImageFallback, type ProductRowMetrics, type ProductRowWheel, type ProductsConfig, type ProductsLayout, 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, attachProductRowWheel, attachScrollArrow, buildAttributionUrl, buildDateOptions, buildQuery, buildSubmitResult, cellDay, cellIso, computeOptionsGridLayout, containScroll, createStore, cursorIsAtEnd, dateCellMarks, dateSelectionFor, extractPlainText, formatAbsoluteDate, formatDate, formatDateRange, formatOptionCount, getCursorOffset, getFooterHint, identifiedParamLabel, isCalendarFormat, isOptionsGridMobileViewport, isoDate, measureOptionsGrid, monthLabel, needsOptionsGridMeasurement, optionCountLabel, optionEnterDelayMs, optionHasImage, optionImageSrc, optionLabel, optionsEntranceDurationMs, optionsGridTemplateColumns, parseDate, parseLooseDate, parseLooseDateRange, plainTextLength, planOptionsGrid, previousGraphemeBoundary, productFromMatchedItem, productInitial, productRowWheelTarget, productsFromCustomFields, renderEditableContent, resolveFormatType, resolveIdentifiedDate, sameOptionRows, sanitizeOptionIconSvg, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, toWireIdentifiedParams, visibleDateRange, 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 CustomFieldsReport, DATE_RANGE_META_END, DATE_RANGE_META_START, DEFAULT_OPTION_COUNT_UNIT, type DateMonthView, type DateRange, type DateSelection, type ExpressedFilter, type FilterOp, type FormatType, type IdentifiedParam, type IdentifiedParamState, type InputItem, type LooseDateOptions, type MatchedItem, type MatchedItems, 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, PRODUCT_PATH_PREFIX, PRODUCT_ROW_PX_PER_LINE, type Product, type ProductImageFallback, type ProductRowMetrics, type ProductRowWheel, type ProductsConfig, type ProductsLayout, 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, attachProductRowWheel, attachScrollArrow, buildAttributionUrl, buildDateOptions, buildQuery, buildSubmitResult, cellDay, cellIso, chipIdFromTap, computeOptionsGridLayout, containScroll, createStore, cursorIsAtEnd, dateCellMarks, dateSelectionFor, extractPlainText, formatAbsoluteDate, formatDate, formatDateRange, formatOptionCount, getCursorOffset, getFooterHint, identifiedParamLabel, isCalendarFormat, isOptionsGridMobileViewport, isoDate, keepCaretOnChip, measureOptionsGrid, monthLabel, needsOptionsGridMeasurement, optionCountLabel, optionEnterDelayMs, optionHasImage, optionImageSrc, optionLabel, optionsEntranceDurationMs, optionsGridTemplateColumns, parseDate, parseLooseDate, parseLooseDateRange, plainTextLength, planOptionsGrid, previousGraphemeBoundary, productFromMatchedItem, productInitial, productRowWheelTarget, productsFromCustomFields, renderEditableContent, resolveFormatType, resolveIdentifiedDate, sameOptionRows, sanitizeOptionIconSvg, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, toWireIdentifiedParams, visibleDateRange, withSkippedParams };