spine-framework 0.1.0

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

@@ -0,0 +1,134 @@
+/**
+ * @module src/components/runtime/SchemaDetailForm
+ * @audience installer
+ * @layer frontend-component
+ * @stability stable
+ *
+ * Renders a `DetailView`'s sections as a schema-driven form. Each
+ * `DetailViewSection` becomes a white card containing a `SchemaFields`
+ * grid. Field definitions come from `DesignSchema.fields`; display widget
+ * overrides come from the view's per-field `ViewFieldConfig.display_type`.
+ *
+ * **Field source resolution:**
+ * - Field schema (`data_type`, `required`, `validation`, etc.) →
+ *   `schema.fields[fieldName]`
+ * - Display widget override → `view.sections[n].fields[fieldName].display_type`
+ * - `system` fields read from `record[fieldName]`; custom fields read
+ *   from `record.data[fieldName]` (split handled upstream by `DataDetailPage`)
+ *
+ * **Read vs edit rendering:** passes `readonly={!isEditing}` to `SchemaFields`
+ * so all field components switch between display and input mode.
+ *
+ * @seeAlso src/components/shared/SchemaFields.tsx
+ * @seeAlso src/types/types.ts (DesignSchema, DetailView)
+ * @seeAlso src/components/runtime/DataDetailPage.tsx (parent, owns form state)
+ */
+
+import { DesignSchema, DetailView, DetailViewSection, FieldDefinition } from '../../types/types'
+import { SchemaFields } from '../shared/SchemaFields'
+
+/**
+ * Props for `SchemaDetailForm`.
+ *
+ * @prop schema - Full `DesignSchema` for field definitions and permissions
+ * @prop view - The `default_detail` `DetailView` from the schema
+ * @prop record - Raw fetched record (used in read-only mode)
+ * @prop isEditing - If true, renders input fields; false = read-only display
+ * @prop isCreating - If true, skips reading from `record` (no record yet)
+ * @prop permissions - Per-field `{ read, write }` map from `useEntityRecord`
+ * @prop formData - Controlled values for all fields (owned by `DataDetailPage`)
+ * @prop onFieldChange - Callback to update a single field value
+ */
+interface SchemaDetailFormProps {
+  schema: DesignSchema
+  view: DetailView
+  record: any
+  isEditing: boolean
+  isCreating: boolean
+  permissions: Record<string, { read: boolean; write: boolean }>
+  formData: Record<string, any>
+  onFieldChange: (key: string, value: any) => void
+}
+
+/**
+ * Renders a schema-defined `DetailView` as a sectioned form.
+ *
+ * @param props - `SchemaDetailFormProps`
+ * @returns One card per `DetailViewSection`, or an empty-state message
+ * @sideEffects none (pure rendering)
+ */
+export function SchemaDetailForm({
+  schema,
+  view,
+  record,
+  isEditing,
+  isCreating,
+  permissions,
+  formData,
+  onFieldChange
+}: SchemaDetailFormProps) {
+  
+  const renderSection = (section: DetailViewSection, sectionIndex: number) => {
+    const fieldNames = Array.isArray(section.fields) ? section.fields : Object.keys(section.fields || {})
+    const sectionFields = fieldNames.map((fieldName: string) => {
+      const fieldDef = schema.fields[fieldName]
+      if (!fieldDef) return null
+
+      return {
+        name: fieldName,
+        label: fieldDef.label,
+        data_type: fieldDef.data_type,
+        required: fieldDef.required,
+        validation: fieldDef.validation,
+        options: fieldDef.options,
+        permissions: fieldDef.permissions,
+        system: fieldDef.system
+      } as FieldDefinition
+    }).filter((field): field is NonNullable<typeof field> => field !== null)
+
+    // Build display_type map from view config — keeps field definitions clean
+    const displayTypes: Record<string, string> = {}
+    if (!Array.isArray(section.fields)) {
+      Object.entries(section.fields || {}).forEach(([fieldName, viewConfig]: [string, any]) => {
+        if (viewConfig.display_type) {
+          displayTypes[fieldName] = viewConfig.display_type
+        }
+      })
+    }
+
+    if (sectionFields.length === 0) return null
+
+    return (
+      <div key={sectionIndex} className="bg-white shadow rounded-lg p-6">
+        <h3 className="text-lg font-medium text-slate-900 mb-4">
+          {section.title}
+        </h3>
+        
+        <SchemaFields
+          fields={sectionFields}
+          data={isCreating || isEditing ? formData : (record || {})}
+          readonly={!isEditing}
+          twoColumn={false}
+          onChange={onFieldChange}
+          displayTypes={displayTypes}
+        />
+      </div>
+    )
+  }
+
+  if (!view.sections || view.sections.length === 0) {
+    return (
+      <div className="bg-white shadow rounded-lg p-6">
+        <div className="text-center py-8">
+          <p className="text-slate-500">No fields configured for this view</p>
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="space-y-6">
+      {view.sections.map((section, index) => renderSection(section, index))}
+    </div>
+  )
+}

package/.framework/src/components/runtime/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @module src/components/runtime
+ * @audience installer
+ * @layer frontend-component
+ * @stability stable
+ *
+ * Barrel export for all schema-driven runtime page components.
+ * Import from this module to get type-safe access to all runtime UI primitives.
+ */
+
+export { DataListPage } from './DataListPage'
+export { DataDetailPage } from './DataDetailPage'
+export { DataHeader } from './DataHeader'
+export { DataStats } from './DataStats'
+export { DataFilters } from './DataFilters'
+export { DataTable } from './DataTable'
+export { DataDetailHeader } from './DataDetailHeader'
+export { SchemaDetailForm } from './SchemaDetailForm'

package/.framework/src/components/search-form.tsx

@@ -0,0 +1,29 @@
+"use client"
+
+import { Label } from "./ui/label"
+import {
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarInput,
+} from "./ui/sidebar"
+import { SearchIcon } from "lucide-react"
+
+export function SearchForm({ ...props }: React.ComponentProps<"form">) {
+  return (
+    <form {...props}>
+      <SidebarGroup className="py-0">
+        <SidebarGroupContent className="relative">
+          <Label htmlFor="search" className="sr-only">
+            Search
+          </Label>
+          <SidebarInput
+            id="search"
+            placeholder="Search the docs..."
+            className="pl-8"
+          />
+          <SearchIcon className="pointer-events-none absolute top-1/2 left-2 size-4 -translate-y-1/2 opacity-50 select-none" />
+        </SidebarGroupContent>
+      </SidebarGroup>
+    </form>
+  )
+}

package/.framework/src/components/shared/AgentView.tsx

@@ -0,0 +1,213 @@
+/**
+ * @component AgentView
+ * @audience installer
+ * @layer component
+ * @stability stable
+ *
+ * Agent View toggle component for exposing raw API data and code examples.
+ * Provides agents (and developers) with:
+ * - Raw JSON of current record/page data
+ * - Copy-pasteable API calls (curl/fetch)
+ * - Equivalent CLI commands
+ *
+ * **Usage:**
+ * ```tsx
+ * <AgentView
+ *   data={recordData}
+ *   endpoint="/.netlify/functions/items"
+ *   method="GET"
+ *   query={{ id: recordId }}
+ * />
+ * ```
+ *
+ * **Features:**
+ * - Collapsible panel (closed by default)
+ * - Copy to clipboard buttons
+ * - Syntax highlighting for JSON
+ * - Responsive layout
+ *
+ * @seeAlso hooks/useApi.ts (API call logging)
+ * @seeAlso pages/admin/* (admin pages using this component)
+ */
+
+import React, { useState, useEffect } from 'react'
+import { Code, Terminal, Copy, Check, ChevronDown, ChevronUp } from 'lucide-react'
+
+interface AgentViewProps {
+  /** The raw data object to display */
+  data: any
+  /** API endpoint path */
+  endpoint: string
+  /** HTTP method */
+  method?: 'GET' | 'POST' | 'PATCH' | 'DELETE'
+  /** Query parameters used */
+  query?: Record<string, any>
+  /** Request body (for POST/PATCH) */
+  body?: any
+  /** Optional title override */
+  title?: string
+}
+
+export function AgentView({
+  data,
+  endpoint,
+  method = 'GET',
+  query,
+  body,
+  title = 'Agent View'
+}: AgentViewProps) {
+  const [isOpen, setIsOpen] = useState(false)
+  const [copied, setCopied] = useState<string | null>(null)
+
+  // Build API URL
+  const baseUrl = window.location.origin
+  const fullUrl = `${baseUrl}${endpoint}${query ? '?' + new URLSearchParams(query).toString() : ''}`
+
+  // Generate curl command
+  const curlCmd = `curl -X ${method} \\
+  ${method !== 'GET' ? `-H "Content-Type: application/json" \\
+  ` : ''}${baseUrl}${endpoint}${query ? '?' + new URLSearchParams(query).toString() : ''}${method !== 'GET' && body ? ` \\
+  -d '${JSON.stringify(body, null, 2)}'` : ''}`
+
+  // Generate fetch code
+  const fetchCode = `fetch('${baseUrl}${endpoint}${query ? '?' + new URLSearchParams(query).toString() : ''}', {
+  method: '${method}',${method !== 'GET' ? `
+  headers: { 'Content-Type': 'application/json' },` : ''}${method !== 'GET' && body ? `
+  body: JSON.stringify(${JSON.stringify(body, null, 2).replace(/\n/g, '\n  ')})` : ''}
+})
+  .then(r => r.json())
+  .then(data => console.log(data))`
+
+  // Generate CLI command
+  const cliCmd = `spine ${endpoint.replace('/.netlify/functions/', '').replace(/\//g, ' ')} ${query?.id || query?.slug || ''}${method === 'POST' && body ? ` --data '${JSON.stringify(body)}'` : ''}${method === 'PATCH' && body ? ` --update '${JSON.stringify(body)}'` : ''}${method === 'DELETE' ? ' --delete' : ''}`
+
+  const handleCopy = (text: string, key: string) => {
+    navigator.clipboard.writeText(text)
+    setCopied(key)
+    setTimeout(() => setCopied(null), 2000)
+  }
+
+  return (
+    <div className="mt-6 border border-gray-200 rounded-lg bg-gray-50">
+      {/* Header */}
+      <button
+        onClick={() => setIsOpen(!isOpen)}
+        className="w-full flex items-center justify-between px-4 py-3 text-left hover:bg-gray-100 transition-colors"
+      >
+        <div className="flex items-center gap-2">
+          <Terminal className="w-4 h-4 text-gray-600" />
+          <span className="font-medium text-gray-700">{title}</span>
+          <span className="text-xs text-gray-500">(for agents & developers)</span>
+        </div>
+        {isOpen ? (
+          <ChevronUp className="w-4 h-4 text-gray-500" />
+        ) : (
+          <ChevronDown className="w-4 h-4 text-gray-500" />
+        )}
+      </button>
+
+      {/* Content */}
+      {isOpen && (
+        <div className="border-t border-gray-200">
+          {/* API Info */}
+          <div className="px-4 py-3 bg-blue-50 border-b border-blue-100">
+            <div className="flex items-center gap-2 text-sm text-blue-800">
+              <span className="font-mono font-bold">{method}</span>
+              <span className="font-mono">{endpoint}</span>
+              {query && (
+                <span className="text-blue-600">
+                  with query: {JSON.stringify(query)}
+                </span>
+              )}
+            </div>
+          </div>
+
+          <div className="p-4 space-y-4">
+            {/* Raw JSON */}
+            <div>
+              <div className="flex items-center justify-between mb-2">
+                <div className="flex items-center gap-2 text-sm font-medium text-gray-700">
+                  <Code className="w-4 h-4" />
+                  Response JSON
+                </div>
+                <button
+                  onClick={() => handleCopy(JSON.stringify(data, null, 2), 'json')}
+                  className="flex items-center gap-1 text-xs text-gray-500 hover:text-gray-700"
+                >
+                  {copied === 'json' ? (
+                    <Check className="w-3 h-3" />
+                  ) : (
+                    <Copy className="w-3 h-3" />
+                  )}
+                  {copied === 'json' ? 'Copied!' : 'Copy'}
+                </button>
+              </div>
+              <pre className="bg-gray-900 text-gray-100 p-3 rounded text-xs overflow-auto max-h-64 font-mono">
+                {JSON.stringify(data, null, 2)}
+              </pre>
+            </div>
+
+            {/* Code Examples */}
+            <div className="grid grid-cols-1 lg:grid-cols-2 gap-4">
+              {/* cURL */}
+              <div>
+                <div className="flex items-center justify-between mb-2">
+                  <div className="text-sm font-medium text-gray-700">cURL</div>
+                  <button
+                    onClick={() => handleCopy(curlCmd, 'curl')}
+                    className="flex items-center gap-1 text-xs text-gray-500 hover:text-gray-700"
+                  >
+                    {copied === 'curl' ? <Check className="w-3 h-3" /> : <Copy className="w-3 h-3" />}
+                    {copied === 'curl' ? 'Copied!' : 'Copy'}
+                  </button>
+                </div>
+                <pre className="bg-gray-800 text-gray-100 p-3 rounded text-xs overflow-auto max-h-32 font-mono">
+                  {curlCmd}
+                </pre>
+              </div>
+
+              {/* Fetch */}
+              <div>
+                <div className="flex items-center justify-between mb-2">
+                  <div className="text-sm font-medium text-gray-700">JavaScript Fetch</div>
+                  <button
+                    onClick={() => handleCopy(fetchCode, 'fetch')}
+                    className="flex items-center gap-1 text-xs text-gray-500 hover:text-gray-700"
+                  >
+                    {copied === 'fetch' ? <Check className="w-3 h-3" /> : <Copy className="w-3 h-3" />}
+                    {copied === 'fetch' ? 'Copied!' : 'Copy'}
+                  </button>
+                </div>
+                <pre className="bg-gray-800 text-gray-100 p-3 rounded text-xs overflow-auto max-h-32 font-mono">
+                  {fetchCode}
+                </pre>
+              </div>
+            </div>
+
+            {/* CLI Command */}
+            <div>
+              <div className="flex items-center justify-between mb-2">
+                <div className="flex items-center gap-2 text-sm font-medium text-gray-700">
+                  <Terminal className="w-4 h-4" />
+                  Spine CLI
+                </div>
+                <button
+                  onClick={() => handleCopy(cliCmd, 'cli')}
+                  className="flex items-center gap-1 text-xs text-gray-500 hover:text-gray-700"
+                >
+                  {copied === 'cli' ? <Check className="w-3 h-3" /> : <Copy className="w-3 h-3" />}
+                  {copied === 'cli' ? 'Copied!' : 'Copy'}
+                </button>
+              </div>
+              <pre className="bg-green-900 text-green-100 p-3 rounded text-xs overflow-auto font-mono">
+                {cliCmd}
+              </pre>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default AgentView