@magicx-eng/ai-autocomplete-react 0.1.16 → 0.1.18

package/README.md

@@ -1,19 +1,22 @@
 # @magicx-eng/ai-autocomplete-react
 
-A React/TypeScript SDK that provides a guided AI-powered autocomplete experience with pill-based input and dropdown suggestions.
+A React/TypeScript SDK that provides a guided AI-powered autocomplete experience with pill-based input and dropdown suggestions. Powered by `@magicx-eng/ai-autocomplete-vanilla` under the hood.
 
 ## Features
 
 - **Two tiers of integration** — use the full `<AIAutocomplete />` component or go headless with `useAIAutocomplete()` + `<AIAutocompleteDropdown />`
 - **Pill-based input** — inline pills for unfilled parameters, bold text for completed ones
+- **Pill placement** — render pills inline in the input or inside the dropdown
+- **Light/dark mode** — built-in themes with `prefers-color-scheme` support, fully overridable via CSS variables
+- **Access token auth** — short-lived tokens with automatic refresh, single-flight deduplication, and 401 retry
 - **Keyboard navigation** — arrow keys, enter to submit, tab to autocomplete
 - **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()` and `reset()` via ref
+- **Ref forwarding** — imperative `focus()`, `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, typewriter reveal effect
-- **Lightweight** — zero dependencies beyond React, styles auto-injected at runtime
+- **Animations** — option selection streak animation, text shimmer on newly added params
+- **Lightweight** — styles auto-injected at runtime
 - **TypeScript first** — full type definitions shipped with the package
 
 ## Installation
@@ -30,9 +33,16 @@ React 17 or later:
 pnpm add react react-dom
 ```
 
-## Usage
+## Two Tiers
 
-### Tier 1: Full Component
+| Tier | What you get | What you own | Use when |
+|---|---|---|---|
+| **Tier 1: Full** | `<AIAutocomplete />` — input, dropdown, pills, state | Nothing — drop in and go | You want a complete widget with zero setup |
+| **Tier 2: Headless** | `useAIAutocomplete()` — state, actions, spread props | The input and layout JSX | You need a custom input or want full control over rendering |
+
+---
+
+## Tier 1: Full Component
 
 Drop-in component that owns the input, pills, dropdown, and all state:
 
@@ -55,7 +65,38 @@ function App() {
 }
 ```
 
-### Tier 2: Headless
+### Controlled Mode
+
+```tsx
+const [text, setText] = useState("");
+const [params, setParams] = useState([]);
+
+<AIAutocomplete
+  value={text}
+  onChange={setText}
+  completedParams={params}
+  onParamsChange={setParams}
+  onSubmit={(result) => console.log(result)}
+/>
+```
+
+### Imperative Handle
+
+```tsx
+import { useRef } from "react";
+import { AIAutocomplete, type AIAutocompleteHandle } from "@magicx-eng/ai-autocomplete-react";
+
+const ref = useRef<AIAutocompleteHandle>(null);
+// ref.current?.focus()
+// ref.current?.reset()
+// ref.current?.setMode("dark")
+
+<AIAutocomplete ref={ref} onSubmit={handleSubmit} />
+```
+
+---
+
+## Tier 2: Headless
 
 Use the hook and dropdown separately for full control over the input and rendering:
 
@@ -86,44 +127,12 @@ function App() {
 }
 ```
 
-### Controlled Mode
-
-Pass `value` and `onChange` to control the text externally:
-
-```tsx
-const [text, setText] = useState("");
-const [params, setParams] = useState([]);
-
-<AIAutocomplete
-  value={text}
-  onChange={setText}
-  completedParams={params}
-  onParamsChange={setParams}
-  onSubmit={(result) => console.log(result)}
-/>
-```
-
-### Imperative Handle
-
-Use a ref to focus or reset programmatically:
-
-```tsx
-import { useRef } from "react";
-import { AIAutocomplete, type AIAutocompleteHandle } from "@magicx-eng/ai-autocomplete-react";
-
-const ref = useRef<AIAutocompleteHandle>(null);
-// ref.current?.focus()
-// ref.current?.reset()
-
-<AIAutocomplete ref={ref} onSubmit={handleSubmit} />
-```
+---
 
 ## API Reference
 
 ### `<AIAutocomplete />`
 
-The full component. Owns the input, pills, dropdown, and keyboard navigation.
-
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `onSubmit` | `(result: AutocompleteResult) => void` | **required** | Called on Enter or submit button. |
@@ -133,38 +142,66 @@ The full component. Owns the input, pills, dropdown, and keyboard navigation.
 | `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. |
-| `typewriterEffect?` | `boolean` | `true` | When `true`, reveal selected option text letter by letter with a shimmer. When `false`, show all at once with a shimmer sweep. |
+| `pillPlacement?` | `"inline" \| "dropdown" \| "hidden"` | `"inline"` | Where to render unfilled pills. `"hidden"` hides pills entirely. |
+| `mode?` | `"light" \| "dark" \| "auto"` | `"auto"` | Color mode. `"auto"` follows `prefers-color-scheme`. |
+| `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. |
 | `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()` and `reset()`. |
+| `ref?` | `Ref<AIAutocompleteHandle>` | — | Imperative handle with `focus()`, `reset()`, and `setMode()`. |
 
 ### `APIConfig`
 
+A discriminated union: `APIKeyConfig | AccessTokenConfig`.
+
+#### API Key Mode (default)
+
+```ts
+{ apiKey: "your_api_key", authScheme: "Bearer", endpoint: "/ac/suggest" }
+```
+
 | Field | Type | Description |
 |---|---|---|
-| `endpoint?` | `string` | Full URL for the suggest endpoint (e.g. `"https://api.example.com/ac/suggest"`). Default: `"/ac/suggest"`. |
-| `apiKey?` | `string` | API key for Authorization header. A dev warning is logged if not provided. |
+| `type?` | `"apiKey"` | Optional discriminator. Default when omitted. |
+| `apiKey?` | `string` | API key for Authorization header. |
 | `authScheme?` | `"Bearer" \| "Basic"` | Auth header scheme. Default: `"Bearer"`. |
-| `appIdentifier?` | `string` | Value for the `X-App-Identifier` header. Only sent when provided. |
+| `endpoint?` | `string` | Full URL for the suggest endpoint. Default: `"/ac/suggest"`. |
+| `appIdentifier?` | `string` | Value for the `X-App-Identifier` header. |
 | `headers?` | `Record<string, string>` | Additional headers merged into every request. |
 
-### `AutocompleteResult`
+#### Access Token Mode
 
-The object passed to `onSubmit`:
+```tsx
+<AIAutocomplete
+  apiConfig={{
+    type: "accessToken",
+    getAccessToken: async () => {
+      const res = await fetch("/api/ac-token");
+      const { access_token, expires_at } = await res.json();
+      return { accessToken: access_token, expiresAt: expires_at };
+    },
+  }}
+  onSubmit={handleSubmit}
+/>
+```
 
 | Field | Type | Description |
 |---|---|---|
-| `query` | `string` | Plain text as the user sees it (e.g. `"Create a email"`). |
-| `raw_query` | `string` | Text with placeholder tokens (e.g. `"Create a {{TASK_1}}"`). |
-| `completed_params` | `CompletedParam[]` | Array of filled parameter values. |
+| `type` | `"accessToken"` | **Required** discriminator. |
+| `getAccessToken` | `() => Promise<AccessTokenResult>` | **Required.** Called when the SDK needs a token. |
+| `accessToken?` | `string` | Initial token. Avoids one round-trip on mount. |
+| `endpoint?` | `string` | Suggest endpoint URL. Default: `"/ac/suggest"`. |
+| `appIdentifier?` | `string` | Value for the `X-App-Identifier` header. |
+| `headers?` | `Record<string, string>` | Additional headers merged into every request. |
 
-### `useAIAutocomplete(options)`
+The SDK handles token refresh transparently: 401 → `getAccessToken` → retry (once). Concurrent 401s share a single refresh. Tokens refresh proactively 30s before `expiresAt`.
 
-The core hook. Manages state, API calls, filtering, pills, and keyboard navigation.
+### `useAIAutocomplete(options)`
 
-Accepts the same props as `<AIAutocomplete />` (except `className` and `ref`), with `onSubmit` receiving an `AutocompleteResult`.
+The headless hook for Tier 2. Accepts the same props as `<AIAutocomplete />` (except `className` and `ref`).
 
 #### Return Value
 
@@ -172,122 +209,113 @@ Accepts the same props as `<AIAutocomplete />` (except `className` and `ref`), w
 
 | Field | Type | Description |
 |---|---|---|
-| `completedParams` | `CompletedParamState[]` | All parameters the user has filled so far. Each entry contains the selected option's `text`, `kind`, `type`, and `metadata`, plus client-side fields like `id` (stable UUID), `options` (cached for re-editing), `suggestionType`, and `suggestionPlaceholder`. Use these to render completed values (e.g. bold text) and to build the final query on submit. |
-| `suggestionPills` | `Suggestion[]` | Unfilled suggestions that should be rendered as pills (inline chips). Excludes placeholder-type suggestions. The first item is the "active" pill whose options appear in the dropdown. Tapping a pill reorders it to the front via `setActivePill`. |
-| `segments` | `Segment[]` | The input text split into typed segments for overlay rendering. Each segment is either `{ type: "text", value: string }` for plain text, or `{ type: "completed", value: string, param: CompletedParamState }` for a completed parameter. Use these to render a styled overlay on top of the textarea — e.g. showing completed params in bold while keeping the textarea's actual text transparent. |
-| `newParamId` | `string \| null` | The `id` of the most recently added completed param, or `null`. Use this to apply shimmer animations to the newly added text segment. Cleared automatically after the animation completes. |
-| `suggestions` | `Suggestion[]` | All suggestions from the server, including placeholder-type suggestions. Most consumers should use `suggestionPills` and `dropdownProps` instead — this is exposed for advanced use cases like custom pill or dropdown rendering. |
-| `activeIndex` | `number` | Index of the currently keyboard-highlighted option in the dropdown. `-1` when no option is highlighted. Automatically managed by arrow keys. |
-| `isLoading` | `boolean` | `true` while a fetch is in flight and no cached suggestions are visible. Only triggers on initial mount, after `reset()`, or when all cached suggestions are consumed. The dropdown stays open with cached data during background re-fetches. |
-| `isReady` | `boolean` | `true` when the server's `is_ready` flag indicates the query is complete and ready for execution. Use this to show a visual indicator or enable a submit button. |
-| `error` | `Error \| null` | The most recent fetch error, or `null` if the last fetch succeeded. Cleared on every new fetch attempt. |
+| `completedParams` | `CompletedParamState[]` | Filled parameters. |
+| `suggestionPills` | `Suggestion[]` | Unfilled suggestions (pills). First item is the active pill. |
+| `segments` | `Segment[]` | Input text split into text vs completed segments for overlay rendering. |
+| `newParamId` | `string \| null` | ID of the most recently added param (for shimmer animation). |
+| `suggestions` | `Suggestion[]` | All suggestions from server (including placeholder type). |
+| `activeIndex` | `number` | Highlighted option index. `-1` = none. |
+| `isLoading` | `boolean` | Fetch in progress. |
+| `isReady` | `boolean` | Server indicates query is complete. |
+| `error` | `Error \| null` | Last fetch error. |
 
 **Actions**
 
 | Field | Type | Description |
 |---|---|---|
-| `setActivePill` | `(index: number) => void` | Reorder pills by moving the pill at `index` to the front, making it the active pill whose options show in the dropdown. |
-| `removeLastParam` | `() => void` | Remove the most recently completed parameter, restore it as a pill, and re-show its options in the dropdown. Useful for handling backspace on an empty input. |
-| `reEditParam` | `(param: CompletedParamState) => void` | Remove a specific completed parameter from the input text, restore it as a pill with its cached options, and open the dropdown. Use this when the user taps on a bold (completed) param to change their selection. |
-| `clearNewParamId` | `() => void` | Manually clear `newParamId`. Called automatically after the shimmer/typewriter animation completes. |
-| `reset` | `() => void` | Clear all text, completed params, and suggestions, then re-fetch initial suggestions from the server. Returns the component to its mount state. |
+| `setActivePill` | `(index: number) => void` | Move pill at `index` to front (active). |
+| `removeLastParam` | `() => void` | Remove last completed param, restore as pill. |
+| `clearNewParamId` | `() => void` | Clear shimmer animation state. |
+| `reset` | `() => void` | Clear all state, re-fetch. |
 
 **Spread Props**
 
 | Field | Type | Description |
 |---|---|---|
-| `inputProps` | `object` | Spread onto a `<textarea>` element. Includes `value`, `placeholder`, `onChange`, `onKeyDown`, and ARIA attributes (`role="combobox"`, `aria-expanded`, `aria-activedescendant`, `aria-autocomplete`, `aria-controls`). Handles keyboard navigation, text capitalization, param reconciliation, and exact-match auto-completion internally. |
-| `dropdownProps` | `AIAutocompleteDropdownProps` | Spread onto `<AIAutocompleteDropdown />`. Includes the filtered options for the active suggestion, highlight index, selection handler, highlight handler, open state, and listbox ID. The dropdown handles mouse selection and hover highlighting. |
+| `inputProps` | `object` | Spread onto a `<textarea>`. Includes `value`, `placeholder`, `onChange`, `onKeyDown`, and ARIA attributes. |
+| `dropdownProps` | `AIAutocompleteDropdownProps` | Spread onto `<AIAutocompleteDropdown />`. Includes options, highlight, selection, pills, and open state. |
 
 ### `<AIAutocompleteDropdown />`
 
-The dropdown component for Tier 2 headless integration. Spread `dropdownProps` from the hook.
+The dropdown component for Tier 2. Spread `dropdownProps` from the hook.
 
 | Prop | Type | Description |
 |---|---|---|
-| `suggestions` | `Suggestion[]` | Suggestions to display (from `dropdownProps`). |
-| `activeIndex` | `number` | Currently highlighted option index. |
+| `suggestions` | `Suggestion[]` | Suggestions to display. |
+| `activeIndex` | `number` | Highlighted option index. |
 | `onSelect` | `(option: SuggestionOption) => void` | Called when an option is selected. |
-| `onHighlight` | `(index: number) => void` | Called when an option is highlighted (mouse hover). |
+| `onHighlight` | `(index: number) => void` | Called on mouse hover. |
 | `isOpen` | `boolean` | Whether the dropdown is visible. |
 | `id` | `string` | Listbox ID for ARIA. |
 | `className?` | `string` | CSS class applied to the dropdown. |
+| `pills?` | `Suggestion[]` | Pills to render inside the dropdown. |
+| `onPillClick?` | `(index: number) => void` | Called when a pill is clicked. |
+| `showPills?` | `boolean` | Whether to render pills. Default: `true`. |
 
-### `Suggestion`
-
-Represents an unfilled parameter slot. Rendered as a pill in Tier 1, or available via `suggestionPills` in Tier 2.
+### `AutocompleteResult`
 
 | Field | Type | Description |
 |---|---|---|
-| `type` | `string` | Suggestion type identifier (e.g. `"task"`, `"goal"`, `"contact"`). Used as the key for `optionOverrides`. |
-| `text` | `string` | Display text for the pill (e.g. `"type"`, `"goal"`). |
-| `required` | `boolean` | Whether this suggestion must be filled before submission. |
-| `options?` | `SuggestionOption[]` | Available options the user can select from. May be `undefined` if the server omits it. |
+| `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[]` | Filled parameter values. |
 
-### `SuggestionOption`
+---
 
-An individual option within a suggestion's dropdown.
+## CSS Customization
 
-| Field | Type | Description |
-|---|---|---|
-| `text` | `string` | Display text for the option. |
-| `icon?` | `string` | Icon shown before the text (e.g. emoji). |
-| `tag?` | `string` | Label shown after the text in smaller, muted style. |
-| `is_tappable` | `boolean` | Whether the option can be selected. Non-tappable options are always-visible hints that cannot be chosen. |
-| `kind` | `string \| null` | Category of the option (e.g. `"automation"`, `"email"`), or `null`. Passed through to `CompletedParam` on selection. |
-| `metadata?` | `Record<string, unknown>` | Arbitrary metadata passed through with the selection. Available on the completed param after the user selects this option. |
+Styles are auto-injected at runtime — no CSS import needed. Built-in light and dark defaults apply automatically based on `mode`.
 
-## CSS Customization
+### CSS Variables
+
+Override on the container (via `className`). All defaults use `:where()` (zero specificity) — your overrides always win.
+
+| Variable | Light | Dark | Description |
+|---|---|---|---|
+| `--aia-pill-bg` | `#bdbdbd` | `#bdbdbd` | Pill background |
+| `--aia-pill-color` | `#000000` | `#ffffff` | Pill text |
+| `--aia-pill-font-size` | `19px` | `19px` | Pill font size |
+| `--aia-option-bg` | `transparent` | `transparent` | Highlighted option background |
+| `--aia-option-color` | `#000000` | `#ffffff` | Option text |
+| `--aia-option-color-selected` | `#000000` | `#ffffff` | Highlighted option text |
+| `--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 |
+
+Legacy `--aia-color-*` variables are still supported as fallbacks.
 
-Styles are auto-injected at runtime — no CSS import needed. The component uses CSS variables for theming. Override them on a parent element:
+### Per-mode Overrides
 
 ```css
-.my-autocomplete {
-  --ac-color-border-default: #ccc;         /* Input border */
-  --ac-color-text-default: #333;           /* Input text, caret, submit button bg, highlighted option */
-  --ac-color-text-muted: #999;             /* Placeholder, pill text, option text */
-  --ac-color-bg-default: #000;             /* Submit button icon color (foreground on button) */
-  --ac-color-background-default: #fff;     /* Dropdown background */
-  --ac-color-background-supportive: #eee;  /* Pill background */
+.my-autocomplete[data-mode="light"] {
+  --aia-pill-bg: #e2e8f0;
+}
+.my-autocomplete[data-mode="dark"] {
+  --aia-pill-bg: #334155;
 }
 ```
 
-## Keyboard Behavior
-
-| Key | Behavior |
-|---|---|
-| **Arrow Down** | Open dropdown (if closed and cursor at end) and select first option, or navigate to next option. |
-| **Arrow Up** | Navigate to previous option. Deselects if on the first row. Does nothing if no option is selected. |
-| **Arrow Right** | Jump to next column when an option is highlighted. Cycles to the next suggestion pill when cursor is at the end and no option is selected. |
-| **Arrow Left** | Jump to previous column when an option is highlighted. |
-| **Tab** | Select the first tappable option (or highlighted one). Accepts placeholder when input is empty. |
-| **Enter** | Select highlighted option if one is highlighted. Otherwise submits the query. |
-| **Escape** | Deselect the highlighted option. |
+---
 
 ## Option Overrides
 
-Use `optionOverrides` to inject client-side options per suggestion type:
-
 ```tsx
-const overrides = {
-  // Static options
-  account: () => [
-    { text: "Savings", is_tappable: true, kind: null },
-    { text: "Checking", is_tappable: true, kind: null },
-  ],
-  // Dynamic options based on filter query
-  value: (query) => {
-    const digits = query.replace(/\D/g, "");
-    if (!digits) return [{ text: "$100", is_tappable: true, kind: null }];
-    return [{ text: `$${digits}`, is_tappable: true, kind: null }];
-  },
-};
-
-<AIAutocomplete optionOverrides={overrides} onSubmit={handleSubmit} />
+<AIAutocomplete
+  optionOverrides={{
+    account: () => [
+      { text: "Savings", is_tappable: true, kind: null },
+      { text: "Checking", is_tappable: true, kind: null },
+    ],
+    value: (query) => {
+      const digits = query.replace(/\D/g, "");
+      if (!digits) return [{ text: "$100", is_tappable: true, kind: null }];
+      return [{ text: `$${digits}`, is_tappable: true, kind: null }];
+    },
+  }}
+  onSubmit={handleSubmit}
+/>
 ```
 
-Override options are prepended to server options (deduplicated by `text`). When a filter query is active and an override function exists, it replaces the default client-side filtering entirely.
-
 ## License
 
 Private package. All rights reserved.

package/dist/index.css

@@ -0,0 +1,2 @@
+:where(.magicx-aia),:where(.magicx-aia[data-mode=light]){--aia-pill-bg: #bdbdbd;--aia-pill-color: #000000;--aia-pill-font-size: 19px;--aia-option-bg: transparent;--aia-option-color: #000000;--aia-option-color-selected: #000000;--aia-option-font-size: 19px;--aia-written-text-color: #000000;--aia-written-text-font-size: 19px}:where(.magicx-aia[data-mode=dark]){--aia-pill-bg: #bdbdbd;--aia-pill-color: #ffffff;--aia-pill-font-size: 19px;--aia-option-bg: transparent;--aia-option-color: #ffffff;--aia-option-color-selected: #ffffff;--aia-option-font-size: 19px;--aia-written-text-color: #ffffff;--aia-written-text-font-size: 19px}:where(.magicx-aia[data-options-position=above]) [data-aia-dropdown]{top:auto;bottom:100%;margin-top:0;margin-bottom:6px}:where(.magicx-aia[data-animations=off]) *,:where(.magicx-aia[data-animations=off]) *:before,:where(.magicx-aia[data-animations=off]) *:after{animation-duration:0s!important;transition-duration:0s!important}
+/*# sourceMappingURL=index.css.map */

package/dist/index.css.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/appearance.css"],"sourcesContent":["/*\n * Built-in appearance defaults — zero specificity via :where().\n * Consumer CSS always wins without !important.\n *\n * Resolution priority (highest wins):\n * 1. Consumer CSS targeting new vars (--aia-pill-bg, etc.)\n * 2. Consumer CSS targeting legacy vars (--aia-color-*, via fallback chain)\n * 3. These built-in defaults\n */\n\n/* Light mode defaults (base) */\n:where(.magicx-aia),\n:where(.magicx-aia[data-mode=\"light\"]) {\n  --aia-pill-bg: #bdbdbd;\n  --aia-pill-color: #000000;\n  --aia-pill-font-size: 19px;\n\n  --aia-option-bg: transparent;\n  --aia-option-color: #000000;\n  --aia-option-color-selected: #000000;\n  --aia-option-font-size: 19px;\n\n  --aia-written-text-color: #000000;\n  --aia-written-text-font-size: 19px;\n}\n\n/* Dark mode defaults */\n:where(.magicx-aia[data-mode=\"dark\"]) {\n  --aia-pill-bg: #bdbdbd;\n  --aia-pill-color: #ffffff;\n  --aia-pill-font-size: 19px;\n\n  --aia-option-bg: transparent;\n  --aia-option-color: #ffffff;\n  --aia-option-color-selected: #ffffff;\n  --aia-option-font-size: 19px;\n\n  --aia-written-text-color: #ffffff;\n  --aia-written-text-font-size: 19px;\n}\n\n/* optionsPosition: dropdown above the input */\n:where(.magicx-aia[data-options-position=\"above\"]) [data-aia-dropdown] {\n  top: auto;\n  bottom: 100%;\n  margin-top: 0;\n  margin-bottom: 6px;\n}\n\n/* Disable all animations when data-animations=\"off\" */\n:where(.magicx-aia[data-animations=\"off\"]) *,\n:where(.magicx-aia[data-animations=\"off\"]) *::before,\n:where(.magicx-aia[data-animations=\"off\"]) *::after {\n  animation-duration: 0s !important;\n  transition-duration: 0s !important;\n}\n"],"mappings":"AAWA,OAAO,CAAC,YACR,OAAO,CADC,UACU,CAAC,kBACjB,eAAe,QACf,kBAAkB,QAClB,sBAAsB,KAEtB,iBAAiB,YACjB,oBAAoB,QACpB,6BAA6B,QAC7B,wBAAwB,KAExB,0BAA0B,QAC1B,8BAA8B,IAChC,CAGA,OAAO,CAhBC,UAgBU,CAAC,iBACjB,eAAe,QACf,kBAAkB,QAClB,sBAAsB,KAEtB,iBAAiB,YACjB,oBAAoB,QACpB,6BAA6B,QAC7B,wBAAwB,KAExB,0BAA0B,QAC1B,8BAA8B,IAChC,CAGA,OAAO,CA/BC,UA+BU,CAAC,8BAAgC,CAAC,mBAClD,IAAK,KACL,OAAQ,KACR,WAAY,EACZ,cAAe,GACjB,CAGA,OAAO,CAvCC,UAuCU,CAAC,sBAAwB,EAC3C,OAAO,CAxCC,UAwCU,CAAC,sBAAwB,CAAC,QAC5C,OAAO,CAzCC,UAyCU,CAAC,sBAAwB,CAAC,OAC1C,mBAAoB,aACpB,oBAAqB,YACvB","names":[]}

package/dist/index.d.mts

@@ -39,17 +39,33 @@ type Segment = {
     value: string;
     param: CompletedParamState;
 };
+type AppearanceMode = "light" | "dark" | "auto";
 interface AIAutocompleteHandle {
     focus: () => void;
     reset: () => void;
+    setMode: (mode: AppearanceMode) => void;
 }
-interface APIConfig {
+interface APIConfigBase {
     endpoint?: string;
-    apiKey?: string;
-    authScheme?: "Bearer" | "Basic";
     appIdentifier?: string;
     headers?: Record<string, string>;
 }
+interface APIKeyConfig extends APIConfigBase {
+    type?: "apiKey";
+    apiKey?: string;
+    authScheme?: "Bearer" | "Basic";
+}
+interface AccessTokenConfig extends APIConfigBase {
+    type: "accessToken";
+    accessToken?: string;
+    getAccessToken: () => Promise<AccessTokenResult>;
+}
+interface AccessTokenResult {
+    accessToken: string;
+    /** UNIX ms. If provided, SDK refreshes proactively 30s before expiry. */
+    expiresAt?: number;
+}
+type APIConfig = APIKeyConfig | AccessTokenConfig;
 type OptionOverrides = Record<string, (query: string) => SuggestionOption[]>;
 interface AIAutocompleteProps {
     onSubmit: (result: AutocompleteResult) => void;
@@ -60,8 +76,16 @@ interface AIAutocompleteProps {
     className?: string;
     apiConfig?: APIConfig;
     columns?: number;
-    /** When true (default), reveal selected option text letter by letter. */
-    typewriterEffect?: boolean;
+    /** Where to render unfilled pills. "inline" (default) renders them in the input; "dropdown" renders them above the options grid. */
+    pillPlacement?: "inline" | "dropdown" | "hidden";
+    /** Color mode. "auto" listens to prefers-color-scheme. Default: "auto" */
+    mode?: AppearanceMode;
+    /** Where the dropdown opens relative to the input. Default: "below" */
+    optionsPosition?: "above" | "below";
+    /** Enable all SDK animations (streak + shimmer). Default: true */
+    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";
     value?: string;
     completedParams?: CompletedParamState[];
     onChange?: (value: string) => void;
@@ -80,8 +104,8 @@ interface UseAIAutocompleteOptions {
     placeholder?: string;
     apiConfig?: APIConfig;
     columns?: number;
-    /** When true (default), reveal selected option text letter by letter. */
-    typewriterEffect?: boolean;
+    /** When the dropdown appears. Default: "auto". */
+    dropdownTrigger?: "auto" | "manual" | "hidden";
     value?: string;
     completedParams?: CompletedParamState[];
     onChange?: (value: string) => void;
@@ -92,7 +116,6 @@ interface UseAIAutocompleteReturn {
     suggestionPills: Suggestion[];
     setActivePill: (index: number) => void;
     removeLastParam: () => void;
-    reEditParam: (param: CompletedParamState) => void;
     reset: () => void;
     segments: Segment[];
     newParamId: string | null;
@@ -123,12 +146,18 @@ interface AIAutocompleteDropdownProps {
     isOpen: boolean;
     id: string;
     className?: string;
+    /** Pills to render inside the dropdown. Provided by `dropdownProps` from the hook. */
+    pills?: Suggestion[];
+    /** Called when a pill inside the dropdown is clicked. Provided by `dropdownProps` from the hook. */
+    onPillClick?: (index: number) => void;
+    /** Whether to render pills inside the dropdown. Default: true. Tier 2 consumers who render their own pills should set this to false. */
+    showPills?: boolean;
 }
 
 declare const AIAutocomplete: react.ForwardRefExoticComponent<AIAutocompleteProps & react.RefAttributes<AIAutocompleteHandle>>;
 
-declare function AIAutocompleteDropdown({ suggestions, activeIndex, onSelect, onHighlight, isOpen, id, className, }: AIAutocompleteDropdownProps): react_jsx_runtime.JSX.Element;
+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, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
+declare function useAIAutocomplete({ onSubmit, onError, optionOverrides, maskCompletedText, placeholder: customPlaceholder, apiConfig, columns, dropdownTrigger, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
 
-export { AIAutocomplete, AIAutocompleteDropdown, type AIAutocompleteDropdownProps, type AIAutocompleteHandle, type AIAutocompleteProps, type APIConfig, type AutocompleteResult, type CompletedParam, type CompletedParamState, type OptionOverrides, type Segment, type Suggestion, type SuggestionOption, type TaskKind, type UseAIAutocompleteOptions, type UseAIAutocompleteReturn, useAIAutocomplete };
+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

@@ -39,17 +39,33 @@ type Segment = {
     value: string;
     param: CompletedParamState;
 };
+type AppearanceMode = "light" | "dark" | "auto";
 interface AIAutocompleteHandle {
     focus: () => void;
     reset: () => void;
+    setMode: (mode: AppearanceMode) => void;
 }
-interface APIConfig {
+interface APIConfigBase {
     endpoint?: string;
-    apiKey?: string;
-    authScheme?: "Bearer" | "Basic";
     appIdentifier?: string;
     headers?: Record<string, string>;
 }
+interface APIKeyConfig extends APIConfigBase {
+    type?: "apiKey";
+    apiKey?: string;
+    authScheme?: "Bearer" | "Basic";
+}
+interface AccessTokenConfig extends APIConfigBase {
+    type: "accessToken";
+    accessToken?: string;
+    getAccessToken: () => Promise<AccessTokenResult>;
+}
+interface AccessTokenResult {
+    accessToken: string;
+    /** UNIX ms. If provided, SDK refreshes proactively 30s before expiry. */
+    expiresAt?: number;
+}
+type APIConfig = APIKeyConfig | AccessTokenConfig;
 type OptionOverrides = Record<string, (query: string) => SuggestionOption[]>;
 interface AIAutocompleteProps {
     onSubmit: (result: AutocompleteResult) => void;
@@ -60,8 +76,16 @@ interface AIAutocompleteProps {
     className?: string;
     apiConfig?: APIConfig;
     columns?: number;
-    /** When true (default), reveal selected option text letter by letter. */
-    typewriterEffect?: boolean;
+    /** Where to render unfilled pills. "inline" (default) renders them in the input; "dropdown" renders them above the options grid. */
+    pillPlacement?: "inline" | "dropdown" | "hidden";
+    /** Color mode. "auto" listens to prefers-color-scheme. Default: "auto" */
+    mode?: AppearanceMode;
+    /** Where the dropdown opens relative to the input. Default: "below" */
+    optionsPosition?: "above" | "below";
+    /** Enable all SDK animations (streak + shimmer). Default: true */
+    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";
     value?: string;
     completedParams?: CompletedParamState[];
     onChange?: (value: string) => void;
@@ -80,8 +104,8 @@ interface UseAIAutocompleteOptions {
     placeholder?: string;
     apiConfig?: APIConfig;
     columns?: number;
-    /** When true (default), reveal selected option text letter by letter. */
-    typewriterEffect?: boolean;
+    /** When the dropdown appears. Default: "auto". */
+    dropdownTrigger?: "auto" | "manual" | "hidden";
     value?: string;
     completedParams?: CompletedParamState[];
     onChange?: (value: string) => void;
@@ -92,7 +116,6 @@ interface UseAIAutocompleteReturn {
     suggestionPills: Suggestion[];
     setActivePill: (index: number) => void;
     removeLastParam: () => void;
-    reEditParam: (param: CompletedParamState) => void;
     reset: () => void;
     segments: Segment[];
     newParamId: string | null;
@@ -123,12 +146,18 @@ interface AIAutocompleteDropdownProps {
     isOpen: boolean;
     id: string;
     className?: string;
+    /** Pills to render inside the dropdown. Provided by `dropdownProps` from the hook. */
+    pills?: Suggestion[];
+    /** Called when a pill inside the dropdown is clicked. Provided by `dropdownProps` from the hook. */
+    onPillClick?: (index: number) => void;
+    /** Whether to render pills inside the dropdown. Default: true. Tier 2 consumers who render their own pills should set this to false. */
+    showPills?: boolean;
 }
 
 declare const AIAutocomplete: react.ForwardRefExoticComponent<AIAutocompleteProps & react.RefAttributes<AIAutocompleteHandle>>;
 
-declare function AIAutocompleteDropdown({ suggestions, activeIndex, onSelect, onHighlight, isOpen, id, className, }: AIAutocompleteDropdownProps): react_jsx_runtime.JSX.Element;
+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, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
+declare function useAIAutocomplete({ onSubmit, onError, optionOverrides, maskCompletedText, placeholder: customPlaceholder, apiConfig, columns, dropdownTrigger, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
 
-export { AIAutocomplete, AIAutocompleteDropdown, type AIAutocompleteDropdownProps, type AIAutocompleteHandle, type AIAutocompleteProps, type APIConfig, type AutocompleteResult, type CompletedParam, type CompletedParamState, type OptionOverrides, type Segment, type Suggestion, type SuggestionOption, type TaskKind, type UseAIAutocompleteOptions, type UseAIAutocompleteReturn, useAIAutocomplete };
+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 };