spine-framework 0.1.61 → 1.0.0

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

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

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

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

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