@magicx-eng/ai-autocomplete-vanilla 0.19.3 → 0.20.1

package/README.md

@@ -88,6 +88,8 @@ const ac = new AIAutocomplete(container, {
   closeDropdownOnBlur: true, // false = keep dropdown open even when input loses focus
   showNonTappableOptions: true, // false = hide non-tappable options from the dropdown
   showSkipButton: true,      // false = hide the pill bar's trailing "skip" button
+  showOptionIcons: true,     // false = render option rows as text only (no icons)
+  showChipIcons: true,       // false = render completed chips as text only (no icons)
 
   // Focus
   autoFocus: true,           // focus the input on mount (Tier 1 only)
@@ -455,6 +457,9 @@ unsub();
 
 
 > **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.
+
+> **Option icons.** An option may carry an icon: `icon_svg` is inline SVG markup and `icon` its name. The built-in dropdown draws the SVG before the option's text, in the text color, and hides it while the row shows its loading skeleton. When rendering options yourself, pass `icon_svg` through the exported `sanitizeOptionIconSvg` before inserting it — it reduces the markup to plain vector drawing and returns `null` for anything else — and use `optionLabel(option)` for the text, which keeps an `icon` that has no `icon_svg` as a legacy text prefix. A picked option's `icon` / `icon_svg` are copied onto its completed parameter, and the chip in the input draws the glyph before its text. Both surfaces can be switched off: `showOptionIcons: false` renders option rows as text only and `showChipIcons: false` renders chips as text only; either way the icon element is omitted rather than hidden.
+
 ### State shape (`CoreState`)
 
 | Field | Type | Description |

package/dist/index.d.mts

@@ -7,7 +7,19 @@ interface CompletedParam {
 }
 interface SuggestionOption {
     text: string;
+    /**
+     * Icon for the option. When `icon_svg` is also set this is the icon's name
+     * (an identifier such as `"apple"`, exposed on the row as `data-aia-icon`)
+     * and the SVG is what renders. Without `icon_svg` it is legacy display text
+     * (an emoji, say) drawn as a prefix to `text`.
+     */
     icon?: string;
+    /**
+     * Inline SVG markup for the option's icon, drawn before `text` in the
+     * option's text color. Passed through `sanitizeOptionIconSvg` before it
+     * touches the DOM; markup that fails it renders no icon.
+     */
+    icon_svg?: string;
     tag?: string;
     is_tappable: boolean;
     kind: TaskKind | null;
@@ -78,6 +90,13 @@ interface CompletedParamState extends CompletedParam {
     /** Cached options from the suggestion that produced this param — re-edit shows these. */
     options: SuggestionOption[];
     metadata?: Record<string, unknown>;
+    /**
+     * The picked option's `icon` / `icon_svg`, carried over so the completed
+     * chip in the input draws the same glyph its option row did. Absent when a
+     * consumer restores params itself or the answer came from a calendar.
+     */
+    icon?: string;
+    icon_svg?: string;
 }
 /**
  * A suggestion the user dismissed with the skip key (→) instead of filling.
@@ -662,6 +681,10 @@ interface CoreOptions {
     closeDropdownOnBlur?: boolean;
     /** When true (default), non-tappable options are rendered in the dropdown alongside tappable ones. Set to false to hide them entirely. */
     showNonTappableOptions?: boolean;
+    /** When true (default), an option that carries an `icon_svg` draws its icon before its text in the dropdown. Set to false to render option rows as text only. */
+    showOptionIcons?: boolean;
+    /** When true (default), a completed chip in the input draws the icon of the option that answered it. Set to false to render chips as text only. */
+    showChipIcons?: boolean;
     /**
      * When true (default), the dropdown's pill bar ends in a small "skip" button
      * that dismisses the active pill — same action as pressing → at the end of
@@ -1426,6 +1449,31 @@ declare function previousGraphemeBoundary(text: string, offset: number): number;
  */
 declare function scrollCaretIntoView(root: HTMLElement): void;
 
+/**
+ * Reduces an option's `icon_svg` markup to plain vector drawing before it is
+ * inserted into the dropdown. The icons come from the server's own curated
+ * set, but markup landing in a consumer's page is a trust boundary, so every
+ * icon is parsed and filtered through an allowlist rather than inserted raw:
+ * only the elements in `ALLOWED_ELEMENTS` survive, stripped of any attribute
+ * that could run script or fetch a resource. The root is marked
+ * `aria-hidden` / non-focusable — the option's text is its accessible name.
+ *
+ * Returns the serialized `<svg>` to insert, or `null` when the markup is not
+ * a well-formed SVG document (or the environment has no `DOMParser`, as in
+ * server rendering), in which case the option renders without an icon.
+ */
+declare function sanitizeOptionIconSvg(markup: string): string | null;
+/**
+ * The text an option row shows. With `icon_svg` the icon draws as its own
+ * element and `icon` is just its name; without it, a legacy `icon` (an emoji
+ * from an option override, say) is display text prefixed to the option.
+ */
+declare function optionLabel(option: {
+    text: string;
+    icon?: string;
+    icon_svg?: string;
+}): string;
+
 /**
  * Types the starting-state placeholder into the input one character at a
  * time instead of popping it in whole.
@@ -1463,6 +1511,8 @@ interface RenderEditableArgs {
     editingParamId: string | null;
     placeholderText: string;
     isFocused: boolean;
+    /** Whether completed chips draw the icon of the option that answered them. Default: true. */
+    showChipIcons?: boolean;
 }
 /**
  * Renders text segments into the contentEditable input. Completed params are
@@ -1693,4 +1743,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, 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 };
+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, optionLabel, optionsEntranceDurationMs, optionsGridTemplateColumns, parseDate, parseLooseDate, parseLooseDateRange, plainTextLength, planOptionsGrid, previousGraphemeBoundary, renderEditableContent, resolveFormatType, resolveIdentifiedDate, sanitizeOptionIconSvg, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, toWireIdentifiedParams, visibleDateRange, withSkippedParams };

package/dist/index.d.ts

@@ -7,7 +7,19 @@ interface CompletedParam {
 }
 interface SuggestionOption {
     text: string;
+    /**
+     * Icon for the option. When `icon_svg` is also set this is the icon's name
+     * (an identifier such as `"apple"`, exposed on the row as `data-aia-icon`)
+     * and the SVG is what renders. Without `icon_svg` it is legacy display text
+     * (an emoji, say) drawn as a prefix to `text`.
+     */
     icon?: string;
+    /**
+     * Inline SVG markup for the option's icon, drawn before `text` in the
+     * option's text color. Passed through `sanitizeOptionIconSvg` before it
+     * touches the DOM; markup that fails it renders no icon.
+     */
+    icon_svg?: string;
     tag?: string;
     is_tappable: boolean;
     kind: TaskKind | null;
@@ -78,6 +90,13 @@ interface CompletedParamState extends CompletedParam {
     /** Cached options from the suggestion that produced this param — re-edit shows these. */
     options: SuggestionOption[];
     metadata?: Record<string, unknown>;
+    /**
+     * The picked option's `icon` / `icon_svg`, carried over so the completed
+     * chip in the input draws the same glyph its option row did. Absent when a
+     * consumer restores params itself or the answer came from a calendar.
+     */
+    icon?: string;
+    icon_svg?: string;
 }
 /**
  * A suggestion the user dismissed with the skip key (→) instead of filling.
@@ -662,6 +681,10 @@ interface CoreOptions {
     closeDropdownOnBlur?: boolean;
     /** When true (default), non-tappable options are rendered in the dropdown alongside tappable ones. Set to false to hide them entirely. */
     showNonTappableOptions?: boolean;
+    /** When true (default), an option that carries an `icon_svg` draws its icon before its text in the dropdown. Set to false to render option rows as text only. */
+    showOptionIcons?: boolean;
+    /** When true (default), a completed chip in the input draws the icon of the option that answered it. Set to false to render chips as text only. */
+    showChipIcons?: boolean;
     /**
      * When true (default), the dropdown's pill bar ends in a small "skip" button
      * that dismisses the active pill — same action as pressing → at the end of
@@ -1426,6 +1449,31 @@ declare function previousGraphemeBoundary(text: string, offset: number): number;
  */
 declare function scrollCaretIntoView(root: HTMLElement): void;
 
+/**
+ * Reduces an option's `icon_svg` markup to plain vector drawing before it is
+ * inserted into the dropdown. The icons come from the server's own curated
+ * set, but markup landing in a consumer's page is a trust boundary, so every
+ * icon is parsed and filtered through an allowlist rather than inserted raw:
+ * only the elements in `ALLOWED_ELEMENTS` survive, stripped of any attribute
+ * that could run script or fetch a resource. The root is marked
+ * `aria-hidden` / non-focusable — the option's text is its accessible name.
+ *
+ * Returns the serialized `<svg>` to insert, or `null` when the markup is not
+ * a well-formed SVG document (or the environment has no `DOMParser`, as in
+ * server rendering), in which case the option renders without an icon.
+ */
+declare function sanitizeOptionIconSvg(markup: string): string | null;
+/**
+ * The text an option row shows. With `icon_svg` the icon draws as its own
+ * element and `icon` is just its name; without it, a legacy `icon` (an emoji
+ * from an option override, say) is display text prefixed to the option.
+ */
+declare function optionLabel(option: {
+    text: string;
+    icon?: string;
+    icon_svg?: string;
+}): string;
+
 /**
  * Types the starting-state placeholder into the input one character at a
  * time instead of popping it in whole.
@@ -1463,6 +1511,8 @@ interface RenderEditableArgs {
     editingParamId: string | null;
     placeholderText: string;
     isFocused: boolean;
+    /** Whether completed chips draw the icon of the option that answered them. Default: true. */
+    showChipIcons?: boolean;
 }
 /**
  * Renders text segments into the contentEditable input. Completed params are
@@ -1693,4 +1743,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, 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 };
+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, optionLabel, optionsEntranceDurationMs, optionsGridTemplateColumns, parseDate, parseLooseDate, parseLooseDateRange, plainTextLength, planOptionsGrid, previousGraphemeBoundary, renderEditableContent, resolveFormatType, resolveIdentifiedDate, sanitizeOptionIconSvg, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, toWireIdentifiedParams, visibleDateRange, withSkippedParams };