# GGM Commerce Default Styling System

## Overview

The GGM Commerce plugin implements a centralized default styling system for all 15 Elementor widgets. This system allows you to:

- **Apply professional styling globally** to all new widgets
- **Remove styling globally** so widgets start blank
- **Edit per-widget** via Elementor's visual controls
- **Maintain from one location** for easy updates

---

## Architecture

### 1. Centralized Configuration File
**Location:** `includes/default-widget-styles.php`

This file contains all default styling values for every widget, organized by widget type. Values are pulled from a design system that ensures consistency across all widgets.

**Example structure:**
```php
'ggmc-add-to-cart' => [
    'button_background_color' => '#2563eb',
    'button_color' => '#FFFFFF',
    'button_padding' => ['top' => '14', 'right' => '24', ...],
    // ... more defaults
],
```

### 2. Helper Class Methods
**Location:** `includes/class-helpers.php`

#### `GGM_Commerce_Helpers::get_plugin_default_styles($widget_name)`
Returns default styles for a specific widget, or empty array if defaults are globally disabled.

#### `GGM_Commerce_Helpers::are_default_styles_enabled()`
Checks if default styles are currently enabled.

#### `GGM_Commerce_Helpers::enable_default_styles()`
Enables default styles globally.

#### `GGM_Commerce_Helpers::disable_default_styles()`
Disables (clears) default styles globally.

### 3. Base Widget Class
**Location:** `widgets/class-ggm-commerce-base-widget.php`

#### `get_static_default_styles()`
Base implementation that checks the global toggle option `ggm_commerce_defaults_cleared`.

#### `get_defaults_from_config()`
Protected helper method that automatically extracts widget name and fetches defaults from the centralized config.

### 4. Individual Widgets
**Location:** `widgets/tags/widget-*.php`

Each of the 15 widgets implements:
```php
public static function get_static_default_styles() {
    return self::get_defaults_from_config();
}
```

This simple implementation delegates to the base class helper, which:
1. Checks if defaults are globally disabled
2. Extracts the widget name from the class name
3. Returns the appropriate defaults from the centralized config

---

## ⚠️ CRITICAL: Control-Level Defaults Architecture

### DO NOT Make Control-Level Defaults Conditional

**WRONG** ❌ - Never do this:
```php
$widget->add_control(
    'button_color',
    [
        'type' => \Elementor\Controls_Manager::COLOR,
        'default' => $some_condition ? '#2563eb' : '',  // ❌ WRONG
    ]
);
```

**CORRECT** ✅ - Always use unconditional defaults:
```php
$widget->add_control(
    'button_color',
    [
        'type' => \Elementor\Controls_Manager::COLOR,
        'default' => '#2563eb',  // ✅ CORRECT
    ]
);
```

### Why This Matters

**Control-level defaults** (`'default' => 'value'` in control arrays) are used by Elementor as:
1. Initial values when creating NEW widgets
2. **Fallback values for EXISTING widgets** that have no saved value for that control

If you make control-level defaults conditional, changing the condition will affect existing widgets - breaking the "existing widgets are never affected" principle.

**The correct implementation:**
- ✅ `get_default_data()` method: Handles conditional defaults for NEW widgets only
- ✅ Control-level defaults: Always have values (never conditional)
- ✅ Result: Only new widgets are affected by settings changes

### Before Making Architectural Changes

**Always check for documentation:**
1. Search for `*.md` files: `find . -name "*.md" -type f`
2. Read relevant docs in `docs/` directory
3. Understand existing architecture before modifying
4. If unclear, document your assumptions and verify them

---

## Global Toggle System

### Option Name
`ggm_commerce_defaults_cleared` (boolean)

**Logic:**
- `false` (default) = Defaults **ENABLED** - widgets get professional styling
- `true` = Defaults **DISABLED** - widgets start blank

### Settings Page UI
**Location:** GGM Commerce > Settings > Default Styles tab

The settings page provides:
- **Status indicator** showing current state
- **"Load All Defaults"** button to enable styling
- **"Remove All Defaults"** button to disable styling
- **Design system reference** showing colors, typography, etc.

---

## The 15 Widgets with Default Styles

1. **ggmc-add-to-cart** - Add to Cart button with quantity controls
2. **ggmc-product-name** - Product title/heading
3. **ggmc-product-price** - Price display with sale pricing
4. **ggmc-product-description** - Product description text
5. **ggmc-product-stock** - Stock status badges
6. **ggmc-product-image** - Single product image
7. **ggmc-product-gallery** - Image gallery with thumbnails
8. **ggmc-product-grid** - Grid layout for multiple products
9. **ggmc-product-list** - List layout for products
10. **ggmc-product-table** - Table layout for products
11. **ggmc-product-filter** - Product filtering controls
12. **ggmc-cart-display** - Shopping cart display
13. **ggmc-mini-cart** - Mini cart dropdown/widget
14. **ggmc-checkout** - Checkout form
15. **ggmc-customer-account** - Customer account/dashboard

---

## Design System

### Colors
- **Primary:** `#2563eb` (Professional Blue)
- **Primary Dark:** `#1d4ed8` (Hover state)
- **Text Primary:** `#0f172a` (Rich dark for headings)
- **Text Secondary:** `#475569` (Body text)
- **Text Muted:** `#64748b` (Subtle text)
- **Background:** `#ffffff` (White)
- **Surface:** `#f8fafc` (Light gray backgrounds)
- **Border:** `#e2e8f0` (Subtle borders)
- **Success:** `#059669` (Green for in-stock, success)
- **Warning:** `#d97706` (Orange for low stock)
- **Error:** `#dc2626` (Red for out of stock, errors)

### Typography
- **Font Family:** `'Poppins', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif`
- **Font Weights:**
  - Light: `300`
  - Normal: `400`
  - Medium: `500`
  - Semibold: `600`
  - Bold: `700`

### Spacing
- XS: `4px`
- SM: `8px`
- MD: `16px`
- LG: `24px`
- XL: `32px`
- XXL: `48px`

### Border Radius
- Small: `4px`
- Medium: `6px`
- Large: `8px`

---

## How It Works

### When Creating a New Widget

1. User drags widget onto Elementor canvas
2. Elementor calls `get_default_data()` on the widget
3. Base widget checks `ggm_commerce_defaults_cleared` option
4. If **enabled** (option is `false`):
   - Widget calls `get_static_default_styles()`
   - Base class helper extracts widget name from class
   - Returns defaults from centralized config
   - Elementor applies these as initial values
5. If **disabled** (option is `true`):
   - Returns empty array
   - Widget starts with no styling

### Modifying Styles Per-Widget

1. Select widget in Elementor
2. Go to Style tab
3. Modify any control value
4. Changes are saved to that specific widget instance
5. Global defaults **do not** override existing widgets

### Enabling/Disabling Globally

**Via Settings Page:**
1. Go to GGM Commerce > Settings > Default Styles
2. Click "Load All Defaults" or "Remove All Defaults"
3. Ajax updates `ggm_commerce_defaults_cleared` option
4. Affects only **NEW** widgets created after the change
5. **Existing widgets** retain their current styling

**Via Code:**
```php
// Enable defaults
GGM_Commerce_Helpers::enable_default_styles();

// Disable defaults
GGM_Commerce_Helpers::disable_default_styles();

// Check status
$enabled = GGM_Commerce_Helpers::are_default_styles_enabled();
```

---

## Maintenance

### Adding a New Widget

1. Create widget class extending `GGM_Commerce_Base_Widget`
2. Add defaults to `includes/default-widget-styles.php`:
   ```php
   'ggmc-your-widget' => [
       'control_name' => 'value',
       // ... more defaults
   ],
   ```
3. Add method to widget class:
   ```php
   public static function get_static_default_styles() {
       return self::get_defaults_from_config();
   }
   ```

### Updating Default Values

1. Open `includes/default-widget-styles.php`
2. Find the widget's array (e.g., `'ggmc-add-to-cart'`)
3. Modify values
4. Save file
5. **Note:** Only affects NEW widgets, not existing ones

### Changing the Design System

1. Open `includes/default-widget-styles.php`
2. Modify the `$design_system` array at the top
3. All widgets that reference these values will automatically update
4. **Note:** Only affects NEW widgets

---

## Important Notes

### Option Naming Convention
The system uses **`ggm_commerce_defaults_cleared`** (not `use_default_widget_styles`) to maintain consistency with existing infrastructure.

**Logic is inverted:**
- Option `false` = Defaults **enabled**
- Option `true` = Defaults **cleared/disabled**

### No Activation Hook Required
Defaults are **not** set during plugin activation. The system respects the global toggle from the start.

### Existing Widgets Are Not Affected
When you enable or disable defaults globally, it **only affects new widgets**. Existing widgets retain their current styling until manually changed in Elementor.

### Per-Widget Override
Individual widgets can always be customized via Elementor's Style tab, regardless of the global setting. The global toggle only sets the *initial* values for new widgets.

---

## File Reference

```
ggm-commerce/
├── includes/
│   ├── default-widget-styles.php      # Centralized defaults config
│   ├── class-helpers.php               # Helper methods for defaults
│   ├── class-admin.php                 # Admin settings page UI
│   └── settings.php                    # Settings registration
│
├── widgets/
│   ├── class-ggm-commerce-base-widget.php  # Base widget with default system
│   └── tags/
│       ├── widget-add-to-cart.php      # Individual widgets (15 total)
│       ├── widget-product-name.php
│       ├── widget-product-price.php
│       └── ... (12 more widgets)
│
└── docs/
    └── DEFAULT-STYLING-SYSTEM.md       # This file
```

---

## API Reference

### Global Functions

None - all functionality is class-based for better organization.

### Class Methods

#### GGM_Commerce_Helpers
```php
// Get defaults for a specific widget
static get_plugin_default_styles( string $widget_name ): array

// Check if defaults are enabled
static are_default_styles_enabled(): bool

// Enable defaults
static enable_default_styles(): bool

// Disable defaults
static disable_default_styles(): bool

// Get list of widgets with defaults
static get_widgets_with_defaults(): array
```

#### GGM_Commerce_Base_Widget
```php
// Get default styles (child classes override this)
static get_static_default_styles(): array

// Protected helper to get defaults from config
protected static get_defaults_from_config(): array
```

---

## Troubleshooting

### Widgets Not Applying Defaults
1. Check if `ggm_commerce_defaults_cleared` option is `false` (enabled)
2. Verify `includes/default-widget-styles.php` exists and is readable
3. Clear Elementor cache (Elementor > Tools > Regenerate CSS & Data)
4. Try creating a **new** widget (existing ones won't update)

### Wrong Styling Applied
1. Check widget name matches key in `default-widget-styles.php`
2. Verify control names in defaults match actual control names in `register_controls()`
3. Look for PHP errors in debug.log

### Settings Page Not Showing
1. Verify `includes/class-admin.php` is loaded
2. Check user has admin permissions
3. Look for JavaScript console errors

---

## Version History

### Version 1.0 (Current)
- Initial implementation of centralized default styling system
- 15 widgets with comprehensive default styles
- Admin settings page with visual toggle controls
- Design system with professional blue theme
- Full documentation and API reference
