@zeyos/zx 2.1.0 → 2.2.0

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

@@ -0,0 +1,24 @@
+import { Field } from '../field/field.js';
+import { Timebox } from './timebox.js';
+
+/**
+ * Registers the duration-oriented `time` field type.
+ * @returns {void}
+ */
+export function registerTimeboxFieldAdapter() {
+  Field.register('time', (field, options) => {
+    const timebox = field.own(new Timebox(null, {
+      ...(options.props ?? {}),
+      value: options.value
+    }));
+    field.listen(timebox.el, 'change', (event) => event.stopImmediatePropagation());
+    timebox.on('change', (event) => field.emit('change', { value: event.detail.value }));
+    return {
+      el: timebox.el,
+      get: () => timebox.get(),
+      set: (value) => timebox.set(Number(value) || 0, { silent: true }),
+      focus: () => timebox.el.querySelector('input:not([disabled]), button:not([disabled])')?.focus(),
+      setDisabled: (disabled) => disabled ? timebox.disable() : timebox.enable()
+    };
+  });
+}

package/src/components/timebox/timebox.css

@@ -0,0 +1,51 @@
+.zx-timebox {
+  display: inline-block;
+  color: var(--zx-color-text);
+  font-size: var(--zx-control-font-size);
+}
+
+.zx-timebox__content {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--zx-space-1);
+}
+
+.zx-timebox__segment {
+  inline-size: calc(var(--zx-control-height) + var(--zx-space-2));
+  padding-inline: var(--zx-space-1);
+  text-align: center;
+  font-variant-numeric: tabular-nums;
+}
+
+.zx-timebox__segment[data-segment="hours"] {
+  inline-size: calc(var(--zx-control-height) + var(--zx-space-4));
+}
+
+.zx-timebox__segment:focus-visible,
+.zx-timebox__sign:focus-visible {
+  box-shadow: var(--zx-focus-ring);
+}
+
+.zx-timebox__separator {
+  color: var(--zx-color-text-muted);
+  font-weight: 700;
+}
+
+.zx-timebox__sign {
+  min-inline-size: var(--zx-control-height);
+  padding: 0;
+  border-color: var(--zx-color-border-control);
+  font-weight: 750;
+}
+
+.zx-timebox__sign[data-state="positive"] {
+  border-color: var(--zx-color-success);
+  background: var(--zx-color-success-bg);
+  color: var(--zx-color-success);
+}
+
+.zx-timebox__sign[data-state="negative"] {
+  border-color: var(--zx-color-danger);
+  background: var(--zx-color-danger-bg);
+  color: var(--zx-color-danger);
+}

package/src/components/timebox/timebox.js

@@ -0,0 +1,276 @@
+import { Component } from '../../core/component.js';
+import { h } from '../../core/dom.js';
+
+/** @typedef {'minutes'|'seconds'|'hours'} TimeUnit */
+/** @typedef {{hours: number, minutes: number, seconds: number, negative: boolean}} TimeParts */
+/**
+ * @typedef {Object} TimeboxOptions
+ * @property {number} [value=0] Initial duration in `unit`.
+ * @property {TimeUnit} [unit='minutes'] Default input and output unit.
+ * @property {boolean} [seconds=false] Show a seconds segment.
+ * @property {boolean} [signed=false] Show a positive/negative toggle.
+ * @property {boolean} [disabled=false] Disable all controls.
+ * @property {(event: CustomEvent<{value: number}>) => void} [onchange] Change listener.
+ */
+/** @typedef {{silent?: boolean}} TimeboxSetOptions */
+
+/**
+ * Splits a duration into unlimited hours and normalized minute/second segments.
+ * @param {number} value Duration value.
+ * @param {TimeUnit} [unit='minutes'] Unit of `value`.
+ * @returns {TimeParts}
+ */
+export function splitTime(value, unit = 'minutes') {
+  const seconds = Math.round(Math.abs(toSeconds(finiteNumber(value), unit)));
+  return {
+    hours: Math.floor(seconds / 3600),
+    minutes: Math.floor(seconds / 60) % 60,
+    seconds: seconds % 60,
+    negative: finiteNumber(value) < 0
+  };
+}
+
+/**
+ * Joins duration segments and converts them to the requested unit.
+ * Minute and second overflow is carried into the unlimited hours value.
+ * @param {Partial<TimeParts>} parts Duration segments.
+ * @param {TimeUnit} [unit='minutes'] Unit of the returned number.
+ * @returns {number}
+ */
+export function joinTime(parts, unit = 'minutes') {
+  assertUnit(unit);
+  const hours = Math.abs(Math.trunc(finiteNumber(parts?.hours)));
+  const minutes = Math.abs(Math.trunc(finiteNumber(parts?.minutes)));
+  const seconds = Math.abs(Math.trunc(finiteNumber(parts?.seconds)));
+  const sign = parts?.negative ? -1 : 1;
+  return fromSeconds(sign * (hours * 3600 + minutes * 60 + seconds), unit);
+}
+
+/**
+ * Segmented duration input supporting unlimited and signed hours.
+ * @fires Timebox#change
+ * @extends {Component<TimeboxOptions>}
+ */
+export class Timebox extends Component {
+  static cssName = 'timebox';
+
+  /** @type {TimeboxOptions} */
+  static defaults = {
+    value: 0,
+    unit: 'minutes',
+    seconds: false,
+    signed: false,
+    disabled: false
+  };
+
+  /** @returns {HTMLElement} */
+  render() {
+    assertUnit(this.options.unit);
+    const root = /** @type {HTMLElement} */ (this.el ?? h('div'));
+    this.el = root;
+    this._originalAriaDisabled = root.getAttribute('aria-disabled');
+    this._disabled = Boolean(this.options.disabled);
+    this._parts = { hours: 0, minutes: 0, seconds: 0, negative: false };
+    this._inputs = [];
+    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'
+    });
+    this._content = content;
+
+    if (this.options.signed) {
+      content.append(h('button', {
+        ref: 'sign',
+        class: 'zx-timebox__sign',
+        type: 'button',
+        ariaLabel: 'Toggle duration sign',
+        ariaPressed: 'false'
+      }, '+'));
+      this.listen(this.refs.sign, 'click', () => {
+        if (this._disabled) return;
+        this._parts.negative = !this._parts.negative;
+        this._writeParts();
+        this._emitChange();
+      });
+    }
+
+    this._addSegment(content, 'hours', 'Hours', false);
+    content.append(h('span', { class: 'zx-timebox__separator', ariaHidden: 'true' }, ':'));
+    this._addSegment(content, 'minutes', 'Minutes', true);
+    if (this.options.seconds) {
+      content.append(h('span', { class: 'zx-timebox__separator', ariaHidden: 'true' }, ':'));
+      this._addSegment(content, 'seconds', 'Seconds', true);
+    }
+    root.append(content);
+    this.set(this.options.value, this.options.unit, { silent: true });
+    this._syncDisabled();
+    return root;
+  }
+
+  /**
+   * Returns the current duration.
+   * @param {TimeUnit} [unit=this.options.unit] Output unit.
+   * @returns {number}
+   */
+  get(unit = this.options.unit) {
+    return joinTime(this._readParts(), unit);
+  }
+
+  /**
+   * Sets the current duration.
+   * @param {number} value Duration value.
+   * @param {TimeUnit|TimeboxSetOptions} [unit=this.options.unit] Input unit, or options when omitted.
+   * @param {TimeboxSetOptions} [options={}] Update behavior.
+   * @returns {this}
+   * @fires Timebox#change
+   */
+  set(value, unit = this.options.unit, options = {}) {
+    if (unit && typeof unit === 'object') {
+      options = unit;
+      unit = this.options.unit;
+    }
+    assertUnit(unit);
+    let numeric = finiteNumber(value);
+    if (!this.options.signed && numeric < 0) numeric = 0;
+    if (!this.options.seconds) {
+      numeric = fromSeconds(Math.round(toSeconds(numeric, unit) / 60) * 60, unit);
+    }
+    this._parts = splitTime(numeric, unit);
+    if (!this.options.signed) this._parts.negative = false;
+    this._writeParts();
+    if (!options.silent) this._emitChange();
+    return this;
+  }
+
+  /** Enables the timebox. @returns {this} */
+  enable() {
+    this._disabled = false;
+    this._syncDisabled();
+    return this;
+  }
+
+  /** Disables the timebox. @returns {this} */
+  disable() {
+    this._disabled = true;
+    this._syncDisabled();
+    return this;
+  }
+
+  /** Removes generated content from an enhanced target. @returns {void} */
+  destroy() {
+    this._content?.remove();
+    if (this._originalAriaDisabled === null) this.el.removeAttribute('aria-disabled');
+    else this.el.setAttribute('aria-disabled', this._originalAriaDisabled);
+    super.destroy();
+  }
+
+  /** @param {HTMLElement} parent @param {'hours'|'minutes'|'seconds'} name @param {string} label @param {boolean} bounded @returns {void} */
+  _addSegment(parent, name, label, bounded) {
+    const input = h('input', {
+      class: 'zx-timebox__segment',
+      type: 'text',
+      inputMode: 'numeric',
+      autocomplete: 'off',
+      ariaLabel: label,
+      maxLength: bounded ? 2 : null,
+      dataset: { segment: name, bounded: String(bounded) }
+    });
+    this._inputs.push(input);
+    parent.append(input);
+    this.listen(input, 'focus', () => input.select());
+    this.listen(input, 'input', () => {
+      if (name === 'hours' && this.options.signed && input.value.trim().startsWith('-')) {
+        this._parts.negative = true;
+      }
+      const digits = input.value.replace(/\D/g, '');
+      input.value = bounded ? digits.slice(0, 2) : digits;
+    });
+    this.listen(input, 'change', () => this._commitSegments());
+    this.listen(input, 'keydown', (event) => {
+      if (event.key !== 'Enter') return;
+      event.preventDefault();
+      this._commitSegments();
+      input.select();
+    });
+  }
+
+  /** @returns {TimeParts} */
+  _readParts() {
+    const parts = { ...this._parts };
+    for (const input of this._inputs) {
+      const name = input.dataset.segment;
+      const maximum = input.dataset.bounded === 'true' ? 59 : Number.MAX_SAFE_INTEGER;
+      parts[name] = Math.max(0, Math.min(maximum, Math.trunc(finiteNumber(input.value))));
+    }
+    return parts;
+  }
+
+  /** @returns {void} */
+  _commitSegments() {
+    this._parts = this._readParts();
+    this._writeParts();
+    this._emitChange();
+  }
+
+  /** @returns {void} */
+  _writeParts() {
+    for (const input of this._inputs) {
+      const name = input.dataset.segment;
+      input.value = name === 'hours' ? String(this._parts[name]) : pad(this._parts[name]);
+    }
+    if (this.refs.sign) {
+      this.refs.sign.textContent = this._parts.negative ? '-' : '+';
+      this.refs.sign.setAttribute('aria-pressed', String(this._parts.negative));
+      this.refs.sign.dataset.state = this._parts.negative ? 'negative' : 'positive';
+    }
+  }
+
+  /** @returns {void} */
+  _syncDisabled() {
+    for (const input of this._inputs) input.disabled = this._disabled;
+    if (this.refs.sign) this.refs.sign.disabled = this._disabled;
+    this.el.setAttribute('aria-disabled', String(this._disabled));
+  }
+
+  /** @returns {void} */
+  _emitChange() {
+    this.emit('change', { value: this.get(this.options.unit) });
+  }
+}
+
+/** @event Timebox#change @type {CustomEvent<{value: number}>} */
+
+/** @param {unknown} value @returns {number} */
+function finiteNumber(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : 0;
+}
+
+/** @param {number} value @param {TimeUnit} unit @returns {number} */
+function toSeconds(value, unit) {
+  assertUnit(unit);
+  if (unit === 'hours') return value * 3600;
+  if (unit === 'minutes') return value * 60;
+  return value;
+}
+
+/** @param {number} value @param {TimeUnit} unit @returns {number} */
+function fromSeconds(value, unit) {
+  assertUnit(unit);
+  if (unit === 'hours') return value / 3600;
+  if (unit === 'minutes') return value / 60;
+  return value;
+}
+
+/** @param {unknown} unit @returns {asserts unit is TimeUnit} */
+function assertUnit(unit) {
+  if (unit !== 'hours' && unit !== 'minutes' && unit !== 'seconds') {
+    throw new RangeError(`Unknown time unit: ${unit}`);
+  }
+}
+
+/** @param {number} value @returns {string} */
+function pad(value) {
+  return String(value).padStart(2, '0');
+}

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

@@ -0,0 +1,24 @@
+import { Field } from '../field/field.js';
+import { Toggle } from './toggle.js';
+
+/**
+ * Registers the boolean `toggle` field type.
+ * @returns {void}
+ */
+export function registerToggleFieldAdapter() {
+  Field.register('toggle', (field, options) => {
+    const toggle = field.own(new Toggle(null, {
+      ...(options.props ?? {}),
+      checked: Boolean(options.value)
+    }));
+    field.listen(toggle.el, 'change', (event) => event.stopImmediatePropagation());
+    toggle.on('change', (event) => field.emit('change', { value: event.detail.value }));
+    return {
+      el: toggle.el,
+      get: () => toggle.getValue(),
+      set: (value) => toggle.set(Boolean(value), { silent: true }),
+      focus: () => toggle.el.focus(),
+      setDisabled: (disabled) => disabled ? toggle.disable() : toggle.enable()
+    };
+  });
+}

package/src/components/toggle/toggle.css

@@ -0,0 +1,66 @@
+.zx-toggle {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--zx-space-2);
+  min-block-size: var(--zx-control-height);
+  border: 0;
+  background: none;
+  color: var(--zx-color-text);
+  padding: 0;
+  font: inherit;
+  font-size: var(--zx-control-font-size);
+  cursor: pointer;
+}
+
+.zx-toggle:hover:not(:disabled) {
+  background: none;
+}
+
+.zx-toggle:focus-visible {
+  border-radius: var(--zx-control-radius);
+  box-shadow: var(--zx-focus-ring);
+}
+
+.zx-toggle:disabled {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+
+.zx-toggle__track {
+  display: block;
+  flex: none;
+  inline-size: 34px;
+  block-size: 20px;
+  border: 1px solid var(--zx-color-border-strong);
+  border-radius: var(--zx-radius-full);
+  background: var(--zx-color-bg-control);
+  padding: 2px;
+}
+
+.zx-toggle__thumb {
+  display: block;
+  inline-size: 14px;
+  block-size: 14px;
+  border-radius: var(--zx-radius-full);
+  background: var(--zx-color-text-muted);
+}
+
+.zx-toggle[aria-checked="true"] .zx-toggle__track {
+  border-color: var(--zx-color-accent);
+  background: var(--zx-color-accent);
+}
+
+.zx-toggle[aria-checked="true"] .zx-toggle__thumb {
+  background: var(--zx-color-on-accent);
+  transform: translateX(14px);
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .zx-toggle__track,
+  .zx-toggle__thumb {
+    transition:
+      background-color var(--zx-dur-fast) var(--zx-ease),
+      border-color var(--zx-dur-fast) var(--zx-ease),
+      transform var(--zx-dur-base) var(--zx-ease);
+  }
+}

package/src/components/toggle/toggle.js

@@ -0,0 +1,150 @@
+import { Component } from '../../core/component.js';
+import { h } from '../../core/dom.js';
+
+/**
+ * @typedef {Object} ToggleOptions
+ * @property {boolean} [checked=false] Initial switch state.
+ * @property {*} [value=true] Value returned while on.
+ * @property {string|null} [label=null] Optional visible label.
+ * @property {boolean} [disabled=false] Initial disabled state.
+ * @property {(event: CustomEvent<{checked: boolean, value: *}>) => void} [onchange] Change callback.
+ */
+
+/**
+ * Accessible on/off switch.
+ * @fires Toggle#change
+ * @extends {Component<ToggleOptions>}
+ */
+export class Toggle extends Component {
+  static cssName = 'toggle';
+
+  /** @type {Readonly<ToggleOptions>} */
+  static defaults = {
+    checked: false,
+    value: true,
+    label: null,
+    disabled: false
+  };
+
+  /** @returns {HTMLButtonElement} */
+  render() {
+    const created = !this.el;
+    const root = /** @type {HTMLButtonElement} */ (this.el ?? h('button'));
+    this.el = root;
+    if (root.localName !== 'button') throw new TypeError('Toggle target must be a button element');
+
+    this._createdRoot = created;
+    this._original = created ? null : snapshot(root);
+    this._checked = Boolean(this.options.checked);
+    this._disabled = Boolean(this.options.disabled);
+    root.type = 'button';
+    root.setAttribute('role', 'switch');
+    const children = [
+      h('span', { class: 'zx-toggle__track', ariaHidden: 'true' },
+        h('span', { class: 'zx-toggle__thumb' }))
+    ];
+    if (this.options.label !== null) {
+      children.push(h('span', { class: 'zx-toggle__label' }, String(this.options.label)));
+    }
+    root.replaceChildren(...children);
+    this._sync();
+    this.listen(root, 'click', () => this.toggle());
+    return root;
+  }
+
+  /**
+   * Returns the current switch state.
+   * @returns {boolean}
+   */
+  get() {
+    return this._checked;
+  }
+
+  /**
+   * Sets the switch state.
+   * @param {boolean} checked Next state.
+   * @param {{silent?: boolean}} [options={}] Set `silent` to suppress `change`.
+   * @returns {this}
+   * @fires Toggle#change
+   */
+  set(checked, { silent = false } = {}) {
+    const next = Boolean(checked);
+    if (next === this._checked) return this;
+    this._checked = next;
+    this._sync();
+    if (!silent) this.emit('change', { checked: this._checked, value: this.getValue() });
+    return this;
+  }
+
+  /**
+   * Toggles the switch state.
+   * @returns {this}
+   * @fires Toggle#change
+   */
+  toggle() {
+    return this.set(!this._checked);
+  }
+
+  /**
+   * Returns the configured value while on, otherwise `false`.
+   * @returns {*}
+   */
+  getValue() {
+    return this._checked ? this.options.value : false;
+  }
+
+  /**
+   * Enables user interaction.
+   * @returns {this}
+   */
+  enable() {
+    this._disabled = false;
+    this.el.removeAttribute('disabled');
+    return this;
+  }
+
+  /**
+   * Disables user interaction.
+   * @returns {this}
+   */
+  disable() {
+    this._disabled = true;
+    this.el.setAttribute('disabled', '');
+    return this;
+  }
+
+  /** @returns {void} */
+  destroy() {
+    if (this._cleaned) return;
+    this._cleaned = true;
+    super.destroy();
+    if (!this._createdRoot && this._original) restore(this.el, this._original);
+  }
+
+  /** @returns {void} */
+  _sync() {
+    this.el.setAttribute('aria-checked', String(this._checked));
+    this.el.toggleAttribute('disabled', this._disabled);
+  }
+}
+
+/**
+ * Change emitted after a real state transition.
+ * @event Toggle#change
+ * @type {CustomEvent<{checked: boolean, value: *}>}
+ */
+
+/** @param {Element} element @returns {{attributes: [string, string][], children: Node[]}} */
+function snapshot(element) {
+  return {
+    attributes: Array.from(element.attributes, (attribute) => [attribute.name, attribute.value]),
+    children: Array.from(element.childNodes)
+  };
+}
+
+/** @param {Element} element @param {{attributes: [string, string][], children: Node[]}} state */
+function restore(element, state) {
+  for (const attribute of Array.from(element.attributes)) element.removeAttribute(attribute.name);
+  for (const [name, value] of state.attributes) element.setAttribute(name, value);
+  element.replaceChildren(...state.children);
+}

package/src/components/toolbar/toolbar.css

@@ -0,0 +1,81 @@
+/*
+ * A single, non-wrapping row of controls. It never wraps on purpose: the component measures the
+ * row and moves what no longer fits into the trailing overflow menu, which is the wrapping-free
+ * replacement for the hand-rolled `.layout-toolbar` row in the website.
+ */
+.zx-toolbar {
+  display: flex;
+  flex-wrap: nowrap;
+  min-inline-size: 0;
+  align-items: center;
+  gap: var(--zx-space-2);
+}
+
+/* Items keep their intrinsic width so the measure pass can decide what fits — squashed controls
+   would hide the overflow instead of reporting it. */
+.zx-toolbar > * {
+  flex: 0 0 auto;
+}
+
+/* Pushes everything after it to the trailing edge (the `.layout-toolbar__spacer` role). */
+.zx-toolbar > .zx-toolbar__spacer {
+  flex: 1 1 auto;
+  min-inline-size: 0;
+}
+
+/* Collapsed items and the empty overflow trigger. The attribute selector outranks the `display`
+   declarations component CSS puts on buttons, which would otherwise defeat `hidden`. */
+.zx-toolbar > [hidden] {
+  display: none;
+}
+
+/* Only the collapsing toolbar clips: between a resize and the next measure pass a control can
+   momentarily stick out, and the clip margin keeps focus rings visible. */
+.zx-toolbar[data-overflow="true"] {
+  overflow: clip;
+  overflow-clip-margin: var(--zx-space-1);
+}
+
+.zx-toolbar[data-align="start"] {
+  justify-content: flex-start;
+}
+
+.zx-toolbar[data-align="end"] {
+  justify-content: flex-end;
+}
+
+.zx-toolbar[data-align="between"] {
+  justify-content: space-between;
+}
+
+.zx-toolbar[data-dense="true"] {
+  gap: var(--zx-space-1);
+}
+
+.zx-toolbar__separator,
+.zx-toolbar > [data-separator] {
+  flex: none;
+  align-self: stretch;
+  inline-size: 1px;
+  min-block-size: calc(var(--zx-control-height) - var(--zx-space-3));
+  margin-block: var(--zx-space-1);
+  border: 0;
+  background: var(--zx-color-border);
+}
+
+.zx-toolbar[data-dense="true"] .zx-toolbar__separator,
+.zx-toolbar[data-dense="true"] > [data-separator] {
+  margin-block: calc(var(--zx-space-1) / 2);
+}
+
+/* The overflow trigger is icon-only; its empty label would otherwise add a gap. */
+.zx-toolbar__overflow > .zx-btn__label:empty {
+  display: none;
+}
+
+/* Every item is reachable by keyboard, so every item rings — including the plain Elements a
+   caller supplied, which carry no Zx button styling of their own. */
+.zx-toolbar > :focus-visible,
+.zx-toolbar > [role="group"] > :focus-visible {
+  box-shadow: var(--zx-focus-ring);
+}