@everystack/admin 0.4.3 → 0.4.5

package/src/hooks/useAdminNavigation.ts

@@ -0,0 +1,19 @@
+/**
+ * AdminNavigationContext — what an admin link needs to navigate: the router's
+ * push, the admin's mount point, and the configured resource names (a link
+ * to any other resource renders as plain text). AdminRouter provides it.
+ */
+
+import { createContext, useContext } from 'react';
+
+export interface AdminNavigationContextValue {
+  push(href: string): void;
+  basePath: string;
+  resources: string[];
+}
+
+export const AdminNavigationContext = createContext<AdminNavigationContextValue | null>(null);
+
+export function useAdminNavigation(): AdminNavigationContextValue | null {
+  return useContext(AdminNavigationContext);
+}

package/src/hooks/useListQuery.ts

@@ -19,6 +19,8 @@ export interface UseListQueryResult {
 export interface UseListQueryOptions {
   /** The resource's page size. A query at this size leaves `size` out of the URL. */
   defaultPerPage?: number;
+  /** The resource's default scope id. A query on this scope leaves `tab` out of the URL. */
+  defaultScope?: string;
 }
 
 export function useListQuery(options: UseListQueryOptions = {}): UseListQueryResult {
@@ -31,13 +33,13 @@ export function useListQuery(options: UseListQueryOptions = {}): UseListQueryRes
 
   // `update` is stable but must read the newest query: a debounce timer or an
   // event handler may call it from a render that is already out of date.
-  const latest = useRef({ query, setParams: view?.setParams, defaultPerPage: options.defaultPerPage });
-  latest.current = { query, setParams: view?.setParams, defaultPerPage: options.defaultPerPage };
+  const latest = useRef({ query, setParams: view?.setParams, defaultPerPage: options.defaultPerPage, defaultScope: options.defaultScope });
+  latest.current = { query, setParams: view?.setParams, defaultPerPage: options.defaultPerPage, defaultScope: options.defaultScope };
 
   const update = useCallback((patch: Partial<ListQuery>) => {
-    const { query: current, setParams, defaultPerPage } = latest.current;
+    const { query: current, setParams, defaultPerPage, defaultScope } = latest.current;
     const next = updateListQuery(current, patch);
-    if (setParams) setParams(listQueryToParams(next, { defaultPerPage }));
+    if (setParams) setParams(listQueryToParams(next, { defaultPerPage, defaultScope }));
     else setLocal(next);
   }, []);
 

package/src/hooks/useRelationLabels.ts

@@ -0,0 +1,131 @@
+/**
+ * useRelationLabels — the display names of relation fields, one batched
+ * request per related `resource.field`.
+ *
+ * Fields that point at the same `resource.field` share one fetchList: the
+ * unique ids of the rows go in one `in.(...)` filter, and the select names the
+ * matched column plus every displayField. Only ids not seen before are
+ * requested, so paging back costs nothing. An id outside /^[A-Za-z0-9_-]+$/
+ * never goes in the filter; it keeps showing raw.
+ *
+ * A failed request is swallowed: the labels stay missing and the cell keeps
+ * the id. The list never waits on this hook. Keys are always String(value),
+ * so a number in the row matches a string in the related row.
+ */
+
+import { useEffect, useMemo, useRef, useState } from 'react';
+import type { DataAdapter } from '../adapters/types';
+import type { FieldDefinition } from '../types';
+
+const RELATION_CHUNK = 100;
+
+/** field name → String(stored value) → label. */
+export type RelationLabels = Map<string, Map<string, string>>;
+
+type Row = Record<string, unknown>;
+
+interface RelationGroup {
+  /** `${resource}.${field}`, the cache key prefix. */
+  key: string;
+  resource: string;
+  field: string;
+  fields: FieldDefinition[];
+  displayFields: string[];
+}
+
+const SAFE_ID = /^[A-Za-z0-9_-]+$/;
+
+/** String(value) when it may go in a filter and be a map key; null for null, undefined, '' or an unsafe id. */
+export function safeRelationId(value: unknown): string | null {
+  if (value == null) return null;
+  const id = String(value);
+  return id !== '' && SAFE_ID.test(id) ? id : null;
+}
+
+function groupRelationFields(fields: FieldDefinition[]): RelationGroup[] {
+  const groups = new Map<string, RelationGroup>();
+  for (const field of fields) {
+    const relation = field.relation;
+    if (field.type !== 'relation' || !relation) continue;
+    const key = `${relation.resource}.${relation.field}`;
+    let group = groups.get(key);
+    if (!group) {
+      group = { key, resource: relation.resource, field: relation.field, fields: [], displayFields: [] };
+      groups.set(key, group);
+    }
+    group.fields.push(field);
+    if (relation.displayField && !group.displayFields.includes(relation.displayField)) {
+      group.displayFields.push(relation.displayField);
+    }
+  }
+  return [...groups.values()];
+}
+
+export function useRelationLabels(
+  adapter: DataAdapter,
+  fields: FieldDefinition[],
+  rows: ReadonlyArray<Row>,
+): RelationLabels {
+  // `${resource}.${field}:${id}` → the related row, for the component's lifetime.
+  const cache = useRef(new Map<string, Row>());
+  // Ids asked for (in flight or answered), so a re-render never asks twice.
+  const requested = useRef(new Set<string>());
+  const mounted = useRef(true);
+  const [version, setVersion] = useState(0);
+  const groups = useMemo(() => groupRelationFields(fields), [fields]);
+
+  useEffect(() => {
+    mounted.current = true;
+    return () => { mounted.current = false; };
+  }, []);
+
+  useEffect(() => {
+    for (const group of groups) {
+      if (group.displayFields.length === 0) continue;
+      const ids = [...new Set(
+        rows.flatMap(row => group.fields.map(f => safeRelationId(row[f.name]))),
+      )].filter((id): id is string => id !== null && !requested.current.has(`${group.key}:${id}`));
+      if (ids.length === 0) continue;
+      for (const id of ids) requested.current.add(`${group.key}:${id}`);
+
+      // 100 ids per request keeps the URL short (a page may hold 500 UUIDs).
+      for (let start = 0; start < ids.length; start += RELATION_CHUNK) {
+        const chunk = ids.slice(start, start + RELATION_CHUNK);
+        adapter.fetchList(group.resource, {
+          page: 1,
+          perPage: chunk.length,
+          filter: { [group.field]: `in.(${chunk.join(',')})` },
+          select: `${group.field},${group.displayFields.join(',')}`,
+        }).then(result => {
+          for (const related of result.data) {
+            cache.current.set(`${group.key}:${String(related[group.field])}`, related);
+          }
+          if (mounted.current) setVersion(v => v + 1);
+        }).catch(() => {
+          // The cell keeps the id. Forget the ask, so a later page may retry it.
+          for (const id of chunk) requested.current.delete(`${group.key}:${id}`);
+        });
+      }
+    }
+  }, [adapter, groups, rows]);
+
+  return useMemo(() => {
+    const labels: RelationLabels = new Map();
+    for (const group of groups) {
+      for (const field of group.fields) {
+        const byId = new Map<string, string>();
+        const displayField = field.relation?.displayField;
+        for (const row of rows) {
+          const id = safeRelationId(row[field.name]);
+          if (id === null || !displayField) continue;
+          const label = cache.current.get(`${group.key}:${id}`)?.[displayField];
+          if (label != null) byId.set(id, String(label));
+        }
+        labels.set(field.name, byId);
+      }
+    }
+    return labels;
+    // `version` is the signal that the cache grew.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [groups, rows, version]);
+}

package/src/hooks/useScopeCounts.ts

@@ -30,7 +30,7 @@ export function useScopeCounts(options: UseScopeCountsOptions): Record<string, n
   const { resource, scopes, enabled, baseFilter, search, searchFields, refreshToken } = options;
 
   // The inputs by value: a new object with the same content must not ask again.
-  const key = JSON.stringify([resource, scopes?.map(s => [s.id, s.filter]), baseFilter, search, searchFields]);
+  const key = JSON.stringify([resource, scopes?.map(s => [s.id, s.filter, s.deleted]), baseFilter, search, searchFields]);
 
   useEffect(() => {
     const aggregate = adapter.aggregate?.bind(adapter);
@@ -52,7 +52,12 @@ export function useScopeCounts(options: UseScopeCountsOptions): Record<string, n
           .then(result => countsFromGrouped(result.data, group)),
       ),
       ...plan.single.map(scope =>
-        aggregate(resource, { aggregates: count, filter: mergeFilters(baseFilter, scope.filter), ...shared })
+        aggregate(resource, {
+          aggregates: count,
+          filter: mergeFilters(baseFilter, scope.filter),
+          ...shared,
+          ...(scope.deleted ? { deleted: scope.deleted } : {}),
+        })
           .then(result => ({ [scope.id]: Number(result.data[0]?.count ?? 0) })),
       ),
     ];

package/src/index.ts

@@ -31,6 +31,8 @@ export type {
   AdminConfig,
   ListParams,
   ScopeConfig,
+  AssociationConfig,
+  DeletedMode,
   ListResult,
   DataRecord,
   AggregateFunction,
@@ -90,6 +92,12 @@ export {
   type ViewStateContextValue,
 } from './hooks/useViewState';
 
+export {
+  AdminNavigationContext,
+  useAdminNavigation,
+  type AdminNavigationContextValue,
+} from './hooks/useAdminNavigation';
+
 // RPC Factory
 export {
   createResourceDashboardRpcs,
@@ -161,8 +169,10 @@ export { useEditors, EditorRegistryContext } from './hooks/useEditors';
 export { ImageFieldInput } from './components/ImageFieldInput';
 export { AvatarFieldInput } from './components/AvatarFieldInput';
 export { TagsFieldInput, type TagsFieldInputProps } from './components/TagsFieldInput';
+export { RelationFieldInput, type RelationFieldInputProps } from './components/RelationFieldInput';
 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';
 
 // Image utilities

package/src/screens/AdminRouter.tsx

@@ -12,6 +12,7 @@ import React, { useMemo } from 'react';
 import { useAdminConfig } from '../hooks/useAdminConfig';
 import { useDataAdapter } from '../hooks/useAdminData';
 import { ViewStateContext, normalizeParams, buildQueryString } from '../hooks/useViewState';
+import { AdminNavigationContext } from '../hooks/useAdminNavigation';
 import { AdminDashboard } from './AdminDashboard';
 import { ResourceListView } from './ResourceListView';
 import { ResourceShow } from './ResourceShow';
@@ -80,10 +81,17 @@ export function AdminRouter({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [JSON.stringify(searchParams), pathname, router]);
 
+  const navigation = useMemo(
+    () => ({ push: (href: string) => router.push(href), basePath, resources: config.resources.map(r => r.name) }),
+    [router, basePath, config.resources],
+  );
+
   return (
-    <ViewStateContext.Provider value={viewState}>
-      {renderScreen()}
-    </ViewStateContext.Provider>
+    <AdminNavigationContext.Provider value={navigation}>
+      <ViewStateContext.Provider value={viewState}>
+        {renderScreen()}
+      </ViewStateContext.Provider>
+    </AdminNavigationContext.Provider>
   );
 
   function renderScreen(): React.ReactElement {
@@ -111,15 +119,22 @@ export function AdminRouter({
         />
       );
 
-    case 'show':
+    case 'show': {
+      // Show gets Delete only behind the delete preview, i.e. when the resource declares associations.
+      const hasAssociations = Boolean(config.resources.find(r => r.name === match.resource)?.associations?.length);
       return (
         <ResourceShow
           resource={match.resource!}
           id={match.id!}
           onEditPress={() => go({ resource: match.resource, id: match.id, action: 'edit' })}
+          onDeletePress={hasAssociations
+            ? async () => { await adapter.delete(match.resource!, match.id!); go({ resource: match.resource }); }
+            : undefined}
           onBackPress={() => go({ resource: match.resource })}
+          confirmDelete={viewState.params.confirmDelete === '1'}
         />
       );
+    }
 
     case 'list':
     default: {

package/src/screens/ResourceCreate.tsx

@@ -17,6 +17,7 @@ import { FormField, TextInput, SelectInput, SwitchInput, DateInput, Button, Erro
 import { ImageFieldInput } from '../components/ImageFieldInput';
 import { AvatarFieldInput } from '../components/AvatarFieldInput';
 import { TagsFieldInput } from '../components/TagsFieldInput';
+import { RelationFieldInput } from '../components/RelationFieldInput';
 import { FormActionBar } from '../components/FormActionBar';
 import { FieldColumns } from '../components/FieldColumns';
 import { useScrollToFirstError } from '../hooks/useScrollToFirstError';
@@ -171,6 +172,7 @@ interface FieldInputProps {
 
 function FieldInput({ field, value, error, onChange, values }: FieldInputProps): React.ReactElement {
   const editors = useEditors();
+  const adapter = useDataAdapter();
 
   // Resolution: inline input → registered editor → type-based default.
   if (field.input) {
@@ -293,6 +295,17 @@ function FieldInput({ field, value, error, onChange, values }: FieldInputProps):
     case 'tags':
       return <TagsFieldInput field={field} value={value} error={error} onChange={onChange} />;
 
+    case 'relation':
+      // Without `relation` there is nothing to search: the plain text input below.
+      if (field.relation) {
+        return (
+          <FormField label={label} error={error} required={required}>
+            <RelationFieldInput field={field} value={value} onChange={onChange} adapter={adapter} />
+          </FormField>
+        );
+      }
+      // falls through
+
     default:
       return (
         <FormField label={label} error={error} required={required}>

package/src/screens/ResourceEdit.tsx

@@ -17,6 +17,7 @@ import { FormField, TextInput, SelectInput, SwitchInput, DateInput, Button, Load
 import { ImageFieldInput } from '../components/ImageFieldInput';
 import { AvatarFieldInput } from '../components/AvatarFieldInput';
 import { TagsFieldInput } from '../components/TagsFieldInput';
+import { RelationFieldInput } from '../components/RelationFieldInput';
 import { FormActionBar } from '../components/FormActionBar';
 import { FieldColumns } from '../components/FieldColumns';
 import { useScrollToFirstError } from '../hooks/useScrollToFirstError';
@@ -71,7 +72,8 @@ export function ResourceEdit({ resource, id, onSuccess, onCancel }: ResourceEdit
     setLoading(true);
     setFetchError(null);
     try {
-      const result = await adapter.fetchOne(resource, id);
+      const select = resourceConfig?.select;
+      const result = select ? await adapter.fetchOne(resource, id, { select }) : await adapter.fetchOne(resource, id);
       setRecord(result);
       // Pre-populate form data with existing values
       const initial: Record<string, unknown> = {};
@@ -84,7 +86,7 @@ export function ResourceEdit({ resource, id, onSuccess, onCancel }: ResourceEdit
     } finally {
       setLoading(false);
     }
-  }, [adapter, resource, id, fields]);
+  }, [adapter, resource, id, fields, resourceConfig?.select]);
 
   useEffect(() => {
     fetchRecord();
@@ -216,6 +218,7 @@ interface EditFieldInputProps {
 
 function EditFieldInput({ field, value, error, onChange, record, values }: EditFieldInputProps): React.ReactElement {
   const editors = useEditors();
+  const adapter = useDataAdapter();
 
   // Resolution: inline input → registered editor → type-based default.
   if (field.input) {
@@ -335,6 +338,17 @@ function EditFieldInput({ field, value, error, onChange, record, values }: EditF
     case 'tags':
       return <TagsFieldInput field={field} value={value} error={error} onChange={onChange} />;
 
+    case 'relation':
+      // Without `relation` there is nothing to search: the plain text input below.
+      if (field.relation) {
+        return (
+          <FormField label={label} error={error} required={required}>
+            <RelationFieldInput field={field} value={value} onChange={onChange} adapter={adapter} />
+          </FormField>
+        );
+      }
+      // falls through
+
     default:
       return (
         <FormField label={label} error={error} required={required}>

package/src/screens/ResourceList.tsx

@@ -21,6 +21,8 @@ import { View, Text } from 'react-native';
 import { useAdminConfig } from '../hooks/useAdminConfig';
 import { useAdminData, useDataAdapter } from '../hooks/useAdminData';
 import { useListQuery } from '../hooks/useListQuery';
+import { useAdminNavigation } from '../hooks/useAdminNavigation';
+import { adminHref } from '../utils/admin-routing';
 import { buildListParams, mergeFilters, nextSort, normalizeSearchText, pageForSize, parseListQuery, resolvePageSize } from '../utils/list-query';
 import { resolveScope } from '../utils/scopes';
 import { useScopeCounts } from '../hooks/useScopeCounts';
@@ -34,6 +36,8 @@ import { ImageDisplay } from '../components/ImageDisplay';
 import { RowActionButton } from '../components/RowActionButton';
 import { InlineEnumCell } from '../components/InlineEnumCell';
 import { wrapBareText } from '../components/CellText';
+import { RelationValue } from '../components/RelationValue';
+import { useRelationLabels, type RelationLabels } from '../hooks/useRelationLabels';
 import type { DataAdapter } from '../adapters/types';
 import type { ResourceConfig, FieldDefinition, DataRecord, RowActionConfig } from '../types';
 
@@ -64,7 +68,8 @@ export function ResourceList({ resource, onRowPress, onEditPress, onCreatePress,
     () => [...new Set([...PAGE_SIZES, defaultPerPage])].sort((a, b) => a - b),
     [defaultPerPage],
   );
-  const { query, update } = useListQuery({ defaultPerPage });
+  const defaultScope = resolveScope(resourceConfig?.scopes, undefined)?.id;
+  const { query, update } = useListQuery({ defaultPerPage, defaultScope });
 
   const searchFields = useMemo(
     () => resourceConfig?.fields.filter(f => f.searchable).map(f => f.name) ?? [],
@@ -79,7 +84,9 @@ export function ResourceList({ resource, onRowPress, onEditPress, onCreatePress,
     [resourceConfig, query.scope],
   );
   const listParams = useMemo(
-    () => buildListParams(query, { perPage: defaultPerPage, baseFilter, scopeFilter: activeScope?.filter, sortableFields, defaultSort }),
+    () => buildListParams(query, {
+      perPage: defaultPerPage, baseFilter, scopeFilter: activeScope?.filter, scopeDeleted: activeScope?.deleted, sortableFields, defaultSort,
+    }),
     [query, defaultPerPage, baseFilter, activeScope, sortableFields, defaultSort],
   );
 
@@ -120,6 +127,8 @@ export function ResourceList({ resource, onRowPress, onEditPress, onCreatePress,
     sort: listParams.sort,
     order: listParams.order,
     ...searchParams,
+    select: resourceConfig?.select,
+    deleted: listParams.deleted,
     baseFilter: mergeFilters(listParams.filter, legacySearchFilter),
   });
 
@@ -157,6 +166,14 @@ export function ResourceList({ resource, onRowPress, onEditPress, onCreatePress,
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [searchText]);
 
+  // Relation cells print the related row's displayField, one request per related resource per page.
+  const relationFields = useMemo(() => {
+    if (!resourceConfig) return [];
+    const listed = new Set(resourceConfig.listFields ?? resourceConfig.fields.map(f => f.name));
+    return resourceConfig.fields.filter(f => listed.has(f.name) && f.type === 'relation' && !f.render);
+  }, [resourceConfig]);
+  const relationLabels = useRelationLabels(adapter, relationFields, data);
+
   // Build columns from field definitions, plus an actions column combining the
   // built-in Show/Edit/Delete (gated by actions.*) with any custom rowActions.
   // Returns the refetch, so the cell can re-sync once the new rows are in.
@@ -165,18 +182,27 @@ export function ResourceList({ resource, onRowPress, onEditPress, onCreatePress,
     return refetch();
   }, [refetch]);
 
+  const deletedOnly = listParams.deleted === 'only';
+  // Under AdminRouter, Delete on a resource with associations opens Show with its delete preview.
+  const navigation = useAdminNavigation();
   const columns = useMemo(() => {
     if (!resourceConfig) return [];
-    const cols = fieldsToColumns(resourceConfig, adapter, afterInlineEdit);
+    const cols = fieldsToColumns(resourceConfig, adapter, afterInlineEdit, relationLabels, deletedOnly);
+    const onConfirmDelete = navigation
+      ? (record: DataRecord) => {
+        const id = (record[resourceConfig.primaryKey ?? 'id'] as string | number) ?? record.id;
+        navigation.push(`${adminHref(navigation.basePath, { resource, id })}?confirmDelete=1`);
+      }
+      : undefined;
     const actions = [
-      ...standardRowActions(resourceConfig, { onShow: onRowPress, onEdit: onEditPress }),
+      ...standardRowActions(resourceConfig, { onShow: onRowPress, onEdit: onEditPress, onConfirmDelete }, { deletedOnly }),
       ...(resourceConfig.rowActions ?? []),
     ];
     if (actions.length) {
       cols.push(actionsColumn(resourceConfig, actions, adapter, refetch));
     }
     return cols;
-  }, [resourceConfig, adapter, refetch, afterInlineEdit, onRowPress, onEditPress]);
+  }, [resourceConfig, 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) => {
@@ -278,6 +304,8 @@ function fieldsToColumns(
   resourceConfig: ResourceConfig,
   adapter: DataAdapter,
   onInlineSaved: () => Promise<void>,
+  relationLabels: RelationLabels,
+  deletedOnly: boolean,
 ): DataTableColumn[] {
   const fieldNames = resourceConfig.listFields ?? resourceConfig.fields.map(f => f.name);
   const fieldMap = new Map(resourceConfig.fields.map(f => [f.name, f]));
@@ -292,23 +320,31 @@ function fieldsToColumns(
       ...(field.listWidth !== undefined && { width: field.listWidth }),
       ...(field.listPriority !== undefined && { priority: field.listPriority }),
       ...(field.listHideBelow !== undefined && { hideBelow: field.listHideBelow }),
-      render: cellRenderer(field, resourceConfig, adapter, onInlineSaved),
+      render: cellRenderer(field, resourceConfig, adapter, onInlineSaved, relationLabels, deletedOnly),
     }));
 }
 
 /**
  * Cell rendering precedence: custom render → image thumbnail → type text.
  * (See render-resolution.cellRenderKind.) An `inlineEdit` enum field shows a
- * picker in place of the type text, unless the resource sets `actions.edit: false`.
+ * picker in place of the type text, unless the resource sets `actions.edit: false`
+ * or the tab lists deleted rows only (the save matches live rows only, so it would fail).
+ * A relation field links to the related show page, labelled with its displayField.
  */
 function cellRenderer(
   field: FieldDefinition,
   resourceConfig: ResourceConfig,
   adapter: DataAdapter,
   onInlineSaved: () => Promise<void>,
+  relationLabels: RelationLabels,
+  deletedOnly: boolean,
 ): DataTableColumn['render'] {
   const kind = cellRenderKind(field);
-  if (kind === 'text' && field.inlineEdit === true && field.type === 'enum' && resourceConfig.actions?.edit !== false) {
+  const relation = field.relation;
+  if (kind === 'text' && field.type === 'relation' && relation) {
+    return (value) => <RelationValue resource={relation.resource} value={value} labels={relationLabels.get(field.name)} numberOfLines={1} />;
+  }
+  if (kind === 'text' && field.inlineEdit === true && field.type === 'enum' && resourceConfig.actions?.edit !== false && !deletedOnly) {
     const primaryKey = resourceConfig.primaryKey ?? 'id';
     return (value, record) => (
       <InlineEnumCell