@zeyos/zx 4.4.0 → 5.0.0

package/src/components/dialog/dialog.js

@@ -20,7 +20,7 @@ import { button } from '../button/button.js';
  * @property {DialogButton[]} [buttons=[]] Footer buttons.
  * @property {boolean} [closable=true] Whether Escape and the header button may close the dialog.
  * @property {Node|string|number|{toElement: () => Node|null}|null} [content=null] Body content.
- * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns the overlay; defaults to the opener.
+ * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns the overlay; defaults to the opener. Resolved on every open, so a scope connected after construction still owns it.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
  * @property {(event: CustomEvent<{result: unknown}>) => void} [onclose] Close event listener.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [oncancel] Cancel event listener.
@@ -51,6 +51,11 @@ import { button } from '../button/button.js';
  * @property {string} [okLabel='OK'] Confirmation label.
  * @property {string} [cancelLabel='Cancel'] Cancellation label.
  * @property {boolean} [danger=false] Whether the confirmation action is dangerous.
+ * @property {string|null} [confirmText=null] Text the reader must type before the confirm button
+ *   enables — the name of what is about to be deleted, say. The dialog adds an input labelled
+ *   "Type <confirmText> to confirm" (message `dialog.typeToConfirm`, `%1` standing for the text),
+ *   focuses it, and enables the confirm button, and Enter, only while its value matches exactly,
+ *   ignoring surrounding spaces.
  */
 /**
  * @typedef {Object} PromptOptions
@@ -58,6 +63,8 @@ import { button } from '../button/button.js';
  * @property {Node|string|number|null} [message=''] Prompt message.
  * @property {string} [value=''] Initial input value.
  * @property {string} [placeholder=''] Input placeholder.
+ * @property {string} [okLabel='OK'] Confirmation label.
+ * @property {string} [cancelLabel='Cancel'] Cancellation label.
  */
 
 /**
@@ -138,7 +145,7 @@ export class Dialog extends Modal {
       h('footer', { class: 'zx-dialog__footer', ref: 'footer' })
     ));
     dialog.dataset.state = 'closed';
-    this.mountTarget().append(dialog);
+    this._mountInitial(dialog);
     return dialog;
   }
 
@@ -281,12 +288,13 @@ export class Dialog extends Modal {
   }
 
   /**
-   * Opens a confirmation dialog.
+   * Opens a confirmation dialog. With `confirmText` it becomes a type-to-confirm dialog: the
+   * confirm button stays disabled until the reader has typed that text.
    * @param {ConfirmOptions} [options={}] Confirmation options.
-   * @returns {Promise<boolean>}
+   * @returns {Promise<boolean>} True when confirmed; false on Cancel, Escape, or the close button.
    */
   static confirm({
-    title = '', message = '', okLabel, cancelLabel, danger = false
+    title = '', message = '', okLabel, cancelLabel, danger = false, confirmText = null
   } = {}) {
     return new Promise((resolve) => {
       let settled = false;
@@ -296,16 +304,58 @@ export class Dialog extends Modal {
         dialog.close(value);
         resolve(value);
       };
-      const dialog = new Dialog(null, { title, content: message });
-      dialog.setButtons([
-        { label: cancelLabel ?? dialog._message('dialog.cancel', 'Cancel'), action: () => finish(false) },
-        {
-          label: okLabel ?? dialog._message('dialog.ok', 'OK'),
-          kind: danger ? 'danger' : 'primary',
-          action: () => finish(true),
+      const expected = confirmText == null ? '' : String(confirmText).trim();
+      const dialog = new Dialog(null, { title, content: expected ? null : message });
+      // A destructive confirmation starts on the least destructive choice, as the APG alert dialog
+      // has it; type-to-confirm starts in its input.
+      const cancel = {
+        label: cancelLabel ?? dialog._message('dialog.cancel', 'Cancel'),
+        action: () => finish(false),
+        autofocus: danger && !expected
+      };
+      const accept = {
+        label: okLabel ?? dialog._message('dialog.ok', 'OK'),
+        kind: /** @type {DialogButtonKind} */ (danger ? 'danger' : 'primary'),
+        action: () => finish(true),
+        autofocus: !danger && !expected
+      };
+      if (expected) {
+        const input = /** @type {HTMLInputElement} */ (h('input', {
+          class: 'zx-dialog__confirm-input',
+          id: uid('zx-dialog-confirm'),
+          type: 'text',
+          autocomplete: 'off',
+          autocapitalize: 'off',
+          spellcheck: false,
           autofocus: true
-        }
-      ]);
+        }));
+        const [before, after] = typeToConfirmParts(
+          dialog._message('dialog.typeToConfirm', 'Type %1 to confirm'), expected);
+        const label = h('label', { class: 'zx-dialog__confirm-label', for: input.id },
+          before, h('b', {}, expected), after);
+        dialog.setContent(h('div', { class: 'zx-dialog__confirm' },
+          isEmptyContent(message) ? null : h('div', { class: 'zx-dialog__prompt-message' }, message),
+          label,
+          input));
+        let matched = false;
+        const settle = () => dialog.setButtons([cancel, { ...accept, autofocus: false, disabled: !matched }]);
+        settle();
+        dialog.listen(input, 'input', () => {
+          const next = typedConfirmation(input.value, expected);
+          if (next === matched) return;
+          matched = next;
+          settle();
+        });
+        // Enter confirms only a match; otherwise it does nothing, as the disabled button would.
+        dialog.listen(input, 'keydown', (event) => {
+          const key = /** @type {KeyboardEvent} */ (event);
+          if (key.key !== 'Enter' || key.isComposing) return;
+          key.preventDefault();
+          if (typedConfirmation(input.value, expected)) finish(true);
+        });
+      } else {
+        dialog.setButtons([cancel, accept]);
+      }
       dialog.once('close', () => {
         if (!settled) {
           settled = true;
@@ -322,7 +372,9 @@ export class Dialog extends Modal {
    * @param {PromptOptions} [options={}] Prompt options.
    * @returns {Promise<string|null>}
    */
-  static prompt({ title = '', message = '', value = '', placeholder = '' } = {}) {
+  static prompt({
+    title = '', message = '', value = '', placeholder = '', okLabel, cancelLabel
+  } = {}) {
     return new Promise((resolve) => {
       let settled = false;
       const input = h('input', {
@@ -344,8 +396,8 @@ export class Dialog extends Modal {
       const dialog = new Dialog(null, { title, content });
       input.setAttribute('aria-label', String(title || dialog._message('dialog.promptValue', 'Prompt value')));
       dialog.setButtons([
-        { label: dialog._message('dialog.cancel', 'Cancel'), action: () => finish(null) },
-        { label: dialog._message('dialog.ok', 'OK'), kind: 'primary', action: () => finish(input.value) }
+        { label: cancelLabel ?? dialog._message('dialog.cancel', 'Cancel'), action: () => finish(null) },
+        { label: okLabel ?? dialog._message('dialog.ok', 'OK'), kind: 'primary', action: () => finish(input.value) }
       ]);
       dialog.listen(input, 'keydown', (event) => {
         if (event.key !== 'Enter') return;
@@ -428,6 +480,36 @@ export class Dialog extends Modal {
   }
 }
 
+/**
+ * Reports whether what the reader typed confirms a type-to-confirm dialog: the same text, exactly
+ * — case and inner spacing included — once surrounding spaces are ignored on both sides.
+ * @param {unknown} typed Input value.
+ * @param {unknown} expected Text the dialog asks for.
+ * @returns {boolean}
+ */
+export function typedConfirmation(typed, expected) {
+  const target = expected == null ? '' : String(expected).trim();
+  return target !== '' && String(typed ?? '').trim() === target;
+}
+
+/**
+ * Splits the type-to-confirm message around `%1`, where the text to type goes. A translation that
+ * leaves `%1` out gets the text after it, following a space; a second `%1` is filled in as text.
+ * @param {string} template Message such as "Type %1 to confirm".
+ * @param {string} expected Text to type.
+ * @returns {[string, string]} The text before and after the text to type.
+ */
+export function typeToConfirmParts(template, expected) {
+  const parts = String(template).split('%1');
+  if (parts.length === 1) return [`${parts[0]} `, ''];
+  return [parts[0], parts.slice(1).join(expected)];
+}
+
+/** @param {unknown} content @returns {boolean} */
+function isEmptyContent(content) {
+  return content == null || content === '';
+}
+
 /**
  * Copies footer-button descriptors without mutating the caller's array or objects, and settles
  * the two booleans the footer renders from.

package/src/components/dropdown/dropdown.css

@@ -3,7 +3,7 @@
   max-block-size: calc(100vh - (2 * var(--zx-space-3)));
   overflow: auto;
   border: 1px solid var(--zx-color-overlay-border);
-  border-radius: var(--zx-radius-md);
+  border-radius: var(--zx-radius-lg);
   background-color: var(--zx-color-overlay-surface);
   background-image: var(--zx-overlay-surface-image);
   background-clip: padding-box;

package/src/components/dropdown/dropdown.js

@@ -1,6 +1,6 @@
 import { Component } from '../../core/component.js';
 import { h, resolveElement } from '../../core/dom.js';
-import { overlayHost } from '../../core/overlay-host.js';
+import { connectedOverlayHost, overlayHost } from '../../core/overlay-host.js';
 import { position } from '../../core/position.js';
 import { uid } from '../../core/util.js';
 
@@ -15,7 +15,7 @@ const HANDLE_ESCAPE_DISMISS = Symbol('zxDropdownEscapeDismiss');
  * @property {boolean} [matchWidth=false] Whether the panel matches the anchor width.
  * @property {'click'|'manual'} [openOn='click'] Trigger behavior.
  * @property {boolean} [closeOnSelect=false] Whether a click within the panel closes it.
- * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns the panel; defaults to the anchor.
+ * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns the panel; defaults to the anchor. Resolved on every open, so an anchor connected after construction still gets its scope.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onclose] Close event listener.
  */
@@ -58,7 +58,9 @@ export class Dropdown extends Component {
     if (!resolved) throw new TypeError('Dropdown anchor could not be resolved');
     super(null, options);
     this.#anchor = resolved;
-    overlayHost(this.options.scope ?? resolved).append(this.el);
+    // An anchor that is not in the document yet has no theme scope to read; the panel then waits
+    // detached and finds its host on the first open, instead of settling on <body>.
+    connectedOverlayHost(this.options.scope ?? resolved)?.append(this.el);
     this.#rememberAnchorAttribute('aria-expanded');
     this.#rememberAnchorAttribute('aria-controls');
     this.#anchor.setAttribute('aria-expanded', 'false');

package/src/components/empty-state/empty-state.css

@@ -11,14 +11,14 @@
 
 .zx-empty-state__icon {
   display: flex;
-  color: var(--zx-color-text-placeholder);
+  color: var(--zx-color-text-subtle);
 }
 
 .zx-empty-state__title {
   margin: 0;
   color: var(--zx-color-text);
   font-size: var(--zx-text-lg);
-  font-weight: 600;
+  font-weight: var(--zx-weight-semibold);
   line-height: 1.4;
 }
 

package/src/components/entity-ref/entity-ref.css

@@ -52,7 +52,7 @@
 
 .zx-entity-ref__title {
   color: var(--zx-color-text);
-  font-weight: 600;
+  font-weight: var(--zx-weight-medium);
   line-height: 1.25;
 }
 

package/src/components/entity-ref/entity-ref.js

@@ -52,7 +52,7 @@ import { isElement } from '../../core/util.js';
  * @property {EntityRefMetadata[]} [metadata=[]] Labelled dense metadata.
  * @property {EntityRefLinkValue} [link=null] Optional native primary link.
  * @property {EntityRefActionEntry[]} [actions=[]] Secondary controls; element actions keep their own behavior.
- * @property {'sm'|'md'|'lg'} [size='md'] Density-independent identity size.
+ * @property {'sm'|'md'|'lg'} [size='md'] Size of the icon and the identity text.
  * @property {boolean} [wrap=false] Whether long identity text may wrap instead of truncating.
  * @property {string} [actionsLabel='Entity actions'] Accessible name for secondary actions.
  * @property {(event: CustomEvent<{id: unknown, entity: Readonly<EntityRefState>, href: string, event: MouseEvent}>) => void} [onactivate]

package/src/components/field/field.css

@@ -1,5 +1,8 @@
+/* Beside a taller field in a multi-column row the field's cell grows, but its label and control
+   stay at the top of it rather than spreading over the extra height. */
 .zx-field {
   display: grid;
+  align-content: start;
   gap: var(--zx-space-1);
   min-inline-size: 0;
 }
@@ -10,15 +13,24 @@
   align-items: start;
 }
 
+/* Beside its control, a label lines up with the control's first line rather than its top edge, so
+   "Status" and "In review" share a baseline — and still sits by the first row of a control that
+   grows taller. */
+.zx-field[data-layout="inline"] .zx-field__label {
+  padding-block-start: max(0px, (var(--zx-control-height) - 1lh) / 2);
+}
+
 .zx-field[data-field-type="hidden"] {
   display: none;
 }
 
+/* Labels are quieter than the values they name: the small size, a medium weight, the muted text
+   colour. The value is what a reader came for. */
 .zx-field__label {
   min-inline-size: 0;
-  color: var(--zx-color-text);
+  color: var(--zx-color-text-muted);
   font-size: var(--zx-text-sm);
-  font-weight: 600;
+  font-weight: var(--zx-weight-medium);
 }
 
 .zx-field__required,
@@ -101,17 +113,24 @@
   border-color: var(--zx-color-danger);
 }
 
-.zx-field__static,
-.zx-field__error-control {
+/* Display content is not an input, so it draws no frame and no fill. It keeps a control's height
+   and centres its first line in it, so it sits level with the fields beside it and with an inline
+   label; in a quiet form it is inset like the quiet values around it. */
+.zx-field__static {
   min-block-size: var(--zx-control-height);
-  padding: var(--zx-space-2) var(--zx-control-pad-x);
-  border: 1px solid var(--zx-color-border);
-  border-radius: var(--zx-control-radius);
-  background: var(--zx-color-bg-surface);
+  padding-block: max(0px, (var(--zx-control-height) - 1lh) / 2);
+  font-size: var(--zx-control-font-size);
+}
+
+[data-zx-fields="quiet"] .zx-field__static {
+  padding-inline: calc(var(--zx-control-pad-x) + 1px);
 }
 
 .zx-field__error-control {
-  border-color: var(--zx-color-danger);
+  min-block-size: var(--zx-control-height);
+  padding: var(--zx-space-2) var(--zx-control-pad-x);
+  border: 1px solid var(--zx-color-danger);
+  border-radius: var(--zx-control-radius);
   background: var(--zx-color-danger-bg);
   color: var(--zx-color-danger);
 }

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.
@@ -28,6 +31,9 @@ import { uid } from '../../core/util.js';
  * @property {() => void} focus Focus the control.
  * @property {(disabled: boolean) => void} setDisabled Set disabled state.
  * @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 */
@@ -45,6 +51,7 @@ export class Field extends Component {
   /** @type {FieldOptions & {msg: Record<string, string>}} */
   static defaults = {
     id: null,
+    name: null,
     type: 'text',
     label: '',
     description: '',
@@ -88,9 +95,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() {
@@ -104,7 +112,10 @@ export class Field extends Component {
     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 +159,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;
@@ -231,11 +247,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 +266,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 +295,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 +416,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,19 +445,26 @@ 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,
@@ -450,7 +489,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,
@@ -474,8 +513,8 @@ function numericAdapter(kind) {
 }
 
 /** @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 +529,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 +541,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 +576,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);

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/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,6 +1,6 @@
 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';
 
 /**
@@ -8,6 +8,9 @@ import { Field } from '../field/field.js';
  * @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 +23,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 +33,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 +53,9 @@ 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.
    * @param {string} id Logical field identifier.
    * @param {FieldOptions|Field|Element|Component} field Field source.
    * @returns {Field}
@@ -64,7 +70,8 @@ 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),
@@ -74,7 +81,14 @@ export class Fieldset extends Component {
       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 +232,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);