@magicx-eng/ai-autocomplete-vanilla 0.1.1 → 0.1.3

package/index.d.ts

@@ -43,7 +43,7 @@ interface APIConfigBase {
 }
 interface APIKeyConfig extends APIConfigBase {
     type?: "apiKey";
-    apiKey: string;
+    apiKey?: string;
     authScheme?: "Bearer" | "Basic";
 }
 interface AccessTokenConfig extends APIConfigBase {
@@ -64,14 +64,6 @@ interface AutocompleteResult {
     completed_params: CompletedParam[];
 }
 
-type Listener<S> = (next: S, prev: S) => void;
-interface Store<S> {
-    get: () => S;
-    set: (patch: Partial<S> | ((s: S) => Partial<S>)) => void;
-    subscribe: (listener: Listener<S>) => () => void;
-}
-declare function createStore<S>(initial: S): Store<S>;
-
 /** Internal state managed by the store. */
 interface CoreState {
     text: string;
@@ -92,60 +84,67 @@ interface CoreState {
     pillTapped: boolean;
     skipNextFetch: boolean;
     lastRawQuery: string;
+    isFocused: boolean;
 }
+/**
+ * Render mode:
+ * - "full" (default) — renders input + dropdown + pills. Tier 1.
+ * - "dropdown" — renders only the dropdown with pills. Consumer owns the input. Tier 2.
+ * - "headless" — no DOM. State + controllers only. For framework wrappers.
+ */
+type RenderMode = "full" | "dropdown" | "headless";
 /** Options passed to the AIAutocomplete constructor. */
 interface CoreOptions {
     apiConfig?: APIConfig;
     optionOverrides?: OptionOverrides;
     maskCompletedText?: boolean;
-    placeholder?: string;
     columns?: number;
-    typewriterEffect?: boolean;
-    pillPlacement?: "inline" | "dropdown";
+    /** Where pills render in "full" mode. Ignored in "dropdown" mode (always in dropdown). */
+    pillPlacement?: "inline" | "dropdown" | "hidden";
     mode?: AppearanceMode;
     optionsPosition?: "above" | "below";
     animations?: boolean;
+    /** When the dropdown appears. "auto" = shows when options available. "manual" = only on pill tap. "hidden" = never. Default: "auto". */
+    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;
+    /** Render mode. Default: "full". */
+    renderMode?: RenderMode;
+    /** Focus the input on mount (Tier 1 / "full" render mode only). Default: true. */
+    autoFocus?: boolean;
     onSubmit?: (result: AutocompleteResult) => void;
     onError?: (error: Error) => void;
     onChange?: (text: string) => void;
     onParamsChange?: (params: CompletedParamState[]) => void;
     onStateChange?: (state: CoreState) => void;
+    /** Called when the input gains focus (or `setFocused(true)` is called). */
+    onFocus?: () => void;
+    /** Called when the input loses focus (or `setFocused(false)` is called). */
+    onBlur?: () => void;
     value?: string;
     completedParams?: CompletedParamState[];
 }
 
-interface KeyboardContext {
-    columns: number;
-    listboxId: string;
-    onSubmit?: (result: AutocompleteResult) => void;
-    selectOption: (option: SuggestionOption) => void;
-}
-declare class KeyboardController {
-    private store;
-    private ctx;
-    constructor(store: Store<CoreState>, ctx: KeyboardContext);
-    handleKeyDown(e: KeyboardEvent): void;
-    private getTappableIndices;
-    private clickOrSelect;
-    /** Delegate to pills controller logic inline (avoids circular dep) */
-    private pillsSetActivePill;
-}
-
 declare class AIAutocomplete {
     private store;
-    private listboxId;
+    private _listboxId;
     private opts;
     private fetchController;
-    keyboardController: KeyboardController;
+    private keyboardController;
     private pillsController;
     private modeController;
     private container;
     private unsubscribers;
     private derivedInProgress;
+    private renderMode;
     private domRefs;
+    private dropdownRefs;
     private newParamTimer;
+    private suggestionRemovalTimer;
+    private externalListeners;
     constructor(container: HTMLElement, opts?: CoreOptions);
     focus(): void;
+    blur(): void;
     reset(): void;
     destroy(): void;
     setMode(mode: AppearanceMode): void;
@@ -154,15 +153,35 @@ declare class AIAutocomplete {
     setActivePill(index: number): void;
     removeLastParam(): void;
     clearNewParamId(): 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(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;
-    private selectOption;
+    selectOption(option: SuggestionOption): void;
     private recomputeDerived;
     private setupContainer;
-    private buildAndRender;
+    private buildAndRenderFull;
+    private buildAndRenderDropdown;
+    /** Batched render subscriber — coalesces multiple store.set calls into one DOM update. */
+    private subscribeBatchedRender;
+    /** Auto-clear newParamId after shimmer animation. */
+    private subscribeNewParamTimer;
     private handleChange;
 }
 
-export { AIAutocomplete, type APIConfig, type APIKeyConfig, type AccessTokenConfig, type AccessTokenResult, type AppearanceMode, type AutocompleteResult, type CompletedParam, type CompletedParamState, type CoreOptions, type CoreState, type Segment, type Store, type Suggestion, type SuggestionOption, createStore };
+type Listener<S> = (next: S, prev: S) => void;
+interface Store<S> {
+    get: () => S;
+    set: (patch: Partial<S> | ((s: S) => Partial<S>)) => void;
+    subscribe: (listener: Listener<S>) => () => void;
+}
+declare function createStore<S>(initial: S): Store<S>;
+
+export { AIAutocomplete, type APIConfig, type APIKeyConfig, type AccessTokenConfig, type AccessTokenResult, type AppearanceMode, type AutocompleteResult, type CompletedParam, type CompletedParamState, type CoreOptions, type CoreState, type RenderMode, type Segment, type Store, type Suggestion, type SuggestionOption, createStore };