@zeyos/zx 2.1.0 → 2.2.0

package/src/components/loading/spinner.css

@@ -0,0 +1,58 @@
+.zx-spinner {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--zx-space-2);
+  vertical-align: middle;
+}
+
+.zx-spinner__ring {
+  display: block;
+  flex: none;
+  inline-size: var(--zx-spinner-size, 24px);
+  block-size: var(--zx-spinner-size, 24px);
+  border: var(--zx-spinner-stroke, 2px) solid var(--zx-color-border);
+  border-block-start-color: var(--zx-color-accent);
+  border-radius: var(--zx-radius-full);
+}
+
+.zx-spinner[data-size="sm"] {
+  --zx-spinner-size: 16px;
+  --zx-spinner-stroke: 2px;
+}
+
+.zx-spinner[data-size="lg"] {
+  --zx-spinner-size: 40px;
+  --zx-spinner-stroke: 3px;
+}
+
+.zx-spinner[data-kind="current"] .zx-spinner__ring {
+  border-color: color-mix(in srgb, currentColor 25%, transparent);
+  border-block-start-color: currentColor;
+}
+
+.zx-spinner__label {
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-control-font-size);
+}
+
+/* An unshown label stays in the accessibility tree so `role="status"` still has something to say. */
+.zx-spinner__label:not([data-visible]) {
+  position: absolute;
+  clip-path: inset(50%);
+  inline-size: 1px;
+  block-size: 1px;
+  overflow: hidden;
+  white-space: nowrap;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .zx-spinner__ring {
+    animation: zx-spinner-turn 720ms linear infinite;
+  }
+}
+
+@keyframes zx-spinner-turn {
+  to {
+    transform: rotate(1turn);
+  }
+}

package/src/components/loading/spinner.js

@@ -0,0 +1,57 @@
+import { h } from '../../core/dom.js';
+
+/**
+ * @typedef {Object} SpinnerOptions
+ * @property {'sm'|'md'|'lg'} [size='md'] Ring diameter: 16px, 24px, or 40px.
+ * @property {string} [label=''] Accessible name. Empty renders a decorative ring that assistive
+ *   technology skips — correct whenever a nearby element already announces the wait.
+ * @property {boolean} [showLabel=false] Whether the label is also drawn beside the ring.
+ * @property {'accent'|'current'} [kind='accent'] Ring colour: the accent token, or `currentColor`
+ *   so the ring inherits the colour of the button or badge it sits in.
+ */
+
+/** @type {Readonly<SpinnerOptions>} */
+const defaults = Object.freeze({
+  size: 'md',
+  label: '',
+  showLabel: false,
+  kind: 'accent'
+});
+
+const SIZES = Object.freeze({ sm: true, md: true, lg: true });
+
+/**
+ * Creates an indeterminate activity ring for a wait whose duration is unknown.
+ *
+ * Presentational and stateless: there is nothing to update and nothing to destroy, so this is a
+ * factory rather than a component. Use `ProgressBar` when the share of work done is known, and
+ * `InlineLoading` when the wait resolves into a success or error message in place.
+ *
+ * A spinner with a `label` announces itself through `role="status"`; without one it is marked
+ * `aria-hidden`, which is what a ring inside an already-labelled button wants.
+ *
+ * @param {SpinnerOptions} [opts={}] Spinner options.
+ * @returns {HTMLSpanElement}
+ */
+export function spinner(opts = {}) {
+  const options = { ...defaults, ...opts };
+  const label = String(options.label ?? '');
+  const element = /** @type {HTMLSpanElement} */ (h('span', {
+    class: 'zx-spinner',
+    dataset: {
+      size: SIZES[options.size] ? options.size : 'md',
+      kind: options.kind === 'current' ? 'current' : 'accent'
+    }
+  }, h('span', { class: 'zx-spinner__ring', ariaHidden: 'true' })));
+
+  if (label) {
+    element.setAttribute('role', 'status');
+    element.append(h('span', {
+      class: 'zx-spinner__label',
+      dataset: { visible: options.showLabel ? 'true' : null }
+    }, label));
+  } else {
+    element.setAttribute('aria-hidden', 'true');
+  }
+  return element;
+}

package/src/components/master-panel/master-panel.css

@@ -0,0 +1,51 @@
+.zx-master-panel {
+  display: flex;
+  min-block-size: 0;
+  block-size: 100%;
+  flex-direction: column;
+  overflow: hidden;
+  border: 1px solid var(--zx-color-border);
+  border-radius: var(--zx-radius-lg);
+  background: var(--zx-color-bg-surface);
+}
+
+.zx-master-panel__header {
+  display: flex;
+  flex: none;
+  align-items: center;
+  gap: var(--zx-space-4);
+  min-block-size: calc(var(--zx-control-height) + var(--zx-space-4));
+  border-block-start: 4px solid var(--zx-master-panel-accent, var(--zx-module-default));
+  border-block-end: 1px solid var(--zx-color-border);
+  background: var(--zx-color-bg-raised);
+  padding: var(--zx-space-2) var(--zx-space-4);
+}
+
+.zx-master-panel__title {
+  min-inline-size: 0;
+  margin: 0;
+  flex: 1;
+  font-size: var(--zx-text-xl);
+}
+
+.zx-master-panel__buttons {
+  display: flex;
+  flex: none;
+  align-items: center;
+  gap: var(--zx-space-2);
+}
+
+.zx-master-panel__content {
+  min-block-size: 0;
+  padding: var(--zx-space-4);
+  flex: 1 1 auto;
+  overflow: auto;
+}
+
+.zx-master-panel__footer {
+  flex: none;
+  border-block-start: 1px solid var(--zx-color-border);
+  background: var(--zx-color-bg-raised);
+  padding: var(--zx-space-3) var(--zx-space-4);
+  color: var(--zx-color-text-muted);
+}

package/src/components/master-panel/master-panel.js

@@ -0,0 +1,203 @@
+import { Component } from '../../core/component.js';
+import { h } from '../../core/dom.js';
+import { isElement } from '../../core/util.js';
+import { button } from '../button/button.js';
+
+/** @typedef {string|Node|Component|null} MasterPanelContent */
+/**
+ * @typedef {Object} MasterPanelButtonDescriptor
+ * @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|MasterPanelButtonDescriptor} MasterPanelButton */
+
+const MODULE_NAMES = Object.freeze([
+  'default', 'settings', 'accounts', 'billing', 'calendar', 'campaigns', 'clocking',
+  'collection', 'contacts', 'contracts', 'enhancements', 'inventory', 'links',
+  'mailinglists', 'messages', 'notes', 'opportunities', 'pricelists', 'procurement',
+  'projects', 'tasks', 'tickets', 'pwd', 'system', 'usermgmt', 'usersettings', 'users', 'groups'
+]);
+
+/**
+ * @typedef {Object} MasterPanelOptions
+ * @property {string} [title=''] Header title.
+ * @property {MasterPanelContent} [content=null] Scrollable body content.
+ * @property {MasterPanelButton[]} [buttons=[]] Header action elements or button descriptors.
+ * @property {string|null} [module=null] ZeyOS module name used for the header accent.
+ * @property {MasterPanelContent} [footer=null] Optional fixed footer content.
+ */
+
+/**
+ * Full-height page panel with fixed header and footer bars.
+ * @extends {Component<MasterPanelOptions>}
+ */
+export class MasterPanel extends Component {
+  static cssName = 'master-panel';
+
+  /** @type {Readonly<MasterPanelOptions>} */
+  static defaults = {
+    title: '',
+    content: null,
+    buttons: [],
+    module: null,
+    footer: null
+  };
+
+  /**
+   * Creates or enhances a page-level panel.
+   * @param {Element|string|null} target Existing container, selector, or null.
+   * @param {MasterPanelOptions} [options={}] Master-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;
+
+    const originalContent = created ? [] : Array.from(root.childNodes);
+    const header = h('header', { class: 'zx-master-panel__header' },
+      h('h1', { class: 'zx-master-panel__title', ref: 'title' }),
+      h('div', {
+        class: 'zx-master-panel__buttons',
+        ref: 'buttons',
+        role: 'group',
+        ariaLabel: 'Panel actions'
+      })
+    );
+    const content = h('div', {
+      class: 'zx-master-panel__content',
+      ref: 'content'
+    });
+    const footer = h('footer', {
+      class: 'zx-master-panel__footer',
+      ref: 'footer',
+      hidden: true
+    });
+    root.replaceChildren(header, content, footer);
+
+    const moduleName = normalizeModule(this.options.module);
+    root.dataset.module = moduleName;
+    root.style.setProperty('--zx-master-panel-accent', `var(--zx-module-${moduleName})`);
+    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);
+    return root;
+  }
+
+  /**
+   * Replaces the header title.
+   * @param {string} title Next title.
+   * @returns {this}
+   */
+  setTitle(title) {
+    this.refs.title.textContent = String(title ?? '');
+    return this;
+  }
+
+  /**
+   * Replaces the scrollable body.
+   * @param {MasterPanelContent} content Next text, node, component, or null to clear.
+   * @returns {this}
+   */
+  setContent(content) {
+    replaceContent(this.refs.content, content, 'MasterPanel content');
+    return this;
+  }
+
+  /**
+   * Replaces the header action area.
+   * @param {MasterPanelButton[]} list Button descriptors or elements.
+   * @returns {this}
+   */
+  setButtons(list) {
+    if (!Array.isArray(list)) throw new TypeError('MasterPanel buttons must be an array');
+    const elements = list.map((item) => {
+      if (isElement(item)) return item;
+      if (!item || typeof item !== 'object' || Array.isArray(item)) {
+        throw new TypeError('MasterPanel buttons 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;
+    });
+    this.refs.buttons.replaceChildren(...elements);
+    return this;
+  }
+
+  /**
+   * Replaces or removes the fixed footer.
+   * @param {MasterPanelContent} content Next footer content, or null to remove it.
+   * @returns {this}
+   */
+  setFooter(content) {
+    replaceContent(this.refs.footer, content, 'MasterPanel footer');
+    this.refs.footer.hidden = content === null;
+    return this;
+  }
+
+  /** @returns {void} */
+  destroy() {
+    if (this._cleaned) return;
+    this._cleaned = true;
+    super.destroy();
+    if (!this._createdRoot && this._original) restore(this.el, this._original);
+  }
+}
+
+/** @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 {MasterPanelContent} 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`);
+}
+
+/** @param {unknown} moduleName @returns {string} */
+function normalizeModule(moduleName) {
+  const normalized = String(moduleName ?? 'default').toLowerCase();
+  return MODULE_NAMES.includes(normalized) ? normalized : 'default';
+}

package/src/components/menu-button/menu-button.css

@@ -0,0 +1,49 @@
+.zx-menu-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--zx-space-2);
+}
+
+.zx-menu-button__menu {
+  min-inline-size: 180px;
+  padding: var(--zx-space-1);
+}
+
+.zx-menu-button__item {
+  display: flex;
+  align-items: center;
+  gap: var(--zx-space-2);
+  inline-size: 100%;
+  min-block-size: var(--zx-control-height);
+  border-color: var(--zx-color-bg-raised);
+  background: var(--zx-color-bg-raised);
+  padding-inline: var(--zx-control-pad-x);
+  text-align: start;
+}
+
+.zx-menu-button__item:hover,
+.zx-menu-button__item:focus-visible {
+  background: var(--zx-color-bg-hover);
+}
+
+.zx-menu-button__item[data-danger="true"] {
+  color: var(--zx-color-danger);
+}
+
+.zx-menu-button__item[aria-disabled="true"] {
+  color: var(--zx-color-text-muted);
+  cursor: not-allowed;
+  opacity: .65;
+}
+
+.zx-menu-button__icon {
+  display: inline-flex;
+  flex: none;
+}
+
+.zx-menu-button__separator {
+  block-size: 1px;
+  margin: var(--zx-space-1) var(--zx-space-2);
+  background: var(--zx-color-border);
+}