spine-framework 0.1.0

package/.framework/src/hooks/useEntityList.ts

@@ -0,0 +1,190 @@
+/**
+ * @module src/hooks/useEntityList
+ * @audience installer
+ * @layer frontend-hook
+ * @stability stable
+ *
+ * Schema-driven list data hook. Given an entity name and a minimal
+ * `MinimalEntityListConfig`, fetches a paginated, filtered, and sorted list
+ * from the API and exposes controls for filters, sort, and pagination.
+ *
+ * **How it works:**
+ * 1. Builds query params from `entity`, `config.api`, filters, sort, and pagination
+ * 2. Calls `apiFetch('/api/<endpoint>?action=list&...')` via `useApi`
+ * 3. Re-fetches when `config` arrives (async schema load), or when filters change
+ *    (which also resets page to 1)
+ *
+ * **Auth retry:** `useApi` re-executes on route navigation, which naturally
+ * retries after the auth session hydrates on the next tick.
+ *
+ * @seeAlso src/hooks/useApi.ts (useApi — underlying fetch + abort primitive)
+ * @seeAlso src/lib/api.ts (apiFetch)
+ * @seeAlso src/components/runtime/DataListPage.tsx (primary consumer)
+ * @seeAlso functions/admin-data.ts (API endpoint for list action)
+ */
+
+import { useState, useEffect, useCallback } from 'react'
+import { useApi } from './useApi'
+import { apiFetch } from '../lib/api'
+
+// ─── TYPES ───────────────────────────────────────────────────────────────────
+
+/**
+ * Minimal configuration shape consumed by `useEntityList`.
+ *
+ * @prop entity - Entity name (used as fallback endpoint, filter param)
+ * @prop typeSlug - Optional type slug; appended as `type_slug` param if present
+ * @prop api.endpoint - Netlify function base path (e.g. `'admin-data'`)
+ * @prop api.listAction - Action string; defaults to `'list'`
+ * @prop list.defaultSort - Initial sort field and direction
+ */
+interface MinimalEntityListConfig {
+  entity: string
+  typeSlug?: string
+  api: {
+    endpoint: string
+    listAction?: string
+  }
+  list: {
+    defaultSort: { field: string; direction: 'asc' | 'desc' }
+  }
+}
+
+/**
+ * Return value of `useEntityList`.
+ *
+ * @prop data - Fetched records array (empty while loading or on error)
+ * @prop loading - True while fetching
+ * @prop error - Error message or null
+ * @prop refetch - Re-execute the current query
+ * @prop filters - Active filter values keyed by param name
+ * @prop setFilters - Replace the active filters (resets page to 1)
+ * @prop sort - Current sort field and direction
+ * @prop setSort - Update sort (does not auto-reset page)
+ * @prop pagination - page/setPage/pageSize/setPageSize/total controls
+ */
+interface UseEntityListReturn {
+  data: any[]
+  loading: boolean
+  error: string | null
+  refetch: () => void
+  filters: Record<string, any>
+  setFilters: (filters: Record<string, any>) => void
+  sort: { field: string; direction: 'asc' | 'desc' }
+  setSort: (sort: { field: string; direction: 'asc' | 'desc' }) => void
+  pagination: {
+    page: number
+    setPage: (page: number) => void
+    pageSize: number
+    setPageSize: (size: number) => void
+    total: number
+  }
+}
+
+// ─── HOOK ────────────────────────────────────────────────────────────────────
+
+/**
+ * Fetches and manages a filtered, sorted, paginated entity list.
+ *
+ * @param entity - Entity name (e.g. `'accounts'`, `'items'`)
+ * @param config - Schema-derived config; pass `null` while schema is loading
+ *   (hook is a no-op until config is non-null)
+ * @returns `UseEntityListReturn` — see type for full details
+ *
+ * @inputSpec config.api.endpoint: string — function name, e.g. `'admin-data'`
+ * @inputSpec filters: values of `''`, `undefined`, or `'all'` are omitted from params
+ * @outputSpec data: any[] — raw API response; shape depends on entity type
+ * @sideEffects Network request via apiFetch; React state mutations
+ * @calledBy DataListPage.tsx
+ *
+ * @example
+ * ```tsx
+ * const { data, loading, setFilters } = useEntityList('accounts', config)
+ * ```
+ */
+export function useEntityList(
+  entity: string,
+  config: MinimalEntityListConfig | null
+): UseEntityListReturn {
+  const [filters, setFilters] = useState<Record<string, any>>({})
+  const [sort, setSort] = useState<{ field: string; direction: 'asc' | 'desc' }>(config?.list?.defaultSort || { field: 'created_at', direction: 'desc' })
+  const [page, setPage] = useState(1)
+  const [pageSize, setPageSize] = useState(50)
+  
+  const fetchData = useCallback(async () => {
+    if (!config) return
+    
+    const params = new URLSearchParams()
+    
+    // Support new endpoint-based API pattern
+    const endpoint = config.api.endpoint || entity
+    const action = config.api.listAction || 'list'
+    params.append('action', action)
+    
+    // Add entity parameter for unified admin-data endpoint
+    if (config.api.endpoint) {
+      params.append('entity', entity)
+    }
+    
+    // Add type_slug for schema-driven filtering if available
+    if (config.typeSlug) {
+      params.append('type_slug', config.typeSlug)
+    }
+    
+    // Add filters
+    Object.entries(filters).forEach(([key, value]) => {
+      if (value !== undefined && value !== '' && value !== 'all') {
+        params.append(key, value.toString())
+      }
+    })
+    
+    // Add sort
+    params.append('sort_field', sort.field)
+    params.append('sort_direction', sort.direction)
+    
+    // Add pagination
+    params.append('limit', pageSize.toString())
+    params.append('offset', ((page - 1) * pageSize).toString())
+    
+    const response = await apiFetch(`/api/${endpoint}?${params.toString()}`)
+    
+    if (!response.ok) {
+      throw new Error(`Failed to fetch ${entity}: ${response.statusText}`)
+    }
+    
+    const result = await response.json()
+    return result.data || []
+  }, [entity, config?.api.endpoint, config?.api.listAction, config?.typeSlug, filters, sort, page, pageSize])
+  
+  const { data, loading, error, execute, refetch } = useApi<any[]>(fetchData, {
+    immediate: true
+  })
+
+  // Re-fetch when config arrives (schema was not ready on initial mount)
+  useEffect(() => {
+    if (config) execute()
+  }, [config?.api.endpoint, config?.api.listAction, config?.typeSlug])
+
+  // Reset page when filters change
+  useEffect(() => {
+    setPage(1)
+  }, [filters])
+  
+  return {
+    data: data || [],
+    loading,
+    error,
+    refetch,
+    filters,
+    setFilters,
+    sort,
+    setSort,
+    pagination: {
+      page,
+      setPage,
+      pageSize,
+      setPageSize,
+      total: data?.length || 0
+    }
+  }
+}

package/.framework/src/hooks/useEntityRecord.ts

@@ -0,0 +1,308 @@
+/**
+ * @module src/hooks/useEntityRecord
+ * @audience installer
+ * @layer frontend-hook
+ * @stability stable
+ *
+ * Schema-driven single-record hook. Fetches a record by ID, exposes its
+ * design schema, computes field-level read/write permissions for the
+ * current principal, and provides save and delete mutations.
+ *
+ * **Field permission model:**
+ * - `system_admin` role always gets `{ read: true, write: true }` on all fields
+ * - Other principals: permissions are read from `design_schema.fields[n].permissions`
+ *   as role arrays; defaults to `true` if absent
+ *
+ * **Save routing:**
+ * - Fields marked `fieldDef.system = true` go to top-level record columns
+ * - All other fields are nested under the `data` JSONB column
+ *
+ * **Delete:** sends a `DELETE` request with the configured `deleteAction`;
+ *   hard vs. soft delete is determined by the API handler (`config.softDelete`
+ *   signals intent to the handler).
+ *
+ * @seeAlso src/hooks/useApi.ts (useApi + useMutation primitives)
+ * @seeAlso src/hooks/useSchemaRecord.ts (companion for schema-driven form data)
+ * @seeAlso src/components/runtime/DataDetailPage.tsx (primary consumer)
+ * @seeAlso functions/admin-data.ts (API endpoint handling get/update/delete)
+ */
+
+import { useCallback } from 'react'
+import { useApi, useMutation } from './useApi'
+import { apiFetch } from '../lib/api'
+import { useAuth } from '../contexts/AuthContext'
+
+// ─── TYPES ───────────────────────────────────────────────────────────────────
+
+/**
+ * Per-field read/write permission map keyed by field name.
+ * Computed from `design_schema.fields[n].permissions` and the current user's roles.
+ */
+interface FieldPermissions {
+  [key: string]: { read: boolean; write: boolean }
+}
+
+/**
+ * Minimal entity configuration consumed by `useEntityRecord`.
+ *
+ * @prop entity - Entity table name
+ * @prop typeSlug - Optional type slug for schema resolution
+ * @prop icon - Icon identifier (used by detail page header)
+ * @prop displayField - Field name used as the record title
+ * @prop api.endpoint - Netlify function base path
+ * @prop api.*Action - Action strings for get/create/update/delete
+ * @prop softDelete - Hint for the API handler (true = set is_active=false)
+ */
+interface MinimalEntityConfig {
+  entity: string
+  typeSlug?: string
+  icon: string
+  displayField: string
+  api: {
+    endpoint: string
+    getAction?: string
+    createAction?: string
+    updateAction?: string
+    deleteAction?: string
+  }
+  softDelete?: boolean
+}
+
+/**
+ * Return value of `useEntityRecord`.
+ *
+ * @prop record - Fetched record or null
+ * @prop schema - `design_schema` extracted from the record (or nested type)
+ * @prop fieldPermissions - Per-field `{ read, write }` map for the current user
+ * @prop loading - True while fetching
+ * @prop error - Error message or null
+ * @prop refetch - Re-fetch the record
+ * @prop save - Trigger the save mutation (create or update based on `id`)
+ * @prop delete - Trigger the delete mutation
+ * @prop saving / deleting - Mutation loading flags
+ */
+interface UseEntityRecordReturn {
+  record: any
+  schema: any
+  fieldPermissions: FieldPermissions
+  loading: boolean
+  error: string | null
+  refetch: () => void
+  save: (data: any) => Promise<void>
+  delete: () => Promise<void>
+  saving: boolean
+  deleting: boolean
+}
+
+// ─── HOOK ────────────────────────────────────────────────────────────────────
+
+/**
+ * Fetches, saves, and deletes a single entity record with schema and
+ * field-permission awareness.
+ *
+ * @param entity - Entity table name (e.g. `'accounts'`)
+ * @param id - Record UUID; pass `undefined` to enter create mode
+ * @param config - Schema-derived config; pass `null` while loading
+ * @returns `UseEntityRecordReturn` — see type for full details
+ *
+ * @inputSpec id: string | undefined — undefined triggers create mode (no GET)
+ * @outputSpec schema: DesignSchema | {} — empty object if no design_schema found
+ * @outputSpec fieldPermissions: FieldPermissions — computed per-render
+ * @sideEffects Network requests via apiFetch; React state mutations
+ * @calledBy DataDetailPage.tsx
+ *
+ * @example
+ * ```tsx
+ * const { record, save, saving, fieldPermissions } =
+ *   useEntityRecord('accounts', id, config)
+ * ```
+ */
+export function useEntityRecord(
+  entity: string,
+  id: string | undefined,
+  config: MinimalEntityConfig | null
+): UseEntityRecordReturn {
+  const { user } = useAuth()
+  
+  // Get API configuration with safe defaults
+  const endpoint = config?.api?.endpoint || entity
+  const getAction = config?.api?.getAction || 'get'
+  const createAction = config?.api?.createAction || 'create'
+  const updateAction = config?.api?.updateAction || 'update'
+  const deleteAction = config?.api?.deleteAction || 'delete'
+  
+  // Fetch record - always call useCallback to maintain hook order
+  const fetchRecord = useCallback(async () => {
+    if (!id) return null
+    
+    const params = new URLSearchParams()
+    params.append('action', getAction)
+    params.append('entity', entity)
+    params.append('id', id)
+    
+    const response = await apiFetch(`/api/${endpoint}?${params.toString()}`)
+    
+    if (!response.ok) {
+      throw new Error(`Failed to fetch ${entity}: ${response.statusText}`)
+    }
+    
+    const result = await response.json()
+    return result.data || result
+  }, [entity, id, endpoint, getAction])
+  
+  const { data: record, loading, error, refetch } = useApi<any>(fetchRecord, {
+    immediate: !!id
+  })
+  
+  // Extract schema from record (accounts have it at root level, items/types have it nested)
+  const schema = record?.design_schema || record?.type?.design_schema || {}
+  
+  // Calculate field permissions from record's schema
+  const calculatePermissions = (): FieldPermissions => {
+    const permissions: FieldPermissions = {}
+    
+    // System admin gets full access
+    const isSystemAdmin = user?.roles?.includes('system_admin')
+    
+    // Get all fields from record's schema
+    const recordSchema = record?.design_schema?.fields
+    if (!recordSchema) return permissions
+    
+    Object.entries(recordSchema).forEach(([fieldName, fieldSchema]: [string, any]) => {
+      if (isSystemAdmin) {
+        permissions[fieldName] = { read: true, write: true }
+      } else {
+        // Check field-level permissions from schema
+        const fieldPerms = fieldSchema?.permissions || {}
+        
+        const canRead = fieldPerms.read?.some((role: string) => 
+          user?.roles?.includes(role)
+        ) ?? true
+        
+        const canWrite = fieldPerms.write?.some((role: string) => 
+          user?.roles?.includes(role)
+        ) ?? true
+        
+        permissions[fieldName] = { read: canRead, write: canWrite }
+      }
+    })
+    
+    return permissions
+  }
+  
+  const fieldPermissions = calculatePermissions()
+  
+  // Save mutation
+  const saveMutation = useMutation(
+    async (data: any) => {
+      // Separate system fields from custom fields
+      const systemData: Record<string, any> = {}
+      const customData: Record<string, any> = {}
+      
+      Object.entries(data).forEach(([key, value]) => {
+        const fieldDef = record?.design_schema?.fields?.[key]
+        if (fieldDef?.system) {
+          systemData[key] = value
+        } else {
+          customData[key] = value
+        }
+      })
+      
+      // Combine system fields with custom data in data field
+      const saveData = {
+        ...systemData,
+        data: Object.keys(customData).length > 0 ? customData : undefined
+      }
+      
+      if (id) {
+        // Update
+        const params = new URLSearchParams()
+        params.append('action', updateAction)
+        params.append('entity', entity)
+        params.append('id', id)
+        
+        const response = await apiFetch(
+          `/api/${endpoint}?${params.toString()}`,
+          {
+            method: 'PATCH',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(saveData)
+          }
+        )
+        
+        if (!response.ok) {
+          throw new Error(`Failed to update ${entity}: ${response.statusText}`)
+        }
+        
+        return response.json()
+      } else {
+        // Create
+        const createData = { entity, ...saveData }
+        
+        const params = new URLSearchParams()
+        params.append('action', createAction)
+        params.append('entity', entity)
+        
+        const response = await apiFetch(
+          `/api/${endpoint}?${params.toString()}`,
+          {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(createData)
+          }
+        )
+        
+        if (!response.ok) {
+          throw new Error(`Failed to create ${entity}: ${response.statusText}`)
+        }
+        
+        return response.json()
+      }
+    },
+    {
+      onSuccess: () => {
+        if (id) {
+          refetch()
+        }
+      }
+    }
+  )
+  
+  // Delete mutation
+  const deleteMutation = useMutation(
+    async () => {
+      if (!id) throw new Error('Cannot delete: no ID provided')
+      
+      const params = new URLSearchParams()
+      params.append('action', deleteAction)
+      params.append('entity', entity)
+      params.append('id', id)
+      
+      const response = await apiFetch(
+        `/api/${endpoint}?${params.toString()}`,
+        {
+          method: 'DELETE'
+        }
+      )
+      
+      if (!response.ok) {
+        throw new Error(`Failed to delete ${entity}: ${response.statusText}`)
+      }
+      
+      return response.json()
+    }
+  )
+  
+  return {
+    record,
+    schema,
+    fieldPermissions,
+    loading,
+    error,
+    refetch,
+    save: saveMutation.mutate,
+    delete: deleteMutation.mutate,
+    saving: saveMutation.loading,
+    deleting: deleteMutation.loading
+  }
+}