Display attribute and property in separate columns

docs/.eleventy.js

@@ -10,7 +10,7 @@ import { replaceTextPlugin } from './_utils/replace-text.js';
 import { searchPlugin } from './_utils/search.js';
 import { readFile } from 'fs/promises';
 import { outlinePlugin } from './_utils/outline.js';
-import componentList from './_data/componentList.js';
+import { getComponents } from './_utils/manifest.js';
 import litPlugin from '@lit-labs/eleventy-plugin-lit';
 
 import process from 'process';
@@ -46,6 +46,16 @@ export default function (eleventyConfig) {
   });
 
   // Helpers
+  eleventyConfig.addNunjucksGlobal('getComponent', tagName => {
+    const component = getComponents().find(c => c.tagName === tagName);
+
+    if (!component) {
+      throw new Error(
+        `Unable to find "<${tagName}>". Make sure the file name is the same as the tag name (without prefix).`
+      );
+    }
+    return component;
+  });
 
   // Use our own markdown instance
   eleventyConfig.setLibrary('md', markdown);
@@ -105,7 +115,8 @@ export default function (eleventyConfig) {
   // mutation-observer (why SSR this?)
   // resize-observer (why SSR this?)
   // tooltip (why SSR this?)
-  const componentModules = componentList
+
+  const componentModules = getComponents()
     // .filter(component => !omittedModules.includes(component.tagName.split(/wa-/)[1]))
     .map(component => {
       const name = component.tagName.split(/wa-/)[1];

docs/_data/componentList.js

@@ -1,75 +0,0 @@
-/**
- * @module components Fetches components from custom-elements.json and exposes them in a saner format.
- */
-import { dirname, resolve } from 'path';
-import { fileURLToPath } from 'url';
-import { readFileSync } from 'fs';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-const manifest = JSON.parse(readFileSync(resolve(__dirname, '../../dist/custom-elements.json'), 'utf-8'));
-
-const components = manifest.modules.flatMap(module => {
-  return module.declarations
-    .filter(c => c?.customElement)
-    .map(declaration => {
-      // Generate the dist path based on the src path and attach it to the component
-      declaration.path = module.path.replace(/^src\//, 'dist/').replace(/\.ts$/, '.js');
-
-      // Remove private members and those that lack a description
-      const members = declaration.members?.filter(member => member.description && member.privacy !== 'private');
-
-      const methods = members?.filter(prop => prop.kind === 'method' && prop.privacy !== 'private');
-      const attributes = declaration.attributes ?? [];
-      const properties = members?.filter(prop => {
-        // Look for a corresponding attribute
-        const attribute = attributes?.find(attr => attr.fieldName === prop.name);
-        if (attribute) {
-          prop.attribute = attribute.name || attribute.fieldName;
-        }
-
-        return prop.kind === 'field' && prop.privacy !== 'private';
-      });
-
-      return {
-        ...declaration,
-        slug: declaration.tagName.replace(/^wa-/, ''),
-        methods,
-        attributes,
-        properties
-      };
-    });
-});
-
-// Build dependency graphs
-components.forEach(component => {
-  const dependencies = [];
-
-  // Recursively fetch sub-dependencies
-  function getDependencies(tag) {
-    const cmp = components.find(c => c.tagName === tag);
-    if (!cmp || !Array.isArray(component.dependencies)) {
-      return;
-    }
-
-    cmp.dependencies?.forEach(dependentTag => {
-      if (!dependencies.includes(dependentTag)) {
-        dependencies.push(dependentTag);
-      }
-      getDependencies(dependentTag);
-    });
-  }
-
-  getDependencies(component.tagName);
-
-  component.dependencies = dependencies.sort();
-});
-
-// Sort by name
-components.sort((a, b) => {
-  if (a.name < b.name) return -1;
-  if (a.name > b.name) return 1;
-  return 0;
-});
-
-export default components;

docs/_data/components.js

@@ -1,3 +0,0 @@
-import componentList from './componentList.js';
-
-export default Object.fromEntries(componentList.map(component => [component.slug, component]));

docs/_data/componentsBy.js

@@ -1,43 +0,0 @@
-import components from './components.js';
-
-const by = {
-  attribute: {},
-  slot: {},
-  event: {},
-  method: {},
-  cssPart: {},
-  cssProperty: {}
-};
-
-function getAll(component, type) {
-  let prop = type + 's';
-  if (type === 'cssProperty') {
-    prop = 'cssProperties';
-  }
-
-  return component[prop] ?? [];
-}
-
-for (const componentName in components) {
-  const component = components[componentName];
-
-  for (const type of ['attribute', 'slot', 'event', 'method', 'cssPart', 'cssProperty']) {
-    for (const item of getAll(component, type)) {
-      by[type][item.name] ??= [];
-      by[type][item.name].push(component);
-    }
-  }
-}
-
-// Sort by descending number of components
-const sortByLengthDesc = (a, b) => b[1].length - a[1].length;
-
-for (const key in by) {
-  by[key] = sortObject(by[key], sortByLengthDesc);
-}
-
-export default by;
-
-function sortObject(obj, sorter) {
-  return Object.fromEntries(Object.entries(obj).sort(sorter));
-}

docs/_layouts/component.njk

@@ -1,6 +1,6 @@
 {% set hasSidebar = true %}
 {% set hasOutline = true %}
-{% set component = components[page.fileSlug] %}
+{% set component = getComponent('wa-' + page.fileSlug) %}
 {% set description = component.summary %}
 
 {% extends '../_includes/base.njk' %}
@@ -62,13 +62,14 @@
 
   {# Properties #}
   {% if component.properties.length %}
-    <h2>Properties</h2>
+    <h2>Properties & Attributes</h2>
 
     <div class="table-scroll">
       <table class="component-table">
         <thead>
           <tr>
-            <th class="table-name">Name</th>
+            <th class="table-name">Property</th>
+            <th class="table-name">Attribute</th>
             <th class="table-description">Description</th>
             <th class="table-reflects">Reflects</th>
           </tr>
@@ -78,8 +79,10 @@
             <tr>
               <td class="table-name">
                 <code>{{ prop.name }}</code><br>
+              </td>
+              <td class="table-name">
                 {% if prop.attribute %}
-                  <div><small><code>{{ prop.attribute }}</code></small></div>
+                <code>{{ prop.attribute }}</code>
                 {% endif %}
               </td>
               <td class="table-description">

docs/_utils/manifest.js

@@ -0,0 +1,71 @@
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+import { readFileSync } from 'fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const manifest = JSON.parse(readFileSync(resolve(__dirname, '../../dist/custom-elements.json'), 'utf-8'));
+/**
+ * @returns Fetches components from custom-elements.json and returns them in more sane format.
+ */
+export function getComponents() {
+  const components = [];
+
+  manifest.modules?.forEach(module => {
+    module.declarations?.forEach(declaration => {
+      if (declaration.customElement) {
+        // Generate the dist path based on the src path and attach it to the component
+        declaration.path = module.path.replace(/^src\//, 'dist/').replace(/\.ts$/, '.js');
+
+        // Remove private members and those that lack a description
+        const members = declaration.members?.filter(member => member.description && member.privacy !== 'private');
+        const methods = members?.filter(prop => prop.kind === 'method' && prop.privacy !== 'private');
+        const properties = members?.filter(prop => {
+          // Look for a corresponding attribute
+          const attribute = declaration.attributes?.find(attr => attr.fieldName === prop.name);
+          if (attribute) {
+            prop.attribute = attribute.name || attribute.fieldName;
+          }
+
+          return prop.kind === 'field' && prop.privacy !== 'private';
+        });
+        components.push({
+          ...declaration,
+          methods,
+          properties
+        });
+      }
+    });
+  });
+
+  // Build dependency graphs
+  components.forEach(component => {
+    const dependencies = [];
+
+    // Recursively fetch sub-dependencies
+    function getDependencies(tag) {
+      const cmp = components.find(c => c.tagName === tag);
+      if (!cmp || !Array.isArray(component.dependencies)) {
+        return;
+      }
+
+      cmp.dependencies?.forEach(dependentTag => {
+        if (!dependencies.includes(dependentTag)) {
+          dependencies.push(dependentTag);
+        }
+        getDependencies(dependentTag);
+      });
+    }
+
+    getDependencies(component.tagName);
+
+    component.dependencies = dependencies.sort();
+  });
+
+  // Sort by name
+  return components.sort((a, b) => {
+    if (a.name < b.name) return -1;
+    if (a.name > b.name) return 1;
+    return 0;
+  });
+}

docs/docs/components/reference.njk

@@ -1,34 +0,0 @@
----
-title: Component Reference
-layout: docs
----
-
-<style>
-table code {
-	white-space: nowrap;
-}
-</style>
-
-{% for type, all in componentsBy -%}
-<h2>All {{ "CSS custom properties" if type == "cssProperty" else ("CSS parts" if type == "cssPart" else (type | title) + "s") }}</h2>
-
-<table>
-	<thead>
-		<tr>
-			<th>Name</th>
-			<th>Components</th>
-		</tr>
-	</thead>
-	{% for name, thingComponents in all -%}
-	<tr>
-		<th><code>{{ name }}{{ "()" if type == "method" }}</code></th>
-		<td>
-			{% for component in thingComponents  %}
-				<a href="../{{ component.slug }}"><code>&lt;{{ component.tagName }}&gt;</code></a>
-			{%- endfor -%}
-		</td>
-	</tr>
-	{%- endfor %}
-</table>
-
-{%- endfor %}

docs/docs/resources/accessibility.md

@@ -6,15 +6,15 @@ layout: page
 
 Web Awesome recognizes the need for all users, regardless of ability and device, to have undeterred access to the websites and applications that are created with it. This is an important goal of the project.
 
-Oftentimes, people will ask “is Web Awesome accessible?” I’m reluctant to answer because accessibility isn’t binary — there’s no simple “yes” or “no” response to provide. What seems accessible to a sighted user might be completely inaccessible to a non-sighted user. And even if you optimize for various screen readers, you still have to account for low-level vision, color blindness, hearing impairments, mobility impairments, and more.
+Oftentimes, people will ask “is Web Awesome accessible?” We’re reluctant to answer because accessibility isn’t binary — there’s no simple “yes” or “no” response to provide. What seems accessible to a sighted user might be completely inaccessible to a non-sighted user. And even if you optimize for various screen readers, you still have to account for low-level vision, color blindness, hearing impairments, mobility impairments, and more.
 
 Accessibility is something you have to continuously strive for. No individual contributor — or perhaps even an entire team — can claim their software is 100% accessible because of the sheer diversity of abilities, devices, assistive technologies, and individual use cases.
 
 Furthermore, accessibility doesn’t stop at the component level. Using accessible building blocks doesn’t magically make the rest of your webpage or application compliant. There is no library or overlay that will make your software “fully accessible” without putting in the effort. It’s also worth noting that web components are still somewhat bleeding edge, so browsers, assistive devices, and [even specifications](https://wicg.github.io/aom/spec/) are still evolving to help improve accessibility on the web platform.
 
-My commitment to Web Awesome users is this: Everything I develop will be built with accessibility in mind. I will test and improve every component to the best of my ability and knowledge. I will work around upstream issues, such as browser bugs and limitations, to the best of my ability and within reason.
+My commitment to Web Awesome users is this: Everything we develop will be built with accessibility in mind. We will test and improve every component to the best of our ability and knowledge. We will work around upstream issues, such as browser bugs and limitations, to the best of our ability and within reason.
 
-I’m fully aware that I may not get it right every time for every user, so I invite the community to participate in this ongoing effort by submitting [issues](https://github.com/shoelace-style/shoelace/issues?q=is%3Aissue+is%3Aopen+label%3Aa11y), [pull requests](https://github.com/shoelace-style/shoelace/pulls?q=is%3Aopen+is%3Apr+label%3Aa11y), and [discussions](https://github.com/shoelace-style/shoelace/discussions). Many accessibility improvements have already been made thanks to contributors submitting code, feedback, and suggestions.
+We’re fully aware that we may not get it right every time for every user, so we invite the community to participate in this ongoing effort by submitting [issues](https://github.com/shoelace-style/shoelace/issues?q=is%3Aissue+is%3Aopen+label%3Aa11y), [pull requests](https://github.com/shoelace-style/shoelace/pulls?q=is%3Aopen+is%3Apr+label%3Aa11y), and [discussions](https://github.com/shoelace-style/shoelace/discussions). Many accessibility improvements have already been made thanks to contributors submitting code, feedback, and suggestions.
 
 This is the path forward. Together, we will continue to make Web Awesome accessible to as many users as possible.