@everystack/admin 0.1.0

package/README.md

@@ -0,0 +1,282 @@
+# @everystack/admin
+
+Declarative admin dashboard framework for PostgREST APIs. Configuration-driven CRUD screens, dashboard widgets, image field renderers, and data hooks — all wired to `@everystack/api`.
+
+## Install
+
+```bash
+pnpm add @everystack/admin @everystack/api @everystack/ui react react-native
+```
+
+## Quick Start
+
+Define your admin configuration and render with `AdminRoot`:
+
+```tsx
+import { AdminRoot, EverystackAdapter } from '@everystack/admin';
+import { createClient } from '@everystack/api/client';
+import type { AdminConfig } from '@everystack/admin';
+
+const client = createClient({ baseUrl: '/api', getToken: () => token });
+const adapter = new EverystackAdapter({ client });
+
+const config: AdminConfig = {
+  resources: {
+    users: {
+      label: 'Users',
+      fields: {
+        id: { type: 'text', label: 'ID' },
+        name: { type: 'text', label: 'Name' },
+        email: { type: 'text', label: 'Email' },
+        avatar: { type: 'image', label: 'Avatar' },
+        createdAt: { type: 'datetime', label: 'Created' },
+      },
+      listFields: ['name', 'email', 'createdAt'],
+      searchFields: ['name', 'email'],
+    },
+    posts: {
+      label: 'Posts',
+      fields: {
+        id: { type: 'text', label: 'ID' },
+        title: { type: 'text', label: 'Title' },
+        content: { type: 'textarea', label: 'Content' },
+        status: { type: 'select', label: 'Status', options: ['draft', 'published'] },
+      },
+    },
+  },
+  menu: [
+    { label: 'Users', resource: 'users', icon: 'users' },
+    { label: 'Posts', resource: 'posts', icon: 'file-text' },
+  ],
+};
+
+function AdminApp() {
+  return <AdminRoot config={config} adapter={adapter} />;
+}
+```
+
+## Entry Points
+
+| Import | Description |
+|--------|-------------|
+| `@everystack/admin` | Config types, hooks, screens, adapter, components |
+| `@everystack/admin/presets/twitter` | Pre-built Twitter clone admin preset |
+
+## Admin Configuration
+
+### Field Types
+
+| Type | Description |
+|------|-------------|
+| `text` | Single-line text input |
+| `textarea` | Multi-line text |
+| `number` | Numeric input |
+| `boolean` | Toggle switch |
+| `select` | Dropdown with `options` array |
+| `datetime` | Date/time display |
+| `image` | Image upload with `ImageFieldInput` |
+| `avatar` | Avatar upload with `AvatarFieldInput` |
+| `json` | JSON display |
+| `relation` | Foreign key reference |
+
+### Resource Config
+
+```typescript
+interface ResourceConfig {
+  label: string;
+  fields: Record<string, FieldDefinition>;
+  listFields?: string[];      // Columns shown in list view
+  searchFields?: string[];    // Fields searchable via text input
+  defaultSort?: string;       // Default ordering (e.g., 'createdAt.desc')
+  dashboard?: ResourceDashboardConfig; // Per-resource analytics
+}
+```
+
+## Data Adapter
+
+The `EverystackAdapter` bridges admin hooks to the `@everystack/api` client:
+
+```typescript
+import { EverystackAdapter } from '@everystack/admin';
+import { createClient } from '@everystack/api/client';
+
+const client = createClient({ baseUrl: '/api', getToken: () => token });
+
+const adapter = new EverystackAdapter({
+  client,
+  // Optional: custom fetch for RPC calls
+  rpcFetch: async (name, body) => { /* ... */ },
+});
+```
+
+The adapter implements the `DataAdapter` interface:
+
+```typescript
+interface DataAdapter {
+  list(resource: string, params: ListParams): Promise<ListResult>;
+  getOne(resource: string, id: string): Promise<DataRecord>;
+  create(resource: string, data: DataRecord): Promise<DataRecord>;
+  update(resource: string, id: string, data: DataRecord): Promise<DataRecord>;
+  delete(resource: string, id: string): Promise<void>;
+  aggregate(resource: string, params: AggregateParams): Promise<AggregateResult>;
+  rpc(name: string, body: unknown): Promise<unknown>;
+  subscribe?(resource: string, callback: (event: SubscriptionEvent) => void): () => void;
+}
+```
+
+## Hooks
+
+### useAdminData
+
+CRUD data hook for any resource:
+
+```tsx
+const { data, total, isLoading, error, refetch } = useAdminData('posts', {
+  page: 1,
+  perPage: 20,
+  sort: 'createdAt.desc',
+  filters: { status: 'eq.published' },
+});
+```
+
+### useAggregates
+
+Server-side aggregation hooks:
+
+```tsx
+const { data: count } = useCount('posts');
+const { data: grouped } = useGroupedCount('posts', 'status');
+const { data: stats } = useStats('posts', 'views', ['sum', 'avg', 'max']);
+```
+
+### useRpc
+
+Call server-side RPC functions:
+
+```tsx
+const { data, isLoading, call } = useRpc('dashboard-stats', {
+  autoFetch: true,
+  body: { period: '7d' },
+});
+```
+
+### useStorageConfig
+
+Access storage configuration for image uploads:
+
+```tsx
+const { uploadUrl, cdnUrl } = useStorageConfig();
+```
+
+## Screens
+
+Built-in screens that render from config:
+
+| Component | Description |
+|-----------|-------------|
+| `AdminLayout` | Navigation sidebar + content area |
+| `AdminDashboard` | Overview with stat cards |
+| `ResourceList` | Paginated table with filters |
+| `ResourceShow` | Read-only record detail |
+| `ResourceCreate` | Create form |
+| `ResourceEdit` | Edit form |
+| `ResourceDashboard` | Per-resource analytics |
+
+### Manual Screen Usage
+
+```tsx
+import { AdminLayout, ResourceList, ResourceEdit } from '@everystack/admin';
+
+// In your router:
+<AdminLayout config={config}>
+  <ResourceList resource="posts" config={config.resources.posts} />
+</AdminLayout>
+```
+
+## Image Fields
+
+Image upload field renderers for use in create/edit forms:
+
+```tsx
+import { ImageFieldInput, AvatarFieldInput, ImageDisplay } from '@everystack/admin';
+
+// In a form
+<ImageFieldInput
+  value={formData.coverImage}
+  onChange={(key) => setFormData({ ...formData, coverImage: key })}
+  storageConfig={{ uploadUrl: '/api/storage', cdnUrl: 'https://cdn.example.com' }}
+/>
+
+<AvatarFieldInput
+  value={formData.avatar}
+  onChange={(key) => setFormData({ ...formData, avatar: key })}
+  storageConfig={storageConfig}
+/>
+
+// Read-only display
+<ImageDisplay value={record.coverImage} cdnUrl="https://cdn.example.com" />
+```
+
+## Dashboard Widgets
+
+SVG-based chart components for analytics:
+
+```tsx
+import { StatDials, DimensionBars, TimeHistogram, EventTable } from '@everystack/admin';
+
+<StatDials data={[{ label: 'Users', value: 1234, trend: 12 }]} />
+<DimensionBars data={[{ label: 'iOS', value: 60 }, { label: 'Android', value: 40 }]} />
+<TimeHistogram data={timeSeriesData} />
+<EventTable columns={columns} data={events} />
+```
+
+## Presets
+
+Pre-built admin configurations for common schemas:
+
+```typescript
+import { twitterPreset } from '@everystack/admin/presets/twitter';
+
+const config = twitterPreset({
+  // Override any resource config
+  resources: {
+    posts: { label: 'Tweets' },
+  },
+});
+```
+
+## Utilities
+
+```typescript
+import { toCamelCase, toSnakeCase, resolveImageUrl, uploadFile } from '@everystack/admin';
+
+// Naming conversion
+toCamelCase('created_at'); // 'createdAt'
+toSnakeCase('createdAt');  // 'created_at'
+
+// Image URL resolution
+const url = resolveImageUrl('uploads/abc.jpg', { cdnUrl: 'https://cdn.example.com' });
+
+// File upload
+const result = await uploadFile(file, {
+  uploadUrl: '/api/storage/presign',
+  getToken: () => token,
+});
+```
+
+## Peer Dependencies
+
+| Package | Version |
+|---------|---------|
+| `@everystack/api` | `>=0.1.0` |
+| `@everystack/ui` | `>=0.1.0` |
+| `react` | `>=18.0.0` |
+| `react-native` | `>=0.72.0` |
+
+---
+
+Part of [everystack](https://github.com/scalable-technology/everystack) — a self-hosted application stack for Expo apps on AWS.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@everystack/admin",
+  "version": "0.1.0",
+  "description": "Declarative admin dashboard framework for PostgREST APIs",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./presets/twitter": {
+      "types": "./src/presets/twitter.ts",
+      "default": "./src/presets/twitter.ts"
+    }
+  },
+  "dependencies": {
+    "d3-scale": "^4.0.2",
+    "d3-time-format": "^4.1.0"
+  },
+  "peerDependencies": {
+    "@everystack/api": ">=0.1.0",
+    "@everystack/ui": ">=0.1.0",
+    "react": ">=18.0.0",
+    "react-native": ">=0.72.0"
+  },
+  "devDependencies": {
+    "@types/d3-scale": "^4.0.9",
+    "@types/d3-time-format": "^4.0.3",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.0.0",
+    "@types/react": "~19.2.14",
+    "jest": "^29.7.0",
+    "react": "^19.0.0",
+    "react-native": ">=0.72.0",
+    "ts-jest": "^29.3.0",
+    "typescript": "^5.7.0",
+    "@everystack/api": "0.1.0",
+    "@everystack/ui": "0.1.0"
+  },
+  "scripts": {
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
+    "build": "tsc --build",
+    "lint": "tsc --noEmit"
+  }
+}

package/src/AdminRoot.tsx

@@ -0,0 +1,34 @@
+/**
+ * AdminRoot
+ *
+ * Root component for the admin dashboard.
+ * Combines AdminConfigProvider and DataAdapterProvider.
+ */
+
+import React from 'react';
+import type { AdminConfig } from './types';
+import type { DataAdapter } from './adapters/types';
+import { AdminConfigProvider } from './providers/AdminConfigProvider';
+import { DataAdapterProvider } from './providers/DataAdapterProvider';
+import { StorageConfigContext } from './hooks/useStorageConfig';
+
+export interface AdminRootProps {
+  /** Admin configuration */
+  config: AdminConfig;
+  /** Data adapter for backend communication */
+  adapter: DataAdapter;
+  /** Children to render (typically expo-router's Slot or navigator) */
+  children?: React.ReactNode;
+}
+
+export function AdminRoot({ config, adapter, children }: AdminRootProps) {
+  return (
+    <AdminConfigProvider config={config}>
+      <DataAdapterProvider adapter={adapter}>
+        <StorageConfigContext.Provider value={config.storage ?? null}>
+          {children}
+        </StorageConfigContext.Provider>
+      </DataAdapterProvider>
+    </AdminConfigProvider>
+  );
+}

package/src/adapters/EverystackAdapter.ts

@@ -0,0 +1,218 @@
+/**
+ * EverystackAdapter — bridges the admin DataAdapter interface to everystack/client.
+ *
+ * Translates the admin's ListParams (page/perPage/sort/order/filter)
+ * into PostgREST-compatible queries via the everystack client.
+ */
+
+import { createClient, type Client, type ClientOptions, type QueryBuilder } from '@everystack/api/client';
+import type { DataAdapter } from './types';
+import type {
+  ListParams,
+  ListResult,
+  DataRecord,
+  AggregateParams,
+  AggregateResult,
+} from '../types';
+
+/** Known PostgREST filter operators */
+const POSTGREST_OPERATORS = new Set([
+  'eq', 'neq', 'gt', 'gte', 'lt', 'lte',
+  'like', 'ilike', 'is', 'in', 'not', 'cs', 'cd',
+  'sl', 'sr', 'nxl', 'nxr', 'adj', 'ov', 'fts',
+]);
+
+export interface EverystackAdapterOptions extends ClientOptions {}
+
+export class EverystackAdapter implements DataAdapter {
+  private client: Client;
+
+  constructor(options: EverystackAdapterOptions) {
+    this.client = createClient(options);
+  }
+
+  async fetchList<T extends DataRecord = DataRecord>(
+    resource: string,
+    params: ListParams,
+  ): Promise<ListResult<T>> {
+    const page = params.page ?? 1;
+    const perPage = params.perPage ?? 25;
+    const offset = (page - 1) * perPage;
+
+    let builder = this.client.from(resource);
+
+    // Apply filters
+    builder = applyFilters(builder, params.filter);
+
+    // Apply sort
+    if (params.sort) {
+      builder = builder.order(params.sort, params.order ?? 'asc');
+    }
+
+    // Apply pagination
+    builder = builder.limit(perPage).offset(offset);
+
+    const result = await builder.executeWithCount();
+
+    if (result.error) {
+      throw new Error(result.error.message);
+    }
+
+    return {
+      data: (result.data ?? []) as T[],
+      total: result.total,
+      page,
+      perPage,
+    };
+  }
+
+  async fetchOne<T extends DataRecord = DataRecord>(
+    resource: string,
+    id: string | number,
+  ): Promise<T> {
+    const result = await this.client.from(resource).eq('id', String(id)).single();
+
+    if (result.error) {
+      throw new Error(result.error.status === 406
+        ? `${resource}/${id} not found`
+        : result.error.message);
+    }
+
+    return result.data as T;
+  }
+
+  async create<T extends DataRecord = DataRecord>(
+    resource: string,
+    data: Omit<T, 'id'>,
+  ): Promise<T> {
+    const result = await this.client.from(resource).insert(data as Record<string, unknown>);
+
+    if (result.error) {
+      throw new Error(result.error.message);
+    }
+
+    return result.data as T;
+  }
+
+  async update<T extends DataRecord = DataRecord>(
+    resource: string,
+    id: string | number,
+    data: Partial<T>,
+  ): Promise<T> {
+    const result = await this.client
+      .from(resource)
+      .eq('id', String(id))
+      .update(data as Record<string, unknown>);
+
+    if (result.error) {
+      throw new Error(result.error.message);
+    }
+
+    const rows = result.data as T[];
+    return rows[0];
+  }
+
+  async delete(resource: string, id: string | number): Promise<void> {
+    const result = await this.client.from(resource).eq('id', String(id)).remove();
+
+    if (result.error) {
+      throw new Error(result.error.message);
+    }
+  }
+
+  async aggregate(resource: string, params: AggregateParams): Promise<AggregateResult> {
+    const selectParts: string[] = [];
+
+    // Add groupBy columns first
+    if (params.groupBy) {
+      selectParts.push(...params.groupBy);
+    }
+
+    // Build aggregate select expressions
+    for (const agg of params.aggregates) {
+      if (agg.column) {
+        // column.fn() — e.g., amount.sum()
+        selectParts.push(`${agg.column}.${agg.function}()`);
+      } else {
+        // count() with no column
+        selectParts.push(`${agg.function}()`);
+      }
+    }
+
+    let builder = this.client.from(resource).select(selectParts.join(','));
+
+    // Apply filters
+    builder = applyFilters(builder, params.filter);
+
+    const result = await builder.execute();
+
+    if (result.error) {
+      throw new Error(result.error.message);
+    }
+
+    return {
+      data: (result.data ?? []) as Record<string, unknown>[],
+      meta: {
+        aggregate: true,
+        groupBy: params.groupBy,
+      },
+    };
+  }
+}
+
+/**
+ * Apply admin filter params to a query builder.
+ * Detects PostgREST-formatted values (e.g., "eq.active", "gt.100")
+ * vs plain values (e.g., "active") and wraps plain values with eq.
+ */
+function applyFilters(builder: QueryBuilder, filter?: Record<string, unknown>): QueryBuilder {
+  if (!filter) return builder;
+
+  for (const [key, value] of Object.entries(filter)) {
+    if (value == null) continue;
+
+    const strValue = String(value);
+
+    if (isPostgrestFilter(strValue)) {
+      // Already formatted — extract operator and value
+      const dotIndex = strValue.indexOf('.');
+      const op = strValue.substring(0, dotIndex);
+      const val = strValue.substring(dotIndex + 1);
+
+      switch (op) {
+        case 'eq': builder = builder.eq(key, val); break;
+        case 'neq': builder = builder.neq(key, val); break;
+        case 'gt': builder = builder.gt(key, val); break;
+        case 'gte': builder = builder.gte(key, val); break;
+        case 'lt': builder = builder.lt(key, val); break;
+        case 'lte': builder = builder.lte(key, val); break;
+        case 'like': builder = builder.like(key, val); break;
+        case 'ilike': builder = builder.ilike(key, val); break;
+        case 'is': builder = builder.is(key, val); break;
+        case 'in': {
+          const values = val.replace(/^\(/, '').replace(/\)$/, '').split(',');
+          builder = builder.in(key, values);
+          break;
+        }
+        default:
+          // Unknown operator — use eq with full value
+          builder = builder.eq(key, strValue);
+      }
+    } else {
+      // Plain value — wrap with eq
+      builder = builder.eq(key, strValue);
+    }
+  }
+
+  return builder;
+}
+
+/**
+ * Check if a filter value is already in PostgREST format (operator.value).
+ */
+function isPostgrestFilter(value: string): boolean {
+  const dotIndex = value.indexOf('.');
+  if (dotIndex <= 0) return false;
+  const prefix = value.substring(0, dotIndex);
+  return POSTGREST_OPERATORS.has(prefix);
+}

package/src/adapters/types.ts

@@ -0,0 +1,78 @@
+/**
+ * Data Adapter Interface
+ *
+ * The DataAdapter provides a backend-agnostic abstraction for data operations.
+ * Implement this interface to connect the admin to any data source.
+ */
+
+import type {
+  ListParams,
+  ListResult,
+  DataRecord,
+  AggregateParams,
+  AggregateResult,
+} from '../types';
+
+// =============================================================================
+// Adapter Interface
+// =============================================================================
+
+export interface DataAdapter {
+  /**
+   * Fetch a list of records with pagination, sorting, and filtering
+   */
+  fetchList<T extends DataRecord = DataRecord>(
+    resource: string,
+    params: ListParams
+  ): Promise<ListResult<T>>;
+
+  /**
+   * Fetch a single record by ID
+   */
+  fetchOne<T extends DataRecord = DataRecord>(resource: string, id: string | number): Promise<T>;
+
+  /**
+   * Create a new record
+   */
+  create<T extends DataRecord = DataRecord>(resource: string, data: Omit<T, 'id'>): Promise<T>;
+
+  /**
+   * Update an existing record
+   */
+  update<T extends DataRecord = DataRecord>(
+    resource: string,
+    id: string | number,
+    data: Partial<T>
+  ): Promise<T>;
+
+  /**
+   * Delete a record
+   */
+  delete(resource: string, id: string | number): Promise<void>;
+
+  /**
+   * Fetch aggregate data (count, sum, avg, min, max) with optional grouping
+   */
+  aggregate?(resource: string, params: AggregateParams): Promise<AggregateResult>;
+
+  /**
+   * Subscribe to real-time updates (optional)
+   */
+  subscribe?<T extends DataRecord = DataRecord>(
+    resource: string,
+    callback: (event: SubscriptionEvent<T>) => void
+  ): () => void;
+}
+
+// =============================================================================
+// Subscription Types
+// =============================================================================
+
+export type SubscriptionEventType = 'insert' | 'update' | 'delete';
+
+export interface SubscriptionEvent<T extends DataRecord = DataRecord> {
+  type: SubscriptionEventType;
+  resource: string;
+  record: T;
+  previousRecord?: T;
+}