@zeyos/zx 2.3.0 → 4.0.0

package/src/components/avatar/avatar.js

@@ -0,0 +1,222 @@
+import { Component } from '../../core/component.js';
+import { h } from '../../core/dom.js';
+
+/**
+ * @typedef {Object} AvatarOptions
+ * @property {string|null} [src=null] Image URL.
+ * @property {string} [name=''] Name used to derive fallback initials.
+ * @property {string|null} [initials=null] Explicit fallback initials.
+ * @property {string|null} [label=null] Accessible label; null makes the avatar decorative.
+ * @property {string|number} [size='md'] Preset (`sm`, `md`, `lg`) or pixel size.
+ * @property {'circle'|'rounded'|'square'} [shape='circle'] Avatar shape.
+ * @property {'online'|'away'|'busy'|'offline'|null} [status=null] Optional presence state.
+ * @property {string|null} [statusLabel=null] Text alternative for the presence state.
+ */
+
+/**
+ * Stable-size user image with deterministic initials fallback and optional presence state.
+ * @extends {Component<AvatarOptions>}
+ */
+export class Avatar extends Component {
+  static cssName = 'avatar';
+
+  /** @type {Readonly<AvatarOptions>} */
+  static defaults = {
+    src: null,
+    name: '',
+    initials: null,
+    label: null,
+    size: 'md',
+    shape: 'circle',
+    status: null,
+    statusLabel: null
+  };
+
+  /** @returns {HTMLElement} */
+  render() {
+    this._createdRoot = this.el === null;
+    const root = /** @type {HTMLElement} */ (this.el ?? h('span'));
+    this.el = root;
+    this._original = this._createdRoot ? null : {
+      attributes: Array.from(root.attributes, (attribute) => [attribute.name, attribute.value]),
+      children: Array.from(root.childNodes)
+    };
+    this._state = {
+      src: this.options.src,
+      name: String(this.options.name ?? ''),
+      initials: this.options.initials,
+      label: this.options.label,
+      size: this.options.size,
+      shape: this.options.shape,
+      status: this.options.status,
+      statusLabel: this.options.statusLabel
+    };
+
+    const image = /** @type {HTMLImageElement} */ (h('img', {
+      ref: 'image',
+      class: 'zx-avatar__image',
+      alt: '',
+      draggable: false
+    }));
+    const fallback = h('span', {
+      ref: 'fallback',
+      class: 'zx-avatar__fallback',
+      ariaHidden: 'true'
+    });
+    const status = h('span', {
+      ref: 'status',
+      class: 'zx-avatar__status',
+      ariaHidden: 'true',
+      hidden: true
+    });
+    root.replaceChildren(image, fallback, status);
+    this.listen(image, 'load', () => {
+      if (this._isCurrentImageSource()) this._showImage(true);
+    });
+    this.listen(image, 'error', () => {
+      if (this._isCurrentImageSource()) this._showImage(false);
+    });
+    this._sync();
+    return root;
+  }
+
+  /**
+   * Replaces avatar identity and presentation values.
+   * @param {Partial<AvatarOptions>} values New values.
+   * @returns {this}
+   */
+  set(values = {}) {
+    if (!values || typeof values !== 'object') return this;
+    for (const key of ['src', 'name', 'initials', 'label', 'size', 'shape', 'status', 'statusLabel']) {
+      if (Object.hasOwn(values, key)) this._state[key] = values[key];
+    }
+    this._sync();
+    return this;
+  }
+
+  /** Sets the presence state and its text alternative. @param {AvatarOptions['status']} status @param {string|null} [label=null] @returns {this} */
+  setStatus(status, label = null) {
+    this._state.status = status;
+    this._state.statusLabel = label;
+    this._syncLabel();
+    this._syncStatus();
+    return this;
+  }
+
+  /** Returns whether the image is currently visible. @returns {boolean} */
+  hasImage() {
+    return !this.refs.image.hidden;
+  }
+
+  /** Restores an enhanced target or removes an owned root. @returns {void} */
+  destroy() {
+    const original = this._original;
+    super.destroy();
+    if (!this._createdRoot && original) {
+      for (const attribute of Array.from(this.el.attributes)) this.el.removeAttribute(attribute.name);
+      for (const [name, value] of original.attributes) this.el.setAttribute(name, value);
+      this.el.replaceChildren(...original.children);
+    }
+  }
+
+  /** @returns {void} */
+  _sync() {
+    const { size, shape, label } = this._state;
+    this.el.dataset.size = typeof size === 'string' ? size : 'custom';
+    this.el.dataset.shape = ['circle', 'rounded', 'square'].includes(shape) ? shape : 'circle';
+    if (typeof size === 'number' && Number.isFinite(size)) {
+      this.el.style.setProperty('--zx-avatar-size', `${Math.max(1, size)}px`);
+    } else {
+      this.el.style.removeProperty('--zx-avatar-size');
+    }
+    this._syncLabel();
+    this.refs.fallback.textContent = String(this._state.initials || avatarInitials(this._state.name));
+    const src = this._state.src == null ? '' : String(this._state.src).trim();
+    if (src) {
+      this.refs.image.setAttribute('src', src);
+      // Keep the fallback visible until this exact source has loaded successfully.
+      this._showImage(/** @type {HTMLImageElement} */ (this.refs.image).complete
+        && /** @type {HTMLImageElement} */ (this.refs.image).naturalWidth > 0);
+    } else {
+      this.refs.image.removeAttribute('src');
+      this._showImage(false);
+    }
+    this._syncStatus();
+  }
+
+  /** Synchronizes the standalone accessible name, including valid presence text. @returns {void} */
+  _syncLabel() {
+    const { label, status, statusLabel } = this._state;
+    if (label) {
+      const presence = ['online', 'away', 'busy', 'offline'].includes(status) ? statusLabel : null;
+      this.el.setAttribute('role', 'img');
+      this.el.setAttribute('aria-label', [label, presence].filter(Boolean).join(', '));
+      this.el.removeAttribute('aria-hidden');
+    } else {
+      this.el.removeAttribute('role');
+      this.el.removeAttribute('aria-label');
+      this.el.setAttribute('aria-hidden', 'true');
+    }
+  }
+
+  /** @param {boolean} visible @returns {void} */
+  _showImage(visible) {
+    this.refs.image.hidden = !visible;
+    this.refs.fallback.hidden = visible;
+    this.el.dataset.fallback = String(!visible);
+  }
+
+  /** Ignores a late load/error from a source that has already been replaced. @returns {boolean} */
+  _isCurrentImageSource() {
+    const image = /** @type {HTMLImageElement} */ (this.refs.image);
+    const requested = image.getAttribute('src');
+    if (!requested) return false;
+    try {
+      return image.currentSrc === new URL(requested, document.baseURI).href;
+    } catch {
+      return image.currentSrc === requested;
+    }
+  }
+
+  /** @returns {void} */
+  _syncStatus() {
+    const allowed = ['online', 'away', 'busy', 'offline'];
+    const status = allowed.includes(this._state.status) ? this._state.status : null;
+    this.refs.status.hidden = status === null;
+    if (status) this.refs.status.dataset.status = status;
+    else delete this.refs.status.dataset.status;
+    const label = this._state.statusLabel;
+    if (label) {
+      this.refs.status.setAttribute('title', String(label));
+    } else {
+      this.refs.status.removeAttribute('title');
+    }
+  }
+}
+
+/**
+ * Derives at most two uppercase initials from the first and last words of a name.
+ * @param {unknown} name Name-like value.
+ * @returns {string}
+ */
+export function avatarInitials(name) {
+  const words = String(name ?? '').trim().split(/\s+/u).filter(Boolean);
+  if (words.length === 0) return '?';
+  const first = uppercaseInitial(words[0]);
+  const last = words.length > 1 ? uppercaseInitial(words[words.length - 1]) : '';
+  return `${first}${last}`;
+}
+
+/** Returns one uppercased grapheme even when Unicode case expansion produces multiple letters. @param {string} word @returns {string} */
+function uppercaseInitial(word) {
+  return firstGrapheme(firstGrapheme(word).toUpperCase());
+}
+
+/** @param {string} value @returns {string} */
+function firstGrapheme(value) {
+  if (typeof Intl.Segmenter === 'function') {
+    const iterator = new Intl.Segmenter(undefined, { granularity: 'grapheme' }).segment(value)[Symbol.iterator]();
+    return iterator.next().value?.segment ?? '';
+  }
+  return Array.from(value)[0] ?? '';
+}

package/src/components/button/button.css

@@ -79,7 +79,6 @@
   font-size: var(--zx-text-sm);
 }
 
-.zx-btn > svg,
 .zx-btn > .zx-icon {
   flex: none;
 }

package/src/components/card/card.css

@@ -0,0 +1,149 @@
+.zx-card {
+  --zx-card-media-size: 8rem;
+  position: relative;
+  inline-size: 100%;
+  container-type: inline-size;
+  overflow: hidden;
+  border-radius: var(--zx-radius-lg);
+  color: var(--zx-color-text);
+}
+
+.zx-card[data-variant="outlined"] {
+  border: 1px solid var(--zx-color-border);
+  background: var(--zx-color-bg-surface);
+}
+
+.zx-card[data-variant="raised"] {
+  border: 1px solid transparent;
+  background: var(--zx-color-bg-surface);
+  box-shadow: var(--zx-overlay-shadow);
+}
+
+.zx-card[data-variant="filled"] {
+  border: 1px solid transparent;
+  background: var(--zx-color-bg-muted);
+}
+
+.zx-card[data-linked="true"]:hover {
+  background: var(--zx-color-bg-hover);
+}
+
+.zx-card:has(.zx-card__primary:focus-visible) {
+  outline: 0;
+  box-shadow: var(--zx-focus-ring);
+}
+
+.zx-card__layout,
+.zx-card__inner {
+  min-inline-size: 0;
+}
+
+.zx-card__inner {
+  display: grid;
+  gap: var(--zx-space-3);
+  padding: var(--zx-space-5);
+}
+
+.zx-card[data-orientation="horizontal"] .zx-card__layout {
+  display: grid;
+  grid-template-columns: var(--zx-card-media-size) minmax(0, 1fr);
+  align-items: stretch;
+}
+
+.zx-card__media {
+  min-inline-size: 0;
+  overflow: hidden;
+}
+
+.zx-card[data-orientation="horizontal"] .zx-card__media {
+  min-block-size: var(--zx-card-media-size);
+}
+
+.zx-card__media > :is(img, video, svg) {
+  display: block;
+  inline-size: 100%;
+  block-size: 100%;
+  object-fit: cover;
+}
+
+.zx-card__header {
+  display: flex;
+  align-items: start;
+  justify-content: space-between;
+  gap: var(--zx-space-3);
+}
+
+.zx-card__header[hidden],
+.zx-card__media[hidden],
+.zx-card__content[hidden],
+.zx-card__footer[hidden],
+.zx-card__actions[hidden] {
+  display: none;
+}
+
+.zx-card__heading {
+  min-inline-size: 0;
+  margin: 0;
+  font-size: var(--zx-text-lg);
+  font-weight: 700;
+  line-height: 1.3;
+  letter-spacing: -0.012em;
+}
+
+.zx-card__primary,
+.zx-card__title {
+  color: inherit;
+}
+
+.zx-card__primary {
+  text-decoration: none;
+}
+
+.zx-card[data-linked="true"] .zx-card__primary::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+}
+
+.zx-card__primary:focus-visible {
+  outline: 0;
+}
+
+.zx-card__actions,
+.zx-card__content :is(a, button, input, select, textarea, summary, [tabindex]:not([tabindex="-1"])),
+.zx-card__footer :is(a, button, input, select, textarea, summary, [tabindex]:not([tabindex="-1"])) {
+  position: relative;
+  z-index: 2;
+}
+
+.zx-card__actions {
+  display: flex;
+  flex: none;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: end;
+  gap: var(--zx-space-2);
+}
+
+.zx-card__content {
+  color: var(--zx-color-text-muted);
+  line-height: 1.6;
+}
+
+.zx-card__footer {
+  padding-block-start: var(--zx-space-3);
+  border-block-start: 1px solid var(--zx-color-border);
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-sm);
+}
+
+@container (max-width: 28rem) {
+  .zx-card[data-orientation="horizontal"] .zx-card__layout {
+    grid-template-columns: minmax(0, 1fr);
+  }
+
+  .zx-card[data-orientation="horizontal"] .zx-card__media {
+    min-block-size: 0;
+  }
+}

package/src/components/card/card.js

@@ -0,0 +1,285 @@
+import { Component } from '../../core/component.js';
+import { h, restoreTarget, safeHref, snapshotTarget } from '../../core/dom.js';
+import { isElement, uid } from '../../core/util.js';
+import { button } from '../button/button.js';
+
+/** @typedef {string|Node|Component|null} CardContent */
+/** @typedef {import('../button/button.js').ButtonOptions} ButtonOptions */
+/** @typedef {Element|ButtonOptions} CardAction */
+/**
+ * @typedef {Object} CardLinkDescriptor
+ * @property {string} href Native link destination; executable/data schemes are rejected.
+ * @property {string} [target] Native browsing context.
+ * @property {string} [rel] Native link relationship.
+ * @property {(event: MouseEvent) => void} [onclick] Native click listener.
+ */
+/** @typedef {string|CardLinkDescriptor|null} CardLink */
+
+/**
+ * @typedef {Object} CardOptions
+ * @property {string} [title=''] Card title.
+ * @property {CardContent} [media=null] Optional image, avatar, icon, or other media.
+ * @property {CardContent} [content=null] Main card content; enhanced children are adopted by default.
+ * @property {CardAction[]} [actions=[]] Secondary native controls beside the title.
+ * @property {CardContent} [footer=null] Optional metadata or trailing content.
+ * @property {CardLink} [link=null] Optional native primary link rendered around the title.
+ * @property {'outlined'|'raised'|'filled'} [variant='outlined'] Surface treatment.
+ * @property {'vertical'|'horizontal'} [orientation='vertical'] Media/content arrangement.
+ * @property {1|2|3|4|5|6} [headingLevel=3] Semantic title heading level.
+ */
+
+/**
+ * Semantic content or record surface with optional media, native primary link, actions, and footer.
+ * The root is never interactive: linked cards keep a real title anchor, so secondary controls are
+ * siblings rather than invalid nested actions.
+ * @extends {Component<CardOptions>}
+ */
+export class Card extends Component {
+  static cssName = 'card';
+
+  /** @type {Readonly<CardOptions>} */
+  static defaults = {
+    title: '',
+    media: null,
+    content: null,
+    actions: [],
+    footer: null,
+    link: null,
+    variant: 'outlined',
+    orientation: 'vertical',
+    headingLevel: 3
+  };
+
+  /**
+   * Creates or enhances one card.
+   * @param {Element|string|null} [target=null] Existing card container, selector, or null.
+   * @param {CardOptions} [options={}] Card options.
+   */
+  constructor(target = null, options = {}) {
+    super(target, options);
+  }
+
+  /** @returns {HTMLElement} */
+  render() {
+    const created = !this.el;
+    const root = /** @type {HTMLElement} */ (this.el ?? h('article'));
+    this.el = root;
+    this._createdRoot = created;
+    this._original = created ? null : snapshotTarget(root);
+    this._cleaned = false;
+    this._title = '';
+    this._link = null;
+    this._actionAbort = null;
+    this._linkAbort = null;
+
+    const originalContent = created ? [] : Array.from(root.childNodes);
+    try {
+      const headingLevel = normalizeHeadingLevel(this.options.headingLevel);
+      const headingId = uid('zx-card-heading');
+      const heading = h(`h${headingLevel}`, {
+        ref: 'heading',
+        class: 'zx-card__heading',
+        id: headingId
+      });
+      const media = h('div', { ref: 'media', class: 'zx-card__media', hidden: true });
+      const actions = h('div', {
+        ref: 'actions',
+        class: 'zx-card__actions',
+        role: 'group',
+        ariaLabel: 'Card actions',
+        hidden: true
+      });
+      const content = h('div', { ref: 'content', class: 'zx-card__content', hidden: true });
+      const footer = h('footer', { ref: 'footer', class: 'zx-card__footer', hidden: true });
+      const header = h('header', { ref: 'header', class: 'zx-card__header' }, heading, actions);
+
+      root.replaceChildren(h('div', { class: 'zx-card__layout' }, media,
+        h('div', { class: 'zx-card__inner' }, header, content, footer)));
+      root.dataset.variant = normalizeVariant(this.options.variant);
+      root.dataset.orientation = normalizeOrientation(this.options.orientation);
+
+      this.setTitle(this.options.title);
+      this.setMedia(this.options.media);
+      if (this.options.content !== null) this.setContent(this.options.content);
+      else if (originalContent.length) {
+        content.replaceChildren(...originalContent);
+        content.hidden = false;
+      }
+      this.setActions(this.options.actions);
+      this.setFooter(this.options.footer);
+      this.setLink(this.options.link);
+      return root;
+    } catch (error) {
+      this._actionAbort?.abort();
+      this._linkAbort?.abort();
+      if (!created) restoreTarget(root, this._original);
+      throw error;
+    }
+  }
+
+  /** Replaces the card title. @param {string} title Next title. @returns {this} */
+  setTitle(title) {
+    const next = String(title ?? '');
+    if (this._link && !next.trim()) throw new TypeError('A linked Card requires a non-empty title');
+    this._title = next;
+    this._renderHeading();
+    return this;
+  }
+
+  /** Replaces or removes the media region. @param {CardContent} content Media. @returns {this} */
+  setMedia(content) {
+    replaceCardContent(this.refs.media, content, 'Card media');
+    this.refs.media.hidden = content === null;
+    return this;
+  }
+
+  /** Replaces or clears the main content. @param {CardContent} content Content. @returns {this} */
+  setContent(content) {
+    replaceCardContent(this.refs.content, content, 'Card content');
+    this.refs.content.hidden = content === null;
+    return this;
+  }
+
+  /** Replaces the secondary action controls. @param {CardAction[]} actions Actions. @returns {this} */
+  setActions(actions) {
+    if (!Array.isArray(actions)) throw new TypeError('Card actions must be an array');
+    const nextAbort = new AbortController();
+    let controls;
+    try {
+      controls = actions.map((action) => {
+        if (isElement(action)) return action;
+        if (!action || typeof action !== 'object' || Array.isArray(action)) {
+          throw new TypeError('Card actions must be Elements or button descriptors');
+        }
+        const descriptor = { ...action };
+        const onclick = descriptor.onclick;
+        delete descriptor.onclick;
+        const control = button(descriptor);
+        if (onclick !== undefined && typeof onclick !== 'function') {
+          throw new TypeError('Card action onclick must be a function');
+        }
+        if (onclick) control.addEventListener('click', onclick, { signal: nextAbort.signal });
+        return control;
+      });
+    } catch (error) {
+      nextAbort.abort();
+      throw error;
+    }
+    this._actionAbort?.abort();
+    this._actionAbort = nextAbort;
+    this.refs.actions.replaceChildren(...controls);
+    this.refs.actions.hidden = controls.length === 0;
+    this._syncHeader();
+    return this;
+  }
+
+  /** Replaces or removes the footer. @param {CardContent} content Footer. @returns {this} */
+  setFooter(content) {
+    replaceCardContent(this.refs.footer, content, 'Card footer');
+    this.refs.footer.hidden = content === null;
+    return this;
+  }
+
+  /** Sets or removes the title's native primary link. @param {CardLink} link Link. @returns {this} */
+  setLink(link) {
+    const next = normalizeCardLink(link);
+    if (next && !this._title.trim()) throw new TypeError('A linked Card requires a non-empty title');
+    this._link = next;
+    this.el.dataset.linked = next ? 'true' : 'false';
+    this._renderHeading();
+    return this;
+  }
+
+  /** Restores an enhanced target exactly, or removes an owned card. @returns {void} */
+  destroy() {
+    if (this._cleaned) return;
+    this._cleaned = true;
+    this._actionAbort?.abort();
+    this._linkAbort?.abort();
+    super.destroy();
+    if (!this._createdRoot) restoreTarget(this.el, this._original);
+  }
+
+  /** @returns {void} */
+  _renderHeading() {
+    const title = this._title;
+    const nextAbort = new AbortController();
+    const node = this._link ? h('a', {
+      class: 'zx-card__primary',
+      href: this._link.href,
+      target: this._link.target,
+      rel: this._link.rel
+    }, title) : h('span', { class: 'zx-card__title' }, title);
+    if (this._link?.onclick) node.addEventListener('click', this._link.onclick, { signal: nextAbort.signal });
+    this._linkAbort?.abort();
+    this._linkAbort = nextAbort;
+    this.refs.heading.replaceChildren(node);
+    this.refs.heading.hidden = title === '';
+    if (title) this.el.setAttribute('aria-labelledby', this.refs.heading.id);
+    else this.el.removeAttribute('aria-labelledby');
+    this._syncHeader();
+  }
+
+  /** @returns {void} */
+  _syncHeader() {
+    if (!this.refs.header) return;
+    this.refs.header.hidden = this._title === '' && this.refs.actions.childElementCount === 0;
+  }
+}
+
+/** @param {Element} host @param {CardContent} content @param {string} label */
+function replaceCardContent(host, content, label) {
+  if (content === null) {
+    host.replaceChildren();
+    return;
+  }
+  if (typeof content === 'string') {
+    host.textContent = content;
+    return;
+  }
+  const node = content instanceof Component ? content.toElement() : content;
+  if (node instanceof Node) {
+    host.replaceChildren(node);
+    return;
+  }
+  throw new TypeError(`${label} must be a string, Node, Component, or null`);
+}
+
+/** @param {CardLink} value @returns {CardLinkDescriptor|null} */
+function normalizeCardLink(value) {
+  if (value === null) return null;
+  const descriptor = typeof value === 'string' ? { href: value } : value;
+  if (!descriptor || typeof descriptor !== 'object' || Array.isArray(descriptor)) {
+    throw new TypeError('Card link must be a URL string, descriptor, or null');
+  }
+  const href = safeHref(descriptor.href);
+  if (href === null) {
+    throw new TypeError('Card link requires a safe non-empty href');
+  }
+  if (descriptor.onclick !== undefined && typeof descriptor.onclick !== 'function') {
+    throw new TypeError('Card link onclick must be a function');
+  }
+  const target = descriptor.target == null ? undefined : String(descriptor.target);
+  let rel = descriptor.rel == null ? '' : String(descriptor.rel).trim();
+  if (target === '_blank' && !/(^|\s)noopener(\s|$)/i.test(rel)) {
+    rel = `${rel} noopener`.trim();
+  }
+  return { href, target, rel: rel || undefined, onclick: descriptor.onclick };
+}
+
+/** @param {unknown} value @returns {'outlined'|'raised'|'filled'} */
+function normalizeVariant(value) {
+  return ['raised', 'filled'].includes(String(value))
+    ? /** @type {'raised'|'filled'} */ (value) : 'outlined';
+}
+
+/** @param {unknown} value @returns {'vertical'|'horizontal'} */
+function normalizeOrientation(value) {
+  return value === 'horizontal' ? 'horizontal' : 'vertical';
+}
+
+/** @param {unknown} value @returns {1|2|3|4|5|6} */
+function normalizeHeadingLevel(value) {
+  const level = Math.trunc(Number(value));
+  return /** @type {1|2|3|4|5|6} */ (level >= 1 && level <= 6 ? level : 3);
+}