@zeyos/zx 5.0.0 → 5.2.0

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

package/src/components/fieldset/fieldset.js

@@ -2,6 +2,7 @@ import { Component } from '../../core/component.js';
 import { h } from '../../core/dom.js';
 import { isElement, uid } from '../../core/util.js';
 import { Field } from '../field/field.js';
+import { externalAdapter, readExternalDisabled, readExternalReadonly, readExternalValue } from './external-adapter.js';
 
 /**
  * @typedef {Object} FieldsetOptions
@@ -56,6 +57,13 @@ export class Fieldset extends Component {
    * Adds a field from options, an existing field, an element, or a component. The key becomes the
    * field's `name` and its `data-field-id`; the control's DOM id is `<idPrefix>-<key>`, unless the
    * field options give an `id` of their own that differs from the key.
+   *
+   * An element or a component that is not a registered field type is wrapped in a `custom` field
+   * that reads and writes it through its own API — `getValue`/`setValue`, `get`/`set`,
+   * `getValues`/`setValues`, `isChecked`/`setChecked`, or a `value` property — disables it
+   * through `setDisabled(bool)` or `enable()`/`disable()`, and makes it read-only through
+   * `setReadonly(bool)`, falling back to the element's native properties only when the component
+   * has none of these. The component's own `change` becomes the field's `change`, once per edit.
    * @param {string} id Logical field identifier.
    * @param {FieldOptions|Field|Element|Component} field Field source.
    * @returns {Field}
@@ -76,7 +84,8 @@ export class Fieldset extends Component {
         label: key,
         value: readExternalValue(source),
         disabled: readExternalDisabled(source),
-        adapter: () => externalAdapter(source)
+        readonly: readExternalReadonly(source),
+        adapter: (owner) => externalAdapter(source, owner)
       });
       owned = true;
     } else {
@@ -270,61 +279,3 @@ export class Fieldset extends Component {
     super.destroy();
   }
 }
-
-/** @param {Element|Component} source @returns {import('../field/field.js').FieldAdapter} */
-function externalAdapter(source) {
-  const el = isElement(source) ? source : source.toElement();
-  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 originalDisabled = 'disabled' in el ? el.disabled : undefined;
-  const originalValue = 'value' in el ? el.value : undefined;
-  return {
-    el,
-    get: () => {
-      if (typeof source.getValue === 'function') return source.getValue();
-      if (typeof source.getValues === 'function') return source.getValues();
-      if ('value' in el) return el.value;
-      return null;
-    },
-    set: (value, options) => {
-      if (typeof source.setValue === 'function') source.setValue(value, options);
-      else if (typeof source.setValues === 'function' && value && typeof value === 'object') source.setValues(value, options);
-      else if ('value' in el) el.value = value == null ? '' : value;
-    },
-    focus: () => {
-      if (typeof source.focus === 'function') source.focus();
-      else if (typeof el.focus === 'function') el.focus();
-    },
-    setDisabled: (disabled) => {
-      if (typeof source.setDisabled === 'function') source.setDisabled(disabled);
-      else if ('disabled' in el) el.disabled = disabled;
-      else el.setAttribute('aria-disabled', String(disabled));
-    },
-    destroy: () => {
-      for (const [name, value] of attributes) {
-        if (value === null) el.removeAttribute(name);
-        else el.setAttribute(name, value);
-      }
-      if (originalDisabled !== undefined) el.disabled = originalDisabled;
-      if (originalValue !== undefined) el.value = originalValue;
-      if (parent) parent.insertBefore(el, next?.parentNode === parent ? next : null);
-      else el.remove();
-    }
-  };
-}
-
-/** @param {Element|Component} source @returns {unknown} */
-function readExternalValue(source) {
-  const el = isElement(source) ? source : source.toElement();
-  if (typeof source.getValue === 'function') return source.getValue();
-  if (typeof source.getValues === 'function') return source.getValues();
-  return 'value' in el ? el.value : null;
-}
-
-/** @param {Element|Component} source @returns {boolean} */
-function readExternalDisabled(source) {
-  const el = isElement(source) ? source : source.toElement();
-  return 'disabled' in el ? Boolean(el.disabled) : el.getAttribute('aria-disabled') === 'true';
-}

package/src/components/file-list/file-list.js

@@ -1,6 +1,7 @@
 // @ts-check
 import { Component } from '../../core/component.js';
 import { h, restoreTarget, snapshotTarget } from '../../core/dom.js';
+import { captureItemFocus, restoreItemFocus } from '../../core/keyboard.js';
 import { skeleton, skeletonText } from '../skeleton/skeleton.js';
 import { FileItem, normalizeFileItem } from '../file-item/file-item.js';
 
@@ -26,6 +27,12 @@ import { FileItem, normalizeFileItem } from '../file-item/file-item.js';
 /**
  * Accessible collection for durable and transient files. Ordering and mutation are local
  * presentation concerns only; transport, authorization, and persistence remain host-owned.
+ *
+ * Mutations are reconciled by file `id`: a file whose descriptor did not change keeps its row
+ * untouched, a changed one is updated in place through `FileItem.set()`, and only added or removed
+ * files create or drop rows. Upload progress can therefore tick through `updateItem()` while the
+ * reader's focus — on that file's Cancel button, say — and the list's scroll position stay put.
+ * Files without an `id` cannot be matched and are rebuilt on every mutation.
  * @fires FileList#activate
  * @fires FileList#action
  * @fires FileList#datachange
@@ -63,6 +70,12 @@ export class FileList extends Component {
     this._items = normalizeFileListItems(this.options.items);
     this._loading = Boolean(this.options.loading);
     this._itemComponents = [];
+    /** @type {Map<FileItem, {row: HTMLElement, state: FileItemState}>} */
+    this._itemRecords = new Map();
+    this._itemList = /** @type {HTMLElement|null} */ (null);
+    this._emptyRegion = /** @type {HTMLElement|null} */ (null);
+    this._loadingRegion = /** @type {HTMLElement|null} */ (null);
+    this._loadingPlaceholders = false;
 
     root.setAttribute('aria-label', String(this.options.label || 'Files'));
     this.listen(root, 'zx-activate', (event) => this._forwardActivate(/** @type {CustomEvent} */ (event)));
@@ -166,37 +179,104 @@ export class FileList extends Component {
     if (!this._createdRoot && root) restoreTarget(root, this._snapshot);
   }
 
-  /** @returns {void} */
+  /**
+   * Brings the rendered rows in line with `_items`, keyed by file id, and keeps focus on the
+   * control that held it when that control's row was updated or removed.
+   * @returns {void}
+   */
   _renderList() {
-    this._destroyItems();
     const root = /** @type {HTMLElement} */ (this.el);
+    const focus = captureItemFocus(root, (element) => {
+      const index = this._itemComponents.findIndex((item) => item.el?.contains(element));
+      return index < 0 ? null : { key: { component: this._itemComponents[index], index }, element: this._itemComponents[index].el };
+    });
     root.setAttribute('aria-busy', String(this._loading));
-    /** @type {HTMLElement[]} */
-    const content = [];
     try {
-      if (this._items.length) {
-        const list = h('ol', { class: 'zx-file-list__items' });
-        for (const descriptor of this._items) {
-          const component = new FileItem(null, descriptor);
-          this._itemComponents.push(component);
-          list.append(h('li', { class: 'zx-file-list__item' }, component));
-        }
-        content.push(list);
-      } else if (!this._loading) {
-        content.push(h('div', {
-          class: 'zx-file-list__empty', role: 'status'
-        }, listContent(this.options.emptyText, 'FileList emptyText')));
-      }
-      if (this._loading) content.push(this._createLoading(this._items.length === 0));
-      root.replaceChildren(...content);
+      this._reconcileItems();
     } catch (error) {
       this._destroyItems();
       throw error;
     }
+    /** @type {HTMLElement[]} */
+    const content = [];
+    if (this._items.length) content.push(/** @type {HTMLElement} */ (this._itemList));
+    else if (!this._loading) {
+      this._emptyRegion ??= h('div', {
+        class: 'zx-file-list__empty', role: 'status'
+      }, listContent(this.options.emptyText, 'FileList emptyText'));
+      content.push(this._emptyRegion);
+    }
+    if (this._loading) content.push(this._createLoading(this._items.length === 0));
+    syncChildren(root, content);
+    restoreItemFocus(root, focus, (key) => {
+      const memo = /** @type {{component: FileItem, index: number}} */ (key);
+      if (this._itemComponents.includes(memo.component)) return memo.component.el;
+      // The focused file went away: its successor — or the new last file — takes over.
+      const fallback = this._itemComponents[Math.min(memo.index, this._itemComponents.length - 1)];
+      return fallback?.el ?? null;
+    });
   }
 
-  /** @param {boolean} placeholders @returns {HTMLElement} */
+  /**
+   * Keyed reconciliation of `FileItem` children. Rows are only moved when out of place, because
+   * detaching a row — even to re-insert it a moment later — takes focus out of it.
+   * @returns {void}
+   */
+  _reconcileItems() {
+    const previous = this._itemComponents;
+    /** @type {Map<unknown, FileItem>} */
+    const byId = new Map();
+    for (const component of previous) {
+      const id = this._itemRecords.get(component)?.state.id ?? null;
+      if (id !== null) byId.set(id, component);
+    }
+    /** @type {FileItem[]} */
+    const next = [];
+    for (const descriptor of this._items) {
+      const existing = descriptor.id === null ? undefined : byId.get(descriptor.id);
+      if (existing) {
+        byId.delete(descriptor.id);
+        const record = /** @type {{row: HTMLElement, state: FileItemState}} */ (this._itemRecords.get(existing));
+        if (!sameDescriptor(record.state, descriptor)) existing.set(descriptor);
+        record.state = descriptor;
+        next.push(existing);
+        continue;
+      }
+      const component = new FileItem(null, descriptor);
+      this._itemRecords.set(component, {
+        row: h('li', { class: 'zx-file-list__item' }, component),
+        state: descriptor
+      });
+      next.push(component);
+    }
+    const kept = new Set(next);
+    for (const component of previous) {
+      if (kept.has(component)) continue;
+      this._itemRecords.get(component)?.row.remove();
+      this._itemRecords.delete(component);
+      component.destroy();
+    }
+    this._itemComponents = next;
+    if (next.length === 0) return;
+    const list = this._itemList ??= h('ol', { class: 'zx-file-list__items' });
+    syncChildren(list, next.map((component) => /** @type {{row: HTMLElement}} */ (this._itemRecords.get(component)).row));
+  }
+
+  /**
+   * The loading region, kept across renders while its shape stays the same so that its live
+   * status is not re-announced by every mutation that happens during a load.
+   * @param {boolean} placeholders Whether skeleton rows stand in for an empty list.
+   * @returns {HTMLElement}
+   */
   _createLoading(placeholders) {
+    if (this._loadingRegion && this._loadingPlaceholders === placeholders) return this._loadingRegion;
+    this._loadingPlaceholders = placeholders;
+    this._loadingRegion = this._buildLoading(placeholders);
+    return this._loadingRegion;
+  }
+
+  /** @param {boolean} placeholders @returns {HTMLElement} */
+  _buildLoading(placeholders) {
     const region = h('div', {
       class: 'zx-file-list__loading', role: 'status', ariaLive: 'polite'
     }, h('span', { class: 'zx-file-list__loading-label' }, String(this.options.loadingText)));
@@ -214,7 +294,9 @@ export class FileList extends Component {
   /** @returns {void} */
   _destroyItems() {
     for (const item of this._itemComponents) item.destroy();
-    this._itemComponents.length = 0;
+    this._itemComponents = [];
+    this._itemRecords?.clear();
+    this._itemList?.replaceChildren();
   }
 
   /** @param {CustomEvent} event @returns {void} */
@@ -297,6 +379,47 @@ function cloneFileDescriptor(item) {
   };
 }
 
+/**
+ * Makes `parent`'s children exactly `children`, in order, moving only the nodes that are out of
+ * place so that an untouched node — and the focus inside it — never leaves the document.
+ * @param {Element} parent Container.
+ * @param {Node[]} children Desired children.
+ * @returns {void}
+ */
+function syncChildren(parent, children) {
+  const wanted = new Set(children);
+  for (const node of [...parent.childNodes]) if (!wanted.has(node)) node.remove();
+  children.forEach((node, index) => {
+    const current = parent.childNodes[index] ?? null;
+    if (current !== node) parent.insertBefore(node, current);
+  });
+}
+
+/**
+ * Structural equality for normalized file descriptors: primitives by value, arrays and plain
+ * objects member by member, and Nodes, Components, or functions by identity.
+ * @param {unknown} left Previous value.
+ * @param {unknown} right Next value.
+ * @returns {boolean}
+ */
+function sameDescriptor(left, right) {
+  if (Object.is(left, right)) return true;
+  if (Array.isArray(left) && Array.isArray(right)) {
+    return left.length === right.length && left.every((value, index) => sameDescriptor(value, right[index]));
+  }
+  if (!isPlainRecord(left) || !isPlainRecord(right)) return false;
+  const keys = Object.keys(left);
+  return keys.length === Object.keys(right).length
+    && keys.every((key) => Object.prototype.hasOwnProperty.call(right, key) && sameDescriptor(left[key], right[key]));
+}
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isPlainRecord(value) {
+  if (!value || typeof value !== 'object') return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
 /** @param {unknown} value @param {string} label @returns {Node|string} */
 function listContent(value, label) {
   if (value == null) return '';