spine-framework 0.1.0

package/.framework/src/components/ui/ItemCard.tsx

@@ -0,0 +1,296 @@
+/**
+ * @module src/components/ui/ItemCard
+ * @audience installer
+ * @layer frontend-component
+ * @stability stable
+ *
+ * Item display components for grid-based views.
+ *
+ * **`ItemCard`** — renders a single `Item` in either full (`compact=false`)
+ * or compact (`compact=true`) form. Derives its display values from
+ * `item.title`, `item.description`, and the first 3 entries of `item.data`.
+ * Optional action buttons (`onView`, `onEdit`, `onDelete`) are shown when
+ * `showActions=true`.
+ *
+ * **`ItemGrid`** — renders a responsive grid of `ItemCard` instances.
+ * Shows a spinner on `loading=true` and an empty state with a doc icon
+ * when `items` is empty.
+ *
+ * @seeAlso src/components/ui/ItemListView.tsx (combines with DataTable)
+ * @seeAlso src/types/types.ts (Item, ItemType)
+ * @seeAlso src/lib/utils.ts (formatDateTime, truncateText)
+ */
+
+import React from 'react'
+import { Item, ItemType } from '../../types/types'
+import { Badge } from './badge'
+import { Button } from './button'
+import { Box, FileText, Calendar, User, MoreVertical } from 'lucide-react';
+import { formatDateTime, truncateText } from '../../lib/utils'
+
+/**
+ * Props for `ItemCard`.
+ *
+ * @prop item - `Item` with optional resolved `item_type` relation
+ * @prop onEdit - Edit action callback
+ * @prop onDelete - Delete action callback
+ * @prop onView - View action callback
+ * @prop showActions - Shows action buttons (default: `true`)
+ * @prop compact - Condensed single-line layout (default: `false`)
+ */
+interface ItemCardProps {
+  item: Item & { item_type?: ItemType | string }
+  onEdit?: (item: Item) => void
+  onDelete?: (item: Item) => void
+  onView?: (item: Item) => void
+  showActions?: boolean
+  compact?: boolean
+}
+
+/**
+ * Item card with optional action buttons.
+ *
+ * @param props - `ItemCardProps`
+ * @returns White rounded card in full or compact layout
+ * @sideEffects none (delegates actions to `onEdit` / `onDelete` / `onView`)
+ */
+export function ItemCard({
+  item,
+  onEdit,
+  onDelete,
+  onView,
+  showActions = true,
+  compact = false
+}: ItemCardProps) {
+  const getPrimaryValue = () => item.title || 'Untitled Item'
+
+  const getSecondaryValue = () => {
+    if (item.description) return truncateText(item.description, 100)
+    return null
+  }
+
+  const getTypeIcon = () => {
+    return <Box className="h-5 w-5 text-blue-500" />
+  }
+
+  const getTypeName = () => {
+    if (!item.item_type) return item.item_type_slug || ''
+    if (typeof item.item_type === 'string') return item.item_type
+    return (item.item_type as ItemType).name || ''
+  }
+
+  const getTypeBadgeColor = () => {
+    if (!item.item_type || typeof item.item_type === 'string') return 'info'
+    return (item.item_type as ItemType).is_active ? 'success' : 'default'
+  }
+
+  if (compact) {
+    return (
+      <div className="bg-white border border-slate-200 rounded-lg p-4 hover:shadow-md transition-shadow">
+        <div className="flex items-start justify-between">
+          <div className="flex items-start space-x-3 flex-1">
+            <div className="flex-shrink-0">
+              {getTypeIcon()}
+            </div>
+            <div className="flex-1 min-w-0">
+              <div className="flex items-center space-x-2">
+                <h3 className="text-sm font-medium text-slate-900 truncate">
+                  {getPrimaryValue()}
+                </h3>
+                <Badge variant={getTypeBadgeColor()}>
+                  {getTypeName()}
+                </Badge>
+              </div>
+              {getSecondaryValue() && (
+                <p className="text-xs text-slate-500 mt-1">
+                  {getSecondaryValue()}
+                </p>
+              )}
+              <div className="flex items-center space-x-4 mt-2 text-xs text-slate-500">
+                <span>Updated {formatDateTime(item.updated_at)}</span>
+              </div>
+            </div>
+          </div>
+          
+          {showActions && (
+            <div className="flex items-center space-x-1">
+              {onView && (
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  onClick={() => onView(item)}
+                >
+                  View
+                </Button>
+              )}
+              <Button
+                variant="ghost"
+                size="sm"
+              >
+                <MoreVertical className="h-4 w-4" />
+              </Button>
+            </div>
+          )}
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="bg-white border border-slate-200 rounded-lg p-6 hover:shadow-md transition-shadow">
+      <div className="flex items-start justify-between">
+        <div className="flex items-start space-x-4 flex-1">
+          <div className="flex-shrink-0">
+            {getTypeIcon()}
+          </div>
+          <div className="flex-1 min-w-0">
+            <div className="flex items-center space-x-2 mb-2">
+              <h3 className="text-lg font-medium text-slate-900 truncate">
+                {getPrimaryValue()}
+              </h3>
+              <Badge variant={getTypeBadgeColor()}>
+                {getTypeName()}
+              </Badge>
+            </div>
+            
+            {getSecondaryValue() && (
+              <p className="text-sm text-slate-600 mb-3">
+                {getSecondaryValue()}
+              </p>
+            )}
+
+            {/* Additional data fields */}
+            {Object.keys(item.data || {}).length > 0 && (
+              <div className="space-y-2 mb-4">
+                {Object.entries(item.data)
+                  .filter(([, v]) => v !== undefined && v !== null && v !== '')
+                  .slice(0, 3)
+                  .map(([key, value]) => (
+                    <div key={key} className="flex items-center space-x-2">
+                      <span className="text-xs font-medium text-slate-500">{key}:</span>
+                      <span className="text-xs text-slate-900">
+                        {truncateText(typeof value === 'boolean' ? (value ? 'Yes' : 'No') : String(value), 50)}
+                      </span>
+                    </div>
+                  ))}
+              </div>
+            )}
+
+            {/* Metadata */}
+            <div className="flex items-center justify-between text-xs text-slate-500">
+              <div className="flex items-center space-x-4">
+                <span className="flex items-center">
+                  <Calendar className="h-3 w-3 mr-1" />
+                  Created {formatDateTime(item.created_at)}
+                </span>
+                <span className="flex items-center">
+                  <User className="h-3 w-3 mr-1" />
+                  ID: {item.id.slice(0, 8)}...
+                </span>
+              </div>
+            </div>
+          </div>
+        </div>
+        
+        {showActions && (
+          <div className="flex items-center space-x-2 ml-4">
+            {onView && (
+              <Button
+                variant="outline"
+                size="sm"
+                onClick={() => onView(item)}
+              >
+                View
+              </Button>
+            )}
+            {onEdit && (
+              <Button
+                variant="outline"
+                size="sm"
+                onClick={() => onEdit(item)}
+              >
+                Edit
+              </Button>
+            )}
+            <Button
+              variant="ghost"
+              size="sm"
+            >
+              <MoreVertical className="h-4 w-4" />
+            </Button>
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
+
+/**
+ * Props for `ItemGrid`.
+ *
+ * @prop items - Typed item array with resolved `item_type`
+ * @prop loading - Shows spinner while true
+ * @prop compact - Passes compact mode to each `ItemCard`
+ * @prop emptyMessage - Text shown when `items` is empty
+ */
+interface ItemGridProps {
+  items: (Item & { item_type: ItemType })[]
+  loading?: boolean
+  onEdit?: (item: Item) => void
+  onDelete?: (item: Item) => void
+  onView?: (item: Item) => void
+  compact?: boolean
+  emptyMessage?: string
+}
+
+/**
+ * Responsive card grid for items.
+ *
+ * @param props - `ItemGridProps`
+ * @returns Responsive grid, loading spinner, or empty state
+ * @sideEffects none (delegates actions to `onEdit` / `onDelete` / `onView`)
+ */
+export function ItemGrid({
+  items,
+  loading = false,
+  onEdit,
+  onDelete,
+  onView,
+  compact = false,
+  emptyMessage = 'No items found'
+}: ItemGridProps) {
+  if (loading) {
+    return (
+      <div className="flex justify-center py-8">
+        <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-blue-600"></div>
+      </div>
+    )
+  }
+
+  if (items.length === 0) {
+    return (
+      <div className="text-center py-8">
+        <FileText className="mx-auto h-12 w-12 text-slate-400" />
+        <h3 className="mt-2 text-sm font-medium text-slate-900">{emptyMessage}</h3>
+      </div>
+    )
+  }
+
+  return (
+    <div className={compact 
+      ? "grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4"
+      : "grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6"
+    }>
+      {items.map((item) => (
+        <ItemCard
+          key={item.id}
+          item={item}
+          onEdit={onEdit}
+          onDelete={onDelete}
+          onView={onView}
+          compact={compact}
+        />
+      ))}
+    </div>
+  )
+}

package/.framework/src/components/ui/ItemListView.tsx

@@ -0,0 +1,308 @@
+/**
+ * @module src/components/ui/ItemListView
+ * @audience installer
+ * @layer frontend-component
+ * @stability stable
+ *
+ * Switchable item view widget and page shell.
+ *
+ * **`ItemListView`** — renders items in either a compact `ItemGrid` or a
+ * full `DataTable` view, toggled by icon buttons. Derives unique type
+ * filter options from the items array and builds a fixed table column
+ * set. The primary display field is resolved from the first `text` or
+ * `textarea` field in the item type's `design_schema`.
+ *
+ * **`ItemListPage`** — wraps `ItemListView` with a page-level title and
+ * description header. Use as a standalone page component.
+ *
+ * @seeAlso src/components/ui/ItemCard.tsx
+ * @seeAlso src/components/ui/DataTable.tsx
+ * @seeAlso src/types/types.ts (Item, ItemType)
+ */
+
+import React, { useState } from 'react'
+import { Item, ItemType } from '../../types/types'
+import { DataTable } from './DataTable'
+import { ItemCard, ItemGrid } from './ItemCard'
+import { Badge } from './badge'
+import { Button } from './button'
+import { Squares2X2Icon, List, Plus } from 'lucide-react';
+import { formatDateTime } from '../../lib/utils'
+
+/**
+ * Props for `ItemListView`.
+ *
+ * @prop items - Typed item array with resolved `item_type`
+ * @prop loading - Shows spinner while fetching
+ * @prop onEdit / onDelete / onView - Row/card action callbacks
+ * @prop onCreate - Create button callback
+ * @prop searchable - Enables search in table view (default: `true`)
+ * @prop filterable - Enables column filters in table view (default: `true`)
+ * @prop emptyMessage - Empty-state label
+ * @prop showCreateButton - Shows the create button (default: `true`)
+ * @prop createButtonText - Create button label (default: `'Create Item'`)
+ */
+interface ItemListViewProps {
+  items: (Item & { item_type: ItemType })[]
+  loading?: boolean
+  onEdit?: (item: Item) => void
+  onDelete?: (item: Item) => void
+  onView?: (item: Item) => void
+  onCreate?: () => void
+  searchable?: boolean
+  filterable?: boolean
+  emptyMessage?: string
+  showCreateButton?: boolean
+  createButtonText?: string
+}
+
+/**
+ * Switchable grid/table item view.
+ *
+ * @param props - `ItemListViewProps`
+ * @returns Header with view-mode toggle + `ItemGrid` or `DataTable`
+ * @sideEffects none (delegates actions and creation to prop callbacks)
+ */
+export function ItemListView({
+  items,
+  loading = false,
+  onEdit,
+  onDelete,
+  onView,
+  onCreate,
+  searchable = true,
+  filterable = true,
+  emptyMessage = 'No items found',
+  showCreateButton = true,
+  createButtonText = 'Create Item'
+}: ItemListViewProps) {
+  const [viewMode, setViewMode] = useState<'grid' | 'table'>('grid')
+
+  // Get unique types for filtering
+  const typesMap = new Map<string, ItemType>()
+  items.forEach(item => {
+    typesMap.set(item.item_type.id, item.item_type)
+  })
+  const types = Array.from(typesMap.values()).map(type => ({
+    value: type.id,
+    label: type.name
+  }))
+
+  // Table columns
+  const tableColumns = [
+    {
+      key: 'data' as const,
+      title: 'Item',
+      sortable: true,
+      render: (value: Record<string, any>, item: Item & { item_type: ItemType }) => {
+        const primaryField = item.item_type.design_schema?.fields ? Object.entries(item.item_type.design_schema.fields).find(([_, f]: [string, any]) => 
+          f.data_type === 'text' || f.data_type === 'textarea'
+        ) : null
+        const fieldEntry = primaryField ? primaryField : null
+        const fieldName = fieldEntry ? fieldEntry[0] : 'name'
+        const displayValue = value[fieldName] || 'Untitled Item'
+        
+        return (
+          <div>
+            <div className="font-medium text-slate-900">{displayValue}</div>
+            <div className="text-sm text-slate-500">
+              <Badge variant={item.item_type.is_active ? 'success' : 'default'}>
+                {item.item_type.name}
+              </Badge>
+            </div>
+          </div>
+        )
+      }
+    },
+    {
+      key: 'item_type' as const,
+      title: 'Type',
+      filterable: true,
+      filterOptions: types,
+      render: (value: ItemType) => (
+        <Badge variant={value.is_active ? 'success' : 'default'}>
+          {value.name}
+        </Badge>
+      )
+    },
+    {
+      key: 'created_at' as const,
+      title: 'Created',
+      sortable: true,
+      render: (value: string) => formatDateTime(value)
+    },
+    {
+      key: 'updated_at' as const,
+      title: 'Updated',
+      sortable: true,
+      render: (value: string) => formatDateTime(value)
+    },
+    {
+      key: 'id' as const,
+      title: 'Actions',
+      render: (_: any, item: Item & { item_type: ItemType }) => (
+        <div className="flex items-center space-x-2">
+          {onView && (
+            <Button
+              variant="outline"
+              size="sm"
+              onClick={() => onView(item)}
+            >
+              View
+            </Button>
+          )}
+          {onEdit && (
+            <Button
+              variant="outline"
+              size="sm"
+              onClick={() => onEdit(item)}
+            >
+              Edit
+            </Button>
+          )}
+        </div>
+      )
+    }
+  ]
+
+  return (
+    <div className="space-y-4">
+      {/* Header */}
+      <div className="flex items-center justify-between">
+        <div className="flex items-center space-x-4">
+          <h2 className="text-lg font-medium text-slate-900">
+            Items ({items.length})
+          </h2>
+          
+          {/* View Mode Toggle */}
+          <div className="flex items-center bg-slate-100 rounded-lg p-1">
+            <button
+              onClick={() => setViewMode('grid')}
+              className={`
+                px-3 py-1.5 rounded-md text-sm font-medium transition-colors
+                ${viewMode === 'grid'
+                  ? 'bg-white text-slate-900 shadow-sm'
+                  : 'text-slate-600 hover:text-slate-900'
+                }
+              `}
+            >
+              <Squares2X2Icon className="h-4 w-4" />
+            </button>
+            <button
+              onClick={() => setViewMode('table')}
+              className={`
+                px-3 py-1.5 rounded-md text-sm font-medium transition-colors
+                ${viewMode === 'table'
+                  ? 'bg-white text-slate-900 shadow-sm'
+                  : 'text-slate-600 hover:text-slate-900'
+                }
+              `}
+            >
+              <List className="h-4 w-4" />
+            </button>
+          </div>
+        </div>
+        
+        {showCreateButton && onCreate && (
+          <Button onClick={onCreate}>
+            <Plus className="h-4 w-4 mr-2" />
+            {createButtonText}
+          </Button>
+        )}
+      </div>
+
+      {/* Content */}
+      {viewMode === 'grid' ? (
+        <ItemGrid
+          items={items}
+          loading={loading}
+          onEdit={onEdit}
+          onDelete={onDelete}
+          onView={onView}
+          compact={true}
+          emptyMessage={emptyMessage}
+        />
+      ) : (
+        <DataTable
+          data={items}
+          columns={tableColumns as any}
+          loading={loading}
+          searchable={searchable}
+          filterable={filterable}
+          emptyMessage={emptyMessage}
+        />
+      )}
+    </div>
+  )
+}
+
+/**
+ * Props for `ItemListPage`.
+ *
+ * @prop title - Page heading (default: `'Items'`)
+ * @prop description - Page subtitle (default: `'Manage and organize your items'`)
+ * (other props same as `ItemListViewProps`)
+ */
+interface ItemListPageProps {
+  items: (Item & { item_type: ItemType })[]
+  loading?: boolean
+  onEdit?: (item: Item) => void
+  onDelete?: (item: Item) => void
+  onView?: (item: Item) => void
+  onCreate?: () => void
+  searchable?: boolean
+  filterable?: boolean
+  emptyMessage?: string
+  showCreateButton?: boolean
+  createButtonText?: string
+  title?: string
+  description?: string
+}
+
+/**
+ * Full item list page with title header and switchable view.
+ *
+ * @param props - `ItemListPageProps`
+ * @returns Page header + `ItemListView`
+ * @sideEffects none (pure rendering)
+ */
+export function ItemListPage({
+  items,
+  loading = false,
+  onEdit,
+  onDelete,
+  onView,
+  onCreate,
+  searchable = true,
+  filterable = true,
+  emptyMessage = 'No items found',
+  showCreateButton = true,
+  createButtonText = 'Create Item',
+  title = 'Items',
+  description = 'Manage and organize your items'
+}: ItemListPageProps) {
+  return (
+    <div className="space-y-6">
+      {/* Page Header */}
+      <div>
+        <h1 className="text-2xl font-bold text-slate-900">{title}</h1>
+        <p className="mt-1 text-sm text-slate-600">{description}</p>
+      </div>
+
+      {/* Item List View */}
+      <ItemListView
+        items={items}
+        loading={loading}
+        onEdit={onEdit}
+        onDelete={onDelete}
+        onView={onView}
+        onCreate={onCreate}
+        searchable={searchable}
+        filterable={filterable}
+        emptyMessage={emptyMessage}
+        showCreateButton={showCreateButton}
+        createButtonText={createButtonText}
+      />
+    </div>
+  )
+}

package/.framework/src/components/ui/LoadingSpinner.tsx

@@ -0,0 +1,52 @@
+/**
+ * @module src/components/ui/LoadingSpinner
+ * @audience installer
+ * @layer frontend-component
+ * @stability stable
+ *
+ * Animated CSS spinner used to indicate loading state inline or as a
+ * centred overlay. Uses `border-t-blue-600` as the active segment colour
+ * and `border-slate-200` for the track.
+ *
+ * @seeAlso src/lib/utils.ts (cn)
+ */
+
+import React from 'react'
+import { Loader2 } from 'lucide-react'
+import { cn } from '../../lib/utils'
+
+/**
+ * Props for `LoadingSpinner`.
+ *
+ * @prop size - Diameter: `'sm'` (16px), `'md'` (24px), `'lg'` (32px)
+ * @prop className - Additional Tailwind classes
+ */
+interface LoadingSpinnerProps {
+  className?: string
+  size?: 'sm' | 'md' | 'lg'
+}
+
+/**
+ * Inline animated spinner.
+ *
+ * @param props - `LoadingSpinnerProps`
+ * @returns `<Loader2>` styled as a spinning ring
+ * @sideEffects none (pure rendering)
+ */
+export function LoadingSpinner({ className, size = 'md' }: LoadingSpinnerProps) {
+  const sizeClasses = {
+    sm: 'h-4 w-4',
+    md: 'h-6 w-6',
+    lg: 'h-8 w-8',
+  }
+
+  return (
+    <Loader2
+      className={cn(
+        'animate-spin',
+        sizeClasses[size],
+        className
+      )}
+    />
+  )
+}