@magicx-eng/ai-autocomplete-react 0.1.38 → 0.1.40

package/README.md

@@ -5,17 +5,23 @@ A React/TypeScript SDK that provides a guided AI-powered autocomplete experience
 ## Features
 
 - **Two tiers of integration** — use the full `<AIAutocomplete />` component or go headless with `useAIAutocomplete()` + `<AIAutocompleteDropdown />`
-- **Pill-based input** — inline pills for unfilled parameters, bold text for completed ones
+- **Rich inline input (Tier 1)** — a single `contentEditable` surface: typed text, bold completed params, and inline pills share one editing context
+- **Pill-based input** — non-editable inline pills for unfilled parameters, bold inline text for completed ones
+- **Instant exact-match bolding** — typing the full text of an option immediately promotes it to a completed param (no debounced fetch wait). Works in the normal typing flow *and* while re-editing an existing completed param.
+- **Re-edit completed params** — tap a bold completed param to replace it; the dropdown re-opens with the cached options the server originally returned for that param
 - **Pill placement** — render pills inline in the input or inside the dropdown
 - **Light/dark mode** — built-in themes with `prefers-color-scheme` support, fully overridable via CSS variables
+- **Inherits your font** — defaults to the host page's font, with `--aia-font-family` to pin a specific font on the library
 - **Access token auth** — short-lived tokens with automatic refresh, single-flight deduplication, and 401 retry
-- **Keyboard navigation** — arrow keys, enter to submit, tab to autocomplete
+- **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
 - **Option overrides** — inject or dynamically generate client-side options per suggestion type
 - **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 pattern with `role="listbox"`, `aria-activedescendant`
+- **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.
 - **Lightweight** — styles auto-injected at runtime
 - **TypeScript first** — full type definitions shipped with the package
 
@@ -96,7 +102,7 @@ const ref = useRef<AIAutocompleteHandle>(null);
 
 ### Focus Control
 
-The component auto-focuses the input on mount. To opt out, pass `autoFocus={false}`. Listen to focus changes with `onFocus` / `onBlur`:
+The component auto-focuses the contentEditable editor on mount. To opt out, pass `autoFocus={false}`. Listen to focus changes with `onFocus` / `onBlur`:
 
 ```tsx
 <AIAutocomplete
@@ -107,6 +113,20 @@ The component auto-focuses the input on mount. To opt out, pass `autoFocus={fals
 />
 ```
 
+### Backspace into a completed param
+
+Pressing Backspace while the caret is inside or immediately after a bold completed param drops the param's "completed" status and removes one grapheme before the caret. The remaining text stays in the editor as plain (un-bold) text so the user can keep editing instead of losing the whole phrase.
+
+### Re-edit a completed param
+
+Tapping a bold completed param enters *re-edit mode* — the dropdown re-opens with the cached options the server originally returned for that param. From there:
+
+- **Typing** atomically replaces the bold with what you type. If what you type exactly matches one of the cached options, it's re-promoted to a bold completed param immediately.
+- **Clicking an option** replaces the bold with the new selection.
+- **Arrow keys, Escape, or clicking outside the param** exit re-edit mode without changing anything.
+
+After a completed param is added (by any means — option click, exact-match typing, or re-edit), the caret always lands right after the trailing space following the bold so typing can continue immediately. A space is inserted if one wasn't already there.
+
 ---
 
 ## Tier 2: Headless
@@ -246,11 +266,11 @@ The headless hook for Tier 2. Accepts the same props as `<AIAutocomplete />` exc
 |---|---|---|
 | `completedParams` | `CompletedParamState[]` | Filled parameters. |
 | `suggestionPills` | `Suggestion[]` | Unfilled suggestions (pills). First item is the active pill. |
-| `segments` | `Segment[]` | Input text split into text vs completed segments for overlay rendering. |
+| `segments` | `Segment[]` | Input text split into typed text vs completed params — completed segments render as bold `<strong>` runs inside the editor. |
 | `newParamId` | `string \| null` | ID of the most recently added param (for shimmer animation). |
 | `suggestions` | `Suggestion[]` | All suggestions from server (including placeholder type). |
 | `activeIndex` | `number` | Highlighted option index. `-1` = none. |
-| `isLoading` | `boolean` | Fetch in progress. |
+| `isLoading` | `boolean` | True when the dropdown should render its loading skeleton — a fetch is in flight, no option-selection animation is playing, and the user is not in re-edit mode (where cached options stay visible). |
 | `isReady` | `boolean` | Server indicates query is complete. |
 | `error` | `Error \| null` | Last fetch error. |
 
@@ -259,7 +279,7 @@ The headless hook for Tier 2. Accepts the same props as `<AIAutocomplete />` exc
 | Field | Type | Description |
 |---|---|---|
 | `setActivePill` | `(index: number) => void` | Move pill at `index` to front (active). |
-| `removeLastParam` | `() => void` | Remove last completed param, restore as pill. |
+| `removeLastParam` | `() => void` | Remove the last completed param from state. The text stays in the input as plain text. |
 | `clearNewParamId` | `() => void` | Clear shimmer animation state. |
 | `reset` | `() => void` | Clear all state, re-fetch, and start a new session (rotates `session_id`). Call this after handling submit. |
 
@@ -286,6 +306,7 @@ The dropdown component for Tier 2. Spread `dropdownProps` from the hook.
 | `pills?` | `Suggestion[]` | Pills to render inside the dropdown. |
 | `onPillClick?` | `(index: number) => void` | Called when a pill is clicked. |
 | `showPills?` | `boolean` | Whether to render pills. Default: `true`. |
+| `isLoading?` | `boolean` | When `true`, the dropdown renders its pills + options as a skeleton: text masked, layout (count and widths) preserved, shimmer pulse animating. Falls back to a generic 3-bar placeholder when no pills/options are cached. |
 
 ### `AutocompleteResult`
 
@@ -307,6 +328,7 @@ Override on the container (via `className`). All defaults use `:where()` (zero s
 
 | Variable | Light | Dark | Description |
 |---|---|---|---|
+| `--aia-font-family` | `inherit` | `inherit` | Font used by the library. Defaults to `inherit` so the library picks up your page's font automatically. Set this to pin a specific font on the library without changing the surrounding page. |
 | `--aia-pill-bg` | `#bdbdbd` | `#bdbdbd` | Pill background |
 | `--aia-pill-color` | `#000000` | `#ffffff` | Pill text |
 | `--aia-pill-font-size` | `19px` | `19px` | Pill font size |
@@ -316,13 +338,14 @@ Override on the container (via `className`). All defaults use `:where()` (zero s
 | `--aia-option-font-size` | `19px` | `19px` | Option font size |
 | `--aia-written-text-color` | `#000000` | `#ffffff` | Input text |
 | `--aia-written-text-font-size` | `19px` | `19px` | Input text font size |
-| `--aia-caret-color` | `--aia-written-text-color` | `--aia-written-text-color` | Textarea caret color. Override independently of input text color. |
+| `--aia-caret-color` | `--aia-written-text-color` | `--aia-written-text-color` | Editor caret color. Override independently of input text color. |
 | `--aia-submit-bg` | `#000000` | `#ffffff` | Submit button background |
 | `--aia-submit-color` | `#ffffff` | `#000000` | Submit button icon color |
 | `--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-skeleton-bg` | `rgba(189, 189, 189, 0.51)` | `#333539` | Fill color for the loading skeleton bars and the masked text in cached pills/options. |
 
 Legacy `--aia-color-*` variables are still supported as fallbacks.
 
@@ -343,14 +366,17 @@ For styling beyond the CSS variables, target these stable `data-aia-*` attribute
 
 | Attribute | Element |
 |---|---|
-| `[data-aia-editor]` | Editor area wrapping the textarea + overlay |
-| `[data-aia-textarea]` | The `<textarea>` |
+| `[data-aia-editor]` | Editor area wrapping the contentEditable + inline pill list |
+| `[data-aia-input]` | The Tier 1 contentEditable `<div>` that owns typed text and bold completed params. (Replaces the previous `[data-aia-textarea]` selector.) |
+| `[data-aia-pill-list-container]` | Inline sibling of the editor that holds unfilled-suggestion pills |
 | `[data-aia-submit]` | Submit button |
 | `[data-aia-pill]` | Each unfilled-suggestion pill |
 | `[data-aia-pillbar]` | Pill bar container inside the dropdown |
 | `[data-aia-option]` | Each suggestion option |
 | `[data-aia-dropdown]` | The dropdown root (listbox) |
 
+Completed params render as inline `<strong>` elements inside the editor. Override their weight with `[data-aia-input] strong { font-weight: 700; }` (the built-in style uses `:where()` so any consumer selector wins without `!important`).
+
 ```css
 /* Solid (non-glass) dropdown */
 .my-autocomplete [data-aia-dropdown] {

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ReactNode, ChangeEvent, KeyboardEvent } from 'react';
+import { ReactNode, KeyboardEvent, ChangeEvent } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 type TaskKind = "automation" | "email" | "insight";
@@ -26,8 +26,11 @@ interface Suggestion {
 interface CompletedParamState extends CompletedParam {
     id: string;
     text: string;
+    /** Source suggestion's `type` — used by re-edit mode to render the dropdown pill. */
     suggestionType: string;
+    /** Source suggestion's `text` — used by re-edit mode to render the dropdown pill. */
     suggestionPlaceholder: string;
+    /** Cached options from the suggestion that produced this param — re-edit shows these. */
     options: SuggestionOption[];
     metadata?: Record<string, unknown>;
 }
@@ -136,6 +139,14 @@ interface UseAIAutocompleteOptions {
     completedParams?: CompletedParamState[];
     onChange?: (value: string) => void;
     onParamsChange?: (params: CompletedParamState[]) => void;
+    /**
+     * Tier 1 helper. Invoked by the core when re-edit / Backspace flows need
+     * the editor caret parked at a specific plain-text offset. The Tier 1
+     * `<AIAutocomplete />` component supplies this from its inputRef; headless
+     * consumers can ignore it.
+     * @internal
+     */
+    setCursor?: (offset: number) => void;
 }
 interface UseAIAutocompleteReturn {
     completedParams: CompletedParamState[];
@@ -150,7 +161,33 @@ interface UseAIAutocompleteReturn {
     activeIndex: number;
     isReady: boolean;
     isLoading: boolean;
+    isFocused: boolean;
+    isDropdownOpen: boolean;
+    placeholderText: string;
+    listboxId: string;
     error: Error | null;
+    /** Tier 1 helper: forward plain-text input to the core (autocapitalize handled). */
+    handleTextChange: (value: string) => void;
+    /** Tier 1 helper: forward keyboard events to the core. */
+    handleKeyDown: (e: KeyboardEvent<HTMLElement> | globalThis.KeyboardEvent) => void;
+    /** Tier 1 helper: notify the core of focus state. */
+    setFocused: (focused: boolean) => void;
+    /** Tier 1 re-edit: snapshot of the bold param currently being re-edited (null when not editing). */
+    editingParam: CompletedParamState | 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. */
+    caretOffset: number | null;
+    /** Tier 1 re-edit: enter re-edit mode for the bold param with the given id. */
+    startEditingParam: (paramId: string) => void;
+    /** Tier 1 re-edit: exit re-edit mode. */
+    exitEditMode: () => void;
+    /** Tier 1 re-edit: update caret tracking after a text-input event (extends edit tail). */
+    handleCaretAfterInput: (offset: number | null) => void;
+    /** Tier 1 re-edit: update caret on a selection-only move (may exit edit mode). */
+    handleCaretMove: (offset: number | null) => void;
+    /** Tier 1 re-edit: replace the bold param being edited with the given text. Returns true when applied. */
+    replaceEditingRange: (replacement: string) => boolean;
     inputProps: {
         value: string;
         placeholder: string | undefined;
@@ -180,12 +217,14 @@ interface AIAutocompleteDropdownProps {
     onPillClick?: (index: number) => void;
     /** Whether to render pills inside the dropdown. Default: true. Tier 2 consumers who render their own pills should set this to false. */
     showPills?: boolean;
+    /** True while a fetch for the latest query is in flight. Replaces options/pills with a skeleton. */
+    isLoading?: boolean;
 }
 
 declare const AIAutocomplete: react.ForwardRefExoticComponent<AIAutocompleteProps & react.RefAttributes<AIAutocompleteHandle>>;
 
-declare function AIAutocompleteDropdown({ suggestions, activeIndex, onSelect, onHighlight, isOpen, id, className, pills, onPillClick, showPills, }: AIAutocompleteDropdownProps): react_jsx_runtime.JSX.Element;
+declare function AIAutocompleteDropdown({ suggestions, activeIndex, onSelect, onHighlight, isOpen, id, className, pills, onPillClick, showPills, isLoading, }: AIAutocompleteDropdownProps): react_jsx_runtime.JSX.Element;
 
-declare function useAIAutocomplete({ onSubmit, onError, optionOverrides, maskCompletedText, apiConfig, columns, dropdownTrigger, closeDropdownOnBlur, onFocus, onBlur, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, source, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
+declare function useAIAutocomplete({ onSubmit, onError, optionOverrides, maskCompletedText, apiConfig, columns, dropdownTrigger, closeDropdownOnBlur, onFocus, onBlur, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, source, setCursor, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
 
 export { AIAutocomplete, AIAutocompleteDropdown, type AIAutocompleteDropdownProps, type AIAutocompleteHandle, type AIAutocompleteProps, type APIConfig, type APIKeyConfig, type AccessTokenConfig, type AccessTokenResult, type AppearanceMode, type AutocompleteResult, type CompletedParam, type CompletedParamState, type OptionOverrides, type Segment, type Suggestion, type SuggestionOption, type TaskKind, type UseAIAutocompleteOptions, type UseAIAutocompleteReturn, useAIAutocomplete };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ReactNode, ChangeEvent, KeyboardEvent } from 'react';
+import { ReactNode, KeyboardEvent, ChangeEvent } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 type TaskKind = "automation" | "email" | "insight";
@@ -26,8 +26,11 @@ interface Suggestion {
 interface CompletedParamState extends CompletedParam {
     id: string;
     text: string;
+    /** Source suggestion's `type` — used by re-edit mode to render the dropdown pill. */
     suggestionType: string;
+    /** Source suggestion's `text` — used by re-edit mode to render the dropdown pill. */
     suggestionPlaceholder: string;
+    /** Cached options from the suggestion that produced this param — re-edit shows these. */
     options: SuggestionOption[];
     metadata?: Record<string, unknown>;
 }
@@ -136,6 +139,14 @@ interface UseAIAutocompleteOptions {
     completedParams?: CompletedParamState[];
     onChange?: (value: string) => void;
     onParamsChange?: (params: CompletedParamState[]) => void;
+    /**
+     * Tier 1 helper. Invoked by the core when re-edit / Backspace flows need
+     * the editor caret parked at a specific plain-text offset. The Tier 1
+     * `<AIAutocomplete />` component supplies this from its inputRef; headless
+     * consumers can ignore it.
+     * @internal
+     */
+    setCursor?: (offset: number) => void;
 }
 interface UseAIAutocompleteReturn {
     completedParams: CompletedParamState[];
@@ -150,7 +161,33 @@ interface UseAIAutocompleteReturn {
     activeIndex: number;
     isReady: boolean;
     isLoading: boolean;
+    isFocused: boolean;
+    isDropdownOpen: boolean;
+    placeholderText: string;
+    listboxId: string;
     error: Error | null;
+    /** Tier 1 helper: forward plain-text input to the core (autocapitalize handled). */
+    handleTextChange: (value: string) => void;
+    /** Tier 1 helper: forward keyboard events to the core. */
+    handleKeyDown: (e: KeyboardEvent<HTMLElement> | globalThis.KeyboardEvent) => void;
+    /** Tier 1 helper: notify the core of focus state. */
+    setFocused: (focused: boolean) => void;
+    /** Tier 1 re-edit: snapshot of the bold param currently being re-edited (null when not editing). */
+    editingParam: CompletedParamState | 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. */
+    caretOffset: number | null;
+    /** Tier 1 re-edit: enter re-edit mode for the bold param with the given id. */
+    startEditingParam: (paramId: string) => void;
+    /** Tier 1 re-edit: exit re-edit mode. */
+    exitEditMode: () => void;
+    /** Tier 1 re-edit: update caret tracking after a text-input event (extends edit tail). */
+    handleCaretAfterInput: (offset: number | null) => void;
+    /** Tier 1 re-edit: update caret on a selection-only move (may exit edit mode). */
+    handleCaretMove: (offset: number | null) => void;
+    /** Tier 1 re-edit: replace the bold param being edited with the given text. Returns true when applied. */
+    replaceEditingRange: (replacement: string) => boolean;
     inputProps: {
         value: string;
         placeholder: string | undefined;
@@ -180,12 +217,14 @@ interface AIAutocompleteDropdownProps {
     onPillClick?: (index: number) => void;
     /** Whether to render pills inside the dropdown. Default: true. Tier 2 consumers who render their own pills should set this to false. */
     showPills?: boolean;
+    /** True while a fetch for the latest query is in flight. Replaces options/pills with a skeleton. */
+    isLoading?: boolean;
 }
 
 declare const AIAutocomplete: react.ForwardRefExoticComponent<AIAutocompleteProps & react.RefAttributes<AIAutocompleteHandle>>;
 
-declare function AIAutocompleteDropdown({ suggestions, activeIndex, onSelect, onHighlight, isOpen, id, className, pills, onPillClick, showPills, }: AIAutocompleteDropdownProps): react_jsx_runtime.JSX.Element;
+declare function AIAutocompleteDropdown({ suggestions, activeIndex, onSelect, onHighlight, isOpen, id, className, pills, onPillClick, showPills, isLoading, }: AIAutocompleteDropdownProps): react_jsx_runtime.JSX.Element;
 
-declare function useAIAutocomplete({ onSubmit, onError, optionOverrides, maskCompletedText, apiConfig, columns, dropdownTrigger, closeDropdownOnBlur, onFocus, onBlur, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, source, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
+declare function useAIAutocomplete({ onSubmit, onError, optionOverrides, maskCompletedText, apiConfig, columns, dropdownTrigger, closeDropdownOnBlur, onFocus, onBlur, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, source, setCursor, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
 
 export { AIAutocomplete, AIAutocompleteDropdown, type AIAutocompleteDropdownProps, type AIAutocompleteHandle, type AIAutocompleteProps, type APIConfig, type APIKeyConfig, type AccessTokenConfig, type AccessTokenResult, type AppearanceMode, type AutocompleteResult, type CompletedParam, type CompletedParamState, type OptionOverrides, type Segment, type Suggestion, type SuggestionOption, type TaskKind, type UseAIAutocompleteOptions, type UseAIAutocompleteReturn, useAIAutocomplete };