@universal-material/web 3.7.2 → 3.9.0

package/skills/datepicker/SKILL.md

@@ -0,0 +1,110 @@
+---
+description: Use u-datepicker and u-range-datepicker — calendar popover for single or range date selection, with editable input mode, locales, and display formats.
+---
+
+# Date picker
+
+`<u-datepicker>` (single date) and `<u-range-datepicker>` (date range) are form-associated text fields with a calendar popover. For inline-only usage, the library also exposes `<u-calendar>` and `<u-range-calendar>`.
+
+## Single date
+
+```html
+<u-datepicker
+  label="Date"
+  placeholder="YYYY-MM-DD"
+></u-datepicker>
+```
+
+The value is always ISO `YYYY-MM-DD` (suitable for form submission). The displayed value is formatted per the `format` prop.
+
+## Display formats
+
+```html
+<u-datepicker label="Short"  format="short"></u-datepicker>   <!-- 12/31/2025 -->
+<u-datepicker label="Medium" format="medium"></u-datepicker>  <!-- Dec 31, 2025 -->
+<u-datepicker label="Long"   format="long"></u-datepicker>    <!-- December 31, 2025 -->
+<u-datepicker label="Full"   format="full"></u-datepicker>    <!-- Wednesday, December 31, 2025 -->
+<u-datepicker label="ISO"    format="iso"></u-datepicker>     <!-- 2025-12-31 -->
+
+<u-datepicker
+  label="Custom"
+  [format]="{ year: 'numeric', month: '2-digit', day: '2-digit' }">
+</u-datepicker>
+```
+
+`format` accepts named presets, `'iso'`, or any `Intl.DateTimeFormatOptions` object.
+
+## Locale
+
+```html
+<u-datepicker label="Data" locale="pt-BR" format="long"></u-datepicker>
+<u-datepicker label="日付"  locale="ja-JP" format="full"></u-datepicker>
+```
+
+When omitted, falls back to `navigator.language`. Also drives the calendar's month/weekday labels.
+
+## Editable input mode
+
+Default — clicking the field opens the calendar; typing is blocked.
+
+```html
+<u-datepicker label="Date"></u-datepicker>
+```
+
+Editable — the input becomes a native `<input type="date">`; the trailing calendar icon opens the popover:
+
+```html
+<u-datepicker label="Date" editable></u-datepicker>
+```
+
+In editable mode the browser's native date-format mask is hidden until the user focuses the field (so it doesn't visually collide with the floating label).
+
+## Read-only
+
+```html
+<u-datepicker label="Date" value="2025-12-31" readOnly></u-datepicker>
+```
+
+## Range
+
+```html
+<u-range-datepicker
+  label="Stay"
+  placeholder="YYYY-MM-DD - YYYY-MM-DD"
+  format="medium"
+></u-range-datepicker>
+```
+
+Value format is `YYYY-MM-DD - YYYY-MM-DD`. Same `format`/`locale`/`editable`/`readOnly` props.
+
+## Inline calendar (no field)
+
+`<u-calendar>` (single) and `<u-range-calendar>` (range) embed the calendar in your own layout (sidebars, custom popovers).
+
+```html
+<u-calendar id="cal" locale="pt-BR"></u-calendar>
+<script>
+  const cal = document.getElementById('cal');
+  cal.value = '2026-06-02';                                   // ISO get/set (range: 'YYYY-MM-DD - YYYY-MM-DD')
+  cal.addEventListener('change', () => console.log(cal.value)); // a pick also fires `input`
+</script>
+```
+
+Inline-calendar gotchas (not obvious):
+- `value` is an ISO string (get/set). A day click fires **both** `input` and `change`, with `e.target.value` = the ISO date.
+- Setting `.value` does **not** move the displayed month — set `.month` / `.year` separately to open on a specific month.
+- `locale` drives the month/weekday labels (defaults to `navigator.language`; use `locale="pt-BR"` for Portuguese).
+
+## Positioning inside clipped containers
+
+`menu-positioning="fixed"` lets the popover escape any scrollable wrapper:
+
+```html
+<u-datepicker label="Date" menu-positioning="fixed"></u-datepicker>
+```
+
+## Caveats
+
+- `value` is always ISO. Format strings only affect display.
+- In editable mode the field uses the browser's native `<input type="date">`, which means OS-level keyboard handling and locale conventions for the typing UX.
+- The popover opens below the field with `direction="down-end"`. Use `menu-positioning="fixed"` if the field is in a scaffold scroll area to avoid being clipped.

package/skills/dialog/SKILL.md

@@ -0,0 +1,92 @@
+---
+description: Show modal dialogs — declarative u-dialog with slots, or imperative Dialog.message() / Dialog.confirm() builders.
+---
+
+# Dialog
+
+Two patterns: a declarative `<u-dialog>` you keep in markup and `show()`/`close()` programmatically, or one-shot imperative builders for the common alert/confirm flows.
+
+## Declarative
+
+```html
+<u-button (click)="dialog.show()">Open dialog</u-button>
+
+<u-dialog #dialog>
+  <span class="material-symbols-outlined" slot="icon">mobile_friendly</span>
+  <span slot="headline">Update available</span>
+  <span>A new version of the app is ready. Restart now to apply the update.</span>
+  <u-button slot="actions" variant="text" (click)="dialog.close('ok')">Restart</u-button>
+  <u-button slot="actions" variant="text" (click)="dialog.close('cancel')">Later</u-button>
+</u-dialog>
+```
+
+Slots: `icon`, `headline`, default (body), `actions`. Each is optional.
+
+API:
+- `show()` / `close(returnValue?)` — open / close. Closing with a value sets `dialog.returnValue`.
+- `open` property mirrors `show()`/`close()`.
+- `closed` and `cancel` events. Calling `event.preventDefault()` on `cancel` blocks dismissal.
+
+### `<form method="dialog">`
+
+Buttons with `form="form-id" value="…"` inside a `method="dialog"` form close the dialog with the submitter's value:
+
+```html
+<u-dialog #d>
+  <span slot="headline">Rename file</span>
+  <form id="rename" method="dialog">
+    <u-text-field label="File name" autofocus name="filename"></u-text-field>
+  </form>
+  <u-button slot="actions" variant="text" form="rename" value="save">Save</u-button>
+  <u-button slot="actions" variant="text" form="rename" value="cancel">Cancel</u-button>
+</u-dialog>
+```
+
+### Long content
+
+The dialog draws subtle dividers above the headline and below the actions when the body overflows. No extra setup needed — just put your content in the default slot.
+
+### Action button order
+
+`.actions` uses `flex-direction: row-reverse`, so the **first child in DOM order renders on the right** (the confirming action, per M3). Always put the affirmative button first in markup.
+
+## Imperative — message
+
+One-shot alert dialog with a single acknowledge button. Removes itself from the DOM on close.
+
+```ts
+import { Dialog } from '@universal-material/web';
+
+Dialog
+  .message('Your changes have been saved.')
+  .headline('Saved')
+  .acknowledgeButton({ label: 'Got it', variant: 'filled' })
+  .show();
+```
+
+## Imperative — confirm
+
+One-shot confirm dialog. `show()` returns a `Promise<boolean>` that resolves `true` on confirm, `false` on cancel/dismiss.
+
+```ts
+import { Dialog } from '@universal-material/web';
+
+const ok = await Dialog
+  .confirm('This action cannot be undone. Continue?')
+  .headline('Delete item')
+  .confirmButton({ label: 'Delete', variant: 'filled', color: 'error' })
+  .cancelButton({ label: 'Keep it' })
+  .show();
+
+if (ok) {
+  // …perform deletion
+}
+```
+
+`confirmButton` / `cancelButton` accept any `{ variant, color, label }` — omitted fields fall back to defaults from `config.dialog.confirmDefaults`.
+
+## Caveats
+
+- The dialog opens via `<dialog>.showModal()` so it stacks above everything (no z-index gymnastics) and traps focus.
+- The imperative builders run their lifecycle outside any framework's change-detection zone (the closed event fires from a transition listener). In Angular, call `ChangeDetectorRef.detectChanges()` after `await …show()` if the resolved value drives template bindings.
+- Don't import `'@universal-material/web/dialog/dialog-builder.js'` directly — it doesn't register `u-button`; use the package root or the dialog entry which already pulls it in.

package/skills/drawer/SKILL.md

@@ -0,0 +1,94 @@
+---
+description: Add a side navigation drawer to an app — sections with headlines, drawer items with icons and badges, toggleable on mobile.
+---
+
+# Side navigation drawer
+
+`<u-side-navigation>` wraps a page with a left-side drawer (`<u-drawer>`) that toggles open/closed. Inside the drawer, group items with `<u-drawer-headline>` and use `<u-drawer-item>` for each link.
+
+## Basic usage
+
+```html
+<u-side-navigation #nav>
+  <u-top-app-bar headline="My app">
+    <u-icon-button slot="leading-icon" type="button"
+      (click)="nav.toggleDrawer = !nav.toggleDrawer">
+      <span class="material-symbols-outlined">menu</span>
+    </u-icon-button>
+  </u-top-app-bar>
+
+  <u-drawer slot="drawer">
+    <u-drawer-headline>Library</u-drawer-headline>
+    <u-drawer-item active>
+      <span class="material-symbols-outlined" slot="icon">home</span>
+      Home
+    </u-drawer-item>
+    <u-drawer-item>
+      <span class="material-symbols-outlined" slot="icon">favorite</span>
+      Favorites
+      <span slot="badge">12</span>
+    </u-drawer-item>
+
+    <u-drawer-headline>Account</u-drawer-headline>
+    <u-drawer-item>
+      <span class="material-symbols-outlined" slot="icon">settings</span>
+      Settings
+    </u-drawer-item>
+  </u-drawer>
+
+  <!-- the main page content goes here as light DOM -->
+  <div class="u-container">
+    Page body
+  </div>
+</u-side-navigation>
+```
+
+The side-navigation:
+- responsively shows the drawer permanently on wide viewports and toggles it as an overlay on narrow ones,
+- sets `--u-app-bar-offset` so the slotted top app bar slides with the drawer,
+- exposes `.toggleDrawer` (boolean) for programmatic control.
+
+## Drawer items
+
+`<u-drawer-item>` slots:
+- default — the label,
+- `icon` — leading icon (24dp),
+- `badge` — trailing badge **content** (plain text in a `<span slot="badge">`, e.g. a count). The drawer item styles this itself — it pins the content to the trailing edge inline with the row.
+
+**Don't put a `<u-badge>` in the `badge` slot.** `<u-badge>` is the *floating* badge used to dot the corner of an icon (notification bell, rail item); it's `position: absolute`. Dropped into a drawer item's inline `badge` slot it floats out of place instead of sitting at the row's trailing edge. Pass the value as a `<span slot="badge">12</span>` — the drawer item provides the badge treatment. (Note this differs from `<u-navigation-rail-item>`, whose collapsed state *does* take a `<u-badge>` because the badge floats over the icon there.)
+
+Attributes:
+- `active` — highlights the item with the secondary-container pill (M3 active state).
+- `href` / `target` — renders as a link instead of a button.
+- `keep-drawer-open` — by default, clicking an item auto-closes the drawer on mobile; set this to disable.
+
+## Routing
+
+For framework routing, set `routerLink` (Angular) / `to` (Vue Router) / `href` on the item and let the framework's link directive handle navigation; the drawer item still emits a click and auto-closes the drawer.
+
+## Sections
+
+Group items with `<u-drawer-headline>` between them. The headline renders a small label-style title above its section.
+
+## Background — and the trap when slotting a drawer into a pane
+
+`<u-drawer>` paints its own background, and that color is **breakpoint-dependent**:
+- below `lg`: `--u-modal-drawer-bg-color` (default `surface-container-low`) — the modal drawer surface;
+- at `lg`+: `--u-standard-drawer-bg-color` (default `surface` / body) — a *standard* permanent drawer is meant to read as part of the page background, so it deliberately matches `surface`.
+
+That default is correct for a drawer used directly inside `<u-side-navigation>`. **But if you slot a `<u-drawer>` into a `<u-pane variant="filled">` (e.g. a settings section-nav in a list-detail), the drawer's surface paints over the pane's filled background.** The visible bug: the nav column shows a background at small/medium widths, then goes flat/background-less on desktop — because at `lg`+ the drawer flips to `surface` (= the scaffold body) and erases the pane's fill. It looks like the pane "lost its background"; really the drawer is painting on top with body color.
+
+Fix it at the drawer: when the pane is the surface, make the drawer transparent so the pane shows through at every breakpoint.
+
+```html
+<u-pane variant="filled" style="--u-modal-drawer-bg-color: transparent; --u-standard-drawer-bg-color: transparent;">
+  <u-drawer>…</u-drawer>
+</u-pane>
+```
+
+(The two custom properties are inherited, so setting them on the pane reaches the drawer.) Don't try to fix it by raising the *pane's* `--u-pane-filled-bg-color` — the drawer still paints over it on desktop, so the column stays flat.
+
+## Caveats
+
+- The drawer is a sibling of the page content inside `<u-side-navigation>`, not a child of the top bar. Don't nest it under the bar.
+- On wide viewports the drawer is permanent; the toggle button still works but the drawer never closes. Use `keep-drawer-open` on items you'd otherwise want auto-closing only on mobile — it's safe either way.

package/skills/expansion-panel/SKILL.md

@@ -0,0 +1,65 @@
+---
+description: Use u-expansion-panel for collapsible sections; wrap in u-expansion-panel-container for accordion behavior.
+---
+
+# Expansion panel
+
+Collapsible surface with a clickable header (with ripple + chevron). Animates via the internal [[collapse]] component.
+
+## Single panel
+
+```html
+<u-expansion-panel>
+  <span slot="header">What is Material 3 Expressive?</span>
+  <div style="padding: 0 1rem 1rem;">
+    Material 3 Expressive is the latest iteration of Material Design.
+  </div>
+</u-expansion-panel>
+```
+
+## Accordion (exclusive)
+
+Wrap multiple panels in `u-expansion-panel-container` — opening one closes the others.
+
+```html
+<u-expansion-panel-container>
+  <u-expansion-panel>
+    <span slot="header">Account</span>
+    <div style="padding: 0 1rem 1rem;">Manage email, password, and connected services.</div>
+  </u-expansion-panel>
+  <u-expansion-panel>
+    <span slot="header">Notifications</span>
+    <div style="padding: 0 1rem 1rem;">Choose how and when you want to be notified.</div>
+  </u-expansion-panel>
+</u-expansion-panel-container>
+```
+
+## Multi (independent panels)
+
+Add `multi` to keep multiple panels open simultaneously.
+
+```html
+<u-expansion-panel-container multi>
+  <u-expansion-panel expanded>
+    <span slot="header">Always-open</span>
+    <div style="padding: 0 1rem 1rem;">Set <code>expanded</code> for the initial state.</div>
+  </u-expansion-panel>
+  <u-expansion-panel>
+    <span slot="header">Independent</span>
+    <div style="padding: 0 1rem 1rem;">Stays open when others open.</div>
+  </u-expansion-panel>
+</u-expansion-panel-container>
+```
+
+## Attributes
+
+- `expanded` — current open state. Reflects to the attribute; dispatches `change` (bubbles, composed) when toggled.
+- `disabled` — prevents toggling and silences the ripple.
+- `hide-toggle` — hides the default chevron icon.
+- `multi` (container) — allow multiple panels open at once.
+
+## Caveats
+
+- Put the header content in `slot="header"`. The default slot is the panel body (wrapped internally in `u-collapse`).
+- The container coordinates panels via the `change` event bubbling out of each panel — works with panels added/removed dynamically.
+- Sibling-close logic uses `querySelectorAll('u-expansion-panel')` against direct descendants of the container only — nested containers operate independently.

package/skills/fab/SKILL.md

@@ -0,0 +1,79 @@
+---
+description: Add a floating action button — u-fab (single primary action), u-fab-menu (expandable speed-dial with multiple items).
+---
+
+# FAB and FAB menu
+
+## `<u-fab>` — single primary action
+
+```html
+<u-fab>
+  <span class="material-symbols-outlined">edit</span>
+</u-fab>
+```
+
+Colors: `primary` (default), `secondary`, `tertiary`, `surface`, `branded`.
+Sizes: `small`, `medium` (default), `large`.
+
+Extended FAB (with label):
+
+```html
+<u-fab label="Compose">
+  <span class="material-symbols-outlined">edit</span>
+</u-fab>
+```
+
+Lowered elevation:
+
+```html
+<u-fab lowered>
+  <span class="material-symbols-outlined">add</span>
+</u-fab>
+```
+
+## Positioning
+
+Inside a `<u-scaffold>`, drop the FAB in the `fab` slot — it's anchored to the scaffold's bottom-right with the correct M3 16dp gap, and offsets above the navigation bar automatically:
+
+```html
+<u-scaffold>
+  <!-- … top-bar, content, bottom-bar … -->
+  <u-fab slot="fab" color="primary">
+    <span class="material-symbols-outlined">edit</span>
+  </u-fab>
+</u-scaffold>
+```
+
+For ad-hoc placement, wrap the FAB in a positioned container.
+
+## `<u-fab-menu>` — speed-dial
+
+A FAB that toggles into multiple `<u-fab-menu-item>`s when clicked:
+
+```html
+<u-fab-menu color="primary">
+  <span class="material-symbols-outlined" slot="icon">add</span>
+
+  <u-fab-menu-item label="New doc">
+    <span class="material-symbols-outlined">description</span>
+  </u-fab-menu-item>
+  <u-fab-menu-item label="New folder">
+    <span class="material-symbols-outlined">folder</span>
+  </u-fab-menu-item>
+  <u-fab-menu-item label="Upload">
+    <span class="material-symbols-outlined">upload</span>
+  </u-fab-menu-item>
+</u-fab-menu>
+```
+
+Slots on `<u-fab-menu>`:
+- `icon` — the closed-state icon (e.g. `add`),
+- `close-icon` — the open-state icon (defaults to an "×").
+
+The toggle FAB animates between the two icons; menu items animate in/out around it.
+
+## Caveats
+
+- `<u-fab-menu>` keeps `pointer-events: none` on its host so the invisible menu-items area (when closed) passes clicks through to whatever is behind it. Don't blanket-override slotted children with `pointer-events: auto`.
+- When slotted into `<u-scaffold>` the scaffold neutralizes the FAB menu's internal `--u-fab-menu-toggle-margin` so the visible toggle aligns with the wrapper box (otherwise it would sit too close to the bottom bar).
+- A FAB does not auto-react to scroll yet — the `scrollContainer` attribute is reserved for future hide-on-scroll behavior.

package/skills/list/SKILL.md

@@ -0,0 +1,105 @@
+---
+description: Render Material 3 lists — u-list + u-list-item, with leading icons, supporting text, badges and trailing actions.
+---
+
+# List
+
+`<u-list>` is a vertical stack of `<u-list-item>`s. Each item supports leading and trailing slots, supporting text and selection states.
+
+## Basic
+
+```html
+<u-list>
+  <u-list-item>Inbox</u-list-item>
+  <u-list-item>Drafts</u-list-item>
+  <u-list-item>Sent</u-list-item>
+</u-list>
+```
+
+## Two-line items with icons
+
+```html
+<u-list>
+  <u-list-item>
+    <span class="material-symbols-outlined" slot="leading-icon">person</span>
+    Maria Andrade
+    <span slot="supporting-text">maria@example.com</span>
+  </u-list-item>
+
+  <u-list-item>
+    <span class="material-symbols-outlined" slot="leading-icon">person</span>
+    Carlos Pereira
+    <span slot="supporting-text">carlos@example.com</span>
+  </u-list-item>
+</u-list>
+```
+
+## Trailing content
+
+```html
+<u-list-item>
+  <span class="material-symbols-outlined" slot="leading-icon">archive</span>
+  Archive
+  <u-icon-button slot="trailing-icon">
+    <span class="material-symbols-outlined">chevron_right</span>
+  </u-icon-button>
+</u-list-item>
+```
+
+## Selectable rows
+
+`selectable` adds the ripple + hover **state layer** so the row reads as interactive:
+
+```html
+<u-list>
+  <u-list-item selectable onclick="…">One</u-list-item>
+  <u-list-item selectable onclick="…">Two</u-list-item>
+</u-list>
+```
+
+For a persistent **active / selected** highlight (e.g. the open row in a list-detail or mail list), use the **`selected`** attribute/property — it paints the M3 selected container (`secondary-container` / `on-secondary-container`):
+
+```html
+<u-list>
+  <u-list-item selectable selected>One</u-list-item>
+  <u-list-item selectable>Two</u-list-item>
+</u-list>
+<script>
+  list.addEventListener('click', (e) => {
+    const item = e.target.closest('u-list-item');
+    if (!item) return;
+    list.querySelectorAll('u-list-item[selected]').forEach((i) => (i.selected = false));
+    item.selected = true;
+  });
+</script>
+```
+
+Override the selected colors per call site with `--u-list-item-selected-container-color` / `--u-list-item-selected-label-color`. For selection lists tied to a form value, use the dedicated `<u-checkbox-list-item>`, `<u-radio-list-item>`, or `<u-switch-list-item>` (see the **selection-controls** skill).
+
+## Aligning a row flush (`no-inset`)
+
+List items carry a 16dp inline inset, so their content sits indented from adjacent non-list content (section headings, paragraph labels). Add **`no-inset`** to pull the row flush — it cancels the inline padding with an equal negative inline margin, so the content lines up with the surrounding labels (the state layer bleeds to the container edges):
+
+```html
+<div class="u-title-s">Channels</div>
+<u-list>
+  <u-list-item no-inset>Email</u-list-item>
+  <u-list-item no-inset>Push</u-list-item>
+</u-list>
+```
+
+The `*-list-item` selection variants accept `no-inset` too (it's forwarded to their inner list item) — handy in settings sections where the row should line up with the heading.
+
+## Three-line items
+
+A second line of supporting text wraps automatically when content exceeds one line; for an explicitly tall three-line variant, use multiple `<span slot="supporting-text">` lines.
+
+## Dividers and sections
+
+For grouped lists with headlines, mix `<u-drawer-headline>`-style elements between groups, or use the `card`/`outlined-card` containers around each section.
+
+## Caveats
+
+- `<u-list-item>` slots accept any node — keep leading/trailing icons inside `<span class="material-symbols-outlined">` or `<u-icon-button>` for consistent sizing.
+- `<u-list>` is unopinionated about scrolling. For long lists inside a constrained container, wrap the list in a `<div style="overflow:auto; max-height: …">`.
+- For very long lists (1000+ items), the M3 list is fine but consider virtualization (`@lit-labs/virtualizer`).

package/skills/menu/SKILL.md

@@ -0,0 +1,120 @@
+---
+description: Open contextual menus — u-menu and u-menu-item for popovers anchored to a trigger, plus u-overflow-menu for action bars that auto-collapse on narrow widths.
+---
+
+# Menus
+
+## `<u-menu>` + `<u-menu-item>` — popover
+
+A floating surface anchored to a trigger. Open with `.show()`/`.toggle()`/`.close()` (or by setting `open`):
+
+```html
+<u-icon-button (click)="menu.toggle()">
+  <span class="material-symbols-outlined">more_vert</span>
+</u-icon-button>
+
+<u-menu #menu>
+  <u-menu-item>
+    <span class="material-symbols-outlined" slot="leading-icon">edit</span>
+    Edit
+  </u-menu-item>
+  <u-menu-item>
+    <span class="material-symbols-outlined" slot="leading-icon">content_copy</span>
+    Duplicate
+  </u-menu-item>
+  <u-menu-item>
+    <span class="material-symbols-outlined" slot="leading-icon">delete</span>
+    Delete
+  </u-menu-item>
+</u-menu>
+```
+
+By default the menu anchors to its parent element. Set `anchorElement` explicitly when needed:
+
+```ts
+menu.anchorElement = triggerButton;
+```
+
+## Positioning
+
+- **`anchor-corner`** — which corner of the anchor the menu attaches to. Supports `start-start`, `start-end`, `end-start`, `end-end`, plus `auto-start` / `auto-end` (auto picks top vs bottom based on space).
+- **`direction`** — which way the menu grows: `up-start`, `up-end`, `down-start`, `down-end` (default).
+
+For a dropdown right under the trigger, the defaults work. For a "more" menu in a top app bar, use `anchor-corner="end-end"`:
+
+```html
+<u-menu anchor-corner="end-end" direction="down-start">…</u-menu>
+```
+
+## Clipped containers
+
+If the menu lives inside a `overflow: hidden` or scrollable wrapper, set `positioning="fixed"` so it escapes:
+
+```html
+<u-menu positioning="fixed">…</u-menu>
+```
+
+## Auto-close
+
+- `autoclose="outside"` (default-ish) — closes on outside clicks but not on clicks inside the menu.
+- `autoclose="true"` — closes on any click anywhere.
+- `autoclose="false"` — never auto-closes; you manage it.
+
+## `<u-overflow-menu>` — responsive action bar
+
+A horizontal row of `<u-overflow-menu-item>`s that automatically collapses items into a "more" menu when there isn't enough horizontal space:
+
+```html
+<u-overflow-menu>
+  <u-overflow-menu-item label="Bold">
+    <span class="material-symbols-outlined">format_bold</span>
+  </u-overflow-menu-item>
+  <u-overflow-menu-item label="Italic">
+    <span class="material-symbols-outlined">format_italic</span>
+  </u-overflow-menu-item>
+  <u-overflow-menu-item label="Underline">
+    <span class="material-symbols-outlined">format_underlined</span>
+  </u-overflow-menu-item>
+  <u-overflow-menu-item label="Strikethrough">
+    <span class="material-symbols-outlined">format_strikethrough</span>
+  </u-overflow-menu-item>
+
+  <!-- Items marked collapse="always" never render inline -->
+  <u-overflow-menu-item label="Delete" collapse="always">
+    <span class="material-symbols-outlined">delete</span>
+  </u-overflow-menu-item>
+</u-overflow-menu>
+```
+
+Inside a clipped wrapper (e.g. a card with `overflow: hidden`), set `menuPositioning="fixed"` so the popover can escape:
+
+```html
+<u-overflow-menu menuPositioning="fixed">…</u-overflow-menu>
+```
+
+### Row "kebab" (all actions behind one trigger)
+
+Mark every item `collapse="always"` so nothing renders inline and only the "more" trigger shows. Items render as **icon buttons** — the `label` is the tooltip/aria text, not visible — so give each an icon. Activation bubbles a `click` from the item; delegate and read it:
+
+```html
+<u-overflow-menu menuPositioning="fixed">
+  <u-overflow-menu-item label="Ver" collapse="always"><span class="material-symbols-outlined">visibility</span></u-overflow-menu-item>
+  <u-overflow-menu-item label="Editar" collapse="always"><span class="material-symbols-outlined">edit</span></u-overflow-menu-item>
+  <u-overflow-menu-item label="Excluir" collapse="always"><span class="material-symbols-outlined">delete</span></u-overflow-menu-item>
+</u-overflow-menu>
+
+<script>
+  table.addEventListener('click', (e) => {
+    const item = e.target.closest('u-overflow-menu-item');
+    if (item) doAction(item.getAttribute('label'), e.target.closest('tr'));
+  });
+</script>
+```
+
+For a single-trigger row menu, `<u-icon-button>` + `<u-menu>` (with `menu.anchorElement = theButton`) is often simpler than `<u-overflow-menu>`.
+
+## Caveats
+
+- A `<u-menu>` is not modal — it doesn't trap focus or scrim the background. Use `<u-dialog>` for modal flows.
+- The overflow menu watches its anchor size with a `ResizeObserver`. If you swap the anchor or animate the container, it re-runs the layout pass automatically.
+- `manualFocus` on `<u-menu>` disables the default auto-focus of the first item on open — useful when the menu wraps a calendar or other custom popover content.