@mhmo91/schmancy 0.9.4 → 0.9.6

package/src/splash-screen/splash-screen.ts

@@ -0,0 +1,154 @@
+import { $LitElement } from '@mixins/litElement.mixin'
+import { css, html } from 'lit'
+import { customElement, property, state } from 'lit/decorators.js'
+import { styleMap } from 'lit/directives/style-map.js'
+import { fromEvent, of, timer, zip } from 'rxjs'
+import { take, takeUntil, tap } from 'rxjs/operators'
+
+export type SchmancySplashScreenDoneEvent = CustomEvent<void>
+
+/**
+ * Full-viewport splash overlay that dismisses once a minimum duration has
+ * elapsed and (optionally) an external `ready` signal has fired. The splash
+ * fades out while the underlying app content fades in.
+ *
+ * Bring-your-own visuals: the `splash` slot is empty by default so the
+ * component pulls in no dependencies. Provide a logo, spinner, or
+ * animation from the consumer side.
+ *
+ * @element schmancy-splash-screen
+ * @slot splash - Content rendered on the splash layer (logo, spinner, etc.).
+ * @slot - Default slot for the actual app content, revealed once dismissed.
+ * @fires schmancy-splash-done - `CustomEvent<void>` when the splash dismisses.
+ *
+ * @example
+ * ```html
+ * <schmancy-splash-screen min-duration="1200">
+ *   <my-logo slot="splash"></my-logo>
+ *   <my-app></my-app>
+ * </schmancy-splash-screen>
+ * ```
+ */
+@customElement('schmancy-splash-screen')
+export default class SchmancySplashScreen extends $LitElement(css`
+	:host {
+		display: block;
+		position: relative;
+	}
+
+	.splash-layer {
+		position: fixed;
+		inset: 0;
+		z-index: 50;
+		overflow: hidden;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		background: var(
+			--schmancy-splash-background,
+			var(--schmancy-sys-color-surface-containerLowest, #000)
+		);
+		transition: opacity var(--schmancy-splash-transition, 500ms) ease-out;
+	}
+
+	.content-layer {
+		display: block;
+		width: 100%;
+		transition: opacity var(--schmancy-splash-transition, 500ms) ease-in-out;
+	}
+`) {
+	/**
+	 * Minimum duration (ms) the splash layer stays visible. Prevents a flash
+	 * when the app loads faster than expected.
+	 */
+	@property({ type: Number, attribute: 'min-duration' }) minDuration = 1500
+
+	/**
+	 * When true, the splash dismisses on the `minDuration` timer alone.
+	 * When false (default), it additionally waits for an external ready signal
+	 * (a `ready` event on this element, or a call to `this.ready()`).
+	 */
+	@property({ type: Boolean }) auto = false
+
+	/**
+	 * When true, the splash starts hidden. Use this for imperative control.
+	 */
+	@property({ type: Boolean, attribute: 'initially-hidden' }) initiallyHidden = false
+
+	@state() private _visible = true
+
+	connectedCallback() {
+		super.connectedCallback()
+
+		if (this.initiallyHidden) {
+			this._visible = false
+			return
+		}
+
+		const readySignal$ = this.auto ? of(null) : fromEvent<Event>(this, 'ready').pipe(take(1))
+		const minTimer$ = timer(this.minDuration)
+
+		zip(readySignal$, minTimer$)
+			.pipe(
+				take(1),
+				tap(() => this._dismiss()),
+				takeUntil(this.disconnecting),
+			)
+			.subscribe()
+	}
+
+	/**
+	 * Imperative API: signal that the app is ready and dismiss the splash
+	 * after the minimum duration has elapsed.
+	 */
+	public ready(): void {
+		this.dispatchEvent(new Event('ready'))
+	}
+
+	/**
+	 * Force the splash to show again (e.g. between route transitions).
+	 */
+	public show(): void {
+		this._visible = true
+	}
+
+	private _dismiss(): void {
+		this._visible = false
+		this.dispatchEvent(
+			new CustomEvent<void>('schmancy-splash-done', {
+				bubbles: true,
+				composed: true,
+			}),
+		)
+	}
+
+	render() {
+		return html`
+			<div
+				class="splash-layer"
+				aria-hidden=${!this._visible}
+				style=${styleMap({
+					opacity: this._visible ? '1' : '0',
+					pointerEvents: this._visible ? 'auto' : 'none',
+				})}
+			>
+				<slot name="splash"></slot>
+			</div>
+			<div
+				class="content-layer"
+				style=${styleMap({
+					opacity: this._visible ? '0' : '1',
+					pointerEvents: this._visible ? 'none' : 'auto',
+				})}
+			>
+				<slot></slot>
+			</div>
+		`
+	}
+}
+
+declare global {
+	interface HTMLElementTagNameMap {
+		'schmancy-splash-screen': SchmancySplashScreen
+	}
+}

package/src/switch/index.ts

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

package/src/switch/switch.test.ts

@@ -0,0 +1,93 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { expectNoA11yViolations } from '../test-utils/a11y'
+import './switch'
+
+describe('schmancy-switch', () => {
+	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 form-associated and contributes when checked', async () => {
+		host.innerHTML = `
+			<form>
+				<schmancy-switch name="notify" value="yes"></schmancy-switch>
+			</form>
+		`
+		const form = host.querySelector('form') as HTMLFormElement
+		const sw = host.querySelector('schmancy-switch') as HTMLElement & { checked: boolean }
+		sw.checked = true
+		await nextUpdate()
+		await nextUpdate()
+		expect(new FormData(form).get('notify')).toBe('yes')
+	})
+
+	it('omits from FormData when unchecked', async () => {
+		host.innerHTML = `<form><schmancy-switch name="notify"></schmancy-switch></form>`
+		const form = host.querySelector('form') as HTMLFormElement
+		await nextUpdate()
+		expect(new FormData(form).get('notify')).toBeNull()
+	})
+
+	it('fires change on toggle and broadcasts :state(checked)', async () => {
+		host.innerHTML = `<schmancy-switch></schmancy-switch>`
+		const sw = host.querySelector('schmancy-switch') as HTMLElement & {
+			checked: boolean
+			updateComplete: Promise<boolean>
+		}
+		await sw.updateComplete
+		let detail: { value: boolean } | undefined
+		sw.addEventListener('change', (e: Event) => {
+			detail = (e as CustomEvent).detail
+		})
+		const btn = sw.shadowRoot!.querySelector('button') as HTMLButtonElement
+		btn.click()
+		await nextUpdate()
+		await nextUpdate()
+		expect(detail).toEqual({ value: true })
+		expect(sw.matches(':state(checked)')).toBe(true)
+	})
+
+	it('exposes role="switch" with aria-checked', async () => {
+		host.innerHTML = `<schmancy-switch></schmancy-switch>`
+		const sw = host.querySelector('schmancy-switch') as HTMLElement & {
+			updateComplete: Promise<boolean>
+		}
+		await sw.updateComplete
+		const btn = sw.shadowRoot!.querySelector('button') as HTMLButtonElement
+		expect(btn.getAttribute('role')).toBe('switch')
+		expect(btn.getAttribute('aria-checked')).toBe('false')
+	})
+
+	it('has no axe-core a11y violations', async () => {
+		host.innerHTML = `<schmancy-switch label="Notifications"></schmancy-switch>`
+		const sw = host.querySelector('schmancy-switch') as HTMLElement & {
+			updateComplete: Promise<boolean>
+		}
+		await sw.updateComplete
+		await expectNoA11yViolations(host)
+	})
+
+	it('fails validation when required and unchecked', async () => {
+		host.innerHTML = `<form><schmancy-switch name="agree" required></schmancy-switch></form>`
+		const form = host.querySelector('form') as HTMLFormElement
+		const sw = host.querySelector('schmancy-switch') as HTMLElement & {
+			checked: boolean
+			checkValidity(): boolean
+		}
+		await nextUpdate()
+		expect(form.checkValidity()).toBe(false)
+		sw.checked = true
+		await nextUpdate()
+		await nextUpdate()
+		expect(form.checkValidity()).toBe(true)
+	})
+})

package/src/switch/switch.ts

@@ -0,0 +1,180 @@
+import { TailwindElement } from '@mixins/index'
+import { css, html, LitElement, nothing } from 'lit'
+import { customElement, property } from 'lit/decorators.js'
+
+export type SchmancySwitchChangeEvent = CustomEvent<{ value: boolean }>
+
+/**
+ * Binary on/off control. Form-associated, keyboard-accessible, semantically a
+ * switch (ARIA role="switch"). Distinct from `schmancy-checkbox`: a switch
+ * represents an immediate state change, a checkbox represents a selection in
+ * a form to be submitted.
+ *
+ * @element schmancy-switch
+ * @fires change - `CustomEvent<{ value: boolean }>` when the state changes.
+ * @attr checked - Initial checked state (also reflected via `value`).
+ * @attr disabled - Disables interaction.
+ * @attr required - Requires the switch to be on for form validity.
+ * @attr name - Form field name for submission.
+ * @csspart track - The background track.
+ * @csspart thumb - The moving thumb.
+ */
+@customElement('schmancy-switch')
+export class SchmancySwitch extends TailwindElement(css`
+	:host {
+		display: inline-block;
+	}
+	:host([disabled]) {
+		opacity: 0.38;
+		pointer-events: none;
+	}
+	button {
+		appearance: none;
+		background: none;
+		border: 0;
+		padding: 0;
+		cursor: pointer;
+		font: inherit;
+	}
+	.track {
+		width: 2.25rem;
+		height: 1.25rem;
+		border-radius: 999px;
+		background: var(--schmancy-sys-color-surface-containerHighest, #e0e0e0);
+		border: 1px solid var(--schmancy-sys-color-outline, #79747e);
+		position: relative;
+		transition: background 150ms ease, border-color 150ms ease;
+	}
+	:host(:state(checked)) .track {
+		background: var(--schmancy-sys-color-primary-default, #6750a4);
+		border-color: var(--schmancy-sys-color-primary-default, #6750a4);
+	}
+	.thumb {
+		position: absolute;
+		top: 50%;
+		left: 0.125rem;
+		width: 0.75rem;
+		height: 0.75rem;
+		border-radius: 999px;
+		background: var(--schmancy-sys-color-outline, #79747e);
+		transform: translateY(-50%);
+		transition: transform 150ms ease, background 150ms ease, width 150ms ease, height 150ms ease;
+	}
+	:host(:state(checked)) .thumb {
+		transform: translate(1rem, -50%);
+		width: 1rem;
+		height: 1rem;
+		background: var(--schmancy-sys-color-primary-on, #ffffff);
+	}
+	button:focus-visible .track {
+		outline: 2px solid var(--schmancy-sys-color-primary-default, #6750a4);
+		outline-offset: 2px;
+	}
+	@media (prefers-reduced-motion: reduce) {
+		.track, .thumb { transition: none; }
+	}
+`) {
+	static formAssociated = true
+	private internals: ElementInternals | undefined
+
+	@property({ type: Boolean, reflect: true }) checked = false
+	@property({ type: Boolean, reflect: true }) disabled = false
+	@property({ type: Boolean, reflect: true }) required = false
+	@property({ type: String }) name = ''
+	@property({ type: String }) value = 'on'
+	@property({ type: String }) label = ''
+
+	protected static shadowRootOptions = {
+		...LitElement.shadowRootOptions,
+		delegatesFocus: true,
+	}
+
+	constructor() {
+		super()
+		try {
+			this.internals = this.attachInternals()
+		} catch {
+			this.internals = undefined
+		}
+	}
+
+	get form(): HTMLFormElement | null {
+		return this.internals?.form ?? null
+	}
+
+	protected updated(changed: Map<string, unknown>) {
+		super.updated?.(changed)
+		if (changed.has('checked') || changed.has('value') || changed.has('name')) {
+			this.internals?.setFormValue(this.checked ? this.value : null)
+			if (this.checked) this.internals?.states.add('checked')
+			else this.internals?.states.delete('checked')
+		}
+		if (changed.has('required') || changed.has('checked')) {
+			if (this.required && !this.checked) {
+				this.internals?.setValidity({ valueMissing: true }, 'This switch is required.')
+			} else {
+				this.internals?.setValidity({})
+			}
+		}
+	}
+
+	formResetCallback() {
+		this.checked = this.hasAttribute('checked')
+	}
+
+	formDisabledCallback(disabled: boolean) {
+		this.disabled = disabled
+	}
+
+	public checkValidity(): boolean {
+		return this.internals?.checkValidity() ?? true
+	}
+
+	public reportValidity(): boolean {
+		return this.internals?.reportValidity() ?? true
+	}
+
+	private _toggle = () => {
+		if (this.disabled) return
+		this.checked = !this.checked
+		this.dispatchEvent(
+			new CustomEvent('change', {
+				detail: { value: this.checked },
+				bubbles: true,
+				composed: true,
+			}),
+		)
+	}
+
+	private _onKeydown = (e: KeyboardEvent) => {
+		if (e.key === ' ' || e.key === 'Enter') {
+			e.preventDefault()
+			this._toggle()
+		}
+	}
+
+	render() {
+		return html`
+			<button
+				type="button"
+				role="switch"
+				aria-checked=${this.checked ? 'true' : 'false'}
+				aria-label=${this.label || nothing}
+				aria-required=${this.required ? 'true' : 'false'}
+				?disabled=${this.disabled}
+				@click=${this._toggle}
+				@keydown=${this._onKeydown}
+			>
+				<span part="track" class="track">
+					<span part="thumb" class="thumb"></span>
+				</span>
+			</button>
+		`
+	}
+}
+
+declare global {
+	interface HTMLElementTagNameMap {
+		'schmancy-switch': SchmancySwitch
+	}
+}

package/src/test-utils/a11y.ts

@@ -0,0 +1,35 @@
+import axe, { type ElementContext, type RunOptions, type Result } from 'axe-core'
+import { expect } from 'vitest'
+
+/**
+ * Run axe-core on the given element (or document) and assert no violations.
+ * Throws a readable failure with a summary of violations so test output is
+ * immediately actionable.
+ *
+ * Keep the axe rule set minimal and appropriate for component tests — the
+ * defaults include many rules that only make sense at the page level (e.g.
+ * `region`, `landmark-one-main`). Override via `options.rules` when needed.
+ */
+export async function expectNoA11yViolations(
+	context: ElementContext = document.body,
+	options: RunOptions = {
+		// Exclude page-level rules that don't apply to a component-in-isolation.
+		rules: {
+			region: { enabled: false },
+			'landmark-one-main': { enabled: false },
+			'page-has-heading-one': { enabled: false },
+			'html-has-lang': { enabled: false },
+			'document-title': { enabled: false },
+			bypass: { enabled: false },
+		},
+	},
+): Promise<Result[]> {
+	const results = await axe.run(context, options)
+	if (results.violations.length > 0) {
+		const summary = results.violations
+			.map(v => `  • ${v.id} (${v.impact}): ${v.help}\n    ${v.helpUrl}`)
+			.join('\n')
+		expect.fail(`axe-core found ${results.violations.length} a11y violation(s):\n${summary}`)
+	}
+	return results.violations
+}

package/src/textarea/textarea.ts

@@ -1,4 +1,4 @@
-import { LitElement, html } from 'lit'
+import { LitElement, html, nothing, type PropertyValues } from 'lit'
 import { customElement, property, query } from 'lit/decorators.js'
 import { ifDefined } from 'lit/directives/if-defined.js'
 import { createRef, ref } from 'lit/directives/ref.js'
@@ -30,6 +30,8 @@ export default class SchmancyTextarea extends TailwindElement(style) {
 	internals: ElementInternals | undefined
 	textareaRef = createRef<HTMLTextAreaElement>()
 
+	private readonly _a11yId = `schmancy-textarea-${Math.random().toString(36).slice(2, 10)}`
+
 	/**
 	 * The label of the control.
 	 * @attr
@@ -179,6 +181,29 @@ export default class SchmancyTextarea extends TailwindElement(style) {
 		}
 	}
 
+	protected willUpdate(changed: PropertyValues): void {
+		super.willUpdate?.(changed)
+		if (changed.has('value') || changed.has('name')) {
+			this.internals?.setFormValue(this.value ?? '')
+		}
+		if (changed.has('required') || changed.has('value')) {
+			if (this.required && !this.value) {
+				this.internals?.setValidity({ valueMissing: true }, 'Please fill out this field.')
+			} else {
+				this.internals?.setValidity({})
+			}
+		}
+	}
+
+	formResetCallback(): void {
+		this.value = this.getAttribute('value') ?? ''
+		this.error = false
+	}
+
+	formDisabledCallback(disabled: boolean): void {
+		this.disabled = disabled
+	}
+
 	firstUpdated() {
 		if (this.autofocus) {
 			this.focus()
@@ -375,6 +400,7 @@ export default class SchmancyTextarea extends TailwindElement(style) {
 			'w-full min-w-0': true,
 			'flex flex-col h-full': this.fillHeight,
 		}
+		const hintId = `${this._a11yId}-hint`
 		return html`
 		<div class="${this.classMap(containerClasses)}">
 			${when(
@@ -404,12 +430,16 @@ export default class SchmancyTextarea extends TailwindElement(style) {
 				rows=${ifDefined(this.rows)}
 				wrap=${ifDefined(this.wrap)}
 				dirname=${ifDefined(this.dirname)}
+				aria-invalid=${this.error ? 'true' : 'false'}
+				aria-required=${this.required ? 'true' : 'false'}
+				aria-describedby=${this.hint ? hintId : nothing}
+				aria-label=${!this.label && this.placeholder ? this.placeholder : nothing}
 			></textarea>
 
 			${when(
 				this.hint,
 				() => html`
-					<div class="mt-1 text-sm ${this.error ? 'text-error-default' : 'text-surface-onVariant'}">
+					<div id=${hintId} class="mt-1 text-sm ${this.error ? 'text-error-default' : 'text-surface-onVariant'}">
 						${this.hint}
 					</div>
 				`,

package/src/tooltip/index.ts

@@ -1,2 +1 @@
-export * from './tooltip.directive';
-export * from './tooltip';
+export * from './tooltip.directive'

package/src/tree/tree.ts

@@ -34,6 +34,22 @@ export class SchmancyTree extends TailwindElement(css`
 	// Since it's actually a <schmancy-button>, use HTMLElement or a custom type
 	@query('#chevron') chevron!: HTMLElement
 
+	private readonly _a11yId = `schmancy-tree-${Math.random().toString(36).slice(2, 10)}`
+	private get _contentId() { return `${this._a11yId}-content` }
+
+	/** ElementInternals — broadcasts `:state(open)` for consumer CSS. */
+	private readonly _internals: ElementInternals | undefined = (() => {
+		try { return this.attachInternals() } catch { return undefined }
+	})()
+
+	updated(changed: Map<string, unknown>) {
+		super.updated?.(changed)
+		if (changed.has('open')) {
+			if (this.open) this._internals?.states.add('open')
+			else this._internals?.states.delete('open')
+		}
+	}
+
 	firstUpdated() {
 		// Hide or show the slot initially based on `open`
 		if (!this.open) {
@@ -116,11 +132,20 @@ export class SchmancyTree extends TailwindElement(css`
 
 				<!-- The chevron or arrow symbol -->
 				<!-- Stop propagation on the schmancy-button itself just to avoid double triggers -->
-				<schmancy-button slot="trailing" id="chevron" @click=${(e: Event) => e.stopPropagation()}> ⌅ </schmancy-button>
+				<schmancy-button
+					slot="trailing"
+					id="chevron"
+					aria-expanded=${this.open ? 'true' : 'false'}
+					aria-controls=${this._contentId}
+					aria-label=${this.open ? 'Collapse' : 'Expand'}
+					@click=${(e: Event) => e.stopPropagation()}
+				>
+					⌅
+				</schmancy-button>
 			</div>
 
 			<!-- The default slot: tree children -->
-			<slot></slot>
+			<slot id=${this._contentId}></slot>
 		`
 	}
 }

package/src/visually-hidden/index.ts

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

package/src/visually-hidden/visually-hidden.ts

@@ -0,0 +1,39 @@
+import { TailwindElement } from '@mixins/index'
+import { css, html } from 'lit'
+import { customElement } from 'lit/decorators.js'
+
+/**
+ * Hides content visually while keeping it in the accessibility tree. Use for
+ * screen-reader-only labels, supplemental descriptions, and live-region text
+ * that sighted users don't need to see.
+ *
+ * Uses the WCAG-recommended clip pattern rather than `display: none` or
+ * `visibility: hidden` so assistive tech still reads the content.
+ *
+ * @element schmancy-visually-hidden
+ * @slot - Content hidden from sighted users but exposed to assistive tech.
+ */
+@customElement('schmancy-visually-hidden')
+export class SchmancyVisuallyHidden extends TailwindElement(css`
+	:host {
+		position: absolute;
+		width: 1px;
+		height: 1px;
+		padding: 0;
+		margin: -1px;
+		overflow: hidden;
+		clip: rect(0, 0, 0, 0);
+		white-space: nowrap;
+		border-width: 0;
+	}
+`) {
+	render() {
+		return html`<slot></slot>`
+	}
+}
+
+declare global {
+	interface HTMLElementTagNameMap {
+		'schmancy-visually-hidden': SchmancyVisuallyHidden
+	}
+}