@magicx-eng/ai-autocomplete-vanilla 0.5.6 → 0.6.0

package/README.md

@@ -374,11 +374,12 @@ Override these on the container element. All built-in defaults use `:where()` (z
 | `--aia-shadow` | `inset 0 1px 0 rgba(255,255,255,0.9), 0 1px 2px rgba(16,24,40,0.1), 0 8px 24px rgba(16,24,40,0.16)` | `inset 0 1px 0 rgba(255,255,255,0.06), 0 1px 2px rgba(0,0,0,0.4), 0 8px 24px rgba(0,0,0,0.5)` | Input container elevation (box-shadow) |
 | `--aia-dropdown-offset` | `13px` | `13px` | Gap between the input box and the dropdown (the dropdown's margin toward the input). |
 | `--aia-footer-gap` | `8px` | `8px` | Breathing room above the dropdown footer (badge / keyboard hints), additive to the dropdown's 8px section gap. |
+| `--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-skeleton-bg` | `rgba(189, 189, 189, 0.51)` | `#333539` | Fill color for the loading skeleton bars and the masked text in cached pills/options. |
+| `--aia-skeleton-bg` | `rgba(189, 189, 189, 0.25)` | `#1a1b1d` | Fill color for the loading skeleton bars and the masked text in cached pills/options. |
 
 ### Per-mode Overrides
 

package/dist/index.d.mts

@@ -23,11 +23,28 @@ interface InputItem {
     type: string;
     text: string;
     state: "completed" | "in_progress";
+    /** Absent or "selected" = echo of client params; "identified" = LLM-inferred. */
+    source?: "selected" | "identified";
+}
+/** Wire shape for an LLM-identified param echoed back to the server. */
+interface IdentifiedParam {
+    type: string;
+    value: string;
+}
+/**
+ * Wire shape for a recently-suggested hint entry: a suggestion that was on
+ * screen when the user started typing the current unresolved trailing text.
+ */
+interface RecentlySuggested {
+    type: string;
+    text: string;
 }
 interface AutocompleteRequest {
     data: {
         raw_query: string;
         completed_params: CompletedParam[];
+        identified_params?: IdentifiedParam[];
+        recently_suggested?: RecentlySuggested[];
         contact_account_count?: number;
     };
     meta: {
@@ -61,6 +78,16 @@ interface CompletedParamState extends CompletedParam {
     options: SuggestionOption[];
     metadata?: Record<string, unknown>;
 }
+/**
+ * Client-side state for an LLM-identified param. Tentative — replaced
+ * wholesale from each response (latest wins) and dropped when its text no
+ * longer matches. Never placeholder-substituted in raw_query.
+ */
+interface IdentifiedParamState {
+    id: string;
+    type: string;
+    text: string;
+}
 type Segment = {
     type: "text";
     value: string;
@@ -68,6 +95,10 @@ type Segment = {
     type: "completed";
     value: string;
     param: CompletedParamState;
+} | {
+    type: "identified";
+    value: string;
+    param: IdentifiedParamState;
 };
 type AppearanceMode = "light" | "dark" | "auto";
 interface APIConfigBase {
@@ -105,6 +136,24 @@ interface AutocompleteResult {
 interface CoreInputState {
     text: string;
     completedParams: CompletedParamState[];
+    /**
+     * LLM-identified params from the latest response. Revisable: replaced
+     * wholesale per response, dropped when their text is edited away. Never
+     * override or overlap completed params.
+     */
+    identifiedParams: IdentifiedParamState[];
+    /**
+     * Open while the user has unresolved trailing text: anchored at the covered
+     * offset where they started typing, snapshotting the actionable suggestions
+     * that were on screen. While open, fetches carry `recently_suggested`
+     * (snapshot ∪ current on-screen suggestions). Closes when the trailing text
+     * becomes covered by a completed/identified param, is deleted back to the
+     * anchor, is consumed by an option selection, or on reset().
+     */
+    pendingSpan: {
+        anchor: number;
+        snapshot: Suggestion[];
+    } | null;
     suggestions: Suggestion[];
     activeDropdownIndex: number;
     newParamId: string | null;
@@ -325,6 +374,14 @@ declare class AIAutocomplete {
     /** Auto-clear newParamId after shimmer animation. */
     private subscribeNewParamTimer;
     private handleChange;
+    /**
+     * Opens the pending span on the first keystroke past covered text: there is
+     * unresolved trailing text beyond the covered offset (filterBase / last pill
+     * end), actionable suggestions are on screen, and no span is already open.
+     * The span snapshots those suggestions so `recently_suggested` can carry
+     * them even after later responses replace what's on screen.
+     */
+    private maybeOpenPendingSpan;
     /**
      * 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
@@ -439,7 +496,12 @@ interface BuildQueryResult {
  * replaces each completed param's text in the string with a {{TYPE_N}} token,
  * and returns the transformed query + params with placeholders filled in.
  *
- * Replacements happen left-to-right, first occurrence only per param.
+ * Replacements advance a position cursor (params are appended in text order in
+ * normal flows), so a short param value (e.g. quantity "1") can never match
+ * INSIDE an already-inserted placeholder (e.g. the "1" in "{{SIZE_1}}") and
+ * splice into it. Out-of-order params fall back to a from-zero rescan that
+ * rejects any match overlapping a previously inserted placeholder; with no
+ * clean match the param is left unreplaced (same as the text-not-found path).
  * Counter is per-type (e.g. {{TASK_1}}, {{GOAL_1}}, {{GOAL_2}}).
  */
 declare function buildQuery(text: string, completedParams: CompletedParamState[]): BuildQueryResult;
@@ -474,4 +536,4 @@ declare class ModeController {
     private detachListener;
 }
 
-export { AIAutocomplete, type APIConfig, type APIKeyConfig, ATTRIBUTION_URL, type AccessTokenConfig, type AccessTokenResult, type AppearanceMode, type AutocompleteRequest, type AutocompleteResponse, type AutocompleteResult, type CompletedParam, type CompletedParamState, type CoreOptions, type CoreState, type InputItem, ModeController, type OptionOverrides, type RenderMode, type Segment, type Store, type Suggestion, type SuggestionOption, type TaskKind, buildAttributionUrl, buildQuery, createStore, cursorIsAtEnd, extractPlainText, getCursorOffset, getFooterHint, plainTextLength, previousGraphemeBoundary, renderEditableContent, setCursorOffset };
+export { AIAutocomplete, type APIConfig, type APIKeyConfig, ATTRIBUTION_URL, type AccessTokenConfig, type AccessTokenResult, type AppearanceMode, type AutocompleteRequest, type AutocompleteResponse, type AutocompleteResult, type CompletedParam, type CompletedParamState, type CoreOptions, type CoreState, type IdentifiedParam, type IdentifiedParamState, type InputItem, ModeController, type OptionOverrides, type RecentlySuggested, type RenderMode, type Segment, type Store, type Suggestion, type SuggestionOption, type TaskKind, buildAttributionUrl, buildQuery, createStore, cursorIsAtEnd, extractPlainText, getCursorOffset, getFooterHint, plainTextLength, previousGraphemeBoundary, renderEditableContent, setCursorOffset };

package/dist/index.d.ts

@@ -23,11 +23,28 @@ interface InputItem {
     type: string;
     text: string;
     state: "completed" | "in_progress";
+    /** Absent or "selected" = echo of client params; "identified" = LLM-inferred. */
+    source?: "selected" | "identified";
+}
+/** Wire shape for an LLM-identified param echoed back to the server. */
+interface IdentifiedParam {
+    type: string;
+    value: string;
+}
+/**
+ * Wire shape for a recently-suggested hint entry: a suggestion that was on
+ * screen when the user started typing the current unresolved trailing text.
+ */
+interface RecentlySuggested {
+    type: string;
+    text: string;
 }
 interface AutocompleteRequest {
     data: {
         raw_query: string;
         completed_params: CompletedParam[];
+        identified_params?: IdentifiedParam[];
+        recently_suggested?: RecentlySuggested[];
         contact_account_count?: number;
     };
     meta: {
@@ -61,6 +78,16 @@ interface CompletedParamState extends CompletedParam {
     options: SuggestionOption[];
     metadata?: Record<string, unknown>;
 }
+/**
+ * Client-side state for an LLM-identified param. Tentative — replaced
+ * wholesale from each response (latest wins) and dropped when its text no
+ * longer matches. Never placeholder-substituted in raw_query.
+ */
+interface IdentifiedParamState {
+    id: string;
+    type: string;
+    text: string;
+}
 type Segment = {
     type: "text";
     value: string;
@@ -68,6 +95,10 @@ type Segment = {
     type: "completed";
     value: string;
     param: CompletedParamState;
+} | {
+    type: "identified";
+    value: string;
+    param: IdentifiedParamState;
 };
 type AppearanceMode = "light" | "dark" | "auto";
 interface APIConfigBase {
@@ -105,6 +136,24 @@ interface AutocompleteResult {
 interface CoreInputState {
     text: string;
     completedParams: CompletedParamState[];
+    /**
+     * LLM-identified params from the latest response. Revisable: replaced
+     * wholesale per response, dropped when their text is edited away. Never
+     * override or overlap completed params.
+     */
+    identifiedParams: IdentifiedParamState[];
+    /**
+     * Open while the user has unresolved trailing text: anchored at the covered
+     * offset where they started typing, snapshotting the actionable suggestions
+     * that were on screen. While open, fetches carry `recently_suggested`
+     * (snapshot ∪ current on-screen suggestions). Closes when the trailing text
+     * becomes covered by a completed/identified param, is deleted back to the
+     * anchor, is consumed by an option selection, or on reset().
+     */
+    pendingSpan: {
+        anchor: number;
+        snapshot: Suggestion[];
+    } | null;
     suggestions: Suggestion[];
     activeDropdownIndex: number;
     newParamId: string | null;
@@ -325,6 +374,14 @@ declare class AIAutocomplete {
     /** Auto-clear newParamId after shimmer animation. */
     private subscribeNewParamTimer;
     private handleChange;
+    /**
+     * Opens the pending span on the first keystroke past covered text: there is
+     * unresolved trailing text beyond the covered offset (filterBase / last pill
+     * end), actionable suggestions are on screen, and no span is already open.
+     * The span snapshots those suggestions so `recently_suggested` can carry
+     * them even after later responses replace what's on screen.
+     */
+    private maybeOpenPendingSpan;
     /**
      * 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
@@ -439,7 +496,12 @@ interface BuildQueryResult {
  * replaces each completed param's text in the string with a {{TYPE_N}} token,
  * and returns the transformed query + params with placeholders filled in.
  *
- * Replacements happen left-to-right, first occurrence only per param.
+ * Replacements advance a position cursor (params are appended in text order in
+ * normal flows), so a short param value (e.g. quantity "1") can never match
+ * INSIDE an already-inserted placeholder (e.g. the "1" in "{{SIZE_1}}") and
+ * splice into it. Out-of-order params fall back to a from-zero rescan that
+ * rejects any match overlapping a previously inserted placeholder; with no
+ * clean match the param is left unreplaced (same as the text-not-found path).
  * Counter is per-type (e.g. {{TASK_1}}, {{GOAL_1}}, {{GOAL_2}}).
  */
 declare function buildQuery(text: string, completedParams: CompletedParamState[]): BuildQueryResult;
@@ -474,4 +536,4 @@ declare class ModeController {
     private detachListener;
 }
 
-export { AIAutocomplete, type APIConfig, type APIKeyConfig, ATTRIBUTION_URL, type AccessTokenConfig, type AccessTokenResult, type AppearanceMode, type AutocompleteRequest, type AutocompleteResponse, type AutocompleteResult, type CompletedParam, type CompletedParamState, type CoreOptions, type CoreState, type InputItem, ModeController, type OptionOverrides, type RenderMode, type Segment, type Store, type Suggestion, type SuggestionOption, type TaskKind, buildAttributionUrl, buildQuery, createStore, cursorIsAtEnd, extractPlainText, getCursorOffset, getFooterHint, plainTextLength, previousGraphemeBoundary, renderEditableContent, setCursorOffset };
+export { AIAutocomplete, type APIConfig, type APIKeyConfig, ATTRIBUTION_URL, type AccessTokenConfig, type AccessTokenResult, type AppearanceMode, type AutocompleteRequest, type AutocompleteResponse, type AutocompleteResult, type CompletedParam, type CompletedParamState, type CoreOptions, type CoreState, type IdentifiedParam, type IdentifiedParamState, type InputItem, ModeController, type OptionOverrides, type RecentlySuggested, type RenderMode, type Segment, type Store, type Suggestion, type SuggestionOption, type TaskKind, buildAttributionUrl, buildQuery, createStore, cursorIsAtEnd, extractPlainText, getCursorOffset, getFooterHint, plainTextLength, previousGraphemeBoundary, renderEditableContent, setCursorOffset };