@zeyos/zx 2.1.0 → 2.2.1

package/src/components/layout/layout.js

@@ -0,0 +1,136 @@
+import { h } from '../../core/dom.js';
+
+/**
+ * @typedef {Object} StackOptions
+ * @property {'column'|'row'} [direction='column'] Flow direction.
+ * @property {number|string} [gap=4] Space between children. A number 1–8 picks the matching
+ *   `--zx-space-*` step; a string is used as-is.
+ * @property {'start'|'center'|'end'|'stretch'|'baseline'} [align] Cross-axis alignment.
+ * @property {'start'|'center'|'end'|'between'|'around'} [justify] Main-axis distribution.
+ * @property {boolean} [wrap=false] Whether a row wraps.
+ * @property {boolean} [inline=false] Whether the stack is laid out inline.
+ * @property {string} [class=''] Extra class names.
+ */
+
+/**
+ * @typedef {Object} GridOptions
+ * @property {number|null} [columns=null] Column count at full width. Null fills the row with as
+ *   many tracks of `min` width as fit.
+ * @property {number|string} [min='16rem'] Narrowest a track may get before the grid drops a
+ *   column. A number is read as pixels.
+ * @property {number|string} [gap=4] Space between cells, as in `stack`.
+ * @property {'start'|'center'|'end'|'stretch'} [align] Block-axis alignment of each cell.
+ * @property {string} [class=''] Extra class names.
+ */
+
+/**
+ * @typedef {Object} AspectOptions
+ * @property {string} [ratio='16 / 9'] Aspect ratio of the box.
+ * @property {'cover'|'contain'|'fill'} [fit='cover'] How the single child fills the box.
+ * @property {string} [class=''] Extra class names.
+ */
+
+/** @typedef {import('../../core/dom.js').DomChild} DomChild */
+
+/**
+ * Creates a one-dimensional flow of children with consistent spacing.
+ *
+ * Zx ships no page grid on purpose: an ERP screen is a shell of panels, and `SplitView`,
+ * `MasterPanel`, and `Panel` already own that layer. `stack` and `grid` are the small pieces that
+ * were missing under them — the spacing every form section, toolbar row, and card list was
+ * otherwise re-inventing with an ad-hoc flex rule.
+ *
+ * @param {StackOptions} [options={}] Stack options.
+ * @param {...DomChild} children Children.
+ * @returns {HTMLDivElement}
+ */
+export function stack(options = {}, ...children) {
+  const element = /** @type {HTMLDivElement} */ (h('div', {
+    class: ['zx-stack', options.class ?? ''],
+    dataset: {
+      direction: options.direction === 'row' ? 'row' : null,
+      align: ALIGN.has(options.align) ? options.align : null,
+      justify: JUSTIFY.has(options.justify) ? options.justify : null,
+      wrap: options.wrap ? 'true' : null,
+      inline: options.inline ? 'true' : null
+    },
+    style: gapStyle('--zx-stack-gap', options.gap)
+  }, children));
+  return element;
+}
+
+/**
+ * Creates a grid that keeps its tracks readable, dropping a column when the container gets too
+ * narrow to hold them at `min` width.
+ *
+ * The reflow is intrinsic — `auto-fit` against a `min` track width — so a grid behaves the same
+ * in a full-width page, a split pane, and a modal. Nothing here consults the viewport, which is
+ * the usual reason a "responsive" grid still breaks inside a narrow panel.
+ *
+ * @param {GridOptions} [options={}] Grid options.
+ * @param {...DomChild} children Cells.
+ * @returns {HTMLDivElement}
+ */
+export function grid(options = {}, ...children) {
+  const columns = Number(options.columns);
+  const style = {
+    ...gapStyle('--zx-grid-gap', options.gap),
+    '--zx-grid-min': length(options.min ?? '16rem')
+  };
+  if (Number.isFinite(columns) && columns >= 1) {
+    style['--zx-grid-columns'] = String(Math.trunc(columns));
+  }
+  return /** @type {HTMLDivElement} */ (h('div', {
+    class: ['zx-grid', options.class ?? ''],
+    dataset: {
+      columns: Number.isFinite(columns) && columns >= 1 ? 'true' : null,
+      align: ALIGN.has(options.align) ? options.align : null
+    },
+    style
+  }, children));
+}
+
+/**
+ * Creates a box that holds a fixed aspect ratio whatever its width, so an image, a map, or a
+ * chart placeholder reserves its space before it loads.
+ * @param {AspectOptions} [options={}] Aspect options.
+ * @param {...DomChild} children The single child to fit.
+ * @returns {HTMLDivElement}
+ */
+export function aspect(options = {}, ...children) {
+  return /** @type {HTMLDivElement} */ (h('div', {
+    class: ['zx-aspect', options.class ?? ''],
+    style: {
+      '--zx-aspect-ratio': String(options.ratio ?? '16 / 9'),
+      '--zx-aspect-fit': FIT.has(options.fit) ? options.fit : 'cover'
+    }
+  }, children));
+}
+
+const ALIGN = new Set(['start', 'center', 'end', 'stretch', 'baseline']);
+const JUSTIFY = new Set(['start', 'center', 'end', 'between', 'around']);
+const FIT = new Set(['cover', 'contain', 'fill']);
+
+/**
+ * Resolves a gap into a custom property, mapping 1–8 onto the spacing scale.
+ * @param {string} property Custom property to set.
+ * @param {number|string|undefined} gap Gap option.
+ * @returns {Record<string, string>}
+ */
+function gapStyle(property, gap) {
+  if (gap === undefined || gap === null || gap === '') return {};
+  const step = Number(gap);
+  if (Number.isInteger(step) && step >= 1 && step <= 8) {
+    return { [property]: `var(--zx-space-${step})` };
+  }
+  return { [property]: String(gap) };
+}
+
+/**
+ * Normalizes a CSS length, reading a bare number as pixels.
+ * @param {string|number} value Length.
+ * @returns {string}
+ */
+function length(value) {
+  return typeof value === 'number' ? `${value}px` : String(value);
+}

package/src/components/loading/inline-loading.css

@@ -0,0 +1,34 @@
+.zx-inline-loading {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--zx-space-2);
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-control-font-size);
+  vertical-align: middle;
+}
+
+.zx-inline-loading__indicator {
+  display: inline-flex;
+  align-items: center;
+  flex: none;
+}
+
+.zx-inline-loading__indicator:empty {
+  display: none;
+}
+
+.zx-inline-loading[data-status="success"] {
+  color: var(--zx-color-success);
+}
+
+.zx-inline-loading[data-status="error"] {
+  color: var(--zx-color-danger);
+}
+
+.zx-inline-loading[data-status="inactive"] {
+  color: var(--zx-color-text-placeholder);
+}
+
+.zx-inline-loading[data-size="md"] {
+  font-size: var(--zx-text-lg);
+}

package/src/components/loading/inline-loading.js

@@ -0,0 +1,140 @@
+import { Component } from '../../core/component.js';
+import { h, restoreTarget, snapshotTarget } from '../../core/dom.js';
+import { icon as createIcon } from '../../core/icons.js';
+import { spinner } from './spinner.js';
+
+/**
+ * @typedef {Object} InlineLoadingOptions
+ * @property {'inactive'|'active'|'success'|'error'} [status='active'] Initial state.
+ * @property {string} [description=''] Text shown beside the indicator.
+ * @property {'sm'|'md'} [size='sm'] Indicator size.
+ * @property {boolean} [live=true] Whether state changes are announced through `aria-live`.
+ * @property {(event: CustomEvent<{status: string, description: string}>) => void} [onstatuschange]
+ *   State-change listener.
+ */
+
+const STATUSES = new Set(['inactive', 'active', 'success', 'error']);
+
+/**
+ * The status line that replaces a spinner once the wait resolves — "Saving…" becoming "Saved" or
+ * "Could not save" in the same place, beside the control that started the work.
+ *
+ * The whole element is one polite live region, so a screen reader hears the outcome without the
+ * focus moving. Reach for `Message` instead when the outcome deserves a dismissible notification
+ * rather than a line of text that stays put.
+ *
+ * @fires InlineLoading#statuschange
+ * @extends {Component<InlineLoadingOptions>}
+ */
+export class InlineLoading extends Component {
+  static cssName = 'inline-loading';
+
+  /** @type {InlineLoadingOptions} */
+  static defaults = {
+    status: 'active',
+    description: '',
+    size: 'sm',
+    live: true
+  };
+
+  /** @returns {HTMLElement} */
+  render() {
+    // render() runs inside the base constructor, before class-field initializers would run.
+    this._status = 'inactive';
+    this._description = '';
+    this._createdRoot = this.el === null;
+    this._snapshot = this._createdRoot ? null : snapshotTarget(this.el);
+
+    const root = /** @type {HTMLElement} */ (this.el ?? h('span'));
+    this.el = root;
+
+    root.replaceChildren(
+      h('span', { ref: 'indicator', class: 'zx-inline-loading__indicator' }),
+      h('span', { ref: 'description', class: 'zx-inline-loading__description' })
+    );
+    root.dataset.size = this.options.size === 'md' ? 'md' : 'sm';
+    if (this.options.live !== false) {
+      root.setAttribute('role', 'status');
+      root.setAttribute('aria-live', 'polite');
+    }
+
+    this.set(this.options.status, this.options.description, { silent: true });
+    return root;
+  }
+
+  /**
+   * Returns the current state.
+   * @returns {'inactive'|'active'|'success'|'error'}
+   */
+  get() {
+    return this._status;
+  }
+
+  /**
+   * Returns the current description.
+   * @returns {string}
+   */
+  getDescription() {
+    return this._description;
+  }
+
+  /**
+   * Moves to a state, optionally replacing the description with it.
+   * @param {'inactive'|'active'|'success'|'error'} status Next state.
+   * @param {string} [description] Replacement description; the current one is kept when omitted.
+   * @param {{silent?: boolean}} [options={}] Set `silent` to suppress `statuschange`.
+   * @returns {this}
+   * @fires InlineLoading#statuschange
+   */
+  set(status, description, { silent = false } = {}) {
+    const next = STATUSES.has(status) ? status : 'inactive';
+    if (description !== undefined) this._description = String(description ?? '');
+    const changed = next !== this._status;
+    this._status = next;
+    this._sync();
+    if (changed && !silent) {
+      this.emit('statuschange', { status: this._status, description: this._description });
+    }
+    return this;
+  }
+
+  /**
+   * Replaces the description without changing the state.
+   * @param {string} description Text beside the indicator.
+   * @returns {this}
+   */
+  setDescription(description) {
+    this._description = String(description ?? '');
+    this.refs.description.textContent = this._description;
+    return this;
+  }
+
+  /** Paints the indicator and the description for the current state. @returns {void} */
+  _sync() {
+    this.el.dataset.status = this._status;
+    this.refs.description.textContent = this._description;
+    this.refs.indicator.replaceChildren(...this._indicator());
+  }
+
+  /** @returns {Node[]} */
+  _indicator() {
+    const size = this.el.dataset.size === 'md' ? 18 : 16;
+    if (this._status === 'active') return [spinner({ size: 'sm', kind: 'current' })];
+    if (this._status === 'success') return [createIcon('success', { size })];
+    if (this._status === 'error') return [createIcon('error', { size })];
+    return [];
+  }
+
+  /** Restores an enhanced target to the markup it had before the takeover. @returns {void} */
+  destroy() {
+    const root = this.el;
+    super.destroy();
+    if (!this._createdRoot && root) restoreTarget(root, this._snapshot);
+  }
+}
+
+/**
+ * State change.
+ * @event InlineLoading#statuschange
+ * @type {CustomEvent<{status: string, description: string}>}
+ */

package/src/components/loading/progress-bar.css

@@ -0,0 +1,115 @@
+.zx-progress-bar {
+  display: flex;
+  flex-direction: column;
+  gap: var(--zx-space-1);
+  inline-size: 100%;
+}
+
+.zx-progress-bar__head {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: var(--zx-space-3);
+  font-size: var(--zx-control-font-size);
+}
+
+.zx-progress-bar__label {
+  color: var(--zx-color-text);
+  font-weight: 500;
+}
+
+.zx-progress-bar__value {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--zx-space-1);
+  color: var(--zx-color-text-muted);
+  font-variant-numeric: tabular-nums;
+}
+
+.zx-progress-bar__track {
+  position: relative;
+  block-size: var(--zx-progress-thickness, 8px);
+  background: var(--zx-color-bg-muted);
+  border-radius: var(--zx-radius-full);
+  overflow: hidden;
+}
+
+.zx-progress-bar__fill {
+  block-size: 100%;
+  inline-size: var(--zx-progress-fill, 0%);
+  background: var(--zx-color-accent);
+  border-radius: inherit;
+}
+
+.zx-progress-bar__helper {
+  margin: 0;
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-sm);
+}
+
+/* An empty head or helper must not add its line box to the stack. */
+.zx-progress-bar__helper:empty,
+.zx-progress-bar__head:not(:has(.zx-progress-bar__label:not(:empty), .zx-progress-bar__value:not(:empty))) {
+  display: none;
+}
+
+.zx-progress-bar[data-size="sm"] {
+  --zx-progress-thickness: 4px;
+}
+
+.zx-progress-bar[data-hide-label] .zx-progress-bar__label {
+  position: absolute;
+  clip-path: inset(50%);
+  inline-size: 1px;
+  block-size: 1px;
+  overflow: hidden;
+  white-space: nowrap;
+}
+
+.zx-progress-bar[data-status="success"] .zx-progress-bar__fill {
+  background: var(--zx-color-success);
+}
+
+.zx-progress-bar[data-status="success"] .zx-progress-bar__value {
+  color: var(--zx-color-success);
+}
+
+.zx-progress-bar[data-status="error"] .zx-progress-bar__fill {
+  background: var(--zx-color-danger);
+}
+
+.zx-progress-bar[data-status="error"] .zx-progress-bar__value {
+  color: var(--zx-color-danger);
+}
+
+/*
+ * With the share unknown there is nothing to fill, so a short band travels the track instead.
+ * Without motion the band would sit still and read as a stalled 30% bar, so reduced motion gets a
+ * full-width muted track — visibly busy, never a wrong number.
+ */
+.zx-progress-bar[data-indeterminate] .zx-progress-bar__fill {
+  inline-size: 100%;
+  background: color-mix(in srgb, var(--zx-color-accent) 30%, var(--zx-color-bg-muted));
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .zx-progress-bar__fill {
+    transition: inline-size var(--zx-dur-base) var(--zx-ease);
+  }
+
+  .zx-progress-bar[data-indeterminate] .zx-progress-bar__fill {
+    inline-size: 35%;
+    background: var(--zx-color-accent);
+    animation: zx-progress-slide 1200ms var(--zx-ease) infinite;
+  }
+}
+
+@keyframes zx-progress-slide {
+  from {
+    transform: translateX(-100%);
+  }
+
+  to {
+    transform: translateX(calc(100% / 0.35));
+  }
+}

package/src/components/loading/progress-bar.js

@@ -0,0 +1,259 @@
+import { Component } from '../../core/component.js';
+import { h, restoreTarget, snapshotTarget } from '../../core/dom.js';
+import { icon as createIcon } from '../../core/icons.js';
+import { clamp, uid } from '../../core/util.js';
+
+/**
+ * @typedef {Object} ProgressBarOptions
+ * @property {number} [value=0] Completed amount, clamped to `[0, max]`.
+ * @property {number} [max=100] Amount that counts as finished.
+ * @property {string} [label=''] Visible name of the task.
+ * @property {string} [helperText=''] Supporting line below the track.
+ * @property {'active'|'success'|'error'} [status='active'] Visual state of the track.
+ * @property {boolean} [indeterminate=false] Whether the amount done is unknown.
+ * @property {'md'|'sm'} [size='md'] Track thickness.
+ * @property {boolean} [hideLabel=false] Whether the label is kept for assistive technology only.
+ * @property {boolean} [showValue=true] Whether the formatted value is drawn opposite the label.
+ * @property {((value: number, max: number) => string)|null} [formatValue=null] Replaces the
+ *   default percentage readout.
+ * @property {(event: CustomEvent<{value: number, percent: number}>) => void} [onchange] Value listener.
+ * @property {(event: CustomEvent<{value: number}>) => void} [oncomplete] Listener for reaching `max`.
+ */
+
+/**
+ * Determinate progress track for work whose completed share is known — a file upload, a batch
+ * posting run, an import.
+ *
+ * The track carries `role="progressbar"` and its ARIA value attributes, which is what a screen
+ * reader reports; an indeterminate bar drops `aria-valuenow` rather than reporting a fake number.
+ * `status` is a display concern only: a finished-with-errors bar still reads 100%.
+ *
+ * @fires ProgressBar#change
+ * @fires ProgressBar#complete
+ * @extends {Component<ProgressBarOptions>}
+ */
+export class ProgressBar extends Component {
+  static cssName = 'progress-bar';
+
+  /** @type {ProgressBarOptions} */
+  static defaults = {
+    value: 0,
+    max: 100,
+    label: '',
+    helperText: '',
+    status: 'active',
+    indeterminate: false,
+    size: 'md',
+    hideLabel: false,
+    showValue: true,
+    formatValue: null
+  };
+
+  /** @returns {HTMLElement} */
+  render() {
+    // render() runs inside the base constructor, before class-field initializers would run.
+    this._value = 0;
+    this._createdRoot = this.el === null;
+    this._snapshot = this._createdRoot ? null : snapshotTarget(this.el);
+
+    const root = /** @type {HTMLElement} */ (this.el ?? h('div'));
+    this.el = root;
+
+    this._max = Math.max(1, Number(this.options.max) || 100);
+    this._status = normalizeStatus(this.options.status);
+    this._indeterminate = Boolean(this.options.indeterminate);
+    this._labelId = uid('zx-progress-label');
+
+    const head = h('div', { ref: 'head', class: 'zx-progress-bar__head' },
+      h('span', { ref: 'label', class: 'zx-progress-bar__label', id: this._labelId },
+        String(this.options.label ?? '')),
+      h('span', { ref: 'value', class: 'zx-progress-bar__value' })
+    );
+    const track = h('div', {
+      ref: 'track',
+      class: 'zx-progress-bar__track',
+      role: 'progressbar',
+      ariaValuemin: '0',
+      ariaValuemax: String(this._max),
+      ariaLabelledby: this._labelId
+    }, h('div', { ref: 'fill', class: 'zx-progress-bar__fill' }));
+
+    root.replaceChildren(head, track,
+      h('p', { ref: 'helper', class: 'zx-progress-bar__helper' },
+        String(this.options.helperText ?? '')));
+    root.dataset.size = this.options.size === 'sm' ? 'sm' : 'md';
+    root.toggleAttribute('data-hide-label', Boolean(this.options.hideLabel));
+
+    this.set(this.options.value, { silent: true });
+    return root;
+  }
+
+  /** Current value. @returns {number} */
+  get value() {
+    return this._value;
+  }
+
+  /** @param {number} next Next value. */
+  set value(next) {
+    this.set(next);
+  }
+
+  /**
+   * Returns the current value.
+   * @returns {number}
+   */
+  get() {
+    return this._value;
+  }
+
+  /**
+   * Sets the completed amount, clamped to `[0, max]`.
+   * @param {number} next Completed amount.
+   * @param {{silent?: boolean}} [options={}] Set `silent` to suppress events.
+   * @returns {this}
+   * @fires ProgressBar#change
+   * @fires ProgressBar#complete
+   */
+  set(next, { silent = false } = {}) {
+    const raw = Number(next);
+    const value = clamp(Number.isFinite(raw) ? raw : 0, 0, this._max);
+    const changed = value !== this._value;
+    const reached = changed && value >= this._max;
+    this._value = value;
+    this._sync();
+    if (!silent && changed) this.emit('change', { value, percent: this.percent() });
+    if (!silent && reached) this.emit('complete', { value });
+    return this;
+  }
+
+  /**
+   * Completed share of the track, as a number between 0 and 100.
+   * @returns {number}
+   */
+  percent() {
+    return (this._value / this._max) * 100;
+  }
+
+  /**
+   * Replaces the upper bound, re-clamping the current value against it.
+   * @param {number} max New maximum.
+   * @returns {this}
+   */
+  setMax(max) {
+    this._max = Math.max(1, Number(max) || 1);
+    this.refs.track.setAttribute('aria-valuemax', String(this._max));
+    return this.set(this._value, { silent: true });
+  }
+
+  /**
+   * Sets the visual state, optionally replacing the helper line with it.
+   * @param {'active'|'success'|'error'} status Track state.
+   * @param {string} [helperText] Replacement helper line.
+   * @returns {this}
+   */
+  setStatus(status, helperText) {
+    this._status = normalizeStatus(status);
+    if (helperText !== undefined) this.setHelperText(helperText);
+    this._sync();
+    return this;
+  }
+
+  /**
+   * Replaces the visible task name.
+   * @param {string} label Task name.
+   * @returns {this}
+   */
+  setLabel(label) {
+    this.refs.label.textContent = String(label ?? '');
+    return this;
+  }
+
+  /**
+   * Replaces the supporting line below the track.
+   * @param {string} helperText Supporting line.
+   * @returns {this}
+   */
+  setHelperText(helperText) {
+    this.refs.helper.textContent = String(helperText ?? '');
+    return this;
+  }
+
+  /**
+   * Switches between a known and an unknown completed share.
+   * @param {boolean} [indeterminate=true] Whether the amount done is unknown.
+   * @returns {this}
+   */
+  setIndeterminate(indeterminate = true) {
+    this._indeterminate = Boolean(indeterminate);
+    this._sync();
+    return this;
+  }
+
+  /** Paints the track, the readout, and the ARIA value attributes. @returns {void} */
+  _sync() {
+    const { track, fill, value } = this.refs;
+    this.el.dataset.status = this._status;
+    this.el.toggleAttribute('data-indeterminate', this._indeterminate);
+
+    if (this._indeterminate) {
+      track.removeAttribute('aria-valuenow');
+      track.removeAttribute('aria-valuetext');
+      fill.style.removeProperty('--zx-progress-fill');
+      value.textContent = '';
+      return;
+    }
+
+    const text = this._format();
+    track.setAttribute('aria-valuenow', String(this._value));
+    track.setAttribute('aria-valuetext', text);
+    fill.style.setProperty('--zx-progress-fill', `${this.percent()}%`);
+    value.replaceChildren(...this._readout(text));
+  }
+
+  /** @returns {string} */
+  _format() {
+    const formatter = this.options.formatValue;
+    if (typeof formatter === 'function') return String(formatter(this._value, this._max));
+    return `${Math.round(this.percent())}%`;
+  }
+
+  /**
+   * The readout beside the label: the formatted value, prefixed by a status glyph once the run
+   * has finished one way or the other.
+   * @param {string} text Formatted value.
+   * @returns {Node[]}
+   */
+  _readout(text) {
+    if (!this.options.showValue) return [];
+    const nodes = [];
+    if (this._status !== 'active') {
+      nodes.push(createIcon(this._status === 'success' ? 'success' : 'error', { size: 14 }));
+    }
+    nodes.push(h('span', { class: 'zx-progress-bar__percent' }, text));
+    return nodes;
+  }
+
+  /** Restores an enhanced target to the markup it had before the takeover. @returns {void} */
+  destroy() {
+    const root = this.el;
+    super.destroy();
+    if (!this._createdRoot && root) restoreTarget(root, this._snapshot);
+  }
+}
+
+/**
+ * Value change.
+ * @event ProgressBar#change
+ * @type {CustomEvent<{value: number, percent: number}>}
+ */
+
+/**
+ * Fired once the value reaches `max`.
+ * @event ProgressBar#complete
+ * @type {CustomEvent<{value: number}>}
+ */
+
+/** @param {unknown} value @returns {'active'|'success'|'error'} */
+function normalizeStatus(value) {
+  return value === 'success' || value === 'error' ? value : 'active';
+}