Skip to content

COMPONENT_SYSTEM_GAP_ANALYSIS.md

Latest commit

 

History

History
231 lines (176 loc) · 7.03 KB

COMPONENT_SYSTEM_GAP_ANALYSIS.md

File metadata and controls

231 lines (176 loc) · 7.03 KB

Component System Gap Analysis

Overview

This document compares the existing implementation with the requirements from the feature specification documents.

Current Implementation Analysis

What Exists

1. HTML Element System

  • Current: Single generic HTMLElement class that takes tag name as parameter
  • Implementation: Helper methods in HTMLHelpers module that create instances of the generic class
  • Coverage: ~30 HTML elements have helper methods

2. Component Architecture

  • Base Classes:
    • Component (abstract base)
    • StatelessComponent (with caching support)
    • StatefulComponent (with JavaScript support)
  • Features:
    • Basic attribute management
    • Component ID generation
    • CSS class tracking
    • Caching integration (basic)
    • JavaScript integration hooks

3. Caching System

  • Implemented:
    • CacheStore abstract class
    • TestCacheStore implementation
    • Cacheable module
    • ComponentCacheManager
    • Basic cache key generation
  • Missing:
    • Redis implementation
    • Russian doll caching
    • Cache warming

4. JavaScript System

  • Files Present:
    • component_manager.js - Basic component lifecycle management
    • component_registry.js - Component registration
    • component_system.js - System initialization and auto-discovery
    • stateful_component_js.js - Base class for JavaScript components
    • Some example components (counter, dropdown, toggle)
  • Analysis: This is a traditional component system, NOT the reactive WebSocket-based system specified
  • Missing:
    • WebSocket connection management
    • DOM morphing algorithm
    • Server state synchronization
    • Reactive updates

5. Integration

  • Stimulus renderer exists
  • CSS registry for tracking used classes
  • Basic asset pipeline integration

Gap Analysis

Critical Gaps

1. HTML Element Classes (HIGHEST PRIORITY)

Specification Requirement: Every HTML5 element must have its own dedicated Crystal class Current State: Generic HTMLElement class with tag name parameter Gap: Missing 100+ individual element classes

This is the fundamental architectural difference. The specification requires:

# Required approach - individual classes
class Div < HTMLElement
class Input < VoidElement  
class Form < HTMLElement

# Current approach - generic class
HTMLElement.container("div", content)

Impact: This is a complete architectural mismatch. The entire component system depends on having proper element classes.

2. Element Hierarchy

Required:

  • HTMLElement base class
  • VoidElement for self-closing elements
  • ContainerElement for elements with children
  • Individual classes inheriting from appropriate base

Current: Single generic class handling all elements

3. Attribute Validation

Required: Each element class validates its specific attributes per HTML5 spec Current: No attribute validation

4. Builder Pattern

Required: Elements support builder pattern for nested structures Current: Basic nesting through helper methods

Component System Gaps

1. Component Composition

Required: Components built by composing element class instances Current: Components use string-based tag generation methods

2. Reactive Components

Required: Full reactive system with WebSocket support Current: Basic stateful components with JavaScript hooks, no reactive system

Caching System Gaps

1. Redis Cache Store

Required: Production-ready Redis implementation Current: Only test implementation

2. Russian Doll Caching

Required: Parent components track child dependencies Current: Basic cache key generation only

3. Cache Warming

Required: Pre-render expensive components Current: Not implemented

Reactive System Gaps

1. Client-Side (amber-reactive.js)

Required:

  • WebSocket connection management
  • DOM morphing algorithm
  • Component registration
  • Event dispatching

Current: Basic component JavaScript, no reactive client

2. Server-Side

Required:

  • ReactiveSocket WebSocket handler
  • ReactiveSession management
  • State synchronization
  • Server-initiated updates

Current: Not implemented

Migration Strategy

Phase 1: Element System Overhaul (MUST DO FIRST)

  1. Keep existing HTMLHelpers temporarily for backwards compatibility

  2. Create new element class hierarchy:

    • Base classes: HTMLElement, VoidElement, ContainerElement
    • All 100+ individual element classes
    • Proper attribute validation

  3. Migration Path:

    # Old way (keep working)
HTMLHelpers.div(content, class: "card")

# New way (implement)
Div.new(class: "card") << content

Phase 2: Update Component Base Classes

  1. Modify Component base class to work with element classes
  2. Update StatelessComponent and StatefulComponent
  3. Create migration helpers

Phase 3: Complete Caching Implementation

  1. Implement RedisCacheStore
  2. Add Russian doll caching to Cacheable
  3. Implement cache warming

Phase 4: Build Reactive System

  1. Create amber-reactive.js from scratch
  2. Implement WebSocket handlers
  3. Create ReactiveStatefulComponent base class

Recommendations

Immediate Actions

  1. DO NOT try to retrofit the existing HTMLElement class
  2. CREATE entirely new element class hierarchy alongside existing code
  3. MAINTAIN backwards compatibility during transition
  4. FOCUS on getting all element classes implemented first

Architecture Decisions

  1. Namespace: Put new elements in Components::Elements namespace
  2. Backwards Compatibility: Keep HTMLHelpers working with deprecation warnings
  3. Progressive Migration: Allow mixing old and new approaches initially

Testing Strategy

  1. Element Tests: Every element class needs comprehensive tests
  2. Migration Tests: Ensure old code continues working
  3. Integration Tests: Test new components with new elements

File Structure Changes

Proposed New Structure

src/asset_pipeline/components/
  elements/           # NEW - All individual element classes
    base/            # NEW - Base element classes
      html_element.cr
      void_element.cr
      container_element.cr
    document/        # NEW - Html, Head, Body, etc.
    sections/        # NEW - Header, Footer, Nav, etc.
    grouping/        # NEW - Div, P, Span, etc.
    # ... other categories
    
  html/              # KEEP - For backwards compatibility
    html_element.cr  # Rename to generic_html_element.cr
    html_helpers.cr  # Add deprecation warnings
    
  reactive/          # NEW - Reactive system
    reactive_socket.cr
    reactive_session.cr
    reactive_component.cr

Next Steps

  1. Begin implementing base element classes (HTMLElement, VoidElement, ContainerElement)
  2. Start creating individual element classes by category
  3. Set up proper testing framework for elements
  4. Plan backwards compatibility strategy

Critical: No other work should proceed until the element class system is complete. This is the foundation everything else depends on.