@zeyos/zx 4.4.0 → 5.2.0

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

@@ -1,4 +1,5 @@
 import { Table } from '../index.js';
+export type TableOptions = import('../components/table/table.js').TableOptions;
 export type ZeyosTableOptions = {
     /**
      * Curated ordered field allow-list.
@@ -8,12 +9,23 @@ export type ZeyosTableOptions = {
      * Per-field label overrides.
      */
     labels?: Record<string, string>;
+    /**
+     * Per-field semantic format overrides, such as
+     * `{ duedate: 'date' }` for a Unix-second field that holds a calendar day.
+     */
+    formats?: Record<string, string>;
+    /**
+     * IANA time zone of the ZeyOS instance. Date-only columns show the
+     * calendar day their stored midnight names in this zone; defaults to the runtime's own zone.
+     */
+    timeZone?: string;
     /**
      * Row id accessor.
      */
     rowId?: string | ((row: Record<string, unknown>) => unknown);
     /**
-     * Server page size.
+     * Server page size, a positive integer. `load({pageSize})` changes
+     * it later — what a `Pagination` page-size select does.
      */
     pageSize?: number;
     /**
@@ -43,6 +55,91 @@ export type ZeyosTableOptions = {
      * Row activation callback.
      */
     onRowClick?: (row: Record<string, unknown>, event: CustomEvent<Record<string, unknown>>) => void;
+    /**
+     * Table frame treatment; `'plain'` for a
+     * table inside a pane or card that already draws the box.
+     */
+    variant?: TableOptions['variant'];
+    /**
+     * Whether alternate rows use the zebra background.
+     */
+    zebra?: boolean;
+    /**
+     * Whether column headers stick while scrolling.
+     */
+    stickyHeader?: boolean;
+    /**
+     * Width below which rows stack.
+     */
+    responsive?: TableOptions['responsive'];
+    /**
+     * Rows rendered at first from a loaded page.
+     */
+    growing?: TableOptions['growing'];
+    /**
+     * What the table shows with no rows.
+     */
+    emptyText?: TableOptions['emptyText'];
+    /**
+     * Additional row class callback.
+     */
+    rowClass?: TableOptions['rowClass'];
+    /**
+     * Row property or callback naming each row's kind.
+     */
+    rowKind?: TableOptions['rowKind'];
+    /**
+     * Presentation per row kind.
+     */
+    rowKinds?: TableOptions['rowKinds'];
+    /**
+     * Whether a column visibility chooser is rendered.
+     */
+    columnVisibility?: boolean;
+    /**
+     * Whether the column chooser exposes reorder controls.
+     */
+    columnReorder?: boolean;
+    /**
+     * Initially hidden column ids.
+     */
+    hiddenColumns?: string[];
+    /**
+     * Table `rowclick` listener, beside `onRowClick`.
+     */
+    onrowclick?: TableOptions['onrowclick'];
+    /**
+     * Table `rowdblclick` listener.
+     */
+    onrowdblclick?: TableOptions['onrowdblclick'];
+    /**
+     * Table `sort` listener; the binding reloads either way.
+     */
+    onsort?: TableOptions['onsort'];
+    /**
+     * Table `selectionchange` listener.
+     */
+    onselectionchange?: TableOptions['onselectionchange'];
+    /**
+     * Table `datachange` listener.
+     */
+    ondatachange?: TableOptions['ondatachange'];
+    /**
+     * Table `stackedchange` listener.
+     */
+    onstackedchange?: TableOptions['onstackedchange'];
+    /**
+     * Table `grow` listener.
+     */
+    ongrow?: TableOptions['ongrow'];
+    /**
+     * Table `columnvisibilitychange` listener.
+     */
+    oncolumnvisibilitychange?: TableOptions['oncolumnvisibilitychange'];
+    /**
+     * Table `columnorderchange` listener.
+     */
+    oncolumnorderchange?: TableOptions['oncolumnorderchange'];
 };
 export type ZeyosTableConfig = {
     /**
@@ -72,9 +169,20 @@ export type ZeyosTableLoadOptions = {
      */
     filters?: Record<string, unknown>;
     /**
-     * Zero-based page; pages above zero append rows.
+     * Zero-based page, a non-negative integer. Pages above zero append
+     * rows unless `replace` is set.
      */
     page?: number;
+    /**
+     * Replace the rows with this page instead of appending it — what a
+     * numbered pager needs. Page zero always replaces.
+     */
+    replace?: boolean;
+    /**
+     * New page size for this and every later load; the request offset is
+     * `page * pageSize`.
+     */
+    pageSize?: number;
 };
 export type ZeyosTableLoadResult = {
     /**
@@ -127,28 +235,164 @@ export type ZeyosTableBinding = {
      * Current zero-based page.
      */
     page: number;
+    /**
+     * Current server page size.
+     */
+    pageSize: number;
     /**
      * Whether another page is available.
      */
     hasMore: boolean;
     /**
-     * Destroys the generated table.
+     * Destroys the generated table. A request still in flight is
+     * ignored when it resolves, and later loads reject.
      */
     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.
- */
+export type ServerPagerTarget = {
+    /**
+     * Replaces the rows.
+     */
+    setData: (rows: Record<string, unknown>[]) => unknown;
+    /**
+     * Appends rows.
+     */
+    addData: (rows: Record<string, unknown>[]) => unknown;
+    /**
+     * Shows or hides the loading state.
+     */
+    setLoading: (loading: boolean) => unknown;
+};
+export type ServerPagerOptions = {
+    /**
+     * Injected ZeyOS client (for result normalization).
+     */
+    client: Record<string, any>;
+    /**
+     * Connection facade from `connect(client)`.
+     */
+    facade: {
+        list: (resource: string, query: Record<string, unknown>) => Promise<unknown>;
+    };
+    /**
+     * Resource name.
+     */
+    resource: string;
+    /**
+     * API projection.
+     */
+    projection: Record<string, string>;
+    /**
+     * Component the rows go to.
+     */
+    target: ServerPagerTarget;
+    /**
+     * Initial page size; must be a positive integer.
+     */
+    pageSize?: unknown;
+    /**
+     * Initial sort.
+     */
+    sort?: {
+        id: string;
+        dir: 'asc' | 'desc';
+    } | null;
+    /**
+     * Initial predicates; must be a plain object.
+     */
+    filters?: unknown;
+    /**
+     * Initial full-text query.
+     */
+    search?: unknown;
+    /**
+     * UI search-field metadata passed to `buildListQuery`.
+     */
+    searchFields?: string[];
+    /**
+     * Name used in error messages.
+     */
+    label?: string;
+};
+export type ServerPager = {
+    /**
+     * Loads a page.
+     */
+    load: (options?: ZeyosTableLoadOptions) => Promise<ZeyosTableLoadResult>;
+    /**
+     * Validates load options without applying them; throws what `load()` would reject with.
+     */
+    check: (options?: ZeyosTableLoadOptions) => {
+        page: number;
+        pageSize: number;
+        filters: Record<string, unknown>;
+        search: string;
+    };
+    /**
+     * Appends the next page when available,
+     * else resolves without a request.
+     */
+    loadMore: () => Promise<ZeyosTableLoadResult>;
+    /**
+     * Replaces the sort used
+     * by the next load.
+     */
+    setSort: (sort: {
+        id: string;
+        dir: 'asc' | 'desc';
+    } | null) => void;
+    /**
+     * Replaces filters and
+     * search without loading.
+     */
+    setQuery: (state: {
+        filters?: unknown;
+        search?: unknown;
+    }) => void;
+    /**
+     * Forgets the loaded page, count, and `hasMore`.
+     */
+    reset: () => void;
+    /**
+     * Stops rendering: in-flight responses are ignored, later loads reject.
+     */
+    destroy: () => void;
+    /**
+     * Whether `destroy()` ran.
+     */
+    destroyed: boolean;
+    /**
+     * Current server count.
+     */
+    count: number | null;
+    /**
+     * Current zero-based page.
+     */
+    page: number;
+    /**
+     * Current page size.
+     */
+    pageSize: number;
+    /**
+     * Whether another page is available.
+     */
+    hasMore: boolean;
+    /**
+     * Current sort.
+     */
+    sort: {
+        id: string;
+        dir: 'asc' | 'desc';
+    } | null;
+    /**
+     * Copy of the current predicates.
+     */
+    filters: Record<string, unknown>;
+    /**
+     * Current full-text query.
+     */
+    search: string;
+};
 /**
  * @typedef {Object} ZeyosTableConfig
  * @property {Record<string, any>[]} fieldMeta Ordered normalized schema metadata.
@@ -160,7 +404,12 @@ export type ZeyosTableBinding = {
  * @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.
+ * @property {number} [page=0] Zero-based page, a non-negative integer. Pages above zero append
+ * rows unless `replace` is set.
+ * @property {boolean} [replace] Replace the rows with this page instead of appending it — what a
+ * numbered pager needs. Page zero always replaces.
+ * @property {number} [pageSize] New page size for this and every later load; the request offset is
+ * `page * pageSize`.
  */
 /**
  * @typedef {Object} ZeyosTableLoadResult
@@ -179,14 +428,61 @@ export type ZeyosTableBinding = {
  * @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 {number} pageSize Current server page size.
+ * @property {boolean} hasMore Whether another page is available.
+ * @property {() => void} destroy Destroys the generated table. A request still in flight is
+ * ignored when it resolves, and later loads reject.
+ */
+/**
+ * The surface a server pager renders into: a Zx `Table`, or any RecordView.
+ * @typedef {Object} ServerPagerTarget
+ * @property {(rows: Record<string, unknown>[]) => unknown} setData Replaces the rows.
+ * @property {(rows: Record<string, unknown>[]) => unknown} addData Appends rows.
+ * @property {(loading: boolean) => unknown} setLoading Shows or hides the loading state.
+ */
+/**
+ * @typedef {Object} ServerPagerOptions
+ * @property {Record<string, any>} client Injected ZeyOS client (for result normalization).
+ * @property {{list: (resource: string, query: Record<string, unknown>) => Promise<unknown>}} facade
+ * Connection facade from `connect(client)`.
+ * @property {string} resource Resource name.
+ * @property {Record<string, string>} projection API projection.
+ * @property {ServerPagerTarget} target Component the rows go to.
+ * @property {unknown} [pageSize=50] Initial page size; must be a positive integer.
+ * @property {{id: string, dir: 'asc'|'desc'}|null} [sort=null] Initial sort.
+ * @property {unknown} [filters={}] Initial predicates; must be a plain object.
+ * @property {unknown} [search=''] Initial full-text query.
+ * @property {string[]} [searchFields] UI search-field metadata passed to `buildListQuery`.
+ * @property {string} [label='ZeyOS binding'] Name used in error messages.
+ */
+/**
+ * @typedef {Object} ServerPager
+ * @property {(options?: ZeyosTableLoadOptions) => Promise<ZeyosTableLoadResult>} load Loads a page.
+ * @property {(options?: ZeyosTableLoadOptions) => {page: number, pageSize: number, filters: Record<string, unknown>, search: string}} check
+ * Validates load options without applying them; throws what `load()` would reject with.
+ * @property {() => Promise<ZeyosTableLoadResult>} loadMore Appends the next page when available,
+ * else resolves without a request.
+ * @property {(sort: {id: string, dir: 'asc'|'desc'}|null) => void} setSort Replaces the sort used
+ * by the next load.
+ * @property {(state: {filters?: unknown, search?: unknown}) => void} setQuery Replaces filters and
+ * search without loading.
+ * @property {() => void} reset Forgets the loaded page, count, and `hasMore`.
+ * @property {() => void} destroy Stops rendering: in-flight responses are ignored, later loads reject.
+ * @property {boolean} destroyed Whether `destroy()` ran.
+ * @property {number|null} count Current server count.
+ * @property {number} page Current zero-based page.
+ * @property {number} pageSize Current page size.
  * @property {boolean} hasMore Whether another page is available.
- * @property {() => void} destroy Destroys the generated table.
+ * @property {{id: string, dir: 'asc'|'desc'}|null} sort Current sort.
+ * @property {Record<string, unknown>} filters Copy of the current predicates.
+ * @property {string} search Current full-text query.
  */
 /**
  * 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.
+ * column strategy and right alignment. Enum columns show labels, date-only columns calendar days in
+ * `timeZone`, and Table presentation options and listeners pass through to `tableOptions`.
  * @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.
@@ -194,12 +490,39 @@ export type ZeyosTableBinding = {
  */
 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()`.
+ * Generates a server-backed Zx Table. Sorting automatically reloads page zero. Paging is
+ * zero-based: `load({page: 0})` replaces data, higher pages append it — load-more paging, which
+ * `loadMore()` drives from `limit`/`offset` plus the returned count — and `replace: true` replaces
+ * at any page, which is what a numbered `Pagination` needs. `Pagination` is one-based, so its
+ * `change` maps as `load({page: detail.page - 1, pageSize: detail.pageSize, replace: true})`, the
+ * request offset being `(page - 1) * pageSize`; feed `result.count` back with `setTotal()`.
+ * DataFilter callers can map state with `dataFilterStateToFilters` before `setFilters()`.
+ * Paging is shared with `zeyosView()` through {@link createServerPager}: the same validation, and
+ * a response that resolves after `destroy()` never touches the destroyed table.
+ * Table presentation options (`variant`, `zebra`, `stickyHeader`, `responsive`, `emptyText`, …) and
+ * listeners are passed through to the generated Table.
  * @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;
+/**
+ * The one server-paging loader behind {@link zeyosTable} and `zeyosView`, so the two bindings
+ * cannot drift apart. It builds the list request (`limit = pageSize`, `offset = page * pageSize`,
+ * always with `count`), renders the response into its target — page zero or `replace` replaces
+ * the rows, a higher page appends them — and keeps `count`, `page`, and `hasMore`.
+ *
+ * Only the newest request may render: an older one that resolves late is returned to its caller
+ * but never touches the target. After `destroy()` nothing renders at all — a response that arrives
+ * afterwards is ignored, the loading state is left alone — and further loads reject.
+ *
+ * Validation is strict and the same for both bindings: a page must be a non-negative integer and a
+ * page size a positive integer (`RangeError`), filters a plain object (`TypeError`). Every argument
+ * of a call is checked before any of it is applied, so a rejected call changes nothing.
+ * @param {ServerPagerOptions} options Pager configuration.
+ * @returns {ServerPager}
+ */
+export declare function createServerPager(options: ServerPagerOptions): ServerPager;
+/** Default server page size shared by `zeyosTable()` and `zeyosView()`. */
+export declare const DEFAULT_SERVER_PAGE_SIZE = 50;

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

@@ -46,6 +46,16 @@ export type ZeyosViewOptions = {
      * Per-field label overrides.
      */
     labels?: Record<string, string>;
+    /**
+     * Per-field semantic format overrides, such as
+     * `{ duedate: 'date' }` for a Unix-second field that holds a calendar day.
+     */
+    formats?: Record<string, string>;
+    /**
+     * IANA time zone of the ZeyOS instance; date-only fields show the
+     * calendar day their stored midnight names in it. Defaults to the runtime's own zone.
+     */
+    timeZone?: string;
     /**
      * View descriptor overrides.
      */
@@ -55,7 +65,8 @@ export type ZeyosViewOptions = {
      */
     recordId?: string | ((record: Record<string, unknown>) => unknown);
     /**
-     * Server page size.
+     * Server page size, a positive integer — the same default and
+     * validation as `zeyosTable()`, because both bindings page through one shared loader.
      */
     pageSize?: number;
     /**
@@ -141,9 +152,18 @@ export type ZeyosViewLoadOptions = {
      */
     filters?: Record<string, unknown>;
     /**
-     * Zero-based page; pages above zero append.
+     * Zero-based page, a non-negative integer; pages above zero append
+     * unless `replace` is set.
      */
     page?: number;
+    /**
+     * Replace the records with this page instead of appending it.
+     */
+    replace?: boolean;
+    /**
+     * New page size for this and every later load.
+     */
+    pageSize?: number;
 };
 export type ZeyosViewLoadResult = {
     /**
@@ -246,6 +266,10 @@ export type ZeyosViewBinding = {
      * Current zero-based page.
      */
     page: number;
+    /**
+     * Current server page size.
+     */
+    pageSize: number;
     /**
      * Whether another page is available.
      */