@mhmo91/schmancy 0.10.15 → 0.10.16

package/src/{textarea → form/fields/textarea}/textarea.ts

@@ -3,9 +3,9 @@ import { customElement, property, query } from 'lit/decorators.js'
 import { ifDefined } from 'lit/directives/if-defined.js'
 import { createRef, ref } from 'lit/directives/ref.js'
 import { when } from 'lit/directives/when.js'
-import { distinctUntilChanged, filter, fromEvent, map } from 'rxjs'
+import { distinctUntilChanged, filter, fromEvent, map, takeUntil, timer } from 'rxjs'
 import style from './textarea.scss?inline'
-import { SchmancyElement } from '@mixins/index'
+import { SchmancyFormField } from '@mixins/index'
 
 /**
  * Textarea component with auto-resize and form integration.
@@ -20,38 +20,21 @@ import { SchmancyElement } from '@mixins/index'
  * @prop {number} maxlength - Maximum character length
  */
 @customElement('schmancy-textarea')
-export default class SchmancyTextarea extends SchmancyElement {
-	static styles = [unsafeCSS(style)];
+export default class SchmancyTextarea extends SchmancyFormField(unsafeCSS(style)) {
 
 	protected static shadowRootOptions = {
 		...LitElement.shadowRootOptions,
 		delegatesFocus: true,
 	}
-	static formAssociated = true
-	// private internals
-	internals: ElementInternals | undefined
+
+	// `formAssociated`, `internals`, `name`, `label`, `required`, `disabled`,
+	// `error`, `validationMessage`, `hint`, `id`, `validateOn`, `touched`,
+	// `dirty`, `submitted`, `markTouched`, `markSubmitted`, `setCustomValidity`,
+	// `formResetCallback`, `formDisabledCallback` — all from the mixin.
 	textareaRef = createRef<HTMLTextAreaElement>()
 
 	private readonly _a11yId = `schmancy-textarea-${Math.random().toString(36).slice(2, 10)}`
 
-	/**
-	 * The label of the control.
-	 * @attr
-	 * @type {string} label
-	 * @default ''
-	 * @public
-	 */
-	@property() label = ''
-
-	/**
-	 * The name of the control.
-	 * @attr name
-	 * @type {string} name
-	 * @default 'name_' + Date.now()
-	 * @public
-	 */
-	@property() name = 'name_' + Date.now()
-
 	/**
 	 * The placeholder of the control.
 	 * @attr placeholder
@@ -62,13 +45,11 @@ export default class SchmancyTextarea extends SchmancyElement {
 	@property() placeholder = ''
 
 	/**
-	 * The value of the control.
+	 * The value of the control. Narrowed from the mixin's wide union to the
+	 * textarea-specific `string` type.
 	 * @attr {string} value - The value of the control.
-	 * @type {string}
-	 * @default ''
-	 * @public
 	 */
-	@property({ type: String, reflect: true }) public value = ''
+	@property({ type: String, reflect: true }) override value: string = ''
 
 	/**
 	 * The minlength attribute of the control.
@@ -148,19 +129,14 @@ export default class SchmancyTextarea extends SchmancyElement {
 	 */
 	@property({ type: String }) dirname: string | undefined
 
-	@property({ type: Boolean, reflect: true }) required = false
-	@property({ type: Boolean, reflect: true }) disabled = false
-	@property({ type: Boolean, reflect: true }) readonly = false
+	// `required`, `disabled`, `readonly`, `error`, `validationMessage`, `hint`
+	// come from the mixin. Textarea-specific extras only:
 	@property({ type: Boolean, reflect: true }) spellcheck = false
 
 	@property({ type: String, reflect: true }) align: 'left' | 'center' | 'right' = 'left'
 
 	/**
 	 * The autofocus attribute of the control.
-	 * @attr
-	 * @type {boolean}
-	 * @default false
-	 * @public
 	 */
 	@property({ type: Boolean })
 	public override autofocus!: boolean
@@ -170,54 +146,33 @@ export default class SchmancyTextarea extends SchmancyElement {
 
 	@query('textarea') textareaElement!: HTMLTextAreaElement
 
-	@property() hint: string | undefined
-
-	@property({ type: Boolean, reflect: true }) public error = false
-
-	constructor() {
-		super()
-		try {
-			this.internals = this.attachInternals()
-		} catch {
-			this.internals = undefined
-		}
-	}
-
-	protected willUpdate(changed: PropertyValues): void {
-		super.willUpdate?.(changed)
-		if (changed.has('value') || changed.has('name')) {
-			this.internals?.setFormValue(this.value ?? '')
-		}
+	// Mixin's willUpdate already calls internals.setFormValue() on value-change
+	// and runs the required-empty / customError validity machinery. Native
+	// `valueMissing` flag is set here for richer ValidityState introspection.
+	override willUpdate(changed: PropertyValues): void {
+		super.willUpdate(changed)
 		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()
 		}
 		if (this.autoHeight) {
-			// Initial adjustment for pre-filled content
-			setTimeout(() => this.adjustHeight(), 0)
+			// Initial adjustment for pre-filled content (cancel-on-disconnect).
+			timer(0)
+				.pipe(takeUntil(this.disconnecting))
+				.subscribe(() => this.adjustHeight())
 		}
 		fromEvent(this.textareaElement, 'input')
 			.pipe(
 				map(event => (event.target as HTMLTextAreaElement).value),
 				distinctUntilChanged(),
+				takeUntil(this.disconnecting),
 			)
 			.subscribe(value => {
 				this.value = value
@@ -236,6 +191,7 @@ export default class SchmancyTextarea extends SchmancyElement {
 			.pipe(
 				map(event => (event.target as HTMLTextAreaElement).value),
 				distinctUntilChanged(),
+				takeUntil(this.disconnecting),
 			)
 			.subscribe(value => {
 				this.value = value
@@ -256,6 +212,7 @@ export default class SchmancyTextarea extends SchmancyElement {
 				filter(event => event.key === 'Enter'),
 				map(event => (event.target as HTMLTextAreaElement).value),
 				distinctUntilChanged(),
+				takeUntil(this.disconnecting),
 			)
 			.subscribe(value => {
 				this.value = value
@@ -434,15 +391,19 @@ export default class SchmancyTextarea extends SchmancyElement {
 				dirname=${ifDefined(this.dirname)}
 				aria-invalid=${this.error ? 'true' : 'false'}
 				aria-required=${this.required ? 'true' : 'false'}
-				aria-describedby=${this.hint ? hintId : nothing}
+				aria-describedby=${this.hint || (this.error && this.validationMessage) ? hintId : nothing}
 				aria-label=${!this.label && this.placeholder ? this.placeholder : nothing}
 			></textarea>
 
 			${when(
-				this.hint,
+				this.hint || (this.error && this.validationMessage),
 				() => html`
-					<div id=${hintId} class="mt-1 text-sm ${this.error ? 'text-error-default' : 'text-surface-onVariant'}">
-						${this.hint}
+					<div
+						id=${hintId}
+						class="mt-1 text-sm ${this.error ? 'text-error-default' : 'text-surface-onVariant'}"
+						role=${ifDefined(this.error ? 'alert' : undefined)}
+					>
+						${this.error && this.validationMessage ? this.validationMessage : this.hint}
 					</div>
 				`,
 			)}

package/src/form/form-state.ts

@@ -0,0 +1,31 @@
+/**
+ * Form-level submit state — consumed by `<schmancy-form>` and any descendant
+ * (e.g. `<schmancy-button type="submit">` to drive its loading/aria-busy).
+ *
+ * `<schmancy-form>` wraps its render output in `<schmancy-context
+ * .provides=${[formSubmitState]}>` so each instance gets an isolated copy
+ * via the schmancy state library's resolveContextual mechanism. Reads of
+ * `formSubmitState.value` and writes via `formSubmitState.set(...)` inside
+ * the form's subtree resolve to the per-form copy automatically — no
+ * `@lit/context` plumbing in user code.
+ */
+
+import { state } from '../state'
+
+export type FormError = {
+	message: string
+	code?: string
+}
+
+export type FormSubmitState = {
+	status: 'idle' | 'submitting' | 'success' | 'error'
+	error: FormError | null
+	/** Increments on every submit attempt — RHF parity. */
+	submitCount: number
+}
+
+export const formSubmitState = state<FormSubmitState>('schmancy/form-submit').memory({
+	status: 'idle',
+	error: null,
+	submitCount: 0,
+})

package/src/form/form-summary.test.ts

@@ -0,0 +1,105 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import './form'
+import './form-summary'
+import './fields/input/input'
+import '../button/button'
+import { expectNoA11yViolations } from '../test-utils/a11y'
+import type SchmancyForm from './form'
+
+const nextUpdate = () => new Promise(r => requestAnimationFrame(() => r(null)))
+
+describe('schmancy-form-summary', () => {
+	let host: HTMLDivElement
+
+	beforeEach(() => {
+		host = document.createElement('div')
+		document.body.appendChild(host)
+	})
+
+	afterEach(() => {
+		host.remove()
+	})
+
+	it('renders nothing when form is idle', async () => {
+		host.innerHTML = `
+			<schmancy-form>
+				<schmancy-form-summary></schmancy-form-summary>
+				<schmancy-input name="email" required></schmancy-input>
+			</schmancy-form>
+		`
+		await nextUpdate()
+		await nextUpdate()
+		const summary = host.querySelector('schmancy-form-summary') as HTMLElement
+		expect(summary.shadowRoot?.querySelector('[role="alert"]')).toBeNull()
+	})
+
+	it('renders banner with heading + form message after setFormError', async () => {
+		host.innerHTML = `
+			<schmancy-form>
+				<schmancy-form-summary></schmancy-form-summary>
+				<schmancy-input name="email" required></schmancy-input>
+			</schmancy-form>
+		`
+		const sf = host.querySelector('schmancy-form') as SchmancyForm
+		await nextUpdate()
+		await nextUpdate()
+		sf.setFormError('Network error — please try again.')
+		await nextUpdate()
+		await nextUpdate()
+		await nextUpdate()
+		const summary = host.querySelector('schmancy-form-summary') as HTMLElement
+		const banner = summary.shadowRoot?.querySelector('[role="alert"]') as HTMLElement
+		expect(banner).toBeTruthy()
+		expect(banner.textContent).toContain('Network error')
+	})
+
+	it('lists invalid field links after a failed submit', async () => {
+		host.innerHTML = `
+			<schmancy-form>
+				<schmancy-form-summary></schmancy-form-summary>
+				<schmancy-input name="email" label="Email" required></schmancy-input>
+				<schmancy-input name="city" label="City" required></schmancy-input>
+				<schmancy-button type="submit">Send</schmancy-button>
+			</schmancy-form>
+		`
+		const btn = host.querySelector('schmancy-button[type=submit]') as HTMLElement
+		await nextUpdate()
+		await nextUpdate()
+		btn.click()
+		// Wait long enough for: form submit chain → markSubmitted → field
+		// updates → live region populated → MutationObserver fired → form-summary
+		// re-render.
+		await new Promise(r => setTimeout(r, 200))
+		const summary = host.querySelector('schmancy-form-summary') as HTMLElement & {
+			updateComplete: Promise<boolean>
+		}
+		await summary.updateComplete
+
+		// Diagnostic: confirm fields actually report :state(invalid).
+		const fields = host.querySelectorAll('schmancy-input')
+		const invalidCount = Array.from(fields).filter(f => f.matches(':state(invalid)')).length
+		expect(invalidCount).toBe(2) // sanity — fields are flagged
+
+		const links = summary.shadowRoot?.querySelectorAll('a') ?? []
+		expect(links.length).toBe(2)
+		expect((links[0] as HTMLAnchorElement).textContent).toContain('Email')
+	})
+
+	it('has no axe-core a11y violations in error state', async () => {
+		host.innerHTML = `
+			<schmancy-form>
+				<schmancy-form-summary></schmancy-form-summary>
+				<schmancy-input name="email" label="Email" required></schmancy-input>
+				<schmancy-button type="submit">Send</schmancy-button>
+			</schmancy-form>
+		`
+		const sf = host.querySelector('schmancy-form') as SchmancyForm
+		await nextUpdate()
+		await nextUpdate()
+		sf.setFormError('Server is down')
+		await nextUpdate()
+		await nextUpdate()
+		await nextUpdate()
+		await expectNoA11yViolations(host)
+	})
+})

package/src/form/form-summary.ts

@@ -0,0 +1,171 @@
+/**
+ * `<schmancy-form-summary>` — top-of-form error summary with anchor links to
+ * each invalid field. Linear / GOV.UK / GitHub pattern.
+ *
+ * Drop one inside any `<schmancy-form>`; on submit-failure or when
+ * `<schmancy-form>.setFormError(...)` is called, the summary renders a
+ * `role="alert"` banner with the form-level error message and a list of
+ * links pointing at each invalid field's `id`.
+ *
+ * Hidden when the form is idle, submitting, or successful — only `error`
+ * populates it.
+ *
+ * @element schmancy-form-summary
+ */
+
+import { html, nothing } from 'lit'
+import { customElement, property, state } from 'lit/decorators.js'
+import { SchmancyElement } from '../../mixins'
+import type SchmancyForm from './form'
+
+@customElement('schmancy-form-summary')
+export class SchmancyFormSummary extends SchmancyElement {
+	/**
+	 * Optional heading text. Defaults to a count-based summary
+	 * ("1 problem with this form" / "3 problems with this form").
+	 */
+	@property({ type: String }) heading?: string
+
+	/**
+	 * Render bumper — incremented to force a re-render when the form's state
+	 * changes (the actual content is computed from the DOM in render()).
+	 */
+	@state() private _bump: number = 0
+
+	private _form: SchmancyForm | null = null
+	private _formObserver?: MutationObserver
+
+	override connectedCallback(): void {
+		super.connectedCallback()
+		this._form = this.closest('schmancy-form') as SchmancyForm | null
+		if (!this._form) {
+			console.error('[schmancy-form-summary] must be a descendant of <schmancy-form>')
+			return
+		}
+		const bump = () => { this._bump++ }
+		this._formObserver = new MutationObserver(bump)
+		// Form host attribute changes (aria-busy, :state class reflections,
+		// descendant attribute changes for fields' aria-invalid). subtree:true
+		// catches attribute mutations on every descendant including light-DOM
+		// fields and the form's own host.
+		this._formObserver.observe(this._form, {
+			attributes: true,
+			subtree: true,
+		})
+		// Defer live-region observation until the form has rendered its
+		// shadow tree.
+		const attachLiveRegionObserver = async (): Promise<void> => {
+			await this._form?.updateComplete
+			const liveRegion = this._form?.shadowRoot?.querySelector('[role="status"]')
+			if (liveRegion) {
+				this._formObserver?.observe(liveRegion, {
+					childList: true,
+					characterData: true,
+					subtree: true,
+				})
+			}
+			// Force a render so the initial state is reflected.
+			this._bump++
+		}
+		void attachLiveRegionObserver()
+	}
+
+	override disconnectedCallback(): void {
+		this._formObserver?.disconnect()
+		this._formObserver = undefined
+		super.disconnectedCallback()
+	}
+
+	private _readFormStatus(): 'idle' | 'submitting' | 'success' | 'error' {
+		if (!this._form) return 'idle'
+		if (this._form.matches(':state(error)')) return 'error'
+		if (this._form.matches(':state(submitting)')) return 'submitting'
+		if (this._form.matches(':state(success)')) return 'success'
+		return 'idle'
+	}
+
+	private _readFormMessage(): string {
+		const liveRegion = this._form?.shadowRoot?.querySelector('[role="status"]')
+		return liveRegion?.textContent?.trim() ?? ''
+	}
+
+	private _readInvalidFields(): Array<{ id: string; label: string; message: string }> {
+		if (!this._form) return []
+		const result: Array<{ id: string; label: string; message: string }> = []
+		for (const el of Array.from(this._form.querySelectorAll('*'))) {
+			if (!(el instanceof HTMLElement)) continue
+			let isInvalid = false
+			try {
+				isInvalid = el.matches(':state(invalid)')
+			} catch {
+				continue
+			}
+			if (!isInvalid) continue
+			const f = el as HTMLElement & {
+				label?: string
+				name?: string
+				validationMessage?: string
+			}
+			result.push({
+				id: f.id,
+				label: f.label || f.name || '(field)',
+				message: f.validationMessage || 'Invalid value',
+			})
+		}
+		return result
+	}
+
+	render() {
+		// Read everything fresh from the DOM each render — no @state cache, no
+		// re-render loops. The MutationObserver bumps `_bump` to trigger this
+		// render; `_bump` itself is never read here.
+		void this._bump
+
+		const status = this._readFormStatus()
+		if (status !== 'error') return nothing
+
+		const formMessage = this._readFormMessage()
+		const invalid = this._readInvalidFields()
+		const count = invalid.length
+		const heading =
+			this.heading ??
+			(count === 0
+				? 'There is a problem with this form'
+				: `There ${count === 1 ? 'is' : 'are'} ${count} problem${count === 1 ? '' : 's'} with this form`)
+
+		return html`
+			<div role="alert" aria-labelledby="schmancy-form-summary-heading">
+				<h2 id="schmancy-form-summary-heading">${heading}</h2>
+				${formMessage ? html`<p>${formMessage}</p>` : nothing}
+				${count > 0
+					? html`
+						<ul>
+							${invalid.map(
+								f => html`
+									<li>
+										<a
+											href="#${f.id}"
+											@click=${(e: MouseEvent) => this._jumpToField(e, f.id)}
+										>${f.label}: ${f.message}</a>
+									</li>
+								`,
+							)}
+						</ul>
+					`
+					: nothing}
+			</div>
+		`
+	}
+
+	private _jumpToField(e: MouseEvent, fieldId: string): void {
+		e.preventDefault()
+		const target = this._form?.querySelector(`#${CSS.escape(fieldId)}`) as HTMLElement | null
+		target?.focus()
+	}
+}
+
+declare global {
+	interface HTMLElementTagNameMap {
+		'schmancy-form-summary': SchmancyFormSummary
+	}
+}