@magicx-eng/ai-autocomplete-react 0.1.25 → 0.1.27

package/README.md

@@ -13,7 +13,7 @@ A React/TypeScript SDK that provides a guided AI-powered autocomplete experience
 - **Client-side filtering** — instant substring filtering on every keystroke
 - **Option overrides** — inject or dynamically generate client-side options per suggestion type
 - **Controlled & uncontrolled** — works out of the box or integrates with external state
-- **Ref forwarding** — imperative `focus()`, `reset()`, and `setMode()` via ref
+- **Ref forwarding** — imperative `focus()`, `blur()`, `reset()`, and `setMode()` via ref
 - **Accessible** — ARIA combobox pattern with `role="listbox"`, `aria-activedescendant`
 - **Animations** — option selection streak animation, text shimmer on newly added params
 - **Lightweight** — styles auto-injected at runtime
@@ -58,7 +58,6 @@ function App() {
         console.log(result.raw_query);        // "Create a {{TASK_1}}"
         console.log(result.completed_params); // [{ placeholder: "{{TASK_1}}", type: "task", ... }]
       }}
-      placeholder="Create a"
       className="my-autocomplete"
     />
   );
@@ -88,12 +87,26 @@ import { AIAutocomplete, type AIAutocompleteHandle } from "@magicx-eng/ai-autoco
 
 const ref = useRef<AIAutocompleteHandle>(null);
 // ref.current?.focus()
+// ref.current?.blur()
 // ref.current?.reset()
 // ref.current?.setMode("dark")
 
 <AIAutocomplete ref={ref} onSubmit={handleSubmit} />
 ```
 
+### Focus Control
+
+The component auto-focuses the input on mount. To opt out, pass `autoFocus={false}`. Listen to focus changes with `onFocus` / `onBlur`:
+
+```tsx
+<AIAutocomplete
+  autoFocus={false}
+  onFocus={() => setIsActive(true)}
+  onBlur={() => setIsActive(false)}
+  onSubmit={handleSubmit}
+/>
+```
+
 ---
 
 ## Tier 2: Headless
@@ -140,7 +153,6 @@ function App() {
 | `apiConfig?` | `APIConfig` | — | Runtime API configuration (see below). |
 | `optionOverrides?` | `Record<string, (query: string) => SuggestionOption[]>` | — | Override options per suggestion type. |
 | `maskCompletedText?` | `boolean` | `false` | When `true`, omits completed params' literal text from API requests (for masking PII/sensitive values from the server). |
-| `placeholder?` | `string` | — | Fallback placeholder when the server doesn't return one. |
 | `className?` | `string` | — | CSS class applied to the container. |
 | `columns?` | `number` | `2` | Number of columns in the dropdown grid. |
 | `pillPlacement?` | `"inline" \| "dropdown" \| "hidden"` | `"inline"` | Where to render unfilled pills. `"hidden"` hides pills entirely. |
@@ -148,11 +160,15 @@ function App() {
 | `optionsPosition?` | `"above" \| "below"` | `"below"` | Where the dropdown opens relative to the input. |
 | `animations?` | `boolean` | `true` | Enable/disable all SDK animations (streak + shimmer). |
 | `dropdownTrigger?` | `"auto" \| "manual" \| "hidden"` | `"auto"` | When the dropdown appears. `"auto"` = when options available. `"manual"` = only on pill tap, closes after selection. `"hidden"` = never shows. |
+| `closeDropdownOnBlur?` | `boolean` | `true` | When `true`, the dropdown closes if the input loses focus. Set to `false` to keep it open whenever options are available, regardless of focus. |
+| `autoFocus?` | `boolean` | `true` | Focus the input on mount. Set to `false` to leave focus to the consumer. |
+| `onFocus?` | `() => void` | — | Called when the input gains focus. |
+| `onBlur?` | `() => void` | — | Called when the input loses focus. |
 | `value?` | `string` | — | Controlled text value. |
 | `completedParams?` | `CompletedParamState[]` | — | Controlled completed params. |
 | `onChange?` | `(value: string) => void` | — | Called when text changes (controlled mode). |
 | `onParamsChange?` | `(params: CompletedParamState[]) => void` | — | Called when params change (controlled mode). |
-| `ref?` | `Ref<AIAutocompleteHandle>` | — | Imperative handle with `focus()`, `reset()`, and `setMode()`. |
+| `ref?` | `Ref<AIAutocompleteHandle>` | — | Imperative handle with `focus()`, `blur()`, `reset()`, and `setMode()`. |
 
 ### `APIConfig`
 
@@ -202,7 +218,7 @@ The SDK handles token refresh transparently: 401 → `getAccessToken` → retry
 
 ### `useAIAutocomplete(options)`
 
-The headless hook for Tier 2. Accepts the same props as `<AIAutocomplete />` except for the rendering-only ones: `className`, `ref`, `pillPlacement`, `mode`, `optionsPosition`, and `animations` (those belong to the wrapping component).
+The headless hook for Tier 2. Accepts the same props as `<AIAutocomplete />` except for the rendering-only ones: `className`, `ref`, `pillPlacement`, `mode`, `optionsPosition`, `animations`, and `autoFocus` (those belong to the wrapping component — the hook doesn't own the input element). `onFocus` and `onBlur` are forwarded and fire whenever the consumer-owned textarea's focus changes (they're driven by `inputProps.onFocus` / `inputProps.onBlur`).
 
 #### Return Value
 
@@ -282,8 +298,13 @@ Override on the container (via `className`). All defaults use `:where()` (zero s
 | `--aia-option-font-size` | `19px` | `19px` | Option font size |
 | `--aia-written-text-color` | `#000000` | `#ffffff` | Input text |
 | `--aia-written-text-font-size` | `19px` | `19px` | Input text font size |
+| `--aia-caret-color` | `--aia-written-text-color` | `--aia-written-text-color` | Textarea caret color. Override independently of input text color. |
+| `--aia-submit-bg` | `#000000` | `#ffffff` | Submit button background |
+| `--aia-submit-color` | `#ffffff` | `#000000` | Submit button icon color |
 | `--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. |
 
 Legacy `--aia-color-*` variables are still supported as fallbacks.
 
@@ -298,6 +319,29 @@ Legacy `--aia-color-*` variables are still supported as fallbacks.
 }
 ```
 
+### Selector Hooks
+
+For styling beyond the CSS variables, target these stable `data-aia-*` attributes (CSS-module class hashes are not part of the public API):
+
+| Attribute | Element |
+|---|---|
+| `[data-aia-editor]` | Editor area wrapping the textarea + overlay |
+| `[data-aia-textarea]` | The `<textarea>` |
+| `[data-aia-submit]` | Submit button |
+| `[data-aia-pill]` | Each unfilled-suggestion pill |
+| `[data-aia-pillbar]` | Pill bar container inside the dropdown |
+| `[data-aia-option]` | Each suggestion option |
+| `[data-aia-dropdown]` | The dropdown root (listbox) |
+
+```css
+/* Solid (non-glass) dropdown */
+.my-autocomplete [data-aia-dropdown] {
+  background: #fff;
+  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.1);
+  backdrop-filter: none;
+}
+```
+
 ---
 
 ## Option Overrides

package/dist/index.d.mts

@@ -42,6 +42,7 @@ type Segment = {
 type AppearanceMode = "light" | "dark" | "auto";
 interface AIAutocompleteHandle {
     focus: () => void;
+    blur: () => void;
     reset: () => void;
     setMode: (mode: AppearanceMode) => void;
 }
@@ -72,7 +73,6 @@ interface AIAutocompleteProps {
     onError?: (error: Error) => void;
     optionOverrides?: OptionOverrides;
     maskCompletedText?: boolean;
-    placeholder?: string;
     className?: string;
     apiConfig?: APIConfig;
     columns?: number;
@@ -86,6 +86,14 @@ interface AIAutocompleteProps {
     animations?: boolean;
     /** When the dropdown appears. "auto" (default) = shows when options available. "manual" = only on pill tap, closes after selection. "hidden" = never shows. */
     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;
+    /** Focus the input on mount. Default: true. */
+    autoFocus?: boolean;
+    /** Called when the input gains focus. */
+    onFocus?: () => void;
+    /** Called when the input loses focus. */
+    onBlur?: () => void;
     value?: string;
     completedParams?: CompletedParamState[];
     onChange?: (value: string) => void;
@@ -101,11 +109,16 @@ interface UseAIAutocompleteOptions {
     onError?: (error: Error) => void;
     optionOverrides?: OptionOverrides;
     maskCompletedText?: boolean;
-    placeholder?: string;
     apiConfig?: APIConfig;
     columns?: number;
     /** When the dropdown appears. 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. */
+    closeDropdownOnBlur?: boolean;
+    /** Called when the input gains focus. */
+    onFocus?: () => void;
+    /** Called when the input loses focus. */
+    onBlur?: () => void;
     value?: string;
     completedParams?: CompletedParamState[];
     onChange?: (value: string) => void;
@@ -130,6 +143,8 @@ interface UseAIAutocompleteReturn {
         placeholder: string | undefined;
         onChange: (e: ChangeEvent<HTMLTextAreaElement>) => void;
         onKeyDown: (e: KeyboardEvent<HTMLTextAreaElement>) => void;
+        onFocus: () => void;
+        onBlur: () => void;
         role: "combobox";
         "aria-expanded": boolean;
         "aria-activedescendant": string | undefined;
@@ -158,6 +173,6 @@ declare const AIAutocomplete: react.ForwardRefExoticComponent<AIAutocompleteProp
 
 declare function AIAutocompleteDropdown({ suggestions, activeIndex, onSelect, onHighlight, isOpen, id, className, pills, onPillClick, showPills, }: AIAutocompleteDropdownProps): react_jsx_runtime.JSX.Element;
 
-declare function useAIAutocomplete({ onSubmit, onError, optionOverrides, maskCompletedText, placeholder: customPlaceholder, apiConfig, columns, dropdownTrigger, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
+declare function useAIAutocomplete({ onSubmit, onError, optionOverrides, maskCompletedText, apiConfig, columns, dropdownTrigger, closeDropdownOnBlur, onFocus, onBlur, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
 
 export { AIAutocomplete, AIAutocompleteDropdown, type AIAutocompleteDropdownProps, type AIAutocompleteHandle, type AIAutocompleteProps, type APIConfig, type APIKeyConfig, type AccessTokenConfig, type AccessTokenResult, type AppearanceMode, type AutocompleteResult, type CompletedParam, type CompletedParamState, type OptionOverrides, type Segment, type Suggestion, type SuggestionOption, type TaskKind, type UseAIAutocompleteOptions, type UseAIAutocompleteReturn, useAIAutocomplete };

package/dist/index.d.ts

@@ -42,6 +42,7 @@ type Segment = {
 type AppearanceMode = "light" | "dark" | "auto";
 interface AIAutocompleteHandle {
     focus: () => void;
+    blur: () => void;
     reset: () => void;
     setMode: (mode: AppearanceMode) => void;
 }
@@ -72,7 +73,6 @@ interface AIAutocompleteProps {
     onError?: (error: Error) => void;
     optionOverrides?: OptionOverrides;
     maskCompletedText?: boolean;
-    placeholder?: string;
     className?: string;
     apiConfig?: APIConfig;
     columns?: number;
@@ -86,6 +86,14 @@ interface AIAutocompleteProps {
     animations?: boolean;
     /** When the dropdown appears. "auto" (default) = shows when options available. "manual" = only on pill tap, closes after selection. "hidden" = never shows. */
     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;
+    /** Focus the input on mount. Default: true. */
+    autoFocus?: boolean;
+    /** Called when the input gains focus. */
+    onFocus?: () => void;
+    /** Called when the input loses focus. */
+    onBlur?: () => void;
     value?: string;
     completedParams?: CompletedParamState[];
     onChange?: (value: string) => void;
@@ -101,11 +109,16 @@ interface UseAIAutocompleteOptions {
     onError?: (error: Error) => void;
     optionOverrides?: OptionOverrides;
     maskCompletedText?: boolean;
-    placeholder?: string;
     apiConfig?: APIConfig;
     columns?: number;
     /** When the dropdown appears. 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. */
+    closeDropdownOnBlur?: boolean;
+    /** Called when the input gains focus. */
+    onFocus?: () => void;
+    /** Called when the input loses focus. */
+    onBlur?: () => void;
     value?: string;
     completedParams?: CompletedParamState[];
     onChange?: (value: string) => void;
@@ -130,6 +143,8 @@ interface UseAIAutocompleteReturn {
         placeholder: string | undefined;
         onChange: (e: ChangeEvent<HTMLTextAreaElement>) => void;
         onKeyDown: (e: KeyboardEvent<HTMLTextAreaElement>) => void;
+        onFocus: () => void;
+        onBlur: () => void;
         role: "combobox";
         "aria-expanded": boolean;
         "aria-activedescendant": string | undefined;
@@ -158,6 +173,6 @@ declare const AIAutocomplete: react.ForwardRefExoticComponent<AIAutocompleteProp
 
 declare function AIAutocompleteDropdown({ suggestions, activeIndex, onSelect, onHighlight, isOpen, id, className, pills, onPillClick, showPills, }: AIAutocompleteDropdownProps): react_jsx_runtime.JSX.Element;
 
-declare function useAIAutocomplete({ onSubmit, onError, optionOverrides, maskCompletedText, placeholder: customPlaceholder, apiConfig, columns, dropdownTrigger, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
+declare function useAIAutocomplete({ onSubmit, onError, optionOverrides, maskCompletedText, apiConfig, columns, dropdownTrigger, closeDropdownOnBlur, onFocus, onBlur, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
 
 export { AIAutocomplete, AIAutocompleteDropdown, type AIAutocompleteDropdownProps, type AIAutocompleteHandle, type AIAutocompleteProps, type APIConfig, type APIKeyConfig, type AccessTokenConfig, type AccessTokenResult, type AppearanceMode, type AutocompleteResult, type CompletedParam, type CompletedParamState, type OptionOverrides, type Segment, type Suggestion, type SuggestionOption, type TaskKind, type UseAIAutocompleteOptions, type UseAIAutocompleteReturn, useAIAutocomplete };