@zeyos/zx 4.3.4 → 5.0.0

package/src/components/chart/chart.js

@@ -1,5 +1,6 @@
 import { Component } from '../../core/component.js';
 import { h } from '../../core/dom.js';
+import { prefersReducedMotion, watchMotion } from '../../core/motion.js';
 import { uid } from '../../core/util.js';
 
 /** @typedef {{label?: string, data?: unknown[], [key: string]: unknown}} ChartDataset */
@@ -9,6 +10,9 @@ import { uid } from '../../core/util.js';
  * @property {string} type Chart type.
  * @property {ChartData} data Chart data.
  * @property {Record<string, unknown>} options Engine-specific options.
+ * @property {boolean} reducedMotion Whether the chart must not animate: the operating system asks
+ *   for reduced motion, or the host sits inside a `data-zx-motion="reduced"` region. An adapter turns
+ *   its engine's own animation off when this is true; `ChartJsAdapter` sets `animation: false`.
  * @property {(detail: ChartSelectDetail) => void} onSelect Point-selection callback.
  */
 /**
@@ -145,6 +149,9 @@ export class Chart extends Component {
 
     this._observer = typeof ResizeObserver === 'function' ? new ResizeObserver(() => this.resize()) : null;
     this._observer?.observe(viewport);
+    // The engine tweens in script, where no stylesheet can reach it: when motion is reduced, or
+    // stops being reduced, the mounted chart is updated with the new answer in its spec.
+    this._stopWatchingMotion = watchMotion(root, () => this._mountOrUpdate(false));
     return root;
   }
 
@@ -232,6 +239,7 @@ export class Chart extends Component {
     this._destroyed = true;
     const original = this._original;
     this._observer?.disconnect();
+    this._stopWatchingMotion?.();
     this._destroyHandle();
     super.destroy();
     if (!this._createdRoot && original) {
@@ -277,6 +285,7 @@ export class Chart extends Component {
         ...themeChartOptions(/** @type {HTMLElement} */ (this.el)),
         ...cloneChartValue(this._chartOptions)
       },
+      reducedMotion: prefersReducedMotion(this.el),
       onSelect: (detail) => this.emit('select', detail)
     };
   }
@@ -386,6 +395,9 @@ function chartJsConfig(spec, defaults, getInstance) {
     ...cloneChartValue(defaults),
     ...supplied
   };
+  // Reduced motion wins over any animation the application configured: a person who asked for
+  // less motion gets it from every chart, not only from the ones that remembered to ask.
+  if (spec.reducedMotion) options.animation = false;
   const originalClick = options.onClick;
   options.onClick = (event, elements, chart) => {
     if (typeof originalClick === 'function') originalClick(event, elements, chart);

package/src/components/check-button/check-button.css

@@ -11,6 +11,7 @@
   padding-inline: var(--zx-control-pad-x);
   font: inherit;
   font-size: var(--zx-control-font-size);
+  font-weight: var(--zx-control-font-weight);
   cursor: pointer;
 }
 
@@ -18,9 +19,16 @@
   background: var(--zx-color-bg-hover);
 }
 
+/* Pressed is a state the button is in, so the button itself goes neutral — the current fill, a
+   stronger border, the full text colour — and only the check glyph, which is the mark, keeps the
+   accent, as a checkbox would. */
 .zx-check-button[aria-pressed="true"] {
-  border-color: var(--zx-color-accent);
-  background: var(--zx-color-bg-selected);
+  border-color: var(--zx-color-border-strong);
+  background: var(--zx-color-bg-current);
+  color: var(--zx-color-text);
+}
+
+.zx-check-button__on {
   color: var(--zx-color-accent);
 }
 

package/src/components/checklist/checklist.css

@@ -7,7 +7,9 @@
 }
 
 .zx-checklist__label {
-  font-weight: 650;
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-sm);
+  font-weight: var(--zx-weight-medium);
 }
 
 .zx-checklist__search {
@@ -31,10 +33,12 @@
   display: flex;
   align-items: center;
   gap: var(--zx-space-2);
-  min-block-size: var(--zx-control-height);
+  /* The same row as a listbox option. */
+  min-block-size: calc(var(--zx-control-height) - 2px);
   border-radius: var(--zx-radius-sm);
   cursor: pointer;
   padding: var(--zx-space-1) var(--zx-space-2);
+  line-height: 1.35;
 }
 
 .zx-checklist__item:hover {
@@ -45,8 +49,11 @@
   background: var(--zx-color-bg-selected);
 }
 
+/* The base control height is for text fields; a checkbox that inherited it would make every row
+   a field tall. */
 .zx-checklist__item input {
   flex: none;
+  min-block-size: 0;
   accent-color: var(--zx-color-accent);
 }
 

package/src/components/checklist/checklist.js

@@ -13,6 +13,9 @@ import { matchItems } from '../select/filter.js';
  * @property {boolean} [search=true] Whether the search field is shown.
  * @property {number} [height=280] Maximum list height in pixels.
  * @property {boolean} [defaultChecked=false] Fallback initial checked state.
+ * @property {boolean} [hideLabel=false] Whether the heading is left out. The group keeps the
+ *   heading text as its accessible name (`aria-label`); a Field labelling the checklist names it
+ *   instead, which is why the `checklist` field type sets this.
  * @property {(() => Promise<ChecklistItem[]>|ChecklistItem[])|null} [load=null] Async item loader.
  * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
  * @property {(event: CustomEvent<ChecklistChangeDetail>) => void} [onchange] Change listener.
@@ -40,6 +43,7 @@ export class Checklist extends Component {
     search: true,
     height: 280,
     defaultChecked: false,
+    hideLabel: false,
     load: null
   };
 
@@ -53,15 +57,16 @@ export class Checklist extends Component {
     const root = /** @type {HTMLElement} */ (this.el ?? h('div'));
     this.el = root;
     if (!this._createdRoot) this._originalChildren = Array.from(root.childNodes);
-    for (const name of ['role', 'aria-labelledby', 'data-state']) {
+    for (const name of ['role', 'aria-label', 'aria-labelledby', 'data-state']) {
       this._originalAttributes.set(name, root.getAttribute(name));
     }
 
+    const labelText = this._message('checklist.label', 'Checklist');
     const labelId = uid('zx-checklist-label');
-    const title = h('div', {
+    const title = this.options.hideLabel ? null : h('div', {
       class: 'zx-checklist__label',
       id: labelId
-    }, this._message('checklist.label', 'Checklist'));
+    }, labelText);
     const search = h('input', {
       ref: 'search',
       class: 'zx-checklist__search',
@@ -76,9 +81,10 @@ export class Checklist extends Component {
       class: 'zx-checklist__list'
     });
     list.style.maxBlockSize = `${Math.max(0, Number(this.options.height) || 0)}px`;
-    root.replaceChildren(title, search, list);
+    root.replaceChildren(...[title, search, list].filter(Boolean));
     root.setAttribute('role', 'group');
-    root.setAttribute('aria-labelledby', labelId);
+    if (title) root.setAttribute('aria-labelledby', labelId);
+    else root.setAttribute('aria-label', labelText);
 
     this.listen(search, 'input', () => this.search(/** @type {HTMLInputElement} */ (search).value));
     this.listen(list, 'change', (event) => {

package/src/components/checklist/field-adapter.js

@@ -7,7 +7,9 @@ import { Checklist } from './checklist.js';
  */
 export function registerChecklistFieldAdapter() {
   Field.register('checklist', (field, options) => {
-    const checklist = field.own(new Checklist(null, { ...(options.props ?? {}) }));
+    // The Field's label names the list (`aria-labelledby`), so the checklist draws no heading of
+    // its own under it.
+    const checklist = field.own(new Checklist(null, { hideLabel: true, ...(options.props ?? {}) }));
     let disabled = false;
     let setting = false;
     const syncDisabled = () => {

package/src/components/code-editor/code-editor.css

@@ -0,0 +1,68 @@
+.zx-code-editor {
+  overflow: hidden;
+  border: 1px solid var(--zx-color-border-control);
+  border-radius: var(--zx-control-radius);
+  background: var(--zx-color-bg-control);
+}
+
+.zx-code-editor:focus-within {
+  box-shadow: var(--zx-focus-ring);
+}
+
+.zx-code-editor__header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--zx-space-3);
+  min-block-size: var(--zx-control-height);
+  padding-inline: var(--zx-space-3);
+  border-block-end: 1px solid var(--zx-color-border);
+  background: var(--zx-color-bg-muted);
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-xs);
+}
+
+/* The language is an identifier (`json`, `sql`), so it is shown as one — in the mono face, as
+   written — rather than shouted in letter-spaced capitals. */
+.zx-code-editor__language {
+  overflow: hidden;
+  font-family: var(--zx-font-mono);
+  font-weight: var(--zx-weight-medium);
+  text-overflow: ellipsis;
+  text-wrap: nowrap;
+}
+
+.zx-code-editor__position {
+  font-variant-numeric: tabular-nums;
+  text-wrap: nowrap;
+}
+
+.zx-code-editor__input {
+  display: block;
+  inline-size: 100%;
+  min-block-size: calc(var(--zx-control-height) * 4);
+  resize: vertical;
+  padding: var(--zx-space-3);
+  border: 0;
+  border-radius: 0;
+  outline: 0;
+  background: transparent;
+  box-shadow: none;
+  color: var(--zx-color-text);
+  font-family: var(--zx-font-mono);
+  font-size: var(--zx-text-sm);
+  line-height: 1.55;
+  tab-size: 2;
+}
+
+.zx-code-editor__input:focus-visible {
+  box-shadow: none;
+}
+
+.zx-code-editor[data-readonly="true"] {
+  background: var(--zx-color-bg-muted);
+}
+
+.zx-code-editor[data-disabled="true"] {
+  opacity: 0.6;
+}

package/src/components/code-editor/code-editor.js

@@ -0,0 +1,306 @@
+import { Component } from '../../core/component.js';
+import { h } from '../../core/dom.js';
+
+/**
+ * @typedef {Object} CodeEditorOptions
+ * @property {unknown} [value=''] Initial text.
+ * @property {string} [name=''] Form field name.
+ * @property {string} [language='text'] Language identifier shown to the user and exposed as data.
+ * @property {string} [label='Code editor'] Accessible editor label.
+ * @property {string} [placeholder=''] Placeholder text.
+ * @property {number} [rows=12] Visible textarea rows.
+ * @property {string} [indent='\t'] Text inserted by Tab and removed by Shift+Tab.
+ * @property {'off'|'soft'|'hard'} [wrap='off'] Textarea wrapping behavior.
+ * @property {boolean} [spellcheck=false] Whether browser spellcheck is enabled.
+ * @property {boolean} [readOnly=false] Whether content can be selected but not changed.
+ * @property {boolean} [disabled=false] Whether the editor is disabled.
+ * @property {boolean} [status=true] Whether the line/column status is visible.
+ * @property {(event: CustomEvent<{value:string}>) => void} [oninput] Input listener.
+ * @property {(event: CustomEvent<{value:string}>) => void} [onchange] Change listener.
+ */
+
+/** Keys that only modify the next one: pressing them is not the keystroke that ends a Tab release. */
+const MODIFIER_KEYS = new Set(['Shift', 'Control', 'Alt', 'Meta', 'AltGraph', 'CapsLock', 'Fn', 'OS']);
+
+/**
+ * Dependency-free source editor for structured text, Markdown, JSON and code. It deliberately uses
+ * a native textarea: values remain text-safe, browser undo and IME behavior stay intact, and Tab /
+ * Shift+Tab provide predictable indentation without a third-party editor runtime.
+ *
+ * Capturing Tab is what a code surface has to do, and it would be a keyboard trap if nothing undid
+ * it: Escape releases the capture until the next keystroke in the editor, so Escape then Tab (or
+ * Shift+Tab) moves focus out of the editor as it would leave any other field.
+ * @fires CodeEditor#input
+ * @fires CodeEditor#change
+ * @extends {Component<CodeEditorOptions>}
+ */
+export class CodeEditor extends Component {
+  static cssName = 'code-editor';
+
+  /** @type {CodeEditorOptions} */
+  static defaults = {
+    value: '',
+    name: '',
+    language: 'text',
+    label: 'Code editor',
+    placeholder: '',
+    rows: 12,
+    indent: '\t',
+    wrap: 'off',
+    spellcheck: false,
+    readOnly: false,
+    disabled: false,
+    status: true
+  };
+
+  /** @returns {HTMLElement} */
+  render() {
+    this._createdRoot = this.el === null;
+    const root = /** @type {HTMLElement} */ (this.el ?? h('div'));
+    this.el = root;
+    this._initialChildren = this._createdRoot ? [] : [...root.childNodes];
+    this._initialAttributes = new Map(['data-language', 'data-readonly', 'data-disabled']
+      .map((name) => [name, root.getAttribute(name)]));
+    this._language = normalizeLanguage(this.options.language);
+    this._languageLabel = h('span', { class: 'zx-code-editor__language' }, this._language);
+    this._position = h('span', {
+      class: 'zx-code-editor__position',
+      role: 'status',
+      ariaLive: 'polite'
+    });
+    this._header = h('div', { class: 'zx-code-editor__header' }, this._languageLabel,
+      this.options.status ? this._position : null);
+    this._input = /** @type {HTMLTextAreaElement} */ (h('textarea', {
+      class: 'zx-code-editor__input',
+      name: this.options.name ? String(this.options.name) : undefined,
+      ariaLabel: String(this.options.label ?? 'Code editor'),
+      placeholder: String(this.options.placeholder ?? ''),
+      rows: normalizeRows(this.options.rows),
+      wrap: normalizeWrap(this.options.wrap),
+      spellcheck: Boolean(this.options.spellcheck),
+      readOnly: Boolean(this.options.readOnly),
+      disabled: Boolean(this.options.disabled),
+      autocomplete: 'off',
+      autocapitalize: 'off'
+    }));
+    this._input.value = String(this.options.value ?? '');
+    root.dataset.language = this._language;
+    root.dataset.readonly = String(Boolean(this.options.readOnly));
+    root.dataset.disabled = String(Boolean(this.options.disabled));
+    root.replaceChildren(this._header, this._input);
+    /** Set by Escape: the next Tab moves focus instead of indenting. */
+    this._tabReleased = false;
+
+    this.listen(this._input, 'keydown', (event) => this._handleKeydown(event));
+    this.listen(this._input, 'blur', () => { this._tabReleased = false; });
+    this.listen(this._input, 'input', () => {
+      this._updatePosition();
+      this.emit('input', { value: this.getValue() });
+    });
+    this.listen(this._input, 'change', () => this.emit('change', { value: this.getValue() }));
+    for (const type of ['click', 'keyup', 'select', 'focus']) {
+      this.listen(this._input, type, () => this._updatePosition());
+    }
+    this._updatePosition();
+    return root;
+  }
+
+  /** @returns {string} */
+  getValue() { return this._input.value; }
+
+  /**
+   * Replaces the editor text.
+   * @param {unknown} value New value.
+   * @param {{silent?:boolean}} [options={}] Suppress the `change` event.
+   * @returns {this}
+   */
+  setValue(value, { silent = false } = {}) {
+    const next = String(value ?? '');
+    if (this._input.value === next) return this;
+    this._input.value = next;
+    this._updatePosition();
+    if (!silent) this.emit('change', { value: next });
+    return this;
+  }
+
+  /** @param {unknown} language New language identifier. @returns {this} */
+  setLanguage(language) {
+    this._language = normalizeLanguage(language);
+    this.el.dataset.language = this._language;
+    this._languageLabel.textContent = this._language;
+    return this;
+  }
+
+  /** @returns {this} */
+  focus() { this._input.focus(); return this; }
+
+  /** @returns {this} */
+  enable() { this._input.disabled = false; this.el.dataset.disabled = 'false'; return this; }
+
+  /** @returns {this} */
+  disable() { this._input.disabled = true; this.el.dataset.disabled = 'true'; return this; }
+
+  /** @param {boolean} value Read-only state. @returns {this} */
+  setReadOnly(value) {
+    this._input.readOnly = Boolean(value);
+    this.el.dataset.readonly = String(Boolean(value));
+    return this;
+  }
+
+  /** @param {KeyboardEvent} event @returns {void} */
+  _handleKeydown(event) {
+    if (event.isComposing || MODIFIER_KEYS.has(event.key)) return;
+    if (event.key === 'Escape') {
+      this._tabReleased = true;
+      return;
+    }
+    // Any other keystroke ends the release, the Tab it was for included.
+    const released = this._tabReleased;
+    this._tabReleased = false;
+    if (released || event.key !== 'Tab' || event.altKey || event.ctrlKey || event.metaKey ||
+        this._input.readOnly || this._input.disabled) return;
+    const indent = String(this.options.indent ?? '\t');
+    if (!indent) return;
+    event.preventDefault();
+    const result = indentSelection(
+      this._input.value,
+      this._input.selectionStart ?? 0,
+      this._input.selectionEnd ?? 0,
+      indent,
+      event.shiftKey
+    );
+    if (result.value === this._input.value) return;
+    this._input.value = result.value;
+    this._input.setSelectionRange(result.start, result.end);
+    this._updatePosition();
+    this.emit('input', { value: this.getValue() });
+  }
+
+  /** @returns {void} */
+  _updatePosition() {
+    if (!this.options.status) return;
+    const position = editorPosition(this._input.value, this._input.selectionStart ?? 0,
+      this._input.selectionEnd ?? 0);
+    this._position.textContent = position.lines > 1
+      ? `Ln ${position.line}, Col ${position.column} · ${position.lines} lines selected`
+      : `Ln ${position.line}, Col ${position.column}`;
+  }
+
+  /** @returns {void} */
+  destroy() {
+    if (!this._createdRoot) {
+      this.el.replaceChildren(...this._initialChildren);
+      for (const [name, value] of this._initialAttributes) {
+        if (value === null) this.el.removeAttribute(name);
+        else this.el.setAttribute(name, value);
+      }
+    }
+    super.destroy();
+  }
+}
+
+/**
+ * Applies Tab or Shift+Tab to a textarea selection.
+ * @param {string} value Complete source value.
+ * @param {number} start Selection start.
+ * @param {number} end Selection end.
+ * @param {string} indent Indentation text.
+ * @param {boolean} outdent Whether to remove indentation.
+ * @returns {{value:string,start:number,end:number}}
+ */
+export function indentSelection(value, start, end, indent = '\t', outdent = false) {
+  const source = String(value ?? '');
+  const unit = String(indent ?? '');
+  const from = clampIndex(start, source.length);
+  const to = clampIndex(end, source.length);
+  if (!unit) return { value: source, start: from, end: to };
+
+  if (from === to && !outdent) {
+    return {
+      value: source.slice(0, from) + unit + source.slice(to),
+      start: from + unit.length,
+      end: from + unit.length
+    };
+  }
+
+  const lineStart = source.lastIndexOf('\n', Math.max(0, from - 1)) + 1;
+  let lineEnd = source.indexOf('\n', to);
+  if (lineEnd < 0) lineEnd = source.length;
+  const block = source.slice(lineStart, lineEnd);
+  const lines = block.split('\n');
+  let removedFirst = 0;
+  let delta = 0;
+  const transformed = lines.map((line, index) => {
+    if (!outdent) {
+      delta += unit.length;
+      return unit + line;
+    }
+    const removed = removableIndent(line, unit);
+    if (index === 0) removedFirst = removed;
+    delta -= removed;
+    return line.slice(removed);
+  }).join('\n');
+  const nextStart = outdent
+    ? Math.max(lineStart, from - Math.min(removedFirst, from - lineStart))
+    : from + unit.length;
+  return {
+    value: source.slice(0, lineStart) + transformed + source.slice(lineEnd),
+    start: nextStart,
+    end: Math.max(nextStart, to + delta)
+  };
+}
+
+/** @param {string} value @param {number} start @param {number} end @returns {{line:number,column:number,lines:number}} */
+export function editorPosition(value, start, end = start) {
+  const source = String(value ?? '');
+  const from = clampIndex(start, source.length);
+  const to = clampIndex(end, source.length);
+  const before = source.slice(0, from);
+  return {
+    line: before.split('\n').length,
+    column: from - before.lastIndexOf('\n'),
+    lines: source.slice(from, to).split('\n').length
+  };
+}
+
+/** @param {string} line @param {string} indent @returns {number} */
+function removableIndent(line, indent) {
+  if (line.startsWith(indent)) return indent.length;
+  if (indent === '\t') return line.startsWith('\t') ? 1 : Math.min(/^ +/.exec(line)?.[0].length ?? 0, 2);
+  return Math.min(/^\s+/.exec(line)?.[0].length ?? 0, indent.length);
+}
+
+/** @param {unknown} value @returns {string} */
+function normalizeLanguage(value) {
+  const language = String(value ?? 'text').trim().toLowerCase();
+  return /^[a-z0-9][a-z0-9+_.-]*$/.test(language) ? language : 'text';
+}
+
+/** @param {unknown} value @returns {number} */
+function normalizeRows(value) {
+  const rows = Number(value);
+  return Number.isFinite(rows) ? Math.max(2, Math.min(100, Math.round(rows))) : 12;
+}
+
+/** @param {unknown} value @returns {'off'|'soft'|'hard'} */
+function normalizeWrap(value) {
+  return ['off', 'soft', 'hard'].includes(String(value)) ? /** @type {'off'|'soft'|'hard'} */ (value) : 'off';
+}
+
+/** @param {unknown} value @param {number} length @returns {number} */
+function clampIndex(value, length) {
+  const number = Number(value);
+  return Math.max(0, Math.min(length, Number.isFinite(number) ? Math.round(number) : 0));
+}
+
+/**
+ * Code editor input event.
+ * @event CodeEditor#input
+ * @type {CustomEvent<{value:string}>}
+ */
+
+/**
+ * Code editor committed change event.
+ * @event CodeEditor#change
+ * @type {CustomEvent<{value:string}>}
+ */

package/src/components/code-editor/field-adapter.js

@@ -0,0 +1,34 @@
+import { CodeEditor } from './code-editor.js';
+import { Field } from '../field/field.js';
+
+/**
+ * Registers the CodeEditor-backed `code` field type.
+ * @returns {void}
+ */
+export function registerCodeEditorFieldAdapter() {
+  Field.register('code', (field, options) => {
+    const editor = field.own(new CodeEditor(null, {
+      label: options.label ? String(options.label) : 'Code editor',
+      placeholder: options.placeholder,
+      readOnly: Boolean(options.props?.readOnly),
+      disabled: Boolean(options.disabled),
+      ...(options.props ?? {}),
+      value: options.value
+    }));
+    let setting = false;
+    editor.on('input', (event) => {
+      if (!setting) field.emit('change', { value: event.detail.value });
+    });
+    return {
+      el: editor.el,
+      get: () => editor.getValue(),
+      set: (value) => {
+        setting = true;
+        try { editor.setValue(value, { silent: true }); }
+        finally { setting = false; }
+      },
+      focus: () => editor.focus(),
+      setDisabled: (value) => (value ? editor.disable() : editor.enable())
+    };
+  });
+}