icuewidget-cli 0.4.45 → 0.4.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "icuewidget-cli",
-  "version": "0.4.45",
+  "version": "0.4.47",
   "description": "Create, validate, update, and package CORSAIR iCUE widgets.",
   "keywords": [
     "corsair",

package/src-node/constants.js

@@ -1,6 +1,6 @@
 export const APP_NAME = "icuewidget";
 export const NPM_PACKAGE_NAME = "icuewidget-cli";
-export const CLI_VERSION = "0.4.45";
+export const CLI_VERSION = "0.4.47";
 export const DEFAULT_APP_VERSION = "5.45";
 export const DEFAULT_FRAMEWORK_VERSION = "1.0.0";
 export const DEFAULT_PLATFORM = "windows";
@@ -13,6 +13,21 @@ export const ALLOWED_DEVICE_TYPES = new Set([
   "keyboard_lcd",
 ]);
 
+// Control types accepted by iCUE for x-icue-property meta parameters (data-type).
+// Anything else makes iCUE reject the widget with "Invalid meta parameter data type".
+export const ALLOWED_PROPERTY_TYPES = new Set([
+  "slider",
+  "switch",
+  "color",
+  "combobox",
+  "search-combobox",
+  "tab-buttons",
+  "textfield",
+  "media-selector",
+  "sensors-combobox",
+  "sensors-factory",
+]);
+
 export const SEMVER_RE = /^\d+\.\d+\.\d+$/;
 export const APP_VERSION_RE = /^\d+\.\d+(?:\.\d+)?$/;
 export const IDENTIFIER_RE = /^[A-Za-z0-9.-]+$/;

package/src-node/templates.js

@@ -15,21 +15,34 @@ export function translationTemplate(widgetName) {
 }
 
 export function indexTemplate(widgetName) {
-  return `<!doctype html>
+  // The widget title and the first property group share the widget name so the group
+  // merges with the default settings panel. tr() marks both for translation.
+  const titleExpr = `tr('${escapeSingleQuoted(widgetName)}')`;
+  const groups = renderGroups([
+    { title: titleExpr, properties: ["headline", "showSubtitle", "subtitle"] },
+    {
+      title: "tr('Widget Personalization')",
+      properties: ["textColor", "accentColor", "backgroundColor", "transparency"],
+    },
+  ]);
+  return `<!DOCTYPE html>
 <html lang="en">
 <head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>${escapeHtml(widgetName)}</title>
-  <link rel="icon" href="resources/icon.svg" type="image/svg+xml">
-  <link rel="stylesheet" href="styles/main.css">
-  <meta name="x-icue-property" content='{"name":"headline","label":"Headline","type":"text","default":"Hello World"}'>
-  <meta name="x-icue-property" content='{"name":"showSubtitle","label":"Show Subtitle","type":"boolean","default":true}'>
-  <meta name="x-icue-property" content='{"name":"subtitle","label":"Subtitle","type":"text","default":"Built with iCUE Widget CLI"}'>
-  <meta name="x-icue-property" content='{"name":"textColor","label":"Text Color","type":"color","default":"#ffffff"}'>
-  <meta name="x-icue-property" content='{"name":"accentColor","label":"Accent Color","type":"color","default":"#59c2ff"}'>
-  <meta name="x-icue-property" content='{"name":"backgroundColor","label":"Background","type":"color","default":"#111827"}'>
-  <meta name="x-icue-property" content='{"name":"transparency","label":"Transparency","type":"number","min":0,"max":100,"default":20}'>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${escapeHtml(titleExpr)}</title>
+  <link rel="icon" href="resources/icon.svg" type="image/svg+xml" />
+  <link rel="stylesheet" href="styles/main.css" />
+  <meta name="x-icue-property" content="headline" data-label="tr('Headline')" data-type="textfield" data-default="'Hello World'" />
+  <meta name="x-icue-property" content="showSubtitle" data-label="tr('Show Subtitle')" data-type="switch" data-default="true" />
+  <meta name="x-icue-property" content="subtitle" data-label="tr('Subtitle')" data-type="textfield" data-default="'Built with iCUE Widget CLI'" />
+  <meta name="x-icue-property" content="textColor" data-label="tr('Text Color')" data-type="color" data-default="'#ffffff'" />
+  <meta name="x-icue-property" content="accentColor" data-label="tr('Accent Color')" data-type="color" data-default="'#59c2ff'" />
+  <meta name="x-icue-property" content="backgroundColor" data-label="tr('Background')" data-type="color" data-default="'#111827'" />
+  <meta name="x-icue-property" content="transparency" data-label="tr('Transparency')" data-type="slider" data-default="20" data-min="0" data-max="100" data-step="1" data-unit-label="'%'" />
+  <script id="x-icue-groups" type="application/json">
+${groups}
+  </script>
 </head>
 <body>
   <main id="content">
@@ -38,6 +51,16 @@ export function indexTemplate(widgetName) {
     <p id="subtitle">Built with iCUE Widget CLI</p>
   </main>
   <script src="scripts/main.js"></script>
+  <script>
+    icueEvents = {
+      onICUEInitialized: function(payload) { applySettings(payload && payload.settings); },
+      onDataUpdated: function(payload) { applySettings(payload && payload.settings); },
+    };
+
+    if (iCUE_initialized) {
+      applySettings();
+    }
+  </script>
 </body>
 </html>
 `;
@@ -115,15 +138,6 @@ function applySettings(settings = {}) {
   subtitle.hidden = !state.showSubtitle;
 }
 
-window.icueEvents = {
-  onICUEInitialized(payload) {
-    applySettings(payload?.settings);
-  },
-  onDataUpdated(payload) {
-    applySettings(payload?.settings);
-  },
-};
-
 applySettings();
 `;
 
@@ -149,3 +163,27 @@ function escapeHtml(value) {
     .replaceAll(">", "&gt;")
     .replaceAll('"', "&quot;");
 }
+
+// Escape a value for embedding inside a single-quoted JavaScript string, e.g. tr('...').
+function escapeSingleQuoted(value) {
+  return String(value).replaceAll("\\", "\\\\").replaceAll("'", "\\'");
+}
+
+// Render the x-icue-groups JSON body. Each group's title/info are already valid JS
+// expressions (e.g. tr('...')) and are serialized as JSON strings; properties stay inline.
+function renderGroups(groups) {
+  const body = groups
+    .map((group) => {
+      const props = group.properties.map((name) => JSON.stringify(name)).join(", ");
+      const lines = [
+        "    {",
+        `      "title": ${JSON.stringify(group.title)},`,
+        `      "properties": [${props}]${group.info ? "," : ""}`,
+      ];
+      if (group.info) lines.push(`      "info": ${JSON.stringify(group.info)}`);
+      lines.push("    }");
+      return lines.join("\n");
+    })
+    .join(",\n");
+  return `  [\n${body}\n  ]`;
+}

package/src-node/validation.js

@@ -4,6 +4,7 @@ import vm from "node:vm";
 import {
   ALLOWED_DEVICE_TYPES,
   ALLOWED_PLATFORMS,
+  ALLOWED_PROPERTY_TYPES,
   APP_VERSION_RE,
   IDENTIFIER_RE,
   SEMVER_RE,
@@ -92,6 +93,10 @@ async function validateIndex(root, warnings) {
   if (!/rel=["'][^"']*icon/i.test(html)) warnings.push("index.html does not reference a favicon/icon.");
   if (!html.includes("icueEvents")) warnings.push("index.html or scripts do not reference icueEvents.");
 
+  validateHeadWellFormed(html);
+  validatePropertyTypes(html);
+  validatePropertyGroups(html);
+
   const assetRefs = [...extractAttributes(html, "href"), ...extractAttributes(html, "src")];
   for (const ref of assetRefs) {
     if (isRemote(ref) || ref.startsWith("data:") || ref.startsWith("#")) continue;
@@ -101,6 +106,81 @@ async function validateIndex(root, warnings) {
   }
 }
 
+// iCUE imports a widget by parsing <head> with a strict XML parser (Qt QDomDocument).
+// HTML5 void elements written without a self-closing slash (e.g. `<meta charset="utf-8">`)
+// are well-formed HTML but invalid XML: the parser never closes the tag, fails at </head>,
+// and reports "Missing Title Element" because <title> is never reached. Catch it here so
+// the widget fails validation instead of silently producing a package iCUE cannot import.
+const VOID_ELEMENTS = ["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "param", "source", "track", "wbr"];
+
+function validateHeadWellFormed(html) {
+  const headMatch = /<head\b[^>]*>([\s\S]*?)<\/head>/i.exec(html);
+  if (!headMatch) return;
+  const head = headMatch[1]
+    .replace(/<!--[\s\S]*?-->/g, "")
+    .replace(/<script\b[\s\S]*?<\/script>/gi, "")
+    .replace(/<style\b[\s\S]*?<\/style>/gi, "");
+  const re = new RegExp(`<(${VOID_ELEMENTS.join("|")})\\b[^>]*?>`, "gi");
+  let match;
+  while ((match = re.exec(head))) {
+    if (!match[0].endsWith("/>")) {
+      throw new ValidationError(
+        `index.html <head> has a non-self-closed <${match[1].toLowerCase()}> element: ${match[0].trim()}. ` +
+          `iCUE parses the head as XML on import, so void elements must self-close (for example <${match[1].toLowerCase()} ... />). ` +
+          `Otherwise iCUE rejects the widget with "Missing Title Element".`
+      );
+    }
+  }
+}
+
+// Each x-icue-property meta declares a control via data-type. iCUE rejects the widget
+// with "Invalid meta parameter data type" if the value is not a known control type, so
+// catch unknown types (e.g. "text" instead of "textfield", "boolean" instead of "switch")
+// at validation time instead of on import.
+function validatePropertyTypes(html) {
+  const metaRe = /<meta\b[^>]*\bname=["']x-icue-property["'][^>]*>/gi;
+  let meta;
+  while ((meta = metaRe.exec(html))) {
+    const tag = meta[0];
+    const typeMatch = /\bdata-type=["']([^"']*)["']/i.exec(tag);
+    if (!typeMatch) {
+      throw new ValidationError(`x-icue-property is missing a data-type attribute: ${tag.trim()}`);
+    }
+    const type = typeMatch[1].trim();
+    if (!ALLOWED_PROPERTY_TYPES.has(type)) {
+      throw new ValidationError(
+        `x-icue-property has an invalid data-type "${type}". ` +
+          `iCUE accepts: ${[...ALLOWED_PROPERTY_TYPES].join(", ")}. ` +
+          `(For example use "textfield" for text input and "switch" for a boolean toggle.)`
+      );
+    }
+  }
+}
+
+// The x-icue-groups script organizes property controls into settings panels. iCUE
+// JSON-parses it, so malformed JSON or an empty group silently drops the panel. Catch
+// it here. Group title/info are JS expressions (e.g. tr('...')) but are always JSON
+// strings, so the block as a whole stays valid JSON.
+function validatePropertyGroups(html) {
+  const match = /<script\b[^>]*\bid=["']x-icue-groups["'][^>]*>([\s\S]*?)<\/script>/i.exec(html);
+  if (!match) return;
+  let groups;
+  try {
+    groups = JSON.parse(match[1]);
+  } catch (error) {
+    throw new ValidationError(`x-icue-groups is not valid JSON: ${error.message}`);
+  }
+  if (!Array.isArray(groups)) throw new ValidationError("x-icue-groups must be a JSON array of groups.");
+  groups.forEach((group, index) => {
+    if (!group || typeof group !== "object" || Array.isArray(group)) {
+      throw new ValidationError(`x-icue-groups[${index}] must be an object.`);
+    }
+    if (!Array.isArray(group.properties) || group.properties.length === 0) {
+      throw new ValidationError(`x-icue-groups[${index}] must list at least one property.`);
+    }
+  });
+}
+
 function* extractAttributes(html, attribute) {
   const re = new RegExp(`${attribute}=["']([^"']+)["']`, "gi");
   let match;