@universal-material/web 3.8.0 → 3.9.0

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>`.

package/slider/slider.d.ts

@@ -0,0 +1,73 @@
+import { PropertyValues } from '@lit/reactive-element';
+import { HTMLTemplateResult, LitElement } from 'lit';
+type LabelFormat = (value: number) => string;
+export type SliderSize = 'extra-small' | 'small' | 'medium' | 'large' | 'extra-large';
+/**
+ * Material 3 expressive slider. Single-thumb by default; becomes a range slider
+ * when both `value-start` and `value-end` are set (or `range` is forced).
+ *
+ * @fires input - Dispatched continuously while dragging.
+ * @fires change - Dispatched when the user commits a value change.
+ * @csspart track - The track container.
+ * @csspart track-inactive-start - The inactive segment before the start handle (range mode only).
+ * @csspart track-active - The highlighted segment between (or up to) the thumbs.
+ * @csspart track-inactive-end - The inactive segment after the end handle.
+ * @csspart thumb - The thumb indicator (or the start thumb in range mode).
+ * @csspart thumb-end - The end thumb in range mode.
+ * @csspart value-indicator - The floating value indicator shown in `discrete` mode while dragging.
+ * @csspart stop-indicator - The dot at each end of the slider.
+ */
+export declare class Slider extends LitElement {
+    #private;
+    static styles: import("lit").CSSResult[];
+    static readonly formAssociated = true;
+    protected readonly elementInternals: ElementInternals;
+    constructor();
+    /** Minimum value. */
+    min: number;
+    /** Maximum value. */
+    max: number;
+    /** Step increment. Use `0` for fully continuous values. */
+    step: number;
+    /** Current value (single-thumb mode). */
+    value: number | undefined;
+    /** Start value (range mode). */
+    valueStart: number | undefined;
+    /** End value (range mode). */
+    valueEnd: number | undefined;
+    /**
+     * Forces range mode. Auto-enabled when both `value-start` and `value-end`
+     * are provided.
+     */
+    range: boolean;
+    /** Shows tick marks and a floating value indicator while dragging. */
+    discrete: boolean;
+    /** Shows tick marks without enabling the floating value indicator. */
+    ticks: boolean;
+    /** Disables the slider. */
+    disabled: boolean;
+    /** Form-association name. */
+    name: string;
+    /** Visual size variant. */
+    size: SliderSize;
+    /** Custom formatter for the floating value indicator. */
+    labelFormat: LabelFormat;
+    private _dragging;
+    private _activeThumb;
+    private _hoveredThumb;
+    private readonly _input;
+    private readonly _inputEnd;
+    private readonly _container;
+    get form(): HTMLFormElement | null;
+    protected willUpdate(changed: PropertyValues): void;
+    protected firstUpdated(): void;
+    protected updated(changed: PropertyValues): void;
+    render(): HTMLTemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'u-slider': Slider;
+    }
+}
+export {};
+//# sourceMappingURL=slider.d.ts.map

package/slider/slider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slider.d.ts","sourceRoot":"","sources":["../../src/slider/slider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAQ,kBAAkB,EAAE,UAAU,EAAW,MAAM,KAAK,CAAC;AASpE,KAAK,WAAW,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;AAG7C,MAAM,MAAM,UAAU,GAAG,aAAa,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,aAAa,CAAC;AAWtF;;;;;;;;;;;;;;GAcG;AACH,qBACa,MAAO,SAAQ,UAAU;;IACpC,OAAgB,MAAM,4BAAwB;IAE9C,MAAM,CAAC,QAAQ,CAAC,cAAc,QAAQ;IAEtC,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;;IAOtD,qBAAqB;IACO,GAAG,SAAK;IAEpC,qBAAqB;IACO,GAAG,SAAO;IAEtC,2DAA2D;IAC/B,IAAI,SAAK;IAErC,yCAAyC;IACb,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAEtD,gCAAgC;IACsB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAErF,8BAA8B;IACsB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAEjF;;;OAGG;IACyC,KAAK,UAAS;IAE1D,sEAAsE;IAC1B,QAAQ,UAAS;IAE7D,sEAAsE;IAC1B,KAAK,UAAS;IAE1D,2BAA2B;IACiB,QAAQ,UAAS;IAE7D,6BAA6B;IACA,IAAI,SAAM;IAEvC,2BAA2B;IACE,IAAI,EAAE,UAAU,CAAiB;IAE9D,yDAAyD;IACzB,WAAW,EAAE,WAAW,CAAoB;IAEnE,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,YAAY,CAAsB;IAC1C,OAAO,CAAC,aAAa,CAAsB;IAEnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2B;IACrD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAe;IAE/D,IAAI,IAAI,IAAI,eAAe,GAAG,IAAI,CAEjC;cAEkB,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;cAkBzC,YAAY,IAAI,IAAI;cAIpB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAMhD,MAAM,IAAI,kBAAkB;CA+VtC;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,UAAU,EAAE,MAAM,CAAC;KACpB;CACF"}