@magicx-eng/ai-autocomplete-vanilla 0.1.14 → 0.1.16

package/README.md

@@ -6,16 +6,20 @@ A framework-agnostic vanilla JS/TypeScript library that provides a guided AI-pow
 
 - **Three tiers of integration** — full drop-in component, dropdown-only, or fully headless
 - **Zero dependencies** — no React, no framework, no virtual DOM
-- **Pill-based input** — inline pills for unfilled parameters, completed text for filled ones
-- **Pill placement** — render pills inline in the input or inside the dropdown
+- **Rich inline input** — a single `contentEditable` surface: typed text, bold completed params, and inline pills all 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
 - **Light/dark mode** — built-in themes with `prefers-color-scheme` support, fully overridable via CSS variables
 - **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
 - **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
-- **Accessible** — ARIA combobox pattern with `role="listbox"`, `aria-activedescendant`
+- **Accessible** — ARIA combobox 1.2 pattern with `role="listbox"`, `aria-activedescendant`
+- **IME-safe** — composition events are buffered so input text is committed once, after composition ends
 - **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** — ~10 KB gzipped, styles auto-injected at runtime
 - **TypeScript first** — full type definitions shipped with the package
 - **SSR-safe** — no top-level `document`/`window` access
@@ -115,7 +119,13 @@ ac.update({ animations: false, optionsPosition: "above" });
 
 > **Tier 1 auto-resets** after both Enter key and built-in submit-button clicks — your `onSubmit` runs, then the SDK clears the input and starts a new session. You don't need to call `ac.reset()` yourself in Tier 1.
 
-> `autoFocus`, `focus()`, and `blur()` only operate on the textarea the library owns (Tier 1 / `renderMode: "full"`). In Tier 2/3, the consumer owns the input and calls `.focus()` / `.blur()` on their own element; the `onFocus` / `onBlur` callbacks still fire whenever `setFocused()` is called.
+> `autoFocus`, `focus()`, and `blur()` only operate on the contentEditable editor the library owns (Tier 1 / `renderMode: "full"`). In Tier 2/3, the consumer owns the input and calls `.focus()` / `.blur()` on their own element; the `onFocus` / `onBlur` callbacks still fire whenever `setFocused()` is called.
+
+> **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. Typing atomically replaces the bold (and re-promotes it to bold if what you type exactly matches one of the cached options); clicking an option replaces it with the new selection; pressing Escape or moving the caret out exits without changes.
+
+> **Caret placement after a completion** — whenever a completed param is added (by any means — option click, exact-match typing, or re-edit), the caret lands right after the trailing space following the bold so typing can continue immediately. A space is inserted if one wasn't already there.
 
 #### Custom submit button
 
@@ -221,12 +231,14 @@ unsub();
 | `suggestions` | `Suggestion[]` | All suggestions from server (including placeholder type) |
 | `actionableSuggestions` | `Suggestion[]` | Non-placeholder suggestions (the pills) |
 | `filteredOptions` | `SuggestionOption[]` | Options for the active suggestion, filtered by current query |
-| `segments` | `Segment[]` | Input text split into typed text vs completed params — for overlay rendering |
+| `segments` | `Segment[]` | Input text split into typed text vs completed params — completed segments render as bold `<strong>` runs inside the editor |
 | `placeholderText` | `string` | Placeholder text from server suggestions (joined `placeholder`-type suggestion texts) |
 | `activeDropdownIndex` | `number` | Highlighted option index (-1 = none) |
 | `isDropdownOpen` | `boolean` | Whether the dropdown should be visible |
 | `newParamId` | `string \| null` | ID of the most recently added param (for shimmer animation) |
-| `isLoading` | `boolean` | Fetch in progress |
+| `isLoading` | `boolean` | Fetch in progress. The Tier 1 / Tier 2 renderers gate the loading skeleton additionally on `!inSelectionAnimation` and `!editingParam`. |
+| `inSelectionAnimation` | `boolean` | True for the 500 ms after a user-initiated option tap so the streak animation can finish before the dropdown switches to the loading skeleton. |
+| `editingParam` | `CompletedParamState \| null` | When non-null, the user is re-editing a bold completed param; cached options remain visible and the loading skeleton is suppressed. |
 | `isReady` | `boolean` | Server indicates query is complete |
 | `error` | `Error \| null` | Last fetch error |
 
@@ -240,7 +252,7 @@ unsub();
 | `selectOption(option)` | Select a dropdown option. Updates text, creates completed param, triggers shimmer. |
 | `setActiveDropdownIndex(index)` | Set the highlighted option (for mouse hover). |
 | `setActivePill(index)` | Reorder pills — moves pill at `index` to front (active). |
-| `removeLastParam()` | Remove last completed param, restore it as a pill. |
+| `removeLastParam()` | Remove the last completed param from state. The text stays in the input as plain text. |
 | `clearNewParamId()` | Clear shimmer animation state. |
 | `reset()` | Clear all state, re-fetch initial suggestions, and start a new session (rotates `session_id`). Call this after handling submit. |
 | `setValue(text)` | Set text (controlled mode). |
@@ -332,6 +344,7 @@ Override these on the container element. All built-in defaults use `:where()` (z
 
 | Variable | Default (light) | Default (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 |
@@ -341,13 +354,14 @@ Override these on the container element. All built-in defaults use `:where()` (z
 | `--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. |
 
 ### Per-mode Overrides
 
@@ -373,14 +387,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 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`).
+
 The vanilla core also exposes stable BEM class names (`magicx-aia-*`); both can be used.
 
 ```css

package/index.d.mts

@@ -22,8 +22,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>;
 }
@@ -85,6 +88,25 @@ interface CoreState {
     skipNextFetch: boolean;
     lastRawQuery: string;
     isFocused: boolean;
+    /**
+     * Re-edit state: while non-null, the user is editing a bold completed param.
+     * The snapshot stays here even after the param is removed from
+     * `completedParams` (when typing/backspace replaces its text), so the
+     * dropdown can keep filtering the cached options.
+     */
+    editingParam: CompletedParamState | null;
+    /** Plain-text offset where the edited param started (anchor for the edit region). */
+    editingAnchor: number | null;
+    /** Plain-text offset of the right edge of the edit region. Caret outside [anchor, tail] exits edit mode. */
+    editingTail: number | null;
+    /** Current caret offset within the editor. Tracked via DOM `selectionchange`. */
+    caretOffset: number | null;
+    /**
+     * True for ~500ms after a user-initiated option selection so the streak
+     * animation can finish before the dropdown switches to its loading skeleton.
+     * Set by selectOption / selectOptionInEditMode, cleared by a timer.
+     */
+    inSelectionAnimation: boolean;
 }
 /**
  * Render mode:
@@ -136,6 +158,14 @@ interface CoreOptions {
     onBlur?: () => void;
     value?: string;
     completedParams?: CompletedParamState[];
+    /**
+     * Headless-mode caret setter. The core invokes this in place of writing to
+     * its own `domRefs.input` when re-edit / Backspace flows need to park the
+     * caret at a specific plain-text offset. Wrappers that own the DOM (React,
+     * etc.) must provide this — vanilla "full" mode falls back to `domRefs`.
+     * @internal
+     */
+    setCursor?: (offset: number) => void;
 }
 
 declare class AIAutocomplete {
@@ -154,6 +184,7 @@ declare class AIAutocomplete {
     private dropdownRefs;
     private newParamTimer;
     private suggestionRemovalTimer;
+    private selectionAnimationTimer;
     private externalListeners;
     private sessionId;
     constructor(container: HTMLElement, opts?: CoreOptions);
@@ -166,7 +197,54 @@ declare class AIAutocomplete {
     setCompletedParams(params: CompletedParamState[]): void;
     setActivePill(index: number): void;
     removeLastParam(): void;
+    /**
+     * Backspace inside a completed param: drop the param's "completed" status so
+     * it renders as plain (un-bold) text, AND remove one grapheme before the
+     * caret — same single-character delete a normal Backspace would do. The
+     * remaining text stays in the input so the user can continue editing what
+     * they had typed instead of losing the whole phrase.
+     *
+     * Returns true when a param was reconciled (caller should `preventDefault`).
+     */
+    removeParamAtCaret(offset: number): boolean;
+    /**
+     * Set the editor caret at the given plain-text offset. Uses the core's own
+     * `domRefs.input` in "full" mode; falls back to the wrapper-provided
+     * `setCursor` callback in "headless" mode where the wrapper owns the DOM.
+     */
+    private scheduleSetCursor;
     clearNewParamId(): void;
+    /**
+     * Enter re-edit mode for the bold completed param with the given id. The
+     * caller is responsible for highlighting the param via the Selection API
+     * (DOM concern). This method just sets the state snapshot so the dropdown
+     * starts filtering the param's cached options.
+     */
+    startEditingParam(paramId: string): void;
+    /**
+     * Replace the editing range (`text[editingAnchor..editingTail]`) with the
+     * given replacement. Used by the DOM layer's `beforeinput` intercept: while
+     * the edited param's strong still exists in `completedParams`, typing or
+     * backspace should swap the WHOLE param atomically (instead of inserting
+     * one char into the bold span). Returns true when the replacement was
+     * applied — callers should `preventDefault` only in that case.
+     */
+    replaceEditingRange(replacement: string): boolean;
+    /** Clear re-edit state. Selection collapsing is a DOM concern handled by the caller. */
+    exitEditMode(): void;
+    /**
+     * Update caret offset after a text-input event. While in edit mode, extends
+     * `editingTail` to keep up with the user typing past the previous tail.
+     * Exits edit mode if the user backspaced past `editingAnchor` (deleting a
+     * character before where the edit started).
+     */
+    handleCaretAfterInput(offset: number | null): void;
+    /**
+     * Update caret offset from a selection-move event that was NOT preceded by
+     * an input event (so the user moved the cursor by click or arrows, not by
+     * typing). Exits edit mode if the caret moved outside the edit region.
+     */
+    handleCaretMove(offset: number | null): void;
     setActiveDropdownIndex(index: number): void;
     handleTextChange(value: string): void;
     handleKeyDown(e: KeyboardEvent): void;
@@ -179,6 +257,8 @@ declare class AIAutocomplete {
     on(event: string, callback: (...args: unknown[]) => void): () => void;
     update(opts: Partial<CoreOptions>): void;
     selectOption(option: SuggestionOption): void;
+    private startSelectionAnimationTimer;
+    private selectOptionInEditMode;
     private fireTelemetry;
     private recomputeDerived;
     private setupContainer;
@@ -189,6 +269,22 @@ declare class AIAutocomplete {
     /** Auto-clear newParamId after shimmer animation. */
     private subscribeNewParamTimer;
     private handleChange;
+    /**
+     * When the user has typed text that exactly matches (case-insensitive) one
+     * of the active suggestion's options, promote it to a completed param right
+     * away. The fetchController does the same check when the debounced fetch
+     * lands; doing it instantly here means bold styling appears as soon as the
+     * option is fully typed, without waiting 100–300ms for the round-trip.
+     */
+    private maybePromoteExactMatch;
+    /**
+     * Edit-mode counterpart to {@link maybePromoteExactMatch}. When the user is
+     * editing a bold completed param and the typed text exactly matches one of
+     * that param's cached options, promote it back to a completed param (bold)
+     * — same instant-bold affordance as the normal typing flow, just driven by
+     * the edited param's cached options instead of the active suggestion.
+     */
+    private maybePromoteEditExactMatch;
 }
 
 type Listener<S> = (next: S, prev: S) => void;

package/index.d.ts

@@ -22,8 +22,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>;
 }
@@ -85,6 +88,25 @@ interface CoreState {
     skipNextFetch: boolean;
     lastRawQuery: string;
     isFocused: boolean;
+    /**
+     * Re-edit state: while non-null, the user is editing a bold completed param.
+     * The snapshot stays here even after the param is removed from
+     * `completedParams` (when typing/backspace replaces its text), so the
+     * dropdown can keep filtering the cached options.
+     */
+    editingParam: CompletedParamState | null;
+    /** Plain-text offset where the edited param started (anchor for the edit region). */
+    editingAnchor: number | null;
+    /** Plain-text offset of the right edge of the edit region. Caret outside [anchor, tail] exits edit mode. */
+    editingTail: number | null;
+    /** Current caret offset within the editor. Tracked via DOM `selectionchange`. */
+    caretOffset: number | null;
+    /**
+     * True for ~500ms after a user-initiated option selection so the streak
+     * animation can finish before the dropdown switches to its loading skeleton.
+     * Set by selectOption / selectOptionInEditMode, cleared by a timer.
+     */
+    inSelectionAnimation: boolean;
 }
 /**
  * Render mode:
@@ -136,6 +158,14 @@ interface CoreOptions {
     onBlur?: () => void;
     value?: string;
     completedParams?: CompletedParamState[];
+    /**
+     * Headless-mode caret setter. The core invokes this in place of writing to
+     * its own `domRefs.input` when re-edit / Backspace flows need to park the
+     * caret at a specific plain-text offset. Wrappers that own the DOM (React,
+     * etc.) must provide this — vanilla "full" mode falls back to `domRefs`.
+     * @internal
+     */
+    setCursor?: (offset: number) => void;
 }
 
 declare class AIAutocomplete {
@@ -154,6 +184,7 @@ declare class AIAutocomplete {
     private dropdownRefs;
     private newParamTimer;
     private suggestionRemovalTimer;
+    private selectionAnimationTimer;
     private externalListeners;
     private sessionId;
     constructor(container: HTMLElement, opts?: CoreOptions);
@@ -166,7 +197,54 @@ declare class AIAutocomplete {
     setCompletedParams(params: CompletedParamState[]): void;
     setActivePill(index: number): void;
     removeLastParam(): void;
+    /**
+     * Backspace inside a completed param: drop the param's "completed" status so
+     * it renders as plain (un-bold) text, AND remove one grapheme before the
+     * caret — same single-character delete a normal Backspace would do. The
+     * remaining text stays in the input so the user can continue editing what
+     * they had typed instead of losing the whole phrase.
+     *
+     * Returns true when a param was reconciled (caller should `preventDefault`).
+     */
+    removeParamAtCaret(offset: number): boolean;
+    /**
+     * Set the editor caret at the given plain-text offset. Uses the core's own
+     * `domRefs.input` in "full" mode; falls back to the wrapper-provided
+     * `setCursor` callback in "headless" mode where the wrapper owns the DOM.
+     */
+    private scheduleSetCursor;
     clearNewParamId(): void;
+    /**
+     * Enter re-edit mode for the bold completed param with the given id. The
+     * caller is responsible for highlighting the param via the Selection API
+     * (DOM concern). This method just sets the state snapshot so the dropdown
+     * starts filtering the param's cached options.
+     */
+    startEditingParam(paramId: string): void;
+    /**
+     * Replace the editing range (`text[editingAnchor..editingTail]`) with the
+     * given replacement. Used by the DOM layer's `beforeinput` intercept: while
+     * the edited param's strong still exists in `completedParams`, typing or
+     * backspace should swap the WHOLE param atomically (instead of inserting
+     * one char into the bold span). Returns true when the replacement was
+     * applied — callers should `preventDefault` only in that case.
+     */
+    replaceEditingRange(replacement: string): boolean;
+    /** Clear re-edit state. Selection collapsing is a DOM concern handled by the caller. */
+    exitEditMode(): void;
+    /**
+     * Update caret offset after a text-input event. While in edit mode, extends
+     * `editingTail` to keep up with the user typing past the previous tail.
+     * Exits edit mode if the user backspaced past `editingAnchor` (deleting a
+     * character before where the edit started).
+     */
+    handleCaretAfterInput(offset: number | null): void;
+    /**
+     * Update caret offset from a selection-move event that was NOT preceded by
+     * an input event (so the user moved the cursor by click or arrows, not by
+     * typing). Exits edit mode if the caret moved outside the edit region.
+     */
+    handleCaretMove(offset: number | null): void;
     setActiveDropdownIndex(index: number): void;
     handleTextChange(value: string): void;
     handleKeyDown(e: KeyboardEvent): void;
@@ -179,6 +257,8 @@ declare class AIAutocomplete {
     on(event: string, callback: (...args: unknown[]) => void): () => void;
     update(opts: Partial<CoreOptions>): void;
     selectOption(option: SuggestionOption): void;
+    private startSelectionAnimationTimer;
+    private selectOptionInEditMode;
     private fireTelemetry;
     private recomputeDerived;
     private setupContainer;
@@ -189,6 +269,22 @@ declare class AIAutocomplete {
     /** Auto-clear newParamId after shimmer animation. */
     private subscribeNewParamTimer;
     private handleChange;
+    /**
+     * When the user has typed text that exactly matches (case-insensitive) one
+     * of the active suggestion's options, promote it to a completed param right
+     * away. The fetchController does the same check when the debounced fetch
+     * lands; doing it instantly here means bold styling appears as soon as the
+     * option is fully typed, without waiting 100–300ms for the round-trip.
+     */
+    private maybePromoteExactMatch;
+    /**
+     * Edit-mode counterpart to {@link maybePromoteExactMatch}. When the user is
+     * editing a bold completed param and the typed text exactly matches one of
+     * that param's cached options, promote it back to a completed param (bold)
+     * — same instant-bold affordance as the normal typing flow, just driven by
+     * the edited param's cached options instead of the active suggestion.
+     */
+    private maybePromoteEditExactMatch;
 }
 
 type Listener<S> = (next: S, prev: S) => void;