@mhmo91/schmancy 0.9.5 → 0.9.7

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'

package/src/button/button.ts

@@ -19,6 +19,7 @@ export type ButtonColor = 'primary' | 'secondary' | 'success' | 'error' | 'warni
  * @slot - The default slot.
  * @slot prefix - The prefix slot.
  * @slot suffix - The suffix slot.
+ * @csspart base - The underlying native `<button>` (or `<a>` when `href` is set).
  */
 @customElement('schmancy-button')
 export class SchmancyButton extends $LitElement(
@@ -57,6 +58,45 @@ export class SchmancyButton extends $LitElement(
 		delegatesFocus: true,
 	}
 
+	static formAssociated = true
+	private internals: ElementInternals | undefined
+
+	constructor() {
+		super()
+		try {
+			this.internals = this.attachInternals()
+		} catch {
+			this.internals = undefined
+		}
+		// Translate clicks into native form semantics so the button works
+		// inside any <form>, not just inside <schmancy-form>.
+		this.addEventListener('click', (e: MouseEvent) => {
+			if (this.disabled) {
+				e.preventDefault()
+				e.stopImmediatePropagation()
+				return
+			}
+			const form = this.internals?.form
+			if (!form) return
+			if (this.type === 'submit') {
+				e.preventDefault()
+				form.requestSubmit()
+			} else if (this.type === 'reset') {
+				e.preventDefault()
+				form.reset()
+			}
+		})
+	}
+
+	/** Associated form, when placed inside a <form>. */
+	get form(): HTMLFormElement | null {
+		return this.internals?.form ?? null
+	}
+
+	formDisabledCallback(disabled: boolean): void {
+		this.disabled = disabled
+	}
+
 	@query('[part="base"]', true)
 	private nativeElement!: HTMLElement
 

package/src/button/icon-button.ts

@@ -9,7 +9,8 @@ import { ButtonVariant } from './button'
 /**
  * An icon button component.
  * @element schmancy-icon-button
- * @slot - The default slot.
+ * @slot - The default slot (usually an icon or glyph).
+ * @csspart base - The underlying native `<button>` (or `<a>` when `href` is set).
  */
 @customElement('schmancy-icon-button')
 export class SchmnacyIconButton extends $LitElement(css`

package/src/checkbox/checkbox.test.ts

@@ -0,0 +1,113 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { expectNoA11yViolations } from '../test-utils/a11y'
+import './checkbox'
+
+describe('schmancy-checkbox', () => {
+	let host: HTMLDivElement
+
+	beforeEach(() => {
+		host = document.createElement('div')
+		document.body.appendChild(host)
+	})
+
+	afterEach(() => {
+		host.remove()
+	})
+
+	const nextUpdate = () => new Promise(r => requestAnimationFrame(() => r(null)))
+
+	it('is defined on the element registry', () => {
+		expect(customElements.get('schmancy-checkbox')).toBeDefined()
+	})
+
+	it('has no axe-core a11y violations in default state', async () => {
+		host.innerHTML = `<schmancy-checkbox label="Accept terms"></schmancy-checkbox>`
+		await nextUpdate()
+		await nextUpdate()
+		await expectNoA11yViolations(host)
+	})
+
+	it('has no axe-core a11y violations when required + invalid', async () => {
+		host.innerHTML = `
+			<form>
+				<schmancy-checkbox name="agree" label="I agree" required></schmancy-checkbox>
+			</form>
+		`
+		await nextUpdate()
+		await nextUpdate()
+		await expectNoA11yViolations(host)
+	})
+
+	it('is form-associated and exposes an ElementInternals form', async () => {
+		host.innerHTML = `
+			<form id="f">
+				<schmancy-checkbox name="agree" required></schmancy-checkbox>
+			</form>
+		`
+		const form = host.querySelector('form') as HTMLFormElement
+		const cb = host.querySelector('schmancy-checkbox') as HTMLElement & { value: boolean; form: HTMLFormElement | null }
+		await nextUpdate()
+		expect(cb.form).toBe(form)
+	})
+
+	it('contributes its value to FormData when checked', async () => {
+		host.innerHTML = `
+			<form id="f">
+				<schmancy-checkbox name="agree"></schmancy-checkbox>
+			</form>
+		`
+		const form = host.querySelector('form') as HTMLFormElement
+		const cb = host.querySelector('schmancy-checkbox') as HTMLElement & { value: boolean }
+		cb.value = true
+		await nextUpdate()
+		await nextUpdate()
+		const fd = new FormData(form)
+		expect(fd.get('agree')).toBe('on')
+	})
+
+	it('omits its value when unchecked', async () => {
+		host.innerHTML = `
+			<form id="f">
+				<schmancy-checkbox name="agree"></schmancy-checkbox>
+			</form>
+		`
+		const form = host.querySelector('form') as HTMLFormElement
+		await nextUpdate()
+		const fd = new FormData(form)
+		expect(fd.get('agree')).toBeNull()
+	})
+
+	it('broadcasts :state(checked) when value is true', async () => {
+		host.innerHTML = `<schmancy-checkbox></schmancy-checkbox>`
+		const cb = host.querySelector('schmancy-checkbox') as HTMLElement & { value: boolean }
+		cb.value = true
+		await nextUpdate()
+		await nextUpdate()
+		expect(cb.matches(':state(checked)')).toBe(true)
+		cb.value = false
+		await nextUpdate()
+		await nextUpdate()
+		expect(cb.matches(':state(checked)')).toBe(false)
+	})
+
+	it('fails constraint validation when required and unchecked', async () => {
+		host.innerHTML = `
+			<form id="f">
+				<schmancy-checkbox name="agree" required></schmancy-checkbox>
+			</form>
+		`
+		const form = host.querySelector('form') as HTMLFormElement
+		const cb = host.querySelector('schmancy-checkbox') as HTMLElement & {
+			value: boolean
+			checkValidity(): boolean
+		}
+		await nextUpdate()
+		expect(cb.checkValidity()).toBe(false)
+		expect(form.checkValidity()).toBe(false)
+		cb.value = true
+		await nextUpdate()
+		await nextUpdate()
+		expect(cb.checkValidity()).toBe(true)
+		expect(form.checkValidity()).toBe(true)
+	})
+})

package/src/checkbox/checkbox.ts

@@ -21,8 +21,17 @@ class SchmancyCheckboxElement extends TailwindElement() {
 		delegatesFocus: true,
 	}
 	static formAssociated = true
-	// private internals
 	internals: ElementInternals | undefined
+
+	constructor() {
+		super()
+		try {
+			this.internals = this.attachInternals()
+		} catch {
+			// attachInternals can throw if the element does not support form association
+		}
+	}
+
 	get form() {
 		return this.internals?.form
 	}
@@ -76,6 +85,37 @@ class SchmancyCheckboxElement extends TailwindElement() {
 
 	connectedCallback() {
 		super.connectedCallback()
+		this._syncFormValue()
+	}
+
+	updated(changed: Map<string, unknown>) {
+		super.updated?.(changed)
+		if (changed.has('value') || changed.has('name')) this._syncFormValue()
+		if (changed.has('required') || changed.has('value')) this._syncValidity()
+		if (changed.has('value')) {
+			if (this.value) this.internals?.states.add('checked')
+			else this.internals?.states.delete('checked')
+		}
+	}
+
+	private _syncFormValue() {
+		this.internals?.setFormValue(this.value ? (this.getAttribute('true-value') ?? 'on') : null)
+	}
+
+	private _syncValidity() {
+		if (this.required && !this.value) {
+			this.internals?.setValidity({ valueMissing: true }, 'Please check this box if you want to proceed.')
+		} else {
+			this.internals?.setValidity({})
+		}
+	}
+
+	public checkValidity(): boolean {
+		return this.internals?.checkValidity() ?? true
+	}
+
+	public reportValidity(): boolean {
+		return this.internals?.reportValidity() ?? true
 	}
 
 	/**

package/src/chips/filter-chip.ts

@@ -113,6 +113,21 @@ export class SchmancyFilterChip extends TailwindElement(css`
 		super.connectedCallback()
 	}
 
+	protected updated(changed: Map<string, unknown>) {
+		super.updated?.(changed)
+		if (changed.has('value') || changed.has('selected')) {
+			this.internals?.setFormValue(this._selected ? (this.value || 'on') : null)
+		}
+	}
+
+	formResetCallback(): void {
+		this._selected = this.hasAttribute('selected')
+	}
+
+	formDisabledCallback(disabled: boolean): void {
+		this.disabled = disabled
+	}
+
 	private handleClick = () => {
 		if (this.disabled) return
 

package/src/chips/input-chip.ts

@@ -172,6 +172,13 @@ export class SchmancyInputChip extends TailwindElement(css`
 		return this.internals?.form
 	}
 
+	protected updated(changed: Map<string, unknown>) {
+		super.updated?.(changed)
+		if (changed.has('value')) {
+			this.internals?.setFormValue(this.value || null)
+		}
+	}
+
 	connectedCallback() {
 		super.connectedCallback()