@zeyos/zx 2.1.0 → 2.2.0

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

@@ -0,0 +1,65 @@
+export type ConnectOptions = {
+    /**
+     * Error reporter.
+     */
+    onError?: (error: unknown, context?: {
+        operation?: string;
+        resource?: string;
+    }) => unknown;
+    /**
+     * BCP 47 locale applied to Zx i18n/date formatting.
+     */
+    locale?: string;
+};
+export type ZeyosFacade = {
+    /**
+     * Injected client instance.
+     */
+    client: Record<string, any>;
+    /**
+     * List a resource.
+     */
+    list: (resource: string, params?: Record<string, unknown>) => Promise<unknown>;
+    /**
+     * Fetch one record.
+     */
+    get: (resource: string, idOrParams: unknown, params?: Record<string, unknown>) => Promise<unknown>;
+    /**
+     * Create one record.
+     */
+    create: (resource: string, data: Record<string, unknown>) => Promise<unknown>;
+    /**
+     * Update one record.
+     */
+    update: (resource: string, idOrInput: unknown, data?: Record<string, unknown>) => Promise<unknown>;
+    /**
+     * Report an API error.
+     */
+    reportError: (error: unknown, context?: {
+        operation?: string;
+        resource?: string;
+    }) => unknown;
+};
+/**
+ * @typedef {Object} ConnectOptions
+ * @property {(error: unknown, context?: {operation?: string, resource?: string}) => unknown} [onError] Error reporter.
+ * @property {string} [locale] BCP 47 locale applied to Zx i18n/date formatting.
+ */
+/**
+ * @typedef {Object} ZeyosFacade
+ * @property {Record<string, any>} client Injected client instance.
+ * @property {(resource: string, params?: Record<string, unknown>) => Promise<unknown>} list List a resource.
+ * @property {(resource: string, idOrParams: unknown, params?: Record<string, unknown>) => Promise<unknown>} get Fetch one record.
+ * @property {(resource: string, data: Record<string, unknown>) => Promise<unknown>} create Create one record.
+ * @property {(resource: string, idOrInput: unknown, data?: Record<string, unknown>) => Promise<unknown>} update Update one record.
+ * @property {(error: unknown, context?: {operation?: string, resource?: string}) => unknown} reportError Report an API error.
+ */
+/**
+ * Connects an existing injected `@zeyos/client` instance to Zx infrastructure. This function never
+ * creates or imports the client package. It applies a supplied/derivable locale and returns thin
+ * operation helpers that report and rethrow failures.
+ * @param {Record<string, any>} client Injected ZeyOS client instance.
+ * @param {ConnectOptions} [options={}] Wiring options.
+ * @returns {ZeyosFacade} Bound facade.
+ */
+export declare function connect(client: Record<string, any>, { onError, locale }?: ConnectOptions): ZeyosFacade;

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

@@ -0,0 +1,140 @@
+import { Form } from '../index.js';
+export type ZeyosFormOptions = {
+    /**
+     * Curated ordered field allow-list.
+     */
+    fields?: string[];
+    /**
+     * Field ids to omit.
+     */
+    exclude?: string[];
+    /**
+     * Per-field label overrides.
+     */
+    labels?: Record<string, string>;
+    /**
+     * Fieldset legend.
+     */
+    title?: string;
+    /**
+     * Fieldset column count.
+     */
+    columns?: 1 | 2 | 3;
+    /**
+     * Initial record using ZeyOS storage values.
+     */
+    value?: Record<string, unknown>;
+    /**
+     * Initial record id to load.
+     */
+    id?: unknown;
+    /**
+     * Success callback.
+     */
+    onSaved?: (record: Record<string, unknown>) => unknown | Promise<unknown>;
+};
+export type ZeyosFormConfig = {
+    /**
+     * Ordered normalized schema metadata.
+     */
+    fieldMeta: Record<string, any>[];
+    /**
+     * Field descriptors keyed by id.
+     */
+    fields: Record<string, Record<string, any>>;
+    /**
+     * Referenced-resource fields.
+     */
+    entityFields: Array<{
+        id: string;
+        resource: string;
+    }>;
+    /**
+     * Plain Zx Form options.
+     */
+    formOptions: Record<string, any>;
+    /**
+     * Maps Unix seconds to Date values.
+     */
+    mapFromRecord: (record: Record<string, unknown>) => Record<string, unknown>;
+    /**
+     * Maps Date and enum values to API storage values.
+     */
+    mapToRecord: (values: Record<string, unknown>) => Record<string, unknown>;
+};
+export type ZeyosFormBinding = {
+    /**
+     * Generated Zx form.
+     */
+    form: Form;
+    /**
+     * Initial value/load readiness.
+     */
+    ready: Promise<Record<string, unknown> | null>;
+    /**
+     * Loads and maps one record.
+     */
+    load: (id: unknown) => Promise<Record<string, unknown>>;
+    /**
+     * Validates and creates or updates the record.
+     */
+    save: () => Promise<Record<string, unknown> | null>;
+    /**
+     * Returns the generated Zx Form.
+     */
+    getForm: () => Form;
+    /**
+     * Destroys the form and all owned fields/selects.
+     */
+    destroy: () => void;
+};
+/**
+ * @typedef {Object} ZeyosFormOptions
+ * @property {string[]} [fields] Curated ordered field allow-list.
+ * @property {string[]} [exclude] Field ids to omit.
+ * @property {Record<string, string>} [labels] Per-field label overrides.
+ * @property {string} [title=''] Fieldset legend.
+ * @property {1|2|3} [columns=2] Fieldset column count.
+ * @property {Record<string, unknown>} [value] Initial record using ZeyOS storage values.
+ * @property {unknown} [id] Initial record id to load.
+ * @property {(record: Record<string, unknown>) => unknown|Promise<unknown>} [onSaved] Success callback.
+ */
+/**
+ * @typedef {Object} ZeyosFormConfig
+ * @property {Record<string, any>[]} fieldMeta Ordered normalized schema metadata.
+ * @property {Record<string, Record<string, any>>} fields Field descriptors keyed by id.
+ * @property {Array<{id: string, resource: string}>} entityFields Referenced-resource fields.
+ * @property {Record<string, any>} formOptions Plain Zx Form options.
+ * @property {(record: Record<string, unknown>) => Record<string, unknown>} mapFromRecord Maps Unix seconds to Date values.
+ * @property {(values: Record<string, unknown>) => Record<string, unknown>} mapToRecord Maps Date and enum values to API storage values.
+ */
+/**
+ * @typedef {Object} ZeyosFormBinding
+ * @property {Form} form Generated Zx form.
+ * @property {Promise<Record<string, unknown>|null>} ready Initial value/load readiness.
+ * @property {(id: unknown) => Promise<Record<string, unknown>>} load Loads and maps one record.
+ * @property {() => Promise<Record<string, unknown>|null>} save Validates and creates or updates the record.
+ * @property {() => Form} getForm Returns the generated Zx Form.
+ * @property {() => void} destroy Destroys the form and all owned fields/selects.
+ */
+/**
+ * Builds the DOM-free form configuration consumed by {@link zeyosForm}. Entity descriptors retain
+ * the `zxselect` type and receive the same async options used by {@link zeyosSelect}; enum options
+ * come from normalized schema metadata, and the returned mappers handle Unix-second dates.
+ * @param {Record<string, any>} client Injected ZeyOS client instance.
+ * @param {string} resource Resource name such as `transactions`.
+ * @param {ZeyosFormOptions} [opts={}] Schema curation and layout options.
+ * @returns {ZeyosFormConfig} Plain generator configuration and value mappers.
+ */
+export declare function buildZeyosFormConfig(client: Record<string, any>, resource: string, opts?: ZeyosFormOptions): ZeyosFormConfig;
+/**
+ * Generates a schema-driven Zx Form and a small async binding object. `load(id)` hydrates entity
+ * labels and converts Unix seconds to Date objects. `save()` validates, maps values back to API
+ * storage types, calls create/update through the WP14 connection facade, shows a success toast,
+ * and invokes `onSaved(record)`. Await `ready` when `opts.id` or `opts.value` is supplied.
+ * @param {Record<string, any>} client Injected ZeyOS client instance.
+ * @param {string} resource Resource name such as `transactions`.
+ * @param {ZeyosFormOptions} [opts={}] Schema, initial value, and save options.
+ * @returns {ZeyosFormBinding} Generated form and lifecycle/data methods.
+ */
+export declare function zeyosForm(client: Record<string, any>, resource: string, opts?: ZeyosFormOptions): ZeyosFormBinding;

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

@@ -0,0 +1,104 @@
+/**
+ * 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
+ */
+/**
+ * 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 declare const ZEYOS_ICON_KIT: string;
+/**
+ * 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 declare function useZeyosIcons(options?: {
+    kit?: string;
+    style?: string;
+    family?: string;
+    fixedWidth?: boolean;
+}): Promise<object>;
+export type ModuleIconOptions = {
+    /**
+     * Rendered size.
+     */
+    size?: number | string;
+    /**
+     * Accessible label; null marks the icon decorative.
+     */
+    label?: string | null;
+    /**
+     * Render the stock Font Awesome fallback instead of the
+     * kit's custom glyph — for pages running on a kit without the ZeyOS icon uploads.
+     */
+    standard?: boolean;
+    /**
+     * Extra class names.
+     */
+    class?: string | string[];
+};
+/**
+ * @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 declare function moduleIcon(name: string, options?: ModuleIconOptions): HTMLElement;
+export type ModuleChipOptions = {
+    /**
+     * Chip edge length.
+     */
+    size?: number | string;
+    /**
+     * Glyph size; `1em` is 60% of the chip edge.
+     */
+    iconSize?: number | string;
+    /**
+     * Accessible label; null marks the chip decorative.
+     */
+    label?: string | null;
+    /**
+     * Adds the module's display name as a `title` tooltip.
+     */
+    title?: boolean;
+    /**
+     * Use the stock Font Awesome fallback glyph.
+     */
+    standard?: boolean;
+    /**
+     * Extra class names.
+     */
+    class?: string | string[];
+};
+/**
+ * @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 declare function moduleChip(name: string, options?: ModuleChipOptions): HTMLElement;

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

@@ -0,0 +1,12 @@
+/**
+ * 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/dist/types/zeyos/modules.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 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
+ */
+export type ZeyosModule = {
+    /**
+     * English display name.
+     */
+    label: string;
+    /**
+     * Icon name in the ZeyOS Font Awesome kit.
+     */
+    icon: string;
+    /**
+     * Identity colour as a hex string.
+     */
+    color: string;
+    /**
+     * Stock Font Awesome name used when the kit's custom icons are missing.
+     */
+    fa: string;
+};
+/**
+ * @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 declare const zeyosModules: Readonly<Record<string, ZeyosModule>>;
+/**
+ * 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 declare const moduleAliases: Readonly<Record<string, string>>;
+/**
+ * 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 declare function normalizeModuleName(name: string | null | undefined): string;
+/**
+ * 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 declare function moduleInfo(name: string | null | undefined): ZeyosModule;
+/**
+ * Reads a module's identity colour.
+ * @param {string|null|undefined} name Module, entity, or resource name.
+ * @returns {string} Hex colour.
+ */
+export declare function moduleColor(name: string | null | undefined): string;
+/**
+ * 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 declare function moduleIconName(name: string | null | undefined, { standard }?: {
+    standard?: boolean;
+}): string;
+/**
+ * Lists every module key, including runtime registrations.
+ * @returns {string[]} Sorted module keys.
+ */
+export declare function moduleKeys(): string[];
+/**
+ * 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 declare function registerModules(modules: Record<string, string | Partial<ZeyosModule>>): void;
+/**
+ * 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 declare function moduleGlyphColor(background: string): string;

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

@@ -0,0 +1,157 @@
+/** @typedef {{id?: string, field?: string, rawField?: string, dir?: 'asc'|'desc'}} ZxSort */
+export type ZxSort = {
+    id?: string;
+    field?: string;
+    rawField?: string;
+    dir?: 'asc' | 'desc';
+};
+export type ListQueryOptions = {
+    /**
+     * Projection, including aliases and dot joins.
+     */
+    fields?: string[] | Record<string, string>;
+    /**
+     * Zx table sort state.
+     */
+    sort?: ZxSort | ZxSort[];
+    /**
+     * ZeyOS field predicates.
+     */
+    filters?: Record<string, unknown>;
+    /**
+     * Full-text query.
+     */
+    search?: string;
+    /**
+     * UI search-field metadata; ZeyOS searches its indexed text fields.
+     */
+    searchFields?: string[];
+    /**
+     * Page size.
+     */
+    limit?: number;
+    /**
+     * Page offset.
+     */
+    offset?: number;
+    /**
+     * Visibility predicate; null is preserved deliberately.
+     */
+    visibility?: number | null;
+    /**
+     * Request a server-side count instead of counting a returned page.
+     */
+    count?: boolean;
+};
+export type ServerFilterDefinition = {
+    /**
+     * DataFilter state key.
+     */
+    id: string;
+    /**
+     * Raw ZeyOS field.
+     */
+    field?: string;
+    /**
+     * Raw ZeyOS field when the UI id is an alias.
+     */
+    rawField?: string;
+    /**
+     * Raw fields combined as an OR group.
+     */
+    fields?: string[];
+    /**
+     * ZeyOS comparison operator such as `>=` or `IN`.
+     */
+    operator?: string;
+    /**
+     * Semantic value format; date/datetime values become Unix seconds.
+     */
+    format?: string;
+    /**
+     * Semantic value type; date/datetime values become Unix seconds.
+     */
+    type?: string;
+    /**
+     * Preserve an empty-string value instead of treating it as inactive UI state.
+     */
+    includeEmpty?: boolean;
+    /**
+     * Preserve null instead of treating it as inactive UI state.
+     */
+    includeNull?: boolean;
+    /**
+     * Value transform.
+     */
+    transform?: (value: unknown, state: Record<string, unknown>) => unknown;
+    /**
+     * Complete predicate transform.
+     */
+    toFilter?: (value: unknown, state: Record<string, unknown>) => Record<string, unknown> | undefined;
+};
+/**
+ * @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 declare function dateToUnixSeconds(date: Date | null | undefined): number | null;
+/**
+ * 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 declare function unixSecondsToDate(seconds: number | string | null | undefined): Date | null;
+/**
+ * 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 declare function tableSortToQuery(sort: ZxSort | ZxSort[] | null | undefined): string[];
+/**
+ * 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 declare function dataFilterStateToFilters(state: Record<string, unknown>, defs?: ServerFilterDefinition[] | Record<string, string | ServerFilterDefinition>): Record<string, unknown>;
+/**
+ * Builds the body passed to a generated `client.api.list<Resource>()` operation. Predicates are
+ * always emitted under `filters` (plural), which is required for indexed foreign-key matching.
+ * 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 declare function buildListQuery(options?: ListQueryOptions): Record<string, unknown>;

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

@@ -0,0 +1,79 @@
+export type FieldMeta = Record<string, unknown>;
+export type FieldTypeStrategy = {
+    /**
+     * Zx Field descriptor fragment.
+     */
+    field: Record<string, unknown> | ((meta: FieldMeta) => Record<string, unknown>);
+    /**
+     * Zx Table column fragment.
+     */
+    column: Record<string, unknown> | ((meta: FieldMeta) => Record<string, unknown>);
+};
+export type ResolveFieldOptions = {
+    /**
+     * Curated allow-list; its order becomes the output order.
+     */
+    fields?: string[];
+    /**
+     * Field ids to omit.
+     */
+    exclude?: string[];
+    /**
+     * Per-field label overrides.
+     */
+    labels?: Record<string, string>;
+};
+/** @typedef {Record<string, unknown>} FieldMeta */
+/**
+ * @typedef {Object} FieldTypeStrategy
+ * @property {Record<string, unknown>|((meta: FieldMeta) => Record<string, unknown>)} field Zx Field descriptor fragment.
+ * @property {Record<string, unknown>|((meta: FieldMeta) => Record<string, unknown>)} column Zx Table column fragment.
+ */
+/**
+ * @typedef {Object} ResolveFieldOptions
+ * @property {string[]} [fields] Curated allow-list; its order becomes the output order.
+ * @property {string[]} [exclude] Field ids to omit.
+ * @property {Record<string, string>} [labels] Per-field label overrides.
+ */
+/**
+ * Extensible ZeyOS semantic/DB type registry. Keys are normalized to lowercase. Built-in choices:
+ * references use `zxselect`; monetary/numeric data uses `float`; Unix timestamps use date widgets;
+ * enums use native Field options; booleans use `toggle`; arrays use `valuelist`; and long structured
+ * text uses `textarea`. Extend it through {@link registerFieldType} rather than replacing entries.
+ * @type {Record<string, FieldTypeStrategy>}
+ */
+export declare const TYPE_MAP: Record<string, FieldTypeStrategy>;
+/**
+ * Registers or replaces a field/column strategy for a semantic format or DB type.
+ * @param {string} typeOrFormat Semantic format or database type.
+ * @param {FieldTypeStrategy} strategy Field and column descriptor builders/fragments.
+ * @returns {FieldTypeStrategy} The registered strategy.
+ */
+export declare function registerFieldType(typeOrFormat: string, strategy: FieldTypeStrategy): FieldTypeStrategy;
+/**
+ * Converts normalized ZeyOS field metadata to a Zx Field configuration. Semantic `format` wins
+ * over the database `type`; relations and enums are detected before scalar DB types. Read-only
+ * fields become disabled controls and NOT NULL/required metadata becomes `required: true`.
+ * @param {FieldMeta} meta Normalized metadata containing at least `id` or `name`.
+ * @returns {Record<string, unknown>} Plain Zx Field descriptor.
+ */
+export declare function fieldToZxField(meta: FieldMeta): Record<string, unknown>;
+/**
+ * Converts normalized ZeyOS field metadata to a Zx Table column configuration. Renderers return
+ * strings only (never DOM): references/enums show labels, numeric columns are right-aligned,
+ * booleans show a check, and Unix seconds are formatted as dates.
+ * @param {FieldMeta} meta Normalized metadata containing at least `id` or `name`.
+ * @returns {Record<string, unknown>} Plain Zx Table column descriptor.
+ */
+export declare function fieldToZxColumn(meta: FieldMeta): Record<string, unknown>;
+/**
+ * Resolves a resource's runtime client schema into ordered normalized field metadata. The current
+ * client returns names from `schema.fields(resource)` and definitions from
+ * `schema.describe(resource).fields`; embedded `enum` data is authoritative. A compatible
+ * `schema.enums(resource, field)` is used when supplied by another client version/stub.
+ * @param {Record<string, any>} client Injected `@zeyos/client` instance.
+ * @param {string} resource Schema resource name such as `tickets`.
+ * @param {ResolveFieldOptions} [opts={}] Curation options.
+ * @returns {FieldMeta[]} Ordered normalized metadata.
+ */
+export declare function resolveFields(client: Record<string, any>, resource: string, opts?: ResolveFieldOptions): FieldMeta[];