prestashop-icons/README.md

# PrestaShop Icons

Semantic icon helper for PrestaShop modules.

```php
MprIcons::get('account');  // Just works
```

## How It Works

- **Admin**: Uses Material Icons (auto-detected)
- **Front**: Reads from `ps_mpr_config` table, defaults to Font Awesome

## Setup (Module Install)

Call `init()` from your module's install method:

```php
public function install()
{
    MprIcons::init();  // Creates config table, detects theme icons
    return parent::install();
}
```

This will:
1. Create `ps_mpr_config` table if it doesn't exist
2. Detect theme icon set (checks theme.yml, assets for Material)
3. Save the detected preference

## PHP

```php
use MyPrestaRocks\Icons\MprIcons;

// Just call get() - it figures out the rest
echo MprIcons::get('account');
echo MprIcons::get('cart');
echo MprIcons::get('success', 'text-green');  // With extra class

// Get raw class/name (no HTML)
$class = MprIcons::raw('edit');  // 'fa fa-pencil' or 'edit'
```

## JavaScript

Include the script and set icon set from PHP:

```php
// In your module
$this->context->controller->addJS($this->getLocalPath() . 'vendor/myprestarocks/prestashop-icons/js/mpr-icons.js');
Media::addJsDef(['mprIconSet' => MprIcons::getIconSet()]);
```

```javascript
MprIcons.get('account');              // HTML string
MprIcons.create('warning');           // DOM element
MprIcons.raw('edit');                 // Class/name only
```

## Configuration

Front office icon set is stored in `ps_mpr_config`:
- module: `mpr_global`
- key: `front_icon_set`
- value: `fontawesome` or `material`

```php
// Save preference
MprIcons::saveIconSet('material');
```

## Admin Configuration Form

Add icon settings to your module's admin page using `MprIconsConfig`:

```php
use MyPrestaRocks\Icons\MprIconsConfig;

// In getConfigForm() - add fields to your form
$fields_form[]['form'] = [
    'legend' => ['title' => 'Icon Settings'],
    'input' => MprIconsConfig::getFormFields(),
    'submit' => ['title' => $this->l('Save')],
];

// In getConfigFormValues() - get current values
$values = array_merge($values, MprIconsConfig::getFormValues());

// In postProcess() - save when form submitted
if (Tools::isSubmit('submitConfig')) {
    MprIconsConfig::processForm();
}
```

This creates a form with:
- **Icon Set selector**: Font Awesome or Material Icons
- **Self-host toggle**: Include icon fonts from module (for themes without icons)

## Self-Hosted Icon Fonts

If a theme doesn't include Font Awesome or Material Icons, enable self-hosting:

```php
// In hookHeader or setMedia
public function hookHeader()
{
    MprIcons::registerAssets($this);
}
```

This will:
1. Check if self-hosting is enabled in config
2. Register the appropriate CSS file (Font Awesome or Material Icons)
3. Load fonts from `assets/fontawesome/` or `assets/material-icons/`

**Bundled assets:**
- Font Awesome 4.7.0 (~30KB CSS + ~80KB woff2)
- Material Icons (~1KB CSS + ~128KB woff2)


## Available Icons

| Name | Font Awesome | Material |
|------|--------------|----------|
| `account` | `fa fa-user` | `person` |
| `cart` | `fa fa-shopping-cart` | `shopping_cart` |
| `orders` | `fa fa-list` | `receipt_long` |
| `success` | `fa fa-check` | `check` |
| `error` | `fa fa-times` | `close` |
| `warning` | `fa fa-exclamation-triangle` | `warning` |
| `info` | `fa fa-info-circle` | `info` |
| `edit` | `fa fa-pencil` | `edit` |
| `delete` | `fa fa-trash` | `delete` |
| `search` | `fa fa-search` | `search` |
| `settings` | `fa fa-cog` | `settings` |
| `email` | `fa fa-envelope` | `email` |
| `phone` | `fa fa-phone` | `phone` |
| `lock` | `fa fa-lock` | `lock` |
| `logout` | `fa fa-sign-out` | `logout` |
| `home` | `fa fa-home` | `home` |
| `address` | `fa fa-map-marker` | `location_on` |
| `truck` | `fa fa-truck` | `local_shipping` |
| `credit-card` | `fa fa-credit-card` | `credit_card` |
| `calendar` | `fa fa-calendar` | `calendar_today` |
| `heart` | `fa fa-heart` | `favorite` |
| `star` | `fa fa-star` | `star` |
| `eye` | `fa fa-eye` | `visibility` |
| `eye-off` | `fa fa-eye-slash` | `visibility_off` |
| `close` | `fa fa-times` | `close` |
| `check` | `fa fa-check` | `check` |
| `plus` | `fa fa-plus` | `add` |
| `minus` | `fa fa-minus` | `remove` |
| `chevron-*` | `fa fa-chevron-*` | `chevron_*` |
| `arrow-*` | `fa fa-arrow-*` | `arrow_*` |
| `download` | `fa fa-download` | `download` |
| `upload` | `fa fa-upload` | `upload` |
| `refresh` | `fa fa-refresh` | `refresh` |
| `spinner` | `fa fa-spinner fa-spin` | `hourglass_empty` |
| `loading` | `fa fa-circle-o-notch fa-spin` | `autorenew` |

Full list: `MprIcons::list()`

## SVG Sprites

For brand icons (payments, social), use the included SVG sprites. One request, multiple icons.

### Sprite Structure

```
sprites/
├── payments/
│   ├── icon-lm.svg        # Logo mark, light mode
│   ├── icon-dm.svg        # Logo mark, dark mode
│   ├── icon-la.svg        # Logo mark, light accent
│   ├── icon-da.svg        # Logo mark, dark accent
│   ├── square-lm.svg      # Square format, light mode
│   ├── square-dm.svg      # Square format, dark mode
│   ├── square-la.svg      # Square format, light accent
│   ├── square-da.svg      # Square format, dark accent
│   ├── rectangle-lm.svg   # Button shape, light mode
│   ├── rectangle-dm.svg   # Button shape, dark mode
│   ├── rectangle-la.svg   # Button shape, light accent
│   ├── rectangle-da.svg   # Button shape, dark accent
│   ├── text-only-lm.svg   # Text only, light mode
│   ├── text-only-dm.svg   # Text only, dark mode
│   ├── text-only-la.svg   # Text only, light accent
│   └── text-only-da.svg   # Text only, dark accent
└── socials/
    ├── icon-lm.svg
    ├── icon-dm.svg
    ├── icon-la.svg
    ├── icon-da.svg
    ├── full-logo-lm.svg
    ├── full-logo-dm.svg
    ├── full-logo-la.svg
    ├── full-logo-da.svg
    ├── text-only-lm.svg
    ├── text-only-dm.svg
    ├── text-only-la.svg
    └── text-only-da.svg
```

### Variants Explained

| Suffix | Mode | Use Case |
|--------|------|----------|
| `-lm` | Light Mode | Dark icons for light backgrounds |
| `-dm` | Dark Mode | White icons for dark backgrounds |
| `-la` | Light Accent | Brand colors on light backgrounds |
| `-da` | Dark Accent | Brand colors on dark backgrounds |

| Shape | Description | Typical Size |
|-------|-------------|--------------|
| `icon` | Logo mark only | 24×24, 32×32 |
| `square` | Square with padding | 45×45 |
| `rectangle` | Card/button shape | 60×38 |
| `text-only` | Brand name text | varies |
| `full-logo` | Logo + brand name (socials) | varies |

### Payment Icons

Copy the sprite you need to your module, include once, use anywhere:

```php
// In module install or build step
copy(
    _PS_MODULE_DIR_ . 'yourmodule/vendor/myprestarocks/prestashop-icons/sprites/payments/square-lm.svg',
    _PS_MODULE_DIR_ . 'yourmodule/views/img/payments.svg'
);
```

```html
<!-- Include sprite (hidden) -->
{include file="module:yourmodule/views/img/payments.svg"}

<!-- Use icons - format: {shape}_{brand}_{mode} -->
<svg width="45" height="45"><use href="#square_visa_lm"/></svg>
<svg width="45" height="45"><use href="#square_mastercard_lm"/></svg>
<svg width="45" height="45"><use href="#square_paypal_lm"/></svg>
```

**Available payment brands (38):**

afterpay, alipay, alma, amazon, american_express, apple_pay, bacs, bancontact, bank, billie, blik, cartes_bancaires, cod, credit_pay, eps, google_pay, ideal, jcb, kakao_pay, klarna, link, mastercard, mobilepay, multibanco, naver_pay, przelewy24, payco, paypal, pickup, point_of_sale, quote, revolut, samsung_pay, satispay, sepa, twint, visa, wechat_pay

### Social Icons

```html
{include file="module:yourmodule/views/img/socials.svg"}

<!-- format: {shape}_{brand}_{mode} -->
<svg width="24" height="24"><use href="#icon_facebook_lm"/></svg>
<svg width="24" height="24"><use href="#icon_x_lm"/></svg>
<svg width="24" height="24"><use href="#icon_google_lm"/></svg>
```

**Available social brands (12):**

amazon, apple, facebook, google, linkedin, microsoft, outlook, paypal, reddit, tiktok, x, yahoo

### Icon ID Format

Icon IDs follow the pattern: `{shape}_{brand}_{mode}`

Examples:
- `icon_visa_lm` - Visa icon, light mode
- `square_visa_dm` - Visa square, dark mode
- `rectangle_paypal_la` - PayPal rectangle, light accent
- `text-only_mastercard_lm` - Mastercard text only, light mode
- `full-logo_facebook_da` - Facebook full logo, dark accent

### Styling

```css
.payment-icon { width: 45px; height: 45px; }
.payment-icon-rect { width: 60px; height: 38px; }
.social-icon { width: 24px; height: 24px; }
```

## License

MIT