fix: generate explicit React prop types for better IDE support (#1446)

Enhanced the React wrapper generation script to produce explicit Props
interfaces for each component. This improves IDE autocomplete and
documentation by:

- Generating typed Props interfaces with JSDoc comments for all public props
- Properly handling type conflicts with React.HTMLAttributes (defaultValue, etc.)
- Using Component references for complex types to avoid import issues
- Filtering internal properties like didSSR from public interfaces
- Exporting Props types alongside components for consumer use

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

packages/webawesome/docs/_includes/base.njk

@@ -41,82 +41,72 @@
         {% endif %}
       {% endfor %}
     >
-      {# wa-page-based Skip to Content #}
-      {% block pageSkipToContent %}{% endblock %}
+        {% block pageBanner %}
+          {% if hasBanner %}
+            {#- WA Launch Banner -#}
+            {% include "_banner-wa-launch.njk" ignore missing %}
+          {% endif %}
+        {% endblock %}
 
-      {# wa-page-based Banner #}
-      {% block pageBanner %}
-        {% if hasBanner %}
-          {#- WA Launch Banner -#}
-          {% include "_banner-wa-launch.njk" ignore missing %}
-        {% endif %}
-      {% endblock %}
+        {% block pageHeader %}
+          <header slot="header" class="wa-split">
+            {# Nav toggle #}
+              <wa-button appearance="plain" size="small" data-toggle-nav>
+                <wa-icon name="bars" label="Toggle navigation" class="icon-default icon-embiggen"></wa-icon>
+                <wa-icon name="burger" aria-hidden="true" class="icon-hover icon-embiggen"></wa-icon>
+              </wa-button>
 
-      {# wa-page-based Subheader #}
-      {% block pageSubheader %}{% endblock %}
+              {# Logo - Desktop #}
+              <a class="brand-logo wa-desktop-only" href="/" aria-label="Web Awesome">
+                {% include "logo.njk" %}
+              </a>
 
-      {# wa-page-based Header #}
-      {% block pageHeader %}
-        <header slot="header" class="wa-split">
-          {# Nav toggle #}
-          <wa-button appearance="plain" size="small" data-toggle-nav>
-            <wa-icon name="bars" label="Toggle navigation" class="icon-default icon-embiggen"></wa-icon>
-            <wa-icon name="burger" aria-hidden="true" class="icon-hover icon-embiggen"></wa-icon>
-          </wa-button>
+            {#- Logo - mobile branding -#}
+            <a href="/" class="brand-logo wa-mobile-only" aria-label="Web Awesome">
+              {# Logo - Mobile #}
+              {% include "logo-simple.njk" %}
+            </a>
 
-          {# Logo - Desktop #}
-          <a href="/" class="brand-logo wa-desktop-only" aria-label="Web Awesome">{% include "logo.njk" %}</a>
-
-          {# Logo - Mobile #}
-          <a href="/" class="brand-logo wa-mobile-only" aria-label="Web Awesome">{% include "logo-simple.njk" %}</a>
-
-          <div id="docs-toolbar" class="wa-cluster gap-s">
-            <div class="wa-desktop-only wa-cluster wa-gap-2xs">
-              {% include "theme-selector.njk" %}
-              {% include "color-scheme-selector.njk" %}
-              {% include "github-icon-buttons.njk" %}
-            </div>
-
-            {#- Login -#}
-            {% include "login-or-avatar.njk" ignore missing %}
-          </div>
-        </header>
-      {% endblock %}
-
-      {# wa-page-based Navigation Header #}
-      {% block pageNavigationHeader %}
-        {# Sidebar - Mobile Selectors #}
-        {% if hasSidebar %}
-          <div class="wa-mobile-only" slot="navigation-header">
-            <div class="wa-cluster wa-gap-s">
-              <a class="brand-logo" href="/" aria-label="Web Awesome">{% include "logo-simple.njk" %}</a>
-              <div class="wa-cluster wa-gap-2xs" style="flex-wrap: nowrap;">
+            <div id="docs-toolbar" class="wa-cluster gap-s">
+              <div class="wa-desktop-only wa-cluster wa-gap-2xs">
                 {% include "theme-selector.njk" %}
                 {% include "color-scheme-selector.njk" %}
                 {% include "github-icon-buttons.njk" %}
               </div>
+              {#- Login -#}
+              {% include "login-or-avatar.njk" ignore missing %}
+            </div>
+          </header>
+        {% endblock %}
+
+      {# Sidebar #}
+      {% if hasSidebar %}
+        {# Mobile selectors #}
+        <div class="wa-mobile-only" slot="navigation-header">
+          <div class="wa-cluster wa-gap-s">
+            <a class="brand-logo" href="/" aria-label="Web Awesome">{% include "logo-simple.njk" %}</a>
+            <div class="wa-cluster wa-gap-2xs" style="flex-wrap: nowrap;">
+              {% include "theme-selector.njk" %}
+              {% include "color-scheme-selector.njk" %}
+              {% include "github-icon-buttons.njk" %}
             </div>
           </div>
-        {% endif %}
-      {% endblock %}
+        </div>
+        <div slot="navigation" id="sidebar" class="docs-aside" data-remember-scroll>
+          {% include "sidebar.njk" %}
+        </div>
+      {% endif %}
 
-      {# wa-page-based Navigation #}
-      {% block pageNavigation %}
-        {# Sidebar - Navigation #}
-        {% if hasSidebar %}
-          <div slot="navigation" id="sidebar" class="docs-aside" data-remember-scroll>
-            {% include "sidebar.njk" %}
-          </div>
-        {% endif %}
-      {% endblock %}
+      {# Outline #}
+      {% if hasOutline %}
+        <aside slot="aside" id="outline" class="docs-aside">
+          <nav id="outline-standard" class="outline-links">
+            <h2><a href="#content">{{ title }}</a></h2>
+          </nav>
+        </aside>
+      {% endif %}
 
-      {# wa-page-based Navigation Footer #}
-      {% block pageNavigationFooter %}{% endblock %}
-
-      {# wa-page-based Main Header #}
-      {% block pageMainHeader %}{% endblock %}
-
-      {# wa-page-based Main Content (default) #}
+      {# Main #}
       <main id="content">
         {# Expandable outline #}
         {% if hasOutline %}
@@ -127,10 +117,7 @@
         </nav>
         {% endif %}
 
-        {# Flashes #}
-        {% block flashes %}
-          <div id="flashes">{% server "flashes" %}</div>
-        {% endblock %}
+        <div id="flashes">{% server "flashes" %}</div>
 
         {% block header %}
           {% if hasGeneratedTitle %}
@@ -147,24 +134,6 @@
         {% block afterContent %}{% endblock %}
       </main>
 
-      {# wa-page-based Main Footer #}
-      {% block pageMainFooter %}{% endblock %}
-
-      {# wa-page-based Aside #}
-      {% block pageAside %}
-        {# Outline #}
-        {% if hasOutline %}
-          <aside slot="aside" id="outline" class="docs-aside">
-            <nav id="outline-standard" class="outline-links">
-              <h2><a href="#content">{{ title }}</a></h2>
-            </nav>
-          </aside>
-        {% endif %}
-      {% endblock %}
-
-      {# wa-page-based Footer #}
-      {% block pageFooter %}{% endblock %}
-
       {% include 'search.njk' %}
 
       {#- Site-Wide Dialog -#}
@@ -174,6 +143,9 @@
 
       {#- Cookie Consent Dialog -#}
       {% include "cookie-consent.njk" ignore missing %}
+
+      {# Footer #}
+      {% block pageFooter %}{% endblock %}
     </wa-page>
 
   </body>

packages/webawesome/scripts/llms.js

@@ -200,7 +200,7 @@ icon names.
   lines.push('## Components');
   lines.push('');
 
-  const sortedComponentsList = components.filter(c => c.tagName).sort((a, b) => a.tagName.localeCompare(b.tagName));
+  const sortedComponentsList = [...components].sort((a, b) => a.tagName.localeCompare(b.tagName));
 
   for (const component of sortedComponentsList) {
     const frontMatter = frontMatterCache.get(component.tagName);
@@ -225,7 +225,7 @@ icon names.
   lines.push('');
 
   // Sort components alphabetically by tag name for the API reference
-  const sortedComponents = components.filter(c => c.tagName).sort((a, b) => a.tagName.localeCompare(b.tagName));
+  const sortedComponents = [...components].sort((a, b) => a.tagName.localeCompare(b.tagName));
 
   for (const component of sortedComponents) {
     lines.push(...generateComponentApiSection(component, frontMatterCache, baseUrl));

packages/webawesome/scripts/make-react.js

@@ -21,6 +21,80 @@ const components = getAllComponents(metadata);
 
 const index = [];
 
+/**
+ * Generate JSDoc comment for a property
+ */
+function generatePropJsDoc(description) {
+  if (!description) return '';
+  // Escape any */ in the description to avoid breaking the JSDoc comment
+  const escaped = description.replace(/\*\//g, '*\\/');
+  return `/** ${escaped} */\n  `;
+}
+
+/**
+ * Get public properties from component members that have an attribute
+ * (these are the props that can be set via JSX)
+ */
+function getPublicProps(component, internalProps = []) {
+  const props = [];
+  const seenProps = new Set();
+
+  // Get properties from members that have attributes (these are the public reactive properties)
+  for (const member of component.members || []) {
+    if (member.kind === 'field' && member.attribute && !member.privacy) {
+      // Skip internal properties
+      if (internalProps.includes(member.name)) continue;
+      if (seenProps.has(member.name)) continue;
+      seenProps.add(member.name);
+
+      props.push({
+        name: member.name,
+        type: member.type?.text || 'any',
+        description: member.description || '',
+      });
+    }
+  }
+
+  return props;
+}
+
+/**
+ * Convert a TypeScript type from the CEM to a valid prop type.
+ * Returns the type to use in the interface, and whether it should use Component reference.
+ */
+function normalizeType(typeText, propName) {
+  if (!typeText) return { type: 'any', useComponentRef: false };
+
+  // Simple/primitive types that don't need Component reference
+  const simpleTypePatterns = [
+    /^(string|number|boolean|null|undefined)$/,
+    /^'[^']*'(\s*\|\s*'[^']*')*$/, // String literal unions like 'small' | 'medium' | 'large'
+    /^(string|number|boolean)\s*\|\s*(string|number|boolean|null|undefined)/, // Simple unions
+  ];
+
+  for (const pattern of simpleTypePatterns) {
+    if (pattern.test(typeText)) {
+      return { type: typeText, useComponentRef: false };
+    }
+  }
+
+  // Complex types (containing Element, custom types, etc.) should use Component reference
+  // to ensure all types are properly resolved
+  const complexTypeIndicators = ['Element', 'VirtualElement', 'HTMLElement', '[]', '()', '=>', 'Record', 'Map', 'Set'];
+  if (complexTypeIndicators.some(indicator => typeText.includes(indicator))) {
+    return { type: `Component['${propName}']`, useComponentRef: true };
+  }
+
+  // Default: use the type directly
+  return { type: typeText, useComponentRef: false };
+}
+
+// Properties that conflict with React.HTMLAttributes and need to be omitted
+const CONFLICTING_HTML_PROPS = ['defaultValue', 'color', 'size', 'value', 'checked', 'disabled', 'type', 'name', 'title'];
+
+// Internal properties that shouldn't be exposed in React props
+const INTERNAL_PROPS = ['didSSR', 'form', 'internals', 'shadowRoot', 'assignedSlot'];
+
 for await (const component of components) {
   if (!component.tagName) {
     continue;
@@ -47,6 +121,51 @@ for await (const component of components) {
 
   const jsDoc = component.jsDoc || '';
 
+  // Generate explicit props interface for better IDE support
+  const publicProps = getPublicProps(component, INTERNAL_PROPS);
+  const propsInterfaceName = `${component.name}Props`;
+
+  // Generate prop definitions with JSDoc comments
+  const propDefinitions = publicProps
+    .map(prop => {
+      const jsDocComment = generatePropJsDoc(prop.description);
+      const { type } = normalizeType(prop.type, prop.name);
+      return `${jsDocComment}'${prop.name}'?: ${type};`;
+    })
+    .join('\n  ');
+
+  // Generate event handler prop definitions
+  const eventPropDefinitions = eventsToWrap
+    .map(event => {
+      const description = component.events?.find(e => e.name === event.name)?.description || '';
+      const jsDocComment = generatePropJsDoc(description);
+      return `${jsDocComment}${event.reactName}?: (event: ${event.eventName}) => void;`;
+    })
+    .join('\n  ');
+
+  // Combine props and events into the interface
+  const allPropDefinitions = [propDefinitions, eventPropDefinitions].filter(Boolean).join('\n  ');
+
+  // Find which conflicting props this component has
+  const componentConflictingProps = publicProps
+    .filter(prop => CONFLICTING_HTML_PROPS.includes(prop.name))
+    .map(prop => `'${prop.name}'`);
+
+  // Generate the base type with omitted conflicting props
+  const baseType = componentConflictingProps.length > 0
+    ? `Omit<React.HTMLAttributes<Component>, ${componentConflictingProps.join(' | ')}>`
+    : `React.HTMLAttributes<Component>`;
+
+  const propsInterface = `
+/**
+ * Props for the ${component.name} component.
+ * This interface provides explicit typing for better IDE support and documentation.
+ */
+export interface ${propsInterfaceName} extends ${baseType} {
+  ${allPropDefinitions}
+}
+`;
+
   const source = await prettier.format(
     `
       import * as React from 'react';
@@ -59,6 +178,8 @@ for await (const component of components) {
 
       const tagName = '${component.tagName}'
 
+      ${propsInterface}
+
       ${jsDoc}
       const reactWrapper = createComponent({
         tagName,
@@ -77,7 +198,7 @@ for await (const component of components) {
     }),
   );
 
-  index.push(`export { default as ${component.name} } from './${tagWithoutPrefix}/index.js';`);
+  index.push(`export { default as ${component.name}, type ${propsInterfaceName} } from './${tagWithoutPrefix}/index.js';`);
 
   fs.writeFileSync(componentFile, source, 'utf8');
 }