@zeyos/zx 4.3.4 → 5.0.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.
@@ -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);

package/src/components/file-item/file-item.css

@@ -0,0 +1,88 @@
+.zx-file-item {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  gap: var(--zx-space-2) var(--zx-space-3);
+  align-items: center;
+  min-inline-size: 0;
+}
+
+.zx-file-item__entity {
+  min-inline-size: 0;
+}
+
+.zx-file-item__status {
+  justify-self: end;
+}
+
+.zx-file-item__status[hidden],
+.zx-file-item__progress[hidden] {
+  display: none;
+}
+
+.zx-file-item__progress {
+  display: grid;
+  grid-column: 1 / -1;
+  grid-template-columns: minmax(0, 1fr) auto;
+  gap: var(--zx-space-2);
+  align-items: center;
+  padding-inline-start: calc(var(--zx-control-height) + var(--zx-space-2));
+}
+
+.zx-file-item__progress-head {
+  grid-column: 2;
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-sm);
+}
+
+.zx-file-item__progress-track {
+  grid-column: 1 / -1;
+  block-size: 4px;
+  overflow: hidden;
+  border-radius: var(--zx-radius-pill);
+  background: var(--zx-color-bg-muted);
+}
+
+.zx-file-item__progress-fill {
+  inline-size: var(--zx-file-progress, 0%);
+  block-size: 100%;
+  border-radius: inherit;
+  background: var(--zx-color-accent);
+}
+
+.zx-file-item[data-status="success"] .zx-file-item__progress-fill {
+  background: var(--zx-color-success);
+}
+
+.zx-file-item[data-status="error"] .zx-file-item__progress-fill {
+  background: var(--zx-color-danger);
+}
+
+.zx-file-item__progress[data-indeterminate] .zx-file-item__progress-fill {
+  inline-size: 35%;
+  transform: translateX(-110%);
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .zx-file-item__progress-fill {
+    transition: inline-size var(--zx-dur-fast) var(--zx-ease);
+  }
+
+  .zx-file-item__progress[data-indeterminate] .zx-file-item__progress-fill {
+    animation: zx-file-progress-slide 1200ms var(--zx-ease) infinite;
+  }
+}
+
+@keyframes zx-file-progress-slide {
+  to { transform: translateX(320%); }
+}
+
+@media (max-width: 36rem) {
+  .zx-file-item {
+    grid-template-columns: minmax(0, 1fr);
+  }
+
+  .zx-file-item__status {
+    justify-self: start;
+    padding-inline-start: calc(var(--zx-control-height) + var(--zx-space-2));
+  }
+}