@universal-material/web 3.7.2 → 3.9.0

package/skills/navigation-bar/SKILL.md

@@ -0,0 +1,87 @@
+---
+description: Build a Material 3 navigation bar — destinations with icon + label, vertical or horizontal layout, active indicator pill.
+---
+
+# Navigation bar
+
+`<u-navigation-bar>` hosts 3–5 top-level destinations at the bottom of a screen. Use `<u-navigation-bar-item>` for each destination — they render the active indicator pill, icon, and label per M3 expressive tokens.
+
+## Default (vertical) layout
+
+```html
+<u-navigation-bar>
+  <u-navigation-bar-item active>
+    <span class="material-symbols-outlined" slot="icon">home</span>
+    Home
+  </u-navigation-bar-item>
+  <u-navigation-bar-item>
+    <span class="material-symbols-outlined" slot="icon">explore</span>
+    Browse
+  </u-navigation-bar-item>
+  <u-navigation-bar-item>
+    <span class="material-symbols-outlined" slot="icon">radio</span>
+    Radio
+  </u-navigation-bar-item>
+  <u-navigation-bar-item>
+    <span class="material-symbols-outlined" slot="icon">library_music</span>
+    Library
+  </u-navigation-bar-item>
+</u-navigation-bar>
+```
+
+M3 tokens applied automatically:
+- container: 64dp height, `surface-container` color, level-2 elevation
+- active indicator pill: 56×32dp, `secondary-container`
+- icon: 24dp, `on-secondary-container` (active) / `on-surface-variant` (inactive)
+- label: label-medium, `secondary` (active) / `on-surface-variant` (inactive)
+
+## Horizontal variant
+
+For wider items where icon and label sit side-by-side inside a 40dp pill:
+
+```html
+<u-navigation-bar>
+  <u-navigation-bar-item variant="horizontal" active>
+    <span class="material-symbols-outlined" slot="icon">home</span>
+    Home
+  </u-navigation-bar-item>
+  <u-navigation-bar-item variant="horizontal">
+    <span class="material-symbols-outlined" slot="icon">explore</span>
+    Browse
+  </u-navigation-bar-item>
+</u-navigation-bar>
+```
+
+## Slots on `<u-navigation-bar-item>`
+
+| Slot | Content |
+| --- | --- |
+| default | Destination label (text). |
+| `icon` | 24dp icon (`<span class="material-symbols-outlined">…</span>`). |
+| `badge` | Optional `<u-badge>` — auto-positions over the icon. |
+
+## Tracking selection
+
+```html
+<u-navigation-bar id="nav">…</u-navigation-bar>
+
+<script>
+  const nav = document.getElementById('nav');
+  nav.addEventListener('click', (e) => {
+    const item = e.target.closest('u-navigation-bar-item');
+    if (!item) return;
+    [...nav.children].forEach(i => i.active = i === item);
+  });
+</script>
+```
+
+In Angular/React, bind `[active]="route === 'home'"` on each item and switch the route on click.
+
+## Positioning
+
+Same model as `<u-top-app-bar>`: `position="fixed"` by default (viewport bottom), or `position="absolute"` when slotted in a `<u-scaffold>` (auto-set). The internal `.spacing` filler reserves the bar's height in the scrolled flow so content isn't obscured.
+
+## Caveats
+
+- Each item should have an icon AND a label per M3 spec; icon-only items look broken at 64dp.
+- Don't use `<u-icon-button>` instead of `<u-navigation-bar-item>` — you'll lose the active indicator pill, label, and badge slot.

package/skills/navigation-rail/SKILL.md

@@ -0,0 +1,127 @@
+---
+description: Build a Material 3 responsive navigation rail — hidden on mobile, collapsed 96dp rail on medium with primary items, permanent expanded rail (220–360dp) on large with the full menu (including headlines). Two slots crossfade between the two states.
+---
+
+# Navigation rail
+
+`<u-navigation-rail>` is a responsive primary navigation surface with two independently configurable destination sets — one short list for the collapsed state, and an optional longer/grouped list for the expanded state. The two share the same on-screen area and the rail crossfades between them as it grows or shrinks.
+
+## Responsive behavior
+
+- **Mobile (< 840px)**: rail is hidden. Provide a different nav pattern (e.g. `<u-navigation-bar>`) for small screens.
+- **Medium (840–1199px)**: rail is a permanent 96dp **collapsed** sidebar showing `slot="rail"` items.
+- **Large (≥ 1200px)**: rail is permanently **expanded** (220–360dp, default 360dp), showing `slot="expanded"` items grouped by `<u-navigation-rail-headline>`s. `toggle-drawer` collapses it back to the 96dp width and crossfades to the `slot="rail"` list. If `slot="expanded"` is empty, the rail keeps showing `slot="rail"` items even when expanded.
+
+## Basic usage
+
+```html
+<u-navigation-rail id="nav">
+  <!-- Collapsed: short list of primary destinations -->
+  <u-navigation-rail-item slot="rail" active>
+    <span class="material-symbols-outlined" slot="icon">home</span>
+    Home
+  </u-navigation-rail-item>
+  <u-navigation-rail-item slot="rail">
+    <span class="material-symbols-outlined" slot="icon">explore</span>
+    Browse
+  </u-navigation-rail-item>
+  <u-navigation-rail-item slot="rail">
+    <span class="material-symbols-outlined" slot="icon">library_music</span>
+    Library
+  </u-navigation-rail-item>
+
+  <!-- Expanded: full menu, grouped with headlines -->
+  <u-navigation-rail-headline slot="expanded">Library</u-navigation-rail-headline>
+  <u-navigation-rail-item slot="expanded" active>
+    <span class="material-symbols-outlined" slot="icon">home</span>
+    Home
+  </u-navigation-rail-item>
+  <u-navigation-rail-item slot="expanded">
+    <span class="material-symbols-outlined" slot="icon">explore</span>
+    Browse
+  </u-navigation-rail-item>
+
+  <u-navigation-rail-headline slot="expanded">Recents</u-navigation-rail-headline>
+  <u-navigation-rail-item slot="expanded">
+    <span class="material-symbols-outlined" slot="icon">favorite</span>
+    Favorites
+  </u-navigation-rail-item>
+
+  <u-scaffold>
+    <u-top-app-bar slot="top-bar" headline="Mail">
+      <u-icon-button slot="leading-icon"
+        onclick="const r = this.closest('u-navigation-rail'); r.toggleDrawer = !r.toggleDrawer;">
+        <span class="material-symbols-outlined">menu</span>
+      </u-icon-button>
+    </u-top-app-bar>
+    <div>Page content</div>
+  </u-scaffold>
+</u-navigation-rail>
+```
+
+## Slots on `<u-navigation-rail>`
+
+| Slot | Content | Shown when |
+| --- | --- | --- |
+| `rail` | Primary destinations (`<u-navigation-rail-item>`s). | Collapsed state (mobile is hidden; md is permanent; lg shows when `toggle-drawer` is set). |
+| `expanded` | Full destination list — items + `<u-navigation-rail-headline>`s. | Expanded state (lg without `toggle-drawer`). Falls back to `rail` when empty. |
+| `top` | Menu button, brand mark, or other top-pinned content. | Always (within visible rail). |
+| `bottom` | FAB or secondary action pinned to the bottom. | Always (within visible rail). |
+| default | Page content (typically `<u-scaffold>`). | Always. |
+
+The rail crossfades (200ms) between the `rail` and `expanded` layers when its state changes.
+
+## `<u-navigation-rail-item>`
+
+The rail sets the item's `variant` automatically based on which slot it lives in:
+
+- Inside `slot="rail"`: `variant="collapsed"` (vertical icon + label, 56×32dp pill around the icon, label-medium).
+- Inside `slot="expanded"`: `variant="expanded"` (horizontal icon + label inside a content-sized 56dp pill aligned to the leading edge with 16dp inset; label-large).
+
+Slots: default (label), `icon` (24dp icon), `badge` (optional `<u-badge>`).
+
+```html
+<u-navigation-rail-item slot="expanded" active>
+  <span class="material-symbols-outlined" slot="icon">inbox</span>
+  Inbox
+  <u-badge slot="badge">12</u-badge>
+</u-navigation-rail-item>
+```
+
+## `<u-navigation-rail-headline>`
+
+Section header for grouping destinations inside `slot="expanded"`. Renders title-small typography in `on-surface-variant`, with M3-correct padding. Only visible while the rail is expanded — headlines never appear in the narrow collapsed form, since the collapsed `slot="rail"` is a separate, headline-free list.
+
+```html
+<u-navigation-rail-headline slot="expanded">Recents</u-navigation-rail-headline>
+```
+
+## Tokens applied (M3 expressive spec)
+
+Sources: `md.comp.nav-rail`, `md.comp.nav-rail-collapsed`, `md.comp.nav-rail-expanded`, `md.comp.nav-rail-item`, `md.comp.nav-rail-item-vertical`, `md.comp.nav-rail-item-horizontal`.
+
+- **Rail container**: 96dp width (collapsed default; 80dp narrow opt-in) / 220–360dp width (expanded); `surface` color; level-0 elevation; `corner-none`; 44dp top space; 20dp vertical-trailing space.
+- **Item container**: 64dp height (default); 4dp gap between items (collapsed) / 0dp (expanded).
+- **Active indicator**: `secondary-container` background; `corner-full` shape; 56×32dp pill (collapsed/vertical) / content-sized 56dp pill (expanded/horizontal) aligned to the 16dp leading edge.
+- **Icon**: 24dp; `on-secondary-container` (active) / `on-surface-variant` (inactive).
+- **Label**: label-medium 12sp (collapsed) / label-large 14sp (expanded). Active color is `secondary` (collapsed/vertical) or `on-secondary-container` (expanded/horizontal); inactive is `on-surface-variant`. Active items use `weight-prominent` (700 / bold).
+- **State layer**: `on-secondary-container` color; hover 8%, focus 10%, pressed 10% — applied **only inside the active-indicator pill**. Click target remains the entire item, ripples confined to the pill via `u-ripple` inside the indicator.
+
+## The two slots are the SAME navigation at two detail levels — not two different menus
+
+`slot="rail"` (collapsed) and `slot="expanded"` are the **same destination set** shown at two levels of detail: collapsed = icons only; expanded = icons + labels grouped under headlines. They are *not* a place to put two different navigations.
+
+A tempting-but-wrong idea: make the collapsed rail the product nav (Mail, Chat, Meet) and the expanded rail the current section's sub-navigation (mail folders — Inbox, Starred, Sent…). This breaks the user's mental model: toggling the rail should reveal *more detail about the same destinations*, not **swap** what the rail navigates. A user who expands the rail expecting fuller product labels instead finds an unrelated folder list. Don't do this.
+
+Where section sub-navigation belongs instead:
+- **A small set of peer views** (e.g. "All / Unread / Starred"): a `u-chip-set` or `u-tab-bar` in the list header.
+- **A genuinely large folder tree** that warrants its own surface: a separate `<u-pane>` with a `<u-drawer>` — but first ask whether the screen actually needs it. A CRM "inbox" is a list of conversations; it usually does **not** need Gmail-style Sent/Drafts/Trash folders at all. Cut the layer rather than house it.
+
+The rail carries **product-level** destinations only. If a sub-navigation doesn't fit as collapsed-icon + expanded-label of those same destinations, it doesn't belong in the rail.
+
+## Caveats
+
+- Don't slot a `<u-drawer>`: the expanded rail is a distinct M3 surface with its own pill-shaped items, not a drawer.
+- Mobile (< 840px) hides the rail entirely — give small screens a different nav (`<u-navigation-bar>`, modal etc).
+- `slot="top"` / `slot="bottom"` children are sized intrinsically (not stretched), and align horizontally based on the rail state — centered when collapsed, leading-aligned with 16dp inset when expanded.
+- The expanded layer scrolls when its content overflows the rail height; the collapsed layer does too if you slot more than ~5 items.

package/skills/overview/SKILL.md

@@ -0,0 +1,44 @@
+---
+description: Overview of @universal-material/web — what's in the library and which skills cover each area.
+---
+
+# @universal-material/web — overview
+
+Material Design 3 web components built with Lit. Custom elements with the `u-` prefix; class names match the tag without the prefix (`<u-button>` → `class Button`).
+
+## What's inside
+
+| Area | Components | Skill |
+| --- | --- | --- |
+| Bootstrap | install, fonts, theme | `setup`, `theming` |
+| Layout | `<u-scaffold>` | `scaffold` |
+| App bars | `<u-top-app-bar>`, `<u-navigation-bar>` | `top-app-bar`, `navigation-bar` |
+| Navigation | `<u-side-navigation>`, `<u-drawer>` | `drawer` |
+| Common buttons | `<u-button>`, `<u-icon-button>`, `<u-button-set>` | `buttons` |
+| FAB | `<u-fab>`, `<u-fab-menu>` | `fab` |
+| Dialogs | `<u-dialog>` + `Dialog.message/.confirm` | `dialog` |
+| Text input | `<u-text-field>`, `<u-text-area>` | `text-field` |
+| Select | `<u-select>`, `<u-option>` | `select` |
+| Chips | `<u-chip>`, `<u-chip-set>`, `<u-chip-field>` | `chips` |
+| Selection controls | `<u-checkbox>`, `<u-radio>`, `<u-switch>` + list-items | `selection-controls` |
+| Date | `<u-datepicker>`, `<u-range-datepicker>`, `<u-calendar>` | `datepicker` |
+| Menus | `<u-menu>`, `<u-menu-item>`, `<u-overflow-menu>` | `menu` |
+| Lists | `<u-list>`, `<u-list-item>` | `list` |
+| Tabs | `<u-tab-bar>`, `<u-tab>` | `tab-bar` |
+| Feedback | `Snackbar.show` | `snackbar` |
+| Progress | `<u-progress-bar>`, `<u-circular-progress>` | `progress` |
+| Badge | `<u-badge>` | `badge` |
+| Cards | `<u-card>`, `<u-card-content>`, `<u-card-media>` | `card` |
+| Autocomplete | `<u-typeahead>`, `<u-highlight>` | `typeahead` |
+| Search | `<u-search>` (M3 search bar; pairs with `u-typeahead`) | `search` |
+
+## Core conventions
+
+- Custom elements have the `u-` prefix; class names are unprefixed PascalCase (`<u-top-app-bar>` → `class TopAppBar`).
+- Every component exposes its main inner boxes via `part` attributes — style externally with `::part(container)` etc.
+- Theming is driven by CSS variables (`--u-color-primary`, ...). Use `ThemeBuilder.create(seedHex).build()` once at boot.
+- Slot names match what they hold (`leading-icon`, `trailing-icon`, `headline`, `actions`, ...).
+- Form-associated components participate in `<form>` submission natively.
+- Major version follows Material spec version (M3 → `3.x`).
+
+When unsure which skill to use, this overview maps it out.

package/skills/progress/SKILL.md

@@ -0,0 +1,63 @@
+---
+description: Show determinate or indeterminate progress — u-progress-bar (linear) and u-circular-progress (ring).
+---
+
+# Progress indicators
+
+Two components share the same value API: `<u-progress-bar>` (linear, M3 4dp track) and `<u-circular-progress>` (ring).
+
+## Determinate
+
+`value` is a number; `max` defaults to `1`. So `value` is a fraction `0–1`, or pass a `max`:
+
+```html
+<u-progress-bar value="0.81"></u-progress-bar>           <!-- 81% -->
+<u-progress-bar value="81" max="100"></u-progress-bar>   <!-- same -->
+
+<u-circular-progress value="0.66"></u-circular-progress>
+```
+
+## Indeterminate
+
+Omit `value` (or set it to `undefined`) for the looping animation:
+
+```html
+<u-progress-bar></u-progress-bar>
+<u-circular-progress></u-circular-progress>
+```
+
+## Setting value from JS
+
+```ts
+const bar = document.querySelector('u-progress-bar')!;
+bar.value = 0.4;        // determinate
+bar.value = undefined;  // back to indeterminate
+```
+
+## Sizing & color (tokens)
+
+- **`<u-progress-bar>` is not full-width by default** — give it `display: block` (or a width) to span its container:
+  ```html
+  <u-progress-bar value="0.5" style="display: block"></u-progress-bar>
+  ```
+- **`<u-circular-progress>`** size via `--u-circular-progress-size` (default `3rem`):
+  ```html
+  <u-circular-progress value="0.81" style="--u-circular-progress-size: 96px"></u-circular-progress>
+  ```
+  Arc color `--u-circular-progress-color` (default `primary`); track `--u-circular-progress-track-color` (default `secondary-container`).
+
+## Centered label in a ring (gauge)
+
+Wrap the ring in a `position: relative` box and absolutely-center the label:
+
+```html
+<div style="position: relative; width: 96px; height: 96px">
+  <u-circular-progress value="0.81" style="--u-circular-progress-size: 96px"></u-circular-progress>
+  <div style="position: absolute; inset: 0; display: flex; align-items: center; justify-content: center">81%</div>
+</div>
+```
+
+## Caveats
+
+- Determinate values are rounded (~2 decimals circular / 1 decimal bar) — sub-pixel differences won't render.
+- Use indeterminate for unknown-duration waits; determinate when you can compute the fraction.