@zeyos/zx 4.4.0 → 5.2.0

package/dist/types/core/overlay-stack.d.ts

@@ -0,0 +1,260 @@
+export type OverlayKind = 'modal' | 'non-modal' | 'popup' | 'tooltip' | 'toast';
+export type OverlayEntryOptions = {
+    /**
+     * Layer kind.
+     */
+    kind: OverlayKind;
+    /**
+     * The overlay's own root: the panel, dialog, or region.
+     */
+    root: Element;
+    /**
+     * Component that owns the entry; informational.
+     */
+    owner?: unknown;
+    /**
+     * Element(s) the overlay was
+     * opened from or is anchored to. The topmost entry whose root contains one becomes the parent.
+     */
+    anchor?: Element | null | Array<Element | null | undefined>;
+    /**
+     * Further elements that count as part of the
+     * overlay for outside presses and focus — a dropdown's trigger, which toggles it on its own.
+     */
+    inside?: Array<Element | null | undefined>;
+    /**
+     * Handles an
+     * Escape routed to this entry. Return `false` to decline, which passes it to the next layer down.
+     * The dispatcher calls `preventDefault()` on an Escape an entry handled.
+     */
+    onEscape?: (event: KeyboardEvent, handle: OverlayHandle) => boolean | void;
+    /**
+     * Called for a press
+     * outside the entry's chain, while nothing above it contained the press.
+     */
+    onOutsidePointer?: (event: Event, handle: OverlayHandle) => void;
+    /**
+     * Called when focus
+     * moves to an element outside the entry's chain.
+     */
+    onFocusOutside?: (event: FocusEvent, handle: OverlayHandle) => void;
+    /**
+     * Called when the parent entry closes.
+     * An entry without it outlives its parent and is re-parented to the grandparent.
+     */
+    onParentClose?: (handle: OverlayHandle) => void;
+};
+export type OverlayEntry = {
+    /**
+     * Z-order; higher is on top. Unique and increasing, never reused.
+     */
+    order: number;
+    /**
+     * Layer kind.
+     */
+    kind: OverlayKind;
+    /**
+     * Overlay root.
+     */
+    root: Element;
+    /**
+     * Owning component.
+     */
+    owner: unknown;
+    /**
+     * Anchor elements.
+     */
+    anchors: Element[];
+    /**
+     * Extra elements that count as inside.
+     */
+    inside: Element[];
+    /**
+     * Overlay the anchor sat in when the entry opened.
+     */
+    parent: OverlayEntry | null;
+    /**
+     * Escape handler.
+     */
+    onEscape?: OverlayEntryOptions['onEscape'];
+    /**
+     * Outside-press handler.
+     */
+    onOutsidePointer?: OverlayEntryOptions['onOutsidePointer'];
+    /**
+     * Focus-outside handler.
+     */
+    onFocusOutside?: OverlayEntryOptions['onFocusOutside'];
+    /**
+     * Parent-close handler.
+     */
+    onParentClose?: OverlayEntryOptions['onParentClose'];
+};
+export type OverlayHandle = {
+    /**
+     * The registered entry.
+     */
+    entry: OverlayEntry;
+    /**
+     * The entry's z-order, for `data-zx-overlay-order`.
+     */
+    order: number;
+    /**
+     * Whether the entry is still registered.
+     */
+    isOpen: () => boolean;
+    /**
+     * Whether no other entry (toasts aside) sits above it.
+     */
+    isTopmost: () => boolean;
+    /**
+     * Whether a node is inside the entry's
+     * chain: its root, its `inside` elements, or any overlay opened from it.
+     */
+    contains: (node: Node | null | undefined) => boolean;
+    /**
+     * Unregisters the entry and closes the children that follow it.
+     * Safe to call repeatedly.
+     */
+    release: () => void;
+};
+/**
+ * Whether `node` is `root` or inside it, crossing shadow roots.
+ * @param {Node|null|undefined} root Container.
+ * @param {Node|null|undefined} node Candidate.
+ * @returns {boolean}
+ */
+export declare function containsNode(root: Node | null | undefined, node: Node | null | undefined): boolean;
+/**
+ * The entry an overlay opened from `anchors` belongs under: the topmost one whose root contains an
+ * anchor. Tooltips and toasts are never parents.
+ * @param {readonly OverlayEntry[]} entries Registered entries, bottom to top.
+ * @param {readonly Element[]} anchors Anchor elements of the overlay being opened.
+ * @returns {OverlayEntry|null}
+ */
+export declare function findParent(entries: readonly OverlayEntry[], anchors: readonly Element[]): OverlayEntry | null;
+/**
+ * Whether a node is inside an entry's chain: its root, its `inside` elements, or — recursively —
+ * any entry whose parent it is.
+ * @param {readonly OverlayEntry[]} entries Registered entries.
+ * @param {OverlayEntry} entry Entry to test.
+ * @param {Node|null|undefined} node Candidate.
+ * @returns {boolean}
+ */
+export declare function insideChain(entries: readonly OverlayEntry[], entry: OverlayEntry, node: Node | null | undefined): boolean;
+/**
+ * The topmost entry, toasts aside, optionally narrowed by a predicate.
+ * @param {readonly OverlayEntry[]} entries Registered entries, bottom to top.
+ * @param {(entry: OverlayEntry) => boolean} [filter] Extra condition.
+ * @returns {OverlayEntry|null}
+ */
+export declare function topmostEntry(entries: readonly OverlayEntry[], filter?: (entry: OverlayEntry) => boolean): OverlayEntry | null;
+/**
+ * The entries an Escape may be offered to, in the order they are asked: from the top down, those
+ * with an Escape handler, stopping at the first modal (whose Escape is the browser's).
+ *
+ * `within` is the open modal dialog the key was pressed in, when there is one. Everything outside
+ * it is inert, so an entry whose root lies outside it is never offered the key — which keeps a
+ * modal the stack does not know about (a `<dialog>` an application opened with `showModal()`)
+ * from losing its Escape to a popup left open behind it.
+ * @param {readonly OverlayEntry[]} entries Registered entries, bottom to top.
+ * @param {Node|null} [within=null] Open modal dialog containing the key's target.
+ * @returns {OverlayEntry[]}
+ */
+export declare function escapeCandidates(entries: readonly OverlayEntry[], within?: Node | null): OverlayEntry[];
+/**
+ * The entries a press on `node` dismisses, topmost first.
+ *
+ * A press inside a toast dismisses nothing. Tooltips go on any press outside them. For the rest,
+ * the walk runs from the top down and stops at the first entry whose chain contains the press — it
+ * landed on that layer, and the layers beneath are covered by it or own it — or at a modal, below
+ * which everything is inert. Every entry passed on the way that handles outside presses is
+ * dismissed. As for Escape, a press inside an open modal dialog dismisses nothing outside it.
+ * @param {readonly OverlayEntry[]} entries Registered entries, bottom to top.
+ * @param {Node|null|undefined} node Press target.
+ * @param {Node|null} [within=null] Open modal dialog containing the press.
+ * @returns {OverlayEntry[]}
+ */
+export declare function outsideTargets(entries: readonly OverlayEntry[], node: Node | null | undefined, within?: Node | null): OverlayEntry[];
+/**
+ * A registry of open overlays. The library uses the one shared instance, `overlayStack`; separate
+ * instances exist for tests and for documents other than the global one.
+ */
+export declare class OverlayStack {
+    #private;
+    /**
+     * @param {{target?: EventTarget|null}} [options={}] Where to listen; the global document when
+     *   omitted. Pass `null` to install no listeners and drive the dispatch methods directly.
+     */
+    constructor(options?: {
+        target?: EventTarget | null;
+    });
+    /**
+     * Registers an open overlay above every other.
+     * @param {OverlayEntryOptions} options Entry description.
+     * @returns {OverlayHandle}
+     */
+    push(options: OverlayEntryOptions): OverlayHandle;
+    /**
+     * The registered entries, bottom to top. A copy: changing it changes nothing.
+     * @returns {OverlayEntry[]}
+     */
+    entries(): OverlayEntry[];
+    /**
+     * The topmost entry, toasts aside.
+     * @param {(entry: OverlayEntry) => boolean} [filter] Extra condition.
+     * @returns {OverlayEntry|null}
+     */
+    topmost(filter?: (entry: OverlayEntry) => boolean): OverlayEntry | null;
+    /**
+     * Root of the topmost open modal dialog, or null when none is open. Asks the registry first and
+     * falls back to the document, so a `<dialog>` opened with `showModal()` outside the library still
+     * counts.
+     * @returns {Element|null}
+     */
+    topmostModal(): Element | null;
+    /**
+     * Whether a node is inside any registered overlay's root or `inside` elements.
+     * @param {Node|null|undefined} node Candidate.
+     * @returns {boolean}
+     */
+    containsNode(node: Node | null | undefined): boolean;
+    /**
+     * Subscribes to registry changes: called after every push and release.
+     * @param {(entries: readonly OverlayEntry[]) => void} listener Change listener.
+     * @returns {() => void} Unsubscribes.
+     */
+    subscribe(listener: (entries: readonly OverlayEntry[]) => void): () => void;
+    /**
+     * Routes an Escape keydown to the topmost layer that handles it. Ignores other keys and events
+     * already `defaultPrevented`. Installed on the document while overlays are open; public so a
+     * stack created without a target can be driven directly.
+     * @param {KeyboardEvent} event Keydown event.
+     * @returns {OverlayEntry|null} The entry that handled it.
+     */
+    handleKeydown(event: KeyboardEvent): OverlayEntry | null;
+    /**
+     * Dismisses the layers a press landed outside of. Installed on the document, capture phase, while
+     * overlays are open; public so a stack created without a target can be driven directly.
+     * @param {Event} event Pointerdown event.
+     * @returns {OverlayEntry[]} The entries asked to dismiss, topmost first.
+     */
+    handlePointerdown(event: Event): OverlayEntry[];
+    /**
+     * Tells the entries that watch focus that it moved outside them.
+     * @param {FocusEvent} event Focusin event.
+     * @returns {void}
+     */
+    handleFocusin(event: FocusEvent): void;
+}
+/**
+ * The document's overlay stack, shared by every overlay in the library.
+ * @type {OverlayStack}
+ */
+export declare const overlayStack: OverlayStack;
+/**
+ * Registers an open overlay on the shared stack. Shorthand for `overlayStack.push(options)`.
+ * @param {OverlayEntryOptions} options Entry description.
+ * @returns {OverlayHandle}
+ */
+export declare function pushOverlay(options: OverlayEntryOptions): OverlayHandle;

package/dist/types/index.d.ts

@@ -11,8 +11,9 @@ export { Component } from './core/component.js';
 export { h, htmlEscape, resolveElement, highlightMatch, __, compactElement, fragment, parseCompactTag, applyCompactProperties, appendContent, appendCompact, appendCompactChild, onCompactEvent, offCompactEvent, fireCompactEvent } from './core/dom.js';
 export { position } from './core/position.js';
 export { breakpoints, breakpointOf, matchBreakpoint, onBreakpoint } from './core/breakpoint.js';
+export { MOTION_ATTRIBUTE, prefersReducedMotion, watchMotion } from './core/motion.js';
 export { Http, zeyosService, parseResult } from './core/http.js';
-export { setTranslator, setLanguage, getLanguage, translate, printf } from './core/i18n.js';
+export { setTranslator, setLanguage, getLanguage, translate, printf, defaultMessages } from './core/i18n.js';
 export { focusTrap, rovingTabindex, typeahead } from './core/keyboard.js';
 export { formatDate, parseDate, clampDate, isSameDay, addDays, addMonths, getWeekStart } from './core/date.js';
 export { icon, icons, iconNames, registerIcons, configureIcons, getIconConfig, useFontAwesome, useBuiltinIcons, loadFontAwesome } from './core/icons.js';
@@ -22,8 +23,8 @@ export { formatNumber, formatCurrency, formatPercent, formatFileSize, formatRela
 export { storage } from './core/storage.js';
 export { toCsv, downloadBlob, copyToClipboard } from './core/export.js';
 export { defineElements } from './elements/define.js';
-export { button, buttonGroup } from './components/button/button.js';
-export { badge, badgeGroup } from './components/badge/badge.js';
+export { button, buttonGroup, setButtonBusy } from './components/button/button.js';
+export { BADGE_TONES, badge, badgeGroup } from './components/badge/badge.js';
 export { CheckButton } from './components/check-button/check-button.js';
 export { emptyState } from './components/empty-state/empty-state.js';
 export { spinner } from './components/loading/spinner.js';
@@ -53,15 +54,17 @@ export { Pagination, paginationRange } from './components/pagination/pagination.
 export { Search } from './components/search/search.js';
 export { AppIcon, appIcon } from './components/app-icon/app-icon.js';
 export { Launcher, rankLauncherItems } from './components/launcher/launcher.js';
-export { Avatar, avatarInitials } from './components/avatar/avatar.js';
+export { AVATAR_TONES, Avatar, avatarInitials, avatarTone } from './components/avatar/avatar.js';
 export { EntityRef, normalizeEntityRef, normalizeEntityRefLink, normalizeEntityRefMetadata, normalizeEntityRefActions } from './components/entity-ref/entity-ref.js';
 export { FileItem, normalizeFileItem } from './components/file-item/file-item.js';
 export { FileList, normalizeFileListItems } from './components/file-list/file-list.js';
 export { ActivityItem, resolveActivityActions, normalizeActivityAction, normalizeActivityTimestamp } from './components/activity-item/activity-item.js';
 export { ActivityList, groupActivityItems, normalizeActivityItems } from './components/activity-list/activity-list.js';
 export { AccountMenu } from './components/account-menu/account-menu.js';
+export { WorkspaceSwitcher } from './components/workspace-switcher/workspace-switcher.js';
 export { normalizeAppItems } from './internal/app-rail.js';
-export { AppSidebar } from './components/app-sidebar/app-sidebar.js';
+export { ModuleBar, partitionModules, resolveModuleColor } from './components/module-bar/module-bar.js';
+export { AppSidebar, presentationGlyph } from './components/app-sidebar/app-sidebar.js';
 export { Message } from './components/message/message.js';
 export { Modal } from './components/modal/modal.js';
 export { Dialog } from './components/dialog/dialog.js';
@@ -72,6 +75,7 @@ export { Tooltip, tooltip, describe } from './components/tooltip/tooltip.js';
 export { MenuButton } from './components/menu-button/menu-button.js';
 export { ContextMenu } from './components/context-menu/context-menu.js';
 export { Select } from './components/select/select.js';
+export { statusIcon, priorityIcon } from './components/select/glyphs.js';
 export { Checklist } from './components/checklist/checklist.js';
 export { TagPicker } from './components/tag-picker/tag-picker.js';
 export { NumberField, parseNumber, snapNumber } from './components/number-field/number-field.js';
@@ -101,6 +105,7 @@ export { DataFilter } from './components/data-filter/data-filter.js';
 export { FilterPanel, isActiveValue, pruneValue, serializeFilterValue } from './components/filter-panel/filter-panel.js';
 export { SortControl } from './components/sort-control/sort-control.js';
 export { ListToolbar } from './components/list-toolbar/list-toolbar.js';
+export { ViewSettings } from './components/view-settings/view-settings.js';
 export { Filter } from './components/filter/filter.js';
 export { filterOperators, emptyFilterAst, filterCondition, filterGroup, parseFilterAst, cloneFilterAst, stringifyFilterAst, validateFilterAst } from './components/filter/filter-model.js';
 export { Field } from './components/field/field.js';

package/dist/types/internal/app-rail.d.ts

@@ -43,6 +43,17 @@ export type AppNavItem = {
      * Child destinations/actions.
      */
     children?: AppNavItem[];
+    /**
+     * 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`.
+     */
+    section?: boolean;
+    /**
+     * A section's trailing controls, such as an add button.
+     */
+    actions?: Node | {
+        toElement: () => Node | null;
+    };
 };
 export type AppRailPresenterOptions = {
     /**
@@ -129,6 +140,9 @@ export type RailFlyout = {
  * @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
@@ -170,6 +184,13 @@ export declare class AppRailPresenter extends Component<AppRailPresenterOptions>
     _pointerFocus: WeakSet<object>;
     _silenceFlyoutEvents: boolean;
     static cssName: string;
+    /**
+     * 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: string;
     /** @type {Readonly<AppRailPresenterOptions>} */
     static defaults: Readonly<AppRailPresenterOptions>;
     /**
@@ -204,6 +225,23 @@ export declare class AppRailPresenter extends Component<AppRailPresenterOptions>
     destroy(): void;
     /** @returns {void} */
     _rebuild(): void;
+    /** @returns {string} The BEM block of the rail's own parts. @protected */
+    protected _partBlock(): string;
+    /**
+     * 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
+     */
+    protected _renderControl(item: AppNavItem, hasFlyout: boolean): HTMLElement;
+    /** Whether an item with children presents them in a flyout. @param {AppNavItem} item @returns {boolean} @protected */
+    protected _flyoutsFor(item: AppNavItem): boolean;
+    /** Whether a top-level control gets a hover/focus tooltip naming it. @param {AppNavItem} item @returns {boolean} @protected */
+    protected _tooltipFor(item: AppNavItem): boolean;
+    /** Runs after every rebuild, before the active state is applied. @returns {void} @protected */
+    protected _afterRebuild(): void;
     /** @param {AppNavItem} item @param {HTMLElement} trigger @param {string} key @param {string|null} parentKey @returns {void} */
     _buildFlyout(item: AppNavItem, trigger: HTMLElement, key: string, parentKey: string | null): void;
     /** @param {AppNavItem} item @param {Event} event @returns {Event} */

package/dist/types/internal/menu-items.d.ts

@@ -80,7 +80,51 @@ export type MenuHeading = {
 export type MenuSeparator = {
     type: 'separator';
 };
-export type MenuEntry = MenuItem | MenuHeading | MenuSeparator | '-';
+export type MenuChoiceOption = {
+    /**
+     * Value the choice takes.
+     */
+    value: unknown;
+    /**
+     * Accessible name and tooltip; the option shows its glyph or icon.
+     */
+    label: string;
+    /**
+     * Kernel icon name.
+     */
+    icon?: string;
+    /**
+     * A pictogram drawn instead of an icon.
+     */
+    glyph?: Node | (() => Node);
+    /**
+     * Whether the option is unavailable.
+     */
+    disabled?: boolean;
+};
+export type MenuChoice = {
+    /**
+     * Entry kind.
+     */
+    type: 'choice';
+    /**
+     * Visible row label.
+     */
+    label: string;
+    /**
+     * Value of the checked option.
+     */
+    value?: unknown;
+    /**
+     * The options, in order.
+     */
+    options: MenuChoiceOption[];
+    /**
+     * Called with the chosen option's value.
+     */
+    onselect?: (value: unknown, entry: MenuChoice, controller: MenuController) => void;
+};
+export type MenuEntry = MenuItem | MenuHeading | MenuSeparator | MenuChoice | '-';
 /** @typedef {'menuitem'|'menuitemcheckbox'|'menuitemradio'} MenuItemRole */
 /**
  * @typedef {Object} MenuController
@@ -111,7 +155,27 @@ export type MenuEntry = MenuItem | MenuHeading | MenuSeparator | '-';
  * @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 declare const MENU_ITEM_SELECTOR: string;
 /**
  * Reports whether an entry is an interactive menu action.
@@ -129,6 +193,10 @@ export declare function menuItemRole(item: MenuItem): MenuItemRole;
  * 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 declare function renderMenuEntries(entries: MenuEntry[], block: string): HTMLElement[];
+export declare function renderMenuEntries(entries: MenuEntry[], block: string, { choices }?: {
+    choices?: boolean;
+}): HTMLElement[];

package/dist/types/zeyos/connect.d.ts

@@ -63,3 +63,9 @@ export type ZeyosFacade = {
  * @returns {ZeyosFacade} Bound facade.
  */
 export declare function connect(client: Record<string, any>, { onError, locale }?: ConnectOptions): ZeyosFacade;
+/**
+ * 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 declare function errorMessage(error: unknown): string;

package/dist/types/zeyos/form.d.ts

@@ -12,6 +12,17 @@ export type ZeyosFormOptions = {
      * Per-field label overrides.
      */
     labels?: Record<string, string>;
+    /**
+     * Per-field semantic format overrides, such as
+     * `{ duedate: 'date' }` for a Unix-second field that holds a calendar day.
+     */
+    formats?: Record<string, string>;
+    /**
+     * 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.
+     */
+    timeZone?: string;
     /**
      * Fieldset legend.
      */
@@ -32,6 +43,17 @@ export type ZeyosFormOptions = {
      * Success callback.
      */
     onSaved?: (record: Record<string, unknown>) => unknown | Promise<unknown>;
+    /**
+     * 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.
+     */
+    scope?: Element | string | null;
+    /**
+     * Whether the binding raises toasts. `false` keeps it silent:
+     * `save()`, `load()`, and `ready` still resolve or reject, and reporting is the caller's.
+     */
+    notify?: boolean;
 };
 export type ZeyosFormConfig = {
     /**
@@ -54,11 +76,13 @@ export type ZeyosFormConfig = {
      */
     formOptions: Record<string, any>;
     /**
-     * Maps Unix seconds to Date values.
+     * Maps Unix
+     * seconds to Date values: a date-only field to local midnight of its calendar day in `timeZone`.
      */
     mapFromRecord: (record: Record<string, unknown>) => Record<string, unknown>;
     /**
-     * Maps Date and enum values to API storage values.
+     * Maps Date and
+     * enum values to API storage values: a date-only field to midnight of its day in `timeZone`.
      */
     mapToRecord: (values: Record<string, unknown>) => Record<string, unknown>;
 };
@@ -76,7 +100,8 @@ export type ZeyosFormBinding = {
      */
     load: (id: unknown) => Promise<Record<string, unknown>>;
     /**
-     * Validates and creates or updates the record.
+     * Validates and creates or updates the
+     * record, then confirms with a toast in the form's scope unless `notify` is false.
      */
     save: () => Promise<Record<string, unknown> | null>;
     /**
@@ -93,11 +118,21 @@ export type ZeyosFormBinding = {
  * @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.
  */
 /**
  * @typedef {Object} ZeyosFormConfig
@@ -105,22 +140,26 @@ export type ZeyosFormBinding = {
  * @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`.
  */
 /**
  * @typedef {Object} ZeyosFormBinding
  * @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.
  */
 /**
  * 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.
@@ -130,8 +169,10 @@ export declare function buildZeyosFormConfig(client: Record<string, any>, resour
 /**
  * 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.

package/dist/types/zeyos/index.d.ts

@@ -3,11 +3,12 @@
  * @module zx/zeyos
  */
 export { fieldToZxField, fieldToZxColumn, resolveFields, registerFieldType } from './schema.js';
-export { buildListQuery, tableSortToQuery, dataFilterStateToFilters, dateToUnixSeconds, unixSecondsToDate } from './query.js';
+export { buildListQuery, tableSortToQuery, dataFilterStateToFilters, dateToUnixSeconds, unixSecondsToDate, calendarDayToUnixSeconds, unixSecondsToCalendarDay } from './query.js';
 export { connect } from './connect.js';
 export { zeyosModules, moduleAliases, moduleInfo, moduleColor, moduleIconName, moduleKeys, moduleGlyphColor, normalizeModuleName, registerModules } from './modules.js';
 export { ZEYOS_ICON_KIT, useZeyosIcons, moduleIcon, moduleChip, zeyosAppIcon } from './icons.js';
 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';
 export { zeyosForm } from './form.js';
 export { zeyosTable } from './table.js';

package/dist/types/zeyos/launcher.d.ts

@@ -145,3 +145,12 @@ export declare function zeyosActiveIdentifier(state?: {
     fork?: unknown;
     weblet?: unknown;
 }): string;
+/**
+ * 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 declare function normalizeApplication(raw: unknown, fallbackId: string | null, fallbackLabel: unknown): Record<string, any> | null;
+/** @param {unknown} raw @param {unknown} resolver @returns {Record<string, any>} */
+export declare function mergeDestination(raw: unknown, resolver: unknown): Record<string, any>;