# Responsive Breakpoints System Guide

## Overview
The responsive system allows setting different values for Desktop, Tablet, and Mobile breakpoints - similar to Elementor in WordPress. This applies to typography, spacing, width, and all other properties.

## Breakpoints
- **Desktop**: ≥1024px (default/base)
- **Tablet**: 768px - 1023px
- **Mobile**: ≤767px

## Architecture

### Frontend (React/Builder)
1. **Utilities**: `/resources/js/builder-v2/utils/responsive.js`
2. **UI Components**: `/resources/js/builder-v2/components/shared/ResponsiveSwitcher.jsx`

### Backend (PHP/Render)
- **Helpers**: `/app/Helpers/builder_v2_helpers.php`
  - `getResponsiveValue()` - Get value for specific device
  - `isResponsiveValue()` - Check if value has responsive breakpoints
  - `generateResponsiveCSS()` - Generate CSS with media queries
  - `generateResponsiveInlineCSS()` - Generate inline styles + `<style>` tag

## Implementation Guide

### Step 1: Update Component Props (React)

```jsx
import { getResponsiveValue, isResponsiveValue } from '../../utils/responsive';

export const MyComponent = ({
    fontSize = '16px',  // Can now be '16px' OR { desktop: '16px', tablet: '14px', mobile: '12px' }
    padding = '20px',
    // ... other props
}) => {
    // Get current device value for display
    const currentFontSize = getResponsiveValue(fontSize, 'desktop');
    const currentPadding = getResponsiveValue(padding, 'desktop');

    // Rest of component...
};
```

### Step 2: Update Settings Panel (React)

```jsx
import { ResponsiveSwitcher, ResponsiveInput, useResponsive } from '../shared/ResponsiveSwitcher';

const MyComponentSettings = () => {
    const { props } = useNode((node) => ({ props: node.data.props }));

    return (
        <ResponsiveSwitcher>
            {/* Typography Section */}
            <div className="mb-3">
                <h6>Typography</h6>

                <ResponsiveInput
                    label="Font Size"
                    value={props.fontSize}
                    onChange={(value) => setProp((props) => props.fontSize = value)}
                >
                    <input type="text" className="form-control" placeholder="16px" />
                </ResponsiveInput>

                <ResponsiveInput
                    label="Line Height"
                    value={props.lineHeight}
                    onChange={(value) => setProp((props) => props.lineHeight = value)}
                >
                    <input type="text" className="form-control" placeholder="1.5" />
                </ResponsiveInput>
            </div>

            {/* Spacing Section */}
            <div className="mb-3">
                <h6>Spacing</h6>

                <ResponsiveInput
                    label="Padding"
                    value={props.padding}
                    onChange={(value) => setProp((props) => props.padding = value)}
                    helpText="e.g., 20px or 20px 40px"
                >
                    <input type="text" className="form-control" />
                </ResponsiveInput>

                <ResponsiveInput
                    label="Margin"
                    value={props.margin}
                    onChange={(value) => setProp((props) => props.margin = value)}
                >
                    <input type="text" className="form-control" />
                </ResponsiveInput>
            </div>
        </ResponsiveSwitcher>
    );
};
```

### Step 3: Update Render Function (PHP)

#### Method A: Using `generateResponsiveInlineCSS` (Recommended)

```php
function renderMyComponent($props) {
    $elementId = 'my-component-' . uniqid();
    $fontSize = $props['fontSize'] ?? '16px';
    $padding = $props['padding'] ?? '20px';

    // Generate responsive CSS
    $responsiveCSS = generateResponsiveInlineCSS($elementId, [
        'font-size' => ['value' => $fontSize, 'unit' => ''],
        'padding' => ['value' => $padding, 'unit' => ''],
        'line-height' => ['value' => $props['lineHeight'] ?? '1.5', 'unit' => '']
    ]);

    $html = $responsiveCSS['mediaQueries']; // Add <style> tag with media queries
    $html .= '<div id="' . $elementId . '" style="' . $responsiveCSS['inline'] . '">';
    $html .= 'Content here';
    $html .= '</div>';

    return $html;
}
```

#### Method B: Using Individual Functions

```php
function renderMyComponent($props) {
    $fontSize = $props['fontSize'] ?? '16px';

    // Check if responsive
    if (isResponsiveValue($fontSize)) {
        $desktopFontSize = getResponsiveValue($fontSize, 'desktop');
        $tabletFontSize = getResponsiveValue($fontSize, 'tablet');
        $mobileFontSize = getResponsiveValue($fontSize, 'mobile');

        // Build CSS manually
        $html = '<style>';
        $html .= '.my-element { font-size: ' . $desktopFontSize . '; }';
        if ($tabletFontSize) {
            $html .= '@media (max-width: 1023px) and (min-width: 768px) { .my-element { font-size: ' . $tabletFontSize . '; } }';
        }
        if ($mobileFontSize) {
            $html .= '@media (max-width: 767px) { .my-element { font-size: ' . $mobileFontSize . '; } }';
        }
        $html .= '</style>';
    } else {
        $html = '<style>.my-element { font-size: ' . $fontSize . '; }</style>';
    }

    $html .= '<div class="my-element">Content</div>';
    return $html;
}
```

## Data Structure

### Responsive Value Object
```javascript
{
    desktop: '16px',   // Required (base value)
    tablet: '14px',    // Optional (empty = inherit from desktop)
    mobile: '12px'     // Optional (empty = inherit from desktop)
}
```

### Non-Responsive Value
```javascript
'16px'  // Plain string - applies to all devices
```

## UI/UX Features

1. **Device Switcher**: Toggle between Desktop/Tablet/Mobile tabs
2. **Inheritance Indicator**: Shows when tablet/mobile inherits from desktop
3. **Active Device Badge**: Shows which device's value you're editing
4. **Empty Value Behavior**: If tablet/mobile value is empty, it inherits from desktop

## Examples

### Example 1: Responsive Typography (Heading Component)

**Props:**
```javascript
{
    fontSize: { desktop: '48px', tablet: '36px', mobile: '24px' },
    lineHeight: { desktop: '1.2', tablet: '1.3', mobile: '1.4' }
}
```

**Generated CSS:**
```css
#heading-123 { font-size: 48px; line-height: 1.2; }
@media (max-width: 1023px) and (min-width: 768px) {
    #heading-123 { font-size: 36px; line-height: 1.3; }
}
@media (max-width: 767px) {
    #heading-123 { font-size: 24px; line-height: 1.4; }
}
```

### Example 2: Responsive Spacing (Container Component)

**Props:**
```javascript
{
    padding: { desktop: '60px 20px', tablet: '40px 15px', mobile: '20px 10px' },
    margin: { desktop: '40px 0', tablet: '', mobile: '20px 0' }  // Tablet inherits from desktop
}
```

**Generated CSS:**
```css
#container-456 { padding: 60px 20px; margin: 40px 0; }
@media (max-width: 767px) {
    #container-456 { padding: 20px 10px; margin: 20px 0; }
}
```

### Example 3: Responsive Width

**Props:**
```javascript
{
    width: { desktop: '1200px', tablet: '100%', mobile: '100%' }
}
```

## Migration Strategy

To add responsive support to existing components:

1. **Identify** properties that should be responsive (typography, spacing, dimensions)
2. **Wrap Settings Panel** with `<ResponsiveSwitcher>`
3. **Replace inputs** with `<ResponsiveInput>` wrapper
4. **Update render function** to use `generateResponsiveInlineCSS()`
5. **Test** on all three breakpoints

## Component Checklist

Components to update with responsive support:

- [ ] Heading - Typography (fontSize, lineHeight, etc.)
- [ ] Paragraph - Typography
- [ ] Button - Size, padding, fontSize
- [ ] Container - Padding, margin, minHeight
- [ ] Image - Width, height
- [ ] Icon List - Gap, iconSize, fontSize
- [ ] Stats - Typography, spacing
- [ ] Testimonials - Typography, spacing
- [ ] All other components...

## Notes

- Desktop values are **required** (used as fallback)
- Tablet/Mobile values are **optional** (inherit from desktop if empty)
- Media queries use `max-width` and `min-width` for precise breakpoint control
- Generated CSS is minimal - only includes breakpoints that have values
- The system works with any CSS property (not just typography/spacing)

## Testing

Test responsive behavior by:
1. Set different values for each breakpoint in builder
2. Save and view public page
3. Resize browser window or use DevTools device toolbar
4. Verify values change at correct breakpoints (1024px, 768px, 767px)