spine-framework 0.2.1 → 1.0.0

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

@@ -1,307 +0,0 @@
-/**
- * @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

@@ -1,264 +0,0 @@
-/**
- * @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
-  }
-}