spine-framework 0.1.0

package/.framework/src/lib/utils.ts

@@ -0,0 +1,317 @@
+/**
+ * @module src/lib/utils
+ * @audience installer
+ * @layer frontend-hook
+ * @stability stable
+ *
+ * General-purpose frontend utility functions. Pure helpers only — no React,
+ * no Supabase, no side effects. Safe to use in any component or hook.
+ *
+ * **Exports:** `cn`, `formatDate`, `formatTime`, `formatDateTime`,
+ * `formatRelativeTime`, `formatFileSize`, `formatCurrency`, `formatNumber`,
+ * `truncateText`, `generateSlug`, `capitalize`, `debounce`, `throttle`,
+ * `isValidUrl`, `getFileExtension`, `generateId`, `deepClone`
+ *
+ * @seeAlso src/lib/api.ts (fetch utilities)
+ * @seeAlso functions/_shared/schema-utils.ts (server-side field formatters
+ *   for storage-layer data; parallel set to the date/currency helpers here)
+ */
+
+import { type ClassValue, clsx } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+// ─── TAILWIND HELPERS ───────────────────────────────────────────────────────────
+
+/**
+ * Merges Tailwind class strings with conflict resolution via `tailwind-merge`
+ * and conditional class support via `clsx`. The standard utility for
+ * composing class names in all Spine components.
+ *
+ * @param inputs - Any number of class values (strings, arrays, objects)
+ * @returns Merged, deduplicated class string
+ * @throws never
+ * @example
+ * ```ts
+ * cn('px-4 py-2', isActive && 'bg-blue-500', 'px-6') // → 'py-2 bg-blue-500 px-6'
+ * ```
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
+
+// ─── DATE FORMATTERS ────────────────────────────────────────────────────────────
+
+/**
+ * Formats a date as a locale date string ('Jan 15, 2024').
+ * Returns `'N/A'` for null/undefined, `'Invalid Date'` for non-parseable input.
+ * @param date - ISO string, Date object, null, or undefined
+ * @param options - Optional `Intl.DateTimeFormatOptions` overrides
+ * @throws never
+ */
+export function formatDate(date: string | Date | null | undefined, options?: Intl.DateTimeFormatOptions) {
+  if (!date) return 'N/A'
+  
+  const dateObj = typeof date === 'string' ? new Date(date) : date
+  
+  // Check if date is invalid
+  if (!dateObj || isNaN(dateObj.getTime())) return 'Invalid Date'
+  
+  return dateObj.toLocaleDateString('en-US', {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+    ...options,
+  })
+}
+
+/**
+ * Formats a date as a locale time string ('02:30 PM').
+ * Returns `'N/A'` for null/undefined, `'Invalid Date'` for bad input.
+ * @throws never
+ */
+export function formatTime(date: string | Date | null | undefined, options?: Intl.DateTimeFormatOptions) {
+  if (!date) return 'N/A'
+  
+  const dateObj = typeof date === 'string' ? new Date(date) : date
+  
+  // Check if date is invalid
+  if (!dateObj || isNaN(dateObj.getTime())) return 'Invalid Date'
+  
+  return dateObj.toLocaleTimeString('en-US', {
+    hour: '2-digit',
+    minute: '2-digit',
+    ...options,
+  })
+}
+
+/**
+ * Formats a date as a locale date+time string ('Jan 15, 2024, 02:30 PM').
+ * Returns `'N/A'` for null/undefined, `'Invalid Date'` for bad input.
+ * @throws never
+ */
+export function formatDateTime(date: string | Date | null | undefined, options?: Intl.DateTimeFormatOptions) {
+  if (!date) return 'N/A'
+  
+  const dateObj = typeof date === 'string' ? new Date(date) : date
+  
+  // Check if date is invalid
+  if (!dateObj || isNaN(dateObj.getTime())) return 'Invalid Date'
+  
+  return dateObj.toLocaleString('en-US', {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+    ...options,
+  })
+}
+
+/**
+ * Formats a date as a human-readable relative string
+ * ('just now', '5 minutes ago', '3 days ago', or falls back to `formatDate`
+ * for dates older than 7 days).
+ * Returns `'N/A'` for null/undefined, `'Invalid Date'` for bad input.
+ * @throws never
+ */
+export function formatRelativeTime(date: string | Date | null | undefined) {
+  if (!date) return 'N/A'
+  
+  const dateObj = typeof date === 'string' ? new Date(date) : date
+  
+  // Check if date is invalid
+  if (isNaN(dateObj.getTime())) return 'Invalid Date'
+  
+  const now = new Date()
+  const diffMs = now.getTime() - dateObj.getTime()
+  const diffSecs = Math.floor(diffMs / 1000)
+  const diffMins = Math.floor(diffSecs / 60)
+  const diffHours = Math.floor(diffMins / 60)
+  const diffDays = Math.floor(diffHours / 24)
+
+  if (diffSecs < 60) {
+    return 'just now'
+  } else if (diffMins < 60) {
+    return `${diffMins} minute${diffMins > 1 ? 's' : ''} ago`
+  } else if (diffHours < 24) {
+    return `${diffHours} hour${diffHours > 1 ? 's' : ''} ago`
+  } else if (diffDays < 7) {
+    return `${diffDays} day${diffDays > 1 ? 's' : ''} ago`
+  } else {
+    return formatDate(dateObj)
+  }
+}
+
+// ─── NUMBER FORMATTERS ───────────────────────────────────────────────────────────
+
+/**
+ * Formats bytes as a human-readable size string ('1.23 MB').
+ * Returns `'0 Bytes'` for 0.
+ * @param bytes - Non-negative byte count
+ * @param decimals - Decimal places (default 2)
+ * @throws never
+ */
+export function formatFileSize(bytes: number, decimals = 2) {
+  if (bytes === 0) return '0 Bytes'
+
+  const k = 1024
+  const dm = decimals < 0 ? 0 : decimals
+  const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB']
+
+  const i = Math.floor(Math.log(bytes) / Math.log(k))
+
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(dm)) + ' ' + sizes[i]
+}
+
+/**
+ * Formats a number as a locale currency string ('$1,234.56').
+ * @param amount - Numeric value
+ * @param currency - ISO 4217 code (default 'USD')
+ * @param locale - BCP 47 locale tag (default 'en-US')
+ * @throws never
+ */
+export function formatCurrency(amount: number, currency = 'USD', locale = 'en-US') {
+  return new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency,
+  }).format(amount)
+}
+
+/**
+ * Formats a number using `Intl.NumberFormat` with optional format options.
+ * @throws never
+ */
+export function formatNumber(num: number, options?: Intl.NumberFormatOptions) {
+  return new Intl.NumberFormat('en-US', options).format(num)
+}
+
+// ─── STRING UTILITIES ────────────────────────────────────────────────────────────
+
+/**
+ * Truncates text to `maxLength` characters, appending `'...'` if truncated.
+ * Returns the original string if it fits within `maxLength`.
+ * @throws never
+ */
+export function truncateText(text: string, maxLength: number) {
+  if (text.length <= maxLength) return text
+  return text.slice(0, maxLength) + '...'
+}
+
+/**
+ * Converts text to a URL-friendly slug: lowercased, diacritics stripped,
+ * spaces/underscores/hyphens collapsed to single `-`, leading/trailing
+ * hyphens removed.
+ * @throws never
+ */
+export function generateSlug(text: string) {
+  return text
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/[\s_-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+/** Capitalises the first character of a string. @throws never */
+export function capitalize(text: string) {
+  return text.charAt(0).toUpperCase() + text.slice(1)
+}
+
+// ─── TIMING UTILITIES ────────────────────────────────────────────────────────────
+
+/**
+ * Returns a debounced wrapper that delays invoking `func` until `wait` ms
+ * after the last call. Resets the timer on each call.
+ * @param func - The function to debounce
+ * @param wait - Delay in milliseconds
+ * @throws never (the wrapper itself never throws; `func` may throw)
+ * @example
+ * ```ts
+ * const search = debounce((q: string) => fetchResults(q), 300)
+ * ```
+ */
+export function debounce<T extends (...args: any[]) => any>(
+  func: T,
+  wait: number
+): (...args: Parameters<T>) => void {
+  let timeout: ReturnType<typeof setTimeout>
+  return (...args: Parameters<T>) => {
+    clearTimeout(timeout)
+    timeout = setTimeout(() => func(...args), wait)
+  }
+}
+
+/**
+ * Returns a throttled wrapper that invokes `func` at most once per `limit` ms.
+ * Subsequent calls within the window are dropped.
+ * @param func - The function to throttle
+ * @param limit - Throttle window in milliseconds
+ * @throws never
+ */
+export function throttle<T extends (...args: any[]) => any>(
+  func: T,
+  limit: number
+): (...args: Parameters<T>) => void {
+  let inThrottle: boolean
+  return (...args: Parameters<T>) => {
+    if (!inThrottle) {
+      func(...args)
+      inThrottle = true
+      setTimeout(() => (inThrottle = false), limit)
+    }
+  }
+}
+
+// ─── VALIDATION & FILE UTILITIES ────────────────────────────────────────────────────
+
+/** Returns true if `url` is a valid absolute URL (any protocol). @throws never */
+export function isValidUrl(url: string) {
+  try {
+    new URL(url)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Extracts the file extension from a filename. Returns an empty string if
+ * there is no extension. Works correctly for dotfiles (e.g. `.gitignore` → `''`).
+ * @throws never
+ */
+export function getFileExtension(filename: string) {
+  return filename.slice((filename.lastIndexOf('.') - 1 >>> 0) + 2)
+}
+
+/** Generates a random alphanumeric ID of the given length (default 8). @throws never */
+export function generateId(length = 8) {
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'
+  let result = ''
+  for (let i = 0; i < length; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length))
+  }
+  return result
+}
+
+// ─── OBJECT UTILITIES ─────────────────────────────────────────────────────────────
+
+/**
+ * Recursively deep-clones an object, array, or Date. Primitives and null
+ * are returned by value. Does not handle Maps, Sets, or class instances
+ * with custom prototypes.
+ * @throws never
+ */
+export function deepClone<T>(obj: T): T {
+  if (obj === null || typeof obj !== 'object') return obj
+  if (obj instanceof Date) return new Date(obj.getTime()) as unknown as T
+  if (obj instanceof Array) return obj.map(item => deepClone(item)) as unknown as T
+  if (typeof obj === 'object') {
+    const clonedObj = {} as T
+    for (const key in obj) {
+      if (obj.hasOwnProperty(key)) {
+        clonedObj[key] = deepClone(obj[key])
+      }
+    }
+    return clonedObj
+  }
+  return obj
+}

package/.framework/src/main.tsx

@@ -0,0 +1,27 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import { BrowserRouter } from 'react-router-dom'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import App from './App'
+import { AuthProvider } from './contexts/AuthContext'
+import './index.css'
+
+// Create a client
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      retry: 1,
+      refetchOnWindowFocus: false,
+    },
+  },
+})
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <QueryClientProvider client={queryClient}>
+    <BrowserRouter>
+      <AuthProvider>
+        <App />
+      </AuthProvider>
+    </BrowserRouter>
+  </QueryClientProvider>,
+)

package/.framework/src/pages/DashboardPage.tsx

@@ -0,0 +1,181 @@
+/**
+ * @module src/pages/DashboardPage
+ * @audience installer
+ * @layer frontend-page
+ * @stability stable
+ *
+ * Admin home page. On mount, fetches all active item types (`kind=item`)
+ * from `/api/types` and then fans out parallel requests to
+ * `/api/admin-data?action=stats&entity=items&type_slug=…` to collect
+ * per-type item counts (capped at 8 types). Renders:
+ * - **Entity overview grid** — one stat card per type + a "Configuration"
+ *   shortcut card
+ * - **Quick Actions row** — "New <Type>" buttons for the first 4 types plus
+ *   a "Configure Types" shortcut
+ *
+ * @seeAlso src/contexts/AuthContext.tsx (provides current user)
+ * @seeAlso src/lib/api.ts (apiFetch)
+ */
+
+import React, { useState, useEffect } from 'react'
+import { useAuth } from '../contexts/AuthContext'
+import { useApi } from '../hooks/useApi'
+import { apiFetch } from '../lib/api'
+import { useNavigate } from 'react-router-dom'
+import { Box, UserGroupIcon, FileText, BarChart3, Settings, Plus } from 'lucide-react';
+
+interface TypeStat {
+  name: string
+  count: number
+  slug: string
+  icon: any
+}
+
+export function DashboardPage() {
+  const { user } = useAuth()
+  const navigate = useNavigate()
+  const [stats, setStats] = useState<Array<{
+    title: string
+    value: number
+    icon: any
+    color: string
+    href: string
+  }>>([])
+  const [typeStats, setTypeStats] = useState<TypeStat[]>([])
+  const [loading, setLoading] = useState(true)
+
+  useEffect(() => {
+    const fetchStats = async () => {
+      try {
+        // Fetch active types with their counts
+        const typesResponse = await apiFetch('/api/types?kind=item&is_active=true')
+        if (typesResponse.ok) {
+          const response = await typesResponse.json()
+          const types = response.data || response // Handle both wrapped and unwrapped responses
+          
+          if (!Array.isArray(types)) {
+            console.error('Expected array of types, got:', types)
+            setTypeStats([])
+            return
+          }
+          
+          // Get counts for each type
+          const statsPromises = types.map(async (type: any) => {
+            const countResponse = await apiFetch(`/api/admin-data?action=stats&entity=items&type_slug=${type.slug}`)
+            if (countResponse.ok) {
+              const countData = await countResponse.json()
+              return {
+                name: type.name,
+                count: countData.count || 0,
+                slug: type.slug,
+                icon: CubeIcon // Default icon, could be enhanced to use type.icon
+              }
+            }
+            return null
+          })
+          
+          const resolvedStats = await Promise.all(statsPromises)
+          const validStats = resolvedStats.filter((s): s is NonNullable<typeof s> => s !== null).slice(0, 8) // Limit to 8 types
+          setTypeStats(validStats)
+        }
+      } catch (error) {
+        console.error('Failed to fetch dashboard stats:', error)
+      } finally {
+        setLoading(false)
+      }
+    }
+
+    fetchStats()
+  }, [apiFetch])
+
+  const handleCreateNewItem = (typeSlug: string) => {
+    navigate(`/spine-framework/admin/data/items/create?typeSlug=${typeSlug}`)
+  }
+
+  const handleViewItems = (typeSlug: string) => {
+    navigate(`/spine-framework/admin/data/items?typeSlug=${typeSlug}`)
+  }
+
+  if (loading) {
+    return (
+      <div className="flex items-center justify-center h-64">
+        <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-blue-600"></div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="space-y-6">
+      {/* Type Stats */}
+      <div>
+        <h2 className="text-lg font-semibold text-slate-900 mb-4">Entity Overview</h2>
+        <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4">
+          {typeStats.map((stat) => {
+            const Icon = stat.icon
+            return (
+              <div
+                key={stat.slug}
+                className="rounded-xl border border-slate-200 bg-white p-5 hover:shadow-md transition-shadow cursor-pointer"
+                onClick={() => handleViewItems(stat.slug)}
+              >
+                <div className="flex items-center gap-4">
+                  <div className="flex h-10 w-10 shrink-0 items-center justify-center rounded-lg bg-blue-50 text-blue-600">
+                    <Icon className="h-5 w-5" />
+                  </div>
+                  <div>
+                    <p className="text-sm text-slate-500">{stat.name}</p>
+                    <p className="text-xl font-semibold text-slate-900">{stat.count.toLocaleString()}</p>
+                  </div>
+                </div>
+              </div>
+            )
+          })}
+          
+          {/* Quick Actions Card */}
+          <div
+            className="rounded-xl border border-slate-200 bg-white p-5 hover:shadow-md transition-shadow cursor-pointer"
+            onClick={() => navigate('/spine-framework/admin/configs/types')}
+          >
+            <div className="flex items-center gap-4">
+              <div className="flex h-10 w-10 shrink-0 items-center justify-center rounded-lg bg-green-50 text-green-600">
+                <Settings className="h-5 w-5" />
+              </div>
+              <div>
+                <p className="text-sm text-slate-500">Configuration</p>
+                <p className="text-xl font-semibold text-slate-900">Manage</p>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      {/* Quick Actions */}
+      <div className="rounded-xl border border-slate-200 bg-white p-6">
+        <h3 className="text-sm font-semibold text-slate-900 mb-4">
+          Quick Actions
+        </h3>
+        
+        <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-4">
+          {typeStats.slice(0, 4).map((stat) => (
+            <button
+              key={`create-${stat.slug}`}
+              onClick={() => handleCreateNewItem(stat.slug)}
+              className="flex flex-col items-center gap-2 rounded-lg border border-slate-200 p-5 text-slate-600 hover:border-blue-200 hover:bg-blue-50 hover:text-blue-700 transition-colors focus:outline-none focus:ring-2 focus:ring-blue-500"
+            >
+              <Plus className="h-6 w-6" />
+              <span className="text-sm font-medium">New {stat.name}</span>
+            </button>
+          ))}
+          
+          <button 
+            onClick={() => navigate('/spine-framework/admin/configs/types')}
+            className="flex flex-col items-center gap-2 rounded-lg border border-slate-200 p-5 text-slate-600 hover:border-blue-200 hover:bg-blue-50 hover:text-blue-700 transition-colors focus:outline-none focus:ring-2 focus:ring-blue-500"
+          >
+            <Settings className="h-6 w-6" />
+            <span className="text-sm font-medium">Configure Types</span>
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}

package/.framework/src/pages/NotFoundPage.tsx

@@ -0,0 +1,39 @@
+/**
+ * @module src/pages/NotFoundPage
+ * @audience installer
+ * @layer frontend-page
+ * @stability stable
+ *
+ * Generic 404 page rendered by the catch-all route. Displays a large
+ * "404" heading and a "Go back home" link to `/dashboard`.
+ */
+
+import React from 'react'
+import { Link } from 'react-router-dom'
+import { Home } from 'lucide-react';
+
+export function NotFoundPage() {
+  return (
+    <div className="min-h-screen bg-slate-50 flex flex-col justify-center py-12 sm:px-6 lg:px-8">
+      <div className="sm:mx-auto sm:w-full sm:max-w-md">
+        <div className="text-center">
+          <h1 className="text-9xl font-bold text-slate-900">404</h1>
+          <h2 className="mt-4 text-3xl font-bold text-slate-900">Page not found</h2>
+          <p className="mt-2 text-sm text-slate-600">
+            Sorry, we couldn't find the page you're looking for.
+          </p>
+          
+          <div className="mt-6">
+            <Link
+              to="/dashboard"
+              className="inline-flex items-center px-4 py-2 border border-transparent text-sm font-medium rounded-md shadow-sm text-white bg-blue-600 hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500"
+            >
+              <Home className="w-4 h-4 mr-2" />
+              Go back home
+            </Link>
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}