@zeyos/zx 2.1.0 → 2.2.1

package/src/components/form/form.js

@@ -0,0 +1,302 @@
+import { Component } from '../../core/component.js';
+import { h } from '../../core/dom.js';
+import { icon as createIcon } from '../../core/icons.js';
+import { Fieldset } from '../fieldset/fieldset.js';
+import { coerceFloat, coerceInteger } from '../field/field.js';
+
+/**
+ * @typedef {Object} FormAction
+ * @property {string} [id] Action identifier.
+ * @property {string} [label] Button text.
+ * @property {string|null} [icon=null] Kernel icon name.
+ * @property {'default'|'primary'|'danger'|'ghost'} [kind='default'] Visual intent.
+ * @property {'md'|'sm'} [size='md'] Button size.
+ * @property {'button'|'submit'|'reset'} [type='button'] Native button type.
+ * @property {boolean} [disabled=false] Disabled state.
+ * @property {string} [title] Native button title.
+ * @property {(event: MouseEvent, form: Form) => void} [onClick] Click callback.
+ */
+
+/**
+ * @typedef {Object} FormOptions
+ * @property {Array<Fieldset|import('../fieldset/fieldset.js').FieldsetOptions>} [fieldsets=[]] Initial fieldsets.
+ * @property {FormAction[]} [actions=[]] Form action descriptors.
+ * @property {boolean} [novalidate=true] Native `novalidate` state.
+ */
+
+/**
+ * Real form element coordinating fieldsets, validation, and actions.
+ * @fires Form#submit
+ * @fires Form#invalid
+ * @fires Form#change
+ * @extends {Component<FormOptions>}
+ */
+export class Form extends Component {
+  static cssName = 'form';
+
+  /** @type {FormOptions & {msg: Record<string, string>}} */
+  static defaults = {
+    fieldsets: [],
+    actions: [],
+    novalidate: true,
+    msg: {
+      'form.required': 'This field is required.',
+      'form.int': 'Enter a whole number.',
+      'form.float': 'Enter a valid number.'
+    }
+  };
+
+  /** @returns {HTMLElement} */
+  render() {
+    const root = /** @type {HTMLElement} */ (this.el ?? h('form'));
+    this._fieldsets = [];
+    this._ownedFieldsets = new Set();
+    this._origins = new Map();
+    this._ownedNodes = [];
+    this._novalidateAttribute = root.getAttribute('novalidate');
+    root.toggleAttribute('novalidate', Boolean(this.options.novalidate));
+
+    this._body = h('div', { class: 'zx-form__body' });
+    this._actions = h('div', { class: 'zx-form__actions' });
+    this._ownedNodes.push(this._body, this._actions);
+    root.append(this._body, this._actions);
+
+    this.listen(root, 'submit', (event) => {
+      event.preventDefault();
+      this.submit();
+    });
+    this.listen(root, 'reset', (event) => {
+      event.preventDefault();
+      this.reset();
+    });
+    this.listen(this._actions, 'click', (event) => this._handleAction(event));
+
+    const fieldsets = Array.isArray(this.options.fieldsets) ? this.options.fieldsets : [];
+    for (const fieldset of fieldsets) this.addFieldset(fieldset);
+    this.setActions(Array.isArray(this.options.actions) ? this.options.actions : []);
+    return root;
+  }
+
+  /**
+   * Adds an existing fieldset or constructs one from options.
+   * @param {Fieldset|import('../fieldset/fieldset.js').FieldsetOptions} fieldset Fieldset source.
+   * @returns {Fieldset}
+   */
+  addFieldset(fieldset) {
+    const owned = !(fieldset instanceof Fieldset);
+    const instance = owned ? new Fieldset(null, fieldset ?? {}) : fieldset;
+    if (this._fieldsets.includes(instance)) return instance;
+    if (owned) this._ownedFieldsets.add(instance);
+    else this._origins.set(instance, { parent: instance.el.parentNode, next: instance.el.nextSibling });
+    this._fieldsets.push(instance);
+    this._body.append(instance.el);
+    this.listen(instance.el, 'zx-change', (event) => {
+      const target = event.target;
+      const id = target instanceof Element ? target.dataset.fieldId : null;
+      if (id) this.emit('change', { id, value: instance.getValue(id) });
+    });
+    return instance;
+  }
+
+  /**
+   * Replaces the rendered action buttons.
+   * @param {FormAction[]} list Button descriptors.
+   * @returns {this}
+   */
+  setActions(list) {
+    this._actionDescriptors = Array.isArray(list) ? list.map((action) => ({ ...action })) : [];
+    this._actions.replaceChildren(...this._actionDescriptors.map((action, index) => {
+      const label = String(action.label ?? action.id ?? 'Action');
+      return h('button', {
+        class: 'zx-btn',
+        type: ['submit', 'reset'].includes(action.type) ? action.type : 'button',
+        disabled: Boolean(action.disabled),
+        title: action.title,
+        ariaLabel: !label && action.title ? action.title : undefined,
+        dataset: {
+          actionIndex: index,
+          kind: ['primary', 'danger', 'ghost'].includes(action.kind) ? action.kind : 'default',
+          size: action.size === 'sm' ? 'sm' : 'md'
+        }
+      }, action.icon ? createIcon(action.icon, { size: 16 }) : null,
+      label ? h('span', { class: 'zx-btn__label' }, label) : null);
+    }));
+    this._actions.hidden = this._actionDescriptors.length === 0;
+    return this;
+  }
+
+  /**
+   * Returns all values merged in fieldset order.
+   * @returns {Record<string, unknown>}
+   */
+  getValues() {
+    return Object.assign({}, ...this._fieldsets.map((fieldset) => fieldset.getValues()));
+  }
+
+  /**
+   * Sets matching values across all fieldsets.
+   * @param {Record<string, unknown>} values Values keyed by field identifier.
+   * @param {{silent?: boolean}} [options={}] Set `silent` to suppress field change events.
+   * @returns {this}
+   */
+  setValues(values, { silent = false } = {}) {
+    for (const fieldset of this._fieldsets) fieldset.setValues(values, { silent });
+    return this;
+  }
+
+  /**
+   * Returns the first matching field.
+   * @param {string} id Field identifier.
+   * @returns {import('../field/field.js').Field|null}
+   */
+  getField(id) {
+    for (const fieldset of this._fieldsets) {
+      const field = fieldset.getField(id);
+      if (field) return field;
+    }
+    return null;
+  }
+
+  /**
+   * Sets one matching field value.
+   * @param {string} id Field identifier.
+   * @param {unknown} value New value.
+   * @returns {this}
+   */
+  setValue(id, value) {
+    this.getField(id)?.setValue(value);
+    return this;
+  }
+
+  /**
+   * Returns one matching field value.
+   * @param {string} id Field identifier.
+   * @returns {unknown}
+   */
+  getValue(id) {
+    return this.getField(id)?.getValue() ?? null;
+  }
+
+  /**
+   * Resets all fieldsets and highlights.
+   * @returns {this}
+   */
+  reset() {
+    for (const fieldset of this._fieldsets) fieldset.reset().clearHighlights();
+    return this;
+  }
+
+  /**
+   * Applies field highlights across all fieldsets.
+   * @param {Record<string, string>} highlights Messages keyed by field identifier.
+   * @param {'danger'|'warning'|'success'} [kind='danger'] Highlight kind.
+   * @returns {number}
+   */
+  setHighlights(highlights, kind = 'danger') {
+    return this._fieldsets.reduce((count, fieldset) => count + fieldset.setHighlights(highlights, kind), 0);
+  }
+
+  /**
+   * Clears all field highlights.
+   * @returns {this}
+   */
+  clearHighlights() {
+    for (const fieldset of this._fieldsets) fieldset.clearHighlights();
+    return this;
+  }
+
+  /**
+   * Validates and emits a preventable submit event.
+   * @returns {boolean} True when valid and not prevented.
+   * @fires Form#submit
+   * @fires Form#invalid
+   */
+  submit() {
+    const errors = {};
+    let firstInvalid = null;
+    for (const fieldset of this._fieldsets) {
+      for (const [id, field] of Object.entries(fieldset.getFields())) {
+        const value = field.getValue();
+        let message = '';
+        if (field.options.required && isEmpty(value)) {
+          message = this.msg('form.required');
+        } else if (!isEmpty(value) && field.options.type === 'int') {
+          const result = coerceInteger(value);
+          if (!result.valid) message = this.msg('form.int');
+          else field.setValue(result.value, { silent: true });
+        } else if (!isEmpty(value) && field.options.type === 'float') {
+          const result = coerceFloat(value);
+          if (!result.valid) message = this.msg('form.float');
+          else field.setValue(result.value, { silent: true });
+        }
+        if (message) {
+          errors[id] = message;
+          field.setHighlight(message, 'danger');
+          firstInvalid ??= field;
+        } else {
+          field.clearHighlight();
+        }
+      }
+    }
+
+    if (Object.keys(errors).length) {
+      this.emit('invalid', { errors });
+      firstInvalid?.focus();
+      return false;
+    }
+    const event = this.emit('submit', { values: this.getValues() });
+    return !event.defaultPrevented;
+  }
+
+  /** @param {Event} event @returns {void} */
+  _handleAction(event) {
+    const button = event.target instanceof Element ? event.target.closest('[data-action-index]') : null;
+    if (!button || !this._actions.contains(button)) return;
+    const action = this._actionDescriptors[Number(button.dataset.actionIndex)];
+    const callback = action?.onClick ?? action?.onclick ?? action?.handler;
+    if (typeof callback === 'function') callback(event, this);
+  }
+
+  /** @returns {void} */
+  destroy() {
+    for (const fieldset of this._fieldsets ?? []) {
+      if (this._ownedFieldsets.has(fieldset)) fieldset.destroy();
+      else {
+        const origin = this._origins.get(fieldset);
+        if (origin?.parent) origin.parent.insertBefore(
+          fieldset.el,
+          origin.next?.parentNode === origin.parent ? origin.next : null
+        );
+        else fieldset.el.remove();
+      }
+    }
+    this._fieldsets = [];
+    for (const node of this._ownedNodes ?? []) node.remove();
+    if (this._novalidateAttribute === null) this.el.removeAttribute('novalidate');
+    else this.el.setAttribute('novalidate', this._novalidateAttribute);
+    super.destroy();
+  }
+}
+
+/** @param {unknown} value @returns {boolean} */
+function isEmpty(value) {
+  return value == null || value === '' || value === false || (Array.isArray(value) && value.length === 0);
+}
+
+/**
+ * Successful form submission event.
+ * @event Form#submit
+ * @type {CustomEvent<{values: Record<string, unknown>}>
+ */
+
+/**
+ * Form validation failure event.
+ * @event Form#invalid
+ * @type {CustomEvent<{errors: Record<string, string>}>
+ */
+
+/**
+ * Delegated field value change event.
+ * @event Form#change
+ * @type {CustomEvent<{id: string, value: unknown}>
+ */

package/src/components/groupbox/groupbox.css

@@ -0,0 +1,51 @@
+.zx-groupbox {
+  overflow: hidden;
+  border: 1px solid var(--zx-color-border);
+  border-radius: var(--zx-radius-lg);
+  background: var(--zx-color-bg-surface);
+}
+
+.zx-groupbox__summary {
+  display: flex;
+  align-items: center;
+  gap: var(--zx-space-2);
+  min-block-size: var(--zx-control-height);
+  padding: var(--zx-space-2) var(--zx-space-4);
+  font-weight: 650;
+  cursor: pointer;
+  user-select: none;
+}
+
+.zx-groupbox__summary::-webkit-details-marker {
+  display: none;
+}
+
+.zx-groupbox__summary:hover {
+  background: var(--zx-color-bg-hover);
+}
+
+.zx-groupbox__summary:focus-visible {
+  box-shadow: var(--zx-focus-ring);
+}
+
+.zx-groupbox__chevron {
+  display: inline-grid;
+  flex: none;
+  place-items: center;
+  color: var(--zx-color-text-muted);
+}
+
+.zx-groupbox[open] .zx-groupbox__chevron {
+  transform: rotate(90deg);
+}
+
+.zx-groupbox__content {
+  border-block-start: 1px solid var(--zx-color-border);
+  padding: var(--zx-space-4);
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .zx-groupbox__chevron {
+    transition: transform var(--zx-dur-fast) var(--zx-ease);
+  }
+}

package/src/components/groupbox/groupbox.js

@@ -0,0 +1,199 @@
+import { Component } from '../../core/component.js';
+import { h, resolveElement } from '../../core/dom.js';
+import { icon } from '../../core/icons.js';
+
+/**
+ * @typedef {Object} GroupboxOptions
+ * @property {string} [title=''] Section title.
+ * @property {boolean} [open=true] Initial expanded state.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open callback.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onclose] Close callback.
+ */
+
+/** @typedef {string|Node|Component} GroupboxContent */
+
+/**
+ * Collapsible section backed by native details and summary elements.
+ * @fires Groupbox#open
+ * @fires Groupbox#close
+ * @extends {Component<GroupboxOptions>}
+ */
+export class Groupbox extends Component {
+  static cssName = 'groupbox';
+
+  /** @type {Readonly<GroupboxOptions>} */
+  static defaults = { title: '', open: true };
+
+  /**
+   * Creates or adopts a native details section.
+   * @param {Element|string|null} target Existing details, plain container, selector, or null.
+   * @param {GroupboxOptions} [options={}] Groupbox options.
+   */
+  constructor(target, options = {}) {
+    let normalizedTarget = target;
+    let adoption = null;
+    if (target !== null) {
+      const resolved = resolveElement(target);
+      if (resolved && resolved.localName !== 'details') {
+        const details = document.createElement('details');
+        const children = Array.from(resolved.childNodes);
+        const parent = resolved.parentNode;
+        const next = resolved.nextSibling;
+        if (parent) parent.insertBefore(details, resolved);
+        details.append(...children);
+        resolved.remove();
+        adoption = { original: resolved, details, children, parent, next };
+        normalizedTarget = details;
+      }
+    }
+
+    try {
+      super(normalizedTarget, options);
+    } catch (error) {
+      if (adoption) restoreAdoption(adoption);
+      throw error;
+    }
+    this._adoption = adoption;
+  }
+
+  /** @returns {HTMLDetailsElement} */
+  render() {
+    const created = !this.el;
+    const details = /** @type {HTMLDetailsElement} */ (this.el ?? h('details'));
+    if (details.localName !== 'details') throw new TypeError('Groupbox requires a details element');
+
+    this._createdRoot = created;
+    this._original = created ? null : snapshot(details);
+    const contentNodes = Array.from(details.childNodes).filter((node) =>
+      !(node.nodeType === 1 && /** @type {Element} */ (node).localName === 'summary')
+    );
+    const summary = h('summary', { class: 'zx-groupbox__summary', ref: 'summary' },
+      h('span', { class: 'zx-groupbox__chevron', ariaHidden: 'true' },
+        icon('chevron-right', { size: 16 })
+      ),
+      h('span', { class: 'zx-groupbox__title', ref: 'title' }, String(this.options.title))
+    );
+    const content = h('div', { class: 'zx-groupbox__content', ref: 'content' }, contentNodes);
+    details.replaceChildren(summary, content);
+    details.open = Boolean(this.options.open);
+    this._lastOpen = details.open;
+    this.listen(details, 'toggle', () => {
+      const open = details.open;
+      if (open === this._lastOpen) return;
+      this._lastOpen = open;
+      this.emit(open ? 'open' : 'close');
+    });
+    return details;
+  }
+
+  /**
+   * Expands the section.
+   * @returns {this}
+   */
+  open() {
+    this.el.setAttribute('open', '');
+    return this;
+  }
+
+  /**
+   * Collapses the section.
+   * @returns {this}
+   */
+  close() {
+    this.el.removeAttribute('open');
+    return this;
+  }
+
+  /**
+   * Toggles the section.
+   * @returns {this}
+   */
+  toggle() {
+    return this.isOpen() ? this.close() : this.open();
+  }
+
+  /**
+   * Reports whether the section is expanded.
+   * @returns {boolean}
+   */
+  isOpen() {
+    return /** @type {HTMLDetailsElement} */ (this.el).open;
+  }
+
+  /**
+   * Replaces the visible title.
+   * @param {string} title Next title.
+   * @returns {this}
+   */
+  setTitle(title) {
+    this.refs.title.textContent = String(title);
+    return this;
+  }
+
+  /**
+   * Replaces the section body.
+   * @param {GroupboxContent} content Next text, node, or component.
+   * @returns {this}
+   */
+  setContent(content) {
+    const node = content instanceof Component ? content.toElement() : content;
+    this.refs.content.replaceChildren();
+    if (typeof node === 'string') this.refs.content.append(document.createTextNode(node));
+    else if (node && typeof node.nodeType === 'number') this.refs.content.append(node);
+    else throw new TypeError('Groupbox content must be a string, Node, or Component');
+    return this;
+  }
+
+  /** @returns {void} */
+  destroy() {
+    if (this._cleaned) return;
+    this._cleaned = true;
+    super.destroy();
+    if (this._adoption) {
+      restoreAdoption(this._adoption);
+    } else if (!this._createdRoot && this._original) {
+      restore(this.el, this._original);
+    }
+  }
+}
+
+/**
+ * Emitted when the native details element opens.
+ * @event Groupbox#open
+ * @type {CustomEvent<Record<string, never>>}
+ */
+
+/**
+ * Emitted when the native details element closes.
+ * @event Groupbox#close
+ * @type {CustomEvent<Record<string, never>>}
+ */
+
+/** @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);
+}
+
+/**
+ * @param {{original: Element, details: Element, children: Node[], parent: Node|null, next: Node|null}} state
+ * @returns {void}
+ */
+function restoreAdoption(state) {
+  state.original.replaceChildren(...state.children);
+  if (state.details.parentNode) {
+    state.details.replaceWith(state.original);
+  } else if (state.parent) {
+    const reference = state.next?.parentNode === state.parent ? state.next : null;
+    state.parent.insertBefore(state.original, reference);
+  }
+}

package/src/components/layout/layout.css

@@ -0,0 +1,117 @@
+.zx-stack {
+  --zx-stack-gap: var(--zx-space-4);
+
+  display: flex;
+  flex-direction: column;
+  gap: var(--zx-stack-gap);
+  min-inline-size: 0;
+}
+
+.zx-stack[data-inline] {
+  display: inline-flex;
+}
+
+.zx-stack[data-direction="row"] {
+  flex-direction: row;
+  align-items: center;
+}
+
+.zx-stack[data-wrap] {
+  flex-wrap: wrap;
+}
+
+.zx-stack[data-align="start"] {
+  align-items: flex-start;
+}
+
+.zx-stack[data-align="center"] {
+  align-items: center;
+}
+
+.zx-stack[data-align="end"] {
+  align-items: flex-end;
+}
+
+.zx-stack[data-align="stretch"] {
+  align-items: stretch;
+}
+
+.zx-stack[data-align="baseline"] {
+  align-items: baseline;
+}
+
+.zx-stack[data-justify="start"] {
+  justify-content: flex-start;
+}
+
+.zx-stack[data-justify="center"] {
+  justify-content: center;
+}
+
+.zx-stack[data-justify="end"] {
+  justify-content: flex-end;
+}
+
+.zx-stack[data-justify="between"] {
+  justify-content: space-between;
+}
+
+.zx-stack[data-justify="around"] {
+  justify-content: space-around;
+}
+
+.zx-grid {
+  --zx-grid-gap: var(--zx-space-4);
+  --zx-grid-min: 16rem;
+
+  display: grid;
+  gap: var(--zx-grid-gap);
+  /* `min(…, 100%)` keeps a track from overflowing a container narrower than the minimum itself. */
+  grid-template-columns: repeat(auto-fit, minmax(min(var(--zx-grid-min), 100%), 1fr));
+  min-inline-size: 0;
+}
+
+/*
+ * With a column count, each track asks for its share of the row but never less than
+ * `--zx-grid-min`, so `auto-fit` lays out the requested columns while there is room for them and
+ * drops one at a time as the container narrows — no media query, and the same behaviour inside a
+ * split pane as on a full-width page.
+ */
+.zx-grid[data-columns] {
+  grid-template-columns: repeat(auto-fit, minmax(
+    max(
+      min(var(--zx-grid-min), 100%),
+      calc((100% - (var(--zx-grid-columns) - 1) * var(--zx-grid-gap)) / var(--zx-grid-columns))
+    ),
+    1fr
+  ));
+}
+
+.zx-grid[data-align="start"] {
+  align-items: start;
+}
+
+.zx-grid[data-align="center"] {
+  align-items: center;
+}
+
+.zx-grid[data-align="end"] {
+  align-items: end;
+}
+
+.zx-grid[data-align="stretch"] {
+  align-items: stretch;
+}
+
+.zx-aspect {
+  display: block;
+  aspect-ratio: var(--zx-aspect-ratio, 16 / 9);
+  inline-size: 100%;
+  overflow: hidden;
+}
+
+.zx-aspect > * {
+  inline-size: 100%;
+  block-size: 100%;
+  object-fit: var(--zx-aspect-fit, cover);
+}