@universal-material/web 3.7.2 → 3.9.0

package/skills/setup/SKILL.md

@@ -0,0 +1,58 @@
+---
+description: Set up @universal-material/web in an app — install the package, import components, wire the Material Symbols font, and the optional CSS reset.
+---
+
+# Setting up @universal-material/web
+
+Use this whenever the user is bootstrapping a project (adding a new app, scaffolding a page from scratch) and hasn't yet imported the library.
+
+## 1. Install
+
+```bash
+npm install @universal-material/web
+```
+
+## 2. Import the components you need
+
+A single side-effect import registers every custom element and exposes the imperative APIs (`ThemeBuilder`, `Snackbar`, `Dialog`):
+
+```ts
+import '@universal-material/web';
+```
+
+For tree-shaken builds, import the components individually:
+
+```ts
+import '@universal-material/web/button/button.js';
+import '@universal-material/web/dialog/dialog.js';
+```
+
+## 3. Add the Material Symbols font
+
+All icons (`<span class="material-symbols-outlined">…</span>`) require the Google Material Symbols font in the document head:
+
+```html
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0..1,0" />
+```
+
+Add a system font (Roboto recommended) for the components themselves:
+
+```html
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,300;0,400;0,500;0,700&display=swap" />
+```
+
+## 4. Optional CSS reset / typography helpers
+
+The library ships an opinionated stylesheet with utility classes (`u-headline-l`, `u-label-m`, `u-container`, `u-grid`, etc.):
+
+```html
+<link rel="stylesheet" href="node_modules/@universal-material/web/css/universal-material.min.css" />
+```
+
+You can also `@import` the SCSS sources from `node_modules/@universal-material/web/scss/universal-material.scss` to opt into theme tokens at build time.
+
+## Caveats
+
+- Custom elements must be defined before they appear in HTML. If you parse HTML before the JS bundle loads, elements upgrade afterwards (Lit handles this gracefully, but property assignments before upgrade are not reactive).
+- The library uses Lit context. **Provider components must register before their consumers** — `import '@universal-material/web'` already orders them correctly; if you cherry-pick imports, register `scaffold` before `top-app-bar`/`fab`.
+- For the `<input type="date">` mask handling and `<dialog>` ergonomics, modern Chromium/Safari/Firefox are required.

package/skills/slider/SKILL.md

@@ -0,0 +1,119 @@
+---
+description: Use u-slider for single-thumb or two-thumb range value selection; wraps a native input[type=range] for keyboard, pointer, and form integration.
+---
+
+# Slider
+
+Material 3 Expressive slider with optional tick marks, floating value label, and range mode. Form-associated — set `name` to participate in `<form>` submission.
+
+## Continuous
+
+```html
+<u-slider min="0" max="100" value="40" aria-label="Volume"></u-slider>
+```
+
+## Discrete (ticks + value indicator while dragging)
+
+The 44dp circular value indicator appears centered above the active handle while the user drags.
+
+```html
+<u-slider discrete min="0" max="10" step="1" value="6" aria-label="Rating"></u-slider>
+```
+
+**Use `discrete` only when the number of stops is small enough to see.** The number of ticks rendered is `(max - min) / step`. Above ~15-20 stops the ticks crowd together, the track turns into a solid bar of dots, and the value indicator becomes the only readable signal — at that point you should drop `discrete` and use a continuous slider instead.
+
+Rule of thumb:
+- ✅ `min="0" max="10" step="1"` — 10 stops, ticks readable
+- ✅ `min="0" max="20" step="2"` — 10 stops
+- ⚠️ `min="0" max="100" step="5"` — 20 stops, borderline
+- ❌ `min="0" max="100" step="1"` — 100 stops, ticks become noise
+- ❌ `min="0" max="12000" step="100"` — 120 stops, looks broken
+
+For wide ranges where the **value** is what matters (price, MRR, score 0-100), use a continuous slider and render the current value separately:
+
+```html
+<u-slider id="preco" min="0" max="12000" step="100" value="3000" aria-label="Preço"></u-slider>
+<span id="preco-label" class="u-label-l">R$ 3.000</span>
+
+<script>
+  const s = document.getElementById('preco');
+  const l = document.getElementById('preco-label');
+  s.addEventListener('input', () => l.textContent = `R$ ${Number(s.value).toLocaleString('pt-BR')}`);
+</script>
+```
+
+Or use `slider.labelFormat` for the floating indicator (only visible while dragging — still helps for discrete sliders with ≤ ~15 stops, doesn't render the dense ticks):
+
+```js
+slider.labelFormat = (v) => `R$ ${v.toLocaleString('pt-BR')}`;
+```
+
+## Range (two thumbs)
+
+Set both `value-start` and `value-end` to enable range mode automatically. The handles clamp to each other so `value-start` cannot exceed `value-end`.
+
+```html
+<u-slider min="0" max="100" value-start="25" value-end="75" aria-label="Price range"></u-slider>
+```
+
+## Sizes
+
+Five M3 expressive size variants. The track height, handle height, state-layer size, and value-indicator typography scale together.
+
+```html
+<u-slider size="extra-small" value="40"></u-slider>
+<u-slider size="small" value="40"></u-slider>
+<u-slider size="medium" value="40"></u-slider>
+<u-slider size="large" value="40"></u-slider>
+<u-slider size="extra-large" value="40"></u-slider>
+```
+
+| size | track | handle | state-layer | typography |
+| --- | --- | --- | --- | --- |
+| `extra-small` (default) | 16dp | 4×44 | 40 | label-large |
+| `small` | 24dp | 4×52 | 48 | label-large |
+| `medium` | 40dp | 6×64 | 56 | title-medium |
+| `large` | 56dp | 6×80 | 68 | title-medium |
+| `extra-large` | 96dp | 8×120 | 96 | title-large |
+
+## Form integration
+
+```html
+<form>
+  <u-slider name="volume" min="0" max="100" value="40"></u-slider>
+  <u-slider name="price" range value-start="20" value-end="80"></u-slider>
+</form>
+```
+
+Range mode submits two entries: `price-start` and `price-end`.
+
+## Events
+
+- `input` — fires continuously while dragging (or on each keyboard step).
+- `change` — fires on commit (pointer up, blur).
+
+```ts
+const slider = document.querySelector('u-slider')!;
+slider.addEventListener('input', () => console.log(slider.value));
+```
+
+## Attributes
+
+- `min`, `max`, `step` — value bounds. Use `step="0"` for fully continuous values.
+- `value` — single-thumb mode.
+- `value-start`, `value-end` — range mode.
+- `range` — force range mode (auto-enabled when both `value-start` and `value-end` are present).
+- `discrete` — show ticks + floating label while dragging.
+- `ticks` — show ticks without enabling the label.
+- `disabled` — disable interaction (dims to 38% opacity).
+- `name` — form-association name.
+- `size` — `extra-small` (default), `small`, `medium`, `large`, `extra-large`.
+
+## Caveats
+
+- Range mode places two `<input type="range">` elements on top of each other. The handles are clamped via `min`/`max` on each input, so dragging beyond the other thumb is impossible by design.
+- The handle in M3 Expressive is a thin **bar** (4–8dp wide depending on size), not a circle. There is a 6dp gap between the handle and each adjacent track segment, and the track ends facing the handle have a 2dp inner corner radius. The gap collapses at min/max so the active bar always fills to the edge.
+- The handle does **not** narrow on press. The spec's narrow-on-press effect causes a 1-2dp jiggle in the bars when the press visual animates, which the project intentionally avoids — press feedback is the value indicator alone.
+- Hit area: the handle's hitbox matches the state-layer size (40–96dp depending on size). In range mode, the focused / hovered / actively-dragged handle is z-index-raised above the other so overlapping hitboxes resolve to the right one.
+- Exposed parts: `track`, `track-active`, `track-inactive-start` (range only), `track-inactive-end`, `thumb`, `thumb-end` (range only), `value-indicator`, `stop-indicator`.
+- Custom value formatting: assign a function to `slider.labelFormat`, e.g. `(v) => v.toFixed(1) + 'kg'`. Not settable via attribute.

package/skills/snackbar/SKILL.md

@@ -0,0 +1,70 @@
+---
+description: Show a snackbar (toast) imperatively via Snackbar.show — message, optional action button, duration, and close affordance.
+---
+
+# Snackbar
+
+Brief, transient messages shown at the bottom of the screen. Created imperatively — no markup needed.
+
+## Show a message
+
+```ts
+import { Snackbar } from '@universal-material/web';
+
+Snackbar.show({
+  message: 'Your changes have been saved.',
+});
+```
+
+## With an action
+
+```ts
+const sb = Snackbar.show({ message: 'Item deleted.', action: 'Undo' });
+// The action button fires an `actionClick` event on the returned snackbar.
+// There is NO `onAction` config option — passing one is silently ignored.
+sb.addEventListener('actionClick', () => undoDelete());
+```
+
+Clicking the action button fires `actionClick` and closes the snackbar.
+
+## Duration
+
+```ts
+import { Snackbar, SnackbarDuration } from '@universal-material/web';
+
+Snackbar.show({
+  message: 'Saved as draft',
+  duration: SnackbarDuration.long,   // 5000ms — this is the default when omitted
+});
+
+Snackbar.show({
+  message: 'Quick toast',
+  duration: SnackbarDuration.short,  // 2500ms
+});
+
+Snackbar.show({
+  message: 'Custom 6s',
+  duration: 6000,                    // any ms value
+});
+```
+
+Pass `duration: 0` (or `Infinity`) for a sticky snackbar that only closes on action or via the close button.
+
+## Close affordance
+
+```ts
+Snackbar.show({
+  message: 'Network request failed',
+  showClose: true,
+});
+```
+
+## Multiple snackbars
+
+Calling `.show()` while another snackbar is visible queues the new one — only one renders at a time.
+
+## Caveats
+
+- The snackbar mounts itself at the document level (escapes any scrim/dialog). To override its anchoring (e.g. inside a scaffold), customize `--u-snackbar-bottom-offset` on `:root`.
+- Don't use snackbars for errors that require user attention — use `<u-dialog>` (`Dialog.message()`/`.confirm()`) instead.
+- The snackbar API is imperative; for declarative usage, mount the element manually and toggle visibility, but it's almost never what you want.

package/skills/tab-bar/SKILL.md

@@ -0,0 +1,55 @@
+---
+description: Use u-tab-bar and u-tab for horizontally arranged content tabs with an animated underline indicator.
+---
+
+# Tab bar
+
+`<u-tab-bar>` groups a row of `<u-tab>`s and animates an underline indicator under the active tab.
+
+## Basic
+
+```html
+<u-tab-bar>
+  <u-tab active>Overview</u-tab>
+  <u-tab>Activity</u-tab>
+  <u-tab>Files</u-tab>
+  <u-tab>Members</u-tab>
+</u-tab-bar>
+```
+
+## Tracking the selected tab
+
+The bar fires a **`change`** event on user selection and exposes **`activeTabIndex`** / **`activeTab`** (read + write). Use these to switch the body view — more robust than reading `click` + `textContent`:
+
+```ts
+const bar = document.querySelector('u-tab-bar')!;
+bar.addEventListener('change', () => {
+  showPanel(bar.activeTabIndex);   // 0-based index of the selected tab
+});
+
+bar.activeTabIndex = 2;            // select programmatically (does NOT fire `change`)
+```
+
+There's also a cancelable `changing` event — call `preventDefault()` to block the switch. (`variant="primary" | "secondary"` chooses the indicator style.)
+
+## With icons
+
+```html
+<u-tab-bar>
+  <u-tab active>
+    <span class="material-symbols-outlined" slot="icon">home</span>
+    Home
+  </u-tab>
+  <u-tab>
+    <span class="material-symbols-outlined" slot="icon">search</span>
+    Search
+  </u-tab>
+</u-tab-bar>
+```
+
+## Caveats
+
+- The bar is meant for **content** tabs (switching the body view). For top-level navigation between pages, use `<u-navigation-bar>` (mobile) or `<u-drawer>` items.
+- `active` in markup sets the **initial** selection — put it on any `<u-tab>` (`<u-tab active>` on the second tab starts there). With no `active`, the first tab is selected. `tab.active` is read-only at runtime (derived from `bar.activeTab`); switch with `bar.activeTabIndex = n`.
+- Don't manually toggle `active` on multiple tabs at once — only one should be active. The bar enforces this on click but not on attribute writes.
+- The underline indicator animates between tabs via CSS. If you toggle `active` programmatically very fast, the indicator may skip frames.

package/skills/text-field/SKILL.md

@@ -0,0 +1,114 @@
+---
+description: Use u-text-field and u-text-area for text input — filled/outlined variants, validation, supporting text, char counter, prefix/suffix slots.
+---
+
+# Text field & text area
+
+Both `<u-text-field>` and `<u-text-area>` are form-associated, support M3 filled and outlined variants, and share the same field chrome (floating label, supporting text, error text, leading/trailing icons).
+
+## Basic text field
+
+```html
+<u-text-field label="Name"></u-text-field>
+<u-text-field label="Email" type="email" placeholder="you@example.com"></u-text-field>
+<u-text-field label="Password" type="password"></u-text-field>
+```
+
+## Variants
+
+```html
+<u-text-field label="Filled (default)"></u-text-field>
+<u-text-field label="Outlined" variant="outlined"></u-text-field>
+```
+
+Set a global default with `FieldBase.setDefaults(rootElement, { variant: 'outlined' })`.
+
+## Icons
+
+```html
+<u-text-field label="Search">
+  <span class="material-symbols-outlined" slot="leading-icon">search</span>
+  <u-icon-button slot="trailing-icon" type="button">
+    <span class="material-symbols-outlined">close</span>
+  </u-icon-button>
+</u-text-field>
+```
+
+## Prefix / suffix (text-field only)
+
+```html
+<u-text-field label="Amount" prefix-text="$" suffix-text="USD"></u-text-field>
+```
+
+## Supporting text, error text, char counter
+
+```html
+<u-text-field
+  label="Bio"
+  supporting-text="Tell us about yourself"
+  [maxlength]="120">
+</u-text-field>
+
+<u-text-field
+  label="Username"
+  error-text="Already taken"
+  invalid>
+</u-text-field>
+```
+
+- `supporting-text` — small caption under the field.
+- `error-text` + `invalid` — replaces the supporting text and tints the chrome red.
+- `maxlength` — drives an automatic `N/MAX` counter.
+- `hide-counter` — suppress the counter even when `maxlength` is set.
+
+## Multi-line
+
+`<u-text-area>` is the textarea equivalent; same API plus `rows`:
+
+```html
+<u-text-area label="Description" rows="4" maxlength="500"></u-text-area>
+```
+
+## Read-only / disabled
+
+```html
+<u-text-field label="ID" value="abc-123" readOnly></u-text-field>
+<u-text-field label="Locked" disabled></u-text-field>
+```
+
+## Validation
+
+`required`, `pattern`, `minlength` and `maxlength` are forwarded to the inner input and participate in **constraint validation** — they block native `<form>` submit and feed `checkValidity()` / `reportValidity()`:
+
+```html
+<u-text-field label="Email" type="email" required></u-text-field>
+<u-text-field label="ZIP" pattern="[0-9]{5}" minlength="5"></u-text-field>
+```
+
+```ts
+field.checkValidity();    // boolean; fires `invalid` if not valid
+field.reportValidity();   // also shows the native bubble + sets the visual `invalid` state
+field.validity.patternMismatch;   // live ValidityState
+field.validationMessage;          // localized message
+```
+
+For custom errors, keep driving `invalid` + `error-text` yourself (`field.invalid = true; field.errorText = 'Already taken'`).
+
+## Reading and writing the value
+
+Form integration via `ElementInternals` — the field participates in `<form>` submission and `FormData`. From JS:
+
+```ts
+const field = document.querySelector('u-text-field')!;
+field.value = 'hello';
+console.log(field.value);
+
+field.addEventListener('input', () => console.log(field.value));
+```
+
+## Caveats
+
+- The placeholder is hidden visually while the field is empty AND not focused so it doesn't collide with the floating label. Don't fight this with custom CSS — that's the M3 behavior.
+- For `type="date"` use `<u-datepicker>` (not `<u-text-field type="date">`) — the datepicker handles the calendar popover, the M3 chrome and the native browser-mask hiding.
+- Wrap inside `<form>` for native submit; `Enter` in the input triggers `form.requestSubmit()` automatically.
+- Constraint validation covers `required` / `pattern` / `minlength` / `maxlength`. Number `min` / `max` / `step` and `inputmode` are **not** forwarded yet — for those, validate in script and drive `invalid` + `error-text` yourself.

package/skills/theming/SKILL.md

@@ -0,0 +1,80 @@
+---
+description: Configure the app's Material 3 color theme via ThemeBuilder — seed color, dark mode, custom colors.
+---
+
+# Theming
+
+Use this when the user wants to set the app's primary color, switch dark/light mode, or customize Material 3 color tokens.
+
+## Seeding a theme from a single source color
+
+`ThemeBuilder.create(seed)` derives an entire M3 color palette (primary, secondary, tertiary, surface, etc.) from one hex color:
+
+```ts
+import { ThemeBuilder } from '@universal-material/web';
+
+const css = ThemeBuilder.create('#4f46e5').build();
+
+const style = document.createElement('style');
+style.id = 'theme-styles';
+style.textContent = css;
+document.head.appendChild(style);
+```
+
+The generated CSS sets variables on `:root` like `--u-color-primary`, `--u-color-on-primary`, `--u-color-secondary-container`, etc. Every component reads from these.
+
+## Reacting to a new color at runtime
+
+```ts
+function setTheme(hex: string): void {
+  const css = ThemeBuilder.create(hex).build();
+  document.getElementById('theme-styles')!.textContent = css;
+}
+```
+
+## Dark mode
+
+`ThemeBuilder` emits each token as a CSS `light-dark(<light>, <dark>)` value, so every color follows the document's **`color-scheme`**. With no override, that tracks the OS via `prefers-color-scheme`.
+
+To force a scheme, add the library's utility class to the **`<body>`** — `u-dark` or `u-light`. No class = follow the system:
+
+```html
+<body class="u-dark">…</body>   <!-- force dark -->
+<body class="u-light">…</body>  <!-- force light -->
+<body>…</body>                  <!-- system default -->
+```
+
+```ts
+// runtime toggle
+document.body.classList.remove('u-dark', 'u-light');
+document.body.classList.add(scheme === 'dark' ? 'u-dark' : 'u-light'); // add neither for "system"
+```
+
+`u-dark` / `u-light` set `color-scheme: dark/light !important` (plus the body text color), which is what `light-dark()` resolves against. There is **no** `theme` attribute hook — use these classes. For a "system / light / dark" toggle, persist the choice and apply the class at boot, before first paint.
+
+## Reading current token values
+
+```ts
+const primary = getComputedStyle(document.documentElement)
+  .getPropertyValue('--u-color-primary').trim();
+```
+
+This is useful when integrating non-component visuals (charts, illustrations) that need to follow the theme.
+
+## Overriding individual tokens
+
+You can override any token after the generated theme by setting the variable yourself:
+
+```css
+:root {
+  --u-color-primary: #2e7d32;            /* override seed-derived primary */
+  --u-shape-corner-large: 24px;          /* tune shape tokens */
+  --u-top-app-bar-container-color: transparent; /* component-specific */
+}
+```
+
+## Caveats
+
+- Call `ThemeBuilder` once at boot, before the first paint, to avoid a flash of unstyled colors.
+- The library reads tokens via CSS variables, so changing them at runtime updates every component live — no re-render needed.
+- Do **not** hardcode hex values in component CSS — always reference tokens (`var(--u-color-primary)`) so the theme controls the look.

package/skills/top-app-bar/SKILL.md

@@ -0,0 +1,64 @@
+---
+description: Add a top app bar to a screen — small/medium/large sizes, leading and trailing icons, scroll-driven collapse.
+---
+
+# Top app bar
+
+`<u-top-app-bar>` is the Material 3 top app bar: persistent strip at the top of a screen with headline, leading icon (menu/back), and trailing actions.
+
+## Basic small bar
+
+```html
+<u-top-app-bar headline="Inbox">
+  <u-icon-button slot="leading-icon">
+    <span class="material-symbols-outlined">menu</span>
+  </u-icon-button>
+  <u-icon-button slot="trailing-icon">
+    <span class="material-symbols-outlined">search</span>
+  </u-icon-button>
+</u-top-app-bar>
+```
+
+## Size variants
+
+```html
+<u-top-app-bar size="small"  headline="Small"></u-top-app-bar>
+<u-top-app-bar size="medium" headline="Medium"></u-top-app-bar>
+<u-top-app-bar size="large"  headline="Large"></u-top-app-bar>
+```
+
+- `small` (64dp) — default.
+- `medium` (112dp) and `large` (152dp) — render an "extended" headline area that fades out as the user scrolls.
+
+## Positioning
+
+| Mode | Anchored to | When to use |
+| --- | --- | --- |
+| `fixed` (default) | Viewport top. Slides with `--u-app-bar-offset` when a `u-side-navigation` drawer opens. | Standalone pages, side-navigation layouts. |
+| `absolute` | Nearest positioned ancestor. | Inside a `u-scaffold` (auto-set), or any custom container. |
+| `static` | In-flow, no special positioning. | Rare — when the bar should scroll with content. |
+
+Inside a `<u-scaffold>` the scaffold flips `position` to `absolute` automatically and feeds the bar its scroll container via context, so the scroll-driven collapse works without manual wiring.
+
+## Scroll-driven collapse
+
+For `medium`/`large` bars, the extended headline fades out as the user scrolls past it. The bar finds its scroll target in this order:
+
+1. Explicit `scrollContainer` attribute (`HTMLElement`, element id, `"window"`, or `"none"` to disable).
+2. The scroll container provided by an ancestor `<u-scaffold>` via Lit context.
+3. `window` (default).
+
+## Customizing colors
+
+```css
+u-top-app-bar {
+  --u-top-app-bar-container-color: var(--u-color-surface);
+  --u-top-app-bar-on-scroll-container-color: var(--u-color-surface-container);
+  --u-top-app-bar-text-color: var(--u-color-on-surface);
+}
+```
+
+## Caveats
+
+- Don't put the headline inside the `leading-icon` / `trailing-icon` slots — those are reserved for `<u-icon-button>`s. Use the `headline` attribute or the default slot.
+- When inside `<u-scaffold>`, do **not** set `position="fixed"` — the scaffold's container clips the bar to itself, and fixed-to-viewport would escape the layout.

package/skills/typeahead/SKILL.md

@@ -0,0 +1,113 @@
+---
+description: Build an autocomplete / typeahead with u-typeahead — a controller attached to a text field via target-id, with sync/async sources, object results, custom item templates, and match highlighting.
+---
+
+# Typeahead
+
+`<u-typeahead>` is **not** a field — it's a controller that attaches to a separate input (`<u-text-field>` or a native input) and opens a popover of suggestions as the user types. You give it a `source`; it renders the dropdown and emits a `selected` event.
+
+> **Key shape (easy to get wrong):** the typeahead has no label/field of its own. Pair it with a field via `target-id`. A standalone `<u-typeahead label="…">` renders nothing.
+
+## Simple string suggestions
+
+```html
+<u-text-field id="country-input" label="Country"></u-text-field>
+<u-typeahead target-id="country-input"></u-typeahead>
+
+<script>
+  const countries = ['Argentina', 'Brazil', 'Chile', 'Spain', 'United States'];
+  const ta = document.querySelector('u-typeahead');
+  // `source` = an array, or a (term) => Array | Promise<Array>
+  ta.source = (term) => countries.filter(c => c.toLowerCase().includes(term.toLowerCase()));
+</script>
+```
+
+When `source` is a plain array, the component filters it internally by case-insensitive substring. When it's a function, you do the filtering and may return a `Promise`.
+
+## Attaching to any input (`target-id`)
+
+`target-id` can point to **any** input — not only `<u-text-field>`. The typeahead reads `target.input?.value ?? target.value` and listens for the target's `input` event, so it works with:
+
+- `<u-search>` — the M3 search bar; this is the **idiomatic pairing** (the popover anchors to its input). See the **search** skill.
+- `<u-text-field>` / `<u-text-area>`.
+- `<u-chip-field>` — multi-select chips.
+- a plain native `<input>`, or any element from **another library** that exposes a `.value` and fires an `input` event.
+
+```html
+<u-search id="q" position="static"><span class="material-symbols-outlined" slot="leading-icon">search</span></u-search>
+<u-typeahead target-id="q"></u-typeahead>
+
+<!-- a native input (or a non-u-* component) works too -->
+<input id="q2" />
+<u-typeahead target-id="q2"></u-typeahead>
+```
+
+The popover anchors to the target's natural box: the search / text-field's inner input or container, or the bare element for a native input.
+
+## Object results + label mapping
+
+```html
+<u-text-field id="user-input" label="User"></u-text-field>
+<u-typeahead target-id="user-input"></u-typeahead>
+
+<script>
+  const ta = document.querySelector('u-typeahead');
+  ta.source = async (term) => {
+    const r = await fetch(`/api/users?q=${encodeURIComponent(term)}`);
+    return await r.json(); // [{ id, name, email }]
+  };
+  // `formatter` maps an object value to the displayed string (input + default option label)
+  ta.formatter = (u) => u.name;
+</script>
+```
+
+## Custom option rendering
+
+`template` is a **function** returning a string / `HTMLElement` / Lit `TemplateResult` per option (not a `<template>` element):
+
+```js
+import { html } from 'lit';
+ta.template = (term, user) => html`
+  <div style="display:flex; align-items:center; gap:8px">
+    <span>${user.name}</span>
+    <span class="u-label-s u-text-low-emphasis">${user.email}</span>
+  </div>`;
+```
+
+`<u-highlight text="..." match="...">` wraps the matched substring of the query in a styled span — useful inside a template to show why a suggestion matched.
+
+## Selection
+
+```ts
+const ta = document.querySelector('u-typeahead')!;
+ta.addEventListener('selected', (e: CustomEvent) => {
+  console.log('Selected:', e.detail); // the chosen value (string or object)
+});
+```
+
+The event is **`selected`** (cancelable; `e.detail` is the value). There is no `select` event.
+
+## Useful properties / attributes
+
+| Name | Default | Purpose |
+| --- | --- | --- |
+| `target-id` | — | **Required.** Id of the input/field the typeahead drives. |
+| `source` (prop) | — | Array, or `(term) => Array \| Promise<Array>`. |
+| `formatter` (prop) | `String(value)` | Maps an object value to its displayed label. |
+| `template` (prop) | — | `(term, value) => string \| HTMLElement \| TemplateResult` per option. |
+| `minlength` | `2` | Min chars before suggestions show. **Array sources show nothing until 2 chars** unless lowered. |
+| `debounce` | `300` (ms) | Debounce before `source` is called. |
+| `limit` | — | Max options shown. |
+| `open-on-focus` | off | Open the popover on focus (before typing). |
+| `editable` | — | Allow free text alongside suggestions. |
+| `positioning="fixed"` | — | Let the popover escape an `overflow:hidden`/scroll wrapper. |
+| `clear()` (method) | — | Clear the current value. |
+
+For multi-select with chips, drive a `<u-chip-field>` from a typeahead instead.
+
+## Caveats
+
+- **No `optionsProvider` / `labelField` / `select`.** Those don't exist — use `source` / `formatter` / the `selected` event. A standalone `<u-typeahead label="…">` (no `target-id`) renders nothing.
+- `source` is called on every keystroke (after `debounce`) — for remote data, abort in-flight requests (`AbortController`).
+- The component does not de-duplicate — dedupe in your `source`.
+- `positioning="fixed"` is needed inside a `<u-scaffold>`'s scrolling `<main>`.