spine-framework 0.1.0

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

@@ -0,0 +1,478 @@
+/**
+ * @module src/components/shared/FieldRenderer
+ * @audience installer
+ * @layer frontend-component
+ * @stability stable
+ *
+ * Low-level field rendering primitive. Given a `FieldDefinition` and a
+ * current value, renders the appropriate input widget (edit mode) or
+ * display element (read-only mode).
+ *
+ * **Render type resolution** (`resolveRenderType`):
+ * 1. If `displayType` is set (from the view config), it maps to a canonical
+ *    render type first — this lets a view override how a field looks without
+ *    changing the underlying `FieldDefinition`.
+ * 2. Falls back to `field.data_type`.
+ *
+ * **Supported render types:**
+ * `text`, `textarea`, `email`, `phone`, `url`, `number`, `date`,
+ * `datetime`, `select`, `multiselect`, `radio`, `checkbox`, `json`,
+ * `file`, `color`, `range`
+ *
+ * **Error display:** when `error` is set, a red helper text is shown below
+ * the field and `border-red-500` is applied where applicable.
+ *
+ * **Label + description:** rendered above / below the input respectively,
+ * with a red `*` suffix when `field.required` is true.
+ *
+ * @seeAlso src/components/shared/SchemaFields.tsx (mounts this component)
+ * @seeAlso src/types/types.ts (FieldDefinition)
+ */
+
+import React from 'react'
+import { FieldDefinition } from '../../types/types'
+
+/**
+ * Props for `FieldRenderer`.
+ *
+ * @prop field - Full field definition including data_type, options, validation
+ * @prop value - Current controlled value
+ * @prop onChange - Value change callback (omit or pass `undefined` for read-only)
+ * @prop onBlur - Optional blur callback for validation triggers
+ * @prop readonly - If true, renders a display element instead of an input
+ * @prop error - Validation error message to display below the field
+ * @prop displayType - View-config widget override (e.g. `'textarea'`, `'select'`)
+ */
+interface FieldRendererProps {
+  field: FieldDefinition
+  value: any
+  onChange?: (value: any) => void
+  onBlur?: () => void
+  readonly?: boolean
+  error?: string
+  displayType?: string // From view config — controls rendering without polluting field data contract
+}
+
+/**
+ * Resolves the canonical render type for a field.
+ *
+ * `displayType` (from view config) takes precedence over `field.data_type`
+ * so view authors can choose a different widget without changing the
+ * underlying schema.
+ *
+ * @param field - Field definition
+ * @param displayType - Optional view-config widget override
+ * @returns Canonical render type string (e.g. `'text'`, `'select'`, `'checkbox'`)
+ */
+function resolveRenderType(field: FieldDefinition, displayType?: string): string {
+  // displayType from view config overrides data_type for rendering decisions
+  if (displayType) {
+    switch (displayType) {
+      case 'textarea':
+      case 'rich_text':
+        return 'textarea'
+      case 'select':
+        return 'select'
+      case 'multiselect':
+        return 'multiselect'
+      case 'radio':
+        return 'radio'
+      case 'checkbox':
+      case 'switch':
+        return 'checkbox'
+      case 'date_picker':
+        return 'date'
+      case 'datetime_picker':
+        return 'datetime'
+      case 'color_picker':
+        return 'color'
+      case 'range_slider':
+        return 'range'
+      case 'file_upload':
+      case 'image_upload':
+        return 'file'
+    }
+  }
+  // Fall back to data_type
+  switch (field.data_type) {
+    case 'textarea':
+    case 'rich_text':
+      return 'textarea'
+    case 'email':
+      return 'email'
+    case 'phone':
+      return 'phone'
+    case 'url':
+      return 'url'
+    case 'number':
+    case 'currency':
+    case 'range':
+      return 'number'
+    case 'date':
+      return 'date'
+    case 'datetime':
+      return 'datetime'
+    case 'boolean':
+    case 'checkbox':
+      return 'checkbox'
+    case 'select':
+      return 'select'
+    case 'multiselect':
+      return 'multiselect'
+    case 'radio':
+      return 'radio'
+    case 'color':
+      return 'color'
+    case 'file':
+    case 'image':
+      return 'file'
+    case 'json':
+      return 'json'
+    default:
+      return 'text'
+  }
+}
+
+/**
+ * Renders a single schema field as an input widget or read-only display.
+ *
+ * @param props - `FieldRendererProps`
+ * @returns Label + field widget + description + error message
+ * @sideEffects none (delegates changes to `onChange`)
+ */
+export function FieldRenderer({ field, value, onChange, readonly = false, error, displayType }: FieldRendererProps) {
+  const renderType = resolveRenderType(field, displayType)
+
+  const renderField = () => {
+    switch (renderType) {
+      case 'text':
+        return readonly ? (
+          <div className={`text-slate-900 ${error ? 'border-red-500' : ''}`}>
+            {value || <span className="text-slate-400 italic">—</span>}
+          </div>
+        ) : (
+          <input
+            type="text"
+            value={value || ''}
+            onChange={(e) => onChange?.(e.target.value)}
+            className={`input ${error ? 'border-red-500' : ''}`}
+            placeholder={field.placeholder}
+          />
+        )
+
+      case 'textarea':
+        return readonly ? (
+          <div className={`text-slate-900 whitespace-pre-wrap ${error ? 'border-red-500' : ''}`}>
+            {value || <span className="text-slate-400 italic">—</span>}
+          </div>
+        ) : (
+          <textarea
+            value={value || ''}
+            onChange={(e) => onChange?.(e.target.value)}
+            className={`textarea ${error ? 'border-red-500' : ''}`}
+            placeholder={field.placeholder}
+            rows={field.rows || 3}
+          />
+        )
+
+      case 'email':
+        return readonly ? (
+          <div className={`text-slate-900 ${error ? 'border-red-500' : ''}`}>
+            {value ? <a href={`mailto:${value}`} className="text-blue-600 hover:text-blue-800">{value}</a> : <span className="text-slate-400 italic">—</span>}
+          </div>
+        ) : (
+          <input
+            type="email"
+            value={value || ''}
+            onChange={(e) => onChange?.(e.target.value)}
+            className={`input ${error ? 'border-red-500' : ''}`}
+            placeholder={field.placeholder}
+          />
+        )
+
+      case 'phone':
+        return readonly ? (
+          <div className={`text-slate-900 ${error ? 'border-red-500' : ''}`}>
+            {value || <span className="text-slate-400 italic">—</span>}
+          </div>
+        ) : (
+          <input
+            type="tel"
+            value={value || ''}
+            onChange={(e) => onChange?.(e.target.value)}
+            className={`input ${error ? 'border-red-500' : ''}`}
+            placeholder={field.placeholder}
+          />
+        )
+
+      case 'number':
+        return (
+          <input
+            type="number"
+            value={value ?? ''}
+            onChange={(e) => onChange?.(e.target.value ? Number(e.target.value) : null)}
+            readOnly={readonly}
+            className={`input ${error ? 'border-red-500' : ''}`}
+            placeholder={field.placeholder}
+            min={field.min ?? field.validation?.min}
+            max={field.max ?? field.validation?.max}
+            step={field.step ?? field.validation?.step}
+          />
+        )
+
+      case 'date':
+        return (
+          <input
+            type="date"
+            value={value ? new Date(value).toISOString().split('T')[0] : ''}
+            onChange={(e) => onChange?.(e.target.value || null)}
+            readOnly={readonly}
+            className={`input ${error ? 'border-red-500' : ''}`}
+          />
+        )
+
+      case 'datetime':
+        return (
+          <input
+            type="datetime-local"
+            value={value ? new Date(value).toISOString().slice(0, 16) : ''}
+            onChange={(e) => onChange?.(e.target.value || null)}
+            readOnly={readonly}
+            className={`input ${error ? 'border-red-500' : ''}`}
+          />
+        )
+
+      case 'select':
+        return readonly ? (
+          <div className={`text-slate-900 ${error ? 'border-red-500' : ''}`}>
+            {(() => {
+              if (!value) return <span className="text-slate-400 italic">—</span>
+              const option = field.options?.find((opt) => {
+                const optVal = typeof opt === 'string' ? opt : opt.value
+                return optVal === value
+              })
+              return typeof option === 'string' ? option : option?.label || value
+            })()}
+          </div>
+        ) : (
+          <select
+            value={value || ''}
+            onChange={(e) => onChange?.(e.target.value)}
+            className={`select ${error ? 'border-red-500' : ''}`}
+          >
+            <option value="">Select...</option>
+            {field.options?.map((option) => {
+              const optVal = typeof option === 'string' ? option : option.value
+              const optLabel = typeof option === 'string' ? option : option.label
+              return (
+                <option key={optVal} value={optVal}>
+                  {optLabel}
+                </option>
+              )
+            })}
+          </select>
+        )
+
+      case 'multiselect':
+        return (
+          <div className="space-y-2">
+            {field.options?.map((option) => {
+              const optionValue = typeof option === 'string' ? option : option.value
+              const optionLabel = typeof option === 'string' ? option : option.label
+              return (
+                <label key={optionValue} className="flex items-center">
+                  <input
+                    type="checkbox"
+                    checked={Array.isArray(value) && value.includes(optionValue)}
+                    onChange={(e) => {
+                      const currentValue = Array.isArray(value) ? value : []
+                      if (e.target.checked) {
+                        onChange?.([...currentValue, optionValue])
+                      } else {
+                        onChange?.(currentValue.filter((v: string) => v !== optionValue))
+                      }
+                    }}
+                    disabled={readonly}
+                    className="mr-2"
+                  />
+                  <span>{optionLabel}</span>
+                </label>
+              )
+            })}
+          </div>
+        )
+
+      case 'radio':
+        return (
+          <div className="space-y-2">
+            {field.options?.map((option) => {
+              const optionValue = typeof option === 'string' ? option : option.value
+              const optionLabel = typeof option === 'string' ? option : option.label
+              return (
+                <label key={optionValue} className="flex items-center">
+                  <input
+                    type="radio"
+                    name={field.name}
+                    value={optionValue}
+                    checked={value === optionValue}
+                    onChange={(e) => onChange?.(e.target.value)}
+                    disabled={readonly}
+                    className="mr-2"
+                  />
+                  <span>{optionLabel}</span>
+                </label>
+              )
+            })}
+          </div>
+        )
+
+      case 'checkbox':
+        return readonly ? (
+          <div className={`text-slate-900 ${error ? 'border-red-500' : ''}`}>
+            {Boolean(value) ? 'Yes' : 'No'}
+          </div>
+        ) : (
+          <label className="flex items-center">
+            <input
+              type="checkbox"
+              checked={Boolean(value)}
+              onChange={(e) => onChange?.(e.target.checked)}
+              className="mr-2"
+            />
+            <span>{field.label}</span>
+          </label>
+        )
+
+      case 'json':
+        return readonly ? (
+          <pre className="bg-slate-100 p-3 rounded-md text-sm overflow-x-auto">
+            {JSON.stringify(value, null, 2)}
+          </pre>
+        ) : (
+          <textarea
+            value={typeof value === 'string' ? value : JSON.stringify(value, null, 2)}
+            onChange={(e) => {
+              try {
+                onChange?.(JSON.parse(e.target.value))
+              } catch {
+                // Invalid JSON, don't update
+              }
+            }}
+            className={`textarea font-mono text-sm ${error ? 'border-red-500' : ''}`}
+            rows={field.rows || 6}
+            placeholder="Enter valid JSON"
+          />
+        )
+
+      case 'url':
+        return readonly ? (
+          <div className={`text-slate-900 ${error ? 'border-red-500' : ''}`}>
+            {value ? <a href={value} target="_blank" rel="noopener noreferrer" className="text-blue-600 hover:text-blue-800">{value}</a> : <span className="text-slate-400 italic">—</span>}
+          </div>
+        ) : (
+          <input
+            type="url"
+            value={value || ''}
+            onChange={(e) => onChange?.(e.target.value)}
+            className={`input ${error ? 'border-red-500' : ''}`}
+            placeholder={field.placeholder || 'https://example.com'}
+          />
+        )
+
+      case 'file':
+        return readonly ? (
+          value ? (
+            <div className="text-sm">
+              <a href={value} target="_blank" rel="noopener noreferrer" className="text-blue-600 hover:text-blue-800">
+                View File
+              </a>
+            </div>
+          ) : (
+            <span className="text-slate-500">No file</span>
+          )
+        ) : (
+          <input
+            type="file"
+            onChange={(e) => {
+              const file = e.target.files?.[0]
+              if (file) onChange?.(file.name)
+            }}
+            className={`input ${error ? 'border-red-500' : ''}`}
+          />
+        )
+
+      case 'color':
+        return (
+          <div className="flex items-center space-x-2">
+            <input
+              type="color"
+              value={value || '#000000'}
+              onChange={(e) => onChange?.(e.target.value)}
+              disabled={readonly}
+              className="h-10 w-20"
+            />
+            <input
+              type="text"
+              value={value || ''}
+              onChange={(e) => onChange?.(e.target.value)}
+              readOnly={readonly}
+              className={`input flex-1 ${error ? 'border-red-500' : ''}`}
+              placeholder="#000000"
+            />
+          </div>
+        )
+
+      case 'range':
+        return (
+          <div className="space-y-2">
+            <input
+              type="range"
+              value={value ?? field.min ?? field.validation?.min ?? 0}
+              onChange={(e) => onChange?.(Number(e.target.value))}
+              disabled={readonly}
+              className="w-full"
+              min={field.min ?? field.validation?.min}
+              max={field.max ?? field.validation?.max}
+              step={field.step ?? field.validation?.step}
+            />
+            <div className="text-sm text-slate-600">
+              Value: {value ?? field.min ?? 0}
+            </div>
+          </div>
+        )
+
+      default:
+        return (
+          <input
+            type="text"
+            value={value || ''}
+            onChange={(e) => onChange?.(e.target.value)}
+            readOnly={readonly}
+            className={`input ${error ? 'border-red-500' : ''}`}
+            placeholder={field.placeholder}
+          />
+        )
+    }
+  }
+
+  return (
+    <div className="space-y-1">
+      {field.label && (
+        <label className="label">
+          {field.label}
+          {field.required && <span className="text-red-500 ml-1">*</span>}
+        </label>
+      )}
+      
+      {renderField()}
+      
+      {field.description && (
+        <p className="text-xs text-slate-500">{field.description}</p>
+      )}
+      
+      {error && (
+        <p className="text-xs text-red-600">{error}</p>
+      )}
+    </div>
+  )
+}

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

@@ -0,0 +1,226 @@
+/**
+ * @module src/components/shared/SchemaFields
+ * @audience installer
+ * @layer frontend-component
+ * @stability stable
+ *
+ * Schema-driven field grid. Renders an ordered list of `FieldDefinition`
+ * entries via `FieldRenderer`, managing the name→value mapping and
+ * propagating `onChange` calls back to the parent.
+ *
+ * **Value source resolution** (per field):
+ * - `system` flag set → `data[name]` (top-level column)
+ * - `system` flag unset → `data.data?.[name] ?? data[name]` (JSONB field
+ *   with column fallback)
+ *
+ * **Layout:** two-column responsive grid by default (`twoColumn=true`);
+ * pass `twoColumn=false` for a single-column stacked layout.
+ *
+ * **Exports:**
+ * - `SchemaFields` — full editable/read-only field grid
+ * - `SchemaFieldDisplay` — read-only single-field key:value display row
+ * - `SchemaField` (unexported) — internal wrapper binding name to value
+ *
+ * @seeAlso src/components/shared/FieldRenderer.tsx
+ * @seeAlso src/types/types.ts (FieldDefinition)
+ * @seeAlso src/components/runtime/SchemaDetailForm.tsx (primary consumer)
+ */
+
+import React from 'react'
+import { FieldDefinition } from '../../types/types'
+import { FieldRenderer } from './FieldRenderer'
+
+/**
+ * Props for `SchemaFields`.
+ *
+ * @prop fields - Ordered array of field definitions to render
+ * @prop data - Record containing current field values; may be flat or
+ *   nested under a `.data` key for JSONB fields
+ * @prop onChange - `(name, value)` callback; omit for pure read-only display
+ * @prop readonly - Passes read-only mode down to every `FieldRenderer`
+ * @prop errors - Per-field validation error messages
+ * @prop twoColumn - Two-column responsive grid (default: `true`)
+ * @prop displayTypes - Widget override map keyed by field name (from view config)
+ */
+interface SchemaFieldsProps {
+  fields: FieldDefinition[]
+  data: Record<string, any>
+  onChange?: (name: string, value: any) => void
+  readonly?: boolean
+  errors?: Record<string, string>
+  /** Render fields in a two-column grid (default: true) */
+  twoColumn?: boolean
+  /** display_type per field key, sourced from view config — never from field definitions */
+  displayTypes?: Record<string, string>
+}
+
+/**
+ * Renders a full schema field grid.
+ *
+ * @param props - `SchemaFieldsProps`
+ * @returns Two-column (or single-column) field grid, or an empty-state message
+ * @sideEffects none (delegates changes to `onChange`)
+ */
+export function SchemaFields({
+  fields,
+  data,
+  onChange,
+  readonly = false,
+  errors = {},
+  twoColumn = true,
+  displayTypes = {}
+}: SchemaFieldsProps) {
+  if (!fields || fields.length === 0) {
+    return (
+      <p className="text-sm text-slate-500 italic">No schema fields defined for this type.</p>
+    )
+  }
+
+  return (
+    <div className={twoColumn ? 'grid grid-cols-1 md:grid-cols-2 gap-4' : 'space-y-4'}>
+      {fields.filter(f => !!f.name).map((field) => {
+        const name = field.name!
+        return (
+          <SchemaField
+            key={name}
+            field={field}
+            value={field.system ? data[name] : (data.data?.[name] ?? data[name])}
+            onChange={onChange}
+            readonly={readonly || field.readonly}
+            error={errors[name]}
+            displayType={displayTypes[name]}
+          />
+        )
+      })}
+    </div>
+  )
+}
+
+/** Internal props for the `SchemaField` name-binding wrapper. */
+interface SchemaFieldProps {
+  field: FieldDefinition
+  value: any
+  onChange?: (name: string, value: any) => void
+  readonly?: boolean
+  error?: string
+  displayType?: string
+}
+
+function SchemaField({ field, value, onChange, readonly, error, displayType }: SchemaFieldProps) {
+  return (
+    <FieldRenderer
+      field={field}
+      value={value}
+      onChange={readonly ? undefined : (val) => field.name && onChange?.(field.name, val)}
+      readonly={readonly}
+      error={error}
+      displayType={displayType}
+    />
+  )
+}
+
+/**
+ * Read-only display of a single schema field value as a label:value row.
+ * Useful for compact detail views outside the full form layout.
+ *
+ * @param field - Field definition (used for label and data_type formatting)
+ * @param value - Raw value to display
+ * @returns A `<div>` with label on the left and formatted value on the right
+ * @sideEffects none (pure rendering)
+ */
+export function SchemaFieldDisplay({
+  field,
+  value
+}: {
+  field: FieldDefinition
+  value: any
+}) {
+  const displayValue = formatFieldValue(field, value)
+
+  return (
+    <div className="flex justify-between items-start py-2">
+      <dt className="text-xs text-slate-500 font-medium flex-shrink-0 mr-4">
+        {field.label || field.name}:
+      </dt>
+      <dd className="text-sm text-slate-900 text-right">
+        {displayValue}
+      </dd>
+    </div>
+  )
+}
+
+/**
+ * Formats a raw field value for read-only display, applying type-specific
+ * transformations:
+ * - `boolean`/`checkbox` → `'Yes'` / `'No'`
+ * - `date` / `datetime` → locale string
+ * - `select` → resolves option label from `field.options`
+ * - `multiselect` → comma-joined option labels
+ * - `json` → `<pre>` code block
+ * - `url` → `<a>` link
+ * - Null/undefined/empty → em-dash placeholder
+ *
+ * @param field - Field definition
+ * @param value - Raw value
+ * @returns Formatted `ReactNode`
+ */
+function formatFieldValue(field: FieldDefinition, value: any): React.ReactNode {
+  if (value === null || value === undefined || value === '') {
+    return <span className="text-slate-400 italic">—</span>
+  }
+
+  switch (field.data_type) {
+    case 'boolean':
+    case 'checkbox':
+      return value ? 'Yes' : 'No'
+
+    case 'date':
+      try {
+        return new Date(value).toLocaleDateString()
+      } catch {
+        return String(value)
+      }
+
+    case 'datetime':
+      try {
+        return new Date(value).toLocaleString()
+      } catch {
+        return String(value)
+      }
+
+    case 'select': {
+      const option = field.options?.find(o => typeof o === 'object' && o.value === value)
+      return option && typeof option === 'object' ? option.label : String(value)
+    }
+
+    case 'multiselect': {
+      if (!Array.isArray(value)) return String(value)
+      return value.map(v => {
+        const option = field.options?.find(o => typeof o === 'object' && o.value === v)
+        return option && typeof option === 'object' ? option.label : v
+      }).join(', ')
+    }
+
+    case 'json':
+      return (
+        <pre className="text-xs bg-slate-50 rounded p-2 max-w-xs overflow-x-auto">
+          {JSON.stringify(value, null, 2)}
+        </pre>
+      )
+
+    case 'url':
+      return (
+        <a
+          href={value}
+          target="_blank"
+          rel="noopener noreferrer"
+          className="text-blue-600 hover:text-blue-800 underline"
+        >
+          {value}
+        </a>
+      )
+
+    default:
+      return String(value)
+  }
+}