Skip to content

README.md

Latest commit

 

History

History
302 lines (217 loc) · 6.62 KB

README.md

File metadata and controls

302 lines (217 loc) · 6.62 KB

Sections Documentation

🎯 Overview

This directory contains comprehensive documentation for the Sections system in the Fynd Commerce App. Sections are reusable UI components that allow sellers to create customizable page templates through the Theme Editor.

📚 Documentation Index

Core Documentation

Quick Start

  1. Read the Overview: Start with Section Pages Overview to understand the system
  2. Follow the Guide: Use Creating Sections Guide for hands-on development
  3. Check Examples: Review existing sections in src/sections/ for reference

🏗️ System Architecture

Key Components

  • Section Pages: Dynamic pages that render multiple sections
  • Section Renderer: Component that handles section loading and rendering
  • Section Map: Registry of available sections
  • Navigation Tracker: Handles URL parsing and theme data fetching

Data Flow

User Navigation → URL Parsing → Theme Fetching → Section Rendering → Predicate Evaluation → UI Display

🧩 Section Types

Built-in Sections

  • Hero Image: Banner section with image, text, and call-to-action
  • Text Section: Simple text content display
  • Product Grid: Product listing with customizable layout
  • Custom Sections: Developer-created reusable components

Section Categories

  • Content Sections: Display text, images, and media
  • Interactive Sections: Buttons, forms, and user interactions
  • Layout Sections: Containers and structural elements
  • Data Sections: Display dynamic content from APIs

🛠️ Development Workflow

1. Planning

  • Define section purpose and functionality
  • Identify configuration requirements
  • Plan responsive behavior
  • Determine predicate needs

2. Development

  • Create section directory structure
  • Implement component logic
  • Define settings configuration
  • Add to section map

3. Testing

  • Unit test component functionality
  • Test configuration options
  • Verify responsive behavior
  • Validate predicate logic

4. Integration

  • Add to theme configuration
  • Test in Theme Editor
  • Deploy to staging
  • Monitor performance

📋 Section Requirements

Required Files

section-name/
├── index.ts              # Default export
├── section-name.tsx      # Main component
├── styles.ts            # Styled components
└── README.md            # Documentation

Required Exports

// Component export
export function SectionName({props, blocks}: any) {
  // Implementation
}

// Settings export
export const settings = {
  label: 'Section Display Name',
  props: [
    // Configuration schema
  ],
  blocks: [
    // Block configurations
  ],
};

🎨 Configuration Schema

Prop Types

  • text: Single line text input
  • textarea: Multi-line text input
  • image: Image upload/selection
  • url: URL input with validation
  • color: Color picker
  • select: Dropdown selection
  • checkbox: Boolean toggle
  • number: Numeric input
  • category: Category selection

Prop Structure

{
  type: "text",
  id: "heading",
  default: "Default Value",
  label: "User-Friendly Label",
  info: "Help text for users"
}

🔄 Predicate System

User Predicates

predicate: {
  user: {
    anonymous: true,    // Show for non-logged-in users
    authenticated: true // Show for logged-in users
  }
}

Screen Predicates

predicate: {
  screen: {
    mobile: true,  // Show on mobile devices
    tablet: true   // Show on tablet devices
  }
}

Platform Predicates

predicate: {
  platform: {
    ios: true,     // Show on iOS
    android: true  // Show on Android
  }
}

📱 Responsive Design

Breakpoints

  • Mobile: < 768px width
  • Tablet: ≥ 768px width

Best Practices

  • Design mobile-first
  • Use flexible layouts
  • Test on multiple devices
  • Handle orientation changes
  • Optimize for performance

🧪 Testing

Unit Testing

import {render, fireEvent} from '@testing-library/react-native';
import {MyCustomSection} from './my-custom-section';

describe('MyCustomSection', () => {
  it('renders correctly', () => {
    const {getByText} = render(<MyCustomSection {...mockProps} />);
    expect(getByText('Test Heading')).toBeTruthy();
  });
});

Integration Testing

  • Test section rendering in SectionRenderer
  • Verify predicate evaluation
  • Test configuration options
  • Validate navigation behavior

🚀 Performance Optimization

Best Practices

  • Use React.lazy for code splitting
  • Implement React.memo for memoization
  • Optimize image loading
  • Minimize re-renders
  • Cache expensive calculations

Monitoring

  • Track section load times
  • Monitor memory usage
  • Measure user interactions
  • Analyze performance metrics

🔧 Troubleshooting

Common Issues

  1. Section Not Rendering

    • Check section map registration
    • Verify predicate conditions
    • Look for console errors

  2. Configuration Not Working

    • Validate prop structure
    • Check prop value access
    • Verify default values

  3. Styling Issues

    • Check theme integration
    • Verify style function
    • Test on different devices

  4. Performance Problems

    • Implement memoization
    • Optimize image loading
    • Check for unnecessary re-renders

📖 Examples

Hero Image Section

See src/sections/hero-image/ for a complete example with:

  • Complex layout positioning
  • Hotspot functionality
  • Responsive design
  • Multiple configuration options
  • Predicate support

Custom Section Template

Use the template in src/sections/my-custom-section/ as a starting point.

🔗 Related Documentation

🤝 Contributing

When contributing new sections:

  1. Follow established patterns
  2. Add comprehensive tests
  3. Include proper documentation
  4. Test on multiple devices
  5. Optimize for performance
  6. Follow accessibility guidelines

📞 Support

For questions or issues:

  1. Check the troubleshooting section
  2. Review existing examples
  3. Consult the platform documentation
  4. Contact the development team

Last Updated: December 2024
Version: 1.0.0