@zeyos/zx 4.1.0 → 4.2.0

package/src/zeyos/table.js

@@ -196,7 +196,9 @@ export function zeyosTable(client, resource, opts = {}) {
   };
 
   table.on('sort', (event) => {
-    currentSort = { id: String(event.detail.id), dir: event.detail.dir === 'desc' ? 'desc' : 'asc' };
+    const id = event.detail?.id;
+    currentSort = id == null ? null
+      : { id: String(id), dir: event.detail.dir === 'desc' ? 'desc' : 'asc' };
     void load({ page: 0 }).catch(() => { /* The connection facade already reported the failure. */ });
   });
   return binding;

package/src/zeyos/view.js

@@ -0,0 +1,543 @@
+import { buildListQuery } from './query.js';
+import { connect } from './connect.js';
+import { normalizeZeyosListResult } from './select.js';
+import { createSavedViewRegistry } from './saved-views.js';
+import { buildZeyosTableConfig } from './table.js';
+
+/** @typedef {import('../components/view/record-view.js').ViewField} ViewField */
+/** @typedef {import('../components/view/record-view.js').ViewSort} ViewSort */
+/** @typedef {import('./saved-views.js').SavedViewEntry} SavedViewEntry */
+/** @typedef {import('./saved-views.js').SavedViewApplyResult} SavedViewApplyResult */
+
+/**
+ * @typedef {Object} ZeyosSavedViewsOptions
+ * @property {Record<string,any>} [controller] Existing saved-view registry. It remains caller-owned.
+ * @property {Record<string,any>} [registry] Alias for `controller`.
+ * @property {Record<string,any>} [transport] Injected persistence transport used to construct a registry.
+ * @property {{userId:string|number,workspaceId:string|number|null,resource?:string}} [scope]
+ * Saved-view isolation scope; null workspace identifies ZeyOS's base workspace.
+ * resource defaults to the bound ZeyOS resource.
+ * @property {Record<string,unknown>} [options] Options passed to `createSavedViewRegistry`.
+ * @property {'table'|'card'|'kanban'} [type] Presentation identity; normally derived from the View.
+ */
+
+/**
+ * @typedef {Object} ZeyosViewOptions
+ * @property {string[]} [fields] Curated ordered schema field allow-list.
+ * @property {string[]} [exclude] Schema fields to omit.
+ * @property {Record<string, string>} [labels] Per-field label overrides.
+ * @property {Record<string, Partial<ViewField>>} [fieldOverrides] View descriptor overrides.
+ * @property {string|((record:Record<string,unknown>)=>unknown)} [recordId='ID'] Record id accessor.
+ * @property {number} [pageSize=50] Server page size.
+ * @property {ViewSort|null} [sort=null] Initial server sort.
+ * @property {Record<string, unknown>} [filters] Initial ZeyOS predicates.
+ * @property {string} [search=''] Initial full-text query.
+ * @property {string[]} [searchFields] Server full-text fields where supported.
+ * @property {Record<string, unknown>} [viewOptions] Options passed to the concrete view.
+ * @property {Element|string|null} [target=null] Concrete view target.
+ * @property {string} [titleField] Card title field included in the projection.
+ * @property {string} [subtitleField] Card subtitle field included in the projection.
+ * @property {string|Function} [preview] Preview field or resolver.
+ * @property {string|Function} [groupBy] Card grouping field or resolver.
+ * @property {string|Function} [columnBy] Kanban column field or resolver.
+ * @property {string|Function} [swimlaneBy] Kanban swim-lane field or resolver.
+ * @property {false|Record<string,any>|ZeyosSavedViewsOptions|null} [savedViews] Existing registry or
+ * injected transport/scope configuration for named saved views.
+ * @property {(record:Record<string,unknown>,event:CustomEvent<Record<string,unknown>>)=>void} [onRecordClick]
+ */
+
+/**
+ * @typedef {Object} ZeyosViewConfig
+ * @property {Record<string, any>[]} fieldMeta Ordered normalized schema metadata.
+ * @property {ViewField[]} fields Common view fields.
+ * @property {Record<string, string>} projection Complete server projection.
+ * @property {Record<string, any>} viewOptions Concrete view options.
+ */
+
+/**
+ * @typedef {Object} ZeyosViewLoadOptions
+ * @property {string} [search] Replacement full-text query.
+ * @property {Record<string, unknown>} [filters] Replacement predicates.
+ * @property {number} [page=0] Zero-based page; pages above zero append.
+ */
+
+/**
+ * @typedef {Object} ZeyosViewLoadResult
+ * @property {Record<string, unknown>[]} data Loaded records.
+ * @property {number|null} count Server count when supplied.
+ * @property {number} page Loaded page.
+ * @property {boolean} hasMore Whether another page is available.
+ * @property {Record<string, unknown>} query Request sent to the list operation.
+ */
+
+/**
+ * @typedef {Object} ZeyosSavedViewCapture
+ * @property {string} [id] Existing saved-view id.
+ * @property {string} name Saved-view name.
+ * @property {'table'|'card'|'kanban'} type Concrete presentation.
+ * @property {Record<string,unknown>} state JSON-safe component view state.
+ * @property {Record<string,unknown>} filters Current server filters.
+ * @property {string} search Current full-text query.
+ */
+
+/**
+ * @typedef {Object} ZeyosSaveViewOptions
+ * @property {string} [id] Existing saved-view id to replace.
+ * @property {string} name Saved-view name.
+ * @property {'reject'|'replace'} [onDuplicate] Duplicate-name behavior.
+ * @property {boolean} [setDefault=false] Make the saved entry the default.
+ */
+
+/**
+ * @typedef {Object} ZeyosApplyViewOptions
+ * @property {boolean} [load=true] Reload the first server page after an applied view.
+ */
+
+/**
+ * @typedef {Object} ZeyosViewBinding
+ * @property {Record<string, any>} view Generated RecordView-compatible instance.
+ * @property {(options?:ZeyosViewLoadOptions)=>Promise<ZeyosViewLoadResult>} load Loads a page.
+ * @property {(search:string)=>Promise<ZeyosViewLoadResult>} setSearch Replaces search and reloads.
+ * @property {(filters:Record<string,unknown>)=>Promise<ZeyosViewLoadResult>} setFilters Replaces filters and reloads.
+ * @property {()=>Promise<ZeyosViewLoadResult>} loadMore Loads the next page when available.
+ * @property {number|null} count Current server count.
+ * @property {number} page Current zero-based page.
+ * @property {boolean} hasMore Whether another page is available.
+ * @property {Record<string,any>|null} savedViews Saved-view registry when configured.
+ * @property {Promise<SavedViewApplyResult|null>} ready Default restoration completed before loads.
+ * @property {(options?:ZeyosApplyViewOptions)=>Promise<SavedViewApplyResult|null>} restoreDefault Restores the current default.
+ * @property {(details:{id?:string,name:string})=>ZeyosSavedViewCapture} captureView Captures current query/view state without persistence.
+ * @property {(details:ZeyosSaveViewOptions)=>Promise<SavedViewEntry>} saveView Captures and persists the current view.
+ * @property {(idOrName:string,options?:ZeyosApplyViewOptions)=>Promise<SavedViewApplyResult>} applyView Applies a compatible named view.
+ * @property {()=>void} destroy Destroys the generated view.
+ */
+
+/** View-specific top-level conveniences copied into the concrete component options. */
+const VIEW_KEYS = [
+  'titleField', 'subtitleField', 'preview', 'previewAlt', 'link', 'actions', 'groupBy', 'groupOrder',
+  'columnBy', 'columns', 'swimlaneBy', 'swimlanes', 'moveMode', 'columnOrder', 'swimlaneOrder',
+  'collapsedColumns', 'collapsedSwimlanes', 'showCounts', 'showEmptyColumns', 'hiddenFields',
+  'fieldOrder', 'fieldControls', 'selectable', 'selection', 'emptyText'
+];
+
+/**
+ * Produces common view fields and a complete ZeyOS projection without touching the DOM. It reuses
+ * the established table schema conversion so entity labels, enums, amounts, currencies, and Unix
+ * dates render identically in TableView, CardView, and KanbanView.
+ * @param {Record<string, any>} client Injected ZeyOS client.
+ * @param {string} resource Schema resource.
+ * @param {ZeyosViewOptions} [opts={}] Schema and view options.
+ * @returns {ZeyosViewConfig} DOM-free configuration.
+ */
+export function buildZeyosViewConfig(client, resource, opts = {}) {
+  const requested = requestedViewFields(client, resource, opts);
+  const table = buildZeyosTableConfig(client, resource, {
+    fields: requested,
+    labels: opts.labels,
+    rowId: opts.recordId ?? 'ID',
+    sort: opts.sort ?? null
+  });
+  const overrides = opts.fieldOverrides && typeof opts.fieldOverrides === 'object'
+    ? opts.fieldOverrides : {};
+  const explicitlyVisible = Array.isArray(opts.fields) ? new Set(opts.fields.map(String)) : null;
+  const fields = table.columns.map((column) => ({
+    ...column,
+    ...(explicitlyVisible && !explicitlyVisible.has(column.id) ? { visible: false } : {}),
+    ...(overrides[column.id] ?? {}),
+    id: column.id
+  }));
+  const projection = { ...table.projection };
+
+  // A view resolver may name a schema field outside the visible field allow-list. The server still
+  // has to return it for grouping/media. Direct projections are safe even for compatible client
+  // schemas whose field metadata omitted a virtual field.
+  for (const id of supplementalFieldIds(opts)) {
+    if (!Object.prototype.hasOwnProperty.call(projection, id)) projection[id] = id;
+  }
+  const viewOptions = { ...(opts.viewOptions ?? {}) };
+  for (const key of VIEW_KEYS) {
+    if (Object.prototype.hasOwnProperty.call(opts, key)) viewOptions[key] = opts[key];
+  }
+  Object.assign(viewOptions, {
+    fields,
+    data: [],
+    recordId: opts.recordId ?? 'ID',
+    sort: opts.sort ?? null,
+    sortMode: 'server'
+  });
+  if (typeof opts.onRecordClick === 'function') {
+    viewOptions.onrecordclick = (event) => opts.onRecordClick(event.detail.record, event);
+  }
+  return { fieldMeta: table.fieldMeta, fields, projection, viewOptions };
+}
+
+/**
+ * Creates and binds any RecordView-compatible constructor to server paging. The caller supplies the
+ * constructor, so this adapter has no dependency on one concrete presentation and remains simple
+ * to unit test or wrap from a framework.
+ * @param {Record<string, any>} client Injected ZeyOS client.
+ * @param {string} resource Schema resource.
+ * @param {new(target:Element|string|null,options:Record<string,unknown>)=>Record<string,any>} View Concrete view class.
+ * @param {ZeyosViewOptions} [opts={}] Binding options.
+ * @returns {ZeyosViewBinding} View and server-state methods.
+ */
+export function zeyosView(client, resource, View, opts = {}) {
+  if (typeof View !== 'function') throw new TypeError('zeyosView() requires a view constructor');
+  const config = buildZeyosViewConfig(client, resource, opts);
+  const view = new View(opts.target ?? null, config.viewOptions);
+  for (const method of ['setData', 'addData', 'setLoading', 'on', 'destroy']) {
+    if (typeof view?.[method] !== 'function') {
+      try { view?.destroy?.(); } catch { /* Preserve the contract error. */ }
+      throw new TypeError(`zeyosView() constructor must provide ${method}()`);
+    }
+  }
+  const facade = connect(client);
+  const pageSize = normalizePageSize(opts.pageSize);
+  let saved;
+  try {
+    saved = resolveSavedViews(opts.savedViews, View, resource);
+  } catch (error) {
+    view.destroy();
+    throw error;
+  }
+  const savedViews = saved?.registry ?? null;
+  const presentation = saved?.type ?? presentationType(View);
+  if (savedViews) {
+    for (const method of ['getViewState', 'setViewState']) {
+      if (typeof view?.[method] !== 'function') {
+        if (saved?.owned) savedViews.destroy?.();
+        view.destroy();
+        throw new TypeError(`zeyosView() saved views require ${method}()`);
+      }
+    }
+  }
+  let currentSort = opts.sort ?? null;
+  let currentFilters = copyFilters(opts.filters ?? {});
+  let currentSearch = String(opts.search ?? '');
+  let currentPage = 0;
+  let totalCount = null;
+  let more = false;
+  let requestSequence = 0;
+  let destroyed = false;
+
+  const performLoad = async (options = {}) => {
+    if (destroyed) throw new Error('ZeyOS view binding has been destroyed');
+    if (Object.prototype.hasOwnProperty.call(options, 'search')) currentSearch = String(options.search ?? '');
+    if (Object.prototype.hasOwnProperty.call(options, 'filters')) currentFilters = copyFilters(options.filters ?? {});
+    const page = normalizePage(options.page ?? 0);
+    const query = buildListQuery({
+      fields: config.projection,
+      sort: currentSort,
+      filters: currentFilters,
+      search: currentSearch,
+      searchFields: opts.searchFields,
+      limit: pageSize,
+      offset: page * pageSize,
+      count: true
+    });
+    const sequence = ++requestSequence;
+    view.setLoading(true);
+    try {
+      const normalized = normalizeZeyosListResult(client, await facade.list(resource, query));
+      const count = normalized.count ?? null;
+      const hasMore = count == null
+        ? normalized.data.length === pageSize
+        : page * pageSize + normalized.data.length < count;
+      if (!destroyed && sequence === requestSequence) {
+        currentPage = page;
+        totalCount = count;
+        more = hasMore;
+        if (page === 0) view.setData(normalized.data);
+        else view.addData(normalized.data);
+      }
+      return { data: normalized.data, count, page, hasMore, query };
+    } finally {
+      if (!destroyed && sequence === requestSequence) view.setLoading(false);
+    }
+  };
+
+  /** @param {string} idOrName @param {{load?:boolean}} [options={}] @returns {Promise<SavedViewApplyResult>} */
+  const applySaved = async (idOrName, options = {}) => {
+    if (!savedViews || !presentation) throw new Error('This ZeyOS view binding has no saved-view registry');
+    if (destroyed) throw new Error('ZeyOS view binding has been destroyed');
+    const result = await savedViews.apply(idOrName, view, {
+      type: presentation,
+      onQuery: async ({ filters, search }) => {
+        if (destroyed) return;
+        currentFilters = copyFilters(filters ?? {});
+        currentSearch = String(search ?? '');
+      }
+    });
+    if (!result.applied || destroyed) return result;
+    currentSort = appliedViewSort(view, result.entry);
+    currentPage = 0;
+    totalCount = null;
+    more = false;
+    if (options.load !== false) await performLoad({ page: 0 });
+    return result;
+  };
+
+  /** @param {{load?:boolean}} [options={}] @returns {Promise<SavedViewApplyResult|null>} */
+  const restoreDefaultInternal = async (options = {}) => {
+    if (!savedViews) return null;
+    await readySavedViews(savedViews);
+    if (destroyed) throw new Error('ZeyOS view binding has been destroyed');
+    const entry = await savedViews.getDefault();
+    if (!entry) return /** @type {SavedViewApplyResult} */ ({
+      status: 'missing', applied: false, entry: null
+    });
+    return applySaved(entry.id, options);
+  };
+
+  /** Default application starts immediately and every server load below awaits it. */
+  const ready = savedViews ? restoreDefaultInternal({ load: false }) : Promise.resolve(null);
+  let initialized = !savedViews;
+  let retryingInitialization = null;
+  // The promise remains rejectable to callers/load(), while this observer prevents an ignored
+  // optional saved-view configuration from becoming a process-level unhandled rejection.
+  void ready.then(() => { initialized = true; }, () => {});
+
+  /**
+   * Later operations retry a failed initial registry/default restoration instead of remaining
+   * poisoned by the intentionally observable first `ready` rejection.
+   * @param {{load?:boolean}} [options={load:false}] Retry apply behavior.
+   * @returns {Promise<SavedViewApplyResult|null>}
+   */
+  const ensureInitialized = async (options = { load: false }) => {
+    if (initialized) return null;
+    try {
+      const result = await ready;
+      initialized = true;
+      return result;
+    } catch {
+      // The first failure remains available through binding.ready; this operation gets a retry.
+    }
+    if (!retryingInitialization) {
+      const retry = restoreDefaultInternal(options).then((result) => {
+        initialized = true;
+        return result;
+      });
+      const pending = retry.finally(() => {
+        if (retryingInitialization === pending) retryingInitialization = null;
+      });
+      retryingInitialization = pending;
+    }
+    return retryingInitialization;
+  };
+
+  const load = async (options = {}) => {
+    await ensureInitialized({ load: false });
+    return performLoad(options);
+  };
+
+  const captureView = (details) => {
+    if (!presentation || typeof view.getViewState !== 'function') {
+      throw new Error('This view does not expose serializable saved-view state');
+    }
+    const source = details && typeof details === 'object' ? details : {};
+    return {
+      ...(source.id == null ? {} : { id: String(source.id) }),
+      name: String(source.name ?? ''),
+      type: presentation,
+      state: view.getViewState(),
+      filters: copyFilters(currentFilters),
+      search: currentSearch
+    };
+  };
+
+  const saveView = async (details) => {
+    if (!savedViews || !presentation) throw new Error('This ZeyOS view binding has no saved-view registry');
+    await ensureInitialized({ load: false });
+    if (destroyed) throw new Error('ZeyOS view binding has been destroyed');
+    const capture = captureView(details);
+    const entry = await savedViews.capture(view, {
+      ...(capture.id == null ? {} : { id: capture.id }),
+      name: capture.name,
+      type: presentation,
+      filters: capture.filters,
+      search: capture.search
+    }, { onDuplicate: details?.onDuplicate, setDefault: Boolean(details?.setDefault) });
+    return entry;
+  };
+
+  const applyView = async (idOrName, options = {}) => {
+    await ensureInitialized({ load: false });
+    return applySaved(idOrName, options);
+  };
+
+  const restoreDefault = async (options = {}) => {
+    if (!initialized) return ensureInitialized(options);
+    return restoreDefaultInternal(options);
+  };
+
+  const sortHandler = (event) => {
+    const id = event.detail?.id;
+    currentSort = id == null ? null : { id: String(id), dir: event.detail.dir === 'desc' ? 'desc' : 'asc' };
+    void load({ page: 0 }).catch(() => { /* connect() already reported the API failure. */ });
+  };
+
+  const binding = {
+    view,
+    load,
+    setSearch: (search) => load({ search, page: 0 }),
+    setFilters: (filters) => load({ filters, page: 0 }),
+    loadMore: async () => {
+      await ensureInitialized({ load: false });
+      return more ? performLoad({ page: currentPage + 1 }) : {
+        data: [],
+        count: totalCount,
+        page: currentPage,
+        hasMore: false,
+        query: buildListQuery({
+          fields: config.projection,
+          sort: currentSort,
+          filters: currentFilters,
+          search: currentSearch,
+          searchFields: opts.searchFields,
+          limit: pageSize,
+          offset: currentPage * pageSize,
+          count: true
+        })
+      };
+    },
+    get count() { return totalCount; },
+    get page() { return currentPage; },
+    get hasMore() { return more; },
+    savedViews,
+    ready,
+    restoreDefault,
+    captureView,
+    saveView,
+    applyView,
+    destroy: () => {
+      if (destroyed) return;
+      destroyed = true;
+      requestSequence += 1;
+      if (typeof view.off === 'function') view.off('sortchange', sortHandler);
+      else view.removeEventListener?.('sortchange', sortHandler);
+      if (saved?.owned) savedViews?.destroy?.();
+      view.destroy();
+    }
+  };
+  view.on('sortchange', sortHandler);
+  return binding;
+}
+
+/** @param {Record<string,any>} client @param {string} resource @param {ZeyosViewOptions} opts @returns {string[]|undefined} */
+function requestedViewFields(client, resource, opts) {
+  if (!Array.isArray(opts.fields) && !Array.isArray(opts.exclude)) return undefined;
+  const excluded = new Set(Array.isArray(opts.exclude) ? opts.exclude.map(String) : []);
+  const listed = Array.isArray(opts.fields) ? opts.fields.map(String) : schemaFieldIds(client, resource);
+  return [...new Set([...listed, ...supplementalFieldIds(opts)])]
+    .filter((id) => !excluded.has(id));
+}
+
+/** @param {Record<string,any>} client @param {string} resource @returns {string[]} */
+function schemaFieldIds(client, resource) {
+  const collection = client?.schema?.fields?.(resource);
+  if (Array.isArray(collection)) return collection.map((entry) => typeof entry === 'string'
+    ? entry : String(entry?.id ?? entry?.name ?? entry?.field ?? '')).filter(Boolean);
+  return collection && typeof collection === 'object' ? Object.keys(collection) : [];
+}
+
+/** @param {ZeyosViewOptions} opts @returns {string[]} */
+function supplementalFieldIds(opts) {
+  const ids = [];
+  for (const key of ['titleField', 'subtitleField', 'preview', 'groupBy', 'columnBy', 'swimlaneBy']) {
+    const value = opts[key];
+    if (typeof value === 'string' && value.trim()) ids.push(value.trim());
+  }
+  return [...new Set(ids)];
+}
+
+/** @param {unknown} value @returns {number} */
+function normalizePageSize(value) {
+  const number = Number(value ?? 50);
+  return Number.isFinite(number) ? Math.max(1, Math.floor(number)) : 50;
+}
+
+/** @param {unknown} value @returns {number} */
+function normalizePage(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? Math.max(0, Math.floor(number)) : 0;
+}
+
+/** @param {unknown} value @returns {Record<string, unknown>} */
+function copyFilters(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? { ...value } : {};
+}
+
+/**
+ * Resolves a supplied registry or constructs one from an injected transport and scope.
+ * @param {ZeyosViewOptions['savedViews']} value Saved-view option.
+ * @param {Function & {cssName?:string}} View Concrete view constructor.
+ * @param {string} resource ZeyOS resource.
+ * @returns {{registry:Record<string,any>,type:'table'|'card'|'kanban',owned:boolean}|null}
+ */
+function resolveSavedViews(value, View, resource) {
+  if (value == null || value === false) return null;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError('savedViews must be a registry or transport/scope configuration');
+  }
+  const source = /** @type {Record<string,any>} */ (value);
+  const configured = source.controller ?? source.registry;
+  const direct = isSavedViewRegistry(source) ? source : isSavedViewRegistry(configured) ? configured : null;
+  const type = normalizePresentationType(source.type ?? presentationType(View));
+  if (!type) throw new TypeError('savedViews requires a table, card, or kanban presentation type');
+  if (direct) return { registry: direct, type, owned: false };
+  if (!source.transport || !source.scope || typeof source.scope !== 'object') {
+    throw new TypeError('savedViews requires a controller or injected transport and scope');
+  }
+  const scope = { ...source.scope, resource: source.scope.resource ?? resource };
+  return {
+    registry: createSavedViewRegistry(source.transport, scope, source.options ?? {}),
+    type,
+    owned: true
+  };
+}
+
+/** @param {unknown} value @returns {boolean} */
+function isSavedViewRegistry(value) {
+  return Boolean(value && typeof value === 'object'
+    && typeof /** @type {Record<string,any>} */ (value).apply === 'function'
+    && typeof /** @type {Record<string,any>} */ (value).capture === 'function'
+    && typeof /** @type {Record<string,any>} */ (value).getDefault === 'function');
+}
+
+/** @param {Function & {cssName?:string}} View @returns {'table'|'card'|'kanban'|null} */
+function presentationType(View) {
+  const cssName = String(View.cssName ?? '').toLowerCase().replace(/-view$/, '');
+  if (['table', 'card', 'kanban'].includes(cssName)) {
+    return /** @type {'table'|'card'|'kanban'} */ (cssName);
+  }
+  const name = String(View.name ?? '').toLowerCase().replace(/view$/, '');
+  return ['table', 'card', 'kanban'].includes(name)
+    ? /** @type {'table'|'card'|'kanban'} */ (name) : null;
+}
+
+/** @param {unknown} value @returns {'table'|'card'|'kanban'|null} */
+function normalizePresentationType(value) {
+  const type = String(value ?? '').toLowerCase();
+  return ['table', 'card', 'kanban'].includes(type)
+    ? /** @type {'table'|'card'|'kanban'} */ (type) : null;
+}
+
+/** @param {Record<string,any>} registry @returns {Promise<void>} */
+async function readySavedViews(registry) {
+  if (typeof registry.ready === 'function') await registry.ready();
+  else if (typeof registry.load === 'function') await registry.load();
+}
+
+/**
+ * Reads the sort after `setViewState()` so unknown saved fields rejected by RecordView do not leak
+ * into the server query. The entry is only a fallback for compatible facade implementations.
+ * @param {Record<string,any>} view Applied view.
+ * @param {SavedViewEntry|null|undefined} entry Saved entry.
+ * @returns {ViewSort|null}
+ */
+function appliedViewSort(view, entry) {
+  const sort = typeof view.getSort === 'function' ? view.getSort()
+    : typeof view.getViewState === 'function' ? view.getViewState()?.sort : entry?.state?.sort;
+  if (!sort || typeof sort !== 'object' || Array.isArray(sort) || sort.id == null) return null;
+  return { id: String(sort.id), dir: sort.dir === 'desc' ? 'desc' : 'asc' };
+}

package/styles/icons.css

@@ -19,16 +19,9 @@ svg.zx-icon {
   vertical-align: middle;
 }
 
-/* ZeyOS module icon chip: the module glyph on its identity colour. `moduleChip()` sets the three
-   custom properties per module; the glyph is whichever ZeyOS foreground contrasts better. */
+/* ZeyOS identity hook. `moduleChip()` now delegates vessel geometry and material entirely to
+   AppIcon; this class only preserves the module variables for host styling and older selectors. */
 .zx-module-icon {
-  display: inline-grid;
-  place-items: center;
   flex: none;
-  inline-size: var(--zx-module-icon-size, 1.5rem);
-  block-size: var(--zx-module-icon-size, 1.5rem);
-  border-radius: var(--zx-radius-sm);
-  background: var(--zx-module-color, var(--zx-module-default));
-  color: var(--zx-module-glyph, var(--zx-module-fg-light));
-  font-size: calc(var(--zx-module-icon-size, 1.5rem) * 0.6);
+  color: var(--zx-module-glyph, var(--zx-color-app-icon-glyph));
 }

package/styles/tokens/semantic.css

@@ -27,6 +27,8 @@
   --zx-color-text-muted: var(--zx-gray-500);
   --zx-color-text-placeholder: var(--zx-gray-400);
   --zx-color-text-invert: var(--zx-gray-50);
+  --zx-color-app-icon-glyph: var(--zx-gray-0);
+  --zx-color-app-icon-shade: var(--zx-gray-950);
   --zx-color-accent: var(--zx-accent-600);
   --zx-color-accent-hover: var(--zx-accent-700);
   --zx-color-accent-active: var(--zx-accent-700);
@@ -53,12 +55,82 @@
   --zx-color-glass-border: color-mix(in srgb, var(--zx-gray-0) 24%, transparent);
   --zx-color-glass-highlight: color-mix(in srgb, var(--zx-gray-0) 24%, transparent);
   --zx-color-glass-highlight-strong: color-mix(in srgb, var(--zx-gray-0) 38%, transparent);
+  --zx-color-app-icon-depth: color-mix(in srgb, var(--zx-color-app-icon-shade) 26%, transparent);
+  /* AppIcon is a dark chromatic lens: colour lives in its rim and low bloom, not a glossy fill. */
+  /* Strengths remain inherited, while each AppIcon mixes them with its own module colour. */
+  --zx-app-icon-core-strength: 52%;
+  --zx-app-icon-rim-strength: 58%;
+  --zx-app-icon-bloom-strength: 64%;
+  --zx-app-icon-specular-strength: 72%;
+  --zx-app-icon-rim-base: var(--zx-color-glass-highlight);
+  --zx-app-icon-halo-size: 14px;
+  --zx-app-icon-halo-strength: 22%;
   --zx-color-glass-surface: color-mix(in srgb, var(--zx-color-bg-raised) 78%, transparent);
+  /* Persistent application chrome is quieter and more opaque than a raised feature card. */
+  --zx-color-glass-chrome: color-mix(in srgb, var(--zx-color-bg-surface) 90%, transparent);
+  --zx-color-glass-control: color-mix(in srgb, var(--zx-color-bg-control) 88%, transparent);
+  --zx-color-glass-control-hover: color-mix(in srgb, var(--zx-color-bg-hover) 76%, var(--zx-color-glass-surface));
+  /* Compact overlays can show more of the page; reading-sized panels stay quieter and more opaque. */
+  --zx-color-overlay-surface: color-mix(in srgb, var(--zx-color-bg-raised) 88%, transparent);
+  --zx-color-overlay-panel: color-mix(in srgb, var(--zx-color-bg-raised) 94%, transparent);
+  --zx-color-overlay-border: color-mix(in srgb, var(--zx-color-border-strong) 72%, var(--zx-color-glass-highlight));
   --zx-glass-blur: 8px;
   --zx-glass-saturation: 130%;
   --zx-glass-color-strength: 82%;
-  --zx-app-icon-shadow: inset 0 1px 0 color-mix(in srgb, var(--zx-gray-0) 28%, transparent), inset 0 -1px 0 color-mix(in srgb, var(--zx-gray-950) 16%, transparent), 0 5px 14px color-mix(in srgb, var(--zx-app-icon-color) 28%, transparent);
-  --zx-glass-glyph-shadow: 0 1px 1px color-mix(in srgb, var(--zx-gray-950) 22%, transparent);
+  /* Material filters are roles, not component recipes. Aurora remains a separate canvas layer. */
+  --zx-glass-filter-icon: blur(4px) saturate(118%);
+  --zx-glass-filter-control: blur(6px) saturate(116%);
+  --zx-glass-filter-raised: blur(8px) saturate(120%);
+  --zx-glass-filter-chrome: blur(10px) saturate(122%);
+  --zx-glass-filter-overlay: blur(12px) saturate(128%);
+  --zx-glass-filter-panel: blur(9px) saturate(120%);
+  --zx-app-icon-shadow: inset 0 1px 0 color-mix(in srgb, var(--zx-gray-0) 14%, transparent), inset 0 -1px 0 color-mix(in srgb, var(--zx-gray-950) 28%, transparent), 0 2px 6px color-mix(in srgb, var(--zx-color-app-icon-shade) 24%, transparent);
+  --zx-app-icon-shadow-hover: inset 0 1px 0 color-mix(in srgb, var(--zx-gray-0) 20%, transparent), inset 0 -1px 0 color-mix(in srgb, var(--zx-gray-950) 32%, transparent), 0 4px 10px color-mix(in srgb, var(--zx-color-app-icon-shade) 30%, transparent);
+  --zx-glass-control-shadow: inset 0 1px 0 color-mix(in srgb, var(--zx-gray-0) 18%, transparent), var(--zx-shadow-1);
+  --zx-glass-chrome-shadow: inset 0 1px 0 color-mix(in srgb, var(--zx-gray-0) 16%, transparent), var(--zx-shadow-1);
+  --zx-glass-raised-shadow: inset 0 1px 0 color-mix(in srgb, var(--zx-gray-0) 18%, transparent), var(--zx-overlay-shadow);
   --zx-header-bg: var(--zx-gray-900);
   --zx-header-text: var(--zx-gray-50);
 }
+
+/* Preferences are resolved at the token seam so every material consumer, including application
+   chrome outside a component stylesheet, receives the same deterministic opaque fallback. */
+@media (prefers-reduced-transparency: reduce), (prefers-contrast: more) {
+  :root,
+  [data-zx-theme] {
+    --zx-color-glass-chrome: var(--zx-color-bg-surface) !important;
+    --zx-color-glass-surface: var(--zx-color-bg-raised) !important;
+    --zx-color-glass-control: var(--zx-color-bg-control) !important;
+    --zx-color-glass-control-hover: var(--zx-color-bg-hover) !important;
+    --zx-color-overlay-surface: var(--zx-color-bg-raised) !important;
+    --zx-color-overlay-panel: var(--zx-color-bg-raised) !important;
+    --zx-app-icon-core-strength: 68% !important;
+    --zx-app-icon-rim-strength: 62% !important;
+    --zx-app-icon-bloom-strength: 0% !important;
+    --zx-app-icon-specular-strength: 0% !important;
+    --zx-app-icon-rim-base: var(--zx-color-border) !important;
+    --zx-app-icon-halo-strength: 0% !important;
+    --zx-glass-filter-icon: none !important;
+    --zx-glass-filter-control: none !important;
+    --zx-glass-filter-raised: none !important;
+    --zx-glass-filter-chrome: none !important;
+    --zx-glass-filter-overlay: none !important;
+    --zx-glass-filter-panel: none !important;
+  }
+}
+
+@media (forced-colors: active) {
+  :root,
+  [data-zx-theme] {
+    --zx-color-glass-chrome: Canvas !important;
+    --zx-color-glass-surface: Canvas !important;
+    --zx-color-glass-control: ButtonFace !important;
+    --zx-color-glass-control-hover: Highlight !important;
+    --zx-color-overlay-surface: Canvas !important;
+    --zx-color-overlay-panel: Canvas !important;
+    --zx-color-overlay-border: CanvasText !important;
+    --zx-glass-control-shadow: none !important;
+    --zx-glass-chrome-shadow: none !important;
+    --zx-glass-raised-shadow: none !important;
+  }
+}