spine-framework 0.1.0

package/.framework/src/components/runtime/DataDetailPage.tsx

@@ -0,0 +1,171 @@
+import { useState, useEffect } from 'react'
+import { useParams, useSearchParams } from 'react-router-dom'
+import { useEntityRecord } from '../../hooks/useEntityRecord'
+import { DataDetailHeader } from './DataDetailHeader'
+import { SchemaDetailForm } from './SchemaDetailForm'
+import { Button } from '../ui/button'
+import { Card, CardContent } from '../ui/card'
+import { Skeleton } from '../ui/skeleton'
+
+export function DataDetailPage() {
+  const { entity, id, typeSlug } = useParams<{ entity: string; id: string; typeSlug?: string }>()
+  const [searchParams, setSearchParams] = useSearchParams()
+  
+  const isCreating = !id
+  const isEditing = searchParams.get('edit') === 'true' || isCreating
+  
+  const config = {
+    entity: entity || '',
+    typeSlug: typeSlug || undefined,
+    icon: 'database',
+    displayField: 'display_name',
+    api: {
+      endpoint: 'admin-data',
+      getAction: 'get',
+      createAction: 'create',
+      updateAction: 'update'
+    }
+  }
+  
+  const { 
+    record, 
+    fieldPermissions,
+    loading, 
+    error, 
+    refetch,
+    save,
+    delete: deleteRecord,
+    saving,
+    deleting
+  } = useEntityRecord(entity!, id, config)
+  
+  const schema = record?.design_schema || null
+  const view = schema?.views?.default_detail || null
+
+  const displayField = schema?.display_field || config.displayField
+  const FALLBACK_FIELDS = ['full_name', 'display_name', 'name', 'title', 'slug', 'email']
+  const recordTitle = record?.[displayField]
+    ?? FALLBACK_FIELDS.map(f => record?.[f]).find(v => v != null)
+    ?? 'Untitled'
+
+  const [formData, setFormData] = useState<Record<string, any>>({})
+
+  useEffect(() => {
+    if (record && view) {
+      const initialData: Record<string, any> = {}
+      view.sections?.forEach((section: any) => {
+        const fieldNames = Array.isArray(section.fields) ? section.fields : Object.keys(section.fields || {})
+        fieldNames.forEach((fieldName: string) => {
+          const fieldDef = schema?.fields?.[fieldName]
+          if (fieldDef?.system) {
+            initialData[fieldName] = record[fieldName]
+          } else {
+            initialData[fieldName] = record.data?.[fieldName]
+          }
+        })
+      })
+      setFormData(initialData)
+    } else if (isCreating) {
+      setFormData({})
+    }
+  }, [record, isCreating, view, schema])
+  
+  const handleFieldChange = (key: string, value: any) => {
+    setFormData((prev) => ({ ...prev, [key]: value }))
+  }
+  
+  const handleEdit = () => {
+    setSearchParams({ edit: 'true' })
+  }
+  
+  const handleCancel = () => {
+    if (isCreating) {
+      window.location.href = `/spine-framework/admin/runtime/${entity}`
+    } else {
+      setSearchParams({})
+      if (record && view) {
+        const initialData: Record<string, any> = {}
+        view.sections?.forEach((section: any) => {
+          const fieldNames = Array.isArray(section.fields) ? section.fields : Object.keys(section.fields || {})
+          fieldNames.forEach((fieldName: string) => {
+            const fieldDef = schema?.fields?.[fieldName]
+            if (fieldDef?.system) {
+              initialData[fieldName] = record[fieldName]
+            } else {
+              initialData[fieldName] = record.data?.[fieldName]
+            }
+          })
+        })
+        setFormData(initialData)
+      }
+    }
+  }
+  
+  const handleSave = async () => {
+    await save(formData)
+    if (!isCreating) {
+      setSearchParams({})
+    } else {
+      window.location.href = `/spine-framework/admin/runtime/${entity}`
+    }
+  }
+  
+  const handleDelete = async () => {
+    if (confirm(`Are you sure you want to delete this ${config?.entity?.slice(0, -1) || 'record'}?`)) {
+      await deleteRecord()
+      window.location.href = `/spine-framework/admin/runtime/${entity}`
+    }
+  }
+  
+  if (loading) {
+    return (
+      <Card>
+        <CardContent className="p-8 space-y-4">
+          <Skeleton className="h-8 w-48" />
+          <Skeleton className="h-32 w-full" />
+          <Skeleton className="h-32 w-full" />
+        </CardContent>
+      </Card>
+    )
+  }
+  
+  if (error || !schema || !view) {
+    return (
+      <Card>
+        <CardContent className="p-8 text-center">
+          <p className="text-destructive">Error: {error || 'Failed to load record or schema'}</p>
+          <Button onClick={refetch} variant="outline" className="mt-4">Retry</Button>
+        </CardContent>
+      </Card>
+    )
+  }
+  
+  return (
+    <div className="space-y-6">
+      <DataDetailHeader
+        entity={config.entity}
+        icon={config.icon}
+        title={isCreating ? `New ${config.entity.slice(0, -1)}` : recordTitle}
+        isEditing={isEditing}
+        isCreating={isCreating}
+        onEdit={handleEdit}
+        onSave={handleSave}
+        onCancel={handleCancel}
+        onDelete={!isCreating ? handleDelete : undefined}
+        saving={saving}
+        deleting={deleting}
+      />
+      
+      <SchemaDetailForm
+        schema={schema}
+        view={view}
+        record={record}
+        isEditing={isEditing}
+        isCreating={isCreating}
+        permissions={fieldPermissions}
+        formData={formData}
+        onFieldChange={handleFieldChange}
+      />
+    </div>
+  )
+}

package/.framework/src/components/runtime/DataFilters.tsx

@@ -0,0 +1,91 @@
+import { EntityFilter } from '../../types/types'
+import { Card, CardContent } from '../ui/card'
+import { Input } from '../ui/input'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../ui/select'
+import { Button } from '../ui/button'
+import { Label } from '../ui/label'
+
+interface DataFiltersProps {
+  filters: EntityFilter[]
+  values: Record<string, any>
+  onChange: (values: Record<string, any>) => void
+  onClear: () => void
+}
+
+export function DataFilters({ filters, values, onChange, onClear }: DataFiltersProps) {
+  const handleFilterChange = (key: string, value: any) => {
+    onChange({ ...values, [key]: value })
+  }
+  
+  const hasActiveFilters = Object.values(values).some(v => v !== undefined && v !== '' && v !== 'all')
+  
+  return (
+    <Card>
+      <CardContent className="p-4">
+        <div className="flex flex-col sm:flex-row gap-4">
+          {filters.map((filter) => (
+            <div key={filter.key} className="sm:w-48">
+              <Label className="text-xs font-medium text-muted-foreground mb-2 block">
+                {filter.label}
+              </Label>
+              
+              {filter.type === 'search' && (
+                <Input
+                  type="text"
+                  value={values[filter.key] || ''}
+                  onChange={(e) => handleFilterChange(filter.key, e.target.value)}
+                  placeholder={`Search ${filter.label.toLowerCase()}...`}
+                />
+              )}
+              
+              {filter.type === 'enum' && (
+                <Select 
+                  value={values[filter.key] || 'all'} 
+                  onValueChange={(value) => handleFilterChange(filter.key, value === 'all' ? undefined : value)}
+                >
+                  <SelectTrigger>
+                    <SelectValue placeholder={`All ${filter.label}`} />
+                  </SelectTrigger>
+                  <SelectContent>
+                    <SelectItem value="all">All {filter.label}</SelectItem>
+                    {filter.options?.map((option) => (
+                      <SelectItem key={option} value={option}>
+                        {option.charAt(0).toUpperCase() + option.slice(1)}
+                      </SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
+              )}
+              
+              {filter.type === 'boolean' && (
+                <Select 
+                  value={values[filter.key]?.toString() || 'all'}
+                  onValueChange={(value) => {
+                    handleFilterChange(filter.key, value === 'all' ? undefined : value === 'true')
+                  }}
+                >
+                  <SelectTrigger>
+                    <SelectValue placeholder="All" />
+                  </SelectTrigger>
+                  <SelectContent>
+                    <SelectItem value="all">All</SelectItem>
+                    <SelectItem value="true">Yes</SelectItem>
+                    <SelectItem value="false">No</SelectItem>
+                  </SelectContent>
+                </Select>
+              )}
+            </div>
+          ))}
+          
+          {hasActiveFilters && (
+            <div className="flex items-end">
+              <Button variant="ghost" size="sm" onClick={onClear}>
+                Clear filters
+              </Button>
+            </div>
+          )}
+        </div>
+      </CardContent>
+    </Card>
+  )
+}

package/.framework/src/components/runtime/DataHeader.tsx

@@ -0,0 +1,68 @@
+/**
+ * @module src/components/runtime/DataHeader
+ * @audience installer
+ * @layer frontend-component
+ * @stability stable
+ *
+ * Title bar for entity list pages. Renders an entity icon, title,
+ * description, and a "New" button that navigates to the create route.
+ * The icon name is resolved dynamically from `@heroicons/react`; falls
+ * back to `CubeIcon` if the name is unrecognised.
+ *
+ * @seeAlso src/components/runtime/DataListPage.tsx (mounts this component)
+ */
+
+import React from 'react'
+import { Button } from '../ui/button'
+import * as Icons from 'lucide-react'
+
+/**
+ * Props for `DataHeader`.
+ *
+ * @prop title - Entity name (displayed capitalised)
+ * @prop icon - Heroicon name string (e.g. `'UserIcon'`)
+ * @prop description - Short subtitle text
+ * @prop newButtonHref - URL to navigate to when "New" is clicked
+ */
+interface DataHeaderProps {
+  title: string
+  icon: string
+  description: string
+  newButtonHref: string
+}
+
+/**
+ * Entity list page header with title, description, and new-record button.
+ *
+ * @param props - `DataHeaderProps`
+ * @returns Header bar JSX
+ * @sideEffects Navigates via `window.location.href` on button click
+ */
+export function DataHeader({ title, icon, description, newButtonHref }: DataHeaderProps) {
+  // Dynamically get the icon component
+  const IconComponent = (Icons as Record<string, React.ComponentType<{ className?: string }>>)[icon] || Icons.Box
+  
+  return (
+    <div className="flex justify-between items-center">
+      <div className="flex items-center gap-3">
+        <div className="flex h-10 w-10 items-center justify-center rounded-lg bg-primary/10">
+          <IconComponent className="h-6 w-6 text-primary" />
+        </div>
+        <div>
+          <h1 className="text-xl font-semibold text-foreground capitalize">
+            {title}
+          </h1>
+          <p className="mt-0.5 text-sm text-muted-foreground">{description}</p>
+        </div>
+      </div>
+      
+      <Button 
+        onClick={() => window.location.href = newButtonHref}
+        className="flex items-center gap-2"
+      >
+        <Icons.Plus className="h-4 w-4" />
+        New {title.slice(0, -1)}
+      </Button>
+    </div>
+  )
+}

package/.framework/src/components/runtime/DataListPage.tsx

@@ -0,0 +1,124 @@
+import { useParams } from 'react-router-dom'
+import { useListSchema } from '../../hooks/useListSchema'
+import { useEntityList } from '../../hooks/useEntityList'
+import { DataHeader } from './DataHeader'
+import { DataStats } from './DataStats'
+import { DataFilters } from './DataFilters'
+import { DataTable } from './DataTable'
+import { Card, CardContent } from '../ui/card'
+import { Skeleton } from '../ui/skeleton'
+
+export function DataListPage() {
+  const { entity, typeSlug } = useParams<{ entity: string; typeSlug?: string }>()
+  
+  const { schema, view, loading: schemaLoading, error: schemaError } = useListSchema({
+    entity: entity || '',
+    viewSlug: 'default_list'
+  })
+  
+  const config = view && schema ? {
+    entity: entity || '',
+    typeSlug: typeSlug || undefined,
+    icon: 'database',
+    api: {
+      endpoint: 'admin-data',
+      listAction: 'list'
+    },
+    list: {
+      defaultSort: (view as any).default_sort || { field: 'created_at', direction: 'desc' },
+      stats: (view as any).stats || [],
+      filters: (view as any).filters || [],
+      columns: Object.entries((view as any).fields || {}).map(([key, fieldConfig]: [string, any]) => ({
+        key,
+        label: schema.fields[key]?.label || key,
+        sortable: fieldConfig.sortable !== false,
+        display_type: fieldConfig.display_type
+      }))
+    }
+  } : null
+  
+  const { 
+    data, 
+    loading, 
+    error, 
+    refetch,
+    filters, 
+    setFilters, 
+    sort, 
+    setSort
+  } = useEntityList(entity!, config)
+  
+  if (schemaLoading) {
+    return (
+      <div className="space-y-6">
+        <Card>
+          <CardContent className="p-6">
+            <Skeleton className="h-8 w-48" />
+            <Skeleton className="h-4 w-96 mt-2" />
+          </CardContent>
+        </Card>
+        <div className="grid grid-cols-1 gap-5 sm:grid-cols-2 lg:grid-cols-4">
+          <Skeleton className="h-24" />
+          <Skeleton className="h-24" />
+          <Skeleton className="h-24" />
+          <Skeleton className="h-24" />
+        </div>
+        <Card>
+          <CardContent className="p-8 space-y-4">
+            <Skeleton className="h-8 w-full" />
+            <Skeleton className="h-8 w-full" />
+            <Skeleton className="h-8 w-3/4" />
+          </CardContent>
+        </Card>
+      </div>
+    )
+  }
+  
+  if (schemaError || !config) {
+    return (
+      <Card>
+        <CardContent className="p-8 text-center">
+          <p className="text-lg font-medium text-destructive">Error</p>
+          <p className="mt-2 text-sm text-muted-foreground">{schemaError || 'Failed to load entity configuration'}</p>
+        </CardContent>
+      </Card>
+    )
+  }
+  
+  return (
+    <div className="space-y-6">
+      <DataHeader 
+        title={config.entity.charAt(0).toUpperCase() + config.entity.slice(1)}
+        icon={config.icon}
+        description={`Manage ${config.entity}`}
+        newButtonHref={`/spine-framework/admin/runtime/${entity}/new`}
+      />
+      
+      <DataStats 
+        stats={config.list.stats} 
+        data={data}
+        loading={loading}
+      />
+      
+      <DataFilters 
+        filters={config.list.filters}
+        values={filters}
+        onChange={setFilters}
+        onClear={() => setFilters({})}
+      />
+      
+      <DataTable 
+        columns={config.list.columns}
+        data={data}
+        loading={loading}
+        error={error}
+        onRetry={refetch}
+        sort={sort}
+        onSort={setSort}
+        entity={entity!}
+        emptyMessage={`No ${config.entity} found`}
+        emptyIcon={config.icon}
+      />
+    </div>
+  )
+}

package/.framework/src/components/runtime/DataStats.tsx

@@ -0,0 +1,70 @@
+import { EntityStat } from '../../types/types'
+import { Card, CardContent } from '../ui/card'
+import * as Icons from 'lucide-react'
+
+interface DataStatsProps {
+  stats: EntityStat[]
+  data: any[]
+  loading?: boolean
+}
+
+const colorMap: Record<string, string> = {
+  blue: 'bg-blue-500/10 text-blue-500',
+  green: 'bg-green-500/10 text-green-500',
+  red: 'bg-red-500/10 text-red-500',
+  orange: 'bg-orange-500/10 text-orange-500',
+  purple: 'bg-purple-500/10 text-purple-500',
+  gray: 'bg-muted text-muted-foreground'
+}
+
+export function DataStats({ stats, data, loading }: DataStatsProps) {
+  const calculateStat = (stat: EntityStat): number => {
+    if (!data) return 0
+    
+    switch (stat.type) {
+      case 'count':
+        return data.length
+      case 'filter_count':
+        return data.filter(item => {
+          if (!stat.filter) return true
+          return Object.entries(stat.filter).every(([key, value]) => {
+            const itemValue = key.includes('.') 
+              ? key.split('.').reduce((obj, k) => obj?.[k], item)
+              : item[key]
+            return itemValue === value
+          })
+        }).length
+      default:
+        return 0
+    }
+  }
+  
+  return (
+    <div className="grid grid-cols-1 gap-5 sm:grid-cols-2 lg:grid-cols-4">
+      {stats.map((stat, index) => {
+        const IconComponent = (Icons as Record<string, React.ComponentType<{ className?: string }>>)[stat.icon] || Icons.Box
+        const value = loading ? '-' : calculateStat(stat)
+        
+        return (
+          <Card key={index}>
+            <CardContent className="p-5">
+              <div className="flex items-center">
+                <div className={`flex-shrink-0 rounded-md p-3 ${colorMap[stat.color] || colorMap.gray}`}>
+                  <IconComponent className="h-6 w-6" />
+                </div>
+                <div className="ml-5 w-0 flex-1">
+                  <p className="text-sm font-medium text-muted-foreground truncate">
+                    {stat.title}
+                  </p>
+                  <p className="text-2xl font-semibold text-foreground">
+                    {typeof value === 'number' ? value.toLocaleString() : value}
+                  </p>
+                </div>
+              </div>
+            </CardContent>
+          </Card>
+        )
+      })}
+    </div>
+  )
+}

package/.framework/src/components/runtime/DataTable.tsx

@@ -0,0 +1,174 @@
+import React from 'react'
+import { useNavigate } from 'react-router-dom'
+import { EntityColumn } from '../../types/types'
+import { formatDateTime } from '../../lib/utils'
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '../ui/table'
+import { Card, CardContent } from '../ui/card'
+import { Button } from '../ui/button'
+import { Skeleton } from '../ui/skeleton'
+import { Badge } from '../ui/badge'
+import * as Icons from 'lucide-react'
+
+interface DataTableProps {
+  columns: EntityColumn[]
+  data: any[]
+  loading?: boolean
+  error?: string | null
+  onRetry?: () => void
+  sort: { field: string; direction: 'asc' | 'desc' }
+  onSort: (sort: { field: string; direction: 'asc' | 'desc' }) => void
+  entity: string
+  emptyMessage: string
+  emptyIcon: string
+}
+
+export function DataTable({ 
+  columns, 
+  data, 
+  loading, 
+  error, 
+  onRetry,
+  sort,
+  onSort,
+  entity,
+  emptyMessage,
+  emptyIcon 
+}: DataTableProps) {
+  const navigate = useNavigate()
+  const EmptyIconComponent = (Icons as Record<string, React.ComponentType<{ className?: string }>>)[emptyIcon] || Icons.Box
+  
+  const handleSort = (key: string) => {
+    if (sort.field === key) {
+      onSort({ 
+        field: key, 
+        direction: sort.direction === 'asc' ? 'desc' : 'asc' 
+      })
+    } else {
+      onSort({ field: key, direction: 'asc' })
+    }
+  }
+  
+  const getSortIcon = (key: string) => {
+    if (sort.field !== key) {
+      return <Icons.ArrowUpDown className="h-4 w-4 text-muted-foreground" />
+    }
+    return sort.direction === 'asc' 
+      ? <Icons.ArrowUp className="h-4 w-4 text-primary" />
+      : <Icons.ArrowDown className="h-4 w-4 text-primary" />
+  }
+  
+  const renderCell = (column: EntityColumn, row: any) => {
+    const value = column.key.includes('.')
+      ? column.key.split('.').reduce((obj, k) => obj?.[k], row)
+      : row[column.key]
+    
+    if (column.type === 'timestamp' && value) {
+      return formatDateTime(value)
+    }
+    
+    if (column.type === 'badge' && column.badgeColors) {
+      const colorClass = column.badgeColors[value?.toString()] || 'bg-muted text-muted-foreground'
+      return (
+        <Badge variant="secondary" className={colorClass}>
+          {value?.toString() || 'Unknown'}
+        </Badge>
+      )
+    }
+    
+    if (column.maxLength && typeof value === 'string' && value.length > column.maxLength) {
+      return value.substring(0, column.maxLength) + '...'
+    }
+    
+    return value?.toString() || '-'
+  }
+  
+  const handleRowClick = (row: any) => {
+    navigate(`/spine-framework/admin/runtime/${entity}/${row.id}`)
+  }
+  
+  if (loading) {
+    return (
+      <Card>
+        <CardContent className="p-8 space-y-4">
+          <Skeleton className="h-8 w-full" />
+          <Skeleton className="h-8 w-full" />
+          <Skeleton className="h-8 w-3/4" />
+        </CardContent>
+      </Card>
+    )
+  }
+  
+  if (error) {
+    return (
+      <Card>
+        <CardContent className="p-8 text-center">
+          <p className="text-destructive">Error: {error}</p>
+          {onRetry && (
+            <Button onClick={onRetry} variant="outline" className="mt-4">
+              Retry
+            </Button>
+          )}
+        </CardContent>
+      </Card>
+    )
+  }
+  
+  if (!data || data.length === 0) {
+    return (
+      <Card>
+        <CardContent className="p-8 text-center">
+          <EmptyIconComponent className="mx-auto h-12 w-12 text-muted-foreground" />
+          <h3 className="mt-2 text-sm font-medium text-foreground">{emptyMessage}</h3>
+          <p className="mt-1 text-sm text-muted-foreground">
+            Try adjusting your filters or create a new record
+          </p>
+        </CardContent>
+      </Card>
+    )
+  }
+  
+  return (
+    <Card>
+      <Table>
+        <TableHeader>
+          <TableRow>
+            {columns.map((column) => (
+              <TableHead 
+                key={column.key}
+                className={column.sortable ? 'cursor-pointer' : ''}
+                onClick={() => column.sortable && handleSort(column.key)}
+              >
+                <div className="flex items-center gap-1">
+                  {column.label}
+                  {column.sortable && getSortIcon(column.key)}
+                </div>
+              </TableHead>
+            ))}
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {data.map((row) => (
+            <TableRow
+              key={row.id}
+              className="cursor-pointer"
+              onClick={() => handleRowClick(row)}
+            >
+              {columns.map((column) => (
+                <TableCell key={column.key}>
+                  {renderCell(column, row)}
+                </TableCell>
+              ))}
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </Card>
+  )
+}