spine-framework 0.1.0

package/.framework/src/hooks/useForm.ts

@@ -0,0 +1,307 @@
+/**
+ * @module src/hooks/useForm
+ * @audience installer
+ * @layer frontend-hook
+ * @stability stable
+ *
+ * Schema-aware form state hook. Manages field values, touched state,
+ * per-field validation (required, email, url, number range, text
+ * length/pattern), and form submission with async support.
+ *
+ * Designed to work directly with `FieldDefinition[]` arrays produced
+ * by `useSchemaRecord` or static field arrays in admin forms.
+ *
+ * **Validation order per field:**
+ * 1. Required check
+ * 2. Type-specific rule (email regex, URL parse, number range, text length/pattern)
+ * 3. Custom `validate` function (whole-form)
+ *
+ * @seeAlso src/types/types.ts (FieldDefinition — field schema shape)
+ * @seeAlso src/hooks/useSchemaRecord.ts (produces FieldDefinition[] for this hook)
+ * @seeAlso src/components/shared/SchemaFields.tsx (renders fields from FieldDefinition[])
+ */
+
+import { useState, useCallback, useEffect } from 'react'
+import { FieldDefinition, FormState, ValidationError } from '../types/types'
+
+// ─── TYPES ───────────────────────────────────────────────────────────────────
+
+interface UseFormOptions {
+  initialValues: Record<string, any>
+  fields: FieldDefinition[]
+  onSubmit?: (values: Record<string, any>) => void | Promise<void>
+  validate?: (values: Record<string, any>) => Record<string, string>
+  onChange?: (values: Record<string, any>) => void
+}
+
+/**
+ * Return value of `useForm`.
+ *
+ * @prop data - Current field values keyed by field name
+ * @prop errors - Per-field error messages (empty string = cleared, absent = untouched)
+ * @prop touched - Fields the user has interacted with
+ * @prop isSubmitting - True while `onSubmit` promise is pending
+ * @prop isValid - True when `errors` is empty
+ * @prop isDirty - True when any touched field differs from `initialValues`
+ * @prop handleChange - Update a field value (clears error, marks touched)
+ * @prop handleBlur - Mark a field touched and run field-level validation
+ * @prop handleSubmit - Validate all fields, then call `onSubmit` if valid
+ * @prop resetForm - Restore all state to `initialValues`
+ * @prop setFieldValue - Programmatic field update (same as handleChange)
+ * @prop setFieldError - Inject a server-side error for a field
+ * @prop clearErrors - Clear all errors (e.g. after navigation)
+ */
+interface UseFormReturn {
+  data: Record<string, any>
+  errors: Record<string, string>
+  touched: Record<string, boolean>
+  isSubmitting: boolean
+  isValid: boolean
+  isDirty: boolean
+  handleChange: (field: string, value: any) => void
+  handleBlur: (field: string) => void
+  handleSubmit: (e?: React.FormEvent) => void
+  resetForm: () => void
+  setFieldValue: (field: string, value: any) => void
+  setFieldError: (field: string, error: string) => void
+  clearErrors: () => void
+}
+
+// ─── HOOK ────────────────────────────────────────────────────────────────────
+
+/**
+ * Schema-driven form state and validation hook.
+ *
+ * @param options.initialValues - Seed values for all fields
+ * @param options.fields - `FieldDefinition[]` from schema or static config
+ * @param options.onSubmit - Async submit handler; called only if validation passes
+ * @param options.validate - Optional whole-form custom validator returning
+ *   `Record<fieldName, errorMessage>`
+ * @param options.onChange - Called on every field change with the full values map
+ *
+ * @returns `UseFormReturn` — see interface for full description
+ *
+ * @inputSpec fields[].data_type: 'email'|'url'|'number'|'text'|'textarea'
+ *   drives built-in validation rules
+ * @inputSpec fields[].validation.minLength/maxLength/pattern: text constraints
+ * @sideEffects React state mutations only
+ * @calledBy SchemaDetailForm.tsx, all admin detail pages
+ *
+ * @example
+ * ```tsx
+ * const form = useForm({
+ *   initialValues: { name: '', email: '' },
+ *   fields: [{ name: 'email', data_type: 'email', required: true, label: 'Email' }],
+ *   onSubmit: async (values) => await save(values)
+ * })
+ * ```
+ */
+export function useForm({
+  initialValues,
+  fields,
+  onSubmit,
+  validate,
+  onChange
+}: UseFormOptions): UseFormReturn {
+  const [data, setData] = useState<Record<string, any>>(initialValues)
+  const [errors, setErrors] = useState<Record<string, string>>({})
+  const [touched, setTouched] = useState<Record<string, boolean>>({})
+  const [isSubmitting, setIsSubmitting] = useState(false)
+  const [submitCount, setSubmitCount] = useState(0)
+
+  // Validate a single field
+  const validateField = useCallback((field: string, value: any): string | null => {
+    const fieldDef = fields.find(f => f.name === field)
+    if (!fieldDef) return null
+
+    // Required validation
+    if (fieldDef.required && (!value || value === '')) {
+      return `${fieldDef.label || field} is required`
+    }
+
+    // Skip validation for empty optional fields
+    if (!fieldDef.required && (!value || value === '')) {
+      return null
+    }
+
+    // Type-specific validation
+    switch (fieldDef.data_type) {
+      case 'email':
+        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+        if (!emailRegex.test(value)) {
+          return 'Please enter a valid email address'
+        }
+        break
+
+      case 'url':
+        try {
+          new URL(value)
+        } catch {
+          return 'Please enter a valid URL'
+        }
+        break
+
+      case 'number':
+        const num = Number(value)
+        if (isNaN(num)) {
+          return 'Please enter a valid number'
+        }
+        if (fieldDef.min !== undefined && num < fieldDef.min) {
+          return `Value must be at least ${fieldDef.min}`
+        }
+        if (fieldDef.max !== undefined && num > fieldDef.max) {
+          return `Value must be at most ${fieldDef.max}`
+        }
+        break
+
+      case 'text':
+      case 'textarea':
+        if (fieldDef.validation?.minLength && value.length < fieldDef.validation.minLength) {
+          return `Must be at least ${fieldDef.validation.minLength} characters`
+        }
+        if (fieldDef.validation?.maxLength && value.length > fieldDef.validation.maxLength) {
+          return `Must be at most ${fieldDef.validation.maxLength} characters`
+        }
+        if (fieldDef.validation?.pattern && !new RegExp(fieldDef.validation.pattern).test(value)) {
+          return 'Invalid format'
+        }
+        break
+    }
+
+    return null
+  }, [fields])
+
+  // Validate all fields
+  const validateForm = useCallback((values: Record<string, any>): Record<string, string> => {
+    const newErrors: Record<string, string> = {}
+
+    // Run field-level validation
+    fields.forEach(field => {
+      if (!field.name) return
+      const fieldErr = validateField(field.name, values[field.name])
+      if (fieldErr) {
+        newErrors[field.name] = fieldErr
+      }
+    })
+
+    // Run custom validation
+    if (validate) {
+      const customErrors = validate(values)
+      Object.assign(newErrors, customErrors)
+    }
+
+    return newErrors
+  }, [fields, validate, validateField])
+
+  // Handle field change
+  const handleChange = useCallback((field: string, value: any) => {
+    const newData = { ...data, [field]: value }
+    setData(newData)
+    
+    // Clear error for this field when user starts typing
+    if (errors[field]) {
+      setErrors(prev => {
+        const newErrors = { ...prev }
+        delete newErrors[field]
+        return newErrors
+      })
+    }
+
+    // Mark field as touched
+    setTouched(prev => ({ ...prev, [field]: true }))
+
+    // Call onChange callback
+    onChange?.(newData)
+  }, [data, errors, onChange])
+
+  // Handle field blur
+  const handleBlur = useCallback((field: string) => {
+    setTouched(prev => ({ ...prev, [field]: true }))
+    
+    // Validate field on blur
+    const error = validateField(field, data[field])
+    setErrors(prev => ({
+      ...prev,
+      ...(error ? { [field]: error } : { [field]: '' })
+    }))
+  }, [data, validateField])
+
+  // Handle form submission
+  const handleSubmit = useCallback(async (e?: React.FormEvent) => {
+    e?.preventDefault()
+    
+    // Mark all fields as touched
+    const allTouched = fields.reduce((acc, field) => {
+      if (field.name) acc[field.name] = true
+      return acc
+    }, {} as Record<string, boolean>)
+    setTouched(allTouched)
+
+    // Validate form
+    const newErrors = validateForm(data)
+    setErrors(newErrors)
+
+    const isValid = Object.keys(newErrors).length === 0
+    if (!isValid) {
+      return
+    }
+
+    setIsSubmitting(true)
+    setSubmitCount(prev => prev + 1)
+
+    try {
+      await onSubmit?.(data)
+    } catch (error) {
+      console.error('Form submission error:', error)
+    } finally {
+      setIsSubmitting(false)
+    }
+  }, [data, fields, validateForm, onSubmit])
+
+  // Reset form
+  const resetForm = useCallback(() => {
+    setData(initialValues)
+    setErrors({})
+    setTouched({})
+    setIsSubmitting(false)
+    setSubmitCount(0)
+  }, [initialValues])
+
+  // Set field value
+  const setFieldValue = useCallback((field: string, value: any) => {
+    handleChange(field, value)
+  }, [handleChange])
+
+  // Set field error
+  const setFieldError = useCallback((field: string, error: string) => {
+    setErrors(prev => ({
+      ...prev,
+      [field]: error
+    }))
+  }, [])
+
+  // Clear all errors
+  const clearErrors = useCallback(() => {
+    setErrors({})
+  }, [])
+
+  // Calculate derived state
+  const isValid = Object.keys(errors).length === 0
+  const isDirty = Object.keys(touched).some(field => data[field] !== initialValues[field])
+
+  return {
+    data,
+    errors,
+    touched,
+    isSubmitting,
+    isValid,
+    isDirty,
+    handleChange,
+    handleBlur,
+    handleSubmit,
+    resetForm,
+    setFieldValue,
+    setFieldError,
+    clearErrors
+  }
+}

package/.framework/src/hooks/useListSchema.ts

@@ -0,0 +1,264 @@
+/**
+ * @module src/hooks/useListSchema
+ * @audience installer
+ * @layer frontend-hook
+ * @stability stable
+ *
+ * Resolves the `DesignSchema` and target `View` for a list page. Because
+ * the `design_schema` is stamp-copied onto records, this hook uses a
+ * two-stage resolution strategy to handle stale or missing stamps:
+ *
+ * **Resolution order:**
+ * 1. Fetch one sample record via `admin-data?action=list&limit=1`
+ * 2. If the sample record's `design_schema` has the requested view, use it
+ * 3. Otherwise, fall back to the canonical `types` table entry for the entity kind
+ * 4. If no records exist, return a minimal fallback schema so the page renders
+ *
+ * **Auth retry:** Auth errors (JWT not ready) trigger a 300 ms retry instead
+ * of silently falling back to an empty schema (which would render a blank list).
+ *
+ * **Entity → kind mapping** (used for the types fallback):
+ * `accounts→account`, `people→person`, `items→item`, `threads→thread`,
+ * `messages→message`, `links→link`, `attachments→attachment`, `watchers→watcher`
+ *
+ * @seeAlso src/lib/api.ts (apiFetch)
+ * @seeAlso src/types/types.ts (DesignSchema, View)
+ * @seeAlso src/components/runtime/DataListPage.tsx (primary consumer)
+ * @seeAlso functions/admin-data.ts (list action endpoint)
+ */
+
+import { useState, useEffect } from 'react'
+import { apiFetch } from '../lib/api'
+import { DesignSchema, View } from '../types/types'
+
+// ─── TYPES ───────────────────────────────────────────────────────────────────
+
+/**
+ * Options for `useListSchema`.
+ *
+ * @prop entity - Entity table name (e.g. `'accounts'`, `'items'`)
+ * @prop viewSlug - View key in `design_schema.views`; defaults to `'default_list'`
+ */
+interface UseListSchemaOptions {
+  entity: string
+  viewSlug?: string
+}
+
+/**
+ * Return value of `useListSchema`.
+ *
+ * @prop schema - Resolved `DesignSchema` or null while loading
+ * @prop view - The specific `View` for `viewSlug`, or null while loading
+ * @prop loading - True during initial fetch and auth retry
+ * @prop error - Error message if schema resolution fails
+ * @prop refetch - Manually re-run schema resolution
+ */
+interface UseListSchemaResult {
+  schema: DesignSchema | null
+  view: View | null
+  loading: boolean
+  error: string | null
+  refetch: () => void
+}
+
+// ─── HOOK ────────────────────────────────────────────────────────────────────
+
+/**
+ * Resolves the `DesignSchema` and target `View` for a list page, using a
+ * two-stage fallback strategy (stamped record → canonical type → minimal fallback).
+ *
+ * @param options.entity - Entity name, e.g. `'accounts'`
+ * @param options.viewSlug - View key; defaults to `'default_list'`
+ * @returns `UseListSchemaResult` — schema, view, loading, error, refetch
+ *
+ * @inputSpec options.entity: string — must be non-empty or an error is set
+ * @outputSpec schema: DesignSchema — minimal fallback if no records exist
+ * @outputSpec view: View — matches `viewSlug` from the resolved schema
+ * @throws never (all errors are caught and stored in `error` state)
+ * @sideEffects Network requests (1–2 calls); React state mutations; 300ms setTimeout on auth retry
+ * @calledBy DataListPage.tsx
+ *
+ * @example
+ * ```tsx
+ * const { schema, view, loading } = useListSchema({ entity: 'accounts' })
+ * ```
+ */
+export function useListSchema(options: UseListSchemaOptions): UseListSchemaResult {
+  const { entity, viewSlug = 'default_list' } = options
+  
+  const [schema, setSchema] = useState<DesignSchema | null>(null)
+  const [view, setView] = useState<View | null>(null)
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  const fetchSchema = async () => {
+    let cancelled = false
+    
+    try {
+      setLoading(true)
+      setError(null)
+
+      // Fetch a sample record to get its design_schema
+      const response = await apiFetch(`/api/admin-data?action=list&entity=${entity}&limit=1`)
+      
+      if (!response.ok) {
+        throw new Error(`Failed to fetch sample record: ${response.statusText}`)
+      }
+
+      const data = await response.json()
+      
+      if (data.error) {
+        // Auth errors (session not yet ready) should not silently fall back to
+        // an empty schema — that causes the list to render with no columns.
+        // Retry once after a short delay to allow the session to hydrate.
+        if (
+          data.error.includes('Invalid authentication') ||
+          data.error.includes('Unauthorized') ||
+          data.error.includes('JWT')
+        ) {
+          if (cancelled) return
+          await new Promise(resolve => setTimeout(resolve, 300))
+          if (!cancelled) fetchSchema()
+          return
+        }
+        throw new Error(data.error || 'Failed to fetch records')
+      }
+
+      // No records yet — use a minimal fallback schema so the list page still renders
+      if (!data.data || data.data.length === 0) {
+        if (cancelled) return
+        const fallback: DesignSchema = {
+          fields: {},
+          record_permissions: {},
+          views: {
+            [viewSlug]: {
+              type: 'list',
+              label: 'Default List',
+              fields: {
+                id: { sortable: false, display_type: 'text' },
+                created_at: { sortable: true, display_type: 'timestamp' }
+              },
+              display: 'table',
+              default_sort: { field: 'created_at', direction: 'desc' }
+            }
+          }
+        }
+        setSchema(fallback)
+        setView(fallback.views![viewSlug]!)
+        setLoading(false)
+        return
+      }
+
+      const sampleRecord = data.data[0]
+      
+      // If the sample record has a design_schema with the requested view, use it directly
+      const stampedSchema = sampleRecord.design_schema as DesignSchema | undefined
+      const stampedView = stampedSchema?.views?.[viewSlug]
+
+      if (stampedSchema && stampedView) {
+        if (cancelled) return
+        setSchema(stampedSchema)
+        setView(stampedView)
+      } else {
+        // Schema missing or stale — fetch current design_schema from the types table
+        const kindMap: Record<string, string> = { accounts: 'account', people: 'person', items: 'item', threads: 'thread', messages: 'message', links: 'link', attachments: 'attachment', watchers: 'watcher', item_progress: 'progress' }
+        const kind = kindMap[entity]
+        let resolvedSchema: DesignSchema | null = null
+
+        if (kind) {
+          const typeResp = await apiFetch(`/api/types?kind=${kind}&limit=1`)
+          if (typeResp.ok) {
+            const typeData = await typeResp.json()
+            const typeRecord = typeData.data?.[0]
+            if (typeRecord?.design_schema) {
+              resolvedSchema = typeRecord.design_schema as DesignSchema
+            }
+          }
+        }
+
+        if (resolvedSchema) {
+          const resolvedView = resolvedSchema.views?.[viewSlug]
+          if (resolvedView) {
+            if (cancelled) return
+            setSchema(resolvedSchema)
+            setView(resolvedView)
+          } else {
+            // Schema found but view key missing — use minimal fallback
+            const fallback: DesignSchema = {
+              fields: {},
+              record_permissions: {},
+              views: {
+                [viewSlug]: {
+                  type: 'list',
+                  label: entity.charAt(0).toUpperCase() + entity.slice(1),
+                  fields: {
+                    id: { sortable: false, display_type: 'text' },
+                    created_at: { sortable: true, display_type: 'timestamp' }
+                  },
+                  display: 'table',
+                  default_sort: { field: 'created_at', direction: 'desc' }
+                }
+              }
+            }
+            if (cancelled) return
+            setSchema(fallback)
+            setView(fallback.views![viewSlug]!)
+          }
+        } else {
+          // No type found in registry — use minimal fallback
+          const fallback: DesignSchema = {
+            fields: {},
+            record_permissions: {},
+            views: {
+              [viewSlug]: {
+                type: 'list',
+                label: entity.charAt(0).toUpperCase() + entity.slice(1),
+                fields: {
+                  id: { sortable: false, display_type: 'text' },
+                  created_at: { sortable: true, display_type: 'timestamp' }
+                },
+                display: 'table',
+                default_sort: { field: 'created_at', direction: 'desc' }
+              }
+            }
+          }
+          if (cancelled) return
+          setSchema(fallback)
+          setView(fallback.views![viewSlug]!)
+        }
+      }
+
+    } catch (err) {
+      if (!cancelled) {
+        setError(err instanceof Error ? err.message : 'Failed to load schema')
+        setSchema(null)
+        setView(null)
+      }
+    } finally {
+      if (!cancelled) {
+        setLoading(false)
+      }
+    }
+
+    return () => {
+      cancelled = true
+    }
+  }
+
+  useEffect(() => {
+    if (entity) {
+      fetchSchema()
+    } else {
+      setError('Entity is required')
+      setLoading(false)
+    }
+  }, [entity, viewSlug])
+
+  return {
+    schema,
+    view,
+    loading,
+    error,
+    refetch: fetchSchema
+  }
+}