@startsimpli/ui 0.1.0

package/src/components/unified-table/utils/export.ts

@@ -0,0 +1,236 @@
+import * as XLSX from 'xlsx'
+import { ColumnConfig } from '../types'
+
+export type ExportFormat = 'csv' | 'excel'
+
+export interface ExportOptions {
+  filename: string
+  format: ExportFormat
+  includeHeaders?: boolean
+  dateFormat?: string
+}
+
+/**
+ * Extracts the value from a row using column configuration
+ */
+function getColumnValue<TData>(row: TData, column: ColumnConfig<TData>): any {
+  if (column.accessorFn) {
+    return column.accessorFn(row)
+  }
+
+  if (column.accessorKey) {
+    const keys = column.accessorKey.split('.')
+    let value: any = row
+    for (const key of keys) {
+      value = value?.[key]
+    }
+    return value
+  }
+
+  return ''
+}
+
+/**
+ * Formats a value for export (handles dates, objects, arrays)
+ */
+function formatValueForExport(value: any): string {
+  if (value == null) {
+    return ''
+  }
+
+  if (value instanceof Date) {
+    return value.toISOString()
+  }
+
+  if (typeof value === 'object') {
+    return JSON.stringify(value)
+  }
+
+  if (typeof value === 'boolean') {
+    return value ? 'Yes' : 'No'
+  }
+
+  return String(value)
+}
+
+/**
+ * Gets the header text for a column
+ */
+function getColumnHeader<TData>(column: ColumnConfig<TData>): string {
+  if (typeof column.header === 'string') {
+    return column.header
+  }
+  return column.id
+}
+
+/**
+ * Prepares data for export based on visible columns
+ */
+function prepareExportData<TData>(
+  data: TData[],
+  columns: ColumnConfig<TData>[],
+  includeHeaders: boolean = true
+): string[][] {
+  const rows: string[][] = []
+
+  // Add headers
+  if (includeHeaders) {
+    rows.push(columns.map(getColumnHeader))
+  }
+
+  // Add data rows
+  for (const row of data) {
+    const rowData: string[] = []
+    for (const column of columns) {
+      const value = getColumnValue(row, column)
+      rowData.push(formatValueForExport(value))
+    }
+    rows.push(rowData)
+  }
+
+  return rows
+}
+
+/**
+ * Converts array data to CSV string
+ */
+function arrayToCSV(data: string[][]): string {
+  return data
+    .map(row =>
+      row
+        .map(cell => {
+          // Escape quotes and wrap in quotes if contains comma, quote, or newline
+          const needsQuotes = /[,"\n\r]/.test(cell)
+          if (needsQuotes) {
+            return `"${cell.replace(/"/g, '""')}"`
+          }
+          return cell
+        })
+        .join(',')
+    )
+    .join('\n')
+}
+
+/**
+ * Triggers a download of the given content
+ */
+function downloadFile(content: string | Blob, filename: string, mimeType: string): void {
+  const blob = content instanceof Blob ? content : new Blob([content], { type: mimeType })
+  const url = URL.createObjectURL(blob)
+  const link = document.createElement('a')
+  link.href = url
+  link.download = filename
+  document.body.appendChild(link)
+  link.click()
+  document.body.removeChild(link)
+  URL.revokeObjectURL(url)
+}
+
+/**
+ * Exports data to CSV format
+ * @param data Array of data to export
+ * @param columns Visible columns configuration
+ * @param filename Name of the file to download (without extension)
+ * @param includeHeaders Whether to include header row (default: true)
+ */
+export function exportToCSV<TData>(
+  data: TData[],
+  columns: ColumnConfig<TData>[],
+  filename: string,
+  includeHeaders: boolean = true
+): void {
+  if (!data || data.length === 0) {
+    throw new Error('No data to export')
+  }
+
+  if (!columns || columns.length === 0) {
+    throw new Error('No columns specified for export')
+  }
+
+  const exportData = prepareExportData(data, columns, includeHeaders)
+  const csv = arrayToCSV(exportData)
+
+  downloadFile(csv, `${filename}.csv`, 'text/csv;charset=utf-8;')
+}
+
+/**
+ * Exports data to Excel format (XLSX)
+ * @param data Array of data to export
+ * @param columns Visible columns configuration
+ * @param filename Name of the file to download (without extension)
+ * @param includeHeaders Whether to include header row (default: true)
+ */
+export function exportToExcel<TData>(
+  data: TData[],
+  columns: ColumnConfig<TData>[],
+  filename: string,
+  includeHeaders: boolean = true
+): void {
+  if (!data || data.length === 0) {
+    throw new Error('No data to export')
+  }
+
+  if (!columns || columns.length === 0) {
+    throw new Error('No columns specified for export')
+  }
+
+  const exportData = prepareExportData(data, columns, includeHeaders)
+
+  // Create workbook and worksheet
+  const ws = XLSX.utils.aoa_to_sheet(exportData)
+  const wb = XLSX.utils.book_new()
+  XLSX.utils.book_append_sheet(wb, ws, 'Data')
+
+  // Auto-size columns
+  const columnWidths = columns.map((column, idx) => {
+    const header = getColumnHeader(column)
+    const maxWidth = exportData.reduce((max, row) => {
+      const cellValue = row[idx] || ''
+      return Math.max(max, cellValue.length)
+    }, header.length)
+    return { wch: Math.min(maxWidth + 2, 50) } // Max width of 50 chars
+  })
+  ws['!cols'] = columnWidths
+
+  // Generate Excel file and trigger download
+  const excelBuffer = XLSX.write(wb, { bookType: 'xlsx', type: 'array' })
+  const blob = new Blob([excelBuffer], {
+    type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+  })
+
+  downloadFile(blob, `${filename}.xlsx`, blob.type)
+}
+
+/**
+ * Generic export function that routes to CSV or Excel based on format
+ * @param data Array of data to export
+ * @param columns Visible columns configuration
+ * @param options Export options including format and filename
+ */
+export function exportData<TData>(
+  data: TData[],
+  columns: ColumnConfig<TData>[],
+  options: ExportOptions
+): void {
+  const { format, filename, includeHeaders = true } = options
+
+  switch (format) {
+    case 'csv':
+      exportToCSV(data, columns, filename, includeHeaders)
+      break
+    case 'excel':
+      exportToExcel(data, columns, filename, includeHeaders)
+      break
+    default:
+      throw new Error(`Unsupported export format: ${format}`)
+  }
+}
+
+/**
+ * Helper to generate a filename with timestamp
+ */
+export function generateExportFilename(baseFilename: string): string {
+  const now = new Date()
+  const timestamp = now.toISOString().replace(/[:.]/g, '-').slice(0, -5)
+  return `${baseFilename}_${timestamp}`
+}

package/src/components/unified-table/utils/index.ts

@@ -0,0 +1,4 @@
+export * from './renderers'
+export * from './themes'
+export * from './validation'
+export * from './export'

package/src/components/unified-table/utils/renderers.ts

@@ -0,0 +1,105 @@
+import { ReactNode } from 'react'
+
+export type CellRenderer<TData = any> = (value: any, row: TData) => ReactNode
+
+export interface RendererConfig {
+  [columnId: string]: CellRenderer
+}
+
+export function createCellRenderer<TData = any>(
+  render: (value: any, row: TData) => ReactNode
+): CellRenderer<TData> {
+  return render
+}
+
+export function getNestedValue(obj: any, path: string): any {
+  if (!path || !obj) return obj
+
+  const keys = path.split('.')
+  let value = obj
+
+  for (const key of keys) {
+    if (value === null || value === undefined) return undefined
+    value = value[key]
+  }
+
+  return value
+}
+
+export const commonRenderers = {
+  text: createCellRenderer((value) => String(value || '-')),
+
+  number: createCellRenderer((value) => {
+    if (value === null || value === undefined) return '-'
+    return new Intl.NumberFormat().format(Number(value))
+  }),
+
+  currency: createCellRenderer((value, row, options?: { currency?: string; locale?: string }) => {
+    if (value === null || value === undefined) return '-'
+    return new Intl.NumberFormat(options?.locale || 'en-US', {
+      style: 'currency',
+      currency: options?.currency || 'USD',
+    }).format(Number(value))
+  }),
+
+  percentage: createCellRenderer((value) => {
+    if (value === null || value === undefined) return '-'
+    return `${Number(value).toFixed(2)}%`
+  }),
+
+  date: createCellRenderer((value) => {
+    if (!value) return '-'
+    const date = new Date(value)
+    return date.toLocaleDateString()
+  }),
+
+  datetime: createCellRenderer((value) => {
+    if (!value) return '-'
+    const date = new Date(value)
+    return date.toLocaleString()
+  }),
+
+  boolean: createCellRenderer((value) => {
+    if (value === null || value === undefined) return '-'
+    return value ? 'Yes' : 'No'
+  }),
+
+  badge: createCellRenderer((value, row, options?: { variant?: 'default' | 'success' | 'warning' | 'error' }) => {
+    if (!value) return null
+    return value
+  }),
+
+  truncate: createCellRenderer((value, row, options?: { maxLength?: number }) => {
+    if (!value) return '-'
+    const str = String(value)
+    const maxLength = options?.maxLength || 50
+    if (str.length <= maxLength) return str
+    return `${str.substring(0, maxLength)}...`
+  }),
+
+  array: createCellRenderer((value, row, options?: { separator?: string; maxItems?: number }) => {
+    if (!Array.isArray(value) || value.length === 0) return '-'
+    const maxItems = options?.maxItems || value.length
+    const items = value.slice(0, maxItems)
+    const separator = options?.separator || ', '
+    const display = items.join(separator)
+    if (value.length > maxItems) {
+      return `${display} +${value.length - maxItems} more`
+    }
+    return display
+  }),
+}
+
+export function combineRenderers<TData = any>(
+  ...renderers: CellRenderer<TData>[]
+): CellRenderer<TData> {
+  return (value, row) => {
+    for (const renderer of renderers) {
+      const result = renderer(value, row)
+      if (result !== null && result !== undefined) {
+        return result
+      }
+    }
+    return value
+  }
+}

package/src/components/unified-table/utils/themes.ts

@@ -0,0 +1,87 @@
+export interface TableTheme {
+  name: string
+  container: string
+  header: string
+  headerCell: string
+  body: string
+  row: string
+  rowHover: string
+  rowSelected: string
+  cell: string
+  pagination: string
+  emptyState: string
+  mobileCard: string
+  mobileCardHeader: string
+  mobileCardContent: string
+}
+
+export const defaultTheme: TableTheme = {
+  name: 'default',
+  container: 'w-full',
+  header: 'bg-muted/50',
+  headerCell: 'px-4 py-3 text-left text-sm font-medium text-muted-foreground',
+  body: '',
+  row: 'border-b transition-colors',
+  rowHover: 'hover:bg-muted/50',
+  rowSelected: 'bg-primary/10 border-primary',
+  cell: 'px-4 py-3 text-sm',
+  pagination: 'flex items-center justify-between px-4 py-3 border-t',
+  emptyState: 'flex items-center justify-center py-12 text-muted-foreground',
+  mobileCard: 'rounded-lg border bg-card shadow-sm',
+  mobileCardHeader: 'p-4 pb-2',
+  mobileCardContent: 'p-4 pt-2',
+}
+
+export const compactTheme: TableTheme = {
+  ...defaultTheme,
+  name: 'compact',
+  headerCell: 'px-2 py-2 text-left text-xs font-medium text-muted-foreground',
+  cell: 'px-2 py-2 text-xs',
+  pagination: 'flex items-center justify-between px-2 py-2 border-t',
+  mobileCardHeader: 'p-3 pb-1',
+  mobileCardContent: 'p-3 pt-1',
+}
+
+export const spaciousTheme: TableTheme = {
+  ...defaultTheme,
+  name: 'spacious',
+  headerCell: 'px-6 py-4 text-left text-sm font-medium text-muted-foreground',
+  cell: 'px-6 py-4 text-sm',
+  pagination: 'flex items-center justify-between px-6 py-4 border-t',
+  mobileCardHeader: 'p-6 pb-3',
+  mobileCardContent: 'p-6 pt-3',
+}
+
+export const minimalTheme: TableTheme = {
+  ...defaultTheme,
+  name: 'minimal',
+  header: '',
+  headerCell: 'px-4 py-3 text-left text-sm font-semibold',
+  row: 'border-b border-border/50',
+  rowHover: 'hover:bg-muted/30',
+  mobileCard: 'rounded-lg border border-border/50 bg-card',
+}
+
+export const themes = {
+  default: defaultTheme,
+  compact: compactTheme,
+  spacious: spaciousTheme,
+  minimal: minimalTheme,
+}
+
+export type ThemeName = keyof typeof themes
+
+export function getTheme(themeName: ThemeName = 'default'): TableTheme {
+  return themes[themeName] || defaultTheme
+}
+
+export function createCustomTheme(
+  baseTheme: ThemeName = 'default',
+  overrides: Partial<TableTheme>
+): TableTheme {
+  return {
+    ...themes[baseTheme],
+    ...overrides,
+    name: overrides.name || `custom-${baseTheme}`,
+  }
+}

package/src/components/unified-table/utils/validation.ts

@@ -0,0 +1,122 @@
+import { MobileCardConfig } from '../components/MobileView/types'
+
+export interface ValidationResult {
+  valid: boolean
+  errors: string[]
+  warnings: string[]
+}
+
+export function validateMobileCardConfig<TData = any>(
+  config: MobileCardConfig<TData>
+): ValidationResult {
+  const errors: string[] = []
+  const warnings: string[] = []
+
+  if (!config.titleKey && !config.titleRender) {
+    errors.push('Mobile card config must have either titleKey or titleRender')
+  }
+
+  if (!config.primaryFields || config.primaryFields.length === 0) {
+    warnings.push('Mobile card config has no primary fields defined')
+  }
+
+  if (config.primaryFields) {
+    config.primaryFields.forEach((field, index) => {
+      if (!field.key && !field.render) {
+        errors.push(`Primary field at index ${index} must have either key or render function`)
+      }
+    })
+  }
+
+  if (config.secondaryFields) {
+    config.secondaryFields.forEach((field, index) => {
+      if (!field.key && !field.render) {
+        errors.push(`Secondary field at index ${index} must have either key or render function`)
+      }
+    })
+  }
+
+  if (config.actions) {
+    config.actions.forEach((action, index) => {
+      if (!action.id) {
+        errors.push(`Action at index ${index} must have an id`)
+      }
+      if (!action.onClick) {
+        errors.push(`Action '${action.id || index}' must have an onClick handler`)
+      }
+      if (!action.label && !action.icon) {
+        warnings.push(`Action '${action.id || index}' should have either a label or icon`)
+      }
+    })
+  }
+
+  if (config.showSelection && !config.onSelectionChange) {
+    warnings.push('showSelection is enabled but onSelectionChange handler is not provided')
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  }
+}
+
+export function validateColumnConfig(columns: any[]): ValidationResult {
+  const errors: string[] = []
+  const warnings: string[] = []
+
+  if (!columns || columns.length === 0) {
+    errors.push('At least one column must be defined')
+    return { valid: false, errors, warnings }
+  }
+
+  const columnIds = new Set<string>()
+
+  columns.forEach((column, index) => {
+    if (!column.id && !column.accessorKey) {
+      errors.push(`Column at index ${index} must have either id or accessorKey`)
+    }
+
+    const columnId = column.id || column.accessorKey
+
+    if (columnIds.has(columnId)) {
+      errors.push(`Duplicate column id: '${columnId}'`)
+    }
+    columnIds.add(columnId)
+
+    if (!column.header && !column.hideHeader) {
+      warnings.push(`Column '${columnId}' has no header defined`)
+    }
+
+    if (!column.cell && !column.accessorKey && !column.accessorFn) {
+      warnings.push(`Column '${columnId}' has no way to access data (missing cell, accessorKey, or accessorFn)`)
+    }
+  })
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  }
+}
+
+export function logValidationResults(
+  configName: string,
+  result: ValidationResult,
+  throwOnError: boolean = false
+): void {
+  if (result.errors.length > 0) {
+    console.error(`[${configName}] Validation Errors:`, result.errors)
+    if (throwOnError) {
+      throw new Error(`${configName} validation failed: ${result.errors.join(', ')}`)
+    }
+  }
+
+  if (result.warnings.length > 0) {
+    console.warn(`[${configName}] Validation Warnings:`, result.warnings)
+  }
+
+  if (result.valid && result.warnings.length === 0) {
+    console.log(`[${configName}] Configuration is valid`)
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+// Main entry point for @startsimpli/ui package
+export * from './components'
+export * from './utils'
+export * from './theme'
+export { THEME_TOKENS } from './theme/contract'
+export type { ThemeColorTokens, ThemeShapeTokens, ThemeToken } from './theme/contract'

package/src/lib/utils.ts

@@ -0,0 +1 @@
+export { cn } from '../utils/cn'

package/src/theme/contract.ts

@@ -0,0 +1,46 @@
+/** All CSS custom property names that apps must define in their theme */
+export const THEME_TOKENS = {
+  colors: [
+    '--background',
+    '--foreground',
+    '--card',
+    '--card-foreground',
+    '--popover',
+    '--popover-foreground',
+    '--primary',
+    '--primary-foreground',
+    '--secondary',
+    '--secondary-foreground',
+    '--muted',
+    '--muted-foreground',
+    '--accent',
+    '--accent-foreground',
+    '--destructive',
+    '--destructive-foreground',
+    '--border',
+    '--input',
+    '--ring',
+  ],
+  shape: [
+    '--radius',
+    '--radius-sm',
+    '--radius-md',
+    '--radius-lg',
+    '--radius-xl',
+    '--radius-full',
+  ],
+  shadows: ['--shadow-sm', '--shadow-md', '--shadow-lg', '--shadow-xl'],
+  typography: ['--font-sans', '--font-mono', '--font-heading'],
+  animation: ['--duration-fast', '--duration-normal', '--duration-slow', '--easing-default'],
+  borders: ['--border-width'],
+} as const
+
+export type ThemeColorTokens = (typeof THEME_TOKENS.colors)[number]
+export type ThemeShapeTokens = (typeof THEME_TOKENS.shape)[number]
+export type ThemeToken =
+  | ThemeColorTokens
+  | ThemeShapeTokens
+  | (typeof THEME_TOKENS.shadows)[number]
+  | (typeof THEME_TOKENS.typography)[number]
+  | (typeof THEME_TOKENS.animation)[number]
+  | (typeof THEME_TOKENS.borders)[number]

package/src/theme/index.ts

@@ -0,0 +1,9 @@
+// Export Tailwind config for apps to extend (legacy CJS config)
+export { default as tailwindConfig } from './tailwind.config'
+
+// Export TypeScript preset — the canonical way for apps to extend the design system
+export { default as tailwindPreset } from './tailwind.preset'
+
+// Design token contract — all CSS variables apps must define
+export { THEME_TOKENS } from './contract'
+export type { ThemeColorTokens, ThemeShapeTokens, ThemeToken } from './contract'

package/src/theme/tailwind.config.js

@@ -0,0 +1,70 @@
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  darkMode: ["class"],
+  theme: {
+    container: {
+      center: true,
+      padding: "2rem",
+      screens: {
+        "2xl": "1400px",
+      },
+    },
+    extend: {
+      colors: {
+        border: "hsl(var(--border))",
+        input: "hsl(var(--input))",
+        ring: "hsl(var(--ring))",
+        background: "hsl(var(--background))",
+        foreground: "hsl(var(--foreground))",
+        primary: {
+          DEFAULT: "hsl(var(--primary))",
+          foreground: "hsl(var(--primary-foreground))",
+        },
+        secondary: {
+          DEFAULT: "hsl(var(--secondary))",
+          foreground: "hsl(var(--secondary-foreground))",
+        },
+        destructive: {
+          DEFAULT: "hsl(var(--destructive))",
+          foreground: "hsl(var(--destructive-foreground))",
+        },
+        muted: {
+          DEFAULT: "hsl(var(--muted))",
+          foreground: "hsl(var(--muted-foreground))",
+        },
+        accent: {
+          DEFAULT: "hsl(var(--accent))",
+          foreground: "hsl(var(--accent-foreground))",
+        },
+        popover: {
+          DEFAULT: "hsl(var(--popover))",
+          foreground: "hsl(var(--popover-foreground))",
+        },
+        card: {
+          DEFAULT: "hsl(var(--card))",
+          foreground: "hsl(var(--card-foreground))",
+        },
+      },
+      borderRadius: {
+        lg: "var(--radius)",
+        md: "calc(var(--radius) - 2px)",
+        sm: "calc(var(--radius) - 4px)",
+      },
+      keyframes: {
+        "accordion-down": {
+          from: { height: 0 },
+          to: { height: "var(--radix-accordion-content-height)" },
+        },
+        "accordion-up": {
+          from: { height: "var(--radix-accordion-content-height)" },
+          to: { height: 0 },
+        },
+      },
+      animation: {
+        "accordion-down": "accordion-down 0.2s ease-out",
+        "accordion-up": "accordion-up 0.2s ease-out",
+      },
+    },
+  },
+  plugins: [require("tailwindcss-animate")],
+}