@magicx-eng/ai-autocomplete-vanilla 0.1.13 → 0.1.15

package/README.md

@@ -6,15 +6,18 @@ 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
 - **Lightweight** — ~10 KB gzipped, styles auto-injected at runtime
 - **TypeScript first** — full type definitions shipped with the package
@@ -115,7 +118,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,7 +230,7 @@ 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 |
@@ -240,7 +249,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 +341,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,7 +351,7 @@ 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. |
@@ -373,14 +383,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,19 @@ 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;
 }
 /**
  * Render mode:
@@ -136,6 +152,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 {
@@ -166,7 +190,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 +250,7 @@ declare class AIAutocomplete {
     on(event: string, callback: (...args: unknown[]) => void): () => void;
     update(opts: Partial<CoreOptions>): void;
     selectOption(option: SuggestionOption): void;
+    private selectOptionInEditMode;
     private fireTelemetry;
     private recomputeDerived;
     private setupContainer;
@@ -189,6 +261,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,19 @@ 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;
 }
 /**
  * Render mode:
@@ -136,6 +152,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 {
@@ -166,7 +190,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 +250,7 @@ declare class AIAutocomplete {
     on(event: string, callback: (...args: unknown[]) => void): () => void;
     update(opts: Partial<CoreOptions>): void;
     selectOption(option: SuggestionOption): void;
+    private selectOptionInEditMode;
     private fireTelemetry;
     private recomputeDerived;
     private setupContainer;
@@ -189,6 +261,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;