@startsimpli/ui 0.1.0

package/src/components/unified-table/components/MobileView/README.md

@@ -0,0 +1,411 @@
+# MobileView Component System
+
+## Overview
+
+The MobileView component system provides a responsive, touch-friendly mobile interface for displaying table data as cards. It automatically switches between table and card views based on screen size and provides extensive customization options.
+
+## Features
+
+- **Responsive Breakpoint Logic**: Automatically switches at 768px (configurable)
+- **Touch-Friendly Actions**: 44px minimum touch targets following iOS/Android guidelines
+- **Selection Support**: Integrated checkbox selection with visual feedback
+- **Custom Renderers**: Full control over title, subtitle, fields, and content
+- **Loading States**: Per-row and global loading indicators
+- **Accessibility**: ARIA labels, keyboard navigation, screen reader support
+
+## Components
+
+### MobileView
+
+Main container component that renders a list of cards.
+
+```tsx
+import { MobileView } from '@/components/tables/unified-table/components/MobileView'
+
+<MobileView
+  data={investors}
+  config={mobileConfig}
+  getRowId={(row) => row.id}
+  loading={false}
+  loadingRows={new Set()}
+  emptyState={<div>No data</div>}
+/>
+```
+
+### Card
+
+Individual card component for displaying a single row of data.
+
+```tsx
+import { Card } from '@/components/tables/unified-table/components/MobileView'
+
+<Card
+  row={investor}
+  config={mobileConfig}
+  rowId={investor.id}
+  isLoading={false}
+/>
+```
+
+### CardActions
+
+Touch-friendly action buttons with overflow menu support.
+
+```tsx
+import { CardActions } from '@/components/tables/unified-table/components/MobileView'
+
+<CardActions
+  actions={[
+    {
+      id: 'edit',
+      label: 'Edit',
+      icon: Edit,
+      onClick: handleEdit,
+    },
+  ]}
+  row={data}
+  maxVisibleActions={2}
+/>
+```
+
+## Configuration
+
+### Basic Configuration
+
+```tsx
+const basicConfig: MobileCardConfig = {
+  titleKey: 'name',
+  subtitleKey: 'email',
+
+  primaryFields: [
+    { key: 'role', label: 'Role' },
+    { key: 'status', label: 'Status' },
+  ],
+
+  secondaryFields: [
+    { key: 'department' },
+    { key: 'location' },
+  ],
+
+  actions: [
+    {
+      id: 'edit',
+      icon: Edit,
+      onClick: handleEdit,
+    },
+  ],
+}
+```
+
+### Advanced Configuration
+
+```tsx
+const advancedConfig: MobileCardConfig<Investor> = {
+  // Custom title rendering
+  titleRender: (investor) => (
+    <div className="flex items-center gap-2">
+      <span>{investor.name}</span>
+      <TierBadge tier={investor.tier} />
+    </div>
+  ),
+
+  // Custom subtitle rendering
+  subtitleRender: (investor) => (
+    <span>{investor.title} at {investor.firm.name}</span>
+  ),
+
+  // Custom image/avatar
+  imageRender: (investor) => (
+    <Avatar src={investor.avatar} name={investor.name} />
+  ),
+
+  // Primary fields with custom renderers
+  primaryFields: [
+    {
+      key: 'tier',
+      render: (value) => <TierBadge tier={value} />,
+    },
+    {
+      key: 'status',
+      render: (value) => <StatusBadge status={value} />,
+    },
+  ],
+
+  // Secondary fields
+  secondaryFields: [
+    {
+      key: 'checkSize',
+      label: 'Check Size',
+      render: (value) => formatCurrency(value),
+    },
+  ],
+
+  // Actions with icons and variants
+  actions: [
+    {
+      id: 'enrich',
+      icon: Sparkles,
+      variant: 'default',
+      onClick: handleEnrich,
+      disabled: (row) => row.enrichmentStatus === 'pending',
+    },
+    {
+      id: 'email',
+      icon: Mail,
+      variant: 'outline',
+      onClick: (row) => window.location.href = `mailto:${row.email}`,
+      hidden: (row) => !row.email,
+    },
+  ],
+
+  // Custom content sections
+  renderCustomContent: (investor) => (
+    <InvestorDetails investor={investor} />
+  ),
+
+  renderCustomFooter: (investor) => (
+    <LastContactInfo date={investor.lastContact} />
+  ),
+
+  // Selection
+  showSelection: true,
+  onSelectionChange: handleSelectionChange,
+  isSelected: (row) => selectedIds.has(row.id),
+
+  // Click handler
+  onClick: (investor) => router.push(`/investors/${investor.id}`),
+}
+```
+
+## Field Renderers
+
+### Built-in Renderers
+
+```tsx
+import { commonRenderers } from '@/components/tables/unified-table/utils/renderers'
+
+{
+  key: 'price',
+  render: commonRenderers.currency,
+}
+
+{
+  key: 'percentage',
+  render: commonRenderers.percentage,
+}
+
+{
+  key: 'createdAt',
+  render: commonRenderers.datetime,
+}
+```
+
+### Custom Renderers
+
+```tsx
+{
+  key: 'status',
+  render: (value, row) => {
+    const colors = {
+      active: 'text-green-600',
+      inactive: 'text-gray-500',
+    }
+    return (
+      <span className={colors[value]}>
+        {value}
+      </span>
+    )
+  },
+}
+```
+
+## Actions
+
+### Basic Actions
+
+```tsx
+actions: [
+  {
+    id: 'edit',
+    label: 'Edit',
+    icon: Edit,
+    onClick: (row) => setEditRow(row),
+  },
+]
+```
+
+### Conditional Actions
+
+```tsx
+actions: [
+  {
+    id: 'delete',
+    label: 'Delete',
+    icon: Trash2,
+    variant: 'destructive',
+    onClick: handleDelete,
+    disabled: (row) => row.isProtected,
+    hidden: (row) => !hasPermission(row),
+  },
+]
+```
+
+### Async Actions
+
+```tsx
+actions: [
+  {
+    id: 'enrich',
+    label: 'Enrich',
+    icon: Sparkles,
+    onClick: async (row) => {
+      await enrichInvestor(row.id)
+      toast.success('Enrichment complete')
+    },
+  },
+]
+```
+
+## Responsive Behavior
+
+### Breakpoints
+
+The default breakpoint is 768px, defined in `types.ts`:
+
+```tsx
+export const MOBILE_BREAKPOINT = 768
+```
+
+### Custom Breakpoints
+
+Use the `useResponsive` hook for custom breakpoint logic:
+
+```tsx
+import { useResponsive } from '@/components/tables/unified-table/hooks/useResponsive'
+
+const { isMobile, isTablet, isDesktop } = useResponsive({
+  mobile: 640,
+  tablet: 1024,
+  desktop: 1280,
+})
+```
+
+## Accessibility
+
+### ARIA Labels
+
+All interactive elements include appropriate ARIA labels:
+
+- Checkboxes: `aria-label="Select row"`
+- Action buttons: Include visible labels or `sr-only` text
+- Cards: Semantic HTML structure
+
+### Keyboard Navigation
+
+- Tab navigation through all interactive elements
+- Enter/Space to activate buttons and checkboxes
+- Focus indicators on all focusable elements
+
+### Touch Targets
+
+All touch targets meet minimum size requirements:
+- Buttons: 44px × 44px minimum
+- Checkboxes: 20px × 20px (5px padding = 30px × 30px touch area)
+
+## Performance
+
+### Optimization Tips
+
+1. **Memoize Renderers**: Use `useCallback` for custom renderers
+2. **Lazy Loading**: Use `React.lazy` for heavy custom content
+3. **Virtual Scrolling**: For large datasets, consider virtualization
+4. **Image Optimization**: Use next/image or lazy loading for avatars
+
+### Example
+
+```tsx
+const titleRender = useCallback((row: Investor) => (
+  <div>{row.name}</div>
+), [])
+
+const mobileConfig = useMemo(() => ({
+  titleRender,
+  // ... other config
+}), [titleRender])
+```
+
+## Examples
+
+See the `examples/` directory for complete examples:
+
+- `basic-mobile-config.tsx` - Simple user list
+- `advanced-mobile-config.tsx` - Complex investor cards
+
+## Best Practices
+
+1. **Title/Subtitle**: Always provide clear, meaningful titles
+2. **Primary Fields**: Limit to 3-4 most important fields
+3. **Secondary Fields**: Use for supplementary information
+4. **Actions**: Show max 2-3 primary actions, overflow the rest
+5. **Custom Content**: Use sparingly, maintain consistency
+6. **Loading States**: Always handle loading and error states
+7. **Selection**: Provide clear visual feedback for selected items
+8. **Touch Targets**: Ensure all interactive elements are easily tappable
+
+## Type Definitions
+
+```typescript
+interface MobileCardConfig<TData> {
+  titleKey: string
+  titleRender?: (row: TData) => ReactNode
+
+  subtitleKey?: string
+  subtitleRender?: (row: TData) => ReactNode
+
+  imageKey?: string
+  imageRender?: (row: TData) => ReactNode
+
+  primaryFields: MobileCardField[]
+  secondaryFields?: MobileCardField[]
+
+  actions?: MobileCardAction[]
+
+  renderCustomContent?: (row: TData) => ReactNode
+  renderCustomHeader?: (row: TData) => ReactNode
+  renderCustomFooter?: (row: TData) => ReactNode
+
+  showSelection?: boolean
+  onSelectionChange?: (id: string, selected: boolean) => void
+  isSelected?: (row: TData) => boolean
+
+  onClick?: (row: TData) => void
+
+  className?: string
+}
+```
+
+## Troubleshooting
+
+### Cards not rendering
+
+- Check that `data` array is not empty
+- Verify `titleKey` matches a property in your data
+- Check console for validation errors
+
+### Actions not working
+
+- Ensure `onClick` is defined for each action
+- Check if action is `disabled` or `hidden` for the row
+- Verify `e.stopPropagation()` is not interfering
+
+### Selection not working
+
+- Provide `getRowId` to generate stable IDs
+- Implement `onSelectionChange` handler
+- Verify `isSelected` returns correct value
+
+### Responsive switching not working
+
+- Check window width is below MOBILE_BREAKPOINT
+- Ensure component is client-side (`'use client'`)
+- Verify no CSS conflicts with breakpoint detection

package/src/components/unified-table/components/MobileView/index.tsx

@@ -0,0 +1,77 @@
+'use client'
+
+import { cn } from '../../../../lib/utils'
+import { useEffect, useState } from 'react'
+import { Card } from './Card'
+import { MobileViewProps, MOBILE_BREAKPOINT } from './types'
+
+export function MobileView<TData = any>({
+  data,
+  config,
+  getRowId,
+  loading = false,
+  loadingRows,
+  emptyState,
+  className
+}: MobileViewProps<TData>) {
+  const [isMobile, setIsMobile] = useState(false)
+
+  useEffect(() => {
+    const checkMobile = () => {
+      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    }
+
+    checkMobile()
+    window.addEventListener('resize', checkMobile)
+    return () => window.removeEventListener('resize', checkMobile)
+  }, [])
+
+  if (data.length === 0 && !loading) {
+    return (
+      <div className={cn('flex items-center justify-center py-12', className)}>
+        {emptyState || (
+          <div className="text-center">
+            <p className="text-muted-foreground text-sm">No data to display</p>
+          </div>
+        )}
+      </div>
+    )
+  }
+
+  return (
+    <div
+      className={cn(
+        'space-y-4',
+        isMobile && 'space-y-3',
+        className
+      )}
+    >
+      {data.map((row, index) => {
+        const rowId = getRowId ? getRowId(row) : String(index)
+        const isRowLoading = loadingRows?.has(rowId) || false
+
+        return (
+          <Card
+            key={rowId}
+            row={row}
+            config={config}
+            rowId={rowId}
+            isLoading={isRowLoading}
+          />
+        )
+      })}
+    </div>
+  )
+}
+
+export { Card } from './Card'
+export { CardActions } from './CardActions'
+export type {
+  MobileViewProps,
+  MobileCardConfig,
+  MobileCardField,
+  MobileCardAction,
+  CardProps,
+  CardActionsProps
+} from './types'
+export { MOBILE_BREAKPOINT } from './types'

package/src/components/unified-table/components/MobileView/types.ts

@@ -0,0 +1,77 @@
+import { ReactNode } from 'react'
+
+export interface MobileCardField {
+  key: string
+  label?: string
+  render?: (value: any, row: any) => ReactNode
+  className?: string
+}
+
+export interface MobileCardAction {
+  id: string
+  label: string
+  icon?: React.ComponentType<{ className?: string }>
+  onClick: (row: any) => void | Promise<void>
+  variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link'
+  disabled?: (row: any) => boolean
+  hidden?: (row: any) => boolean
+  className?: string
+}
+
+export interface MobileCardConfig<TData = any> {
+  titleKey: string
+  titleRender?: (row: TData) => ReactNode
+
+  subtitleKey?: string
+  subtitleRender?: (row: TData) => ReactNode
+
+  imageKey?: string
+  imageRender?: (row: TData) => ReactNode
+
+  primaryFields: MobileCardField[]
+  secondaryFields?: MobileCardField[]
+
+  actions?: MobileCardAction[]
+
+  renderCustomContent?: (row: TData) => ReactNode
+  renderCustomHeader?: (row: TData) => ReactNode
+  renderCustomFooter?: (row: TData) => ReactNode
+
+  showSelection?: boolean
+  onSelectionChange?: (id: string, selected: boolean) => void
+  isSelected?: (row: TData) => boolean
+
+  onClick?: (row: TData) => void
+
+  className?: string
+  headerClassName?: string
+  contentClassName?: string
+  footerClassName?: string
+}
+
+export interface MobileViewProps<TData = any> {
+  data: TData[]
+  config: MobileCardConfig<TData>
+  getRowId?: (row: TData) => string
+  loading?: boolean
+  loadingRows?: Set<string>
+  emptyState?: ReactNode
+  className?: string
+}
+
+export interface CardProps<TData = any> {
+  row: TData
+  config: MobileCardConfig<TData>
+  rowId?: string
+  isLoading?: boolean
+  className?: string
+}
+
+export interface CardActionsProps {
+  actions: MobileCardAction[]
+  row: any
+  className?: string
+  maxVisibleActions?: number
+}
+
+export const MOBILE_BREAKPOINT = 768 // px