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

JSON Eligibility Checklist

Use this checklist during every conversion to determine whether a component can be safely represented in JSON.

Core requirements (must all be true)

• No side-effects: The component should be render-only; it must not perform data fetching, subscriptions, timers, or imperative DOM work. Side-effects belong in wrappers or higher-level orchestration.
• Supported bindings only: Props must map to supported JSON bindings (static values, expression bindings, or schema-recognized props). Avoid custom callbacks, ref usage, or passing functions through JSON.
• Stable props: Props should be serializable and deterministic (strings, numbers, booleans, arrays, objects). Avoid non-serializable values like class instances, functions, or dates unless explicitly supported by the JSON schema.

Derived state guidance

• Prefer pure derivation: If state can be derived from props or data bindings, compute it at render time in the renderer or via expression bindings rather than introducing component state.
• Avoid local state in JSON components: If a component needs internal state to function, wrap it in a React component and expose only the minimal, declarative props to JSON.
• Keep calculations explicit: Use named props (e.g., selectedCount, isComplete) rather than embedding complex logic that would need component state.

Event handler guidance

• Use schema-recognized actions: Wire events to supported JSON actions or expression handlers (e.g., onClick -> actions.navigate, actions.submit), not raw functions.
• Pass data, not closures: Event handlers should reference IDs, routes, or action payloads so the runtime can resolve them.
• Escalate complex logic: If an event handler needs branching logic or side-effects, move that logic into an app-level action or wrapper component and keep JSON props declarative.

Naming & Value Conventions

Use these conventions to keep JSON component schemas consistent and easy to validate.

Core naming rules

• id: Required, unique within a page or component subtree. Use kebab-case (panel-header, user-card) so IDs remain stable across tools and scripts.
• type: Must match a registered ComponentType or HTML element name exactly (case-sensitive). Avoid aliases or custom casing.
• props keys: Use camelCase for prop names (className, defaultValue, onClick). Avoid nesting children under multiple keys.

children rules

• Accepted values: Either a string (text-only) or an array of component objects.
• Do not mix: If children is an array, text content should be represented by a nested Text/Heading component.
• Prefer props.children only for leaf text: When a component has no nested child components, you can set props.children to a string. Do not set both children and props.children at the same time.

variant rules

Use variant for style tokens rather than ad-hoc CSS classes.

• Shadcn-style variants (buttons, badges, dialog actions):
  default, secondary, destructive, outline, ghost, link
• Feedback/status variants (alerts, toasts, status messaging):
  success, error, info, warning

size rules

• Dialog size:
  sm, md, lg, xl, full
• Token-based sizes (progress indicators, spinners, badges):
  sm, md, lg
• Numeric sizes (icons or pixel-based controls):
  Use a number (e.g., 16, 20, 24) when the component expects pixel sizes.

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
• FileUpload - File upload control

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
• ProgressBar - Linear progress
• Divider - Section divider

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: 51 (85%)
• Planned: 9 (15%)

Status Summary

Status	Count
Supported	51
Maybe	0
Planned	9

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

Deprecation & JSON Migration Process

Use this process when retiring legacy components or renaming JSON component types.

Deprecation workflow

1. Assess usage: Identify schemas and component usage (search in src/config/schemas or project JSON). Flag any external consumers.
2. Define a replacement: Ensure a supported JSON-safe replacement exists (or create a wrapper) and document prop differences.
3. Mark deprecated in the registry: Update json-components-registry.json with "status": "deprecated" and optional "deprecated" metadata:
   • replacedBy: the new component type to use.
   • message: extra guidance for migrations.
4. Update definitions: If needed, adjust src/lib/component-definitions.ts to align defaults and prop expectations for the replacement.
5. Communicate the change: Add a note to release documentation or changelog and note the replacement.
6. Set a removal window: Target the next minor/major release for removal once migration is complete.

JSON migration checklist

• Replace deprecated component types in schemas with their replacements.
• Validate props against the replacement component definition.
• Run JSON renderer previews to confirm layout and bindings.
• Remove any legacy bindings or props that are no longer supported.

Runtime warning mechanism

The schema renderer emits a console.warn when a deprecated component type appears in a JSON schema. This warning uses the metadata in json-components-registry.json to suggest replacements and highlight remediation guidance.

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