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

package/README.md

@@ -0,0 +1,291 @@
+# @magicx-eng/ai-autocomplete-vanilla
+
+A framework-agnostic vanilla JS/TypeScript library that provides a guided AI-powered autocomplete experience with pill-based input and dropdown suggestions. Works with any tech stack — React, Vue, Svelte, Angular, or plain HTML.
+
+## Features
+
+- **Zero dependencies** — no React, no framework, no virtual DOM
+- **Pill-based input** — inline pills for unfilled parameters, completed text for filled 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 via `setValue()` / `setCompletedParams()`
+- **Imperative API** — `focus()`, `reset()`, `setMode()`, `destroy()`, and more
+- **Accessible** — ARIA combobox pattern with `role="listbox"`, `aria-activedescendant`
+- **Animations** — option selection streak animation, text shimmer on newly added params
+- **Lightweight** — ~10 KB gzipped, styles auto-injected at runtime
+- **TypeScript first** — full type definitions shipped with the package
+- **SSR-safe** — no top-level `document`/`window` access
+
+## Installation
+
+```bash
+pnpm add @magicx-eng/ai-autocomplete-vanilla
+```
+
+## Quick Start
+
+```html
+<div id="ac"></div>
+
+<script type="module">
+  import { AIAutocomplete } from "@magicx-eng/ai-autocomplete-vanilla";
+
+  const instance = new AIAutocomplete(document.getElementById("ac"), {
+    apiConfig: {
+      endpoint: "https://api.example.com/ac/suggest",
+      apiKey: "your_api_key",
+    },
+    onSubmit: (result) => {
+      console.log(result.query);            // "Create a email"
+      console.log(result.raw_query);        // "Create a {{TASK_1}}"
+      console.log(result.completed_params); // [{ placeholder: "{{TASK_1}}", type: "task", ... }]
+    },
+  });
+</script>
+```
+
+No CSS import needed — styles are auto-injected on first instantiation.
+
+## Usage with Frameworks
+
+### Vue
+
+```vue
+<template>
+  <div ref="acRef" />
+</template>
+
+<script setup>
+import { ref, onMounted, onUnmounted } from "vue";
+import { AIAutocomplete } from "@magicx-eng/ai-autocomplete-vanilla";
+
+const acRef = ref(null);
+let instance;
+
+onMounted(() => {
+  instance = new AIAutocomplete(acRef.value, {
+    apiConfig: { endpoint: "/ac/suggest", apiKey: "your_key" },
+    onSubmit: (result) => console.log(result),
+  });
+});
+
+onUnmounted(() => instance?.destroy());
+</script>
+```
+
+### Svelte
+
+```svelte
+<script>
+  import { onMount, onDestroy } from "svelte";
+  import { AIAutocomplete } from "@magicx-eng/ai-autocomplete-vanilla";
+
+  let el;
+  let instance;
+
+  onMount(() => {
+    instance = new AIAutocomplete(el, {
+      apiConfig: { endpoint: "/ac/suggest", apiKey: "your_key" },
+      onSubmit: (result) => console.log(result),
+    });
+  });
+
+  onDestroy(() => instance?.destroy());
+</script>
+
+<div bind:this={el}></div>
+```
+
+### Plain HTML (CDN)
+
+```html
+<div id="ac"></div>
+<script type="module">
+  import { AIAutocomplete } from "https://unpkg.com/@magicx-eng/ai-autocomplete-vanilla/index.mjs";
+
+  new AIAutocomplete(document.getElementById("ac"), {
+    apiConfig: { endpoint: "/ac/suggest", apiKey: "your_key" },
+    onSubmit: (result) => console.log(result),
+  });
+</script>
+```
+
+## API Reference
+
+### Constructor
+
+```ts
+new AIAutocomplete(container: HTMLElement, options?: CoreOptions)
+```
+
+### `CoreOptions`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiConfig` | `APIConfig` | — | API configuration (see below). |
+| `optionOverrides?` | `Record<string, (query: string) => SuggestionOption[]>` | — | Override options per suggestion type. |
+| `placeholder?` | `string` | — | Fallback placeholder when the server doesn't return one. |
+| `columns?` | `number` | `2` | Number of columns in the dropdown grid. |
+| `typewriterEffect?` | `boolean` | `false` | Letter-by-letter reveal on option select. |
+| `pillPlacement?` | `"inline" \| "dropdown"` | `"inline"` | Where to render unfilled pills. |
+| `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 animations (streak + shimmer). |
+| `onSubmit?` | `(result: AutocompleteResult) => void` | — | Called on Enter or submit button. |
+| `onError?` | `(error: Error) => void` | — | Called when a fetch fails. |
+| `onChange?` | `(text: string) => void` | — | Called when text changes. |
+| `onParamsChange?` | `(params: CompletedParamState[]) => void` | — | Called when completed params change. |
+| `value?` | `string` | — | Controlled text value. |
+| `completedParams?` | `CompletedParamState[]` | — | Controlled completed params. |
+
+### `APIConfig`
+
+A discriminated union: `APIKeyConfig | AccessTokenConfig`.
+
+#### API Key Mode (default)
+
+```ts
+{
+  apiKey: "your_api_key",
+  authScheme: "Bearer",         // or "Basic"
+  endpoint: "/ac/suggest",      // optional
+  appIdentifier: "my-app",      // optional
+  headers: { "X-Custom": "v" }, // optional
+}
+```
+
+#### Access Token Mode
+
+```ts
+{
+  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 };
+  },
+  endpoint: "/ac/suggest",      // optional
+}
+```
+
+The SDK handles token refresh transparently: if a request returns 401, it calls `getAccessToken` once, retries, and only surfaces an error if the retry also fails. Concurrent 401s share a single refresh call.
+
+### Instance Methods
+
+| Method | Description |
+|---|---|
+| `focus()` | Focus the textarea. |
+| `reset()` | Clear all state and re-fetch initial suggestions. |
+| `destroy()` | Remove all DOM, listeners, and timers. Call when unmounting. |
+| `setMode(mode)` | Switch color mode at runtime (`"light"`, `"dark"`, `"auto"`). |
+| `update(opts)` | Update any option at runtime (mode, pillPlacement, animations, etc.). |
+| `setValue(text)` | Set text value (controlled mode). |
+| `setCompletedParams(params)` | Set completed params (controlled mode). |
+| `setActivePill(index)` | Reorder pills, making the one at `index` active. |
+| `removeLastParam()` | Remove the last completed param and restore it as a pill. |
+| `clearNewParamId()` | Clear the shimmer animation state. |
+| `getState()` | Get a snapshot of the full internal state. |
+| `isReady` | `true` when the server indicates the query is ready for execution. |
+
+### Event Subscription
+
+```ts
+const off = instance.on("submit", (result) => { ... });
+off(); // unsubscribe
+```
+
+Events: `submit`, `error`, `change`, `paramsChange`, `stateChange`.
+
+Constructor callbacks (`onSubmit`, `onChange`, etc.) are equivalent to calling `on()`.
+
+### `AutocompleteResult`
+
+The object passed to `onSubmit`:
+
+| Field | Type | Description |
+|---|---|---|
+| `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. |
+
+## CSS Customization
+
+Styles are auto-injected at runtime — no CSS import needed. The component ships built-in light and dark defaults that apply automatically based on the `mode` option.
+
+### CSS Variables
+
+Override these on the container element to customize the appearance. All built-in defaults use `:where()` (zero specificity), so your overrides always win without `!important`.
+
+| Variable | Default (light) | Default (dark) | Description |
+|---|---|---|---|
+| `--ac-pill-bg` | `#f1f5f9` | `#1e293b` | Pill background color |
+| `--ac-pill-color` | `#475569` | `#cbd5e1` | Pill text color |
+| `--ac-pill-font-size` | `19px` | `19px` | Pill font size |
+| `--ac-option-bg` | `transparent` | `transparent` | Option background (highlighted) |
+| `--ac-option-color` | `#475569` | `#cbd5e1` | Option text color |
+| `--ac-option-color-selected` | `#0f172a` | `#f8fafc` | Highlighted option text color |
+| `--ac-option-font-size` | `19px` | `19px` | Option font size |
+| `--ac-written-text-color` | `#0f172a` | `#f1f5f9` | Input text color |
+| `--ac-written-text-font-size` | `19px` | `19px` | Input text font size |
+
+### Per-mode Overrides
+
+```css
+#my-autocomplete[data-mode="light"] {
+  --ac-pill-bg: #e2e8f0;
+  --ac-written-text-color: #1e293b;
+}
+
+#my-autocomplete[data-mode="dark"] {
+  --ac-pill-bg: #334155;
+  --ac-written-text-color: #f8fafc;
+}
+```
+
+### Live Preview
+
+CSS variables update instantly — great for theme editors:
+
+```ts
+document.getElementById("my-autocomplete")
+  .style.setProperty("--ac-pill-bg", newColor);
+```
+
+## Keyboard Behavior
+
+| Key | Behavior |
+|---|---|
+| **Arrow Down** | Open dropdown and select first option, or navigate to next option. |
+| **Arrow Up** | Navigate to previous option. Deselects if on the first row. |
+| **Arrow Right** | Jump to next column when an option is highlighted. Cycles to next pill when cursor is at the end. |
+| **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
+
+```ts
+new AIAutocomplete(el, {
+  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,
+});
+```
+
+## License
+
+Private package. All rights reserved.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magicx-eng/ai-autocomplete-vanilla",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "AI Autocomplete — framework-agnostic vanilla JS library",
   "main": "./index.js",
   "module": "./index.mjs",