Data to UI¶

Overview¶

Patterns for transforming static data into type-safe React components. This skill covers JSON → TypeScript → React pipelines with emphasis on semantic color systems, derived types, and formatting utilities.

Workflows¶

1. JSON Schema → TypeScript Types¶

[ ] Read JSON schema/data structure
[ ] Create base TypeScript interfaces matching JSON shape
[ ] Export union types for enums (e.g., type Severity = 'safety_hazard' | 'repair_needed')
[ ] Use optional properties (?) for nullable/missing fields
[ ] Add JSDoc comments for complex types

2. Derived Types for UI¶

[ ] Create composed types extending base types with extends
[ ] Use Pick<T, K> and Omit<T, K> for component props
[ ] Build intersection types with & for joined data (e.g., FindingWithAsset)
[ ] Create aggregate interfaces for statistics/summaries

3. Color Mapping Systems¶

[ ] Define Record<EnumType, ColorValue> for semantic colors
[ ] Provide multiple color formats: badge, bg, text, border, dot
[ ] Use Tailwind utility classes (e.g., 'bg-red-500 text-red-600')
[ ] Export accessor functions (e.g., getSeverityColors())
[ ] Document color choices with comments

4. Icon Mapping¶

[ ] Create Record<EnumType, string> mapping to lucide-react icon names
[ ] Use PascalCase icon names (e.g., 'AlertTriangle', 'Thermometer')
[ ] Export accessor function (e.g., getSeverityIcon())

5. Formatting Utilities¶

[ ] Currency: Use Intl.NumberFormat with USD, no decimals
[ ] Dates: Use toLocaleDateString with short month format
[ ] Calculations: Create helpers for years, percentages, lifespans
[ ] Labels: Create human-readable label maps

6. Aggregation & Grouping¶

[ ] Implement groupBy patterns using reduce or forEach
[ ] Sort with custom comparators using severity/priority order
[ ] Calculate summary statistics (min, max, avg, count)
[ ] Return strongly-typed aggregates

Reference Implementation¶

Color Mapping System¶

// Single source of truth for semantic colors
export interface SeverityColors {
  badge: string;  // 'text-red-600 bg-red-100'
  bg: string;     // 'bg-red-500'
  text: string;   // 'text-red-600'
  border: string; // 'border-red-500'
  dot: string;    // 'bg-red-500'
}

const SEVERITY_COLOR_MAP: Record<Severity, SeverityColors> = {
  safety_hazard: {
    badge: 'text-red-600 bg-red-100',
    bg: 'bg-red-500',
    text: 'text-red-600',
    dot: 'bg-red-500',
    border: 'border-red-500',
  },
  // ... other severities
};

export function getSeverityColors(severity: Severity): SeverityColors {
  return SEVERITY_COLOR_MAP[severity];
}

Icon Mapping¶

export function getSeverityIcon(severity: Severity): string {
  const icons: Record<Severity, string> = {
    safety_hazard: 'AlertTriangle',
    repair_needed: 'Wrench',
    maintenance_item: 'Settings',
    monitor: 'Eye',
    informational: 'Info'
  };
  return icons[severity];
}

Derived Types¶

// Base type
export interface Finding {
  id: string;
  assetId?: string | null;
  severity: Severity;
  title: string;
}

// Derived type with relationship
export interface FindingWithAsset extends Finding {
  asset?: Asset;
}

// Aggregate type
export interface PropertyWithDetails {
  property: Property;
  inspectionReport: InspectionReport;
  findings: Finding[];
  assets: Asset[];
}

Formatting Utilities¶

export function formatCurrency(value: number): string {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: 'USD',
    minimumFractionDigits: 0,
    maximumFractionDigits: 0
  }).format(value);
}

export function formatDate(dateString: string): string {
  return new Date(dateString).toLocaleDateString('en-US', {
    year: 'numeric',
    month: 'short',
    day: 'numeric'
  });
}

export function yearsSince(dateString: string): number {
  const date = new Date(dateString);
  const now = new Date();
  return Math.floor((now.getTime() - date.getTime()) / (365.25 * 24 * 60 * 60 * 1000));
}

Aggregation Patterns¶

// Group by enum value
export function groupFindingsBySeverity(findings: Finding[]): Record<Severity, Finding[]> {
  const grouped: Record<Severity, Finding[]> = {
    safety_hazard: [],
    repair_needed: [],
    maintenance_item: [],
    monitor: [],
    informational: []
  };

  findings.forEach(f => grouped[f.severity].push(f));
  return grouped;
}

// Sort by priority
export function sortFindingsBySeverity(findings: Finding[]): Finding[] {
  const severityOrder: Record<Severity, number> = {
    safety_hazard: 0,
    repair_needed: 1,
    maintenance_item: 2,
    monitor: 3,
    informational: 4
  };
  return [...findings].sort((a, b) =>
    severityOrder[a.severity] - severityOrder[b.severity]
  );
}

Best Practices¶

Single Source of Truth: All color/icon mappings in one place with accessor functions
Multi-Format Colors: Provide badge, bg, text, border, dot variants for flexibility
Type Safety: Use Record<EnumType, Value> instead of plain objects
Intl APIs: Use Intl.NumberFormat and Intl.DateTimeFormat for localization
Immutability: Use spread operator when sorting/filtering arrays
Documentation: Add JSDoc comments explaining color choices and data structures
Colocate Utilities: Keep types and utilities in same file for easy import

Anti-Patterns¶

DO NOT use generic color names without semantic meaning (e.g., 'red' instead of 'safety_hazard')
DO NOT inline color classes in components; always use mapping functions
DO NOT use any types; prefer unknown and type guards
DO NOT mutate input arrays in sort/filter functions; always create copies
DO NOT hardcode date formats; use Intl.DateTimeFormat for consistency
DO NOT create separate files for simple utilities; colocate with types
DO NOT forget to handle null/undefined in optional fields
DO NOT use snake_case or kebab-case for TypeScript file names; use camelCase

Feedback Loops¶

Type Checking: Run tsc --noEmit to validate types
Runtime Validation: Consider Zod for JSON schema validation at runtime
Visual Testing: Build Storybook stories to verify color systems
Data Consistency: Compare aggregated stats with source data counts
Import Verification: Ensure all utilities are exported and importable

interface-design - Use color systems in React components
refactoring-code - Consolidate duplicate color/formatting logic