@everystack/admin 0.4.6 → 0.4.8

package/src/hooks/useAdminData.ts

@@ -4,9 +4,11 @@
  * Provides data fetching capabilities using the configured DataAdapter.
  */
 
-import { createContext, useContext, useState, useEffect, useCallback, useRef } from 'react';
+import { createContext, useContext, useMemo, useState, useEffect, useCallback, useRef } from 'react';
 import type { DataAdapter } from '../adapters/types';
 import type { ListParams, DataRecord } from '../types';
+import { AdminConfigContext } from './useAdminConfig';
+import { resourceQuerySignature, withResourceQuery } from '../utils/resource-query';
 
 // =============================================================================
 // Context
@@ -18,12 +20,41 @@ export interface DataAdapterContextValue {
 
 export const DataAdapterContext = createContext<DataAdapterContextValue | null>(null);
 
+/**
+ * The adapter every screen calls, mapped to each resource's `table` and narrowed to its `where`.
+ * The wrapping is done here, where both contexts are read, so the order the providers are nested
+ * in cannot leave a resource's `table` or `where` quietly unapplied.
+ */
 export function useDataAdapter(): DataAdapter {
   const context = useContext(DataAdapterContext);
-  if (!context) {
+  const config = useContext(AdminConfigContext)?.config;
+  const adapter = context?.adapter;
+  // Keyed on what the wrapper reads, not on the config object: an inline config literal is a new
+  // object every render, and a new wrapper would refetch every hook keyed on the adapter.
+  // The memo runs with this render's config whenever the signature changes, and the signature
+  // covers every part of the config the wrapper reads, so `config` itself is not a dependency.
+  const signature = config ? resourceQuerySignature(config) : null;
+  const queryAdapter = useMemo(
+    () => (adapter && config ? withResourceQuery(adapter, config) : adapter),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [adapter, signature],
+  );
+  if (!queryAdapter) {
     throw new Error('useDataAdapter must be used within a DataAdapterProvider');
   }
-  return context.adapter;
+  return queryAdapter;
+}
+
+/**
+ * The adapter as the DataAdapterProvider holds it, without the `table` and `where` mapping. For a
+ * call that names a real table, never a resource (a delete-preview association's `table`).
+ */
+export function useRawDataAdapter(): DataAdapter {
+  const adapter = useContext(DataAdapterContext)?.adapter;
+  if (!adapter) {
+    throw new Error('useRawDataAdapter must be used within a DataAdapterProvider');
+  }
+  return adapter;
 }
 
 // =============================================================================
@@ -146,6 +177,16 @@ export function useAdminData<T extends DataRecord = DataRecord>(
     const byRefetch = refetchIndex !== lastRefetchIndexRef.current;
     lastRefetchIndexRef.current = refetchIndex;
     if (options.skip) {
+      // A skipped query holds no result: a response in flight must not land, and rows or an
+      // error from the last query must not show once the query it belonged to is gone.
+      ++seqRef.current;
+      setData(rows => (rows.length === 0 ? rows : []));
+      setTotal(0);
+      setError(null);
+      shownParamsRef.current = null;
+      setLoading(false);
+      setRefreshing(false);
+      settle(carriedRef.current.splice(0));
       settle(queuedRef.current.splice(0));
       return;
     }

package/src/hooks/useDateRangeFilters.ts

@@ -0,0 +1,47 @@
+import { useMemo } from 'react';
+import { parseOwnedRange, rangeFilter, type DateRangeFilter } from '../utils/date-range';
+
+export interface DateRangeRow {
+  field: string;
+  status: 'off' | 'ready' | 'invalid';
+  pair?: DateRangeFilter;
+  reason?: string;
+}
+
+export interface UseDateRangeFiltersResult {
+  rows: DateRangeRow[];
+  /** The ready rows' bounds, merged: one `gte`/`lt` pair per field. */
+  filter?: Record<string, string[]>;
+  /** True while any row is invalid: the list fetches nothing. */
+  block: boolean;
+}
+
+/** Validate each field's owned URL conditions independently of the display zone. */
+export function useDateRangeFilters(
+  fields: readonly string[],
+  valuesOf: (field: string) => readonly string[],
+): UseDateRangeFiltersResult {
+  const key = JSON.stringify([...new Set(fields)].map(field => [field, valuesOf(field)]));
+  return useMemo((): UseDateRangeFiltersResult => {
+    const rows: DateRangeRow[] = [];
+    const bounds: Array<[string, string[]]> = [];
+    for (const [field, values] of JSON.parse(key) as Array<[string, string[]]>) {
+      const parsed = parseOwnedRange(values);
+      if (parsed.kind === 'absent') {
+        rows.push({ field, status: 'off' });
+      } else if (parsed.kind === 'invalid') {
+        rows.push({ field, status: 'invalid', reason: parsed.reason });
+      } else {
+        const pair = { gte: parsed.gte, lt: parsed.lt };
+        rows.push({ field, status: 'ready', pair });
+        bounds.push(...Object.entries(rangeFilter(field, pair)));
+      }
+    }
+    return {
+      rows,
+      // fromEntries defines own properties, so a column named `__proto__` is not a prototype write.
+      ...(bounds.length > 0 ? { filter: Object.fromEntries(bounds) } : {}),
+      block: rows.some(row => row.status === 'invalid'),
+    };
+  }, [key]);
+}

package/src/hooks/useViewState.ts

@@ -12,13 +12,22 @@ import { createContext, useContext } from 'react';
 /** Current query params, normalized to single strings (first value wins). */
 export type ViewParams = Record<string, string>;
 
+/** Every nonempty query value for each key, in URL order. */
+export type ViewParamValues = Record<string, string[]>;
+
+/** A delta replaces all values of a key; undefined or an empty array removes it. */
+export type ViewParamDelta = Record<string, string | string[] | undefined>;
+
 export interface ViewStateContextValue {
   params: ViewParams;
+  /** All values per key; optional for contexts supplied by existing embedders. */
+  paramValues?: ViewParamValues;
   /**
    * Merge `next` into the current params and navigate. Keys set to undefined are
-   * removed from the URL. The path is preserved; only the query changes.
+   * removed from the URL. An array replaces all values; an empty array removes
+   * the key. The path is preserved; only the query changes.
    */
-  setParams: (next: Record<string, string | undefined>) => void;
+  setParams: (next: ViewParamDelta) => void;
 }
 
 export const ViewStateContext = createContext<ViewStateContextValue | null>(null);
@@ -28,9 +37,17 @@ export function useViewState(): ViewStateContextValue {
   return useContext(ViewStateContext) ?? { params: {}, setParams: () => {} };
 }
 
+/** Read all values when available, falling back to the first-value context. */
+export function valuesOf(view: Pick<ViewStateContextValue, 'params' | 'paramValues'>, key: string): string[] {
+  const own = (record: object | undefined, name: string): boolean => record !== undefined && Object.prototype.hasOwnProperty.call(record, name);
+  const values = own(view.paramValues, key) ? view.paramValues![key]
+    : own(view.params, key) && view.params[key] !== undefined ? [view.params[key]] : [];
+  return values.filter(value => value !== '');
+}
+
 /** Normalize a raw searchParams object (values may be arrays) to single strings. */
 export function normalizeParams(raw?: Record<string, string | string[] | undefined>): ViewParams {
-  const out: ViewParams = {};
+  const out: ViewParams = Object.create(null);
   if (!raw) return out;
   for (const [k, v] of Object.entries(raw)) {
     if (v == null) continue;
@@ -39,12 +56,28 @@ export function normalizeParams(raw?: Record<string, string | string[] | undefin
   return out;
 }
 
-/** Build a `?a=1&b=2` query string from params; empty → ''. Undefined dropped. */
-export function buildQueryString(params: Record<string, string | undefined>): string {
+/** Keep every nonempty value; an empty key has [] so keys match normalizeParams. */
+export function normalizeParamValues(
+  raw?: Record<string, string | (string | null | undefined)[] | null | undefined>,
+): ViewParamValues {
+  const out: ViewParamValues = Object.create(null);
+  if (!raw) return out;
+  for (const [key, value] of Object.entries(raw)) {
+    if (value == null) continue;
+    const values = Array.isArray(value) ? value : [value];
+    out[key] = values.filter((v): v is string => v != null && v !== '');
+  }
+  return out;
+}
+
+/** Build a query string, appending each value. Empty and undefined values are dropped. */
+export function buildQueryString(params: ViewParamDelta): string {
   const usp = new URLSearchParams();
-  for (const [k, v] of Object.entries(params)) {
-    if (v == null || v === '') continue;
-    usp.set(k, v);
+  for (const [key, value] of Object.entries(params)) {
+    for (const v of Array.isArray(value) ? value : [value]) {
+      if (v == null || v === '') continue;
+      usp.append(key, v);
+    }
   }
   const s = usp.toString();
   return s ? `?${s}` : '';

package/src/index.ts

@@ -12,6 +12,7 @@ export type {
   FieldDefinition,
   FieldDefinitionBase,
   WallClockDatetime,
+  InstantDatetime,
   NoTimeZone,
   TagGroup,
   ImageSize,
@@ -23,6 +24,8 @@ export type {
   EditorComponent,
   EditorRegistry,
   ResourceConfig,
+  DateRangeConfig,
+  DateRangePreset,
   ScreenLayout,
   LayoutColumn,
   StorageConfig,
@@ -36,6 +39,7 @@ export type {
   ScopeConfig,
   AssociationConfig,
   DeletedMode,
+  WhereValues,
   ListResult,
   DataRecord,
   AggregateFunction,
@@ -59,10 +63,12 @@ export type {
 } from './adapters/types';
 
 // EverystackAdapter
+export { CannotSortError, isCannotSortError } from './adapters/CannotSortError';
 export { EverystackApiError } from './adapters/EverystackApiError';
 export { EverystackAdapter, type EverystackAdapterOptions } from './adapters/EverystackAdapter';
 
 // Hooks
+export { useDateRangeFilters, type UseDateRangeFiltersResult, type DateRangeRow } from './hooks/useDateRangeFilters';
 export { useAdminConfig, type AdminConfigContextValue } from './hooks/useAdminConfig';
 export {
   useDataAdapter,
@@ -91,8 +97,12 @@ export {
   useViewState,
   ViewStateContext,
   normalizeParams,
+  normalizeParamValues,
+  valuesOf,
   buildQueryString,
   type ViewParams,
+  type ViewParamValues,
+  type ViewParamDelta,
   type ViewStateContextValue,
 } from './hooks/useViewState';
 
@@ -178,6 +188,7 @@ export { ImageDisplay } from './components/ImageDisplay';
 export { RowActionButton, type RowActionButtonProps } from './components/RowActionButton';
 export { AdminLink, type AdminLinkProps } from './components/AdminLink';
 export { FormActionBar, type FormActionBarProps } from './components/FormActionBar';
+export { DateConditionInput, type DateConditionInputProps } from './components/DateConditionInput';
 
 // Image utilities
 export { resolveImageUrl, type ResolveImageUrlOptions } from './utils/resolve-image-url';
@@ -188,6 +199,7 @@ export { visibleRowActions } from './utils/row-actions';
 export { enumScopes } from './utils/scopes';
 
 // Utilities
+export { isFieldSortable } from './utils/field-sortable';
 export {
   toCamelCase,
   toSnakeCase,

package/src/providers/AdminConfigProvider.tsx

@@ -5,9 +5,10 @@
  */
 
 import React, { useMemo } from 'react';
+import { TimeZoneProvider } from '@everystack/ui';
 import type { AdminConfig } from '../types';
 import { AdminConfigContext } from '../hooks/useAdminConfig';
-import { validateAdminConfig } from '../utils/wall-clock';
+import { validateAdminConfig } from '../utils/validate-config';
 
 export interface AdminConfigProviderProps {
   config: AdminConfig;
@@ -18,5 +19,9 @@ export function AdminConfigProvider({ config, children }: AdminConfigProviderPro
   // 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>;
+  return (
+    <AdminConfigContext.Provider value={{ config }}>
+      <TimeZoneProvider timeZone={config.timeZone}>{children}</TimeZoneProvider>
+    </AdminConfigContext.Provider>
+  );
 }

package/src/providers/DataAdapterProvider.tsx

@@ -1,10 +1,11 @@
 /**
  * DataAdapterProvider
  *
- * Provides the DataAdapter to the admin component tree.
+ * Provides the DataAdapter to the admin component tree. useDataAdapter() hands screens this adapter
+ * mapped to the config's `table` and `where` (withResourceQuery), whichever way the providers are nested.
  */
 
-import React from 'react';
+import React, { useMemo } from 'react';
 import type { DataAdapter } from '../adapters/types';
 import { DataAdapterContext } from '../hooks/useAdminData';
 
@@ -14,5 +15,6 @@ export interface DataAdapterProviderProps {
 }
 
 export function DataAdapterProvider({ adapter, children }: DataAdapterProviderProps) {
-  return <DataAdapterContext.Provider value={{ adapter }}>{children}</DataAdapterContext.Provider>;
+  const value = useMemo(() => ({ adapter }), [adapter]);
+  return <DataAdapterContext.Provider value={value}>{children}</DataAdapterContext.Provider>;
 }

package/src/rpc/list-filter.ts

@@ -0,0 +1,210 @@
+import { sql, type SQL } from 'drizzle-orm';
+import { HandlerError } from '@everystack/api/errors';
+import { toCamelCase } from '../utils/naming';
+import type { ResourceDashboardConfig } from '../types';
+
+// Keep recognition in step with EverystackAdapter's POSTGREST_OPERATORS. Recognized
+// but unsupported operators must refuse, rather than turn into plain equality.
+const KNOWN_OPERATORS = new Set([
+  'eq', 'neq', 'gt', 'gte', 'lt', 'lte',
+  'like', 'ilike', 'is', 'in', 'not', 'cs', 'cd',
+  'sl', 'sr', 'nxl', 'nxr', 'adj', 'ov', 'fts',
+]);
+const OPERATORS = new Map([
+  ['eq', '='], ['neq', '<>'], ['gt', '>'], ['gte', '>='], ['lt', '<'], ['lte', '<='],
+]);
+const ERROR_COLUMN = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+const UTC_INSTANT = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(\.\d{1,9})?Z$/;
+const LONE_SURROGATE = /[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/;
+const MAX_MEMBERS = 25;
+const MAX_MEMBER_LENGTH = 256;
+const MAX_MEMBERSHIP_LENGTH = MAX_MEMBERS * MAX_MEMBER_LENGTH + MAX_MEMBERS - 1 + 2;
+
+interface FilterColumns {
+  exact: Set<string>;
+  search: Set<string>;
+  dimensions: Set<string>;
+  aliases: Map<string, string | null>;
+  allowedValues: Map<string, Set<string>>;
+}
+
+const columnsByConfig = new WeakMap<ResourceDashboardConfig, FilterColumns>();
+
+function filterColumns(config: ResourceDashboardConfig): FilterColumns {
+  const cached = columnsByConfig.get(config);
+  if (cached) return cached;
+  const exact = new Set([
+    ...config.listColumns, config.timestampColumn, ...config.dimensions.map(dim => dim.column),
+  ]);
+  const search = new Set(config.searchColumns ?? []);
+  const dimensions = new Set(config.dimensions.map(dim => dim.column));
+  const aliases = new Map<string, string | null>();
+  for (const column of new Set([...exact, ...search])) {
+    const alias = toCamelCase(column);
+    aliases.set(alias, aliases.has(alias) ? null : column);
+  }
+  const allowedValues = new Map<string, Set<string>>();
+  for (const dim of config.dimensions) {
+    if (dim.allowedValues?.length) allowedValues.set(dim.column, new Set(dim.allowedValues));
+  }
+  const result = { exact, search, dimensions, aliases, allowedValues };
+  columnsByConfig.set(config, result);
+  return result;
+}
+
+function refuse(message: string, column?: string): never {
+  // Never pass an unsafe caller name to HandlerError's metadata constructor.
+  throw new HandlerError(400, message, {
+    code: 'invalid_filter',
+    ...(column !== undefined && ERROR_COLUMN.exec(column)?.[0] === column ? { column } : {}),
+  });
+}
+
+function isUtcInstant(value: string): boolean {
+  const match = UTC_INSTANT.exec(value);
+  if (!match) return false;
+  // PostgreSQL has no year 0000; refuse it here rather than let the database answer 422.
+  if (Number(match[1]) < 1) return false;
+  const [, year, month, day, hour, minute, second] = match;
+  const parts = [year, month, day, hour, minute, second].map(Number);
+  const [y, m, d, h, min, s] = parts;
+  // Date.UTC treats years 0..99 as 1900..1999. A 400-year shift preserves leap
+  // years, then setUTCFullYear restores the requested year without that coercion.
+  const date = new Date(Date.UTC(y < 100 ? y + 400 : y, m - 1, d, h, min, s));
+  if (y < 100) date.setUTCFullYear(y);
+  return date.getUTCFullYear() === y && date.getUTCMonth() === m - 1 &&
+    date.getUTCDate() === d && date.getUTCHours() === h &&
+    date.getUTCMinutes() === min && date.getUTCSeconds() === s;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object') return false;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype === null) return true;
+  // Request.json() can return another realm's Object.prototype (also in Jest).
+  const constructor = Object.getOwnPropertyDescriptor(prototype, 'constructor')?.value;
+  return Object.getPrototypeOf(prototype) === null && typeof constructor === 'function' &&
+    Function.prototype.toString.call(constructor) === Function.prototype.toString.call(Object);
+}
+
+function isWellFormed(value: string): boolean {
+  const check = (String.prototype as typeof String.prototype & {
+    isWellFormed?: (this: string) => boolean;
+  }).isWellFormed;
+  return check ? check.call(value) : !LONE_SURROGATE.test(value);
+}
+
+/** Translate the adapter's `*` pattern to SQL LIKE with `ESCAPE '!'`. */
+export function ilikePattern(raw: string): string | null {
+  if (raw.length > 256 || raw.includes('\0') || !isWellFormed(raw)) return null;
+  let pattern = '';
+  let wildcards = 0;
+  for (let i = 0; i < raw.length; i++) {
+    let char = raw[i];
+    if (char === '\\') {
+      if (i + 1 < raw.length) char = raw[++i];
+    } else if (char === '*') {
+      if (++wildcards > 8) return null;
+      pattern += '%';
+      continue;
+    }
+    pattern += char === '!' || char === '%' || char === '_' ? `!${char}` : char;
+  }
+  return pattern;
+}
+
+function parseCondition(raw: unknown, column: string): { operator: string; value: string } {
+  // The adapter sends a number or boolean as its String() text; mirror that, and refuse the rest.
+  const text = typeof raw === 'string' ? raw
+    : typeof raw === 'boolean' || (typeof raw === 'number' && Number.isFinite(raw)) ? String(raw)
+    : undefined;
+  if (text === undefined) refuse('Filter values must be strings, numbers or booleans', column);
+  if (text.includes('\0')) refuse('Invalid filter value', column);
+  // Same rule as the adapter: only an exact known-operator prefix is an operator. Any other
+  // dotted text (`example.com`, `cs2.log`, `gte;.x`) is a plain value, bound as a parameter.
+  let operator = 'eq';
+  let value = text;
+  const dot = text.indexOf('.');
+  if (dot > 0) {
+    const prefix = text.slice(0, dot);
+    if (KNOWN_OPERATORS.has(prefix)) {
+      if (!OPERATORS.has(prefix) && prefix !== 'ilike' && prefix !== 'in') refuse('Unsupported filter operator', column);
+      operator = prefix;
+      value = text.slice(dot + 1);
+    }
+  }
+  if (value.length > (operator === 'in' ? MAX_MEMBERSHIP_LENGTH : 256)) refuse('Filter value is too long', column);
+  if (!isWellFormed(value)) refuse('Invalid filter value', column);
+  return { operator, value };
+}
+
+function membershipValues(value: string, column: string): string[] {
+  if (!value.startsWith('(') || !value.endsWith(')')) refuse('Invalid filter membership', column);
+  const body = value.slice(1, -1);
+  // The native mapper emits simple comma lists. Refuse quoted, escaped or nested
+  // forms rather than interpret a quoted comma as two different members.
+  if (/[()"\\]/.test(body)) refuse('Invalid filter membership', column);
+  // parseCondition bounds the entire list before this allocation.
+  const members = body.split(',');
+  if (members.length > MAX_MEMBERS || members.some(member => member.length === 0 || member.length > MAX_MEMBER_LENGTH)) {
+    refuse('Invalid filter membership', column);
+  }
+  return members;
+}
+
+/** Compile list-protocol conditions using only factory-validated config identifiers. */
+export function compileListFilter(
+  config: ResourceDashboardConfig,
+  filter: unknown,
+): { conditions: SQL[]; timeBounded: boolean } {
+  const columns = filterColumns(config);
+  const conditions: SQL[] = [];
+  let timeBounded = false;
+  if (filter == null) return { conditions, timeBounded };
+  if (!isPlainObject(filter)) {
+    refuse('Filter must be a plain object');
+  }
+  const countByColumn = new Map<string, number>();
+  for (const [name, raw] of Object.entries(filter)) {
+    const column = columns.exact.has(name) || columns.search.has(name) ? name : columns.aliases.get(name);
+    if (column === null) refuse('Ambiguous filter column', name);
+    if (column === undefined) refuse('Unknown filter column', name);
+    const values = Array.isArray(raw) ? raw : [raw];
+    if (values.length === 0) refuse('Filter conditions must not be empty', name);
+    const count = (countByColumn.get(column) ?? 0) + values.length;
+    if (count > 10 || conditions.length + values.length > 50) refuse('Too many filter conditions', name);
+    countByColumn.set(column, count);
+    for (const rawValue of values) {
+      if (rawValue == null) continue; // the adapter skips null and undefined
+      const { operator, value } = parseCondition(rawValue, name);
+      if (operator === 'in') {
+        if (!columns.dimensions.has(column)) refuse('Column does not support membership filters', name);
+        const members = membershipValues(value, name);
+        const allowed = columns.allowedValues.get(column);
+        if (allowed && members.some(member => !allowed.has(member))) refuse('Invalid filter dimension value', name);
+        if (column === config.timestampColumn && members.some(member => !isUtcInstant(member))) {
+          refuse('Filter timestamp must be a valid UTC instant', name);
+        }
+        conditions.push(sql`${sql.raw(column)} IN (${sql.join(members.map(member => sql`${member}`), sql`, `)})`);
+        continue; // Membership does not replace the default time window.
+      }
+      if (operator === 'ilike') {
+        if (!columns.search.has(column)) refuse('Column does not support ilike filters', name);
+        const pattern = ilikePattern(value);
+        if (pattern === null) refuse('Invalid filter pattern', name);
+        conditions.push(sql`${sql.raw(column)} ILIKE ${pattern} ESCAPE '!'`);
+        continue;
+      }
+      if (!columns.exact.has(column)) refuse('Unknown filter column', name);
+      if (column === config.timestampColumn && !isUtcInstant(value)) refuse('Filter timestamp must be a valid UTC instant', name);
+      const allowed = columns.allowedValues.get(column);
+      if ((operator === 'eq' || operator === 'neq') && allowed && !allowed.has(value)) {
+        refuse('Invalid filter dimension value', name);
+      }
+      // No cast: PostgreSQL infers the parameter type from the configured column.
+      conditions.push(sql`${sql.raw(column)} ${sql.raw(OPERATORS.get(operator)!)} ${value}`);
+      if (column === config.timestampColumn && operator !== 'neq') timeBounded = true;
+    }
+  }
+  return { conditions, timeBounded };
+}