[RFC] feat(accordion): add initial rules

package.json

@@ -23,6 +23,7 @@
     "clean": "rimraf es lib umd junit.xml",
     "format": "prettier --write \"**/*.{scss,css,js,md}\"",
     "format:diff": "prettier --list-different \"**/*.{scss,css,js,md}\"",
+    "format:staged": "prettier --write",
     "test": "jest"
   },
   "devDependencies": {
@@ -33,11 +34,11 @@
     "@commitlint/cli": "^7.2.1",
     "@commitlint/config-conventional": "^7.1.2",
     "babel-core": "^7.0.0-bridge.0",
-    "babel-jest": "^23.6.0",
+    "babel-jest": "^24.0.0",
     "husky": "^1.3.1",
-    "jest": "^23.6.0",
-    "jest-circus": "^23.6.0",
-    "jest-junit": "^5.2.0",
+    "jest": "^24.0.0",
+    "jest-circus": "^24.0.0",
+    "jest-junit": "^6.2.1",
     "lint-staged": "^8.1.0",
     "prettier": "^1.15.3",
     "rimraf": "^2.6.3",
@@ -59,7 +60,7 @@
   },
   "lint-staged": {
     "*.{js,md}": [
-      "yarn format",
+      "yarn format:staged",
       "git add"
     ]
   },
@@ -105,5 +106,9 @@
       "[/\\\\]node_modules[/\\\\].+\\.(js|jsx)$"
     ],
     "watchPathIgnorePatterns": []
+  },
+  "dependencies": {
+    "htm": "^2.0.0",
+    "pretty-format": "^24.0.0"
   }
 }

src/error.js

@@ -5,4 +5,20 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-export class ValidationError extends Error {}
+import format from 'pretty-format';
+
+export class ValidationError extends Error {
+  constructor([expectation, expected, actual]) {
+    super(expectation);
+
+    if (!expected && !actual) {
+      this.message = expectation;
+    } else if (actual) {
+      this.message =
+        `${expectation}. Expected \`${format(expected)}\`, ` +
+        `instead received: \`${format(actual)}\``;
+    } else {
+      this.message = `${expectation}. Expected \`${format(expected)}\``;
+    }
+  }
+}

src/index.js

@@ -5,6 +5,5 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-export * from './error';
 export * from './rules';
 export * from './runner';

src/rules/__tests__/accordion-test.js

@@ -0,0 +1,149 @@
+/**
+ * Copyright IBM Corp. 2018, 2019
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @jest-environment jsdom
+ */
+
+import { rules } from '../accordion';
+import { createRunner } from '../../runner';
+import { html } from '../../tools/html';
+
+describe('accordion', () => {
+  describe('accordion.html', () => {
+    let runner;
+
+    beforeEach(() => {
+      runner = createRunner(rules, {
+        only: ['accordion.html'],
+      });
+      runner.beforeEach(context => {
+        const children = context.children.map(
+          (child, i) => html`
+            <li class="bx--accordion__item">
+              <button
+                class="bx--accordion__heading"
+                aria-expanded="false"
+                aria-controls="${`item-${i}`}"
+              >
+                <svg class="bx--accordion__arrow"></svg>
+                <div class="bx--accordion__title">${child.header}</div>
+              </button>
+              <div id="${`item-${i}`}" class="bx--accordion__content">
+                ${child.panel}
+              </div>
+            </li>
+          `
+        );
+        const node = html`
+          <ul class="bx--accordion">
+            ${children}
+          </ul>
+        `;
+        document.body.appendChild(node);
+        return node;
+      });
+      runner.afterEach(node => {
+        node.parentNode.removeChild(node);
+      });
+    });
+
+    it('should warn about an HTML mismatch', async () => {
+      runner.beforeEach(() => {
+        const node = html`
+          <ul class="bx--accordion"></ul>
+        `;
+        document.body.appendChild(node);
+        return node;
+      });
+
+      const { violations } = await runner.run();
+      expect(violations.length > 0).toBe(true);
+    });
+
+    it('should validate ids correctly', async () => {
+      runner.beforeEach(context => {
+        const children = context.children.map(
+          (child, i) => html`
+            <li class="bx--accordion__item">
+              <button
+                class="bx--accordion__heading"
+                aria-expanded="false"
+                aria-controls="${`item-${i}`}"
+              >
+                <svg class="bx--accordion__arrow"></svg>
+                <div class="bx--accordion__title">${child.header}</div>
+              </button>
+              <div class="bx--accordion__content">${child.panel}</div>
+            </li>
+          `
+        );
+        const node = html`
+          <ul class="bx--accordion">
+            ${children}
+          </ul>
+        `;
+        document.body.appendChild(node);
+        return node;
+      });
+      const { violations } = await runner.run();
+      expect(violations.length > 0).toBe(true);
+      expect(violations).toMatchInlineSnapshot(`
+Array [
+  [Error: Expected the value for \`aria-controls\` to match the id of the panel. Expected \`"item-0"\`],
+]
+`);
+    });
+  });
+
+  describe('accordion.header.mouse', () => {
+    let runner;
+
+    beforeEach(() => {
+      runner = createRunner(rules, {
+        only: ['accordion.header.mouse'],
+      });
+      runner.beforeEach(context => {
+        const children = context.children.map(
+          (child, i) => html`
+            <li class="bx--accordion__item">
+              <button
+                class="bx--accordion__heading"
+                aria-expanded="false"
+                aria-controls="${`item-${i}`}"
+              >
+                <svg class="bx--accordion__arrow"></svg>
+                <div class="bx--accordion__title">${child.header}</div>
+              </button>
+              <div id="${`item-${i}`}" class="bx--accordion__content">
+                ${child.panel}
+              </div>
+            </li>
+          `
+        );
+        const node = html`
+          <ul class="bx--accordion">
+            ${children}
+          </ul>
+        `;
+        document.body.appendChild(node);
+        return node;
+      });
+      runner.afterEach(node => {
+        node.parentNode.removeChild(node);
+      });
+    });
+
+    it('should verify aria attributes', async () => {
+      const { violations } = await runner.run();
+      expect(violations.length > 0).toBe(true);
+      expect(violations).toMatchInlineSnapshot(`
+Array [
+  [Error: Expected aria-expanded to be true after the heading is clicked],
+]
+`);
+    });
+  });
+});

src/rules/accordion.js

@@ -5,15 +5,122 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-const rules = [
+import { ValidationError } from '../error';
+import { diff } from '../tools/diff';
+import { createExpected } from '../tools/createElement';
+
+const defaultContext = {
+  children: [
+    {
+      header: 'header-1',
+      panel: 'panel-1',
+    },
+    {
+      header: 'header-2',
+      panel: 'panel-2',
+    },
+    {
+      header: 'header-3',
+      panel: 'panel-3',
+    },
+  ],
+};
+
+export const rules = [
   {
-    id: 'a.rule.identifier',
-    description: 'A rule description',
-    origin: 'some.location',
-    validate(node) {
-      //
+    id: 'accordion.html',
+    description:
+      'The accordion default state matches at least the expected HTML structure',
+    level: 'error',
+    context: defaultContext,
+    validate(root, context) {
+      const expected = createExpected(
+        'ul',
+        {
+          class: 'bx--accordion',
+        },
+        ...context.children.map(child =>
+          createExpected(
+            'li',
+            {
+              class: 'bx--accordion__item',
+            },
+            createExpected(
+              'button',
+              {
+                class: 'bx--accordion__heading',
+                'aria-expanded': 'false',
+                'aria-controls': node => {
+                  const attribute = node.getAttribute('aria-controls');
+                  const id = node.parentNode.childNodes[1].id;
+                  if (attribute !== id) {
+                    return [
+                      [
+                        'Expected the value for `aria-controls` to match the id of the panel',
+                        attribute,
+                        id,
+                      ],
+                    ];
+                  }
+                },
+              },
+              createExpected('svg', {
+                class: 'bx--accordion__arrow',
+              })
+            ),
+            createExpected(
+              'div',
+              {
+                class: 'bx--accordion__content',
+              },
+              child.panel
+            )
+          )
+        )
+      );
+
+      const differences = diff(expected, root);
+      if (differences.length > 0) {
+        return differences.map(difference => new ValidationError(difference));
+      }
     },
   },
-];
 
-export default rules;
+  // https://www.w3.org/TR/wai-aria-practices/#accordion
+  {
+    id: 'accordion.header.mouse',
+    description:
+      'The accordion header expands its associated panel on mouse click',
+    reference: 'https://www.w3.org/TR/wai-aria-practices/#accordion',
+    level: 'error',
+    context: defaultContext,
+    validate(root, context) {
+      const headers = root.querySelectorAll('.bx--accordion__heading');
+
+      for (let i = 0; i < context.children.length; i++) {
+        const header = headers[i];
+        header.click();
+
+        if (header.getAttribute('aria-expanded') === 'false') {
+          return new ValidationError([
+            'Expected aria-expanded to be true after the heading is clicked',
+          ]);
+        }
+      }
+    },
+  },
+
+  // Keyboard
+  // One of [Enter, Space]:
+  // When focus is on the accordion header for a collapsed panel,
+  // expands the associated panel.
+
+  // Tab: moves focus to next focusable element. All focusable elements in the
+  // accordion are included in the page Tab sequence
+
+  // Shift + tab: moves focus to the previous focusable element; all focusable
+  // elements in the accordoin are included the page Tab sequence
+
+  // Optional
+  // Down Arrow: if focus is on an accordion header
+];

src/rules/index.js

@@ -7,4 +7,6 @@
 
 import accordion from './accordion';
 
-export const rules = [...accordion];
+export const rules = {
+  accordion,
+};