Sync Up Layout Blocks with Page Component Slots (#1712)

* revising + adding Page component-based blocks to base.njk

* skip base classes (no tag names)

---------

Co-authored-by: Cory LaViska <cory@abeautifulsite.net>

packages/webawesome/docs/_includes/base.njk

@@ -41,72 +41,82 @@
         {% endif %}
       {% endfor %}
     >
-        {% block pageBanner %}
-          {% if hasBanner %}
-            {#- WA Launch Banner -#}
-            {% include "_banner-wa-launch.njk" ignore missing %}
-          {% endif %}
-        {% endblock %}
+      {# wa-page-based Skip to Content #}
+      {% block pageSkipToContent %}{% 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 Banner #}
+      {% block pageBanner %}
+        {% if hasBanner %}
+          {#- WA Launch Banner -#}
+          {% include "_banner-wa-launch.njk" ignore missing %}
+        {% endif %}
+      {% endblock %}
 
-              {# Logo - Desktop #}
-              <a class="brand-logo wa-desktop-only" href="/" aria-label="Web Awesome">
-                {% include "logo.njk" %}
-              </a>
+      {# wa-page-based Subheader #}
+      {% block pageSubheader %}{% endblock %}
 
-            {#- Logo - mobile branding -#}
-            <a href="/" class="brand-logo wa-mobile-only" aria-label="Web Awesome">
-              {# Logo - Mobile #}
-              {% include "logo-simple.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>
 
-            <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 %}
+          {# Logo - Desktop #}
+          <a href="/" class="brand-logo wa-desktop-only" aria-label="Web Awesome">{% include "logo.njk" %}</a>
 
-      {# 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;">
+          {# 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>
-        </div>
-        <div slot="navigation" id="sidebar" class="docs-aside" data-remember-scroll>
-          {% include "sidebar.njk" %}
-        </div>
-      {% endif %}
+        </header>
+      {% 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 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;">
+                {% include "theme-selector.njk" %}
+                {% include "color-scheme-selector.njk" %}
+                {% include "github-icon-buttons.njk" %}
+              </div>
+            </div>
+          </div>
+        {% endif %}
+      {% endblock %}
 
-      {# Main #}
+      {# 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 %}
+
+      {# wa-page-based Navigation Footer #}
+      {% block pageNavigationFooter %}{% endblock %}
+
+      {# wa-page-based Main Header #}
+      {% block pageMainHeader %}{% endblock %}
+
+      {# wa-page-based Main Content (default) #}
       <main id="content">
         {# Expandable outline #}
         {% if hasOutline %}
@@ -117,7 +127,10 @@
         </nav>
         {% endif %}
 
-        <div id="flashes">{% server "flashes" %}</div>
+        {# Flashes #}
+        {% block flashes %}
+          <div id="flashes">{% server "flashes" %}</div>
+        {% endblock %}
 
         {% block header %}
           {% if hasGeneratedTitle %}
@@ -134,6 +147,24 @@
         {% 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 -#}
@@ -143,9 +174,6 @@
 
       {#- 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].sort((a, b) => a.tagName.localeCompare(b.tagName));
+  const sortedComponentsList = components.filter(c => c.tagName).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].sort((a, b) => a.tagName.localeCompare(b.tagName));
+  const sortedComponents = components.filter(c => c.tagName).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,80 +21,6 @@ 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;
@@ -121,51 +47,6 @@ 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';
@@ -178,8 +59,6 @@ export interface ${propsInterfaceName} extends ${baseType} {
 
       const tagName = '${component.tagName}'
 
-      ${propsInterface}
-
       ${jsDoc}
       const reactWrapper = createComponent({
         tagName,
@@ -198,7 +77,7 @@ export interface ${propsInterfaceName} extends ${baseType} {
     }),
   );
 
-  index.push(`export { default as ${component.name}, type ${propsInterfaceName} } from './${tagWithoutPrefix}/index.js';`);
+  index.push(`export { default as ${component.name} } from './${tagWithoutPrefix}/index.js';`);
 
   fs.writeFileSync(componentFile, source, 'utf8');
 }