@everystack/admin 0.4.5 → 0.4.7

package/CHANGELOG.md

@@ -4,6 +4,44 @@ All notable changes to `@everystack/admin` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.7] - 2026-10-18
+
+### BREAKING CHANGES
+
+- list fields sort by default; the API refuses an order it cannot apply (#92)
+- datetimes show in the viewer's zone and edit round-trip in it (#94)
+- eventList applies the list-protocol filter; a time bound replaces the default window
+- Add filter on the list; a datetime column adds its own date range row that owns every URL value of that column (see docs/upgrading.md)
+
+### Added
+
+- add ResourceConfig.where and table, a view filter and forced default for one slice of a table
+- date foundations: zone resolver, DST-correct day bounds, zone-aware DateInput (#93)
+- date-range helpers: DST-correct UTC bounds and presets
+- DateConditionInput range mode: draft From/To days, Apply once, presets fill
+- block list fetches until the date range and its zone are known
+- eventList ilike on search columns, with literal matching and no lone surrogates
+- repeated URL parameters survive the view state; ignoreParams for route params
+- read a date range back from its URL instants; refuse what the URL cannot carry
+- the list date range lives in native repeated instant keys on its field
+- which datetime columns the list can filter with a date range row
+- the DateInput calendar floats above the page and closes on an outside press or Escape
+- the Add filter menu is a floating card that closes on an outside press or Escape
+
+## [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.7",
   "description": "Declarative admin dashboard framework for PostgREST APIs",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -32,6 +32,11 @@
       "types": "./src/rpc/resource-dashboard-rpc.ts",
       "default": "./src/rpc/resource-dashboard-rpc.ts"
     },
+    "./sortable": {
+      "source": "./src/utils/field-sortable.ts",
+      "types": "./src/utils/field-sortable.ts",
+      "default": "./src/utils/field-sortable.ts"
+    },
     "./presets/twitter": {
       "source": "./src/presets/twitter.ts",
       "types": "./src/presets/twitter.ts",
@@ -42,6 +47,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": {
@@ -50,8 +65,8 @@
   },
   "peerDependencies": {
     "drizzle-orm": "0.41.0",
-    "@everystack/api": ">=0.4.4",
-    "@everystack/ui": ">=0.4.2",
+    "@everystack/api": ">=0.4.7",
+    "@everystack/ui": ">=0.4.6",
     "@tiptap/extension-code": ">=3.0.0",
     "@tiptap/extension-code-block": ">=3.0.0",
     "@tiptap/extension-image": ">=3.0.0",
@@ -113,12 +128,14 @@
     "jsdom": "^20.0.3",
     "parse5": "^7.3.0",
     "react": "19.2.0",
+    "react-dom": "19.2.0",
     "react-native": "0.83.6",
+    "react-native-web": "0.20.0",
     "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/api": "0.4.7",
+    "@everystack/ui": "0.4.6"
   },
   "scripts": {
     "test": "jest",

package/src/adapters/CannotSortError.ts

@@ -0,0 +1,19 @@
+/** An adapter cannot order a list by the field the admin sent. */
+export class CannotSortError extends Error {
+  readonly field: string;
+
+  constructor(field: string) {
+    super(`Cannot sort by ${field}`);
+    this.name = 'CannotSortError';
+    this.field = field;
+  }
+}
+
+/**
+ * Whether an error is a sort refusal. Also matches one thrown by another copy of
+ * this package, where `instanceof` fails: an Error named 'CannotSortError' with a string field.
+ */
+export function isCannotSortError(error: unknown): error is CannotSortError {
+  return error instanceof CannotSortError
+    || (error instanceof Error && error.name === 'CannotSortError' && typeof (error as { field?: unknown }).field === 'string');
+}

package/src/adapters/EverystackAdapter.ts

@@ -6,6 +6,8 @@
  */
 
 import { createClient, type Client, type ClientOptions, type QueryBuilder } from '@everystack/api/client';
+import { EverystackApiError } from './EverystackApiError';
+import { CannotSortError } from './CannotSortError';
 import { toCamelCaseKeys } from '../utils/naming';
 import { mergeFilters, normalizeSearchText } from '../utils/list-query';
 import type { DataAdapter } from './types';
@@ -45,7 +47,7 @@ const ZERO_ROW_DELETE = 'No row was deleted. It may not exist, or you may not ha
 export interface EverystackAdapterOptions extends ClientOptions {
   /**
    * Resources whose list rows come from an RPC instead of the PostgREST table.
-   * Maps resource name → RPC function name. The RPC speaks the same list
+   * Maps resource name (the table name, when the resource sets `table`) → RPC function name. The RPC speaks the same list
    * protocol — body `{ limit, offset, sort, dir, filter }`, result
    * `{ data, total }` — so the list UI is identical to the REST path. Used to
    * serve DB-free observability tables (logs, crashes) from the S3 archive.
@@ -53,7 +55,7 @@ export interface EverystackAdapterOptions extends ClientOptions {
   listRpcs?: Record<string, string>;
   /**
    * Resources whose single-record reads + writes go through an RPC instead of
-   * the PostgREST table. Maps resource name → RPC function name. The RPC is
+   * the PostgREST table. Maps resource name (the table name, when the resource sets `table`) → RPC function name. The RPC is
    * action-dispatched: body `{ action: 'get'|'create'|'update'|'delete', id?,
    * data? }` → the record (get/create/update) or `{}` (delete). Used to serve
    * DB-free mutable config (alert rules) from an S3 object with CAS. Pair with
@@ -93,14 +95,22 @@ export class EverystackAdapter implements DataAdapter {
         : params.filter;
       // Accept either the S3 list shape ({ data, total }) or the dashboard eventList shape
       // ({ rows, total }) so a resource can be served by either kind of RPC.
-      const result = await this.rpc<{ data?: T[]; rows?: T[]; total: number }>(listRpc, {
-        limit: perPage,
-        offset,
-        sort: params.sort,
-        dir: params.order ?? 'asc',
-        filter,
-        ...(params.deleted ? { deleted: params.deleted } : {}),
-      });
+      let result: { data?: T[]; rows?: T[]; total: number };
+      try {
+        result = await this.rpc<typeof result>(listRpc, {
+          limit: perPage,
+          offset,
+          sort: params.sort,
+          dir: params.order ?? 'asc',
+          filter,
+          ...(params.deleted ? { deleted: params.deleted } : {}),
+        });
+      } catch (error) {
+        if (params.sort && error instanceof EverystackApiError && error.status === 400 && error.code === 'invalid_order') {
+          throw new CannotSortError(params.sort);
+        }
+        throw error;
+      }
       // Normalize row keys to camelCase so the list columns resolve regardless of whether
       // the RPC returns snake_case (e.g. jobsEventList over ops.runs) or camelCase (S3 lists,
       // already camelCase so this is a no-op). The REST path is camelCase too.
@@ -132,6 +142,9 @@ export class EverystackAdapter implements DataAdapter {
     const result = await builder.executeWithCount();
 
     if (result.error) {
+      if (params.sort && result.error.status === 400 && result.error.code === 'invalid_order') {
+        throw new CannotSortError(params.sort);
+      }
       throw new Error(result.error.message);
     }
 
@@ -146,7 +159,7 @@ export class EverystackAdapter implements DataAdapter {
   async fetchOne<T extends DataRecord = DataRecord>(
     resource: string,
     id: string | number,
-    params?: { select?: string; deleted?: DeletedMode },
+    params?: { select?: string; deleted?: DeletedMode; filter?: Record<string, unknown> },
   ): Promise<T> {
     // RPC-backed single read (e.g. DB-free alert rules from the S3 config object).
     const crudRpc = this.crudRpcs[resource];
@@ -160,7 +173,7 @@ export class EverystackAdapter implements DataAdapter {
       return record;
     }
 
-    let builder = this.client.from(resource).eq('id', String(id));
+    let builder = applyFilters(this.client.from(resource).eq('id', String(id)), params?.filter);
     if (params?.select) builder = builder.select(params.select);
     if (params?.deleted) builder = builder.deleted(params.deleted);
     const result = await builder.single();
@@ -186,7 +199,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;
@@ -196,7 +209,7 @@ export class EverystackAdapter implements DataAdapter {
     resource: string,
     id: string | number,
     data: Partial<T>,
-    params?: { deleted?: DeletedMode },
+    params?: { deleted?: DeletedMode; filter?: Record<string, unknown> },
   ): Promise<T> {
     const crudRpc = this.crudRpcs[resource];
     if (crudRpc) {
@@ -208,12 +221,12 @@ export class EverystackAdapter implements DataAdapter {
       }));
     }
 
-    let builder = this.client.from(resource).eq('id', String(id));
+    let builder = applyFilters(this.client.from(resource).eq('id', String(id)), params?.filter);
     if (params?.deleted) builder = builder.deleted(params.deleted);
     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[];
@@ -224,17 +237,17 @@ export class EverystackAdapter implements DataAdapter {
     return rows[0];
   }
 
-  async delete(resource: string, id: string | number): Promise<void> {
+  async delete(resource: string, id: string | number, params?: { filter?: Record<string, unknown> }): Promise<void> {
     const crudRpc = this.crudRpcs[resource];
     if (crudRpc) {
       this.rpcResult(await this.rpc<{ error?: string }>(crudRpc, { action: 'delete', id: String(id) }));
       return;
     }
 
-    const result = await this.client.from(resource).eq('id', String(id)).remove();
+    const result = await applyFilters(this.client.from(resource).eq('id', String(id)), params?.filter).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 +265,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/adapters/types.ts

@@ -34,11 +34,18 @@ export interface DataAdapter {
    * Fetch a single record by ID. `params.select` is a PostgREST select string,
    * embeds included. EverystackAdapter ignores it on the crudRpcs branch.
    * `params.deleted` reads a soft-deleted row (see ListParams.deleted).
+   *
+   * `params.filter` (same shape as ListParams.filter) is ANDed with the id: a row
+   * that matches the id but not the filter is not found. fetchOne, update and
+   * delete must all honor it in the one request they send. `ResourceConfig.where`
+   * depends on it, and the types cannot enforce it: a custom adapter that drops it
+   * lets an id-addressed call reach a row outside the `where` slice.
+   * EverystackAdapter honors it on the REST path; its crudRpcs branch ignores it.
    */
   fetchOne<T extends DataRecord = DataRecord>(
     resource: string,
     id: string | number,
-    params?: { select?: string; deleted?: DeletedMode }
+    params?: { select?: string; deleted?: DeletedMode; filter?: Record<string, unknown> }
   ): Promise<T>;
 
   /**
@@ -49,18 +56,20 @@ export interface DataAdapter {
   /**
    * Update an existing record. `params.deleted` lets the write match a
    * soft-deleted row: Restore sends `{ [column]: null }` with `{ deleted: 'only' }`.
+   * `params.filter` is ANDed with the id in the write itself (see fetchOne).
    */
   update<T extends DataRecord = DataRecord>(
     resource: string,
     id: string | number,
     data: Partial<T>,
-    params?: { deleted?: DeletedMode }
+    params?: { deleted?: DeletedMode; filter?: Record<string, unknown> }
   ): Promise<T>;
 
   /**
-   * Delete a record
+   * Delete a record. `params.filter` is ANDed with the id in the delete itself
+   * (see fetchOne).
    */
-  delete(resource: string, id: string | number): Promise<void>;
+  delete(resource: string, id: string | number, params?: { filter?: Record<string, unknown> }): Promise<void>;
 
   /**
    * Fetch aggregate data (count, sum, avg, min, max) with optional grouping.

package/src/components/DateConditionInput.tsx

@@ -0,0 +1,148 @@
+import React, { useEffect, useState } from 'react';
+import { Text, View } from 'react-native';
+import { instantToParts, parseDay } from '@everystack/ui/date-time';
+import { Button, DateInput, nowInZone, useTimeZone, zoneAbbreviation } from '@everystack/ui';
+import type { DateRangeConfig, DateRangePreset } from '../types';
+import {
+  daysToConditions, instantsToDays, presetRange, type DateRange, type DateRangeFilter,
+} from '../utils/date-range';
+
+export interface DateConditionInputProps {
+  mode: 'range';
+  field: string;
+  /** The column's name, shown in bold before From. */
+  label?: string;
+  value: DateRangeFilter | null;
+  invalidReason?: string;
+  presets?: DateRangePreset[];
+  weekStartsOn?: DateRangeConfig['weekStartsOn'];
+  onApply: (values: string[]) => void;
+  onClear: () => void;
+  /** Given for a row the user added: a Remove button drops the row. */
+  onRemove?: () => void;
+}
+
+const PRESET_LABELS: Record<DateRangePreset, string> = {
+  today: 'Today', yesterday: 'Yesterday', last7Days: 'Last 7 days', last30Days: 'Last 30 days',
+  thisWeek: 'This week', lastWeek: 'Last week', thisMonth: 'This month', lastMonth: 'Last month',
+};
+
+/** Edits local calendar-day drafts; the parent owns the applied range and navigation. */
+export function DateConditionInput({
+  field, label, value, invalidReason, presets = [], weekStartsOn = 1, onApply, onClear, onRemove,
+}: DateConditionInputProps): React.ReactElement {
+  const zone = useTimeZone();
+  const [todayZone, setTodayZone] = useState<string | null>(null);
+  // Only after mount: an empty draft names today's zone, and reading the clock in render would let server and client markup differ.
+  useEffect(() => {
+    setTodayZone(zone.ready ? dayAbbreviation('', zone.timeZone) : null);
+  }, [zone.ready, zone.timeZone]);
+  const appliedDays = value && zone.ready && invalidReason === undefined ? instantsToDays(value, zone.timeZone) : null;
+  const from = appliedDays?.from ?? '';
+  const to = appliedDays?.to ?? '';
+  const [draft, setDraft] = useState<DateRange>({ from, to });
+  useEffect(() => { setDraft({ from, to }); }, [value?.gte, value?.lt, zone.ready, zone.timeZone, from, to, invalidReason]);
+
+  const validDays = parseDay(draft.from) !== null && parseDay(draft.to) !== null;
+  const conditions = validDays && zone.ready ? daysToConditions(field, draft, zone.timeZone) : undefined;
+  const canApply = conditions?.kind === 'ok';
+  const error = !validDays && (draft.from || draft.to) ? 'From and To must both be valid YYYY-MM-DD days.'
+    : conditions?.kind === 'invalid' ? conditions.reason : undefined;
+  const customLabel = value && !appliedDays
+    ? zone.ready
+      ? `Custom range: ${formatInZone(value.gte, zone.timeZone)} ${instantAbbreviation(value.gte, zone.timeZone)} to before ${formatInZone(value.lt, zone.timeZone)} ${instantAbbreviation(value.lt, zone.timeZone)} (${value.gte} to ${value.lt} UTC)`
+      : `Custom range (time zone resolving): ${value.gte} to before ${value.lt} UTC`
+    : undefined;
+
+  function apply(): void {
+    if (conditions?.kind !== 'ok') return;
+    onApply(conditions.values);
+  }
+
+  function clear(): void {
+    setDraft({ from: '', to: '' });
+    onClear();
+  }
+
+  function fillPreset(preset: DateRangePreset): void {
+    if (!zone.ready) return;
+    const now = nowInZone(zone.timeZone);
+    const today = `${String(now.year).padStart(4, '0')}-${String(now.month + 1).padStart(2, '0')}-${String(now.day).padStart(2, '0')}`;
+    setDraft(presetRange(preset, today, weekStartsOn));
+  }
+
+  return (
+    <View className="gap-2 bg-gray-100 border border-gray-200 rounded-xl px-3 py-2">
+      <View style={{ zIndex: 1 }} className="flex-row flex-wrap items-center gap-2">
+        {label !== undefined && <Text testID="date-range-label" className="text-sm font-bold text-gray-900">{label}</Text>}
+        <View testID="date-range-from" style={{ zIndex: 2 }} className="flex-row items-center gap-2">
+          <Text className="text-sm text-gray-600">From</Text>
+          <DateInput value={draft.from} granularity="date" weekStartsOn={weekStartsOn}
+            placeholder="Select From date" disabled={!zone.ready}
+            suffix={zone.ready ? stampZone(draft.from, zone.timeZone, todayZone) ?? undefined : undefined}
+            onValueChange={next => setDraft(current => ({ ...current, from: next }))} />
+        </View>
+        <View testID="date-range-to" style={{ zIndex: 1 }} className="flex-row items-center gap-2">
+          <Text className="text-sm text-gray-600">To</Text>
+          <DateInput value={draft.to} granularity="date" weekStartsOn={weekStartsOn}
+            placeholder="Select To date" disabled={!zone.ready}
+            suffix={zone.ready ? stampZone(draft.to, zone.timeZone, todayZone) ?? undefined : undefined}
+            onValueChange={next => setDraft(current => ({ ...current, to: next }))} />
+        </View>
+        {!zone.ready && <Text className="text-sm text-gray-500">Resolving time zone…</Text>}
+        {presets.map(preset => (
+          <View key={preset} testID={`date-range-preset-${preset}`}>
+            <Button label={PRESET_LABELS[preset]} variant="outline" disabled={!zone.ready} onPress={() => fillPreset(preset)} />
+          </View>
+        ))}
+        <View testID="date-range-actions" className="ml-auto flex-row items-center gap-2">
+          <View testID="date-range-apply">
+            <Button label="Apply" disabled={!canApply} onPress={apply} />
+          </View>
+          {(value !== null || draft.from || draft.to || invalidReason !== undefined) && (
+            <View testID="date-range-clear">
+              <Button label="Clear" variant="ghost" onPress={clear} />
+            </View>
+          )}
+          {onRemove && (
+            <View testID="date-range-remove">
+              <Button label="Remove" variant="ghost" onPress={onRemove} />
+            </View>
+          )}
+        </View>
+      </View>
+      {customLabel && <Text testID="date-range-custom" className="text-sm text-gray-600">{customLabel}</Text>}
+      {invalidReason !== undefined && <Text testID="date-range-invalid" accessibilityRole="alert" className="text-sm text-red-700">{invalidReason}</Text>}
+      {error && <Text testID="date-range-error" accessibilityRole="alert" className="text-sm text-red-700">{error}</Text>}
+    </View>
+  );
+}
+
+/** Exact local clock digits for a validated instant; custom ranges keep their milliseconds. */
+function formatInZone(value: string, timeZone: string): string {
+  const parts = instantToParts(value, timeZone)!;
+  const pad = (n: number, width = 2): string => String(n).padStart(width, '0');
+  return `${pad(parts.year, 4)}-${pad(parts.month + 1)}-${pad(parts.day)} ${pad(parts.hour)}:${pad(parts.minute)}:${pad(parts.second)}.${pad(parts.millisecond, 3)}`;
+}
+
+/** A draft day names its own day's zone; an empty draft names today's once that is known. */
+function stampZone(day: string, timeZone: string, todayZone: string | null): string | null {
+  return parseDay(day) ? dayAbbreviation(day, timeZone) : todayZone;
+}
+
+/** The zone's short name on a draft day (noon, so never in a DST gap or overlap); today's when the draft is empty. */
+function dayAbbreviation(day: string, timeZone: string): string {
+  const parsed = parseDay(day);
+  const parts = parsed
+    ? { year: parsed.year, month: parsed.month - 1, day: parsed.day, hour: 12, minute: 0, second: 0, millisecond: 0 }
+    : { ...nowInZone(timeZone), hour: 12, minute: 0, second: 0, millisecond: 0 };
+  return zoneAbbreviation(parts, timeZone);
+}
+
+/** The zone's short name at an exact validated instant: 'PST', 'PDT', or 'GMT+9' where English has no letters. */
+function instantAbbreviation(value: string, timeZone: string): string {
+  const name = new Intl.DateTimeFormat('en-US', { timeZone, timeZoneName: 'short' })
+    .formatToParts(new Date(value))
+    .find(part => part.type === 'timeZoneName');
+  return name?.value ?? timeZone;
+}

package/src/components/DateFilterBar.tsx

@@ -0,0 +1,85 @@
+import React, { useRef, useState } from 'react';
+import { Pressable, Text, View } from 'react-native';
+import { Button, useDismissOnOutsidePress } from '@everystack/ui';
+import type { DateRangePreset } from '../types';
+import type { DateRangeFilter } from '../utils/date-range';
+import { DateConditionInput, type DateConditionInputProps } from './DateConditionInput';
+
+export interface DateFilterRow {
+  field: string;
+  /** The column's name, shown in bold. */
+  label: string;
+  value: DateRangeFilter | null;
+  invalidReason?: string;
+  presets?: DateRangePreset[];
+  weekStartsOn?: DateConditionInputProps['weekStartsOn'];
+  /** True for a row the user added; the pinned row cannot be removed. */
+  removable: boolean;
+}
+
+export interface DateFilterBarProps {
+  rows: DateFilterRow[];
+  /** Datetime columns that have no row yet. */
+  addable: Array<{ field: string; label: string }>;
+  onApply: (field: string, values: string[]) => void;
+  onClear: (field: string) => void;
+  onRemove: (field: string) => void;
+  onAdd: (field: string) => void;
+}
+
+/** One date range row per filtered datetime column, and an Add filter menu for the rest. */
+export function DateFilterBar({ rows, addable, onApply, onClear, onRemove, onAdd }: DateFilterBarProps): React.ReactElement | null {
+  const [open, setOpen] = useState(false);
+  const addRef = useRef<View>(null);
+  useDismissOnOutsidePress(addRef, open, () => setOpen(false));
+  if (rows.length === 0 && addable.length === 0) return null;
+  return (
+    // Each View is its own stacking context: an open calendar must paint above the page content after the bar,
+    // and above the rows after its own row, so the bar and every row carry a descending z-index.
+    <View style={{ zIndex: 1 }} className="px-4 py-3 gap-2">
+      {rows.map((row, index) => (
+        <View key={row.field} testID={`date-filter-row-${row.field}`} style={{ zIndex: rows.length - index + 1 }}>
+          <DateConditionInput
+            mode="range"
+            field={row.field}
+            label={row.label}
+            value={row.value}
+            invalidReason={row.invalidReason}
+            presets={row.presets}
+            weekStartsOn={row.weekStartsOn}
+            onApply={values => onApply(row.field, values)}
+            onClear={() => onClear(row.field)}
+            onRemove={row.removable ? () => onRemove(row.field) : undefined}
+          />
+        </View>
+      ))}
+      {addable.length > 0 && (
+        // The open card lifts this block above the content after the bar (every View is its own stacking context).
+        <View ref={addRef} style={open ? { zIndex: 50, alignSelf: 'flex-start' } : { alignSelf: 'flex-start' }}>
+          <View testID="date-filter-add">
+            <Button label="Add filter" variant="outline" onPress={() => setOpen(current => !current)} />
+          </View>
+          {open && (
+            <View
+              testID="date-filter-menu"
+              style={{ position: 'absolute', top: '100%', left: 0, marginTop: 4, minWidth: 200, zIndex: 50 }}
+              className="border border-gray-200 rounded-lg bg-white shadow-lg overflow-hidden py-1"
+            >
+              {addable.map(option => (
+                <View key={option.field} testID={`date-filter-option-${option.field}`}>
+                  <Pressable
+                    accessibilityRole="menuitem"
+                    onPress={() => { setOpen(false); onAdd(option.field); }}
+                    className="px-4 py-2"
+                  >
+                    <Text className="text-sm text-gray-900">{option.label}</Text>
+                  </Pressable>
+                </View>
+              ))}
+            </View>
+          )}
+        </View>
+      )}
+    </View>
+  );
+}

package/src/components/DateTimeValue.tsx

@@ -0,0 +1,37 @@
+import React, { useState } from 'react';
+import { Platform, Pressable, Text, View } from 'react-native';
+import { useTimeZone } from '@everystack/ui';
+import type { FieldDefinition } from '../types';
+import { dateTimeRawValue, formatCellValue } from '../utils/format-cell-value';
+import { isWallClock } from '../utils/wall-clock';
+
+/** One datetime presentation for list cells, records and deletion metadata. */
+export function DateTimeValue({ field, value }: {
+  field: FieldDefinition;
+  value: unknown;
+}): React.ReactElement {
+  const zone = useTimeZone();
+  const [expanded, setExpanded] = useState(false);
+  const raw = isWallClock(field) || zone.ready ? dateTimeRawValue(field, value) : null;
+  const content = (
+    <>
+      <Text className="text-sm text-gray-900">{formatCellValue(field, value, zone.timeZone)}</Text>
+      {raw && (
+        <Pressable
+          testID="datetime-value-detail-toggle"
+          accessibilityRole="button"
+          accessibilityLabel="Show raw date value"
+          accessibilityState={{ expanded }}
+          onPress={event => { event?.stopPropagation(); setExpanded(open => !open); }}
+        >
+          <Text className="text-xs text-gray-500">{expanded ? 'Hide raw value' : 'Raw value'}</Text>
+        </Pressable>
+      )}
+      {raw && expanded && <Text testID="datetime-value-detail" selectable className="text-xs text-gray-600">{raw}</Text>}
+    </>
+  );
+  // React Native Web filters title out of View props. The DOM wrapper owns hover detail.
+  return Platform.OS === 'web'
+    ? <div data-testid="datetime-value" title={raw ?? undefined}>{content}</div>
+    : <View testID="datetime-value">{content}</View>;
+}