@zeyos/zx 4.4.0 → 5.0.0

package/docs/llms.txt

@@ -2,8 +2,8 @@
 
 > Xenon is a dependency-free design system for browser applications; Zx is its product-agnostic
 > vanilla-JavaScript implementation. ES2022 modules, WAI-ARIA-accessible native
-> controls, semantic `--zx-*` design tokens with light/dark/density theming, and lifecycle-safe
-> components. Source modules run directly in the browser; a build step emits ESM, IIFE-global,
+> controls, semantic `--zx-*` design tokens with light/dark theming and one token-driven geometry,
+> and lifecycle-safe components. Source modules run directly in the browser; a build step emits ESM, IIFE-global,
 > ZeyOS binding, and CSS bundles. Zero runtime dependencies.
 
 Instantiate every component as `new Component(target, options)` where `target` is an Element, a
@@ -56,7 +56,7 @@ exports and as `window.zx.*`.
 - 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"]`. The theme studio controls accent, neutral tint, density, font, type size, radius, control height, and CSS-first glass material. Compact menus, pickers, tooltips, column menus, and toasts share responsive compact glass; Launcher, Modal, Dialog, and floating Sheets share a calmer reading panel. Both preserve scoped theme inheritance and refract Aurora/page content; docked Sheets and dense data surfaces remain opaque. Never use tier-1 palette tokens or raw color literals in application CSS.
+Load `zx.css` once; set `data-zx-theme` (`light`|`dark`|`auto`) on any ancestor. There is one geometry: spacing steps are multiples of `--zx-space-unit` (4px), radius steps are fractions of `--zx-radius` (4px: 2/3/4/6px), and controls are `--zx-control-height` (30px) tall — override those to tighten or loosen an application. Define a product theme by overriding semantic `--zx-color-*` / `--zx-control-*` tokens under `[data-zx-theme="name"]`. The theme studio controls accent, neutral tint, spacing, font, type size, radius, control height, and CSS-first glass material. Compact menus, pickers, tooltips, column menus, and toasts share responsive compact glass; Launcher, Modal, Dialog, and floating Sheets share a calmer reading panel. Both preserve scoped theme inheritance and refract Aurora/page content; docked Sheets and dense data surfaces remain opaque. 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.4.0",
+  "version": "5.0.0",
   "description": "Dependency-free JavaScript implementation of the Xenon Design System.",
   "type": "module",
   "license": "MIT",

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

@@ -3,26 +3,50 @@
   min-inline-size: 0;
 }
 
-.zx-account-menu__trigger {
+/*
+ * The trigger is a flat row, not a button. MenuButton makes it a `.zx-btn.zx-menu-button`, and
+ * both of those stylesheets load after this one — `menu-button.css` centres it as an inline-flex
+ * pill and `button.css` gives it a border, a glass fill, a backdrop blur and a shadow. Every rule
+ * here is scoped under the root so it out-specifies them instead of depending on load order, and
+ * takes back each property they set rather than only the ones that were visible at the time.
+ */
+.zx-account-menu .zx-account-menu__trigger {
   display: grid;
   grid-template-columns: auto minmax(0, 1fr) auto;
   align-items: center;
-  gap: var(--zx-space-3);
+  justify-content: stretch;
+  gap: var(--zx-space-2);
   inline-size: 100%;
   min-block-size: calc(var(--zx-control-height) + var(--zx-space-2));
-  border-color: transparent;
+  border: 0;
+  border-radius: var(--zx-radius-md);
   background: transparent;
-  padding: var(--zx-space-2);
+  -webkit-backdrop-filter: none;
+  backdrop-filter: none;
+  box-shadow: none;
+  padding: var(--zx-space-1) var(--zx-space-2);
   color: inherit;
+  font-weight: var(--zx-weight-medium);
+  line-height: 1.3;
   text-align: start;
 }
 
-.zx-account-menu__trigger:hover,
-.zx-account-menu__trigger:focus-visible,
-.zx-account-menu__trigger[aria-expanded="true"] {
+.zx-account-menu .zx-account-menu__trigger:is(:hover, [aria-expanded="true"]):not(:disabled) {
   background: var(--zx-color-bg-hover);
 }
 
+.zx-account-menu .zx-account-menu__trigger:active:not(:disabled) {
+  background: var(--zx-color-bg-current);
+}
+
+.zx-account-menu .zx-account-menu__trigger:focus-visible {
+  box-shadow: var(--zx-focus-ring);
+}
+
+.zx-account-menu__chevron {
+  color: var(--zx-color-text-subtle);
+}
+
 .zx-account-menu__identity {
   display: grid;
   min-inline-size: 0;
@@ -36,8 +60,8 @@
   white-space: nowrap;
 }
 
-.zx-account-menu__name { font-weight: 650; }
-.zx-account-menu__secondary { color: var(--zx-color-text-muted); font-size: var(--zx-text-xs); }
+.zx-account-menu__name { font-weight: var(--zx-weight-semibold); }
+.zx-account-menu__secondary { color: var(--zx-color-text-muted); font-size: var(--zx-text-xs); font-weight: 400; }
 .zx-account-menu__chevron { display: inline-flex; }
 
 .zx-account-menu[data-compact="true"] {
@@ -48,6 +72,7 @@
   display: inline-grid;
   grid-template-columns: auto;
   inline-size: auto;
+  padding: var(--zx-space-1);
 }
 
 .zx-account-menu[data-compact="true"] .zx-account-menu__identity,
@@ -61,7 +86,7 @@
   gap: 2px;
   margin: calc(-1 * var(--zx-space-1)) calc(-1 * var(--zx-space-1)) var(--zx-space-1);
   border-block-end: 1px solid var(--zx-color-overlay-divider);
-  padding: var(--zx-space-3);
+  padding: var(--zx-space-2) var(--zx-space-3);
 }
 
 .zx-account-menu__panel-identity span {

package/src/components/activity-item/activity-item.css

@@ -48,7 +48,7 @@
 }
 
 .zx-activity-item__actor {
-  font-weight: 700;
+  font-weight: var(--zx-weight-semibold);
 }
 
 .zx-activity-item__title {

package/src/components/activity-item/activity-item.js

@@ -200,6 +200,9 @@ export class ActivityItem extends Component {
       headingChildren.push(h('span', { class: 'zx-activity-item__actor' }, actor));
     }
     if (title !== null) {
+      // The flex gap separates the two on screen; the space separates them in the heading's text,
+      // which is what a screen reader reads ("Jonas Weber set…", not "Jonas Weberset…").
+      if (headingChildren.length) headingChildren.push(' ');
       headingChildren.push(h('span', { class: 'zx-activity-item__title' }, title));
     }
     const heading = headingChildren.length ? h(`h${normalizeHeadingLevel(activity.headingLevel)}`, {

package/src/components/activity-list/activity-list.css

@@ -15,8 +15,7 @@
   margin: 0;
   color: var(--zx-color-text-muted);
   font-size: var(--zx-text-sm);
-  font-weight: 700;
-  letter-spacing: 0.02em;
+  font-weight: var(--zx-weight-semibold);
 }
 
 .zx-activity-list__items {
@@ -28,7 +27,7 @@
 }
 
 .zx-activity-list__items > .zx-activity-item:not(:last-child) {
-  border-block-end: 1px solid var(--zx-color-border);
+  border-block-end: 1px solid var(--zx-color-border-subtle);
 }
 
 .zx-activity-list__empty,
@@ -62,3 +61,39 @@
 .zx-activity-list__skeleton > .zx-skeleton-text {
   padding-block-start: var(--zx-space-1);
 }
+
+/* ------------------------------------------------------------------ compact -- */
+
+/*
+ * `variant: 'compact'` — one line per entry at any width, for a summary card narrower than 30rem:
+ * who and what read as one sentence that wraps as text, the time keeps the trailing end of the
+ * first line instead of stacking under it, and metadata follows as a muted second line. These
+ * rules outrank the entry's own narrow-container layout, which would stack the header.
+ */
+.zx-activity-list[data-variant="compact"] .zx-activity-item__article {
+  gap: var(--zx-space-2);
+  padding-block: var(--zx-space-2);
+}
+
+.zx-activity-list[data-variant="compact"] .zx-activity-item__main {
+  gap: calc(var(--zx-space-1) / 2);
+}
+
+.zx-activity-list[data-variant="compact"] .zx-activity-item__header {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: baseline;
+  justify-content: flex-start;
+  gap: var(--zx-space-2);
+}
+
+.zx-activity-list[data-variant="compact"] .zx-activity-item__heading {
+  display: block;
+  flex: 1 1 auto;
+}
+
+/* The state badge sits on the first line with the time, not centred against a wrapped sentence. */
+.zx-activity-list[data-variant="compact"] .zx-activity-item__state {
+  align-self: baseline;
+  margin-inline-start: 0;
+}

package/src/components/activity-list/activity-list.js

@@ -9,6 +9,13 @@ import { ActivityItem } from '../activity-item/activity-item.js';
 /** @typedef {string|number|Node|Component|null} ActivityListContent */
 /** @typedef {string|((item:ActivityItemOptions,index:number)=>unknown)|null} ActivityGroupReader */
 /** @typedef {(group:unknown,items:ActivityItemOptions[])=>ActivityListContent} ActivityGroupLabel */
+/**
+ * Entry layout. `'default'` gives each entry its avatar, a heading row, and room for content;
+ * below 30rem the time moves under the heading. `'compact'` is one line per entry at any width —
+ * actor and summary reading as one sentence, the time at the trailing end, a small avatar, and
+ * metadata as a muted second line — for a summary card narrower than 30rem.
+ * @typedef {'default'|'compact'} ActivityListVariant
+ */
 
 /**
  * @typedef {Object} ActivityGroup
@@ -22,6 +29,8 @@ import { ActivityItem } from '../activity-item/activity-item.js';
  * @property {ActivityGroupReader} [groupBy=null] Property or resolver used for stable grouping.
  * @property {ActivityGroupLabel|null} [groupLabel=null] Group-heading renderer.
  * @property {string} [label='Activity'] Accessible collection name.
+ * @property {ActivityListVariant} [variant='default'] Entry layout, reflected as `data-variant` on
+ * the root. `'compact'` also makes an avatar descriptor without a `size` small.
  * @property {boolean} [loading=false] Whether initial or incremental activity is loading.
  * @property {number} [loadingCount=3] Placeholder rows shown for an empty loading list.
  * @property {string} [loadingText='Loading activity'] Loading status text.
@@ -48,6 +57,7 @@ export class ActivityList extends Component {
     groupBy: null,
     groupLabel: null,
     label: 'Activity',
+    variant: 'default',
     loading: false,
     loadingCount: 3,
     loadingText: 'Loading activity',
@@ -78,6 +88,8 @@ export class ActivityList extends Component {
     this._itemComponents = [];
     this._groupSequence = 0;
     root.setAttribute('aria-label', String(this.options.label || 'Activity'));
+    this._variant = normalizeActivityListVariant(this.options.variant);
+    if (this._variant === 'compact') root.dataset.variant = 'compact';
     try {
       this._renderList();
       return root;
@@ -229,6 +241,7 @@ export class ActivityList extends Component {
     for (const item of group.items) {
       const component = new ActivityItem(null, {
         ...item,
+        avatar: this._variant === 'compact' ? compactAvatar(item.avatar) : item.avatar,
         headingLevel: item.headingLevel ?? this.options.itemHeadingLevel
       });
       this._itemComponents.push(component);
@@ -362,6 +375,27 @@ function normalizeHeadingLevel(value, fallback) {
   return /** @type {1|2|3|4|5|6} */ (level >= 1 && level <= 6 ? level : fallback);
 }
 
+/**
+ * Resolves the entry layout; anything but `'compact'` is the default layout.
+ * @param {unknown} value Requested variant.
+ * @returns {ActivityListVariant}
+ */
+export function normalizeActivityListVariant(value) {
+  return value === 'compact' ? 'compact' : 'default';
+}
+
+/**
+ * A compact entry is one line tall, so an avatar descriptor that leaves its size open gets the
+ * small one. An explicit size, an Element, or no avatar passes through untouched.
+ * @param {ActivityItemOptions['avatar']} avatar Avatar descriptor, Element, or null.
+ * @returns {ActivityItemOptions['avatar']}
+ */
+function compactAvatar(avatar) {
+  if (!isPlainObject(avatar)) return avatar;
+  const descriptor = /** @type {import('../avatar/avatar.js').AvatarOptions} */ (avatar);
+  return descriptor.size == null ? { ...descriptor, size: 'sm' } : descriptor;
+}
+
 /** @param {unknown} value @returns {number} */
 function normalizeLoadingCount(value) {
   const count = Math.trunc(Number(value));

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

@@ -153,7 +153,7 @@
   background: var(--zx-color-danger);
   color: var(--zx-color-text-invert);
   font-size: 9px;
-  font-weight: 700;
+  font-weight: var(--zx-weight-semibold);
   line-height: 1;
 }
 

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

@@ -48,13 +48,19 @@
   text-decoration: none;
 }
 
+/* Hover, an open flyout, and a branch over the active route are one light step; the current page
+   is the neutral current fill. Neither is the accent: where you are is not something you picked. */
 .zx-app-rail__item:hover,
 .zx-app-rail__item:focus-visible,
 .zx-app-rail__item[aria-expanded="true"],
-.zx-app-rail__item[data-active-descendant="true"],
-.zx-app-rail__item[aria-current="page"] {
+.zx-app-rail__item[data-active-descendant="true"] {
   background: var(--zx-color-bg-hover);
-  color: var(--zx-color-accent);
+  color: var(--zx-color-text);
+}
+
+.zx-app-rail__item[aria-current="page"] {
+  background: var(--zx-color-bg-current);
+  color: var(--zx-color-text);
 }
 
 .zx-app-rail__item[aria-disabled="true"] {
@@ -86,44 +92,44 @@
  * A minimized sidebar is the same navigation as an expanded one, so the panel a rail item opens
  * has to read as a slice of the tree rather than as a menu that happens to hang off it: the same
  * icon gutter, the same item height, labels that wrap instead of truncating, and the same active
- * recipe — filled pill, docked marker, heavier label.
+ * recipe — the neutral current fill and a heavier label.
  *
  * The panel is portaled to the overlay host, so `.zx-app-sidebar` descendant selectors and the
  * `--zx-app-sidebar-*` scale declared on that root cannot reach it. The scale is re-declared here
- * against the same density-aware tier-2 tokens the sidebar derives it from, so the two surfaces
- * move together when a token moves rather than agreeing on a number frozen twice.
+ * against the same tier-2 control and spacing tokens the sidebar derives it from, so the two
+ * surfaces move together when a token moves rather than agreeing on a number frozen twice.
  */
 .zx-app-rail__popover {
   --zx-app-rail-gutter: var(--zx-space-2);
   --zx-app-rail-icon: var(--zx-space-6);
-  --zx-app-rail-item-gap: var(--zx-space-3);
-  --zx-app-rail-item-height: calc(var(--zx-control-height) + var(--zx-space-2));
-  --zx-app-rail-pad-x: var(--zx-space-3);
-  --zx-app-rail-row-gap: var(--zx-space-1);
-  --zx-app-rail-radius: var(--zx-radius-xl);
-  --zx-app-rail-marker: 3px;
-  --zx-app-rail-hover: color-mix(in srgb, var(--zx-color-text) 7%, transparent);
-  --zx-app-rail-press: color-mix(in srgb, var(--zx-color-text) 14%, transparent);
+  --zx-app-rail-item-gap: var(--zx-space-2);
+  --zx-app-rail-item-height: var(--zx-control-height);
+  --zx-app-rail-pad-x: var(--zx-space-2);
+  --zx-app-rail-row-gap: 2px;
+  --zx-app-rail-radius: var(--zx-radius-md);
+  --zx-app-rail-hover: var(--zx-color-bg-hover);
+  --zx-app-rail-current: var(--zx-color-bg-current);
+  --zx-app-rail-press: color-mix(in srgb, var(--zx-color-text) 12%, transparent);
   min-inline-size: 240px;
 }
 
 /* `styles/zx.css` imports this file before `dropdown.css`, so the two properties the flyout has
-   to take back from the generic overlay surface — the padding, which is the gutter the marker
-   docks into, and the width the panel may grow to, which is the tree's own 280px — have to
+   to take back from the generic overlay surface — the padding, which is the tree's own gutter,
+   and the width the panel may grow to, which is the tree's own 280px — have to
    out-specify it instead of merely following it. The viewport clamp the dropdown guarantees is
    carried over rather than dropped. */
 .zx-dropdown.zx-app-rail__popover {
   max-inline-size: min(280px, calc(100vw - (2 * var(--zx-space-3))));
-  padding: var(--zx-space-2) var(--zx-app-rail-gutter);
+  padding: var(--zx-space-1) var(--zx-app-rail-gutter);
 }
 
 /* The branch's own label, naming what the panel is a slice of. It aligns with the row padding
    rather than with the labels under it: a caption for the list, not a row in it. */
 .zx-app-rail__flyout-title {
-  padding: var(--zx-space-1) var(--zx-app-rail-pad-x) var(--zx-space-2);
+  padding: var(--zx-space-1) var(--zx-app-rail-pad-x);
   color: var(--zx-color-text-muted);
   font-size: var(--zx-text-xs);
-  font-weight: 700;
+  font-weight: var(--zx-weight-semibold);
   line-height: 1.3;
 }
 
@@ -152,7 +158,9 @@
   border: 0;
   border-radius: var(--zx-app-rail-radius);
   background: transparent;
-  padding-block: var(--zx-space-1);
+  /* The icon column fills the row exactly; a row without one keeps a space-1 margin round its
+     label. Either way a single-line row is one control tall, and a wrapped one grows. */
+  padding-block: min(var(--zx-space-1), (var(--zx-app-rail-item-height) - var(--zx-app-rail-icon)) / 2);
   padding-inline: var(--zx-app-rail-pad-x);
   color: var(--zx-color-text);
   font-size: var(--zx-text-md);
@@ -166,39 +174,6 @@
   .zx-app-rail__flyout-item { min-block-size: 40px; }
 }
 
-/* The marker, docked to the panel's own leading edge exactly as the tree's is docked to the
-   sidebar's: it sits in the panel's gutter, so every row lines up however deep the flyout chain
-   runs. On a right-hand rail the panel opens toward the workspace and the marker moves to the
-   edge facing the screen, which is the rule `.zx-app-sidebar[data-side="right"]` states. */
-.zx-app-rail__flyout-item::before {
-  content: "";
-  position: absolute;
-  inset-block: 50%;
-  inset-inline-start: calc(-1 * var(--zx-app-rail-gutter));
-  inline-size: var(--zx-app-rail-marker);
-  border-start-end-radius: var(--zx-radius-full);
-  border-end-end-radius: var(--zx-radius-full);
-  background: var(--zx-color-accent);
-  opacity: 0;
-}
-
-.zx-app-rail__popover[data-side="right"] .zx-app-rail__flyout-item::before {
-  inset-inline: auto calc(-1 * var(--zx-app-rail-gutter));
-  border-radius: 0;
-  border-start-start-radius: var(--zx-radius-full);
-  border-end-start-radius: var(--zx-radius-full);
-}
-
-.zx-app-rail__flyout-item[aria-current="page"]::before {
-  inset-block: 25%;
-  opacity: 1;
-}
-
-.zx-app-rail__flyout-item[data-active-descendant="true"][aria-expanded="false"]::before {
-  inset-block: 38%;
-  opacity: .55;
-}
-
 .zx-app-rail__flyout-item-icon {
   grid-column: 1;
   display: flex;
@@ -247,34 +222,28 @@
 }
 
 .zx-app-rail__flyout-item[data-active-descendant="true"][aria-expanded="false"] {
-  color: var(--zx-color-accent);
-  font-weight: 600;
+  font-weight: var(--zx-weight-semibold);
 }
 
-.zx-app-rail__flyout-item[aria-current="page"] {
-  background: var(--zx-color-accent);
-  color: var(--zx-color-on-accent);
-  font-weight: 600;
+.zx-app-rail__flyout-item[data-active-descendant="true"][aria-expanded="false"] .zx-app-rail__flyout-item-icon {
+  color: var(--zx-color-text);
 }
 
-.zx-app-rail__flyout-item[aria-current="page"]:hover {
-  background: color-mix(in srgb, var(--zx-color-text) 8%, var(--zx-color-accent));
+/* The current page, as in the tree: the neutral current fill, the full text colour and a heavier
+   label, with the shared focus ring drawn on top when a keyboard user arrives on it. */
+.zx-app-rail__flyout-item[aria-current="page"] {
+  background: var(--zx-app-rail-current);
+  color: var(--zx-color-text);
+  font-weight: var(--zx-weight-semibold);
 }
 
 .zx-app-rail__flyout-item[aria-current="page"]:active {
-  background: color-mix(in srgb, var(--zx-color-text) 16%, var(--zx-color-accent));
-}
-
-/* An accent glow around an accent fill is a ring nobody can see, so the pill draws an inner line
-   in its own text colour first — the same repair the tree makes. */
-.zx-app-rail__flyout-item[aria-current="page"]:focus-visible {
-  box-shadow: inset 0 0 0 2px var(--zx-color-on-accent), var(--zx-focus-ring);
+  background: var(--zx-app-rail-press);
 }
 
 .zx-app-rail__flyout-item[aria-current="page"] .zx-app-rail__flyout-item-icon,
-.zx-app-rail__flyout-item[aria-current="page"] .zx-app-rail__flyout-item-badge,
 .zx-app-rail__flyout-item[aria-current="page"] .zx-app-rail__flyout-item-disclosure {
-  color: inherit;
+  color: var(--zx-color-text);
 }
 
 /* Unavailable, and still readable: the icon carries the dimming so the label can keep the muted
@@ -296,23 +265,15 @@
       box-shadow var(--zx-dur-fast) var(--zx-ease);
   }
 
-  .zx-app-rail__flyout-item::before {
-    transition: opacity var(--zx-dur-base) var(--zx-ease),
-      inset-block var(--zx-dur-base) var(--zx-ease);
-  }
-
   .zx-app-rail__flyout-item:active { transform: scale(.985); }
 }
 
-/* Forced colours drop the fill and the marker together; the system's selected pair carries the
-   state there instead. */
+/* Forced colours drop the fill; the system's selected pair carries the state there instead. */
 @media (forced-colors: active) {
   .zx-app-rail__flyout-item[aria-current="page"] {
     background: Highlight;
     color: HighlightText;
   }
-
-  .zx-app-rail__flyout-item::before { background: Highlight; }
 }
 
 @media (prefers-reduced-transparency: reduce) {