@everystack/admin 0.1.0

package/src/types.ts

@@ -0,0 +1,358 @@
+/**
+ * Core type definitions for everystack/admin
+ *
+ * These types define the DSL (Domain-Specific Language) for configuring
+ * admin dashboards declaratively.
+ */
+
+// =============================================================================
+// Field Types
+// =============================================================================
+
+export type FieldType =
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'date'
+  | 'datetime'
+  | 'email'
+  | 'url'
+  | 'json'
+  | 'enum'
+  | 'relation'
+  | 'image'
+  | 'file';
+
+export interface FieldDefinition {
+  /** Field name (matches data key) */
+  name: string;
+  /** Display label */
+  label?: string;
+  /** Field type for rendering */
+  type: FieldType;
+  /** Whether field is sortable in tables */
+  sortable?: boolean;
+  /** Whether field is searchable */
+  searchable?: boolean;
+  /** Whether field is filterable */
+  filterable?: boolean;
+  /** For enum types: allowed values */
+  enumValues?: string[];
+  /** For relation types: related resource name */
+  relation?: {
+    resource: string;
+    field: string;
+    displayField?: string;
+  };
+  /** Validation rules */
+  validation?: {
+    required?: boolean;
+    min?: number;
+    max?: number;
+    pattern?: string;
+    message?: string;
+  };
+  /** Renderer variant for this field type (e.g., 'avatar' for image fields) */
+  renderer?: string;
+}
+
+// =============================================================================
+// Resource Configuration
+// =============================================================================
+
+export interface ResourceConfig {
+  /** Unique resource identifier (e.g., 'users', 'orders') */
+  name: string;
+  /** Display label (singular) */
+  label?: string;
+  /** Display label (plural) */
+  labelPlural?: string;
+  /** Icon name for navigation */
+  icon?: string;
+  /** Field definitions */
+  fields: FieldDefinition[];
+  /** Default sort field */
+  defaultSort?: {
+    field: string;
+    order: 'asc' | 'desc';
+  };
+  /** Available actions */
+  actions?: {
+    list?: boolean;
+    show?: boolean;
+    create?: boolean;
+    edit?: boolean;
+    delete?: boolean;
+  };
+  /** Fields to display in list view */
+  listFields?: string[];
+  /** Fields to display in detail/show view */
+  showFields?: string[];
+  /** Fields to display in create form */
+  createFields?: string[];
+  /** Fields to display in edit form */
+  editFields?: string[];
+  /** Primary key field name */
+  primaryKey?: string;
+  /** Optional observability-style dashboard configuration */
+  dashboard?: ResourceDashboardConfig;
+}
+
+// =============================================================================
+// Resource Dashboard
+// =============================================================================
+
+/** How to compute a stat dial value. */
+export type StatDialValue =
+  | { type: 'count' }
+  | { type: 'count_where'; column: string; equals: string }
+  | { type: 'distinct'; column: string }
+  | { type: 'table_count'; table: string; timestampColumn?: string };
+
+/** Configuration for a single stat dial in the dashboard header. */
+export interface StatDialConfig {
+  /** Unique identifier */
+  id: string;
+  /** Display label */
+  label: string;
+  /** Ring color (hex) */
+  color: string;
+  /** How to compute the value */
+  value: StatDialValue;
+  /** Ring fill: 'of_total' computes value/total, number is a fixed ratio. Default: 1. */
+  ratio?: 'of_total' | number;
+}
+
+/** A filterable dimension (renders as bars or donut chart). */
+export interface DimensionConfig {
+  /** Column name in the database table */
+  column: string;
+  /** Display label */
+  label: string;
+  /** Chart type for this dimension */
+  chartType: 'bars' | 'donut';
+  /** Allowed values — whitelist for SQL safety. Falls back to field enumValues. */
+  allowedValues?: string[];
+  /** Color map: { value: hexColor } */
+  colors?: Record<string, string>;
+  /** Display order for values (donut chart). */
+  order?: string[];
+}
+
+/** Dashboard configuration attached to a ResourceConfig. */
+export interface ResourceDashboardConfig {
+  /** Title displayed at the top */
+  title?: string;
+  /** The datetime column for the time histogram */
+  timestampColumn: string;
+  /** Time window in hours (default: 168 = 7 days) */
+  defaultHours?: number;
+  /** Time bucket granularity (default: 'hour') */
+  bucketSize?: 'hour' | 'day';
+  /** Stat dials to show above the histogram */
+  stats: StatDialConfig[];
+  /** Filterable dimensions (columns → bar/donut charts) */
+  dimensions: DimensionConfig[];
+  /** Primary key column(s) for the event list (default: 'id'). Use array for composite keys. */
+  primaryKey?: string | string[];
+  /** Columns to display in the event list */
+  listColumns: string[];
+  /** Columns searchable via ILIKE in the event list */
+  searchColumns?: string[];
+  /** Navigate to detail on row press (default: true) */
+  linkToDetail?: boolean;
+}
+
+// =============================================================================
+// Dashboard & Widgets
+// =============================================================================
+
+export type WidgetType = 'stat' | 'chart' | 'table' | 'list' | 'custom';
+export type ChartType = 'line' | 'bar' | 'area' | 'pie' | 'donut';
+
+export interface WidgetConfig {
+  /** Unique widget identifier */
+  id: string;
+  /** Widget type */
+  type: WidgetType;
+  /** Display title */
+  title: string;
+  /** Grid position and size */
+  grid?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  /** Data source configuration */
+  data?: {
+    resource?: string;
+    query?: Record<string, unknown>;
+    aggregation?: 'count' | 'sum' | 'avg' | 'min' | 'max';
+    field?: string;
+    groupBy?: string;
+  };
+  /** Chart-specific options */
+  chart?: {
+    type: ChartType;
+    xField?: string;
+    yField?: string;
+    colorField?: string;
+  };
+  /** Stat-specific options */
+  stat?: {
+    format?: 'number' | 'currency' | 'percent';
+    trend?: {
+      field: string;
+      comparison: 'previous_period' | 'previous_year';
+    };
+  };
+}
+
+export interface DashboardConfig {
+  /** Unique dashboard identifier */
+  id: string;
+  /** Display title */
+  title: string;
+  /** Dashboard description */
+  description?: string;
+  /** Widget configurations */
+  widgets: WidgetConfig[];
+  /** Auto-refresh interval in seconds */
+  refreshInterval?: number;
+}
+
+// =============================================================================
+// Navigation & Menu
+// =============================================================================
+
+export interface MenuItem {
+  /** Menu item identifier */
+  id: string;
+  /** Display label */
+  label: string;
+  /** Icon name */
+  icon?: string;
+  /** Navigation path */
+  path?: string;
+  /** Resource name (for resource links) */
+  resource?: string;
+  /** Dashboard ID (for dashboard links) */
+  dashboard?: string;
+  /** Nested menu items */
+  children?: MenuItem[];
+  /** Badge content */
+  badge?: string | number;
+}
+
+// =============================================================================
+// Admin Configuration
+// =============================================================================
+
+// =============================================================================
+// Storage Configuration
+// =============================================================================
+
+export interface StorageConfig {
+  /** Storage API endpoint (e.g., '/api/storage') */
+  endpoint: string;
+  /** CDN base URL for image transforms (e.g., 'https://d15vjr4un7lj63.cloudfront.net') */
+  cdnUrl?: string;
+  /** Auth token getter for upload requests */
+  getToken?: () => string | null | Promise<string | null>;
+}
+
+export interface AdminConfig {
+  /** Application title */
+  title: string;
+  /** Application subtitle/description */
+  subtitle?: string;
+  /** Resource configurations */
+  resources: ResourceConfig[];
+  /** Dashboard configurations */
+  dashboards?: DashboardConfig[];
+  /** Navigation menu */
+  menu?: MenuItem[];
+  /** Theme configuration */
+  theme?: {
+    primaryColor?: string;
+    backgroundColor?: string;
+    textColor?: string;
+    accentColor?: string;
+  };
+  /** Base path for admin routes */
+  basePath?: string;
+  /** Storage configuration for image/file upload fields */
+  storage?: StorageConfig;
+}
+
+// =============================================================================
+// Data Types
+// =============================================================================
+
+export interface ListParams {
+  /** Page number (1-indexed) */
+  page?: number;
+  /** Items per page */
+  perPage?: number;
+  /** Sort field */
+  sort?: string;
+  /** Sort order */
+  order?: 'asc' | 'desc';
+  /** Filter conditions */
+  filter?: Record<string, unknown>;
+  /** Search query */
+  search?: string;
+}
+
+export interface ListResult<T = Record<string, unknown>> {
+  /** Data items */
+  data: T[];
+  /** Total count (for pagination) */
+  total: number;
+  /** Current page */
+  page: number;
+  /** Items per page */
+  perPage: number;
+}
+
+export interface DataRecord {
+  id: string | number;
+  [key: string]: unknown;
+}
+
+// =============================================================================
+// Aggregate Types
+// =============================================================================
+
+export type AggregateFunction = 'count' | 'sum' | 'avg' | 'min' | 'max';
+
+export interface AggregateQuery {
+  /** Aggregate function to apply */
+  function: AggregateFunction;
+  /** Column to aggregate (optional for count()) */
+  column?: string;
+  /** Alias for the result */
+  alias?: string;
+  /** Use DISTINCT (for count) */
+  distinct?: boolean;
+}
+
+export interface AggregateParams {
+  /** Aggregate functions to compute */
+  aggregates: AggregateQuery[];
+  /** Columns to group by */
+  groupBy?: string[];
+  /** Filter conditions */
+  filter?: Record<string, unknown>;
+}
+
+export interface AggregateResult {
+  /** Aggregated data rows */
+  data: Record<string, unknown>[];
+  /** Metadata about the query */
+  meta?: {
+    aggregate: boolean;
+    groupBy?: string[];
+  };
+}

package/src/utils/naming.ts

@@ -0,0 +1,105 @@
+/**
+ * Column Naming Utilities
+ *
+ * Utilities for resolving field values from records that may use
+ * either snake_case (database convention) or camelCase (JavaScript convention).
+ */
+
+/**
+ * Convert snake_case to camelCase
+ */
+export function toCamelCase(str: string): string {
+  return str.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+
+/**
+ * Convert camelCase to snake_case
+ */
+export function toSnakeCase(str: string): string {
+  return str.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}
+
+/**
+ * Get a value from a record, trying both snake_case and camelCase keys
+ */
+export function getFieldValue<T = unknown>(
+  record: Record<string, unknown>,
+  fieldName: string
+): T | undefined {
+  // Try exact match first
+  if (fieldName in record) {
+    return record[fieldName] as T;
+  }
+
+  // If fieldName is snake_case, try camelCase
+  if (fieldName.includes('_')) {
+    const camelCase = toCamelCase(fieldName);
+    if (camelCase in record) {
+      return record[camelCase] as T;
+    }
+  }
+
+  // If fieldName is camelCase, try snake_case
+  const snakeCase = toSnakeCase(fieldName);
+  if (snakeCase !== fieldName && snakeCase in record) {
+    return record[snakeCase] as T;
+  }
+
+  return undefined;
+}
+
+/**
+ * Check if a field exists in a record (using both naming conventions)
+ */
+export function hasField(record: Record<string, unknown>, fieldName: string): boolean {
+  return getFieldValue(record, fieldName) !== undefined;
+}
+
+/**
+ * Resolve the actual key name used in a record for a given field
+ */
+export function resolveFieldKey(record: Record<string, unknown>, fieldName: string): string {
+  if (fieldName in record) {
+    return fieldName;
+  }
+
+  if (fieldName.includes('_')) {
+    const camelCase = toCamelCase(fieldName);
+    if (camelCase in record) {
+      return camelCase;
+    }
+  }
+
+  const snakeCase = toSnakeCase(fieldName);
+  if (snakeCase !== fieldName && snakeCase in record) {
+    return snakeCase;
+  }
+
+  return fieldName;
+}
+
+/**
+ * Transform a record's keys from camelCase to snake_case
+ */
+export function toSnakeCaseKeys<T extends Record<string, unknown>>(
+  record: T
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(record)) {
+    result[toSnakeCase(key)] = value;
+  }
+  return result;
+}
+
+/**
+ * Transform a record's keys from snake_case to camelCase
+ */
+export function toCamelCaseKeys<T extends Record<string, unknown>>(
+  record: T
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(record)) {
+    result[toCamelCase(key)] = value;
+  }
+  return result;
+}

package/src/utils/pick-image-web.ts

@@ -0,0 +1,81 @@
+/**
+ * pickImageWeb
+ *
+ * Web-only image picker using the native file input API.
+ * Creates a hidden <input type="file">, triggers click, and returns
+ * both the File object (for upload) and a PickResult (for preview).
+ */
+
+import type { PickResult } from '@everystack/ui';
+
+export interface PickImageWebResult {
+  file: File;
+  preview: PickResult;
+}
+
+export function pickImageWeb(accept?: string): Promise<PickImageWebResult | null> {
+  return new Promise((resolve) => {
+    const input = document.createElement('input');
+    input.type = 'file';
+    input.accept = accept ?? 'image/*';
+    input.style.display = 'none';
+    document.body.appendChild(input);
+
+    let resolved = false;
+
+    input.onchange = () => {
+      resolved = true;
+      const file = input.files?.[0];
+      document.body.removeChild(input);
+
+      if (!file) {
+        resolve(null);
+        return;
+      }
+
+      const uri = URL.createObjectURL(file);
+
+      // Read image dimensions
+      const img = new window.Image();
+      img.onload = () => {
+        resolve({
+          file,
+          preview: {
+            uri,
+            width: img.naturalWidth,
+            height: img.naturalHeight,
+            type: file.type,
+            fileName: file.name,
+            fileSize: file.size,
+          },
+        });
+      };
+      img.onerror = () => {
+        // Non-image or unreadable — still return with what we have
+        resolve({
+          file,
+          preview: {
+            uri,
+            type: file.type,
+            fileName: file.name,
+            fileSize: file.size,
+          },
+        });
+      };
+      img.src = uri;
+    };
+
+    // Detect cancel: focus returns to window without onchange firing
+    window.addEventListener('focus', function onFocus() {
+      window.removeEventListener('focus', onFocus);
+      setTimeout(() => {
+        if (!resolved) {
+          try { document.body.removeChild(input); } catch { /* already removed */ }
+          resolve(null);
+        }
+      }, 300);
+    }, { once: true });
+
+    input.click();
+  });
+}

package/src/utils/resolve-image-url.ts

@@ -0,0 +1,43 @@
+/**
+ * resolveImageUrl
+ *
+ * Resolves a stored value (storage key or full URL) to a displayable image URL.
+ *
+ * - Full URLs (http:// or https://) are returned as-is (legacy data).
+ * - Storage keys are routed through CDN (with optional transforms) or
+ *   the storage handler's /files/:key endpoint.
+ */
+
+import { buildImageUrl, type ImageTransformOptions } from '@everystack/ui/image-url';
+
+export interface ResolveImageUrlOptions {
+  /** CDN base URL for image transforms */
+  cdnUrl?: string;
+  /** Storage API endpoint for direct file serving */
+  endpoint?: string;
+  /** Image transform options (only used with cdnUrl) */
+  transform?: ImageTransformOptions;
+}
+
+export function resolveImageUrl(
+  value: string,
+  options: ResolveImageUrlOptions,
+): string {
+  // Full URL — return unchanged
+  if (value.startsWith('http://') || value.startsWith('https://')) {
+    return value;
+  }
+
+  // CDN URL — build transform URL
+  if (options.cdnUrl) {
+    return buildImageUrl(options.cdnUrl, value, options.transform);
+  }
+
+  // Storage endpoint — direct file serving
+  if (options.endpoint) {
+    return `${options.endpoint}/files/${encodeURIComponent(value)}`;
+  }
+
+  // No options — return raw value
+  return value;
+}

package/src/utils/upload-file.ts

@@ -0,0 +1,93 @@
+/**
+ * uploadFile
+ *
+ * Self-contained presigned URL upload utility.
+ * Step 1: POST /presign with file metadata + auth token → { url, key }
+ * Step 2: XHR PUT to presigned URL with progress tracking.
+ *
+ * No external dependencies — avoids coupling everystack/admin to @everystack/storage.
+ */
+
+export interface UploadFileOptions {
+  /** Storage API endpoint (e.g., '/api/storage') */
+  endpoint: string;
+  /** File to upload */
+  file: File;
+  /** Auth token getter */
+  getToken?: () => string | null | Promise<string | null>;
+  /** Upload progress callback (0-100) */
+  onProgress?: (percentage: number) => void;
+  /** AbortSignal for cancellation */
+  signal?: AbortSignal;
+}
+
+export interface UploadFileResult {
+  key: string;
+}
+
+export async function uploadFile(options: UploadFileOptions): Promise<UploadFileResult> {
+  const { endpoint, file, getToken, onProgress, signal } = options;
+
+  // Build auth headers
+  const headers: Record<string, string> = { 'content-type': 'application/json' };
+  if (getToken) {
+    const token = await getToken();
+    if (token) headers['authorization'] = `Bearer ${token}`;
+  }
+
+  // Step 1: Get presigned URL
+  const presignRes = await fetch(`${endpoint}/presign`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({
+      name: file.name,
+      type: file.type,
+      size: file.size,
+    }),
+    signal,
+  });
+
+  if (!presignRes.ok) {
+    const body = await presignRes.json().catch(() => ({ error: 'Presign failed' }));
+    throw new Error((body as Record<string, unknown>).error as string || `Presign failed: ${presignRes.status}`);
+  }
+
+  const { url, key } = await presignRes.json() as { url: string; key: string };
+
+  // Step 2: XHR PUT to presigned URL with progress
+  await new Promise<void>((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+
+    if (signal) {
+      if (signal.aborted) {
+        reject(new Error('Upload cancelled'));
+        return;
+      }
+      signal.addEventListener('abort', () => xhr.abort());
+    }
+
+    xhr.upload.onprogress = (e: ProgressEvent) => {
+      if (e.lengthComputable && onProgress) {
+        onProgress(Math.round((e.loaded / e.total) * 100));
+      }
+    };
+
+    xhr.onload = () => {
+      if (xhr.status >= 200 && xhr.status < 300) {
+        resolve();
+      } else {
+        reject(new Error(`Upload failed: ${xhr.status}`));
+      }
+    };
+
+    xhr.onerror = () => reject(new Error('Upload failed: network error'));
+    xhr.onabort = () => reject(new Error('Upload cancelled'));
+
+    xhr.open('PUT', url);
+    xhr.setRequestHeader('content-type', file.type);
+    xhr.send(file);
+  });
+
+  onProgress?.(100);
+  return { key };
+}