@zeyos/zx 4.4.0 → 5.0.0

package/dist/types/core/breakpoint.d.ts

@@ -5,7 +5,7 @@
  * used inside a media query, so a `--zx-bp-*` token would be a value no stylesheet could read.
  * Zx's own layout utilities avoid the problem entirely — `.zx-grid` reflows on intrinsic track
  * widths, not on breakpoints — which leaves this module for the cases only script can decide:
- * rendering a Table as cards below a width, collapsing a MasterPanel, choosing a chart density.
+ * rendering a Table as cards below a width, collapsing a MasterPanel, choosing how many labels a chart shows.
  * @module zx/core/breakpoint
  */
 export type BreakpointName = 'xs' | 'sm' | 'md' | 'lg' | 'xl';

package/dist/types/core/icons.d.ts

@@ -1,7 +1,8 @@
 /**
  * The icon layer. Two renderers sit behind one `icon()` call:
  *
- * - **built-in** (default) — the inline SVG glyphs below, no network, no stylesheet, no font.
+ * - **built-in** (default) — the inline SVG outline glyphs below (Lucide), no network, no
+ *   stylesheet, no font. Applications can add their own, filled or outlined, with `registerIcons()`.
  * - **Font Awesome** — `<i>` elements carrying Font Awesome classes, after an application opts in
  *   with `useFontAwesome()` or `loadFontAwesome(kit)`. Zx never loads a kit by itself.
  *
@@ -40,28 +41,16 @@ export type IconOptions = {
      */
     strict?: boolean;
 };
+export type IconPaint = 'fill' | 'stroke';
+export type IconGlyph = [string, string] | [string, string, IconPaint];
 /**
- * @typedef {Object} IconOptions
- * @property {number|string} [size=16] Rendered width and height.
- * @property {string|null} [label=null] Accessible label; null marks the icon decorative.
- * @property {string|string[]} [class] Extra class names added to the element.
- * @property {string} [style] Font Awesome style for this icon only (`'solid'`, `'duotone'`, …).
- * @property {string} [family] Font Awesome family for this icon only (`'classic'`, `'sharp'`, …).
- * @property {boolean} [fixedWidth] Adds Font Awesome's `fa-fw` for column-aligned glyphs.
- * @property {boolean} [strict=false] Throws `RangeError` on a name the bundled glyph set does not
- *   carry, instead of returning the placeholder. For call sites that can afford to fail — a test,
- *   a build-time check — rather than a screen rendering server data.
+ * The bundled glyph set: outline icons from Lucide (ISC; see the notice above), embedded as path
+ * data so the library carries no webfont, stylesheet, or package dependency. Every entry is
+ * `[viewBox, path, 'stroke']` in a 24-unit view box. Extend the set with `registerIcons()`; read
+ * every available name with `iconNames()`.
+ * @type {Readonly<Record<string, IconGlyph>>}
  */
-/**
- * Icon glyphs from Font Awesome Free 6 (solid, plus `square` from regular), fontawesome.com,
- * licensed CC BY 4.0 (https://fontawesome.com/license/free). Path data is embedded unmodified so
- * the library carries no webfont, stylesheet, or package dependency. Each entry is
- * `[viewBox, path]`; Font Awesome glyphs are filled (not stroked) and use per-glyph 512-unit view
- * boxes — outlines such as `square` are a filled path with a counter-wound hole.
- * Extend the set with `registerIcons()`; read every available name with `iconNames()`.
- * @type {Readonly<Record<string, [string, string]>>}
- */
-export declare const icons: Readonly<Record<string, [string, string]>>;
+export declare const icons: Readonly<Record<string, IconGlyph>>;
 export type IconConfig = {
     /**
      * Renderer used for bare icon names.
@@ -120,12 +109,21 @@ export declare function loadFontAwesome(options: string | (Partial<Omit<IconConf
     activate?: boolean;
 })): Promise<IconConfig>;
 /**
- * Adds inline SVG glyphs to the built-in set, or replaces existing ones. Entries use the same
- * `[viewBox, path]` shape as `icons`.
- * @param {Record<string, [string, string]>} glyphs Glyphs keyed by icon name.
+ * Adds inline SVG glyphs to the built-in set, or replaces existing ones.
+ *
+ * An entry is `[viewBox, path]` — a filled shape, the format Font Awesome path data comes in, and
+ * how it always rendered — or `[viewBox, path, 'stroke']` — an outline drawn with the same pen as
+ * the bundled set: `currentColor`, round caps and joins, and a stroke scaled to the view box, so a
+ * glyph from a 24-unit outline set such as Lucide renders exactly like a bundled one.
+ *
+ *     registerIcons({ rocket: ['0 0 512 512', 'M…'] });           // filled
+ *     registerIcons({ anchor: ['0 0 24 24', 'M12 6v16…', 'stroke'] });  // outline
+ * @param {Record<string, IconGlyph>} glyphs Glyphs keyed by icon name.
  * @returns {void}
+ * @throws {TypeError} When an entry is neither a `[viewBox, path]` pair nor a
+ *   `[viewBox, path, 'fill'|'stroke']` triple.
  */
-export declare function registerIcons(glyphs: Record<string, [string, string]>): void;
+export declare function registerIcons(glyphs: Record<string, IconGlyph>): void;
 /**
  * Lists every inline SVG glyph name available, built-in and registered.
  * @returns {string[]} Sorted icon names.

package/dist/types/core/motion.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Motion as a setting, for the code that animates in script.
+ *
+ * CSS motion needs nothing from here: `tokens/global.css` sets every `--zx-dur-*` to 0ms and
+ * `base.css` stops animations and transitions both under the operating system's reduced-motion
+ * preference and inside any `data-zx-motion="reduced"` region. A chart engine's own tweening, a
+ * `requestAnimationFrame` loop, or `element.animate()` never sees those rules, so a component that
+ * moves things itself asks `prefersReducedMotion()` before it starts and `watchMotion()` for the
+ * moment the answer changes.
+ *
+ * There is no "full motion" value: a region can only ask for less. Someone who asked their system
+ * for reduced motion gets it whatever an application or a region says.
+ * @module zx/core/motion
+ */
+/** The attribute that marks a reduced-motion region. Its one meaningful value is `reduced`. */
+export declare const MOTION_ATTRIBUTE = "data-zx-motion";
+/**
+ * Whether motion should stop where `element` is: true under the operating system's reduced-motion
+ * preference, or when the element sits inside a `data-zx-motion="reduced"` region (the element
+ * itself included). The region check crosses shadow-root boundaries.
+ * @param {Element|null} [element] Where the motion would happen. Omitted, the document root is
+ *   asked — which answers for an application that sets the attribute on `<html>`.
+ * @returns {boolean}
+ */
+export declare function prefersReducedMotion(element?: Element | null): boolean;
+export type WatchMotionOptions = {
+    /**
+     * Stops watching when aborted, exactly as calling the returned
+     * disposer does. A signal that is already aborted watches nothing.
+     */
+    signal?: AbortSignal;
+    /**
+     * Also calls back once, synchronously, with the current
+     * answer — convenient for a loop that starts or stays stopped in the same callback.
+     */
+    immediate?: boolean;
+};
+/**
+ * @typedef {Object} WatchMotionOptions
+ * @property {AbortSignal} [signal] Stops watching when aborted, exactly as calling the returned
+ *   disposer does. A signal that is already aborted watches nothing.
+ * @property {boolean} [immediate=false] Also calls back once, synchronously, with the current
+ *   answer — convenient for a loop that starts or stays stopped in the same callback.
+ */
+/**
+ * Calls back whenever `prefersReducedMotion(element)` changes: when the operating-system preference
+ * flips, or when a `data-zx-motion` attribute is set, changed, or removed on the element or any
+ * ancestor (in the document, or in the shadow root the element lives in). The callback receives
+ * the new answer and runs only on a real change.
+ *
+ * Moving the element into or out of a reduced region is not observed — ask
+ * `prefersReducedMotion()` again after re-parenting.
+ * @param {Element|null} element Where the motion happens. Null watches the document root.
+ * @param {(reduced: boolean) => void} fn Receives `true` when motion must stop, `false` when it may
+ *   run again.
+ * @param {WatchMotionOptions} [options={}]
+ * @returns {() => void} Disposer: stops watching. Safe to call more than once.
+ */
+export declare function watchMotion(element: Element | null, fn: (reduced: boolean) => void, options?: WatchMotionOptions): () => void;

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

@@ -2,7 +2,7 @@
  * Finds the closest styling scope for a top-layer element.
  *
  * Popovers and dialogs escape clipping even when their DOM parent is inside an application shell,
- * so keeping them below that parent preserves inherited theme, density, material, and product
+ * so keeping them below that parent preserves inherited theme, preset, material, and product
  * token overrides without sacrificing top-layer behaviour. The document body remains the safe
  * fallback for unscoped applications.
  *
@@ -10,3 +10,17 @@
  * @returns {Element}
  */
 export declare function overlayHost(source?: Element | string | null): Element;
+/**
+ * Like `overlayHost()`, but declines to guess for a source that is not in the document yet.
+ *
+ * A component created before its anchor is connected cannot know which themed region the anchor
+ * will end up in: the anchor's ancestors are not there yet, so `overlayHost()` would answer
+ * `<body>`, outside every `[data-zx-theme]` and `.zx-scope`. This returns null instead, so the
+ * overlay can stay detached until it first opens and resolve its host with `overlayHost()` then,
+ * when the anchor is in place. The focused-element default (`source` null) is always connected and
+ * resolves exactly as `overlayHost()` does.
+ *
+ * @param {Element|string|null} [source=null] Element or selector whose styling scope should own the overlay.
+ * @returns {Element|null} The host, or null while the source is not connected to the document.
+ */
+export declare function connectedOverlayHost(source?: Element | string | null): Element | null;

package/dist/types/index.d.ts

@@ -11,6 +11,7 @@ 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 { focusTrap, rovingTabindex, typeahead } from './core/keyboard.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,7 +54,7 @@ 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';
@@ -72,6 +73,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';

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,7 +3,7 @@
  * @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';

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

@@ -129,6 +129,85 @@ export declare function dateToUnixSeconds(date: Date | null | undefined): number
  * @returns {Date|null} Date value, or null for a nullish input.
  */
 export declare function unixSecondsToDate(seconds: number | string | null | undefined): Date | null;
+export type CalendarDay = {
+    /**
+     * Full year.
+     */
+    year: number;
+    /**
+     * Zero-based month, as `Date` counts them.
+     */
+    month: number;
+    /**
+     * Day of the month.
+     */
+    day: number;
+};
+export type CalendarZone = {
+    /**
+     * Canonical IANA zone, or undefined for the runtime's own zone.
+     */
+    timeZone: string | undefined;
+    /**
+     * Calendar day an instant falls on in the zone.
+     */
+    dayOf: (milliseconds: number) => CalendarDay;
+    /**
+     * 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).
+     */
+    midnightOf: (year: number, month: number, day: number) => number;
+};
+/**
+ * @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 declare function unixSecondsToCalendarDay(seconds: number | string | null | undefined, timeZone?: string): Date | null;
+/**
+ * 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 declare function calendarDayToUnixSeconds(date: Date | null | undefined, timeZone?: string): number | null;
+/**
+ * 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 declare function normalizeTimeZone(timeZone: unknown): string | undefined;
+/**
+ * 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 declare function calendarZone(timeZone?: string): CalendarZone;
 /**
  * Converts one or more Zx Table sort records to the signed field notation used by ZeyOS.
  * A missing sort produces an empty array.

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

@@ -22,6 +22,19 @@ export type ResolveFieldOptions = {
      * Per-field label overrides.
      */
     labels?: Record<string, string>;
+    /**
+     * Per-field semantic format overrides (`date`,
+     * `datetime`, `money`, or any registered key). The schema types a timestamp only by its storage,
+     * so this is how a Unix-second field the built-in rules misread is declared a calendar day
+     * (`date`) or an instant (`datetime`).
+     */
+    formats?: Record<string, string>;
+    /**
+     * IANA time zone of the ZeyOS instance, such as `Europe/Vienna`.
+     * Date-only fields store midnight of a calendar day in this zone; it is copied onto every field's
+     * metadata as `timeZone`. Defaults to the runtime's own zone.
+     */
+    timeZone?: string;
 };
 /** @typedef {Record<string, unknown>} FieldMeta */
 /**
@@ -34,6 +47,13 @@ export type ResolveFieldOptions = {
  * @property {string[]} [fields] Curated allow-list; its order becomes the output order.
  * @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 (`date`,
+ * `datetime`, `money`, or any registered key). The schema types a timestamp only by its storage,
+ * so this is how a Unix-second field the built-in rules misread is declared a calendar day
+ * (`date`) or an instant (`datetime`).
+ * @property {string} [timeZone] IANA time zone of the ZeyOS instance, such as `Europe/Vienna`.
+ * Date-only fields store midnight of a calendar day in this zone; it is copied onto every field's
+ * metadata as `timeZone`. Defaults to the runtime's own zone.
  */
 /**
  * Extensible ZeyOS semantic/DB type registry. Keys are normalized to lowercase. Built-in choices:
@@ -61,7 +81,8 @@ export declare function fieldToZxField(meta: FieldMeta): Record<string, unknown>
 /**
  * Converts normalized ZeyOS field metadata to a Zx Table column configuration. Renderers return
  * strings only (never DOM): references/enums show labels, numeric columns are right-aligned,
- * booleans show a check, and Unix seconds are formatted as dates.
+ * booleans show a check, and Unix seconds are formatted as dates — a date-only field as the
+ * calendar day it names in `meta.timeZone`, with no time; a date-time field with its time.
  * @param {FieldMeta} meta Normalized metadata containing at least `id` or `name`.
  * @returns {Record<string, unknown>} Plain Zx Table column descriptor.
  */
@@ -71,6 +92,8 @@ export declare function fieldToZxColumn(meta: FieldMeta): Record<string, unknown
  * client returns names from `schema.fields(resource)` and definitions from
  * `schema.describe(resource).fields`; embedded `enum` data is authoritative. A compatible
  * `schema.enums(resource, field)` is used when supplied by another client version/stub.
+ * `formats` overrides a field's semantic `format`, and `timeZone` is validated once and copied
+ * onto every field.
  * @param {Record<string, any>} client Injected `@zeyos/client` instance.
  * @param {string} resource Schema resource name such as `tickets`.
  * @param {ResolveFieldOptions} [opts={}] Curation options.

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

@@ -1,4 +1,5 @@
 import { Table } from '../index.js';
+export type TableOptions = import('../components/table/table.js').TableOptions;
 export type ZeyosTableOptions = {
     /**
      * Curated ordered field allow-list.
@@ -8,6 +9,16 @@ export type ZeyosTableOptions = {
      * 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. Date-only columns show the
+     * calendar day their stored midnight names in this zone; defaults to the runtime's own zone.
+     */
+    timeZone?: string;
     /**
      * Row id accessor.
      */
@@ -43,6 +54,91 @@ export type ZeyosTableOptions = {
      * Row activation callback.
      */
     onRowClick?: (row: Record<string, unknown>, event: CustomEvent<Record<string, unknown>>) => void;
+    /**
+     * Table frame treatment; `'plain'` for a
+     * table inside a pane or card that already draws the box.
+     */
+    variant?: TableOptions['variant'];
+    /**
+     * Whether alternate rows use the zebra background.
+     */
+    zebra?: boolean;
+    /**
+     * Whether column headers stick while scrolling.
+     */
+    stickyHeader?: boolean;
+    /**
+     * Width below which rows stack.
+     */
+    responsive?: TableOptions['responsive'];
+    /**
+     * Rows rendered at first from a loaded page.
+     */
+    growing?: TableOptions['growing'];
+    /**
+     * What the table shows with no rows.
+     */
+    emptyText?: TableOptions['emptyText'];
+    /**
+     * Additional row class callback.
+     */
+    rowClass?: TableOptions['rowClass'];
+    /**
+     * Row property or callback naming each row's kind.
+     */
+    rowKind?: TableOptions['rowKind'];
+    /**
+     * Presentation per row kind.
+     */
+    rowKinds?: TableOptions['rowKinds'];
+    /**
+     * Whether a column visibility chooser is rendered.
+     */
+    columnVisibility?: boolean;
+    /**
+     * Whether the column chooser exposes reorder controls.
+     */
+    columnReorder?: boolean;
+    /**
+     * Initially hidden column ids.
+     */
+    hiddenColumns?: string[];
+    /**
+     * Table `rowclick` listener, beside `onRowClick`.
+     */
+    onrowclick?: TableOptions['onrowclick'];
+    /**
+     * Table `rowdblclick` listener.
+     */
+    onrowdblclick?: TableOptions['onrowdblclick'];
+    /**
+     * Table `sort` listener; the binding reloads either way.
+     */
+    onsort?: TableOptions['onsort'];
+    /**
+     * Table `selectionchange` listener.
+     */
+    onselectionchange?: TableOptions['onselectionchange'];
+    /**
+     * Table `datachange` listener.
+     */
+    ondatachange?: TableOptions['ondatachange'];
+    /**
+     * Table `stackedchange` listener.
+     */
+    onstackedchange?: TableOptions['onstackedchange'];
+    /**
+     * Table `grow` listener.
+     */
+    ongrow?: TableOptions['ongrow'];
+    /**
+     * Table `columnvisibilitychange` listener.
+     */
+    oncolumnvisibilitychange?: TableOptions['oncolumnvisibilitychange'];
+    /**
+     * Table `columnorderchange` listener.
+     */
+    oncolumnorderchange?: TableOptions['oncolumnorderchange'];
 };
 export type ZeyosTableConfig = {
     /**
@@ -136,19 +232,6 @@ export type ZeyosTableBinding = {
      */
     destroy: () => void;
 };
-/**
- * @typedef {Object} ZeyosTableOptions
- * @property {string[]} [fields] Curated ordered field allow-list.
- * @property {Record<string, string>} [labels] Per-field label overrides.
- * @property {string|((row: Record<string, unknown>) => unknown)} [rowId='ID'] Row id accessor.
- * @property {number} [pageSize=50] Server page size.
- * @property {{id: string, dir: 'asc'|'desc'}|null} [sort=null] Initial server sort.
- * @property {Record<string, unknown>} [filters] Initial ZeyOS predicates.
- * @property {string} [search=''] Initial full-text query.
- * @property {false|'single'|'multi'} [selectable=false] Row selection mode.
- * @property {number|string|null} [height=null] Table scroll-region height.
- * @property {(row: Record<string, unknown>, event: CustomEvent<Record<string, unknown>>) => void} [onRowClick] Row activation callback.
- */
 /**
  * @typedef {Object} ZeyosTableConfig
  * @property {Record<string, any>[]} fieldMeta Ordered normalized schema metadata.
@@ -186,7 +269,8 @@ export type ZeyosTableBinding = {
  * Builds the DOM-free schema-derived columns and Table options used by {@link zeyosTable}. Entity
  * projections include an `<field>_label` alias from a real label field on the referenced resource.
  * Amount fields use each row's real `currency` value for display while retaining the WP14 typed
- * column strategy and right alignment.
+ * column strategy and right alignment. Enum columns show labels, date-only columns calendar days in
+ * `timeZone`, and Table presentation options and listeners pass through to `tableOptions`.
  * @param {Record<string, any>} client Injected ZeyOS client instance.
  * @param {string} resource Resource name such as `transactions`.
  * @param {ZeyosTableOptions} [opts={}] Schema, table, and initial query options.
@@ -197,6 +281,8 @@ export declare function buildZeyosTableConfig(client: Record<string, any>, resou
  * Generates a server-backed Zx Table. Sorting automatically reloads page zero. `load({page: 0})`
  * replaces data, higher pages append it, and `loadMore()` uses `limit`/`offset` plus the returned
  * count. DataFilter callers can map state with `dataFilterStateToFilters` before `setFilters()`.
+ * Table presentation options (`variant`, `zebra`, `stickyHeader`, `responsive`, `emptyText`, …) and
+ * listeners are passed through to the generated Table.
  * @param {Record<string, any>} client Injected ZeyOS client instance.
  * @param {string} resource Resource name such as `transactions`.
  * @param {ZeyosTableOptions} [opts={}] Schema, table, and initial query options.