spine-framework 0.1.61 → 1.0.0

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

@@ -1,190 +0,0 @@
-/**
- * @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

@@ -1,308 +0,0 @@
-/**
- * @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
-  }
-}