@zeyos/zx 4.3.4 → 5.0.0

package/src/index.js

@@ -4,6 +4,7 @@
  */
 
 import { registerChecklistFieldAdapter } from './components/checklist/field-adapter.js';
+import { registerCodeEditorFieldAdapter } from './components/code-editor/field-adapter.js';
 import { registerDatePickerFieldAdapters } from './components/date-picker/field-adapter.js';
 import { registerDateRangeFieldAdapter } from './components/date-picker/range-field-adapter.js';
 import { registerDateboxFieldAdapters } from './components/datebox/field-adapter.js';
@@ -25,6 +26,7 @@ import { registerValueListFieldAdapter } from './components/value-list/field-ada
 export function registerFieldAdapters() {
   registerSelectFieldAdapter();
   registerChecklistFieldAdapter();
+  registerCodeEditorFieldAdapter();
   registerDateboxFieldAdapters();
   registerDatePickerFieldAdapters();
   registerDateRangeFieldAdapter();
@@ -50,6 +52,7 @@ export {
 } 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 { focusTrap, rovingTabindex, typeahead } from './core/keyboard.js';
@@ -73,8 +76,8 @@ export {
 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';
@@ -85,10 +88,12 @@ export { stack, grid, aspect } from './components/layout/layout.js';
 export { truncate, isTruncated } from './components/truncate/truncate.js';
 export { copyButton } from './components/copy/copy-button.js';
 export { CopyInput } from './components/copy/copy-input.js';
+export { CodeEditor, indentSelection, editorPosition } from './components/code-editor/code-editor.js';
 export { Toolbar } from './components/toolbar/toolbar.js';
 export { Toggle } from './components/toggle/toggle.js';
 export { Groupbox } from './components/groupbox/groupbox.js';
 export { Card } from './components/card/card.js';
+export { StatTile, statTile } from './components/stat-tile/stat-tile.js';
 export { Aurora } from './components/aurora/aurora.js';
 export { Panel } from './components/panel/panel.js';
 export { MasterPanel } from './components/master-panel/master-panel.js';
@@ -104,7 +109,19 @@ 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 { normalizeAppItems } from './internal/app-rail.js';
 export { AppSidebar } from './components/app-sidebar/app-sidebar.js';
@@ -118,6 +135,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';
@@ -154,6 +172,10 @@ export {
   kanbanSearchTerms, locateKanbanRecord, matchesKanbanSearch, normalizeKanbanRules,
   reorderKanbanRecords, resolveKanbanRules
 } from './components/kanban-view/kanban-policy.js';
+export {
+  createKanbanAvatars, createKanbanCardHead, createKanbanIndicator, createKanbanProgress,
+  kanbanAvatarLimit, resolveKanbanAssignees, resolveKanbanIndicator, resolveKanbanProgress
+} from './components/kanban-view/kanban-card.js';
 export { Grid, billingColumns, isBillingLine } from './components/grid/grid.js';
 export {
   Chart, ChartJsAdapter, chartSummaryTable, cloneChartValue, isEmptyChartData
@@ -161,6 +183,11 @@ export {
 export { TreeView } from './components/tree/tree.js';
 export { Finder } from './components/finder/finder.js';
 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 { Filter } from './components/filter/filter.js';
 export {
   filterOperators, emptyFilterAst, filterCondition, filterGroup,

package/src/internal/app-rail.js

@@ -1,4 +1,5 @@
 import { Component } from '../core/component.js';
+import { printf } from '../core/i18n.js';
 import { h, safeHref } from '../core/dom.js';
 import { icon } from '../core/icons.js';
 import { Dropdown } from '../components/dropdown/dropdown.js';
@@ -292,8 +293,11 @@ export class AppRailPresenter extends Component {
     });
     const actualPanel = dropdown.getPanel();
     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.
+    actualPanel.dataset.side = this.el.dataset.side;
     actualPanel.setAttribute('role', 'region');
-    actualPanel.setAttribute('aria-label', `${item.label} sub-navigation`);
+    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);
     dropdown.on('open', () => {
@@ -573,6 +577,19 @@ export class AppRailPresenter extends Component {
     this._interaction = null;
     this._flyouts = new Map();
   }
+  /**
+   * Resolves one message through `msg()`, which falls back to the host translator. Copied from
+   * `Pagination` rather than invented: the rail's flyout label was the last user-visible string
+   * in the navigation stack with no way to change it.
+   * @param {string} key Message key.
+   * @param {string} fallback English default.
+   * @param {...unknown} args Interpolation arguments.
+   * @returns {string}
+   */
+  _message(key, fallback, ...args) {
+    const message = this.msg(key, ...args);
+    return message === key ? printf(fallback, args) : message;
+  }
 }
 
 /** Owns listeners attached to one dynamic rail render so `setItems()` can release them immediately. */

package/src/internal/menu-items.js

@@ -0,0 +1,142 @@
+import { h, safeHref } from '../core/dom.js';
+import { icon } from '../core/icons.js';
+
+/** @typedef {'menuitem'|'menuitemcheckbox'|'menuitemradio'} MenuItemRole */
+/**
+ * @typedef {Object} MenuController
+ * @property {() => unknown} close Close the owning menu.
+ */
+/**
+ * @typedef {Object} MenuItem
+ * @property {string} label Item label.
+ * @property {string} [icon] Kernel icon name.
+ * @property {unknown} [value] Value emitted on selection.
+ * @property {boolean} [disabled=false] Whether selection is disabled.
+ * @property {boolean} [danger=false] Whether the action is dangerous.
+ * @property {string} [href] Native-link destination.
+ * @property {string} [target] Native-link target.
+ * @property {string} [rel] Native-link relationship.
+ * @property {string} [description] Supporting text under the label.
+ * @property {string|number} [badge] Compact trailing metadata.
+ * @property {string} [shortcut] Keyboard shortcut label.
+ * @property {string|number|Node} [adornment] Additional trailing content.
+ * @property {MenuItemRole} [role='menuitem'] APG role.
+ * @property {boolean} [checked=false] Checked state for checkbox/radio roles.
+ * @property {(value: unknown, item: MenuItem, controller: MenuController) => void} [onselect]
+ *   Selection callback.
+ */
+/**
+ * @typedef {Object} MenuHeading
+ * @property {'heading'} type Entry kind.
+ * @property {string} label Visible heading.
+ */
+/** @typedef {{type: 'separator'}} MenuSeparator */
+/** @typedef {MenuItem|MenuHeading|MenuSeparator|'-'} MenuEntry */
+
+export const MENU_ITEM_SELECTOR = [
+  '[role="menuitem"]',
+  '[role="menuitemcheckbox"]',
+  '[role="menuitemradio"]'
+].join(',');
+
+/**
+ * Reports whether an entry is an interactive menu action.
+ * @param {MenuEntry|unknown} entry Candidate entry.
+ * @returns {entry is MenuItem}
+ */
+export function isMenuItem(entry) {
+  return Boolean(entry && entry !== '-' && typeof entry === 'object'
+    && !['heading', 'separator'].includes(String(/** @type {{type?: unknown}} */ (entry).type ?? '')));
+}
+
+/**
+ * Resolves the only APG roles accepted by the shared action model.
+ * @param {MenuItem} item Item definition.
+ * @returns {MenuItemRole}
+ */
+export function menuItemRole(item) {
+  return ['menuitemcheckbox', 'menuitemradio'].includes(String(item.role))
+    ? /** @type {MenuItemRole} */ (item.role)
+    : 'menuitem';
+}
+
+/**
+ * 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.
+ * @returns {HTMLElement[]}
+ */
+export function renderMenuEntries(entries, block) {
+  const nodes = [];
+  entries.forEach((entry, index) => {
+    if (entry === '-' || (entry && typeof entry === 'object' && entry.type === 'separator')) {
+      nodes.push(h('div', { class: `zx-${block}__separator`, role: 'separator' }));
+      return;
+    }
+    if (entry && typeof entry === 'object' && entry.type === 'heading') {
+      nodes.push(h('div', {
+        class: `zx-${block}__heading`,
+        role: 'presentation'
+      }, String(entry.label ?? '')));
+      return;
+    }
+    if (!isMenuItem(entry)) return;
+
+    const role = menuItemRole(entry);
+    const href = safeHref(entry.href);
+    const target = entry.target == null ? null : String(entry.target);
+    const rel = entry.rel == null
+      ? (target === '_blank' ? 'noopener noreferrer' : null)
+      : String(entry.rel);
+    const content = [];
+    const leading = [];
+    if (role !== 'menuitem') {
+      leading.push(h('span', {
+        class: `zx-${block}__check`,
+        'data-check-kind': role === 'menuitemradio' ? 'radio' : 'checkbox'
+      }));
+    }
+    if (entry.icon) leading.push(icon(entry.icon));
+    content.push(h('span', {
+      class: `zx-${block}__leading`,
+      ariaHidden: 'true'
+    }, leading));
+    content.push(h('span', { class: `zx-${block}__body` },
+      h('span', { class: `zx-${block}__label` }, String(entry.label ?? '')),
+      entry.description == null || entry.description === '' ? null : h('span', {
+        class: `zx-${block}__description`
+      }, String(entry.description))));
+
+    const meta = [];
+    if (entry.badge != null) {
+      meta.push(h('span', { class: `zx-${block}__badge` }, String(entry.badge)));
+    }
+    if (entry.shortcut) {
+      meta.push(h('kbd', { class: `zx-${block}__shortcut` }, String(entry.shortcut)));
+    }
+    if (entry.adornment != null) {
+      const adornment = entry.adornment && typeof entry.adornment === 'object'
+        && 'nodeType' in entry.adornment
+        ? /** @type {Node} */ (entry.adornment)
+        : String(entry.adornment);
+      meta.push(h('span', { class: `zx-${block}__adornment` }, adornment));
+    }
+    if (meta.length) content.push(h('span', { class: `zx-${block}__meta` }, meta));
+
+    const properties = {
+      class: `zx-${block}__item`,
+      role,
+      tabindex: '-1',
+      'data-menu-item': String(index),
+      'data-danger': entry.danger ? 'true' : null,
+      ariaDisabled: entry.disabled ? 'true' : null,
+      ariaChecked: role === 'menuitem' ? null : String(Boolean(entry.checked))
+    };
+    if (href) {
+      nodes.push(h('a', { ...properties, href, target, rel }, content));
+    } else {
+      nodes.push(h('button', { ...properties, type: 'button' }, content));
+    }
+  });
+  return nodes;
+}

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 { overlayHost } 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,8 @@ 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;
 
     savePending = (async () => {
       let payload;
@@ -157,7 +189,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 +215,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 +259,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 {

package/src/zeyos/query.js

@@ -55,6 +55,159 @@ export function unixSecondsToDate(seconds) {
   return new Date(value * 1000);
 }
 
+/**
+ * @typedef {Object} CalendarDay
+ * @property {number} year Full year.
+ * @property {number} month Zero-based month, as `Date` counts them.
+ * @property {number} day Day of the month.
+ */
+
+/**
+ * @typedef {Object} CalendarZone
+ * @property {string|undefined} timeZone Canonical IANA zone, or undefined for the runtime's own zone.
+ * @property {(milliseconds: number) => CalendarDay} dayOf Calendar day an instant falls on in the zone.
+ * @property {(year: number, month: number, day: number) => number} midnightOf Epoch milliseconds of
+ * the first moment of a calendar day in the zone (its midnight, or the first minute after a
+ * daylight-saving gap that swallows midnight).
+ */
+
+/**
+ * Reads a ZeyOS date-only value as the calendar day it names. Date-only fields — an invoice's
+ * `date` and `duedate`, a contact's `birthdate` — hold Unix seconds at midnight of a day in the
+ * instance's time zone: a calendar day, not an instant. The result is midnight of that same day in
+ * the runtime's own zone, which is what Datebox and DatePicker edit, so the day survives a viewer in
+ * another zone and a daylight-saving change.
+ * @param {number|string|null|undefined} seconds Unix seconds; numeric strings are accepted.
+ * @param {string} [timeZone] IANA zone of the instance, such as `Europe/Vienna`; the runtime's own
+ * zone when omitted.
+ * @returns {Date|null} Local midnight of the day, or null for a nullish or empty input.
+ */
+export function unixSecondsToCalendarDay(seconds, timeZone) {
+  if (seconds == null || seconds === '') return null;
+  const value = Number(seconds);
+  if (!Number.isFinite(value)) throw new TypeError('Expected finite Unix seconds');
+  const { year, month, day } = calendarZone(timeZone).dayOf(value * 1000);
+  return localMidnight(year, month, day);
+}
+
+/**
+ * Converts the calendar day of a Date to the Unix seconds a ZeyOS date-only field stores: midnight
+ * of that day in the instance's time zone. Only the Date's local year, month, and day count — its
+ * time of day is ignored — so a Datebox value round-trips through {@link unixSecondsToCalendarDay}.
+ * @param {Date|null|undefined} date Day to store.
+ * @param {string} [timeZone] IANA zone of the instance; the runtime's own zone when omitted.
+ * @returns {number|null} Unix seconds, or null for a nullish input.
+ */
+export function calendarDayToUnixSeconds(date, timeZone) {
+  if (date == null) return null;
+  if (!(date instanceof Date)) throw new TypeError('Expected a Date');
+  if (!Number.isFinite(date.getTime())) throw new RangeError('Invalid Date');
+  const midnight = calendarZone(timeZone).midnightOf(date.getFullYear(), date.getMonth(), date.getDate());
+  return Math.floor(midnight / 1000);
+}
+
+/**
+ * Validates an IANA time-zone name.
+ * @param {unknown} timeZone Zone name; nullish or empty selects the runtime's own zone.
+ * @returns {string|undefined} The canonical zone name, or undefined for the runtime's own zone.
+ * @throws {RangeError} When the runtime does not know the zone.
+ */
+export function normalizeTimeZone(timeZone) {
+  if (timeZone == null || timeZone === '') return undefined;
+  try {
+    return new Intl.DateTimeFormat('en-US', { timeZone: String(timeZone) }).resolvedOptions().timeZone;
+  } catch {
+    throw new RangeError(`Unknown time zone "${String(timeZone)}"`);
+  }
+}
+
+/**
+ * Calendar arithmetic for one time zone. The `Intl` formatter is built once, so a table column can
+ * hold one zone for all of its cells.
+ * @param {string} [timeZone] IANA zone; the runtime's own zone when omitted.
+ * @returns {CalendarZone} Day lookup and midnight construction for the zone.
+ */
+export function calendarZone(timeZone) {
+  const zone = normalizeTimeZone(timeZone);
+  if (!zone) {
+    return {
+      timeZone: undefined,
+      dayOf: (milliseconds) => {
+        const date = new Date(milliseconds);
+        return { year: date.getFullYear(), month: date.getMonth(), day: date.getDate() };
+      },
+      midnightOf: (year, month, day) => localMidnight(year, month, day).getTime()
+    };
+  }
+
+  const formatter = new Intl.DateTimeFormat('en-US', {
+    timeZone: zone,
+    hourCycle: 'h23',
+    year: 'numeric',
+    month: 'numeric',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: 'numeric',
+    second: 'numeric'
+  });
+  /** @param {number} milliseconds @returns {CalendarDay & {seconds: number}} */
+  const wallClock = (milliseconds) => {
+    const parts = {};
+    for (const part of formatter.formatToParts(new Date(milliseconds))) parts[part.type] = Number(part.value);
+    return {
+      year: parts.year,
+      month: parts.month - 1,
+      day: parts.day,
+      seconds: (parts.hour % 24) * 3600 + parts.minute * 60 + parts.second
+    };
+  };
+  /** @param {number} milliseconds @returns {number} The zone's UTC offset at that instant, in milliseconds. */
+  const offsetAt = (milliseconds) => {
+    const wall = wallClock(milliseconds);
+    return utcMidnight(wall.year, wall.month, wall.day) + wall.seconds * 1000
+      - Math.floor(milliseconds / 1000) * 1000;
+  };
+
+  return {
+    timeZone: zone,
+    dayOf: (milliseconds) => {
+      const { year, month, day } = wallClock(milliseconds);
+      return { year, month, day };
+    },
+    midnightOf: (year, month, day) => {
+      // Midnight is the instant whose wall clock reads the target day at 00:00. Two offset
+      // corrections settle it on either side of a daylight-saving change; where a change skips
+      // midnight altogether, the earlier candidate lands on the previous evening and the later one
+      // on the first minute of the day, which is the one kept.
+      const target = utcMidnight(year, month, day);
+      const first = target - offsetAt(target);
+      const second = target - offsetAt(first);
+      let best = null;
+      for (const candidate of [second, first]) {
+        const wall = wallClock(candidate);
+        if (wall.year !== year || wall.month !== month || wall.day !== day) continue;
+        if (!best || wall.seconds < best.seconds) best = { candidate, seconds: wall.seconds };
+      }
+      return best ? best.candidate : second;
+    }
+  };
+}
+
+/** @param {number} year @param {number} month @param {number} day @returns {Date} */
+function localMidnight(year, month, day) {
+  const date = new Date(2000, 0, 1);
+  date.setFullYear(year, month, day);
+  date.setHours(0, 0, 0, 0);
+  return date;
+}
+
+/** @param {number} year @param {number} month @param {number} day @returns {number} */
+function utcMidnight(year, month, day) {
+  const date = new Date(0);
+  date.setUTCFullYear(year, month, day);
+  return date.getTime();
+}
+
 /**
  * Converts one or more Zx Table sort records to the signed field notation used by ZeyOS.
  * A missing sort produces an empty array.