@everystack/admin 0.4.2 → 0.4.3

package/src/screens/ResourceShow.tsx

@@ -5,13 +5,18 @@
  * Fetches via adapter.fetchOne() and displays field values.
  */
 
-import React, { useState, useEffect, useCallback } from 'react';
+import React, { useState, useEffect, useLayoutEffect, useCallback, useRef } from 'react';
 import { View, Text, ScrollView } from 'react-native';
 import { useAdminConfig } from '../hooks/useAdminConfig';
 import { useDataAdapter } from '../hooks/useAdminData';
 import { LoadingState, ErrorState, Button, Card, Divider } from '@everystack/ui';
 import { ImageDisplay } from '../components/ImageDisplay';
+import { TagsDisplay } from '../components/TagsDisplay';
 import { RowActionButton } from '../components/RowActionButton';
+import { FieldColumns } from '../components/FieldColumns';
+import { useEditors } from '../hooks/useEditors';
+import { resolveColumns, screenLayout } from '../utils/resolve-columns';
+import { wrapBareText } from '../components/CellText';
 import { visibleRowActions } from '../utils/row-actions';
 import { toCamelCase } from '../utils/naming';
 import { formatDateOnly } from '../utils/format-cell-value';
@@ -41,23 +46,46 @@ export function ResourceShow({
   const config = useAdminConfig();
   const adapter = useDataAdapter();
   const resourceConfig = config.resources.find(r => r.name === resource);
+  const editors = useEditors();
 
   const [record, setRecord] = useState<DataRecord | null>(null);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<Error | null>(null);
 
-  const fetchRecord = useCallback(async () => {
-    setLoading(true);
+  // Latest-request guard: only the most recent load may write state, so an older
+  // id's or an older request's response can't land over a newer one.
+  const seqRef = useRef(0);
+  // The id on screen now. A load captured for an older id (a row action's refetch
+  // after it navigated away) writes nothing.
+  const idRef = useRef(id);
+  // Set when the id commits, not during render: a render React throws away must not move it.
+  // Declared before the fetch effect, so a layout effect always runs first.
+  useLayoutEffect(() => { idRef.current = id; }, [id]);
+
+  // A quiet load keeps the screen (and a row action's error) mounted; it still
+  // ends in the ErrorState when the fetch throws, so stale data never stays.
+  // A superseded load still resolves; it just writes nothing.
+  const loadRecord = useCallback(async (quiet: boolean): Promise<void> => {
+    // A call from an older id's closure takes no turn, so it cannot supersede the current load.
+    if (id !== idRef.current) return;
+    const seq = ++seqRef.current;
+    // An id change starts a new load (a new seq), so the seq alone drops an older id's result.
+    const latest = (): boolean => seq === seqRef.current;
+    if (!quiet) setLoading(true);
     setError(null);
     try {
-      setRecord(await fetchDetail(adapter, resource, id, resourceConfig));
+      const next = await fetchDetail(adapter, resource, id, resourceConfig);
+      if (latest()) setRecord(next);
     } catch (err) {
-      setError(err instanceof Error ? err : new Error(String(err)));
+      if (latest()) setError(err instanceof Error ? err : new Error(String(err)));
     } finally {
-      setLoading(false);
+      if (latest()) setLoading(false);
     }
   }, [adapter, resource, id, resourceConfig]);
 
+  const fetchRecord = useCallback((): Promise<void> => loadRecord(false), [loadRecord]);
+  const refetchQuietly = useCallback((): Promise<void> => loadRecord(true), [loadRecord]);
+
   useEffect(() => {
     fetchRecord();
   }, [fetchRecord]);
@@ -84,6 +112,14 @@ export function ResourceShow({
   const canEdit = resourceConfig.actions?.edit !== false;
   const canDelete = resourceConfig.actions?.delete !== false;
   const rowActions = visibleRowActions(resourceConfig.rowActions, record);
+  const layout = screenLayout(resourceConfig, 'show');
+  const columns = layout
+    ? resolveColumns(
+      showFields.map(name => fieldMap.get(name)).filter((f): f is FieldDefinition => f != null),
+      layout,
+      editors,
+    )
+    : null;
 
   return (
     <ScrollView className="flex-1">
@@ -105,7 +141,7 @@ export function ResourceShow({
               record={record}
               recordId={id}
               adapter={adapter}
-              refetch={fetchRecord}
+              refetch={refetchQuietly}
             />
           ))}
           {canEdit && onEditPress && (
@@ -119,7 +155,17 @@ export function ResourceShow({
 
       {/* Fields */}
       <Card style={{ marginHorizontal: 16, marginBottom: 16 }}>
-        {showFields.map((fieldName, idx) => {
+        {columns ? (
+          <FieldColumns
+            columns={columns}
+            renderField={(fieldDef, idx) => (
+              <>
+                {idx > 0 && <Divider />}
+                <FieldRow field={fieldDef} value={record[fieldDef.name]} record={record} />
+              </>
+            )}
+          />
+        ) : showFields.map((fieldName, idx) => {
           const fieldDef = fieldMap.get(fieldName);
           if (!fieldDef) return null;
           const value = record[fieldName];
@@ -178,9 +224,11 @@ function FieldRow({ field, value, record }: FieldRowProps): React.ReactElement {
         {field.label ?? field.name}
       </Text>
       {field.render ? (
-        <>{field.render(value, record, { view: 'show' })}</>
+        <>{wrapBareText(field.render(value, record, { view: 'show' }))}</>
       ) : field.type === 'image' ? (
         <ImageDisplay field={field} value={value} view="show" />
+      ) : field.type === 'tags' ? (
+        <TagsDisplay field={field} value={value} />
       ) : (
         <Text className="text-sm text-gray-900">{formatFieldValue(value, field)}</Text>
       )}

package/src/types.ts

@@ -38,7 +38,11 @@ export interface ActionContext {
   adapter: DataAdapter;
   /** Re-fetch the current view after a mutation. */
   refetch: () => Promise<void> | void;
-  /** Navigate to an admin path, when the route layer provides it. */
+  /**
+   * Go to an admin path. Optional: RowActionButton passes it through when its
+   * caller supplies one, but the built-in ResourceList and ResourceShow do not,
+   * so it is undefined there. Check it before you call it.
+   */
   navigate?: (path: string) => void;
 }
 
@@ -53,6 +57,11 @@ export interface InputContext {
   field: FieldDefinition;
   record?: DataRecord;
   error?: string;
+  /**
+   * The whole form's current values, keyed by field name (what Save would
+   * send). Read another field here to render a block that depends on it.
+   */
+  values: Record<string, unknown>;
 }
 
 /**
@@ -100,7 +109,18 @@ export type FieldType =
   | 'enum'
   | 'relation'
   | 'image'
-  | 'file';
+  | 'file'
+  | 'tags';
+
+/**
+ * One group of options for a `tags` field. `label` is shown as a small heading
+ * above the group's pills; leave it out for a flat set. An option's label
+ * defaults to its value.
+ */
+export interface TagGroup {
+  label?: string;
+  options: Array<{ value: string; label?: string }>;
+}
 
 export interface FieldDefinition {
   /** Field name (matches data key) */
@@ -117,6 +137,19 @@ export interface FieldDefinition {
   filterable?: boolean;
   /** For enum types: allowed values */
   enumValues?: string[];
+  /**
+   * For enum types: edit the value from the list cell. The cell shows a picker
+   * of `enumValues` and saves a pick with `adapter.update(resource, id, { [name]: value })`.
+   * Ignored for other types, and when a `render` override is set.
+   * Follows `actions.edit`: a resource with `actions.edit: false` shows the plain text cell.
+   */
+  inlineEdit?: boolean;
+  /**
+   * For tags types (a text[] column): the options, as pills in groups. A press
+   * toggles one value and keeps every other stored value, including values in
+   * no group (they show in an "Other" row).
+   */
+  tagGroups?: TagGroup[];
   /** For relation types: related resource name */
   relation?: {
     resource: string;
@@ -131,6 +164,26 @@ export interface FieldDefinition {
     pattern?: string;
     message?: string;
   };
+  /**
+   * Fixed width of this field's list column, in px (list view only). The
+   * column then neither grows nor shrinks; without it the column shares the
+   * remaining space.
+   */
+  listWidth?: number;
+  /**
+   * How soon this field's list column drops when the list is too narrow
+   * (list view only; the Show page keeps every field). 1 (or less) never
+   * drops, a larger number drops sooner, and a field without one drops
+   * before every field that has one. Nothing drops until some field sets
+   * `listPriority` or `listHideBelow`; the Actions column never drops.
+   */
+  listPriority?: number;
+  /**
+   * Drop this field's list column while the list's container is narrower
+   * than this many px, even if it would fit (list view only). Ignored on a
+   * field that never drops (`listPriority` of 1 or less).
+   */
+  listHideBelow?: number;
   /** Renderer variant for this field type (e.g., 'avatar' for image fields) */
   renderer?: string;
   /**
@@ -146,6 +199,9 @@ export interface FieldDefinition {
   /**
    * Custom form input (create/edit) — wins over the type/renderer input. The
    * custom input owns its element (control + optional label/error frame).
+   * It is rendered as its own component, so hooks inside it are fine. Pass a
+   * stable function (declared once, not an inline arrow made on each render),
+   * or the input remounts and loses its state every render.
    */
   input?: (ctx: InputContext) => ReactNode;
   /**
@@ -162,6 +218,26 @@ export interface FieldDefinition {
 // Resource Configuration
 // =============================================================================
 
+/**
+ * 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
+ * default is 'wide' for the first column and 'narrow' for the others.
+ */
+export interface LayoutColumn {
+  /** Field names, top to bottom. */
+  fields: string[];
+  width?: 'wide' | 'narrow' | number;
+}
+
+/**
+ * How a Show/Edit/Create screen places its fields. 'auto' puts long fields
+ * (custom render/input, json, image, file, tags, relation, rich or long text)
+ * in a wide main column and short ones in a narrow side column. A field no
+ * column lists goes at the end of the first column. Columns stack below a
+ * 720px container.
+ */
+export type ScreenLayout = 'auto' | { columns: LayoutColumn[] };
+
 /**
  * A declarative action on a single record (delete/restore, retry/cancel a job),
  * rendered on both the list and show views and gated by the `when` clause.
@@ -214,8 +290,22 @@ export interface ResourceConfig {
     edit?: boolean;
     delete?: boolean;
   };
+  /**
+   * Rows per page when the list opens. Default 20. The page bar also offers
+   * 20, 50 and 100 (and this size, when it is not one of them); the chosen
+   * size is kept in the URL as `size`. A value that is not a whole number
+   * above 0 is ignored; one above 500 is capped to 500.
+   */
+  perPage?: number;
   /** Fields to display in list view */
   listFields?: string[];
+  /**
+   * Fixed width of the list's Actions column, in px. Default, or when this is
+   * not a finite number above 0: an estimate from the idle labels of the
+   * actions the column renders, built-in and rowActions. A longer two-step
+   * confirm label wraps to a second line inside the cell.
+   */
+  actionsWidth?: number;
   /** Fields to display in detail/show view */
   showFields?: string[];
   /** Fields to display in create form */
@@ -231,8 +321,30 @@ export interface ResourceConfig {
   detailVia?: 'rpc' | 'rest';
   /** Optional observability-style dashboard configuration */
   dashboard?: ResourceDashboardConfig;
-  /** RPC-backed record actions shown on the show view */
+  /**
+   * Custom record actions (rpc, onPress or render). They show on the show view
+   * and in the list's Actions column, after the built-in Show/Edit/Delete.
+   */
   rowActions?: RowActionConfig[];
+  /** Tabs above the list, each a named filter. Without this the list shows no tabs. */
+  scopes?: ScopeConfig[];
+  /**
+   * Show a row count on each tab. Off unless set: counts cost queries. The values of one
+   * enum column share one grouped query; every other tab costs one count. Counts follow the
+   * search, and need an adapter with `aggregate`.
+   */
+  scopeCounts?: boolean;
+  /**
+   * Field columns for Show, Edit and Create. Without any layout, each screen
+   * shows one column of fields, as before.
+   */
+  layout?: ScreenLayout;
+  /** Show only: wins over `layout`. */
+  showLayout?: ScreenLayout;
+  /** Edit (and Create, unless `createLayout` is set): wins over `layout`. */
+  editLayout?: ScreenLayout;
+  /** Create only: wins over `editLayout` and `layout`. */
+  createLayout?: ScreenLayout;
 }
 
 // =============================================================================
@@ -452,6 +564,20 @@ export interface AdminConfig {
 // Data Types
 // =============================================================================
 
+/**
+ * A named filter shown as a tab above a list ("Current", "Draft"). Scopes are
+ * ANDed with the search and any column filters.
+ */
+export interface ScopeConfig {
+  /** Stable id; this is what the URL carries (`?tab=draft`). */
+  id: string;
+  label: string;
+  /** Filter applied while this scope is active, in the adapter's filter syntax. None means all rows. */
+  filter?: Record<string, unknown>;
+  /** The scope active when the URL names none. If none is marked, the first is. */
+  default?: boolean;
+}
+
 export interface ListParams {
   /** Page number (1-indexed) */
   page?: number;
@@ -463,8 +589,14 @@ export interface ListParams {
   order?: 'asc' | 'desc';
   /** Filter conditions */
   filter?: Record<string, unknown>;
-  /** Search query */
+  /** Search text, matched (ILIKE, case-insensitive) in any of `searchFields`. */
   search?: string;
+  /**
+   * Columns `search` looks in. Required with `search`: the adapter does not know
+   * your schema, so it refuses search text without them rather than silently
+   * returning unfiltered rows. Plain column names only.
+   */
+  searchFields?: string[];
 }
 
 export interface ListResult<T = Record<string, unknown>> {
@@ -507,6 +639,10 @@ export interface AggregateParams {
   groupBy?: string[];
   /** Filter conditions */
   filter?: Record<string, unknown>;
+  /** Search text, matched in any of `searchFields`, exactly as `ListParams.search`. */
+  search?: string;
+  /** Columns `search` looks in. Required with `search`. Plain column names only. */
+  searchFields?: string[];
 }
 
 export interface AggregateResult {

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

@@ -7,6 +7,7 @@
  */
 
 import type { FieldDefinition } from '../types';
+import { tagLabel, tagValues } from './tags';
 
 /**
  * A date-only ISO string has no time-of-day; `new Date(str)` parses it as UTC midnight, and
@@ -63,6 +64,10 @@ export function formatCellValue(field: FieldDefinition, value: unknown): string
       return value ? 'Yes' : 'No';
     case 'json':
       return typeof value === 'string' ? value : JSON.stringify(value);
+    case 'tags': {
+      const tags = tagValues(value);
+      return tags.length === 0 ? '—' : tags.map(tag => tagLabel(field, tag)).join(', ');
+    }
     default:
       return typeof value === 'object' ? JSON.stringify(value) : String(value);
   }

package/src/utils/list-query.ts

@@ -0,0 +1,199 @@
+/**
+ * Pure model of a list's query state: search text, scope tab, sort and page.
+ *
+ * The URL is the source of truth (see useViewState), so every list view is a
+ * link. This file holds the rules and nothing else: parse the URL, write it
+ * back, apply a change, and turn the state into the adapter's ListParams. It
+ * knows no React and no resource schema, which keeps it testable on its own.
+ *
+ * URL names: `q`, `tab`, `sort`, `dir`, `page`, `size`. They are reserved (see view-filters.ts), so a
+ * resource column with one of those names cannot be drilled into from the URL. `tab` and
+ * `dir`, not `scope` and `order`, because those are common column names.
+ *
+ * Column filters from the URL (`?state=draft`) are a separate mechanism
+ * (view-filters.ts) and are left alone here.
+ */
+
+import type { ViewParams } from '../hooks/useViewState';
+import type { ListParams } from '../types';
+
+/** Longest search text kept. A pasted paragraph is not a search. */
+export const MAX_SEARCH_LENGTH = 200;
+
+/** Search text only: PostgreSQL text values cannot contain NUL. */
+export function normalizeSearchText(text?: string): string | undefined {
+  return text?.replace(/\u0000/g, '').trim().slice(0, MAX_SEARCH_LENGTH) || undefined;
+}
+
+export interface ListQuery {
+  search?: string;
+  scope?: string;
+  sort?: string;
+  order?: 'asc' | 'desc';
+  /** 1-based. Absent means page 1. */
+  page?: number;
+  /** Rows per page (`size` in the URL). Absent means the resource's default. */
+  perPage?: number;
+}
+
+/** Largest page size the list fetches. A larger `size` in the URL is capped to it. */
+export const MAX_PAGE_SIZE = 500;
+
+/**
+ * The page size to use for a resource's configured `perPage`: a whole number
+ * above 0, capped to MAX_PAGE_SIZE. Anything else gives `fallback`, so a bad
+ * config never reaches the adapter or the page bar.
+ */
+export function resolvePageSize(configured: number | undefined, fallback = 20): number {
+  if (configured === undefined || !Number.isInteger(configured) || configured <= 0) return fallback;
+  return Math.min(configured, MAX_PAGE_SIZE);
+}
+
+/**
+ * The page that holds the first row of `page` once the list shows `newSize`
+ * rows a page, so changing the size keeps that row in view.
+ */
+export function pageForSize(page: number, oldSize: number, newSize: number): number {
+  return Math.floor(((page - 1) * oldSize) / newSize) + 1;
+}
+
+const POSITIVE_INTEGER = /^[1-9]\d*$/;
+/** No real list has more pages. A larger number is not a page: sent on, it is read as an exponent. */
+const MAX_PAGE = 1_000_000;
+
+/** URL query → list state. Anything malformed is ignored, never thrown. */
+export function parseListQuery(params: ViewParams): ListQuery {
+  const query: ListQuery = {};
+
+  const search = normalizeSearchText(params.q);
+  if (search) query.search = search;
+
+  const scope = params.tab?.trim();
+  if (scope) query.scope = scope;
+
+  const sort = params.sort?.trim();
+  if (sort) query.sort = sort;
+
+  if (params.dir === 'asc' || params.dir === 'desc') query.order = params.dir;
+
+  if (params.page && POSITIVE_INTEGER.test(params.page) && Number(params.page) <= MAX_PAGE) query.page = Number(params.page);
+
+  if (params.size && POSITIVE_INTEGER.test(params.size)) query.perPage = Math.min(Number(params.size), MAX_PAGE_SIZE);
+
+  return query;
+}
+
+/**
+ * List state → a `setParams` delta. Every key is present, so a cleared field
+ * removes its key from the URL. Defaults (page 1, no search, the resource's
+ * `defaultPerPage`) are not written.
+ */
+export function listQueryToParams(
+  query: ListQuery,
+  options: { defaultPerPage?: number } = {},
+): Record<string, string | undefined> {
+  return {
+    q: query.search || undefined,
+    tab: query.scope || undefined,
+    sort: query.sort || undefined,
+    dir: query.order,
+    page: query.page && query.page > 1 ? String(query.page) : undefined,
+    size: query.perPage && query.perPage !== options.defaultPerPage ? String(query.perPage) : undefined,
+  };
+}
+
+/**
+ * Apply a change. Changing what the list shows (search, scope, sort) returns to
+ * page 1, because the old page number no longer means anything. A patch that
+ * names a page keeps it.
+ */
+export function updateListQuery(prev: ListQuery, patch: Partial<ListQuery>): ListQuery {
+  const next: ListQuery = { ...prev, ...patch };
+  const changesView = (['search', 'scope', 'sort', 'order'] as const).some(
+    key => key in patch && patch[key] !== prev[key],
+  );
+  if (changesView && !('page' in patch)) next.page = undefined;
+  return next;
+}
+
+/**
+ * AND two filter objects together. Two conditions on one column are kept as an
+ * array (the adapter applies an array as several ANDed conditions), so a scope
+ * and a column filter on the same column cannot overwrite each other.
+ */
+export function mergeFilters(
+  a?: Record<string, unknown>,
+  b?: Record<string, unknown>,
+): Record<string, unknown> | undefined {
+  const merged: Record<string, unknown> = {};
+  for (const source of [a, b]) {
+    if (!source) continue;
+    for (const [key, value] of Object.entries(source)) {
+      if (value == null) continue;
+      merged[key] = key in merged ? [...toArray(merged[key]), ...toArray(value)] : value;
+    }
+  }
+  return Object.keys(merged).length ? merged : undefined;
+}
+
+const toArray = (value: unknown): unknown[] => (Array.isArray(value) ? value : [value]);
+
+export interface BuildListParamsOptions {
+  /** The resource's default page size, used when the query has none. */
+  perPage?: number;
+  /** Filters from outside the query (analytics header, URL column filters). */
+  baseFilter?: Record<string, unknown>;
+  /** The active scope's filter, already resolved from the scope id. */
+  scopeFilter?: Record<string, unknown>;
+  /** Columns a user may sort by. A sort outside this set is dropped. */
+  sortableFields?: ReadonlySet<string>;
+  /** Used when the query has no valid sort of its own. */
+  defaultSort?: { field: string; order?: 'asc' | 'desc' };
+}
+
+/** List state → the adapter's ListParams. */
+export function buildListParams(query: ListQuery, options: BuildListParamsOptions): ListParams {
+  const sortAllowed = query.sort && (!options.sortableFields || options.sortableFields.has(query.sort));
+
+  let sort: string | undefined;
+  let order: 'asc' | 'desc' | undefined;
+  if (sortAllowed) {
+    sort = query.sort;
+    order = query.order ?? 'asc';
+  } else if (options.defaultSort && (!options.sortableFields || options.sortableFields.has(options.defaultSort.field))) {
+    sort = options.defaultSort.field;
+    order = options.defaultSort.order ?? 'asc';
+  }
+
+  return {
+    page: query.page ?? 1,
+    perPage: query.perPage ?? options.perPage,
+    search: query.search,
+    sort,
+    order,
+    filter: mergeFilters(options.baseFilter, options.scopeFilter),
+  };
+}
+
+/** What the list is sorted by right now, defaults included. */
+export interface EffectiveSort {
+  sort?: string;
+  order?: 'asc' | 'desc';
+}
+
+/**
+ * The next sort after a click on a column header: ascending, then descending,
+ * then off (back to the default sort). On the default sort's own column "off"
+ * would be the same view, so it flips between ascending and descending instead.
+ * `off` is `{ sort: undefined, order: undefined }`, which clears both from the URL.
+ */
+export function nextSort(
+  current: EffectiveSort,
+  key: string,
+  defaultSort?: { field: string; order?: 'asc' | 'desc' },
+): EffectiveSort {
+  if (current.sort !== key) return { sort: key, order: 'asc' };
+  if ((current.order ?? 'asc') === 'asc') return { sort: key, order: 'desc' };
+  if (defaultSort?.field === key) return { sort: key, order: 'asc' };
+  return { sort: undefined, order: undefined };
+}

package/src/utils/required.ts

@@ -0,0 +1,10 @@
+import type { FieldDefinition } from '../types';
+
+/**
+ * Whether a value fails `validation.required`: null, undefined or ''. For a
+ * tags field an empty array fails too.
+ */
+export function missingRequired(field: FieldDefinition, value: unknown): boolean {
+  if (value == null || value === '') return true;
+  return field.type === 'tags' && Array.isArray(value) && value.length === 0;
+}