sautocomplete-suggestion

SAutocomplete Suggestion

A lightweight, dependency-free grouped autocomplete suggestion input built with Vanilla TypeScript.

Behavioral port of the Consent AI 4 main input — without any AI: the host app provides grouped data ({ id, group, label }[]), the component handles accent-insensitive filtering, active-word highlight, staged multi-select and submit. Framework-agnostic with React, Vue and Angular wrappers (full dynamic @Input/@Output for Angular).

All UI strings are in English by default and overridable via locale.

Enterprise edition (v1.2.1): async dataSource (debounce + abort + cache), virtualization, allowlist-sanitized icons, native form integration (name + getFormValue()), generic SuggestionItem<T> payloads, pluggable history adapters, logger + telemetry hooks, design tokens (theme/density/RTL/font/ surfaces/cssVars), full keyboard nav + live regions. Full guide: docs/ENTERPRISE.md.

Table of Contents

• Features
• Installation
• Quick Start
  • Using ES Modules (Recommended)
  • Using UMD (via script tag in plain HTML)
    • Option 1: Via CDN (unpkg / jsDelivr)
    • Option 2: Using importmap (modern browsers, no bundler)
• API
  • createAutocomplete(options)
    • Options
    • Instance methods
  • Working with the query (getQuery / setQuery / onChange)
• Custom Groups
• Available Default Groups
• Custom Color & Submit Icon
• Locale (English by default)
• Keyboard Shortcuts
• How It Works (staged flow)
• Bundle Sizes
• Framework Integration
  • React
  • Vue
  • Angular
• Development
• Publishing to npm
• Project Structure
• License

Features

• 🚀 Lightweight — tiny bundle, 0 runtime dependencies
• 🗂️ Grouped suggestions — any groups + values; data is assumed available (no AI, no network)
• 🔍 Accent-insensitive matching + token matching (cafe matches Café)
• 🖍️ Active-word highlight — mirrored underlay with amber highlight on the word/entity at the cursor
• ✅ Staged multi-select — Click/Space stages chips, Enter/Apply commits to input, Enter again submits
• 🎨 Customizable — accent color, submitIcon, radii, fonts, surfaces and shadows via tokens + cssVars (full CSS-variable theming, no overrides needed)
• ⌨️ Full keyboard control — Tab cycle, Arrows navigate, Enter commit/submit, Esc close
• 🕘 Recent history — dropdown when input is empty (configurable, default 5)
• ⬆️ Dropup mode — for docked bottom search bars
• ♿ Accessible — combobox/listbox/option roles, aria-selected, aria-expanded, labeled buttons
• 🛡️ XSS-safe — all labels/queries escaped via a dedicated sanitizer module
• 🌙 Dark Mode — automatic via prefers-color-scheme
• 📱 Responsive — works on all screen sizes
• 🔧 Simple API — one createAutocomplete() call, framework wrappers included

Installation

npm install sautocomplete-suggestion

Quick Start

Using ES Modules (Recommended)

import { createAutocomplete } from 'sautocomplete-suggestion';
import 'sautocomplete-suggestion/dist/styles.css';

const editor = createAutocomplete({
  container: '#editor',
  items: [
    { id: 'l1', group: 'Language', label: 'TypeScript' },
    { id: 'f1', group: 'Framework', label: 'React' },
    { id: 't1', group: 'Tool', label: 'Vite' },
  ],
  placeholder: 'Search languages, frameworks, tools...',
  onSubmit: (query) => console.log('Submitted:', query),
});

// Programmatic access
editor.setQuery('typ');
console.log(editor.getQuery());

Using UMD (via script tag in plain HTML)

Option 1: Via CDN (unpkg / jsDelivr)

No installation needed — just add these to your HTML <head>:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>My Page</title>
  <link rel="stylesheet" href="https://unpkg.com/sautocomplete-suggestion/dist/styles.css" />
</head>
<body>
  <div id="editor"></div>
  <script src="https://unpkg.com/sautocomplete-suggestion/dist/sautocomplete-suggestion.umd.js"></script>
  <script>
    const editor = SAutocomplete.createAutocomplete({
      container: '#editor',
      items: [{ id: '1', group: 'Language', label: 'TypeScript' }],
      onSubmit: (query) => console.log(query),
    });
  </script>
</body>
</html>

Note: the UMD build exposes the global SAutocomplete. Call SAutocomplete.createAutocomplete(...).

Option 2: Using importmap (modern browsers, no bundler)

<link rel="stylesheet" href="https://unpkg.com/sautocomplete-suggestion/dist/styles.css" />
<div id="editor"></div>
<script type="importmap">
{ "imports": { "sautocomplete-suggestion": "https://unpkg.com/sautocomplete-suggestion/dist/sautocomplete-suggestion.esm.js" } }
</script>
<script type="module">
  import { createAutocomplete } from 'sautocomplete-suggestion';
  createAutocomplete({ container: '#editor', items: [] });
</script>

API

createAutocomplete(options)

Creates a new autocomplete instance. Returns an AutocompleteInstance.

Options

Instance methods

Working with the query (getQuery / setQuery / onChange)

const editor = createAutocomplete({
  container: '#editor',
  onChange: (query) => {
    // same string as getQuery()
    console.log('Current query:', query);
  },
});

editor.setQuery('React, Vite');
console.log(editor.getQuery()); // "React, Vite"

document.getElementById('save')?.addEventListener('click', () => {
  fetch('/api/search', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query: editor.getQuery(), staged: editor.getStaged() }),
  });
});

Custom Groups

Any domain works — groups are just strings:

createAutocomplete({
  container: '#editor',
  items: [
    { id: 'g1', group: 'Genre', label: 'Sci-Fi' },
    { id: 'm1', group: 'Movie', label: 'Dune: Part Two' },
    { id: 'd1', group: 'Director', label: 'Denis Villeneuve' },
  ],
  groupOrder: ['Genre', 'Movie', 'Director'],
});

Available Default Groups

The bundled sample dataset ships with 6 groups (override freely via items / groupOrder):

Custom Color, Submit Icon & Border Radius

Each instance can carry its own accent theme, submit icon and input radius — no CSS overrides needed:

const editor = createAutocomplete({
  container: '#editor',
  items,
  color: '#0f766e', // any CSS color; focus ring, submit button, staged chips follow
  colorDark: '#115e59', // optional hover shade (auto-derived when omitted)
  borderRadius: 16, // main input bar radius: px number or any CSS radius (default 24)
  submitIcon: '<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M5 12h14"/><path d="m12 5 7 7-7 7"/></svg>',
});

// Update radius later without recreating:
editor.setBorderRadius(12);
editor.setBorderRadius('999px'); // pill

<!-- Angular -->
<s-autocomplete-suggestion
  [items]="items"
  [color]="'#0f766e'"
  [borderRadius]="16"
  [submitIcon]="arrowIcon">
</s-autocomplete-suggestion>

Design tokens & CSS variables (v1.2+)

For deeper customization (fonts, surfaces, panel, shadows) use tokens — every key maps to a CSS variable on the instance root, so instances stay isolated:

createAutocomplete({
  container: '#editor',
  items,
  tokens: {
    theme: 'system',       // 'light' | 'dark' | 'system'
    density: 'compact',    // 'comfortable' | 'compact'
    direction: 'auto',     // 'ltr' | 'rtl' | 'auto'
    fontFamily: 'Inter, system-ui, sans-serif',
    fontSize: 15,
    background: '#ffffff',
    foreground: '#1e293b',
    borderColor: '#e2e8f0',
    mutedColor: '#64748b',
    dropdownRadius: 14,
    maxDropdownHeight: 320,
    shadow: '0 20px 50px rgba(15,23,42,.18)',
    cssVars: { '--sa-chip-gap': '10px' }, // escape hatch for any variable below
  },
});

The status bar shows scope, hits, the replacing pill, staged count, keyboard hints and Apply — all overridable via locale. The ms timing was removed in v1.2.1 (it implied remote AI search; this library assumes local data) — elapsed time remains available via telemetry.onSearch.

Locale (English by default)

createAutocomplete({
  container: '#editor',
  locale: {
    recentTitle: 'Recent searches',
    selected: 'Selected',
    apply: 'Apply',
    done: 'Done',
    hits: 'hits',
    groups: 'groups',
    replacing: 'replacing',
    loading: 'Loading…',
    loadError: 'Could not load suggestions',
    retry: 'Retry',
    empty: 'No matches — try another keyword',
  },
});

Keyboard Shortcuts

How It Works (staged flow)

1. Type — the active word at the cursor filters all groups (accent-insensitive).
2. Stage — Click a chip or focus it with Tab and press Space. Repeat for multi-select. The header shows Selected: N.
3. Apply — press Enter or click Apply (N) to commit staged labels into the input (dropdown closes, no submit yet).
4. Submit — press Enter on the input or click the Send button. The query is saved to history and onSubmit fires.

Bundle Sizes

Total package: ~70 KB (~39 KB served: pick ESM or UMD + CSS) · Total runtime dependencies: 0.

Framework Integration

React

Copy frameworks/react.tsx into your app:

import { SAutocomplete } from './SAutocomplete';

function Page() {
  return (
    <SAutocomplete
      items={items}
      placeholder="Search..."
      onSubmit={(q) => console.log('Submitted:', q)}
      onQueryChange={(q) => console.log('Query:', q)}
      onStagedChange={(s) => console.log('Staged:', s)}
    />
  );
}

Vue

Copy frameworks/vue.vue:

<template>
  <SAutocomplete :items="items" placeholder="Search..." @submit="onSubmit" @change="onChange" @stage="onStage" />
</template>

<script setup lang="ts">
import SAutocomplete from './SAutocomplete.vue';
const items = [{ id: '1', group: 'Language', label: 'TypeScript' }];
function onSubmit(q: string) { console.log('Submitted:', q); }
function onChange(q: string) { console.log('Query:', q); }
function onStage(s: unknown) { console.log('Staged:', s); }
</script>

Angular

1. Install the package

npm install sautocomplete-suggestion

2. Copy the wrapper component

Copy frameworks/angular.ts into your app (e.g. s-autocomplete-suggestion.component.ts). Every option is an @Input(), every event an @Output():

// @Input(): placeholder, value, items, groups, groupOrder, dropup, disabled,
//   minChars, maxHistory, history, maxItemsPerGroup, maxTotalItems,
//   showStatusBar, showHistory, showApplyButton, className, locale,
//   submitIcon, color, colorDark, borderRadius
// @Output(): querySubmit, queryChange, stagedChange, focused, blurred, ready
// Methods: getQuery(), getText(), isEmpty(), getWordCount(), getCharacterCount(),
//   setQuery(v), clear(), focus(), submit(q?), setDropup(v), setBorderRadius(v)

3. Use in a page

<s-autocomplete-suggestion
  [placeholder]="'Search...'"
  [items]="items"
  [groupOrder]="['Language', 'Framework']"
  [dropup]="false"
  [disabled]="false"
  [maxHistory]="5"
  (querySubmit)="onSubmit($event)"
  (queryChange)="onChange($event)"
  (stagedChange)="onStage($event)">
</s-autocomplete-suggestion>

export class AppComponent {
  items = [{ id: '1', group: 'Language', label: 'TypeScript' }];
  onSubmit(q: string) { console.log('Submitted:', q); }
  onChange(q: string) { console.log('Query:', q); }
  onStage(s: unknown) { console.log('Staged:', s); }
}

Development

# Install dependencies
npm install --legacy-peer-deps

# Development mode with watch
npm run dev

# Build for production (styles.css + ESM + UMD + d.ts)
npm run build

# Run unit tests
npm run test

# Run unit tests in watch mode
npm run test:watch

# Lint
npm run lint

# Run E2E tests (requires build first)
npm run build && npm run test:e2e

# Open demo (build first, then serve repo root)
npm run build && npx http-server ./ -p 8080
# → http://127.0.0.1:8080/demo/index.html

Publishing to npm

# Login to npm
npm login

# (Optional) Dry run to check what will be published
npm pack --dry-run

# Publish
npm publish

# Update version and publish
npm version patch  # or minor / major
npm publish

Project Structure

sautocomplete-suggestion/
├── src/
│   ├── index.ts          # Entry point, exports
│   ├── types.ts          # TypeScript interfaces
│   ├── core.ts           # Core vanilla logic (input, dropdown, staged, keyboard, history)
│   ├── matching.ts       # Accent-insensitive grouped matching
│   ├── matching.test.ts  # Unit tests for matching
│   ├── sanitizer.ts      # HTML escaping (XSS protection)
│   ├── sanitizer.test.ts # Unit tests for sanitizer
│   ├── highlight.ts      # Active word/entity highlight
│   ├── default-data.ts   # Default sample dataset (English)
│   ├── themes.ts         # Group badge color themes
│   ├── core.test.ts      # Unit tests for core
│   ├── styles.css        # Component styles (light + dark mode)
│   └── global.d.ts       # CSS module declaration
├── frameworks/
│   ├── react.tsx         # React wrapper
│   ├── vue.vue           # Vue wrapper
│   └── angular.ts        # Angular wrapper (full @Input/@Output)
├── demo/
│   ├── index.html        # Demo page (basic + dropup + custom groups + events log)
│   └── screenshot.png    # Demo screenshot
├── e2e/
│   ├── autocomplete.spec.ts  # Playwright E2E tests
│   ├── test-page.html        # Isolated E2E test page
│   └── server.js             # Dev server for E2E
├── dist/                 # Build output (git-ignored)
├── package.json
├── rollup.config.mjs     # Rollup build config (CSS + ESM + UMD + d.ts)
├── tsconfig.json         # TypeScript config
├── eslint.config.mjs     # ESLint config
├── vitest.config.ts      # Vitest config (unit tests)
├── playwright.config.ts  # Playwright config (E2E tests)
├── .gitignore
├── LICENSE
└── README.md

License

MIT