@universal-material/web 3.8.0 → 3.9.0

package/skills/search/SKILL.md

@@ -0,0 +1,65 @@
+---
+description: Use u-search — the Material 3 search bar (rounded input with leading/trailing icon slots), optionally driven by u-typeahead for suggestions.
+---
+
+# Search
+
+`<u-search>` is the Material 3 **search bar**: a rounded, single-line input with leading/trailing icon slots. It is form-associated (`value`, submits its `<form>` on Enter) and is the idiomatic input to pair with `<u-typeahead>` for autocomplete.
+
+Use it for a search box; use `<u-text-field>` for a labeled form field.
+
+## Basic
+
+```html
+<u-search placeholder="Search">
+  <span class="material-symbols-outlined" slot="leading-icon">search</span>
+</u-search>
+```
+
+Slots: `leading-icon`, `trailing-icon` (e.g. a clear/voice button). Parts: `input`, `icon` / `leading` / `trailing`.
+
+## Position
+
+```html
+<u-search position="static"></u-search>    <!-- in-flow, inline (toolbar / pane header) -->
+<u-search position="fixed"></u-search>     <!-- floating bar (default) -->
+<u-search position="absolute"></u-search>
+```
+
+`position` defaults to **`fixed`** (the floating M3 search bar). For a search input that sits inline in a header/toolbar, use `position="static"`.
+
+## Reading the value
+
+```ts
+const search = document.querySelector('u-search')!;
+search.value;                               // current text (form-associated)
+search.addEventListener('input', () => …);  // fires as the user types
+// Enter submits the associated <form> (form.requestSubmit()).
+```
+
+Other props: `placeholder`, `autocomplete`, `maxlength`, `role`.
+
+## With suggestions (`u-typeahead`)
+
+`<u-search>` is the idiomatic target for `<u-typeahead>` — the suggestions popover anchors to the search input:
+
+```html
+<u-search id="q" position="static" placeholder="Search clients">
+  <span class="material-symbols-outlined" slot="leading-icon">search</span>
+</u-search>
+<u-typeahead target-id="q" positioning="fixed"></u-typeahead>
+
+<script>
+  const ta = document.querySelector('u-typeahead');
+  ta.source = (term) => clients.filter((c) => c.name.toLowerCase().includes(term.toLowerCase()));
+  ta.formatter = (c) => c.name;
+  ta.addEventListener('selected', (e) => openClient(e.detail));
+</script>
+```
+
+See the **typeahead** skill for the full suggestions API.
+
+## Caveats
+
+- It's a search **bar**, not a labeled field — use `placeholder`; there is no floating label. For a labeled form input use `<u-text-field>`.
+- Default `position` is `fixed` (floating). Set `position="static"` to keep it inline in a header/toolbar.

package/skills/select/SKILL.md

@@ -0,0 +1,120 @@
+---
+description: Use u-select — a Material 3 dropdown built on the field chrome, with u-option children, supporting text and validation.
+---
+
+# Select
+
+`<u-select>` is a form-associated dropdown that opens a `<u-menu>` of `<u-option>` children. It shares the field chrome with `<u-text-field>` (label, supporting/error text, leading/trailing icons).
+
+## Basic usage
+
+```html
+<u-select label="Country">
+  <u-option value="br">Brazil</u-option>
+  <u-option value="us">United States</u-option>
+  <u-option value="es">Spain</u-option>
+  <u-option value="jp">Japan</u-option>
+</u-select>
+```
+
+## Variants and helpers
+
+```html
+<u-select label="Country" variant="outlined" supporting-text="Pick where you live">
+  …
+</u-select>
+
+<u-select label="Country" error-text="Required" invalid>
+  …
+</u-select>
+```
+
+## Programmatic value
+
+```ts
+const select = document.querySelector('u-select')!;
+select.value = 'br';        // set
+console.log(select.value);  // get
+
+select.addEventListener('change', () => console.log(select.value));
+```
+
+## Initial selection (in markup)
+
+Like the native `<select>`, there is **no `value` attribute** — set the initial selection with `selected` on the option (or assign `.value` in JS after upgrade). With neither, the first enabled option is selected.
+
+```html
+<u-select label="Country">
+  <u-option value="br">Brazil</u-option>
+  <u-option value="us" selected>United States</u-option>
+</u-select>
+```
+
+## Icons in options
+
+```html
+<u-select label="Theme">
+  <u-option value="auto">
+    <span class="material-symbols-outlined" slot="icon">brightness_4</span>
+    System
+  </u-option>
+  <u-option value="light">
+    <span class="material-symbols-outlined" slot="icon">light_mode</span>
+    Light
+  </u-option>
+  <u-option value="dark">
+    <span class="material-symbols-outlined" slot="icon">dark_mode</span>
+    Dark
+  </u-option>
+</u-select>
+```
+
+## Positioning inside clipped containers
+
+When the select sits inside a scrollable/clipped wrapper, set `menu-positioning="fixed"` so the dropdown escapes its bounds:
+
+```html
+<u-select label="Country" menu-positioning="fixed">…</u-select>
+```
+
+## Disabled / read-only
+
+```html
+<u-select label="Country" disabled>…</u-select>
+<u-select label="Country" readOnly>…</u-select>
+```
+
+## Required / validation
+
+`required` participates in constraint validation and blocks native form submit. Because a select with options always has a selection, add an **empty-valued placeholder option** so "nothing chosen" is representable:
+
+```html
+<u-select label="Country" required error-text="Please choose a country">
+  <u-option value="">Choose…</u-option>
+  <u-option value="br">Brazil</u-option>
+  <u-option value="us">United States</u-option>
+</u-select>
+```
+
+```ts
+select.checkValidity();    // boolean (fires `invalid` if not)
+select.reportValidity();   // also shows the bubble + sets the visual `invalid` state
+```
+
+## When NOT to use `<u-select>`
+
+- Free-text input with suggestions → use `<u-typeahead>`.
+- Multi-select chip input → use `<u-chip-field>`.
+- A non-form action menu (Edit/Delete/Share) → use `<u-button>` + `<u-menu>` directly.
+
+## SPA / framework binding
+
+The select keeps its selection when the framework **re-renders the `<u-option>` list** (e.g. an `*ngFor`/`v-for`). It remembers the last value you set (via `.value`/`.selectedIndex`, a click, or `<u-option selected>`) and re-applies it once the matching option is present — so you don't need to re-assign `.value` after the options change. Setting `.value` **before** the options exist (async load) also works: it applies when that option appears. The first-option default is *not* sticky, matching the native `<select>`.
+
+## Caveats
+
+- The displayed value is the matching `<u-option>`'s text content. Keep option text concise. **An icon inside an option** (`<span slot="icon">`) shows in the dropdown but its ligature text leaks into the *closed* select's displayed value (e.g. "groups Todos") — omit option icons when the value is shown as text.
+- **Single-select only** — there is no `multiple` attribute. For multiple values use `<u-chip-field>`.
+- `required` only triggers when the current value is empty; without an empty-valued option the select always has a non-empty value and so is always valid.
+- For long lists, the menu virtualizes after a threshold but very large lists (1000+) feel sluggish — consider a typeahead instead.
+- Don't put non-`u-option` children inside `<u-select>` — they're ignored.

package/skills/selection-controls/SKILL.md

@@ -0,0 +1,88 @@
+---
+description: Use u-checkbox, u-radio, u-switch — and their u-*-list-item variants for selection lists.
+---
+
+# Selection controls — checkbox, radio, switch
+
+All three are form-associated and share API conventions: `checked`, `disabled`, `value`, `name`, plus a `change` event.
+
+## Checkbox
+
+```html
+<u-checkbox></u-checkbox>
+<u-checkbox checked></u-checkbox>
+<u-checkbox indeterminate></u-checkbox>
+<u-checkbox disabled></u-checkbox>
+```
+
+With a label, either inline or via `<u-checkbox-list-item>`:
+
+```html
+<label class="flex items-center gap-2">
+  <u-checkbox></u-checkbox>
+  Subscribe to newsletter
+</label>
+```
+
+## Radio
+
+```html
+<u-radio name="color" value="red"></u-radio>
+<u-radio name="color" value="green" checked></u-radio>
+<u-radio name="color" value="blue"></u-radio>
+```
+
+`name` groups them — only one in a group can be checked. Listen on each, or use a wrapping `<form>` and read `FormData`.
+
+## Switch
+
+```html
+<u-switch></u-switch>
+<u-switch checked></u-switch>
+<u-switch disabled></u-switch>
+```
+
+Same API as the checkbox.
+
+## List-item variants
+
+For settings screens with rows of controls, use the `u-*-list-item` components — they render a `<u-list-item>` with the control on the trailing side and a label/supporting-text on the leading side. Drop them inside a `<u-list>`:
+
+```html
+<u-list>
+  <u-switch-list-item checked>
+    Wi-Fi
+    <span slot="supporting-text">Connected to "Office"</span>
+  </u-switch-list-item>
+
+  <u-switch-list-item>
+    Bluetooth
+    <span slot="supporting-text">Off</span>
+  </u-switch-list-item>
+
+  <u-checkbox-list-item>
+    Show passwords
+  </u-checkbox-list-item>
+
+  <u-radio-list-item name="theme" value="light">Light</u-radio-list-item>
+  <u-radio-list-item name="theme" value="dark" checked>Dark</u-radio-list-item>
+</u-list>
+```
+
+The list items handle the click on the whole row (toggling the control), the ripple, and the spacing.
+
+## Programmatic
+
+```ts
+const cb = document.querySelector('u-checkbox')!;
+cb.checked = true;
+cb.addEventListener('change', () => console.log(cb.checked));
+```
+
+## Caveats
+
+- `<u-checkbox>` and `<u-switch>` emit `change` on every toggle; `<u-radio>` emits `change` only on the newly-selected radio in a group (not on deselected siblings).
+- `indeterminate` is visual only — `checked` still reads the underlying boolean. For **dynamically-built DOM** (innerHTML / generated rows) set it via the **property** after upgrade (`cb.indeterminate = true`), not the markup attribute. Setting `checked = true` clears `indeterminate`.
+- `change` **bubbles**, so you can delegate it on an ancestor (e.g. a `<tbody>`) for bulk-selection — `wrapper.addEventListener('change', e => e.target.closest('u-checkbox') && …)` works.
+- For groups of switches/checkboxes in settings, prefer the `*-list-item` variants — they're keyboard-accessible across the whole row and follow the M3 list spec.
+- The `*-list-item` variants accept **`no-inset`** — pulls the row flush with surrounding content (a negative inline margin equal to the inline padding) so it lines up with the section heading/labels. See the **list** skill.

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.