@magicx-eng/ai-autocomplete-react 0.12.1 → 0.13.0

package/README.md

@@ -16,6 +16,7 @@ A React/TypeScript SDK that provides a guided AI-powered autocomplete experience
 - **Keyboard navigation** — arrow keys, enter to submit, tab to autocomplete, backspace to un-bold the last completed param
 - **IME-safe** — composition events are buffered so input text is committed once, after composition ends
 - **Client-side filtering** — instant substring filtering on every keystroke
+- **Datepicker** — date parameters are answered with a calendar instead of an option list. Click a day or navigate with the arrow keys; the date is committed as `MONTH DAY YEAR` (e.g. `March 23 2026`). Tapping a committed date re-opens the calendar on the month it holds.
 - **Option overrides** — inject or dynamically generate client-side options per suggestion type
 - **Product strip (opt-in)** — plug in any platform's product search and the dropdown renders a horizontal row of product cards below the options; the SDK owns the UI, your integration owns only `fetch` and `transform`
 - **Controlled & uncontrolled** — works out of the box or integrates with external state
@@ -131,6 +132,74 @@ After a completed param is added (by any means — option click, exact-match typ
 
 ---
 
+### Datepicker
+
+When the next parameter is a date, the dropdown shows a calendar instead of a
+list of options. A parameter counts as a date when its name says so, or when at
+least three of the options it offers are themselves written as dates — so a
+parameter called `when` or `arrival` still gets a calendar. Options written as
+relative phrases (`today`, `next week`) are not read as dates; a parameter
+offering those needs a name that says date.
+
+Nothing is required to switch it on — a date parameter renders this way
+automatically, and every other parameter is unaffected. Tier 1 and Tier 2
+render the calendar for you; in Tier 3 the same data reaches `dropdownProps` so
+you can render your own (see [Tier 3](#tier-3-headless)).
+
+**What the user can do**
+
+| Input | Result |
+|---|---|
+| Click a day | Commits that date |
+| <kbd>↓</kbd> | Moves into the calendar, starting on today |
+| <kbd>←</kbd> / <kbd>→</kbd> | Previous / next day, crossing week boundaries |
+| <kbd>↑</kbd> / <kbd>↓</kbd> | Previous / next week. Past either end of the month, focus returns to the input |
+| <kbd>Enter</kbd> | Commits the highlighted day |
+| Month arrows | Page the calendar. Paging never commits anything |
+| <kbd>→</kbd> at the end of the input | Skips the parameter, same as any other pill |
+
+**The committed value** is always `MONTH DAY YEAR` in English — `March 23 2026`
+— regardless of the visitor's locale, so the value you receive has one shape
+everywhere. It arrives as an ordinary completed parameter: bold in the input,
+and present in `completed_params` on submit like any other answer.
+
+**Re-editing** a committed date re-opens the calendar on that date's month with
+the day marked, so changing an answer takes one click.
+
+**Reading the value back.** The date arrives as text, so if you need a `Date`
+object, `parseDate` is exported for it:
+
+```ts
+import { parseDate } from "@magicx-eng/ai-autocomplete-react";
+
+const due = parseDate("March 23 2026"); // Date, or null if the text isn't one of ours
+```
+
+`parseLooseDate` is exported too, for the looser shapes a person types into a
+query — it reads `september 5th`, `5th September`, `Sept 5` and `2026-09-05`,
+and answers `null` for anything ambiguous rather than guessing.
+
+**Dates the user writes themselves.** When someone types a date into their query
+— "fly to vegas on september 5th" — the parameter it answers is recognised in
+place and the date becomes tappable. Tapping it opens the calendar on that
+month with the day already marked, so confirming or changing it takes one tap,
+and the picked date replaces their words with the canonical form.
+
+The written date is read where it can be: `september 5th`, `5th September`,
+`Sept 5`, `September 5, 2026` and `2026-09-05` all resolve, in any of those
+orders and with or without the year (a date with no year means its next
+occurrence). Two cases deliberately don't pre-select — a numeric date like
+`09/05`, which is September 5th in the US and May 9th elsewhere with nothing to
+say which, and phrases like `next friday`. Those still open the calendar, just
+on the current month with nothing marked, so the user picks rather than being
+shown a guess that might be wrong.
+
+**Typing** while the calendar is open does not filter it. The text is treated as
+a new query, so suggestions refresh as the user types — useful when someone
+would rather describe what they want than pick a day.
+
+---
+
 ## Tier 2: Hook + Dropdown
 
 Use the hook to drive state and render our dropdown; you own the input element and layout:
@@ -182,6 +251,8 @@ function App() {
 
 Skip `<AIAutocompleteDropdown />` and render the suggestions UI yourself. `dropdownProps` carries the data + actions — the active suggestion's options, the highlighted index, `isOpen`, and `onSelect` / `onHighlight`:
 
+> **Datepicker in a custom UI.** For a date parameter, `dropdownProps.formatType` is `"date"` and `suggestions[0].options` holds that month's day cells. Each cell's `text` is the date it commits (`"March 23 2026"`), so rendering them as a plain list already works — `onSelect` behaves exactly as it does for an option. To draw an actual calendar, read `dateView` for the month on show, `cellDay(option)` for the number to paint, and call `onPreviousMonth` / `onNextMonth` to page. Cells that pad the start and end of the month have `is_tappable: false`.
+
 ```tsx
 import { useAIAutocomplete } from "@magicx-eng/ai-autocomplete-react";
 
@@ -556,6 +627,13 @@ Override on the container (via `className`). All defaults use `:where()` (zero s
 | `--aia-product-price-font-size` | `11px` | `11px` | Product price font size. |
 | `--aia-product-vendor-font-size` | `10px` | `10px` | Product vendor font size. |
 | `--aia-products-label-font-size` | `11px` | `11px` | Section label font size. |
+| `--aia-date-cell-size` | `36px` | `36px` | Size of a day's square — the box that carries the highlight, the today ring and the selected fill. |
+| `--aia-date-row-height` | `40px` | `40px` | Height of one week row. Lower it to fit a 6-week month in a shorter dropdown. |
+| `--aia-date-cell-font-size` | `14px` | `14px` | Day-number font size. |
+| `--aia-date-month-font-size` | `14px` | `14px` | Font size of the "March 2026" header. |
+| `--aia-date-weekday-font-size` | `11px` | `11px` | Font size of the S/M/T/W/T/F/S column letters. |
+| `--aia-date-today-ring` | `--aia-option-color` | `--aia-option-color` | Outline drawn around today's date. |
+| `--aia-date-selected-bg` | white at 12% | white at 12% | Fill behind the date a re-edited parameter already holds. |
 | `--aia-skeleton-bg` | `rgba(189, 189, 189, 0.25)` | `#1a1b1d` | Fill color for the loading skeleton bars and the masked text in cached pills/options. |
 
 Legacy `--aia-color-*` variables are still supported as fallbacks.
@@ -587,6 +665,11 @@ For styling beyond the CSS variables, target these stable `data-aia-*` attribute
 | `[data-aia-skip]` | The pill bar's trailing "skip" button. Tune via `--aia-skip-font-size` / `--aia-skip-color` / `--aia-skip-color-hover` / `--aia-skip-hover-bg` |
 | `[data-aia-option]` | Each suggestion option |
 | `[data-aia-dropdown]` | The dropdown root (listbox). Carries `data-aia-has-products` while the product strip has cards. |
+| `[data-aia-datepicker]` | The calendar, rendered in place of the option list for a date parameter |
+| `[data-aia-date-month]` | The "March 2026" header label |
+| `[data-aia-date-prev]` / `[data-aia-date-next]` | The month arrows |
+| `[data-aia-date-grid]` | The 7-column grid of day cells |
+| `[data-aia-date-cell]` | Each day cell. Also carries `[data-aia-option]`, so option-level styling applies to both bodies |
 | `[data-aia-products]` | Product strip section (label + row) |
 | `[data-aia-products-row]` | The horizontally scrolling row of cards |
 | `[data-aia-product]` | Each product card |
@@ -611,11 +694,24 @@ Every `/api/suggest` request carries a `meta.session_id` UUID. A session runs fr
 
 The contract is simple: **after the user submits the query, call `reset()`**. That clears the input and rotates `session_id` so the next session begins clean.
 
-> **Why it matters:** the server uses `session_id` to track each session's history — what the user has been typing sequentially, which options they've selected, and how the query evolved. That context lets the model produce better, more relevant suggestions on subsequent requests within the same session. Calling `reset()` at the right moment (when the user actually submits) keeps that history accurate, so your users get higher-quality results.
+> **Why it matters:** suggestions get sharper as a query develops. Each one
+> takes account of what the user has already answered, so the parameters offered
+> late in a query are shaped by the choices made early in it — that is what makes
+> the experience feel guided rather than like a static list. `session_id` is what
+> ties those requests together into one query.
+>
+> So `reset()` is not bookkeeping: it is how you say "that query is finished".
+> Skip it and the next query is treated as a continuation of the last one, and
+> its suggestions keep being shaped by answers the user has already moved on
+> from — the failure is quiet, and shows up as steadily less relevant options
+> rather than as an error.
 
 - **Tier 1 `<AIAutocomplete />`** does this automatically — it calls `reset()` for you after `onSubmit` returns, for both Enter-key and built-in-button submits.
 - **Tier 2 & 3 `useAIAutocomplete()`** — you own the submit flow, so call `reset()` from your `onSubmit` handler (see the example above) or from your custom button after firing `onSubmit`.
 
+The id is a plain UUID. Log it next to your own request logs if you want to
+correlate a user's report with the query that produced it.
+
 ## Option Overrides
 
 ```tsx

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { AutocompleteResult, OptionOverrides, APIConfig, AppearanceMode, CompletedParamState, ProductsConfig, Product, Suggestion, SuggestionOption, SkippedParamState, Segment } from '@magicx-eng/ai-autocomplete-vanilla';
-export { APIConfig, APIKeyConfig, AccessTokenConfig, AccessTokenResult, AppearanceMode, AutocompleteResult, CompletedParam, CompletedParamState, OptionOverrides, Product, ProductsConfig, Segment, SkippedParamState, Suggestion, SuggestionOption, TaskKind, buildSubmitResult, withSkippedParams } from '@magicx-eng/ai-autocomplete-vanilla';
+import { AutocompleteResult, OptionOverrides, APIConfig, AppearanceMode, CompletedParamState, ProductsConfig, Product, Suggestion, SuggestionOption, FormatType, DateMonthView, SkippedParamState, Segment } from '@magicx-eng/ai-autocomplete-vanilla';
+export { APIConfig, APIKeyConfig, AccessTokenConfig, AccessTokenResult, AppearanceMode, AutocompleteResult, CompletedParam, CompletedParamState, DateMonthView, FormatType, OptionOverrides, Product, ProductsConfig, Segment, SkippedParamState, Suggestion, SuggestionOption, TaskKind, WEEKDAY_LABELS, buildSubmitResult, cellDay, cellIso, formatDate, isoDate, monthLabel, parseDate, parseLooseDate, 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';
@@ -239,6 +239,17 @@ interface UseAIAutocompleteReturn {
     setFocused: (focused: boolean) => void;
     /** Tier 1 re-edit: snapshot of the bold param currently being re-edited (null when not editing). */
     editingParam: CompletedParamState | 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". Null otherwise.
+     */
+    editingIdentified: {
+        id: string;
+        type: string;
+        anchor: number;
+        tail: number;
+        iso: string | null;
+    } | null;
     /** Tier 1 re-edit: plain-text offset where the editing region starts (null when not editing). */
     editingAnchor: number | null;
     /** Tier 1 helper: latest known caret offset within the editor. Promote paths stamp this with the position the caret should land after a completion. */
@@ -329,6 +340,22 @@ interface AIAutocompleteDropdownProps {
      * Default: `"below"`.
      */
     optionsPosition?: "above" | "below";
+    /**
+     * How the active pill is answered. `"date"` renders a calendar in place of
+     * the options grid, and `suggestions[0].options` then carries that month's
+     * cells rather than the parameter's own options — the core swaps them before
+     * they reach here. Provided by `dropdownProps` from the hook.
+     * Default: `"options"`.
+     */
+    formatType?: FormatType;
+    /** The month the calendar shows. Null unless `formatType` is `"date"`. Provided by `dropdownProps` from the hook. */
+    dateView?: DateMonthView | null;
+    /** `YYYY-MM-DD` already held by the param being re-edited, so its cell reads as the current answer. Provided by `dropdownProps` from the hook. */
+    selectedDateIso?: string | null;
+    /** Page the calendar back a month. Provided by `dropdownProps` from the hook. */
+    onPreviousMonth?: () => void;
+    /** Page the calendar forward a month. Provided by `dropdownProps` from the hook. */
+    onNextMonth?: () => void;
     /**
      * Color mode for a **standalone** dropdown. When set, the dropdown scopes the
      * SDK's design tokens to its own root (adds the `magicx-aia` class +
@@ -344,7 +371,7 @@ 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, skipDisabled, activeSelected, isLoading, isInputEmpty, products, onProductSelect, onProductFocusChange, optionsPosition, mode, }: AIAutocompleteDropdownProps): react_jsx_runtime.JSX.Element;
+declare function AIAutocompleteDropdown({ suggestions, activeIndex, onSelect, onHighlight, isOpen, id, className, pills, onPillClick, showPills, onSkip, showSkipButton, skipDisabled, activeSelected, isLoading, isInputEmpty, products, onProductSelect, onProductFocusChange, formatType, dateView, selectedDateIso, onPreviousMonth, onNextMonth, optionsPosition, mode, }: AIAutocompleteDropdownProps): react_jsx_runtime.JSX.Element;
 
 declare function useAIAutocomplete({ onSubmit, onError, optionOverrides, maskCompletedText, apiConfig, additionalContext, columns, dropdownTrigger, optionsPosition, closeDropdownOnBlur, showNonTappableOptions, showSkipButton, onFocus, onBlur, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, products, onProductSelect, source, setCursor, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { AutocompleteResult, OptionOverrides, APIConfig, AppearanceMode, CompletedParamState, ProductsConfig, Product, Suggestion, SuggestionOption, SkippedParamState, Segment } from '@magicx-eng/ai-autocomplete-vanilla';
-export { APIConfig, APIKeyConfig, AccessTokenConfig, AccessTokenResult, AppearanceMode, AutocompleteResult, CompletedParam, CompletedParamState, OptionOverrides, Product, ProductsConfig, Segment, SkippedParamState, Suggestion, SuggestionOption, TaskKind, buildSubmitResult, withSkippedParams } from '@magicx-eng/ai-autocomplete-vanilla';
+import { AutocompleteResult, OptionOverrides, APIConfig, AppearanceMode, CompletedParamState, ProductsConfig, Product, Suggestion, SuggestionOption, FormatType, DateMonthView, SkippedParamState, Segment } from '@magicx-eng/ai-autocomplete-vanilla';
+export { APIConfig, APIKeyConfig, AccessTokenConfig, AccessTokenResult, AppearanceMode, AutocompleteResult, CompletedParam, CompletedParamState, DateMonthView, FormatType, OptionOverrides, Product, ProductsConfig, Segment, SkippedParamState, Suggestion, SuggestionOption, TaskKind, WEEKDAY_LABELS, buildSubmitResult, cellDay, cellIso, formatDate, isoDate, monthLabel, parseDate, parseLooseDate, 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';
@@ -239,6 +239,17 @@ interface UseAIAutocompleteReturn {
     setFocused: (focused: boolean) => void;
     /** Tier 1 re-edit: snapshot of the bold param currently being re-edited (null when not editing). */
     editingParam: CompletedParamState | 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". Null otherwise.
+     */
+    editingIdentified: {
+        id: string;
+        type: string;
+        anchor: number;
+        tail: number;
+        iso: string | null;
+    } | null;
     /** Tier 1 re-edit: plain-text offset where the editing region starts (null when not editing). */
     editingAnchor: number | null;
     /** Tier 1 helper: latest known caret offset within the editor. Promote paths stamp this with the position the caret should land after a completion. */
@@ -329,6 +340,22 @@ interface AIAutocompleteDropdownProps {
      * Default: `"below"`.
      */
     optionsPosition?: "above" | "below";
+    /**
+     * How the active pill is answered. `"date"` renders a calendar in place of
+     * the options grid, and `suggestions[0].options` then carries that month's
+     * cells rather than the parameter's own options — the core swaps them before
+     * they reach here. Provided by `dropdownProps` from the hook.
+     * Default: `"options"`.
+     */
+    formatType?: FormatType;
+    /** The month the calendar shows. Null unless `formatType` is `"date"`. Provided by `dropdownProps` from the hook. */
+    dateView?: DateMonthView | null;
+    /** `YYYY-MM-DD` already held by the param being re-edited, so its cell reads as the current answer. Provided by `dropdownProps` from the hook. */
+    selectedDateIso?: string | null;
+    /** Page the calendar back a month. Provided by `dropdownProps` from the hook. */
+    onPreviousMonth?: () => void;
+    /** Page the calendar forward a month. Provided by `dropdownProps` from the hook. */
+    onNextMonth?: () => void;
     /**
      * Color mode for a **standalone** dropdown. When set, the dropdown scopes the
      * SDK's design tokens to its own root (adds the `magicx-aia` class +
@@ -344,7 +371,7 @@ 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, skipDisabled, activeSelected, isLoading, isInputEmpty, products, onProductSelect, onProductFocusChange, optionsPosition, mode, }: AIAutocompleteDropdownProps): react_jsx_runtime.JSX.Element;
+declare function AIAutocompleteDropdown({ suggestions, activeIndex, onSelect, onHighlight, isOpen, id, className, pills, onPillClick, showPills, onSkip, showSkipButton, skipDisabled, activeSelected, isLoading, isInputEmpty, products, onProductSelect, onProductFocusChange, formatType, dateView, selectedDateIso, onPreviousMonth, onNextMonth, optionsPosition, mode, }: AIAutocompleteDropdownProps): react_jsx_runtime.JSX.Element;
 
 declare function useAIAutocomplete({ onSubmit, onError, optionOverrides, maskCompletedText, apiConfig, additionalContext, columns, dropdownTrigger, optionsPosition, closeDropdownOnBlur, showNonTappableOptions, showSkipButton, onFocus, onBlur, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, products, onProductSelect, source, setCursor, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;