@zeyos/zx 4.1.1 → 4.3.0

package/src/core/overlay-host.js

@@ -0,0 +1,23 @@
+import { resolveElement } from './dom.js';
+
+const SCOPE_SELECTOR = '.zx-scope, [data-zx-theme], [data-zx-density], [data-zx-preset]';
+
+/**
+ * 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
+ * token overrides without sacrificing top-layer behaviour. The document body remains the safe
+ * fallback for unscoped applications.
+ *
+ * @param {Element|string|null} [source=null] Element or selector whose styling scope should own the overlay.
+ * @returns {Element}
+ */
+export function overlayHost(source = null) {
+  const context = source == null
+    ? (document.activeElement instanceof Element ? document.activeElement : null)
+    : resolveElement(source);
+  const scope = context?.closest?.(SCOPE_SELECTOR) ?? null;
+  if (!scope || scope === document.documentElement || scope === document.body) return document.body;
+  return scope;
+}

package/src/index.js

@@ -89,6 +89,7 @@ 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 { Aurora } from './components/aurora/aurora.js';
 export { Panel } from './components/panel/panel.js';
 export { MasterPanel } from './components/master-panel/master-panel.js';
 export {
@@ -133,7 +134,21 @@ export {
   DateRangeBox, formatRangeText, parseRangeText
 } from './components/datebox/date-range-box.js';
 export { Timebox, splitTime, joinTime } from './components/timebox/timebox.js';
+export { Calendar } from './components/calendar/calendar.js';
+export {
+  CALENDAR_VIEWS, addCalendarDays, calendarDayDifference, calendarDayKey,
+  calendarEventIntersects, calendarEventSpansDays, calendarRange, cloneCalendarEvent,
+  layoutCalendarSpans, layoutTimedCalendarEvents, normalizeCalendarEvents,
+  shiftCalendarEvent, startOfCalendarDay, startOfCalendarWeek
+} from './components/calendar/calendar-model.js';
+export {
+  RecordView, normalizeViewFields, reconcileFieldOrder, moveViewField,
+  readViewField, renderViewField, sortViewRecords, normalizeViewState, viewRecordId
+} from './components/view/record-view.js';
 export { Table, reorderTableRows } from './components/table/table.js';
+export { TableView } from './components/table-view/table-view.js';
+export { CardView } from './components/card-view/card-view.js';
+export { KanbanView } from './components/kanban-view/kanban-view.js';
 export { Grid, billingColumns, isBillingLine } from './components/grid/grid.js';
 export {
   Chart, ChartJsAdapter, chartSummaryTable, cloneChartValue, isEmptyChartData

package/src/zeyos/calendar.js

@@ -0,0 +1,115 @@
+import { Calendar, calendarDayDifference } from '../index.js';
+import { dateToUnixSeconds, unixSecondsToDate } from './query.js';
+
+/**
+ * @typedef {Object} ZeyosCalendarOptions
+ * @property {Record<string, any>[]} [appointments=[]] Current ZeyOS appointment/event occurrences.
+ * @property {Record<string, any>[]} [events] Already-normalized generic Calendar records.
+ * @property {string|number|Date|null} [date] Calendar anchor.
+ * @property {'agenda'|'day'|'week'|'month'|'year'} [view='month'] Initial view.
+ * @property {boolean} [optimistic=true] Apply move/resize proposals locally before persistence.
+ * @property {boolean} [editable=false] Enable moving and resizing.
+ * @property {number} [weekStart=1] User-preferred first weekday.
+ * @property {boolean} [workweek=false] Show five days in week view.
+ * @property {(event: CustomEvent<Record<string, any>>) => void} [oneventchange] Persistence listener.
+ */
+
+/**
+ * Maps one expanded ZeyOS appointment/event row to the product-neutral Calendar shape. Occurrence
+ * identity includes the start timestamp because recurring rows intentionally share their base ID;
+ * persistence callers keep using `event.data.ID`.
+ * @param {Record<string, any>} record ZeyOS row.
+ * @returns {Record<string, any>} Generic Calendar event.
+ */
+export function zeyosAppointmentToEvent(record) {
+  if (!record || typeof record !== 'object' || Array.isArray(record)) {
+    throw new TypeError('ZeyOS appointment must be an object');
+  }
+  const baseId = record.ID ?? record.id;
+  if (baseId == null || baseId === '') throw new TypeError('ZeyOS appointment requires ID');
+  const start = unixSecondsToDate(record.datefrom);
+  const end = unixSecondsToDate(record.dateto ?? record.datefrom);
+  if (!(start instanceof Date) || !(end instanceof Date)) throw new TypeError('ZeyOS appointment requires datefrom and dateto');
+  const association = String(record.assoc_name ?? '').trim();
+  const name = String(record.name ?? '').trim() || 'Untitled appointment';
+  const title = record.entity && association ? `${association}: ${name}` : name;
+  const allDay = record.allDay != null ? Boolean(record.allDay)
+    : isMidnight(start) && isMidnight(end) && calendarDayDifference(start, end) >= 1;
+  return {
+    id: String(record.occurrenceid ?? `${baseId}@${record.datefrom}`),
+    title,
+    start,
+    end,
+    allDay,
+    color: zeyosCalendarColor(record.color),
+    location: String(record.location ?? '').trim(),
+    editable: record.editable == null ? null : Boolean(record.editable),
+    durationEditable: record.durationEditable == null ? null : Boolean(record.durationEditable),
+    data: record
+  };
+}
+
+/** @param {Record<string, any>[]} records @returns {Record<string, any>[]} */
+export function zeyosAppointmentsToEvents(records) {
+  if (!Array.isArray(records)) throw new TypeError('ZeyOS appointments must be an array');
+  return records.map(zeyosAppointmentToEvent);
+}
+
+/**
+ * Converts a proposed Calendar occurrence back to the current ZeyOS appointment update fields.
+ * The base appointment identifier remains the source record's `ID`; date values become Unix
+ * seconds and the adapter never adds recurrence or DAV fields.
+ * @param {{start: Date, end: Date, data?: Record<string, any>}} event Calendar event proposal.
+ * @returns {{ID?: unknown, datefrom: number|null, dateto: number|null}}
+ */
+export function calendarEventToZeyosPatch(event) {
+  if (!event || !(event.start instanceof Date) || !(event.end instanceof Date)) {
+    throw new TypeError('Calendar event patch requires start and end Dates');
+  }
+  const patch = {
+    datefrom: dateToUnixSeconds(event.start),
+    dateto: dateToUnixSeconds(event.end)
+  };
+  if (event.data?.ID != null) return { ID: event.data.ID, ...patch };
+  return patch;
+}
+
+/**
+ * Builds Calendar options while preserving every explicit generic option. `appointments` is
+ * mapped only when present; callers may instead pass already-normalized `events`.
+ * @param {ZeyosCalendarOptions & Record<string, any>} [options={}] ZeyOS and Calendar options.
+ * @returns {Record<string, any>} Plain Calendar options.
+ */
+export function buildZeyosCalendarOptions(options = {}) {
+  const { appointments, ...calendarOptions } = options;
+  return {
+    weekStart: 1,
+    optimistic: true,
+    ...calendarOptions,
+    events: appointments == null
+      ? (Array.isArray(calendarOptions.events) ? calendarOptions.events : [])
+      : zeyosAppointmentsToEvents(appointments)
+  };
+}
+
+/**
+ * Creates a Calendar that accepts current ZeyOS appointment/event occurrences directly.
+ * @param {Element|string|null} target Existing target or null.
+ * @param {ZeyosCalendarOptions & Record<string, any>} [options={}] Adapter and Calendar options.
+ * @returns {Calendar}
+ */
+export function zeyosCalendar(target, options = {}) {
+  return new Calendar(target, buildZeyosCalendarOptions(options));
+}
+
+/** @param {unknown} value @returns {string|null} */
+function zeyosCalendarColor(value) {
+  const color = String(value ?? '').trim();
+  if (!color) return null;
+  return /^[\da-f]{3,8}$/i.test(color) ? `#${color}` : color;
+}
+
+/** @param {Date} date @returns {boolean} */
+function isMidnight(date) {
+  return date.getHours() === 0 && date.getMinutes() === 0 && date.getSeconds() === 0 && date.getMilliseconds() === 0;
+}

package/src/zeyos/icons.js

@@ -59,6 +59,9 @@ export function moduleIcon(name, options = {}) {
  * @property {boolean} [standard=false] Use the stock Font Awesome fallback glyph.
  * @property {string|Node|(()=>string|Node)|null} [icon] Explicit glyph override, useful for an offline fallback.
  * @property {string} [color] Override the module colour for a server-defined fork or weblet.
+ * @property {string|number|null} [badge=null] Optional corner badge.
+ * @property {boolean} [selected=false] Whether the application identity is selected.
+ * @property {'tile'|'circle'} [shape='tile'] AppIcon vessel geometry.
  * @property {false|'subtle'|'strong'} [glass='subtle'] AppIcon material treatment.
  * @property {string|string[]} [class] Extra class names.
  */
@@ -66,7 +69,7 @@ export function moduleIcon(name, options = {}) {
 /**
  * Creates a module's icon chip: the glyph on the module's identity colour, the way ZeyOS draws
  * module icons in navigation and record headers. AppIcon identity glyphs stay white across every
- * module colour; material shading and the glyph shadow preserve their silhouette on light colours.
+ * module colour; material shading preserves their silhouette on light colours.
  * @param {string} name Module, entity, or resource name.
  * @param {ModuleChipOptions} [options={}] Display and accessibility options.
  * @returns {HTMLElement} A `<span class="zx-module-icon">` wrapping the glyph.
@@ -74,7 +77,7 @@ export function moduleIcon(name, options = {}) {
 export function moduleChip(name, options = {}) {
   const {
     size = 24, iconSize = '52%', label = null, title = false, standard = false,
-    color = null
+    color = null, badge = null, selected = false
   } = options;
   const key = normalizeModuleName(name);
   const info = moduleInfo(name);
@@ -88,6 +91,9 @@ export function moduleChip(name, options = {}) {
     iconSize,
     color: background,
     label,
+    badge,
+    selected,
+    shape: options.shape ?? 'tile',
     glass: options.glass ?? 'subtle',
     class: ['zx-module-icon', options.class].flat().filter(Boolean)
   });
@@ -100,11 +106,12 @@ export function moduleChip(name, options = {}) {
 }
 
 /**
- * Creates the public ZeyOS AppIcon preset for any module, entity, fork, or weblet identity.
+ * Creates the public ZeyOS application-identity preset for any module, fork, or weblet. It uses
+ * the circular application vessel by default; use `moduleChip()` for compact entity/record tiles.
  * @param {string} name Module/entity identifier.
  * @param {ModuleChipOptions} [options={}] AppIcon options.
  * @returns {HTMLElement}
  */
 export function zeyosAppIcon(name, options = {}) {
-  return moduleChip(name, options);
+  return moduleChip(name, { shape: 'circle', ...options });
 }

package/src/zeyos/index.js

@@ -25,3 +25,16 @@ export {
 } from './select.js';
 export { zeyosForm } from './form.js';
 export { zeyosTable } from './table.js';
+export {
+  buildZeyosCalendarOptions, calendarEventToZeyosPatch, zeyosAppointmentToEvent,
+  zeyosAppointmentsToEvents, zeyosCalendar
+} from './calendar.js';
+export { buildZeyosViewConfig, zeyosView } from './view.js';
+export {
+  SAVED_VIEWS_VERSION, SavedViewDuplicateNameError, SavedViewRegistry,
+  SavedViewScopeMismatchError, createSavedViewRegistry, migrateSavedViewDocument,
+  normalizeSavedViewDocument, normalizeSavedViewScope
+} from './saved-views.js';
+export {
+  createLegacySavedViewTransport, legacySavedViewRequest
+} from './legacy-saved-views.js';

package/src/zeyos/launcher.js

@@ -1,5 +1,5 @@
 import { Launcher } from '../components/launcher/launcher.js';
-import { moduleChip } from './icons.js';
+import { moduleChip, zeyosAppIcon } from './icons.js';
 import { moduleInfo } from './modules.js';
 
 /** Static application identifiers present in the current ZeyOS shell prototype. */
@@ -139,7 +139,7 @@ export function normalizeZeyosLauncherApplications(state = {}, options = {}) {
         ? options.renderApplicationIcon(app.raw, app)
         : app.type === 'weblet' && typeof options.renderWebletIcon === 'function'
           ? options.renderWebletIcon(app.raw, app) : null;
-      return custom ?? moduleChip(app.module, {
+      return custom ?? zeyosAppIcon(app.module, {
         size: 36,
         standard: Boolean(options.standardIcons),
         color: app.color

package/src/zeyos/legacy-saved-views.js

@@ -0,0 +1,155 @@
+/**
+ * @typedef {Object} SavedViewScope
+ * @property {string|number} userId Client identity used by the controller; never sent to the legacy endpoint.
+ * @property {string|number|null} workspaceId ZeyOS fork/workspace id.
+ * @property {string} resource ZeyOS resource whose record views are being saved.
+ */
+
+/**
+ * @typedef {Object} LegacySavedViewTransportOptions
+ * @property {string} [recordName='__zx_record_views_v1__'] Reserved `userfields.name` value.
+ * @property {string} [viewPrefix='zx.record-views:'] Namespace prepended to `userfields.view`.
+ * @property {string} [module=''] Legacy UMI/module value.
+ */
+
+/**
+ * Converts the callback form of `PG.load` into the promise request consumed by
+ * `createLegacySavedViewTransport`. Pass a bound method (`PG.load.bind(PG)`) so legacy receivers
+ * that depend on `this` remain intact.
+ * @param {(params:Record<string,unknown>,onLoad:(data:unknown)=>void,onCatch:(message:unknown,type?:unknown,info?:unknown)=>boolean)=>unknown} load Legacy loader.
+ * @returns {(params:Record<string,unknown>)=>Promise<unknown>}
+ */
+export function legacySavedViewRequest(load) {
+  if (typeof load !== 'function') throw new TypeError('Legacy saved-view loader must be a function');
+  return (params) => new Promise((resolve, reject) => {
+    load(params, resolve, (message, type, info) => {
+      const error = new Error(String(message ?? 'ZeyOS saved-view request failed'));
+      Object.assign(error, { type, info });
+      reject(error);
+      return true;
+    });
+  });
+}
+
+/**
+ * Adapts ZeyOS's existing `fields`, `fields_save`, and `fields_remove` endpoints to the atomic
+ * document transport used by saved record views. The endpoint derives the user from the
+ * authenticated session; accepting `userId` in the scope prevents accidental controller reuse but
+ * deliberately does not turn a client-supplied identity into an authorization input.
+ *
+ * `request` is injected because Zx supports both the legacy `PG.load` bridge and modern hosts. It
+ * receives the familiar plain endpoint parameters and returns a promise for the decoded response.
+ *
+ * @param {(params:Record<string,unknown>)=>Promise<unknown>} request Promise-based legacy request bridge.
+ * @param {LegacySavedViewTransportOptions} [options={}] Endpoint namespace options.
+ * @returns {{load:(scope:SavedViewScope)=>Promise<Record<string,unknown>|null>,save:(scope:SavedViewScope,document:Record<string,unknown>)=>Promise<Record<string,unknown>>,remove:(scope:SavedViewScope)=>Promise<void>}}
+ */
+export function createLegacySavedViewTransport(request, options = {}) {
+  if (typeof request !== 'function') throw new TypeError('Saved-view request must be a function');
+  const recordName = normalizeNonEmpty(options.recordName, '__zx_record_views_v1__', 'recordName');
+  const viewPrefix = normalizeNonEmpty(options.viewPrefix, 'zx.record-views:', 'viewPrefix');
+  const module = options.module == null ? '' : String(options.module);
+
+  const paramsFor = (scope, page) => {
+    const normalized = normalizeScope(scope);
+    return {
+      umi: module,
+      page,
+      fork: normalized.workspaceId,
+      view: `${viewPrefix}${normalized.resource}`
+    };
+  };
+
+  return {
+    async load(scope) {
+      const response = await request(paramsFor(scope, 'fields'));
+      const value = findReservedDocument(response, recordName);
+      if (value == null || value === '') return null;
+      if (typeof value === 'string') {
+        try {
+          const parsed = JSON.parse(value);
+          return isRecord(parsed) ? parsed : null;
+        } catch {
+          return null;
+        }
+      }
+      return isRecord(value) ? cloneJson(value) : null;
+    },
+
+    async save(scope, document) {
+      if (!isRecord(document)) throw new TypeError('Saved-view document must be an object');
+      const copy = cloneJson(document);
+      await request({
+        ...paramsFor(scope, 'fields_save'),
+        name: recordName,
+        data: JSON.stringify(copy)
+      });
+      return copy;
+    },
+
+    async remove(scope) {
+      await request({
+        ...paramsFor(scope, 'fields_remove'),
+        name: recordName
+      });
+    }
+  };
+}
+
+/** @param {unknown} scope @returns {{userId:string,workspaceId:string|number|null,resource:string}} */
+function normalizeScope(scope) {
+  if (!isRecord(scope)) throw new TypeError('Saved-view scope must be an object');
+  if (scope.userId == null || String(scope.userId).trim() === '') {
+    throw new TypeError('Saved-view scope requires userId');
+  }
+  const resource = String(scope.resource ?? '').trim();
+  if (!resource) throw new TypeError('Saved-view scope requires resource');
+  const workspaceId = scope.workspaceId == null || scope.workspaceId === '' ? null : scope.workspaceId;
+  return { userId: String(scope.userId), workspaceId, resource };
+}
+
+/** @param {unknown} response @param {string} recordName @returns {unknown} */
+function findReservedDocument(response, recordName) {
+  if (!Array.isArray(response) || !Array.isArray(response[0]) || !Array.isArray(response[1])) {
+    return null;
+  }
+  const index = response[0].findIndex((name) => String(name) === recordName);
+  return index < 0 ? null : response[1][index];
+}
+
+/** @param {unknown} value @param {string} fallback @param {string} label @returns {string} */
+function normalizeNonEmpty(value, fallback, label) {
+  const normalized = value == null ? fallback : String(value).trim();
+  if (!normalized) throw new TypeError(`${label} must not be empty`);
+  return normalized;
+}
+
+/** @param {unknown} value @returns {value is Record<string,unknown>} */
+function isRecord(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** @param {Record<string,unknown>} value @returns {Record<string,unknown>} */
+function cloneJson(value) {
+  assertJsonValue(value, new Set());
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    throw new TypeError('Saved-view document must be JSON-serializable');
+  }
+}
+
+/** @param {unknown} value @param {Set<object>} ancestors @returns {void} */
+function assertJsonValue(value, ancestors) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return;
+  if (typeof value === 'number' && Number.isFinite(value)) return;
+  if (typeof value !== 'object') throw new TypeError('Saved-view document must be JSON-serializable');
+  if (ancestors.has(value)) throw new TypeError('Saved-view document must be JSON-serializable');
+  if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    throw new TypeError('Saved-view document must be JSON-serializable');
+  }
+  ancestors.add(value);
+  const entries = Array.isArray(value) ? value : Object.values(value);
+  for (const entry of entries) assertJsonValue(entry, ancestors);
+  ancestors.delete(value);
+}