Property Manager

Overview

The Property Manager library is a powerful tool for managing and transforming React component props. It provides a structured way to handle complex component structures, redirect props to appropriate child components, and simplify component testing by analyzing prop interactions and results.

Key Features

• Prop Transformation: Convert incoming props into appropriate styles and properties
• Manage Design Systems: Better supporting Design systems
• Component Inheritance: Extend existing property managers to create new components
• Child Component Management: Define and manage props for child components
• Pattern Matching: Transform props based on patterns
• Provider Integration: Connect to dynamic data sources
• Testing Support: Simplified testing of component prop behaviors

Core Concepts

PropertyManager

The PropertyManager is the core class responsible for managing component prop transformations. Its key features include:

1. Separate Style and Prop Management

   • Allows independent control of styles and props transformations
   • Uses distinct .styles() and .props() methods for clear separation

2. Sequential Processing

   • Transformations are applied in the order they are defined
   • Later transformations can override earlier ones
   • This enables flexible layering of properties

3. Component Creation and Inheritance

const grid = PropertyManager.create('Grid')
  .styles(
    // Style transformations
  )
  .props(
    // Props transformations
  );

const box = PropertyManager.create('Box')
  .extends('Grid')  // Inheritance
  .styles(
    // Additional style transformations
  )
  .props(
    // Props transformations
  );

4. Transformation Order

   • Base component transformations are applied first
   • Extended component transformations are applied afterward
   • Final output combines all transformations in sequence

5. Usage Benefits

   • Promotes clean and maintainable code structure
   • Enables component composition through inheritance
   • Provides predictable prop transformation behavior
   • Simplifies complex styling patterns

This structure makes PropertyManager ideal for:

• Building consistent component libraries
• Managing complex styling systems
• Creating extensible component hierarchies
• Maintaining clear separation of styling and behavioral props

Style and Prop Transformers

The transformation system provides different ways to convert input props into desired output formats. Here's a detailed breakdown of the Prop transformer:

Prop

The Prop transformer is a versatile tool that can handle prop transformations in three main ways:

1. Single Prop Renaming

   Prop('color', 'backgroundColor')

• Input: { color: 'blue' }
• Output: { backgroundColor: 'blue' }
• Process:
  1. Takes the value from input prop 'color'
  2. Creates new property with name 'backgroundColor'
  3. Assigns the original value to the new property

2. Multiple Props Pass-through

   Prop(['borderColor', 'borderWidth'])

• Input: { borderColor: 'black', borderWidth: 2 }
• Output: { borderColor: 'black', borderWidth: 2 }
• Process:
  1. Takes an array of prop names
  2. Creates identical properties in output
  3. Copies values directly without transformation
  4. If a prop is missing in input, it's skipped in output

3. Custom Transformation Function

   Prop('color', ({color}) => ({ backgroundColor: color, borderColor: color }))

• Input: { color: 'red' }
• Output: { backgroundColor: 'red', borderColor: 'red' }
• Process:
  1. Takes input prop name ('color')
  2. Executes transformation function with props object
  3. Function can return complex object with multiple properties
  4. Allows for computed values and conditional logic

Advanced Features

1. Value Processing

   Prop('size', (props) => ({
     width: props.size * 2,
     height: props.size * 2
   }))

• Input: { size: 10 }
• Output: { width: 20, height: 20 }
• Allows mathematical operations and complex calculations

2. Conditional Transformations

   Prop('variant', ({variant, disabled}) => ({
     backgroundColor: disabled ? 'grey' : variant === 'primary' ? 'blue' : 'white'
   }))

• Input: { variant: 'primary', disabled: true }
• Output: { backgroundColor: 'grey' }
• Can access multiple props for conditional logic

3. Type Safety
   • Preserves TypeScript type information
   • Provides autocomplete for prop names
   • Validates prop types during transformation

This transformation system enables:

• Clean prop mapping
• Complex computed values
• Conditional styling
• Type-safe transformations
• Reusable transformation logic

The transformer can be used in both and methods, allowing for separation of visual styles from behavioral properties while using the same powerful transformation capabilities. .styles() .props()

Static

Applies constant styles or props:

Static({
  minHeight: 48,
  overflow: 'hidden'
})

Pattern

The Pattern transformer is a powerful tool that generates multiple prop transformations using a template system. It's particularly useful for creating consistent, systematic prop mappings.

Core Concepts

1. Pattern Definition

   Pattern('{placeholder}', valuesObject)

• First argument: pattern template with placeholders
• Second argument: object containing possible values
• Returns a pattern builder for defining transformations

2. Value Mapping

   const spacing = {
       s: 8,
       m: 16,
       l: 24,
   }

• Values object defines all possible substitutions
• Keys become available for placeholder substitution
• Values are used in the resulting transformations

3. Key Definition

   Pattern('{size}', spacing)
     .key('margin-{size}', 'margin')
     .key('padding-{size}', 'padding')

• .key() defines transformation rules
• First argument: input prop pattern
• Second argument: output property name

Transformation Process

1. Pattern Recognition

   • Identifies placeholders in curly braces {}
   • Matches placeholders with values object keys
   • Creates combinations for each possible value

2. Property Generation

   // Input pattern
   .key('m-{size}', 'margin')
   
   // Generates transformations for:
   // m-s  → { margin: 8 }
   // m-m  → { margin: 16 }
   // m-l  → { margin: 24 }

3. Multiple Patterns
   • Can define multiple .key() patterns
   • Each pattern generates its own set of transformations
   • All transformations are combined into final result

Benefits

1. Reduced Boilerplate

   • Generates multiple transformations from single pattern
   • Eliminates repetitive transformer definitions
   • Maintains consistency across related properties

2. Systematic Approach

   • Creates predictable naming patterns
   • Ensures consistent value mapping
   • Makes style systems more maintainable

3. Flexible Configuration

   • Easy to modify value sets
   • Simple to add new patterns
   • Supports complex transformation logic

The Pattern transformer is especially useful for:

• Design systems with systematic spacing
• Responsive design properties
• Consistent naming conventions
• Scale-based property systems

Provider

The Provider system is a mechanism for connecting transformers to dynamic data sources, enabling real-time updates of component properties based on changing values.

Core Components

1. Provider Registration

   PropertyManager.registerProvider(
     name: string,
     getData: () => any,
     subscribeToChanges?: (callback: () => void) => void
   )

• name: Unique identifier for the provider
• getData: Function that returns current provider data
• subscribeToChanges: Optional function to listen for data changes

2. Provider Usage

   Provider(
     providerName: string,
     transformerFactory: (data: any) => Transformer
   )

• providerName: References registered provider
• transformerFactory: Function that creates transformer using provider data

How It Works

1. Registration Process

   // Data structure
   interface Theme {
     colors: Record<string, string>;
     spacing: Record<string, number>;
   }

   // Provider setup
   const themeProvider = {
     data: initialTheme,
     eventEmitter: new EventEmitter()
   };

   // Registration
   PropertyManager.registerProvider(
     'theme',
     () => themeProvider.data,
     (onChange) => themeProvider.eventEmitter.subscribe(onChange)
   );

2. Data Flow

   // Creating transformer with provider
   const componentStyles = PropertyManager.create('Component')
     .styles(
       Provider('theme', (theme) => 
         Prop('variant', ({variant}) => ({
           backgroundColor: theme.colors[variant]
         }))
       )
     );

   // Using component
   const styles = componentStyles.get({ variant: 'primary' });
   // → { backgroundColor: 'white' }

   // When theme changes
   themeProvider.data = newTheme;
   themeProvider.eventEmitter.emit();
   // → Automatically updates all dependent components

3. Update Mechanism
   1. Provider data changes
   2. Provider emits change event
   3. PropertyManager receives notification
   4. All transformers using this provider are re-evaluated
   5. Components using these transformers get updated properties

Use Cases

1. Theming

   • Dynamic color schemes
   • Light/dark mode switching
   • Brand theme variations

2. Responsive Design

   • Screen size-based adjustments
   • Device-specific styling
   • Orientation changes

3. Feature Flags

   • Component variants
   • Experimental features
   • A/B testing

4. Localization

   • RTL/LTR layouts
   • Language-specific spacing
   • Cultural adaptations

The Provider system enables:

• Dynamic styling updates
• Theme switching
• Responsive adaptations
• Real-time feature toggles
• Performance optimizations through selective updates

Child Components

The Child Components system provides a structured way to manage props for complex components with multiple nested elements. It handles prop distribution and transformation for each child component independently.

Core Concepts

1. Child Definition

   Child(name: string)
     .extends(parentName: string)
     .props(...transformers)
     .styles(...transformers)

Components:

• name: Unique identifier for the child
• props: Prop transformers specific to this child
• styles: Style transformers for this child
• extends: Inherit from another component's transformations, reusing transformers

1. Props Distribution

   const componentProps = PropertyManager.create('Component')
     .styles(rootStyles)
     .props(rootProps)
     .child(
       Child('childA').props(childAProps),
       Child('childB').props(childBProps)
     )

How It Works

1. Transformation Process

   const result = componentProps.get({
     color: 'primary',
     children: 'Text',
     Icon: 'star'
   });

   // Result structure:
   {
     // Root component props
     prop: { ... },
     style: { ... },
     
     // Child components props
     props: {
       childA: { ... },
       childB: { ... },
     },
     styles: {
       childA: { ... },
       childB: { ... },
     }
   }

1. Prop Flow

   1. Input props are received
   2. Root transformers process props first
   3. Each child processes relevant props
   4. Results are organized by component hierarchy

2. Usage in Components

   function ComplexComponent(props) {
     const {
       // Root props
       prop: rootProps,
       style: rootStyle,
       
       // Child props
       props: {
         icon: iconProps,
         text: textProps
       }
     } = componentProps.get(props);

     return (
       <Root {...rootProps} style={rootStyle}>
         <Icon {...iconProps} />
         <Text {...textProps} />
       </Root>
     );
   }

Advanced Features

1. Prop Inheritance

   Child('text')
     .extends('Typography')
     .props(
       // Additional props specific to this usage
     )

• Inherit transformations from other components
• Override or extend inherited props
• Maintain consistency across components

1. Conditional Child Props

   Child('icon').props(
     Prop('visible', ({hasIcon}) => ({
       display: hasIcon ? 'flex' : 'none'
     }))
   )

• Transform props based on conditions
• Dynamic child component behavior
• Responsive to parent state

1. Style Organization

   Child('container')
     .styles(
       // Layout styles
       Static({ display: 'flex' }),
       Prop('direction', 'flexDirection'),
       
       // Spacing
       Pattern('{size}', spacing)
         .key('gap-{size}', 'gap'),
       
       // Visual
       Prop('variant', ({variant, theme}) => ({
         backgroundColor: theme.colors[variant]
       }))
     )

• Grouped style transformations
• Clear separation of concerns
• Maintainable style structure

Benefits

1. Organized Prop Management

   • Clear hierarchy of components
   • Structured prop distribution
   • Isolated child component logic

2. Reusability

   • Share transformations between components
   • Consistent prop handling
   • Reduced code duplication

3. Maintainability

   • Isolated child component changes
   • Clear prop flow
   • Easy debugging

4. Type Safety

   • TypeScript support
   • Prop validation
   • IDE autocompletion

This system is particularly useful for:

• Complex compound components
• Reusable component libraries
• Design systems
• Components with multiple variants
• Nested component structures

The Child Components system provides a powerful way to manage complex component hierarchies while maintaining clean, maintainable code.

Benefits

1. Structured Prop Management: Organizes prop handling logic in a declarative way
2. Component Reusability: Easily extend existing components with new behaviors
3. Enhanced Testability: Test component prop transformations without rendering
4. Dynamic Styling: Connect to theme providers and other dynamic data sources
5. Simplified Complex Components: Manage multi-level component structures with clarity
6. Pattern-Based Props: Create consistent prop interfaces using patterns
7. Separation of Concerns: Clear separation between prop handling and rendering

Testing

The Property Manager provides robust testing features that make it easy to verify prop transformations and component behavior.

Core Testing Features

1. Prop Transformation Testing

   const componentPM = PropertyManager.create('Component')
     .styles(...)
     .props(...)

   test('verifies prop transformations', () => {
     const result = componentPM.get({
       variant: 'primary',
       size: 'large'
     });

     expect(result).toMatchObject({
       style: {
         // Style transformations
       },
       props: {
         // Prop transformations
       }
     });
   });

1. Child Component Testing

   test('child components receive correct props', () => {
     const result = componentPM.get(inputProps);

     expect(result.props.icon).toMatchObject({
       // Icon-specific props
     });
     expect(result.props.text).toMatchObject({
       // Text-specific props
     });
   });

Testing Strategies

1. Unit Testing Transformers

   • Test individual prop transformations
   • Verify style calculations
   • Check conditional logic

2. Integration Testing

   • Test multiple transformers together
   • Verify provider interactions
   • Check child component prop flow

3. Snapshot Testing

   • Capture full transformation results
   • Track changes over time
   • Ensure consistent behavior

Benefits of Property Manager

1. Development Experience

• Clear prop transformation syntax
• Type-safe prop handling
• Predictable component behavior
• Easy debugging and testing

2. Code Organization

• Separation of concerns
• Reusable transformations
• Structured prop management
• Maintainable component logic

3. Performance

• Optimized prop calculations
• Efficient updates
• Minimal re-renders
• Scalable architecture

4. Maintainability

• Centralized prop management
• Clear transformation flow
• Easy to modify and extend
• Consistent patterns

5. Component Systems

• Design system integration
• Theme management
• Responsive design
• Dynamic styling

Best Practices

1. Transformer Organization

   • Group related transformations
   • Use meaningful names
   • Keep transformations simple
   • Document complex logic

2. Testing Strategy

   • Test all transformation paths
   • Verify edge cases
   • Include provider testing
   • Use snapshot testing

3. Code Structure

   • Separate styling from behavior
   • Use child components appropriately
   • Leverage providers for dynamic data
   • Keep transformations pure

4. Performance Considerations

   • Minimize complex calculations
   • Use memoization when needed
   • Optimize provider updates
   • Profile transformation performance

Use Cases

1. Component Libraries

   • Consistent interfaces
   • Reusable patterns
   • Maintainable code
   • Clear documentation

2. Design Systems

   • Theme management
   • Style consistency
   • Component variants
   • Dynamic updates

3. Complex Applications

   • Organized prop handling
   • Clear component hierarchy
   • Testable components
   • Maintainable code base

The Property Manager library provides a solid foundation for building scalable, maintainable React applications with well-organized prop management and clear testing strategies.