@everystack/admin 0.4.5 → 0.4.6

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to `@everystack/admin` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.6] - 2026-10-16
+
+### Added
+
+- export editors/rich-html-extensions and editors/unsupported-markup
+- the Edit form sends only the fields you changed, so beforeUpdate hooks and PATCH bodies carry less; a cleared field sends null, and a save with no changes sends nothing
+- wall-clock datetime fields in a fixed business zone ({ timezone, storage: 'wall' } on a naive timestamp column); admin's FieldDefinition is now a union type, so an interface that extends it should extend FieldDefinitionBase instead
+
+### Fixed
+
+- show integrity errors under matching form fields
+- match a column for integrity code 23000 too
+- ResourceShow prints an html or markdown field as text on native
+
 ## [0.4.5] - 2026-10-15
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/admin",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "Declarative admin dashboard framework for PostgREST APIs",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -42,6 +42,16 @@
       "types": "./src/editors/tiptap.tsx",
       "default": "./src/editors/tiptap.tsx"
     },
+    "./editors/rich-html-extensions": {
+      "source": "./src/editors/rich-html-extensions.ts",
+      "types": "./src/editors/rich-html-extensions.ts",
+      "default": "./src/editors/rich-html-extensions.ts"
+    },
+    "./editors/unsupported-markup": {
+      "source": "./src/editors/unsupported-markup.ts",
+      "types": "./src/editors/unsupported-markup.ts",
+      "default": "./src/editors/unsupported-markup.ts"
+    },
     "./package.json": "./package.json"
   },
   "dependencies": {
@@ -51,7 +61,7 @@
   "peerDependencies": {
     "drizzle-orm": "0.41.0",
     "@everystack/api": ">=0.4.4",
-    "@everystack/ui": ">=0.4.2",
+    "@everystack/ui": ">=0.4.5",
     "@tiptap/extension-code": ">=3.0.0",
     "@tiptap/extension-code-block": ">=3.0.0",
     "@tiptap/extension-image": ">=3.0.0",
@@ -117,8 +127,8 @@
     "react-test-renderer": "19.2.0",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
-    "@everystack/ui": "0.4.4",
-    "@everystack/api": "0.4.5"
+    "@everystack/ui": "0.4.5",
+    "@everystack/api": "0.4.6"
   },
   "scripts": {
     "test": "jest",

package/src/adapters/EverystackAdapter.ts

@@ -6,6 +6,7 @@
  */
 
 import { createClient, type Client, type ClientOptions, type QueryBuilder } from '@everystack/api/client';
+import { EverystackApiError } from './EverystackApiError';
 import { toCamelCaseKeys } from '../utils/naming';
 import { mergeFilters, normalizeSearchText } from '../utils/list-query';
 import type { DataAdapter } from './types';
@@ -186,7 +187,7 @@ export class EverystackAdapter implements DataAdapter {
     const result = await this.client.from(resource).insert(data as Record<string, unknown>);
 
     if (result.error) {
-      throw new Error(result.error.message);
+      throw new EverystackApiError(result.error);
     }
 
     return result.data as T;
@@ -213,7 +214,7 @@ export class EverystackAdapter implements DataAdapter {
     const result = await builder.update(data as Record<string, unknown>);
 
     if (result.error) {
-      throw new Error(result.error.message);
+      throw new EverystackApiError(result.error);
     }
 
     const rows = (result.data ?? []) as T[];
@@ -234,7 +235,7 @@ export class EverystackAdapter implements DataAdapter {
     const result = await this.client.from(resource).eq('id', String(id)).remove();
 
     if (result.error) {
-      throw new Error(result.error.message);
+      throw new EverystackApiError(result.error);
     }
 
     if ((result.data ?? []).length === 0) throw new Error(ZERO_ROW_DELETE);
@@ -252,7 +253,7 @@ export class EverystackAdapter implements DataAdapter {
     const result = await this.client.rpc<T>(fn, body);
 
     if (result.error) {
-      throw new Error(result.error.message);
+      throw new EverystackApiError(result.error);
     }
 
     return result.data as T;

package/src/adapters/EverystackApiError.ts

@@ -0,0 +1,18 @@
+import type { ClientError } from '@everystack/api/client';
+
+/** An API refusal with the server's message and optional integrity metadata. */
+export class EverystackApiError extends Error {
+  readonly status: number;
+  readonly code?: string;
+  readonly constraint?: string;
+  readonly column?: string;
+
+  constructor(error: ClientError) {
+    super(error.message);
+    this.name = 'EverystackApiError';
+    this.status = error.status;
+    if (typeof error.code === 'string') this.code = error.code;
+    if (typeof error.constraint === 'string') this.constraint = error.constraint;
+    if (typeof error.column === 'string') this.column = error.column;
+  }
+}

package/src/index.ts

@@ -10,6 +10,9 @@
 export type {
   FieldType,
   FieldDefinition,
+  FieldDefinitionBase,
+  WallClockDatetime,
+  NoTimeZone,
   TagGroup,
   ImageSize,
   CellContext,
@@ -56,6 +59,7 @@ export type {
 } from './adapters/types';
 
 // EverystackAdapter
+export { EverystackApiError } from './adapters/EverystackApiError';
 export { EverystackAdapter, type EverystackAdapterOptions } from './adapters/EverystackAdapter';
 
 // Hooks

package/src/providers/AdminConfigProvider.tsx

@@ -4,9 +4,10 @@
  * Provides AdminConfig to the admin component tree.
  */
 
-import React from 'react';
+import React, { useMemo } from 'react';
 import type { AdminConfig } from '../types';
 import { AdminConfigContext } from '../hooks/useAdminConfig';
+import { validateAdminConfig } from '../utils/wall-clock';
 
 export interface AdminConfigProviderProps {
   config: AdminConfig;
@@ -14,5 +15,8 @@ export interface AdminConfigProviderProps {
 }
 
 export function AdminConfigProvider({ config, children }: AdminConfigProviderProps) {
+  // Setup is where a bad config fails: loudly, naming the resource and field, not later on a
+  // screen that happens to read it.
+  useMemo(() => validateAdminConfig(config), [config]);
   return <AdminConfigContext.Provider value={{ config }}>{children}</AdminConfigContext.Provider>;
 }

package/src/screens/ResourceCreate.tsx

@@ -12,7 +12,9 @@ import { useDataAdapter } from '../hooks/useAdminData';
 import { useEditors } from '../hooks/useEditors';
 import { editorFor } from '../utils/render-resolution';
 import { toDateInputValue } from '../utils/format-cell-value';
+import { integrityErrorField } from '../utils/integrity-error';
 import { missingRequired } from '../utils/required';
+import { isWallClock, wallClockError } from '../utils/wall-clock';
 import { FormField, TextInput, SelectInput, SwitchInput, DateInput, Button, ErrorState } from '@everystack/ui';
 import { ImageFieldInput } from '../components/ImageFieldInput';
 import { AvatarFieldInput } from '../components/AvatarFieldInput';
@@ -77,7 +79,10 @@ export function ResourceCreate({ resource, onSuccess, onCancel }: ResourceCreate
       const value = formData[field.name];
       if (field.validation?.required && missingRequired(field, value)) {
         newErrors[field.name] = field.validation.message ?? `${field.label ?? field.name} is required`;
+        continue;
       }
+      const skipped = wallClockError(field, value);
+      if (skipped) newErrors[field.name] = skipped;
     }
     setErrors(newErrors);
     return newErrors;
@@ -99,7 +104,14 @@ export function ResourceCreate({ resource, onSuccess, onCancel }: ResourceCreate
       const record = await adapter.create(resource, formData as Record<string, unknown> & { id?: never });
       onSuccess?.(record);
     } catch (err) {
-      setSubmitError(err instanceof Error ? err.message : String(err));
+      const message = err instanceof Error ? err.message : String(err);
+      const field = integrityErrorField(err, fields);
+      if (field) {
+        setErrors({ [field.name]: message });
+        requestScrollToFirstError(fields);
+      } else {
+        setSubmitError(message);
+      }
     } finally {
       inFlight.current = false;
       setSubmitting(false);
@@ -220,7 +232,11 @@ function FieldInput({ field, value, error, onChange, values }: FieldInputProps):
     case 'datetime':
       return (
         <FormField label={label} error={error} required={required}>
-          <DateInput value={toDateInputValue(value)} onValueChange={onChange} granularity="datetime" />
+          {isWallClock(field) ? (
+            <DateInput value={toDateInputValue(value)} onValueChange={onChange} timeZone={field.timezone} storage="wall" />
+          ) : (
+            <DateInput value={toDateInputValue(value)} onValueChange={onChange} granularity="datetime" />
+          )}
         </FormField>
       );
 

package/src/screens/ResourceEdit.tsx

@@ -2,7 +2,7 @@
  * ResourceEdit
  *
  * Edit form for an existing resource record.
- * Pre-populates form with existing data, submits via adapter.update().
+ * Pre-populates form with existing data, submits the changed fields via adapter.update().
  */
 
 import React, { useState, useEffect, useCallback, useMemo, useRef } from 'react';
@@ -12,7 +12,10 @@ import { useDataAdapter } from '../hooks/useAdminData';
 import { useEditors } from '../hooks/useEditors';
 import { editorFor } from '../utils/render-resolution';
 import { toDateInputValue } from '../utils/format-cell-value';
+import { integrityErrorField } from '../utils/integrity-error';
 import { missingRequired } from '../utils/required';
+import { isWallClock, wallClockError } from '../utils/wall-clock';
+import { changedFields } from '../utils/changed-fields';
 import { FormField, TextInput, SelectInput, SwitchInput, DateInput, Button, LoadingState, ErrorState } from '@everystack/ui';
 import { ImageFieldInput } from '../components/ImageFieldInput';
 import { AvatarFieldInput } from '../components/AvatarFieldInput';
@@ -49,6 +52,8 @@ export function ResourceEdit({ resource, id, onSuccess, onCancel }: ResourceEdit
   const [submitError, setSubmitError] = useState<string | null>(null);
   // Set synchronously so two presses in one tick (before a re-render) submit once.
   const inFlight = useRef(false);
+  // The values as loaded. A save sends only the fields that differ from these.
+  const initialValues = useRef<Record<string, unknown>>({});
 
   const fields = useMemo(() => {
     if (!resourceConfig) return [];
@@ -80,6 +85,7 @@ export function ResourceEdit({ resource, id, onSuccess, onCancel }: ResourceEdit
       for (const field of fields) {
         initial[field.name] = result[field.name];
       }
+      initialValues.current = initial;
       setFormData(initial);
     } catch (err) {
       setFetchError(err instanceof Error ? err : new Error(String(err)));
@@ -103,11 +109,17 @@ export function ResourceEdit({ resource, id, onSuccess, onCancel }: ResourceEdit
 
   const validate = useCallback((): Record<string, string> => {
     const newErrors: Record<string, string> = {};
+    // Only a value this save would send is checked for a skipped wall time: a stored one the user
+    // did not touch must not block saving another field.
+    const changes = changedFields(fields, initialValues.current, formData);
     for (const field of fields) {
       const value = formData[field.name];
       if (field.validation?.required && missingRequired(field, value)) {
         newErrors[field.name] = field.validation.message ?? `${field.label ?? field.name} is required`;
+        continue;
       }
+      const skipped = field.name in changes ? wallClockError(field, value) : null;
+      if (skipped) newErrors[field.name] = skipped;
     }
     setErrors(newErrors);
     return newErrors;
@@ -121,20 +133,38 @@ export function ResourceEdit({ resource, id, onSuccess, onCancel }: ResourceEdit
       return;
     }
 
+    const changes = changedFields(fields, initialValues.current, formData);
+    // The API refuses an empty update, and there is nothing to save.
+    if (Object.keys(changes).length === 0) {
+      setSubmitError(null);
+      if (record) onSuccess?.(record);
+      return;
+    }
+
     inFlight.current = true;
     setSubmitting(true);
     setSubmitError(null);
 
     try {
-      const updated = await adapter.update(resource, id, formData);
+      const updated = await adapter.update(resource, id, changes);
+      // What was saved is now what is stored: the next save diffs against it.
+      initialValues.current = { ...formData };
+      setRecord(prev => ({ ...prev, ...updated }));
       onSuccess?.(updated);
     } catch (err) {
-      setSubmitError(err instanceof Error ? err.message : String(err));
+      const message = err instanceof Error ? err.message : String(err);
+      const field = integrityErrorField(err, fields);
+      if (field) {
+        setErrors({ [field.name]: message });
+        requestScrollToFirstError(fields);
+      } else {
+        setSubmitError(message);
+      }
     } finally {
       inFlight.current = false;
       setSubmitting(false);
     }
-  }, [adapter, resource, id, formData, validate, onSuccess, fields, requestScrollToFirstError]);
+  }, [adapter, resource, id, formData, record, validate, onSuccess, fields, requestScrollToFirstError]);
 
   if (!resourceConfig) {
     return <ErrorState message={`Resource "${resource}" not found in admin configuration`} />;
@@ -263,7 +293,11 @@ function EditFieldInput({ field, value, error, onChange, record, values }: EditF
     case 'datetime':
       return (
         <FormField label={label} error={error} required={required}>
-          <DateInput value={toDateInputValue(value)} onValueChange={onChange} granularity="datetime" />
+          {isWallClock(field) ? (
+            <DateInput value={toDateInputValue(value)} onValueChange={onChange} timeZone={field.timezone} storage="wall" />
+          ) : (
+            <DateInput value={toDateInputValue(value)} onValueChange={onChange} granularity="datetime" />
+          )}
         </FormField>
       );
 

package/src/screens/ResourceShow.tsx

@@ -6,7 +6,7 @@
  */
 
 import React, { useState, useEffect, useLayoutEffect, useCallback, useMemo, useRef } from 'react';
-import { View, Text, ScrollView } from 'react-native';
+import { View, Text, ScrollView, Platform } from 'react-native';
 import { useAdminConfig } from '../hooks/useAdminConfig';
 import { useDataAdapter } from '../hooks/useAdminData';
 import { LoadingState, ErrorState, Button, Card, Divider, RichContent } from '@everystack/ui';
@@ -23,7 +23,7 @@ import { wrapBareText } from '../components/CellText';
 import { visibleRowActions } from '../utils/row-actions';
 import { restoreAction, softDeleteColumn } from '../utils/standard-actions';
 import { toCamelCase } from '../utils/naming';
-import { formatDateOnly } from '../utils/format-cell-value';
+import { formatDateOnly, formatDateTime } from '../utils/format-cell-value';
 import type { FieldDefinition, DataRecord, ResourceConfig } from '../types';
 import type { DataAdapter } from '../adapters/types';
 
@@ -194,7 +194,7 @@ export function ResourceShow({
 
       {restore && (
         <View testID="soft-delete-banner" className="flex-row items-center justify-between mx-4 mb-4 p-3 rounded-md bg-red-50">
-          <Text className="text-sm text-red-700">{`Deleted ${formatDateTime(deletedAt)}`}</Text>
+          <Text className="text-sm text-red-700">{`Deleted ${formatDateTime(deletedField(resourceConfig, deletedColumn), deletedAt)}`}</Text>
           <RowActionButton action={restore} record={record} recordId={id} adapter={adapter} refetch={refetchQuietly} />
         </View>
       )}
@@ -283,8 +283,9 @@ function FieldRow({ field, value, record, labels }: FieldRowProps): React.ReactE
         <TagsDisplay field={field} value={value} />
       ) : field.type === 'relation' && field.relation && value != null && value !== '' ? (
         <RelationValue resource={field.relation.resource} value={value} labels={labels.get(field.name)} />
-      ) : value != null && (field.format === 'html' || field.format === 'markdown') ? (
-        // Stored rich text is sanitised at render by ui RichContent (web-only).
+      ) : value != null && Platform.OS === 'web' && (field.format === 'html' || field.format === 'markdown') ? (
+        // Stored rich text is sanitised at render by ui RichContent (web-only: it emits a div,
+        // which native has no host component for). Native prints the value as plain text below.
         <RichContent value={value} format={field.format} className="text-sm text-gray-900" />
       ) : (
         <Text className="text-sm text-gray-900">{formatFieldValue(value, field)}</Text>
@@ -293,9 +294,9 @@ function FieldRow({ field, value, record, labels }: FieldRowProps): React.ReactE
   );
 }
 
-function formatDateTime(value: unknown): string {
-  const date = new Date(String(value));
-  return Number.isNaN(date.getTime()) ? String(value) : date.toLocaleString();
+/** The soft-delete column's declared field, so a wall-clock one shows its digits; else a plain datetime. */
+function deletedField(resource: ResourceConfig, column: string | undefined): FieldDefinition {
+  return resource.fields.find(f => f.name === column && f.type === 'datetime') ?? { name: column ?? '', type: 'datetime' };
 }
 
 function formatFieldValue(value: unknown, field: FieldDefinition): string {
@@ -307,7 +308,7 @@ function formatFieldValue(value: unknown, field: FieldDefinition): string {
     case 'date':
       return formatDateOnly(value);
     case 'datetime':
-      return formatDateTime(value);
+      return formatDateTime(field, value);
     case 'json':
       return JSON.stringify(value, null, 2);
     case 'url':

package/src/types.ts

@@ -124,7 +124,8 @@ export interface TagGroup {
   options: Array<{ value: string; label?: string }>;
 }
 
-export interface FieldDefinition {
+/** Every field option except the wall-clock datetime pair (see {@link FieldDefinition}). */
+export interface FieldDefinitionBase {
   /** Field name (matches data key) */
   name: string;
   /** Display label */
@@ -216,6 +217,33 @@ export interface FieldDefinition {
   format?: ContentFormat;
 }
 
+/**
+ * A wall-clock datetime: the column holds "this wall-clock time in one business zone", and every
+ * screen shows and edits it in that zone, whatever the viewer's zone. ONLY for a naive `timestamp`
+ * column (`field.timestamp()`): the API carries its stored digits labelled `Z`, and the admin
+ * writes digits labelled `Z` back. On a `timestamptz` column those digits are a UTC instant and
+ * this option is wrong; the admin cannot see the column type, so it cannot catch that.
+ *
+ * A time the zone skips (a spring-forward gap) is a field error on submit. A time the zone
+ * repeats (a fall-back overlap) is stored as typed.
+ */
+export interface WallClockDatetime {
+  type: 'datetime';
+  /** IANA zone name, e.g. 'America/Los_Angeles'. Checked at setup: an invalid name throws. */
+  timezone: string;
+  /** How the column holds the time. Only 'wall' (a naive `timestamp`) exists today. */
+  storage: 'wall';
+}
+
+/** Any other field: neither `timezone` nor `storage` is set. */
+export interface NoTimeZone {
+  timezone?: undefined;
+  storage?: undefined;
+}
+
+/** `storage` is required whenever `timezone` is set, and both only on a `datetime` field. */
+export type FieldDefinition = FieldDefinitionBase & (WallClockDatetime | NoTimeZone);
+
 // =============================================================================
 // Resource Configuration
 // =============================================================================

package/src/utils/changed-fields.ts

@@ -0,0 +1,54 @@
+/**
+ * The update body for an edit form: only the fields whose value differs from
+ * the value loaded with the record. A field that was never loaded, or that the
+ * user did not touch, stays out, so a save never overwrites a value it did not
+ * mean to change.
+ */
+
+import type { FieldDefinition } from '../types';
+
+/** null, undefined and '' are one "empty" value: an input shows all three as blank. */
+function isEmpty(value: unknown): boolean {
+  return value == null || value === '';
+}
+
+/** Structural equality for form values: primitives, Dates, arrays and plain objects. */
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true;
+  if (a instanceof Date || b instanceof Date) {
+    return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();
+  }
+  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a)) {
+    const other = b as unknown[];
+    return a.length === other.length && a.every((item, i) => deepEqual(item, other[i]));
+  }
+  const left = a as Record<string, unknown>;
+  const right = b as Record<string, unknown>;
+  const keys = Object.keys(left);
+  if (keys.length !== Object.keys(right).length) return false;
+  return keys.every(key => Object.prototype.hasOwnProperty.call(right, key) && deepEqual(left[key], right[key]));
+}
+
+/**
+ * The fields of `current` that differ from `initial`. A field changed to an
+ * empty value is sent as null.
+ */
+export function changedFields(
+  fields: readonly FieldDefinition[],
+  initial: Record<string, unknown>,
+  current: Record<string, unknown>,
+): Record<string, unknown> {
+  const body: Record<string, unknown> = {};
+  for (const { name } of fields) {
+    const before = initial[name];
+    const after = current[name];
+    if (isEmpty(after)) {
+      if (!isEmpty(before)) body[name] = null;
+    } else if (!deepEqual(before, after)) {
+      body[name] = after;
+    }
+  }
+  return body;
+}

package/src/utils/format-cell-value.ts

@@ -8,6 +8,7 @@
 
 import type { FieldDefinition } from '../types';
 import { tagLabel, tagValues } from './tags';
+import { formatWallClock, isWallClock } from './wall-clock';
 
 /**
  * A date-only ISO string has no time-of-day; `new Date(str)` parses it as UTC midnight, and
@@ -50,14 +51,23 @@ export function toDateInputValue(value: unknown): string {
   return value == null ? '' : String(value);
 }
 
+/**
+ * A datetime for display, on the list and the show page alike. A wall-clock field shows its
+ * stored digits and its zone, whatever the viewer's zone; any other datetime is an instant shown
+ * in the viewer's local time.
+ */
+export function formatDateTime(field: FieldDefinition, value: unknown): string {
+  if (isWallClock(field)) return formatWallClock(field, value);
+  const date = new Date(String(value));
+  return Number.isNaN(date.getTime()) ? String(value) : date.toLocaleString();
+}
+
 export function formatCellValue(field: FieldDefinition, value: unknown): string {
   if (value === null || value === undefined) return '—';
 
   switch (field.type) {
-    case 'datetime': {
-      const date = new Date(String(value));
-      return Number.isNaN(date.getTime()) ? String(value) : date.toLocaleString();
-    }
+    case 'datetime':
+      return formatDateTime(field, value);
     case 'date':
       return formatDateOnly(value);
     case 'boolean':

package/src/utils/integrity-error.ts

@@ -0,0 +1,16 @@
+import { EverystackApiError } from '../adapters/EverystackApiError';
+import type { FieldDefinition } from '../types';
+import { toCamelCase, toSnakeCase } from './naming';
+
+const INTEGRITY_CODES = new Set(['23000', '23502', '23503', '23505', '23514', '23P01']);
+
+/** Match only fields in this form; an exact name wins over a converted alias. */
+export function integrityErrorField(error: unknown, fields: FieldDefinition[]): FieldDefinition | undefined {
+  if (!(error instanceof EverystackApiError)
+    || !INTEGRITY_CODES.has(error.code ?? '')
+    || typeof error.column !== 'string') return undefined;
+
+  const column = error.column;
+  return fields.find(field => field.name === column)
+    ?? fields.find(field => field.name === toCamelCase(column) || field.name === toSnakeCase(column));
+}

package/src/utils/wall-clock.ts

@@ -0,0 +1,71 @@
+/**
+ * Wall-clock datetime fields (`type: 'datetime', timezone, storage: 'wall'`): a naive `timestamp`
+ * column holding "this wall-clock time in one business zone". The API carries the stored digits
+ * labelled `Z`; these helpers read those digits literally and never through the viewer's zone.
+ */
+
+import { assertTimeZone, partsToWall, wallTimeExists, wallToParts, zoneAbbreviation } from '@everystack/ui/wall-time';
+import type { AdminConfig, FieldDefinition, FieldDefinitionBase, WallClockDatetime } from '../types';
+
+export type WallClockField = FieldDefinitionBase & WallClockDatetime;
+
+export function isWallClock(field: FieldDefinition): field is WallClockField {
+  return field.storage === 'wall';
+}
+
+/**
+ * A wall value as the string the input and the parser read. A native Date (a custom adapter's
+ * prerogative) carries the digits as its UTC fields, the same as the `Z`-labelled string.
+ */
+function wallString(value: unknown): unknown {
+  return value instanceof Date && !Number.isNaN(value.getTime()) ? value.toISOString() : value;
+}
+
+/**
+ * The stored digits, formatted with no zone shift (a Date built from the digits as UTC, shown in
+ * UTC), then the business zone's abbreviation. An unparseable value passes through untouched.
+ */
+export function formatWallClock(field: WallClockField, value: unknown): string {
+  const parts = wallToParts(wallString(value));
+  if (!parts) return String(value);
+  const digits = new Date(partsToWall(parts)).toLocaleString(undefined, { timeZone: 'UTC' });
+  return `${digits} ${zoneAbbreviation(parts, field.timezone)}`;
+}
+
+/**
+ * The field error for a wall value the business zone's clocks skip (a spring-forward gap), or
+ * null. An overlap time exists (twice) and is accepted as typed. An empty or unparseable value
+ * is not this check's concern.
+ */
+export function wallClockError(field: FieldDefinition, value: unknown): string | null {
+  if (!isWallClock(field)) return null;
+  const parts = wallToParts(wallString(value));
+  if (!parts || wallTimeExists(parts, field.timezone)) return null;
+  return `${field.label ?? field.name} does not exist in ${field.timezone}: clocks skip that time. Pick another time.`;
+}
+
+/**
+ * Checks every field's wall-clock options at setup, loudly: a `timezone` needs `storage: 'wall'`
+ * on a `datetime` field and must be a time zone this engine knows. Config can arrive untyped,
+ * so the TypeScript union is not enough on its own.
+ */
+export function validateAdminConfig(config: AdminConfig): void {
+  for (const resource of config.resources ?? []) {
+    for (const field of resource.fields ?? []) {
+      const raw = field as { name: string; type: unknown; timezone?: unknown; storage?: unknown };
+      if (raw.timezone === undefined && raw.storage === undefined) continue;
+      const where = `Admin resource "${resource.name}", field "${raw.name}"`;
+      if (raw.type !== 'datetime') {
+        throw new TypeError(`${where}: timezone and storage are only for a datetime field, not type ${JSON.stringify(raw.type)}`);
+      }
+      if (raw.storage !== 'wall') {
+        throw new TypeError(`${where}: a timezone needs storage: 'wall' (a naive timestamp column), got storage ${JSON.stringify(raw.storage)}`);
+      }
+      try {
+        assertTimeZone(raw.timezone as string);
+      } catch (err) {
+        throw new RangeError(`${where}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+  }
+}