@magicx-eng/ai-autocomplete-vanilla 0.5.7 → 0.7.0

package/README.md

@@ -323,7 +323,19 @@ The object passed to `onSubmit`:
 |---|---|---|
 | `query` | `string` | Plain text as the user sees it. |
 | `raw_query` | `string` | Text with placeholder tokens (e.g. `"Create a {{TASK_1}}"`). |
-| `completed_params` | `CompletedParam[]` | Array of filled parameter values. |
+| `completed_params` | `CompletedParam[]` | Array of filled parameter values, followed by any the user skipped (see below). |
+
+#### Skipped parameters
+
+Pressing <kbd>→</kbd> at the end of the input dismisses the active pill. The dismissal is reported to the server — and included in `completed_params` here — as an entry with no placeholder and the sentinel text `"skipped"`:
+
+```ts
+{ placeholder: "", type: "goal", text: "skipped", kind: null }
+```
+
+Skipped entries are appended after the filled params (they have no position in the query) and are deduped by type. A skip is dropped if a param of the same type ends up filled anyway. Skipping the last available pill triggers an immediate request so the server can suggest something else; earlier skips ride along on the next request. `reset()` clears them.
+
+> **Reading `state.skippedParams` directly:** the array is append-only until `reset()`. The "drop a skip whose type got filled" rule is applied when the payload is built, not by pruning the array — so if the user skips `goal` and later fills one, the raw array still holds the `goal` entry. That's deliberate: the filter self-heals if they then delete that param's text, where pruning would discard the signal for good. Apply the same rule yourself with the exported `withSkippedParams(completedParams, skippedParams)`.
 
 ### Event Subscription
 

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,40 @@ interface CompletedParamState extends CompletedParam {
     options: SuggestionOption[];
     metadata?: Record<string, unknown>;
 }
+/**
+ * A suggestion the user dismissed with the skip key (→) instead of filling.
+ *
+ * Client-only bookkeeping. A skipped suggestion has no text in the input, so
+ * it can't live in `completedParams` — that array is reconciled against the
+ * input on every keystroke and anything missing from the text is dropped.
+ * Skipped entries are folded into the wire `completed_params` array (with
+ * `text: "skipped"`, no placeholder) only when a request or a submit result is
+ * built. See `withSkippedParams`.
+ *
+ * The array is append-only until `reset()` — a skip is filtered out at
+ * build time when a param of its type ended up filled, not pruned here.
+ * That's deliberate: the filter self-heals if the user later deletes that
+ * param's text (the skip reappears in the payload), where pruning would have
+ * discarded the signal permanently. Consumers reading this array directly
+ * should apply the same filter — `withSkippedParams` is exported for it.
+ */
+interface SkippedParamState {
+    id: string;
+    /** The skipped suggestion's `type` (e.g. "goal"). */
+    type: string;
+    /** The suggestion's display text at skip time. Introspection only — never sent. */
+    suggestionPlaceholder: string;
+}
+/**
+ * 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 +119,10 @@ type Segment = {
     type: "completed";
     value: string;
     param: CompletedParamState;
+} | {
+    type: "identified";
+    value: string;
+    param: IdentifiedParamState;
 };
 type AppearanceMode = "light" | "dark" | "auto";
 interface APIConfigBase {
@@ -105,6 +160,33 @@ 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[];
+    /**
+     * Suggestions the user dismissed with the skip key (→). Held apart from
+     * `completedParams` because they have no text in the input; folded into the
+     * wire `completed_params` array (as `text: "skipped"`) on every request and
+     * on the submit result. Append-only until `reset()` — see
+     * {@link SkippedParamState} for why skips of a since-filled type are
+     * filtered at build time rather than pruned here.
+     */
+    skippedParams: SkippedParamState[];
+    /**
+     * 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 +407,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
@@ -336,6 +426,8 @@ declare class AIAutocomplete {
      * subscription early-returns on subsequent fires.
      */
     private maybeExitReEditOnNoMatch;
+    /** Fire an immediate (undebounced) fetch for the current text + params. */
+    private fetchNow;
     /**
      * 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
@@ -439,7 +531,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 +571,36 @@ 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 };
+/**
+ * Sentinel `text` marking a `completed_params` entry the user skipped (→)
+ * rather than filled. Sent regardless of `maskCompletedText` — it's a fixed
+ * marker, never user-entered content.
+ */
+declare const SKIPPED_PARAM_TEXT = "skipped";
+/**
+ * Folds skipped suggestions into a wire `completed_params` array so the server
+ * learns which parameters the user dismissed and can stop re-suggesting them.
+ *
+ * Skipped entries carry no placeholder: nothing was substituted into
+ * `raw_query`, so a `{{TYPE_N}}` token would point at text that doesn't exist.
+ * They're appended after the real params for the same reason — they have no
+ * position in the query.
+ *
+ * A skip is dropped when a param of the same type ends up filled anyway (the
+ * user skipped `goal`, then typed one): sending both would tell the server the
+ * parameter is simultaneously answered and declined.
+ */
+declare function withSkippedParams(completed: CompletedParam[], skipped: SkippedParamState[]): CompletedParam[];
+
+/**
+ * Builds the `AutocompleteResult` handed to `onSubmit`: the placeholder-
+ * tokenized raw query plus the completed params, with skipped suggestions
+ * folded in (see {@link withSkippedParams}).
+ *
+ * Shared by every submit path — vanilla Enter / submit button, the React Tier 1
+ * component, the Angular Tier 1 component — so they can't drift on what a
+ * result contains.
+ */
+declare function buildSubmitResult(text: string, completedParams: CompletedParamState[], skippedParams?: SkippedParamState[]): AutocompleteResult;
+
+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, SKIPPED_PARAM_TEXT, type Segment, type SkippedParamState, type Store, type Suggestion, type SuggestionOption, type TaskKind, buildAttributionUrl, buildQuery, buildSubmitResult, createStore, cursorIsAtEnd, extractPlainText, getCursorOffset, getFooterHint, plainTextLength, previousGraphemeBoundary, renderEditableContent, setCursorOffset, withSkippedParams };

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,40 @@ interface CompletedParamState extends CompletedParam {
     options: SuggestionOption[];
     metadata?: Record<string, unknown>;
 }
+/**
+ * A suggestion the user dismissed with the skip key (→) instead of filling.
+ *
+ * Client-only bookkeeping. A skipped suggestion has no text in the input, so
+ * it can't live in `completedParams` — that array is reconciled against the
+ * input on every keystroke and anything missing from the text is dropped.
+ * Skipped entries are folded into the wire `completed_params` array (with
+ * `text: "skipped"`, no placeholder) only when a request or a submit result is
+ * built. See `withSkippedParams`.
+ *
+ * The array is append-only until `reset()` — a skip is filtered out at
+ * build time when a param of its type ended up filled, not pruned here.
+ * That's deliberate: the filter self-heals if the user later deletes that
+ * param's text (the skip reappears in the payload), where pruning would have
+ * discarded the signal permanently. Consumers reading this array directly
+ * should apply the same filter — `withSkippedParams` is exported for it.
+ */
+interface SkippedParamState {
+    id: string;
+    /** The skipped suggestion's `type` (e.g. "goal"). */
+    type: string;
+    /** The suggestion's display text at skip time. Introspection only — never sent. */
+    suggestionPlaceholder: string;
+}
+/**
+ * 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 +119,10 @@ type Segment = {
     type: "completed";
     value: string;
     param: CompletedParamState;
+} | {
+    type: "identified";
+    value: string;
+    param: IdentifiedParamState;
 };
 type AppearanceMode = "light" | "dark" | "auto";
 interface APIConfigBase {
@@ -105,6 +160,33 @@ 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[];
+    /**
+     * Suggestions the user dismissed with the skip key (→). Held apart from
+     * `completedParams` because they have no text in the input; folded into the
+     * wire `completed_params` array (as `text: "skipped"`) on every request and
+     * on the submit result. Append-only until `reset()` — see
+     * {@link SkippedParamState} for why skips of a since-filled type are
+     * filtered at build time rather than pruned here.
+     */
+    skippedParams: SkippedParamState[];
+    /**
+     * 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 +407,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
@@ -336,6 +426,8 @@ declare class AIAutocomplete {
      * subscription early-returns on subsequent fires.
      */
     private maybeExitReEditOnNoMatch;
+    /** Fire an immediate (undebounced) fetch for the current text + params. */
+    private fetchNow;
     /**
      * 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
@@ -439,7 +531,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 +571,36 @@ 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 };
+/**
+ * Sentinel `text` marking a `completed_params` entry the user skipped (→)
+ * rather than filled. Sent regardless of `maskCompletedText` — it's a fixed
+ * marker, never user-entered content.
+ */
+declare const SKIPPED_PARAM_TEXT = "skipped";
+/**
+ * Folds skipped suggestions into a wire `completed_params` array so the server
+ * learns which parameters the user dismissed and can stop re-suggesting them.
+ *
+ * Skipped entries carry no placeholder: nothing was substituted into
+ * `raw_query`, so a `{{TYPE_N}}` token would point at text that doesn't exist.
+ * They're appended after the real params for the same reason — they have no
+ * position in the query.
+ *
+ * A skip is dropped when a param of the same type ends up filled anyway (the
+ * user skipped `goal`, then typed one): sending both would tell the server the
+ * parameter is simultaneously answered and declined.
+ */
+declare function withSkippedParams(completed: CompletedParam[], skipped: SkippedParamState[]): CompletedParam[];
+
+/**
+ * Builds the `AutocompleteResult` handed to `onSubmit`: the placeholder-
+ * tokenized raw query plus the completed params, with skipped suggestions
+ * folded in (see {@link withSkippedParams}).
+ *
+ * Shared by every submit path — vanilla Enter / submit button, the React Tier 1
+ * component, the Angular Tier 1 component — so they can't drift on what a
+ * result contains.
+ */
+declare function buildSubmitResult(text: string, completedParams: CompletedParamState[], skippedParams?: SkippedParamState[]): AutocompleteResult;
+
+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, SKIPPED_PARAM_TEXT, type Segment, type SkippedParamState, type Store, type Suggestion, type SuggestionOption, type TaskKind, buildAttributionUrl, buildQuery, buildSubmitResult, createStore, cursorIsAtEnd, extractPlainText, getCursorOffset, getFooterHint, plainTextLength, previousGraphemeBoundary, renderEditableContent, setCursorOffset, withSkippedParams };