@zeyos/zx 4.3.0 → 4.4.0

package/src/components/timebox/timebox.js

@@ -75,7 +75,9 @@ export class Timebox extends Component {
     const content = h('div', {
       class: 'zx-timebox__content',
       role: 'group',
-      ariaLabel: this.options.seconds ? 'Duration in hours, minutes, and seconds' : 'Duration in hours and minutes'
+      ariaLabel: this.options.seconds
+        ? this._message('timebox.durationWithSeconds', 'Duration in hours, minutes, and seconds')
+        : this._message('timebox.duration', 'Duration in hours and minutes')
     });
     this._content = content;
 
@@ -84,7 +86,7 @@ export class Timebox extends Component {
         ref: 'sign',
         class: 'zx-timebox__sign',
         type: 'button',
-        ariaLabel: 'Toggle duration sign',
+        ariaLabel: this._message('timebox.toggleSign', 'Toggle duration sign'),
         ariaPressed: 'false'
       }, '+'));
       this.listen(this.refs.sign, 'click', () => {
@@ -95,12 +97,12 @@ export class Timebox extends Component {
       });
     }
 
-    this._addSegment(content, 'hours', 'Hours', false);
+    this._addSegment(content, 'hours', this._message('timebox.hours', 'Hours'), false);
     content.append(h('span', { class: 'zx-timebox__separator', ariaHidden: 'true' }, ':'));
-    this._addSegment(content, 'minutes', 'Minutes', true);
+    this._addSegment(content, 'minutes', this._message('timebox.minutes', 'Minutes'), true);
     if (this.options.seconds) {
       content.append(h('span', { class: 'zx-timebox__separator', ariaHidden: 'true' }, ':'));
-      this._addSegment(content, 'seconds', 'Seconds', true);
+      this._addSegment(content, 'seconds', this._message('timebox.seconds', 'Seconds'), true);
     }
     root.append(content);
     this.set(this.options.value, this.options.unit, { silent: true });
@@ -237,6 +239,17 @@ export class Timebox extends Component {
   _emitChange() {
     this.emit('change', { value: this.get(this.options.unit) });
   }
+
+  /**
+   * Resolves a message through the host translator, falling back to the built-in English text.
+   * @param {string} key Message key.
+   * @param {string} fallback English default.
+   * @returns {string}
+   */
+  _message(key, fallback) {
+    const message = this.msg(key);
+    return message === key ? fallback : message;
+  }
 }
 
 /** @event Timebox#change @type {CustomEvent<{value: number}>} */

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

@@ -1,5 +1,6 @@
 import { Component } from '../../core/component.js';
 import { h } from '../../core/dom.js';
+import { printf } from '../../core/i18n.js';
 import { uid } from '../../core/util.js';
 
 /**
@@ -49,14 +50,14 @@ export class ValueList extends Component {
     this._list = h('ul', {
       class: 'zx-value-list__list',
       role: 'listbox',
-      ariaLabel: 'Values',
+      ariaLabel: this._message('valueList.values', 'Values'),
       ariaOrientation: 'horizontal'
     });
     this._input = h('input', {
       class: 'zx-value-list__input',
       type: 'text',
       placeholder: String(this.options.placeholder ?? ''),
-      ariaLabel: 'Add value',
+      ariaLabel: this._message('valueList.add', 'Add value'),
       ariaDescribedby: instructionsId
     });
     this._status = h('div', {
@@ -67,7 +68,8 @@ export class ValueList extends Component {
     this._instructions = h('span', {
       class: 'zx-value-list__instructions',
       id: instructionsId
-    }, 'Press Enter to add. Focus a value and press Ctrl plus Left or Right to reorder.');
+    }, this._message('valueList.instructions',
+      'Press Enter to add. Focus a value and press Ctrl plus Left or Right to reorder.'));
     this._ownedNodes.push(this._list, this._input, this._status, this._instructions);
     root.append(this._list, this._input, this._status, this._instructions);
 
@@ -120,13 +122,14 @@ export class ValueList extends Component {
     const normalized = String(value ?? '').trim();
     if (!normalized) return false;
     if (this.options.unique && this._values.includes(normalized)) {
-      this._showError('This value already exists.');
+      this._showError(this._message('valueList.duplicate', 'This value already exists.'));
       return false;
     }
     if (typeof this.options.validate === 'function') {
       const result = this.options.validate(normalized);
       if (result !== true) {
-        this._showError(typeof result === 'string' ? result : 'This value is not valid.');
+        this._showError(typeof result === 'string' ? result
+          : this._message('valueList.invalid', 'This value is not valid.'));
         return false;
       }
     }
@@ -196,7 +199,8 @@ export class ValueList extends Component {
       draggable: Boolean(this.options.sortable) && !this._disabled,
       ariaSelected: 'false',
       ariaDisabled: String(this._disabled),
-      ariaLabel: this.options.deletable ? `${value}. Press Delete to remove.` : value,
+      ariaLabel: this.options.deletable
+        ? this._message('valueList.removable', '%1. Press Delete to remove.', value) : value,
       dataset: { index }
     }, h('span', { class: 'zx-value-list__value' }, value), this.options.deletable ? h('span', {
       class: 'zx-value-list__remove',
@@ -302,6 +306,18 @@ export class ValueList extends Component {
     this._input.setAttribute('aria-invalid', 'true');
   }
 
+  /**
+   * Resolves a message through the host translator, falling back to the built-in English text.
+   * @param {string} key Message key.
+   * @param {string} fallback Built-in text, with `%1`-style placeholders.
+   * @param {...unknown} args Interpolation values.
+   * @returns {string}
+   */
+  _message(key, fallback, ...args) {
+    const message = this.msg(key, ...args);
+    return message === key ? printf(fallback, args) : message;
+  }
+
   /** @returns {void} */
   destroy() {
     for (const node of this._ownedNodes ?? []) node.remove();

package/src/components/view/record-view.css

@@ -17,6 +17,11 @@
   margin-inline-start: auto;
 }
 
+/* Mounted into a host toolbar the view does not own: the host decides where it sits. */
+.zx-record-view__field-controls[data-mounted="external"] {
+  margin-inline-start: 0;
+}
+
 .zx-record-view__field-controls > summary {
   display: inline-flex;
   align-items: center;

package/src/components/view/record-view.js

@@ -1,7 +1,8 @@
 // @ts-check
 import { Component } from '../../core/component.js';
-import { h, restoreTarget, snapshotTarget } from '../../core/dom.js';
+import { h, resolveElement, restoreTarget, snapshotTarget } from '../../core/dom.js';
 import { icon } from '../../core/icons.js';
+import { printf } from '../../core/i18n.js';
 import { sortRows } from '../table/sort.js';
 
 /** @typedef {Record<string, any>} ViewRecord */
@@ -31,6 +32,23 @@ import { sortRows } from '../table/sort.js';
  * @property {ViewSortDirection} dir Sort direction.
  */
 
+/**
+ * Trigger customisation for the shared field chooser. Passing this object in place of `true` keeps
+ * the control and its state model exactly as they are; only its wording and mount point change.
+ * @typedef {Object} ViewFieldControlsConfig
+ * @property {string} [label] Trigger label. Omitted resolves `recordView.fields`, English `Fields`.
+ * @property {Element|string|null} [target=null] Element or selector the disclosure is mounted into
+ * instead of the view's own toolbar. An unresolvable target falls back to the view.
+ */
+
+/**
+ * @typedef {Object} ViewFieldControlsSettings
+ * @property {boolean} enabled Whether a concrete view renders the chooser at all.
+ * @property {boolean} custom Whether the option was given as a `ViewFieldControlsConfig` object.
+ * @property {string|null} label Configured trigger label, or null to resolve the message.
+ * @property {Element|string|null} target Configured mount point, before resolution.
+ */
+
 /**
  * @typedef {Object} RecordViewState
  * @property {1} version State schema version.
@@ -50,7 +68,10 @@ import { sortRows } from '../table/sort.js';
  * @property {unknown[]} [selection=[]] Initially selected record ids.
  * @property {string[]} [fieldOrder=[]] Field ids in preferred order.
  * @property {string[]} [hiddenFields=[]] Initially hidden field ids.
- * @property {boolean} [fieldControls=true] Whether concrete views show the shared field chooser.
+ * @property {boolean|ViewFieldControlsConfig} [fieldControls=true] Whether concrete views show the
+ * shared field chooser. `true` renders it in the view's own toolbar and `false` omits it; a
+ * `ViewFieldControlsConfig` object renders the same control with a translated `label` and, with
+ * `target`, mounts it into a host element such as a list toolbar.
  * @property {string|Node|(() => string|Node)|null} [emptyText=null] Empty-result content.
  * @property {(event: CustomEvent<Record<string, unknown>>) => void} [onrecordclick]
  * @property {(event: CustomEvent<Record<string, unknown>>) => void} [onrecorddblclick]
@@ -117,6 +138,7 @@ export class RecordView extends Component {
     this._recordViewDestroyed = true;
     const root = this.el;
     const snapshot = this._recordViewOriginal;
+    this._removeViewFieldControls();
     super.destroy();
     if (snapshot && root) restoreTarget(root, snapshot);
   }
@@ -139,6 +161,9 @@ export class RecordView extends Component {
     this._viewSelectionAnchor = null;
     this._viewFieldControls = null;
     this._viewFieldList = null;
+    this._viewFieldSettings = normalizeViewFieldControls(this.options.fieldControls);
+    // Resolved once, here, so the mount point cannot drift between render and destroy.
+    this._viewFieldControlsTarget = resolveElement(this._viewFieldSettings.target);
     this._viewInitialized = true;
     if (this._viewSort && this.options.sortMode === 'local') this._sortViewData();
     this._setInitialSelection(this.options.selection);
@@ -467,13 +492,15 @@ export class RecordView extends Component {
   /**
    * Builds the shared show/hide and ordering disclosure for a concrete view toolbar.
    * @protected
-   * @param {string} [label='Fields'] Trigger label.
+   * @param {string|null} [label=null] Explicit trigger label. Omitted resolves the configured
+   * `fieldControls.label` and then the `recordView.fields` message.
    * @returns {HTMLElement} Disclosure element.
    */
-  _createViewFieldControls(label = 'Fields') {
+  _createViewFieldControls(label = null) {
+    const text = label ?? this._viewFieldControlsLabel();
     const list = h('div', { class: 'zx-record-view__field-list' });
     const details = h('details', { class: 'zx-record-view__field-controls' },
-      h('summary', { class: 'zx-button zx-button--sm' }, icon('fields', { size: 13 }), label),
+      h('summary', { class: 'zx-button zx-button--sm' }, icon('fields', { size: 13 }), text),
       list);
     this._viewFieldControls = details;
     this._viewFieldList = list;
@@ -498,6 +525,58 @@ export class RecordView extends Component {
     return details;
   }
 
+  /**
+   * Builds the shared field disclosure and mounts it where `fieldControls` asks for it: the host
+   * element named by `target`, or the view's own toolbar when no target resolves.
+   * @protected
+   * @param {Element} toolbar The view's own toolbar.
+   * @param {string|null} [label=null] Explicit trigger label, for views that own their wording.
+   * @returns {HTMLElement} The mounted disclosure.
+   */
+  _mountViewFieldControls(toolbar, label = null) {
+    const controls = this._createViewFieldControls(label);
+    const target = this._viewFieldControlsTarget;
+    if (target) controls.dataset.mounted = 'external';
+    (target ?? toolbar).append(controls);
+    return controls;
+  }
+
+  /**
+   * Removes the shared field disclosure from wherever it was mounted. An external `target` keeps
+   * every node it had before the view was created.
+   * @protected
+   * @returns {void}
+   */
+  _removeViewFieldControls() {
+    this._viewFieldControls?.remove?.();
+    this._viewFieldControls = null;
+    this._viewFieldList = null;
+    this._viewFieldControlsTarget = null;
+  }
+
+  /**
+   * Resolves the field-chooser trigger label: the configured one, else the translated message.
+   * @protected
+   * @returns {string} Trigger label.
+   */
+  _viewFieldControlsLabel() {
+    const settings = this._viewFieldSettings ?? normalizeViewFieldControls(this.options.fieldControls);
+    return settings.label ?? this._message('recordView.fields', 'Fields');
+  }
+
+  /**
+   * Resolves a message through the host translator, falling back to the built-in English text.
+   * @protected
+   * @param {string} key Message key.
+   * @param {string} fallback Built-in text, with `%1`-style placeholders.
+   * @param {...unknown} args Interpolation values.
+   * @returns {string} Translated or built-in text.
+   */
+  _message(key, fallback, ...args) {
+    const message = this.msg(key, ...args);
+    return message === key ? printf(fallback, args) : message;
+  }
+
   /** Concrete renderers override this hook. @protected @param {string} _reason Refresh reason. @returns {void} */
   _refreshView(_reason) {}
 
@@ -567,14 +646,14 @@ export class RecordView extends Component {
       const up = h('button', {
         class: 'zx-record-view__field-move',
         type: 'button',
-        ariaLabel: `Move ${field.label} up`,
+        ariaLabel: this._message('recordView.moveFieldUp', 'Move %1 up', field.label),
         disabled: index === 0,
         dataset: { viewFieldAction: 'up', fieldId: field.id }
       }, icon('chevron-up', { size: 11 }));
       const down = h('button', {
         class: 'zx-record-view__field-move',
         type: 'button',
-        ariaLabel: `Move ${field.label} down`,
+        ariaLabel: this._message('recordView.moveFieldDown', 'Move %1 down', field.label),
         disabled: index === fields.length - 1,
         dataset: { viewFieldAction: 'down', fieldId: field.id }
       }, icon('chevron-down', { size: 11 }));
@@ -593,6 +672,20 @@ export class RecordView extends Component {
   }
 }
 
+/**
+ * Reads the `fieldControls` option in its three shapes. `true` and `false` keep their exact
+ * meaning; an object additionally carries the trigger label and the host element to mount into.
+ * @param {boolean|ViewFieldControlsConfig|null|undefined} value Raw option value.
+ * @returns {ViewFieldControlsSettings} Normalized settings.
+ */
+export function normalizeViewFieldControls(value) {
+  if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+    const label = value.label == null ? null : String(value.label);
+    return { enabled: true, custom: true, label, target: value.target ?? null };
+  }
+  return { enabled: Boolean(value), custom: false, label: null, target: null };
+}
+
 /**
  * Validates and clones field descriptors.
  * @param {ViewField[]} fields Fields.

package/src/core/component.js

@@ -157,21 +157,26 @@ export class Component extends EventTarget {
    * Dispatches a component event and a bubbling, composed `zx-*` DOM event.
    * @param {string} type Lowercase event name.
    * @param {Record<string, unknown>} [detail={}] Single event detail object.
+   * @param {{honorDomCancellation?:boolean}} [options={}] Mirrored DOM-event behavior. Components
+   * with a cancelable mutation boundary may opt into treating `preventDefault()` on the bubbling
+   * `zx-*` event exactly like cancellation of the component event.
    * @returns {Event & {detail: Record<string, unknown>}}
    * @fires Component#event
    */
-  emit(type, detail = {}) {
+  emit(type, detail = {}, options = {}) {
     if (detail === null || typeof detail !== 'object' || Array.isArray(detail)) {
       throw new TypeError('Event detail must be an object');
     }
     const componentEvent = createCustomEvent(type, detail, { cancelable: true });
     this.dispatchEvent(componentEvent);
     if (this.el) {
-      this.el.dispatchEvent(createCustomEvent(`zx-${type}`, detail, {
+      const domEvent = createCustomEvent(`zx-${type}`, detail, {
         bubbles: true,
         composed: true,
         cancelable: true
-      }));
+      });
+      this.el.dispatchEvent(domEvent);
+      if (options.honorDomCancellation && domEvent.defaultPrevented) componentEvent.preventDefault();
     }
     return componentEvent;
   }

package/src/core/icons.js

@@ -22,6 +22,9 @@ const SVG_NS = 'http://www.w3.org/2000/svg';
  * @property {string} [style] Font Awesome style for this icon only (`'solid'`, `'duotone'`, …).
  * @property {string} [family] Font Awesome family for this icon only (`'classic'`, `'sharp'`, …).
  * @property {boolean} [fixedWidth] Adds Font Awesome's `fa-fw` for column-aligned glyphs.
+ * @property {boolean} [strict=false] Throws `RangeError` on a name the bundled glyph set does not
+ *   carry, instead of returning the placeholder. For call sites that can afford to fail — a test,
+ *   a build-time check — rather than a screen rendering server data.
  */
 
 /**
@@ -34,6 +37,8 @@ const SVG_NS = 'http://www.w3.org/2000/svg';
  * @type {Readonly<Record<string, [string, string]>>}
  */
 export const icons = Object.freeze({
+  'arrow-up-wide-short': ['0 0 576 512', 'M151.6 42.4C145.5 35.8 137 32 128 32s-17.5 3.8-23.6 10.4l-88 96c-11.9 13-11.1 33.3 2 45.2s33.3 11.1 45.2-2L96 146.3 96 448c0 17.7 14.3 32 32 32s32-14.3 32-32l0-301.7 32.4 35.4c11.9 13 32.2 13.9 45.2 2s13.9-32.2 2-45.2l-88-96zM320 480l32 0c17.7 0 32-14.3 32-32s-14.3-32-32-32l-32 0c-17.7 0-32 14.3-32 32s14.3 32 32 32zm0-128l96 0c17.7 0 32-14.3 32-32s-14.3-32-32-32l-96 0c-17.7 0-32 14.3-32 32s14.3 32 32 32zm0-128l160 0c17.7 0 32-14.3 32-32s-14.3-32-32-32l-160 0c-17.7 0-32 14.3-32 32s14.3 32 32 32zm0-128l224 0c17.7 0 32-14.3 32-32s-14.3-32-32-32L320 32c-17.7 0-32 14.3-32 32s14.3 32 32 32z'],
+  'arrow-down-wide-short': ['0 0 576 512', 'M151.6 469.6C145.5 476.2 137 480 128 480s-17.5-3.8-23.6-10.4l-88-96c-11.9-13-11.1-33.3 2-45.2s33.3-11.1 45.2 2L96 365.7 96 64c0-17.7 14.3-32 32-32s32 14.3 32 32l0 301.7 32.4-35.4c11.9-13 32.2-13.9 45.2-2s13.9 32.2 2 45.2l-88 96zM320 480c-17.7 0-32-14.3-32-32s14.3-32 32-32l32 0c17.7 0 32 14.3 32 32s-14.3 32-32 32l-32 0zm0-128c-17.7 0-32-14.3-32-32s14.3-32 32-32l96 0c17.7 0 32 14.3 32 32s-14.3 32-32 32l-96 0zm0-128c-17.7 0-32-14.3-32-32s14.3-32 32-32l160 0c17.7 0 32 14.3 32 32s-14.3 32-32 32l-160 0zm0-128c-17.7 0-32-14.3-32-32s14.3-32 32-32l224 0c17.7 0 32 14.3 32 32s-14.3 32-32 32L320 96z'],
   'chevron-down': ['0 0 512 512', 'M233.4 406.6c12.5 12.5 32.8 12.5 45.3 0l192-192c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0L256 338.7 86.6 169.4c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3l192 192z'],
   'chevron-up': ['0 0 512 512', 'M233.4 105.4c12.5-12.5 32.8-12.5 45.3 0l192 192c12.5 12.5 12.5 32.8 0 45.3s-32.8 12.5-45.3 0L256 173.3 86.6 342.6c-12.5 12.5-32.8 12.5-45.3 0s-12.5-32.8 0-45.3l192-192z'],
   'chevron-left': ['0 0 320 512', 'M9.4 233.4c-12.5 12.5-12.5 32.8 0 45.3l192 192c12.5 12.5 32.8 12.5 45.3 0s12.5-32.8 0-45.3L109.3 256 246.6 118.6c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0l-192 192z'],
@@ -188,9 +193,17 @@ export function iconNames() {
  * its renderer itself — `'fa:user'`, `'duotone:user'`, `'kit:zeyos-notes'`, `'builtin:check'`, or
  * a literal Font Awesome class list such as `'fa-solid fa-user'`.
  *
+ * **A name this cannot resolve never throws.** Icon names routinely arrive from a server, and one
+ * unconfigured name must not take down the screen it appears on. An inline glyph the bundled set
+ * does not carry renders as the placeholder described in `missingIcon()` and is reported once per
+ * distinct name through `console.warn`; pass `{ strict: true }` to get a `RangeError` instead.
+ * Only the inline-SVG path can fail this way: Font Awesome resolves names in the browser at render
+ * time, so a name under a loaded kit or stylesheet is never "unknown" here and never warns.
+ *
  * @param {string} name Icon name or spec.
  * @param {IconOptions} [options={}] Display and accessibility options.
  * @returns {SVGSVGElement|HTMLElement} An `<svg>` for inline glyphs, an `<i>` for Font Awesome.
+ * @throws {RangeError} With `{ strict: true }` only, when the bundled set has no such glyph.
  */
 export function icon(name, options = {}) {
   const spec = parseIconSpec(name);
@@ -218,18 +231,37 @@ export function icon(name, options = {}) {
 }
 
 /**
- * Renders one of the bundled inline SVG glyphs.
+ * Renders one of the bundled inline SVG glyphs, or the placeholder when there is no such glyph.
  * @param {string} name Resolved glyph name.
  * @param {IconOptions} options Display and accessibility options.
  * @returns {SVGSVGElement}
+ * @throws {RangeError} With `options.strict`, when no glyph carries that name.
  */
 function builtinIcon(name, options) {
   const entry = extraGlyphs[name] ?? icons[name];
-  if (!entry) throw new RangeError(`Unknown icon: ${name}`);
+  if (!entry) {
+    if (options.strict) throw new RangeError(`Unknown icon: ${name}`);
+    warnMissingIcon(name);
+    return missingIcon(name, options);
+  }
   const [viewBox, pathData] = entry;
+  const svg = iconSvg(viewBox, options);
+  const path = document.createElementNS(SVG_NS, 'path');
+  path.setAttribute('d', pathData);
+  svg.append(path);
+  return svg;
+}
+
+/**
+ * Builds the `<svg>` root every inline glyph shares, so the placeholder is the same element in
+ * the same box as the icon it stands in for.
+ * @param {string} viewBox The glyph's view box.
+ * @param {IconOptions} options Display and accessibility options.
+ * @returns {SVGSVGElement}
+ */
+function iconSvg(viewBox, options) {
   const { size = 16 } = options;
   const svg = document.createElementNS(SVG_NS, 'svg');
-  const path = document.createElementNS(SVG_NS, 'path');
   svg.setAttribute('class', classList('zx-icon', options.class));
   svg.setAttribute('viewBox', viewBox);
   svg.setAttribute('width', String(size));
@@ -237,11 +269,48 @@ function builtinIcon(name, options) {
   svg.setAttribute('fill', 'currentColor');
   svg.setAttribute('focusable', 'false');
   applyLabel(svg, options.label ?? null);
-  path.setAttribute('d', pathData);
-  svg.append(path);
   return svg;
 }
 
+/** View box the placeholder reserves — the square most Font Awesome glyphs are drawn in. */
+const PLACEHOLDER_VIEW_BOX = '0 0 512 512';
+
+/**
+ * The element an unresolvable name renders as: the ordinary `zx-icon` root at the requested size,
+ * carrying no path.
+ *
+ * Empty rather than a fallback glyph on purpose. The box is what layout needs — a row of icons
+ * keeps its alignment and nothing reflows — while a question mark or an outlined square would
+ * read as an icon somebody chose, and would be the wrong one wherever colour or shape carries
+ * meaning. The gap is addressed to the developer instead, through the `console.warn` and through
+ * `data-zx-icon-missing`, which names it in devtools and lets a test or a page audit find every
+ * one of them with a single selector.
+ * @param {string} name Resolved glyph name that could not be found.
+ * @param {IconOptions} options Display and accessibility options.
+ * @returns {SVGSVGElement}
+ */
+function missingIcon(name, options) {
+  const svg = iconSvg(PLACEHOLDER_VIEW_BOX, options);
+  svg.setAttribute('data-zx-icon-missing', name);
+  return svg;
+}
+
+/** @type {Set<string>} Names already reported, so each gap is warned about exactly once. */
+const warnedMissing = new Set();
+
+/**
+ * Reports a missing glyph once per distinct name. A list of four hundred rows built from the same
+ * unconfigured name is one gap to fix, so it is one line in the console, not four hundred.
+ * @param {string} name Resolved glyph name that could not be found.
+ * @returns {void}
+ */
+function warnMissingIcon(name) {
+  if (warnedMissing.has(name)) return;
+  warnedMissing.add(name);
+  console.warn(`[zx.icon] Unknown icon "${name}" — rendered an empty placeholder. `
+    + 'Add it with registerIcons(), or render Font Awesome with useFontAwesome().');
+}
+
 /**
  * Renders a Font Awesome icon element. The glyph itself comes from the kit or stylesheet the
  * application loaded; Zx only writes the classes.

package/src/index.js

@@ -4,6 +4,7 @@
  */
 
 import { registerChecklistFieldAdapter } from './components/checklist/field-adapter.js';
+import { registerCodeEditorFieldAdapter } from './components/code-editor/field-adapter.js';
 import { registerDatePickerFieldAdapters } from './components/date-picker/field-adapter.js';
 import { registerDateRangeFieldAdapter } from './components/date-picker/range-field-adapter.js';
 import { registerDateboxFieldAdapters } from './components/datebox/field-adapter.js';
@@ -25,6 +26,7 @@ import { registerValueListFieldAdapter } from './components/value-list/field-ada
 export function registerFieldAdapters() {
   registerSelectFieldAdapter();
   registerChecklistFieldAdapter();
+  registerCodeEditorFieldAdapter();
   registerDateboxFieldAdapters();
   registerDatePickerFieldAdapters();
   registerDateRangeFieldAdapter();
@@ -85,10 +87,12 @@ export { stack, grid, aspect } from './components/layout/layout.js';
 export { truncate, isTruncated } from './components/truncate/truncate.js';
 export { copyButton } from './components/copy/copy-button.js';
 export { CopyInput } from './components/copy/copy-input.js';
+export { CodeEditor, indentSelection, editorPosition } from './components/code-editor/code-editor.js';
 export { Toolbar } from './components/toolbar/toolbar.js';
 export { Toggle } from './components/toggle/toggle.js';
 export { Groupbox } from './components/groupbox/groupbox.js';
 export { Card } from './components/card/card.js';
+export { StatTile, statTile } from './components/stat-tile/stat-tile.js';
 export { Aurora } from './components/aurora/aurora.js';
 export { Panel } from './components/panel/panel.js';
 export { MasterPanel } from './components/master-panel/master-panel.js';
@@ -105,6 +109,18 @@ export { Search } from './components/search/search.js';
 export { AppIcon, appIcon } from './components/app-icon/app-icon.js';
 export { Launcher, rankLauncherItems } from './components/launcher/launcher.js';
 export { Avatar, avatarInitials } from './components/avatar/avatar.js';
+export {
+  EntityRef, normalizeEntityRef, normalizeEntityRefLink,
+  normalizeEntityRefMetadata, normalizeEntityRefActions
+} from './components/entity-ref/entity-ref.js';
+export { FileItem, normalizeFileItem } from './components/file-item/file-item.js';
+export { FileList, normalizeFileListItems } from './components/file-list/file-list.js';
+export {
+  ActivityItem, resolveActivityActions, normalizeActivityAction, normalizeActivityTimestamp
+} from './components/activity-item/activity-item.js';
+export {
+  ActivityList, groupActivityItems, normalizeActivityItems
+} from './components/activity-list/activity-list.js';
 export { AccountMenu } from './components/account-menu/account-menu.js';
 export { normalizeAppItems } from './internal/app-rail.js';
 export { AppSidebar } from './components/app-sidebar/app-sidebar.js';
@@ -136,9 +152,9 @@ export {
 export { Timebox, splitTime, joinTime } from './components/timebox/timebox.js';
 export { Calendar } from './components/calendar/calendar.js';
 export {
-  CALENDAR_VIEWS, addCalendarDays, calendarDayDifference, calendarDayKey,
-  calendarEventIntersects, calendarEventSpansDays, calendarRange, cloneCalendarEvent,
-  layoutCalendarSpans, layoutTimedCalendarEvents, normalizeCalendarEvents,
+  CALENDAR_VIEWS, addCalendarDays, addCalendarMonths, calendarDayDifference, calendarDayKey,
+  calendarEventIntersects, calendarEventSpansDays, calendarPageDate, calendarRange,
+  cloneCalendarEvent, layoutCalendarSpans, layoutTimedCalendarEvents, normalizeCalendarEvents,
   shiftCalendarEvent, startOfCalendarDay, startOfCalendarWeek
 } from './components/calendar/calendar-model.js';
 export {
@@ -149,6 +165,15 @@ export { Table, reorderTableRows } from './components/table/table.js';
 export { TableView } from './components/table-view/table-view.js';
 export { CardView } from './components/card-view/card-view.js';
 export { KanbanView } from './components/kanban-view/kanban-view.js';
+export {
+  absoluteKanbanIndex, allowsKanbanTransition, createKanbanHistory, evaluateKanbanMove,
+  kanbanSearchTerms, locateKanbanRecord, matchesKanbanSearch, normalizeKanbanRules,
+  reorderKanbanRecords, resolveKanbanRules
+} from './components/kanban-view/kanban-policy.js';
+export {
+  createKanbanAvatars, createKanbanCardHead, createKanbanIndicator, createKanbanProgress,
+  kanbanAvatarLimit, resolveKanbanAssignees, resolveKanbanIndicator, resolveKanbanProgress
+} from './components/kanban-view/kanban-card.js';
 export { Grid, billingColumns, isBillingLine } from './components/grid/grid.js';
 export {
   Chart, ChartJsAdapter, chartSummaryTable, cloneChartValue, isEmptyChartData
@@ -156,6 +181,11 @@ export {
 export { TreeView } from './components/tree/tree.js';
 export { Finder } from './components/finder/finder.js';
 export { DataFilter } from './components/data-filter/data-filter.js';
+export {
+  FilterPanel, isActiveValue, pruneValue, serializeFilterValue
+} from './components/filter-panel/filter-panel.js';
+export { SortControl } from './components/sort-control/sort-control.js';
+export { ListToolbar } from './components/list-toolbar/list-toolbar.js';
 export { Filter } from './components/filter/filter.js';
 export {
   filterOperators, emptyFilterAst, filterCondition, filterGroup,

package/src/internal/app-rail.js

@@ -1,4 +1,5 @@
 import { Component } from '../core/component.js';
+import { printf } from '../core/i18n.js';
 import { h, safeHref } from '../core/dom.js';
 import { icon } from '../core/icons.js';
 import { Dropdown } from '../components/dropdown/dropdown.js';
@@ -292,8 +293,12 @@ export class AppRailPresenter extends Component {
     });
     const actualPanel = dropdown.getPanel();
     actualPanel.classList.add('zx-app-rail__popover');
+    // The panel is portaled out of the rail, so its stylesheet cannot ask which edge the rail
+    // occupies. Presentation only: it carries the active marker to the edge facing the screen
+    // on a right-hand rail, exactly as the expanded tree does.
+    actualPanel.dataset.side = this.el.dataset.side;
     actualPanel.setAttribute('role', 'region');
-    actualPanel.setAttribute('aria-label', `${item.label} sub-navigation`);
+    actualPanel.setAttribute('aria-label', this._message('appRail.subNavigation', '%1 sub-navigation', item.label));
     const flyout = { key, parentKey, item, trigger, panel: actualPanel, dropdown };
     this._flyouts.set(key, flyout);
     dropdown.on('open', () => {
@@ -573,6 +578,19 @@ export class AppRailPresenter extends Component {
     this._interaction = null;
     this._flyouts = new Map();
   }
+  /**
+   * Resolves one message through `msg()`, which falls back to the host translator. Copied from
+   * `Pagination` rather than invented: the rail's flyout label was the last user-visible string
+   * in the navigation stack with no way to change it.
+   * @param {string} key Message key.
+   * @param {string} fallback English default.
+   * @param {...unknown} args Interpolation arguments.
+   * @returns {string}
+   */
+  _message(key, fallback, ...args) {
+    const message = this.msg(key, ...args);
+    return message === key ? printf(fallback, args) : message;
+  }
 }
 
 /** Owns listeners attached to one dynamic rail render so `setItems()` can release them immediately. */