@zeyos/zx 4.4.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,19 +346,34 @@ 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 carries the active marker to the edge facing the screen
-    // on a right-hand rail, exactly as the expanded tree does.
+    // occupies. Presentation only: it tells the panel's styles which side it opened from.
     actualPanel.dataset.side = this.el.dataset.side;
     actualPanel.setAttribute('role', 'region');
     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 });
     });
 
@@ -394,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';
@@ -417,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);
@@ -607,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.
@@ -614,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/connect.js

@@ -107,8 +107,12 @@ function isRecord(value) {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
 
-/** @param {unknown} error @returns {string} */
-function errorMessage(error) {
+/**
+ * The text a failed request is reported with: the error's own message, or a generic sentence.
+ * @param {unknown} error Rejection reason.
+ * @returns {string}
+ */
+export function errorMessage(error) {
   if (error instanceof Error && error.message) return error.message;
   if (error && typeof error === 'object' && typeof error.message === 'string') return error.message;
   return String(error ?? 'ZeyOS request failed');

package/src/zeyos/form.js

@@ -1,6 +1,9 @@
 import { Form, Message, Select } from '../index.js';
-import { connect } from './connect.js';
-import { dateToUnixSeconds, unixSecondsToDate } from './query.js';
+import { overlayScope } from '../core/overlay-host.js';
+import { connect, errorMessage } from './connect.js';
+import {
+  calendarDayToUnixSeconds, dateToUnixSeconds, unixSecondsToCalendarDay, unixSecondsToDate
+} from './query.js';
 import { fieldToZxField, resolveFields } from './schema.js';
 import { buildZeyosSelectConfig } from './select.js';
 
@@ -9,11 +12,21 @@ import { buildZeyosSelectConfig } from './select.js';
  * @property {string[]} [fields] Curated ordered field allow-list.
  * @property {string[]} [exclude] Field ids to omit.
  * @property {Record<string, string>} [labels] Per-field label overrides.
+ * @property {Record<string, string>} [formats] Per-field semantic format overrides, such as
+ * `{ duedate: 'date' }` for a Unix-second field that holds a calendar day.
+ * @property {string} [timeZone] IANA time zone of the ZeyOS instance. A date-only field's stored
+ * midnight is read as the calendar day it names in this zone, and a picked day is saved as midnight
+ * in it; defaults to the runtime's own zone.
  * @property {string} [title=''] Fieldset legend.
  * @property {1|2|3} [columns=2] Fieldset column count.
  * @property {Record<string, unknown>} [value] Initial record using ZeyOS storage values.
  * @property {unknown} [id] Initial record id to load.
  * @property {(record: Record<string, unknown>) => unknown|Promise<unknown>} [onSaved] Success callback.
+ * @property {Element|string|null} [scope=null] Element or selector whose theme scope shows the
+ * binding's toasts — the save confirmation and the report of a failed request. Null uses the form's
+ * own element, so a form inside a scoped shell or dialog toasts inside that scope.
+ * @property {boolean} [notify=true] Whether the binding raises toasts. `false` keeps it silent:
+ * `save()`, `load()`, and `ready` still resolve or reject, and reporting is the caller's.
  */
 
 /**
@@ -22,8 +35,10 @@ import { buildZeyosSelectConfig } from './select.js';
  * @property {Record<string, Record<string, any>>} fields Field descriptors keyed by id.
  * @property {Array<{id: string, resource: string}>} entityFields Referenced-resource fields.
  * @property {Record<string, any>} formOptions Plain Zx Form options.
- * @property {(record: Record<string, unknown>) => Record<string, unknown>} mapFromRecord Maps Unix seconds to Date values.
- * @property {(values: Record<string, unknown>) => Record<string, unknown>} mapToRecord Maps Date and enum values to API storage values.
+ * @property {(record: Record<string, unknown>) => Record<string, unknown>} mapFromRecord Maps Unix
+ * seconds to Date values: a date-only field to local midnight of its calendar day in `timeZone`.
+ * @property {(values: Record<string, unknown>) => Record<string, unknown>} mapToRecord Maps Date and
+ * enum values to API storage values: a date-only field to midnight of its day in `timeZone`.
  */
 
 /**
@@ -31,7 +46,8 @@ import { buildZeyosSelectConfig } from './select.js';
  * @property {Form} form Generated Zx form.
  * @property {Promise<Record<string, unknown>|null>} ready Initial value/load readiness.
  * @property {(id: unknown) => Promise<Record<string, unknown>>} load Loads and maps one record.
- * @property {() => Promise<Record<string, unknown>|null>} save Validates and creates or updates the record.
+ * @property {() => Promise<Record<string, unknown>|null>} save Validates and creates or updates the
+ * record, then confirms with a toast in the form's scope unless `notify` is false.
  * @property {() => Form} getForm Returns the generated Zx Form.
  * @property {() => void} destroy Destroys the form and all owned fields/selects.
  */
@@ -39,7 +55,8 @@ import { buildZeyosSelectConfig } from './select.js';
 /**
  * Builds the DOM-free form configuration consumed by {@link zeyosForm}. Entity descriptors retain
  * the `zxselect` type and receive the same async options used by {@link zeyosSelect}; enum options
- * come from normalized schema metadata, and the returned mappers handle Unix-second dates.
+ * come from normalized schema metadata with readable labels, and the returned mappers handle
+ * Unix-second dates — date-only fields as calendar days in `opts.timeZone`.
  * @param {Record<string, any>} client Injected ZeyOS client instance.
  * @param {string} resource Resource name such as `transactions`.
  * @param {ZeyosFormOptions} [opts={}] Schema curation and layout options.
@@ -49,9 +66,14 @@ export function buildZeyosFormConfig(client, resource, opts = {}) {
   const fieldMeta = resolveFields(client, resource, opts);
   const fields = {};
   const entityFields = [];
+  /** @type {Map<string, 'date'|'datetime'>} */
+  const dateKinds = new Map();
 
   for (const meta of fieldMeta) {
     const descriptor = fieldToZxField(meta);
+    if (descriptor.type === 'date' || descriptor.type === 'datetime') {
+      dateKinds.set(String(meta.id), descriptor.type);
+    }
     const referencedResource = descriptor.type === 'zxselect' && typeof descriptor.props?.entity === 'string'
       ? descriptor.props.entity
       : null;
@@ -78,16 +100,18 @@ export function buildZeyosFormConfig(client, resource, opts = {}) {
         fields
       }]
     },
-    mapFromRecord: (record) => mapFromRecord(record, fieldMeta),
-    mapToRecord: (values) => mapToRecord(values, fieldMeta)
+    mapFromRecord: (record) => mapFromRecord(record, fieldMeta, dateKinds),
+    mapToRecord: (values) => mapToRecord(values, fieldMeta, dateKinds)
   };
 }
 
 /**
  * Generates a schema-driven Zx Form and a small async binding object. `load(id)` hydrates entity
  * labels and converts Unix seconds to Date objects. `save()` validates, maps values back to API
- * storage types, calls create/update through the WP14 connection facade, shows a success toast,
- * and invokes `onSaved(record)`. Await `ready` when `opts.id` or `opts.value` is supplied.
+ * storage types, calls create/update through the WP14 connection facade, invokes
+ * `onSaved(record)`, and shows a success toast. Its toasts — that confirmation and the report of a
+ * failed request — appear in the theme scope of `opts.scope` or of the form itself, and
+ * `notify: false` silences them. Await `ready` when `opts.id` or `opts.value` is supplied.
  * @param {Record<string, any>} client Injected ZeyOS client instance.
  * @param {string} resource Resource name such as `transactions`.
  * @param {ZeyosFormOptions} [opts={}] Schema, initial value, and save options.
@@ -97,8 +121,14 @@ export function zeyosForm(client, resource, opts = {}) {
   if (opts.onSaved != null && typeof opts.onSaved !== 'function') {
     throw new TypeError('zeyosForm onSaved must be a function');
   }
+  const notify = opts.notify !== false;
   const config = buildZeyosFormConfig(client, resource, opts);
-  const facade = connect(client);
+  // The caller's scope, or the form's own element, decides where a toast appears — never whatever
+  // element happens to hold focus when a request settles.
+  const toastScope = () => opts.scope ?? form.el;
+  const facade = connect(client, {
+    onError: (error) => notify ? Message.error(errorMessage(error), { scope: toastScope() }) : undefined
+  });
   const form = new Form(null, config.formOptions);
   let currentId = opts.value?.ID ?? opts.id ?? null;
   let destroyed = false;
@@ -133,6 +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, 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;
@@ -157,7 +191,7 @@ export function zeyosForm(client, resource, opts = {}) {
           throw error;
         }
       }
-      Message.success(`${recordLabel(record, resource)} saved successfully.`);
+      if (host) Message.success(`${recordLabel(record, resource)} saved successfully.`, { scope: host });
       return record;
     })().finally(() => {
       savePending = null;
@@ -183,27 +217,41 @@ export function zeyosForm(client, resource, opts = {}) {
   };
 }
 
-/** @param {Record<string, unknown>} record @param {Record<string, any>[]} meta @returns {Record<string, unknown>} */
-function mapFromRecord(record, meta) {
+/**
+ * @param {Record<string, unknown>} record
+ * @param {Record<string, any>[]} meta
+ * @param {Map<string, 'date'|'datetime'>} dateKinds
+ * @returns {Record<string, unknown>}
+ */
+function mapFromRecord(record, meta, dateKinds) {
   const values = {};
   for (const field of meta) {
     const id = String(field.id);
     const value = record[id];
-    values[id] = isDateField(field) && value != null && value !== ''
-      ? unixSecondsToDate(/** @type {number|string} */ (value))
-      : value;
+    const kind = dateKinds.get(id);
+    if (!kind || value == null || value === '') values[id] = value;
+    else if (kind === 'date') values[id] = unixSecondsToCalendarDay(/** @type {number|string} */ (value), field.timeZone);
+    else values[id] = unixSecondsToDate(/** @type {number|string} */ (value));
   }
   return values;
 }
 
-/** @param {Record<string, unknown>} values @param {Record<string, any>[]} meta @returns {Record<string, unknown>} */
-function mapToRecord(values, meta) {
+/**
+ * @param {Record<string, unknown>} values
+ * @param {Record<string, any>[]} meta
+ * @param {Map<string, 'date'|'datetime'>} dateKinds
+ * @returns {Record<string, unknown>}
+ */
+function mapToRecord(values, meta, dateKinds) {
   const record = {};
   for (const field of meta) {
     const id = String(field.id);
     let value = values[id];
-    if (isDateField(field)) {
-      value = value == null || value === '' ? null : dateToUnixSeconds(/** @type {Date} */ (value));
+    const kind = dateKinds.get(id);
+    if (kind) {
+      if (value == null || value === '') value = null;
+      else if (kind === 'date') value = calendarDayToUnixSeconds(/** @type {Date} */ (value), field.timeZone);
+      else value = dateToUnixSeconds(/** @type {Date} */ (value));
     } else if (hasEnum(field) && isNumericType(field.type) && value !== '' && value != null) {
       const numeric = Number(value);
       if (Number.isFinite(numeric)) value = numeric;
@@ -213,12 +261,6 @@ function mapToRecord(values, meta) {
   return record;
 }
 
-/** @param {Record<string, any>} meta @returns {boolean} */
-function isDateField(meta) {
-  const descriptor = fieldToZxField(meta);
-  return descriptor.type === 'date' || descriptor.type === 'datetime';
-}
-
 /** @param {Record<string, any>} meta @returns {boolean} */
 function hasEnum(meta) {
   return meta.enums != null || meta.enum != null;

package/src/zeyos/index.js

@@ -8,7 +8,7 @@ export {
 } from './schema.js';
 export {
   buildListQuery, tableSortToQuery, dataFilterStateToFilters,
-  dateToUnixSeconds, unixSecondsToDate
+  dateToUnixSeconds, unixSecondsToDate, calendarDayToUnixSeconds, unixSecondsToCalendarDay
 } from './query.js';
 export { connect } from './connect.js';
 export {
@@ -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 : {};