Merge pull request #564 from universal-ember/heading/add-article-and-aside

Heading: add more elements to auto-leveling detection, supporting usage in qunit testing, and in general just be more robust

Author: NullVoxPopuli

docs-app/public/docs/3-ui/heading.md

@@ -10,7 +10,7 @@ This enables distributed teams to correctly produce appropriate section heading
 
 ## Usage
 
-In your app (and in this demo), you'll use `<section>` elements to denote when the [_Section Heading_][mdn-h] element should change its level.
+In your app, you can use any of `<section>`, `<article>`, and `<aside>` elements to denote when the [_Section Heading_][mdn-h] element should change its level.
 Note that this demo starts with `h3`, because this docs page already has an `h1`, and _this_ section (Usage) uses an `h2`.
 
 <div class="featured-demo auto-height">
@@ -19,42 +19,105 @@ Note that this demo starts with `h3`, because this docs page already has an `h1`
 import { Heading } from 'ember-primitives/components/heading';
   
 <template>
-  <Heading>a heading</Heading>
-  <Heading>a heading</Heading>
-
-  <section>
-    <Heading>a heading</Heading>
+  <main aria-label="heading-demo">
     <Heading>a heading</Heading>
-    <section>
+
+    <nav>
+      <Heading>a heading</Heading>
+    </nav>
+
+    <article>
+      <Heading>a heading</Heading>
+      <a href="#">
+        <Heading>a heading</Heading>
+      </a>
       <Heading>a heading</Heading>
       <section>
         <Heading>a heading</Heading>
         <Heading>a heading</Heading>
+        <a href="#">
+          <Heading>a heading</Heading>
+        </a>
       </section>
-      <Heading>a heading</Heading>
-    </section>
-  </section>
+      <footer>
+        <Heading>a heading</Heading>
+
+      </footer>
+    </article>
+  </main>
 
   <style>
-    h3, h4, h5, h6 { margin: 0; }
+    h1, h2, h3, h4, h5, h6 { margin: 0; }
 
-    h3::before, h4::before, h5::before, h6::before {
+    h1::before, h2::before, h3::before, h4::before, h5::before, h6::before {
       position: absolute;
       margin-left: -1.2em;
       font-size: 0.7em;
       text-align: right;
       opacity: 0.8;
     }
 
+    h1 { font-size: 2.5rem; }
+    h2 { font-size: 2.25rem; }
     h3 { font-size: 2rem; }
     h4 { font-size: 1.5rem; }
     h5 { font-size: 1.25rem; }
     h6 { font-size: 1rem; }
+    a { color: white; }
 
+    h1::before { content: 'h1'; }
+    h2::before { content: 'h2'; }
     h3::before { content: 'h3'; }
     h4::before { content: 'h4'; }
     h5::before { content: 'h5'; }
     h6::before { content: 'h6'; }
+
+    article, section, aside, nav, main, footer {
+      border: 1px dotted;
+      padding: 0.25rem 1.5rem;
+      padding-left: 2rem;
+      padding-right: 0.5rem;
+      position: relative;
+
+      &::before {
+        position: absolute;
+        right: 0.5rem;
+        top: -1rem;
+        font-size: 0.7rem;
+        text-align: right;
+        opacity: 0.8;
+      }
+    }
+
+    section, article {
+      display: flex;
+      flex-direction: column;
+      gap: 0.75rem;
+    }
+
+    article::before { content: '<article>'; }
+    section::before { content: '<section>'; }
+    aside::before { content: '<aside>'; }
+    nav::before { content: '<nav>'; }
+    main::before { content: '<main>'; }
+    footer::before { content: '<footer>'; }
+
+    main {
+      display: grid;
+      gap: 2.5rem;
+      grid-template-columns: max-content 1fr;
+      grid-template-areas:
+        "heading heading"
+        "nav content"
+        "nav content"
+        "nav content";
+
+    }
+
+    >:first-child { grid-area: heading; }
+    nav { grid-area: nav; }
+    article { grid-area: content; }
+
   </style>
 </template>
 ```

docs-app/tests/application/pages-test.ts

@@ -9,10 +9,28 @@ import { a11yAudit } from 'ember-a11y-testing/test-support';
 // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
 const pages: { path: string }[] = (window as any).__pages__;
 
+/**
+ * per-page settings
+ */
+const a11yChecks: {
+  [url: string]: {
+    [checkName: string]: Record<string, unknown>;
+  };
+} = {
+  '/3-ui/heading.md': {
+    'landmark-main-is-top-level': {
+      enabled: false,
+    },
+    'landmark-no-duplicate-main': {
+      enabled: false,
+    },
+  },
+};
+
 /**
  * a11yAudit halts tests, this gets around that
  */
-async function checkA11y(assert: Assert, path: string, theme: string) {
+async function checkA11y(assert: Assert, path: string, theme: string, settings: object) {
   await settled();
 
   try {
@@ -23,6 +41,7 @@ async function checkA11y(assert: Assert, path: string, theme: string) {
         'color-contrast': {
           enabled: false,
         },
+        ...settings,
       },
     });
     assert.ok(true, `no a11y errors found for ${path} using the ${theme} theme`);
@@ -52,18 +71,19 @@ module('Application | Pages', function (hooks) {
   for (const page of pages) {
     test(`${page.path}`, async function (assert) {
       const path = page.path.replace('.md', '');
+      const settings: object = a11yChecks[page.path] ?? {};
 
       await visit(path);
       await waitUntil(() => findAll('nav a').length !== 0);
-      await checkA11y(assert, path, 'default');
+      await checkA11y(assert, path, 'default', settings);
 
       assert.dom('[data-page-error]').doesNotExist();
 
       colorScheme.update('dark');
-      await checkA11y(assert, path, 'dark');
+      await checkA11y(assert, path, 'dark', settings);
 
       colorScheme.update('light');
-      await checkA11y(assert, path, 'light');
+      await checkA11y(assert, path, 'light', settings);
     });
   }
 });

ember-primitives/src/components/heading.gts

@@ -1,20 +1,56 @@
 import Component from "@glimmer/component";
+import { assert } from "@ember/debug";
 
 import { element } from "ember-element-helper";
 
 import type Owner from "@ember/owner";
 
 const LOOKUP = new WeakMap<Text, number>();
 
-function levelOf(node: Text): number {
+const BOUNDARY_ELEMENTS = new Set([
+  "SECTION",
+  "ARTICLE",
+  "ASIDE",
+  "HEADER",
+  "FOOTER",
+  "MAIN",
+  "NAV",
+]);
+
+/**
+ * A set with both cases is more performant than calling toLowerCase
+ */
+const SECTION_HEADINGS = new Set([
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "H1",
+  "H2",
+  "H3",
+  "H4",
+  "H5",
+  "H6",
+]);
+const TEST_BOUNDARY = "ember-testing";
+
+function isRoot(element: Element) {
+  return element === document.body || element.id === TEST_BOUNDARY;
+}
+
+/**
+ * The Platform native 'closest' function can't punch through shadow-boundaries
+ */
+function nearestAncestor(node: Text | Element, matcher: (el: Element) => boolean) {
   let parent: ParentNode | null = node.parentElement;
-  let level = 0;
+
+  if (!parent) return;
 
   while (parent) {
     if (parent instanceof Element) {
-      if (parent.tagName.toLowerCase() === "section") {
-        level++;
-      }
+      if (matcher(parent)) return parent;
     }
 
     if (parent instanceof ShadowRoot) {
@@ -23,8 +59,69 @@ function levelOf(node: Text): number {
 
     parent = parent.parentNode;
   }
+}
+
+/**
+ * The algorithm:
+ *
+ * section <- "our" level-changing boundary element
+ *   h# <- the element we want to figure out the level of
+ *
+ * We start assuming we'll emit an h1.
+ * We adjust this based on what we find crawling up the tree.
+ *
+ * While traversing up, when we go from the h# to the section,
+ *  and ignore it. Because this alone has no bearing on if the h# should be an h2.
+ *  We need to continue traversing upwards, until we hit the next boundary element.
+ *
+ * IF we would change the level the heading, we will find another heading between
+ *  these two boundary elements.
+ *  We'll need to check the subtrees between these elements, stopping if we
+ *  encounter other boundary elements.
+ *
+ */
+function levelOf(node: Text): number {
+  const ourBoundary = nearestAncestor(node, (el) => BOUNDARY_ELEMENTS.has(el.tagName));
+
+  /**
+   * We are the top-level
+   */
+  if (!ourBoundary) {
+    return 1;
+  }
+
+  const stopAt = nearestAncestor(ourBoundary, (el) => {
+    if (BOUNDARY_ELEMENTS.has(el.tagName)) return true;
+
+    return isRoot(el);
+  });
+
+  assert(
+    `[BUG]: Could not find a stopping boundary for automatic heading level detection. Checked for ${[...BOUNDARY_ELEMENTS, "body", "#ember-testing"].map((x) => x.toLowerCase()).join(", ")}`,
+    stopAt,
+  );
+
+  let current: ParentNode | null = ourBoundary.parentNode;
+
+  while (current) {
+    for (const child of current.children) {
+      if (!SECTION_HEADINGS.has(child.tagName)) continue;
+
+      const level = parseInt(child.tagName.replace("h", "").replace("H", ""));
+
+      return level + 1;
+    }
+
+    if (current === stopAt) break;
+
+    if (current instanceof ShadowRoot) {
+      current = current.host;
+    }
+
+    current = current.parentNode;
+  }
 
-  return level;
+  return 1;
 }
 
 export class Heading extends Component<{
@@ -44,7 +141,7 @@ export class Heading extends Component<{
     if (existing) return existing;
 
     const parentLevel = levelOf(this.headingScopeAnchor);
-    const myLevel = parentLevel + 1;
+    const myLevel = parentLevel;
 
     LOOKUP.set(this.headingScopeAnchor, myLevel);