@zeyos/zx 4.4.0 → 5.2.0

package/dist/types/zeyos/module-bar.d.ts

@@ -0,0 +1,176 @@
+import { ModuleBar } from '../components/module-bar/module-bar.js';
+export type ModuleItem = import('../components/module-bar/module-bar.js').ModuleItem;
+export type ModuleBarOptions = import('../components/module-bar/module-bar.js').ModuleBarOptions;
+export type AppSidebarOptions = import('../components/app-sidebar/app-sidebar.js').AppSidebarOptions;
+export type ZeyosMenuEntry = {
+    /**
+     * Entry identifier; a section needs none.
+     */
+    id?: string | number;
+    /**
+     * Entry label.
+     */
+    label: string;
+    /**
+     * Destination.
+     */
+    href?: string;
+    /**
+     * Link browsing context.
+     */
+    target?: string;
+    /**
+     * Application-owned action.
+     */
+    invoke?: () => void;
+    /**
+     * Count.
+     */
+    badge?: string | number;
+    /**
+     * Icon name or node.
+     */
+    icon?: string | Node;
+    /**
+     * A heading over `children` rather than a destination.
+     */
+    section?: boolean;
+    /**
+     * Nested entries.
+     */
+    children?: Array<ZeyosMenuEntry | Array<any>>;
+};
+export type ZeyosModuleBarState = {
+    /**
+     * Permitted module catalogue.
+     */
+    modules?: Record<string, string> | Array<string | Record<string, any>>;
+    /**
+     * Forks, weblets, and authoritative menu entries.
+     */
+    menuApps?: Array<Array<any> | Record<string, any>>;
+    /**
+     * Application identifiers on the bar, in order; the rest are under "All modules".
+     */
+    pinned?: string[];
+    /**
+     * Current module, `fork#…`, or `weblet#…` identifier.
+     */
+    activeIdentifier?: string | null;
+    /**
+     * Current menu entry, when it is more precise than the module.
+     */
+    active?: string | number | null;
+    /**
+     * Permission predicate.
+     */
+    canUseModule?: (module: string) => boolean;
+    /**
+     * Maps an application to href/invoke/value metadata.
+     */
+    resolveApplication?: (app: unknown) => Record<string, any> | null;
+    /**
+     * Each application's menu, keyed by identifier.
+     */
+    menus?: Record<string, Array<ZeyosMenuEntry | Array<any>>>;
+    /**
+     * Badges keyed by application identifier or menu entry id.
+     */
+    badges?: Record<string, string | number>;
+    /**
+     * "All modules" group per application identifier.
+     */
+    groups?: Record<string, string>;
+    /**
+     * Group labels for forks and weblets.
+     */
+    labels?: {
+        forks?: string;
+        weblets?: string;
+    };
+    /**
+     * Host icon renderer.
+     */
+    renderApplicationIcon?: (app: unknown, normalized: Record<string, any>) => Node | null;
+};
+export type ZeyosModuleBarOptions = {
+    /**
+     * Use stock Font Awesome glyphs instead of the ZeyOS kit.
+     */
+    standardIcons?: boolean;
+    /**
+     * Tile treatment; ZeyOS draws its modules solid.
+     */
+    appearance?: 'solid' | 'tint' | 'plain';
+};
+/** @typedef {import('../components/module-bar/module-bar.js').ModuleItem} ModuleItem */
+/** @typedef {import('../components/module-bar/module-bar.js').ModuleBarOptions} ModuleBarOptions */
+/** @typedef {import('../components/app-sidebar/app-sidebar.js').AppSidebarOptions} AppSidebarOptions */
+/**
+ * One entry of a module's menu, as the ZeyOS shell describes it: an object, or an
+ * `[id, label, href]` array.
+ * @typedef {Object} ZeyosMenuEntry
+ * @property {string|number} [id] Entry identifier; a section needs none.
+ * @property {string} label Entry label.
+ * @property {string} [href] Destination.
+ * @property {string} [target] Link browsing context.
+ * @property {() => void} [invoke] Application-owned action.
+ * @property {string|number} [badge] Count.
+ * @property {string|Node} [icon] Icon name or node.
+ * @property {boolean} [section] A heading over `children` rather than a destination.
+ * @property {Array<ZeyosMenuEntry|Array<any>>} [children] Nested entries.
+ */
+/**
+ * The ZeyOS shell state a module bar is built from. The application fields are the launcher's
+ * (`buildZeyosLauncherConfig()`), so one state object can feed both.
+ * @typedef {Object} ZeyosModuleBarState
+ * @property {Record<string, string>|Array<string|Record<string, any>>} [modules={}] Permitted module catalogue.
+ * @property {Array<Array<any>|Record<string, any>>} [menuApps=[]] Forks, weblets, and authoritative menu entries.
+ * @property {string[]} [pinned] Application identifiers on the bar, in order; the rest are under "All modules".
+ * @property {string|null} [activeIdentifier=null] Current module, `fork#…`, or `weblet#…` identifier.
+ * @property {string|number|null} [active=null] Current menu entry, when it is more precise than the module.
+ * @property {(module: string) => boolean} [canUseModule] Permission predicate.
+ * @property {(app: unknown) => Record<string, any>|null} [resolveApplication] Maps an application to href/invoke/value metadata.
+ * @property {Record<string, Array<ZeyosMenuEntry|Array<any>>>} [menus={}] Each application's menu, keyed by identifier.
+ * @property {Record<string, string|number>} [badges={}] Badges keyed by application identifier or menu entry id.
+ * @property {Record<string, string>} [groups={}] "All modules" group per application identifier.
+ * @property {{forks?: string, weblets?: string}} [labels] Group labels for forks and weblets.
+ * @property {(app: unknown, normalized: Record<string, any>) => Node|null} [renderApplicationIcon] Host icon renderer.
+ */
+/**
+ * @typedef {Object} ZeyosModuleBarOptions
+ * @property {boolean} [standardIcons=false] Use stock Font Awesome glyphs instead of the ZeyOS kit.
+ * @property {'solid'|'tint'|'plain'} [appearance='solid'] Tile treatment; ZeyOS draws its modules solid.
+ */
+/**
+ * Maps ZeyOS shell state to module bar items: every permitted module, fork, and weblet with its
+ * kit icon, its identity colour (the payload's, else the registry's), its menu, and its badge.
+ * A module with a menu is a panel module; one without is a destination.
+ * @param {ZeyosModuleBarState} [state={}] Application-owned shell state.
+ * @param {ZeyosModuleBarOptions} [options={}] Mapping options.
+ * @returns {ModuleItem[]}
+ */
+export declare function zeyosModuleItems(state?: ZeyosModuleBarState, options?: ZeyosModuleBarOptions): ModuleItem[];
+/**
+ * Builds plain ModuleBar options from ZeyOS shell state.
+ * @param {ZeyosModuleBarState} [state={}] Application-owned shell state.
+ * @param {ZeyosModuleBarOptions & ModuleBarOptions} [options={}] Mapping and ModuleBar options.
+ * @returns {ModuleBarOptions}
+ */
+export declare function buildZeyosModuleBarConfig(state?: ZeyosModuleBarState, options?: ZeyosModuleBarOptions & ModuleBarOptions): ModuleBarOptions;
+/**
+ * Builds AppSidebar options for the modules layout from ZeyOS shell state: the module strip beside
+ * a panel with the current module's menu.
+ * @param {ZeyosModuleBarState} [state={}] Application-owned shell state.
+ * @param {ZeyosModuleBarOptions & AppSidebarOptions} [options={}] Mapping and AppSidebar options.
+ * @returns {AppSidebarOptions}
+ */
+export declare function buildZeyosAppSidebarConfig(state?: ZeyosModuleBarState, options?: ZeyosModuleBarOptions & AppSidebarOptions): AppSidebarOptions;
+/**
+ * Creates a ModuleBar from ZeyOS shell state.
+ * @param {Element|string|null} target Bar target, or null to create one.
+ * @param {ZeyosModuleBarState} [state={}] Application-owned shell state.
+ * @param {ZeyosModuleBarOptions & ModuleBarOptions} [options={}] Mapping and ModuleBar options.
+ * @returns {ModuleBar}
+ */
+export declare function zeyosModuleBar(target: Element | string | null, state?: ZeyosModuleBarState, options?: ZeyosModuleBarOptions & ModuleBarOptions): ModuleBar;

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

@@ -65,11 +65,13 @@ export type ServerFilterDefinition = {
      */
     operator?: string;
     /**
-     * Semantic value format; date/datetime values become Unix seconds.
+     * Semantic value format; date/datetime values become Unix seconds. With
+     * a `timeZone` conversion option, a `date` (date-only) value is a calendar day and becomes that
+     * day's midnight in the zone, like a ZeyOS form stores it; `datetime` values stay instants.
      */
     format?: string;
     /**
-     * Semantic value type; date/datetime values become Unix seconds.
+     * Semantic value type, read like `format`.
      */
     type?: string;
     /**
@@ -108,8 +110,10 @@ export type ServerFilterDefinition = {
  * @property {string} [rawField] Raw ZeyOS field when the UI id is an alias.
  * @property {string[]} [fields] Raw fields combined as an OR group.
  * @property {string} [operator] ZeyOS comparison operator such as `>=` or `IN`.
- * @property {string} [format] Semantic value format; date/datetime values become Unix seconds.
- * @property {string} [type] Semantic value type; date/datetime values become Unix seconds.
+ * @property {string} [format] Semantic value format; date/datetime values become Unix seconds. With
+ * a `timeZone` conversion option, a `date` (date-only) value is a calendar day and becomes that
+ * day's midnight in the zone, like a ZeyOS form stores it; `datetime` values stay instants.
+ * @property {string} [type] Semantic value type, read like `format`.
  * @property {boolean} [includeEmpty=false] Preserve an empty-string value instead of treating it as inactive UI state.
  * @property {boolean} [includeNull=false] Preserve null instead of treating it as inactive UI state.
  * @property {(value: unknown, state: Record<string, unknown>) => unknown} [transform] Value transform.
@@ -129,6 +133,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.
@@ -136,6 +219,26 @@ export declare function unixSecondsToDate(seconds: number | string | null | unde
  * @returns {string[]} Signed raw fields such as `+name` or `-lastmodified`.
  */
 export declare function tableSortToQuery(sort: ZxSort | ZxSort[] | null | undefined): string[];
+export type FilterConversionOptions = {
+    /**
+     * IANA zone of the ZeyOS instance. When given, values of
+     * `date` (date-only) definitions are calendar days: a `Date` counts by its local year, month, and
+     * day, a `YYYY-MM-DD` string by its digits, and either becomes midnight of that day in the zone —
+     * exactly what `calendarDayToUnixSeconds()` and `zeyosForm()` store, so a viewer in another zone
+     * filters `duedate` by the day they picked. `null` names the runtime's own zone. Omitted, dates
+     * convert as exact instants, as they always have.
+     */
+    timeZone?: string | null;
+};
+/**
+ * @typedef {Object} FilterConversionOptions
+ * @property {string|null} [timeZone] IANA zone of the ZeyOS instance. When given, values of
+ * `date` (date-only) definitions are calendar days: a `Date` counts by its local year, month, and
+ * day, a `YYYY-MM-DD` string by its digits, and either becomes midnight of that day in the zone —
+ * exactly what `calendarDayToUnixSeconds()` and `zeyosForm()` store, so a viewer in another zone
+ * filters `duedate` by the day they picked. `null` names the runtime's own zone. Omitted, dates
+ * convert as exact instants, as they always have.
+ */
 /**
  * Converts DataFilter state to ZeyOS field predicates. Definitions may rename UI ids,
  * add comparison operators, combine several fields with OR, or transform values. Blank/null
@@ -143,9 +246,11 @@ export declare function tableSortToQuery(sort: ZxSort | ZxSort[] | null | undefi
  * the distinct ZeyOS meanings. Zero and false are always retained.
  * @param {Record<string, unknown>} state DataFilter state keyed by definition id.
  * @param {ServerFilterDefinition[]|Record<string, string|ServerFilterDefinition>} [defs=[]] Server mappings.
+ * @param {FilterConversionOptions} [options={}] Conversion options, such as the instance zone.
  * @returns {Record<string, unknown>} ZeyOS `filters` object (plural at the call site).
+ * @throws {RangeError} When `options.timeZone` names a zone the runtime does not know.
  */
-export declare function dataFilterStateToFilters(state: Record<string, unknown>, defs?: ServerFilterDefinition[] | Record<string, string | ServerFilterDefinition>): Record<string, unknown>;
+export declare function dataFilterStateToFilters(state: Record<string, unknown>, defs?: ServerFilterDefinition[] | Record<string, string | ServerFilterDefinition>, options?: FilterConversionOptions): Record<string, unknown>;
 /**
  * Builds the body passed to a generated `client.api.list<Resource>()` operation. Predicates are
  * always emitted under `filters` (plural), which is required for indexed foreign-key matching.

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.