spine-framework 0.1.0

package/.framework/src/hooks/useSchemaRecord.ts

@@ -0,0 +1,223 @@
+/**
+ * @module src/hooks/useSchemaRecord
+ * @audience installer
+ * @layer frontend-hook
+ * @stability stable
+ *
+ * Schema-record data management hooks. Two complementary hooks:
+ *
+ * - **`useSchemaRecord`** — given an already-fetched record and its schema
+ *   type, returns structured `FieldDefinition[]`, a managed `data` state
+ *   seeded from `record.data` with schema defaults, and field setters.
+ *   Used on detail/edit pages where the record is fetched by a parent hook.
+ *
+ * - **`useTypeSelection`** — fetches all types of a given `kind` and exposes
+ *   a `selectedTypeId` state. Used on create pages for the type-first flow
+ *   where the user picks a type before filling in fields.
+ *
+ * **Data seeding invariant:** `useSchemaRecord` re-seeds `data` state only
+ * when `record.id` or `schemaType.id` changes, not on every render. This
+ * prevents losing unsaved edits during re-renders.
+ *
+ * @seeAlso src/hooks/useEntityRecord.ts (fetches the record passed here)
+ * @seeAlso src/hooks/useForm.ts (consumes FieldDefinition[] from this hook)
+ * @seeAlso src/types/types.ts (FieldDefinition, ItemType)
+ */
+
+import { useState, useEffect, useCallback } from 'react'
+import { apiFetch } from '../lib/api'
+import { FieldDefinition, ItemType } from '../types/types'
+
+// ─── TYPES ───────────────────────────────────────────────────────────────────
+
+/**
+ * A record from the `types` table as loaded for schema resolution.
+ * @prop design_schema - Full design schema including fields and views
+ */
+export interface SchemaType {
+  id: string
+  name: string
+  slug: string
+  kind?: string
+  icon?: string
+  color?: string
+  app_id?: string
+  design_schema: ItemType['design_schema']
+}
+
+/**
+ * A generic record that may carry its resolved type in a nested `type` join.
+ * @prop data - The JSONB `data` column; all custom field values live here
+ */
+export interface SchemaRecord {
+  id: string
+  type_id?: string
+  type?: SchemaType
+  data: Record<string, any>
+  [key: string]: any
+}
+
+/** Options for `useSchemaRecord`. */
+export interface UseSchemaRecordOptions {
+  typeApiKind: string // e.g. 'account', 'person', 'item'
+}
+
+/**
+ * Return value of `useSchemaRecord`.
+ *
+ * @prop fields - Ordered `FieldDefinition[]` from schema; empty if no schema
+ * @prop data - Managed field values (seeded from `record.data` + defaults)
+ * @prop setData - Replace the entire data map
+ * @prop setField - Update a single field by name
+ * @prop schemaType - The resolved schema type (passed through)
+ * @prop loading - Always false (data is derived, not fetched here)
+ * @prop error - Always null
+ */
+export interface UseSchemaRecordResult {
+  fields: FieldDefinition[]
+  data: Record<string, any>
+  setData: (data: Record<string, any>) => void
+  setField: (name: string, value: any) => void
+  schemaType: SchemaType | null
+  loading: boolean
+  error: string | null
+}
+
+// ─── useSchemaRecord ─────────────────────────────────────────────────────────
+
+/**
+ * Given an already-fetched record and its resolved schema type, returns
+ * structured field definitions and a managed data state for the record's
+ * `.data` JSONB column, with schema defaults seeded on load.
+ *
+ * Does NOT fetch anything — this is a pure derived-state hook.
+ *
+ * @param record - Fetched record (or null while loading)
+ * @param schemaType - Resolved schema type (or null while loading)
+ * @returns `UseSchemaRecordResult`
+ *
+ * @inputSpec record.data: Record<string, any> | undefined — custom field values
+ * @inputSpec schemaType.design_schema.fields: FieldDefinition map
+ * @outputSpec fields: FieldDefinition[] — ordered array with `.name` injected
+ * @sideEffects React state mutations (data re-seed on record/type change only)
+ * @calledBy DataDetailPage.tsx, create pages
+ *
+ * @example
+ * ```tsx
+ * const { fields, data, setField } = useSchemaRecord(record, schemaType)
+ * ```
+ */
+export function useSchemaRecord(
+  record: SchemaRecord | null,
+  schemaType: SchemaType | null
+): UseSchemaRecordResult {
+  const [data, setDataState] = useState<Record<string, any>>({})
+
+  // Re-seed data state only when the record id or schema type id changes
+  const recordId = record?.id ?? null
+  const schemaTypeId = schemaType?.id ?? null
+
+  useEffect(() => {
+    if (!record) return
+
+    const base = record.data ? { ...record.data } : {}
+
+    // Seed defaults for fields that have no value
+    if (schemaType?.design_schema?.fields) {
+      for (const [name, field] of Object.entries(schemaType.design_schema.fields)) {
+        if (base[name] === undefined && (field as any).defaultValue !== undefined) {
+          base[name] = (field as any).defaultValue
+        }
+      }
+    }
+
+    setDataState(base)
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [recordId, schemaTypeId])
+
+  const setData = useCallback((newData: Record<string, any>) => {
+    setDataState(newData)
+  }, [])
+
+  const setField = useCallback((name: string, value: any) => {
+    setDataState(prev => ({ ...prev, [name]: value }))
+  }, [])
+
+  const fields: FieldDefinition[] = schemaType?.design_schema?.fields
+    ? Object.entries(schemaType.design_schema.fields).map(([name, field]) => ({ ...field, name }))
+    : []
+
+  return {
+    fields,
+    data,
+    setData,
+    setField,
+    schemaType,
+    loading: false,
+    error: null
+  }
+}
+
+// ─── useTypeSelection ─────────────────────────────────────────────────────────
+
+/**
+ * Return value of `useTypeSelection`.
+ *
+ * @prop types - All active types of the requested kind
+ * @prop selectedType - The full `SchemaType` for `selectedTypeId`, or null
+ * @prop selectedTypeId - Controlled string state for the `<select>` value
+ * @prop setSelectedTypeId - Setter for `selectedTypeId`
+ * @prop loading - True while fetching types
+ * @prop error - Error message or null
+ */
+export interface UseTypeSelectionResult {
+  types: SchemaType[]
+  selectedType: SchemaType | null
+  selectedTypeId: string
+  setSelectedTypeId: (id: string) => void
+  loading: boolean
+  error: string | null
+}
+
+/**
+ * Fetches all active types of a given `kind` and exposes a controlled
+ * `selectedTypeId` state for the type-first create flow.
+ *
+ * @param kind - Type kind: `'account'`, `'person'`, `'item'`, etc.
+ * @returns `UseTypeSelectionResult`
+ *
+ * @inputSpec kind: string — passed as `?kind=<kind>&is_active=true` to `/api/types`
+ * @outputSpec types: SchemaType[] — active types; empty while loading
+ * @sideEffects Network request via apiFetch on mount and kind change
+ * @calledBy Create pages (e.g. AccountCreatePage, ItemCreatePage)
+ */
+export function useTypeSelection(kind: string): UseTypeSelectionResult {
+  const [types, setTypes] = useState<SchemaType[]>([])
+  const [selectedTypeId, setSelectedTypeId] = useState('')
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    let cancelled = false
+    setLoading(true)
+    apiFetch(`/api/types?action=list&kind=${kind}&is_active=true`)
+      .then(r => r.json())
+      .then(result => {
+        if (!cancelled) {
+          setTypes(result.data || [])
+          setLoading(false)
+        }
+      })
+      .catch(err => {
+        if (!cancelled) {
+          setError(err.message || 'Failed to load types')
+          setLoading(false)
+        }
+      })
+    return () => { cancelled = true }
+  }, [kind])
+
+  const selectedType = types.find(t => t.id === selectedTypeId) ?? null
+
+  return { types, selectedType, selectedTypeId, setSelectedTypeId, loading, error }
+}

package/.framework/src/index.css

@@ -0,0 +1,128 @@
+@import url('https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap');
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 240 10% 3.9%;
+    --card: 0 0% 100%;
+    --card-foreground: 240 10% 3.9%;
+    --popover: 0 0% 100%;
+    --popover-foreground: 240 10% 3.9%;
+    --primary: 221.2 83.2% 53.3%;
+    --primary-foreground: 210 40% 98%;
+    --secondary: 240 4.8% 95.9%;
+    --secondary-foreground: 240 5.9% 10%;
+    --muted: 240 4.8% 95.9%;
+    --muted-foreground: 240 3.8% 46.1%;
+    --accent: 240 4.8% 95.9%;
+    --accent-foreground: 240 5.9% 10%;
+    --destructive: 0 84.2% 60.2%;
+    --destructive-foreground: 0 0% 98%;
+    --border: 240 5.9% 90%;
+    --input: 240 5.9% 90%;
+    --ring: 221.2 83.2% 53.3%;
+    --radius: 0.3rem;
+    --chart-1: 221.2 83.2% 53.3%;
+    --chart-2: 212 96% 78%;
+    --chart-3: 199 98% 48%;
+    --chart-4: 245 58% 51%;
+    --chart-5: 258 60% 44%;
+    --sidebar: 0 0% 98%;
+    --sidebar-foreground: 240 5.3% 26.1%;
+    --sidebar-primary: 221.2 83.2% 53.3%;
+    --sidebar-primary-foreground: 0 0% 100%;
+    --sidebar-accent: 240 4.8% 95.9%;
+    --sidebar-accent-foreground: 240 5.9% 10%;
+    --sidebar-border: 220 13% 91%;
+    --sidebar-ring: 217.2 91.2% 59.8%;
+  }
+
+  .dark {
+    --background: 240 10% 3.9%;
+    --foreground: 0 0% 98%;
+    --card: 240 10% 3.9%;
+    --card-foreground: 0 0% 98%;
+    --popover: 240 10% 3.9%;
+    --popover-foreground: 0 0% 98%;
+    --primary: 217.2 91.2% 59.8%;
+    --primary-foreground: 222.2 47.4% 11.2%;
+    --secondary: 240 3.7% 15.9%;
+    --secondary-foreground: 0 0% 98%;
+    --muted: 240 3.7% 15.9%;
+    --muted-foreground: 240 5% 64.9%;
+    --accent: 240 3.7% 15.9%;
+    --accent-foreground: 0 0% 98%;
+    --destructive: 0 62.8% 30.6%;
+    --destructive-foreground: 0 0% 98%;
+    --border: 240 3.7% 15.9%;
+    --input: 240 3.7% 15.9%;
+    --ring: 217.2 91.2% 59.8%;
+    --chart-1: 217.2 91.2% 59.8%;
+    --chart-2: 212 96% 78%;
+    --chart-3: 199 98% 60%;
+    --chart-4: 245 58% 61%;
+    --chart-5: 258 60% 54%;
+    --sidebar: 240 5.9% 10%;
+    --sidebar-foreground: 240 4.8% 95.9%;
+    --sidebar-primary: 224.3 76.3% 48%;
+    --sidebar-primary-foreground: 0 0% 100%;
+    --sidebar-accent: 240 3.7% 15.9%;
+    --sidebar-accent-foreground: 240 4.8% 95.9%;
+    --sidebar-border: 240 3.7% 15.9%;
+    --sidebar-ring: 217.2 91.2% 59.8%;
+  }
+}
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+  html, body, #root {
+    height: 100%;
+  }
+  body {
+    @apply bg-background text-foreground;
+    font-family: 'Inter', system-ui, -apple-system, sans-serif;
+    font-feature-settings: "rlig" 1, "calt" 1;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
+}
+
+@layer utilities {
+  .text-balance {
+    text-wrap: balance;
+  }
+  .scrollbar-hide,
+  .no-scrollbar {
+    -ms-overflow-style: none;
+    scrollbar-width: none;
+  }
+  .scrollbar-hide::-webkit-scrollbar,
+  .no-scrollbar::-webkit-scrollbar {
+    display: none;
+  }
+
+  /* Tailwind v4 CSS variable shorthand — sidebar layout */
+  .w-\(--sidebar-width\) { width: var(--sidebar-width); }
+  .w-\(--sidebar-width-icon\) { width: var(--sidebar-width-icon); }
+  .max-w-\(--skeleton-width\) { max-width: var(--skeleton-width); }
+
+  /* Tailwind v4 outline-hidden */
+  .outline-hidden { outline: 2px solid transparent; outline-offset: 2px; }
+
+  /* Tailwind v4 !important suffix variants used in sidebar collapse */
+  [data-collapsible="icon"] .group-data-\[collapsible\=icon\]\:size-8\!,
+  [data-collapsible="icon"].group .group-data-\[collapsible\=icon\]\:size-8\! {
+    width: 2rem !important;
+    height: 2rem !important;
+  }
+  [data-collapsible="icon"] .group-data-\[collapsible\=icon\]\:p-2\!,
+  [data-collapsible="icon"].group .group-data-\[collapsible\=icon\]\:p-2\! {
+    padding: 0.5rem !important;
+  }
+}

package/.framework/src/lib/api.ts

@@ -0,0 +1,156 @@
+/**
+ * @module src/lib/api
+ * @audience installer
+ * @layer frontend-hook
+ * @stability stable
+ *
+ * Authenticated fetch wrapper and account context for all Spine frontend
+ * API calls. Injects the Supabase JWT and `X-Account-Id` header into every
+ * request made via `apiFetch`.
+ *
+ * **Account context** is a module-level singleton set once after login:
+ * ```ts
+ * setAccountId(ctx.account_id) // called in AuthContext after auth.context()
+ * ```
+ * All subsequent `apiFetch` calls include `X-Account-Id` automatically.
+ *
+ * INVARIANT: Call `setAccountId` before making any authenticated API requests.
+ *   If `_accountId` is null, the backend may reject scoped requests.
+ *
+ * @seeAlso src/lib/supabase.ts (supabase client used for getSession)
+ * @seeAlso src/hooks/useApi.ts (wraps apiFetch with React state management)
+ * @seeAlso src/contexts/AuthContext.tsx (calls setAccountId after login)
+ */
+
+import { supabase } from './supabase'
+
+// ─── ACCOUNT CONTEXT ─────────────────────────────────────────────────────────
+
+let _accountId: string | null = null
+
+/**
+ * Sets the module-level account ID injected into all subsequent `apiFetch`
+ * calls as `X-Account-Id`. Pass `null` to clear (e.g. on logout).
+ *
+ * @param id - UUID of the active account, or null to clear
+ * @sideEffects Mutates module-level `_accountId`
+ * @calledBy src/contexts/AuthContext.tsx (after successful login)
+ */
+export function setAccountId(id: string | null) {
+  _accountId = id
+}
+
+/**
+ * Returns the currently active account ID, or null if not set.
+ *
+ * @returns UUID string or null
+ * @sideEffects none
+ * @calledBy src/hooks/useApi.ts, any component needing the current account scope
+ */
+export function getAccountId(): string | null {
+  return _accountId
+}
+
+// ─── INTERNAL HELPERS ─────────────────────────────────────────────────────────
+
+/**
+ * Normalises any `HeadersInit` variant to a plain `Record<string, string>`
+ * so headers can be safely spread and merged.
+ * @throws never
+ */
+function normalizeHeaders(headers?: HeadersInit): Record<string, string> {
+   if (!headers) return {}
+
+   if (headers instanceof Headers) {
+     return Object.fromEntries(headers.entries())
+   }
+
+   if (Array.isArray(headers)) {
+     return Object.fromEntries(headers)
+   }
+
+   return Object.fromEntries(
+     Object.entries(headers).map(([key, value]) => [key, String(value)])
+   )
+ }
+
+// ─── AUTH HEADERS ─────────────────────────────────────────────────────────────────
+
+/**
+ * Builds the auth header map for a request: `Authorization: Bearer <jwt>`
+ * and, if set, `X-Account-Id: <accountId>`.
+ *
+ * Called internally by `apiFetch` — do not call directly unless constructing
+ * a manual `fetch` outside of `apiFetch`.
+ *
+ * @returns Plain header object; empty if no active session
+ * @throws never — missing session returns empty headers, not an error
+ * @sideEffects DB read: supabase.auth.getSession (reads localStorage)
+ * @calledBy apiFetch
+ */
+export async function getAuthHeaders(): Promise<Record<string, string>> {
+  const headers: Record<string, string> = {}
+
+  const { data: { session } } = await supabase.auth.getSession()
+  if (session?.access_token) {
+    headers['Authorization'] = `Bearer ${session.access_token}`
+  }
+
+  if (_accountId) {
+    headers['X-Account-Id'] = _accountId
+  }
+
+  return headers
+}
+
+// ─── FETCH WRAPPER ────────────────────────────────────────────────────────────────
+
+/**
+ * Authenticated fetch wrapper. Injects `Authorization` + `X-Account-Id`
+ * headers, strips invalid Bearer values (`null`/`undefined`/empty), and
+ * forwards all other options (including `signal` for AbortController).
+ *
+ * Use this for ALL Spine API calls from the frontend. Never call `fetch`
+ * directly for API routes.
+ *
+ * @param path - API path, e.g. `'/.netlify/functions/items'`
+ * @param options - Standard `RequestInit` options (method, body, signal, etc.)
+ * @returns Raw `Response` — callers must check `response.ok` / status
+ * @throws Network errors from `fetch` (e.g. `TypeError: Failed to fetch`)
+ * @inputSpec path: string — relative URL to a Netlify function
+ * @inputSpec options.signal: AbortSignal | undefined — forwarded for cancellation
+ * @outputSpec Response — with auth headers injected; not yet parsed
+ * @sideEffects Network request; reads localStorage via getAuthHeaders
+ * @calledBy src/hooks/useApi.ts, useEntityList.ts, useEntityRecord.ts
+ *
+ * @example
+ * ```ts
+ * const res = await apiFetch('/.netlify/functions/items?action=list')
+ * if (!res.ok) throw new Error(await res.text())
+ * const { data } = await res.json()
+ * ```
+ */
+export async function apiFetch(path: string, options: RequestInit = {}): Promise<Response> {
+  console.log('apiFetch called with:', { path, options, signal: options.signal })
+  const authHeaders = await getAuthHeaders()
+  const optionHeaders = normalizeHeaders(options.headers)
+  const optionAuthorization = optionHeaders.Authorization || optionHeaders.authorization
+
+  if (
+    optionAuthorization &&
+    ['Bearer null', 'Bearer undefined', 'null', 'undefined', ''].includes(optionAuthorization.trim())
+  ) {
+    delete optionHeaders.Authorization
+    delete optionHeaders.authorization
+  }
+
+  const fetchOptions = {
+    ...options,
+    headers: {
+      ...authHeaders,
+      ...optionHeaders,
+    },
+  }
+  console.log('apiFetch final options:', { fetchOptions, signal: fetchOptions.signal })
+  return fetch(path, fetchOptions)
+}

package/.framework/src/lib/supabase.ts

@@ -0,0 +1,94 @@
+/**
+ * @module src/lib/supabase
+ * @audience installer
+ * @layer frontend-hook
+ * @stability stable
+ *
+ * Browser-side Supabase client singleton and session helpers for the Spine
+ * frontend. Reads `VITE_SUPABASE_URL` and `VITE_SUPABASE_ANON_KEY` from
+ * Vite env at build time; throws immediately on missing values so
+ * misconfigured builds fail loudly rather than silently.
+ *
+ * INVARIANT: `supabase` is a module-level singleton — do not call
+ *   `createClient` again in components or hooks. Import this module instead.
+ *
+ * @seeAlso src/lib/api.ts (uses supabase.auth.getSession for apiFetch headers)
+ * @seeAlso src/contexts/AuthContext.tsx (wraps supabase.auth for React state)
+ */
+
+import { createClient } from '@supabase/supabase-js'
+
+const supabaseUrl = import.meta.env.VITE_SUPABASE_URL
+const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY
+
+if (!supabaseUrl || !supabaseAnonKey) {
+  throw new Error('Missing Supabase environment variables')
+}
+
+// ─── CLIENT SINGLETON ─────────────────────────────────────────────────────────
+
+/**
+ * Browser-side Supabase client with persistent session, auto-refresh, and
+ * URL-based session detection enabled. This is the only Supabase client
+ * instance in the frontend; all auth and RLS-scoped queries flow through it.
+ *
+ * @inputSpec VITE_SUPABASE_URL: string — valid Supabase project URL
+ * @inputSpec VITE_SUPABASE_ANON_KEY: string — anon (public) key
+ * @throws Error('Missing Supabase environment variables') at module load if
+ *   either env var is absent
+ * @sideEffects Reads localStorage for persisted session on construction
+ * @calledBy src/lib/api.ts (getAuthHeaders), src/contexts/AuthContext.tsx
+ */
+export const supabase = createClient(supabaseUrl, supabaseAnonKey, {
+  auth: {
+    persistSession: true,
+    autoRefreshToken: true,
+    detectSessionInUrl: true,
+  },
+})
+
+// ─── SESSION HELPERS ─────────────────────────────────────────────────────────
+
+/**
+ * Returns the current Supabase auth session, or `null` if unauthenticated.
+ *
+ * @returns Session object or null
+ * @throws Supabase AuthError on unexpected failure
+ * @sideEffects none (read-only)
+ * @calledBy AuthContext.tsx, login flows
+ */
+export const getCurrentSession = async () => {
+  const { data: { session }, error } = await supabase.auth.getSession()
+  if (error) throw error
+  return session
+}
+
+/**
+ * Returns the currently authenticated Supabase user, or `null` if not signed in.
+ *
+ * @returns User object or null
+ * @throws Supabase AuthError on unexpected failure
+ * @sideEffects none (read-only)
+ * @calledBy AuthContext.tsx
+ */
+export const getCurrentUser = async () => {
+  const { data: { user }, error } = await supabase.auth.getUser()
+  if (error) throw error
+  return user
+}
+
+/**
+ * Forces a session token refresh. Call this when a request returns 401 due
+ * to an expired JWT. Supabase auto-refresh normally handles this, but this
+ * function is exposed for explicit refresh flows.
+ *
+ * @returns `{ session, user }` after refresh
+ * @throws Supabase AuthError if refresh fails (e.g. refresh token expired)
+ * @sideEffects Updates localStorage session via Supabase client
+ * @calledBy AuthContext.tsx (manual token refresh)
+ */
+export const refreshSession = async () => {
+  const { data, error } = await supabase.auth.refreshSession()
+  if (error) throw error
+  return data
+}