@zeyos/zx 4.0.0 → 4.1.1

package/docs/llms.txt

@@ -22,30 +22,32 @@ exports and as `window.zx.*`.
 
 ## Components
 - Inputs and identity: `button()`, `buttonGroup()`, `badge()`/`badgeGroup()`, `CheckButton`,
-  `Toggle`, `Search`, `Launcher`, `Avatar`, `AccountMenu`, `Select` (APG combobox;
-  `filter: false|'local'|async`; priority, status, permission, and optional ZeyOS entity presets),
-  `Checklist`, `TagPicker`, `NumberField`, `Rating`, `Slider`,
+  `Toggle`, `Search`, `AppIcon` (+ `zeyosAppIcon()` presets), `Avatar`,
+  `Select` (APG combobox; `filter: false|'local'|async`; priority, status, permission, and
+  `Select.entity()` presets), `Checklist`, `TagPicker` (icon/color identity), `NumberField`, `Rating`, `Slider`,
   `copyButton()`/`CopyInput`, `DatePicker`, `MonthPicker`, `TimePicker`,
   `Datebox`/`DateTimeBox`, `DateRangePicker`/`DateRangeBox`, `Timebox`.
 - Overlays: `Message` (toasts/inline/progress), `Modal`, `Dialog` (+ `alert`/`confirm`/`prompt` Promises), `Sheet` (edge-anchored Dialog; `side`, `modal: true|'trap-focus'|false`, `backdrop`, `snap` detents, swipe-to-dismiss), `SheetStack` (drill-down; `stack`/`cascade`), `Dropdown`, `MenuButton`, `ContextMenu` (right-click; `selector` for per-row menus), `Tooltip`/`tooltip()`/`describe()`.
-- Data: `Table` (sortable, selectable, sticky header, opt-in inline cell/row editing via
-  `editMode`), `Grid` with `Grid.BillingItems()`, engine-neutral `Chart` with injected
-  `ChartJsAdapter`, `DataFilter`, `Pagination` (+ pure `paginationRange()`), `TreeView` (APG tree),
+- Data: `Table` (sortable, selectable, sticky header, opt-in inline cell/row editing, row reorder,
+  column visibility), `Grid` with single-click editing and `Grid.BillingItems()`, engine-neutral
+  `Chart` with injected `ChartJsAdapter`, backend-neutral nested `Filter`, simple client-side
+  `DataFilter`, `Pagination` (+ pure `paginationRange()`), `TreeView` (APG tree),
   `Finder` (Miller columns).
 - Forms: `Form`, `Fieldset`, `Questionnaire` (guided one-question-at-a-time flow with branching), `Field` (type registry), `ValueList`, `MultiValueEditor`, `FieldUpload`.
 - Layout: `stack()`/`grid()`/`aspect()` (spacing, an intrinsically reflowing grid, a fixed-ratio
   box), `Groupbox`, `Card` (media/title link/actions/footer), `Panel` (header/footer action
   buttons), `MasterPanel`, `Tabbox`
   (`variant: 'divided'|'bracket'|'line'|'segmented'`), `NavigationBar`, `AppSidebar` (expanded and
-  minimized vertical states plus horizontal rail layouts), `Toolbar` (APG toolbar with overflow menu), `SplitView`, `Dock`
+  minimized vertical states plus horizontal rail layouts), `AccountMenu`, `Launcher`,
+  `spinner()`/`ProgressBar`/`InlineLoading`, `skeleton()`/`skeletonText()`/`skeletonTable()`,
+  `Toolbar` (APG toolbar with overflow menu), `SplitView`, `Dock`
   (collapsible resizable pane stack; tab groups, regions, adopts a `Sheet`), `Stepper`,
   `Breadcrumb`, `emptyState()`.
-- Feedback: `spinner()` (unknown duration), `ProgressBar` (known share; determinate or indeterminate), `InlineLoading` (a wait resolving into its outcome in place), `skeleton()`/`skeletonText()`/`skeletonTable()` (placeholders shaped like the content; `aria-hidden`, set `aria-busy` on the region).
 - Core: `Component`, `h`/`__`/`icon`, `position`, `breakpoints`/`breakpointOf`/`matchBreakpoint`/`onBreakpoint` (named width bands, observed on an element or the window), `Http`/`zeyosService`, i18n, date utils, `defineElements` (declarative `<zx-*>` custom elements).
 - Helpers: `formatNumber`/`formatCurrency`/`formatPercent`/`formatFileSize`/`formatRelativeTime` (locale-aware, cached `Intl`), `debounce`/`throttle`, `groupBy`/`sortBy`/`uniqueBy`, `escapeRegExp`/`highlightMatch`, `storage()` (namespaced JSON, degrades to memory), `toCsv`/`downloadBlob`/`copyToClipboard`, `truncate()`/`isTruncated()` (line clamp with the full value on hover).
 
 ## Theming
-Load `zx.css` once; set `data-zx-theme` (`light`|`dark`|`auto`) and `data-zx-density` (`cozy`|`compact`) on any ancestor. Define a product theme by overriding semantic `--zx-color-*` / `--zx-control-*` tokens under `[data-zx-theme="name"]`. Never use tier-1 palette tokens or raw color literals in application CSS.
+Load `zx.css` once; set `data-zx-theme` (`light`|`dark`|`auto`) and `data-zx-density` (`cozy`|`compact`) on any ancestor. Define a product theme by overriding semantic `--zx-color-*` / `--zx-control-*` tokens under `[data-zx-theme="name"]`. The theme studio controls accent, neutral tint, density, font, type size, radius, control height, and CSS-first glass material. Never use tier-1 palette tokens or raw color literals in application CSS.
 
 ## Talking to ZeyOS
 Use the dedicated ZeyOS client library **`@zeyos/client`** (`npm install @zeyos/client`) for ZeyOS business data: `createZeyosClient({ platform, auth })`, typed `client.api.list/get/create/update<Resource>` over the full OpenAPI surface, and `normalizeListResult`. Zx accepts the client by injection and does not bundle it. See the `website/layouts/zeyos-invoices.layout.js` layout for a Zx-components-on-@zeyos/client reference. Zx also ships a minimal `Http`/`zeyosService` for ad-hoc in-app `remotecall`, but `@zeyos/client` is the recommended default.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeyos/zx",
-  "version": "4.0.0",
+  "version": "4.1.1",
   "description": "Dependency-free JavaScript implementation of the Xenon Design System.",
   "type": "module",
   "license": "MIT",

package/src/components/app-icon/app-icon.css

@@ -0,0 +1,189 @@
+.zx-app-icon {
+  --zx-app-icon-size: 36px;
+  --zx-app-icon-glyph-size: 52%;
+  --zx-app-icon-color: var(--zx-color-accent);
+  position: relative;
+  isolation: isolate;
+  display: inline-grid;
+  place-items: center;
+  flex: none;
+  inline-size: var(--zx-app-icon-size);
+  block-size: var(--zx-app-icon-size);
+  overflow: hidden;
+  border: 1px solid var(--zx-color-glass-border);
+  border-radius: max(var(--zx-radius-sm), calc(var(--zx-app-icon-size) * .12));
+  background: var(--zx-app-icon-color);
+  box-shadow: var(--zx-app-icon-shadow);
+  color: var(--zx-app-icon-glyph, var(--zx-color-app-icon-glyph));
+  font-size: var(--zx-app-icon-size);
+  vertical-align: middle;
+  transform: translateZ(0);
+}
+
+.zx-app-icon[data-glass="subtle"],
+.zx-app-icon[data-glass="strong"] {
+  background:
+    linear-gradient(145deg, var(--zx-color-glass-highlight-strong), transparent 38%),
+    linear-gradient(to bottom right, transparent 42%, var(--zx-color-app-icon-depth)),
+    color-mix(in srgb, var(--zx-app-icon-color) var(--zx-glass-color-strength), transparent);
+  -webkit-backdrop-filter: blur(calc(var(--zx-glass-blur) * .55)) saturate(var(--zx-glass-saturation));
+  backdrop-filter: blur(calc(var(--zx-glass-blur) * .55)) saturate(var(--zx-glass-saturation));
+}
+
+.zx-app-icon[data-glass="strong"] {
+  -webkit-backdrop-filter: blur(var(--zx-glass-blur)) saturate(var(--zx-glass-saturation));
+  backdrop-filter: blur(var(--zx-glass-blur)) saturate(var(--zx-glass-saturation));
+}
+
+.zx-app-icon[data-glass="none"] {
+  border-color: var(--zx-color-border);
+  box-shadow: none;
+}
+
+.zx-app-icon[data-glass="none"] .zx-app-icon__shine { display: none; }
+.zx-app-icon[data-glass="none"]::after { display: none; }
+
+.zx-app-icon[data-selected] {
+  outline: 2px solid var(--zx-color-bg-page);
+  box-shadow: 0 0 0 3px var(--zx-color-ring), var(--zx-overlay-shadow);
+}
+
+.zx-app-icon__shine {
+  position: absolute;
+  z-index: 1;
+  inset: 1px 13% auto;
+  block-size: 38%;
+  border-radius: 999px;
+  background: linear-gradient(to bottom, var(--zx-color-glass-highlight-strong), transparent);
+  filter: blur(1px);
+  pointer-events: none;
+}
+
+.zx-app-icon::after {
+  content: "";
+  position: absolute;
+  z-index: 1;
+  inset: 0;
+  border-radius: inherit;
+  box-shadow: inset 0 0 0 1px var(--zx-color-glass-highlight);
+  pointer-events: none;
+}
+
+.zx-app-icon__glyph {
+  position: absolute;
+  z-index: 2;
+  inset-block-start: 50%;
+  inset-inline-start: 50%;
+  display: grid;
+  place-items: center;
+  inline-size: var(--zx-app-icon-glyph-size);
+  block-size: var(--zx-app-icon-glyph-size);
+  margin: 0;
+  padding: 0;
+  font-size: var(--zx-app-icon-glyph-size);
+  line-height: 1;
+  filter: drop-shadow(var(--zx-glass-glyph-shadow));
+  transform: translate(-50%, -50%);
+}
+
+.zx-app-icon__glyph > .zx-icon,
+.zx-app-icon__glyph > svg,
+.zx-app-icon__glyph > i {
+  display: grid;
+  place-items: center;
+  inline-size: 1em;
+  block-size: 1em;
+  margin: 0;
+  color: inherit;
+  font-size: 1em;
+  line-height: 1;
+  text-align: center;
+  vertical-align: middle;
+}
+
+.zx-app-icon__glyph > i::before {
+  display: block;
+  line-height: 1;
+}
+
+.zx-app-icon__glyph svg [fill]:not([fill="none"]) {
+  fill: currentColor;
+}
+
+.zx-app-icon__glyph svg [stroke]:not([stroke="none"]) {
+  stroke: currentColor;
+}
+
+.zx-app-icon__badge {
+  position: absolute;
+  z-index: 3;
+  inset-block-end: 1px;
+  inset-inline-end: 1px;
+  display: grid;
+  place-items: center;
+  min-inline-size: 14px;
+  block-size: 14px;
+  padding-inline: 3px;
+  border: 1px solid var(--zx-color-bg-raised);
+  border-radius: var(--zx-radius-full);
+  background: var(--zx-color-danger);
+  color: var(--zx-color-text-invert);
+  font-size: 9px;
+  font-weight: 700;
+  line-height: 1;
+}
+
+.zx-app-icon:hover {
+  border-color: var(--zx-color-glass-highlight-strong);
+  box-shadow: var(--zx-app-icon-shadow-hover);
+  filter: brightness(1.06) saturate(1.08);
+}
+
+.zx-app-icon:focus-visible,
+:is(a, button, [role="button"]):focus-visible > .zx-app-icon {
+  outline: none;
+  box-shadow: var(--zx-focus-ring), var(--zx-app-icon-shadow-hover);
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .zx-app-icon {
+    transition: border-color var(--zx-dur-fast) var(--zx-ease),
+      box-shadow var(--zx-dur-fast) var(--zx-ease),
+      filter var(--zx-dur-fast) var(--zx-ease),
+      transform var(--zx-dur-fast) var(--zx-ease);
+  }
+
+  .zx-app-icon:hover {
+    transform: translateY(-2px) scale(1.035);
+  }
+}
+
+@media (prefers-reduced-transparency: reduce) {
+  .zx-app-icon[data-glass="strong"] {
+    background: var(--zx-app-icon-color);
+    -webkit-backdrop-filter: none;
+    backdrop-filter: none;
+  }
+
+  .zx-app-icon[data-glass="subtle"] {
+    background: var(--zx-app-icon-color);
+    -webkit-backdrop-filter: none;
+    backdrop-filter: none;
+  }
+}
+
+@media (forced-colors: active) {
+  .zx-app-icon {
+    border-color: ButtonText;
+    background: ButtonFace;
+    color: ButtonText;
+    box-shadow: none;
+    filter: none;
+    transform: none;
+    -webkit-backdrop-filter: none;
+    backdrop-filter: none;
+  }
+
+  .zx-app-icon::after,
+  .zx-app-icon__shine { display: none; }
+}

package/src/components/app-icon/app-icon.js

@@ -0,0 +1,137 @@
+import { Component } from '../../core/component.js';
+import { h, restoreTarget, snapshotTarget } from '../../core/dom.js';
+import { icon as renderIcon } from '../../core/icons.js';
+import { isCssColor } from '../../core/util.js';
+
+/**
+ * @typedef {Object} AppIconOptions
+ * @property {string|Node|(()=>string|Node)|null} [icon=null] Icon name, node, or lazy renderer.
+ * @property {string|null} [color=null] Identity colour; falls back to the accent colour.
+ * @property {number|string} [size=36] Edge length in pixels or any CSS length.
+ * @property {number|string} [iconSize='52%'] Glyph size.
+ * @property {string|null} [label=null] Accessible image label; null makes the icon decorative.
+ * @property {string|number|null} [badge=null] Optional corner badge.
+ * @property {boolean} [selected=false] Whether the icon represents the active application.
+ * @property {false|'subtle'|'strong'} [glass='subtle'] CSS-first glass treatment.
+ * @property {string|string[]} [class] Additional class names.
+ */
+
+/**
+ * Stable application-identity tile with progressive CSS glass treatment.
+ * @extends {Component<AppIconOptions>}
+ */
+export class AppIcon extends Component {
+  static cssName = 'app-icon';
+
+  /** @type {Readonly<AppIconOptions>} */
+  static defaults = {
+    icon: null,
+    color: null,
+    size: 36,
+    iconSize: '52%',
+    label: null,
+    badge: null,
+    selected: false,
+    glass: 'subtle',
+    class: []
+  };
+
+  /** @returns {HTMLElement} */
+  render() {
+    this._createdRoot = this.el === null;
+    const root = /** @type {HTMLElement} */ (this.el ?? h('span'));
+    this.el = root;
+    this._snapshot = this._createdRoot ? null : snapshotTarget(root);
+    this._state = { ...this.options };
+    this._appliedClasses = [];
+    this._sync();
+    return root;
+  }
+
+  /** Updates identity or presentation without replacing the root. @param {Partial<AppIconOptions>} values @returns {this} */
+  set(values = {}) {
+    if (!values || typeof values !== 'object') return this;
+    Object.assign(this._state, values);
+    this._sync();
+    return this;
+  }
+
+  /** Restores an enhanced target. @returns {void} */
+  destroy() {
+    const root = this.el;
+    const snapshot = this._snapshot;
+    super.destroy();
+    if (!this._createdRoot && root) restoreTarget(root, snapshot);
+  }
+
+  /** @returns {void} */
+  _sync() {
+    const state = this._state;
+    this.el.classList.remove(...this._appliedClasses);
+    this._appliedClasses = [state.class].flat()
+      .flatMap((value) => String(value ?? '').split(/\s+/)).filter(Boolean);
+    this.el.classList.add(...this._appliedClasses);
+    const size = cssLength(state.size, '36px');
+    const glyphSize = cssLength(state.iconSize, '52%');
+    this.el.style.setProperty('--zx-app-icon-size', size);
+    this.el.style.setProperty('--zx-app-icon-glyph-size', glyphSize);
+    if (isCssColor(state.color)) this.el.style.setProperty('--zx-app-icon-color', String(state.color));
+    else this.el.style.removeProperty('--zx-app-icon-color');
+    this.el.dataset.glass = normalizeGlass(state.glass);
+    this.el.toggleAttribute('data-selected', Boolean(state.selected));
+
+    const label = state.label == null ? '' : String(state.label).trim();
+    if (label) {
+      this.el.setAttribute('role', 'img');
+      this.el.setAttribute('aria-label', label);
+      this.el.removeAttribute('aria-hidden');
+    } else {
+      this.el.removeAttribute('role');
+      this.el.removeAttribute('aria-label');
+      this.el.setAttribute('aria-hidden', 'true');
+    }
+
+    const visual = resolveVisual(state.icon);
+    const badge = state.badge == null || state.badge === '' ? null : h('span', {
+      class: 'zx-app-icon__badge', ariaHidden: 'true'
+    }, String(state.badge));
+    const children = [
+      h('span', { class: 'zx-app-icon__shine', ariaHidden: 'true' }),
+      h('span', { class: 'zx-app-icon__glyph', ariaHidden: 'true' }, visual)
+    ];
+    // Native replaceChildren() stringifies nullish arguments. Only append a badge when it exists,
+    // otherwise the icon gets a visible "null" text node that can also disturb optical centring.
+    if (badge) children.push(badge);
+    this.el.replaceChildren(...children);
+  }
+}
+
+/**
+ * Creates an AppIcon element without retaining a component lifecycle handle.
+ * @param {AppIconOptions} [options={}] Icon options.
+ * @returns {HTMLElement}
+ */
+export function appIcon(options = {}) {
+  return new AppIcon(null, options).toElement();
+}
+
+/** @param {AppIconOptions['icon']} value @returns {Node|string|null} */
+function resolveVisual(value) {
+  const resolved = typeof value === 'function' ? value() : value;
+  if (typeof resolved === 'string') return renderIcon(resolved, { size: '1em' });
+  return resolved && typeof resolved === 'object' && typeof resolved.nodeType === 'number'
+    ? /** @type {Node} */ (resolved) : null;
+}
+
+/** @param {unknown} value @param {string} fallback @returns {string} */
+function cssLength(value, fallback) {
+  if (typeof value === 'number' && Number.isFinite(value)) return `${Math.max(1, value)}px`;
+  const text = String(value ?? '').trim();
+  return text && !/[;{}]/.test(text) ? text : fallback;
+}
+
+/** @param {unknown} value @returns {'none'|'subtle'|'strong'} */
+function normalizeGlass(value) {
+  if (value === false || value === 'none') return 'none';
+  return value === 'strong' ? 'strong' : 'subtle';
+}

package/src/components/button/button.css

@@ -6,7 +6,7 @@
   min-block-size: var(--zx-control-height);
   border: 1px solid var(--zx-color-border-control);
   border-radius: var(--zx-button-radius, var(--zx-control-radius));
-  background: var(--zx-color-bg-control);
+  background: var(--zx-color-glass-control);
   color: var(--zx-color-text);
   padding-inline: var(--zx-control-pad-x);
   font: inherit;
@@ -14,6 +14,9 @@
   font-weight: var(--zx-control-font-weight);
   line-height: 1;
   cursor: pointer;
+  -webkit-backdrop-filter: blur(var(--zx-glass-blur)) saturate(var(--zx-glass-saturation));
+  backdrop-filter: blur(var(--zx-glass-blur)) saturate(var(--zx-glass-saturation));
+  box-shadow: var(--zx-glass-control-shadow);
   transition: color var(--zx-dur-fast) var(--zx-ease),
     background-color var(--zx-dur-fast) var(--zx-ease),
     border-color var(--zx-dur-fast) var(--zx-ease),
@@ -21,7 +24,7 @@
 }
 
 .zx-btn:hover:not(:disabled) {
-  background: var(--zx-color-bg-hover);
+  background: var(--zx-color-glass-control-hover);
 }
 
 .zx-btn:active:not(:disabled) {
@@ -66,6 +69,9 @@
 .zx-btn[data-kind="ghost"] {
   border-color: transparent;
   background: none;
+  -webkit-backdrop-filter: none;
+  backdrop-filter: none;
+  box-shadow: none;
 }
 
 .zx-btn[data-kind="ghost"]:hover:not(:disabled) {
@@ -101,3 +107,29 @@
 .zx-btn-group > .zx-btn:focus-visible {
   z-index: 1;
 }
+
+@media (prefers-reduced-transparency: reduce) {
+  .zx-btn {
+    background: var(--zx-color-bg-control);
+    -webkit-backdrop-filter: none;
+    backdrop-filter: none;
+    box-shadow: none;
+  }
+}
+
+@media (forced-colors: active) {
+  .zx-btn {
+    border-color: ButtonText;
+    background: ButtonFace;
+    color: ButtonText;
+    box-shadow: none;
+    -webkit-backdrop-filter: none;
+    backdrop-filter: none;
+  }
+
+  .zx-btn[data-kind="primary"] {
+    border-color: Highlight;
+    background: Highlight;
+    color: HighlightText;
+  }
+}

package/src/components/card/card.css

@@ -14,9 +14,11 @@
 }
 
 .zx-card[data-variant="raised"] {
-  border: 1px solid transparent;
-  background: var(--zx-color-bg-surface);
-  box-shadow: var(--zx-overlay-shadow);
+  border: 1px solid var(--zx-color-glass-border);
+  background: var(--zx-color-glass-surface);
+  -webkit-backdrop-filter: blur(var(--zx-glass-blur)) saturate(var(--zx-glass-saturation));
+  backdrop-filter: blur(var(--zx-glass-blur)) saturate(var(--zx-glass-saturation));
+  box-shadow: var(--zx-glass-raised-shadow);
 }
 
 .zx-card[data-variant="filled"] {
@@ -24,6 +26,26 @@
   background: var(--zx-color-bg-muted);
 }
 
+@media (prefers-reduced-transparency: reduce) {
+  .zx-card[data-variant="raised"] {
+    border-color: var(--zx-color-border);
+    background: var(--zx-color-bg-surface);
+    -webkit-backdrop-filter: none;
+    backdrop-filter: none;
+    box-shadow: var(--zx-overlay-shadow);
+  }
+}
+
+@media (forced-colors: active) {
+  .zx-card[data-variant="raised"] {
+    border-color: ButtonText;
+    background: Canvas;
+    box-shadow: none;
+    -webkit-backdrop-filter: none;
+    backdrop-filter: none;
+  }
+}
+
 .zx-card[data-linked="true"]:hover {
   background: var(--zx-color-bg-hover);
 }