@mhmo91/schmancy 0.10.15 → 0.10.16

package/src/form/form.ts

@@ -1,146 +1,377 @@
-import { customElement } from 'lit/decorators.js'
-
 /**
- * A thin ergonomic wrapper around a native `<form>` element. Its children are
- * reparented into a `<form>` element in light DOM on connection, so:
- *
- * - Form-associated custom elements (FACE) resolve their `internals.form`
- *   correctly via native DOM ancestry.
- * - `new FormData(form)` collects values from every FACE + native control
- *   without any manual walking.
- * - `form.reset()` triggers `formResetCallback()` on every FACE.
- * - `form.reportValidity()` runs native validation UI.
- * - `<button type="submit">` and `<schmancy-button type="submit">` both
- *   submit the form via the native submitter pipeline.
+ * `<schmancy-form>` — schmancy form owner with isolated submit state.
  *
- * This component exists only to translate the native `submit` / `reset`
- * events into the Schmancy event shape (`detail: FormData`). All heavy
- * lifting is the platform's.
+ * Architecture:
+ * - Extends `SchmancyElement` (shadow DOM, RxJS + `disconnecting` conventions).
+ * - Renders content inside `<schmancy-context .provides=${[formSubmitState]}>`
+ *   so each form instance gets an isolated copy of the submit state via the
+ *   schmancy state library — no `@lit/context` plumbing in user code.
+ * - Inner `<form novalidate>` is the native-semantics trigger for Enter-key
+ *   submit and `type=submit` button activation.
+ * - Fields self-register via `FIELD_CONNECT_EVENT` (composed event from
+ *   `FormFieldMixin.connectedCallback`). Stale refs (from disconnected
+ *   fields) are filtered by `isConnected` at iteration time.
  *
- * @element schmancy-form
- * @fires submit - `CustomEvent<FormData>` emitted when the form is submitted.
- * @fires reset - Emitted after the underlying form resets.
+ * Schema seam — pass any `{ parse(input): T }` object (zod, valibot, ArkType,
+ * etc.) via the `schema` property to get typed `submit` event detail.
  */
+
+import { html } from 'lit'
+import { customElement, property, state } from 'lit/decorators.js'
+import { fromEvent, takeUntil } from 'rxjs'
+import { SchmancyElement } from '../../mixins'
+import { FIELD_CONNECT_EVENT, type IFormFieldMixin } from '../../mixins/formField.mixin'
+import { formSubmitState, type FormSubmitState, type FormError } from './form-state'
+
+/** Structural type matching zod, valibot, ArkType, etc. — any schema with `.parse()`. */
+export interface ParseSchema<T = unknown> {
+	parse(input: unknown): T
+}
+
+const isButton = (node: EventTarget): node is HTMLElement => {
+	if (!(node instanceof HTMLElement)) return false
+	return node.tagName === 'BUTTON' || node.tagName === 'SCHMANCY-BUTTON'
+}
+
+/** Submit event detail. `data` is typed when `schema` is set. */
+export type SchmancyFormSubmitDetail<T = Record<string, FormDataEntryValue>> = {
+	data: T
+	formData: FormData
+	/**
+	 * Register a promise that gates the form's success/error state. If unused,
+	 * the form synchronously flips to `success` after dispatch. If used,
+	 * `success`/`error` reflect the promise's outcome.
+	 */
+	until(p: Promise<unknown>): void
+}
+
 @customElement('schmancy-form')
-export default class SchmancyForm extends HTMLElement {
+export default class SchmancyForm<TSchema extends ParseSchema | undefined = undefined>
+	extends SchmancyElement {
 	public static readonly tagName: string = 'schmancy-form'
 
-	private _form: HTMLFormElement | null = null
-	private _wrapped = false
+	/**
+	 * Optional schema for parsing FormData on submit. Anything with a
+	 * `.parse(input)` method works (zod, valibot, ArkType). When set, the
+	 * `submit` event's `detail.data` is typed `z.infer<TSchema>`.
+	 */
+	@property({ attribute: false })
+	schema?: TSchema
 
-	/** ElementInternals for `:state(invalid)` / `:state(submitting)` broadcasting. */
-	private readonly _internals: ElementInternals | undefined = (() => {
-		try { return this.attachInternals() } catch { return undefined }
-	})()
+	/** Skip built-in browser constraint validation. Mirrors `<form novalidate>`. */
+	@property({ type: Boolean })
+	novalidate: boolean = true
 
-	/** Skip built-in constraint validation on submit. Mirrors `<form novalidate>`. */
-	get novalidate(): boolean {
-		return this.hasAttribute('novalidate')
-	}
-	set novalidate(value: boolean) {
-		if (value) this.setAttribute('novalidate', '')
-		else this.removeAttribute('novalidate')
-	}
+	private _fields = new Set<IFormFieldMixin>()
+	private _submitting = false
 
-	connectedCallback(): void {
-		this.ensureForm()
-	}
+	/**
+	 * Local mirror of the submit-state status — drives the inline live region
+	 * synchronously. Independent of the schmancy-state library's resolution
+	 * chain (which has known cross-await fallback semantics) so the AT-facing
+	 * announcement is always correct for this form instance.
+	 */
+	@state() private _liveStatus: 'idle' | 'submitting' | 'success' | 'error' = 'idle'
+	@state() private _liveError: string = ''
+	private _internals: ElementInternals | undefined = (() => {
+		try {
+			return this.attachInternals()
+		} catch {
+			return undefined
+		}
+	})()
 
-	disconnectedCallback(): void {
-		if (this._form) {
-			this._form.removeEventListener('submit', this._onSubmit)
-			this._form.removeEventListener('reset', this._onReset)
+	override connectedCallback(): void {
+		super.connectedCallback()
+
+		// Forbid nested <schmancy-form>.
+		if (this.parentElement?.closest('schmancy-form')) {
+			console.error('[schmancy-form] nested <schmancy-form> is not supported')
+			return
 		}
+
+		// Field registry — composed event from FormFieldMixin.connectedCallback.
+		fromEvent<CustomEvent<IFormFieldMixin>>(this, FIELD_CONNECT_EVENT)
+			.pipe(takeUntil(this.disconnecting))
+			.subscribe(e => this._fields.add(e.detail))
+
+		// Submit-trigger interception — slotted descendants live in light DOM
+		// while the inner <form> is in shadow DOM, so native form-association
+		// across the shadow boundary doesn't work for `<button type=submit>`.
+		// Capture clicks on type=submit buttons (native + schmancy-button) and
+		// Enter keys on registered fields, then call the inner form's
+		// requestSubmit() which fires the same native submit event handler
+		// chain that a directly-associated button would have triggered.
+		fromEvent<MouseEvent>(this, 'click')
+			.pipe(takeUntil(this.disconnecting))
+			.subscribe(e => this._maybeRequestSubmit(e))
+		fromEvent<KeyboardEvent>(this, 'keydown')
+			.pipe(takeUntil(this.disconnecting))
+			.subscribe(e => {
+				if (e.key !== 'Enter' || e.shiftKey) return
+				// Skip Enter inside <textarea> (newline) and contenteditable.
+				const target = e.target as HTMLElement | null
+				if (target?.tagName === 'TEXTAREA') return
+				if (target?.isContentEditable) return
+				this._maybeRequestSubmit(e)
+			})
 	}
 
-	/**
-	 * On first connection, create the internal light-DOM `<form>` and move
-	 * existing children into it. Re-entry is a no-op.
-	 */
-	private ensureForm(): void {
-		if (this._wrapped) return
-
-		// Respect an explicit consumer-supplied wrapping <form>.
-		const existing = Array.from(this.children).find(c => c instanceof HTMLFormElement) as
-			| HTMLFormElement
-			| undefined
-
-		const form = existing ?? document.createElement('form')
-		form.noValidate = true
-
-		if (!existing) {
-			// Snapshot children because appending mutates `this.childNodes`.
-			const children = Array.from(this.childNodes)
-			for (const node of children) form.appendChild(node)
-			this.appendChild(form)
+	private _maybeRequestSubmit(e: Event): void {
+		// On click: trigger only when the target is a type=submit button.
+		// On keydown(Enter): always trigger if focus is on a registered field.
+		// type=reset is handled separately in _maybeReset.
+		if (e.type === 'click') {
+			const path = e.composedPath()
+			const resetBtn = path.find(
+				node => isButton(node) && node.getAttribute('type') === 'reset',
+			)
+			if (resetBtn) {
+				e.preventDefault()
+				const form = this.shadowRoot?.querySelector('form')
+				form?.reset()
+				return
+			}
+			const submitBtn = path.find(
+				node => isButton(node) && node.getAttribute('type') === 'submit',
+			)
+			if (!submitBtn) return
+			e.preventDefault()
 		}
+		const form = this.shadowRoot?.querySelector('form')
+		form?.requestSubmit()
+	}
 
-		form.addEventListener('submit', this._onSubmit)
-		form.addEventListener('reset', this._onReset)
-
-		this._form = form
-		this._wrapped = true
+	/** Active fields — drops stale refs from disconnected nodes. */
+	private get _activeFields(): IFormFieldMixin[] {
+		return [...this._fields].filter(f => f.isConnected)
 	}
 
-	private _onSubmit = (e: SubmitEvent): void => {
-		// Prevent the default navigation AND stop the native submit from
-		// bubbling past this wrapper — otherwise consumers listening for
-		// `submit` on <schmancy-form> would see the native event plus our
-		// CustomEvent (two fires per submission).
+	private async _onSubmit(e: SubmitEvent): Promise<void> {
 		e.preventDefault()
 		e.stopPropagation()
-		if (!this.novalidate && !this._form!.reportValidity()) {
-			this._internals?.states.add('invalid')
+		if (this._submitting) return
+
+		// If any field has an async validator pending, wait for them all to
+		// settle before deciding validity. This is the hard-block model: the
+		// user clicks submit, the form holds (aria-busy="true"), waits for
+		// validators, then proceeds with the truth they reported.
+		const pendingValidators = this._activeFields.filter(f => f.isValidating)
+		if (pendingValidators.length > 0) {
+			this._broadcastStatus('submitting')
+			await new Promise<void>(resolve => {
+				const tick = () => {
+					if (this._activeFields.every(f => !f.isValidating)) resolve()
+					else requestAnimationFrame(tick)
+				}
+				tick()
+			})
+		}
+
+		// Phase 4 — submit forces error display on every field.
+		this._activeFields.forEach(f => f.markSubmitted())
+
+		// Validate; success path entered ONLY if all valid.
+		const allValid = this._activeFields.every(f => f.checkValidity())
+		const fs = formSubmitState.value
+		if (!allValid) {
+			formSubmitState.set({
+				...fs,
+				status: 'error',
+				error: { message: 'Validation failed' },
+			})
+			this._broadcastStatus('error', 'Validation failed. Please correct the highlighted fields.')
+			const firstInvalid = this._activeFields.find(f => f.error) as unknown as
+				| HTMLElement
+				| undefined
+			firstInvalid?.focus()
 			return
 		}
-		this._internals?.states.delete('invalid')
-		this._internals?.states.add('submitting')
+
+		this._submitting = true
+		formSubmitState.set({
+			...fs,
+			status: 'submitting',
+			error: null,
+			submitCount: fs.submitCount + 1,
+		})
+		this._broadcastStatus('submitting')
+
+		// Build payload from the registered fields' contracted toFormEntries().
+		const formData = new FormData()
+		for (const field of this._activeFields) {
+			for (const [k, v] of field.toFormEntries()) formData.append(k, v)
+		}
+		const raw = Object.fromEntries(formData)
+		const data = this.schema ? this.schema.parse(raw) : raw
+
+		// Awaitable submit — consumers register promises via e.detail.until(p).
+		const pending: Promise<unknown>[] = []
+		this.dispatchEvent(
+			new CustomEvent<SchmancyFormSubmitDetail<unknown>>('submit', {
+				detail: {
+					data,
+					formData,
+					until: (p: Promise<unknown>) => pending.push(p),
+				},
+			}),
+		)
+
 		try {
-			this.dispatchEvent(
-				new CustomEvent('submit', {
-					detail: new FormData(this._form!),
-				}),
-			)
+			await Promise.all(pending)
+			formSubmitState.set({
+				...formSubmitState.value,
+				status: 'success',
+				error: null,
+			})
+			this._broadcastStatus('success')
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err)
+			formSubmitState.set({
+				...formSubmitState.value,
+				status: 'error',
+				error: { message },
+			})
+			this._broadcastStatus('error', message)
 		} finally {
-			this._internals?.states.delete('submitting')
+			this._submitting = false
 		}
 	}
 
-	private _onReset = (e: Event): void => {
+	private _onReset(e: Event): void {
 		e.stopPropagation()
-		this._internals?.states.delete('invalid')
+		this._activeFields.forEach(f => f.resetForm())
+		formSubmitState.set({ status: 'idle', error: null, submitCount: 0 })
+		this._broadcastStatus('idle')
 		this.dispatchEvent(new CustomEvent('reset'))
 	}
 
+	private _broadcastStatus(status: FormSubmitState['status'], errorMessage?: string): void {
+		this._liveStatus = status
+		this._liveError = errorMessage ?? ''
+		const states = this._internals?.states
+		if (states) {
+			for (const s of ['submitting', 'success', 'error', 'idle']) states.delete(s)
+			states.add(status)
+		}
+		// aria-busy on the host while submitting (WCAG 2.2 AA — disabled buttons
+		// drop from tab order; keep them focusable, signal busy via aria).
+		if (status === 'submitting') this.setAttribute('aria-busy', 'true')
+		else this.removeAttribute('aria-busy')
+		// Public formstate event — external state stores subscribe without
+		// having to consume formSubmitState directly.
+		this.dispatchEvent(
+			new CustomEvent<FormSubmitState>('formstate', {
+				detail: { ...formSubmitState.value },
+				bubbles: true,
+				composed: true,
+			}),
+		)
+	}
+
+	/**
+	 * Server-side error mapping (RHF `setError(name, ...)`-equivalent).
+	 * Sets `setCustomValidity(message)` on the matching field and ensures the
+	 * error displays by marking it submitted.
+	 */
+	public setFieldError(name: string, message: string): boolean {
+		const field = this._activeFields.find(f => f.name === name)
+		if (!field) return false
+		field.setCustomValidity(message)
+		field.markSubmitted()
+		return true
+	}
+
+	/**
+	 * Top-of-form error (RHF `setError('root.serverError', ...)`-equivalent).
+	 * Flips form status to 'error' with a structured `FormError`.
+	 */
+	public setFormError(message: string, code?: string): void {
+		formSubmitState.set({
+			...formSubmitState.value,
+			status: 'error',
+			error: { message, code } as FormError,
+		})
+		this._broadcastStatus('error', message)
+	}
+
+	/**
+	 * Clear the `submitted` flag on every registered field without resetting
+	 * their values. Wizard pattern: stepping back from a later step should not
+	 * leave the earlier step's fields in aggressive "show all errors" mode
+	 * (which `submitted = true` triggers via the `_shouldShowError()` gate).
+	 *
+	 * Pristine fields with `validateOn: 'dirty'` go quiet again. Fields the
+	 * user actually dirtied keep showing their errors (correct UX — those are
+	 * still genuine mistakes the user can see).
+	 */
+	public clearSubmitted(): void {
+		this._activeFields.forEach(f => f.clearSubmitted())
+		formSubmitState.set({
+			...formSubmitState.value,
+			status: 'idle',
+			error: null,
+		})
+		this._broadcastStatus('idle')
+	}
+
 	/** Programmatically submit via the native submitter pipeline. */
 	public submit(): boolean {
-		if (!this._form) return false
-		if (!this.novalidate && !this._form.reportValidity()) return false
-		this._form.requestSubmit()
+		const form = this.shadowRoot?.querySelector('form')
+		if (!form) return false
+		form.requestSubmit()
 		return true
 	}
 
 	/** Programmatically reset via native `form.reset()`. */
 	public reset(): void {
-		this._form?.reset()
+		const form = this.shadowRoot?.querySelector('form')
+		form?.reset()
 	}
 
 	public reportValidity(): boolean {
-		return this._form?.reportValidity() ?? true
+		return this._activeFields.every(f => f.reportValidity())
 	}
 
 	public checkValidity(): boolean {
-		return this._form?.checkValidity() ?? true
+		return this._activeFields.every(f => f.checkValidity())
 	}
 
-	/** Snapshot of current form values. Equivalent to `new FormData(this.form)`. */
+	/** Snapshot of current form values from the registered fields. */
 	public getFormData(): FormData {
-		return this._form ? new FormData(this._form) : new FormData()
+		const formData = new FormData()
+		for (const field of this._activeFields) {
+			for (const [k, v] of field.toFormEntries()) formData.append(k, v)
+		}
+		return formData
 	}
 
-	/** The underlying `<form>` element (escape hatch for advanced integration). */
-	public get form(): HTMLFormElement | null {
-		return this._form
+	render() {
+		return html`
+			<schmancy-context .provides=${[formSubmitState]}>
+				<form
+					?novalidate=${this.novalidate}
+					@submit=${this._onSubmit}
+					@reset=${this._onReset}
+				>
+					<slot></slot>
+				</form>
+				<!--
+					Form-level live region — assistive tech announces server-side
+					form errors (validation summary, network failure, server reject)
+					here. Visually hidden via the .sr-only convention; consumers
+					render their own visible banner from formSubmitState if they
+					want one. Empty content while idle/submitting/success — only
+					error states populate the region. WCAG 4.1.3 (Status Messages).
+				-->
+				<div
+					role="status"
+					aria-live="assertive"
+					aria-atomic="true"
+					class="sr-only"
+				>${this._liveStatus === 'error' ? this._liveError : ''}</div>
+			</schmancy-context>
+		`
 	}
 }
 
@@ -150,10 +381,9 @@ declare global {
 	}
 }
 
-// === Retained type surface ===
-// These interfaces were part of the old collection-based engine. They're kept
-// exported because downstream code may still import them as documentation.
-// The new implementation no longer uses them internally.
+// Retained type surfaces — kept exported because downstream code may import
+// them as documentation. The new implementation no longer uses them
+// internally.
 
 export interface FormElement extends HTMLElement {
 	name?: string
@@ -173,6 +403,7 @@ export interface ValidatableFormElement extends FormElement {
 }
 
 export interface FormEventMap {
-	submit: CustomEvent<FormData>
+	submit: CustomEvent<SchmancyFormSubmitDetail<unknown>>
 	reset: CustomEvent
+	formstate: CustomEvent<FormSubmitState>
 }

package/src/form/index.ts

@@ -1,2 +1,4 @@
 export * from './form'
 export { default as SchmancyForm } from './form'
+export * from './form-state'
+export * from './form-summary'

package/src/index.ts

@@ -1,16 +1,16 @@
 export * from './area';
 export * from './audio';
-export * from './autocomplete';
+export * from './form/fields/autocomplete';
 export * from './badge';
 export * from './boat';
 export * from './busy';
 export * from './button';
 export * from './card';
-export * from './checkbox';
+export * from './form/fields/checkbox';
 export * from './chips';
 export * from './connectivity';
 export * from './content-drawer';
-export * from './date-range';
+export * from './form/fields/date-range';
 export * from './date-range-inline';
 export * from './delay';
 export * from './details';
@@ -24,7 +24,7 @@ export * from './window';
 export * from './form';
 export * from './icons';
 export * from './iframe';
-export * from './input';
+export * from './form/fields/input';
 export * from './json';
 export * from './layout';
 export * from './lightbox';
@@ -37,10 +37,10 @@ export * from './notification';
 export * from './option';
 export * from './page';
 export * from './progress';
-export * from './radio-group';
-export * from './range';
+export * from './form/fields/radio-group';
+export * from './form/fields/range';
 export * from './rxjs-utils';
-export * from './select';
+export * from './form/fields/select';
 export * from './slider';
 export * from './state';
 export * from './steps';
@@ -48,7 +48,7 @@ export * from './surface';
 export * from './table';
 export * from './tabs';
 export * from './teleport';
-export * from './textarea';
+export * from './form/fields/textarea';
 export * from './theme';
 export * from './theme-button';
 export * from './tooltip';
@@ -62,5 +62,5 @@ export * from './breadcrumb';
 export * from './kbd';
 export * from './skeleton';
 export * from './splash-screen';
-export * from './switch';
+export * from './form/fields/switch';
 export * from './visually-hidden';

package/types/mixins/formField.mixin.d.ts

@@ -8,6 +8,38 @@ import { ITailwindElementMixin } from './tailwind.mixin';
  * the global registry so detection works across module realms/bundles.
  */
 export declare const SCHMANCY_FORM_FIELD: unique symbol;
+/**
+ * Composed event a field dispatches in `connectedCallback`. `<schmancy-form>`
+ * subscribes via `fromEvent(this, FIELD_CONNECT_EVENT)` and adds the field to
+ * its registry. No matching disconnect event — composed events from a
+ * disconnected node have an empty composed path; cleanup is via `isConnected`
+ * filter at iteration time.
+ */
+export declare const FIELD_CONNECT_EVENT = "schmancy:field:connect";
+/**
+ * Validation modes.
+ * - `dirty` (default per Revolute) — show errors only after value diverged.
+ * - `touched` — show errors after first blur, even if value unchanged.
+ * - `always` — show errors immediately (live search).
+ * - `submitted` — hold all errors until submit (wizard step).
+ * - `length` — fire validation only when `value.length` reaches `maxlength`
+ *   (Stripe pattern for predictable-length fields: ZIP, phone, card number).
+ */
+export type ValidateOn = 'always' | 'touched' | 'dirty' | 'submitted' | 'length';
+/**
+ * Per-field error-message override map. Keys are `ValidityState` flag names;
+ * values are the message to display when that flag is set. Unset flags fall
+ * back to the mixin's hardcoded defaults (English).
+ *
+ * Use for i18n or domain-specific copy:
+ * ```ts
+ * <schmancy-input
+ *   .errorMessages=${{ valueMissing: 'Adresse e-mail requise', typeMismatch: 'Format e-mail invalide' }}
+ *   type="email" required
+ * ></schmancy-input>
+ * ```
+ */
+export type ErrorMessages = Partial<Record<keyof ValidityState, string>>;
 /**
  * Interface defining the properties and methods that the FormFieldMixin adds.
  */
@@ -22,10 +54,68 @@ export interface IFormFieldMixin extends Element {
     validationMessage: string;
     hint?: string;
     id: string;
+    /** Set to `true` once the user has blurred the field at least once. */
+    touched: boolean;
+    /** `true` when the current value differs from the captured default. */
+    dirty: boolean;
+    /** Inverse of `dirty`. */
+    pristine: boolean;
+    /** Set to `true` by `<schmancy-form>` on submit (forces error display). */
+    submitted: boolean;
+    /** Validation mode — controls when errors display. Default `'dirty'`. */
+    validateOn: ValidateOn;
+    /**
+     * Per-field error-message override map (i18n hook). See `ErrorMessages`.
+     * Unset keys fall back to the mixin's hardcoded English defaults.
+     */
+    errorMessages?: ErrorMessages;
+    /**
+     * `ElementInternals` instance attached by the mixin. Exposed so subclasses
+     * with non-standard validity semantics (date-range, multi-select) can
+     * surface platform `ValidityStateFlags` directly via
+     * `internals.setValidity({ valueMissing: true })` rather than rolling their
+     * own `attachInternals` call.
+     */
+    internals: ElementInternals | undefined;
     form: HTMLFormElement | null;
     checkValidity(): boolean;
     reportValidity(): boolean;
     setCustomValidity(message: string): void;
+    /** Mark the field as touched (component should call on blur). */
+    markTouched(): void;
+    /** Mark the field as submitted (called by `<schmancy-form>` on submit). */
+    markSubmitted(): void;
+    /**
+     * Clear the `submitted` flag without resetting value/touched/error.
+     * Used by wizards: stepping back from step N to step N-1 should not
+     * leave step N-1's fields in aggressive "show all errors" mode.
+     */
+    clearSubmitted(): void;
+    /**
+     * `true` while an async validator is in flight. Broadcast as
+     * `:state(validating)`. `<schmancy-form>` blocks submit until every
+     * registered field's `isValidating` is back to `false`.
+     */
+    isValidating: boolean;
+    /**
+     * Run an async validator. While the promise is pending, `isValidating` is
+     * `true` and `:state(validating)` is broadcast. On resolve, the returned
+     * string is passed to `setCustomValidity` — empty string clears any
+     * existing custom error; non-empty marks the field invalid with that
+     * message.
+     *
+     * Submitting the form while a validator is pending is queued — the form
+     * waits for `Promise.all(pending validators)` to settle before proceeding.
+     */
+    runAsyncValidator(fn: () => Promise<string>): Promise<void>;
+    /**
+     * Whether the gate for showing validation errors is open right now. Exposed
+     * so subclasses with custom error-display channels (e.g. select renders
+     * errors on a child input) can keep their gate consistent with the mixin's.
+     * Subclasses should not override this — extend the truth table by changing
+     * `validateOn` instead.
+     */
+    _shouldShowError(): boolean;
     toFormEntries(): Array<[string, FormDataEntryValue]>;
     resetForm(): void;
     emitChange(detail: any): void;