@schalkneethling/miyagi-core 4.4.4 → 4.6.0

package/frontend/assets/js/_controls.js

@@ -0,0 +1,206 @@
+const CACHE_PREFIX = "miyagi-controls::";
+const LS_MODE_KEY = "miyagi-controls-mode";
+
+function getPanel() {
+  return document.getElementById("controls-panel");
+}
+
+function getFieldsContainer() {
+  return document.getElementById("controls-fields");
+}
+
+function hidePanel() {
+  const panel = getPanel();
+  if (!panel) {
+    return;
+  }
+  panel.hidden = true;
+  getFieldsContainer().innerHTML = "";
+}
+
+function showPanel() {
+  const panel = getPanel();
+  if (panel) {
+    panel.hidden = false;
+  }
+}
+
+function initMode() {
+  const panel = getPanel();
+  if (!panel) {
+    return;
+  }
+
+  const mode = localStorage.getItem(LS_MODE_KEY) ?? "docked";
+  panel.setAttribute("data-mode", mode);
+
+  const toggle = document.getElementById("controls-mode-toggle");
+  if (toggle) {
+    toggle.addEventListener("click", () => {
+      const next =
+        panel.getAttribute("data-mode") === "docked" ? "floating" : "docked";
+      panel.setAttribute("data-mode", next);
+      localStorage.setItem(LS_MODE_KEY, next);
+    });
+  }
+}
+
+function buildOverrideSrc(baseSrc, property, value) {
+  const url = new URL(baseSrc, window.location.origin);
+  url.searchParams.set(`overrides[${property}]`, String(value));
+  return url.pathname + url.search;
+}
+
+function updateIframe(src) {
+  const iframe = document.getElementById("iframe");
+  const frameWrapper = document.querySelector(".FrameWrapper");
+  if (!iframe || !frameWrapper) {
+    return;
+  }
+  iframe.remove();
+  iframe.src = src;
+  frameWrapper.appendChild(iframe);
+  loadControls(src);
+}
+
+function renderControls(controls, iframeSrc) {
+  const fieldsContainer = getFieldsContainer();
+  fieldsContainer.innerHTML = "";
+
+  const url = new URL(iframeSrc, window.location.origin);
+  const urlOverrides = {};
+  url.searchParams.forEach((value, key) => {
+    const match = key.match(/^overrides\[(.+)\]$/);
+    if (match) {
+      urlOverrides[match[1]] = value;
+    }
+  });
+
+  controls.forEach(({ property, type, values, current }) => {
+    const displayValue =
+      urlOverrides[property] !== undefined ? urlOverrides[property] : current;
+
+    const fieldEl = document.createElement("div");
+    fieldEl.className = "Controls-field";
+
+    const labelEl = document.createElement("label");
+    labelEl.className = "Controls-label";
+
+    const labelText = document.createElement("span");
+    labelText.className = "Controls-labelText";
+    labelText.textContent = property;
+    labelEl.appendChild(labelText);
+
+    let inputEl;
+
+    if (type === "enum") {
+      inputEl = document.createElement("select");
+      inputEl.className = "Controls-select";
+      values.forEach((value) => {
+        const option = document.createElement("option");
+        option.value = value;
+        option.textContent = value;
+        // eslint-disable-next-line eqeqeq
+        if (value == displayValue) {
+          option.selected = true;
+        }
+        inputEl.appendChild(option);
+      });
+      inputEl.addEventListener("change", () => {
+        updateIframe(buildOverrideSrc(iframeSrc, property, inputEl.value));
+      });
+    } else if (type === "boolean") {
+      inputEl = document.createElement("input");
+      inputEl.type = "checkbox";
+      inputEl.className = "Controls-checkbox";
+      inputEl.checked =
+        typeof displayValue === "string"
+          ? displayValue === "true"
+          : Boolean(displayValue);
+      inputEl.addEventListener("change", () => {
+        updateIframe(buildOverrideSrc(iframeSrc, property, inputEl.checked));
+      });
+    }
+
+    if (inputEl) {
+      labelEl.appendChild(inputEl);
+      fieldEl.appendChild(labelEl);
+      fieldsContainer.appendChild(fieldEl);
+    }
+  });
+
+  showPanel();
+}
+
+export async function loadControls(iframeSrc) {
+  const url = new URL(iframeSrc, window.location.origin);
+  const file = url.searchParams.get("file");
+  const variation = url.searchParams.get("variation");
+
+  if (!file || !variation) {
+    hidePanel();
+    return;
+  }
+
+  const cacheKey = `${CACHE_PREFIX}${file}::${variation}`;
+  let data = null;
+  try {
+    data = JSON.parse(sessionStorage.getItem(cacheKey) ?? "null");
+  } catch {
+    sessionStorage.removeItem(cacheKey);
+  }
+
+  if (!data) {
+    try {
+      const res = await fetch(
+        `/api/component-controls?file=${encodeURIComponent(file)}&variation=${encodeURIComponent(variation)}`,
+      );
+      data = await res.json();
+      sessionStorage.setItem(cacheKey, JSON.stringify(data));
+    } catch {
+      hidePanel();
+      return;
+    }
+  }
+
+  if (data.controls?.length) {
+    renderControls(data.controls, iframeSrc);
+  } else {
+    hidePanel();
+  }
+}
+
+export function invalidateControlsCache(paths) {
+  for (const key of Object.keys(sessionStorage)) {
+    if (!key.startsWith(CACHE_PREFIX)) {
+      continue;
+    }
+
+    if (!paths || paths.length === 0) {
+      sessionStorage.removeItem(key);
+      continue;
+    }
+
+    const file = key.slice(CACHE_PREFIX.length).split("::")[0];
+    if (paths.some((p) => p.includes(file))) {
+      sessionStorage.removeItem(key);
+    }
+  }
+}
+
+window.addEventListener("message", (e) => {
+  if (e.data?.type === "miyagi:invalidate-cache") {
+    invalidateControlsCache(e.data.paths ?? []);
+  }
+});
+
+document.addEventListener("DOMContentLoaded", () => {
+  initMode();
+  const iframe = document.getElementById("iframe");
+  if (iframe) {
+    const src = iframe.getAttribute("src");
+    if (src) {
+      loadControls(src);
+    }
+  }
+});

package/frontend/assets/js/_main.js

@@ -1,5 +1,6 @@
 import "./_goto.js";
 import "./_search.js";
+import { loadControls } from "./_controls.js";
 import ThemeConfigSwitcher from "./config-switcher/theme.js";
 import TextDirectionConfigSwitcher from "./config-switcher/text-direction.js";
 import DevelopmentModeConfigSwitcher from "./config-switcher/development-mode.js";
@@ -77,6 +78,7 @@ class Main {
     this.elements.iframe.remove();
     this.elements.iframe.src = src;
     this.elements.frameWrapper.appendChild(this.elements.iframe);
+    loadControls(src);
   }
 
   /**

package/frontend/assets/js/_socket.js

@@ -49,6 +49,22 @@ function parseScope(messageData) {
   return parseJsonScope(messageData);
 }
 
+function parseReason(messageData) {
+  try {
+    return JSON.parse(messageData).reason ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function parsePaths(messageData) {
+  try {
+    return JSON.parse(messageData).paths ?? [];
+  } catch {
+    return [];
+  }
+}
+
 function scheduleReconnect() {
   const jitter = Math.floor(Math.random() * 100);
   const delay = Math.min(retryDelay + jitter, MAX_RETRY_DELAY_MS);
@@ -67,6 +83,13 @@ function connect() {
   };
 
   websocket.onmessage = (message) => {
+    const reason = parseReason(message.data);
+    if (reason === "schema" || reason === "data") {
+      window.parent.postMessage(
+        { type: "miyagi:invalidate-cache", paths: parsePaths(message.data) },
+        "*",
+      );
+    }
     triggerReload(parseScope(message.data));
   };
 

package/frontend/assets/js/iframe.js

@@ -13,6 +13,18 @@ if (
   window.location = new URL(window.location).replace("&embedded=true", "");
 }
 
+document.addEventListener("DOMContentLoaded", () => {
+  const mockDataEl = document.getElementById("miyagi-mock-data");
+  if (mockDataEl) {
+    try {
+      const detail = JSON.parse(mockDataEl.textContent);
+      document.dispatchEvent(new CustomEvent("miyagi:mockdata", { detail }));
+    } catch (e) {
+      console.debug("[miyagi] Failed to parse mock data island:", e);
+    }
+  }
+});
+
 document.addEventListener("DOMContentLoaded", function () {
   const links = Array.from(document.querySelectorAll(".Component-file"));
   const styleguide = document.querySelector(".Styleguide");

package/frontend/views/component_variation.twig.miyagi

@@ -24,6 +24,9 @@
     {% if assets.js %}
       <script src="{{ assets.js }}"></script>
     {% endif %}
+    {% if mockDataResolved is defined %}
+    <script type="application/json" id="miyagi-mock-data">{{ mockDataResolved|replace({'</script>': '<\\/script>'})|raw }}</script>
+    {% endif %}
     <script>
       {{ theme.js }}
 

package/frontend/views/main.twig.miyagi

@@ -19,6 +19,15 @@
       <div class="FrameWrapper">
         <iframe class="Frame" id="iframe" src="{{ iframeSrc }}" name="iframe" title="Components"></iframe>
       </div>
+      <div class="Controls" id="controls-panel" hidden>
+        <div class="Controls-header">
+          <h2 class="Controls-heading">Controls</h2>
+          <button class="Controls-modeToggle" id="controls-mode-toggle">
+            <span class="u-hiddenVisually">Toggle floating panel</span>
+          </button>
+        </div>
+        <div class="Controls-fields" id="controls-fields"></div>
+      </div>
     </main>
   </body>
 </html>

package/lib/cli/index.js

@@ -2,8 +2,10 @@ import lintImport from "./lint.js";
 import componentImport from "./component.js";
 import drupalAssetsImport from "./drupal-assets.js";
 import doctorImport from "./doctor.js";
+import validateHtmlImport from "./validate-html.js";
 
 export const lint = lintImport;
 export const component = componentImport;
 export const drupalAssets = drupalAssetsImport;
 export const doctor = doctorImport;
+export const validateHtml = validateHtmlImport;

package/lib/cli/run.js

@@ -9,6 +9,7 @@ import {
   component as createComponentViaCli,
   drupalAssets,
   doctor,
+  validateHtml as validateHtmlCli,
 } from "./index.js";
 import { EXIT_CODES, MiyagiError } from "../errors.js";
 
@@ -220,6 +221,11 @@ async function runDrupalAssetsCommand(args) {
  * @param {object} args
  * @returns {Promise<object>}
  */
+async function runValidateHtmlCommand(args) {
+  applyCliEnv(args);
+  return await validateHtmlCli(args);
+}
+
 async function runDoctorCommand(args) {
   applyCliEnv(args);
   return await doctor(args);
@@ -268,6 +274,7 @@ export async function runCli(argv = process.argv) {
       new: runComponentCommand,
       mocks: runMocksCommand,
       lint: runLintCommand,
+      validateHtml: runValidateHtmlCommand,
       drupalAssets: runDrupalAssetsCommand,
       doctor: runDoctorCommand,
     },

package/lib/cli/validate-html.js

@@ -0,0 +1,110 @@
+import path from "path";
+import { writeFile } from "node:fs/promises";
+import init from "./app.js";
+import getConfig from "../config.js";
+import log from "../logger.js";
+import { t } from "../i18n/index.js";
+import { EXIT_CODES } from "../errors.js";
+import {
+  validateAllHtml,
+  validateComponentHtml,
+  validateHtmlFiles,
+} from "../validator/html.js";
+import { generateMarkdownReport } from "../validator/html-report.js";
+
+/**
+ * @param {object} args
+ * @returns {Promise<object>}
+ */
+export default async function validateHtml(args) {
+  process.env.NODE_ENV = "development";
+
+  const filesGlob = args.files;
+
+  if (filesGlob) {
+    // Files mode — validate pre-existing HTML files
+    const config = await getConfig(args);
+    global.config = config;
+    const results = await validateHtmlFiles(filesGlob);
+    return await writeReport(results, args, config);
+  }
+
+  // Render mode — render components and validate
+  const componentArg = args.component;
+  const config = await getConfig(args);
+  global.app = await init(config);
+
+  let results;
+
+  if (componentArg) {
+    const component = global.state.routes.find(
+      ({ alias }) =>
+        alias === path.relative(config.components.folder, componentArg),
+    );
+
+    if (!component) {
+      const message = t("htmlValidation.componentNotFound").replace("{{component}}", componentArg);
+      log("error", message);
+      return {
+        success: false,
+        code: EXIT_CODES.CLI_USAGE_ERROR,
+        shouldExit: true,
+        message,
+      };
+    }
+
+    const result = await validateComponentHtml(component);
+    results = {
+      components: [result],
+      summary: {
+        total: 1,
+        passed: result.variations.every((v) => v.valid) ? 1 : 0,
+        failed: result.variations.some((v) => !v.valid) ? 1 : 0,
+        errors: result.variations.reduce(
+          (sum, v) =>
+            sum + v.messages.filter((m) => m.severity === 2).length,
+          0,
+        ),
+        warnings: result.variations.reduce(
+          (sum, v) =>
+            sum + v.messages.filter((m) => m.severity !== 2).length,
+          0,
+        ),
+      },
+    };
+  } else {
+    results = await validateAllHtml();
+  }
+
+  return await writeReport(results, args, config);
+}
+
+/**
+ * @param {object} results
+ * @param {object} args
+ * @param {object} config
+ * @returns {Promise<object>}
+ */
+async function writeReport(results, args, config) {
+  const report = generateMarkdownReport(results);
+  const outputPath = args.output ?? config.htmlValidation?.output ?? "html-validation-report.md";
+
+  try {
+    await writeFile(outputPath, report, "utf-8");
+    log(
+      "info",
+      t("htmlValidation.reportWritten").replace("{{path}}", outputPath),
+    );
+  } catch (error) {
+    log("error", t("htmlValidation.reportWriteFailed").replace("{{error}}", error.message));
+  }
+
+  return {
+    success: results.summary.failed === 0,
+    code:
+      results.summary.failed === 0
+        ? EXIT_CODES.SUCCESS
+        : EXIT_CODES.VALIDATION_ERROR,
+    shouldExit: true,
+  };
+}

package/lib/default-config.js

@@ -49,6 +49,18 @@ export default {
     lint: {
       logLevel: "error",
     },
+    htmlValidation: {
+      output: "html-validation-report.md",
+      htmlValidateConfig: {
+        extends: ["html-validate:recommended"],
+        rules: {
+          "doctype-style": "off",
+          "input-missing-label": "error",
+          "missing-doctype": "off",
+          "no-missing-references": "off",
+        },
+      },
+    },
     extensions: [],
     files: {
       css: {

package/lib/i18n/en.js

@@ -31,6 +31,29 @@ export default {
       done: "Finished creating component {{component}}.",
     },
   },
+  htmlValidation: {
+    all: {
+      start: "Validating rendered HTML for all components\u2026",
+      valid: "All rendered HTML is valid!",
+      invalid: {
+        one: "1 component has HTML validation errors!",
+        other: "{{amount}} components have HTML validation errors!",
+      },
+    },
+    component: {
+      start: "Validating rendered HTML for {{component}}\u2026",
+      valid: "Rendered HTML is valid!",
+      renderFailed:
+        "Could not render {{component}} variation {{variation}}.",
+    },
+    files: {
+      start: "Validating HTML files matching {{pattern}}\u2026",
+      noFilesFound: "No files found matching {{pattern}}.",
+    },
+    componentNotFound: "The component {{component}} does not seem to exist.",
+    reportWriteFailed: "Failed to write report: {{error}}.",
+    reportWritten: "HTML validation report written to {{path}}.",
+  },
   linter: {
     all: {
       start: "Validating schema files and mock data for all components…",

package/lib/init/args.js

@@ -101,6 +101,28 @@ export default function createCli(handlers, argv = process.argv) {
         }),
       commandHandler(handlers.lint),
     )
+    .command(
+      "validate-html [component]",
+      "Validates rendered HTML of components and generates a Markdown report",
+      (builder) =>
+        builder
+          .positional("component", {
+            description: "Optional component path to validate (render mode)",
+            type: "string",
+          })
+          .option("files", {
+            alias: "f",
+            description:
+              "Glob pattern pointing to HTML files to validate (e.g. build/miyagi/component-*.html)",
+            type: "string",
+          })
+          .option("output", {
+            alias: "o",
+            description: "Path for the Markdown report file",
+            type: "string",
+          }),
+      commandHandler(handlers.validateHtml),
+    )
     .command(
       "drupal-assets",
       "Resolves Drupal *.libraries.yml dependencies and updates component $assets in mock files",

package/lib/init/router.js

@@ -160,8 +160,61 @@ export default function Router() {
     }
   });
 
+  global.app.get("/api/component-controls", async (req, res) => {
+    const { file, variation } = req.query;
+
+    if (!file || !variation) {
+      return res.json({ controls: [] });
+    }
+
+    const routesEntry = global.state.routes.find(
+      (route) => route.paths.dir.short === file,
+    );
+
+    if (!routesEntry) {
+      return res.json({ controls: [] });
+    }
+
+    const schemaPath = routesEntry.paths?.schema?.full;
+    const schema = schemaPath
+      ? global.state.fileContents[schemaPath]
+      : undefined;
+
+    if (!schema?.properties) {
+      return res.json({ controls: [] });
+    }
+
+    if (!getDataForComponent(routesEntry)) {
+      return res.json({ controls: [] });
+    }
+
+    const data = await getVariationData(routesEntry, decodeURI(variation));
+    const resolvedData = data?.resolved ?? {};
+    const controls = [];
+
+    for (const [property, propSchema] of Object.entries(schema.properties)) {
+      if (Array.isArray(propSchema.enum) && propSchema.enum.length > 0) {
+        controls.push({
+          property,
+          type: "enum",
+          values: propSchema.enum,
+          current:
+            resolvedData[property] ?? propSchema.default ?? propSchema.enum[0],
+        });
+      } else if (propSchema.type === "boolean") {
+        controls.push({
+          property,
+          type: "boolean",
+          current: resolvedData[property] ?? propSchema.default ?? false,
+        });
+      }
+    }
+
+    return res.json({ controls });
+  });
+
   global.app.get("/component", async (req, res) => {
-    const { file, variation, embedded } = req.query;
+    const { file, variation, embedded, overrides } = req.query;
 
     if (!file) {
       return res.redirect(302, global.config.indexPath.default);
@@ -209,6 +262,7 @@ export default function Router() {
             variation,
             cookies: req.cookies,
             data,
+            overrides: overrides ?? null,
           });
         }
 
@@ -224,6 +278,7 @@ export default function Router() {
           componentData: data?.resolved ?? {},
           componentDeclaredAssets: data?.$assets || null,
           cookies: req.cookies,
+          overrides: overrides ?? null,
         });
       }
 

package/lib/render/helpers/apply-overrides.js

@@ -0,0 +1,36 @@
+/**
+ * Applies query-param override values to resolved component data.
+ * Values are coerced to the appropriate type based on the JSON schema.
+ * Only schema-defined properties are overridden; unknown keys are ignored.
+ *
+ * @param {object} data - the resolved mock data object
+ * @param {object} overrides - key/value overrides from req.query.overrides
+ * @param {object} [schema] - the JSON schema for the component
+ * @returns {object} a new object with overrides applied
+ */
+export default function applyOverrides(data, overrides, schema) {
+  if (!overrides || typeof overrides !== "object") {
+    return data;
+  }
+
+  const properties = schema?.properties ?? {};
+  const coerced = {};
+
+  for (const [key, value] of Object.entries(overrides)) {
+    const propSchema = properties[key];
+    if (!propSchema) continue;
+
+    if (propSchema.type === "boolean") {
+      coerced[key] = value === "true";
+    } else if (
+      Array.isArray(propSchema.enum) &&
+      propSchema.enum.every((v) => typeof v === "number")
+    ) {
+      coerced[key] = Number(value);
+    } else {
+      coerced[key] = value;
+    }
+  }
+
+  return { ...data, ...coerced };
+}

package/lib/render/views/iframe/variation.js

@@ -4,6 +4,7 @@ import { t } from "../../../i18n/index.js";
 import * as helpers from "../../../helpers.js";
 import validateMocks from "../../../validator/mocks.js";
 import { getUserUiConfig, getThemeMode } from "../../helpers.js";
+import applyOverrides from "../../helpers/apply-overrides.js";
 
 /**
  * @param {object} object - parameter object
@@ -22,9 +23,16 @@ export default async function renderIframeVariation({
   cb,
   cookies,
   data,
+  overrides,
 }) {
   const rawComponentData = (data && data.raw) ?? null;
-  const componentData = (data && data.resolved) ?? null;
+  let componentData = (data && data.resolved) ?? null;
+
+  if (overrides && componentData) {
+    const schema =
+      global.state.fileContents[component.paths?.schema?.full] ?? null;
+    componentData = applyOverrides(componentData, overrides, schema);
+  }
   const themeMode = getThemeMode(cookies);
 
   const validatedMocks = validateMocks(component, [
@@ -44,6 +52,16 @@ export default async function renderIframeVariation({
     standaloneUrl = `/component?file=${path.dirname(
       component.paths.tpl.short,
     )}&variation=${encodeURIComponent(variation)}`;
+
+    if (overrides && Object.keys(overrides).length > 0) {
+      const overrideParams = Object.entries(overrides)
+        .map(
+          ([k, v]) =>
+            `overrides[${encodeURIComponent(k)}]=${encodeURIComponent(v)}`,
+        )
+        .join("&");
+      standaloneUrl += `&${overrideParams}`;
+    }
   }
 
   const mockValidation = validatedMocks