@zeyos/zx 5.0.0 → 5.2.0

package/src/zeyos/query.js

@@ -20,8 +20,10 @@
  * @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 {string} [format] Semantic value format; date/datetime values become Unix seconds. With
+ * a `timeZone` conversion option, a `date` (date-only) value is a calendar day and becomes that
+ * day's midnight in the zone, like a ZeyOS form stores it; `datetime` values stay instants.
+ * @property {string} [type] Semantic value type, read like `format`.
  * @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.
@@ -225,6 +227,16 @@ export function tableSortToQuery(sort) {
   });
 }
 
+/**
+ * @typedef {Object} FilterConversionOptions
+ * @property {string|null} [timeZone] IANA zone of the ZeyOS instance. When given, values of
+ * `date` (date-only) definitions are calendar days: a `Date` counts by its local year, month, and
+ * day, a `YYYY-MM-DD` string by its digits, and either becomes midnight of that day in the zone —
+ * exactly what `calendarDayToUnixSeconds()` and `zeyosForm()` store, so a viewer in another zone
+ * filters `duedate` by the day they picked. `null` names the runtime's own zone. Omitted, dates
+ * convert as exact instants, as they always have.
+ */
+
 /**
  * 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
@@ -232,12 +244,17 @@ export function tableSortToQuery(sort) {
  * 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.
+ * @param {FilterConversionOptions} [options={}] Conversion options, such as the instance zone.
  * @returns {Record<string, unknown>} ZeyOS `filters` object (plural at the call site).
+ * @throws {RangeError} When `options.timeZone` names a zone the runtime does not know.
  */
-export function dataFilterStateToFilters(state, defs = []) {
+export function dataFilterStateToFilters(state, defs = [], options = {}) {
   if (!state || typeof state !== 'object' || Array.isArray(state)) {
     throw new TypeError('DataFilter state must be an object');
   }
+  const calendarDays = Boolean(options) && typeof options === 'object'
+    && Object.prototype.hasOwnProperty.call(options, 'timeZone');
+  const zone = calendarDays ? normalizeTimeZone(options.timeZone) : undefined;
   const definitions = normalizeDefinitions(state, defs);
   const filters = {};
   let groupIndex = 0;
@@ -259,7 +276,7 @@ export function dataFilterStateToFilters(state, defs = []) {
 
     let value = typeof definition.transform === 'function'
       ? definition.transform(original, state)
-      : normalizeFilterValue(original, definition);
+      : normalizeFilterValue(original, definition, calendarDays ? { timeZone: zone } : null);
     if (value === undefined) continue;
     if (definition.operator) value = { [definition.operator]: value };
 
@@ -327,16 +344,30 @@ function normalizeDefinitions(state, defs) {
   return Object.keys(state).map((id) => ({ id, field: id }));
 }
 
-/** @param {unknown} value @param {ServerFilterDefinition} definition @returns {unknown} */
-function normalizeFilterValue(value, definition) {
+/**
+ * @param {unknown} value Filter value.
+ * @param {ServerFilterDefinition} definition Server mapping.
+ * @param {{timeZone: string|undefined}|null} calendar Zone for date-only values, or null to convert
+ * every date as an instant.
+ * @returns {unknown}
+ */
+function normalizeFilterValue(value, definition, calendar = null) {
   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;
+  if (!['date', 'datetime', 'date-time'].includes(semantic)) return value;
+  /** @param {unknown} entry @returns {unknown} */
+  const convert = (entry) => {
+    if (calendar && semantic === 'date') {
+      if (entry instanceof Date) return calendarDayToUnixSeconds(entry, calendar.timeZone);
+      const day = typeof entry === 'string' ? /^(\d{4})-(\d{2})-(\d{2})$/.exec(entry.trim()) : null;
+      if (day) {
+        const midnight = calendarZone(calendar.timeZone).midnightOf(Number(day[1]), Number(day[2]) - 1, Number(day[3]));
+        return Math.floor(midnight / 1000);
+      }
+      return entry;
+    }
+    return entry instanceof Date ? dateToUnixSeconds(entry) : entry;
+  };
+  return Array.isArray(value) ? value.map(convert) : convert(value);
 }
 
 /** @param {ZxSort|ZxSort[]|undefined} sort @param {string[]|Record<string, string>|undefined} fields @returns {ZxSort|ZxSort[]|undefined} */

package/src/zeyos/table.js

@@ -15,7 +15,8 @@ import { normalizeZeyosListResult } from './select.js';
  * @property {string} [timeZone] 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.
  * @property {string|((row: Record<string, unknown>) => unknown)} [rowId='ID'] Row id accessor.
- * @property {number} [pageSize=50] Server page size.
+ * @property {number} [pageSize=50] Server page size, a positive integer. `load({pageSize})` changes
+ * it later — what a `Pagination` page-size select does.
  * @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.
@@ -70,7 +71,12 @@ const TABLE_OPTION_KEYS = [
  * @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`.
  */
 
 /**
@@ -91,8 +97,57 @@ const TABLE_OPTION_KEYS = [
  * @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.
+ * @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 {{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.
  */
 
 /**
@@ -160,9 +215,15 @@ export function buildZeyosTableConfig(client, resource, opts = {}) {
 }
 
 /**
- * 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.
@@ -174,82 +235,156 @@ export function zeyosTable(client, resource, opts = {}) {
   const config = buildZeyosTableConfig(client, resource, opts);
   const facade = connect(client);
   const table = new Table(null, config.tableOptions);
-  const pageSize = normalizePageSize(opts.pageSize);
-  let currentSort = opts.sort ?? null;
-  let currentFilters = copyFilters(opts.filters ?? {});
-  let currentSearch = String(opts.search ?? '');
-  let currentPage = 0;
-  let totalCount = null;
+  let pager;
+  try {
+    pager = createServerPager({
+      client, facade, resource, projection: config.projection, target: table,
+      pageSize: opts.pageSize, sort: opts.sort ?? null, filters: opts.filters ?? {}, search: opts.search,
+      label: 'ZeyOS table'
+    });
+  } catch (error) {
+    table.destroy();
+    throw error;
+  }
+
+  const binding = {
+    table,
+    load: pager.load,
+    setSearch: (search) => pager.load({ search, page: 0 }),
+    setFilters: (filters) => pager.load({ filters, page: 0 }),
+    loadMore: pager.loadMore,
+    get count() { return pager.count; },
+    get page() { return pager.page; },
+    get pageSize() { return pager.pageSize; },
+    get hasMore() { return pager.hasMore; },
+    destroy: () => {
+      if (pager.destroyed) return;
+      pager.destroy();
+      table.destroy();
+    }
+  };
+
+  table.on('sort', (event) => {
+    if (pager.destroyed) return;
+    const id = event.detail?.id;
+    pager.setSort(id == null ? null : { id: String(id), dir: event.detail.dir === 'desc' ? 'desc' : 'asc' });
+    void pager.load({ page: 0 }).catch(() => { /* The connection facade already reported the failure. */ });
+  });
+  return binding;
+}
+
+/**
+ * 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 function createServerPager(options) {
+  const { client, facade, resource, projection, target, searchFields } = options;
+  const label = String(options.label ?? 'ZeyOS binding');
+  let pageSize = normalizePageSize(options.pageSize, label);
+  let sort = options.sort ?? null;
+  let filters = copyFilters(options.filters ?? {}, label);
+  let search = String(options.search ?? '');
+  let page = 0;
+  let count = null;
   let more = false;
-  let requestSequence = 0;
+  let sequence = 0;
+  let destroyed = false;
 
-  const load = async (options = {}) => {
-    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,
-      limit: pageSize,
-      offset: page * pageSize,
-      count: true
-    });
-    const sequence = ++requestSequence;
-    table.setLoading(true);
+  const query = (forPage) => buildListQuery({
+    fields: projection, sort, filters, search, searchFields,
+    limit: pageSize, offset: forPage * pageSize, count: true
+  });
+
+  /**
+   * Validates a load request without applying any of it.
+   * @param {ZeyosTableLoadOptions} [request={}] Load options.
+   * @returns {{page: number, pageSize: number, filters: Record<string, unknown>, search: string}}
+   */
+  const check = (request = {}) => {
+    const source = request && typeof request === 'object' ? request : {};
+    const has = (key) => Object.prototype.hasOwnProperty.call(source, key);
+    return {
+      page: normalizePage(source.page ?? 0, label),
+      pageSize: has('pageSize') && source.pageSize !== undefined
+        ? normalizePageSize(source.pageSize, label) : pageSize,
+      filters: has('filters') ? copyFilters(source.filters ?? {}, label) : filters,
+      search: has('search') ? String(source.search ?? '') : search
+    };
+  };
+
+  /** @param {ZeyosTableLoadOptions} [request={}] @returns {Promise<ZeyosTableLoadResult>} */
+  const load = async (request = {}) => {
+    if (destroyed) throw new Error(`${label} binding has been destroyed`);
+    // Every argument is validated before any state changes, so a call that rejects leaves the
+    // binding exactly as it was: no page size or search half-applied ahead of a bad filter.
+    const next = check(request);
+    const nextPage = next.page;
+    pageSize = next.pageSize;
+    filters = next.filters;
+    search = next.search;
+    const replace = nextPage === 0 || request.replace === true;
+    const sent = query(nextPage);
+    const mine = ++sequence;
+    target.setLoading(true);
     try {
-      const normalized = normalizeZeyosListResult(client, await facade.list(resource, query));
-      const count = normalized.count ?? null;
-      const hasMore = count == null
+      const normalized = normalizeZeyosListResult(client, await facade.list(resource, sent));
+      const total = normalized.count ?? null;
+      const hasMore = total == null
         ? normalized.data.length === pageSize
-        : (page * pageSize + normalized.data.length) < count;
-      if (sequence === requestSequence) {
-        currentPage = page;
-        totalCount = count;
+        : nextPage * pageSize + normalized.data.length < total;
+      if (!destroyed && mine === sequence) {
+        page = nextPage;
+        count = total;
         more = hasMore;
-        if (page === 0) table.setData(normalized.data);
-        else table.addData(normalized.data);
+        if (replace) target.setData(normalized.data);
+        else target.addData(normalized.data);
       }
-      return { data: normalized.data, count, page, hasMore, query };
+      return { data: normalized.data, count: total, page: nextPage, hasMore, query: sent };
     } finally {
-      if (sequence === requestSequence) table.setLoading(false);
+      if (!destroyed && mine === sequence) target.setLoading(false);
     }
   };
 
-  const binding = {
-    table,
+  return {
     load,
-    setSearch: (search) => load({ search, page: 0 }),
-    setFilters: (filters) => load({ filters, page: 0 }),
-    loadMore: () => more ? load({ page: currentPage + 1 }) : Promise.resolve({
-      data: [],
-      count: totalCount,
-      page: currentPage,
-      hasMore: false,
-      query: buildListQuery({
-        fields: config.projection,
-        sort: currentSort,
-        filters: currentFilters,
-        search: currentSearch,
-        limit: pageSize,
-        offset: currentPage * pageSize,
-        count: true
-      })
-    }),
-    get count() { return totalCount; },
-    get page() { return currentPage; },
+    check,
+    loadMore: () => more ? load({ page: page + 1 }) : (destroyed
+      ? Promise.reject(new Error(`${label} binding has been destroyed`))
+      : Promise.resolve({ data: [], count, page, hasMore: false, query: query(page) })),
+    setSort: (next) => { sort = next ?? null; },
+    setQuery: (state = {}) => {
+      const nextFilters = Object.prototype.hasOwnProperty.call(state, 'filters')
+        ? copyFilters(state.filters ?? {}, label) : filters;
+      if (Object.prototype.hasOwnProperty.call(state, 'search')) search = String(state.search ?? '');
+      filters = nextFilters;
+    },
+    reset: () => { page = 0; count = null; more = false; },
+    destroy: () => {
+      if (destroyed) return;
+      destroyed = true;
+      sequence += 1;
+    },
+    get destroyed() { return destroyed; },
+    get count() { return count; },
+    get page() { return page; },
+    get pageSize() { return pageSize; },
     get hasMore() { return more; },
-    destroy: () => table.destroy()
+    get sort() { return sort; },
+    get filters() { return { ...filters }; },
+    get search() { return search; }
   };
-
-  table.on('sort', (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(() => { /* The connection facade already reported the failure. */ });
-  });
-  return binding;
 }
 
 /**
@@ -315,23 +450,28 @@ function schemaHasField(client, resource, id) {
   return Boolean(fields && typeof fields === 'object' && Object.prototype.hasOwnProperty.call(fields, id));
 }
 
-/** @param {unknown} value @returns {number} */
-function normalizePageSize(value) {
-  const number = Number(value ?? 50);
-  return Number.isInteger(number) && number > 0 ? number : 50;
+/** Default server page size shared by `zeyosTable()` and `zeyosView()`. */
+export const DEFAULT_SERVER_PAGE_SIZE = 50;
+
+/** @param {unknown} value @param {string} [label='ZeyOS table'] @returns {number} */
+function normalizePageSize(value, label = 'ZeyOS table') {
+  if (value === undefined || value === null) return DEFAULT_SERVER_PAGE_SIZE;
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < 1) throw new RangeError(`${label} page size must be a positive integer`);
+  return number;
 }
 
-/** @param {unknown} value @returns {number} */
-function normalizePage(value) {
+/** @param {unknown} value @param {string} [label='ZeyOS table'] @returns {number} */
+function normalizePage(value, label = 'ZeyOS table') {
   const number = Number(value);
-  if (!Number.isInteger(number) || number < 0) throw new RangeError('ZeyOS table page must be a non-negative integer');
+  if (!Number.isInteger(number) || number < 0) throw new RangeError(`${label} page must be a non-negative integer`);
   return number;
 }
 
-/** @param {Record<string, unknown>} filters @returns {Record<string, unknown>} */
-function copyFilters(filters) {
+/** @param {unknown} filters @param {string} [label='ZeyOS table'] @returns {Record<string, unknown>} */
+function copyFilters(filters, label = 'ZeyOS table') {
   if (!filters || typeof filters !== 'object' || Array.isArray(filters)) {
-    throw new TypeError('ZeyOS table filters must be an object');
+    throw new TypeError(`${label} filters must be an object`);
   }
-  return { ...filters };
+  return { .../** @type {Record<string, unknown>} */ (filters) };
 }