@zeyos/zx 2.1.0 → 2.2.1

package/src/zeyos/icons.js

@@ -0,0 +1,92 @@
+/**
+ * ZeyOS module icons: the Font Awesome kit that carries them, and the two renderers built on the
+ * configuration in `./modules.js`.
+ * @module zx/zeyos/icons
+ */
+
+import { h, icon, loadFontAwesome } from '../index.js';
+import { moduleGlyphColor, moduleInfo, normalizeModuleName } from './modules.js';
+
+/**
+ * The ZeyOS Font Awesome kit. It carries the licensed Font Awesome styles plus the custom
+ * `zeyos-*` module glyphs, which render as `<i class="fa-kit fa-zeyos-notes">`.
+ * @type {string}
+ */
+export const ZEYOS_ICON_KIT = 'https://kit.fontawesome.com/ae8320b210.js';
+
+/**
+ * Loads the ZeyOS kit and makes Font Awesome the renderer for every Zx icon. Call it once at
+ * startup; repeat calls reuse the first load.
+ * @param {{kit?: string, style?: string, family?: string, fixedWidth?: boolean}} [options={}]
+ *   Overrides — a different kit, or a different default style such as `'duotone'`.
+ * @returns {Promise<object>} Resolves with the icon configuration once the kit has loaded.
+ */
+export function useZeyosIcons(options = {}) {
+  return loadFontAwesome({ kit: ZEYOS_ICON_KIT, ...options });
+}
+
+/**
+ * @typedef {Object} ModuleIconOptions
+ * @property {number|string} [size=16] Rendered size.
+ * @property {string|null} [label=null] Accessible label; null marks the icon decorative.
+ * @property {boolean} [standard=false] Render the stock Font Awesome fallback instead of the
+ *   kit's custom glyph — for pages running on a kit without the ZeyOS icon uploads.
+ * @property {string|string[]} [class] Extra class names.
+ */
+
+/**
+ * Creates a module's icon. Module, entity, and API resource names are all accepted
+ * (`'notes'`, `'transactions.billing'`, `'invoices'`); unknown names fall back to the ZeyOS
+ * default glyph.
+ * @param {string} name Module, entity, or resource name.
+ * @param {ModuleIconOptions} [options={}] Display and accessibility options.
+ * @returns {HTMLElement} An `<i>` element carrying the Font Awesome classes.
+ */
+export function moduleIcon(name, options = {}) {
+  const { standard = false, ...rest } = options;
+  const info = moduleInfo(name);
+  return icon(standard ? `fa:${info.fa}` : `kit:${info.icon}`, rest);
+}
+
+/**
+ * @typedef {Object} ModuleChipOptions
+ * @property {number|string} [size=24] Chip edge length.
+ * @property {number|string} [iconSize='1em'] Glyph size; `1em` is 60% of the chip edge.
+ * @property {string|null} [label=null] Accessible label; null marks the chip decorative.
+ * @property {boolean} [title=false] Adds the module's display name as a `title` tooltip.
+ * @property {boolean} [standard=false] Use the stock Font Awesome fallback glyph.
+ * @property {string|string[]} [class] Extra class names.
+ */
+
+/**
+ * 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. The glyph colour is whichever of ZeyOS's two
+ * foregrounds contrasts better with the background.
+ * @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.
+ */
+export function moduleChip(name, options = {}) {
+  const { size = 24, iconSize = '1em', label = null, title = false, standard = false } = options;
+  const key = normalizeModuleName(name);
+  const info = moduleInfo(name);
+
+  const chip = h('span', {
+    class: ['zx-module-icon', options.class].flat().filter(Boolean),
+    dataset: { module: key },
+    style: {
+      '--zx-module-color': info.color,
+      '--zx-module-glyph': moduleGlyphColor(info.color),
+      '--zx-module-icon-size': typeof size === 'number' ? `${size}px` : String(size)
+    },
+    title: title ? info.label : null
+  }, moduleIcon(name, { size: iconSize, standard }));
+
+  if (label === null) {
+    chip.setAttribute('aria-hidden', 'true');
+  } else {
+    chip.setAttribute('role', 'img');
+    chip.setAttribute('aria-label', label);
+  }
+  return chip;
+}

package/src/zeyos/index.js

@@ -0,0 +1,21 @@
+/**
+ * Optional injection-based Zx binding for `@zeyos/client` applications.
+ * @module zx/zeyos
+ */
+
+export {
+  fieldToZxField, fieldToZxColumn, resolveFields, registerFieldType
+} from './schema.js';
+export {
+  buildListQuery, tableSortToQuery, dataFilterStateToFilters,
+  dateToUnixSeconds, unixSecondsToDate
+} from './query.js';
+export { connect } from './connect.js';
+export {
+  zeyosModules, moduleAliases, moduleInfo, moduleColor, moduleIconName, moduleKeys,
+  moduleGlyphColor, normalizeModuleName, registerModules
+} from './modules.js';
+export { ZEYOS_ICON_KIT, useZeyosIcons, moduleIcon, moduleChip } from './icons.js';
+export { zeyosSelect } from './select.js';
+export { zeyosForm } from './form.js';
+export { zeyosTable } from './table.js';

package/src/zeyos/modules.js

@@ -0,0 +1,269 @@
+/**
+ * ZeyOS module and entity identity — the icon and the colour each one is drawn with.
+ *
+ * This is the configuration file the rest of the ZeyOS layer reads. One entry per module:
+ *
+ * ```js
+ * notes: { label: 'Notes', icon: 'zeyos-notes', color: '#008853', fa: 'note-sticky' }
+ * ```
+ *
+ * - `icon` is the icon's name in the ZeyOS Font Awesome kit; it renders as
+ *   `<i class="fa-kit fa-zeyos-notes">` and needs the kit loaded (see `./icons.js`).
+ * - `fa` is a stock Font Awesome name used when the custom icons are unavailable — every one of
+ *   them exists in Font Awesome Free, so the fallback also works on a Free kit.
+ * - `color` is the module's identity colour, used for icon chips and header accents. Colours
+ *   marked "ZeyOS runtime" below are the values ZeyOS itself ships (`ICO.Colors`); the rest are
+ *   Zx defaults for modules ZeyOS has no colour for. Both are overridable: a ZeyOS menu payload
+ *   is authoritative, so pass its colours to `registerModules()` at startup.
+ *
+ * The `--zx-module-*` CSS custom properties in `styles/tokens/modules.css` are generated from
+ * this file by `tools/build-module-tokens.js`; `tests/unit/zeyos-modules.test.js` fails if the
+ * two drift apart.
+ *
+ * @module zx/zeyos/modules
+ */
+
+/**
+ * @typedef {Object} ZeyosModule
+ * @property {string} label English display name.
+ * @property {string} icon Icon name in the ZeyOS Font Awesome kit.
+ * @property {string} color Identity colour as a hex string.
+ * @property {string} fa Stock Font Awesome name used when the kit's custom icons are missing.
+ */
+
+/**
+ * Every module in the ZeyOS Font Awesome kit, keyed by module identifier.
+ * @type {Readonly<Record<string, ZeyosModule>>}
+ */
+export const zeyosModules = Object.freeze({
+  /* ---------------------------------------------- colours from the ZeyOS runtime (ICO.Colors) */
+  accounts: { label: 'Accounts', icon: 'zeyos-accounts', color: '#bc3885', fa: 'building' },
+  actionsteps: { label: 'Action Steps', icon: 'zeyos-actionsteps', color: '#f67f00', fa: 'clock' },
+  appointments: { label: 'Appointments', icon: 'zeyos-appointments', color: '#bd1e32', fa: 'calendar-check' },
+  billing: { label: 'Billing', icon: 'zeyos-billing', color: '#535494', fa: 'file-invoice-dollar' },
+  calendar: { label: 'Calendar', icon: 'zeyos-calendar', color: '#bd1e32', fa: 'calendar-days' },
+  campaigns: { label: 'Campaigns', icon: 'zeyos-campaigns', color: '#f16528', fa: 'bullhorn' },
+  collection: { label: 'Collection', icon: 'zeyos-collection', color: '#0d60ae', fa: 'hand-holding-dollar' },
+  contacts: { label: 'Contacts', icon: 'zeyos-contacts', color: '#8c6641', fa: 'address-book' },
+  contracts: { label: 'Contracts', icon: 'zeyos-contracts', color: '#823e89', fa: 'file-contract' },
+  coupons: { label: 'Coupons', icon: 'zeyos-coupons', color: '#10775c', fa: 'ticket-simple' },
+  devices: { label: 'Devices', icon: 'zeyos-devices', color: '#064e4f', fa: 'desktop' },
+  documents: { label: 'Documents', icon: 'zeyos-documents', color: '#808000', fa: 'file' },
+  dunning: { label: 'Dunning', icon: 'zeyos-dunning', color: '#0d60ae', fa: 'file-invoice-dollar' },
+  events: { label: 'Events', icon: 'zeyos-events', color: '#bd1e32', fa: 'calendar-day' },
+  inventory: { label: 'Inventory', icon: 'zeyos-inventory', color: '#064e4f', fa: 'warehouse' },
+  items: { label: 'Items', icon: 'zeyos-items', color: '#064e4f', fa: 'box-open' },
+  ledgers: { label: 'Ledgers', icon: 'zeyos-ledgers', color: '#4679c8', fa: 'book-open' },
+  line: { label: 'Line Items', icon: 'zeyos-line', color: '#064e4f', fa: 'list-ul' },
+  links: { label: 'Links', icon: 'zeyos-links', color: '#405e76', fa: 'bookmark' },
+  mailinglists: { label: 'Mailing Lists', icon: 'zeyos-mailinglists', color: '#0299ac', fa: 'envelope-open-text' },
+  messages: { label: 'Messages', icon: 'zeyos-messages', color: '#31a8e0', fa: 'message' },
+  'messages-unread': { label: 'Unread Messages', icon: 'zeyos-messages-unread', color: '#31a8e0', fa: 'envelope' },
+  notes: { label: 'Notes', icon: 'zeyos-notes', color: '#008853', fa: 'note-sticky' },
+  opportunities: { label: 'Opportunities', icon: 'zeyos-opportunities', color: '#7b67ae', fa: 'handshake' },
+  payments: { label: 'Payments', icon: 'zeyos-payments', color: '#4679c8', fa: 'sack-dollar' },
+  pricelists: { label: 'Price Lists', icon: 'zeyos-pricelists', color: '#10775c', fa: 'clipboard-list' },
+  procurement: { label: 'Procurement', icon: 'zeyos-procurement', color: '#006e9f', fa: 'truck' },
+  production: { label: 'Production', icon: 'zeyos-production', color: '#226375', fa: 'industry' },
+  projects: { label: 'Projects', icon: 'zeyos-projects', color: '#db532d', fa: 'diagram-project' },
+  stocktransactions: { label: 'Stock Transactions', icon: 'zeyos-stocktransactions', color: '#064e4f', fa: 'arrow-right-arrow-left' },
+  storages: { label: 'Storages', icon: 'zeyos-storages', color: '#064e4f', fa: 'boxes-stacked' },
+  tasks: { label: 'Tasks', icon: 'zeyos-tasks', color: '#e2b301', fa: 'list-check' },
+  text: { label: 'Text Blocks', icon: 'zeyos-text', color: '#064e4f', fa: 'file-lines' },
+  tickets: { label: 'Tickets', icon: 'zeyos-tickets', color: '#f04639', fa: 'ticket' },
+  'transactions-billing': { label: 'Billing Transactions', icon: 'zeyos-transactions-billing', color: '#535494', fa: 'file-invoice' },
+  'transactions-collection': { label: 'Collection Transactions', icon: 'zeyos-transactions-collection', color: '#0d60ae', fa: 'money-bill-transfer' },
+  'transactions-procurement': { label: 'Procurement Transactions', icon: 'zeyos-transactions-procurement', color: '#006e9f', fa: 'cart-shopping' },
+  'transactions-production': { label: 'Production Transactions', icon: 'zeyos-transactions-production', color: '#226375', fa: 'gears' },
+
+  /* ------------------------------------- Zx defaults: modules ZeyOS ships no identity colour for */
+  zeyos: { label: 'ZeyOS', icon: 'zeyos', color: '#007a55', fa: 'cloud' },
+  default: { label: 'Default', icon: 'zeyos-default', color: '#21cc75', fa: 'cube' },
+  admin: { label: 'Administration', icon: 'zeyos-admin', color: '#4b5563', fa: 'screwdriver-wrench' },
+  applications: { label: 'Applications', icon: 'zeyos-applications', color: '#2563eb', fa: 'window-maximize' },
+  auth: { label: 'Credentials', icon: 'zeyos-auth', color: '#a16207', fa: 'shield-halved' },
+  categories: { label: 'Categories', icon: 'zeyos-categories', color: '#9a3412', fa: 'folder-tree' },
+  channels: { label: 'Channels', icon: 'zeyos-channels', color: '#0891b2', fa: 'share-nodes' },
+  control: { label: 'Control Center', icon: 'zeyos-control', color: '#0f766e', fa: 'sliders' },
+  davservers: { label: 'DAV Servers', icon: 'zeyos-davservers', color: '#475569', fa: 'server' },
+  dev: { label: 'Development', icon: 'zeyos-dev', color: '#1f2937', fa: 'code' },
+  error: { label: 'Errors', icon: 'zeyos-error', color: '#b91c1c', fa: 'triangle-exclamation' },
+  global: { label: 'Global', icon: 'zeyos-global', color: '#0369a1', fa: 'globe' },
+  groups: { label: 'Groups', icon: 'zeyos-groups', color: '#007a55', fa: 'users' },
+  logout: { label: 'Logout', icon: 'zeyos-logout', color: '#9f1239', fa: 'right-from-bracket' },
+  objects: { label: 'Custom Objects', icon: 'zeyos-objects', color: '#7e22ce', fa: 'cubes' },
+  participants: { label: 'Participants', icon: 'zeyos-participants', color: '#4338ca', fa: 'user-group' },
+  permissions: { label: 'Permissions', icon: 'zeyos-permissions', color: '#5b21b6', fa: 'user-lock' },
+  records: { label: 'Records', icon: 'zeyos-records', color: '#57534e', fa: 'database' },
+  resources: { label: 'Resources', icon: 'zeyos-resources', color: '#15803d', fa: 'layer-group' },
+  services: { label: 'Services', icon: 'zeyos-services', color: '#b45309', fa: 'bell-concierge' },
+  system: { label: 'System', icon: 'zeyos-system', color: '#374151', fa: 'gear' },
+  users: { label: 'Users', icon: 'zeyos-users', color: '#007a55', fa: 'user' },
+  weblets: { label: 'Weblets', icon: 'zeyos-weblets', color: '#4f46e5', fa: 'window-restore' }
+});
+
+/**
+ * Alternative identifiers resolving to a module key: API resource names, ZeyOS entity names, and
+ * the legacy gx module names. Dotted ZeyOS identifiers (`transactions.billing`) need no entry —
+ * `normalizeModuleName()` turns dots into hyphens first.
+ * @type {Readonly<Record<string, string>>}
+ */
+export const moduleAliases = Object.freeze({
+  addresses: 'contacts',
+  clocking: 'actionsteps',
+  comments: 'notes',
+  couponcodes: 'coupons',
+  customers: 'accounts',
+  customfields: 'objects',
+  davids: 'davservers',
+  documentversions: 'documents',
+  enhancements: 'applications',
+  extdata: 'objects',
+  feedservers: 'channels',
+  files: 'documents',
+  filters: 'records',
+  forks: 'applications',
+  imports: 'records',
+  invoices: 'transactions-billing',
+  linecoupon: 'line',
+  logins: 'auth',
+  mailservers: 'channels',
+  notifications: 'messages',
+  'participants-campaigns': 'participants',
+  'participants-mailinglists': 'participants',
+  prices: 'pricelists',
+  pwd: 'auth',
+  purchaseorders: 'transactions-procurement',
+  sessions: 'auth',
+  settings: 'system',
+  suppliers: 'accounts',
+  tags: 'categories',
+  tokens: 'auth',
+  transactions: 'transactions-billing',
+  usergroups: 'groups',
+  usermgmt: 'users',
+  usersettings: 'system',
+  userfields: 'objects',
+  userfilters: 'records'
+});
+
+/** Glyph colour candidates, matching the two foregrounds ZeyOS measured its palette against. */
+const glyphColors = Object.freeze({ light: '#ffffff', dark: '#141414' });
+
+/** @type {Record<string, ZeyosModule>} Modules registered or overridden at runtime. */
+const overrides = Object.create(null);
+
+/**
+ * Normalizes a module, entity, or resource name to a module key. Case, surrounding whitespace,
+ * dots (`transactions.billing`), and underscores are all accepted; aliases are resolved.
+ * @param {string|null|undefined} name Module, entity, or resource name.
+ * @returns {string} A module key, or `'default'` when nothing matches.
+ */
+export function normalizeModuleName(name) {
+  const key = String(name ?? '').trim().toLowerCase().replaceAll(/[._\s]+/g, '-');
+  if (!key) return 'default';
+  if (Object.hasOwn(overrides, key) || Object.hasOwn(zeyosModules, key)) return key;
+  const alias = moduleAliases[key];
+  if (alias) return alias;
+  return 'default';
+}
+
+/**
+ * Looks a module up. Unknown names fall back to the `default` entry, so callers always get an
+ * icon and a colour.
+ * @param {string|null|undefined} name Module, entity, or resource name.
+ * @returns {ZeyosModule} The module's configuration.
+ */
+export function moduleInfo(name) {
+  const key = normalizeModuleName(name);
+  return overrides[key] ?? zeyosModules[key] ?? zeyosModules.default;
+}
+
+/**
+ * Reads a module's identity colour.
+ * @param {string|null|undefined} name Module, entity, or resource name.
+ * @returns {string} Hex colour.
+ */
+export function moduleColor(name) {
+  return moduleInfo(name).color;
+}
+
+/**
+ * Reads the kit icon name for a module (`'zeyos-notes'`), or its stock Font Awesome fallback.
+ * @param {string|null|undefined} name Module, entity, or resource name.
+ * @param {{standard?: boolean}} [options={}] Set `standard` for the stock Font Awesome name.
+ * @returns {string} Icon name without the `fa-` prefix.
+ */
+export function moduleIconName(name, { standard = false } = {}) {
+  const info = moduleInfo(name);
+  return standard ? info.fa : info.icon;
+}
+
+/**
+ * Lists every module key, including runtime registrations.
+ * @returns {string[]} Sorted module keys.
+ */
+export function moduleKeys() {
+  return [...new Set([...Object.keys(zeyosModules), ...Object.keys(overrides)])].sort();
+}
+
+/**
+ * Registers modules, or overrides shipped ones — for forks, weblets, and the colours a ZeyOS
+ * menu payload carries. A partial entry inherits the rest from the module it replaces.
+ * @param {Record<string, string|Partial<ZeyosModule>>} modules Entries keyed by module name;
+ *   a string value sets the colour only.
+ * @returns {void}
+ */
+export function registerModules(modules) {
+  for (const [name, value] of Object.entries(modules)) {
+    const key = String(name).trim().toLowerCase().replaceAll(/[._\s]+/g, '-');
+    const patch = typeof value === 'string' ? { color: value } : value;
+    const base = overrides[key] ?? zeyosModules[key] ?? zeyosModules.default;
+    overrides[key] = Object.freeze({
+      label: patch.label ?? base.label,
+      icon: patch.icon ?? base.icon,
+      color: patch.color ?? base.color,
+      fa: patch.fa ?? base.fa
+    });
+  }
+}
+
+/**
+ * Picks the higher-contrast glyph colour for a background, using the same two candidates and the
+ * same WCAG relative-luminance maths ZeyOS used to measure its palette.
+ * @param {string} background Hex colour, three or six digits.
+ * @returns {string} `'#ffffff'` or `'#141414'`.
+ */
+export function moduleGlyphColor(background) {
+  const luminance = hexLuminance(background);
+  if (luminance === null) return glyphColors.light;
+  const light = contrastRatio(luminance, hexLuminance(glyphColors.light) ?? 1);
+  const dark = contrastRatio(luminance, hexLuminance(glyphColors.dark) ?? 0);
+  return light >= dark ? glyphColors.light : glyphColors.dark;
+}
+
+/**
+ * WCAG relative luminance of a hex colour.
+ * @param {string} color Hex colour, three or six digits.
+ * @returns {number|null} Luminance, or null when the colour is not hex.
+ */
+function hexLuminance(color) {
+  const match = /^#([\da-f]{3}|[\da-f]{6})$/i.exec(String(color).trim());
+  if (!match) return null;
+  const digits = match[1].length === 3 ? [...match[1]].map((digit) => digit + digit).join('') : match[1];
+  const [red, green, blue] = [0, 2, 4].map((offset) => {
+    const channel = Number.parseInt(digits.slice(offset, offset + 2), 16) / 255;
+    return channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * red + 0.7152 * green + 0.0722 * blue;
+}
+
+/**
+ * Contrast ratio between two relative luminances.
+ * @param {number} first First luminance.
+ * @param {number} second Second luminance.
+ * @returns {number}
+ */
+function contrastRatio(first, second) {
+  return (Math.max(first, second) + 0.05) / (Math.min(first, second) + 0.05);
+}

package/src/zeyos/query.js

@@ -0,0 +1,199 @@
+/** @typedef {{id?: string, field?: string, rawField?: string, dir?: 'asc'|'desc'}} ZxSort */
+
+/**
+ * @typedef {Object} ListQueryOptions
+ * @property {string[]|Record<string, string>} [fields] Projection, including aliases and dot joins.
+ * @property {ZxSort|ZxSort[]} [sort] Zx table sort state.
+ * @property {Record<string, unknown>} [filters] ZeyOS field predicates.
+ * @property {string} [search] Full-text query.
+ * @property {string[]} [searchFields] UI search-field metadata; ZeyOS searches its indexed text fields.
+ * @property {number} [limit] Page size.
+ * @property {number} [offset] Page offset.
+ * @property {number|null} [visibility=0] Visibility predicate; null is preserved deliberately.
+ * @property {boolean} [count=false] Request a server-side count instead of counting a returned page.
+ */
+
+/**
+ * @typedef {Object} ServerFilterDefinition
+ * @property {string} id DataFilter state key.
+ * @property {string} [field] Raw ZeyOS field.
+ * @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 {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.
+ * @property {(value: unknown, state: Record<string, unknown>) => Record<string, unknown>|undefined} [toFilter] Complete predicate transform.
+ */
+
+/**
+ * Converts a Date to the Unix-second unit used by every ZeyOS timestamp.
+ * Milliseconds are truncated because the server stores whole seconds.
+ * @param {Date|null|undefined} date Date value.
+ * @returns {number|null} Unix seconds, or null for a nullish input.
+ */
+export function dateToUnixSeconds(date) {
+  if (date == null) return null;
+  if (!(date instanceof Date)) throw new TypeError('Expected a Date');
+  const milliseconds = date.getTime();
+  if (!Number.isFinite(milliseconds)) throw new RangeError('Invalid Date');
+  return Math.floor(milliseconds / 1000);
+}
+
+/**
+ * Converts a ZeyOS Unix-second timestamp to a Date.
+ * Numeric strings are accepted because some endpoints serialize bigint columns as strings.
+ * @param {number|string|null|undefined} seconds Unix seconds.
+ * @returns {Date|null} Date value, or null for a nullish input.
+ */
+export function unixSecondsToDate(seconds) {
+  if (seconds == null) return null;
+  const value = Number(seconds);
+  if (!Number.isFinite(value)) throw new TypeError('Expected finite Unix seconds');
+  return new Date(value * 1000);
+}
+
+/**
+ * Converts one or more Zx Table sort records to the signed field notation used by ZeyOS.
+ * A missing sort produces an empty array.
+ * @param {ZxSort|ZxSort[]|null|undefined} sort Zx sort state.
+ * @returns {string[]} Signed raw fields such as `+name` or `-lastmodified`.
+ */
+export function tableSortToQuery(sort) {
+  const entries = Array.isArray(sort) ? sort : (sort ? [sort] : []);
+  return entries.flatMap((entry) => {
+    if (!entry || typeof entry !== 'object') return [];
+    const source = entry.rawField ?? entry.field ?? entry.id;
+    if (source == null || String(source).trim() === '') return [];
+    const field = String(source).trim().replace(/^[+-]/, '');
+    return [`${entry.dir === 'desc' ? '-' : '+'}${field}`];
+  });
+}
+
+/**
+ * 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
+ * values are DataFilter's inactive sentinels by default; `includeEmpty`/`includeNull` opt in to
+ * 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.
+ * @returns {Record<string, unknown>} ZeyOS `filters` object (plural at the call site).
+ */
+export function dataFilterStateToFilters(state, defs = []) {
+  if (!state || typeof state !== 'object' || Array.isArray(state)) {
+    throw new TypeError('DataFilter state must be an object');
+  }
+  const definitions = normalizeDefinitions(state, defs);
+  const filters = {};
+  let groupIndex = 0;
+
+  for (const definition of definitions) {
+    if (!definition.id || !Object.prototype.hasOwnProperty.call(state, definition.id)) continue;
+    const original = state[definition.id];
+    if (original === undefined) continue;
+    if (original === null && definition.includeNull !== true) continue;
+    if (typeof original === 'string' && original.trim() === '' && definition.includeEmpty !== true) continue;
+
+    if (typeof definition.toFilter === 'function') {
+      const predicate = definition.toFilter(original, state);
+      if (predicate && typeof predicate === 'object' && !Array.isArray(predicate)) {
+        Object.assign(filters, predicate);
+      }
+      continue;
+    }
+
+    let value = typeof definition.transform === 'function'
+      ? definition.transform(original, state)
+      : normalizeFilterValue(original, definition);
+    if (value === undefined) continue;
+    if (definition.operator) value = { [definition.operator]: value };
+
+    const fields = Array.isArray(definition.fields)
+      ? definition.fields.filter((field) => typeof field === 'string' && field)
+      : [];
+    if (fields.length > 1) {
+      while (Object.prototype.hasOwnProperty.call(filters, String(groupIndex))) groupIndex += 1;
+      filters[String(groupIndex)] = ['OR', ...fields.map((field) => ({ [field]: value }))];
+      groupIndex += 1;
+      continue;
+    }
+    const field = fields[0] ?? definition.rawField ?? definition.field ?? definition.id;
+    if (typeof field === 'string' && field) filters[field] = value;
+  }
+  return filters;
+}
+
+/**
+ * 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.
+ * Full-text `query` is server-scoped: `searchFields` describes the UI but is not an API parameter.
+ * Set `count` to use ZeyOS's server-side count; there is no equivalent server-side SUM.
+ * @param {ListQueryOptions} [options={}] Zx list state.
+ * @returns {Record<string, unknown>} ZeyOS list request body.
+ */
+export function buildListQuery(options = {}) {
+  const {
+    fields, sort, filters = {}, search, limit, offset, visibility = 0, count = false
+  } = options;
+  if (!filters || typeof filters !== 'object' || Array.isArray(filters)) {
+    throw new TypeError('ZeyOS filters must be an object');
+  }
+
+  const query = {};
+  if (Array.isArray(fields)) query.fields = [...fields];
+  else if (fields && typeof fields === 'object') query.fields = { ...fields };
+
+  const fieldPredicates = { ...filters };
+  const explicitVisibility = Object.prototype.hasOwnProperty.call(options, 'visibility');
+  if (visibility !== undefined && (explicitVisibility || !Object.prototype.hasOwnProperty.call(fieldPredicates, 'visibility'))) {
+    fieldPredicates.visibility = visibility;
+  }
+  if (Object.keys(fieldPredicates).length) query.filters = fieldPredicates;
+
+  const mappedSort = mapSortAliases(sort, fields);
+  const sortQuery = tableSortToQuery(mappedSort);
+  if (sortQuery.length) query.sort = sortQuery;
+
+  if (search != null && String(search).trim()) query.query = String(search).trim();
+  if (limit != null) query.limit = limit;
+  if (offset != null) query.offset = offset;
+  if (count) query.count = true;
+  return query;
+}
+
+/** @param {Record<string, unknown>} state @param {ServerFilterDefinition[]|Record<string, string|ServerFilterDefinition>} defs @returns {ServerFilterDefinition[]} */
+function normalizeDefinitions(state, defs) {
+  if (Array.isArray(defs) && defs.length) return defs.map((definition) => ({ ...definition }));
+  if (defs && typeof defs === 'object' && !Array.isArray(defs) && Object.keys(defs).length) {
+    return Object.entries(defs).map(([id, definition]) => typeof definition === 'string'
+      ? { id, field: definition }
+      : { ...definition, id });
+  }
+  return Object.keys(state).map((id) => ({ id, field: id }));
+}
+
+/** @param {unknown} value @param {ServerFilterDefinition} definition @returns {unknown} */
+function normalizeFilterValue(value, definition) {
+  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;
+}
+
+/** @param {ZxSort|ZxSort[]|undefined} sort @param {string[]|Record<string, string>|undefined} fields @returns {ZxSort|ZxSort[]|undefined} */
+function mapSortAliases(sort, fields) {
+  if (!sort || !fields || Array.isArray(fields) || typeof fields !== 'object') return sort;
+  const mapOne = (entry) => {
+    if (!entry || typeof entry !== 'object') return entry;
+    const alias = entry.id;
+    if (!alias || !Object.prototype.hasOwnProperty.call(fields, alias)) return entry;
+    return { ...entry, rawField: fields[alias] };
+  };
+  return Array.isArray(sort) ? sort.map(mapOne) : mapOne(sort);
+}