@zeyos/zx 4.4.0 → 5.2.0

package/src/components/fieldset/fieldset.css

@@ -15,11 +15,13 @@
   inline-size: 100%;
 }
 
+/* A caption for the group, in sentence case and the same quiet voice as the field labels inside
+   it — the fields are the content. */
 .zx-fieldset__legend {
   padding-inline: var(--zx-space-2);
-  color: var(--zx-color-text);
-  font-size: var(--zx-text-lg);
-  font-weight: 600;
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-sm);
+  font-weight: var(--zx-weight-medium);
 }
 
 .zx-fieldset__grid {

package/src/components/fieldset/fieldset.js

@@ -1,13 +1,17 @@
 import { Component } from '../../core/component.js';
 import { h } from '../../core/dom.js';
-import { isElement } from '../../core/util.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
  * @property {string} [title=''] Legend text.
  * @property {1|2|3} [columns=1] Grid column count.
  * @property {Record<string, FieldOptions|Field|Element|Component>} [fields={}] Initial fields.
+ * @property {string|null} [idPrefix=null] Prefix of the DOM ids generated for the fields, as
+ *   `<idPrefix>-<key>`. Null generates one per instance, so the same fieldset mounted twice
+ *   never repeats an id and a field key never collides with an element id elsewhere on the page.
  */
 
 /** @typedef {import('../field/field.js').FieldOptions} FieldOptions */
@@ -20,7 +24,7 @@ export class Fieldset extends Component {
   static cssName = 'fieldset';
 
   /** @type {FieldsetOptions} */
-  static defaults = { title: '', columns: 1, fields: {} };
+  static defaults = { title: '', columns: 1, fields: {}, idPrefix: null };
 
   /** @returns {HTMLElement} */
   render() {
@@ -30,6 +34,7 @@ export class Fieldset extends Component {
     this._origins = new Map();
     this._fieldIdAttributes = new Map();
     this._ownedNodes = [];
+    this._idPrefix = this.options.idPrefix ? String(this.options.idPrefix) : uid('zx-fieldset');
     this._columnAttribute = root.getAttribute('data-columns');
     const columns = [1, 2, 3].includes(Number(this.options.columns)) ? Number(this.options.columns) : 1;
     root.dataset.columns = String(columns);
@@ -49,7 +54,16 @@ export class Fieldset extends Component {
   }
 
   /**
-   * Adds a field from options, an existing field, an element, or a 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}
@@ -64,17 +78,26 @@ export class Fieldset extends Component {
     } else if (isElement(field) || field instanceof Component) {
       const source = field;
       instance = new Field(null, {
-        id: key,
+        id: this._controlId(key),
+        name: key,
         type: 'custom',
         label: key,
         value: readExternalValue(source),
         disabled: readExternalDisabled(source),
-        adapter: () => externalAdapter(source)
+        readonly: readExternalReadonly(source),
+        adapter: (owner) => externalAdapter(source, owner)
       });
       owned = true;
     } else {
       const options = field && typeof field === 'object' ? field : {};
-      instance = new Field(null, { ...options, id: options.id ?? key });
+      // An `id` equal to the key is the key restated (schema descriptors carry both), not a
+      // request for that DOM id.
+      const explicit = options.id != null && String(options.id) !== '' && String(options.id) !== key;
+      instance = new Field(null, {
+        ...options,
+        id: explicit ? String(options.id) : this._controlId(key),
+        name: options.name ?? key
+      });
       owned = true;
     }
 
@@ -218,6 +241,15 @@ export class Fieldset extends Component {
     return this;
   }
 
+  /**
+   * The DOM id generated for a field key: unique per instance unless `idPrefix` was given.
+   * @param {string} key Field key.
+   * @returns {string}
+   */
+  _controlId(key) {
+    return `${this._idPrefix}-${key.trim().replace(/\s+/g, '-')}`;
+  }
+
   /** @param {Field} field @returns {void} */
   _releaseField(field) {
     const fieldId = this._fieldIdAttributes.get(field);
@@ -247,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-item/file-item.js

@@ -2,6 +2,7 @@
 import { Component } from '../../core/component.js';
 import { h, restoreTarget, snapshotTarget } from '../../core/dom.js';
 import { formatFileSize } from '../../core/format.js';
+import { getIconConfig, iconNames } from '../../core/icons.js';
 import { isElement } from '../../core/util.js';
 import { badge } from '../badge/badge.js';
 import {
@@ -20,9 +21,13 @@ import {
  * @property {unknown} [id=null] Application-owned file identifier included in events.
  * @property {string} [name=''] File name.
  * @property {number|string|null} [size=null] Byte count; invalid and negative values are omitted.
- * @property {string} [mime=''] MIME type.
+ * @property {string} [mime=''] MIME type. Shown as a readable type ("PDF", "Image"), never as
+ *   the raw string, and used to pick the icon.
+ * @property {string|null} [typeLabel=null] Type shown beside the size; null derives it from the
+ *   MIME type (or the name's extension when the MIME type is unfamiliar), an empty string hides it.
  * @property {EntityRefContent} [subtitle=null] Optional supporting text before generated metadata.
- * @property {EntityRefIcon} [icon='file'] File icon name, node, component, or lazy renderer.
+ * @property {EntityRefIcon} [icon='file'] File icon name, node, component, or lazy renderer. The
+ *   generic `'file'` glyph gives way to one for the MIME type when the active icon set has it.
  * @property {EntityRefMetadata[]} [metadata=[]] Additional labelled metadata.
  * @property {EntityRefLinkValue} [link=null] Optional safe native file/download link.
  * @property {EntityRefActionEntry[]} [actions=[]] File actions; application policy stays external.
@@ -30,7 +35,7 @@ import {
  * @property {string|null} [statusLabel=null] Overrides the generated state label; an empty string hides it.
  * @property {number|null} [progress=null] Completed percentage, clamped to 0–100.
  * @property {boolean} [indeterminate=false] Whether active progress has no known amount.
- * @property {'sm'|'md'|'lg'} [density='md'] File-identity presentation size.
+ * @property {'sm'|'md'|'lg'} [identitySize='md'] Size of the file's icon and name.
  * @property {boolean} [wrap=false] Whether long identity text may wrap.
  * @property {string} [actionsLabel='File actions'] Accessible name for secondary actions.
  * @property {string} [locale] Locale passed to `formatFileSize`.
@@ -46,6 +51,7 @@ import {
  * @property {string} name File name.
  * @property {number|null} size Byte count.
  * @property {string} mime MIME type.
+ * @property {string|null} typeLabel Explicit type label, or null for the one derived from `mime`.
  * @property {EntityRefContent} subtitle Supporting content.
  * @property {EntityRefIcon} icon File visual.
  * @property {EntityRefMetadata[]} metadata Additional metadata.
@@ -55,7 +61,7 @@ import {
  * @property {string|null} statusLabel Explicit state label, or null for the generated label.
  * @property {number|null} progress Completed percentage.
  * @property {boolean} indeterminate Unknown-progress state.
- * @property {'sm'|'md'|'lg'} density Identity size.
+ * @property {'sm'|'md'|'lg'} identitySize Size of the file's icon and name.
  * @property {boolean} wrap Wrapping state.
  * @property {string} actionsLabel Action-group label.
  * @property {string|undefined} locale File-size locale.
@@ -91,6 +97,7 @@ export class FileItem extends Component {
     name: '',
     size: null,
     mime: '',
+    typeLabel: null,
     subtitle: null,
     icon: 'file',
     metadata: [],
@@ -100,7 +107,7 @@ export class FileItem extends Component {
     statusLabel: null,
     progress: null,
     indeterminate: false,
-    density: 'md',
+    identitySize: 'md',
     wrap: false,
     actionsLabel: 'File actions'
   };
@@ -207,7 +214,7 @@ export class FileItem extends Component {
     const track = /** @type {HTMLElement} */ (this.refs.progressTrack);
     const fill = /** @type {HTMLElement} */ (this.refs.progressFill);
     root.dataset.status = state.status;
-    root.dataset.density = state.density;
+    root.dataset.identitySize = state.identitySize;
     this._entity.set(entityOptions(state));
 
     const label = fileStatusLabel(state);
@@ -282,6 +289,7 @@ export function normalizeFileItem(values = {}) {
     name: String(source.name ?? ''),
     size: rawSize !== null && Number.isFinite(rawSize) && rawSize >= 0 ? rawSize : null,
     mime: String(source.mime ?? ''),
+    typeLabel: source.typeLabel == null ? null : String(source.typeLabel),
     subtitle: normalizeFileContent(source.subtitle),
     icon: source.icon === undefined ? 'file' : source.icon,
     metadata: normalizeEntityRefMetadata(source.metadata),
@@ -292,7 +300,7 @@ export function normalizeFileItem(values = {}) {
     progress: rawProgress === null || !Number.isFinite(rawProgress)
       ? null : Math.min(100, Math.max(0, rawProgress)),
     indeterminate: Boolean(source.indeterminate),
-    density: source.density === 'sm' || source.density === 'lg' ? source.density : 'md',
+    identitySize: source.identitySize === 'sm' || source.identitySize === 'lg' ? source.identitySize : 'md',
     wrap: Boolean(source.wrap),
     actionsLabel: String(source.actionsLabel || 'File actions'),
     locale: normalizeLocale(source.locale)
@@ -302,7 +310,8 @@ export function normalizeFileItem(values = {}) {
 /** @param {FileItemState} state @returns {import('../entity-ref/entity-ref.js').EntityRefOptions} */
 function entityOptions(state) {
   const metadata = [];
-  if (state.mime) metadata.push({ label: 'Type', value: state.mime, showLabel: false });
+  const type = state.typeLabel ?? fileTypeLabel(state.mime, state.name);
+  if (type) metadata.push({ label: 'Type', value: type, showLabel: false });
   if (state.size !== null) {
     metadata.push({
       label: 'Size',
@@ -315,16 +324,141 @@ function entityOptions(state) {
     id: state.id,
     title: state.name,
     subtitle: state.subtitle,
-    icon: state.icon,
+    icon: state.icon === 'file' ? fileTypeIcon(state.mime) : state.icon,
     metadata,
     link: state.link,
     actions: state.actions,
-    size: state.density,
+    size: state.identitySize,
     wrap: state.wrap,
     actionsLabel: state.actionsLabel
   };
 }
 
+/**
+ * What a MIME type is called and drawn as. Labels are what a reader recognises — a format's own
+ * acronym where it has a well-known one, the family otherwise — and icons are Font Awesome names
+ * in order of preference, used only when the active icon set can draw them.
+ * @type {Readonly<Record<string, {label: string, icons: string[]}>>}
+ */
+const FILE_KINDS = Object.freeze({
+  pdf: { label: 'PDF', icons: ['file-pdf'] },
+  csv: { label: 'CSV', icons: ['file-csv', 'file-excel'] },
+  tsv: { label: 'TSV', icons: ['file-csv', 'file-excel'] },
+  spreadsheet: { label: 'Spreadsheet', icons: ['file-excel'] },
+  document: { label: 'Document', icons: ['file-word', 'file-lines'] },
+  presentation: { label: 'Presentation', icons: ['file-powerpoint'] },
+  text: { label: 'Text', icons: ['file-lines'] },
+  markdown: { label: 'Markdown', icons: ['file-lines'] },
+  html: { label: 'HTML', icons: ['file-code', 'code'] },
+  css: { label: 'CSS', icons: ['file-code', 'code'] },
+  javascript: { label: 'JavaScript', icons: ['file-code', 'code'] },
+  json: { label: 'JSON', icons: ['file-code', 'code'] },
+  xml: { label: 'XML', icons: ['file-code', 'code'] },
+  zip: { label: 'ZIP', icons: ['file-zipper'] },
+  gzip: { label: 'GZIP', icons: ['file-zipper'] },
+  tar: { label: 'TAR', icons: ['file-zipper'] },
+  rar: { label: 'RAR', icons: ['file-zipper'] },
+  sevenZip: { label: '7Z', icons: ['file-zipper'] },
+  email: { label: 'Email', icons: ['envelope'] },
+  calendar: { label: 'Calendar', icons: ['calendar'] },
+  contact: { label: 'Contact', icons: ['address-card'] },
+  image: { label: 'Image', icons: ['file-image', 'image'] },
+  video: { label: 'Video', icons: ['file-video', 'video'] },
+  audio: { label: 'Audio', icons: ['file-audio'] },
+  font: { label: 'Font', icons: ['font'] }
+});
+
+/** Exact MIME types, lower case and without parameters, mapped to their kind. */
+const MIME_KINDS = new Map(Object.entries({
+  'application/pdf': 'pdf',
+  'text/csv': 'csv',
+  'application/csv': 'csv',
+  'text/comma-separated-values': 'csv',
+  'text/tab-separated-values': 'tsv',
+  'application/vnd.ms-excel': 'spreadsheet',
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': 'spreadsheet',
+  'application/vnd.oasis.opendocument.spreadsheet': 'spreadsheet',
+  'application/msword': 'document',
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document': 'document',
+  'application/vnd.oasis.opendocument.text': 'document',
+  'application/rtf': 'document',
+  'text/rtf': 'document',
+  'application/vnd.ms-powerpoint': 'presentation',
+  'application/vnd.openxmlformats-officedocument.presentationml.presentation': 'presentation',
+  'application/vnd.oasis.opendocument.presentation': 'presentation',
+  'text/plain': 'text',
+  'text/markdown': 'markdown',
+  'text/x-markdown': 'markdown',
+  'text/html': 'html',
+  'application/xhtml+xml': 'html',
+  'text/css': 'css',
+  'text/javascript': 'javascript',
+  'application/javascript': 'javascript',
+  'application/json': 'json',
+  'application/ld+json': 'json',
+  'application/xml': 'xml',
+  'text/xml': 'xml',
+  'application/zip': 'zip',
+  'application/x-zip-compressed': 'zip',
+  'application/gzip': 'gzip',
+  'application/x-gzip': 'gzip',
+  'application/x-tar': 'tar',
+  'application/vnd.rar': 'rar',
+  'application/x-rar-compressed': 'rar',
+  'application/x-7z-compressed': 'sevenZip',
+  'message/rfc822': 'email',
+  'text/calendar': 'calendar',
+  'text/vcard': 'contact',
+  'text/x-vcard': 'contact'
+}));
+
+/** Top-level MIME types that name a whole family. */
+const MIME_FAMILIES = new Map([
+  ['image', 'image'], ['video', 'video'], ['audio', 'audio'], ['font', 'font'], ['text', 'text']
+]);
+
+/**
+ * @param {string} mime MIME type, possibly with parameters.
+ * @returns {{label: string, icons: string[]}|null}
+ */
+function fileKind(mime) {
+  const essence = String(mime ?? '').split(';')[0].trim().toLowerCase();
+  if (!essence) return null;
+  const kind = MIME_KINDS.get(essence) ?? MIME_FAMILIES.get(essence.split('/')[0]);
+  return kind ? FILE_KINDS[kind] : null;
+}
+
+/**
+ * A readable name for a file's type: "PDF", "CSV", "Image", "Spreadsheet". An unfamiliar MIME type
+ * falls back to the name's extension in capitals ("EXE"); without a MIME type, or with neither,
+ * the result is empty — a raw MIME string is never shown.
+ * @param {string} mime MIME type, possibly with parameters (`text/csv; charset=utf-8`).
+ * @param {string} [name=''] File name, consulted only when the MIME type is unfamiliar.
+ * @returns {string}
+ */
+export function fileTypeLabel(mime, name = '') {
+  if (!String(mime ?? '').trim()) return '';
+  const kind = fileKind(mime);
+  if (kind) return kind.label;
+  const extension = /\.([a-z0-9]{1,5})$/i.exec(String(name ?? ''))?.[1];
+  return extension ? extension.toUpperCase() : '';
+}
+
+/**
+ * The icon name for a MIME type: a type-specific glyph when the active icon set can draw one,
+ * `'file'` otherwise. Font Awesome resolves every name it is given; the bundled inline set only
+ * those it carries or that `registerIcons()` added, so a missing glyph never shows a placeholder.
+ * @param {string} mime MIME type, possibly with parameters.
+ * @returns {string}
+ */
+export function fileTypeIcon(mime) {
+  const candidates = fileKind(mime)?.icons ?? [];
+  if (!candidates.length) return 'file';
+  if (getIconConfig().provider === 'fontawesome') return candidates[0];
+  const available = new Set(iconNames());
+  return candidates.find((name) => available.has(name)) ?? 'file';
+}
+
 /** @param {FileItemState} state @returns {string} */
 function fileStatusLabel(state) {
   return state.statusLabel === null ? STATUS_LABELS[state.status] : state.statusLabel;

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 '';