@everystack/admin 0.1.0

package/src/hooks/useAggregates.ts

@@ -0,0 +1,290 @@
+/**
+ * useAggregates hook
+ *
+ * Provides aggregate query capabilities for dashboard charts and statistics.
+ * Uses the configured DataAdapter's aggregate method for PostgREST-style queries.
+ */
+
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { useDataAdapter } from './useAdminData';
+import type { AggregateParams, AggregateResult, AggregateQuery } from '../types';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface UseAggregatesOptions extends Omit<AggregateParams, 'aggregates'> {
+  /** Aggregate functions to compute */
+  aggregates: AggregateQuery[];
+  /** Skip initial fetch */
+  skip?: boolean;
+  /** Polling interval in milliseconds (0 = disabled) */
+  pollInterval?: number;
+  /** Callback when data is fetched successfully */
+  onSuccess?: (result: AggregateResult) => void;
+  /** Callback when fetch fails */
+  onError?: (error: Error) => void;
+}
+
+export interface UseAggregatesResult {
+  /** Aggregated data rows */
+  data: Record<string, unknown>[];
+  /** Loading state */
+  loading: boolean;
+  /** Error state */
+  error: Error | null;
+  /** Refetch data manually */
+  refetch: () => Promise<void>;
+  /** Update filter and refetch */
+  setFilter: (filter: Record<string, unknown>) => void;
+  /** Whether the adapter supports aggregates */
+  isSupported: boolean;
+}
+
+// =============================================================================
+// Hook Implementation
+// =============================================================================
+
+export function useAggregates(
+  resource: string,
+  options: UseAggregatesOptions
+): UseAggregatesResult {
+  const adapter = useDataAdapter();
+
+  const [data, setData] = useState<Record<string, unknown>[]>([]);
+  const [loading, setLoading] = useState(!options.skip);
+  const [error, setError] = useState<Error | null>(null);
+  const [filter, setFilterState] = useState(options.filter ?? {});
+
+  // Track if adapter supports aggregates
+  const isSupported = typeof adapter.aggregate === 'function';
+
+  // Use ref to track mounted state for cleanup
+  const isMounted = useRef(true);
+
+  // Stable reference for options
+  const aggregatesRef = useRef(options.aggregates);
+  const groupByRef = useRef(options.groupBy);
+  aggregatesRef.current = options.aggregates;
+  groupByRef.current = options.groupBy;
+
+  const fetchData = useCallback(async () => {
+    if (!isSupported) {
+      setError(new Error('DataAdapter does not support aggregate queries'));
+      return;
+    }
+
+    setLoading(true);
+    setError(null);
+
+    try {
+      const result = await adapter.aggregate!(resource, {
+        aggregates: aggregatesRef.current,
+        groupBy: groupByRef.current,
+        filter,
+      });
+
+      if (isMounted.current) {
+        setData(result.data);
+        options.onSuccess?.(result);
+      }
+    } catch (err) {
+      if (isMounted.current) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        setError(error);
+        options.onError?.(error);
+      }
+    } finally {
+      if (isMounted.current) {
+        setLoading(false);
+      }
+    }
+  }, [adapter, resource, filter, isSupported, options.onSuccess, options.onError]);
+
+  // Set error if adapter doesn't support aggregates
+  useEffect(() => {
+    if (!isSupported && !options.skip) {
+      setError(new Error('DataAdapter does not support aggregate queries'));
+      setLoading(false);
+    }
+  }, [isSupported, options.skip]);
+
+  // Initial fetch
+  useEffect(() => {
+    if (!options.skip && isSupported) {
+      fetchData();
+    }
+  }, [fetchData, options.skip, isSupported]);
+
+  // Polling
+  useEffect(() => {
+    if (options.pollInterval && options.pollInterval > 0 && isSupported) {
+      const intervalId = setInterval(fetchData, options.pollInterval);
+      return () => clearInterval(intervalId);
+    }
+  }, [fetchData, options.pollInterval, isSupported]);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    isMounted.current = true;
+    return () => {
+      isMounted.current = false;
+    };
+  }, []);
+
+  const setFilter = useCallback((newFilter: Record<string, unknown>) => {
+    setFilterState(newFilter);
+  }, []);
+
+  return {
+    data,
+    loading,
+    error,
+    refetch: fetchData,
+    setFilter,
+    isSupported,
+  };
+}
+
+// =============================================================================
+// Convenience Hooks
+// =============================================================================
+
+export interface UseCountOptions {
+  column?: string;
+  distinct?: boolean;
+  filter?: Record<string, unknown>;
+  skip?: boolean;
+  pollInterval?: number;
+}
+
+export interface UseCountResult {
+  count: number | null;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => Promise<void>;
+}
+
+export function useCount(resource: string, options: UseCountOptions = {}): UseCountResult {
+  const result = useAggregates(resource, {
+    aggregates: [
+      {
+        function: 'count',
+        column: options.column,
+        distinct: options.distinct,
+        alias: 'count',
+      },
+    ],
+    filter: options.filter,
+    skip: options.skip,
+    pollInterval: options.pollInterval,
+  });
+
+  const count = (result.data[0]?.count as number | null) ?? null;
+
+  return {
+    count,
+    loading: result.loading,
+    error: result.error,
+    refetch: result.refetch,
+  };
+}
+
+export interface UseGroupedCountOptions {
+  filter?: Record<string, unknown>;
+  skip?: boolean;
+  pollInterval?: number;
+}
+
+export interface UseGroupedCountResult {
+  data: { [key: string]: unknown; count: number }[];
+  loading: boolean;
+  error: Error | null;
+  refetch: () => Promise<void>;
+}
+
+export function useGroupedCount(
+  resource: string,
+  groupBy: string,
+  options: UseGroupedCountOptions = {}
+): UseGroupedCountResult {
+  const result = useAggregates(resource, {
+    aggregates: [{ function: 'count', alias: 'count' }],
+    groupBy: [groupBy],
+    filter: options.filter,
+    skip: options.skip,
+    pollInterval: options.pollInterval,
+  });
+
+  return {
+    data: result.data as { [key: string]: unknown; count: number }[],
+    loading: result.loading,
+    error: result.error,
+    refetch: result.refetch,
+  };
+}
+
+export interface UseStatsOptions {
+  count?: boolean;
+  sum?: string;
+  avg?: string;
+  min?: string;
+  max?: string;
+  filter?: Record<string, unknown>;
+  skip?: boolean;
+  pollInterval?: number;
+}
+
+export interface UseStatsResult {
+  stats: {
+    count?: number;
+    sum?: number;
+    avg?: number;
+    min?: number;
+    max?: number;
+  };
+  loading: boolean;
+  error: Error | null;
+  refetch: () => Promise<void>;
+}
+
+export function useStats(resource: string, options: UseStatsOptions = {}): UseStatsResult {
+  const aggregates: AggregateQuery[] = [];
+
+  if (options.count) {
+    aggregates.push({ function: 'count', alias: 'count' });
+  }
+  if (options.sum) {
+    aggregates.push({ function: 'sum', column: options.sum, alias: 'sum' });
+  }
+  if (options.avg) {
+    aggregates.push({ function: 'avg', column: options.avg, alias: 'avg' });
+  }
+  if (options.min) {
+    aggregates.push({ function: 'min', column: options.min, alias: 'min' });
+  }
+  if (options.max) {
+    aggregates.push({ function: 'max', column: options.max, alias: 'max' });
+  }
+
+  // Default to count if no options specified
+  if (aggregates.length === 0) {
+    aggregates.push({ function: 'count', alias: 'count' });
+  }
+
+  const result = useAggregates(resource, {
+    aggregates,
+    filter: options.filter,
+    skip: options.skip,
+    pollInterval: options.pollInterval,
+  });
+
+  const stats = (result.data[0] ?? {}) as UseStatsResult['stats'];
+
+  return {
+    stats,
+    loading: result.loading,
+    error: result.error,
+    refetch: result.refetch,
+  };
+}

package/src/hooks/useRpc.ts

@@ -0,0 +1,124 @@
+/**
+ * useRpc — Lightweight hook for calling RPC endpoints.
+ *
+ * Calls POST {baseUrl}/rpc/{fn} with JSON body.
+ * Manages loading/error state and supports manual refetch.
+ *
+ * Resilience features:
+ * - Debounces rapid body changes (150ms) to prevent request storms
+ * - AbortController cancels stale in-flight requests
+ * - Keeps previous data visible during refetch (no flash to loading state)
+ */
+
+import { useState, useEffect, useCallback, useRef } from 'react';
+
+export interface UseRpcOptions {
+  baseUrl: string;
+  fn: string;
+  body?: unknown;
+  skip?: boolean;
+  /** Debounce delay in ms before firing request on body change. Default: 150 */
+  debounce?: number;
+  getToken?: () => string | null | Promise<string | null>;
+}
+
+export interface UseRpcResult<T> {
+  data: T | null;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => Promise<void>;
+}
+
+export function useRpc<T = unknown>(options: UseRpcOptions): UseRpcResult<T> {
+  const { baseUrl, fn, body, skip, debounce = 150, getToken } = options;
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState(!skip);
+  const [error, setError] = useState<Error | null>(null);
+
+  const serializedBody = JSON.stringify(body) ?? '{}';
+  const abortRef = useRef<AbortController | null>(null);
+  const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const fetchData = useCallback(async (signal?: AbortSignal) => {
+    setLoading(true);
+    setError(null);
+    try {
+      const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+      if (getToken) {
+        const token = await getToken();
+        if (token) headers['Authorization'] = `Bearer ${token}`;
+      }
+      const res = await fetch(`${baseUrl}/rpc/${fn}`, {
+        method: 'POST',
+        headers,
+        body: serializedBody,
+        signal,
+      });
+      if (signal?.aborted) return;
+      if (!res.ok) {
+        throw new Error(`RPC ${fn} failed: ${res.status}`);
+      }
+      const json = await res.json();
+      if (!signal?.aborted) {
+        setData(json as T);
+      }
+    } catch (err) {
+      if (err instanceof DOMException && err.name === 'AbortError') return;
+      if (!signal?.aborted) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+      }
+    } finally {
+      if (!signal?.aborted) {
+        setLoading(false);
+      }
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [baseUrl, fn, getToken, serializedBody]);
+
+  useEffect(() => {
+    if (skip) return;
+
+    // Clear any pending debounce
+    if (debounceRef.current) {
+      clearTimeout(debounceRef.current);
+    }
+
+    // Abort previous in-flight request
+    if (abortRef.current) {
+      abortRef.current.abort();
+    }
+
+    // Debounce the fetch (skip debounce for initial load when no data yet)
+    const delay = data === null ? 0 : debounce;
+    debounceRef.current = setTimeout(() => {
+      const controller = new AbortController();
+      abortRef.current = controller;
+      fetchData(controller.signal);
+    }, delay);
+
+    return () => {
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+      }
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [fetchData, skip]);
+
+  // Manual refetch (bypasses debounce)
+  const refetch = useCallback(async () => {
+    if (abortRef.current) abortRef.current.abort();
+    const controller = new AbortController();
+    abortRef.current = controller;
+    await fetchData(controller.signal);
+  }, [fetchData]);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (abortRef.current) abortRef.current.abort();
+      if (debounceRef.current) clearTimeout(debounceRef.current);
+    };
+  }, []);
+
+  return { data, loading, error, refetch };
+}

package/src/hooks/useStorageConfig.ts

@@ -0,0 +1,16 @@
+/**
+ * useStorageConfig
+ *
+ * Provides storage configuration (endpoint, CDN URL, auth) to admin
+ * image/file field components via React context. Nullable by design —
+ * when storage is not configured, image fields degrade to plain TextInput.
+ */
+
+import { createContext, useContext } from 'react';
+import type { StorageConfig } from '../types';
+
+export const StorageConfigContext = createContext<StorageConfig | null>(null);
+
+export function useStorageConfig(): StorageConfig | null {
+  return useContext(StorageConfigContext);
+}

package/src/index.ts

@@ -0,0 +1,138 @@
+/**
+ * everystack/admin — Declarative admin dashboard framework.
+ *
+ * Provides a configuration-driven admin UI with hooks for data access,
+ * an EverystackAdapter that bridges to everystack/client, and utilities
+ * for building admin dashboards.
+ */
+
+// Types
+export type {
+  FieldType,
+  FieldDefinition,
+  ResourceConfig,
+  StorageConfig,
+  WidgetType,
+  ChartType,
+  WidgetConfig,
+  DashboardConfig,
+  MenuItem,
+  AdminConfig,
+  ListParams,
+  ListResult,
+  DataRecord,
+  AggregateFunction,
+  AggregateQuery,
+  AggregateParams,
+  AggregateResult,
+  // Resource Dashboard types
+  ResourceDashboardConfig,
+  StatDialConfig,
+  StatDialValue,
+  DimensionConfig,
+} from './types';
+
+// Adapter types
+export type {
+  DataAdapter,
+  SubscriptionEventType,
+  SubscriptionEvent,
+} from './adapters/types';
+
+// EverystackAdapter
+export { EverystackAdapter, type EverystackAdapterOptions } from './adapters/EverystackAdapter';
+
+// Hooks
+export { useAdminConfig, type AdminConfigContextValue } from './hooks/useAdminConfig';
+export {
+  useDataAdapter,
+  useAdminData,
+  type UseAdminDataOptions,
+  type UseAdminDataResult,
+} from './hooks/useAdminData';
+export {
+  useAggregates,
+  useCount,
+  useGroupedCount,
+  useStats,
+  type UseAggregatesOptions,
+  type UseAggregatesResult,
+  type UseCountOptions,
+  type UseCountResult,
+  type UseGroupedCountOptions,
+  type UseGroupedCountResult,
+  type UseStatsOptions,
+  type UseStatsResult,
+} from './hooks/useAggregates';
+
+// useRpc hook
+export { useRpc, type UseRpcOptions, type UseRpcResult } from './hooks/useRpc';
+
+// RPC Factory
+export {
+  createResourceDashboardRpcs,
+  createAllDashboardRpcs,
+  type ResourceDashboardRpcs,
+  type DashboardFilters,
+  type DashboardAggregates,
+  type EventListResult,
+} from './rpc/resource-dashboard-rpc';
+
+// Dashboard Components
+export { StatDials, type DialData, type StatDialsProps } from './components/dashboard/StatDials';
+export { DimensionBars, type DimensionBarsProps } from './components/dashboard/DimensionBars';
+export { DimensionDonut, type DimensionDonutProps } from './components/dashboard/DimensionDonut';
+export { EventTable, type EventTableProps, type EventTableColumn } from './components/dashboard/EventTable';
+export { TimeHistogram, type TimeHistogramProps } from './components/dashboard/TimeHistogram';
+export { Brush, type BrushProps, clamp, computeBrushExtent } from './components/dashboard/Brush';
+
+// Providers
+export { AdminConfigProvider, type AdminConfigProviderProps } from './providers/AdminConfigProvider';
+export { DataAdapterProvider, type DataAdapterProviderProps } from './providers/DataAdapterProvider';
+
+// AdminRoot
+export { AdminRoot, type AdminRootProps } from './AdminRoot';
+
+// Screens
+export {
+  AdminLayout,
+  AdminDashboard,
+  ResourceList,
+  ResourceShow,
+  ResourceCreate,
+  ResourceEdit,
+  ResourceDashboard,
+  type AdminLayoutProps,
+  type AdminDashboardProps,
+  type ResourceListProps,
+  type ResourceShowProps,
+  type ResourceCreateProps,
+  type ResourceEditProps,
+  type ResourceDashboardProps,
+} from './screens';
+
+// Context (virtual routing for expo-router)
+export { createAdminContext, type RequireContext } from './context';
+
+// Storage hooks
+export { useStorageConfig, StorageConfigContext } from './hooks/useStorageConfig';
+
+// Image field components
+export { ImageFieldInput } from './components/ImageFieldInput';
+export { AvatarFieldInput } from './components/AvatarFieldInput';
+export { ImageDisplay } from './components/ImageDisplay';
+
+// Image utilities
+export { resolveImageUrl, type ResolveImageUrlOptions } from './utils/resolve-image-url';
+export { uploadFile, type UploadFileOptions, type UploadFileResult } from './utils/upload-file';
+
+// Utilities
+export {
+  toCamelCase,
+  toSnakeCase,
+  getFieldValue,
+  hasField,
+  resolveFieldKey,
+  toSnakeCaseKeys,
+  toCamelCaseKeys,
+} from './utils/naming';