@zeyos/zx 2.1.0 → 2.2.1

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

@@ -0,0 +1,167 @@
+import { Select } from '../index.js';
+export type ZeyosSelectOptions = {
+    /**
+     * Resource fields or aliased projections.
+     */
+    fields?: string[] | Record<string, string>;
+    /**
+     * Display-label field or reader.
+     */
+    labelKey?: string | ((item: Record<string, unknown>) => string);
+    /**
+     * Value field or reader.
+     */
+    valueKey?: string | ((item: Record<string, unknown>) => unknown);
+    /**
+     * Indexed text fields described to the query builder.
+     */
+    searchFields?: string[];
+    /**
+     * Maximum rows returned for one query.
+     */
+    limit?: number;
+    /**
+     * Persistent ZeyOS field predicates.
+     */
+    filters?: Record<string, unknown>;
+    /**
+     * Initially selected id or record.
+     */
+    value?: unknown;
+    /**
+     * Optional seed records.
+     */
+    items?: Record<string, unknown>[];
+    /**
+     * Option renderer.
+     */
+    renderItem?: ((item: Record<string, unknown>) => Node | string) | null;
+    /**
+     * Selected-value renderer.
+     */
+    renderValue?: ((item: Record<string, unknown>) => string) | null;
+    /**
+     * Whether interaction is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Empty control text.
+     */
+    placeholder?: string;
+    /**
+     * Whether selection may be cleared.
+     */
+    clearable?: boolean;
+    /**
+     * Minimum async query length.
+     */
+    minQuery?: number;
+    /**
+     * Async query delay in milliseconds.
+     */
+    debounce?: number;
+    /**
+     * Maximum option-list height in pixels.
+     */
+    listHeight?: number;
+    /**
+     * Optional group reader.
+     */
+    groupKey?: string | ((item: Record<string, unknown>) => unknown) | null;
+    /**
+     * Local messages.
+     */
+    msg?: Record<string, string> | Record<string, Record<string, string>>;
+    /**
+     * Change listener.
+     */
+    onchange?: (event: CustomEvent<Record<string, unknown>>) => void;
+    /**
+     * Open listener.
+     */
+    onopen?: (event: CustomEvent<Record<string, unknown>>) => void;
+    /**
+     * Close listener.
+     */
+    onclose?: (event: CustomEvent<Record<string, unknown>>) => void;
+    /**
+     * Query listener.
+     */
+    onquery?: (event: CustomEvent<Record<string, unknown>>) => void;
+    /**
+     * Loaded listener.
+     */
+    onloaded?: (event: CustomEvent<Record<string, unknown>>) => void;
+};
+export type ZeyosListResult = {
+    /**
+     * Normalized records.
+     */
+    data: Record<string, unknown>[];
+    /**
+     * Optional server-side count.
+     */
+    count?: number;
+};
+/**
+ * @typedef {Object} ZeyosSelectOptions
+ * @property {string[]|Record<string, string>} [fields] Resource fields or aliased projections.
+ * @property {string|((item: Record<string, unknown>) => string)} [labelKey] Display-label field or reader.
+ * @property {string|((item: Record<string, unknown>) => unknown)} [valueKey='ID'] Value field or reader.
+ * @property {string[]} [searchFields] Indexed text fields described to the query builder.
+ * @property {number} [limit=50] Maximum rows returned for one query.
+ * @property {Record<string, unknown>} [filters] Persistent ZeyOS field predicates.
+ * @property {unknown} [value=null] Initially selected id or record.
+ * @property {Record<string, unknown>[]} [items=[]] Optional seed records.
+ * @property {((item: Record<string, unknown>) => Node|string)|null} [renderItem=null] Option renderer.
+ * @property {((item: Record<string, unknown>) => string)|null} [renderValue=null] Selected-value renderer.
+ * @property {boolean} [disabled=false] Whether interaction is disabled.
+ * @property {string} [placeholder=''] Empty control text.
+ * @property {boolean} [clearable=false] Whether selection may be cleared.
+ * @property {number} [minQuery=0] Minimum async query length.
+ * @property {number} [debounce=200] Async query delay in milliseconds.
+ * @property {number} [listHeight=280] Maximum option-list height in pixels.
+ * @property {string|((item: Record<string, unknown>) => unknown)|null} [groupKey=null] Optional group reader.
+ * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Local messages.
+ * @property {(event: CustomEvent<Record<string, unknown>>) => void} [onchange] Change listener.
+ * @property {(event: CustomEvent<Record<string, unknown>>) => void} [onopen] Open listener.
+ * @property {(event: CustomEvent<Record<string, unknown>>) => void} [onclose] Close listener.
+ * @property {(event: CustomEvent<Record<string, unknown>>) => void} [onquery] Query listener.
+ * @property {(event: CustomEvent<Record<string, unknown>>) => void} [onloaded] Loaded listener.
+ */
+/**
+ * @typedef {Object} ZeyosListResult
+ * @property {Record<string, unknown>[]} data Normalized records.
+ * @property {number} [count] Optional server-side count.
+ */
+/**
+ * Builds the DOM-free Zx Select options used by {@link zeyosSelect}. The generated async filter
+ * sends full-text input as `query`, keeps predicates under `filters` (plural), and normalizes both
+ * array and `{data,count}` responses.
+ * @param {Record<string, any>} client Injected ZeyOS client instance.
+ * @param {string} resource Resource name such as `accounts`.
+ * @param {ZeyosSelectOptions} [opts={}] Query and Select options.
+ * @returns {Record<string, any>} Plain Zx Select options.
+ */
+export declare function buildZeyosSelectConfig(client: Record<string, any>, resource: string, opts?: ZeyosSelectOptions): Record<string, any>;
+/**
+ * Creates an async Zx Select backed by the injected client's generated list operation. A non-null
+ * initial id is hydrated through the resource get operation; await `select.ready` when code must
+ * wait for that label before presenting the control.
+ * @param {Record<string, any>} client Injected ZeyOS client instance.
+ * @param {string} resource Resource name such as `accounts`.
+ * @param {ZeyosSelectOptions} [opts={}] Query and Select options.
+ * @returns {Select & {ready: Promise<Select>}} Configured Select with an initial-value readiness promise.
+ */
+export declare function zeyosSelect(client: Record<string, any>, resource: string, opts?: ZeyosSelectOptions): Select & {
+    ready: Promise<Select>;
+};
+/**
+ * Normalizes list output without importing the client package. If the injected client exposes its
+ * own `normalizeListResult`, that implementation wins; otherwise arrays and `.data` are handled
+ * locally and numeric string counts are accepted.
+ * @param {Record<string, any>} client Injected ZeyOS client instance.
+ * @param {unknown} result Generated list-operation result.
+ * @returns {ZeyosListResult} Normalized rows and optional count.
+ */
+export declare function normalizeZeyosListResult(client: Record<string, any>, result: unknown): ZeyosListResult;

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

@@ -0,0 +1,205 @@
+import { Table } from '../index.js';
+export type ZeyosTableOptions = {
+    /**
+     * Curated ordered field allow-list.
+     */
+    fields?: string[];
+    /**
+     * Per-field label overrides.
+     */
+    labels?: Record<string, string>;
+    /**
+     * Row id accessor.
+     */
+    rowId?: string | ((row: Record<string, unknown>) => unknown);
+    /**
+     * Server page size.
+     */
+    pageSize?: number;
+    /**
+     * Initial server sort.
+     */
+    sort?: {
+        id: string;
+        dir: 'asc' | 'desc';
+    } | null;
+    /**
+     * Initial ZeyOS predicates.
+     */
+    filters?: Record<string, unknown>;
+    /**
+     * Initial full-text query.
+     */
+    search?: string;
+    /**
+     * Row selection mode.
+     */
+    selectable?: false | 'single' | 'multi';
+    /**
+     * Table scroll-region height.
+     */
+    height?: number | string | null;
+    /**
+     * Row activation callback.
+     */
+    onRowClick?: (row: Record<string, unknown>, event: CustomEvent<Record<string, unknown>>) => void;
+};
+export type ZeyosTableConfig = {
+    /**
+     * Ordered normalized schema metadata.
+     */
+    fieldMeta: Record<string, any>[];
+    /**
+     * Generated Zx columns.
+     */
+    columns: Record<string, any>[];
+    /**
+     * API projection including row ids/entity labels.
+     */
+    projection: Record<string, string>;
+    /**
+     * Plain Zx Table options.
+     */
+    tableOptions: Record<string, any>;
+};
+export type ZeyosTableLoadOptions = {
+    /**
+     * Replacement full-text query.
+     */
+    search?: string;
+    /**
+     * Replacement ZeyOS predicates.
+     */
+    filters?: Record<string, unknown>;
+    /**
+     * Zero-based page; pages above zero append rows.
+     */
+    page?: number;
+};
+export type ZeyosTableLoadResult = {
+    /**
+     * Loaded page rows.
+     */
+    data: Record<string, unknown>[];
+    /**
+     * Server count when supplied.
+     */
+    count: number | null;
+    /**
+     * Loaded zero-based page.
+     */
+    page: number;
+    /**
+     * Whether another page is available.
+     */
+    hasMore: boolean;
+    /**
+     * Request passed to the list operation.
+     */
+    query: Record<string, unknown>;
+};
+export type ZeyosTableBinding = {
+    /**
+     * Generated Zx table.
+     */
+    table: Table;
+    /**
+     * Loads/reloads a server page.
+     */
+    load: (options?: ZeyosTableLoadOptions) => Promise<ZeyosTableLoadResult>;
+    /**
+     * Replaces search and reloads page zero.
+     */
+    setSearch: (search: string) => Promise<ZeyosTableLoadResult>;
+    /**
+     * Replaces predicates and reloads page zero.
+     */
+    setFilters: (filters: Record<string, unknown>) => Promise<ZeyosTableLoadResult>;
+    /**
+     * Appends the next page when available.
+     */
+    loadMore: () => Promise<ZeyosTableLoadResult>;
+    /**
+     * Current server count.
+     */
+    count: number | null;
+    /**
+     * Current zero-based page.
+     */
+    page: number;
+    /**
+     * Whether another page is available.
+     */
+    hasMore: boolean;
+    /**
+     * Destroys the generated table.
+     */
+    destroy: () => void;
+};
+/**
+ * @typedef {Object} ZeyosTableOptions
+ * @property {string[]} [fields] Curated ordered field allow-list.
+ * @property {Record<string, string>} [labels] Per-field label overrides.
+ * @property {string|((row: Record<string, unknown>) => unknown)} [rowId='ID'] Row id accessor.
+ * @property {number} [pageSize=50] Server page size.
+ * @property {{id: string, dir: 'asc'|'desc'}|null} [sort=null] Initial server sort.
+ * @property {Record<string, unknown>} [filters] Initial ZeyOS predicates.
+ * @property {string} [search=''] Initial full-text query.
+ * @property {false|'single'|'multi'} [selectable=false] Row selection mode.
+ * @property {number|string|null} [height=null] Table scroll-region height.
+ * @property {(row: Record<string, unknown>, event: CustomEvent<Record<string, unknown>>) => void} [onRowClick] Row activation callback.
+ */
+/**
+ * @typedef {Object} ZeyosTableConfig
+ * @property {Record<string, any>[]} fieldMeta Ordered normalized schema metadata.
+ * @property {Record<string, any>[]} columns Generated Zx columns.
+ * @property {Record<string, string>} projection API projection including row ids/entity labels.
+ * @property {Record<string, any>} tableOptions Plain Zx Table options.
+ */
+/**
+ * @typedef {Object} ZeyosTableLoadOptions
+ * @property {string} [search] Replacement full-text query.
+ * @property {Record<string, unknown>} [filters] Replacement ZeyOS predicates.
+ * @property {number} [page=0] Zero-based page; pages above zero append rows.
+ */
+/**
+ * @typedef {Object} ZeyosTableLoadResult
+ * @property {Record<string, unknown>[]} data Loaded page rows.
+ * @property {number|null} count Server count when supplied.
+ * @property {number} page Loaded zero-based page.
+ * @property {boolean} hasMore Whether another page is available.
+ * @property {Record<string, unknown>} query Request passed to the list operation.
+ */
+/**
+ * @typedef {Object} ZeyosTableBinding
+ * @property {Table} table Generated Zx table.
+ * @property {(options?: ZeyosTableLoadOptions) => Promise<ZeyosTableLoadResult>} load Loads/reloads a server page.
+ * @property {(search: string) => Promise<ZeyosTableLoadResult>} setSearch Replaces search and reloads page zero.
+ * @property {(filters: Record<string, unknown>) => Promise<ZeyosTableLoadResult>} setFilters Replaces predicates and reloads page zero.
+ * @property {() => Promise<ZeyosTableLoadResult>} loadMore Appends 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 {() => void} destroy Destroys the generated table.
+ */
+/**
+ * Builds the DOM-free schema-derived columns and Table options used by {@link zeyosTable}. Entity
+ * projections include an `<field>_label` alias from a real label field on the referenced resource.
+ * Amount fields use each row's real `currency` value for display while retaining the WP14 typed
+ * column strategy and right alignment.
+ * @param {Record<string, any>} client Injected ZeyOS client instance.
+ * @param {string} resource Resource name such as `transactions`.
+ * @param {ZeyosTableOptions} [opts={}] Schema, table, and initial query options.
+ * @returns {ZeyosTableConfig} Plain columns, projection, and Table options.
+ */
+export declare function buildZeyosTableConfig(client: Record<string, any>, resource: string, opts?: ZeyosTableOptions): ZeyosTableConfig;
+/**
+ * Generates a server-backed Zx Table. Sorting automatically reloads page zero. `load({page: 0})`
+ * replaces data, higher pages append it, and `loadMore()` uses `limit`/`offset` plus the returned
+ * count. DataFilter callers can map state with `dataFilterStateToFilters` before `setFilters()`.
+ * @param {Record<string, any>} client Injected ZeyOS client instance.
+ * @param {string} resource Resource name such as `transactions`.
+ * @param {ZeyosTableOptions} [opts={}] Schema, table, and initial query options.
+ * @returns {ZeyosTableBinding} Generated table and server-state methods/getters.
+ */
+export declare function zeyosTable(client: Record<string, any>, resource: string, opts?: ZeyosTableOptions): ZeyosTableBinding;