@zeyos/zx 2.1.0 → 2.2.0

package/src/elements/reflect.js

@@ -0,0 +1,79 @@
+/**
+ * Attribute value types supported by the custom-element wrappers.
+ * @typedef {'string'|'number'|'boolean'|'json'} AttributeType
+ */
+
+/** Sentinel returned when an attribute value cannot be safely applied. */
+export const INVALID_ATTRIBUTE = Symbol('invalid attribute');
+
+/**
+ * Coerces a serialized attribute into a component option value.
+ * Missing boolean attributes are false; other missing attributes are undefined.
+ *
+ * @param {string|null} value Attribute text, or null when the attribute is absent.
+ * @param {AttributeType} [type='string'] Requested option type.
+ * @param {(message: string) => void} [warn=console.warn] Invalid-value reporter.
+ * @returns {string|number|boolean|unknown|undefined|typeof INVALID_ATTRIBUTE}
+ */
+export function coerceAttribute(value, type = 'string', warn = console.warn) {
+  assertType(type);
+  if (type === 'boolean') return value !== null;
+  if (value === null) return undefined;
+  if (type === 'string') return value;
+
+  if (type === 'number') {
+    const number = Number(value);
+    if (Number.isFinite(number)) return number;
+    warn(`Ignoring invalid number attribute: ${JSON.stringify(value)}`);
+    return INVALID_ATTRIBUTE;
+  }
+
+  try {
+    return JSON.parse(value);
+  } catch {
+    warn(`Ignoring invalid JSON attribute: ${JSON.stringify(value)}`);
+    return INVALID_ATTRIBUTE;
+  }
+}
+
+/**
+ * Serializes a property value for attribute reflection.
+ * A null return value means the corresponding attribute should be removed.
+ *
+ * @param {unknown} value Property value.
+ * @param {AttributeType} [type='string'] Attribute representation.
+ * @param {(message: string) => void} [warn=console.warn] Invalid-value reporter.
+ * @returns {string|null|typeof INVALID_ATTRIBUTE}
+ */
+export function serializeAttribute(value, type = 'string', warn = console.warn) {
+  assertType(type);
+  if (type === 'boolean') return value ? '' : null;
+  if (value === null || value === undefined) return null;
+
+  if (type === 'number') {
+    const number = Number(value);
+    if (Number.isFinite(number)) return String(number);
+    warn(`Ignoring invalid number property: ${String(value)}`);
+    return INVALID_ATTRIBUTE;
+  }
+
+  if (type === 'json') {
+    try {
+      const serialized = JSON.stringify(value);
+      if (serialized !== undefined) return serialized;
+    } catch {
+      // Report through the common warning below.
+    }
+    warn('Ignoring property that cannot be serialized as JSON');
+    return INVALID_ATTRIBUTE;
+  }
+
+  return String(value);
+}
+
+/** @param {unknown} type @returns {asserts type is AttributeType} */
+function assertType(type) {
+  if (!['string', 'number', 'boolean', 'json'].includes(String(type))) {
+    throw new TypeError(`Unknown reflected attribute type: ${String(type)}`);
+  }
+}

package/src/index.js

@@ -0,0 +1,131 @@
+/**
+ * Zx public API.
+ * @module zx
+ */
+
+import { registerChecklistFieldAdapter } from './components/checklist/field-adapter.js';
+import { registerDatePickerFieldAdapters } from './components/date-picker/field-adapter.js';
+import { registerDateRangeFieldAdapter } from './components/date-picker/range-field-adapter.js';
+import { registerDateboxFieldAdapters } from './components/datebox/field-adapter.js';
+import { registerFieldUploadAdapter } from './components/field-upload/field-adapter.js';
+import { registerMultiValueEditorFieldAdapter } from './components/multi-value-editor/field-adapter.js';
+import { registerNumberFieldAdapter } from './components/number-field/field-adapter.js';
+import { registerRatingFieldAdapter } from './components/rating/field-adapter.js';
+import { registerSelectFieldAdapter } from './components/select/field-adapter.js';
+import { registerSliderFieldAdapter } from './components/slider/field-adapter.js';
+import { registerTagPickerFieldAdapter } from './components/tag-picker/field-adapter.js';
+import { registerTimeboxFieldAdapter } from './components/timebox/field-adapter.js';
+import { registerToggleFieldAdapter } from './components/toggle/field-adapter.js';
+import { registerValueListFieldAdapter } from './components/value-list/field-adapter.js';
+
+/**
+ * Registers every component-backed Field adapter. Calling this function repeatedly is safe.
+ * @returns {void}
+ */
+export function registerFieldAdapters() {
+  registerSelectFieldAdapter();
+  registerChecklistFieldAdapter();
+  registerDateboxFieldAdapters();
+  registerDatePickerFieldAdapters();
+  registerDateRangeFieldAdapter();
+  registerTimeboxFieldAdapter();
+  registerValueListFieldAdapter();
+  registerMultiValueEditorFieldAdapter();
+  registerFieldUploadAdapter();
+  registerToggleFieldAdapter();
+  registerNumberFieldAdapter();
+  registerRatingFieldAdapter();
+  registerTagPickerFieldAdapter();
+  registerSliderFieldAdapter();
+}
+
+registerFieldAdapters();
+
+export { Component } from './core/component.js';
+export { h, htmlEscape, resolveElement, highlightMatch } from './core/dom.js';
+export { position } from './core/position.js';
+export { breakpoints, breakpointOf, matchBreakpoint, onBreakpoint } from './core/breakpoint.js';
+export { Http, zeyosService, parseResult } from './core/http.js';
+export { setTranslator, setLanguage, getLanguage, translate, printf } from './core/i18n.js';
+export { focusTrap, rovingTabindex, typeahead } from './core/keyboard.js';
+export {
+  formatDate, parseDate, clampDate, isSameDay, addDays, addMonths, getWeekStart
+} from './core/date.js';
+export {
+  icon, icons, iconNames, registerIcons,
+  configureIcons, getIconConfig, useFontAwesome, useBuiltinIcons, loadFontAwesome
+} from './core/icons.js';
+export {
+  faStyles, faFamilies, faNames, faIconClasses, parseIconSpec, kitUrl, loadFontAwesomeKit
+} from './core/fontawesome.js';
+export {
+  debounce, throttle, uid, deepMerge, isElement, clamp, toArray, groupBy, sortBy, uniqueBy,
+  escapeRegExp
+} from './core/util.js';
+export {
+  formatNumber, formatCurrency, formatPercent, formatFileSize, formatRelativeTime
+} from './core/format.js';
+export { storage } from './core/storage.js';
+export { toCsv, downloadBlob, copyToClipboard } from './core/export.js';
+export { defineElements } from './elements/define.js';
+export { button, buttonGroup } from './components/button/button.js';
+export { badge, badgeGroup } from './components/badge/badge.js';
+export { CheckButton } from './components/check-button/check-button.js';
+export { emptyState } from './components/empty-state/empty-state.js';
+export { spinner } from './components/loading/spinner.js';
+export { ProgressBar } from './components/loading/progress-bar.js';
+export { InlineLoading } from './components/loading/inline-loading.js';
+export { skeleton, skeletonText, skeletonTable } from './components/skeleton/skeleton.js';
+export { stack, grid, aspect } from './components/layout/layout.js';
+export { truncate, isTruncated } from './components/truncate/truncate.js';
+export { copyButton } from './components/copy/copy-button.js';
+export { CopyInput } from './components/copy/copy-input.js';
+export { Toolbar } from './components/toolbar/toolbar.js';
+export { Toggle } from './components/toggle/toggle.js';
+export { Groupbox } from './components/groupbox/groupbox.js';
+export { Panel } from './components/panel/panel.js';
+export { MasterPanel } from './components/master-panel/master-panel.js';
+export {
+  SplitView, clampSize, resolveSize, snapSize
+} from './components/split-view/split-view.js';
+export { Tabbox } from './components/tabbox/tabbox.js';
+export { NavigationBar } from './components/navigation-bar/navigation-bar.js';
+export { Stepper } from './components/stepper/stepper.js';
+export { Breadcrumb } from './components/breadcrumb/breadcrumb.js';
+export { Pagination, paginationRange } from './components/pagination/pagination.js';
+export { Search } from './components/search/search.js';
+export { Message } from './components/message/message.js';
+export { Modal } from './components/modal/modal.js';
+export { Dialog } from './components/dialog/dialog.js';
+export { Dropdown } from './components/dropdown/dropdown.js';
+export { Tooltip, tooltip, describe } from './components/tooltip/tooltip.js';
+export { MenuButton } from './components/menu-button/menu-button.js';
+export { ContextMenu } from './components/context-menu/context-menu.js';
+export { Select } from './components/select/select.js';
+export { Checklist } from './components/checklist/checklist.js';
+export { TagPicker } from './components/tag-picker/tag-picker.js';
+export { NumberField, parseNumber, snapNumber } from './components/number-field/number-field.js';
+export { Rating } from './components/rating/rating.js';
+export { Slider, stepPrecision } from './components/slider/slider.js';
+export { Permission } from './components/permission/permission.js';
+export { DatePicker } from './components/date-picker/date-picker.js';
+export { MonthPicker } from './components/date-picker/month-picker.js';
+export { TimePicker } from './components/date-picker/time-picker.js';
+export { Datebox, DateTimeBox } from './components/datebox/datebox.js';
+export {
+  DateRangePicker, clampRange, defaultDateRangePresets, normalizeRange, rangeNights, rangeStateOf
+} from './components/date-picker/date-range-picker.js';
+export {
+  DateRangeBox, formatRangeText, parseRangeText
+} from './components/datebox/date-range-box.js';
+export { Timebox, splitTime, joinTime } from './components/timebox/timebox.js';
+export { Table } from './components/table/table.js';
+export { TreeView } from './components/tree/tree.js';
+export { Finder } from './components/finder/finder.js';
+export { DataFilter } from './components/data-filter/data-filter.js';
+export { Field } from './components/field/field.js';
+export { Fieldset } from './components/fieldset/fieldset.js';
+export { Form } from './components/form/form.js';
+export { ValueList } from './components/value-list/value-list.js';
+export { MultiValueEditor } from './components/multi-value-editor/multi-value-editor.js';
+export { FieldUpload } from './components/field-upload/field-upload.js';

package/src/zeyos/connect.js

@@ -0,0 +1,142 @@
+import { Message, setLanguage } from '../index.js';
+
+/**
+ * @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 function connect(client, { onError, locale } = {}) {
+  if (!client || typeof client !== 'object' || !client.api || typeof client.api !== 'object') {
+    throw new TypeError('connect() requires a ZeyOS client with an api namespace');
+  }
+  if (onError != null && typeof onError !== 'function') throw new TypeError('onError must be a function');
+
+  const language = locale ?? deriveLocale(client);
+  if (language) setLanguage(String(language));
+
+  const reportError = (error, context) => {
+    if (onError) return onError(error, context);
+    return Message.error(errorMessage(error));
+  };
+
+  const invoke = async (action, resource, input) => {
+    const operation = operationFor(client, action, resource);
+    try {
+      return await client.api[operation](input);
+    } catch (error) {
+      try { reportError(error, { operation, resource }); } catch { /* Preserve the API failure. */ }
+      throw error;
+    }
+  };
+
+  return {
+    client,
+    list: (resource, params = {}) => invoke('list', resource, params),
+    get: (resource, idOrParams, params = {}) => invoke('get', resource,
+      isRecord(idOrParams) ? idOrParams : { ID: idOrParams, ...params }),
+    create: (resource, data) => invoke('create', resource, data),
+    update: (resource, idOrInput, data) => invoke('update', resource,
+      data === undefined && isRecord(idOrInput) ? idOrInput : { ID: idOrInput, body: data ?? {} }),
+    reportError
+  };
+}
+
+/** @param {Record<string, any>} client @returns {unknown} */
+function deriveLocale(client) {
+  return client.locale ?? client.language ?? client.config?.locale ?? client.metadata?.locale ?? null;
+}
+
+/** @param {Record<string, any>} client @param {'list'|'get'|'create'|'update'} action @param {string} resource @returns {string} */
+function operationFor(client, action, resource) {
+  const name = String(resource ?? '').trim();
+  if (!name) throw new TypeError('ZeyOS resource must not be empty');
+  const resourceOperations = typeof client.schema?.operations === 'function'
+    ? client.schema.operations(name)
+    : [];
+  if (Array.isArray(resourceOperations) && resourceOperations.length) {
+    const exactResourceMatches = resourceOperations
+      .filter((operation) => typeof operation === 'string' && operation.toLowerCase().startsWith(action))
+      .sort((left, right) => left.length - right.length);
+    if (exactResourceMatches.length) return exactResourceMatches[0];
+  }
+  const known = Array.isArray(resourceOperations) && resourceOperations.length
+    ? resourceOperations
+    : (typeof client.schema?.operationIds === 'function'
+      ? client.schema.operationIds()
+      : Object.keys(client.api));
+  if (known.includes(name) && name.toLowerCase().startsWith(action)) return name;
+
+  const normalizedResource = normalizeResource(name);
+  const singular = singularize(normalizedResource);
+  const matches = known.filter((operation) => {
+    if (typeof operation !== 'string' || !operation.toLowerCase().startsWith(action)) return false;
+    const suffix = normalizeResource(operation.slice(action.length));
+    return suffix === normalizedResource || suffix === singular || singularize(suffix) === singular;
+  });
+  if (matches.length) return matches.sort((left, right) => left.length - right.length)[0];
+
+  const candidates = action === 'list'
+    ? [`list${pascalCase(name)}`]
+    : [`${action}${pascalCase(singularizeName(name))}`, `${action}${pascalCase(name)}`];
+  const apiKeys = new Set(Object.keys(client.api));
+  const fallback = candidates.find((candidate) => apiKeys.has(candidate));
+  if (fallback) return fallback;
+  throw new RangeError(`No ${action} operation found for ZeyOS resource "${name}"`);
+}
+
+/** @param {unknown} value @returns {boolean} */
+function isRecord(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** @param {unknown} error @returns {string} */
+function errorMessage(error) {
+  if (error instanceof Error && error.message) return error.message;
+  if (error && typeof error === 'object' && typeof error.message === 'string') return error.message;
+  return String(error ?? 'ZeyOS request failed');
+}
+
+/** @param {string} value @returns {string} */
+function normalizeResource(value) {
+  return String(value).replace(/[^a-z\d]/gi, '').toLowerCase();
+}
+
+/** @param {string} value @returns {string} */
+function singularize(value) {
+  if (value.endsWith('ies')) return `${value.slice(0, -3)}y`;
+  if (value.endsWith('sses')) return value.slice(0, -2);
+  if (value.endsWith('s') && !value.endsWith('ss')) return value.slice(0, -1);
+  return value;
+}
+
+/** @param {string} value @returns {string} */
+function singularizeName(value) {
+  const source = String(value);
+  if (/ies$/i.test(source)) return `${source.slice(0, -3)}y`;
+  if (/s$/i.test(source) && !/ss$/i.test(source)) return source.slice(0, -1);
+  return source;
+}
+
+/** @param {string} value @returns {string} */
+function pascalCase(value) {
+  return String(value).split(/[^a-z\d]+/i).filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join('');
+}

package/src/zeyos/form.js

@@ -0,0 +1,254 @@
+import { Form, Message, Select } from '../index.js';
+import { connect } from './connect.js';
+import { dateToUnixSeconds, unixSecondsToDate } from './query.js';
+import { fieldToZxField, resolveFields } from './schema.js';
+import { buildZeyosSelectConfig } from './select.js';
+
+/**
+ * @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 function buildZeyosFormConfig(client, resource, opts = {}) {
+  const fieldMeta = resolveFields(client, resource, opts);
+  const fields = {};
+  const entityFields = [];
+
+  for (const meta of fieldMeta) {
+    const descriptor = fieldToZxField(meta);
+    const referencedResource = descriptor.type === 'zxselect' && typeof descriptor.props?.entity === 'string'
+      ? descriptor.props.entity
+      : null;
+    if (referencedResource) {
+      entityFields.push({ id: String(meta.id), resource: referencedResource });
+      descriptor.props = {
+        ...buildZeyosSelectConfig(client, referencedResource, {
+          clearable: !descriptor.required,
+          placeholder: `Select ${String(descriptor.label).toLowerCase()}`
+        })
+      };
+    }
+    fields[String(meta.id)] = descriptor;
+  }
+
+  return {
+    fieldMeta,
+    fields,
+    entityFields,
+    formOptions: {
+      fieldsets: [{
+        title: String(opts.title ?? ''),
+        columns: normalizeColumns(opts.columns),
+        fields
+      }]
+    },
+    mapFromRecord: (record) => mapFromRecord(record, fieldMeta),
+    mapToRecord: (values) => mapToRecord(values, fieldMeta)
+  };
+}
+
+/**
+ * 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 function zeyosForm(client, resource, opts = {}) {
+  if (opts.onSaved != null && typeof opts.onSaved !== 'function') {
+    throw new TypeError('zeyosForm onSaved must be a function');
+  }
+  const config = buildZeyosFormConfig(client, resource, opts);
+  const facade = connect(client);
+  const form = new Form(null, config.formOptions);
+  let currentId = opts.value?.ID ?? opts.id ?? null;
+  let destroyed = false;
+  let savePending = null;
+
+  const applyRecord = async (record) => {
+    if (!record || typeof record !== 'object' || Array.isArray(record)) {
+      throw new TypeError('ZeyOS form value must be a record');
+    }
+    await Promise.all(config.entityFields.map(async ({ id, resource: referencedResource }) => {
+      const value = record[id];
+      if (value == null) return;
+      const selected = value && typeof value === 'object'
+        ? value
+        : normalizeRecord(await facade.get(referencedResource, value));
+      const select = Select.from(form.getField(id)?.getInput());
+      if (select instanceof Select) select.setItems([selected]);
+    }));
+    if (!destroyed) form.setValues(config.mapFromRecord(record), { silent: true });
+    return record;
+  };
+
+  const load = async (id) => {
+    if (id == null || id === '') throw new TypeError('zeyosForm.load() requires an id');
+    const record = normalizeRecord(await facade.get(resource, id));
+    currentId = record.ID ?? id;
+    await applyRecord(record);
+    return record;
+  };
+
+  const save = () => {
+    if (destroyed) return Promise.reject(new Error('Cannot save a destroyed ZeyOS form'));
+    if (savePending) return savePending;
+    if (!form.submit()) return Promise.resolve(null);
+
+    savePending = (async () => {
+      let payload;
+      try {
+        payload = config.mapToRecord(form.getValues());
+        delete payload.ID;
+      } catch (error) {
+        facade.reportError(error, { operation: 'serialize', resource });
+        throw error;
+      }
+
+      const result = currentId == null
+        ? await facade.create(resource, payload)
+        : await facade.update(resource, { ID: currentId, ...payload });
+      const record = normalizeRecord(result);
+      currentId = record.ID ?? currentId;
+      if (opts.onSaved) {
+        try {
+          await opts.onSaved(record);
+        } catch (error) {
+          facade.reportError(error, { operation: 'onSaved', resource });
+          throw error;
+        }
+      }
+      Message.success(`${recordLabel(record, resource)} saved successfully.`);
+      return record;
+    })().finally(() => {
+      savePending = null;
+    });
+    return savePending;
+  };
+
+  const ready = Object.prototype.hasOwnProperty.call(opts, 'id')
+    ? load(opts.id)
+    : (opts.value ? applyRecord(opts.value) : Promise.resolve(null));
+
+  return {
+    form,
+    ready,
+    load,
+    save,
+    getForm: () => form,
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      form.destroy();
+    }
+  };
+}
+
+/** @param {Record<string, unknown>} record @param {Record<string, any>[]} meta @returns {Record<string, unknown>} */
+function mapFromRecord(record, meta) {
+  const values = {};
+  for (const field of meta) {
+    const id = String(field.id);
+    const value = record[id];
+    values[id] = isDateField(field) && value != null && value !== ''
+      ? unixSecondsToDate(/** @type {number|string} */ (value))
+      : value;
+  }
+  return values;
+}
+
+/** @param {Record<string, unknown>} values @param {Record<string, any>[]} meta @returns {Record<string, unknown>} */
+function mapToRecord(values, meta) {
+  const record = {};
+  for (const field of meta) {
+    const id = String(field.id);
+    let value = values[id];
+    if (isDateField(field)) {
+      value = value == null || value === '' ? null : dateToUnixSeconds(/** @type {Date} */ (value));
+    } else if (hasEnum(field) && isNumericType(field.type) && value !== '' && value != null) {
+      const numeric = Number(value);
+      if (Number.isFinite(numeric)) value = numeric;
+    }
+    record[id] = value;
+  }
+  return record;
+}
+
+/** @param {Record<string, any>} meta @returns {boolean} */
+function isDateField(meta) {
+  const descriptor = fieldToZxField(meta);
+  return descriptor.type === 'date' || descriptor.type === 'datetime';
+}
+
+/** @param {Record<string, any>} meta @returns {boolean} */
+function hasEnum(meta) {
+  return meta.enums != null || meta.enum != null;
+}
+
+/** @param {unknown} type @returns {boolean} */
+function isNumericType(type) {
+  return /^(?:smallint|integer|bigint|int|int2|int4|int8|numeric|decimal)$/i.test(String(type ?? ''));
+}
+
+/** @param {unknown} value @returns {1|2|3} */
+function normalizeColumns(value) {
+  const number = Number(value ?? 2);
+  return /** @type {1|2|3} */ ([1, 2, 3].includes(number) ? number : 2);
+}
+
+/** @param {unknown} result @returns {Record<string, unknown>} */
+function normalizeRecord(result) {
+  if (result && typeof result === 'object' && !Array.isArray(result)) {
+    const nested = result.data;
+    if (nested && typeof nested === 'object' && !Array.isArray(nested)) return nested;
+    return result;
+  }
+  throw new TypeError('ZeyOS operation did not return a record');
+}
+
+/** @param {Record<string, unknown>} record @param {string} resource @returns {string} */
+function recordLabel(record, resource) {
+  for (const key of ['transactionnum', 'name', 'lastname', 'customernum', 'number', 'ID']) {
+    if (record[key] != null && record[key] !== '') return String(record[key]);
+  }
+  return String(resource);
+}