brandrail 0.4.0 → 0.4.1

package/dist/brandrail.mjs

@@ -723,7 +723,7 @@ function webComponentSetup(target, u, tag) {
   const load = u.importPath ? `Load it once with \`import "${u.importPath}";\` at the app entry.` : "";
   switch (target) {
     case "angular":
-      return `Web component: add \`CUSTOM_ELEMENTS_SCHEMA\` to the component's \`schemas\`. ${load}`.trim();
+      return `Web component: add \`CUSTOM_ELEMENTS_SCHEMA\` to the \`schemas\` of every NgModule or standalone component whose template uses it (with module federation, each remote's modules too). ${load} Importing it again in another bundle is harmless.`.trim();
     case "vue":
       return `Web component: set \`compilerOptions.isCustomElement = (tag) => tag.startsWith("${prefixOf(tag)}")\` in the Vue config. ${load}`.trim();
     case "html":
@@ -778,8 +778,48 @@ function fromUsage(c, framework, kind, u) {
       if (path && !setup) setup = /\.css(\?|$)/.test(path) ? `Include \`<link rel="stylesheet" href="${path}">\` once.` : /\.m?js(\?|$)/.test(path) ? `Include \`<script type="module" src="${path}"></script>\` once.` : void 0;
       break;
   }
-  return { framework, importLine, tag, setup, example: u.example?.trim() || void 0, lang: LANG[kind], props: u.props?.length ? u.props : void 0 };
+  return {
+    framework,
+    importLine,
+    tag,
+    setup,
+    example: u.example?.trim() || void 0,
+    lang: LANG[kind],
+    props: u.props?.length ? u.props : void 0,
+    events: u.events?.length ? u.events : void 0,
+    customElement: kind === "web-components" || kind === "html" && tag.includes("-")
+  };
+}
+var VALUE_PROPS = ["value", "checked", "selected", "selected-date", "selectedDate"];
+function bindingHowTo(u) {
+  const ev = u.events?.[0];
+  if (!ev) return [];
+  const camel = (n) => n.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+  const vp = u.props?.find((p) => VALUE_PROPS.includes(p.name))?.name;
+  const valueProp = vp ? camel(vp) : void 0;
+  const dashed = (u.props ?? []).find((p) => p.name.includes("-"))?.name;
+  const caseNote = dashed ? ` Static attributes are kebab-case (\`${dashed}="\u2026"\`); bindings use the camelCase property (\`${u.framework === "vue" ? ":" : "["}${camel(dashed)}${u.framework === "vue" ? "" : "]"}="expr"\`), never \`${u.framework === "vue" ? ":" : "["}${dashed}${u.framework === "vue" ? "" : "]"}\`.` : "";
+  const attrs = (u.props ?? []).filter((p) => p.required).map((p) => `${p.name}="\u2026"`).join(" ");
+  const open = (extra) => `<${u.tag}${attrs ? ` ${attrs}` : ""}${extra}></${u.tag}>`;
+  const ce = u.customElement || u.via === "web-components";
+  switch (u.framework) {
+    case "angular":
+      if (!ce) return [`Outputs: bind with (${ev.name})="on${pascal(ev.name)}($event)".`];
+      return [
+        `Inputs: \`[prop]="expr"\` (objects and arrays work too). Events: \`(${ev.name})\` with the value in \`$any($event).detail\` (Angular types \`$event\` on custom elements as a plain Event, so \`$event.detail\` doesn't compile).${caseNote}`,
+        `Example: \`${open(`${valueProp ? ` [${valueProp}]="model"` : ""} (${ev.name})="model = $any($event).detail"`)}\``
+      ];
+    case "vue":
+      return [
+        ce ? `Props: \`:prop="expr"\`. Events: \`@${ev.name}\` with the value in \`$event.detail\`.${caseNote} Example: \`${open(`${valueProp ? ` :${valueProp}="model"` : ""} @${ev.name}="model = $event.detail"`)}\`` : `Events: \`@${ev.name}="handler"\`.`
+      ];
+    case "react":
+      return [];
+    default:
+      return [`Events: \`el.addEventListener("${ev.name}", (e) => e.detail)\`. Set lists and objects as properties (\`el.items = [\u2026]\`) or as JSON attributes.`];
+  }
 }
+var pascal = (s) => s.replace(/(^|[-_:])(\w)/g, (_, __, c) => c.toUpperCase());
 var markup = (u) => `<${u.tag}>`;
 function detectFramework(pkg) {
   if (!pkg) return "html";
@@ -1219,12 +1259,16 @@ function propName(raw) {
   return n;
 }
 var sameName = (a, b) => a.replace(/-/g, "").toLowerCase() === b.replace(/-/g, "").toLowerCase();
+var NATIVE_EVENT = /^(?:click|dblclick|auxclick|contextmenu|focus|blur|focusin|focusout|key(?:down|up|press)|mouse\w+|pointer\w+|touch\w+|wheel|drag\w*|drop|scroll|animation\w+|transition\w+)$/;
+function eventName(raw) {
+  const m = /^\(([^)]+)\)$|^on-(.+)$|^@([^.]+)|^v-on:([^.]+)/.exec(raw);
+  return m ? (m[1] ?? m[2] ?? m[3] ?? m[4]).replace(/\..*$/, "") : null;
+}
 function templateProps({ code, config, framework }) {
   const tagged = [];
   for (const comp of config.components) {
     const u = resolveUsage(comp, framework);
-    const props = u?.props;
-    if (u && props?.length) tagged.push({ comp, tag: u.tag, props });
+    if (u && (u.props?.length || u.events?.length)) tagged.push({ comp, tag: u.tag, props: u.props, events: u.events, ce: Boolean(u.customElement || u.via) });
   }
   if (!tagged.length) return [];
   const out = [];
@@ -1238,19 +1282,39 @@ function templateProps({ code, config, framework }) {
     const t = forms.get(m[1]);
     const parsed = parseHtmlAttributes(code, m.index + m[0].length);
     if (!parsed) continue;
-    const list = t.props.map((p) => p.required ? `${p.name} (required)` : p.name).join(", ");
+    const list = (t.props ?? []).map((p) => p.required ? `${p.name} (required)` : p.name).join(", ");
     const passed = [];
     for (const a of parsed.attrs) {
       const raw = a.name;
+      const ev = eventName(raw);
+      if (ev) {
+        if (!t.events?.length || NATIVE_EVENT.test(ev) || t.events.some((e) => e.name === ev)) continue;
+        const like = t.events.find((e) => e.name.endsWith(`-${ev}`) || e.name.endsWith(ev)) ?? (t.events.length === 1 ? t.events[0] : void 0);
+        out.push({
+          offset: a.offset,
+          message: `<${t.tag}> has no "${ev}" event`,
+          suggestion: `${like ? `Listen to ${framework === "angular" ? `(${like.name})` : framework === "vue" ? `@${like.name}` : `"${like.name}"`}${like.detail ? ` and read ${framework === "angular" ? "$any($event).detail" : framework === "vue" ? "$event.detail" : "event.detail"} (${like.detail})` : ""}. ` : ""}Events: ${t.events.map((e) => e.name).join(", ")}`
+        });
+        continue;
+      }
       if (/^v-model$/.test(raw)) passed.push("modelValue", "value");
       if (/^\[\(ngModel\)\]$/.test(raw)) passed.push("value");
       const n = propName(raw);
-      if (!n) continue;
+      if (!n || !t.props?.length) continue;
       passed.push(n);
+      if (t.ce && n.includes("-") && /^(?:\[(?!attr\.)|:|v-bind:|bind-)/.test(raw)) {
+        const camel = n.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+        out.push({
+          offset: a.offset,
+          message: `${raw} binds a property that doesn't exist on <${t.tag}>`,
+          suggestion: `Bind the camelCase property: ${framework === "vue" ? `:${camel}` : `[${camel}]`}="\u2026" (kebab-case is only for static attributes: ${n}="\u2026")`
+        });
+        continue;
+      }
       if (t.props.some((p) => sameName(p.name, n))) continue;
       out.push({ offset: a.offset, message: `<${t.tag}> has no "${n}" input`, suggestion: `Remove it. ${t.comp.name} takes: ${list}` });
     }
-    for (const p of t.props) {
+    for (const p of t.props ?? []) {
       if (!p.required || passed.some((n) => sameName(n, p.name))) continue;
       if (p.name === "children" || p.name === "content") continue;
       out.push({ offset: m.index, message: `<${t.tag}> is missing the required "${p.name}" input`, suggestion: `Add ${p.name}${p.type ? ` (${p.type})` : ""}` });
@@ -1453,7 +1517,7 @@ function makeIgnore(globs) {
 }
 
 // ../engine/src/check.ts
-var ENGINE_VERSION = "0.4.0";
+var ENGINE_VERSION = "0.4.1";
 var WEIGHT = { error: 4, warning: 1.5, info: 0.25 };
 function computeScore(counts, lines) {
   const penalty = counts.error * WEIGHT.error + counts.warning * WEIGHT.warning + counts.info * WEIGHT.info;
@@ -2249,8 +2313,13 @@ function generateInstructions(config, opts = {}) {
   );
   lines.push("");
   const usesKit = fw === "react" && r.components.some((c) => c.importPath === KIT_PACKAGE);
-  if (opts.tokensCss || usesKit) {
+  const usesKitElements = fw !== "react" && r.components.some((c) => resolveUsage(c, fw)?.importLine?.includes(`"${KIT_PACKAGE}/`));
+  if (opts.tokensCss || usesKit || usesKitElements) {
     lines.push("## Setup");
+    if (usesKit || usesKitElements) lines.push(`- The kit comes from npm: \`npm i ${KIT_PACKAGE}\` (once per app, if it isn't in package.json yet).`);
+    if (usesKitElements) {
+      lines.push(`- \`import "${KIT_PACKAGE}/elements";\` once at the app entry registers every \`<br-*>\` element. Don't import the React components from \`${KIT_PACKAGE}\` in this project.`);
+    }
     if (opts.tokensCss) {
       lines.push(`- \`${opts.tokensCss}\` defines every CSS variable below (light and dark). Import it once at the app entry, before other styles. Don't edit it: it's generated from the Brand Kit.`);
     }
@@ -2272,6 +2341,11 @@ function generateInstructions(config, opts = {}) {
       const how = fw === "react" ? `\`${c.name}\` from \`${c.importPath}\`` : `\`${markup(u)}\`${u.importLine ? ` (\`${u.importLine}\`)` : ""}`;
       lines.push(`- ${how}${fw === "react" ? "" : ` \u2014 ${c.name}`}${tags.length ? ` (instead of ${tags.join(", ")})` : ""}${props}`);
     }
+    const evented = here.find((x2) => x2.u.events?.length && (x2.u.customElement || x2.u.via));
+    if (evented && fw !== "react") {
+      lines.push(`- Events: ${here.filter((x2) => x2.u.events?.length).slice(0, 12).map((x2) => `\`<${x2.u.tag}>\` ${x2.u.events.map((e) => `\`${e.name}\``).join(", ")}`).join("; ")}.`);
+      for (const b of bindingHowTo(evented.u)) lines.push(`- ${b}`);
+    }
     const setups = [...new Set(here.map((x2) => x2.u.setup).filter(Boolean))];
     if (setups.length && setups.length <= 3) for (const s of setups) lines.push(`- Setup: ${s}`);
     else if (setups.length) lines.push("- Each component's setup is in its docs (MCP `get_component_docs`).");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brandrail",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Keep AI-generated UI on-brand: checks code and live pages against your design system, and wires your Brand Kit into Claude Code, Cursor, Copilot and Codex.",
   "keywords": [
     "design-system",