@magicx-eng/ai-autocomplete-react 0.24.2 → 0.25.0

package/README.md

@@ -288,6 +288,8 @@ Skip `<AIAutocompleteDropdown />` and render the suggestions UI yourself. `dropd
 
 > **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 — it is the option's `text` alone; `icon` is the icon's name and is never shown as text, even when `icon_svg` is missing or fails to draw. 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.
 
+> **Option pictures and counts.** An option may also carry `image_url` — a picture of the best-matching catalog item offering it — and `item_count`, how many items offer it (each is present only when the server includes it; when it includes counts, the options also arrive ordered by them, most items first; a starting state carries pictures but no counts). The built-in dropdown draws the picture as a square thumbnail before the option's text (in place of its `icon_svg`, so a row never leads with two visuals) and the count as a muted label at the row's trailing edge (`"12 items"`); a skeleton row keeps the tile's placeholder fill and hides the count. The unit word after the number is a token: set `--aia-option-count-unit: "sneakers"` to name what is being counted, `--aia-option-count-unit-one: "sneaker"` for a count of 1 (it falls back to the plural token), or `--aia-option-count-unit: ""` for the number alone. When rendering options yourself, pass `image_url` through the exported `optionImageSrc` before using it as an `<img src>` — it returns the URL only when it is `http(s)` and `null` otherwise — and `formatOptionCount(option.item_count)` gives the number the built-in rows print (`null` when there is no count); `optionCountLabel(count, unit?)` appends a unit for a dropdown that prints the word itself (`"item"` / `"items"` by default; one word, a `{ one, other }` pair, or `""` for none). Both surfaces can be switched off: `showOptionImages: false` renders rows without pictures (an option's icon then draws instead) and `showOptionCounts: false` hides the counts. A picked option's `image_url` is copied onto its completed parameter too, and the chip in the input draws it as a small rounded tile before its text, in place of the icon; `showChipImages: false` renders chips without pictures (the icon then draws instead). The tile is sized by `--aia-option-image-size` (40px), rounded by `--aia-option-image-radius` (12px), spaced by `--aia-option-image-gap` (12px) and filled by `--aia-option-image-bg` while its picture loads; the count reads `--aia-option-count-font-size` (12px), `--aia-option-count-color` and `--aia-option-count-opacity` (0.6); the chip's tile reads `--aia-chip-image-size` (1.25em of the chip's font), `--aia-chip-image-radius` (4px) and `--aia-chip-image-bg`.
+
 ```tsx
 import { useAIAutocomplete } from "@magicx-eng/ai-autocomplete-react";
 
@@ -351,6 +353,9 @@ function App() {
 | `showSkipButton?` | `boolean` | `true` | When `true`, the dropdown's pill bar ends in a small "skip" button that dismisses the active pill — same action as pressing <kbd>→</kbd> at the end of the input. It sits top-right when the dropdown opens below the input, bottom-right when `optionsPosition` is `"above"`, and appears once the input has text (alongside the footer's "→ to skip" hint). Set to `false` to hide it. |
 | `showOptionIcons?` | `boolean` | `true` | When `true`, 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. |
 | `showChipIcons?` | `boolean` | `true` | When `true`, a completed chip in the input draws the icon of the option that answered it. Set to `false` to render chips as text only. |
+| `showChipImages?` | `boolean` | `true` | When `true`, a completed chip in the input draws the picture (`image_url`) of the option that answered it, in place of its icon. Set to `false` to render chips without pictures. |
+| `showOptionImages?` | `boolean` | `true` | When `true`, an option that carries an `image_url` draws it as a square thumbnail before its text in the dropdown, in place of its icon. Set to `false` to render option rows without pictures. |
+| `showOptionCounts?` | `boolean` | `true` | When `true`, an option that carries an `item_count` shows it as a muted label at the row's trailing edge (`"12 items"`). Set to `false` to hide the counts. |
 | `autoFocus?` | `boolean` | `true` | Focus the input on mount. Set to `false` to leave focus to the consumer. |
 | `onFocus?` | `() => void` | — | Called when the input gains focus. |
 | `onBlur?` | `() => void` | — | Called when the input loses focus. |

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { AutocompleteResult, OptionOverrides, APIConfig, AppearanceMode, CompletedParamState, ProductsLayout, ProductsConfig, Product, Suggestion, SuggestionOption, FormatType, DateMonthView, DateRange, SkippedParamState, IdentifiedParamState, Segment, CustomFieldsReport } from '@magicx-eng/ai-autocomplete-vanilla';
-export { APIConfig, APIKeyConfig, AccessTokenConfig, AccessTokenResult, AppearanceMode, AutocompleteResult, CompletedParam, CompletedParamState, CustomFieldsReport, DATE_RANGE_META_END, DATE_RANGE_META_START, DateMonthView, DateRange, ExpressedFilter, FilterOp, FormatType, IdentifiedParam, IdentifiedParamState, MatchedItem, MatchedItems, OptionOverrides, PRODUCT_PATH_PREFIX, Product, ProductsConfig, ProductsLayout, Segment, SkippedParamState, SubmitResultExtras, Suggestion, SuggestionOption, TaskKind, WEEKDAY_LABELS, buildSubmitResult, cellDay, cellIso, dateCellMarks, formatDate, formatDateRange, isoDate, monthLabel, optionLabel, parseDate, parseLooseDate, parseLooseDateRange, productFromMatchedItem, productsFromCustomFields, sanitizeOptionIconSvg, selectedRangeFor, visibleDateRange, withSkippedParams } from '@magicx-eng/ai-autocomplete-vanilla';
+export { APIConfig, APIKeyConfig, AccessTokenConfig, AccessTokenResult, AppearanceMode, AutocompleteResult, CompletedParam, CompletedParamState, CustomFieldsReport, DATE_RANGE_META_END, DATE_RANGE_META_START, DEFAULT_OPTION_COUNT_UNIT, DateMonthView, DateRange, ExpressedFilter, FilterOp, FormatType, IdentifiedParam, IdentifiedParamState, MatchedItem, MatchedItems, OptionOverrides, PRODUCT_PATH_PREFIX, Product, ProductsConfig, ProductsLayout, Segment, SkippedParamState, SubmitResultExtras, Suggestion, SuggestionOption, TaskKind, WEEKDAY_LABELS, buildSubmitResult, cellDay, cellIso, dateCellMarks, formatDate, formatDateRange, formatOptionCount, isoDate, monthLabel, optionCountLabel, optionHasImage, optionImageSrc, optionLabel, parseDate, parseLooseDate, parseLooseDateRange, productFromMatchedItem, productsFromCustomFields, sanitizeOptionIconSvg, selectedRangeFor, visibleDateRange, withSkippedParams } from '@magicx-eng/ai-autocomplete-vanilla';
 import * as react from 'react';
 import { ReactNode, KeyboardEvent, ChangeEvent } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
@@ -64,6 +64,12 @@ interface AIAutocompleteProps {
     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), a completed chip in the input draws the picture (`image_url`) of the option that answered it, in place of its icon. Set to false to render chips without pictures. */
+    showChipImages?: boolean;
+    /** When true (default), an option that carries an `image_url` draws it as a square thumbnail before its text in the dropdown (in place of its `icon_svg`). Set to false to render option rows without pictures. */
+    showOptionImages?: boolean;
+    /** When true (default), an option that carries an `item_count` shows it as a muted label at the row's trailing edge ("12 items"). Set to false to hide the counts. */
+    showOptionCounts?: 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
@@ -182,6 +188,18 @@ interface UseAIAutocompleteOptions {
      * option's `icon_svg` before its text. Set to false for text-only rows.
      */
     showOptionIcons?: boolean;
+    /**
+     * When true (default), `dropdownProps` asks the dropdown to draw each
+     * option's `image_url` as a thumbnail before its text. Set to false for
+     * rows without pictures.
+     */
+    showOptionImages?: boolean;
+    /**
+     * When true (default), `dropdownProps` asks the dropdown to show each
+     * option's `item_count` at the row's trailing edge. Set to false to hide
+     * the counts.
+     */
+    showOptionCounts?: boolean;
     /**
      * When true (default), `dropdownProps` asks the dropdown to render its
      * trailing "skip" button (see `AIAutocompleteProps.showSkipButton`). Set to
@@ -397,6 +415,18 @@ interface AIAutocompleteDropdownProps {
      * (the hook's `dropdownProps` folds in the `showOptionIcons` option).
      */
     showOptionIcons?: boolean;
+    /**
+     * Whether option rows draw their `image_url` as a square thumbnail before
+     * the text, in place of the icon. Default: true (the hook's `dropdownProps`
+     * folds in the `showOptionImages` option).
+     */
+    showOptionImages?: boolean;
+    /**
+     * Whether option rows show their `item_count` at the trailing edge.
+     * Default: true (the hook's `dropdownProps` folds in the
+     * `showOptionCounts` option).
+     */
+    showOptionCounts?: boolean;
     /**
      * Extra disabled gate for the skip button beyond `isLoading`. Provided by
      * `dropdownProps` from the hook (wired to `inSelectionAnimation`): the
@@ -469,8 +499,8 @@ interface AIAutocompleteDropdownProps {
 
 declare const AIAutocomplete: react.ForwardRefExoticComponent<AIAutocompleteProps & react.RefAttributes<AIAutocompleteHandle>>;
 
-declare function AIAutocompleteDropdown({ suggestions, activeIndex, onSelect, onHighlight, isOpen, id, className, pills, onPillClick, showPills, onSkip, showSkipButton, showOptionIcons, skipDisabled, activeSelected, isLoading, isInputEmpty, products, onProductSelect, onProductFocusChange, productsLayout, formatType, dateView, selectedDateIso, selectedDateRange, dateRangeStart, onPreviousMonth, onNextMonth, optionsPosition, mode, }: AIAutocompleteDropdownProps): react_jsx_runtime.JSX.Element;
+declare function AIAutocompleteDropdown({ suggestions, activeIndex, onSelect, onHighlight, isOpen, id, className, pills, onPillClick, showPills, onSkip, showSkipButton, showOptionIcons, showOptionImages, showOptionCounts, skipDisabled, activeSelected, isLoading, isInputEmpty, products, onProductSelect, onProductFocusChange, productsLayout, formatType, dateView, selectedDateIso, selectedDateRange, dateRangeStart, onPreviousMonth, onNextMonth, optionsPosition, mode, }: AIAutocompleteDropdownProps): react_jsx_runtime.JSX.Element;
 
-declare function useAIAutocomplete({ onSubmit, onResult, onError, optionOverrides, maskCompletedText, apiConfig, additionalContext, columns, dropdownTrigger, optionsPosition, closeDropdownOnBlur, showNonTappableOptions, showOptionIcons, showSkipButton, showProducts, onFocus, onBlur, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, products, onProductSelect, source, setCursor, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
+declare function useAIAutocomplete({ onSubmit, onResult, onError, optionOverrides, maskCompletedText, apiConfig, additionalContext, columns, dropdownTrigger, optionsPosition, closeDropdownOnBlur, showNonTappableOptions, showOptionIcons, showOptionImages, showOptionCounts, showSkipButton, showProducts, onFocus, onBlur, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, products, onProductSelect, source, setCursor, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
 
 export { AIAutocomplete, AIAutocompleteDropdown, type AIAutocompleteDropdownProps, type AIAutocompleteHandle, type AIAutocompleteProps, type UseAIAutocompleteOptions, type UseAIAutocompleteReturn, useAIAutocomplete };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { AutocompleteResult, OptionOverrides, APIConfig, AppearanceMode, CompletedParamState, ProductsLayout, ProductsConfig, Product, Suggestion, SuggestionOption, FormatType, DateMonthView, DateRange, SkippedParamState, IdentifiedParamState, Segment, CustomFieldsReport } from '@magicx-eng/ai-autocomplete-vanilla';
-export { APIConfig, APIKeyConfig, AccessTokenConfig, AccessTokenResult, AppearanceMode, AutocompleteResult, CompletedParam, CompletedParamState, CustomFieldsReport, DATE_RANGE_META_END, DATE_RANGE_META_START, DateMonthView, DateRange, ExpressedFilter, FilterOp, FormatType, IdentifiedParam, IdentifiedParamState, MatchedItem, MatchedItems, OptionOverrides, PRODUCT_PATH_PREFIX, Product, ProductsConfig, ProductsLayout, Segment, SkippedParamState, SubmitResultExtras, Suggestion, SuggestionOption, TaskKind, WEEKDAY_LABELS, buildSubmitResult, cellDay, cellIso, dateCellMarks, formatDate, formatDateRange, isoDate, monthLabel, optionLabel, parseDate, parseLooseDate, parseLooseDateRange, productFromMatchedItem, productsFromCustomFields, sanitizeOptionIconSvg, selectedRangeFor, visibleDateRange, withSkippedParams } from '@magicx-eng/ai-autocomplete-vanilla';
+export { APIConfig, APIKeyConfig, AccessTokenConfig, AccessTokenResult, AppearanceMode, AutocompleteResult, CompletedParam, CompletedParamState, CustomFieldsReport, DATE_RANGE_META_END, DATE_RANGE_META_START, DEFAULT_OPTION_COUNT_UNIT, DateMonthView, DateRange, ExpressedFilter, FilterOp, FormatType, IdentifiedParam, IdentifiedParamState, MatchedItem, MatchedItems, OptionOverrides, PRODUCT_PATH_PREFIX, Product, ProductsConfig, ProductsLayout, Segment, SkippedParamState, SubmitResultExtras, Suggestion, SuggestionOption, TaskKind, WEEKDAY_LABELS, buildSubmitResult, cellDay, cellIso, dateCellMarks, formatDate, formatDateRange, formatOptionCount, isoDate, monthLabel, optionCountLabel, optionHasImage, optionImageSrc, optionLabel, parseDate, parseLooseDate, parseLooseDateRange, productFromMatchedItem, productsFromCustomFields, sanitizeOptionIconSvg, selectedRangeFor, visibleDateRange, withSkippedParams } from '@magicx-eng/ai-autocomplete-vanilla';
 import * as react from 'react';
 import { ReactNode, KeyboardEvent, ChangeEvent } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
@@ -64,6 +64,12 @@ interface AIAutocompleteProps {
     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), a completed chip in the input draws the picture (`image_url`) of the option that answered it, in place of its icon. Set to false to render chips without pictures. */
+    showChipImages?: boolean;
+    /** When true (default), an option that carries an `image_url` draws it as a square thumbnail before its text in the dropdown (in place of its `icon_svg`). Set to false to render option rows without pictures. */
+    showOptionImages?: boolean;
+    /** When true (default), an option that carries an `item_count` shows it as a muted label at the row's trailing edge ("12 items"). Set to false to hide the counts. */
+    showOptionCounts?: 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
@@ -182,6 +188,18 @@ interface UseAIAutocompleteOptions {
      * option's `icon_svg` before its text. Set to false for text-only rows.
      */
     showOptionIcons?: boolean;
+    /**
+     * When true (default), `dropdownProps` asks the dropdown to draw each
+     * option's `image_url` as a thumbnail before its text. Set to false for
+     * rows without pictures.
+     */
+    showOptionImages?: boolean;
+    /**
+     * When true (default), `dropdownProps` asks the dropdown to show each
+     * option's `item_count` at the row's trailing edge. Set to false to hide
+     * the counts.
+     */
+    showOptionCounts?: boolean;
     /**
      * When true (default), `dropdownProps` asks the dropdown to render its
      * trailing "skip" button (see `AIAutocompleteProps.showSkipButton`). Set to
@@ -397,6 +415,18 @@ interface AIAutocompleteDropdownProps {
      * (the hook's `dropdownProps` folds in the `showOptionIcons` option).
      */
     showOptionIcons?: boolean;
+    /**
+     * Whether option rows draw their `image_url` as a square thumbnail before
+     * the text, in place of the icon. Default: true (the hook's `dropdownProps`
+     * folds in the `showOptionImages` option).
+     */
+    showOptionImages?: boolean;
+    /**
+     * Whether option rows show their `item_count` at the trailing edge.
+     * Default: true (the hook's `dropdownProps` folds in the
+     * `showOptionCounts` option).
+     */
+    showOptionCounts?: boolean;
     /**
      * Extra disabled gate for the skip button beyond `isLoading`. Provided by
      * `dropdownProps` from the hook (wired to `inSelectionAnimation`): the
@@ -469,8 +499,8 @@ interface AIAutocompleteDropdownProps {
 
 declare const AIAutocomplete: react.ForwardRefExoticComponent<AIAutocompleteProps & react.RefAttributes<AIAutocompleteHandle>>;
 
-declare function AIAutocompleteDropdown({ suggestions, activeIndex, onSelect, onHighlight, isOpen, id, className, pills, onPillClick, showPills, onSkip, showSkipButton, showOptionIcons, skipDisabled, activeSelected, isLoading, isInputEmpty, products, onProductSelect, onProductFocusChange, productsLayout, formatType, dateView, selectedDateIso, selectedDateRange, dateRangeStart, onPreviousMonth, onNextMonth, optionsPosition, mode, }: AIAutocompleteDropdownProps): react_jsx_runtime.JSX.Element;
+declare function AIAutocompleteDropdown({ suggestions, activeIndex, onSelect, onHighlight, isOpen, id, className, pills, onPillClick, showPills, onSkip, showSkipButton, showOptionIcons, showOptionImages, showOptionCounts, skipDisabled, activeSelected, isLoading, isInputEmpty, products, onProductSelect, onProductFocusChange, productsLayout, formatType, dateView, selectedDateIso, selectedDateRange, dateRangeStart, onPreviousMonth, onNextMonth, optionsPosition, mode, }: AIAutocompleteDropdownProps): react_jsx_runtime.JSX.Element;
 
-declare function useAIAutocomplete({ onSubmit, onResult, onError, optionOverrides, maskCompletedText, apiConfig, additionalContext, columns, dropdownTrigger, optionsPosition, closeDropdownOnBlur, showNonTappableOptions, showOptionIcons, showSkipButton, showProducts, onFocus, onBlur, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, products, onProductSelect, source, setCursor, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
+declare function useAIAutocomplete({ onSubmit, onResult, onError, optionOverrides, maskCompletedText, apiConfig, additionalContext, columns, dropdownTrigger, optionsPosition, closeDropdownOnBlur, showNonTappableOptions, showOptionIcons, showOptionImages, showOptionCounts, showSkipButton, showProducts, onFocus, onBlur, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, products, onProductSelect, source, setCursor, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
 
 export { AIAutocomplete, AIAutocompleteDropdown, type AIAutocompleteDropdownProps, type AIAutocompleteHandle, type AIAutocompleteProps, type UseAIAutocompleteOptions, type UseAIAutocompleteReturn, useAIAutocomplete };