low-code-react-app-b/JSON_COMPONENTS.md

JSON UI Components Registry

This document describes the JSON UI component system and lists all components that can be rendered from JSON schemas.

Overview

The JSON UI system allows you to define user interfaces using JSON schemas instead of writing React code. This is useful for:

• Dynamic UI generation
• No-code/low-code interfaces
• Configuration-driven UIs
• Rapid prototyping

Quick Start

List All JSON-Compatible Components

# List all components with details
npm run components:list

# List only supported components
npm run components:list -- --status=supported

# List only planned components
npm run components:list -- --status=planned

# Output as JSON
npm run components:list -- --format=json

Using JSON UI Components

Components are defined in the ComponentType union in src/types/json-ui.ts and registered in src/lib/json-ui/component-registry.tsx.

Example JSON schema:

{
  "id": "example-page",
  "type": "Card",
  "props": {
    "className": "p-6"
  },
  "children": [
    {
      "id": "heading",
      "type": "Heading",
      "props": {
        "level": 2,
        "children": "Welcome"
      }
    },
    {
      "id": "description",
      "type": "Text",
      "props": {
        "children": "This is a dynamically rendered component"
      }
    },
    {
      "id": "cta",
      "type": "Button",
      "props": {
        "variant": "default",
        "children": "Get Started"
      }
    }
  ]
}

Component Categories

Layout Components (12)

Container elements for organizing content:

• div, section, article, header, footer, main - HTML semantic elements
• Card - Container with optional header, content, and footer
• Grid - Responsive grid layout
• Stack - Vertical or horizontal stack layout
• Flex - Flexible box layout
• Container - Centered container with max-width
• Dialog - Modal dialog overlay

Input Components (11)

Form inputs and interactive controls:

• Button - Interactive button
• Input - Text input field
• TextArea - Multi-line text input
• Select - Dropdown select
• Checkbox - Checkbox toggle
• Radio - Radio button
• Switch - Toggle switch
• Slider - Numeric range slider
• NumberInput - Numeric input with increment/decrement
• DatePicker - Date selection (planned)
• FileUpload - File upload control (planned)

Display Components (16)

Presentation and visual elements:

• Heading - Heading text (h1-h6)
• Text - Text content with typography
• Label - Form label
• Badge - Status or count indicator
• Tag - Removable tag/chip
• Code - Inline or block code
• Image - Image with loading states
• Avatar - User avatar image
• Icon - Icon from library (planned)
• Progress - Progress bar
• Spinner - Loading spinner
• Skeleton - Loading placeholder
• Separator - Visual divider
• CircularProgress - Circular indicator (planned)
• ProgressBar - Linear progress (planned)
• Divider - Section divider (planned)

Navigation Components (3)

Navigation and routing:

• Link - Hyperlink element
• Breadcrumb - Navigation trail (planned)
• Tabs - Tabbed interface

Feedback Components (7)

Alerts, notifications, and status:

• Alert - Alert notification message
• InfoBox - Information box with icon
• EmptyState - Empty state placeholder
• StatusBadge - Status indicator
• StatusIcon - Status icon (planned)
• ErrorBadge - Error state (planned)
• Notification - Toast notification (planned)

Data Components (8)

Data display and visualization:

• List - Generic list renderer
• Table - Data table
• KeyValue - Key-value pair display
• StatCard - Statistic card
• DataList - Styled data list (planned)
• DataTable - Advanced table with sorting/filtering (planned)
• Timeline - Timeline visualization (planned)
• MetricCard - Metric display (planned)

Custom Components (3)

Domain-specific components:

• DataCard - Custom data display card
• SearchInput - Search input with icon
• ActionBar - Action button toolbar

Current Status

• Total Components: 60
• Supported: 46 (77%)
• Planned: 14 (23%)

Files

• json-components-registry.json - Complete registry with metadata
• src/types/json-ui.ts - TypeScript types and ComponentType union
• src/lib/json-ui/component-registry.tsx - Component registry mapping
• src/lib/component-definitions.ts - Component definitions with defaults
• scripts/list-json-components.cjs - CLI tool to list components

Adding New Components

To add a new component to the JSON UI system:

1. Add the component type to ComponentType union in src/types/json-ui.ts
2. Import and register it in src/lib/json-ui/component-registry.tsx
3. Add component definition in src/lib/component-definitions.ts
4. Update json-components-registry.json with metadata
5. Test the component in a JSON schema

JSON Compatibility Checklist

Before migrating a component, confirm all required conditions are met:

• Hooks/state are registry-safe: hooks and internal state are acceptable when the component registry can control or expose them through JSON bindings.
• Bindings are defined: any required actions, event handlers, or state bindings are already supported by the JSON UI binding system.
• Refactoring covered by PR: JSON compatibility gaps should be resolved via refactoring as part of the same pull request.

Step-by-Step Migration Path

Use this repeatable migration flow for planned components:

1. Update the type union in src/types/json-ui.ts to include the new component type name.
2. Register the component in src/lib/json-ui/component-registry.tsx so JSON schemas can resolve it at runtime.
3. Define component metadata in src/lib/component-definitions.ts (defaults, prop schema, and any JSON-driven constraints).
4. Validate JSON schema usage by rendering a sample schema that uses the new type.
5. Update registry metadata in json-components-registry.json so the CLI/listing reflects the new status.

Migration Strategy

Components marked as "planned" are:

• Available in the codebase as React components
• Not yet integrated into the JSON UI system
• Can be migrated following the steps above

Priority for migration:

1. High-usage components
2. Components with simple props
3. Components with good atomic design
4. Components without complex state management

Related Documentation

• PRD.md - Product requirements document
• REDUX_DOCUMENTATION.md - Redux integration
• src/types/json-ui.ts - Type definitions
• src/lib/component-definitions.ts - Component metadata