@mhmo91/schmancy 0.9.5 → 0.9.7

package/src/icons/icon.ts

@@ -24,6 +24,7 @@ export type IconSize = 'xxs' | 'xs' | 'sm' | 'md' | 'lg' | string
  * @cssprop --schmancy-icon-weight - Weight value for icon (100-700)
  * @cssprop --schmancy-icon-grade - Grade value for icon (-50-200)
  * @cssprop --schmancy-icon-opsz - Optical size (default: 24)
+ * @csspart icon - The inner `<span>` carrying the Material Symbols glyph.
  */
 @customElement('schmancy-icon')
 export default class SchmancyIcon extends TailwindElement(css`

package/src/index.ts

@@ -67,3 +67,9 @@ export * from './typewriter';
 export * from './typography';
 export * from './utils';
 export * from './avatar';
+export * from './breadcrumb';
+export * from './kbd';
+export * from './skeleton';
+export * from './splash-screen';
+export * from './switch';
+export * from './visually-hidden';

package/src/kbd/index.ts

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

package/src/kbd/kbd.ts

@@ -0,0 +1,59 @@
+import { TailwindElement } from '@mixins/index'
+import { css, html } from 'lit'
+import { customElement, property } from 'lit/decorators.js'
+
+/**
+ * Renders a keyboard shortcut hint (e.g. `⌘ K`, `Ctrl+C`). Semantically a
+ * `<kbd>` element for screen readers; visually styled as a pressed key.
+ *
+ * Compose multiple instances for combinations:
+ * ```html
+ * <schmancy-kbd>⌘</schmancy-kbd> + <schmancy-kbd>K</schmancy-kbd>
+ * ```
+ *
+ * @element schmancy-kbd
+ * @slot - The key label (e.g. `⌘`, `Shift`, `K`).
+ * @attr size - 'sm' | 'md'. Default 'md'.
+ * @csspart base - The inner native `<kbd>` element.
+ */
+@customElement('schmancy-kbd')
+export class SchmancyKbd extends TailwindElement(css`
+	:host {
+		display: inline-block;
+		vertical-align: middle;
+	}
+	kbd {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		min-width: var(--_ksize, 1.5rem);
+		height: var(--_ksize, 1.5rem);
+		padding: 0 0.375rem;
+		font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+		font-size: var(--_kfont, 0.75rem);
+		font-weight: 500;
+		line-height: 1;
+		color: var(--schmancy-sys-color-surface-on, #1d1b20);
+		background: var(--schmancy-sys-color-surface-container, #f3f0f7);
+		border: 1px solid var(--schmancy-sys-color-outline-variant, #cac4d0);
+		border-radius: 0.375rem;
+		box-shadow: inset 0 -1px 0 var(--schmancy-sys-color-outline-variant, #cac4d0);
+		white-space: nowrap;
+	}
+	:host([size='sm']) kbd {
+		--_ksize: 1.25rem;
+		--_kfont: 0.6875rem;
+	}
+`) {
+	@property({ type: String, reflect: true }) size: 'sm' | 'md' = 'md'
+
+	render() {
+		return html`<kbd part="base"><slot></slot></kbd>`
+	}
+}
+
+declare global {
+	interface HTMLElementTagNameMap {
+		'schmancy-kbd': SchmancyKbd
+	}
+}

package/src/skeleton/index.ts

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

package/src/skeleton/skeleton.ts

@@ -0,0 +1,78 @@
+import { TailwindElement } from '@mixins/index'
+import { css, html } from 'lit'
+import { customElement, property } from 'lit/decorators.js'
+
+/**
+ * Placeholder shimmer surface shown while content loads. Renders a
+ * shape-configurable rectangle with a reduced-motion-aware shimmer.
+ *
+ * @element schmancy-skeleton
+ * @attr shape - 'rect' | 'circle' | 'text'. Default 'rect'.
+ * @attr width  - CSS length (e.g. `100%`, `12rem`).
+ * @attr height - CSS length; for `shape=text` defaults to 1em.
+ * @attr radius - CSS length for corner radius; ignored for `shape=circle`.
+ * @csspart surface - The shimmering surface element.
+ */
+@customElement('schmancy-skeleton')
+export class SchmancySkeleton extends TailwindElement(css`
+	:host {
+		display: block;
+		width: var(--_sw, 100%);
+		height: var(--_sh, 1rem);
+	}
+	.surface {
+		width: 100%;
+		height: 100%;
+		border-radius: var(--_sr, 0.25rem);
+		background: linear-gradient(
+			90deg,
+			var(--schmancy-sys-color-surface-containerHighest, #e6e6e6) 25%,
+			var(--schmancy-sys-color-surface-container, #f2f2f2) 37%,
+			var(--schmancy-sys-color-surface-containerHighest, #e6e6e6) 63%
+		);
+		background-size: 400% 100%;
+		animation: schmancy-skeleton-shimmer 1.4s ease infinite;
+	}
+	:host([shape='circle']) .surface {
+		border-radius: 50%;
+	}
+	@keyframes schmancy-skeleton-shimmer {
+		0% { background-position: 100% 50%; }
+		100% { background-position: 0 50%; }
+	}
+	@media (prefers-reduced-motion: reduce) {
+		.surface {
+			animation: none;
+			background: var(--schmancy-sys-color-surface-containerHighest, #e6e6e6);
+		}
+	}
+`) {
+	@property({ type: String, reflect: true }) shape: 'rect' | 'circle' | 'text' = 'rect'
+	@property({ type: String }) width = ''
+	@property({ type: String }) height = ''
+	@property({ type: String }) radius = ''
+
+	connectedCallback(): void {
+		super.connectedCallback()
+		this.setAttribute('role', 'status')
+		this.setAttribute('aria-busy', 'true')
+		this.setAttribute('aria-label', 'Loading')
+	}
+
+	protected updated(): void {
+		if (this.width) this.style.setProperty('--_sw', this.width)
+		const defaultHeight = this.shape === 'text' ? '1em' : '1rem'
+		this.style.setProperty('--_sh', this.height || defaultHeight)
+		if (this.radius) this.style.setProperty('--_sr', this.radius)
+	}
+
+	render() {
+		return html`<div part="surface" class="surface"></div>`
+	}
+}
+
+declare global {
+	interface HTMLElementTagNameMap {
+		'schmancy-skeleton': SchmancySkeleton
+	}
+}

package/src/splash-screen/index.ts

@@ -0,0 +1 @@
+export * from './splash-screen';

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
+}