@zeyos/zx 5.0.0 → 5.2.0

package/docs/llms.txt

@@ -35,7 +35,9 @@ exports and as `window.zx.*`.
   drag and resize, `optimistic: true|false`), backend-neutral nested `Filter`, simple client-side
   `DataFilter`, `FilterPanel` (typed filter form built from a server's own field metadata;
   `mode: 'draft'|'live'`, `serialize`), `ListToolbar` (search, live result count, view switch, and
-  tools whose badge is part of the accessible name), `Pagination` (+ pure `paginationRange()`),
+  tools whose badge is part of the accessible name), `ViewSettings` (view-settings drawer content:
+  reorder, hide, and add fields, grouping, board axes; `bind()` to a record view),
+  `Pagination` (+ pure `paginationRange()`),
   `SortControl` (searchable field selector with a direction toggle, one atomic `{id,dir}`),
   `TreeView` (APG tree), `Finder` (Miller columns).
 - Forms: `Form`, `Fieldset`, `Questionnaire` (guided one-question-at-a-time flow with branching), `Field` (type registry), `CodeEditor` (structured text in a native textarea; never executes or injects the value), `ValueList`, `MultiValueEditor`, `FieldUpload`.
@@ -47,7 +49,9 @@ exports and as `window.zx.*`.
   canvas light; shared material roles govern chrome and overlays), `Avatar`, `Panel` (header/footer action
   buttons), `MasterPanel`, `Tabbox`
   (`variant: 'divided'|'bracket'|'line'|'segmented'`), `NavigationBar`, `AppSidebar` (expanded and
-  minimized vertical states plus horizontal rail layouts), `AccountMenu`, `Launcher`,
+  minimized vertical states plus horizontal rail layouts; sections; a modules layout), `ModuleBar`
+  (colour-coded module strip or bar with flyout menus and an "All modules" catalogue), `AccountMenu`,
+  `WorkspaceSwitcher` (workspace tile, name and menu at the head of a navigation column), `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`,

package/package.json

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

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

@@ -124,6 +124,18 @@ export class AccountMenu extends Component {
     return this;
   }
 
+  /**
+   * Shows the avatar alone or the avatar with the name and secondary line — for a navigation
+   * column that narrows to icons and widens again. The trigger keeps its full accessible name
+   * either way.
+   * @param {boolean} compact
+   * @returns {this}
+   */
+  setCompact(compact) {
+    this.el.dataset.compact = String(Boolean(compact));
+    return this;
+  }
+
   /** Replaces account actions. @param {MenuButtonItem[]} items @returns {this} */
   setItems(items) {
     this._menu.setItems(items);

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

@@ -1,6 +1,7 @@
 // @ts-check
 import { Component } from '../../core/component.js';
 import { h, restoreTarget, snapshotTarget } from '../../core/dom.js';
+import { captureItemFocus, restoreItemFocus } from '../../core/keyboard.js';
 import { uid } from '../../core/util.js';
 import { skeleton, skeletonText } from '../skeleton/skeleton.js';
 import { ActivityItem } from '../activity-item/activity-item.js';
@@ -208,8 +209,33 @@ export class ActivityList extends Component {
     if (!this._createdRoot) restoreTarget(this.el, this._original);
   }
 
-  /** @private @returns {void} */
+  /**
+   * Rebuilds the list. Items are regrouped on every mutation, so the rows are new; focus that sat
+   * on an item's control is put back on the same control of the same activity (matched by `id`,
+   * else by position), so a live feed prepending entries does not throw the reader to `<body>`.
+   * @private
+   * @returns {void}
+   */
   _renderList() {
+    const root = /** @type {HTMLElement} */ (this.el);
+    const focus = captureItemFocus(root, (element) => {
+      const index = this._itemComponents.findIndex((item) => item.el?.contains(element));
+      if (index < 0) return null;
+      const component = this._itemComponents[index];
+      return { key: { id: component.getActivity().id ?? null, index }, element: component.el };
+    });
+    this._renderItems();
+    restoreItemFocus(root, focus, (key) => {
+      const memo = /** @type {{id: unknown, index: number}} */ (key);
+      const match = memo.id === null ? undefined
+        : this._itemComponents.find((item) => Object.is(item.getActivity().id ?? null, memo.id));
+      const fallback = match ?? this._itemComponents[Math.min(memo.index, this._itemComponents.length - 1)];
+      return fallback?.el ?? null;
+    });
+  }
+
+  /** @private @returns {void} */
+  _renderItems() {
     this._destroyItems();
     this._groupSequence = 0;
     const root = /** @type {HTMLElement} */ (this.el);

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

@@ -26,6 +26,17 @@
   border-radius: var(--zx-radius-full);
 }
 
+/* A tone is identity from the theme's categorical palette. An inline `color` overrides it. */
+.zx-app-icon[data-tone="blue"] { --zx-app-icon-color: var(--zx-color-tone-blue-solid); }
+.zx-app-icon[data-tone="teal"] { --zx-app-icon-color: var(--zx-color-tone-teal-solid); }
+.zx-app-icon[data-tone="green"] { --zx-app-icon-color: var(--zx-color-tone-green-solid); }
+.zx-app-icon[data-tone="amber"] { --zx-app-icon-color: var(--zx-color-tone-amber-solid); }
+.zx-app-icon[data-tone="orange"] { --zx-app-icon-color: var(--zx-color-tone-orange-solid); }
+.zx-app-icon[data-tone="red"] { --zx-app-icon-color: var(--zx-color-tone-red-solid); }
+.zx-app-icon[data-tone="pink"] { --zx-app-icon-color: var(--zx-color-tone-pink-solid); }
+.zx-app-icon[data-tone="violet"] { --zx-app-icon-color: var(--zx-color-tone-violet-solid); }
+.zx-app-icon[data-tone="slate"] { --zx-app-icon-color: var(--zx-color-tone-slate-solid); }
+
 .zx-app-icon__surface {
   position: absolute;
   z-index: 0;
@@ -62,7 +73,7 @@
 .zx-app-icon[data-glass="none"] .zx-app-icon__surface::after { display: none; }
 
 .zx-app-icon[data-selected] .zx-app-icon__surface {
-  outline: none;
+  outline-color: transparent;
   box-shadow: 0 0 0 1px var(--zx-color-bg-page),
     0 0 0 3px var(--zx-app-icon-selected-ring),
     var(--zx-app-icon-shadow-hover),
@@ -166,7 +177,7 @@
 
 .zx-app-icon:is(a, button, [role="button"]):not(:disabled):not([aria-disabled="true"]):focus-visible .zx-app-icon__surface,
 :is(a, button, [role="button"]):not(:disabled):not([aria-disabled="true"]):focus-visible .zx-app-icon__surface {
-  outline: none;
+  outline-color: transparent;
   box-shadow: var(--zx-focus-ring), var(--zx-app-icon-shadow-hover), var(--zx-app-icon-halo);
 }
 

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

@@ -3,10 +3,16 @@ import { h, restoreTarget, snapshotTarget } from '../../core/dom.js';
 import { icon as renderIcon } from '../../core/icons.js';
 import { isCssColor } from '../../core/util.js';
 
+/** @typedef {'blue'|'teal'|'green'|'amber'|'orange'|'red'|'pink'|'violet'|'slate'} AppIconTone */
+/** The categorical tones a `tone` option accepts. @type {ReadonlyArray<AppIconTone>} */
+export const APP_ICON_TONES = Object.freeze(['blue', 'teal', 'green', 'amber', 'orange', 'red', 'pink', 'violet', 'slate']);
+
 /**
  * @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 {string|null} [color=null] Identity colour, any CSS colour; takes precedence over `tone`.
+ * @property {AppIconTone|null} [tone=null] Categorical identity colour from the theme's tone palette,
+ *   drawn with its `--zx-color-tone-<tone>-solid` fill. Without `color` or `tone` the icon takes the accent.
  * @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.
@@ -28,6 +34,7 @@ export class AppIcon extends Component {
   static defaults = {
     icon: null,
     color: null,
+    tone: null,
     size: 36,
     iconSize: '52%',
     label: null,
@@ -80,6 +87,9 @@ export class AppIcon extends Component {
     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');
+    // An inline colour outranks the tone rule in the stylesheet, which is what makes `color` win.
+    if (APP_ICON_TONES.includes(state.tone)) this.el.dataset.tone = state.tone;
+    else delete this.el.dataset.tone;
     this.el.dataset.glass = normalizeGlass(state.glass);
     this.el.dataset.shape = normalizeShape(state.shape);
     this.el.toggleAttribute('data-selected', Boolean(state.selected));

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

@@ -34,6 +34,16 @@
 .zx-app-rail[data-orientation="horizontal"] .zx-app-rail__list { flex-direction: row; }
 .zx-app-rail__row { display: flex; }
 
+/* Where a section of the tree ends on a rail: a short rule, since a rail has no room for a heading. */
+.zx-app-rail__separator {
+  flex: none;
+  align-self: center;
+  background: var(--zx-color-border-subtle);
+}
+
+.zx-app-rail[data-orientation="vertical"] .zx-app-rail__separator { inline-size: var(--zx-space-4); block-size: 1px; margin-block: var(--zx-space-1); }
+.zx-app-rail[data-orientation="horizontal"] .zx-app-rail__separator { inline-size: 1px; block-size: var(--zx-space-4); margin-inline: var(--zx-space-1); }
+
 .zx-app-rail__item {
   position: relative;
   display: inline-grid;
@@ -133,6 +143,15 @@
   line-height: 1.3;
 }
 
+/* A section inside a flyout keeps its heading, in the same quiet caption as the panel's title. */
+.zx-app-rail__flyout-section {
+  padding: var(--zx-space-2) var(--zx-app-rail-pad-x) var(--zx-space-1);
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-xs);
+  font-weight: var(--zx-weight-semibold);
+  line-height: 1.3;
+}
+
 .zx-app-rail__flyout-list {
   display: grid;
   gap: var(--zx-app-rail-row-gap);

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

@@ -113,7 +113,9 @@
    single icon keeps the column on every row so the labels stay in one line down the list. Each
    list answers for its own rows only — a branch of plain labels under iconned parents drops the
    column without taking it from the parents. */
-.zx-app-sidebar__list:not(:has(> .zx-app-sidebar__row > .zx-app-sidebar__item .zx-app-sidebar__item-icon)),
+.zx-app-sidebar__list:not(:has(> .zx-app-sidebar__row > .zx-app-sidebar__item .zx-app-sidebar__item-icon,
+  > .zx-app-sidebar__section > .zx-app-sidebar__section-list > .zx-app-sidebar__row > .zx-app-sidebar__item .zx-app-sidebar__item-icon)),
+.zx-app-sidebar__section-list:not(:has(> .zx-app-sidebar__row > .zx-app-sidebar__item .zx-app-sidebar__item-icon)),
 .zx-app-sidebar__sublist:not(:has(> .zx-app-sidebar__row > .zx-app-sidebar__item .zx-app-sidebar__item-icon)) {
   --zx-app-sidebar-icon: 0px;
   --zx-app-sidebar-item-gap: 0px;
@@ -169,6 +171,43 @@
 
 .zx-app-sidebar__list > .zx-app-sidebar__row:first-child { margin-block-start: 0; }
 
+/*
+ * Sections. A heading over rows that stay at its own level: not a branch, never collapsed, never
+ * focused. Sections are separated by the group gap, like the groups a branch opens, and the
+ * heading is the same quiet sentence-case caption a flyout uses for its title.
+ */
+.zx-app-sidebar__section { list-style: none; }
+
+.zx-app-sidebar__section + .zx-app-sidebar__section,
+.zx-app-sidebar__section + .zx-app-sidebar__row,
+.zx-app-sidebar__row + .zx-app-sidebar__section {
+  margin-block-start: var(--zx-app-sidebar-group-gap);
+}
+
+.zx-app-sidebar__section-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--zx-space-2);
+  min-block-size: calc(var(--zx-control-height) - var(--zx-space-1));
+  padding-inline: var(--zx-app-sidebar-pad-x) var(--zx-space-1);
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-xs);
+  font-weight: var(--zx-weight-semibold);
+  line-height: 1.3;
+}
+
+.zx-app-sidebar__section-label { min-inline-size: 0; overflow-wrap: break-word; }
+.zx-app-sidebar__section-actions { display: inline-flex; flex: none; align-items: center; gap: var(--zx-space-1); }
+
+.zx-app-sidebar__section-list {
+  display: grid;
+  gap: var(--zx-app-sidebar-row-gap);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
 .zx-app-sidebar__item {
   position: relative;
   display: grid;
@@ -294,7 +333,165 @@
 }
 .zx-app-sidebar__footer[hidden] { display: none; }
 
-.zx-app-sidebar__rail-header { display: grid; gap: var(--zx-space-1); }
+.zx-app-sidebar__rail-header { display: grid; gap: var(--zx-space-1); justify-items: center; }
+
+/*
+ * The modules layout: the module strip beside a panel of one module's menu. Both share the
+ * sidebar's chrome surface; the subtle rule between them is the one line tone cannot draw, since
+ * they are the same tone.
+ */
+.zx-app-sidebar__modules {
+  display: flex;
+  min-inline-size: 0;
+  min-block-size: 0;
+}
+
+.zx-app-sidebar[data-side="right"] .zx-app-sidebar__modules { flex-direction: row-reverse; }
+
+.zx-app-sidebar__strip.zx-module-bar { background: transparent; }
+.zx-app-sidebar__modules > .zx-app-sidebar__strip { border-inline-end: 1px solid var(--zx-color-border-subtle); }
+.zx-app-sidebar[data-side="right"] .zx-app-sidebar__modules > .zx-app-sidebar__strip {
+  border-inline-end: 0;
+  border-inline-start: 1px solid var(--zx-color-border-subtle);
+}
+
+.zx-app-sidebar[data-layout="modules"][data-orientation="horizontal"] > .zx-app-sidebar__strip { inline-size: 100%; }
+
+/* The foot of the strip: the one expand/collapse control, then what the application put there.
+   With names beside the tiles it lines up with their tiles rather than sitting centred. */
+.zx-app-sidebar__strip-foot {
+  display: grid;
+  justify-items: center;
+  gap: var(--zx-space-2);
+}
+
+.zx-app-sidebar__strip[data-labels="beside"] .zx-app-sidebar__strip-foot {
+  justify-items: stretch;
+  /* The toggle's centre on the tiles' centre: list inset + row inset, less the footer's own pad. */
+  padding-inline-start: calc(var(--zx-space-1) + var(--zx-space-2) - var(--zx-module-bar-pad)
+    + (var(--zx-module-bar-tile) - var(--zx-control-height)) / 2);
+}
+
+/* With names printed the strip's head spans the column, like the rows under it. */
+.zx-app-sidebar__strip[data-labels="beside"] .zx-app-sidebar__rail-header { justify-items: stretch; }
+
+.zx-app-sidebar__presentation {
+  display: inline-grid;
+  justify-self: center;
+  gap: 2px;
+  border-radius: var(--zx-radius-md);
+  background: var(--zx-color-bg-hover);
+  padding: 2px;
+}
+
+/* Named strip: the three options in a row at the start of the foot; icon strip: a column. */
+.zx-app-sidebar__strip[data-labels="beside"] .zx-app-sidebar__presentation {
+  grid-auto-flow: column;
+  justify-self: start;
+}
+
+.zx-app-sidebar__presentation-option {
+  display: grid;
+  place-items: center;
+  inline-size: var(--zx-space-6);
+  block-size: var(--zx-space-6);
+  border: 0;
+  border-radius: var(--zx-radius-sm);
+  background: transparent;
+  padding: 0;
+  color: var(--zx-color-text-muted);
+  cursor: pointer;
+}
+
+.zx-app-sidebar__presentation-option:hover { color: var(--zx-color-text); }
+
+/* The chosen presentation is where you are: the surface lifted out of the track, full text colour. */
+.zx-app-sidebar__presentation-option[aria-checked="true"] {
+  background: var(--zx-color-bg-surface);
+  box-shadow: 0 0 0 1px var(--zx-color-border-subtle);
+  color: var(--zx-color-text);
+}
+
+.zx-app-sidebar__presentation-option:focus-visible {
+  outline-color: transparent;
+  box-shadow: var(--zx-focus-ring);
+}
+
+/*
+ * The pictogram: a window with its navigation drawn in it — a module strip, wide when it is named,
+ * and a side menu when it shows. Drawn from boxes in the text colour, so it needs no icon set and
+ * follows the theme, forced colours included.
+ */
+.zx-app-sidebar__presentation-glyph {
+  display: flex;
+  gap: 1px;
+  box-sizing: border-box;
+  inline-size: 16px;
+  block-size: 12px;
+  border: 1.5px solid currentColor;
+  border-radius: 2px;
+  padding: 1px;
+}
+
+.zx-app-sidebar__presentation-strip,
+.zx-app-sidebar__presentation-panel {
+  border-radius: 1px;
+  background: currentColor;
+}
+
+.zx-app-sidebar__presentation-strip { flex: 0 0 2px; }
+.zx-app-sidebar__presentation-panel { flex: 0 0 4px; opacity: .5; }
+.zx-app-sidebar__presentation-glyph[data-presentation="expanded"] > .zx-app-sidebar__presentation-strip { flex-basis: 4px; }
+.zx-app-sidebar__presentation-glyph[data-presentation="collapsed"] > .zx-app-sidebar__presentation-panel { display: none; }
+
+@media (forced-colors: active) {
+  .zx-app-sidebar__presentation-option[aria-checked="true"] {
+    background: Highlight;
+    color: HighlightText;
+    forced-color-adjust: none;
+  }
+}
+
+.zx-app-sidebar__panel {
+  display: grid;
+  grid-template-rows: auto minmax(0, 1fr) auto;
+  inline-size: min(14rem, 100vw - var(--zx-control-height) * 3);
+  min-block-size: 0;
+}
+
+.zx-app-sidebar__panel-title {
+  color: var(--zx-color-text);
+  font-size: var(--zx-text-md);
+  font-weight: var(--zx-weight-semibold);
+  line-height: 1.3;
+  overflow-wrap: break-word;
+}
+
+/* One scroller for the module's lead content, its menu, and its own content, so a long menu and
+   a long list under it read as one column. The nav loses its own scroll box inside it. */
+.zx-app-sidebar__panel-body {
+  display: grid;
+  /* Rows take their content's height and the body scrolls; a row the grid could shrink would
+     draw the menu under the content beneath it. */
+  grid-auto-rows: max-content;
+  align-content: start;
+  min-block-size: 0;
+  overflow: auto;
+}
+
+.zx-app-sidebar__panel-body > .zx-app-sidebar__nav { overflow: visible; min-block-size: auto; }
+.zx-app-sidebar__panel-body > [hidden] { display: none; }
+
+.zx-app-sidebar__panel-lead {
+  display: grid;
+  gap: var(--zx-space-2);
+  padding: var(--zx-space-1) var(--zx-space-3) 0;
+}
+
+.zx-app-sidebar__panel-content {
+  min-inline-size: 0;
+  padding: 0 var(--zx-app-sidebar-gutter) var(--zx-space-3);
+}
 
 /*
  * The minimized rail. Only the presentation changes; the same vocabulary applies — the neutral
@@ -379,9 +576,13 @@
   .zx-app-sidebar__rail .zx-app-rail__item:active { transform: scale(.985); }
 
   .zx-app-sidebar__expanded,
-  .zx-app-sidebar__rail { animation: zx-app-sidebar-mode var(--zx-dur-base) var(--zx-ease); }
+  .zx-app-sidebar__rail,
+  .zx-app-sidebar__panel { animation: zx-app-sidebar-mode var(--zx-dur-base) var(--zx-ease); }
 
   .zx-app-sidebar__sublist[data-branch-motion="expand"] { animation: zx-app-sidebar-branch var(--zx-dur-base) var(--zx-ease); }
+
+  /* The panel's content cross-fades when it switches module; the width never animates. */
+  .zx-app-sidebar__panel-body[data-module-motion="enter"] { animation: zx-app-sidebar-mode var(--zx-dur-base) var(--zx-ease); }
 }
 
 @keyframes zx-app-sidebar-mode {