@everystack/admin 0.4.2 → 0.4.4

package/src/hooks/useAdminData.ts

@@ -39,6 +39,13 @@ export interface UseAdminDataOptions extends ListParams {
    * Memoize it at the call site to keep identity stable across renders.
    */
   baseFilter?: Record<string, unknown>;
+  /**
+   * The caller owns the list query (e.g. the URL). `page`, `perPage`, `sort`,
+   * `order`, `search` and `searchFields` are then the values to fetch, read on every
+   * render, not starting values; the hook's own setters for them do nothing.
+   * Without this, they are only initial values and the hook keeps its own state.
+   */
+  controlled?: boolean;
 }
 
 export interface UseAdminDataResult<T extends DataRecord = DataRecord> {
@@ -50,7 +57,19 @@ export interface UseAdminDataResult<T extends DataRecord = DataRecord> {
   loading: boolean;
   /** Error state */
   error: Error | null;
-  /** Refetch data */
+  /**
+   * True while a fetch started by `refetch()` runs over data an earlier fetch
+   * already put on screen, with no error shown. A screen can keep that data in
+   * view instead of a loading state. `loading` is still true during it. False
+   * on the first load, on a page, sort, search or filter change, and on a
+   * retry after an error.
+   */
+  refreshing: boolean;
+  /**
+   * Fetch again with the same params. Resolves after that fetch has settled and
+   * its result (data, total, or error) is in state. Never rejects: a failure
+   * lands in `error`.
+   */
   refetch: () => Promise<void>;
   /** Current page */
   page: number;
@@ -76,13 +95,19 @@ export function useAdminData<T extends DataRecord = DataRecord>(
   const [loading, setLoading] = useState(!options.skip);
   const [error, setError] = useState<Error | null>(null);
 
-  // Params state
+  // Params state. In controlled mode the caller's options win over this state.
+  const controlled = options.controlled === true;
   const [page, setPage] = useState(options.page ?? 1);
   const [perPage, setPerPage] = useState(options.perPage ?? 10);
   const [sort, setSortState] = useState(options.sort);
   const [order, setOrder] = useState(options.order ?? 'asc');
   const [filter, setFilterState] = useState(options.filter ?? {});
 
+  const pageValue = controlled ? options.page ?? 1 : page;
+  const perPageValue = controlled ? options.perPage ?? 10 : perPage;
+  const sortValue = controlled ? options.sort : sort;
+  const orderValue = controlled ? options.order ?? 'asc' : order;
+
   // Manual-refetch trigger (bumped by refetch()).
   const [refetchIndex, setRefetchIndex] = useState(0);
 
@@ -91,80 +116,139 @@ export function useAdminData<T extends DataRecord = DataRecord>(
   // new-but-equal `filter`/`baseFilter` (e.g. FilterBar's initial empty search,
   // or the auth refresh re-rendering the tree) does NOT re-fire the fetch.
   // This is what collapses the per-load double request.
-  const reqKey = JSON.stringify({
+  const paramsKey = JSON.stringify({
     resource,
-    page,
-    perPage,
-    sort: sort ?? null,
-    order,
+    page: pageValue,
+    perPage: perPageValue,
+    sort: sortValue ?? null,
+    order: orderValue,
     baseFilter: options.baseFilter ?? {},
     filter,
     search: options.search ?? null,
-    refetchIndex,
+    searchFields: options.searchFields ?? null,
+    select: options.select ?? null,
+    deleted: options.deleted ?? null,
   });
+  const reqKey = `${paramsKey}#${refetchIndex}`;
 
   // Latest-request guard: only the most recent fetch may write state, so a
   // superseded in-flight response can't clobber newer data (out-of-order races).
   const seqRef = useRef(0);
+  const [refreshing, setRefreshing] = useState(false);
+  // The params of the data on screen, set only by a fetch that succeeded; null after an error.
+  const shownParamsRef = useRef<string | null>(null);
+  const lastRefetchIndexRef = useRef(refetchIndex);
+  // refetch() callers not yet taken by a fetch, and the ones the latest fetch carries.
+  const queuedRef = useRef<Array<() => void>>([]);
+  const carriedRef = useRef<Array<() => void>>([]);
 
   useEffect(() => {
-    if (options.skip) return;
+    const byRefetch = refetchIndex !== lastRefetchIndexRef.current;
+    lastRefetchIndexRef.current = refetchIndex;
+    if (options.skip) {
+      settle(queuedRef.current.splice(0));
+      return;
+    }
     const seq = ++seqRef.current;
+    // A superseded fetch hands its callers to this one: they resolve once fresh data is in.
+    const waiters = [...carriedRef.current, ...queuedRef.current.splice(0)];
+    carriedRef.current = waiters;
     setLoading(true);
+    setRefreshing(byRefetch && shownParamsRef.current === paramsKey);
     setError(null);
 
     adapter
       .fetchList<T>(resource, {
-        page,
-        perPage,
-        sort,
-        order,
+        page: pageValue,
+        perPage: perPageValue,
+        sort: sortValue,
+        order: orderValue,
         // Base filters (time range, segment) sit beneath the in-view search filter.
         filter: { ...(options.baseFilter ?? {}), ...filter },
-        search: options.search,
+        ...(options.search !== undefined ? { search: options.search } : {}),
+        ...(options.searchFields !== undefined ? { searchFields: options.searchFields } : {}),
+        ...(options.select ? { select: options.select } : {}),
+        ...(options.deleted ? { deleted: options.deleted } : {}),
       })
       .then(result => {
         if (seq !== seqRef.current) return;
         setData(result.data);
         setTotal(result.total);
+        shownParamsRef.current = paramsKey;
       })
       .catch(err => {
         if (seq !== seqRef.current) return;
         setError(err instanceof Error ? err : new Error(String(err)));
+        shownParamsRef.current = null;
       })
       .finally(() => {
-        if (seq === seqRef.current) setLoading(false);
+        if (seq !== seqRef.current) return;
+        setLoading(false);
+        setRefreshing(false);
+        carriedRef.current = [];
+        settle(waiters);
       });
     // reqKey encodes every input; the per-field deps are folded into it.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [adapter, reqKey, options.skip]);
 
+  // On unmount no fetch will write state again: release every waiting caller.
+  const mountedRef = useRef(true);
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+      settle(carriedRef.current.splice(0));
+      settle(queuedRef.current.splice(0));
+    };
+  }, []);
+
   // Refetch by bumping the trigger — runs through the same effect/guard path.
-  const refetch = useCallback(async () => {
+  // After unmount no effect will run, so it resolves at once.
+  const refetch = useCallback((): Promise<void> => new Promise<void>(resolve => {
+    if (!mountedRef.current) {
+      resolve();
+      return;
+    }
+    queuedRef.current.push(resolve);
     setRefetchIndex(i => i + 1);
-  }, []);
+  }), []);
 
   const setSort = useCallback((field: string, newOrder?: 'asc' | 'desc') => {
+    if (controlled) return;
     setSortState(field);
     setOrder(newOrder ?? 'asc');
-  }, []);
+  }, [controlled]);
 
   const setFilter = useCallback((newFilter: Record<string, unknown>) => {
     setFilterState(newFilter);
-    setPage(1); // Reset to first page when filter changes
-  }, []);
+    if (!controlled) setPage(1); // Reset to first page when filter changes
+  }, [controlled]);
+
+  const setPageChecked = useCallback((next: number) => {
+    if (!controlled) setPage(next);
+  }, [controlled]);
+
+  const setPerPageChecked = useCallback((next: number) => {
+    if (!controlled) setPerPage(next);
+  }, [controlled]);
 
   return {
     data,
     total,
     loading,
+    refreshing,
     error,
     refetch,
-    page,
-    perPage,
-    setPage,
-    setPerPage,
+    page: pageValue,
+    perPage: perPageValue,
+    setPage: setPageChecked,
+    setPerPage: setPerPageChecked,
     setSort,
     setFilter,
   };
 }
+
+function settle(waiters: Array<() => void>): void {
+  for (const resolve of waiters) resolve();
+}

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

@@ -0,0 +1,47 @@
+/**
+ * useListQuery — a list's query (search, scope, sort, page, page size).
+ *
+ * The URL owns it when a view-state provider is present, so every list view is
+ * a link. Outside a provider (a list embedded without the router) it falls back
+ * to local state, so the list still works. The rules live in utils/list-query.
+ */
+
+import { useCallback, useContext, useMemo, useRef, useState } from 'react';
+import { ViewStateContext } from './useViewState';
+import { listQueryToParams, parseListQuery, updateListQuery, type ListQuery } from '../utils/list-query';
+
+export interface UseListQueryResult {
+  query: ListQuery;
+  /** Apply a change. Changing search, scope or sort returns to page 1. */
+  update: (patch: Partial<ListQuery>) => void;
+}
+
+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 {
+  const view = useContext(ViewStateContext);
+  const [local, setLocal] = useState<ListQuery>({});
+
+  const params = view?.params;
+  const urlQuery = useMemo(() => (params ? parseListQuery(params) : null), [params]);
+  const query = urlQuery ?? local;
+
+  // `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, 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, defaultScope } = latest.current;
+    const next = updateListQuery(current, patch);
+    if (setParams) setParams(listQueryToParams(next, { defaultPerPage, defaultScope }));
+    else setLocal(next);
+  }, []);
+
+  return { query, update };
+}

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

@@ -0,0 +1,77 @@
+/**
+ * useScopeCounts — the number on each scope tab. Opt-in (`enabled`); off, it makes no request.
+ *
+ * Counts are decoration, so they never break the list: a count that fails is left out, and an
+ * adapter without `aggregate` shows none. A slower, older answer never overwrites a newer one.
+ */
+
+import { useEffect, useRef, useState } from 'react';
+import { useDataAdapter } from './useAdminData';
+import { mergeFilters } from '../utils/list-query';
+import { planScopeCounts, countsFromGrouped } from '../utils/scope-counts';
+import type { ScopeConfig } from '../types';
+
+export interface UseScopeCountsOptions {
+  resource: string;
+  scopes: ScopeConfig[] | undefined;
+  enabled: boolean;
+  /** The page's own filter, applied to every tab. A tab's own filter is added per tab. */
+  baseFilter?: Record<string, unknown>;
+  search?: string;
+  searchFields?: string[];
+  /** Change it to ask again with the same inputs, e.g. after a row was edited. */
+  refreshToken?: number;
+}
+
+export function useScopeCounts(options: UseScopeCountsOptions): Record<string, number> | undefined {
+  const adapter = useDataAdapter();
+  const [counts, setCounts] = useState<Record<string, number> | undefined>(undefined);
+  const latest = useRef(0);
+  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, s.deleted]), baseFilter, search, searchFields]);
+
+  useEffect(() => {
+    const aggregate = adapter.aggregate?.bind(adapter);
+    if (!enabled || !scopes?.length || !aggregate) {
+      setCounts(undefined);
+      return;
+    }
+    const run = ++latest.current;
+    const plan = planScopeCounts(scopes);
+    const count = [{ function: 'count' as const }];
+    const shared = {
+      ...(search !== undefined ? { search } : {}),
+      ...(searchFields !== undefined ? { searchFields } : {}),
+    };
+
+    const tasks: Array<Promise<Record<string, number>>> = [
+      ...plan.grouped.map(group =>
+        aggregate(resource, { aggregates: count, groupBy: [group.column], filter: baseFilter, ...shared })
+          .then(result => countsFromGrouped(result.data, group)),
+      ),
+      ...plan.single.map(scope =>
+        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) })),
+      ),
+    ];
+
+    Promise.allSettled(tasks).then(results => {
+      if (run !== latest.current) return;
+      const merged: Record<string, number> = {};
+      for (const result of results) if (result.status === 'fulfilled') Object.assign(merged, result.value);
+      setCounts(merged);
+    });
+    // Leaving (new inputs, or unmount) retires this run's answer.
+    return () => { latest.current++; };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [adapter, enabled, key, refreshToken]);
+
+  return counts;
+}

package/src/hooks/useScrollToFirstError.ts

@@ -0,0 +1,74 @@
+/**
+ * useScrollToFirstError — after a failed submit, scroll an Edit/Create form
+ * so the topmost errored field on screen is in view. With a layout that can
+ * differ from the first errored field in field order: stacked columns draw
+ * the main column first.
+ *
+ * The scroll waits for the render that shows the errors. A scroll in the same
+ * tick as setErrors runs before the error line is laid out, so the scroll
+ * range does not include it yet and the message can stay below the visible
+ * area. A request is pending until the next change to `errors`; a change with
+ * no request pending (typing clears an error) does not scroll.
+ *
+ * Offsets come from onLayout: the fields container's y in the scroll content,
+ * plus each field's y in that container. An errored field with no offset yet
+ * is skipped; equal offsets keep field order. With no ScrollView ref, no
+ * container offset, or no errored field with an offset it does nothing.
+ */
+
+import { useCallback, useEffect, useRef, type RefObject } from 'react';
+import type { LayoutChangeEvent, ScrollView } from 'react-native';
+import type { FieldDefinition } from '../types';
+
+export interface ScrollToFirstError {
+  /** Attach to the form's ScrollView. */
+  scrollRef: RefObject<ScrollView | null>;
+  /** Attach to the View that holds the fields, a direct child of the scroll content. */
+  onContainerLayout: (event: LayoutChangeEvent) => void;
+  /** A field's y within that View. */
+  onFieldOffset: (name: string, y: number) => void;
+  /**
+   * Call with the screen's fields when validation fails, after setErrors.
+   * Once the new errors have rendered, scroll to the errored field with the
+   * smallest offset.
+   */
+  requestScrollToFirstError: (fields: FieldDefinition[]) => void;
+}
+
+export function useScrollToFirstError(errors: Record<string, string>): ScrollToFirstError {
+  const scrollRef = useRef<ScrollView | null>(null);
+  const containerY = useRef<number | undefined>(undefined);
+  const fieldY = useRef(new Map<string, number>());
+  const pending = useRef<FieldDefinition[] | null>(null);
+
+  const onContainerLayout = useCallback((event: LayoutChangeEvent) => {
+    containerY.current = event.nativeEvent.layout.y;
+  }, []);
+
+  const onFieldOffset = useCallback((name: string, y: number) => {
+    fieldY.current.set(name, y);
+  }, []);
+
+  const requestScrollToFirstError = useCallback((fields: FieldDefinition[]) => {
+    pending.current = fields;
+  }, []);
+
+  useEffect(() => {
+    const fields = pending.current;
+    if (!fields) return;
+    pending.current = null;
+    let topmost: number | undefined;
+    for (const field of fields) {
+      if (errors[field.name] === undefined) continue;
+      const y = fieldY.current.get(field.name);
+      // Strict `<`: on a tie the earlier field in field order stays.
+      if (y !== undefined && (topmost === undefined || y < topmost)) topmost = y;
+    }
+    const top = containerY.current;
+    const scroll = scrollRef.current;
+    if (topmost === undefined || top === undefined || !scroll) return;
+    scroll.scrollTo({ y: top + topmost, animated: true });
+  }, [errors]);
+
+  return { scrollRef, onContainerLayout, onFieldOffset, requestScrollToFirstError };
+}

package/src/index.ts

@@ -10,6 +10,7 @@
 export type {
   FieldType,
   FieldDefinition,
+  TagGroup,
   ImageSize,
   CellContext,
   ActionContext,
@@ -19,6 +20,8 @@ export type {
   EditorComponent,
   EditorRegistry,
   ResourceConfig,
+  ScreenLayout,
+  LayoutColumn,
   StorageConfig,
   WidgetType,
   ChartType,
@@ -27,6 +30,9 @@ export type {
   MenuItem,
   AdminConfig,
   ListParams,
+  ScopeConfig,
+  AssociationConfig,
+  DeletedMode,
   ListResult,
   DataRecord,
   AggregateFunction,
@@ -86,6 +92,12 @@ export {
   type ViewStateContextValue,
 } from './hooks/useViewState';
 
+export {
+  AdminNavigationContext,
+  useAdminNavigation,
+  type AdminNavigationContextValue,
+} from './hooks/useAdminNavigation';
+
 // RPC Factory
 export {
   createResourceDashboardRpcs,
@@ -156,8 +168,12 @@ export { useEditors, EditorRegistryContext } from './hooks/useEditors';
 // Image field components
 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
 export { resolveImageUrl, type ResolveImageUrlOptions } from './utils/resolve-image-url';
@@ -165,6 +181,7 @@ export { uploadFile, type UploadFileOptions, type UploadFileResult } from './uti
 
 // Row actions
 export { visibleRowActions } from './utils/row-actions';
+export { enumScopes } from './utils/scopes';
 
 // Utilities
 export {