@zeyos/zx 2.1.0 → 2.2.0

package/src/components/dropdown/dropdown.js

@@ -0,0 +1,288 @@
+import { Component } from '../../core/component.js';
+import { h, resolveElement } from '../../core/dom.js';
+import { position } from '../../core/position.js';
+import { uid } from '../../core/util.js';
+
+const HANDLE_POINTER_DISMISS = Symbol('zxDropdownPointerDismiss');
+const HANDLE_ESCAPE_DISMISS = Symbol('zxDropdownEscapeDismiss');
+
+/**
+ * @typedef {Object} DropdownOptions
+ * @property {Node|string|number|{toElement: () => Node|null}|null} [content=null] Panel content.
+ * @property {'bottom-start'|'bottom-end'|'top-start'|'top-end'|'bottom'|'top'} [placement='bottom-start'] Panel placement.
+ * @property {number} [offset=4] Gap between anchor and panel in pixels.
+ * @property {boolean} [matchWidth=false] Whether the panel matches the anchor width.
+ * @property {'click'|'manual'} [openOn='click'] Trigger behavior.
+ * @property {boolean} [closeOnSelect=false] Whether a click within the panel closes it.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onclose] Close event listener.
+ */
+
+/**
+ * Generic anchored floating panel using the browser popover top layer.
+ * @fires Dropdown#open
+ * @fires Dropdown#close
+ * @extends {Component<DropdownOptions>}
+ */
+export class Dropdown extends Component {
+  static cssName = 'dropdown';
+
+  /** @type {Readonly<DropdownOptions>} */
+  static defaults = {
+    content: null,
+    placement: 'bottom-start',
+    offset: 4,
+    matchWidth: false,
+    openOn: 'click',
+    closeOnSelect: false
+  };
+
+  /** @type {Element} */
+  #anchor;
+  /** @type {ReturnType<typeof position>|null} */
+  #position = null;
+  /** @type {Map<string, string|null>} */
+  #anchorAttributes = new Map();
+  #destroyed = false;
+
+  /**
+   * Creates a floating panel anchored to an existing element.
+   * @param {Element|string} anchor Anchor element or selector.
+   * @param {DropdownOptions} [options={}] Dropdown options.
+   */
+  constructor(anchor, options = {}) {
+    const resolved = resolveElement(anchor);
+    if (!resolved) throw new TypeError('Dropdown anchor could not be resolved');
+    super(null, options);
+    this.#anchor = resolved;
+    this.#rememberAnchorAttribute('aria-expanded');
+    this.#rememberAnchorAttribute('aria-controls');
+    this.#anchor.setAttribute('aria-expanded', 'false');
+    this.#anchor.setAttribute('aria-controls', this.el.id);
+    this.setContent(this.options.content);
+
+    if (this.options.openOn === 'click') {
+      this.listen(this.#anchor, 'click', () => this.toggle());
+    }
+    this.listen(this.el, 'click', () => {
+      if (this.options.closeOnSelect) this.close();
+    });
+  }
+
+  /**
+   * Creates the owned popover panel.
+   * @returns {HTMLElement}
+   */
+  render() {
+    const panel = h('div', {
+      id: uid('zx-dropdown'),
+      popover: 'manual'
+    });
+    panel.dataset.state = 'closed';
+    document.body.append(panel);
+    return panel;
+  }
+
+  /**
+   * Opens and positions the panel.
+   * @returns {this}
+   * @fires Dropdown#open
+   */
+  open() {
+    if (this.isOpen() || this.#destroyed) return this;
+    this.#position = position(this.#anchor, this.el, {
+      placement: this.options.placement,
+      offset: Number(this.options.offset),
+      matchWidth: Boolean(this.options.matchWidth)
+    });
+    this.el.dataset.state = 'open';
+    this.el.dataset.zxOverlayOrder = String(nextOverlayOrder());
+    this.#anchor.setAttribute('aria-expanded', 'true');
+    ensureDismissManager();
+    this.emit('open');
+    return this;
+  }
+
+  /**
+   * Closes the panel and releases its positioning resources.
+   * @returns {this}
+   * @fires Dropdown#close
+   */
+  close() {
+    if (!this.isOpen()) return this;
+    this.#position?.destroy();
+    this.#position = null;
+    this.el.dataset.state = 'closed';
+    delete this.el.dataset.zxOverlayOrder;
+    this.#anchor.setAttribute('aria-expanded', 'false');
+    this.emit('close');
+    destroyUnusedDismissManager();
+    return this;
+  }
+
+  /**
+   * Toggles the panel.
+   * @returns {this}
+   */
+  toggle() {
+    return this.isOpen() ? this.close() : this.open();
+  }
+
+  /**
+   * Reports whether the panel is open.
+   * @returns {boolean}
+   */
+  isOpen() {
+    return this.#position !== null;
+  }
+
+  /**
+   * Replaces panel content without interpreting strings as HTML.
+   * @param {Node|string|number|{toElement: () => Node|null}|null} content Panel content.
+   * @returns {this}
+   */
+  setContent(content) {
+    replaceContent(this.el, content);
+    this.#position?.update();
+    return this;
+  }
+
+  /**
+   * Returns the owned popover panel.
+   * @returns {HTMLElement}
+   */
+  getPanel() {
+    return this.el;
+  }
+
+  /**
+   * Closes and removes the panel, restoring anchor ARIA attributes.
+   * @returns {void}
+   */
+  destroy() {
+    if (this.#destroyed) return;
+    this.#destroyed = true;
+    this.close();
+    for (const [name, value] of this.#anchorAttributes) restoreAttribute(this.#anchor, name, value);
+    super.destroy();
+  }
+
+  /** @param {PointerEvent} event @returns {void} */
+  [HANDLE_POINTER_DISMISS](event) {
+    if (!this.isOpen()) return;
+    const path = event.composedPath();
+    if (path.includes(this.el) || path.includes(this.#anchor)) return;
+    this.close();
+  }
+
+  /** @param {KeyboardEvent} event @returns {void} */
+  [HANDLE_ESCAPE_DISMISS](event) {
+    if (event.key !== 'Escape' || !this.isOpen()) return;
+    event.preventDefault();
+    const restoreFocus = this.el.contains(document.activeElement);
+    this.close();
+    if (restoreFocus && this.#anchor instanceof HTMLElement) this.#anchor.focus();
+  }
+
+  /** @param {string} name @returns {void} */
+  #rememberAnchorAttribute(name) {
+    this.#anchorAttributes.set(name, this.#anchor.getAttribute(name));
+  }
+}
+
+/** Shared document-level light-dismiss listener owned only while a dropdown is open. */
+class DropdownDismissManager extends Component {
+  /** Creates the transient listener owner. */
+  constructor() {
+    super(null);
+    this.listen(document, 'pointerdown', (event) => {
+      const component = topmostOverlayComponent();
+      if (component instanceof Dropdown) component[HANDLE_POINTER_DISMISS](event);
+    });
+    this.listen(document, 'keydown', (event) => {
+      if (event.key !== 'Escape') return;
+      const component = topmostOverlayComponent();
+      if (component instanceof Dropdown) component[HANDLE_ESCAPE_DISMISS](event);
+    });
+  }
+
+  /** @returns {HTMLElement} */
+  render() {
+    const marker = h('span', { hidden: true, 'data-zx-dropdown-dismiss-manager': '' });
+    document.body.append(marker);
+    return marker;
+  }
+}
+
+/**
+ * Fired when the dropdown panel opens.
+ * @event Dropdown#open
+ * @type {CustomEvent<Record<string, never>>}
+ */
+
+/**
+ * Fired when the dropdown panel closes.
+ * @event Dropdown#close
+ * @type {CustomEvent<Record<string, never>>}
+ */
+
+/**
+ * @param {Element} target
+ * @param {Node|string|number|{toElement: () => Node|null}|null|undefined} content
+ * @returns {void}
+ */
+function replaceContent(target, content) {
+  target.replaceChildren();
+  if (content == null) return;
+  if (typeof content === 'string' || typeof content === 'number') {
+    target.append(document.createTextNode(String(content)));
+  } else if (typeof content.toElement === 'function') {
+    const element = content.toElement();
+    if (element) target.append(element);
+  } else if (typeof content.nodeType === 'number') {
+    target.append(content);
+  }
+}
+
+/** @returns {Component|null} */
+function topmostOverlayComponent() {
+  let topmost = null;
+  let highest = -1;
+  for (const candidate of document.querySelectorAll('[data-zx-overlay-order]')) {
+    const order = Number(candidate.getAttribute('data-zx-overlay-order')) || 0;
+    if (order > highest) {
+      highest = order;
+      topmost = candidate;
+    }
+  }
+  return topmost ? Component.from(topmost) : null;
+}
+
+/** @returns {number} */
+function nextOverlayOrder() {
+  const orders = Array.from(document.querySelectorAll('[data-zx-overlay-order]'), (element) =>
+    Number(element.getAttribute('data-zx-overlay-order')) || 0
+  );
+  return Math.max(0, ...orders) + 1;
+}
+
+/** @returns {DropdownDismissManager} */
+function ensureDismissManager() {
+  const marker = document.querySelector('[data-zx-dropdown-dismiss-manager]');
+  const existing = marker ? Component.from(marker) : null;
+  return existing instanceof DropdownDismissManager ? existing : new DropdownDismissManager();
+}
+
+/** @returns {void} */
+function destroyUnusedDismissManager() {
+  if (document.querySelector('.zx-dropdown[data-state="open"]')) return;
+  const marker = document.querySelector('[data-zx-dropdown-dismiss-manager]');
+  const manager = marker ? Component.from(marker) : null;
+  if (manager instanceof DropdownDismissManager) manager.destroy();
+}
+
+/** @param {Element} element @param {string} name @param {string|null} value @returns {void} */
+function restoreAttribute(element, name, value) {
+  if (value === null) element.removeAttribute(name);
+  else element.setAttribute(name, value);
+}

package/src/components/empty-state/empty-state.css

@@ -0,0 +1,80 @@
+.zx-empty-state {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--zx-space-2);
+  padding-block: var(--zx-space-7);
+  padding-inline: var(--zx-space-5);
+  color: var(--zx-color-text-muted);
+  text-align: center;
+}
+
+.zx-empty-state__icon {
+  display: flex;
+  color: var(--zx-color-text-placeholder);
+}
+
+.zx-empty-state__title {
+  margin: 0;
+  color: var(--zx-color-text);
+  font-size: var(--zx-text-lg);
+  font-weight: 600;
+  line-height: 1.4;
+}
+
+.zx-empty-state__description {
+  margin: 0;
+  max-inline-size: 52ch;
+  font-size: var(--zx-control-font-size);
+  line-height: 1.6;
+}
+
+.zx-empty-state__actions {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: center;
+  gap: var(--zx-space-2);
+  margin-block-start: var(--zx-space-2);
+}
+
+.zx-empty-state[data-align="start"] {
+  align-items: flex-start;
+  text-align: start;
+}
+
+.zx-empty-state[data-align="start"] .zx-empty-state__actions {
+  justify-content: flex-start;
+}
+
+.zx-empty-state[data-size="sm"] {
+  gap: var(--zx-space-1);
+  padding-block: var(--zx-space-5);
+  padding-inline: var(--zx-space-4);
+}
+
+.zx-empty-state[data-size="sm"] .zx-empty-state__title {
+  font-size: var(--zx-control-font-size);
+}
+
+.zx-empty-state[data-size="sm"] .zx-empty-state__description {
+  font-size: var(--zx-text-sm);
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .zx-empty-state {
+    animation: zx-empty-state-in var(--zx-dur-base) var(--zx-ease) both;
+  }
+}
+
+@keyframes zx-empty-state-in {
+  from {
+    opacity: 0;
+    transform: translateY(4px);
+  }
+
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}

package/src/components/empty-state/empty-state.js

@@ -0,0 +1,92 @@
+import { h } from '../../core/dom.js';
+import { icon as createIcon } from '../../core/icons.js';
+import { isElement } from '../../core/util.js';
+import { button } from '../button/button.js';
+
+/** @typedef {import('../button/button.js').ButtonOptions} ButtonOptions */
+
+/**
+ * @typedef {Object} EmptyStateOptions
+ * @property {string|null} [icon='folder-open'] Decorative icon name; null renders no icon.
+ * @property {string} [title=''] Headline text, rendered as a paragraph so page outlines stay intact.
+ * @property {string} [description=''] Supporting sentence below the headline.
+ * @property {Array<Element|ButtonOptions>} [actions=[]] Buttons or button descriptors below the text.
+ * @property {'md'|'sm'} [size='md'] Overall scale.
+ * @property {'center'|'start'} [align='center'] Content alignment.
+ */
+
+/** Icon sizes per `size` option. */
+const ICON_SIZE = Object.freeze({ md: 40, sm: 28 });
+
+/** @type {Readonly<EmptyStateOptions>} */
+const defaults = Object.freeze({
+  icon: 'folder-open',
+  title: '',
+  description: '',
+  actions: [],
+  size: 'md',
+  align: 'center'
+});
+
+/**
+ * Creates the placeholder shown where a list, table, or panel has no content yet.
+ *
+ * Purely presentational: the icon is decorative, the headline is a paragraph rather than a heading
+ * so dropping the element into a Table's empty slot or a Panel body never disturbs the page's
+ * heading outline.
+ *
+ * @param {EmptyStateOptions} [opts={}] Empty-state options.
+ * @returns {HTMLDivElement}
+ */
+export function emptyState(opts = {}) {
+  const options = { ...defaults, ...opts };
+  const size = normalizeSize(options.size);
+  const element = /** @type {HTMLDivElement} */ (h('div', {
+    class: 'zx-empty-state',
+    dataset: { size, align: normalizeAlign(options.align) }
+  }));
+
+  if (options.icon) {
+    element.append(h('div', { class: 'zx-empty-state__icon', ariaHidden: 'true' },
+      createIcon(options.icon, { size: ICON_SIZE[size] })
+    ));
+  }
+  if (options.title) {
+    element.append(h('p', { class: 'zx-empty-state__title' }, String(options.title)));
+  }
+  if (options.description) {
+    element.append(h('p', { class: 'zx-empty-state__description' }, String(options.description)));
+  }
+
+  const actions = buildActions(options.actions);
+  if (actions.length > 0) {
+    element.append(h('div', { class: 'zx-empty-state__actions' }, actions));
+  }
+  return element;
+}
+
+/**
+ * Turns action descriptors into buttons, passing through any Element unchanged.
+ * @param {Array<Element|ButtonOptions>} list Buttons or button descriptors.
+ * @returns {Element[]}
+ */
+function buildActions(list) {
+  if (!Array.isArray(list)) throw new TypeError('emptyState actions must be an array');
+  return list.map((item) => {
+    if (isElement(item)) return item;
+    if (!item || typeof item !== 'object' || Array.isArray(item)) {
+      throw new TypeError('emptyState actions must be Elements or button descriptors');
+    }
+    return button(item);
+  });
+}
+
+/** @param {unknown} value @returns {'md'|'sm'} */
+function normalizeSize(value) {
+  return value === 'sm' ? 'sm' : 'md';
+}
+
+/** @param {unknown} value @returns {'center'|'start'} */
+function normalizeAlign(value) {
+  return value === 'start' ? 'start' : 'center';
+}

package/src/components/field/field.css

@@ -0,0 +1,127 @@
+.zx-field {
+  display: grid;
+  gap: var(--zx-space-1);
+  min-inline-size: 0;
+}
+
+.zx-field[data-layout="inline"] {
+  grid-template-columns: minmax(8rem, 1fr) minmax(0, 2fr);
+  column-gap: var(--zx-space-4);
+  align-items: start;
+}
+
+.zx-field[data-field-type="hidden"] {
+  display: none;
+}
+
+.zx-field__label {
+  min-inline-size: 0;
+  color: var(--zx-color-text);
+  font-size: var(--zx-text-sm);
+  font-weight: 600;
+}
+
+.zx-field__required,
+.zx-field[data-state="danger"] .zx-field__label {
+  color: var(--zx-color-danger);
+}
+
+.zx-field[data-state="warning"] .zx-field__label {
+  color: var(--zx-color-warning);
+}
+
+.zx-field[data-state="success"] .zx-field__label {
+  color: var(--zx-color-success);
+}
+
+.zx-field__body,
+.zx-field__control {
+  min-inline-size: 0;
+}
+
+.zx-field__control > input:not([type="checkbox"]):not([type="radio"]),
+.zx-field__control > select,
+.zx-field__control > textarea {
+  inline-size: 100%;
+}
+
+.zx-field__control > textarea {
+  min-block-size: calc(var(--zx-control-height) * 2.5);
+  padding-block: var(--zx-space-2);
+  resize: vertical;
+}
+
+.zx-field__option-list {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--zx-space-2) var(--zx-space-4);
+  min-block-size: var(--zx-control-height);
+  align-items: center;
+}
+
+.zx-field__option {
+  display: inline-flex;
+  gap: var(--zx-space-2);
+  align-items: center;
+  cursor: pointer;
+}
+
+.zx-field__option input {
+  margin: 0;
+}
+
+.zx-field__description,
+.zx-field__highlight {
+  margin-block-start: var(--zx-space-1);
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-sm);
+}
+
+.zx-field__highlight[hidden],
+.zx-field__description:empty {
+  display: none;
+}
+
+.zx-field[data-state="danger"] .zx-field__highlight {
+  color: var(--zx-color-danger);
+}
+
+.zx-field[data-state="warning"] .zx-field__highlight {
+  color: var(--zx-color-warning);
+}
+
+.zx-field[data-state="success"] .zx-field__highlight {
+  color: var(--zx-color-success);
+}
+
+.zx-field[data-state="danger"] .zx-field__control > input,
+.zx-field[data-state="danger"] .zx-field__control > select,
+.zx-field[data-state="danger"] .zx-field__control > textarea,
+.zx-field[data-state="danger"] .zx-field__option-list {
+  border-color: var(--zx-color-danger);
+}
+
+.zx-field__static,
+.zx-field__error-control {
+  min-block-size: var(--zx-control-height);
+  padding: var(--zx-space-2) var(--zx-control-pad-x);
+  border: 1px solid var(--zx-color-border);
+  border-radius: var(--zx-control-radius);
+  background: var(--zx-color-bg-surface);
+}
+
+.zx-field__error-control {
+  border-color: var(--zx-color-danger);
+  background: var(--zx-color-danger-bg);
+  color: var(--zx-color-danger);
+}
+
+.zx-field[data-disabled="true"] {
+  opacity: 0.65;
+}
+
+@container (max-width: 30rem) {
+  .zx-field[data-layout="inline"] {
+    grid-template-columns: 1fr;
+  }
+}