heraspec 0.1.13 → 0.1.15

package/dist/core/templates/skills/wordpress/plugin-standard/templates/plugin-main.php

@@ -0,0 +1,169 @@
+<?php
+/**
+ * Plugin Name:       {{plugin_name}}
+ * Description:       A high-quality WordPress plugin following WP.org standards.
+ * Version:           1.0.0
+ * Author:            Your Name
+ * Author URI:        https://example.com
+ * License:           GPL-2.0-or-later
+ * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
+ * Text Domain:       {{text_domain}}
+ * Domain Path:       /languages
+ *
+ * @package           {{namespace}}
+ */
+
+// If this file is called directly, abort.
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * The core plugin class.
+ */
+class {{namespace}}\Main {
+
+	/**
+	 * Instance of this class.
+	 *
+	 * @var object
+	 */
+	protected static $instance = null;
+
+	/**
+	 * Initialize the plugin.
+	 */
+	public function __construct() {
+		$this->define_constants();
+		$this->includes();
+		$this->init_hooks();
+	}
+
+	/**
+	 * Return an instance of this class.
+	 */
+	public static function get_instance() {
+		if ( null === self::$instance ) {
+			self::$instance = new self();
+		}
+		return self::$instance;
+	}
+
+	/**
+	 * Define constants.
+	 */
+	private function define_constants() {
+		define( '{{prefix|upper}}VERSION', '1.0.0' );
+		define( '{{prefix|upper}}PATH', plugin_dir_path( __FILE__ ) );
+		define( '{{prefix|upper}}URL', plugin_dir_url( __FILE__ ) );
+	}
+
+	/**
+	 * Include required files.
+	 */
+	private function includes() {
+		// Include admin classes, helpers, etc.
+	}
+
+	/**
+	 * Initialize hooks.
+	 */
+	private function init_hooks() {
+		add_action( 'admin_menu', [ $this, 'add_menu_pages' ] );
+		add_action( 'admin_enqueue_scripts', [ $this, 'enqueue_admin_assets' ] );
+		
+		// Activation / Deactivation hooks
+		register_activation_hook( __FILE__, [ $this, 'activate' ] );
+		register_deactivation_hook( __FILE__, [ $this, 'deactivate' ] );
+	}
+
+	/**
+	 * Add Admin Menu Pages.
+	 */
+	public function add_menu_pages() {
+		add_menu_page(
+			__( '{{plugin_name}}', '{{text_domain}}' ),
+			__( '{{plugin_name}}', '{{text_domain}}' ),
+			'manage_options',
+			'{{plugin_slug}}',
+			[ $this, 'render_dashboard_page' ],
+			'dashicons-admin-generic',
+			100
+		);
+
+		add_submenu_page(
+			'{{plugin_slug}}',
+			__( 'Dashboard', '{{text_domain}}' ),
+			__( 'Dashboard', '{{text_domain}}' ),
+			'manage_options',
+			'{{plugin_slug}}',
+			[ $this, 'render_dashboard_page' ]
+		);
+
+		add_submenu_page(
+			'{{plugin_slug}}',
+			__( 'Settings', '{{text_domain}}' ),
+			__( 'Settings', '{{text_domain}}' ),
+			'manage_options',
+			'{{plugin_slug}}-settings',
+			[ $this, 'render_settings_page' ]
+		);
+	}
+
+	/**
+	 * Enqueue Admin Assets.
+	 */
+	public function enqueue_admin_assets( $hook ) {
+		// Only load on our plugin pages
+		if ( strpos( $hook, '{{plugin_slug}}' ) === false ) {
+			return;
+		}
+
+		wp_enqueue_style( '{{plugin_slug}}-admin', {{prefix|upper}}URL . 'assets/css/admin.css', [], {{prefix|upper}}VERSION );
+		wp_enqueue_script( '{{plugin_slug}}-admin', {{prefix|upper}}URL . 'assets/js/admin.js', [ 'jquery' ], {{prefix|upper}}VERSION, true );
+		
+		wp_localize_script( '{{plugin_slug}}-admin', '{{prefix}}params', [
+			'ajax_url' => admin_url( 'admin-ajax.php' ),
+			'nonce'    => wp_create_nonce( '{{prefix}}nonce' ),
+		]);
+	}
+
+	/**
+	 * Render Dashboard Page.
+	 */
+	public function render_dashboard_page() {
+		// Include template file
+		include {{prefix|upper}}PATH . 'templates/admin-dashboard.php';
+	}
+
+	/**
+	 * Render Settings Page.
+	 */
+	public function render_settings_page() {
+		// Include template file
+		include {{prefix|upper}}PATH . 'templates/admin-settings.php';
+	}
+
+	/**
+	 * Activation logic.
+	 */
+	public function activate() {
+		// Setup database tables, default options, etc.
+	}
+
+	/**
+	 * Deactivation logic.
+	 */
+	public function deactivate() {
+		// Clear scheduled tasks, etc.
+	}
+}
+
+/**
+ * Initialize the plugin.
+ */
+function {{prefix}}init() {
+	return {{namespace}}\Main::get_instance();
+}
+
+add_action( 'plugins_loaded', '{{prefix}}init' );

package/dist/core/templates/skills/wordpress/plugin-standard/templates/readme.txt

@@ -0,0 +1,41 @@
+=== {{plugin_name}} ===
+Contributors: yourname
+Tags: wordpress, plugin, standard
+Requires at least: 6.0
+Tested up to: 6.4
+Requires PHP: 7.4
+Stable tag: 1.0.0
+License: GPLv2 or later
+License URI: https://www.gnu.org/licenses/gpl-2.0.html
+
+{{plugin_name}} is a high-quality WordPress plugin built with HeraSpec.
+
+== Description ==
+
+Describe your plugin features here.
+
+== Installation ==
+
+1. Upload the plugin files to the `/wp-content/plugins/{{plugin_slug}}` directory.
+2. Activate the plugin through the 'Plugins' screen in WordPress.
+3. Go to {{plugin_name}} -> Settings to configure.
+
+== Frequently Asked Questions ==
+
+= Is this plugin free? =
+
+Yes!
+
+== Screenshots ==
+
+1. Dashboard view.
+
+== Changelog ==
+
+= 1.0.0 =
+* Initial release.
+
+== Upgrade Notice ==
+
+= 1.0.0 =
+* First version.

package/dist/core/templates/skills/wordpress/plugin-standard/templates/uninstall.php

@@ -0,0 +1,21 @@
+<?php
+/**
+ * Fired when the plugin is uninstalled.
+ *
+ * @package {{namespace}}
+ */
+
+// If uninstall not called from WordPress, then exit.
+if ( ! defined( 'WP_UNINSTALL_PLUGIN' ) ) {
+	exit;
+}
+
+/**
+ * Clean up plugin data.
+ */
+delete_option( '{{prefix}}version' );
+delete_option( '{{prefix}}api_key' );
+
+// Delete custom tables if any...
+// global $wpdb;
+// $wpdb->query( "DROP TABLE IF EXISTS {$wpdb->prefix}your_table_name" );

package/dist/core/templates/skills/wordpress/ux-element/skill.md

@@ -0,0 +1,83 @@
+# Skill: Flatsome UX Element
+
+This skill guides the creation of custom UX Builder elements for the Flatsome theme within the PolyUtilities plugin.
+
+## Purpose
+Standardize the development of UX elements to ensure consistency across controllers, shortcodes, and templates, with special focus on real-time preview functionality. This skill is portable and uses dynamic prefixes for identity (Shortcode, Namespace, CSS Classes).
+
+## Required Variables
+When calling this skill, define the following identity prefixes:
+- `{{namespace_prefix}}`: The root namespace (e.g., `polyxgo\PolyUtilities`).
+- `{{shortcode_prefix}}`: Prefix for shortcode names (e.g., `poly_ux_`).
+- `{{class_prefix}}`: Prefix for CSS classes (e.g., `poly-`).
+- `{{plugin_dir_const}}`: The plugin directory constant (e.g., `__POLYUTILITIES_PLUGIN_DIR__`).
+
+## Prerequisites
+- Knowledge of PHP, WordPress Shortcodes, and AngularJS (for UX Builder templates).
+- Access to `inc/Core/Helper.php` for utility functions.
+
+## Implementation Steps
+
+### 1. Register Shortcode Logic (The Controller)
+Create a new controller class in `inc/Controllers/Elements/`.
+- **Namespace**: `{{namespace_prefix}}\Controllers\Elements`
+- **Method `register_hooks()`**: Add the shortcode `{{shortcode_prefix}}{{element_slug}}` and `ux_builder_setup` action.
+- **Method `render_element($atts, $content)`**: Handle the frontend output.
+
+### 2. Register UX Builder UI (The Shortcode)
+Create a registration file in `inc/builder/shortcodes/`.
+- Use `add_ux_builder_shortcode('{{shortcode_prefix}}{{element_slug}}', ...)`.
+- Define options (textfield, select, colorpicker, slider, etc.).
+- Link to the AngularJS template using `Helper::get_poly_ux_builder_template()`.
+
+### 3. Build the Preview Template (AngularJS)
+Create an HTML file in `inc/builder/shortcodes/templates/`.
+- **CRITICAL**: Wrap the entire content in a `<span>` with `id="{{:: shortcode.$id }}"`.
+- This ensures that clicking the element in the builder correctly selects it and shows options.
+- Use `ng-style` and `style scope="scope"` for real-time CSS updates.
+
+### 4. Create SVG Thumbnail
+Create an SVG file in `inc/builder/shortcodes/thumbnails/`.
+- **Naming**: Use `{{element_slug}}.svg`.
+- **Dimensions**: Use `100x68px`.
+- **Theme**: Use the "Pastel Red" theme (`#F87171` for accents, `#FCA5A5` for fills).
+
+### 5. Create the Frontend View
+(Optional) Extract the HTML into `inc/Views/elements/` for cleaner controllers.
+
+## Standards and Rules
+
+### The Wrapping Rule
+Every UX Builder template MUST follow this structure:
+```html
+<span id="{{:: shortcode.$id }}">
+    <!-- Main element (e.g., <a>, <div>, <section>) -->
+    <div class="{{class_prefix}}{{element_slug}}" ng-style="{ 'color': shortcode.options.color }">
+        {{ shortcode.options.text }}
+    </div>
+    
+    <!-- Scoped styles for hover effects or complex rules -->
+    <style scope="scope">
+        #{{::shortcode.$id }} .{{class_prefix}}{{element_slug}}:hover {
+            opacity: 0.8;
+        }
+    </style>
+</span>
+```
+
+### Variable Naming (PHP vs AngularJS)
+**CRITICAL**: When accessing shortcode options in the AngularJS template (`.html`), variables declared with underscores (`_`) in PHP MUST be accessed via **camelCase**.
+- **PHP**: `bg_color` → **AngularJS**: `shortcode.options.bgColor`
+- **PHP**: `pxg_clock_font` → **AngularJS**: `shortcode.options.pxgClockFont`
+- **PHP**: `text_align` → **AngularJS**: `shortcode.options.textAlign`
+
+### Color Handling
+- Use HEX or RGBA strings consistently.
+- Always provide default values in the shortcode registration or handle them in the template/controller.
+
+## Templates
+- [Controller.php](templates/Controller.php)
+- [Shortcode.php](templates/Shortcode.php)
+- [Template.html](templates/Template.html)
+- [View.php](templates/View.php)
+- [Thumbnail.svg](templates/Thumbnail.svg)

package/dist/core/templates/skills/wordpress/ux-element/templates/Controller.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace {{namespace_prefix}}\Controllers\Elements;
+
+use polyxgo\PolyUtilities\Core\Helper;
+
+class Element{{ElementName}}Controller
+{
+    public function register_hooks()
+    {
+        // 1. Frontend Shortcode
+        add_shortcode('{{shortcode_prefix}}{{element_slug}}', [$this, 'render_element']);
+
+        // 2. UX Builder Integration (Flatsome only)
+        if (Helper::is_flatsome_theme_activated()) {
+            add_action('ux_builder_setup', [$this, 'register_ux_builder_element']);
+        }
+    }
+
+    public function register_ux_builder_element()
+    {
+        if (function_exists('add_ux_builder_shortcode')) {
+            // Include the UI registration file
+            require_once Helper::get_poly_ux_builder_shortcode('{{element_slug}}');
+        }
+    }
+
+    public function render_element($atts, $content = null)
+    {
+        $atts = shortcode_atts([
+            '_id' => '{{element_slug}}-' . rand(),
+            'title' => '',
+            'class' => '',
+            'visibility' => '',
+            // Add more attributes here
+        ], $atts, '{{shortcode_prefix}}{{element_slug}}');
+
+        ob_start();
+        $view_path = plugin_dir_path({{plugin_dir_const}}) . '/inc/Views/elements/{{element_slug}}.php';
+        
+        if (file_exists($view_path)) {
+            include $view_path;
+        } else {
+            // Fallback inline rendering
+            echo '<div class="' . esc_attr($atts['class']) . '">' . esc_html($atts['title']) . '</div>';
+        }
+        
+        return ob_get_clean();
+    }
+}

package/dist/core/templates/skills/wordpress/ux-element/templates/Shortcode.php

@@ -0,0 +1,23 @@
+<?php
+
+use polyxgo\PolyUtilities\Core\Helper;
+use polyxgo\PolyUtilities\Core\Options;
+
+add_ux_builder_shortcode('{{shortcode_prefix}}{{element_slug}}', array(
+    'name'      => __('{{ElementName}}', 'polyutilities'),
+    'category'  => __('PolyUtilities', 'polyutilities'),
+    'template'  => Helper::get_poly_ux_builder_template('{{element_slug}}'),
+    'thumbnail' => Helper::get_poly_ux_builder_thumbnail('{{element_slug}}'),
+    'info'      => '{{ title }}',
+    'priority'  => 10,
+    'options'   => array(
+        'title' => array(
+            'type'        => 'textfield',
+            'heading'     => __('Title', 'polyutilities'),
+            'default'     => 'Element Title',
+            'auto_focus'  => true,
+        ),
+        // Add more options here (colorpicker, slider, select, etc.)
+        'advanced_options' => require Helper::get_poly_ux_builder_element('commons', 'advanced'),
+    ),
+));

package/dist/core/templates/skills/wordpress/ux-element/templates/Template.html

@@ -0,0 +1,20 @@
+<span id="{{:: shortcode.$id }}">
+    <div class="{{class_prefix}}{{element_slug}} {{ shortcode.options.class }} {{ shortcode.options.visibility }}"
+         ng-style="{
+             'color': shortcode.options.textColor,
+             'background-color': shortcode.options.bgColor,
+             'font-family': shortcode.options.pxgClockFont
+         }">
+        <span ng-bind="shortcode.options.title"></span>
+    </div>
+
+    <style scope="scope">
+        #{{::shortcode.$id }} .{{class_prefix}}{{element_slug}} {
+            /* Add scoped styles here */
+        }
+        
+        #{{::shortcode.$id }} .{{class_prefix}}{{element_slug}}:hover {
+            /* Hover effects */
+        }
+    </style>
+</span>

package/dist/core/templates/skills/wordpress/ux-element/templates/Thumbnail.svg

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="100px" height="68px" viewBox="0 0 100 68" version="1.1" xmlns="http://www.w3.org/2000/svg">
+    <rect x="0" y="0" width="100" height="68" fill="#FFFFFF"></rect>
+    <!-- Placeholder: Replace with actual icon geometry -->
+    <rect x="25" y="20" width="50" height="28" rx="2" fill="#FCA5A5" stroke="#F87171" stroke-width="2"></rect>
+    <rect x="30" y="28" width="40" height="4" rx="1" fill="#FFFFFF"></rect>
+    <rect x="30" y="36" width="25" height="4" rx="1" fill="#FFFFFF"></rect>
+</svg>

package/dist/core/templates/skills/wordpress/ux-element/templates/View.php

@@ -0,0 +1,21 @@
+<?php
+/**
+ * Frontend view for {{ElementName}}
+ * 
+ * @var array $atts
+ */
+
+$classes = array('{{class_prefix}}{{element_slug}}');
+if (!empty($atts['class'])) $classes[] = $atts['class'];
+if (!empty($atts['visibility'])) $classes[] = $atts['visibility'];
+
+$inline_style = '';
+if (!empty($atts['textColor'])) $inline_style .= 'color: ' . esc_attr($atts['textColor']) . ';';
+if (!empty($atts['bgColor'])) $inline_style .= 'background-color: ' . esc_attr($atts['bgColor']) . ';';
+
+?>
+<div id="<?php echo esc_attr($atts['_id']); ?>" 
+     class="<?php echo esc_attr(implode(' ', $classes)); ?>"
+     style="<?php echo esc_attr($inline_style); ?>">
+    <?php echo esc_html($atts['title']); ?>
+</div>