@zeyos/zx 2.1.0 → 2.2.0

package/src/components/panel/panel.js

@@ -0,0 +1,336 @@
+import { Component } from '../../core/component.js';
+import { h } from '../../core/dom.js';
+import { icon } from '../../core/icons.js';
+import { isElement, uid } from '../../core/util.js';
+import { button } from '../button/button.js';
+
+/** @typedef {string|Node|Component|null} PanelContent */
+/**
+ * @typedef {Object} PanelButtonDescriptor
+ * @property {string} [label=''] Visible button label.
+ * @property {string|null} [icon=null] Icon name from the kernel icon set.
+ * @property {'default'|'primary'|'danger'|'ghost'} [kind='default'] Visual intent.
+ * @property {'md'|'sm'} [size='md'] Control size.
+ * @property {boolean} [disabled=false] Whether the button is disabled.
+ * @property {string} [title] Native title text.
+ * @property {(event: MouseEvent) => void} [onclick] Click callback.
+ */
+/** @typedef {Element|PanelButtonDescriptor} PanelButton */
+
+/**
+ * @typedef {Object} PanelOptions
+ * @property {string} [title=''] Section title.
+ * @property {PanelContent} [content=null] Initial body content.
+ * @property {boolean} [open=true] Initial expanded state.
+ * @property {boolean} [collapsible=true] Whether the header toggles the body.
+ * @property {PanelButton[]} [buttons=[]] Header actions, right-aligned next to the title.
+ * @property {PanelContent} [footer=null] Optional footer content.
+ * @property {PanelButton[]} [footerButtons=[]] Footer actions, right-aligned in the footer bar.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open callback.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onclose] Close callback.
+ */
+
+/**
+ * Framed, optionally collapsible titled section.
+ *
+ * The header is a row rather than one big button: the title and chevron form the collapse control
+ * and the action area sits beside it, because a button may not contain other buttons.
+ * @fires Panel#open
+ * @fires Panel#close
+ * @extends {Component<PanelOptions>}
+ */
+export class Panel extends Component {
+  static cssName = 'panel';
+
+  /** @type {Readonly<PanelOptions>} */
+  static defaults = {
+    title: '',
+    content: null,
+    open: true,
+    collapsible: true,
+    buttons: [],
+    footer: null,
+    footerButtons: []
+  };
+
+  /**
+   * Creates or enhances a panel.
+   * @param {Element|string|null} target Existing container, selector, or null.
+   * @param {PanelOptions} [options={}] Panel options.
+   */
+  constructor(target, options = {}) {
+    super(target, options);
+  }
+
+  /** @returns {HTMLElement} */
+  render() {
+    const created = !this.el;
+    const root = /** @type {HTMLElement} */ (this.el ?? h('section'));
+    this.el = root;
+    this._createdRoot = created;
+    this._original = created ? null : snapshot(root);
+    this._cleaned = false;
+    this._open = Boolean(this.options.open);
+    this._collapsible = Boolean(this.options.collapsible);
+
+    this._hasFooterContent = false;
+
+    const originalContent = created ? [] : Array.from(root.childNodes);
+    const bodyId = uid('zx-panel-body');
+    const title = h('span', { class: 'zx-panel__title', ref: 'title' });
+    const toggleChildren = [];
+    if (this._collapsible) {
+      toggleChildren.push(h('span', {
+        class: 'zx-panel__chevron',
+        ariaHidden: 'true'
+      }, icon('chevron-right', { size: 16 })));
+    }
+    toggleChildren.push(title);
+
+    const toggle = this._collapsible ? h('button', {
+      class: 'zx-panel__toggle',
+      ref: 'toggle',
+      type: 'button',
+      ariaControls: bodyId,
+      ariaExpanded: String(this._open)
+    }, toggleChildren) : h('div', {
+      class: 'zx-panel__toggle',
+      ref: 'toggle'
+    }, toggleChildren);
+    const header = h('div', { class: 'zx-panel__header', ref: 'header' },
+      toggle,
+      h('div', {
+        class: 'zx-panel__buttons',
+        ref: 'buttons',
+        role: 'group',
+        ariaLabel: 'Panel actions'
+      })
+    );
+    const content = h('div', {
+      class: 'zx-panel__content',
+      ref: 'content'
+    });
+    const body = h('div', {
+      class: 'zx-panel__body',
+      ref: 'body',
+      id: bodyId
+    }, content);
+    const footer = h('div', {
+      class: 'zx-panel__footer',
+      ref: 'footer',
+      hidden: true
+    },
+    h('div', { class: 'zx-panel__footer-content', ref: 'footerContent' }),
+    h('div', {
+      class: 'zx-panel__footer-buttons',
+      ref: 'footerButtons',
+      role: 'group',
+      ariaLabel: 'Panel footer actions'
+    }));
+    root.replaceChildren(header, body, footer);
+
+    this.setTitle(this.options.title);
+    if (this.options.content !== null) this.setContent(this.options.content);
+    else content.append(...originalContent);
+    this.setButtons(this.options.buttons);
+    this.setFooter(this.options.footer);
+    this.setFooterButtons(this.options.footerButtons);
+    this._syncOpenState();
+
+    if (this._collapsible) {
+      this.listen(toggle, 'click', () => this.toggle());
+    }
+    return root;
+  }
+
+  /**
+   * Replaces the visible title.
+   * @param {string} title Next title.
+   * @returns {this}
+   */
+  setTitle(title) {
+    this.refs.title.textContent = String(title ?? '');
+    return this;
+  }
+
+  /**
+   * Replaces the panel body.
+   * @param {PanelContent} content Next text, node, component, or null to clear.
+   * @returns {this}
+   */
+  setContent(content) {
+    replaceContent(this.refs.content, content, 'Panel content');
+    return this;
+  }
+
+  /**
+   * Replaces the header action area, right-aligned beside the title.
+   * @param {PanelButton[]} list Button descriptors or elements.
+   * @returns {this}
+   */
+  setButtons(list) {
+    this.refs.buttons.replaceChildren(...this._buildButtons(list, 'Panel buttons'));
+    return this;
+  }
+
+  /**
+   * Replaces or removes the footer content. The footer bar appears whenever it has content,
+   * footer buttons, or both.
+   * @param {PanelContent} content Next footer content, or null to remove it.
+   * @returns {this}
+   */
+  setFooter(content) {
+    replaceContent(this.refs.footerContent, content, 'Panel footer');
+    this._hasFooterContent = content !== null;
+    this._syncFooter();
+    return this;
+  }
+
+  /**
+   * Replaces the footer action area, right-aligned in the footer bar.
+   * @param {PanelButton[]} list Button descriptors or elements.
+   * @returns {this}
+   */
+  setFooterButtons(list) {
+    this.refs.footerButtons.replaceChildren(
+      ...this._buildButtons(list, 'Panel footer buttons'));
+    this._syncFooter();
+    return this;
+  }
+
+  /**
+   * Expands the panel.
+   * @returns {this}
+   * @fires Panel#open
+   */
+  open() {
+    if (this._open) return this;
+    this._open = true;
+    this._syncOpenState();
+    this.emit('open');
+    return this;
+  }
+
+  /**
+   * Collapses the panel.
+   * @returns {this}
+   * @fires Panel#close
+   */
+  close() {
+    if (!this._open) return this;
+    this._open = false;
+    this._syncOpenState();
+    this.emit('close');
+    return this;
+  }
+
+  /**
+   * Toggles the panel's expanded state.
+   * @returns {this}
+   * @fires Panel#open
+   * @fires Panel#close
+   */
+  toggle() {
+    return this.isOpen() ? this.close() : this.open();
+  }
+
+  /**
+   * Reports whether the body is expanded.
+   * @returns {boolean}
+   */
+  isOpen() {
+    return this._open;
+  }
+
+  /** @returns {void} */
+  destroy() {
+    if (this._cleaned) return;
+    this._cleaned = true;
+    super.destroy();
+    if (!this._createdRoot && this._original) restore(this.el, this._original);
+  }
+
+  /** @returns {void} */
+  _syncOpenState() {
+    this.el.setAttribute('data-state', this._open ? 'open' : 'closed');
+    this.refs.body.hidden = !this._open;
+    if (this._collapsible) {
+      this.refs.toggle.setAttribute('aria-expanded', String(this._open));
+    }
+  }
+
+  /** @returns {void} */
+  _syncFooter() {
+    this.refs.footer.hidden = !this._hasFooterContent
+      && this.refs.footerButtons.childElementCount === 0;
+  }
+
+  /**
+   * Turns button descriptors into elements, passing through any Element unchanged.
+   * @param {PanelButton[]} list Button descriptors or elements.
+   * @param {string} label Error-message prefix.
+   * @returns {Element[]}
+   */
+  _buildButtons(list, label) {
+    if (!Array.isArray(list)) throw new TypeError(`${label} must be an array`);
+    return list.map((item) => {
+      if (isElement(item)) return item;
+      if (!item || typeof item !== 'object' || Array.isArray(item)) {
+        throw new TypeError(`${label} must be Elements or button descriptors`);
+      }
+      const descriptor = { ...item };
+      const onclick = descriptor.onclick;
+      delete descriptor.onclick;
+      const element = button(descriptor);
+      if (typeof onclick === 'function') this.listen(element, 'click', onclick);
+      return element;
+    });
+  }
+}
+
+/**
+ * Emitted after the panel expands.
+ * @event Panel#open
+ * @type {CustomEvent<Record<string, never>>}
+ */
+
+/**
+ * Emitted after the panel collapses.
+ * @event Panel#close
+ * @type {CustomEvent<Record<string, never>>}
+ */
+
+/** @param {Element} element @returns {{attributes: Array<[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: Array<[string, string]>, children: Node[]}} original
+ * @returns {void}
+ */
+function restore(element, original) {
+  for (const attribute of Array.from(element.attributes)) element.removeAttribute(attribute.name);
+  for (const [name, value] of original.attributes) element.setAttribute(name, value);
+  element.replaceChildren(...original.children);
+}
+
+/** @param {Element} target @param {PanelContent} content @param {string} label @returns {void} */
+function replaceContent(target, content, label) {
+  target.replaceChildren();
+  if (content === null) return;
+  if (typeof content === 'string') {
+    target.append(document.createTextNode(content));
+    return;
+  }
+  const node = content instanceof Component ? content.toElement() : content;
+  if (node && typeof node.nodeType === 'number') {
+    target.append(node);
+    return;
+  }
+  throw new TypeError(`${label} must be a string, Node, Component, or null`);
+}

package/src/components/permission/permission.css

@@ -0,0 +1,47 @@
+.zx-permission {
+  min-inline-size: 0;
+  color: var(--zx-color-text);
+  font-size: var(--zx-control-font-size);
+}
+
+.zx-permission__choices {
+  display: grid;
+  grid-template-columns: repeat(3, max-content) minmax(160px, 1fr);
+  align-items: center;
+  gap: var(--zx-space-2) var(--zx-space-4);
+}
+
+.zx-permission__choice {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--zx-space-2);
+  min-block-size: var(--zx-control-height);
+  cursor: pointer;
+}
+
+.zx-permission__choice input {
+  accent-color: var(--zx-color-accent);
+}
+
+.zx-permission__choice:has(input:focus-visible) {
+  border-radius: var(--zx-radius-sm);
+  box-shadow: var(--zx-focus-ring);
+}
+
+.zx-permission__groups {
+  min-inline-size: 160px;
+}
+
+.zx-permission:not([data-state="group"]) .zx-permission__groups {
+  color: var(--zx-color-text-muted);
+}
+
+@media (max-width: 640px) {
+  .zx-permission__choices {
+    grid-template-columns: 1fr;
+  }
+
+  .zx-permission__groups {
+    inline-size: 100%;
+  }
+}

package/src/components/permission/permission.js

@@ -0,0 +1,198 @@
+import { Component } from '../../core/component.js';
+import { h } from '../../core/dom.js';
+import { uid } from '../../core/util.js';
+import { Select } from '../select/select.js';
+
+/** @typedef {Record<string, any>|string|number|boolean|symbol|bigint|null|undefined} PermissionGroup */
+/**
+ * @typedef {Object} PermissionOptions
+ * @property {boolean|string|number|symbol|bigint|null} [value=true] Public, private, or group ID.
+ * @property {PermissionGroup[]} [groups=[]] Available groups.
+ * @property {string|((item: PermissionGroup) => unknown)} [groupsValueKey='ID'] Group ID property or reader.
+ * @property {string|((item: PermissionGroup) => string)} [groupsLabelKey='name'] Group label property or reader.
+ * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
+ * @property {(event: CustomEvent<PermissionChangeDetail>) => void} [onchange] Change listener.
+ */
+/** @typedef {{value: unknown}} PermissionChangeDetail */
+
+/**
+ * Record-permission choice for private, public, and group access.
+ *
+ * @fires Permission#change
+ * @extends {Component<PermissionOptions>}
+ */
+export class Permission extends Component {
+  static cssName = 'permission';
+
+  /** @type {PermissionOptions} */
+  static defaults = {
+    value: true,
+    groups: [],
+    groupsValueKey: 'ID',
+    groupsLabelKey: 'name'
+  };
+
+
+  /** @returns {HTMLElement} */
+  render() {
+    // Instance state initialized here because render() runs inside the base
+    // constructor, before class-field initializers would run (and clobber it).
+    this._mode = 'public'; this._groupValue = null; this._groupSelect = null; this._createdRoot = false; this._originalChildren = []; this._root = null; this._originalState = null;
+    this._createdRoot = this.el === null;
+    const root = /** @type {HTMLElement} */ (this.el ?? h('div'));
+    this.el = root;
+    this._root = root;
+    if (!this._createdRoot) {
+      this._originalChildren = Array.from(root.childNodes);
+      this._originalState = root.getAttribute('data-state');
+    }
+    const name = uid('zx-permission');
+    const choices = h('div', {
+      class: 'zx-permission__choices',
+      role: 'radiogroup',
+      ariaLabel: this._message('permission.label', 'Permission')
+    });
+    const privateChoice = this._choice(name, 'private', this._message('permission.private', 'Private'));
+    const publicChoice = this._choice(name, 'public', this._message('permission.public', 'Public'));
+    const groupChoice = this._choice(name, 'group', this._message('permission.group', 'Group'));
+    const groupHost = h('div', { ref: 'groupHost', class: 'zx-permission__groups' });
+    choices.append(privateChoice.label, publicChoice.label, groupChoice.label, groupHost);
+    root.replaceChildren(choices);
+    this.refs.private = privateChoice.input;
+    this.refs.public = publicChoice.input;
+    this.refs.group = groupChoice.input;
+
+    this._groupSelect = new Select(groupHost, {
+      items: Array.isArray(this.options.groups) ? this.options.groups : [],
+      valueKey: this.options.groupsValueKey,
+      labelKey: this.options.groupsLabelKey,
+      placeholder: this._message('permission.group', 'Group')
+    });
+    this._groupSelect.refs.input.setAttribute(
+      'aria-label',
+      this._message('permission.group', 'Group')
+    );
+    for (const input of [privateChoice.input, publicChoice.input, groupChoice.input]) {
+      this.listen(input, 'change', () => {
+        if (!input.checked) return;
+        if (input.value === 'group') this._selectGroupMode();
+        else this.set(input.value);
+      });
+    }
+    this.listen(groupHost, 'zx-change', (event) => {
+      event.stopPropagation();
+      if (this._mode !== 'group') return;
+      const previous = this.get();
+      this._groupValue = /** @type {CustomEvent} */ (event).detail.value;
+      const value = this.get();
+      if (!Object.is(previous, value)) this.emit('change', { value });
+    });
+
+    this.set(this.options.value, { silent: true });
+    return root;
+  }
+
+  /** Returns the normalized permission value. @returns {'private'|'public'|unknown} */
+  get() {
+    if (this._mode === 'private') return 'private';
+    if (this._mode === 'public') return 'public';
+    return this._groupValue;
+  }
+
+  /**
+   * Sets a public, private, or group permission.
+   * @param {boolean|string|number|symbol|bigint|null} value Permission value.
+   * @param {{silent?: boolean}} [options={}] Update behavior.
+   * @returns {this}
+   * @fires Permission#change
+   */
+  set(value, { silent = false } = {}) {
+    const previous = this.get();
+    if (value === true || value === 'public') {
+      this._mode = 'public';
+    } else if (value === false || value === 'private') {
+      this._mode = 'private';
+    } else {
+      this._mode = 'group';
+      this._groupValue = value;
+      this._groupSelect?.set(value, { silent: true });
+    }
+    this._sync();
+    const next = this.get();
+    if (!silent && !Object.is(previous, next)) this.emit('change', { value: next });
+    return this;
+  }
+
+  /** Destroys the embedded Select and restores an enhanced target. @returns {void} */
+  destroy() {
+    this._groupSelect?.destroy();
+    this._groupSelect = null;
+    if (!this._createdRoot && this.el) {
+      this.el.replaceChildren(...this._originalChildren);
+      if (this._originalState === null) this.el.removeAttribute('data-state');
+      else this.el.setAttribute('data-state', this._originalState);
+    }
+    super.destroy();
+  }
+
+  /** @returns {void} */
+  _selectGroupMode() {
+    const previous = this.get();
+    this._mode = 'group';
+    if (this._groupValue == null) {
+      const first = Array.isArray(this.options.groups) ? this.options.groups[0] : null;
+      this._groupValue = first == null ? null : read(first, this.options.groupsValueKey);
+    }
+    this._groupSelect?.set(this._groupValue, { silent: true });
+    this._sync();
+    const next = this.get();
+    if (!Object.is(previous, next)) this.emit('change', { value: next });
+  }
+
+  /** @returns {void} */
+  _sync() {
+    /** @type {HTMLInputElement} */ (this.refs.private).checked = this._mode === 'private';
+    /** @type {HTMLInputElement} */ (this.refs.public).checked = this._mode === 'public';
+    /** @type {HTMLInputElement} */ (this.refs.group).checked = this._mode === 'group';
+    if (this._mode === 'group') this._groupSelect?.enable();
+    else this._groupSelect?.disable();
+    this._root?.setAttribute('data-state', this._mode);
+  }
+
+  /**
+   * @param {string} name
+   * @param {'private'|'public'|'group'} value
+   * @param {string} text
+   * @returns {{label: HTMLLabelElement, input: HTMLInputElement}}
+   */
+  _choice(name, value, text) {
+    const input = /** @type {HTMLInputElement} */ (h('input', {
+      type: 'radio',
+      name,
+      value
+    }));
+    const label = /** @type {HTMLLabelElement} */ (h('label', {
+      class: 'zx-permission__choice'
+    }, input, h('span', {}, text)));
+    return { label, input };
+  }
+
+  /** @param {string} key @param {string} fallback @returns {string} */
+  _message(key, fallback) {
+    const message = this.msg(key);
+    return message === key ? fallback : message;
+  }
+}
+
+/** Permission-value change. @event Permission#change @type {CustomEvent<PermissionChangeDetail>} */
+
+/**
+ * @param {PermissionGroup} item
+ * @param {string|((item: PermissionGroup) => unknown)} reader
+ * @returns {unknown}
+ */
+function read(item, reader) {
+  if (typeof reader === 'function') return reader(item);
+  if (item === null || typeof item !== 'object') return item;
+  return item[reader];
+}

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

@@ -0,0 +1,34 @@
+import { Field } from '../field/field.js';
+import { Rating } from './rating.js';
+
+/**
+ * Registers the Rating-backed `rating` field type.
+ * @returns {void}
+ */
+export function registerRatingFieldAdapter() {
+  Field.register('rating', (field, options) => {
+    const rating = field.own(new Rating(null, {
+      label: options.label ? String(options.label) : undefined,
+      ...(options.props ?? {})
+    }));
+    let setting = false;
+    rating.on('change', (event) => {
+      if (!setting) field.emit('change', { value: event.detail.value });
+    });
+    return {
+      el: rating.el,
+      // Unrated reads as null rather than 0, so Form's required check treats it as empty.
+      get: () => rating.get() || null,
+      set: (value) => {
+        setting = true;
+        try {
+          rating.set(Number(value) || 0, { silent: true });
+        } finally {
+          setting = false;
+        }
+      },
+      focus: () => rating.focus(),
+      setDisabled: (value) => (value ? rating.disable() : rating.enable())
+    };
+  });
+}