spine-framework 0.2.1 → 1.0.0

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

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

@@ -1,128 +0,0 @@
-@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

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

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