@magicx-eng/ai-autocomplete-vanilla 0.2.1 → 0.4.0

package/dist/index.d.mts

@@ -136,6 +136,12 @@ interface CoreInputState {
      * Set by selectOption / ReEditManager.selectOption, cleared by a timer.
      */
     inSelectionAnimation: boolean;
+    /**
+     * True once the user has pressed Tab to highlight a dropdown option. Drives
+     * the dropdown footer hint: "tab to select" before the first Tab, then
+     * "→ to skip" afterwards. Sticky until `reset()` clears it.
+     */
+    hasTabbedToHighlight: boolean;
 }
 /**
  * Derived fields recomputed from {@link CoreInputState} + {@link CoreOptions}.
@@ -148,6 +154,18 @@ interface CoreDerivedState {
     filteredOptions: SuggestionOption[];
     placeholderText: string;
     isDropdownOpen: boolean;
+    /**
+     * Whether the active (leading) pill should render in its `selected` state
+     * (full opacity) rather than the de-emphasized `first` tier. True when the
+     * dropdown is open AND a tappable option is highlighted (`activeDropdownIndex
+     * >= 0 && is_tappable`). This rule is uniform across all trigger modes:
+     * - `auto`: becomes true on keyboard nav / hover / pill tap.
+     * - `manual`: becomes true on pill tap — `setActivePill` opens the dropdown
+     *   and auto-highlights the first tappable option; false if the pill has no
+     *   tappable option.
+     * - `hidden`: always false (the dropdown never opens).
+     */
+    isActivePillSelected: boolean;
 }
 /**
  * Full state shape (inputs + derived) exposed to consumers via `getState()`
@@ -415,6 +433,24 @@ interface BuildQueryResult {
  */
 declare function buildQuery(text: string, completedParams: CompletedParamState[]): BuildQueryResult;
 
+/**
+ * The dropdown footer's keyboard hint has four states, in priority order:
+ * 1. an option is highlighted → "enter to proceed" (Enter commits it);
+ * 2. otherwise, the input is empty → "tab to skip" — with nothing typed there's
+ *    nothing to select, so Tab skips the active pill. This holds regardless of
+ *    whether the user has tabbed to highlight yet;
+ * 3. otherwise, the user has tabbed to highlight at some point → "→ to skip"
+ *    (the right arrow skips the active pill);
+ * 4. otherwise (fresh, with text) → "tab to select".
+ *
+ * Pure computation — no DOM access. Shared by the vanilla renderer and the
+ * React / Angular footer components so the wording can't drift between them.
+ */
+declare function getFooterHint(hasTabbedToHighlight: boolean, optionHighlighted: boolean, isInputEmpty: boolean): {
+    key: string;
+    hint: string;
+};
+
 declare class ModeController {
     private container;
     private mode;
@@ -429,4 +465,4 @@ declare class ModeController {
     private detachListener;
 }
 
-export { AIAutocomplete, type APIConfig, type APIKeyConfig, 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, buildQuery, createStore, cursorIsAtEnd, extractPlainText, getCursorOffset, plainTextLength, previousGraphemeBoundary, renderEditableContent, setCursorOffset };
+export { AIAutocomplete, type APIConfig, type APIKeyConfig, 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, buildQuery, createStore, cursorIsAtEnd, extractPlainText, getCursorOffset, getFooterHint, plainTextLength, previousGraphemeBoundary, renderEditableContent, setCursorOffset };

package/dist/index.d.ts

@@ -136,6 +136,12 @@ interface CoreInputState {
      * Set by selectOption / ReEditManager.selectOption, cleared by a timer.
      */
     inSelectionAnimation: boolean;
+    /**
+     * True once the user has pressed Tab to highlight a dropdown option. Drives
+     * the dropdown footer hint: "tab to select" before the first Tab, then
+     * "→ to skip" afterwards. Sticky until `reset()` clears it.
+     */
+    hasTabbedToHighlight: boolean;
 }
 /**
  * Derived fields recomputed from {@link CoreInputState} + {@link CoreOptions}.
@@ -148,6 +154,18 @@ interface CoreDerivedState {
     filteredOptions: SuggestionOption[];
     placeholderText: string;
     isDropdownOpen: boolean;
+    /**
+     * Whether the active (leading) pill should render in its `selected` state
+     * (full opacity) rather than the de-emphasized `first` tier. True when the
+     * dropdown is open AND a tappable option is highlighted (`activeDropdownIndex
+     * >= 0 && is_tappable`). This rule is uniform across all trigger modes:
+     * - `auto`: becomes true on keyboard nav / hover / pill tap.
+     * - `manual`: becomes true on pill tap — `setActivePill` opens the dropdown
+     *   and auto-highlights the first tappable option; false if the pill has no
+     *   tappable option.
+     * - `hidden`: always false (the dropdown never opens).
+     */
+    isActivePillSelected: boolean;
 }
 /**
  * Full state shape (inputs + derived) exposed to consumers via `getState()`
@@ -415,6 +433,24 @@ interface BuildQueryResult {
  */
 declare function buildQuery(text: string, completedParams: CompletedParamState[]): BuildQueryResult;
 
+/**
+ * The dropdown footer's keyboard hint has four states, in priority order:
+ * 1. an option is highlighted → "enter to proceed" (Enter commits it);
+ * 2. otherwise, the input is empty → "tab to skip" — with nothing typed there's
+ *    nothing to select, so Tab skips the active pill. This holds regardless of
+ *    whether the user has tabbed to highlight yet;
+ * 3. otherwise, the user has tabbed to highlight at some point → "→ to skip"
+ *    (the right arrow skips the active pill);
+ * 4. otherwise (fresh, with text) → "tab to select".
+ *
+ * Pure computation — no DOM access. Shared by the vanilla renderer and the
+ * React / Angular footer components so the wording can't drift between them.
+ */
+declare function getFooterHint(hasTabbedToHighlight: boolean, optionHighlighted: boolean, isInputEmpty: boolean): {
+    key: string;
+    hint: string;
+};
+
 declare class ModeController {
     private container;
     private mode;
@@ -429,4 +465,4 @@ declare class ModeController {
     private detachListener;
 }
 
-export { AIAutocomplete, type APIConfig, type APIKeyConfig, 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, buildQuery, createStore, cursorIsAtEnd, extractPlainText, getCursorOffset, plainTextLength, previousGraphemeBoundary, renderEditableContent, setCursorOffset };
+export { AIAutocomplete, type APIConfig, type APIKeyConfig, 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, buildQuery, createStore, cursorIsAtEnd, extractPlainText, getCursorOffset, getFooterHint, plainTextLength, previousGraphemeBoundary, renderEditableContent, setCursorOffset };