@zeyos/zx 5.0.0 → 5.2.0

package/src/internal/app-rail.js

@@ -17,6 +17,9 @@ import { Tooltip } from '../components/tooltip/tooltip.js';
  * @property {() => void} [invoke] Application-owned non-link action.
  * @property {boolean} [disabled] Whether activation is unavailable.
  * @property {AppNavItem[]} [children] Child destinations/actions.
+ * @property {boolean} [section] Makes the item a section: a quiet heading over its `children`, which
+ *   render at the same level. A section is never focused, selected, or collapsed, and needs no `id`.
+ * @property {Node|{toElement: () => Node|null}} [actions] A section's trailing controls, such as an add button.
  */
 /**
  * @typedef {Object} AppRailPresenterOptions
@@ -45,6 +48,14 @@ import { Tooltip } from '../components/tooltip/tooltip.js';
 export class AppRailPresenter extends Component {
   static cssName = 'app-rail';
 
+  /**
+   * BEM block of the rail's own parts (header, list, footer, row, item). A component built on the
+   * presenter names its parts after itself; flyout panels keep the `zx-app-rail__` vocabulary,
+   * because every rail portals the same panel.
+   * @type {string}
+   */
+  static partBlock = 'zx-app-rail';
+
   /** @type {Readonly<AppRailPresenterOptions>} */
   static defaults = {
     items: [],
@@ -93,13 +104,14 @@ export class AppRailPresenter extends Component {
     root.dataset.orientation = this.options.orientation === 'horizontal' ? 'horizontal' : 'vertical';
     const sides = root.dataset.orientation === 'horizontal' ? ['top', 'bottom'] : ['left', 'right'];
     root.dataset.side = sides.includes(this.options.side) ? this.options.side : sides[0];
-    const header = h('div', { class: 'zx-app-rail__header' });
-    const footer = h('div', { class: 'zx-app-rail__footer' });
+    const block = this._partBlock();
+    const header = h('div', { class: `${block}__header` });
+    const footer = h('div', { class: `${block}__footer` });
     appendSlot(header, this.options.header);
     appendSlot(footer, this.options.footer);
     header.hidden = !header.hasChildNodes();
     footer.hidden = !footer.hasChildNodes();
-    root.replaceChildren(header, h('ul', { ref: 'list', class: 'zx-app-rail__list' }), footer);
+    root.replaceChildren(header, h('ul', { ref: 'list', class: `${block}__list` }), footer);
     this.listen(root, 'keydown', (event) => this._onRailKeydown(/** @type {KeyboardEvent} */ (event)));
     return root;
   }
@@ -209,31 +221,28 @@ export class AppRailPresenter extends Component {
     this._clearArtifacts();
     this.refs.list.replaceChildren();
     this._interaction = new RailListenerScope(/** @type {HTMLElement} */ (this.el));
-    this._items.forEach((item) => {
-      const hasChildren = Array.isArray(item.children) && item.children.length > 0;
-      const control = navControl(item, {
-        className: 'zx-app-rail__item',
-        index: String(item.id),
-        iconOnly: true,
-        disclosure: hasChildren,
-        disclosureIcon: railDisclosureIcon(this.el.dataset.side),
-        visual: appNavIcon(item, this.options.renderIcon, {
-          orientation: this.el.dataset.orientation,
-          collapsed: true,
-          side: this.el.dataset.side,
-          level: 1,
-          location: 'root'
-        })
-      });
-      const row = h('li', { class: 'zx-app-rail__row' }, control);
+    let started = false;
+    for (const item of railEntries(this._items)) {
+      // A section has no rail control: the rail draws a rule between the groups instead.
+      if (item === SECTION_BREAK) {
+        if (started) this.refs.list.append(h('li', { class: `${this._partBlock()}__separator`, ariaHidden: 'true' }));
+        continue;
+      }
+      started = true;
+      const hasChildren = Array.isArray(item.children) && item.children.length > 0
+        && this._flyoutsFor(item);
+      const control = this._renderControl(item, hasChildren);
+      const row = h('li', { class: `${this._partBlock()}__row` }, control);
       this.refs.list.append(row);
-      const tooltip = new Tooltip(control, {
-        content: item.label,
-        placement: tooltipPlacement(this.el.dataset.side),
-        delay: 450
-      });
-      this._tooltips.push(tooltip);
-      this._tooltipById.set(String(item.id), tooltip);
+      if (this._tooltipFor(item)) {
+        const tooltip = new Tooltip(control, {
+          content: item.label,
+          placement: tooltipPlacement(this.el.dataset.side),
+          delay: 450
+        });
+        this._tooltips.push(tooltip);
+        this._tooltipById.set(String(item.id), tooltip);
+      }
       if (hasChildren) this._buildFlyout(item, control, String(item.id), null);
       else this._interaction.listen(control, 'click', (event) => {
         const selected = this._select(item, event);
@@ -243,21 +252,66 @@ export class AppRailPresenter extends Component {
           }
         }
       });
-    });
-    this._interaction.listen(document, 'pointerdown', (event) => {
-      const open = [...this._flyouts.values()].filter((flyout) => flyout.dropdown.isOpen());
-      if (open.length === 0) return;
-      const path = event.composedPath();
-      if (open.some((flyout) => path.includes(flyout.panel) || path.includes(flyout.trigger))) return;
-      for (const flyout of open) if (flyout.parentKey === null) this.closeFlyout(flyout.key);
-    });
+    }
+    // Outside presses need no listener here: each open flyout is a Dropdown on the overlay stack,
+    // which closes it on a press outside it and every flyout opened from it, and a nested flyout,
+    // anchored inside its parent's panel, counts as part of that parent.
+    this._afterRebuild();
     this._syncActive();
   }
 
+  /** @returns {string} The BEM block of the rail's own parts. @protected */
+  _partBlock() {
+    return /** @type {typeof AppRailPresenter} */ (this.constructor).partBlock;
+  }
+
+  /**
+   * Builds one top-level rail control. The control must carry `data-app-nav-id` and
+   * `data-app-nav-value-id`, which keyboard handling, flyouts, and the active state read.
+   * @param {AppNavItem} item Top-level item.
+   * @param {boolean} hasFlyout Whether the control opens a flyout of the item's children.
+   * @returns {HTMLElement}
+   * @protected
+   */
+  _renderControl(item, hasFlyout) {
+    return navControl(item, {
+      className: 'zx-app-rail__item',
+      index: String(item.id),
+      iconOnly: true,
+      disclosure: hasFlyout,
+      disclosureIcon: railDisclosureIcon(this.el.dataset.side),
+      visual: appNavIcon(item, this.options.renderIcon, {
+        orientation: this.el.dataset.orientation,
+        collapsed: true,
+        side: this.el.dataset.side,
+        level: 1,
+        location: 'root'
+      })
+    });
+  }
+
+  /** Whether an item with children presents them in a flyout. @param {AppNavItem} item @returns {boolean} @protected */
+  _flyoutsFor(item) {
+    return true;
+  }
+
+  /** Whether a top-level control gets a hover/focus tooltip naming it. @param {AppNavItem} item @returns {boolean} @protected */
+  _tooltipFor(item) {
+    return true;
+  }
+
+  /** Runs after every rebuild, before the active state is applied. @returns {void} @protected */
+  _afterRebuild() {}
+
   /** @param {AppNavItem} item @param {HTMLElement} trigger @param {string} key @param {string|null} parentKey @returns {void} */
   _buildFlyout(item, trigger, key, parentKey) {
     const list = h('ul', { class: 'zx-app-rail__flyout-list' });
-    for (const child of item.children ?? []) {
+    for (const child of railEntries(item.children ?? [], true)) {
+      if (child.section) {
+        // A caption, not a destination: keyboard movement skips it with every other non-action.
+        list.append(h('li', { class: 'zx-app-rail__flyout-section' }, child.label));
+        continue;
+      }
       const childKey = `${key}/${child.id}`;
       const hasChildren = Boolean(child.children?.length);
       const control = navControl(child, {
@@ -292,6 +346,17 @@ export class AppRailPresenter extends Component {
       offset: 6
     });
     const actualPanel = dropdown.getPanel();
+    // Escape arrives through the overlay stack, which offers it to the topmost flyout only. The
+    // rail returns focus itself, so the trigger's focus does not reopen what Escape just closed,
+    // and a flyout is reached with the arrow keys rather than Tab: every tile is its own Tab stop.
+    dropdown._configure({
+      tabReach: false,
+      onEscape: () => {
+        const hadFocus = actualPanel.contains(document.activeElement);
+        this.closeFlyout(key);
+        if (hadFocus) this._restoreFocus(trigger);
+      }
+    });
     actualPanel.classList.add('zx-app-rail__popover');
     // The panel is portaled out of the rail, so its stylesheet cannot ask which edge the rail
     // occupies. Presentation only: it tells the panel's styles which side it opened from.
@@ -300,10 +365,15 @@ export class AppRailPresenter extends Component {
     actualPanel.setAttribute('aria-label', this._message('appRail.subNavigation', '%1 sub-navigation', item.label));
     const flyout = { key, parentKey, item, trigger, panel: actualPanel, dropdown };
     this._flyouts.set(key, flyout);
+    // While a tile's own flyout is open its tooltip says nothing the flyout's title does not, and
+    // would take the first Escape meant for the flyout.
+    const tooltip = parentKey === null ? this._tooltipById.get(String(item.id)) : null;
     dropdown.on('open', () => {
+      tooltip?.disable();
       if (!this._silenceFlyoutEvents) this.emit('flyoutchange', { item, id: item.id, open: true });
     });
     dropdown.on('close', () => {
+      tooltip?.enable();
       if (!this._silenceFlyoutEvents) this.emit('flyoutchange', { item, id: item.id, open: false });
     });
 
@@ -393,20 +463,6 @@ export class AppRailPresenter extends Component {
     const controls = actions(flyout.panel);
     const current = /** @type {Element|null} */ (event.target)?.closest?.('a, button');
     const index = controls.indexOf(current);
-    if (event.key === 'Escape') {
-      event.preventDefault();
-      event.stopPropagation();
-      const nested = [...this._flyouts.values()].find((candidate) =>
-        candidate.trigger === current && candidate.dropdown.isOpen());
-      if (nested) {
-        this.closeFlyout(nested.key);
-        this._restoreFocus(nested.trigger);
-        return;
-      }
-      this.closeFlyout(flyout.key);
-      this._restoreFocus(flyout.trigger);
-      return;
-    }
     const nested = [...this._flyouts.values()].find((candidate) => candidate.trigger === current);
     const into = this.el.dataset.side === 'right' ? 'ArrowLeft' : 'ArrowRight';
     const out = into === 'ArrowRight' ? 'ArrowLeft' : 'ArrowRight';
@@ -416,7 +472,8 @@ export class AppRailPresenter extends Component {
       this.openFlyout(nested.key, { focus: true });
       return;
     }
-    if (flyout.parentKey !== null && event.key === out) {
+    // Out of a nested flyout, or out of a top-level one beside a vertical rail, back to its trigger.
+    if ((flyout.parentKey !== null || this.el.dataset.orientation === 'vertical') && event.key === out) {
       event.preventDefault();
       event.stopPropagation();
       this.closeFlyout(flyout.key);
@@ -606,6 +663,22 @@ class RailListenerScope extends Component {
   }
 }
 
+/** Marks the boundary of a section in a flattened rail. */
+const SECTION_BREAK = Object.freeze({});
+
+/**
+ * Flattens sections for a rail: a section's children take its place. With `labels`, each section
+ * leaves its own item ahead of its children, for a flyout to caption; otherwise a section break.
+ * @param {AppNavItem[]} items Normalized items.
+ * @param {boolean} [labels=false] Keep section items as captions.
+ * @returns {AppNavItem[]}
+ */
+function railEntries(items, labels = false) {
+  return items.flatMap((item) => (item.section
+    ? [labels ? item : /** @type {AppNavItem} */ (SECTION_BREAK), ...railEntries(item.children ?? [], labels)]
+    : [item]));
+}
+
 /**
  * Normalizes an application navigation tree without mutating caller data.
  * @param {unknown} items Candidate tree.
@@ -613,13 +686,21 @@ class RailListenerScope extends Component {
  */
 export function normalizeAppItems(items) {
   if (!Array.isArray(items)) return [];
-  return items.filter((item) => item && typeof item === 'object' && item.id != null && item.label != null)
-    .map((item) => {
+  return items.filter((item) => item && typeof item === 'object' && item.label != null
+    && (item.id != null || item.section === true))
+    .map((item, index) => {
       const normalized = {
         ...item,
+        // A section is addressed by nothing, so one written without an id gets a stable one.
+        id: item.id ?? `section:${index}:${item.label}`,
         label: String(item.label),
         children: Array.isArray(item.children) ? normalizeAppItems(item.children) : []
       };
+      if (item.section === true) {
+        normalized.section = true;
+        delete normalized.href;
+        return normalized;
+      }
       if (item.href == null) return normalized;
       const href = safeHref(item.href);
       if (href !== null) normalized.href = href;

package/src/internal/menu-items.js

@@ -1,5 +1,6 @@
 import { h, safeHref } from '../core/dom.js';
 import { icon } from '../core/icons.js';
+import { uid } from '../core/util.js';
 
 /** @typedef {'menuitem'|'menuitemcheckbox'|'menuitemradio'} MenuItemRole */
 /**
@@ -31,7 +32,27 @@ import { icon } from '../core/icons.js';
  * @property {string} label Visible heading.
  */
 /** @typedef {{type: 'separator'}} MenuSeparator */
-/** @typedef {MenuItem|MenuHeading|MenuSeparator|'-'} MenuEntry */
+/**
+ * One option of a menu choice.
+ * @typedef {Object} MenuChoiceOption
+ * @property {unknown} value Value the choice takes.
+ * @property {string} label Accessible name and tooltip; the option shows its glyph or icon.
+ * @property {string} [icon] Kernel icon name.
+ * @property {Node|(() => Node)} [glyph] A pictogram drawn instead of an icon.
+ * @property {boolean} [disabled=false] Whether the option is unavailable.
+ */
+/**
+ * A setting chosen in place: a labelled row of two to a few options, one checked — a theme, a
+ * layout. Choosing an option keeps the menu open, so its effect shows.
+ * @typedef {Object} MenuChoice
+ * @property {'choice'} type Entry kind.
+ * @property {string} label Visible row label.
+ * @property {unknown} [value] Value of the checked option.
+ * @property {MenuChoiceOption[]} options The options, in order.
+ * @property {(value: unknown, entry: MenuChoice, controller: MenuController) => void} [onselect]
+ *   Called with the chosen option's value.
+ */
+/** @typedef {MenuItem|MenuHeading|MenuSeparator|MenuChoice|'-'} MenuEntry */
 
 export const MENU_ITEM_SELECTOR = [
   '[role="menuitem"]',
@@ -46,7 +67,7 @@ export const MENU_ITEM_SELECTOR = [
  */
 export function isMenuItem(entry) {
   return Boolean(entry && entry !== '-' && typeof entry === 'object'
-    && !['heading', 'separator'].includes(String(/** @type {{type?: unknown}} */ (entry).type ?? '')));
+    && !['heading', 'separator', 'choice'].includes(String(/** @type {{type?: unknown}} */ (entry).type ?? '')));
 }
 
 /**
@@ -64,9 +85,11 @@ export function menuItemRole(item) {
  * Builds one menu's entries with shared structure and link safety.
  * @param {MenuEntry[]} entries Entry definitions.
  * @param {string} block CSS block name, without the `zx-` prefix.
+ * @param {{choices?: boolean}} [options={}] Whether the menu handles `choice` entries; a menu that
+ *   does not leaves them out rather than drawing a row that does nothing.
  * @returns {HTMLElement[]}
  */
-export function renderMenuEntries(entries, block) {
+export function renderMenuEntries(entries, block, { choices = false } = {}) {
   const nodes = [];
   entries.forEach((entry, index) => {
     if (entry === '-' || (entry && typeof entry === 'object' && entry.type === 'separator')) {
@@ -80,6 +103,10 @@ export function renderMenuEntries(entries, block) {
       }, String(entry.label ?? '')));
       return;
     }
+    if (entry && typeof entry === 'object' && entry.type === 'choice') {
+      if (choices) nodes.push(renderChoice(/** @type {MenuChoice} */ (entry), index, block));
+      return;
+    }
     if (!isMenuItem(entry)) return;
 
     const role = menuItemRole(entry);
@@ -140,3 +167,34 @@ export function renderMenuEntries(entries, block) {
   });
   return nodes;
 }
+
+/**
+ * A choice row: its label, then a segmented group of `menuitemradio` options. The group is named
+ * by the label, so a screen reader hears "Theme, Dark, radio, checked, 2 of 3".
+ * @param {MenuChoice} entry Choice definition.
+ * @param {number} index Entry index.
+ * @param {string} block CSS block name, without the `zx-` prefix.
+ * @returns {HTMLElement}
+ */
+function renderChoice(entry, index, block) {
+  const labelId = uid(`zx-${block}-choice`);
+  const options = Array.isArray(entry.options) ? entry.options : [];
+  return h('div', { class: `zx-${block}__choice`, role: 'group', ariaLabelledby: labelId },
+    h('span', { class: `zx-${block}__choice-label`, id: labelId }, String(entry.label ?? '')),
+    h('span', { class: `zx-${block}__choice-options` }, options.map((option, position) => {
+      const glyph = typeof option.glyph === 'function' ? option.glyph() : option.glyph;
+      return h('button', {
+        class: `zx-${block}__choice-option`,
+        type: 'button',
+        role: 'menuitemradio',
+        tabindex: '-1',
+        title: String(option.label ?? ''),
+        ariaLabel: String(option.label ?? ''),
+        ariaChecked: String(Object.is(option.value, entry.value)),
+        ariaDisabled: option.disabled ? 'true' : null,
+        'data-menu-item': String(index),
+        'data-menu-option': String(position)
+      }, glyph && typeof glyph === 'object' && 'nodeType' in glyph ? glyph
+        : option.icon ? icon(option.icon) : String(option.label ?? ''));
+    })));
+}

package/src/zeyos/form.js

@@ -1,5 +1,5 @@
 import { Form, Message, Select } from '../index.js';
-import { overlayHost } from '../core/overlay-host.js';
+import { overlayScope } from '../core/overlay-host.js';
 import { connect, errorMessage } from './connect.js';
 import {
   calendarDayToUnixSeconds, dateToUnixSeconds, unixSecondsToCalendarDay, unixSecondsToDate
@@ -163,8 +163,10 @@ export function zeyosForm(client, resource, opts = {}) {
     if (destroyed) return Promise.reject(new Error('Cannot save a destroyed ZeyOS form'));
     if (savePending) return savePending;
     if (!form.submit()) return Promise.resolve(null);
-    // Resolved now, while the form is in place: `onSaved` may close the dialog that holds it.
-    const host = notify ? overlayHost(toastScope()) : null;
+    // Resolved now, while the form is in place, and to the theme scope rather than the open
+    // dialog the overlay host would be: `onSaved` may close and destroy that dialog, and a toast
+    // parked inside it would fall back to an unstyled <body>.
+    const host = notify ? overlayScope(toastScope()) : null;
 
     savePending = (async () => {
       let payload;

package/src/zeyos/index.js

@@ -20,6 +20,9 @@ export {
   ZEYOS_LAUNCHER_APPLICATIONS, buildZeyosLauncherConfig, zeyosLauncher,
   normalizeZeyosLauncherApplications, normalizeZeyosLauncherRecords, zeyosActiveIdentifier
 } from './launcher.js';
+export {
+  zeyosModuleItems, buildZeyosModuleBarConfig, buildZeyosAppSidebarConfig, zeyosModuleBar
+} from './module-bar.js';
 export {
   zeyosSelect, buildZeyosSelectConfig, zeyosEntitySelect, buildZeyosEntitySelectConfig
 } from './select.js';

package/src/zeyos/launcher.js

@@ -224,8 +224,13 @@ export function zeyosActiveIdentifier(state = {}) {
   return String(state.module ?? '');
 }
 
-/** @param {unknown} raw @param {string|null} fallbackId @param {unknown} fallbackLabel @returns {Record<string, any>|null} */
-function normalizeApplication(raw, fallbackId, fallbackLabel) {
+/**
+ * Normalizes one application of the ZeyOS shell catalogue: a `[module, label]` pair, a
+ * `[ID, name, module, color]` fork, a weblet row, or an object. Shared with the module bar.
+ * @param {unknown} raw @param {string|null} fallbackId @param {unknown} fallbackLabel
+ * @returns {Record<string, any>|null}
+ */
+export function normalizeApplication(raw, fallbackId, fallbackLabel) {
   if (Array.isArray(raw)) {
     if (raw.length < 2) return null;
     if (raw.length === 2) {
@@ -305,7 +310,7 @@ function normalizeRecord(raw, group, query) {
 }
 
 /** @param {unknown} raw @param {unknown} resolver @returns {Record<string, any>} */
-function mergeDestination(raw, resolver) {
+export function mergeDestination(raw, resolver) {
   const direct = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
   const resolved = typeof resolver === 'function' ? resolver(raw) : null;
   const destination = resolved && typeof resolved === 'object' ? resolved : {};

package/src/zeyos/module-bar.js

@@ -0,0 +1,181 @@
+import { ModuleBar } from '../components/module-bar/module-bar.js';
+import { normalizeAppItems } from '../internal/app-rail.js';
+import { moduleIcon } from './icons.js';
+import { mergeDestination, normalizeApplication } from './launcher.js';
+import { moduleInfo } from './modules.js';
+
+/** @typedef {import('../components/module-bar/module-bar.js').ModuleItem} ModuleItem */
+/** @typedef {import('../components/module-bar/module-bar.js').ModuleBarOptions} ModuleBarOptions */
+/** @typedef {import('../components/app-sidebar/app-sidebar.js').AppSidebarOptions} AppSidebarOptions */
+/**
+ * One entry of a module's menu, as the ZeyOS shell describes it: an object, or an
+ * `[id, label, href]` array.
+ * @typedef {Object} ZeyosMenuEntry
+ * @property {string|number} [id] Entry identifier; a section needs none.
+ * @property {string} label Entry label.
+ * @property {string} [href] Destination.
+ * @property {string} [target] Link browsing context.
+ * @property {() => void} [invoke] Application-owned action.
+ * @property {string|number} [badge] Count.
+ * @property {string|Node} [icon] Icon name or node.
+ * @property {boolean} [section] A heading over `children` rather than a destination.
+ * @property {Array<ZeyosMenuEntry|Array<any>>} [children] Nested entries.
+ */
+/**
+ * The ZeyOS shell state a module bar is built from. The application fields are the launcher's
+ * (`buildZeyosLauncherConfig()`), so one state object can feed both.
+ * @typedef {Object} ZeyosModuleBarState
+ * @property {Record<string, string>|Array<string|Record<string, any>>} [modules={}] Permitted module catalogue.
+ * @property {Array<Array<any>|Record<string, any>>} [menuApps=[]] Forks, weblets, and authoritative menu entries.
+ * @property {string[]} [pinned] Application identifiers on the bar, in order; the rest are under "All modules".
+ * @property {string|null} [activeIdentifier=null] Current module, `fork#…`, or `weblet#…` identifier.
+ * @property {string|number|null} [active=null] Current menu entry, when it is more precise than the module.
+ * @property {(module: string) => boolean} [canUseModule] Permission predicate.
+ * @property {(app: unknown) => Record<string, any>|null} [resolveApplication] Maps an application to href/invoke/value metadata.
+ * @property {Record<string, Array<ZeyosMenuEntry|Array<any>>>} [menus={}] Each application's menu, keyed by identifier.
+ * @property {Record<string, string|number>} [badges={}] Badges keyed by application identifier or menu entry id.
+ * @property {Record<string, string>} [groups={}] "All modules" group per application identifier.
+ * @property {{forks?: string, weblets?: string}} [labels] Group labels for forks and weblets.
+ * @property {(app: unknown, normalized: Record<string, any>) => Node|null} [renderApplicationIcon] Host icon renderer.
+ */
+/**
+ * @typedef {Object} ZeyosModuleBarOptions
+ * @property {boolean} [standardIcons=false] Use stock Font Awesome glyphs instead of the ZeyOS kit.
+ * @property {'solid'|'tint'|'plain'} [appearance='solid'] Tile treatment; ZeyOS draws its modules solid.
+ */
+
+/**
+ * Maps ZeyOS shell state to module bar items: every permitted module, fork, and weblet with its
+ * kit icon, its identity colour (the payload's, else the registry's), its menu, and its badge.
+ * A module with a menu is a panel module; one without is a destination.
+ * @param {ZeyosModuleBarState} [state={}] Application-owned shell state.
+ * @param {ZeyosModuleBarOptions} [options={}] Mapping options.
+ * @returns {ModuleItem[]}
+ */
+export function zeyosModuleItems(state = {}, options = {}) {
+  const pinned = Array.isArray(state.pinned) ? state.pinned.map(String) : null;
+  const menus = state.menus && typeof state.menus === 'object' ? state.menus : {};
+  const badges = state.badges && typeof state.badges === 'object' ? state.badges : {};
+  const groups = state.groups && typeof state.groups === 'object' ? state.groups : {};
+  const labels = { forks: 'Forks', weblets: 'Weblets', ...(state.labels ?? {}) };
+  const seen = new Set();
+  /** @type {Record<string, any>[]} */
+  const items = [];
+  const add = (raw, fallbackId = null, fallbackLabel = null) => {
+    const app = normalizeApplication(raw, fallbackId, fallbackLabel);
+    if (!app || seen.has(app.identifier)) return;
+    if (app.type === 'module' && typeof state.canUseModule === 'function' && !state.canUseModule(app.module)) return;
+    seen.add(app.identifier);
+    const children = menuEntries(menus[app.identifier], badges);
+    const destination = children.length ? {} : mergeDestination(app.raw, state.resolveApplication);
+    const pin = pinned ? pinned.indexOf(app.identifier) : -1;
+    const group = groups[app.identifier]
+      ?? (app.type === 'fork' ? labels.forks : app.type === 'weblet' ? labels.weblets : undefined);
+    items.push({
+      id: app.identifier,
+      label: app.label,
+      // A factory, so a host renderer or the kit glyph is built per tile rather than shared.
+      icon: () => (typeof state.renderApplicationIcon === 'function' ? state.renderApplicationIcon(app.raw, app) : null)
+        ?? moduleIcon(app.module, { size: '1em', standard: Boolean(options.standardIcons) }),
+      color: app.color ?? moduleInfo(app.module).color,
+      module: app.module,
+      ...(group ? { group } : {}),
+      ...(badges[app.identifier] != null ? { badge: badges[app.identifier] } : {}),
+      ...(pinned ? { pinned: pin >= 0 ? pin : false } : {}),
+      ...(children.length ? { children } : destination)
+    });
+  };
+  for (const raw of Array.isArray(state.menuApps) ? state.menuApps : []) add(raw);
+  if (Array.isArray(state.modules)) {
+    for (const module of state.modules) {
+      if (typeof module === 'string') add([module, moduleInfo(module).label]);
+      else add(module, module?.id ?? module?.module, module?.label);
+    }
+  } else {
+    for (const [module, label] of Object.entries(state.modules ?? {})) add([module, label]);
+  }
+  return normalizeAppItems(items);
+}
+
+/**
+ * Builds plain ModuleBar options from ZeyOS shell state.
+ * @param {ZeyosModuleBarState} [state={}] Application-owned shell state.
+ * @param {ZeyosModuleBarOptions & ModuleBarOptions} [options={}] Mapping and ModuleBar options.
+ * @returns {ModuleBarOptions}
+ */
+export function buildZeyosModuleBarConfig(state = {}, options = {}) {
+  const { standardIcons = false, appearance = 'solid', ...barOptions } = options;
+  return {
+    ...barOptions,
+    items: zeyosModuleItems(state, { standardIcons }),
+    active: state.active ?? state.activeIdentifier ?? null,
+    appearance
+  };
+}
+
+/**
+ * Builds AppSidebar options for the modules layout from ZeyOS shell state: the module strip beside
+ * a panel with the current module's menu.
+ * @param {ZeyosModuleBarState} [state={}] Application-owned shell state.
+ * @param {ZeyosModuleBarOptions & AppSidebarOptions} [options={}] Mapping and AppSidebar options.
+ * @returns {AppSidebarOptions}
+ */
+export function buildZeyosAppSidebarConfig(state = {}, options = {}) {
+  const { standardIcons = false, appearance = 'solid', moduleBar = {}, ...sidebarOptions } = options;
+  return {
+    label: 'ZeyOS',
+    ...sidebarOptions,
+    layout: 'modules',
+    items: zeyosModuleItems(state, { standardIcons }),
+    active: state.active ?? state.activeIdentifier ?? null,
+    moduleBar: { appearance, ...moduleBar }
+  };
+}
+
+/**
+ * Creates a ModuleBar from ZeyOS shell state.
+ * @param {Element|string|null} target Bar target, or null to create one.
+ * @param {ZeyosModuleBarState} [state={}] Application-owned shell state.
+ * @param {ZeyosModuleBarOptions & ModuleBarOptions} [options={}] Mapping and ModuleBar options.
+ * @returns {ModuleBar}
+ */
+export function zeyosModuleBar(target, state = {}, options = {}) {
+  return new ModuleBar(target, buildZeyosModuleBarConfig(state, options));
+}
+
+/**
+ * Normalizes a ZeyOS menu: objects and `[id, label, href]` arrays, sections, nested entries, and
+ * badges looked up by entry id. Entries without a label, and leaves without an id, are dropped.
+ * @param {unknown} entries Menu entries.
+ * @param {Record<string, string|number>} badges Badges by id.
+ * @returns {Record<string, any>[]}
+ */
+function menuEntries(entries, badges) {
+  if (!Array.isArray(entries)) return [];
+  return entries.flatMap((entry) => {
+    if (Array.isArray(entry)) {
+      const [id, label, href] = entry;
+      if (id == null || label == null) return [];
+      return [{
+        id, label: String(label),
+        ...(href != null ? { href: String(href) } : {}),
+        ...(badges[String(id)] != null ? { badge: badges[String(id)] } : {})
+      }];
+    }
+    if (!entry || typeof entry !== 'object' || entry.label == null) return [];
+    const children = menuEntries(entry.children, badges);
+    if (entry.section === true) {
+      return children.length ? [{ ...(entry.id != null ? { id: entry.id } : {}), section: true, label: String(entry.label), children }] : [];
+    }
+    if (entry.id == null) return [];
+    const picked = Object.fromEntries(['id', 'href', 'target', 'invoke', 'icon', 'value', 'disabled']
+      .filter((key) => entry[key] !== undefined).map((key) => [key, entry[key]]));
+    const badge = badges[String(entry.id)] ?? entry.badge;
+    return [{
+      ...picked,
+      label: String(entry.label),
+      ...(badge != null ? { badge } : {}),
+      ...(children.length ? { children } : {})
+    }];
+  });
+}