@everystack/admin 0.4.5 → 0.4.7

package/src/screens/ResourceList.tsx

@@ -16,11 +16,16 @@ const DEFAULT_PER_PAGE = 20;
 /** Sizes the page bar always offers; the resource's own size is added when missing. */
 const PAGE_SIZES = [20, 50, 100];
 
-import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import React, { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
 import { View, Text } from 'react-native';
 import { useAdminConfig } from '../hooks/useAdminConfig';
 import { useAdminData, useDataAdapter } from '../hooks/useAdminData';
 import { useListQuery } from '../hooks/useListQuery';
+import { useViewState, valuesOf, ViewStateContext } from '../hooks/useViewState';
+import { useDateRangeFilters } from '../hooks/useDateRangeFilters';
+import { DateFilterBar, type DateFilterRow } from '../components/DateFilterBar';
+import { dateFilterFields } from '../utils/date-filter-fields';
+import type { DateRangePreset } from '../types';
 import { useAdminNavigation } from '../hooks/useAdminNavigation';
 import { adminHref } from '../utils/admin-routing';
 import { buildListParams, mergeFilters, nextSort, normalizeSearchText, pageForSize, parseListQuery, resolvePageSize } from '../utils/list-query';
@@ -28,7 +33,9 @@ import { resolveScope } from '../utils/scopes';
 import { useScopeCounts } from '../hooks/useScopeCounts';
 import { RESERVED_PARAMS } from '../utils/view-filters';
 import { DataTable, FilterBar, PaginationBar, ScopeTabs, LoadingState, ErrorState, EmptyState, Button, type DataTableColumn } from '@everystack/ui';
+import { DateTimeValue } from '../components/DateTimeValue';
 import { formatCellValue } from '../utils/format-cell-value';
+import { isFieldSortable } from '../utils/field-sortable';
 import { cellRenderKind } from '../utils/render-resolution';
 import { estimateActionsWidth, visibleRowActions } from '../utils/row-actions';
 import { standardRowActions } from '../utils/standard-actions';
@@ -38,6 +45,7 @@ import { InlineEnumCell } from '../components/InlineEnumCell';
 import { wrapBareText } from '../components/CellText';
 import { RelationValue } from '../components/RelationValue';
 import { useRelationLabels, type RelationLabels } from '../hooks/useRelationLabels';
+import { isCannotSortError } from '../adapters/CannotSortError';
 import type { DataAdapter } from '../adapters/types';
 import type { ResourceConfig, FieldDefinition, DataRecord, RowActionConfig } from '../types';
 
@@ -57,10 +65,28 @@ export interface ResourceListProps {
   baseFilter?: Record<string, unknown>;
 }
 
+/** What a row the user added offers: the pinned row's own presets are its config. */
+const ADDED_ROW_PRESETS: DateRangePreset[] = ['today', 'last7Days', 'thisMonth'];
+
 export function ResourceList({ resource, onRowPress, onEditPress, onCreatePress, baseFilter }: ResourceListProps): React.ReactElement {
   const config = useAdminConfig();
   const adapter = useDataAdapter();
   const resourceConfig = config.resources.find(r => r.name === resource);
+  const view = useViewState();
+  const { setParams } = view;
+  const hasViewState = useContext(ViewStateContext) !== null;
+  // Without a URL provider there is nowhere to keep the bounds: no rows, filter, or block.
+  const rangeConfig = hasViewState ? resourceConfig?.dateRange : undefined;
+  const filterable = hasViewState && resourceConfig ? dateFilterFields(resourceConfig) : [];
+  const [addedState, setAddedState] = useState<{ resource: string; fields: string[] }>(() => ({ resource, fields: [] }));
+  const added = addedState.resource === resource ? addedState.fields : [];
+  // The pinned row, then rows the user added, then any datetime column whose URL already holds values.
+  const activeFields = [...new Set([
+    ...(rangeConfig ? [rangeConfig.field] : []),
+    ...added,
+    ...filterable.map(field => field.name).filter(name => valuesOf(view, name).length > 0),
+  ])];
+  const dateRange = useDateRangeFilters(activeFields, field => valuesOf(view, field));
 
   const defaultSort = resourceConfig?.defaultSort;
   const defaultPerPage = resolvePageSize(resourceConfig?.perPage, DEFAULT_PER_PAGE);
@@ -75,9 +101,15 @@ export function ResourceList({ resource, onRowPress, onEditPress, onCreatePress,
     () => resourceConfig?.fields.filter(f => f.searchable).map(f => f.name) ?? [],
     [resourceConfig],
   );
+  // Fields the adapter refused to sort by (CannotSortError), for this resource. Dropping them
+  // from sortableFields drops them from the URL sort and the default sort alike.
+  const [refused, setRefused] = useState<{ resource: string; fields: ReadonlySet<string> }>(
+    () => ({ resource, fields: new Set() }),
+  );
+  const refusedSorts = refused.resource === resource ? refused.fields : undefined;
   const sortableFields = useMemo(
-    () => new Set(resourceConfig?.fields.filter(f => f.sortable).map(f => f.name) ?? []),
-    [resourceConfig],
+    () => new Set(resourceConfig?.fields.filter(f => isFieldSortable(f) && !refusedSorts?.has(f.name)).map(f => f.name) ?? []),
+    [resourceConfig, refusedSorts],
   );
   const activeScope = useMemo(
     () => resolveScope(resourceConfig?.scopes, query.scope),
@@ -99,14 +131,23 @@ export function ResourceList({ resource, onRowPress, onEditPress, onCreatePress,
       ? { [searchFields[0]]: `ilike.*${text}*` }
       : undefined;
   }, [adapter.supportsSearch, query.search, searchFields]);
+  const listFilter = useMemo(
+    () => mergeFilters(mergeFilters(listParams.filter, legacySearchFilter), dateRange.filter),
+    [listParams.filter, legacySearchFilter, dateRange.filter],
+  );
+  // Counts share the range, but each tab supplies its own scope filter.
+  const countsFilter = useMemo(
+    () => mergeFilters(mergeFilters(baseFilter, legacySearchFilter), dateRange.filter),
+    [baseFilter, legacySearchFilter, dateRange.filter],
+  );
 
   // Bumped after an inline edit, so the tab counts follow the change.
   const [countsToken, setCountsToken] = useState(0);
   const scopeCounts = useScopeCounts({
     resource,
     scopes: resourceConfig?.scopes,
-    enabled: Boolean(resourceConfig?.scopeCounts),
-    baseFilter: mergeFilters(baseFilter, legacySearchFilter),
+    enabled: Boolean(resourceConfig?.scopeCounts) && !dateRange.block,
+    baseFilter: countsFilter,
     ...searchParams,
     refreshToken: countsToken,
   });
@@ -121,6 +162,7 @@ export function ResourceList({ resource, onRowPress, onEditPress, onCreatePress,
     page,
     perPage,
   } = useAdminData(resource, {
+    skip: dateRange.block,
     controlled: true,
     page: listParams.page,
     perPage: listParams.perPage,
@@ -129,7 +171,7 @@ export function ResourceList({ resource, onRowPress, onEditPress, onCreatePress,
     ...searchParams,
     select: resourceConfig?.select,
     deleted: listParams.deleted,
-    baseFilter: mergeFilters(listParams.filter, legacySearchFilter),
+    baseFilter: listFilter,
   });
 
   // A column named like a list URL param cannot be filtered from the URL: say so while developing.
@@ -187,7 +229,7 @@ export function ResourceList({ resource, onRowPress, onEditPress, onCreatePress,
   const navigation = useAdminNavigation();
   const columns = useMemo(() => {
     if (!resourceConfig) return [];
-    const cols = fieldsToColumns(resourceConfig, adapter, afterInlineEdit, relationLabels, deletedOnly);
+    const cols = fieldsToColumns(resourceConfig, sortableFields, adapter, afterInlineEdit, relationLabels, deletedOnly);
     const onConfirmDelete = navigation
       ? (record: DataRecord) => {
         const id = (record[resourceConfig.primaryKey ?? 'id'] as string | number) ?? record.id;
@@ -202,7 +244,7 @@ export function ResourceList({ resource, onRowPress, onEditPress, onCreatePress,
       cols.push(actionsColumn(resourceConfig, actions, adapter, refetch));
     }
     return cols;
-  }, [resourceConfig, adapter, refetch, afterInlineEdit, onRowPress, onEditPress, relationLabels, deletedOnly, navigation, resource]);
+  }, [resourceConfig, sortableFields, adapter, refetch, afterInlineEdit, onRowPress, onEditPress, relationLabels, deletedOnly, navigation, resource]);
 
   // The click cycles from what is shown (the default sort included), not from the URL alone.
   const handleSort = useCallback((key: string) => {
@@ -217,16 +259,60 @@ export function ResourceList({ resource, onRowPress, onEditPress, onCreatePress,
 
   const label = resourceConfig.labelPlural ?? resourceConfig.label ?? resourceConfig.name;
   const canCreate = resourceConfig.actions?.create !== false;
+  const rows: DateFilterRow[] = activeFields.map(field => {
+    const state = dateRange.rows.find(row => row.field === field);
+    const pinned = field === rangeConfig?.field;
+    return {
+      field,
+      label: resourceConfig.fields.find(candidate => candidate.name === field)?.label ?? field,
+      value: state?.pair ?? null,
+      invalidReason: state?.status === 'invalid' ? state.reason : undefined,
+      presets: pinned ? rangeConfig?.presets : ADDED_ROW_PRESETS,
+      weekStartsOn: rangeConfig?.weekStartsOn,
+      removable: !pinned,
+    };
+  });
+  const dateFilters = (
+    <DateFilterBar
+      rows={rows}
+      addable={filterable.filter(field => !activeFields.includes(field.name)).map(field => ({ field: field.name, label: field.label ?? field.name }))}
+      onApply={(field, values) => setParams({ [field]: values, page: undefined })}
+      onClear={field => setParams({ [field]: undefined, page: undefined })}
+      onRemove={field => {
+        setAddedState(current => ({ resource, fields: (current.resource === resource ? current.fields : []).filter(name => name !== field) }));
+        if (valuesOf(view, field).length > 0) setParams({ [field]: undefined, page: undefined });
+      }}
+      onAdd={field => setAddedState(current => {
+        const fields = current.resource === resource ? current.fields : [];
+        return { resource, fields: fields.includes(field) ? fields : [...fields, field] };
+      })}
+    />
+  );
+
+  const header = (
+    <View className="flex-row items-center justify-between px-4 py-4">
+      <Text className="text-xl font-bold text-gray-900">{label}</Text>
+      {canCreate && onCreatePress && (
+        <Button label="Create" onPress={onCreatePress} />
+      )}
+    </View>
+  );
+
+  // Check the synchronous range status before any stale rows, errors, totals, or tab counts render.
+  // The title and Create stay: a mistyped date must not take them away.
+  if (dateRange.block) {
+    return (
+      <View className="flex-1">
+        {header}
+        {dateFilters}
+        <EmptyState title="Choose a valid date range, or clear it, to see rows." />
+      </View>
+    );
+  }
 
   return (
     <View className="flex-1">
-      {/* Header */}
-      <View className="flex-row items-center justify-between px-4 py-4">
-        <Text className="text-xl font-bold text-gray-900">{label}</Text>
-        {canCreate && onCreatePress && (
-          <Button label="Create" onPress={onCreatePress} />
-        )}
-      </View>
+      {header}
 
       {/* Filter bar */}
       {searchFields.length > 0 ? (
@@ -236,6 +322,7 @@ export function ResourceList({ resource, onRowPress, onEditPress, onCreatePress,
           value={searchText}
         />
       ) : null}
+      {dateFilters}
       {query.search && searchFields.length > 0 && (!loading || refreshing) && !error ? (
         <Text className="px-4 pb-2 text-sm text-gray-500">
           {`${total} ${total === 1 ? 'result' : 'results'}`}
@@ -254,7 +341,19 @@ export function ResourceList({ resource, onRowPress, onEditPress, onCreatePress,
       {loading && !refreshing ? (
         <LoadingState message={`Loading ${label.toLowerCase()}...`} />
       ) : error ? (
-        <ErrorState message={error.message} onRetry={refetch} />
+        <ErrorState
+          message={error.message}
+          onRetry={isCannotSortError(error)
+            ? () => {
+              const field = error.field;
+              setRefused(previous => ({
+                resource,
+                fields: new Set([...(previous.resource === resource ? previous.fields : []), field]),
+              }));
+              update({ sort: undefined, order: undefined });
+            }
+            : refetch}
+        />
       ) : data.length === 0 ? (
         query.search ? (
           <EmptyState title={`No results for \u201c${query.search}\u201d`} message="Try a different search." />
@@ -302,6 +401,7 @@ export function ResourceList({ resource, onRowPress, onEditPress, onCreatePress,
 
 function fieldsToColumns(
   resourceConfig: ResourceConfig,
+  sortableFields: ReadonlySet<string>,
   adapter: DataAdapter,
   onInlineSaved: () => Promise<void>,
   relationLabels: RelationLabels,
@@ -316,7 +416,7 @@ function fieldsToColumns(
     .map(field => ({
       key: field.name,
       label: field.label ?? field.name,
-      sortable: field.sortable,
+      sortable: sortableFields.has(field.name),
       ...(field.listWidth !== undefined && { width: field.listWidth }),
       ...(field.listPriority !== undefined && { priority: field.listPriority }),
       ...(field.listHideBelow !== undefined && { hideBelow: field.listHideBelow }),
@@ -364,6 +464,7 @@ function cellRenderer(
     case 'image':
       return (value) => <ImageDisplay field={field} value={value} view="list" />;
     default:
+      if (field.type === 'datetime') return value => <DateTimeValue field={field} value={value} />;
       return (value) => (
         <Text className="text-sm text-gray-900" numberOfLines={1}>
           {formatCellValue(field, value)}

package/src/screens/ResourceListView.tsx

@@ -10,6 +10,7 @@
  * link and drill-downs work (`/admin/log_events?level=error`, `?from=&to=`).
  */
 
+import { dateFilterFields } from '../utils/date-filter-fields';
 import React, { useMemo } from 'react';
 import { View } from 'react-native';
 import { useAdminConfig } from '../hooks/useAdminConfig';
@@ -38,7 +39,7 @@ export function ResourceListView({
   const config = useAdminConfig();
   const resourceConfig = config.resources.find(r => r.name === resource);
   const dashboard = resourceConfig?.dashboard;
-  const { params, setParams } = useViewState();
+  const { params, paramValues, setParams } = useViewState();
 
   const dimensions = dashboard?.dimensions ?? [];
   const filters = useMemo(() => paramsToFilters(params, dimensions), [params, dimensions]);
@@ -49,10 +50,13 @@ export function ResourceListView({
     const fromAnalytics = dashboard ? filtersToBaseFilter(filters, dashboard) : undefined;
     const fieldNames = new Set((resourceConfig?.fields ?? []).map(f => f.name));
     const exclude = new Set(dimensions.map(d => d.column));
-    const passthrough = paramsToColumnFilters(params, fieldNames, exclude);
+    // The date range rows own every filterable datetime column's URL values.
+    if (resourceConfig?.dateRange) exclude.add(resourceConfig.dateRange.field);
+    if (resourceConfig) for (const field of dateFilterFields(resourceConfig)) exclude.add(field.name);
+    const passthrough = paramsToColumnFilters(params, fieldNames, exclude, paramValues);
     const merged = { ...fromAnalytics, ...passthrough };
     return Object.keys(merged).length ? merged : undefined;
-  }, [filters, dashboard, params, resourceConfig, dimensions]);
+  }, [filters, dashboard, params, paramValues, resourceConfig, dimensions]);
 
   const showHeader = Boolean(dashboard && baseUrl);
 

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,6 +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 { DateTimeValue } from '../components/DateTimeValue';
 import { formatDateOnly } from '../utils/format-cell-value';
 import type { FieldDefinition, DataRecord, ResourceConfig } from '../types';
 import type { DataAdapter } from '../adapters/types';
@@ -194,7 +195,10 @@ 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>
+          <View>
+            <Text className="text-sm text-red-700">Deleted</Text>
+            <DateTimeValue field={deletedField(resourceConfig, deletedColumn)} value={deletedAt} />
+          </View>
           <RowActionButton action={restore} record={record} recordId={id} adapter={adapter} refetch={refetchQuietly} />
         </View>
       )}
@@ -277,14 +281,17 @@ function FieldRow({ field, value, record, labels }: FieldRowProps): React.ReactE
       </Text>
       {field.render ? (
         <>{wrapBareText(field.render(value, record, { view: 'show' }))}</>
+      ) : field.type === 'datetime' ? (
+        <DateTimeValue field={field} value={value} />
       ) : field.type === 'image' ? (
         <ImageDisplay field={field} value={value} view="show" />
       ) : field.type === 'tags' ? (
         <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 +300,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 {
@@ -306,8 +313,6 @@ function formatFieldValue(value: unknown, field: FieldDefinition): string {
       return value ? 'Yes' : 'No';
     case 'date':
       return formatDateOnly(value);
-    case 'datetime':
-      return formatDateTime(value);
     case 'json':
       return JSON.stringify(value, null, 2);
     case 'url':

package/src/types.ts

@@ -124,15 +124,18 @@ 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 */
   label?: string;
   /** Field type for rendering */
   type: FieldType;
-  /** Whether field is sortable in tables */
+  /** List sorting defaults on by type; false opts out, true opts in unless virtual. */
   sortable?: boolean;
+  /** No backing column (adapter-computed). Never sortable, so the header never sends an order the server would refuse. */
+  virtual?: boolean;
   /** Whether field is searchable */
   searchable?: boolean;
   /** Whether field is filterable */
@@ -216,10 +219,57 @@ 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;
+  /** Literal digits in a naive timestamp column, rather than an instant. */
+  storage: 'wall';
+}
+
+/** An instant datetime. Omitting storage on a datetime has exactly the same meaning. */
+export interface InstantDatetime {
+  type: 'datetime';
+  storage: 'utc';
+  timezone?: undefined;
+}
+
+/** Any field without explicit storage; datetimes are instants by default. */
+export interface NoTimeZone {
+  timezone?: undefined;
+  storage?: undefined;
+}
+
+/** Field-level timezone is a wall-storage exception; instant zones come from AdminConfig. */
+export type FieldDefinition = FieldDefinitionBase & (WallClockDatetime | InstantDatetime | NoTimeZone);
+
 // =============================================================================
 // Resource Configuration
 // =============================================================================
 
+/** Named calendar ranges in the display zone. Declaration only; list behavior comes later. */
+export type DateRangePreset =
+  | 'today' | 'yesterday' | 'last7Days' | 'last30Days'
+  | 'thisWeek' | 'lastWeek' | 'thisMonth' | 'lastMonth';
+
+export interface DateRangeConfig {
+  /** A declared, non-virtual datetime field with instant storage (omitted or 'utc'). */
+  field: string;
+  presets?: DateRangePreset[];
+  /** 0 = Sunday through 6 = Saturday. */
+  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+}
+
 /**
  * One column of a Show/Edit/Create screen. `width`: 'wide' takes the space
  * left over; 'narrow' is a fixed 320px; a number is a fixed width in px. The
@@ -279,6 +329,8 @@ export interface ResourceConfig {
   icon?: string;
   /** Field definitions */
   fields: FieldDefinition[];
+  /** Pin a non-dimension instant datetime's date row. Overrides filterable:false; validated at setup. */
+  dateRange?: DateRangeConfig;
   /** Default sort field */
   defaultSort?: {
     field: string;
@@ -322,6 +374,27 @@ export interface ResourceConfig {
    * through a field `render`. RPC-backed resources ignore it.
    */
   select?: string;
+  /**
+   * The table this resource reads and writes. Default: the resource `name`. Two resources may
+   * share a table, each with its own `where` (single-table inheritance). The URL, nav,
+   * `relation.resource`, scopes and `where` stay keyed by the resource name; the adapter receives
+   * the table name, so an adapter's own per-resource keys (EverystackAdapter `listRpcs` and
+   * `crudRpcs`) use the table name. A resource `dashboard` does NOT follow `table`: its
+   * `dashboard.tableName` still defaults to the resource name, so set it when `table` is set.
+   */
+  table?: string;
+  /**
+   * A view filter and a forced default. It is not authorization: any client with the same token
+   * can address any row through the API. For a boundary, use a role and an RLS policy (or a view).
+   *
+   * Every adapter call for this resource (lists, counts, aggregates, show, update, delete) carries
+   * `column=eq.value` for each entry, after the caller's own filters and winning on the same key.
+   * Create and update bodies carry the values, and Create and Edit render no input for these
+   * columns. Keys are spelled like the resource's field names. RPC-backed resources ignore it.
+   * Equality only: values are plain, never operator strings (see WhereValues).
+   * Example: `where: { type: 'Adventure' }`.
+   */
+  where?: WhereValues;
   /** How the show view fetches one record. 'rpc' calls the role-gated
    *  {camelResource}EventDetail RPC (the resource stays off the REST surface);
    *  'rest' (default) uses adapter.fetchOne. Lets a plain list (no dashboard) —
@@ -421,15 +494,18 @@ export interface ResourceDashboardConfig {
   title?: string;
   /**
    * Physical table for dashboard SQL, may be schema-qualified (e.g. 'ops.runs',
-   * 'logs.crash_reports'). Defaults to the resource name. Required whenever the
-   * exposed resource name differs from the table the raw aggregation queries
-   * must hit — there is no search_path to paper over the difference.
+   * 'logs.crash_reports'). Defaults to the resource `table`, else the resource
+   * name. Required whenever neither is the table the raw aggregation queries
+   * must hit — there is no search_path to paper over the difference. When it
+   * names a table other than the resource's own, the resource `where` is not
+   * applied; set `where` here instead.
    */
   tableName?: string;
   /**
    * Static predicates ANDed into every dashboard query (server-side constants,
    * never user input). The STI case: jobs over ops.runs use
-   * [{ column: 'type', equals: 'job' }].
+   * [{ column: 'type', equals: 'job' }]. On the resource's own table the
+   * resource `where` is ANDed in too and wins on the same column.
    */
   where?: Array<{ column: string; equals: string }>;
   /** The datetime column for the time histogram */
@@ -444,7 +520,7 @@ export interface ResourceDashboardConfig {
   dimensions: DimensionConfig[];
   /** Primary key column(s) for the event list (default: 'id'). Use array for composite keys. */
   primaryKey?: string | string[];
-  /** Columns to display in the event list */
+  /** Columns to display and allow sorting in eventList (snake_case or camelCase aliases). The timestamp column is always sortable; other columns are refused. */
   listColumns: string[];
   /** Columns searchable via ILIKE in the event list */
   searchColumns?: string[];
@@ -560,6 +636,8 @@ export interface StorageConfig {
 }
 
 export interface AdminConfig {
+  /** IANA display zone for instants. Omit to resolve the viewer's browser zone after mount. */
+  timeZone?: string;
   /** Application title */
   title: string;
   /** Application subtitle/description */
@@ -592,11 +670,9 @@ export interface AdminConfig {
  * link (`resource_id` + `resource_type`, often with no foreign key) sets
  * `typeColumn` and `typeValue` as well.
  */
-export interface AssociationConfig {
+interface AssociationBase {
   /** Shown in the preview, e.g. 'Bookmarks'. */
   label: string;
-  /** The related table or resource name, as the adapter knows it. */
-  resource: string;
   /** The column on the related table that holds this record's id. */
   foreignKey: string;
   /** The polymorphic type column on the related table, e.g. 'resource_type'. */
@@ -605,6 +681,23 @@ export interface AssociationConfig {
   typeValue?: string;
 }
 
+/** The related rows, named by exactly one of `resource` or `table`. */
+export type AssociationConfig = AssociationBase & (
+  | {
+      /**
+       * The related table, or a resource name. A resource name is read through that resource's
+       * `table` and `where`. A plain table name that is no resource's name passes unchanged.
+       */
+      resource: string;
+      table?: never;
+    }
+  | {
+      /** The related table, used as is: never read as a resource, no `table` mapping, no `where`. */
+      table: string;
+      resource?: never;
+    }
+);
+
 /**
  * A named filter shown as a tab above a list ("Current", "Draft"). Scopes are
  * ANDed with the search and any column filters.
@@ -624,12 +717,22 @@ export interface ScopeConfig {
 /** Soft-delete reads: 'include' returns live and deleted rows, 'only' deleted rows. */
 export type DeletedMode = 'include' | 'only';
 
+/**
+ * `ResourceConfig.where`: column → the one value every row of the resource has. Equality only: a
+ * value is a plain string, finite number or boolean, matched exactly. It is never an operator
+ * string; `'in.(a,b)'` matches the literal text `in.(a,b)`.
+ */
+export type WhereValues = Record<string, string | number | boolean>;
+
 export interface ListParams {
   /** Page number (1-indexed) */
   page?: number;
   /** Items per page */
   perPage?: number;
-  /** Sort field */
+  /**
+   * The field name the user sorted by. An adapter that cannot order by it MUST
+   * throw CannotSortError(field); it must not fall back to another order.
+   */
   sort?: string;
   /** Sort order */
   order?: 'asc' | 'desc';

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/date-filter-fields.ts

@@ -0,0 +1,32 @@
+import type { FieldDefinition, ResourceConfig } from '../types';
+import { toCamelCase } from './naming';
+import { RESERVED_PARAMS } from './view-filters';
+
+/**
+ * The datetime fields the list can filter with a date range row: real instant columns, not wall-clock,
+ * not opted out with `filterable: false`, and not named like a reserved view param (`page`, `from`, ...), which the URL never carries as a column filter. A resource with a `dashboard` may be listed by the eventList RPC,
+ * which only accepts its list and timestamp columns here unless a field opts in with `filterable: true`.
+ * Dimension columns always belong to analytics, so they never get a date row.
+ */
+export function dateFilterFields(resource: ResourceConfig): FieldDefinition[] {
+  const accepted = resource.dashboard ? acceptedColumns(resource.dashboard) : undefined;
+  return (resource.fields ?? []).filter(field =>
+    field.type === 'datetime'
+    && !field.virtual
+    && field.storage !== 'wall'
+    && field.filterable !== false
+    && !RESERVED_PARAMS.has(field.name)
+    && !isDashboardDimension(resource, field.name)
+    && (accepted === undefined || field.filterable === true || accepted.has(field.name)));
+}
+
+/** SQL names and their camelCase field names identify the same analytics dimension. */
+export function isDashboardDimension(resource: ResourceConfig, field: string): boolean {
+  const name = toCamelCase(field);
+  return resource.dashboard?.dimensions.some(dimension => toCamelCase(dimension.column) === name) ?? false;
+}
+
+function acceptedColumns(dashboard: NonNullable<ResourceConfig['dashboard']>): Set<string> {
+  const columns = [...dashboard.listColumns, dashboard.timestampColumn];
+  return new Set(columns.flatMap(column => [column, toCamelCase(column)]));
+}