@magicx-eng/ai-autocomplete-vanilla 0.1.17 → 0.1.18

package/README.md

@@ -82,6 +82,7 @@ const ac = new AIAutocomplete(container, {
   pillPlacement: "inline",     // "inline" | "dropdown" | "hidden"
   dropdownTrigger: "auto",   // "auto" | "manual" | "hidden"
   closeDropdownOnBlur: true, // false = keep dropdown open even when input loses focus
+  showNonTappableOptions: true, // false = hide non-tappable options from the dropdown
 
   // Focus
   autoFocus: true,           // focus the input on mount (Tier 1 only)
@@ -201,7 +202,9 @@ const state = ac.getState();
 // state.placeholderText, state.isDropdownOpen, state.activeDropdownIndex,
 // state.newParamId, state.isLoading, state.isReady, state.error
 
-// Subscribe to changes (fires after derived state is settled)
+// Subscribe to state changes. The listener receives the full state shape
+// (raw inputs + derived fields like `segments`, `actionableSuggestions`,
+// `filteredOptions`, `placeholderText`, `isDropdownOpen`).
 const unsub = ac.subscribe((state) => {
   renderMyInput(state.text, state.placeholderText);
   renderMyPills(state.actionableSuggestions);
@@ -260,7 +263,7 @@ unsub();
 | `setMode(mode)` | Switch color mode at runtime. |
 | `update(opts)` | Update multiple options at once (e.g. `animations`, `pillPlacement`, `dropdownTrigger`, `optionsPosition`). |
 | `getState()` | Get a snapshot of the current state. Useful for initial read before subscribing. |
-| `subscribe(listener)` | Subscribe to state changes (fires after derived state settles). Returns unsubscribe function. |
+| `subscribe(listener)` | Subscribe to state changes. The listener receives the full state (raw inputs + derived fields). Returns unsubscribe function. |
 | `destroy()` | Cleanup — abort fetches, clear timers, remove listeners. |
 
 ### Building a framework wrapper
@@ -324,13 +327,18 @@ The object passed to `onSubmit`:
 ```ts
 const off = ac.on("submit", (result) => { ... });
 off(); // unsubscribe
+
+// Multiple listeners on the same event are supported — each `on()` call adds
+// a listener; the returned function removes only the listener it registered.
+const offA = ac.on("change", logToAnalytics);
+const offB = ac.on("change", syncToStore);
 ```
 
-Events: `submit`, `error`, `change`, `paramsChange`, `focus`, `blur`.
+Events: `submit`, `error`, `change`, `paramsChange`, `stateChange`, `focus`, `blur`.
 
-Constructor callbacks (`onSubmit`, `onChange`, etc.) are equivalent to calling `on()`.
+Constructor callbacks (`onSubmit`, `onChange`, etc.) are registered once at construction as the initial listener for that event. Use `on()` for any additional or replacement listeners. **`update()` does not swap event listeners** — use `on()` for dynamic listener management.
 
-**`subscribe()` vs `on()`:** Use `on()` for specific events (submit, error, text change). Use `subscribe()` (Tier 3) for full state updates — it fires after derived state is settled, making it safe for rendering.
+**`subscribe()` vs `on()`:** Use `on()` for specific events (submit, error, text change). Use `subscribe()` (Tier 3) for full state updates — every `subscribe` callback receives the merged input + derived state, ready to read.
 
 ---
 

package/index.d.mts

@@ -67,8 +67,11 @@ interface AutocompleteResult {
     completed_params: CompletedParam[];
 }
 
-/** Internal state managed by the store. */
-interface CoreState {
+/**
+ * Raw, user/network/internal-driven fields. The store holds *only* these —
+ * derived state is recomputed lazily on read. See {@link CoreDerivedState}.
+ */
+interface CoreInputState {
     text: string;
     completedParams: CompletedParamState[];
     suggestions: Suggestion[];
@@ -77,11 +80,6 @@ interface CoreState {
     isLoading: boolean;
     isReady: boolean;
     error: Error | null;
-    segments: Segment[];
-    actionableSuggestions: Suggestion[];
-    filteredOptions: SuggestionOption[];
-    placeholderText: string;
-    isDropdownOpen: boolean;
     filterBase: number;
     filterInProgress: boolean;
     pillTapped: boolean;
@@ -104,10 +102,27 @@ interface CoreState {
     /**
      * 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.
+     * Set by selectOption / ReEditManager.selectOption, cleared by a timer.
      */
     inSelectionAnimation: boolean;
 }
+/**
+ * Derived fields recomputed from {@link CoreInputState} + {@link CoreOptions}.
+ * Never stored — produced lazily by the derive function and merged onto
+ * `get()` reads / subscriber notifications.
+ */
+interface CoreDerivedState {
+    segments: Segment[];
+    actionableSuggestions: Suggestion[];
+    filteredOptions: SuggestionOption[];
+    placeholderText: string;
+    isDropdownOpen: boolean;
+}
+/**
+ * Full state shape (inputs + derived) exposed to consumers via `getState()`
+ * and subscribers.
+ */
+type CoreState = CoreInputState & CoreDerivedState;
 /**
  * Render mode:
  * - "full" (default) — renders input + dropdown + pills. Tier 1.
@@ -130,6 +145,8 @@ interface CoreOptions {
     dropdownTrigger?: "auto" | "manual" | "hidden";
     /** When true (default), the dropdown closes when the input loses focus. Set to false to keep it open whenever options are available, regardless of focus. */
     closeDropdownOnBlur?: boolean;
+    /** When true (default), non-tappable options are rendered in the dropdown alongside tappable ones. Set to false to hide them entirely. */
+    showNonTappableOptions?: boolean;
     /** Render mode. Default: "full". */
     renderMode?: RenderMode;
     /**
@@ -168,25 +185,36 @@ interface CoreOptions {
     setCursor?: (offset: number) => void;
 }
 
+type AIAutocompleteEvents = {
+    submit: [result: AutocompleteResult];
+    error: [error: Error];
+    change: [text: string];
+    paramsChange: [params: CompletedParamState[]];
+    stateChange: [state: CoreState];
+    focus: [];
+    blur: [];
+};
+type CoreUpdateOptions = Partial<Omit<CoreOptions, "onSubmit" | "onError" | "onChange" | "onParamsChange" | "onStateChange" | "onFocus" | "onBlur">>;
 declare class AIAutocomplete {
+    private inputStore;
     private store;
     private _listboxId;
     private opts;
     private fetchController;
     private keyboardController;
     private pillsController;
+    private reEdit;
     private modeController;
     private container;
     private unsubscribers;
-    private derivedInProgress;
     private renderMode;
     private domRefs;
     private dropdownRefs;
-    private newParamTimer;
-    private suggestionRemovalTimer;
-    private selectionAnimationTimer;
-    private externalListeners;
+    private timers;
+    private emitter;
     private sessionId;
+    private readonly emitSubmit;
+    private readonly emitError;
     constructor(container: HTMLElement, opts?: CoreOptions);
     focus(): void;
     blur(): void;
@@ -211,56 +239,41 @@ declare class AIAutocomplete {
      * 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.
+     *
+     * Also focuses the input — setting a selection range without focus leaves a
+     * visible caret that doesn't actually accept typing, and every caller (pill
+     * tap, post-promote refocus, re-edit entry, Backspace-into-param) expects
+     * the editor to be focused afterwards.
      */
     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;
     setFocused(focused: boolean): void;
-    /** Subscribe to state changes (fires after derived state is settled). Returns unsubscribe function. */
+    /** Subscribe to state changes. Listener receives the full (input + derived) shape. */
     subscribe(listener: (state: CoreState) => void): () => void;
     getState(): CoreState;
     get listboxId(): string;
     get isReady(): boolean;
-    on(event: string, callback: (...args: unknown[]) => void): () => void;
-    update(opts: Partial<CoreOptions>): void;
+    /**
+     * Subscribe to an event. Multiple listeners may register for the same event;
+     * `emit` fans out to all of them. The returned function removes only the
+     * listener it registered.
+     *
+     * Note: `opts.on*` listeners passed at construction are equivalent to calling
+     * `on()` once each; their unsubscribe handles are not exposed.
+     */
+    on<E extends keyof AIAutocompleteEvents>(event: E, callback: (...args: AIAutocompleteEvents[E]) => void): () => void;
+    update(opts: CoreUpdateOptions): void;
     selectOption(option: SuggestionOption): void;
     private startSelectionAnimationTimer;
-    private selectOptionInEditMode;
     private fireTelemetry;
-    private recomputeDerived;
     private setupContainer;
     private buildAndRenderFull;
     private buildAndRenderDropdown;
@@ -269,6 +282,17 @@ declare class AIAutocomplete {
     /** Auto-clear newParamId after shimmer animation. */
     private subscribeNewParamTimer;
     private handleChange;
+    /**
+     * In re-edit mode, once the user has typed enough that no *tappable* options
+     * still match (non-tappable options are kept by filterOptions regardless of
+     * the query, so they don't count as "still matching"), exit re-edit and
+     * fire an immediate fetch so the dropdown swaps over to fresh server
+     * suggestions instead of staying frozen on a dead filter.
+     *
+     * Guarded against re-entry: once we exit, editingParam is null and the
+     * subscription early-returns on subsequent fires.
+     */
+    private maybeExitReEditOnNoMatch;
     /**
      * 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
@@ -277,14 +301,6 @@ declare class AIAutocomplete {
      * 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

@@ -67,8 +67,11 @@ interface AutocompleteResult {
     completed_params: CompletedParam[];
 }
 
-/** Internal state managed by the store. */
-interface CoreState {
+/**
+ * Raw, user/network/internal-driven fields. The store holds *only* these —
+ * derived state is recomputed lazily on read. See {@link CoreDerivedState}.
+ */
+interface CoreInputState {
     text: string;
     completedParams: CompletedParamState[];
     suggestions: Suggestion[];
@@ -77,11 +80,6 @@ interface CoreState {
     isLoading: boolean;
     isReady: boolean;
     error: Error | null;
-    segments: Segment[];
-    actionableSuggestions: Suggestion[];
-    filteredOptions: SuggestionOption[];
-    placeholderText: string;
-    isDropdownOpen: boolean;
     filterBase: number;
     filterInProgress: boolean;
     pillTapped: boolean;
@@ -104,10 +102,27 @@ interface CoreState {
     /**
      * 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.
+     * Set by selectOption / ReEditManager.selectOption, cleared by a timer.
      */
     inSelectionAnimation: boolean;
 }
+/**
+ * Derived fields recomputed from {@link CoreInputState} + {@link CoreOptions}.
+ * Never stored — produced lazily by the derive function and merged onto
+ * `get()` reads / subscriber notifications.
+ */
+interface CoreDerivedState {
+    segments: Segment[];
+    actionableSuggestions: Suggestion[];
+    filteredOptions: SuggestionOption[];
+    placeholderText: string;
+    isDropdownOpen: boolean;
+}
+/**
+ * Full state shape (inputs + derived) exposed to consumers via `getState()`
+ * and subscribers.
+ */
+type CoreState = CoreInputState & CoreDerivedState;
 /**
  * Render mode:
  * - "full" (default) — renders input + dropdown + pills. Tier 1.
@@ -130,6 +145,8 @@ interface CoreOptions {
     dropdownTrigger?: "auto" | "manual" | "hidden";
     /** When true (default), the dropdown closes when the input loses focus. Set to false to keep it open whenever options are available, regardless of focus. */
     closeDropdownOnBlur?: boolean;
+    /** When true (default), non-tappable options are rendered in the dropdown alongside tappable ones. Set to false to hide them entirely. */
+    showNonTappableOptions?: boolean;
     /** Render mode. Default: "full". */
     renderMode?: RenderMode;
     /**
@@ -168,25 +185,36 @@ interface CoreOptions {
     setCursor?: (offset: number) => void;
 }
 
+type AIAutocompleteEvents = {
+    submit: [result: AutocompleteResult];
+    error: [error: Error];
+    change: [text: string];
+    paramsChange: [params: CompletedParamState[]];
+    stateChange: [state: CoreState];
+    focus: [];
+    blur: [];
+};
+type CoreUpdateOptions = Partial<Omit<CoreOptions, "onSubmit" | "onError" | "onChange" | "onParamsChange" | "onStateChange" | "onFocus" | "onBlur">>;
 declare class AIAutocomplete {
+    private inputStore;
     private store;
     private _listboxId;
     private opts;
     private fetchController;
     private keyboardController;
     private pillsController;
+    private reEdit;
     private modeController;
     private container;
     private unsubscribers;
-    private derivedInProgress;
     private renderMode;
     private domRefs;
     private dropdownRefs;
-    private newParamTimer;
-    private suggestionRemovalTimer;
-    private selectionAnimationTimer;
-    private externalListeners;
+    private timers;
+    private emitter;
     private sessionId;
+    private readonly emitSubmit;
+    private readonly emitError;
     constructor(container: HTMLElement, opts?: CoreOptions);
     focus(): void;
     blur(): void;
@@ -211,56 +239,41 @@ declare class AIAutocomplete {
      * 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.
+     *
+     * Also focuses the input — setting a selection range without focus leaves a
+     * visible caret that doesn't actually accept typing, and every caller (pill
+     * tap, post-promote refocus, re-edit entry, Backspace-into-param) expects
+     * the editor to be focused afterwards.
      */
     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;
     setFocused(focused: boolean): void;
-    /** Subscribe to state changes (fires after derived state is settled). Returns unsubscribe function. */
+    /** Subscribe to state changes. Listener receives the full (input + derived) shape. */
     subscribe(listener: (state: CoreState) => void): () => void;
     getState(): CoreState;
     get listboxId(): string;
     get isReady(): boolean;
-    on(event: string, callback: (...args: unknown[]) => void): () => void;
-    update(opts: Partial<CoreOptions>): void;
+    /**
+     * Subscribe to an event. Multiple listeners may register for the same event;
+     * `emit` fans out to all of them. The returned function removes only the
+     * listener it registered.
+     *
+     * Note: `opts.on*` listeners passed at construction are equivalent to calling
+     * `on()` once each; their unsubscribe handles are not exposed.
+     */
+    on<E extends keyof AIAutocompleteEvents>(event: E, callback: (...args: AIAutocompleteEvents[E]) => void): () => void;
+    update(opts: CoreUpdateOptions): void;
     selectOption(option: SuggestionOption): void;
     private startSelectionAnimationTimer;
-    private selectOptionInEditMode;
     private fireTelemetry;
-    private recomputeDerived;
     private setupContainer;
     private buildAndRenderFull;
     private buildAndRenderDropdown;
@@ -269,6 +282,17 @@ declare class AIAutocomplete {
     /** Auto-clear newParamId after shimmer animation. */
     private subscribeNewParamTimer;
     private handleChange;
+    /**
+     * In re-edit mode, once the user has typed enough that no *tappable* options
+     * still match (non-tappable options are kept by filterOptions regardless of
+     * the query, so they don't count as "still matching"), exit re-edit and
+     * fire an immediate fetch so the dropdown swaps over to fresh server
+     * suggestions instead of staying frozen on a dead filter.
+     *
+     * Guarded against re-entry: once we exit, editingParam is null and the
+     * subscription early-returns on subsequent fires.
+     */
+    private maybeExitReEditOnNoMatch;
     /**
      * 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
@@ -277,14 +301,6 @@ declare class AIAutocomplete {
      * 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;