hyva-cms-component

What this skill does

# Hyvä CMS Component Creator

## Overview

This skill guides the interactive creation of custom Hyvä CMS components for Magento 2. It supports creating components in new or existing modules, with field presets for common patterns and automatic setup:upgrade execution.

**Command execution:** For commands that need to run inside the development environment (e.g., `bin/magento`), use the `hyva-exec-shell-cmd` skill to detect the environment and determine the appropriate command wrapper.

## Workflow

### Step 1: Module Selection

If not already specified in the prompt, ask the user where to create the component:

**Option A: New Module**

Ask for both values (do not assume defaults without asking):
1. **Vendor name** (e.g., `Acme`) - Required, no default. Do not suggest a Vendor name, prompt for user input.
2. **Module name** - Suggest `CmsComponents` as default so user can press Enter to accept

Then use the `hyva-create-module` skill with:
  - `dependencies`: `["Hyva_CmsBase"]`
  - `composer_require`: `{"hyva-themes/commerce-module-cms": "^1.0"}`

**Option B: Existing Module**
- Request the module path (can be in `app/code/`, `vendor/`, or custom location)
- Verify the module has `Hyva_CmsBase` as a dependency in `etc/module.xml`. If not present, add it.
- Verify the module has `hyva-themes/commerce-module-cms` as a dependency in `composer.json`. If not present, add it.

### Step 2: Component Details

Gather component information:

1. **Component name** (snake_case, e.g., `feature_card`)
2. **Label** (display name in editor, e.g., "Feature Card")
3. **Category** (Layout, Elements, Media, Content, or Other)
4. **Icon** - Automatically select an appropriate icon:

   **Step 4a: Identify icons already in use**
   Use the `hyva-cms-components-dump` skill to dump all current CMS components. Extract all `icon` values from the output to build a list of icons already in use by existing components.

   **Step 4b: Find available lucide icons**
   List the SVG files in `vendor/hyva-themes/magento2-theme-module/src/view/base/web/svg/lucide/` to get the full set of available icons.

   **Step 4c: Select the best fitting icon**
   From the available lucide icons that are NOT already in use by another component:
   - Choose the icon whose name best matches the purpose/meaning of the new component
   - Consider semantic meaning (e.g., `shopping-cart.svg` for cart-related, `image.svg` for image-related, `layout-grid.svg` for grid layouts)
   - Format the selected icon as `Hyva_Theme::svg/lucide/[icon-name].svg`

   If no suitable unused icon can be found, or if the lucide directory doesn't exist, leave the `icon` property unset.

### Step 3: Field Selection

Offer field presets or custom field creation. See `references/field-types.md` "Field Presets" section for available presets (Basic Card, Image Card, CTA Block, Text Block, Feature Item, Testimonial, Accordion Item) or allow custom field definition.

For custom fields, iterate through each field asking:
1. Field name (snake_case)
2. Field type (see `references/field-types.md`)
3. Label
4. Default value (optional)
5. Required? (yes/no) - Note: This will be added as `attributes.required`, NOT as a direct field property
6. Any additional attributes (these go in the `attributes` object)

### Step 4: Variant Support

Ask if the component needs template variants:

- If **yes**: Gather variant names and labels (e.g., default, compact, wide). See `references/variant-support.md` for configuration details.
- If **no**: Use single template

### Step 5: Generate Files

Create the required files:

#### For New Modules

The `hyva-create-module` skill creates the base module structure. Then add the CMS-specific directories:

```
app/code/[Vendor]/[Module]/
├── registration.php          # Created by hyva-create-module
├── composer.json             # Created by hyva-create-module
├── etc/
│   ├── module.xml            # Created by hyva-create-module
│   └── hyva_cms/
│       └── components.json   # Create this
└── view/
    └── frontend/
        └── templates/
            └── elements/
                └── [component-name].phtml (or [component-name]/ for variants)
```

#### For Existing Modules

Create or update:
- `etc/hyva_cms/components.json` (merge with existing if present)
- `view/frontend/templates/elements/[component-name].phtml`

### Step 6: Run Setup

After creating files, run `bin/magento setup:upgrade` using the appropriate command wrapper detected by the `hyva-exec-shell-cmd` skill.

## File Generation Details

### components.json Structure

```json
{
    "[component_name]": {
        "label": "[Label]",
        "category": "[Category]",
        "template": "[Vendor]_[Module]::elements/[component-name].phtml",
        "content": {
            // Generated fields
        },
        "design": {
            "includes": [
                "Hyva_CmsBase::etc/hyva_cms/default_design.json",
                "Hyva_CmsBase::etc/hyva_cms/default_design_typography.json"
            ]
        },
        "advanced": {
            "includes": [
                "Hyva_CmsBase::etc/hyva_cms/default_advanced.json"
            ]
        }
    }
}
```

### Valid Component Properties

**IMPORTANT:** Only specific properties are allowed at the component level. See `references/component-schema.md` for the complete schema reference.

Key properties: `label` (required), `category`, `template`, `icon`, `children`, `require_parent`, `content`, `design`, `advanced`, `disabled`, `custom_properties`.

**Invalid properties that will cause schema errors:**
- `hidden` - Does not exist. Use `require_parent: true` for child-only components, or `disabled: true`
- Any property not listed in the schema reference

### Children Configuration (CRITICAL)

**IMPORTANT:** `children` is a ROOT-LEVEL component property, NOT a field type within `content`, `design`, or `advanced`.

**INCORRECT ❌:**
```json
{
    "my_component": {
        "content": {
            "items": {
                "type": "children",
                "label": "Items"
            }
        }
    }
}
```

**CORRECT ✅:**
```json
{
    "my_component": {
        "label": "My Component",
        "children": {
            "config": {
                "accepts": ["child_component"],
                "max_children": 10
            }
        },
        "content": {
            "title": {
                "type": "text",
                "label": "Title"
            }
        }
    }
}
```

In templates, access children via `$block->getData('children')`, NOT via a custom field name.

### Field Validation (CRITICAL)

**IMPORTANT:** Field validation attributes like `required` must be placed in the `attributes` object, NOT as direct field properties.

**INCORRECT ❌:**
```json
{
    "title": {
        "type": "text",
        "label": "Title",
        "required": true
    }
}
```

**CORRECT ✅:**
```json
{
    "title": {
        "type": "text",
        "label": "Title",
        "attributes": {
            "required": true
        }
    }
}
```

Other validation attributes that go in `attributes`:
- `required` (boolean)
- `minlength` / `maxlength` (string)
- `min` / `max` (for numbers)
- `pattern` (regex string)
- `placeholder` (string)
- `comment` (help text)
- Custom data attributes for validation messages

### Child-Only Components

For components that should only be used as children of other components (like list items), use `require_parent: true`:

```json
{
    "my_list_item": {
        "label": "My List Item",
        "category": "Elements",
        "require_parent": true,
        "template": false,
        "content": {
            "title": {"type": "text", "label": "Title"}
        }
    },
    "my_list": {
        "label": "My List",
        "category": "Elements",
        "template": "Vendor_Module::elements/my-list.phtml",
        "children": {
            "config": {
                "accepts": ["my_list_item"]
            }
        }
    }
}
```

When `template: false`, the parent component renders the