@zeyos/zx 4.4.0 → 5.2.0

package/src/zeyos/module-bar.js

@@ -0,0 +1,181 @@
+import { ModuleBar } from '../components/module-bar/module-bar.js';
+import { normalizeAppItems } from '../internal/app-rail.js';
+import { moduleIcon } from './icons.js';
+import { mergeDestination, normalizeApplication } from './launcher.js';
+import { moduleInfo } from './modules.js';
+
+/** @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 function zeyosModuleItems(state = {}, options = {}) {
+  const pinned = Array.isArray(state.pinned) ? state.pinned.map(String) : null;
+  const menus = state.menus && typeof state.menus === 'object' ? state.menus : {};
+  const badges = state.badges && typeof state.badges === 'object' ? state.badges : {};
+  const groups = state.groups && typeof state.groups === 'object' ? state.groups : {};
+  const labels = { forks: 'Forks', weblets: 'Weblets', ...(state.labels ?? {}) };
+  const seen = new Set();
+  /** @type {Record<string, any>[]} */
+  const items = [];
+  const add = (raw, fallbackId = null, fallbackLabel = null) => {
+    const app = normalizeApplication(raw, fallbackId, fallbackLabel);
+    if (!app || seen.has(app.identifier)) return;
+    if (app.type === 'module' && typeof state.canUseModule === 'function' && !state.canUseModule(app.module)) return;
+    seen.add(app.identifier);
+    const children = menuEntries(menus[app.identifier], badges);
+    const destination = children.length ? {} : mergeDestination(app.raw, state.resolveApplication);
+    const pin = pinned ? pinned.indexOf(app.identifier) : -1;
+    const group = groups[app.identifier]
+      ?? (app.type === 'fork' ? labels.forks : app.type === 'weblet' ? labels.weblets : undefined);
+    items.push({
+      id: app.identifier,
+      label: app.label,
+      // A factory, so a host renderer or the kit glyph is built per tile rather than shared.
+      icon: () => (typeof state.renderApplicationIcon === 'function' ? state.renderApplicationIcon(app.raw, app) : null)
+        ?? moduleIcon(app.module, { size: '1em', standard: Boolean(options.standardIcons) }),
+      color: app.color ?? moduleInfo(app.module).color,
+      module: app.module,
+      ...(group ? { group } : {}),
+      ...(badges[app.identifier] != null ? { badge: badges[app.identifier] } : {}),
+      ...(pinned ? { pinned: pin >= 0 ? pin : false } : {}),
+      ...(children.length ? { children } : destination)
+    });
+  };
+  for (const raw of Array.isArray(state.menuApps) ? state.menuApps : []) add(raw);
+  if (Array.isArray(state.modules)) {
+    for (const module of state.modules) {
+      if (typeof module === 'string') add([module, moduleInfo(module).label]);
+      else add(module, module?.id ?? module?.module, module?.label);
+    }
+  } else {
+    for (const [module, label] of Object.entries(state.modules ?? {})) add([module, label]);
+  }
+  return normalizeAppItems(items);
+}
+
+/**
+ * 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 function buildZeyosModuleBarConfig(state = {}, options = {}) {
+  const { standardIcons = false, appearance = 'solid', ...barOptions } = options;
+  return {
+    ...barOptions,
+    items: zeyosModuleItems(state, { standardIcons }),
+    active: state.active ?? state.activeIdentifier ?? null,
+    appearance
+  };
+}
+
+/**
+ * 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 function buildZeyosAppSidebarConfig(state = {}, options = {}) {
+  const { standardIcons = false, appearance = 'solid', moduleBar = {}, ...sidebarOptions } = options;
+  return {
+    label: 'ZeyOS',
+    ...sidebarOptions,
+    layout: 'modules',
+    items: zeyosModuleItems(state, { standardIcons }),
+    active: state.active ?? state.activeIdentifier ?? null,
+    moduleBar: { appearance, ...moduleBar }
+  };
+}
+
+/**
+ * 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 function zeyosModuleBar(target, state = {}, options = {}) {
+  return new ModuleBar(target, buildZeyosModuleBarConfig(state, options));
+}
+
+/**
+ * Normalizes a ZeyOS menu: objects and `[id, label, href]` arrays, sections, nested entries, and
+ * badges looked up by entry id. Entries without a label, and leaves without an id, are dropped.
+ * @param {unknown} entries Menu entries.
+ * @param {Record<string, string|number>} badges Badges by id.
+ * @returns {Record<string, any>[]}
+ */
+function menuEntries(entries, badges) {
+  if (!Array.isArray(entries)) return [];
+  return entries.flatMap((entry) => {
+    if (Array.isArray(entry)) {
+      const [id, label, href] = entry;
+      if (id == null || label == null) return [];
+      return [{
+        id, label: String(label),
+        ...(href != null ? { href: String(href) } : {}),
+        ...(badges[String(id)] != null ? { badge: badges[String(id)] } : {})
+      }];
+    }
+    if (!entry || typeof entry !== 'object' || entry.label == null) return [];
+    const children = menuEntries(entry.children, badges);
+    if (entry.section === true) {
+      return children.length ? [{ ...(entry.id != null ? { id: entry.id } : {}), section: true, label: String(entry.label), children }] : [];
+    }
+    if (entry.id == null) return [];
+    const picked = Object.fromEntries(['id', 'href', 'target', 'invoke', 'icon', 'value', 'disabled']
+      .filter((key) => entry[key] !== undefined).map((key) => [key, entry[key]]));
+    const badge = badges[String(entry.id)] ?? entry.badge;
+    return [{
+      ...picked,
+      label: String(entry.label),
+      ...(badge != null ? { badge } : {}),
+      ...(children.length ? { children } : {})
+    }];
+  });
+}

package/src/zeyos/query.js

@@ -20,8 +20,10 @@
  * @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.
@@ -55,6 +57,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.
@@ -72,6 +227,16 @@ export function tableSortToQuery(sort) {
   });
 }
 
+/**
+ * @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
@@ -79,12 +244,17 @@ export function tableSortToQuery(sort) {
  * 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 function dataFilterStateToFilters(state, defs = []) {
+export function dataFilterStateToFilters(state, defs = [], options = {}) {
   if (!state || typeof state !== 'object' || Array.isArray(state)) {
     throw new TypeError('DataFilter state must be an object');
   }
+  const calendarDays = Boolean(options) && typeof options === 'object'
+    && Object.prototype.hasOwnProperty.call(options, 'timeZone');
+  const zone = calendarDays ? normalizeTimeZone(options.timeZone) : undefined;
   const definitions = normalizeDefinitions(state, defs);
   const filters = {};
   let groupIndex = 0;
@@ -106,7 +276,7 @@ export function dataFilterStateToFilters(state, defs = []) {
 
     let value = typeof definition.transform === 'function'
       ? definition.transform(original, state)
-      : normalizeFilterValue(original, definition);
+      : normalizeFilterValue(original, definition, calendarDays ? { timeZone: zone } : null);
     if (value === undefined) continue;
     if (definition.operator) value = { [definition.operator]: value };
 
@@ -174,16 +344,30 @@ function normalizeDefinitions(state, defs) {
   return Object.keys(state).map((id) => ({ id, field: id }));
 }
 
-/** @param {unknown} value @param {ServerFilterDefinition} definition @returns {unknown} */
-function normalizeFilterValue(value, definition) {
+/**
+ * @param {unknown} value Filter value.
+ * @param {ServerFilterDefinition} definition Server mapping.
+ * @param {{timeZone: string|undefined}|null} calendar Zone for date-only values, or null to convert
+ * every date as an instant.
+ * @returns {unknown}
+ */
+function normalizeFilterValue(value, definition, calendar = null) {
   const semantic = String(definition.format ?? definition.type ?? '').toLowerCase();
-  if (value instanceof Date && ['date', 'datetime', 'date-time'].includes(semantic)) {
-    return dateToUnixSeconds(value);
-  }
-  if (Array.isArray(value) && ['date', 'datetime', 'date-time'].includes(semantic)) {
-    return value.map((entry) => entry instanceof Date ? dateToUnixSeconds(entry) : entry);
-  }
-  return value;
+  if (!['date', 'datetime', 'date-time'].includes(semantic)) return value;
+  /** @param {unknown} entry @returns {unknown} */
+  const convert = (entry) => {
+    if (calendar && semantic === 'date') {
+      if (entry instanceof Date) return calendarDayToUnixSeconds(entry, calendar.timeZone);
+      const day = typeof entry === 'string' ? /^(\d{4})-(\d{2})-(\d{2})$/.exec(entry.trim()) : null;
+      if (day) {
+        const midnight = calendarZone(calendar.timeZone).midnightOf(Number(day[1]), Number(day[2]) - 1, Number(day[3]));
+        return Math.floor(midnight / 1000);
+      }
+      return entry;
+    }
+    return entry instanceof Date ? dateToUnixSeconds(entry) : entry;
+  };
+  return Array.isArray(value) ? value.map(convert) : convert(value);
 }
 
 /** @param {ZxSort|ZxSort[]|undefined} sort @param {string[]|Record<string, string>|undefined} fields @returns {ZxSort|ZxSort[]|undefined} */