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

package/README.md

@@ -16,14 +16,14 @@ 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.
+- **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 the way it would be written — `Tuesday` for a date inside the next week, `March 23` for one later this year, `March 23 2027` for another year. Tapping a committed date re-opens the calendar on the month that text names now — for a weekday name, that is the next such day, not the one originally picked.
 - **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
 - **Ref forwarding** — imperative `focus()`, `blur()`, `reset()`, and `setMode()` via ref
 - **Accessible** — ARIA combobox 1.2 pattern with `role="listbox"`, `aria-activedescendant`
-- **Animations** — option selection streak animation, text shimmer on newly added params
-- **Loading skeleton** — while a fetch is in flight, the dropdown and inline pills keep the previous layout (same count and widths) with their text masked and a shimmer pulse. The skeleton is held back until the selection streak animation finishes, so taps don't visually "stutter" into loading.
+- **Animations** — option press (the picked option compresses while the rest step back), text shimmer on newly added params
+- **Loading skeleton** — while a fetch is in flight, the dropdown and inline pills keep the previous layout (same count and widths) with their text masked and a shimmer pulse. The skeleton is held back until the option-press animation finishes, so taps don't visually "stutter" into loading.
 - **Lightweight** — styles auto-injected at runtime
 - **TypeScript first** — full type definitions shipped with the package
 
@@ -158,13 +158,24 @@ you can render your own (see [Tier 3](#tier-3-headless)).
 | 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,
+**The committed value** is written the way a person would write it, always in
+English regardless of the visitor's locale, so the value you receive has one
+vocabulary everywhere:
+
+- a date inside the next week (today included) commits as its weekday name —
+  `Tuesday`. Like the sentence it sits in, that name is relative: read later,
+  it means the next such day;
+- one further out in the current year as `MONTH DAY` — `March 23`;
+- one in another year as `MONTH DAY YEAR` — `March 23 2027`.
+
+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.
+**Re-editing** a committed date re-opens the calendar on the month the committed
+text names, with that day marked, so changing an answer takes one click. For a
+weekday name that reading is relative, so once the day it named has gone by,
+re-editing marks the next such day rather than the one originally picked — the
+calendar shows what the sentence says today, which is also what gets submitted.
 
 **Reading the value back.** The date arrives as text, so if you need a `Date`
 object, `parseDate` is exported for it:
@@ -172,7 +183,9 @@ 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
+// Reads all three committed shapes: a weekday name is the one date it can
+// mean in the next seven days, and a yearless month-day is the current year.
+const due = parseDate("March 23"); // Date, or null if the text isn't one of ours
 ```
 
 `parseLooseDate` is exported too, for the looser shapes a person types into a
@@ -251,7 +264,7 @@ 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`.
+> **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"`, or `"Tuesday"` inside the next week), 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";
@@ -308,7 +321,7 @@ function App() {
 | `pillPlacement?` | `"inline" \| "dropdown" \| "hidden"` | `"dropdown"` | Where to render unfilled pills. `"hidden"` hides pills entirely. |
 | `mode?` | `"light" \| "dark" \| "auto"` | `"auto"` | Color mode. `"auto"` follows `prefers-color-scheme`. |
 | `optionsPosition?` | `"above" \| "below"` | `"below"` | Where the dropdown opens relative to the input. |
-| `animations?` | `boolean` | `true` | Enable/disable all SDK animations (streak + shimmer). |
+| `animations?` | `boolean` | `true` | Enable/disable all SDK animations (press + shimmer, the typed-in starting-state placeholder, the option rows' staggered entrance, and the "more below" arrow's slide). `prefers-reduced-motion` also switches the last three off. |
 | `dropdownTrigger?` | `"auto" \| "manual" \| "hidden"` | `"auto"` | When the dropdown appears. `"auto"` = when options available. `"manual"` = only on pill tap, closes after selection. `"hidden"` = never shows. |
 | `closeDropdownOnBlur?` | `boolean` | `true` | When `true`, the dropdown closes if the input loses focus. Set to `false` to keep it open whenever options are available, regardless of focus. |
 | `showNonTappableOptions?` | `boolean` | `true` | When `true`, non-tappable options are rendered alongside tappable ones in the dropdown. Set to `false` to hide non-tappable options entirely. |
@@ -610,13 +623,17 @@ Override on the container (via `className`). All defaults use `:where()` (zero s
 | `--aia-footer-chip-bg` | `--aia-surface` at 65% | `--aia-surface` at 65% | Fill behind the footer's keyboard hint and AI-Autocomplete badge. The option list scrolls under the footer, so this keeps both legible over the row passing behind them. `transparent` on the glass surface. |
 | `--aia-dropdown-bg` | — | — | Optional bg color the dropdown's "glass" rim shadow tints toward. Set this to the page background behind the dropdown so the bottom-corner glow blends seamlessly. |
 | `--aia-scrollbar-thumb` | `rgba(0, 0, 0, 0.3)` | `rgba(0, 0, 0, 0.3)` | Color of the option list's scrollbar thumb (Firefox + WebKit). |
-| `--aia-streak-rgb` | `99, 102, 241` | `255, 255, 255` | Comma-separated RGB triplet used to tint the option-selection streak animation (consumed via `rgba(var(--aia-streak-rgb), …)`). |
-| `--aia-streak-glass-bg` | `rgba(99, 102, 241, 0.1)` | `rgba(255, 255, 255, 0.1)` | Background fill for the streak's glass-pill effect. |
+| `--aia-streak-rgb` | `99, 102, 241` | `255, 255, 255` | Comma-separated RGB triplet tinting the datepicker's pressed cell, and its selected cell when `--aia-date-selected-bg` is unset. The today ring uses `--aia-date-today-ring`, not this. |
 | `--aia-product-card-width` | `116px` | `116px` | Width of a product card in the strip. The media tile is square, so this also sets its height. |
 | `--aia-product-gap` | `8px` | `8px` | Gap between product cards. |
 | `--aia-product-bg` | `transparent` | `transparent` | Product card background. |
 | `--aia-product-bg-active` | `--aia-option-bg` | `--aia-option-bg` | Product card background on hover. |
 | `--aia-product-media-bg` | `--aia-skeleton-bg` | `--aia-skeleton-bg` | Fill behind the product image, and of the placeholder tile when a product has no image. |
+| `--aia-scroll-arrow-bg` | `--aia-surface` | `--aia-surface` | Fill of the "more below" arrow — the round button that rises at the bottom of the option list while there is more to scroll to. |
+| `--aia-scroll-arrow-color` | `--aia-option-color` | `--aia-option-color` | Chevron color of the arrow (`--aia-scroll-arrow-color-hover` on hover). |
+| `--aia-scroll-arrow-border` | `--aia-dropdown-border` | `--aia-dropdown-border` | Hairline around the arrow. |
+| `--aia-scroll-arrow-shadow` | `0 2px 8px rgba(0,0,0,0.12)` | `0 2px 8px rgba(0,0,0,0.12)` | Elevation of the arrow. |
+| `--aia-placeholder-fade` | `120ms` | `120ms` | Fade-out of the outgoing placeholder phrase when the starting-state placeholder changes (the incoming one types itself in). |
 | `--aia-product-placeholder-color` | `--aia-option-color` | `--aia-option-color` | Glyph color of the no-image placeholder tile. |
 | `--aia-product-title-color` | `--aia-option-color-selected` | `--aia-option-color-selected` | Product title text. Follows the option colors by default, so theming the panel moves suggestions and products together. |
 | `--aia-product-price-color` | `--aia-option-color-selected` | `--aia-option-color-selected` | Product price text. |
@@ -627,9 +644,10 @@ 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-panel-width` | `312px` | `312px` | Max width of the whole dropdown panel while the calendar is up — the panel narrows to calendar size. |
+| `--aia-date-cell-size` | `26px` | `26px` | Size of a day's square — the box that carries the highlight, the today ring and the selected fill. |
+| `--aia-date-row-height` | `28px` | `28px` | Height of one week row. Lower it to fit a 6-week month in a shorter dropdown. |
+| `--aia-date-cell-font-size` | `13px` | `13px` | 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. |
@@ -664,6 +682,7 @@ For styling beyond the CSS variables, target these stable `data-aia-*` attribute
 | `[data-aia-pill-scroll]` | Scrollable pill region inside the bar — carries the horizontal scroll and right-edge fade mask |
 | `[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-scroll-arrow]` | The "more below" arrow on the dropdown — carries `data-aia-visible` while shown |
 | `[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 |

package/dist/index.d.mts

@@ -38,7 +38,7 @@ interface AIAutocompleteProps {
     mode?: AppearanceMode;
     /** Where the dropdown opens relative to the input. Default: "below" */
     optionsPosition?: "above" | "below";
-    /** Enable all SDK animations (streak + shimmer). Default: true */
+    /** Enable all SDK animations (press + shimmer). Default: true */
     animations?: boolean;
     /** When the dropdown appears. "auto" (default) = shows when options available. "manual" = only on pill tap, closes after selection. "hidden" = never shows. */
     dropdownTrigger?: "auto" | "manual" | "hidden";

package/dist/index.d.ts

@@ -38,7 +38,7 @@ interface AIAutocompleteProps {
     mode?: AppearanceMode;
     /** Where the dropdown opens relative to the input. Default: "below" */
     optionsPosition?: "above" | "below";
-    /** Enable all SDK animations (streak + shimmer). Default: true */
+    /** Enable all SDK animations (press + shimmer). Default: true */
     animations?: boolean;
     /** When the dropdown appears. "auto" (default) = shows when options available. "manual" = only on pill tap, closes after selection. "hidden" = never shows. */
     dropdownTrigger?: "auto" | "manual" | "hidden";