spine-framework 0.1.0

package/.framework/src/components/app-shell/GenericDetailPage.tsx

@@ -0,0 +1,200 @@
+import { useState, useEffect } from 'react'
+import { useParams, useSearchParams, useNavigate } from 'react-router-dom'
+import { useEntityRecord } from '../../hooks/useEntityRecord'
+import { DataDetailHeader } from '../runtime/DataDetailHeader'
+import { SchemaDetailForm } from '../runtime/SchemaDetailForm'
+
+interface GenericDetailPageProps {
+  typeSlug: string
+  viewSlug?: string
+  isCreating?: boolean
+}
+
+/**
+ * Schema-driven detail page for the Generic App Shell.
+ * Reuses the same runtime components as admin (DataDetailHeader, SchemaDetailForm)
+ * but scoped to a specific type from the app's nav_items.
+ */
+export function GenericDetailPage({ typeSlug, viewSlug, isCreating: forceCreate }: GenericDetailPageProps) {
+  const { id } = useParams<{ id: string }>()
+  const navigate = useNavigate()
+  const [searchParams, setSearchParams] = useSearchParams()
+
+  const isCreating = forceCreate || !id
+  const isEditing = searchParams.get('edit') === 'true' || isCreating
+
+  const config = {
+    entity: 'items',
+    typeSlug,
+    icon: 'database',
+    displayField: 'title',
+    api: {
+      endpoint: 'admin-data',
+      getAction: 'get',
+      createAction: 'create',
+      updateAction: 'update'
+    }
+  }
+
+  const {
+    record,
+    fieldPermissions,
+    loading,
+    error,
+    refetch,
+    save,
+    delete: deleteRecord,
+    saving,
+    deleting
+  } = useEntityRecord('items', id, config)
+
+  // Extract schema and view from the record itself
+  const schema = record?.design_schema || null
+  const resolvedDetailView = viewSlug
+    ? schema?.views?.[viewSlug] || schema?.views?.default_detail
+    : schema?.views?.default_detail
+  const view = resolvedDetailView || null
+
+  // Derive display title
+  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'
+
+  // Lifted form state
+  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) {
+      navigate(-1)
+    } 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 () => {
+    try {
+      await save(formData)
+      if (isCreating) {
+        navigate(-1)
+      } else {
+        setSearchParams({})
+      }
+    } catch (err) {
+      console.error('Save failed:', err)
+    }
+  }
+
+  const handleDelete = async () => {
+    if (window.confirm('Are you sure you want to delete this record?')) {
+      try {
+        await deleteRecord()
+        navigate(-1)
+      } catch (err) {
+        console.error('Delete failed:', err)
+      }
+    }
+  }
+
+  if (loading) {
+    return (
+      <div className="p-8 text-center">
+        <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-blue-600 mx-auto"></div>
+        <p className="mt-2 text-sm text-slate-500">Loading record...</p>
+      </div>
+    )
+  }
+
+  if (error && !isCreating) {
+    return (
+      <div className="p-8 text-center">
+        <h2 className="text-lg font-medium text-red-600">Error</h2>
+        <p className="mt-2 text-sm text-slate-500">{error}</p>
+      </div>
+    )
+  }
+
+  if (!schema && !isCreating) {
+    return (
+      <div className="p-8 text-center">
+        <h2 className="text-lg font-medium text-slate-900">No schema available</h2>
+        <p className="mt-2 text-sm text-slate-500">This record does not have a design_schema.</p>
+      </div>
+    )
+  }
+
+  return (
+    <div className="space-y-6">
+      <DataDetailHeader
+        entity="items"
+        title={isCreating ? `New ${typeSlug}` : recordTitle}
+        icon="database"
+        isEditing={isEditing}
+        isCreating={isCreating}
+        saving={saving}
+        deleting={deleting}
+        onEdit={handleEdit}
+        onCancel={handleCancel}
+        onSave={handleSave}
+        onDelete={!isCreating ? handleDelete : undefined}
+      />
+
+      {schema && view && (
+        <SchemaDetailForm
+          schema={schema}
+          view={view}
+          record={record}
+          isEditing={isEditing}
+          isCreating={isCreating}
+          permissions={fieldPermissions}
+          formData={formData}
+          onFieldChange={handleFieldChange}
+        />
+      )}
+    </div>
+  )
+}

package/.framework/src/components/app-shell/GenericListPage.tsx

@@ -0,0 +1,116 @@
+import { useListSchema } from '../../hooks/useListSchema'
+import { useEntityList } from '../../hooks/useEntityList'
+import { DataHeader } from '../runtime/DataHeader'
+import { DataStats } from '../runtime/DataStats'
+import { DataFilters } from '../runtime/DataFilters'
+import { DataTable } from '../runtime/DataTable'
+
+interface GenericListPageProps {
+  typeSlug: string
+  viewSlug?: string
+  appPrefix: string
+  detailPath: string
+}
+
+/**
+ * Schema-driven list page for the Generic App Shell.
+ * Resolves the type's design_schema and renders using the specified view
+ * (or default_list if not specified).
+ */
+export function GenericListPage({ typeSlug, viewSlug, appPrefix, detailPath }: GenericListPageProps) {
+  const resolvedViewSlug = viewSlug || 'default_list'
+
+  // Resolve schema and view — uses the same hook as admin runtime
+  const { schema, view, loading: schemaLoading, error: schemaError } = useListSchema({
+    entity: 'items',
+    viewSlug: resolvedViewSlug
+  })
+
+  // Build config from resolved schema + view
+  const config = view && schema ? {
+    entity: 'items',
+    typeSlug,
+    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('items', config)
+
+  if (schemaLoading) {
+    return (
+      <div className="p-8 text-center">
+        <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-blue-600 mx-auto"></div>
+        <p className="mt-2 text-sm text-slate-500">Loading schema...</p>
+      </div>
+    )
+  }
+
+  if (schemaError || !config) {
+    return (
+      <div className="p-8 text-center">
+        <h2 className="text-lg font-medium text-red-600">Error</h2>
+        <p className="mt-2 text-sm text-slate-500">{schemaError || 'Failed to load entity configuration'}</p>
+      </div>
+    )
+  }
+
+  return (
+    <div className="space-y-6">
+      <DataHeader
+        title={schema?.fields ? Object.keys(schema.fields).length > 0 ? (view as any)?.label || typeSlug : typeSlug : typeSlug}
+        icon={config.icon}
+        description={`Manage ${typeSlug}`}
+        newButtonHref={`${appPrefix}/${detailPath}/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="items"
+        emptyMessage={`No ${typeSlug} found`}
+        emptyIcon={config.icon}
+      />
+    </div>
+  )
+}

package/.framework/src/components/app-sidebar.tsx

@@ -0,0 +1,228 @@
+import * as React from "react"
+
+import { SearchForm } from "./search-form"
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "./ui/collapsible"
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarGroup,
+  SidebarHeader,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarMenuSub,
+  SidebarMenuSubButton,
+  SidebarMenuSubItem,
+  SidebarRail,
+} from "./ui/sidebar"
+import { GalleryVerticalEndIcon, PlusIcon, MinusIcon } from "lucide-react"
+
+// This is sample data.
+const data = {
+  navMain: [
+    {
+      title: "Getting Started",
+      url: "#",
+      items: [
+        {
+          title: "Installation",
+          url: "#",
+        },
+        {
+          title: "Project Structure",
+          url: "#",
+        },
+      ],
+    },
+    {
+      title: "Build Your Application",
+      url: "#",
+      items: [
+        {
+          title: "Routing",
+          url: "#",
+        },
+        {
+          title: "Data Fetching",
+          url: "#",
+          isActive: true,
+        },
+        {
+          title: "Rendering",
+          url: "#",
+        },
+        {
+          title: "Caching",
+          url: "#",
+        },
+        {
+          title: "Styling",
+          url: "#",
+        },
+        {
+          title: "Optimizing",
+          url: "#",
+        },
+        {
+          title: "Configuring",
+          url: "#",
+        },
+        {
+          title: "Testing",
+          url: "#",
+        },
+        {
+          title: "Authentication",
+          url: "#",
+        },
+        {
+          title: "Deploying",
+          url: "#",
+        },
+        {
+          title: "Upgrading",
+          url: "#",
+        },
+        {
+          title: "Examples",
+          url: "#",
+        },
+      ],
+    },
+    {
+      title: "API Reference",
+      url: "#",
+      items: [
+        {
+          title: "Components",
+          url: "#",
+        },
+        {
+          title: "File Conventions",
+          url: "#",
+        },
+        {
+          title: "Functions",
+          url: "#",
+        },
+        {
+          title: "next.config.js Options",
+          url: "#",
+        },
+        {
+          title: "CLI",
+          url: "#",
+        },
+        {
+          title: "Edge Runtime",
+          url: "#",
+        },
+      ],
+    },
+    {
+      title: "Architecture",
+      url: "#",
+      items: [
+        {
+          title: "Accessibility",
+          url: "#",
+        },
+        {
+          title: "Fast Refresh",
+          url: "#",
+        },
+        {
+          title: "Next.js Compiler",
+          url: "#",
+        },
+        {
+          title: "Supported Browsers",
+          url: "#",
+        },
+        {
+          title: "Turbopack",
+          url: "#",
+        },
+      ],
+    },
+    {
+      title: "Community",
+      url: "#",
+      items: [
+        {
+          title: "Contribution Guide",
+          url: "#",
+        },
+      ],
+    },
+  ],
+}
+
+export function AppSidebar({ ...props }: React.ComponentProps<typeof Sidebar>) {
+  return (
+    <Sidebar {...props}>
+      <SidebarHeader>
+        <SidebarMenu>
+          <SidebarMenuItem>
+            <SidebarMenuButton size="lg" asChild>
+              <a href="#">
+                <div className="flex aspect-square size-8 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground">
+                  <GalleryVerticalEndIcon className="size-4" />
+                </div>
+                <div className="flex flex-col gap-0.5 leading-none">
+                  <span className="font-medium">Documentation</span>
+                  <span className="">v1.0.0</span>
+                </div>
+              </a>
+            </SidebarMenuButton>
+          </SidebarMenuItem>
+        </SidebarMenu>
+        <SearchForm />
+      </SidebarHeader>
+      <SidebarContent>
+        <SidebarGroup>
+          <SidebarMenu>
+            {data.navMain.map((item, index) => (
+              <Collapsible
+                key={item.title}
+                defaultOpen={index === 1}
+                className="group/collapsible"
+              >
+                <SidebarMenuItem>
+                  <CollapsibleTrigger asChild>
+                    <SidebarMenuButton>
+                      {item.title}{" "}
+                      <PlusIcon className="ml-auto group-data-[state=open]/collapsible:hidden" />
+                      <MinusIcon className="ml-auto group-data-[state=closed]/collapsible:hidden" />
+                    </SidebarMenuButton>
+                  </CollapsibleTrigger>
+                  {item.items?.length ? (
+                    <CollapsibleContent>
+                      <SidebarMenuSub>
+                        {item.items.map((item) => (
+                          <SidebarMenuSubItem key={item.title}>
+                            <SidebarMenuSubButton
+                              asChild
+                              isActive={item.isActive}
+                            >
+                              <a href={item.url}>{item.title}</a>
+                            </SidebarMenuSubButton>
+                          </SidebarMenuSubItem>
+                        ))}
+                      </SidebarMenuSub>
+                    </CollapsibleContent>
+                  ) : null}
+                </SidebarMenuItem>
+              </Collapsible>
+            ))}
+          </SidebarMenu>
+        </SidebarGroup>
+      </SidebarContent>
+      <SidebarRail />
+    </Sidebar>
+  )
+}

package/.framework/src/components/auth/ProtectedRoute.tsx

@@ -0,0 +1,88 @@
+/**
+ * @module src/components/auth/ProtectedRoute
+ * @audience installer
+ * @layer frontend-component
+ * @stability stable
+ *
+ * React Router route guard that enforces authentication and optional
+ * system-admin role checks. Wrap any `<Route>` element that requires
+ * a logged-in user.
+ *
+ * **Auth check:** If `AuthContext.user` is null (not yet logged in or
+ * session expired), redirects to `/login` using `<Navigate replace>`.
+ *
+ * **System-admin check:** When `requireSystemAdmin=true`, verifies that
+ * `user.roles` includes `'system_admin'`. On failure it renders an
+ * access-denied screen rather than redirecting, to avoid redirect loops.
+ *
+ * @example
+ * ```tsx
+ * <Route path="/admin" element={
+ *   <ProtectedRoute requireSystemAdmin>
+ *     <AdminLayout />
+ *   </ProtectedRoute>
+ * } />
+ * ```
+ *
+ * @seeAlso src/contexts/AuthContext.tsx
+ */
+
+import React from 'react'
+import { Navigate } from 'react-router-dom'
+import { useAuth } from '../../contexts/AuthContext'
+
+/**
+ * Props for `ProtectedRoute`.
+ *
+ * @prop children - The protected route content
+ * @prop requireSystemAdmin - If true, also requires the `system_admin` role
+ */
+interface ProtectedRouteProps {
+  children: React.ReactNode
+  requireSystemAdmin?: boolean
+}
+
+/**
+ * Route guard component.
+ *
+ * @param props - `ProtectedRouteProps`
+ * @returns `children` when authorised, a redirect to `/login` when
+ *   unauthenticated, or an access-denied screen when role check fails
+ * @sideEffects none (navigation is declarative via `<Navigate>`)
+ */
+export function ProtectedRoute({ children, requireSystemAdmin = false }: ProtectedRouteProps) {
+  const { user } = useAuth()
+
+  if (!user) {
+    return <Navigate to="/login" replace />
+  }
+
+  if (requireSystemAdmin && !user.roles?.includes('system_admin')) {
+    // Show access denied message instead of redirect to avoid loops
+    return (
+      <div className="min-h-screen flex items-center justify-center bg-slate-50">
+        <div className="text-center p-8">
+          <div className="w-16 h-16 bg-red-100 rounded-full flex items-center justify-center mx-auto mb-4">
+            <svg className="w-8 h-8 text-red-600" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L3.732 16.5c-.77.833.192 2.5 1.732 2.5z" />
+            </svg>
+          </div>
+          <h1 className="text-2xl font-bold text-slate-900 mb-2">Access Denied</h1>
+          <p className="text-slate-600 mb-6">You need system administrator privileges to access this page.</p>
+          <div className="bg-slate-100 rounded-lg p-4 text-left">
+            <p className="text-sm text-slate-600 mb-2"><strong>Your roles:</strong> {user.roles?.join(', ') || 'None'}</p>
+            <p className="text-sm text-slate-600"><strong>Required:</strong> system_admin</p>
+          </div>
+          <button
+            onClick={() => window.location.href = '/dashboard'}
+            className="mt-6 px-4 py-2 bg-navy text-white rounded-lg hover:bg-navy/90 transition-colors"
+          >
+            Go to Dashboard
+          </button>
+        </div>
+      </div>
+    )
+  }
+
+  return <>{children}</>
+}