@zeyos/zx 4.4.0 → 5.2.0

package/src/components/field/field.js

@@ -4,7 +4,10 @@ import { uid } from '../../core/util.js';
 
 /**
  * @typedef {Object} FieldOptions
- * @property {string|null} [id=null] Control ID and logical field identifier.
+ * @property {string|null} [id=null] DOM id of the control. Generated when omitted; a Fieldset
+ *   derives it from its `idPrefix` and the field key, so a key never becomes a DOM id by itself.
+ * @property {string|null} [name=null] Field name: the `name` of a native control and the key the
+ *   field is filed under. A Fieldset sets it to the field key; a standalone field falls back to `id`.
  * @property {string} [type='text'] Registered field type.
  * @property {string} [label=''] Visible label.
  * @property {string} [description=''] Supporting description.
@@ -12,6 +15,9 @@ import { uid } from '../../core/util.js';
  * @property {string} [placeholder=''] Control placeholder.
  * @property {boolean} [required=false] Whether a value is required.
  * @property {boolean} [disabled=false] Whether the control is disabled.
+ * @property {boolean} [readonly=false] Whether the value is read-only: shown and focusable, not
+ *   editable. Types whose control has no read-only state (`checkbox`, `select`, `optionlist`,
+ *   `zxselect`, `date`, `time`, …) ignore it.
  * @property {string[]|Record<string, string>|null} [options=null] Select or option-list values.
  * @property {'stack'|'inline'} [layout='stack'] Label/control layout.
  * @property {Record<string, unknown>} [props={}] Adapter-specific control properties.
@@ -27,7 +33,12 @@ import { uid } from '../../core/util.js';
  * @property {(value: unknown, options?: {silent?: boolean}) => void} set Set the current value.
  * @property {() => void} focus Focus the control.
  * @property {(disabled: boolean) => void} setDisabled Set disabled state.
+ * @property {(readonly: boolean) => void} [setReadonly] Set read-only state; left out when the
+ *   control has none.
  * @property {() => void} [destroy] Release adapter-owned resources.
+ * @property {Element} [labelTarget] The element the field's label, description, and validity
+ *   belong to when it is not `el` — the text input inside a composite control. Left out, a
+ *   wrapper that cannot be labelled hands them to the first unnamed form control inside it.
  */
 
 /** @typedef {(field: Field, options: Readonly<FieldOptions>) => FieldAdapter} FieldAdapterFactory */
@@ -36,6 +47,7 @@ import { uid } from '../../core/util.js';
 /**
  * One labelled form control backed by a registered adapter.
  * @fires Field#change
+ * @fires Field#input
  * @fires Field#invalid
  * @extends {Component<FieldOptions>}
  */
@@ -45,6 +57,7 @@ export class Field extends Component {
   /** @type {FieldOptions & {msg: Record<string, string>}} */
   static defaults = {
     id: null,
+    name: null,
     type: 'text',
     label: '',
     description: '',
@@ -52,6 +65,7 @@ export class Field extends Component {
     placeholder: '',
     required: false,
     disabled: false,
+    readonly: false,
     options: null,
     layout: 'stack',
     props: {},
@@ -88,9 +102,10 @@ export class Field extends Component {
     return Field.#adapters.has(String(type).trim().toLowerCase());
   }
 
-  // `adapter` (FieldAdapter), `initialValue`, and `controlId` are assigned in render();
-  // declaring them as class fields would re-initialize them to undefined after the base
-  // constructor (which calls render()) returns — see AGENTS.md.
+  // `adapter` (FieldAdapter), `initialValue`, `controlId` (the control's DOM id), and `name` (the
+  // field name, '' when there is none) are assigned in render(); declaring them as class fields
+  // would re-initialize them to undefined after the base constructor (which calls render())
+  // returns — see AGENTS.md.
 
   /** @returns {HTMLElement} */
   render() {
@@ -100,11 +115,14 @@ export class Field extends Component {
     const layout = this.options.layout === 'inline' ? 'inline' : 'stack';
     this._ownedComponents = new Set();
     this._ownedNodes = [];
-    this._rootAttributes = rememberAttributes(root, ['data-layout', 'data-field-type', 'data-disabled', 'data-state']);
+    this._rootAttributes = rememberAttributes(root, ['data-layout', 'data-field-type', 'data-disabled', 'data-readonly', 'data-state']);
     root.dataset.layout = layout;
     root.dataset.fieldType = type;
 
+    /** @type {string} The control's DOM id: `options.id`, or a generated one. */
     this.controlId = this.options.id ? String(this.options.id) : uid('zx-field');
+    /** @type {string} The field name (`options.name`, else `options.id`), '' when there is none. */
+    this.name = String(this.options.name ?? this.options.id ?? '');
     const labelId = `${this.controlId}-label`;
     const descriptionId = `${this.controlId}-description`;
     const highlightId = `${this.controlId}-highlight`;
@@ -148,9 +166,14 @@ export class Field extends Component {
 
     const control = this.adapter.el;
     if (!control.id) control.id = this.controlId;
-    label.htmlFor = control.id;
-    if (!isLabelable(control)) control.setAttribute('aria-labelledby', labelId);
-    this._baseDescribedBy = control.getAttribute('aria-describedby') ?? '';
+    // A wrapper (a `custom` adapter's box) cannot carry a name; the control inside it can.
+    const labelled = this.adapter.labelTarget
+      ?? (isLabelable(control) ? control : unnamedControlWithin(control)) ?? control;
+    this._labelled = labelled;
+    if (labelled !== control && isLabelable(labelled) && !labelled.id) labelled.id = `${this.controlId}-input`;
+    label.htmlFor = isLabelable(labelled) ? labelled.id : control.id;
+    if (!isLabelable(labelled)) labelled.setAttribute('aria-labelledby', labelId);
+    this._baseDescribedBy = labelled.getAttribute('aria-describedby') ?? '';
     controlSlot.append(control);
     this._descriptionId = String(this.options.description ?? '') ? descriptionId : '';
     this._highlightId = highlightId;
@@ -159,6 +182,8 @@ export class Field extends Component {
     this.initialValue = initialValue(type, this.options.value);
     this.adapter.set(this.initialValue, { silent: true });
     this.setDisabled(Boolean(this.options.disabled));
+    if (this.options.readonly) this.setReadonly(true);
+    // Adapters whose widget reports its own commits stop the native `change` before this sees it.
     this.listen(control, 'change', () => {
       this.emit('change', { value: this.getValue() });
     });
@@ -217,6 +242,19 @@ export class Field extends Component {
     return this;
   }
 
+  /**
+   * Makes the value read-only or editable again, where the control has a read-only state (see
+   * the `readonly` option); reflected as `data-readonly` on the root either way.
+   * @param {boolean} readonly Read-only state.
+   * @returns {this}
+   */
+  setReadonly(readonly) {
+    const value = Boolean(readonly);
+    this.adapter.setReadonly?.(value);
+    this.el.dataset.readonly = String(value);
+    return this;
+  }
+
   /**
    * Displays a validation or status message.
    * @param {string} message Message text.
@@ -231,11 +269,11 @@ export class Field extends Component {
     this._highlight.hidden = !message;
     if (normalizedKind === 'danger' && message) {
       this._highlight.setAttribute('role', 'alert');
-      this.adapter.el.setAttribute('aria-invalid', 'true');
+      this._labelled.setAttribute('aria-invalid', 'true');
       this.emit('invalid', { message: String(message) });
     } else {
       this._highlight.removeAttribute('role');
-      this.adapter.el.removeAttribute('aria-invalid');
+      this._labelled.removeAttribute('aria-invalid');
     }
     this._syncDescription(Boolean(message));
     return this;
@@ -250,7 +288,7 @@ export class Field extends Component {
     this._highlight.textContent = '';
     this._highlight.hidden = true;
     this._highlight.removeAttribute('role');
-    this.adapter.el.removeAttribute('aria-invalid');
+    this._labelled.removeAttribute('aria-invalid');
     this._syncDescription(false);
     return this;
   }
@@ -279,8 +317,8 @@ export class Field extends Component {
   _syncDescription(highlighted = false) {
     const ids = [this._baseDescribedBy, this._descriptionId, highlighted ? this._highlightId : '']
       .flatMap((value) => value.split(/\s+/)).filter(Boolean);
-    if (ids.length) this.adapter.el.setAttribute('aria-describedby', [...new Set(ids)].join(' '));
-    else this.adapter.el.removeAttribute('aria-describedby');
+    if (ids.length) this._labelled.setAttribute('aria-describedby', [...new Set(ids)].join(' '));
+    else this._labelled.removeAttribute('aria-describedby');
   }
 
   /** @returns {void} */
@@ -400,6 +438,22 @@ function isLabelable(element) {
   return ['BUTTON', 'INPUT', 'METER', 'OUTPUT', 'PROGRESS', 'SELECT', 'TEXTAREA'].includes(element.tagName);
 }
 
+/**
+ * The first form control inside `root` that nothing names yet — no `aria-label`, no
+ * `aria-labelledby`, no `<label>` with any text — or null.
+ * @param {Element} root
+ * @returns {Element|null}
+ */
+function unnamedControlWithin(root) {
+  for (const candidate of root.querySelectorAll('input:not([type="hidden"]), select, textarea')) {
+    if (candidate.hasAttribute('aria-label') || candidate.hasAttribute('aria-labelledby')) continue;
+    const labels = [.../** @type {HTMLInputElement} */ (candidate).labels ?? []];
+    if (labels.some((label) => label.textContent?.trim())) continue;
+    return candidate;
+  }
+  return null;
+}
+
 /** @param {HTMLElement} element @param {string[]} names @returns {Map<string, string|null>} */
 function rememberAttributes(element, names) {
   return new Map(names.map((name) => [name, element.getAttribute(name)]));
@@ -413,25 +467,32 @@ function restoreAttributes(element, attributes) {
   }
 }
 
-/** @param {Readonly<FieldOptions>} options @param {Record<string, unknown>} base @returns {Record<string, unknown>} */
-function controlProps(options, base) {
+/**
+ * The properties a native control is built with: the adapter's own `base` over the caller's
+ * `props`, with the field name as the control's `name` unless `props` gives one.
+ * @param {Field} field Field the control belongs to.
+ * @param {Readonly<FieldOptions>} options Field options.
+ * @param {Record<string, unknown>} base Properties the adapter owns.
+ * @returns {Record<string, unknown>}
+ */
+function controlProps(field, options, base) {
   const props = { ...(options.props ?? {}) };
   for (const key of Object.keys(props)) {
     if (/^on[a-z]/i.test(key) || key === 'content') delete props[key];
   }
-  return { ...props, ...base };
+  return { name: field.name || undefined, ...props, ...base };
 }
 
 /** @param {'input'|'textarea'} tag @param {string} type @returns {FieldAdapterFactory} */
 function textAdapter(tag, type) {
-  return (_field, options) => {
-    const el = h(tag, controlProps(options, {
+  return (field, options) => {
+    const el = h(tag, controlProps(field, options, {
       type: tag === 'input' ? type : undefined,
       placeholder: options.placeholder,
       required: options.required,
       disabled: options.disabled
     }));
-    return elementValueAdapter(el);
+    return { ...elementValueAdapter(el), setReadonly: (readonly) => { el.readOnly = readonly; } };
   };
 }
 
@@ -450,7 +511,7 @@ function elementValueAdapter(el) {
 function numericAdapter(kind) {
   return (field, options) => {
     const coerce = kind === 'int' ? coerceInteger : coerceFloat;
-    const input = h('input', controlProps(options, {
+    const input = h('input', controlProps(field, options, {
       type: 'text',
       inputMode: kind === 'int' ? 'numeric' : 'decimal',
       placeholder: options.placeholder,
@@ -468,14 +529,15 @@ function numericAdapter(kind) {
     });
     return {
       ...elementValueAdapter(input),
-      get: () => coerce(input.value).value
+      get: () => coerce(input.value).value,
+      setReadonly: (readonly) => { input.readOnly = readonly; }
     };
   };
 }
 
 /** @type {FieldAdapterFactory} */
-const checkboxAdapter = (_field, options) => {
-  const input = h('input', controlProps(options, {
+const checkboxAdapter = (field, options) => {
+  const input = h('input', controlProps(field, options, {
     type: 'checkbox',
     required: options.required,
     disabled: options.disabled
@@ -490,8 +552,8 @@ const checkboxAdapter = (_field, options) => {
 };
 
 /** @type {FieldAdapterFactory} */
-const selectAdapter = (_field, options) => {
-  const select = h('select', controlProps(options, {
+const selectAdapter = (field, options) => {
+  const select = h('select', controlProps(field, options, {
     required: options.required,
     disabled: options.disabled
   }));
@@ -502,12 +564,15 @@ const selectAdapter = (_field, options) => {
 };
 
 /** @type {FieldAdapterFactory} */
-const optionListAdapter = (_field, options) => {
+const optionListAdapter = (field, options) => {
   const root = h('div', {
     class: 'zx-field__option-list',
     role: 'radiogroup'
   });
-  const name = options.id ? String(options.id) : uid('zx-option-list');
+  // The radios are grouped by the control's id, not by the field key: radios outside a <form>
+  // share one group per name across the whole document, so the same fieldset mounted twice
+  // would otherwise check one copy's option by clicking the other's.
+  const name = field.controlId;
   const radios = normalizeOptions(options.options).map(([value, label], index) => {
     const input = h('input', {
       type: 'radio',
@@ -534,8 +599,8 @@ const optionListAdapter = (_field, options) => {
 };
 
 /** @type {FieldAdapterFactory} */
-const htmlAdapter = (_field, options) => {
-  const el = h('div', controlProps(options, { class: 'zx-field__static' }));
+const htmlAdapter = (field, options) => {
+  const el = h('div', controlProps(field, options, { class: 'zx-field__static', name: undefined }));
   let adopted = null;
   const set = (value) => {
     restoreAdopted(adopted);
@@ -600,6 +665,13 @@ Field.register('custom', customAdapter);
  * @type {CustomEvent<{value: unknown}>}
  */
 
+/**
+ * Live edit before it is committed, from the types whose widget tells the two apart (`code`,
+ * `slider`): every keystroke or drag step, where `change` follows only on commit.
+ * @event Field#input
+ * @type {CustomEvent<{value: unknown}>}
+ */
+
 /**
  * Field validation failure event.
  * @event Field#invalid

package/src/components/field-upload/field-upload.css

@@ -32,7 +32,7 @@
 
 .zx-field-upload__prompt {
   color: var(--zx-color-text);
-  font-weight: 600;
+  font-weight: var(--zx-weight-medium);
 }
 
 .zx-field-upload__hint,

package/src/components/fieldset/external-adapter.js

@@ -0,0 +1,363 @@
+import { isElement } from '../../core/util.js';
+
+/** @typedef {import('../field/field.js').Field} Field */
+/** @typedef {import('../field/field.js').FieldAdapter} FieldAdapter */
+
+/**
+ * An element or component a Fieldset adopts with `addField(id, source)`: anything that renders
+ * into an element. Components are read through the methods they have, elements through their
+ * native properties.
+ * @typedef {Element|{el?: Element, toElement?: () => Element}} ExternalSource
+ */
+
+/**
+ * The value accessor pairs the library's components use, in the order they are tried. A reader
+ * counts only when it takes no required argument (`Fieldset.getValue(id)` is not a reader), a
+ * writer of another pair only when the value is its sole required argument.
+ * - `getValue/setValue`: Field, CodeEditor, Filter, SortControl, Toggle (`getValue()` is the
+ *   configured on-value or `false`, the same as the `toggle` field type reads).
+ * - `get/set`: NumberField, Select, Slider, Rating, CheckButton, Datebox, Timebox, Search,
+ *   CopyInput, DatePicker and the other pickers.
+ * - `getValues/setValues`: Checklist, TagPicker, ValueList, MultiValueEditor, Fieldset, Form.
+ * - `isChecked/setChecked`: boolean controls that name their state that way.
+ * @type {ReadonlyArray<readonly [string, string]>}
+ */
+export const VALUE_METHODS = Object.freeze([
+  Object.freeze(['getValue', 'setValue']),
+  Object.freeze(['get', 'set']),
+  Object.freeze(['getValues', 'setValues']),
+  Object.freeze(['isChecked', 'setChecked'])
+]);
+
+/** Value properties a component may expose instead of methods, in the order they are tried. */
+const VALUE_PROPERTIES = Object.freeze(['value', 'values', 'checked']);
+
+/** Form controls the fallback disables or makes read-only inside a plain wrapper element. */
+const CONTROLS = 'input, select, textarea, button';
+const TEXT_CONTROLS = 'input, textarea';
+
+/**
+ * The element a source renders into.
+ * @param {ExternalSource} source Element or component.
+ * @returns {Element}
+ */
+export function externalElement(source) {
+  if (isElement(source)) return /** @type {Element} */ (source);
+  const component = /** @type {{el?: Element, toElement?: () => Element}} */ (source);
+  if (typeof component.toElement === 'function') return component.toElement();
+  if (isElement(component.el)) return /** @type {Element} */ (component.el);
+  throw new TypeError('External field source must be an Element or a Component');
+}
+
+/**
+ * Reads the current value of an element or component through the first value dialect it
+ * supports (see {@link VALUE_METHODS}), then a `value`, `values`, or `checked` property, then the
+ * element itself: `checked` for a checkbox or radio, `value` for any other control. Null when
+ * the source has no value at all.
+ * @param {ExternalSource} source Element or component.
+ * @returns {unknown}
+ */
+export function readExternalValue(source) {
+  return valueAccess(source, externalElement(source)).get();
+}
+
+/**
+ * Reports whether an element or component is disabled: its `isDisabled()`, a `disabled`
+ * property, the element's own `disabled`, an `aria-disabled="true"` or `data-disabled` root, or
+ * a wrapper whose every form control is disabled.
+ * @param {ExternalSource} source Element or component.
+ * @returns {boolean}
+ */
+export function readExternalDisabled(source) {
+  const el = externalElement(source);
+  const component = isElement(source) ? null : /** @type {Record<string, any>} */ (source);
+  if (component && callable(component, 'isDisabled', 0)) return Boolean(component.isDisabled());
+  if (component && typeof component.disabled === 'boolean') return component.disabled;
+  if (hasNativeProperty(el, 'disabled')) return Boolean(/** @type {any} */ (el).disabled) || el.hasAttribute('disabled');
+  if (el.getAttribute('aria-disabled') === 'true') return true;
+  const flag = el.getAttribute('data-disabled');
+  if (flag !== null && flag !== 'false') return true;
+  const controls = [...el.querySelectorAll(CONTROLS)];
+  return controls.length > 0 && controls.every((control) => /** @type {any} */ (control).disabled);
+}
+
+/**
+ * Reports whether an element or component is read-only: a `readonly`/`readOnly` property, the
+ * element's own `readOnly`, or an `aria-readonly="true"` or `data-readonly` root.
+ * @param {ExternalSource} source Element or component.
+ * @returns {boolean}
+ */
+export function readExternalReadonly(source) {
+  const el = externalElement(source);
+  const component = isElement(source) ? null : /** @type {Record<string, any>} */ (source);
+  for (const name of ['readonly', 'readOnly']) {
+    if (component && typeof component[name] === 'boolean') return component[name];
+  }
+  if (hasNativeProperty(el, 'readOnly')) return Boolean(/** @type {any} */ (el).readOnly) || el.hasAttribute('readonly');
+  if (el.getAttribute('aria-readonly') === 'true') return true;
+  const flag = el.getAttribute('data-readonly');
+  return flag !== null && flag !== 'false';
+}
+
+/**
+ * Builds the Field adapter for an element or component that is not a registered field type.
+ *
+ * Values go through the source's own accessors ({@link readExternalValue}); disabling through
+ * `setDisabled(bool)`, then `enable()`/`disable()`, then a `disabled` property, and only then the
+ * DOM — the element's `disabled`, or for a plain wrapper `aria-disabled` plus `disabled` on every
+ * form control inside it. Read-only goes through `setReadonly(bool)`/`setReadOnly(bool)`, a
+ * `readonly`/`readOnly` property, or the element's own `readOnly`.
+ *
+ * Writes pass the caller's options to the component: `Field.setValue(v)` or
+ * `Fieldset.setValues(values)` without `silent` lets the component emit its own `change` to its
+ * own listeners, while the field emits one `change` for the write; with `silent` neither does.
+ *
+ * Given the field, a component's own `change` event becomes the field's `change`, and the native
+ * `change` its inner controls bubble is dropped unless it carries a value the component did not
+ * already report — so one edit is one field `change`, whether the component reports it, its
+ * input does, or (Search, CopyInput) only its input does.
+ *
+ * `destroy()` puts the element back where it was found and undoes what the adapter changed:
+ * attributes, the native value, disabled and read-only state.
+ * @param {ExternalSource} source Element or component to adopt.
+ * @param {Field|null} [field=null] The field the adapter serves; needed to forward events. Its
+ *   `listen()` owns every listener the adapter adds, so destroying the field removes them.
+ * @returns {FieldAdapter}
+ */
+export function externalAdapter(source, field = null) {
+  const el = externalElement(source);
+  const component = isElement(source) ? null : /** @type {Record<string, any>} */ (source);
+  const parent = el.parentNode;
+  const next = el.nextSibling;
+  const attributes = new Map(['id', 'aria-labelledby', 'aria-describedby', 'aria-disabled', 'aria-invalid']
+    .map((name) => [name, el.getAttribute(name)]));
+  const native = component === null;
+  const originalValue = native && hasNativeProperty(el, 'value') ? /** @type {any} */ (el).value : undefined;
+  const originalChecked = native && isCheckable(el) ? /** @type {any} */ (el).checked : undefined;
+  const originalDisabled = readExternalDisabled(source);
+  const originalReadonly = readExternalReadonly(source);
+  /** @type {Map<Element, {disabled?: boolean, readOnly?: boolean}>} */
+  const poked = new Map();
+  const value = valueAccess(source, el);
+  const disabled = disabledAccess(component, el, poked);
+  const readonly = readonlyAccess(component, el, poked);
+  let lastDisabled = originalDisabled;
+  let lastReadonly = originalReadonly;
+  let setting = false;
+  let reported = value.get();
+
+  if (field && component && typeof component.addEventListener === 'function') {
+    // Through the field's `listen()`, so destroying the field unsubscribes. A write through
+    // `set()` is not forwarded: the Field reports that one itself.
+    field.listen(/** @type {any} */ (component), 'change', () => {
+      if (setting) return;
+      reported = value.get();
+      field.emit('change', { value: reported });
+    });
+    // Registered before the Field's own `change` listener on the same element, so a native
+    // change the component already reported never reaches it.
+    field.listen(el, 'change', (event) => {
+      const current = value.get();
+      if (sameValue(current, reported)) event.stopImmediatePropagation();
+      else reported = current;
+    });
+  }
+
+  /** @type {FieldAdapter} */
+  const adapter = {
+    el,
+    get: () => value.get(),
+    set: (next, options) => {
+      setting = true;
+      try { value.set(next, options); }
+      finally { setting = false; }
+      reported = value.get();
+    },
+    focus: () => {
+      if (component && callable(component, 'focus', 0)) component.focus();
+      else if (typeof (/** @type {any} */ (el).focus) === 'function') /** @type {any} */ (el).focus();
+    },
+    setDisabled: (state) => {
+      lastDisabled = Boolean(state);
+      disabled(lastDisabled);
+    },
+    destroy: () => {
+      if (lastReadonly !== originalReadonly && readonly) readonly(originalReadonly);
+      if (lastDisabled !== originalDisabled) disabled(originalDisabled);
+      for (const [control, state] of poked) {
+        if (state.disabled !== undefined) /** @type {any} */ (control).disabled = state.disabled;
+        if (state.readOnly !== undefined) /** @type {any} */ (control).readOnly = state.readOnly;
+      }
+      poked.clear();
+      for (const [name, saved] of attributes) {
+        if (saved === null) el.removeAttribute(name);
+        else el.setAttribute(name, saved);
+      }
+      if (originalValue !== undefined) /** @type {any} */ (el).value = originalValue;
+      if (originalChecked !== undefined) /** @type {any} */ (el).checked = originalChecked;
+      if (parent) parent.insertBefore(el, next?.parentNode === parent ? next : null);
+      else el.remove();
+    }
+  };
+  if (readonly) {
+    adapter.setReadonly = (state) => {
+      lastReadonly = Boolean(state);
+      readonly(lastReadonly);
+    };
+  }
+  return adapter;
+}
+
+/**
+ * The value reader and writer for a source: the first {@link VALUE_METHODS} pair whose reader
+ * exists (its own writer first, then any other dialect's), then a value property, then the
+ * element.
+ * @param {ExternalSource} source Element or component.
+ * @param {Element} el Its element.
+ * @returns {{get: () => unknown, set: (value: unknown, options?: {silent?: boolean}) => void}}
+ */
+function valueAccess(source, el) {
+  const component = isElement(source) ? null : /** @type {Record<string, any>} */ (source);
+  if (component) {
+    const pair = VALUE_METHODS.find(([reader]) => callable(component, reader, 0));
+    // The pair's own writer whatever its signature; another dialect's only when the value is its
+    // sole required argument.
+    const writer = !pair ? undefined : callable(component, pair[1], 2)
+      ? pair[1]
+      : VALUE_METHODS.map(([, name]) => name).find((name) => callable(component, name, 1));
+    if (pair) {
+      return {
+        get: () => component[pair[0]](),
+        // The caller's options pass through: a write that is not silent reaches the component's
+        // own `change` listeners too, and the adapter does not forward it a second time.
+        set: (next, options = {}) => {
+          if (writer) component[writer](next, { ...options, silent: Boolean(options.silent) });
+        }
+      };
+    }
+    const property = VALUE_PROPERTIES.find((name) => name in component);
+    if (property) {
+      return {
+        get: () => component[property],
+        set: (next) => { component[property] = next; }
+      };
+    }
+  }
+  if (isCheckable(el)) {
+    return {
+      get: () => Boolean(/** @type {any} */ (el).checked),
+      set: (next) => { /** @type {any} */ (el).checked = Boolean(next); }
+    };
+  }
+  if (hasNativeProperty(el, 'value')) {
+    return {
+      get: () => /** @type {any} */ (el).value,
+      set: (next) => { /** @type {any} */ (el).value = next == null ? '' : next; }
+    };
+  }
+  return { get: () => null, set: () => {} };
+}
+
+/**
+ * The disabling dialect for a source.
+ * @param {Record<string, any>|null} component Component, or null for a plain element.
+ * @param {Element} el Its element.
+ * @param {Map<Element, {disabled?: boolean, readOnly?: boolean}>} poked Original states of the
+ *   controls the DOM fallback touched.
+ * @returns {(disabled: boolean) => void}
+ */
+function disabledAccess(component, el, poked) {
+  if (component && callable(component, 'setDisabled', 1)) return (state) => component.setDisabled(state);
+  if (component && callable(component, 'enable', 0) && callable(component, 'disable', 0)) {
+    return (state) => (state ? component.disable() : component.enable());
+  }
+  if (component && typeof component.disabled === 'boolean') return (state) => { component.disabled = state; };
+  if (hasNativeProperty(el, 'disabled')) return (state) => { /** @type {any} */ (el).disabled = state; };
+  return (state) => {
+    el.setAttribute('aria-disabled', String(state));
+    for (const control of el.querySelectorAll(CONTROLS)) {
+      remember(poked, control, 'disabled');
+      /** @type {any} */ (control).disabled = state || Boolean(poked.get(control)?.disabled);
+    }
+  };
+}
+
+/**
+ * The read-only dialect for a source, or null when it has none.
+ * @param {Record<string, any>|null} component Component, or null for a plain element.
+ * @param {Element} el Its element.
+ * @param {Map<Element, {disabled?: boolean, readOnly?: boolean}>} poked Original states of the
+ *   controls the DOM fallback touched.
+ * @returns {((readonly: boolean) => void)|null}
+ */
+function readonlyAccess(component, el, poked) {
+  if (component) {
+    for (const name of ['setReadonly', 'setReadOnly']) {
+      if (callable(component, name, 1)) return (state) => component[name](state);
+    }
+    for (const name of ['readonly', 'readOnly']) {
+      if (typeof component[name] === 'boolean') return (state) => { component[name] = state; };
+    }
+    return null;
+  }
+  if (hasNativeProperty(el, 'readOnly')) return (state) => { /** @type {any} */ (el).readOnly = state; };
+  const controls = [...el.querySelectorAll(TEXT_CONTROLS)];
+  if (!controls.length) return null;
+  return (state) => {
+    for (const control of controls) {
+      remember(poked, control, 'readOnly');
+      /** @type {any} */ (control).readOnly = state || Boolean(poked.get(control)?.readOnly);
+    }
+  };
+}
+
+/**
+ * @param {Map<Element, {disabled?: boolean, readOnly?: boolean}>} poked
+ * @param {Element} control
+ * @param {'disabled'|'readOnly'} name
+ * @returns {void}
+ */
+function remember(poked, control, name) {
+  const state = poked.get(control) ?? {};
+  if (state[name] === undefined) state[name] = Boolean(/** @type {any} */ (control)[name]);
+  poked.set(control, state);
+}
+
+/**
+ * Whether `target[name]` is a method taking at most `arity` required arguments.
+ * @param {Record<string, any>} target
+ * @param {string} name
+ * @param {number} arity
+ * @returns {boolean}
+ */
+function callable(target, name, arity) {
+  const fn = target[name];
+  return typeof fn === 'function' && fn.length <= arity;
+}
+
+/** @param {Element} el @param {string} name @returns {boolean} */
+function hasNativeProperty(el, name) {
+  return ['INPUT', 'SELECT', 'TEXTAREA', 'BUTTON', 'FIELDSET', 'OUTPUT'].includes(el.tagName) && name in el;
+}
+
+/** @param {Element} el @returns {boolean} */
+function isCheckable(el) {
+  const type = String(/** @type {any} */ (el).type ?? '').toLowerCase();
+  return el.tagName === 'INPUT' && (type === 'checkbox' || type === 'radio');
+}
+
+/**
+ * Value equality for change de-duplication: identical primitives, Dates at the same instant,
+ * arrays and plain objects with the same JSON.
+ * @param {unknown} a
+ * @param {unknown} b
+ * @returns {boolean}
+ */
+function sameValue(a, b) {
+  if (Object.is(a, b)) return true;
+  if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+  if (a && b && typeof a === 'object' && typeof b === 'object') {
+    try { return JSON.stringify(a) === JSON.stringify(b); } catch { return false; }
+  }
+  return false;
+}