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/docs/docs/resources/changelog.md

@@ -49,15 +49,14 @@ Components with the <wa-badge variant="warning">Experimental</wa-badge> badge sh
 - Fixed a bug in `<wa-icon>` that caused some icon libraries to render with the incorrect SVG fill [issue:1733]
 - Fixed a bug in `<wa-tree-item>` that caused the spinner to not show when lazy loading [issue:1678]
 - Fixed a bug in `<wa-dropdown>` that caused the browser to hang when cancelling the `wa-hide` event [issue:1483]
-- Fixed a bug in `<wa-tab-group>` that ensures the active indicator always shows [issue:1206]
 - Fixed a bug in `<wa-dropdown-item>` that prevented the icon dependency from being imported [issue:1825]
 - Fixed a bug in `<wa-select>` that prevented clicks on the tag's remove button from removing options in multiple mode
 - Fixed a bug in `<wa-select>` that caused tags to appear in alphabetical order instead of selection order when using `multiple`
+- Improved performance of `<wa-icon>` so initial rendering occurs faster, especially with multiple icons on the page [issue:1729]
+- Improved `<wa-slider>` to not throw an error when string values are passed to the `min`, `max`, and `step` properties [issue:1823]
 - Fixed a bug in Web Awesome form controls that caused `<wa-input form="foo">` to set the form property to equal `"foo"` instead of returning an `HTMLFormElement` breaking platform expectations. [pr:1815]
 - Fixed a bug in `<wa-button>` causing it to not copy over attributes for form submissions. [pr:1815]
 - Fixed a bug where the build script was not building `/dist/(utilities|events).js` [pr:1816]
-- Improved performance of `<wa-icon>` so initial rendering occurs faster, especially with multiple icons on the page [issue:1729]
-- Improved `<wa-slider>` to not throw an error when string values are passed to the `min`, `max`, and `step` properties [issue:1823]
 - Improved performance of all components by fixing how CSS is imported and reused [issue:1812]
 - Modified the default `transition` styles of `<wa-dropdown-item>` to use design tokens [pr:1693]
 

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');
 }

packages/webawesome/src/components/tab-group/tab-group.styles.ts

@@ -6,9 +6,6 @@ export default css`
     --track-color: var(--wa-color-neutral-fill-normal);
     --track-width: 0.125rem;
 
-    /* Private */
-    --safe-track-width: max(0.5px, round(var(--track-width), 0.5px));
-
     display: block;
   }
 
@@ -54,8 +51,8 @@ export default css`
   }
 
   /*
-    * Top
-    */
+   * Top
+   */
 
   .tab-group-top {
     flex-direction: column;
@@ -83,12 +80,12 @@ export default css`
     flex: 1 1 auto;
     position: relative;
     flex-direction: row;
-    border-bottom: solid var(--safe-track-width) var(--track-color);
+    border-bottom: solid var(--track-width) var(--track-color);
   }
 
   .tab-group-top .indicator {
-    bottom: calc(-1 * var(--safe-track-width));
-    border-bottom: solid var(--safe-track-width) var(--indicator-color);
+    bottom: calc(-1 * var(--track-width));
+    border-bottom: solid var(--track-width) var(--indicator-color);
   }
 
   .tab-group-top .body {
@@ -96,8 +93,8 @@ export default css`
   }
 
   .tab-group-top ::slotted(wa-tab[active]) {
-    border-block-end: solid var(--safe-track-width) var(--indicator-color);
-    margin-block-end: calc(-1 * var(--safe-track-width));
+    border-block-end: solid var(--track-width) var(--indicator-color);
+    margin-block-end: calc(-1 * var(--track-width));
   }
 
   .tab-group-top ::slotted(wa-tab-panel) {
@@ -105,8 +102,8 @@ export default css`
   }
 
   /*
-    * Bottom
-    */
+   * Bottom
+   */
 
   .tab-group-bottom {
     flex-direction: column;
@@ -134,12 +131,12 @@ export default css`
     flex: 1 1 auto;
     position: relative;
     flex-direction: row;
-    border-top: solid var(--safe-track-width) var(--track-color);
+    border-top: solid var(--track-width) var(--track-color);
   }
 
   .tab-group-bottom .indicator {
-    top: calc(-1 * var(--safe-track-width));
-    border-top: solid var(--safe-track-width) var(--indicator-color);
+    top: calc(-1 * var(--track-width));
+    border-top: solid var(--track-width) var(--indicator-color);
   }
 
   .tab-group-bottom .body {
@@ -147,8 +144,8 @@ export default css`
   }
 
   .tab-group-bottom ::slotted(wa-tab[active]) {
-    border-block-start: solid var(--safe-track-width) var(--indicator-color);
-    margin-block-start: calc(-1 * var(--safe-track-width));
+    border-block-start: solid var(--track-width) var(--indicator-color);
+    margin-block-start: calc(-1 * var(--track-width));
   }
 
   .tab-group-bottom ::slotted(wa-tab-panel) {
@@ -156,8 +153,8 @@ export default css`
   }
 
   /*
-    * Start
-    */
+   * Start
+   */
 
   .tab-group-start {
     flex-direction: row;
@@ -170,12 +167,12 @@ export default css`
   .tab-group-start .tabs {
     flex: 0 0 auto;
     flex-direction: column;
-    border-inline-end: solid var(--safe-track-width) var(--track-color);
+    border-inline-end: solid var(--track-width) var(--track-color);
   }
 
   .tab-group-start .indicator {
-    inset-inline-end: calc(-1 * var(--safe-track-width));
-    border-right: solid var(--safe-track-width) var(--indicator-color);
+    inset-inline-end: calc(-1 * var(--track-width));
+    border-right: solid var(--track-width) var(--indicator-color);
   }
 
   .tab-group-start .body {
@@ -184,8 +181,8 @@ export default css`
   }
 
   .tab-group-start ::slotted(wa-tab[active]) {
-    border-inline-end: solid var(--safe-track-width) var(--indicator-color);
-    margin-inline-end: calc(-1 * var(--safe-track-width));
+    border-inline-end: solid var(--track-width) var(--indicator-color);
+    margin-inline-end: calc(-1 * var(--track-width));
   }
 
   .tab-group-start ::slotted(wa-tab-panel) {
@@ -193,8 +190,8 @@ export default css`
   }
 
   /*
-    * End
-    */
+   * End
+   */
 
   .tab-group-end {
     flex-direction: row;
@@ -207,12 +204,12 @@ export default css`
   .tab-group-end .tabs {
     flex: 0 0 auto;
     flex-direction: column;
-    border-left: solid var(--safe-track-width) var(--track-color);
+    border-left: solid var(--track-width) var(--track-color);
   }
 
   .tab-group-end .indicator {
-    inset-inline-start: calc(-1 * var(--safe-track-width));
-    border-inline-start: solid var(--safe-track-width) var(--indicator-color);
+    inset-inline-start: calc(-1 * var(--track-width));
+    border-inline-start: solid var(--track-width) var(--indicator-color);
   }
 
   .tab-group-end .body {
@@ -221,8 +218,8 @@ export default css`
   }
 
   .tab-group-end ::slotted(wa-tab[active]) {
-    border-inline-start: solid var(--safe-track-width) var(--indicator-color);
-    margin-inline-start: calc(-1 * var(--safe-track-width));
+    border-inline-start: solid var(--track-width) var(--indicator-color);
+    margin-inline-start: calc(-1 * var(--track-width));
   }
 
   .tab-group-end ::slotted(wa-tab-panel) {