@everystack/admin 0.2.2 → 0.2.5

package/src/hooks/useAdminData.ts

@@ -4,7 +4,7 @@
  * Provides data fetching capabilities using the configured DataAdapter.
  */
 
-import { createContext, useContext, useState, useEffect, useCallback } from 'react';
+import { createContext, useContext, useState, useEffect, useCallback, useRef } from 'react';
 import type { DataAdapter } from '../adapters/types';
 import type { ListParams, DataRecord } from '../types';
 
@@ -33,6 +33,12 @@ export function useDataAdapter(): DataAdapter {
 export interface UseAdminDataOptions extends ListParams {
   /** Skip initial fetch */
   skip?: boolean;
+  /**
+   * Reactive filters merged into every fetch beneath the in-view search filter
+   * (e.g. an analytics-header time range or segment). Changing it refetches.
+   * Memoize it at the call site to keep identity stable across renders.
+   */
+  baseFilter?: Record<string, unknown>;
 }
 
 export interface UseAdminDataResult<T extends DataRecord = DataRecord> {
@@ -77,34 +83,66 @@ export function useAdminData<T extends DataRecord = DataRecord>(
   const [order, setOrder] = useState(options.order ?? 'asc');
   const [filter, setFilterState] = useState(options.filter ?? {});
 
-  const fetchData = useCallback(async () => {
+  // Manual-refetch trigger (bumped by refetch()).
+  const [refetchIndex, setRefetchIndex] = useState(0);
+
+  // A stable, value-based key for the whole request. The effect keys on this
+  // string rather than on object identity, so a re-render that produces a
+  // 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({
+    resource,
+    page,
+    perPage,
+    sort: sort ?? null,
+    order,
+    baseFilter: options.baseFilter ?? {},
+    filter,
+    search: options.search ?? null,
+    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);
+
+  useEffect(() => {
+    if (options.skip) return;
+    const seq = ++seqRef.current;
     setLoading(true);
     setError(null);
 
-    try {
-      const result = await adapter.fetchList<T>(resource, {
+    adapter
+      .fetchList<T>(resource, {
         page,
         perPage,
         sort,
         order,
-        filter,
+        // Base filters (time range, segment) sit beneath the in-view search filter.
+        filter: { ...(options.baseFilter ?? {}), ...filter },
         search: options.search,
+      })
+      .then(result => {
+        if (seq !== seqRef.current) return;
+        setData(result.data);
+        setTotal(result.total);
+      })
+      .catch(err => {
+        if (seq !== seqRef.current) return;
+        setError(err instanceof Error ? err : new Error(String(err)));
+      })
+      .finally(() => {
+        if (seq === seqRef.current) setLoading(false);
       });
+    // reqKey encodes every input; the per-field deps are folded into it.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [adapter, reqKey, options.skip]);
 
-      setData(result.data);
-      setTotal(result.total);
-    } catch (err) {
-      setError(err instanceof Error ? err : new Error(String(err)));
-    } finally {
-      setLoading(false);
-    }
-  }, [adapter, resource, page, perPage, sort, order, filter, options.search]);
-
-  useEffect(() => {
-    if (!options.skip) {
-      fetchData();
-    }
-  }, [fetchData, options.skip]);
+  // Refetch by bumping the trigger — runs through the same effect/guard path.
+  const refetch = useCallback(async () => {
+    setRefetchIndex(i => i + 1);
+  }, []);
 
   const setSort = useCallback((field: string, newOrder?: 'asc' | 'desc') => {
     setSortState(field);
@@ -121,7 +159,7 @@ export function useAdminData<T extends DataRecord = DataRecord>(
     total,
     loading,
     error,
-    refetch: fetchData,
+    refetch,
     page,
     perPage,
     setPage,

package/src/hooks/useEditors.ts

@@ -0,0 +1,17 @@
+/**
+ * Editor registry context.
+ *
+ * Apps register editor adapters (TipTap, MDXEditor, a GrapesJS email builder,
+ * …) on AdminRoot/AdminShell; fields select one via `field.editor`. The core
+ * admin depends on no editor library — the registry is the plug socket.
+ * See docs/plans/admin-editors.md.
+ */
+
+import { createContext, useContext } from 'react';
+import type { EditorRegistry } from '../types';
+
+export const EditorRegistryContext = createContext<EditorRegistry>({});
+
+export function useEditors(): EditorRegistry {
+  return useContext(EditorRegistryContext);
+}

package/src/hooks/useViewState.ts

@@ -0,0 +1,51 @@
+/**
+ * useViewState — read/write the admin's in-view state as URL query params.
+ *
+ * Router-agnostic: AdminRouter populates the context from the `searchParams` it
+ * receives (e.g. expo-router's useLocalSearchParams) and a setter built on the
+ * navigation port. Screens read the current params and push updates, so every
+ * filtered/scrubbed view is a direct link and drill-downs (`?level=error`) work.
+ */
+
+import { createContext, useContext } from 'react';
+
+/** Current query params, normalized to single strings (first value wins). */
+export type ViewParams = Record<string, string>;
+
+export interface ViewStateContextValue {
+  params: ViewParams;
+  /**
+   * 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.
+   */
+  setParams: (next: Record<string, string | undefined>) => void;
+}
+
+export const ViewStateContext = createContext<ViewStateContextValue | null>(null);
+
+/** Safe outside a provider: returns empty params and a no-op setter. */
+export function useViewState(): ViewStateContextValue {
+  return useContext(ViewStateContext) ?? { params: {}, setParams: () => {} };
+}
+
+/** 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 = {};
+  if (!raw) return out;
+  for (const [k, v] of Object.entries(raw)) {
+    if (v == null) continue;
+    out[k] = Array.isArray(v) ? String(v[0] ?? '') : String(v);
+  }
+  return out;
+}
+
+/** Build a `?a=1&b=2` query string from params; empty → ''. Undefined dropped. */
+export function buildQueryString(params: Record<string, string | undefined>): string {
+  const usp = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    if (v == null || v === '') continue;
+    usp.set(k, v);
+  }
+  const s = usp.toString();
+  return s ? `?${s}` : '';
+}

package/src/index.ts

@@ -10,6 +10,14 @@
 export type {
   FieldType,
   FieldDefinition,
+  ImageSize,
+  CellContext,
+  ActionContext,
+  InputContext,
+  ContentFormat,
+  EditorProps,
+  EditorComponent,
+  EditorRegistry,
   ResourceConfig,
   StorageConfig,
   WidgetType,
@@ -69,6 +77,14 @@ export {
 
 // useRpc hook
 export { useRpc, type UseRpcOptions, type UseRpcResult } from './hooks/useRpc';
+export {
+  useViewState,
+  ViewStateContext,
+  normalizeParams,
+  buildQueryString,
+  type ViewParams,
+  type ViewStateContextValue,
+} from './hooks/useViewState';
 
 // RPC Factory
 export {
@@ -104,6 +120,8 @@ export {
   ResourceCreate,
   ResourceEdit,
   ResourceDashboard,
+  AdminRouter,
+  AdminShell,
   type AdminLayoutProps,
   type AdminDashboardProps,
   type ResourceListProps,
@@ -111,18 +129,35 @@ export {
   type ResourceCreateProps,
   type ResourceEditProps,
   type ResourceDashboardProps,
+  type AdminRouterProps,
+  type AdminShellProps,
+  type AdminNavigator,
 } from './screens';
 
+// Routing (router-agnostic path↔route mapping behind AdminRouter)
+export {
+  resolveAdminRoute,
+  adminHref,
+  pathToSegments,
+  type AdminScreen,
+  type AdminRouteMatch,
+  type AdminHrefParts,
+} from './utils/admin-routing';
+
 // Context (virtual routing for expo-router)
 export { createAdminContext, type RequireContext } from './context';
 
 // Storage hooks
 export { useStorageConfig, StorageConfigContext } from './hooks/useStorageConfig';
 
+// Editor registry (pluggable rich-text/content editors)
+export { useEditors, EditorRegistryContext } from './hooks/useEditors';
+
 // Image field components
 export { ImageFieldInput } from './components/ImageFieldInput';
 export { AvatarFieldInput } from './components/AvatarFieldInput';
 export { ImageDisplay } from './components/ImageDisplay';
+export { RowActionButton, type RowActionButtonProps } from './components/RowActionButton';
 
 // Image utilities
 export { resolveImageUrl, type ResolveImageUrlOptions } from './utils/resolve-image-url';

package/src/presets/twitter.ts

@@ -35,7 +35,7 @@ const profilesResource: ResourceConfig = {
   labelPlural: 'Profiles',
   icon: 'person',
   primaryKey: 'id',
-  actions: { list: true, show: true, create: false, edit: true, delete: false },
+  actions: { list: true, show: true, create: true, edit: true, delete: true },
   fields: [
     { name: 'id', type: 'string', label: 'ID' },
     { name: 'username', type: 'string', label: 'Username', sortable: true, searchable: true },
@@ -72,7 +72,7 @@ const postsResource: ResourceConfig = {
   labelPlural: 'Posts',
   icon: 'chatbubble',
   primaryKey: 'id',
-  actions: { list: true, show: true, create: false, edit: false, delete: true },
+  actions: { list: true, show: true, create: true, edit: true, delete: true },
   fields: [
     { name: 'id', type: 'string', label: 'ID' },
     {
@@ -111,7 +111,7 @@ const likesResource: ResourceConfig = {
   labelPlural: 'Likes',
   icon: 'heart',
   primaryKey: 'user_id',
-  actions: { list: true, show: false, create: false, edit: false, delete: false },
+  actions: { list: true, show: true, create: true, edit: false, delete: true },
   fields: [
     {
       name: 'user_id',
@@ -154,7 +154,7 @@ const followsResource: ResourceConfig = {
   labelPlural: 'Follows',
   icon: 'people',
   primaryKey: 'follower_id',
-  actions: { list: true, show: false, create: false, edit: false, delete: false },
+  actions: { list: true, show: true, create: true, edit: false, delete: true },
   fields: [
     {
       name: 'follower_id',

package/src/rpc/resource-dashboard-rpc.ts

@@ -15,6 +15,7 @@
  */
 
 import { sql, type SQL } from 'drizzle-orm';
+import { toCamelCaseKeys } from '../utils/naming';
 import type { ResourceDashboardConfig, DimensionConfig, StatDialConfig } from '../types';
 
 interface DbExecutor {
@@ -413,6 +414,61 @@ function createEventListHandler(
   };
 }
 
+// ────────────────────────────────────────────────────────────
+// Event Detail RPC
+//
+// The show view's data source for detailVia: 'rpc' resources — one row
+// by primary key, the static where still applied (an STI discriminator
+// must gate detail exactly like it gates the list), keys camelCased to
+// match field definitions. Keeps telemetry off the REST surface entirely.
+// ────────────────────────────────────────────────────────────
+
+const MAX_ID_LENGTH = 256;
+
+function createEventDetailHandler(
+  tableName: string,
+  config: ResourceDashboardConfig,
+  db: DbExecutor,
+): (body: unknown) => Promise<unknown> {
+  const pkColumn = Array.isArray(config.primaryKey)
+    ? config.primaryKey[0]
+    : config.primaryKey ?? 'id';
+
+  return async (body: unknown) => {
+    const id = (body as { id?: unknown } | null)?.id;
+    if (
+      (typeof id !== 'string' && typeof id !== 'number') ||
+      String(id).length === 0 ||
+      String(id).length > MAX_ID_LENGTH
+    ) {
+      throw new Error('Invalid id');
+    }
+
+    const conditions: SQL[] = [sql`${sql.raw(pkColumn)} = ${String(id)}`];
+    for (const predicate of config.where ?? []) {
+      conditions.push(sql`${sql.raw(predicate.column)} = ${predicate.equals}`);
+    }
+    let where = conditions[0];
+    for (let i = 1; i < conditions.length; i++) {
+      where = sql`${where} AND ${conditions[i]}`;
+    }
+
+    const result = await db.execute(sql`
+      SELECT row_to_json(r) AS row
+      FROM (SELECT * FROM ${sql.raw(tableName)} WHERE ${where} LIMIT 1) r
+    `);
+
+    const rows = extractRows(result);
+    const first = rows[0] as { row: Record<string, unknown> | string } | undefined;
+    if (!first) {
+      throw new Error(`Record not found: ${id}`);
+    }
+
+    const raw = typeof first.row === 'string' ? JSON.parse(first.row) : first.row;
+    return toCamelCaseKeys(raw);
+  };
+}
+
 // ────────────────────────────────────────────────────────────
 // Public API
 // ────────────────────────────────────────────────────────────
@@ -420,6 +476,7 @@ function createEventListHandler(
 export interface ResourceDashboardRpcs {
   dashboardData: (body: unknown) => Promise<unknown>;
   eventList: (body: unknown) => Promise<unknown>;
+  eventDetail: (body: unknown) => Promise<unknown>;
 }
 
 /**
@@ -438,6 +495,7 @@ export function createResourceDashboardRpcs(
   return {
     dashboardData: createDashboardDataHandler(tableName, config, db),
     eventList: createEventListHandler(tableName, config, db),
+    eventDetail: createEventDetailHandler(tableName, config, db),
   };
 }
 
@@ -464,6 +522,7 @@ export function createAllDashboardRpcs(
     const prefix = resource.name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
     rpcs[`${prefix}DashboardData`] = handlers.dashboardData;
     rpcs[`${prefix}EventList`] = handlers.eventList;
+    rpcs[`${prefix}EventDetail`] = handlers.eventDetail;
   }
 
   return rpcs;

package/src/screens/AdminLayout.tsx

@@ -5,10 +5,24 @@
  * Reads menu items from AdminConfig via useAdminConfig().
  */
 
-import React, { useState } from 'react';
+import React, { useEffect, useState } from 'react';
 import { View, Text, Pressable, ScrollView } from 'react-native';
 import { useAdminConfig } from '../hooks/useAdminConfig';
 import type { MenuItem } from '../types';
+import type { Crumb } from '../utils/breadcrumbs';
+
+/** The group id whose children contain the active item, if any. */
+function activeGroupId(menu: MenuItem[] | undefined, activeItem: string | undefined): string | null {
+  for (const top of menu ?? []) {
+    if (top.children?.some(c => c.id === activeItem)) return top.id;
+  }
+  return null;
+}
+
+/** First top-level group (the default-open one \u2014 e.g. "Content"). */
+function firstGroupId(menu: MenuItem[] | undefined): string | null {
+  return menu?.find(m => m.children && m.children.length > 0)?.id ?? null;
+}
 
 export interface AdminLayoutProps {
   children?: React.ReactNode;
@@ -16,34 +30,73 @@ export interface AdminLayoutProps {
   activeItem?: string;
   /** Called when a menu item is pressed */
   onNavigate?: (item: MenuItem) => void;
+  /** Breadcrumb trail for the content top bar. */
+  breadcrumbs?: Crumb[];
+  /** Navigate to a breadcrumb's admin path. */
+  onNavigatePath?: (path: string) => void;
 }
 
-export function AdminLayout({ children, activeItem, onNavigate }: AdminLayoutProps): React.ReactElement {
+export function AdminLayout({
+  children,
+  activeItem,
+  onNavigate,
+  breadcrumbs,
+  onNavigatePath,
+}: AdminLayoutProps): React.ReactElement {
   const config = useAdminConfig();
   const [sidebarOpen, setSidebarOpen] = useState(true);
 
+  // Accordion: at most one group open. Default to the active group, else the
+  // first group ("Content"). Navigating into a group opens it (and closes the
+  // others); the active item is always visible.
+  const activeGroup = activeGroupId(config.menu, activeItem);
+  const [openGroup, setOpenGroup] = useState<string | null>(activeGroup ?? firstGroupId(config.menu));
+  useEffect(() => {
+    if (activeGroup) setOpenGroup(activeGroup);
+  }, [activeGroup]);
+
   return (
     <View className="flex-1 flex-row bg-gray-50">
       {/* Sidebar */}
       {sidebarOpen && (
         <View className="w-64 bg-white border-r border-gray-200">
-          {/* Header */}
-          <View className="px-4 py-5 border-b border-gray-200">
-            <Text className="text-lg font-bold text-gray-900">{config.title}</Text>
-            {config.subtitle && (
-              <Text className="text-xs text-gray-500 mt-0.5">{config.subtitle}</Text>
-            )}
+          {/* Header \u2014 collapse toggle sits to the LEFT of the title. */}
+          <View className="flex-row items-center px-4 py-5 border-b border-gray-200">
+            <Pressable
+              className="p-2 -ml-2 mr-1 rounded-lg"
+              accessibilityLabel="Collapse menu"
+              onPress={() => setSidebarOpen(false)}
+            >
+              <Text className="text-lg text-gray-600">{'\u2630'}</Text>
+            </Pressable>
+            <View className="flex-1">
+              <Text className="text-lg font-bold text-gray-900">{config.title}</Text>
+              {config.subtitle && (
+                <Text className="text-xs text-gray-500 mt-0.5">{config.subtitle}</Text>
+              )}
+            </View>
           </View>
 
           {/* Menu */}
           <ScrollView className="flex-1 py-2">
             {config.menu?.map(item => (
-              <MenuItemRow
-                key={item.id}
-                item={item}
-                active={activeItem === item.id}
-                onPress={onNavigate}
-              />
+              item.children && item.children.length > 0 ? (
+                <MenuGroup
+                  key={item.id}
+                  item={item}
+                  activeItem={activeItem}
+                  open={openGroup === item.id}
+                  onToggle={() => setOpenGroup(g => (g === item.id ? null : item.id))}
+                  onPress={onNavigate}
+                />
+              ) : (
+                <MenuItemRow
+                  key={item.id}
+                  item={item}
+                  active={activeItem === item.id}
+                  onPress={onNavigate}
+                />
+              )
             ))}
           </ScrollView>
         </View>
@@ -51,14 +104,18 @@ export function AdminLayout({ children, activeItem, onNavigate }: AdminLayoutPro
 
       {/* Main content */}
       <View className="flex-1">
-        {/* Top bar */}
+        {/* Top bar \u2014 breadcrumbs (and a menu-open button when collapsed). */}
         <View className="flex-row items-center px-4 py-3 bg-white border-b border-gray-200">
-          <Pressable
-            className="p-2 rounded-lg mr-2"
-            onPress={() => setSidebarOpen(!sidebarOpen)}
-          >
-            <Text className="text-lg text-gray-600">{sidebarOpen ? '\u2190' : '\u2192'}</Text>
-          </Pressable>
+          {!sidebarOpen && (
+            <Pressable
+              className="p-2 -ml-2 mr-2 rounded-lg"
+              accessibilityLabel="Open menu"
+              onPress={() => setSidebarOpen(true)}
+            >
+              <Text className="text-lg text-gray-600">{'\u2630'}</Text>
+            </Pressable>
+          )}
+          <Breadcrumbs crumbs={breadcrumbs} onNavigatePath={onNavigatePath} />
         </View>
 
         {/* Content */}
@@ -68,6 +125,42 @@ export function AdminLayout({ children, activeItem, onNavigate }: AdminLayoutPro
   );
 }
 
+// =============================================================================
+// Breadcrumbs
+// =============================================================================
+
+function Breadcrumbs({
+  crumbs,
+  onNavigatePath,
+}: {
+  crumbs?: Crumb[];
+  onNavigatePath?: (path: string) => void;
+}): React.ReactElement | null {
+  if (!crumbs || crumbs.length === 0) return null;
+  return (
+    <View className="flex-row items-center flex-wrap">
+      {crumbs.map((crumb, i) => {
+        const last = i === crumbs.length - 1;
+        const navigable = crumb.href != null && !last;
+        return (
+          <View key={`${crumb.label}-${i}`} className="flex-row items-center">
+            {i > 0 && <Text className="text-sm text-gray-300 mx-2">{'/'}</Text>}
+            {navigable ? (
+              <Pressable onPress={() => onNavigatePath?.(crumb.href!)}>
+                <Text className="text-sm text-blue-600">{crumb.label}</Text>
+              </Pressable>
+            ) : (
+              <Text className={last ? 'text-sm font-semibold text-gray-900' : 'text-sm text-gray-500'}>
+                {crumb.label}
+              </Text>
+            )}
+          </View>
+        );
+      })}
+    </View>
+  );
+}
+
 // =============================================================================
 // MenuItemRow
 // =============================================================================
@@ -76,12 +169,24 @@ interface MenuItemRowProps {
   item: MenuItem;
   active: boolean;
   onPress?: (item: MenuItem) => void;
+  indent?: boolean;
 }
 
-function MenuItemRow({ item, active, onPress }: MenuItemRowProps): React.ReactElement {
+function MenuItemRow({ item, active, onPress, indent }: MenuItemRowProps): React.ReactElement {
+  // react-native-tailwind can't resolve dynamic/template-literal classNames — it
+  // falls back to passing the string as `style`, which crashes react-dom. Keep
+  // every className a static string literal (a ternary of literals is fine).
   return (
     <Pressable
-      className={active ? "flex-row items-center px-4 py-2.5 mx-2 rounded-lg bg-blue-50" : "flex-row items-center px-4 py-2.5 mx-2 rounded-lg"}
+      className={
+        indent
+          ? (active
+              ? 'flex-row items-center pl-7 pr-4 py-2 mx-2 rounded-lg bg-blue-50'
+              : 'flex-row items-center pl-7 pr-4 py-2 mx-2 rounded-lg')
+          : (active
+              ? 'flex-row items-center px-4 py-2.5 mx-2 rounded-lg bg-blue-50'
+              : 'flex-row items-center px-4 py-2.5 mx-2 rounded-lg')
+      }
       onPress={() => onPress?.(item)}
     >
       <Text className={active ? "text-sm text-blue-700 font-semibold" : "text-sm text-gray-700"}>
@@ -95,3 +200,41 @@ function MenuItemRow({ item, active, onPress }: MenuItemRowProps): React.ReactEl
     </Pressable>
   );
 }
+
+// =============================================================================
+// MenuGroup — collapsible section. The group header toggles; children navigate.
+// =============================================================================
+
+interface MenuGroupProps {
+  item: MenuItem;
+  activeItem?: string;
+  /** Controlled open state (accordion — at most one group open). */
+  open: boolean;
+  onToggle: () => void;
+  onPress?: (item: MenuItem) => void;
+}
+
+function MenuGroup({ item, activeItem, open, onToggle, onPress }: MenuGroupProps): React.ReactElement {
+  return (
+    <View className="mt-2">
+      <Pressable
+        className="flex-row items-center px-4 py-1.5"
+        onPress={onToggle}
+      >
+        <Text className="text-xs font-semibold uppercase tracking-wide text-gray-400">
+          {item.label}
+        </Text>
+        <Text className="ml-auto text-xs text-gray-400">{open ? '⌄' : '›'}</Text>
+      </Pressable>
+      {open && item.children?.map(child => (
+        <MenuItemRow
+          key={child.id}
+          item={child}
+          active={activeItem === child.id}
+          onPress={onPress}
+          indent
+        />
+      ))}
+    </View>
+  );
+}