@zeyos/zx 2.1.0 → 2.2.0

package/src/components/truncate/truncate.css

@@ -0,0 +1,20 @@
+.zx-truncate {
+  min-inline-size: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/*
+ * `-webkit-line-clamp` is still the only clamp every target browser implements, and it needs the
+ * legacy flexbox display to take effect. `line-clamp` is listed alongside it so the rule stops
+ * needing the prefix as soon as the standard property ships.
+ */
+.zx-truncate[data-lines] {
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: var(--zx-truncate-lines, 2);
+  line-clamp: var(--zx-truncate-lines, 2);
+  white-space: normal;
+  overflow-wrap: anywhere;
+}

package/src/components/truncate/truncate.js

@@ -0,0 +1,92 @@
+import { resolveElement } from '../../core/dom.js';
+import { clamp } from '../../core/util.js';
+
+/**
+ * @typedef {Object} TruncateOptions
+ * @property {number} [lines=1] Lines to keep. One line ends in an ellipsis; more clamp the block.
+ * @property {boolean} [title=true] Whether a native `title` tooltip is set — and kept up to date —
+ *   while the text is actually cut off, so the full value stays reachable on hover.
+ */
+
+/**
+ * @typedef {Object} TruncateController
+ * @property {() => boolean} update Re-measures and returns whether the text is currently cut off.
+ * @property {() => boolean} isTruncated Whether the text was cut off at the last measurement.
+ * @property {() => void} destroy Removes the classes, the observer, and any title this set.
+ */
+
+/**
+ * Clamps an element's text to a number of lines, and gives the cut-off text back on hover.
+ *
+ * The `title` half is what makes this more than a CSS class. A table cell that silently drops the
+ * end of a value is a data-loss bug wearing a layout costume; a tooltip that is always present is
+ * noise. Measuring on every resize means the tooltip appears exactly when the text is short of
+ * room and disappears when the column is widened.
+ *
+ * @param {Element|string} target Element or selector to clamp.
+ * @param {TruncateOptions} [options={}] Truncation options.
+ * @returns {TruncateController}
+ */
+export function truncate(target, options = {}) {
+  const element = resolveElement(target);
+  if (!element) throw new TypeError('truncate() target could not be resolved');
+
+  const lines = clamp(Math.trunc(Number(options.lines) || 1), 1, 10);
+  const withTitle = options.title !== false;
+  const hadClass = element.classList.contains('zx-truncate');
+  const previousTitle = element.getAttribute('title');
+  let truncated = false;
+  let observer = null;
+
+  element.classList.add('zx-truncate');
+  if (lines > 1) {
+    element.dataset.lines = String(lines);
+    /** @type {HTMLElement} */ (element).style.setProperty('--zx-truncate-lines', String(lines));
+  }
+
+  const update = () => {
+    truncated = isTruncated(element);
+    if (withTitle) {
+      if (truncated) element.setAttribute('title', element.textContent?.trim() ?? '');
+      else if (previousTitle === null) element.removeAttribute('title');
+      else element.setAttribute('title', previousTitle);
+    }
+    return truncated;
+  };
+
+  update();
+  if (typeof ResizeObserver === 'function') {
+    observer = new ResizeObserver(update);
+    observer.observe(element);
+  }
+
+  return {
+    update,
+    isTruncated: () => truncated,
+    destroy: () => {
+      observer?.disconnect();
+      observer = null;
+      if (!hadClass) element.classList.remove('zx-truncate');
+      delete element.dataset.lines;
+      /** @type {HTMLElement} */ (element).style.removeProperty('--zx-truncate-lines');
+      if (!withTitle) return;
+      if (previousTitle === null) element.removeAttribute('title');
+      else element.setAttribute('title', previousTitle);
+    }
+  };
+}
+
+/**
+ * Whether an element's text overflows the box it is in.
+ *
+ * Both axes are checked because the two clamping modes overflow differently: a single line runs
+ * out of width, a multi-line clamp runs out of height. The one-pixel tolerance absorbs the
+ * sub-pixel difference between scroll and client sizes that fractional zoom levels produce.
+ *
+ * @param {Element} element Element to measure.
+ * @returns {boolean}
+ */
+export function isTruncated(element) {
+  return element.scrollWidth - element.clientWidth > 1
+    || element.scrollHeight - element.clientHeight > 1;
+}

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

@@ -0,0 +1,24 @@
+import { Field } from '../field/field.js';
+import { ValueList } from './value-list.js';
+
+/**
+ * Registers the ValueList-backed `valuelist` field type.
+ * @returns {void}
+ */
+export function registerValueListFieldAdapter() {
+  Field.register('valuelist', (field, options) => {
+    const valueList = field.own(new ValueList(null, {
+      ...(options.props ?? {}),
+      values: Array.isArray(options.value) ? options.value : []
+    }));
+    field.listen(valueList.el, 'change', (event) => event.stopImmediatePropagation());
+    valueList.on('change', (event) => field.emit('change', { value: event.detail.values }));
+    return {
+      el: valueList.el,
+      get: () => valueList.getValues(),
+      set: (value) => valueList.setValues(Array.isArray(value) ? value : [], { silent: true }),
+      focus: () => valueList.focus(),
+      setDisabled: (disabled) => disabled ? valueList.disable() : valueList.enable()
+    };
+  });
+}

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

@@ -0,0 +1,108 @@
+.zx-value-list {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--zx-space-2);
+  min-block-size: var(--zx-control-height);
+  padding: var(--zx-space-1);
+  border: 1px solid var(--zx-color-border-control);
+  border-radius: var(--zx-control-radius);
+  background: var(--zx-color-bg-control);
+}
+
+.zx-value-list:focus-within {
+  box-shadow: var(--zx-focus-ring);
+}
+
+.zx-value-list__list {
+  display: contents;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.zx-value-list__chip {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--zx-space-1);
+  min-block-size: calc(var(--zx-control-height) - var(--zx-space-2));
+  max-inline-size: 100%;
+  padding-inline: var(--zx-space-2);
+  border: 1px solid var(--zx-color-border);
+  border-radius: var(--zx-radius-full);
+  background: var(--zx-color-bg-selected);
+  color: var(--zx-color-text);
+  cursor: grab;
+}
+
+.zx-value-list__chip:focus-visible {
+  box-shadow: var(--zx-focus-ring);
+}
+
+.zx-value-list__value {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  text-wrap: nowrap;
+}
+
+.zx-value-list__remove {
+  display: inline-grid;
+  place-items: center;
+  min-inline-size: 1.25rem;
+  min-block-size: 1.25rem;
+  border-radius: var(--zx-radius-full);
+  color: var(--zx-color-text-muted);
+  cursor: pointer;
+}
+
+.zx-value-list__remove:hover {
+  background: var(--zx-color-bg-hover);
+  color: var(--zx-color-danger);
+}
+
+.zx-value-list__input {
+  flex: 1 1 8rem;
+  min-inline-size: 6rem;
+  border: 0;
+  background: inherit;
+  box-shadow: none;
+}
+
+.zx-value-list__input:focus-visible {
+  box-shadow: none;
+}
+
+.zx-value-list__status {
+  flex-basis: 100%;
+  color: var(--zx-color-danger);
+  font-size: var(--zx-text-sm);
+}
+
+.zx-value-list__status:empty {
+  display: none;
+}
+
+.zx-value-list__instructions {
+  position: absolute;
+  inline-size: 1px;
+  block-size: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+}
+
+.zx-value-list[data-state="dragging"] .zx-value-list__chip {
+  cursor: grabbing;
+}
+
+.zx-value-list[data-disabled="true"] {
+  background: var(--zx-color-bg-page);
+  opacity: 0.65;
+}
+
+.zx-value-list[data-disabled="true"] .zx-value-list__chip {
+  cursor: default;
+}
+
+.zx-value-list[data-disabled="true"] .zx-value-list__remove {
+  display: none;
+}

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

@@ -0,0 +1,336 @@
+import { Component } from '../../core/component.js';
+import { h } from '../../core/dom.js';
+import { uid } from '../../core/util.js';
+
+/**
+ * @typedef {Object} ValueListOptions
+ * @property {unknown[]} [values=[]] Initial ordered values.
+ * @property {string} [placeholder=''] Input placeholder.
+ * @property {boolean} [deletable=true] Whether values can be removed.
+ * @property {boolean} [sortable=true] Whether values can be reordered.
+ * @property {boolean} [unique=true] Whether duplicate strings are rejected.
+ * @property {((value: string) => boolean|string)|null} [validate=null] Value validator.
+ */
+
+/**
+ * Tag/chip editor. It uses the APG listbox/option focus model: each chip is an option, arrow keys
+ * move focus, Ctrl+Left/Right reorders, and Delete/Backspace removes the focused option.
+ * @fires ValueList#change
+ * @fires ValueList#add
+ * @fires ValueList#remove
+ * @extends {Component<ValueListOptions>}
+ */
+export class ValueList extends Component {
+  static cssName = 'value-list';
+
+  /** @type {ValueListOptions} */
+  static defaults = {
+    values: [],
+    placeholder: '',
+    deletable: true,
+    sortable: true,
+    unique: true,
+    validate: null
+  };
+
+  /** @returns {HTMLElement} */
+  render() {
+    const root = /** @type {HTMLElement} */ (this.el ?? h('div'));
+    this._ownedNodes = [];
+    this._disabled = false;
+    this._dragIndex = -1;
+    this._initialState = root.getAttribute('data-state');
+    this._initialDisabled = root.getAttribute('data-disabled');
+    this._values = normalizeValues(this.options.values, Boolean(this.options.unique));
+    const instructionsId = uid('zx-value-list-instructions');
+    this._list = h('ul', {
+      class: 'zx-value-list__list',
+      role: 'listbox',
+      ariaLabel: 'Values',
+      ariaOrientation: 'horizontal'
+    });
+    this._input = h('input', {
+      class: 'zx-value-list__input',
+      type: 'text',
+      placeholder: String(this.options.placeholder ?? ''),
+      ariaLabel: 'Add value',
+      ariaDescribedby: instructionsId
+    });
+    this._status = h('div', {
+      class: 'zx-value-list__status',
+      role: 'status',
+      ariaLive: 'polite'
+    });
+    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._ownedNodes.push(this._list, this._input, this._status, this._instructions);
+    root.append(this._list, this._input, this._status, this._instructions);
+
+    this.listen(this._input, 'keydown', (event) => this._handleInputKeydown(event));
+    this.listen(this._list, 'keydown', (event) => this._handleChipKeydown(event));
+    this.listen(this._list, 'click', (event) => this._handleChipClick(event));
+    this.listen(this._list, 'dragstart', (event) => this._handleDragStart(event));
+    this.listen(this._list, 'dragover', (event) => {
+      if (this._dragIndex >= 0 && !this._disabled) event.preventDefault();
+    });
+    this.listen(this._list, 'drop', (event) => this._handleDrop(event));
+    this.listen(this._list, 'dragend', () => this._finishDrag());
+    this.listen(root, 'click', (event) => {
+      if (event.target === root && !this._disabled) this.focus();
+    });
+    this._renderChips();
+    return root;
+  }
+
+  /**
+   * Returns a copy of the ordered values.
+   * @returns {string[]}
+   */
+  getValues() {
+    return this._values.slice();
+  }
+
+  /**
+   * Replaces all values.
+   * @param {unknown[]} values New values.
+   * @param {{silent?: boolean}} [options={}] Set `silent` to suppress `change`.
+   * @returns {this}
+   */
+  setValues(values, { silent = false } = {}) {
+    this._values = normalizeValues(values, Boolean(this.options.unique));
+    this._renderChips();
+    if (!silent) this.emit('change', { values: this.getValues() });
+    return this;
+  }
+
+  /**
+   * Validates and appends one value.
+   * @param {unknown} value Value to append.
+   * @returns {boolean} Whether the value was added.
+   * @fires ValueList#add
+   * @fires ValueList#change
+   */
+  addValue(value) {
+    if (this._disabled) return false;
+    const normalized = String(value ?? '').trim();
+    if (!normalized) return false;
+    if (this.options.unique && this._values.includes(normalized)) {
+      this._showError('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.');
+        return false;
+      }
+    }
+    this._status.textContent = '';
+    this._input.removeAttribute('aria-invalid');
+    this._values.push(normalized);
+    this._renderChips();
+    this.emit('add', { value: normalized });
+    this.emit('change', { values: this.getValues() });
+    return true;
+  }
+
+  /**
+   * Removes the first matching value.
+   * @param {unknown} value Value to remove.
+   * @returns {boolean} Whether a value was removed.
+   * @fires ValueList#remove
+   * @fires ValueList#change
+   */
+  removeValue(value) {
+    if (this._disabled || !this.options.deletable) return false;
+    const index = this._values.indexOf(String(value));
+    if (index < 0) return false;
+    this._removeAt(index);
+    return true;
+  }
+
+  /**
+   * Focuses the value input.
+   * @returns {this}
+   */
+  focus() {
+    this._input.focus();
+    return this;
+  }
+
+  /**
+   * Enables editing.
+   * @returns {this}
+   */
+  enable() {
+    this._disabled = false;
+    this._input.disabled = false;
+    this.el.dataset.disabled = 'false';
+    this._renderChips();
+    return this;
+  }
+
+  /**
+   * Disables editing, removal, and reordering.
+   * @returns {this}
+   */
+  disable() {
+    this._disabled = true;
+    this._input.disabled = true;
+    this.el.dataset.disabled = 'true';
+    this._renderChips();
+    return this;
+  }
+
+  /** @returns {void} */
+  _renderChips(focusIndex = -1) {
+    const chips = this._values.map((value, index) => h('li', {
+      class: 'zx-value-list__chip',
+      role: 'option',
+      tabIndex: this._disabled ? -1 : 0,
+      draggable: Boolean(this.options.sortable) && !this._disabled,
+      ariaSelected: 'false',
+      ariaDisabled: String(this._disabled),
+      ariaLabel: this.options.deletable ? `${value}. Press Delete to remove.` : value,
+      dataset: { index }
+    }, h('span', { class: 'zx-value-list__value' }, value), this.options.deletable ? h('span', {
+      class: 'zx-value-list__remove',
+      dataset: { remove: '' },
+      ariaHidden: 'true'
+    }, '×') : null));
+    this._list.replaceChildren(...chips);
+    if (focusIndex >= 0) chips[Math.min(focusIndex, chips.length - 1)]?.focus();
+  }
+
+  /** @param {KeyboardEvent} event @returns {void} */
+  _handleInputKeydown(event) {
+    if (this._disabled) return;
+    if (event.key === 'Enter') {
+      event.preventDefault();
+      if (this.addValue(this._input.value)) this._input.value = '';
+    } else if (event.key === 'Backspace' && this._input.value === '' && this._values.length && this.options.deletable) {
+      event.preventDefault();
+      this._removeAt(this._values.length - 1);
+    }
+  }
+
+  /** @param {KeyboardEvent} event @returns {void} */
+  _handleChipKeydown(event) {
+    if (this._disabled) return;
+    const chip = event.target instanceof Element ? event.target.closest('[data-index]') : null;
+    if (!chip) return;
+    const index = Number(chip.dataset.index);
+    if ((event.key === 'Delete' || event.key === 'Backspace') && this.options.deletable) {
+      event.preventDefault();
+      this._removeAt(index, Math.min(index, this._values.length - 2));
+      return;
+    }
+    const horizontal = event.key === 'ArrowLeft' ? -1 : event.key === 'ArrowRight' ? 1 : 0;
+    const vertical = event.key === 'ArrowUp' ? -1 : event.key === 'ArrowDown' ? 1 : 0;
+    const direction = horizontal || vertical;
+    if (!direction) return;
+    event.preventDefault();
+    const next = Math.max(0, Math.min(this._values.length - 1, index + direction));
+    if (event.ctrlKey && horizontal && this.options.sortable) this._move(index, next, true);
+    else this._list.querySelector(`[data-index="${next}"]`)?.focus();
+  }
+
+  /** @param {MouseEvent} event @returns {void} */
+  _handleChipClick(event) {
+    const target = event.target instanceof Element ? event.target : null;
+    const chip = target?.closest('[data-index]');
+    if (!chip || this._disabled) return;
+    if (target.closest('[data-remove]') && this.options.deletable) this._removeAt(Number(chip.dataset.index));
+    else chip.focus();
+  }
+
+  /** @param {DragEvent} event @returns {void} */
+  _handleDragStart(event) {
+    if (this._disabled || !this.options.sortable) return;
+    const chip = event.target instanceof Element ? event.target.closest('[data-index]') : null;
+    if (!chip) return;
+    this._dragIndex = Number(chip.dataset.index);
+    this.el.dataset.state = 'dragging';
+    event.dataTransfer?.setData('text/plain', String(this._dragIndex));
+    if (event.dataTransfer) event.dataTransfer.effectAllowed = 'move';
+  }
+
+  /** @param {DragEvent} event @returns {void} */
+  _handleDrop(event) {
+    if (this._dragIndex < 0 || this._disabled) return;
+    event.preventDefault();
+    const chip = event.target instanceof Element ? event.target.closest('[data-index]') : null;
+    const target = chip ? Number(chip.dataset.index) : this._values.length - 1;
+    this._move(this._dragIndex, target, true);
+    this._finishDrag();
+  }
+
+  /** @returns {void} */
+  _finishDrag() {
+    this._dragIndex = -1;
+    if (this._initialState === null) this.el.removeAttribute('data-state');
+    else this.el.setAttribute('data-state', this._initialState);
+  }
+
+  /** @param {number} start @param {number} end @param {boolean} focus @returns {void} */
+  _move(start, end, focus) {
+    if (start === end || start < 0 || end < 0 || start >= this._values.length || end >= this._values.length) return;
+    const [value] = this._values.splice(start, 1);
+    this._values.splice(end, 0, value);
+    this._renderChips(focus ? end : -1);
+    this.emit('change', { values: this.getValues() });
+  }
+
+  /** @param {number} index @param {number} [focusIndex=-1] @returns {void} */
+  _removeAt(index, focusIndex = -1) {
+    const [value] = this._values.splice(index, 1);
+    if (value === undefined) return;
+    this._renderChips(focusIndex);
+    if (focusIndex < 0 && this._values.length === 0) this._input.focus();
+    this.emit('remove', { value });
+    this.emit('change', { values: this.getValues() });
+  }
+
+  /** @param {string} message @returns {void} */
+  _showError(message) {
+    this._status.textContent = message;
+    this._input.setAttribute('aria-invalid', 'true');
+  }
+
+  /** @returns {void} */
+  destroy() {
+    for (const node of this._ownedNodes ?? []) node.remove();
+    if (this._initialState === null) this.el.removeAttribute('data-state');
+    else this.el.setAttribute('data-state', this._initialState);
+    if (this._initialDisabled === null) this.el.removeAttribute('data-disabled');
+    else this.el.setAttribute('data-disabled', this._initialDisabled);
+    super.destroy();
+  }
+}
+
+/** @param {unknown} values @param {boolean} unique @returns {string[]} */
+function normalizeValues(values, unique) {
+  if (!Array.isArray(values)) return [];
+  const normalized = values.map((value) => String(value));
+  return unique ? [...new Set(normalized)] : normalized;
+}
+
+/**
+ * Values changed event.
+ * @event ValueList#change
+ * @type {CustomEvent<{values: string[]}>
+ */
+
+/**
+ * Value added event.
+ * @event ValueList#add
+ * @type {CustomEvent<{value: string}>
+ */
+
+/**
+ * Value removed event.
+ * @event ValueList#remove
+ * @type {CustomEvent<{value: string}>
+ */