@mhmo91/schmancy 0.9.5 → 0.9.6

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mhmo91/schmancy",
-	"version": "0.9.5",
+	"version": "0.9.6",
 	"description": "UI library build with web components",
 	"main": "./dist/index.js",
 	"customElements": "custom-elements.json",
@@ -53,7 +53,10 @@
 		"test": "vitest run",
 		"test:watch": "vitest",
 		"test:ui": "vitest --ui",
-		"test:coverage": "vitest run --coverage"
+		"test:coverage": "vitest run --coverage",
+		"knip": "knip",
+		"format": "prettier --write 'src/**/*.{ts,css,scss}' 'mixins/**/*.{ts,css}'",
+		"format:check": "prettier --check 'src/**/*.{ts,css,scss}' 'mixins/**/*.{ts,css}'"
 	},
 	"author": "@mhmo91",
 	"license": "Apache-2.0",
@@ -67,53 +70,41 @@
 		"@lit-labs/virtualizer": "^2.1.1",
 		"@lit/context": "^1.1.6",
 		"@material/material-color-utilities": "^0.4.0",
-		"@material/mwc-base": "^0.27.0",
 		"@material/web": "^2.4.1",
-		"@rollup/plugin-strip": "^3.0.4",
-		"@rollup/plugin-terser": "^1.0.0",
-		"@tailwindcss/nesting": "^0.0.0-insiders.565cd3e",
 		"@types/cleave.js": "^1.4.12",
-		"@webcomponents/scoped-custom-element-registry": "^0.0.10",
-		"@webcomponents/webcomponentsjs": "^2.8.0",
 		"cleave.js": "^1.6.0",
 		"dayjs": "^1.11.20",
-		"fastest-levenshtein": "^1.0.16",
 		"highlight.js": "^11.11.1",
 		"immer": "^11.1.4",
 		"jsqr": "^1.4.0",
 		"lit": "^3.3.2",
-		"playground-elements": "^0.21.2",
 		"rxjs": "^7.8.2",
-		"tippy.js": "^6.3.7",
 		"ts-is-present": "^1.2.2",
-		"typeit": "^8.8.7",
-		"typescript": "^5.9.3",
-		"uuid": "^13.0.0",
-		"web-component-analyzer": "^2.0.0"
+		"typeit": "^8.8.7"
 	},
 	"devDependencies": {
-		"@tailwindcss/container-queries": "^0.1.1",
-		"@tailwindcss/forms": "^0.5.11",
+		"@rollup/plugin-strip": "^3.0.4",
+		"@rollup/plugin-terser": "^1.0.0",
 		"@tailwindcss/postcss": "^4.2.1",
 		"@tailwindcss/vite": "^4.2.1",
 		"@types/node": "^25.5.0",
-		"@types/uuid": "^11.0.0",
-		"@typescript-eslint/parser": "^8.57.1",
+		"@vitest/browser-playwright": "^4.1.4",
+		"@vitest/coverage-v8": "^4.1.5",
 		"@vitest/ui": "^4.1.0",
-		"autoprefixer": "^10.4.27",
-		"c8": "^11.0.0",
-		"concurrently": "^9.2.1",
-		"deepmerge": "^4.3.1",
-		"eslint": "^10.0.3",
+		"axe-core": "^4.11.3",
 		"happy-dom": "^20.8.4",
+		"knip": "^6.6.0",
+		"playwright": "^1.59.1",
 		"postcss": "^8.5.8",
 		"prettier": "^3.8.1",
 		"rollup-plugin-copy": "^3.5.0",
 		"sass": "^1.98.0",
 		"tailwindcss": "^4.2.1",
+		"ts-lit-plugin": "^2.0.2",
+		"typescript": "^5.9.3",
 		"vite": "^8.0.0",
-		"vite-plugin-sitemap": "^0.8.2",
-		"vitest": "^4.1.0"
+		"vitest": "^4.1.0",
+		"web-component-analyzer": "^2.0.0"
 	},
 	"peerDependencies": {
 		"lit": "^3.2.1",

package/skills/schmancy/INDEX.md

@@ -16,25 +16,25 @@ The framework pieces — touch before components.
 ## Components by job
 
 ### Display
-[Typography](./typography.md) · [Icons](./icons.md) · [Avatar](./avatar.md) · [Divider](./divider.md) · [Badge](./badge.md) · [Code Highlight](./code-highlight.md) · [Typewriter](./typewriter.md) · [JSON](./json.md) · [Iframe](./iframe.md) · [Map](./map.md) · [Charts](./charts.md)
+[Typography](./typography.md) · [Icons](./icons.md) · [Avatar](./avatar.md) · [Divider](./divider.md) · [Badge](./badge.md) · [Kbd](./kbd.md) · [Code Highlight](./code-highlight.md) · [Typewriter](./typewriter.md) · [JSON](./json.md) · [Iframe](./iframe.md) · [Map](./map.md) · [Charts](./charts.md)
 
 ### Surfaces & layout
-[Surface](./surface.md) · [Card](./card.md) · [Scroll / Grid / Flex](./layout.md) · [Page](./page.md) · [Content Drawer](./content-drawer.md) · [Window](./window.md) · [Boat](./boat.md) · [Float](./float.md)
+[Surface](./surface.md) · [Card](./card.md) · [Scroll / Grid / Flex](./layout.md) · [Page](./page.md) · [Content Drawer](./content-drawer.md) · [Window](./window.md) · [Boat](./boat.md) · [Float](./float.md) · [Splash Screen](./splash-screen.md)
 
 ### Forms
-[Form](./form.md) · [Input](./input.md) · [Textarea](./textarea.md) · [Select](./select.md) · [Autocomplete](./autocomplete.md) · [Option](./option.md) · [Checkbox](./checkbox.md) · [Radio Group](./radio-group.md) · [Chips](./chips.md) · [Date Range](./date-range.md) · [Date Range Inline](./date-range-inline.md) · [Range](./range.md) · [Extra (Country/Timezone)](./extra.md)
+[Form](./form.md) · [Input](./input.md) · [Textarea](./textarea.md) · [Select](./select.md) · [Autocomplete](./autocomplete.md) · [Option](./option.md) · [Checkbox](./checkbox.md) · [Switch](./switch.md) · [Radio Group](./radio-group.md) · [Chips](./chips.md) · [Date Range](./date-range.md) · [Date Range Inline](./date-range-inline.md) · [Range](./range.md) · [Extra (Country/Timezone)](./extra.md)
 
 ### Navigation
-[Nav Drawer](./nav-drawer.md) · [Tabs](./tabs.md) · [Navigation Bar](./navigation-bar.md) · [Navigation Rail](./navigation-rail.md) · [Steps](./steps.md) · [Teleport](./teleport.md) · [Theme Button](./theme-button.md)
+[Breadcrumb](./breadcrumb.md) · [Nav Drawer](./nav-drawer.md) · [Tabs](./tabs.md) · [Navigation Bar](./navigation-bar.md) · [Navigation Rail](./navigation-rail.md) · [Steps](./steps.md) · [Teleport](./teleport.md) · [Theme Button](./theme-button.md)
 
 ### Overlays
-[Dialog](./dialog.md) · [Sheet](./sheet.md) · [Notification](./notification.md) · [Menu](./menu.md) · [Dropdown](./dropdown.md) · [Tooltip](./tooltip.md) · [Lightbox](./lightbox.md) · [Expand](./expand.md)
+[Dialog](./dialog.md) · [Sheet](./sheet.md) · [Notification](./notification.md) · [Menu](./menu.md) · [Dropdown](./dropdown.md) · [Tooltip (directive)](./tooltip.md) · [Lightbox](./lightbox.md) · [Expand](./expand.md)
 
 ### Interactive
 [Button](./button.md) · [List](./list.md) · [Details](./details.md) · [Table](./table.md) · [Tree](./tree.md) · [Slider](./slider.md) · [QR Scanner](./qr-scanner.md)
 
 ### Feedback
-[Progress](./progress.md) · [Busy](./busy.md) · [Connectivity](./connectivity.md) · [Delay](./delay.md)
+[Progress](./progress.md) · [Busy](./busy.md) · [Skeleton](./skeleton.md) · [Connectivity](./connectivity.md) · [Delay](./delay.md)
 
 ### Domain
 [Mailbox](./mailbox.md)
@@ -57,6 +57,7 @@ The framework pieces — touch before components.
 [Discovery](./discovery.md) — cross-shadow component lookup.
 [RxJS Utils](./rxjs-utils.md) — `waitForElement`, `waitUntil`, `mutationObserver`.
 [Utils](./utils.md) — `similarity`, `numbers`, `overlayStack`, `intersection$`, `hashContent`.
+[Visually Hidden](./visually-hidden.md) — screen-reader-only content wrapper.
 [Audio](./audio.md) — synthesized feedback sounds.
 
 ## Conventions

package/skills/schmancy/breadcrumb.md

@@ -0,0 +1,53 @@
+# schmancy-breadcrumb
+
+> Breadcrumb navigation with auto-inserted separators and ARIA landmark semantics.
+
+## Usage
+```html
+<schmancy-breadcrumb>
+  <schmancy-breadcrumb-item href="/">Home</schmancy-breadcrumb-item>
+  <schmancy-breadcrumb-item href="/projects">Projects</schmancy-breadcrumb-item>
+  <schmancy-breadcrumb-item current>Dashboard</schmancy-breadcrumb-item>
+</schmancy-breadcrumb>
+```
+
+## schmancy-breadcrumb
+
+Container. Renders a `<nav aria-label="Breadcrumb">` and inserts a separator element between each slotted item.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| separator | string | `'/'` | Character or string rendered between items. Hidden from assistive tech via `aria-hidden="true"`. |
+
+| Part | Description |
+|------|-------------|
+| separator | Each inserted separator element. Style bulk via `schmancy-breadcrumb::part(separator)`. |
+
+The host sets `aria-label="Breadcrumb"` on connection if none was already set.
+
+## schmancy-breadcrumb-item
+
+Individual crumb. Renders as `<a>` when `href` is set, otherwise `<span>`.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| href | string | `''` | When set (and `current` is false), renders as an anchor. |
+| current | boolean | `false` | Marks this item as `aria-current="page"`. Renders as a plain `<span>` even if `href` is set. |
+
+## Examples
+```html
+<!-- Custom separator -->
+<schmancy-breadcrumb separator="›">
+  <schmancy-breadcrumb-item href="/">Home</schmancy-breadcrumb-item>
+  <schmancy-breadcrumb-item href="/docs">Docs</schmancy-breadcrumb-item>
+  <schmancy-breadcrumb-item current>API</schmancy-breadcrumb-item>
+</schmancy-breadcrumb>
+```
+
+```html
+<!-- Two-level (just two crumbs) -->
+<schmancy-breadcrumb>
+  <schmancy-breadcrumb-item href="/users">Users</schmancy-breadcrumb-item>
+  <schmancy-breadcrumb-item current>Jane Doe</schmancy-breadcrumb-item>
+</schmancy-breadcrumb>
+```

package/skills/schmancy/kbd.md

@@ -0,0 +1,40 @@
+# schmancy-kbd
+
+> Render a keyboard shortcut hint. Semantically a `<kbd>` element; visually styled as a pressed key.
+
+## Usage
+```html
+Press <schmancy-kbd>⌘</schmancy-kbd> + <schmancy-kbd>K</schmancy-kbd> to search.
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| size | `'sm'\|'md'` | `'md'` | Smaller variant for inline text. |
+
+## Parts
+| Part | Description |
+|------|-------------|
+| base | The inner native `<kbd>` element. |
+
+## Examples
+```html
+<!-- Inline combo -->
+<schmancy-typography>
+  <schmancy-kbd size="sm">Shift</schmancy-kbd>
+  +
+  <schmancy-kbd size="sm">Tab</schmancy-kbd>
+  to move backwards
+</schmancy-typography>
+```
+
+```html
+<!-- Command palette shortcut -->
+<div class="flex items-center gap-2">
+  Open command palette
+  <span>
+    <schmancy-kbd>⌘</schmancy-kbd>
+    <schmancy-kbd>K</schmancy-kbd>
+  </span>
+</div>
+```

package/skills/schmancy/skeleton.md

@@ -0,0 +1,40 @@
+# schmancy-skeleton
+
+> Placeholder shimmer surface shown while content loads. Reduced-motion-aware.
+
+## Usage
+```html
+<schmancy-skeleton width="12rem" height="1rem"></schmancy-skeleton>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| shape | `'rect'\|'circle'\|'text'` | `'rect'` | Visual shape. `circle` forces 50% border radius; `text` defaults height to `1em`. |
+| width | string (CSS length) | `100%` | Any CSS length (e.g. `12rem`, `50%`). |
+| height | string (CSS length) | `1rem` (or `1em` when `shape=text`) | Any CSS length. |
+| radius | string (CSS length) | `0.25rem` | Corner radius; ignored when `shape=circle`. |
+
+## Parts
+| Part | Description |
+|------|-------------|
+| surface | The shimmering inner surface. |
+
+## Accessibility
+The host sets `role="status" aria-busy="true" aria-label="Loading"` on connection, so assistive tech announces the loading region. Under `prefers-reduced-motion: reduce`, the shimmer animation is removed and a flat surface color is used.
+
+## Examples
+```html
+<!-- Single line of text -->
+<schmancy-skeleton shape="text" width="60%"></schmancy-skeleton>
+
+<!-- Avatar placeholder -->
+<schmancy-skeleton shape="circle" width="48px" height="48px"></schmancy-skeleton>
+
+<!-- Card placeholder -->
+<schmancy-card>
+  <schmancy-skeleton width="100%" height="160px" radius="0.5rem"></schmancy-skeleton>
+  <schmancy-skeleton shape="text" width="80%"></schmancy-skeleton>
+  <schmancy-skeleton shape="text" width="40%"></schmancy-skeleton>
+</schmancy-card>
+```

package/skills/schmancy/splash-screen.md

@@ -0,0 +1,60 @@
+# schmancy-splash-screen
+
+> Full-viewport splash overlay that fades out once ready; consumer supplies the visuals.
+
+## Usage
+```html
+<schmancy-splash-screen min-duration="1200">
+  <my-logo slot="splash"></my-logo>
+  <my-app></my-app>
+</schmancy-splash-screen>
+```
+
+The `splash` slot holds the overlay content (logo, animation, whatever). The default slot is the real app, revealed after the splash dismisses. The overlay is empty by default — no built-in spinner, no hidden dependencies. Bring your own visuals.
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| minDuration | number | `1500` | Minimum ms the splash stays visible (prevents flash on fast loads). |
+| auto | boolean | `false` | When true, dismiss on the `minDuration` timer alone. When false, also wait for a `ready` signal. |
+| initiallyHidden | boolean | `false` | When true, the splash starts hidden. Use with `show()` for imperative control (e.g. between route transitions). |
+
+## Methods
+| Method | Description |
+|--------|-------------|
+| `ready()` | Signal that the app is ready — dismisses once `minDuration` has also elapsed. |
+| `show()` | Force the splash back on (e.g. re-show between route transitions). |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| schmancy-splash-done | `void` | Fires when the splash finishes dismissing. |
+
+## CSS custom properties
+| Property | Default | Description |
+|----------|---------|-------------|
+| `--schmancy-splash-background` | `var(--schmancy-sys-color-surface-containerLowest, #000)` | Splash layer background. |
+| `--schmancy-splash-transition` | `500ms` | Fade duration. |
+
+## Examples
+```html
+<!-- Wait for explicit ready signal (default) -->
+<schmancy-splash-screen min-duration="800">
+  <img slot="splash" src="/logo.svg" />
+  <main-app></main-app>
+</schmancy-splash-screen>
+```
+
+```typescript
+// Imperative: signal ready when data loads
+const splash = document.querySelector('schmancy-splash-screen')!
+dataStore.loaded$.subscribe(() => splash.ready())
+```
+
+```html
+<!-- Auto mode: dismisses purely on the timer -->
+<schmancy-splash-screen min-duration="1200" auto>
+  <schmancy-typography type="display" token="lg" slot="splash">Welcome</schmancy-typography>
+  <app-shell></app-shell>
+</schmancy-splash-screen>
+```

package/skills/schmancy/switch.md

@@ -0,0 +1,58 @@
+# schmancy-switch
+
+> Binary on/off control. Form-associated, ARIA `role="switch"`. Use for immediate state changes; use `<schmancy-checkbox>` for form selections.
+
+## Usage
+```html
+<schmancy-switch name="notifications" label="Email notifications" @change=${(e) => handle(e.detail.value)}>
+</schmancy-switch>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| checked | boolean | `false` | Current on/off state. Reflected as attribute. |
+| name | string | `''` | Form submission name. |
+| value | string | `'on'` | Value submitted when checked. |
+| label | string | `''` | ARIA label on the inner button; also used by axe. |
+| required | boolean | `false` | Must be on for form validity. |
+| disabled | boolean | `false` | Disables interaction. |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| change | `{ value: boolean }` | Fires when the state toggles (via click or Enter/Space). |
+
+## Parts
+| Part | Description |
+|------|-------------|
+| track | Background track element. |
+| thumb | Moving thumb element. |
+
+## States
+| State | When |
+|-------|------|
+| `:state(checked)` | While the switch is on. Target via `schmancy-switch:state(checked) { … }`. |
+
+## Form association
+Uses `ElementInternals` — participates in `<form>` submission natively. Contributes `name=value` when checked; omitted when unchecked. `formResetCallback` restores the initial `checked` attribute. `formDisabledCallback` propagates `<fieldset disabled>`.
+
+## Examples
+```html
+<!-- Inside a form -->
+<schmancy-form>
+  <schmancy-switch name="marketing" label="Marketing emails"></schmancy-switch>
+  <schmancy-switch name="product" label="Product updates" checked></schmancy-switch>
+  <schmancy-button type="submit">Save</schmancy-button>
+</schmancy-form>
+```
+
+```html
+<!-- Required toggle (must be on to submit) -->
+<schmancy-switch name="agree" label="I agree" required></schmancy-switch>
+```
+
+```html
+<!-- Custom submitted value -->
+<schmancy-switch name="mode" value="dark" label="Dark mode"></schmancy-switch>
+```

package/skills/schmancy/tooltip.md

@@ -1,6 +1,6 @@
 # tooltip (directive)
 
-> Lit directive that adds a positioned tooltip to any element on hover/focus.
+> Lit directive that adds a positioned tooltip to any element on hover/focus. The `<schmancy-tooltip>` component was removed — use this directive.
 
 ## Usage
 ```typescript

package/skills/schmancy/visually-hidden.md

@@ -0,0 +1,41 @@
+# schmancy-visually-hidden
+
+> Hide content visually while keeping it in the accessibility tree. For screen-reader-only labels, supplemental descriptions, and live-region text.
+
+## Usage
+```html
+<button>
+  <schmancy-icon>close</schmancy-icon>
+  <schmancy-visually-hidden>Close dialog</schmancy-visually-hidden>
+</button>
+```
+
+## Why not `display: none` / `visibility: hidden` / `aria-hidden`?
+Those remove content from assistive tech too. `<schmancy-visually-hidden>` uses the WCAG-recommended clip pattern, so screen readers still read the content while sighted users don't see it.
+
+## Properties
+None. Pure wrapper.
+
+## Examples
+```html
+<!-- Icon-only button label -->
+<schmancy-icon-button>
+  <schmancy-icon>delete</schmancy-icon>
+  <schmancy-visually-hidden>Delete item</schmancy-visually-hidden>
+</schmancy-icon-button>
+```
+
+```html
+<!-- Additional context for links -->
+<a href="/article/42">
+  Read more
+  <schmancy-visually-hidden>about quarterly earnings</schmancy-visually-hidden>
+</a>
+```
+
+```html
+<!-- Live region announcements -->
+<schmancy-visually-hidden role="status" aria-live="polite">
+  ${this.status}
+</schmancy-visually-hidden>
+```

package/src/audio/emotional-sounds.ts

@@ -78,10 +78,8 @@ export type Feeling =
   | HappyFeeling | SadFeeling | AnxiousFeeling | AngryFeeling
   | TiredFeeling | CalmFeeling | ConnectedFeeling | MixedFeeling
 
-/** Feeling category */
-export type FeelingCategory =
-  | 'happy' | 'sad' | 'anxious' | 'angry'
-  | 'tired' | 'calm' | 'connected' | 'mixed'
+// FeelingCategory is defined in ../types/mood-audio.types.ts and re-exported
+// from ./index.ts — the canonical source.
 
 // ============================================================================
 // SOUND GENERATOR

package/src/autocomplete/autocomplete.ts

@@ -1,7 +1,7 @@
 import { $LitElement } from '@mixins/index'
 import { InputSize, SchmancyInput } from '@schmancy/input'
 import SchmancyOption from '@schmancy/option/option'
-import { html } from 'lit'
+import { html, nothing } from 'lit'
 import { customElement, property, query, queryAssignedElements, state } from 'lit/decorators.js'
 import { classMap } from 'lit/directives/class-map.js'
 import { createRef, ref } from 'lit/directives/ref.js'
@@ -48,6 +48,40 @@ interface FilteredOption {
  */
 @customElement('schmancy-autocomplete')
 export default class SchmancyAutocomplete extends $LitElement(style) {
+    static formAssociated = true
+    internals: ElementInternals | undefined
+
+    constructor() {
+        super()
+        try {
+            this.internals = this.attachInternals()
+        } catch {
+            this.internals = undefined
+        }
+    }
+
+    get form(): HTMLFormElement | null {
+        return this.internals?.form ?? null
+    }
+
+    formResetCallback(): void {
+        if (this.multi) {
+            this._selectedValues$.next([])
+        } else {
+            this._selectedValue$.next('')
+        }
+        this._inputValue = ''
+        this._inputValue$.next('')
+        this.error = false
+        this.validationMessage = ''
+    }
+
+    formDisabledCallback(disabled: boolean): void {
+        // The component does not expose a disabled prop directly; propagate via attribute.
+        if (disabled) this.setAttribute('disabled', '')
+        else this.removeAttribute('disabled')
+    }
+
     // Track whether value/values have been explicitly set
      _valueSet: boolean = false
      _valuesSet: boolean = false
@@ -67,6 +101,8 @@ export default class SchmancyAutocomplete extends $LitElement(style) {
     @property({ type: Boolean }) error = false
     @property({ type: String }) validationMessage = ''
 
+    private readonly _a11yId = `schmancy-autocomplete-${Math.random().toString(36).slice(2, 10)}`
+
     // Values property for multi-select mode
     @property({ type: Array })
     get values() {
@@ -139,6 +175,16 @@ export default class SchmancyAutocomplete extends $LitElement(style) {
         ]).pipe(
             tap(([selectedValue, selectedValues]) => {
                 this._updateOptionSelection(selectedValue, selectedValues)
+                // Keep ElementInternals form value in sync with selection (single and multi).
+                const formValue = this.multi ? selectedValues.join(',') : selectedValue
+                this.internals?.setFormValue(formValue || null)
+                if (this.required) {
+                    const missing = this.multi ? selectedValues.length === 0 : !selectedValue
+                    this.internals?.setValidity(
+                        missing ? { valueMissing: true } : {},
+                        missing ? this.validationMessage || 'Please select an option.' : undefined,
+                    )
+                }
             }),
             takeUntil(this.disconnecting)
         ).subscribe()
@@ -494,6 +540,10 @@ export default class SchmancyAutocomplete extends $LitElement(style) {
                                         .placeholder=${this._selectedValues$.value.length > 0 ? 'Add more...' : this.placeholder}
                                         .value=${this._inputValue}
                                         .autocomplete=${this.autocomplete}
+                                        aria-invalid=${this.error ? 'true' : 'false'}
+                                        aria-required=${this.required ? 'true' : 'false'}
+                                        aria-describedby=${this.error && this.validationMessage ? `${this._a11yId}-err` : nothing}
+                                        aria-label=${!this.label && this.placeholder ? this.placeholder : nothing}
                                         @input=${(e: Event) => {
                                             const value = (e.target as HTMLInputElement).value
                                             this._inputValue = value
@@ -517,7 +567,7 @@ export default class SchmancyAutocomplete extends $LitElement(style) {
 
                                 <!-- Validation message -->
                                 ${when(this.error && this.validationMessage, () => html`
-                                    <div class="mt-1 text-sm text-error-default">
+                                    <div id="${this._a11yId}-err" class="mt-1 text-sm text-error-default" role="alert">
                                         ${this.validationMessage}
                                     </div>
                                 `)}

package/src/breadcrumb/breadcrumb.ts

@@ -0,0 +1,109 @@
+import { TailwindElement } from '@mixins/index'
+import { css, html } from 'lit'
+import { customElement, property } from 'lit/decorators.js'
+
+/**
+ * Breadcrumb navigation container. Wraps a list of `schmancy-breadcrumb-item`
+ * elements with the correct ARIA landmark and semantics.
+ *
+ * @element schmancy-breadcrumb
+ * @slot - Default slot for `<schmancy-breadcrumb-item>` children.
+ * @attr separator - Character or string rendered between items. Default `/`.
+ * @csspart separator - The separator element.
+ */
+@customElement('schmancy-breadcrumb')
+export class SchmancyBreadcrumb extends TailwindElement(css`
+	:host {
+		display: block;
+	}
+	nav {
+		display: flex;
+		flex-wrap: wrap;
+		align-items: center;
+		gap: 0.25rem;
+	}
+	.sep {
+		color: var(--schmancy-sys-color-surface-onVariant, #79747e);
+		user-select: none;
+		padding: 0 0.25rem;
+	}
+	::slotted(schmancy-breadcrumb-item:last-of-type) {
+		font-weight: 500;
+	}
+`) {
+	@property({ type: String }) separator = '/'
+
+	connectedCallback(): void {
+		super.connectedCallback()
+		if (!this.hasAttribute('aria-label')) this.setAttribute('aria-label', 'Breadcrumb')
+	}
+
+	render() {
+		// Render separators between slotted items by manipulating after render.
+		// The simpler approach uses the CSS adjacent-sibling pattern so the
+		// separator is visually present without affecting the accessible name.
+		return html`
+			<nav role="navigation">
+				<slot @slotchange=${() => this._insertSeparators()}></slot>
+			</nav>
+		`
+	}
+
+	private _insertSeparators() {
+		const slot = this.shadowRoot?.querySelector('slot') as HTMLSlotElement | null
+		if (!slot) return
+		const items = slot.assignedElements({ flatten: true })
+		// Remove any previously-inserted separators.
+		this.querySelectorAll('[data-schmancy-sep]').forEach(el => el.remove())
+		items.forEach((el, idx) => {
+			if (idx === items.length - 1) return
+			const sep = document.createElement('span')
+			sep.setAttribute('data-schmancy-sep', '')
+			sep.setAttribute('aria-hidden', 'true')
+			sep.setAttribute('part', 'separator')
+			sep.className = 'sep'
+			sep.textContent = this.separator
+			el.insertAdjacentElement('afterend', sep)
+		})
+	}
+}
+
+/**
+ * Individual breadcrumb item. Renders as a link when `href` is provided,
+ * otherwise as a plain span (represents the current page).
+ *
+ * @element schmancy-breadcrumb-item
+ * @slot - Label content.
+ * @attr href - If set, renders as an anchor.
+ * @attr current - Marks as `aria-current="page"`.
+ */
+@customElement('schmancy-breadcrumb-item')
+export class SchmancyBreadcrumbItem extends TailwindElement(css`
+	:host {
+		display: inline-block;
+	}
+	a, span {
+		color: inherit;
+		text-decoration: none;
+	}
+	a:hover {
+		text-decoration: underline;
+	}
+`) {
+	@property({ type: String }) href = ''
+	@property({ type: Boolean, reflect: true }) current = false
+
+	render() {
+		if (this.href && !this.current) {
+			return html`<a href=${this.href}><slot></slot></a>`
+		}
+		return html`<span aria-current=${this.current ? 'page' : 'false'}><slot></slot></span>`
+	}
+}
+
+declare global {
+	interface HTMLElementTagNameMap {
+		'schmancy-breadcrumb': SchmancyBreadcrumb
+		'schmancy-breadcrumb-item': SchmancyBreadcrumbItem
+	}
+}

package/src/breadcrumb/index.ts

@@ -0,0 +1 @@
+export * from './breadcrumb'