Skip to content

ANALYSIS_GUIDE.md

Latest commit

 

History

History
173 lines (118 loc) · 4.31 KB

ANALYSIS_GUIDE.md

File metadata and controls

173 lines (118 loc) · 4.31 KB

Effective Component Analysis Guide

Overview

The effectiveness of the Component Generator heavily depends on the quality and completeness of your component analysis. This guide explains what information sources make for the best analysis and how to gather them.

Key Information Sources

1. Component Source Code

  • Component implementation (.ts files)
  • Templates (inline or .html files)
  • Styles (.scss, .css files)
  • Type definitions and interfaces

2. Documentation Sources

Storybook (Preferred)

  • Component stories showing different states
  • Props documentation
  • Usage examples
  • Edge cases and variations
  • Interactive examples

Alternative Documentation

  • README files
  • JSDoc comments
  • API documentation
  • Design system documentation

3. Usage Examples

  • Real implementation examples from your codebase
  • Integration patterns
  • Service usage patterns
  • Common combinations with other components

4. Tests

  • Unit tests showing expected behavior
  • Integration tests showing component relationships
  • Test fixtures demonstrating prop combinations
  • Edge case handling

Why These Sources Matter

Each source provides unique insights that help the AI understand:

  1. Component Behavior

    • Source code shows implementation
    • Tests reveal edge cases
    • Stories demonstrate intended use

  2. Integration Patterns

    • Usage examples show real-world applications
    • Integration tests reveal component relationships
    • Service interactions demonstrate dependencies

  3. State Management

    • Source code shows internal state
    • Tests reveal state transitions
    • Stories demonstrate state variations

  4. Props and Events

    • Type definitions show API design
    • Stories show prop combinations
    • Tests validate event handling

Analyzing Components Without Storybook

If your project doesn't use Storybook, you can still get good results by focusing on:

  1. Test Coverage

    • Unit tests often contain comprehensive usage examples
    • Test fixtures show valid prop combinations
    • Integration tests reveal component relationships

  2. Code Comments

    • JSDoc comments documenting props and usage
    • Implementation comments explaining patterns
    • TODO comments indicating potential issues

  3. Real Usage

    • Find multiple instances of component usage
    • Look for different configurations
    • Document common patterns

  4. Type Definitions

    • Props and their types
    • Event definitions
    • Interfaces and enums

Best Practices

  1. Gather Multiple Examples

    • Don't rely on a single usage pattern
    • Look for edge cases and variations
    • Document both simple and complex uses

  2. Document Relationships

    • Note which components are often used together
    • Identify parent-child relationships
    • Map service dependencies

  3. Capture State Management

    • Document state initialization
    • Note state transitions
    • Record side effects

  4. Track Dependencies

    • List required imports
    • Note optional features
    • Document service requirements

Analysis Quality Checklist

✅ Have you included:

  • Complete component source code
  • Documentation (Storybook or alternatives)
  • At least 3 different usage examples
  • Test cases or fixtures
  • Type definitions
  • Service interactions (if applicable)
  • Common component combinations
  • State management patterns
  • Prop variations
  • Event handling examples

Common Pitfalls

  1. Insufficient Examples

    • Problem: Only analyzing the component in isolation
    • Solution: Find multiple real-world usage examples

  2. Missing Service Context

    • Problem: Not documenting service dependencies
    • Solution: Include service interaction patterns

  3. Incomplete State Analysis

    • Problem: Only capturing initial state
    • Solution: Document state transitions and effects

  4. Limited Pattern Recognition

    • Problem: Missing common combinations
    • Solution: Analyze multiple implementations

Impact on Generated Components

Better analysis leads to:

  • More accurate component generation
  • Better pattern matching
  • Proper service integration
  • Correct state management
  • Appropriate prop usage
  • Better type safety

Remember: The AI can only be as good as the analysis we provide. Comprehensive analysis leads to better generated components.