hyva-ui-component: Скилл для установки и применения

--- name: hyva-ui-component description: Apply Hyva UI template-based components to a Hyvä theme. This skill should be used when the user wants to add, install, or apply a Hyva UI component (such as header, footer, gallery, menu, minicart, etc.) to their Hyvä theme. It lists available non-CMS components and their variants, displays component README instructions, and copies component files to the theme directory. requires: hyva-exec-shell-cmd, hyva-theme-list, hyva-child-theme, hyva-compile-tailwind-css --- # Hyva UI Component Applies Hyva UI template-based (non-CMS) components to a Hyvä theme by copying files from `{hyva_ui_path}/components/` to `app/design/frontend/{Vendor}/{Theme}/`. **Path variable:** `{hyva_ui_path}` = `vendor/hyva-themes/hyva-ui` (default) or user-provided custom path. **Command execution:** For any commands that need to run inside the development environment (e.g., `bin/magento` commands), use the `hyva-exec-shell-cmd` skill to detect the environment and determine the appropriate command wrapper. ## Step 0: Verify Hyva UI Installation ```bash ls vendor/hyva-themes/hyva-ui/components/ 2>/dev/null ``` **If NOT found**, offer options: (A) User provides custom extraction path, (B) `composer require --dev hyva-themes/hyva-ui`, (C) Download from https://hyva.io/my-account/my-downloads/ After install, refresh catalog: `<skill_path>/scripts/refresh_catalog.sh {hyva_ui_path} <skill_path>/references/components.md` Where `<skill_path>` is the directory containing this SKILL.md file. ## Step 1: Identify Theme Path Use the `hyva-theme-list` skill to find existing Hyvä themes. Filter the results to only include themes in `app/design/frontend/` (exclude vendor themes). Prompt the user to select: - **Existing Hyvä themes**: List themes returned by the script as options (e.g., `Example/winterWonderTheme`) - **Create new theme**: Always include an option to create a new child theme **If user selects "Create new theme":** 1. Use the `hyva-child-theme` skill to create the new theme first 2. Continue with the newly created theme path after the skill completes **If user selects an existing theme:** Continue with the selected theme path: `app/design/frontend/{Vendor}/{Theme}` ## Step 2: List or Select Component If no component specified or user asks to list components, show **only the "Non-CMS Components (Template-Based)" section** from `references/components.md`. **Do NOT list or mention:** - CMS components (accordion, card, categories, error-page, generic-content, order-confirmation, shortcuts, testimonial, usp, product-data/C-highlights) - Plugins (alpine-collapse, splidejs, sticky-header, tailwind-v3-design-tokens, tailwind-v4) These are internal dependencies or require the CMS Tailwind JIT compiler and are not applicable for direct installation via this skill. ## Step 3: Show Variants Variants: **A**=Basic, **B**=Enhanced, **C**=Advanced, **D**=Specialized. List with: `ls {hyva_ui_path}/components/{component}/` ## Step 4: Read Component README Always read `{hyva_ui_path}/components/{component}/{variant}/README.md` before copying. Present to user: dependencies, configuration options, special requirements. ## Step 5: Copy Component Files **Before copying**, check which destination files already exist to track created vs updated: ```bash # List source files find {hyva_ui_path}/components/{component}/{variant}/src -type f # For each source file, check if destination exists # e.g., for src/Magento_Catalog/templates/product/view/gallery.phtml # check: {theme_path}/Magento_Catalog/templates/product/view/gallery.phtml ``` Track each file as either: - **created**: Destination file did not exist before copy - **updated**: Destination file already existed (will be overwritten) Then copy: ```bash cp -r {hyva_ui_path}/components/{component}/{variant}/src/* {theme_path}/ ``` The `src/` directory contains Magento module folders (`Magento_Theme/`, `Magento_Catalog/`, etc.) that map directly to theme structure. For existing layout XML files, **merge** content rather than overwriting. ## Step 5.5: Add XML Configuration Options Check if README contains XML configuration (look for `<var name="`, `etc/view.xml`). **If found:** 1. Extract the first XML block containing `<var name=` elements with default values 2. Identify the module attribute (e.g., `module="Magento_Catalog"`) 3. Add to `{theme_path}/etc/view.xml`: - If file doesn't exist: Create with full `<view>` structure - If `<vars module="...">` exists: Add `<var>` elements inside it - If section missing: Add new `<vars module="...">` before `</view>` 4. Notify: "Added configuration options to `{theme_path}/etc/view.xml` with default values." Preserve existing view.xml content and keep XML comments from README. ## Step 6: Handle Dependencies Check README for dependencies and install them automatically (do not ask the user to select plugins): - **Plugin dependencies:** Copy required files from `{hyva_ui_path}/plugins/{plugin}/src/` (e.g., splidejs for gallery/D-splide) - **Component dependencies:** Apply dependent components first - **External packages:** e.g., `composer require hyva-themes/magento2-hyva-payment-icons` ## Step 7: Ask to recompile styles - **Rebuild Tailwind:** Always ask: "Do you need to recompile Tailwind CSS styles?" Never automatically build — an external tool may already be handling this. If the user wants to compile, use the `hyva-compile-tailwind-css` skill with the target theme. ## Step 8: Output Summary After applying all changes, output a summary of modifications: ### 8.1: List Modified Files Display all files that were created or modified during this component installation. Use the tracking from Step 5 to label each file correctly: - **(created)**: File did not exist before and was newly created - **(updated)**: File already existed and was overwritten ``` Modified files: - {theme_path}/Magento_Catalog/templates/product/view/gallery.phtml (updated) - {theme_path}/Magento_Theme/templates/html/header.phtml (created) - {theme_path}/etc/view.xml (updated) ``` ### 8.2: XML Configuration Table If XML configuration was added to `{theme_path}/etc/view.xml`, parse the XML block from the README and display a table of options: ```bash # Extract the XML config block from README and parse it php <skill_path>/scripts/parse_readme_xml.php --format=table < xml_block.txt ``` The table shows each option with columns: - **Option**: The full option path without a common prefix (e.g., `magnifier.enable`) - **Value**: The default value configured - **Description**: Explanatory text from the XML comment Example output (common prefix like `gallery.` is automatically stripped): ``` Option | Value | Description ---------------------+------------+--------------------------------------------------- nav | thumbs | Gallery navigation style (false/thumbs/counter) magnifier.enable | false | Turn on/off magnifier (true/false) ``` For markdown output (e.g., when creating documentation), use `--format=md`. ## Step 9: Final steps 1. **Review** copied templates for store-specific customization ## Quick Reference ``` {hyva_ui_path}/components/{component}/{variant}/ ├── README.md # Instructions ├── media/ # Preview images └── src/ # Files to copy to theme ``` See `references/components.md` for the full component catalog (only show non-CMS section to users). <!-- Copyright © Hyvä Themes https://hyva.io. All rights reserved. Licensed under OSL 3.0 -->