Merge branch 'staging'

Author: himerus

.changeset/narrative-common-mistakes.md

@@ -0,0 +1,5 @@
+---
+'helixir': patch
+---
+
+Add component-specific "common mistakes" section to narrative output with valid part names, no-CSS-API warnings, React event guidance, and styling_preflight reminder

packages/core/src/handlers/narrative.ts

@@ -167,6 +167,51 @@ export function buildNarrative(meta: ComponentMetadata): string {
     sections.push(eventLines.join('\n'));
   }
 
+  // --- Common mistakes (component-specific) ---
+  const mistakes: string[] = [];
+
+  if (meta.cssParts.length > 0) {
+    const partNames = meta.cssParts.map((p) => `\`${p.name}\``).join(', ');
+    mistakes.push(
+      `Only these CSS parts exist: ${partNames}. ` +
+        `Any other part name in \`::part()\` will silently fail.`,
+    );
+  }
+
+  if (meta.cssProperties.length > 0 && meta.cssParts.length === 0) {
+    mistakes.push(
+      `This component has NO CSS parts — use CSS custom properties only. ` +
+        `\`::part()\` selectors will not match anything.`,
+    );
+  }
+
+  if (meta.cssProperties.length === 0 && meta.cssParts.length === 0) {
+    mistakes.push(
+      `This component exposes NO CSS API (no parts, no custom properties). ` +
+        `You cannot style its internals. Only the host element box can be styled.`,
+    );
+  }
+
+  if (meta.events.some((e) => e.name.includes('-'))) {
+    mistakes.push(
+      `Custom events (with hyphens) cannot use React \`onXxx\` props. ` +
+        `Use \`ref.current.addEventListener()\` instead.`,
+    );
+  }
+
+  if (meta.slots.length > 0 && meta.cssParts.length > 0) {
+    mistakes.push(
+      `Style slotted content in light DOM CSS (before it enters the slot), ` +
+        `not with \`::slotted()\` in your consumer stylesheet.`,
+    );
+  }
+
+  if (mistakes.length > 0) {
+    const mistakeLines = ['**Common mistakes:**', ...mistakes.map((m) => `- ${m}`)];
+    mistakeLines.push('', `*Run \`styling_preflight\` with your CSS to validate all references.*`);
+    sections.push(mistakeLines.join('\n'));
+  }
+
   return sections.join('\n\n');
 }
 

tests/handlers/narrative.test.ts

@@ -138,3 +138,65 @@ describe('buildNarrative — tailored Shadow DOM constraints', () => {
     expect(result).toContain(':host');
   });
 });
+
+// ---------------------------------------------------------------------------
+// buildNarrative — common mistakes section
+// ---------------------------------------------------------------------------
+
+describe('buildNarrative — common mistakes', () => {
+  it('lists valid part names when component has parts', () => {
+    const result = getComponentNarrative('my-button', FIXTURE_CEM);
+    expect(result).toContain('Common mistakes');
+    expect(result).toContain('`base`');
+    expect(result).toContain('silently fail');
+  });
+
+  it('warns about no CSS parts when component has only properties', () => {
+    const meta: ComponentMetadata = {
+      tagName: 'my-test',
+      description: 'Test',
+      members: [],
+      events: [],
+      slots: [],
+      cssParts: [],
+      cssProperties: [{ name: '--test-color', description: '' }],
+    };
+    const result = buildNarrative(meta);
+    expect(result).toContain('NO CSS parts');
+    expect(result).toContain('::part()');
+  });
+
+  it('warns about no CSS API when component has neither', () => {
+    const meta: ComponentMetadata = {
+      tagName: 'my-bare',
+      description: 'Bare',
+      members: [],
+      events: [],
+      slots: [],
+      cssParts: [],
+      cssProperties: [],
+    };
+    const result = buildNarrative(meta);
+    expect(result).toContain('NO CSS API');
+  });
+
+  it('warns about custom events and React onXxx props', () => {
+    const meta: ComponentMetadata = {
+      tagName: 'my-dialog',
+      description: 'Dialog',
+      members: [],
+      events: [{ name: 'my-close', type: 'CustomEvent', description: '' }],
+      slots: [],
+      cssParts: [],
+      cssProperties: [],
+    };
+    const result = buildNarrative(meta);
+    expect(result).toContain('React');
+    expect(result).toContain('addEventListener');
+  });
+
+  it('includes styling_preflight reminder', () => {
+    const result = getComponentNarrative('my-button', FIXTURE_CEM);
+    expect(result).toContain('styling_preflight');
+  });
+});