@zeyos/zx 4.4.0 → 5.2.0

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

@@ -161,6 +161,11 @@ export class RecordView extends Component {
     this._viewSelectionAnchor = null;
     this._viewFieldControls = null;
     this._viewFieldList = null;
+    this._viewFieldStatus = null;
+    this._viewFieldHome = null;
+    this._viewNativeMounted = null;
+    /** @type {{id: string, action: 'toggle'|'up'|'down'}|null} */
+    this._viewFieldFocus = 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);
@@ -286,6 +291,57 @@ export class RecordView extends Component {
     return [...this._viewFieldOrder];
   }
 
+  /**
+   * Returns the element that lets a reader show, hide, and reorder this view's fields: the shared
+   * field chooser, or — for a `TableView` with `fieldControls: true` — the column chooser of its
+   * composed `Table`. Null when the view renders none (`fieldControls: false`).
+   *
+   * The element stays owned by the view: move it with {@link RecordView#mountFieldControls}
+   * rather than appending it elsewhere yourself, so `destroy()` can still find and remove it.
+   * @returns {HTMLElement|null}
+   */
+  getFieldControls() {
+    if (this._viewFieldControls) return this._viewFieldControls;
+    return this._nativeFieldControls();
+  }
+
+  /**
+   * Moves the view's field chooser into a host element — a list toolbar, a pane header — or, with
+   * `null`, back to where the view first rendered it. It keeps driving this view wherever it
+   * sits, and `destroy()` removes it from the host. `ListToolbar.bind()` calls this for every
+   * record view, which is how its field chooser ends up in the bar.
+   * @param {Element|string|null} target Host element or selector; null returns the chooser home.
+   * @returns {HTMLElement|null} The chooser, or null when the view renders none or the target
+   * does not resolve.
+   */
+  mountFieldControls(target) {
+    const controls = this.getFieldControls();
+    if (!controls) return null;
+    if (target === null || target === undefined) {
+      const home = this._viewFieldHome;
+      if (!home) return controls;
+      this._viewFieldHome = null;
+      if (controls === this._viewNativeMounted) this._viewNativeMounted = null;
+      if (home.parent) home.parent.insertBefore(controls, home.next?.parentNode === home.parent ? home.next : null);
+      else controls.remove();
+      if (home.mounted === undefined) delete controls.dataset.mounted;
+      else controls.dataset.mounted = home.mounted;
+      return controls;
+    }
+    const host = resolveElement(target);
+    if (!host) return null;
+    if (controls.parentNode === host) return controls;
+    if (!this._viewFieldHome) {
+      this._viewFieldHome = {
+        parent: controls.parentNode, next: controls.nextSibling, mounted: controls.dataset.mounted
+      };
+    }
+    if (controls !== this._viewFieldControls) this._viewNativeMounted = controls;
+    controls.dataset.mounted = 'external';
+    host.append(controls);
+    return controls;
+  }
+
   /**
    * Shows or hides one field. The final visible field cannot be hidden.
    * @param {string} id Field id.
@@ -347,7 +403,7 @@ export class RecordView extends Component {
     if (arraysEqual(next, this._viewFieldOrder)) return this;
     this._viewFieldOrder = next;
     this._refreshView('fields');
-    this._renderViewFieldControls();
+    this._renderViewFieldControls(this._viewFieldFocus ?? null);
     if (!options.silent) {
       this.emit('fieldorderchange', { order: this.getFieldOrder() });
       this._emitViewState('fieldorder');
@@ -499,12 +555,30 @@ export class RecordView extends Component {
   _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 }), text),
-      list);
+    // Present from the start and only ever re-worded: a live region inserted together with its
+    // text is frequently missed. Clipped inline because it has no visual role at all.
+    const status = h('div', {
+      class: 'zx-record-view__field-status', role: 'status', ariaLive: 'polite',
+      style: {
+        position: 'absolute', inlineSize: '1px', blockSize: '1px', overflow: 'hidden',
+        clipPath: 'inset(50%)', whiteSpace: 'nowrap'
+      }
+    });
+    const summary = h('summary', { class: 'zx-btn', dataset: { size: 'sm', kind: 'ghost' } }, icon('fields'), text);
+    const details = /** @type {HTMLDetailsElement} */ (h('details', { class: 'zx-record-view__field-controls' }, summary, list, status));
     this._viewFieldControls = details;
     this._viewFieldList = list;
+    this._viewFieldStatus = status;
     this._renderViewFieldControls();
+    this.listen(details, 'keydown', (event) => {
+      const key = /** @type {KeyboardEvent} */ (event);
+      if (key.key !== 'Escape' || !details.open) return;
+      // Handled here so an enclosing sheet or dialog does not close along with the disclosure.
+      key.preventDefault();
+      key.stopPropagation();
+      details.open = false;
+      summary.focus();
+    });
     this.listen(list, 'change', (event) => {
       const input = /** @type {HTMLInputElement|null} */ (event.target);
       if (input?.classList.contains('zx-record-view__field-toggle')) {
@@ -516,11 +590,7 @@ export class RecordView extends Component {
       if (!button) return;
       const id = /** @type {HTMLElement} */ (button).dataset.fieldId;
       const action = /** @type {HTMLElement} */ (button).dataset.viewFieldAction;
-      const index = this._viewFieldOrder.indexOf(String(id));
-      if (action === 'up' && index > 0) this.moveField(String(id), this._viewFieldOrder[index - 1], 'before');
-      if (action === 'down' && index >= 0 && index < this._viewFieldOrder.length - 1) {
-        this.moveField(String(id), this._viewFieldOrder[index + 1], 'after');
-      }
+      this._moveViewFieldFromChooser(String(id), action === 'up' ? -1 : 1);
     });
     return details;
   }
@@ -549,11 +619,68 @@ export class RecordView extends Component {
    */
   _removeViewFieldControls() {
     this._viewFieldControls?.remove?.();
+    // A native chooser moved out by mountFieldControls() would outlive its owner in the host.
+    if (this._viewNativeMounted && !this.el?.contains(this._viewNativeMounted)) {
+      this._viewNativeMounted.remove();
+    }
+    this._viewNativeMounted = null;
+    this._viewFieldHome = null;
     this._viewFieldControls = null;
     this._viewFieldList = null;
+    this._viewFieldStatus = null;
     this._viewFieldControlsTarget = null;
   }
 
+  /**
+   * A field chooser the concrete view renders natively instead of the shared one. The base class
+   * recognises a composed `Table` exposed through `getTable()` — `TableView` with
+   * `fieldControls: true` keeps Table's own column chooser — and any other subclass may override
+   * this to publish its own.
+   * @protected
+   * @returns {HTMLElement|null}
+   */
+  _nativeFieldControls() {
+    if (!this._viewFieldSettings?.enabled) return null;
+    const self = /** @type {{getTable?: () => unknown}} */ (/** @type {unknown} */ (this));
+    const table = typeof self.getTable === 'function' ? /** @type {{el?: Element|null}|null} */ (self.getTable()) : null;
+    const root = table?.el;
+    if (!root || typeof root.querySelector !== 'function') return null;
+    const own = /** @type {HTMLElement|null} */ (root.querySelector('.zx-table__column-controls'));
+    return own ?? this._viewNativeMounted;
+  }
+
+  /**
+   * Moves a field one place through the chooser's buttons, keeps focus on that field's control
+   * across the re-render, and announces where it landed.
+   * @private
+   * @param {string} id Field id.
+   * @param {-1|1} delta Direction.
+   * @returns {void}
+   */
+  _moveViewFieldFromChooser(id, delta) {
+    const order = this._viewFieldOrder;
+    const index = order.indexOf(id);
+    if (index < 0) return;
+    const neighbour = order[index + delta];
+    const action = /** @type {'up'|'down'} */ (delta < 0 ? 'up' : 'down');
+    if (neighbour === undefined) {
+      this._renderViewFieldControls({ id, action });
+      return;
+    }
+    this._viewFieldFocus = { id, action };
+    try {
+      this.moveField(id, neighbour, delta < 0 ? 'before' : 'after');
+    } finally {
+      this._viewFieldFocus = null;
+    }
+    const field = this._viewFields.find((candidate) => candidate.id === id);
+    const position = this._viewFieldOrder.indexOf(id) + 1;
+    if (this._viewFieldStatus && field) {
+      this._viewFieldStatus.textContent = this._message('recordView.fieldMoved',
+        '%1 moved to position %2 of %3', field.label, position, this._viewFieldOrder.length);
+    }
+  }
+
   /**
    * Resolves the field-chooser trigger label: the configured one, else the translated message.
    * @protected
@@ -629,8 +756,15 @@ export class RecordView extends Component {
     this.emit('statechange', { state: this.getViewState(), reason });
   }
 
-  /** @private @param {string|null} [focusId=null] @returns {void} */
-  _renderViewFieldControls(focusId = null) {
+  /**
+   * Re-renders the chooser list. A focus request names the field and the control that should
+   * hold focus afterwards — a bare id means its checkbox — and falls back to the field's other
+   * enabled control when the requested one became disabled (a move button at either end).
+   * @private
+   * @param {string|{id:string,action:'toggle'|'up'|'down'}|null} [focus=null] Control to focus.
+   * @returns {void}
+   */
+  _renderViewFieldControls(focus = null) {
     if (!this._viewFieldList) return;
     const fields = this.getFields();
     const visible = fields.filter((field) => !this._viewHidden.has(field.id));
@@ -641,7 +775,8 @@ export class RecordView extends Component {
         type: 'checkbox',
         value: field.id,
         checked: !this._viewHidden.has(field.id),
-        disabled: !this._viewHidden.has(field.id) && visible.length === 1
+        disabled: !this._viewHidden.has(field.id) && visible.length === 1,
+        dataset: { viewFieldAction: 'toggle', fieldId: field.id }
       });
       const up = h('button', {
         class: 'zx-record-view__field-move',
@@ -662,14 +797,39 @@ export class RecordView extends Component {
         h('span', { class: 'zx-record-view__field-order' }, up, down));
     });
     this._viewFieldList.replaceChildren(...controls);
-    if (focusId != null) {
-      const match = [...this._viewFieldList.querySelectorAll('.zx-record-view__field-toggle')]
-        .find((control) => /** @type {HTMLInputElement} */ (control).value === focusId);
-      queueMicrotask(() => {
-        if (match?.isConnected) /** @type {HTMLElement} */ (match).focus();
-      });
+    if (focus == null) return;
+    const request = typeof focus === 'string' ? { id: focus, action: 'toggle' } : focus;
+    const match = chooserFocusTarget(controls, request);
+    if (!match) return;
+    // Synchronously, so focus never passes through <body> between the removal and the restore.
+    match.focus();
+    queueMicrotask(() => {
+      if (match.isConnected && match.ownerDocument?.activeElement !== match) match.focus();
+    });
+  }
+}
+
+/**
+ * Picks the chooser control that should hold focus after a re-render: the requested control of
+ * the field, else that field's other enabled move button, else any enabled control of the field.
+ * @param {HTMLElement[]} options Rendered `.zx-record-view__field-option` rows.
+ * @param {{id:string,action:string}} request Field id and control kind.
+ * @returns {HTMLElement|null}
+ */
+function chooserFocusTarget(options, request) {
+  /** @type {HTMLElement[]} */
+  const controls = [];
+  for (const option of options) {
+    for (const control of option.querySelectorAll?.('[data-view-field-action]') ?? []) {
+      if (/** @type {HTMLElement} */ (control).dataset.fieldId === request.id) controls.push(/** @type {HTMLElement} */ (control));
     }
   }
+  const enabled = (control) => !(/** @type {HTMLButtonElement} */ (control).disabled);
+  const exact = controls.find((control) => control.dataset.viewFieldAction === request.action);
+  if (exact && enabled(exact)) return exact;
+  const move = controls.find((control) => control.dataset.viewFieldAction !== 'toggle' && enabled(control));
+  if (request.action !== 'toggle' && move) return move;
+  return controls.find(enabled) ?? null;
 }
 
 /**

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

@@ -0,0 +1,285 @@
+/*
+ * The content of a "View settings" panel: the shown fields in order, the hidden ones to bring
+ * back, grouping, and the board's axes. It fills whatever the host gives it — a sheet body, a
+ * dropdown, a settings page — and draws no frame of its own.
+ */
+.zx-view-settings {
+  /* A size container, so the board settings stack when the panel is narrow rather than the window.
+     Size containment ignores the contents' width, so the width is declared: the host's, with a
+     floor for a host such as a dropdown that sizes itself to its contents. */
+  container-type: inline-size;
+  inline-size: 100%;
+  min-inline-size: 15rem;
+  display: grid;
+  gap: var(--zx-space-5);
+  color: var(--zx-color-text);
+  font-size: var(--zx-control-font-size);
+}
+
+.zx-view-settings__section {
+  display: grid;
+  gap: var(--zx-space-2);
+  min-inline-size: 0;
+}
+
+.zx-view-settings__heading {
+  margin: 0;
+  color: var(--zx-color-text);
+  font-size: var(--zx-text-md);
+  font-weight: var(--zx-weight-semibold);
+  line-height: 1.3;
+}
+
+.zx-view-settings__subheading {
+  margin: var(--zx-space-1) 0 0;
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-sm);
+  font-weight: var(--zx-weight-medium);
+  line-height: 1.3;
+}
+
+.zx-view-settings__search-slot:empty {
+  display: none;
+}
+
+.zx-view-settings__search {
+  inline-size: 100%;
+}
+
+/* The shown list and its insertion line share a positioned frame; the line is not a list item. */
+.zx-view-settings__frame {
+  position: relative;
+}
+
+.zx-view-settings__list,
+.zx-view-settings__hidden {
+  display: grid;
+  gap: calc(var(--zx-space-1) / 2);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+/* A long hidden list scrolls on its own, so the shown fields above never leave the screen. */
+.zx-view-settings__hidden {
+  max-block-size: calc(var(--zx-control-height) * 8);
+  overflow-y: auto;
+  overscroll-behavior: contain;
+}
+
+.zx-view-settings__hidden[hidden] {
+  display: none;
+}
+
+/*
+ * One row: handle, type glyph, label, action. The type glyph follows the label in the source, so
+ * a screen reader hears "Owner, Text", and is placed before it here, where the eye expects it.
+ */
+.zx-view-settings__row {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: var(--zx-space-2);
+  min-block-size: var(--zx-control-height);
+  padding-inline: var(--zx-space-1);
+  border-radius: var(--zx-control-radius);
+  background: var(--zx-color-bg-surface);
+}
+
+.zx-view-settings__row:hover {
+  background: var(--zx-color-bg-hover);
+}
+
+.zx-view-settings__handle {
+  order: -2;
+  flex: none;
+}
+
+.zx-view-settings__type {
+  order: -1;
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  inline-size: 1.25rem;
+  color: var(--zx-color-text-subtle);
+}
+
+.zx-view-settings__label {
+  flex: 1 1 auto;
+  min-inline-size: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Handle and hide buttons: flat until hovered or focused, square at the control height. */
+.zx-view-settings__handle,
+.zx-view-settings__hide {
+  display: inline-grid;
+  place-items: center;
+  inline-size: var(--zx-control-height);
+  block-size: var(--zx-control-height);
+  min-block-size: 0;
+  padding: 0;
+  border: 1px solid transparent;
+  border-radius: var(--zx-control-radius);
+  background: none;
+  color: var(--zx-color-text-subtle);
+}
+
+.zx-view-settings__handle[data-placeholder] {
+  visibility: hidden;
+}
+
+button.zx-view-settings__handle {
+  cursor: grab;
+  touch-action: none;
+  -webkit-user-select: none;
+  user-select: none;
+}
+
+.zx-view-settings__handle:hover,
+.zx-view-settings__hide:hover:not(:disabled) {
+  background: var(--zx-color-bg-hover);
+  color: var(--zx-color-text);
+}
+
+.zx-view-settings__handle:focus-visible,
+.zx-view-settings__hide:focus-visible {
+  box-shadow: var(--zx-focus-ring);
+}
+
+.zx-view-settings__hide:disabled {
+  color: var(--zx-color-text-placeholder);
+  cursor: default;
+}
+
+.zx-view-settings__lock {
+  display: inline-grid;
+  flex: none;
+  place-items: center;
+  inline-size: var(--zx-control-height);
+  color: var(--zx-color-text-placeholder);
+}
+
+.zx-view-settings__add {
+  flex: none;
+}
+
+/* Picked up from the keyboard: marked by the border as well as the fill, never by colour alone. */
+.zx-view-settings__row[data-state="grabbed"] {
+  outline: 2px solid var(--zx-color-ring);
+  outline-offset: -2px;
+  background: var(--zx-color-bg-selected);
+}
+
+.zx-view-settings[data-dragging="true"],
+.zx-view-settings[data-dragging="true"] .zx-view-settings__handle {
+  cursor: grabbing;
+}
+
+.zx-view-settings__row[data-dragging="true"] {
+  z-index: 1;
+  background: var(--zx-color-bg-raised);
+  box-shadow: var(--zx-overlay-shadow);
+}
+
+.zx-view-settings__drop-indicator {
+  position: absolute;
+  inset-inline: 0;
+  inset-block-start: 0;
+  z-index: 2;
+  block-size: 2px;
+  margin-block-start: -1px;
+  border-radius: var(--zx-radius-full);
+  background: var(--zx-color-accent);
+  pointer-events: none;
+}
+
+.zx-view-settings__drop-indicator[hidden] {
+  display: none;
+}
+
+.zx-view-settings__empty {
+  margin: 0;
+  padding-block: var(--zx-space-1);
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-sm);
+}
+
+.zx-view-settings__empty[hidden] {
+  display: none;
+}
+
+.zx-view-settings__option {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--zx-space-2);
+  min-inline-size: 0;
+}
+
+.zx-view-settings__option > .zx-icon,
+.zx-view-settings .zx-select__value-adornment > .zx-icon {
+  flex: none;
+  color: var(--zx-color-text-subtle);
+}
+
+.zx-view-settings__group {
+  inline-size: 100%;
+}
+
+/* Board settings: label beside its select where there is room, above it where there is not. */
+.zx-view-settings__setting {
+  display: grid;
+  grid-template-columns: minmax(6rem, auto) minmax(0, 1fr);
+  align-items: center;
+  gap: var(--zx-space-2);
+}
+
+.zx-view-settings__setting-label {
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-sm);
+}
+
+@container (max-width: 18rem) {
+  .zx-view-settings__setting {
+    grid-template-columns: minmax(0, 1fr);
+    gap: var(--zx-space-1);
+  }
+}
+
+.zx-view-settings__toggle {
+  justify-self: start;
+}
+
+.zx-view-settings__instructions[hidden] {
+  display: none;
+}
+
+.zx-view-settings__sr,
+.zx-view-settings__status {
+  position: absolute;
+  inline-size: 1px;
+  block-size: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .zx-view-settings__row,
+  .zx-view-settings__handle,
+  .zx-view-settings__hide {
+    transition: background var(--zx-dur-fast) var(--zx-ease),
+      color var(--zx-dur-fast) var(--zx-ease),
+      box-shadow var(--zx-dur-fast) var(--zx-ease);
+  }
+
+  .zx-view-settings__drop-indicator {
+    transition: inset-block-start var(--zx-dur-fast) var(--zx-ease);
+  }
+}