feat: hero variants, block colors, theme preview tab, CSS var sync on upgrade
- Add .hero#primary / .hero#secondary CSS variant system to template.css - Add :nth-child() block color palette for top-a/b, bottom-a/b positions - Add named per-module overrides (#block-highlight, #block-cta, #block-alert) - Add all hero + block CSS variables to light/dark custom palette templates - Add theme-test.html with full visual CSS variable reference + color test - Add "Theme Preview" tab to admin config with embedded iframe of test sheet - Add script.php install/update script (Joomla 5/6 compatible) - Add sync_custom_vars.php — detects missing vars in user palettes on upgrade - Add en-GB and en-US language strings for new admin config fields - Update CSS_VARIABLES.md and CHANGELOG.md - Bump version to 03.09.02 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
406
src/sync_custom_vars.php
Normal file
406
src/sync_custom_vars.php
Normal file
@@ -0,0 +1,406 @@
|
||||
<?php
|
||||
/**
|
||||
* @package Joomla.Site
|
||||
* @subpackage Templates.MokoCassiopeia
|
||||
*
|
||||
* @copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
|
||||
* @license GNU General Public License version 2 or later; see LICENSE.txt
|
||||
*
|
||||
* CSS Variable Sync Utility
|
||||
*
|
||||
* Compares a user's custom palette file against the template starter file and
|
||||
* injects any missing CSS variable declarations. Existing user values are
|
||||
* never overwritten — only genuinely new variables are added.
|
||||
*
|
||||
* Usage (CLI):
|
||||
* php sync_custom_vars.php
|
||||
*
|
||||
* Usage (from Joomla script.php or plugin):
|
||||
* require_once __DIR__ . '/sync_custom_vars.php';
|
||||
* MokoCssVarSync::run();
|
||||
*
|
||||
* The script auto-detects Joomla's root by walking up from __DIR__.
|
||||
*/
|
||||
|
||||
defined('_JEXEC') or define('MOKO_CLI', true);
|
||||
|
||||
final class MokoCssVarSync
|
||||
{
|
||||
/**
|
||||
* Template name used in Joomla's media path.
|
||||
*/
|
||||
private const TPL = 'mokocassiopeia';
|
||||
|
||||
/**
|
||||
* Palette pairs: [starter template path relative to this file, user file relative to Joomla root].
|
||||
*/
|
||||
private const PALETTES = [
|
||||
[
|
||||
'starter' => 'templates/light.custom.css',
|
||||
'user' => 'media/templates/site/%s/css/theme/light.custom.css',
|
||||
],
|
||||
[
|
||||
'starter' => 'templates/dark.custom.css',
|
||||
'user' => 'media/templates/site/%s/css/theme/dark.custom.css',
|
||||
],
|
||||
];
|
||||
|
||||
/**
|
||||
* Run the sync for all palette pairs.
|
||||
*
|
||||
* @param string|null $joomlaRoot Absolute path to Joomla root (auto-detected if null).
|
||||
* @return array<string, array{added: string[], skipped: string[]}> Results keyed by file path.
|
||||
*/
|
||||
public static function run(?string $joomlaRoot = null): array
|
||||
{
|
||||
$tplDir = self::resolveTemplateDir();
|
||||
$root = $joomlaRoot ?? self::detectJoomlaRoot();
|
||||
|
||||
$results = [];
|
||||
|
||||
foreach (self::PALETTES as $pair) {
|
||||
$starterPath = $tplDir . '/' . $pair['starter'];
|
||||
$userPath = $root . '/' . sprintf($pair['user'], self::TPL);
|
||||
|
||||
if (!is_file($starterPath)) {
|
||||
self::log("SKIP starter not found: {$starterPath}");
|
||||
continue;
|
||||
}
|
||||
|
||||
if (!is_file($userPath)) {
|
||||
self::log("SKIP user file not found (custom palette not deployed): {$userPath}");
|
||||
continue;
|
||||
}
|
||||
|
||||
$result = self::syncFile($starterPath, $userPath);
|
||||
$results[$userPath] = $result;
|
||||
|
||||
$addedCount = count($result['added']);
|
||||
if ($addedCount > 0) {
|
||||
self::log("ADDED {$addedCount} variable(s) to {$userPath}");
|
||||
foreach ($result['added'] as $var) {
|
||||
self::log(" + {$var}");
|
||||
}
|
||||
} else {
|
||||
self::log("OK {$userPath} — all variables present");
|
||||
}
|
||||
}
|
||||
|
||||
return $results;
|
||||
}
|
||||
|
||||
/**
|
||||
* Compare a starter file against a user file and inject missing variables.
|
||||
*
|
||||
* @param string $starterPath Absolute path to the starter template CSS.
|
||||
* @param string $userPath Absolute path to the user's custom CSS.
|
||||
* @return array{added: string[], skipped: string[]}
|
||||
*/
|
||||
private static function syncFile(string $starterPath, string $userPath): array
|
||||
{
|
||||
$starterVars = self::extractVarsWithContext($starterPath);
|
||||
$userVars = self::extractVarNames($userPath);
|
||||
|
||||
$missing = [];
|
||||
foreach ($starterVars as $name => $declaration) {
|
||||
if (!isset($userVars[$name])) {
|
||||
$missing[$name] = $declaration;
|
||||
}
|
||||
}
|
||||
|
||||
if (empty($missing)) {
|
||||
return ['added' => [], 'skipped' => []];
|
||||
}
|
||||
|
||||
// Group missing variables by their section comment header.
|
||||
$sections = self::groupBySection($missing, $starterPath);
|
||||
|
||||
// Build the injection block.
|
||||
$injection = self::buildInjectionBlock($sections);
|
||||
|
||||
// Insert before the closing } of the :root rule.
|
||||
$userCss = file_get_contents($userPath);
|
||||
$userCss = self::injectBeforeRootClose($userCss, $injection);
|
||||
|
||||
// Write back (atomic: write to .tmp then rename).
|
||||
$tmpPath = $userPath . '.tmp';
|
||||
file_put_contents($tmpPath, $userCss);
|
||||
rename($tmpPath, $userPath);
|
||||
|
||||
return ['added' => array_keys($missing), 'skipped' => []];
|
||||
}
|
||||
|
||||
/**
|
||||
* Extract CSS custom property declarations with their full text (name: value).
|
||||
* Only extracts from the first :root block.
|
||||
*
|
||||
* @return array<string, string> Variable name => full declaration line.
|
||||
*/
|
||||
private static function extractVarsWithContext(string $filePath): array
|
||||
{
|
||||
$css = file_get_contents($filePath);
|
||||
$vars = [];
|
||||
|
||||
// Match --variable-name: value (possibly spanning multiple lines until ;)
|
||||
if (preg_match_all('/^\s*(--[\w-]+)\s*:\s*([^;]+);/m', $css, $matches, PREG_SET_ORDER)) {
|
||||
foreach ($matches as $m) {
|
||||
$name = trim($m[1]);
|
||||
$value = trim($m[2]);
|
||||
$vars[$name] = "{$name}: {$value};";
|
||||
}
|
||||
}
|
||||
|
||||
return $vars;
|
||||
}
|
||||
|
||||
/**
|
||||
* Extract just the variable names present in a CSS file.
|
||||
*
|
||||
* @return array<string, true>
|
||||
*/
|
||||
private static function extractVarNames(string $filePath): array
|
||||
{
|
||||
$css = file_get_contents($filePath);
|
||||
$vars = [];
|
||||
|
||||
if (preg_match_all('/^\s*(--[\w-]+)\s*:/m', $css, $matches)) {
|
||||
foreach ($matches[1] as $name) {
|
||||
$vars[trim($name)] = true;
|
||||
}
|
||||
}
|
||||
|
||||
return $vars;
|
||||
}
|
||||
|
||||
/**
|
||||
* Group missing variables by the section comment they appear under in the starter file.
|
||||
*
|
||||
* @param array<string, string> $missing Variable name => declaration.
|
||||
* @param string $starterPath Path to starter file.
|
||||
* @return array<string, string[]> Section header => list of declarations.
|
||||
*/
|
||||
private static function groupBySection(array $missing, string $starterPath): array
|
||||
{
|
||||
$lines = file($starterPath, FILE_IGNORE_NEW_LINES);
|
||||
$section = 'Uncategorised';
|
||||
$map = []; // variable name => section
|
||||
|
||||
foreach ($lines as $line) {
|
||||
// Detect section comment headers like /* ===== HERO VARIANTS ===== */
|
||||
if (preg_match('/\/\*\s*=+\s*(.+?)\s*=+\s*\*\//', $line, $m)) {
|
||||
$section = trim($m[1]);
|
||||
}
|
||||
// Detect variable declaration
|
||||
if (preg_match('/^\s*(--[\w-]+)\s*:/', $line, $m)) {
|
||||
$name = trim($m[1]);
|
||||
if (isset($missing[$name])) {
|
||||
$map[$name] = $section;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Group by section
|
||||
$sections = [];
|
||||
foreach ($missing as $name => $declaration) {
|
||||
$sec = $map[$name] ?? 'Uncategorised';
|
||||
$sections[$sec][] = $declaration;
|
||||
}
|
||||
|
||||
return $sections;
|
||||
}
|
||||
|
||||
/**
|
||||
* Build a CSS block from grouped sections ready for injection.
|
||||
*/
|
||||
private static function buildInjectionBlock(array $sections): string
|
||||
{
|
||||
$lines = [];
|
||||
$lines[] = '';
|
||||
$lines[] = '/* ===== VARIABLES ADDED BY SYNC (' . date('Y-m-d') . ') ===== */';
|
||||
|
||||
foreach ($sections as $sectionName => $declarations) {
|
||||
$lines[] = '';
|
||||
$lines[] = "/* -- {$sectionName} -- */";
|
||||
foreach ($declarations as $decl) {
|
||||
$lines[] = $decl;
|
||||
}
|
||||
}
|
||||
|
||||
$lines[] = '';
|
||||
|
||||
return implode("\n", $lines);
|
||||
}
|
||||
|
||||
/**
|
||||
* Inject a block of CSS just before the closing } of the :root[data-bs-theme] rule.
|
||||
*/
|
||||
private static function injectBeforeRootClose(string $css, string $block): string
|
||||
{
|
||||
// Find the :root block's closing brace. The :root rule is the first major
|
||||
// rule in the file; its closing } is on its own line.
|
||||
// Strategy: find the LAST } that is preceded only by CSS variable content.
|
||||
// More robustly: find the first } that appears on its own line (possibly
|
||||
// with whitespace), which closes the :root block.
|
||||
|
||||
// Walk backwards from each } to see if it's inside the :root block.
|
||||
// Simple approach: the :root closing } is the first bare } on its own line.
|
||||
$pos = self::findRootClosingBrace($css);
|
||||
|
||||
if ($pos === false) {
|
||||
// Fallback: append before last }
|
||||
$pos = strrpos($css, '}');
|
||||
}
|
||||
|
||||
if ($pos === false) {
|
||||
// Last resort: append to end
|
||||
return $css . $block;
|
||||
}
|
||||
|
||||
return substr($css, 0, $pos) . $block . substr($css, $pos);
|
||||
}
|
||||
|
||||
/**
|
||||
* Find the byte position of the closing } for the :root rule.
|
||||
*/
|
||||
private static function findRootClosingBrace(string $css): int|false
|
||||
{
|
||||
// Find where :root starts
|
||||
$rootStart = preg_match('/:root\b/', $css, $m, PREG_OFFSET_CAPTURE);
|
||||
if (!$rootStart) {
|
||||
return false;
|
||||
}
|
||||
|
||||
$offset = $m[0][1];
|
||||
$depth = 0;
|
||||
$len = strlen($css);
|
||||
|
||||
for ($i = $offset; $i < $len; $i++) {
|
||||
if ($css[$i] === '{') {
|
||||
$depth++;
|
||||
} elseif ($css[$i] === '}') {
|
||||
$depth--;
|
||||
if ($depth === 0) {
|
||||
return $i;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve the template source directory (where this file lives).
|
||||
*/
|
||||
private static function resolveTemplateDir(): string
|
||||
{
|
||||
return dirname(__FILE__);
|
||||
}
|
||||
|
||||
/**
|
||||
* Auto-detect Joomla root by walking up from template dir looking for
|
||||
* configuration.php or the media/templates directory structure.
|
||||
*/
|
||||
private static function detectJoomlaRoot(): string
|
||||
{
|
||||
$dir = dirname(__FILE__);
|
||||
|
||||
// Walk up max 10 levels
|
||||
for ($i = 0; $i < 10; $i++) {
|
||||
if (is_file($dir . '/configuration.php')) {
|
||||
return $dir;
|
||||
}
|
||||
// Also check for the media/templates structure (works in dev too)
|
||||
if (is_dir($dir . '/media/templates')) {
|
||||
return $dir;
|
||||
}
|
||||
$parent = dirname($dir);
|
||||
if ($parent === $dir) {
|
||||
break;
|
||||
}
|
||||
$dir = $parent;
|
||||
}
|
||||
|
||||
// Fallback for dev: if JPATH_ROOT is defined, use it
|
||||
if (defined('JPATH_ROOT')) {
|
||||
return JPATH_ROOT;
|
||||
}
|
||||
|
||||
self::log('WARNING: Could not auto-detect Joomla root. Pass it explicitly.');
|
||||
return dirname(__FILE__);
|
||||
}
|
||||
|
||||
/**
|
||||
* Log a message (CLI: stdout, web: Joomla enqueueMessage if available).
|
||||
*/
|
||||
private static function log(string $message): void
|
||||
{
|
||||
if (defined('MOKO_CLI') || PHP_SAPI === 'cli') {
|
||||
echo $message . PHP_EOL;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Dry-run mode: report what would be added without writing.
|
||||
*
|
||||
* @return array<string, string[]> File path => list of missing variable names.
|
||||
*/
|
||||
public static function dryRun(?string $joomlaRoot = null): array
|
||||
{
|
||||
$tplDir = self::resolveTemplateDir();
|
||||
$root = $joomlaRoot ?? self::detectJoomlaRoot();
|
||||
$report = [];
|
||||
|
||||
foreach (self::PALETTES as $pair) {
|
||||
$starterPath = $tplDir . '/' . $pair['starter'];
|
||||
$userPath = $root . '/' . sprintf($pair['user'], self::TPL);
|
||||
|
||||
if (!is_file($starterPath) || !is_file($userPath)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$starterVars = self::extractVarsWithContext($starterPath);
|
||||
$userVars = self::extractVarNames($userPath);
|
||||
|
||||
$missing = [];
|
||||
foreach ($starterVars as $name => $declaration) {
|
||||
if (!isset($userVars[$name])) {
|
||||
$missing[] = $name;
|
||||
}
|
||||
}
|
||||
|
||||
if (!empty($missing)) {
|
||||
$report[$userPath] = $missing;
|
||||
}
|
||||
}
|
||||
|
||||
return $report;
|
||||
}
|
||||
}
|
||||
|
||||
// CLI entry point
|
||||
if (PHP_SAPI === 'cli' && realpath($argv[0] ?? '') === realpath(__FILE__)) {
|
||||
$dryRun = in_array('--dry-run', $argv, true);
|
||||
|
||||
echo "MokoCassiopeia CSS Variable Sync\n";
|
||||
echo str_repeat('─', 40) . "\n\n";
|
||||
|
||||
if ($dryRun) {
|
||||
echo "DRY RUN — no files will be modified\n\n";
|
||||
$report = MokoCssVarSync::dryRun();
|
||||
if (empty($report)) {
|
||||
echo "All custom palettes are up to date.\n";
|
||||
} else {
|
||||
foreach ($report as $file => $vars) {
|
||||
echo "MISSING in {$file}:\n";
|
||||
foreach ($vars as $var) {
|
||||
echo " - {$var}\n";
|
||||
}
|
||||
echo "\n";
|
||||
}
|
||||
}
|
||||
} else {
|
||||
MokoCssVarSync::run();
|
||||
}
|
||||
|
||||
echo "\nDone.\n";
|
||||
}
|
||||
Reference in New Issue
Block a user