book-of-elementals 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Nikola Stamatović
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# 📓 Book of Elementals [![npm version](https://img.shields.io/npm/v/book-of-elementals)](https://www.npmjs.com/package/book-of-elementals) [![license mit](https://img.shields.io/badge/license-MIT-green)](https://github.com/stamat/book-of-elementals/blob/main/LICENSE)
+
+Accessible, dependency-free custom elements. Light DOM, no build step required.
+
+Sibling to [book-of-spells](https://github.com/stamat/book-of-spells) — that one
+holds the JavaScript helpers, this one holds the elements.
+
+## Principles
+
+- **Native first** — an element exists only where the platform leaves a real gap
+- **Light DOM, always** — no shadow roots, your CSS reaches every part
+- **Accessible or it does not ship** — [W3C APG](https://www.w3.org/WAI/ARIA/apg/patterns/) patterns, keyboard and reduced-motion included
+- **No runtime dependencies**
+
+## Elements
+
+| Element             | Pattern                                                                                        |
+| ------------------- | ---------------------------------------------------------------------------------------------- |
+| `<accordion-elemental>` | [APG Accordion](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/), over native `<details>`   |
+
+## Docs
+
+[stamat.github.io/book-of-elementals](https://stamat.github.io/book-of-elementals/)
+
+## Installation
+
+```bash
+npm install book-of-elementals
+```
+
+Import one element and only that element is registered:
+
+```javascript
+import "book-of-elementals/accordion";
+```
+
+```scss
+@use "book-of-elementals/accordion/style.scss";
+```
+
+Or the whole book:
+
+```javascript
+import "book-of-elementals";
+```
+
+```scss
+@use "book-of-elementals/styles/index.scss";
+```
+
+Or the CDN, no build step. Every element ships its own bundle:
+
+```html
+<script src="https://unpkg.com/book-of-elementals/dist/elementals/accordion.min.js"></script>
+<link
+  rel="stylesheet"
+  href="https://unpkg.com/book-of-elementals/dist/elementals/accordion.min.css"
+/>
+```
+
+No global, no boot call — including a bundle registers its element and it
+upgrades itself wherever it appears, including markup added later. Swap in
+`book-of-elementals.min.js` for the whole book.
+
+## `<accordion-elemental>`
+
+Wraps native `<details>`/`<summary>` instead of reimplementing disclosure on
+`<div>`s, so the semantics, Enter/Space activation, screen-reader announcement
+and find-in-page expansion are the browser's.
+
+```html
+<accordion-elemental exclusive>
+  <details open>
+    <summary>First question</summary>
+    <p>First answer.</p>
+  </details>
+  <details>
+    <summary>Second question</summary>
+    <p>Second answer.</p>
+  </details>
+</accordion-elemental>
+```
+
+What the element adds on top of native:
+
+- `exclusive` — assigns a shared `name` so only one panel stays open
+- <kbd>Up</kbd>/<kbd>Down</kbd>/<kbd>Home</kbd>/<kbd>End</kbd> navigation between headers ([APG accordion](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/))
+- deep links — a URL fragment pointing inside a panel opens it
+- an `accordion-toggle` event on the group, since `toggle` does not bubble
+
+| Attribute   | Type    | Default | Description                                                |
+| ----------- | ------- | ------- | ---------------------------------------------------------- |
+| `exclusive` | boolean | `false` | Only one panel open at a time.                             |
+| `name`      | string  | auto    | The shared `name` used by `exclusive`. Generated if unset. |
+
+Put a heading inside the `<summary>` when the panels are page sections, so
+screen reader users can navigate to them by heading:
+
+```html
+<summary><h3>Question</h3></summary>
+```
+
+Styling is yours — there is no shadow DOM. The open/close animation is pure CSS
+on `::details-content` and degrades to native instant toggling where that is
+unsupported:
+
+```css
+accordion-elemental {
+  --accordion-elemental-duration: 250ms;
+  --accordion-elemental-easing: ease;
+}
+```
+
+## Development
+
+```bash
+npm install
+npm run dev    # docs site on :4040 with livereload
+npm test       # unit tests (jest), colocated as src/**/*.test.js
+npm run lint   # eslint + stylelint
+npm run build  # dist/ (package) and _site/ (docs) — both gitignored
+```
+
+`src/` is the package, `docs/` is the site's markdown and its skin. Building writes
+`dist/` (rebuilt on `prepack`, so it never has to be committed) and `_site/`, which
+`.github/workflows/pages.yml` deploys to GitHub Pages. `dist/` is copied into `_site/`
+because a Pages artifact is a single directory — nothing above the site root exists once
+deployed, so the live demos need their bundle inside it.
+
+
+---
+
+Made with ❤️ by @stamat.

package/dist/book-of-elementals.css

@@ -0,0 +1,29 @@
+/* book-of-elementals v0.1.0 | https://stamat.github.io/book-of-elementals/ | MIT License */
+:root {
+  --accordion-elemental-duration: 250ms;
+  --accordion-elemental-easing: ease;
+}
+
+accordion-elemental {
+  display: block;
+}
+accordion-elemental > details {
+  interpolate-size: allow-keywords;
+}
+accordion-elemental > details > summary {
+  cursor: pointer;
+}
+accordion-elemental > details::details-content {
+  block-size: 0;
+  overflow: hidden;
+  transition: block-size var(--accordion-elemental-duration) var(--accordion-elemental-easing), content-visibility var(--accordion-elemental-duration) var(--accordion-elemental-easing) allow-discrete;
+}
+accordion-elemental > details[open]::details-content {
+  block-size: auto;
+}
+@media (prefers-reduced-motion: reduce) {
+  accordion-elemental > details::details-content {
+    transition: none;
+  }
+}
+/*# sourceMappingURL=book-of-elementals.css.map */

package/dist/book-of-elementals.css.map

@@ -0,0 +1 @@
+{"version":3,"sourceRoot":"","sources":["file:///Users/stamat/Sites/localhost/book-of-elementals/src/elementals/accordion/index.scss"],"names":[],"mappings":";AAAA;EACE;EACA;;;AAGF;EACE;;AAEA;EAIE;;AAGF;EACE;;AAKF;EACE;EACA;EACA,YACE;;AAIJ;EACE;;AAGF;EACE;IACE","sourcesContent":[":root {\n  --accordion-elemental-duration: 250ms;\n  --accordion-elemental-easing: ease;\n}\n\naccordion-elemental {\n  display: block;\n\n  > details {\n    // Lets `block-size` animate to and from the `auto` keyword. Scoped here\n    // rather than on :root so the library does not change how the whole page\n    // interpolates sizes.\n    interpolate-size: allow-keywords;\n  }\n\n  > details > summary {\n    cursor: pointer;\n  }\n\n  // Open/close animation. Browsers without ::details-content drop this rule and\n  // fall back to native instant toggling, which is correct, just unanimated.\n  > details::details-content {\n    block-size: 0;\n    overflow: hidden;\n    transition:\n      block-size var(--accordion-elemental-duration) var(--accordion-elemental-easing),\n      content-visibility var(--accordion-elemental-duration) var(--accordion-elemental-easing) allow-discrete;\n  }\n\n  > details[open]::details-content {\n    block-size: auto;\n  }\n\n  @media (prefers-reduced-motion: reduce) {\n    > details::details-content {\n      transition: none;\n    }\n  }\n}\n"]}

package/dist/book-of-elementals.js

@@ -0,0 +1,148 @@
+/* book-of-elementals v0.1.0 | https://stamat.github.io/book-of-elementals/ | MIT License */
+(() => {
+  // src/core.js
+  var ElementBase = typeof HTMLElement !== "undefined" ? HTMLElement : class {
+  };
+  function readOptions(el, schema) {
+    const options = {};
+    for (const key in schema) {
+      const kebab = key.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase());
+      const raw = el.dataset[key] != null ? el.dataset[key] : el.getAttribute(kebab);
+      if (raw == null) continue;
+      if (schema[key] === "boolean") {
+        options[key] = raw !== "false" && raw !== "0";
+      } else if (schema[key] === "number") {
+        const num = parseFloat(raw);
+        if (!Number.isNaN(num)) options[key] = num;
+      } else {
+        options[key] = raw;
+      }
+    }
+    return options;
+  }
+  function define(tag, ctor) {
+    if (typeof customElements === "undefined" || customElements.get(tag)) return;
+    customElements.define(tag, ctor);
+  }
+
+  // src/elementals/accordion/index.js
+  function nextIndex(current, key, length) {
+    if (length === 0) return null;
+    switch (key) {
+      case "ArrowDown":
+        return (current + 1) % length;
+      case "ArrowUp":
+        return (current - 1 + length) % length;
+      case "Home":
+        return 0;
+      case "End":
+        return length - 1;
+      default:
+        return null;
+    }
+  }
+  var OPTIONS = { exclusive: "boolean" };
+  var groupCount = 0;
+  var AccordionElemental = class extends ElementBase {
+    /** Direct-child panels only, so a nested accordion is not swallowed. */
+    get panels() {
+      return Array.from(this.querySelectorAll(":scope > details"));
+    }
+    /** The `<summary>` of each panel, in document order. */
+    get headers() {
+      return this.panels.map((panel) => panel.querySelector(":scope > summary")).filter(Boolean);
+    }
+    connectedCallback() {
+      if (this.initialized || !this.panels.length) return;
+      this.initialized = true;
+      this.options = Object.assign({ exclusive: false }, readOptions(this, OPTIONS));
+      this.onKeyDown = this.onKeyDown.bind(this);
+      this.onToggle = this.onToggle.bind(this);
+      this.onHashChange = this.onHashChange.bind(this);
+      if (this.options.exclusive) this.applyExclusive();
+      this.addCarets();
+      this.addEventListener("keydown", this.onKeyDown);
+      this.addEventListener("toggle", this.onToggle, true);
+      window.addEventListener("hashchange", this.onHashChange);
+      this.openFromHash();
+    }
+    disconnectedCallback() {
+      if (!this.initialized) return;
+      this.removeEventListener("keydown", this.onKeyDown);
+      this.removeEventListener("toggle", this.onToggle, true);
+      window.removeEventListener("hashchange", this.onHashChange);
+      this.initialized = false;
+    }
+    /**
+     * Give every panel the same `name`, which is what makes native `<details>`
+     * mutually exclusive.
+     */
+    applyExclusive() {
+      const panels = this.panels;
+      let seenOpen = false;
+      for (const panel of panels) {
+        if (!panel.open) continue;
+        if (seenOpen) panel.open = false;
+        seenOpen = true;
+      }
+      if (!this.groupName) {
+        this.groupName = this.getAttribute("name") || "accordion-elemental-" + ++groupCount;
+      }
+      for (const panel of panels) panel.name = this.groupName;
+    }
+    /**
+     * Append the caret to every header that has not got one, so authors write
+     * plain `<summary>` and still get a marker. Writing the span yourself is
+     * respected and left alone - that is also how you keep the caret without
+     * JavaScript.
+     */
+    addCarets() {
+      for (const header of this.headers) {
+        if (header.querySelector(":scope > ." + CARET_CLASS)) continue;
+        header.insertAdjacentHTML("beforeend", CARET);
+      }
+    }
+    onKeyDown(e) {
+      const summary = e.target.closest && e.target.closest("summary");
+      if (!summary) return;
+      const headers = this.headers;
+      const current = headers.indexOf(summary);
+      if (current === -1) return;
+      const next = nextIndex(current, e.key, headers.length);
+      if (next === null) return;
+      e.preventDefault();
+      headers[next].focus();
+    }
+    onToggle(e) {
+      const panel = e.target;
+      if (!this.panels.includes(panel)) return;
+      this.dispatchEvent(new CustomEvent("accordion-toggle", {
+        bubbles: true,
+        detail: { panel, open: panel.open }
+      }));
+    }
+    onHashChange() {
+      this.openFromHash();
+    }
+    /**
+     * Open the panel containing the element the URL fragment points at, so a link
+     * to a single question lands on it opened.
+     *
+     * ponytail: Chrome already auto-expands `<details>` on fragment navigation;
+     * this covers the browsers that do not. Drop it once that is everywhere.
+     */
+    openFromHash() {
+      const id = decodeURIComponent(window.location.hash.slice(1));
+      if (!id) return;
+      const target = document.getElementById(id);
+      if (!target || !this.contains(target)) return;
+      let panel = target.closest("details");
+      while (panel && this.contains(panel)) {
+        panel.open = true;
+        panel = panel.parentElement && panel.parentElement.closest("details");
+      }
+    }
+  };
+  define("accordion-elemental", AccordionElemental);
+})();
+//# sourceMappingURL=book-of-elementals.js.map

package/dist/book-of-elementals.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/core.js", "../src/elementals/accordion/index.js"],
+  "sourcesContent": ["/**\n * Shared plumbing for every element in the book. Deliberately three small\n * functions and no base class - a base class would have to guess at a lifecycle\n * before there are enough elements to know what the lifecycle is.\n */\n\n// Fall back to a plain base when HTMLElement is absent (e.g. Node under test),\n// so element modules stay importable outside the browser.\nexport const ElementBase = typeof HTMLElement !== 'undefined' ? HTMLElement : class {};\n\n/**\n * Read options off an element's attributes, accepting bare, `data-*` and\n * kebab-case forms. `data-*` wins when both are present.\n *\n * @param {HTMLElement} el\n * @param {Object<string, 'boolean'|'number'|'string'>} schema - camelCase option key to type.\n * @returns {Object} Only the options actually present on the element.\n */\nexport function readOptions(el, schema) {\n  const options = {};\n  for (const key in schema) {\n    const kebab = key.replace(/[A-Z]/g, (m) => '-' + m.toLowerCase());\n    const raw = el.dataset[key] != null ? el.dataset[key] : el.getAttribute(kebab);\n    if (raw == null) continue;\n\n    if (schema[key] === 'boolean') {\n      // A bare attribute reads as '', which means \"on\".\n      options[key] = raw !== 'false' && raw !== '0';\n    } else if (schema[key] === 'number') {\n      const num = parseFloat(raw);\n      if (!Number.isNaN(num)) options[key] = num;\n    } else {\n      options[key] = raw;\n    }\n  }\n  return options;\n}\n\n/**\n * Register a custom element - in the browser only, and only once, so the module\n * is safe to import twice or to import under Node.\n * @param {string} tag\n * @param {Function} ctor\n */\nexport function define(tag, ctor) {\n  if (typeof customElements === 'undefined' || customElements.get(tag)) return;\n  customElements.define(tag, ctor);\n}\n", "import { ElementBase, readOptions, define } from '../../core.js';\n\n/**\n * Compute the header to move focus to for a roving-arrow key press.\n * @param {number} current - Index of the currently focused header.\n * @param {string} key - KeyboardEvent.key value.\n * @param {number} length - Number of headers in the group.\n * @returns {number|null} Target index, or null if the key is unhandled.\n */\nexport function nextIndex(current, key, length) {\n  if (length === 0) return null;\n  switch (key) {\n    case 'ArrowDown':\n      return (current + 1) % length;\n    case 'ArrowUp':\n      return (current - 1 + length) % length;\n    case 'Home':\n      return 0;\n    case 'End':\n      return length - 1;\n    default:\n      return null;\n  }\n}\n\nconst OPTIONS = { exclusive: 'boolean' };\n\n// Monotonic counter for generating unique `name` values for exclusive groups.\nlet groupCount = 0;\n\n/**\n * `<accordion-elemental>` custom element.\n *\n * A thin coordinator over native `<details>`/`<summary>` rather than a\n * reimplementation of the APG Accordion pattern. Native already provides the\n * disclosure semantics, Enter/Space activation, screen-reader announcement and\n * find-in-page expansion. This element only adds what native leaves out:\n *\n * - `exclusive`: assigns a shared `name` so only one panel stays open\n * - arrow/Home/End navigation between headers (APG accordion, optional but recommended)\n * - opening the panel that contains the current URL fragment\n * - an `accordion-toggle` event on the group, since `toggle` does not bubble\n *\n * Light DOM, no shadow root, so every part stays stylable by the page author.\n *\n * @see https://www.w3.org/WAI/ARIA/apg/patterns/accordion/\n */\nexport class AccordionElemental extends ElementBase {\n  /** Direct-child panels only, so a nested accordion is not swallowed. */\n  get panels() {\n    return Array.from(this.querySelectorAll(':scope > details'));\n  }\n\n  /** The `<summary>` of each panel, in document order. */\n  get headers() {\n    return this.panels\n      .map((panel) => panel.querySelector(':scope > summary'))\n      .filter(Boolean);\n  }\n\n  connectedCallback() {\n    // Wait until the light-DOM panels have been parsed. The bundle is loaded\n    // deferred or at the end of the body, so by upgrade time they are there.\n    if (this.initialized || !this.panels.length) return;\n    this.initialized = true;\n\n    this.options = Object.assign({ exclusive: false }, readOptions(this, OPTIONS));\n\n    this.onKeyDown = this.onKeyDown.bind(this);\n    this.onToggle = this.onToggle.bind(this);\n    this.onHashChange = this.onHashChange.bind(this);\n\n    if (this.options.exclusive) this.applyExclusive();\n    this.addCarets();\n\n    this.addEventListener('keydown', this.onKeyDown);\n    // `toggle` does not bubble, but non-bubbling events still run the capture\n    // phase through ancestors - so capture is how the group hears its panels.\n    this.addEventListener('toggle', this.onToggle, true);\n    window.addEventListener('hashchange', this.onHashChange);\n\n    this.openFromHash();\n  }\n\n  disconnectedCallback() {\n    if (!this.initialized) return;\n    this.removeEventListener('keydown', this.onKeyDown);\n    this.removeEventListener('toggle', this.onToggle, true);\n    window.removeEventListener('hashchange', this.onHashChange);\n    this.initialized = false;\n  }\n\n  /**\n   * Give every panel the same `name`, which is what makes native `<details>`\n   * mutually exclusive.\n   */\n  applyExclusive() {\n    const panels = this.panels;\n\n    // Close extras *before* naming them: assigning a shared name to several\n    // already-open panels leaves it to the browser which one survives. Doing it\n    // here means the first authored `open` wins, deterministically.\n    let seenOpen = false;\n    for (const panel of panels) {\n      if (!panel.open) continue;\n      if (seenOpen) panel.open = false;\n      seenOpen = true;\n    }\n\n    // Remember the generated name so moving the group in the DOM re-uses it\n    // instead of minting a new one on every reconnect.\n    if (!this.groupName) {\n      this.groupName = this.getAttribute('name') || 'accordion-elemental-' + (++groupCount);\n    }\n    for (const panel of panels) panel.name = this.groupName;\n  }\n\n  /**\n   * Append the caret to every header that has not got one, so authors write\n   * plain `<summary>` and still get a marker. Writing the span yourself is\n   * respected and left alone - that is also how you keep the caret without\n   * JavaScript.\n   */\n  addCarets() {\n    for (const header of this.headers) {\n      if (header.querySelector(':scope > .' + CARET_CLASS)) continue;\n      header.insertAdjacentHTML('beforeend', CARET);\n    }\n  }\n\n  onKeyDown(e) {\n    const summary = e.target.closest && e.target.closest('summary');\n    if (!summary) return;\n    const headers = this.headers;\n    const current = headers.indexOf(summary);\n    // -1 means the summary belongs to a nested accordion; let it handle itself.\n    if (current === -1) return;\n\n    const next = nextIndex(current, e.key, headers.length);\n    if (next === null) return;\n    e.preventDefault();\n    headers[next].focus();\n  }\n\n  onToggle(e) {\n    const panel = e.target;\n    if (!this.panels.includes(panel)) return;\n    this.dispatchEvent(new CustomEvent('accordion-toggle', {\n      bubbles: true,\n      detail: { panel: panel, open: panel.open }\n    }));\n  }\n\n  onHashChange() {\n    this.openFromHash();\n  }\n\n  /**\n   * Open the panel containing the element the URL fragment points at, so a link\n   * to a single question lands on it opened.\n   *\n   * ponytail: Chrome already auto-expands `<details>` on fragment navigation;\n   * this covers the browsers that do not. Drop it once that is everywhere.\n   */\n  openFromHash() {\n    const id = decodeURIComponent(window.location.hash.slice(1));\n    if (!id) return;\n    const target = document.getElementById(id);\n    if (!target || !this.contains(target)) return;\n\n    // Walk up so a nested panel opens its ancestors too.\n    let panel = target.closest('details');\n    while (panel && this.contains(panel)) {\n      panel.open = true;\n      panel = panel.parentElement && panel.parentElement.closest('details');\n    }\n  }\n}\n\ndefine('accordion-elemental', AccordionElemental);\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/book-of-elementals.min.css

@@ -0,0 +1,2 @@
+/* book-of-elementals v0.1.0 | https://stamat.github.io/book-of-elementals/ | MIT License */
+:root{--accordion-elemental-duration: .25s;--accordion-elemental-easing: ease}accordion-elemental{display:block}accordion-elemental>details{interpolate-size:allow-keywords}accordion-elemental>details>summary{cursor:pointer}accordion-elemental>details::details-content{block-size:0;overflow:hidden;transition:block-size var(--accordion-elemental-duration) var(--accordion-elemental-easing),content-visibility var(--accordion-elemental-duration) var(--accordion-elemental-easing) allow-discrete}accordion-elemental>details[open]::details-content{block-size:auto}@media(prefers-reduced-motion:reduce){accordion-elemental>details::details-content{transition:none}}

package/dist/book-of-elementals.min.js

@@ -0,0 +1,2 @@
+/* book-of-elementals v0.1.0 | https://stamat.github.io/book-of-elementals/ | MIT License */
+(()=>{var r=typeof HTMLElement<"u"?HTMLElement:class{};function l(e,n){const t={};for(const s in n){const i=s.replace(/[A-Z]/g,a=>"-"+a.toLowerCase()),o=e.dataset[s]!=null?e.dataset[s]:e.getAttribute(i);if(o!=null)if(n[s]==="boolean")t[s]=o!=="false"&&o!=="0";else if(n[s]==="number"){const a=parseFloat(o);Number.isNaN(a)||(t[s]=a)}else t[s]=o}return t}function c(e,n){typeof customElements>"u"||customElements.get(e)||customElements.define(e,n)}function h(e,n,t){if(t===0)return null;switch(n){case"ArrowDown":return(e+1)%t;case"ArrowUp":return(e-1+t)%t;case"Home":return 0;case"End":return t-1;default:return null}}var u={exclusive:"boolean"},d=0,f=class extends r{get panels(){return Array.from(this.querySelectorAll(":scope > details"))}get headers(){return this.panels.map(e=>e.querySelector(":scope > summary")).filter(Boolean)}connectedCallback(){this.initialized||!this.panels.length||(this.initialized=!0,this.options=Object.assign({exclusive:!1},l(this,u)),this.onKeyDown=this.onKeyDown.bind(this),this.onToggle=this.onToggle.bind(this),this.onHashChange=this.onHashChange.bind(this),this.options.exclusive&&this.applyExclusive(),this.addCarets(),this.addEventListener("keydown",this.onKeyDown),this.addEventListener("toggle",this.onToggle,!0),window.addEventListener("hashchange",this.onHashChange),this.openFromHash())}disconnectedCallback(){this.initialized&&(this.removeEventListener("keydown",this.onKeyDown),this.removeEventListener("toggle",this.onToggle,!0),window.removeEventListener("hashchange",this.onHashChange),this.initialized=!1)}applyExclusive(){const e=this.panels;let n=!1;for(const t of e)t.open&&(n&&(t.open=!1),n=!0);this.groupName||(this.groupName=this.getAttribute("name")||"accordion-elemental-"+ ++d);for(const t of e)t.name=this.groupName}addCarets(){for(const e of this.headers)e.querySelector(":scope > ."+CARET_CLASS)||e.insertAdjacentHTML("beforeend",CARET)}onKeyDown(e){const n=e.target.closest&&e.target.closest("summary");if(!n)return;const t=this.headers,s=t.indexOf(n);if(s===-1)return;const i=h(s,e.key,t.length);i!==null&&(e.preventDefault(),t[i].focus())}onToggle(e){const n=e.target;this.panels.includes(n)&&this.dispatchEvent(new CustomEvent("accordion-toggle",{bubbles:!0,detail:{panel:n,open:n.open}}))}onHashChange(){this.openFromHash()}openFromHash(){const e=decodeURIComponent(window.location.hash.slice(1));if(!e)return;const n=document.getElementById(e);if(!n||!this.contains(n))return;let t=n.closest("details");for(;t&&this.contains(t);)t.open=!0,t=t.parentElement&&t.parentElement.closest("details")}};c("accordion-elemental",f)})();

package/dist/elementals/accordion.css

@@ -0,0 +1,29 @@
+/* book-of-elementals v0.1.0 | https://stamat.github.io/book-of-elementals/ | MIT License */
+:root {
+  --accordion-elemental-duration: 250ms;
+  --accordion-elemental-easing: ease;
+}
+
+accordion-elemental {
+  display: block;
+}
+accordion-elemental > details {
+  interpolate-size: allow-keywords;
+}
+accordion-elemental > details > summary {
+  cursor: pointer;
+}
+accordion-elemental > details::details-content {
+  block-size: 0;
+  overflow: hidden;
+  transition: block-size var(--accordion-elemental-duration) var(--accordion-elemental-easing), content-visibility var(--accordion-elemental-duration) var(--accordion-elemental-easing) allow-discrete;
+}
+accordion-elemental > details[open]::details-content {
+  block-size: auto;
+}
+@media (prefers-reduced-motion: reduce) {
+  accordion-elemental > details::details-content {
+    transition: none;
+  }
+}
+/*# sourceMappingURL=accordion.css.map */

package/dist/elementals/accordion.css.map

@@ -0,0 +1 @@
+{"version":3,"sourceRoot":"","sources":["file:///Users/stamat/Sites/localhost/book-of-elementals/src/elementals/accordion/index.scss"],"names":[],"mappings":";AAAA;EACE;EACA;;;AAGF;EACE;;AAEA;EAIE;;AAGF;EACE;;AAKF;EACE;EACA;EACA,YACE;;AAIJ;EACE;;AAGF;EACE;IACE","sourcesContent":[":root {\n  --accordion-elemental-duration: 250ms;\n  --accordion-elemental-easing: ease;\n}\n\naccordion-elemental {\n  display: block;\n\n  > details {\n    // Lets `block-size` animate to and from the `auto` keyword. Scoped here\n    // rather than on :root so the library does not change how the whole page\n    // interpolates sizes.\n    interpolate-size: allow-keywords;\n  }\n\n  > details > summary {\n    cursor: pointer;\n  }\n\n  // Open/close animation. Browsers without ::details-content drop this rule and\n  // fall back to native instant toggling, which is correct, just unanimated.\n  > details::details-content {\n    block-size: 0;\n    overflow: hidden;\n    transition:\n      block-size var(--accordion-elemental-duration) var(--accordion-elemental-easing),\n      content-visibility var(--accordion-elemental-duration) var(--accordion-elemental-easing) allow-discrete;\n  }\n\n  > details[open]::details-content {\n    block-size: auto;\n  }\n\n  @media (prefers-reduced-motion: reduce) {\n    > details::details-content {\n      transition: none;\n    }\n  }\n}\n"]}

package/dist/elementals/accordion.js

@@ -0,0 +1,148 @@
+/* book-of-elementals v0.1.0 | https://stamat.github.io/book-of-elementals/ | MIT License */
+(() => {
+  // src/core.js
+  var ElementBase = typeof HTMLElement !== "undefined" ? HTMLElement : class {
+  };
+  function readOptions(el, schema) {
+    const options = {};
+    for (const key in schema) {
+      const kebab = key.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase());
+      const raw = el.dataset[key] != null ? el.dataset[key] : el.getAttribute(kebab);
+      if (raw == null) continue;
+      if (schema[key] === "boolean") {
+        options[key] = raw !== "false" && raw !== "0";
+      } else if (schema[key] === "number") {
+        const num = parseFloat(raw);
+        if (!Number.isNaN(num)) options[key] = num;
+      } else {
+        options[key] = raw;
+      }
+    }
+    return options;
+  }
+  function define(tag, ctor) {
+    if (typeof customElements === "undefined" || customElements.get(tag)) return;
+    customElements.define(tag, ctor);
+  }
+
+  // src/elementals/accordion/index.js
+  function nextIndex(current, key, length) {
+    if (length === 0) return null;
+    switch (key) {
+      case "ArrowDown":
+        return (current + 1) % length;
+      case "ArrowUp":
+        return (current - 1 + length) % length;
+      case "Home":
+        return 0;
+      case "End":
+        return length - 1;
+      default:
+        return null;
+    }
+  }
+  var OPTIONS = { exclusive: "boolean" };
+  var groupCount = 0;
+  var AccordionElemental = class extends ElementBase {
+    /** Direct-child panels only, so a nested accordion is not swallowed. */
+    get panels() {
+      return Array.from(this.querySelectorAll(":scope > details"));
+    }
+    /** The `<summary>` of each panel, in document order. */
+    get headers() {
+      return this.panels.map((panel) => panel.querySelector(":scope > summary")).filter(Boolean);
+    }
+    connectedCallback() {
+      if (this.initialized || !this.panels.length) return;
+      this.initialized = true;
+      this.options = Object.assign({ exclusive: false }, readOptions(this, OPTIONS));
+      this.onKeyDown = this.onKeyDown.bind(this);
+      this.onToggle = this.onToggle.bind(this);
+      this.onHashChange = this.onHashChange.bind(this);
+      if (this.options.exclusive) this.applyExclusive();
+      this.addCarets();
+      this.addEventListener("keydown", this.onKeyDown);
+      this.addEventListener("toggle", this.onToggle, true);
+      window.addEventListener("hashchange", this.onHashChange);
+      this.openFromHash();
+    }
+    disconnectedCallback() {
+      if (!this.initialized) return;
+      this.removeEventListener("keydown", this.onKeyDown);
+      this.removeEventListener("toggle", this.onToggle, true);
+      window.removeEventListener("hashchange", this.onHashChange);
+      this.initialized = false;
+    }
+    /**
+     * Give every panel the same `name`, which is what makes native `<details>`
+     * mutually exclusive.
+     */
+    applyExclusive() {
+      const panels = this.panels;
+      let seenOpen = false;
+      for (const panel of panels) {
+        if (!panel.open) continue;
+        if (seenOpen) panel.open = false;
+        seenOpen = true;
+      }
+      if (!this.groupName) {
+        this.groupName = this.getAttribute("name") || "accordion-elemental-" + ++groupCount;
+      }
+      for (const panel of panels) panel.name = this.groupName;
+    }
+    /**
+     * Append the caret to every header that has not got one, so authors write
+     * plain `<summary>` and still get a marker. Writing the span yourself is
+     * respected and left alone - that is also how you keep the caret without
+     * JavaScript.
+     */
+    addCarets() {
+      for (const header of this.headers) {
+        if (header.querySelector(":scope > ." + CARET_CLASS)) continue;
+        header.insertAdjacentHTML("beforeend", CARET);
+      }
+    }
+    onKeyDown(e) {
+      const summary = e.target.closest && e.target.closest("summary");
+      if (!summary) return;
+      const headers = this.headers;
+      const current = headers.indexOf(summary);
+      if (current === -1) return;
+      const next = nextIndex(current, e.key, headers.length);
+      if (next === null) return;
+      e.preventDefault();
+      headers[next].focus();
+    }
+    onToggle(e) {
+      const panel = e.target;
+      if (!this.panels.includes(panel)) return;
+      this.dispatchEvent(new CustomEvent("accordion-toggle", {
+        bubbles: true,
+        detail: { panel, open: panel.open }
+      }));
+    }
+    onHashChange() {
+      this.openFromHash();
+    }
+    /**
+     * Open the panel containing the element the URL fragment points at, so a link
+     * to a single question lands on it opened.
+     *
+     * ponytail: Chrome already auto-expands `<details>` on fragment navigation;
+     * this covers the browsers that do not. Drop it once that is everywhere.
+     */
+    openFromHash() {
+      const id = decodeURIComponent(window.location.hash.slice(1));
+      if (!id) return;
+      const target = document.getElementById(id);
+      if (!target || !this.contains(target)) return;
+      let panel = target.closest("details");
+      while (panel && this.contains(panel)) {
+        panel.open = true;
+        panel = panel.parentElement && panel.parentElement.closest("details");
+      }
+    }
+  };
+  define("accordion-elemental", AccordionElemental);
+})();
+//# sourceMappingURL=accordion.js.map

package/dist/elementals/accordion.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/core.js", "../../src/elementals/accordion/index.js"],
+  "sourcesContent": ["/**\n * Shared plumbing for every element in the book. Deliberately three small\n * functions and no base class - a base class would have to guess at a lifecycle\n * before there are enough elements to know what the lifecycle is.\n */\n\n// Fall back to a plain base when HTMLElement is absent (e.g. Node under test),\n// so element modules stay importable outside the browser.\nexport const ElementBase = typeof HTMLElement !== 'undefined' ? HTMLElement : class {};\n\n/**\n * Read options off an element's attributes, accepting bare, `data-*` and\n * kebab-case forms. `data-*` wins when both are present.\n *\n * @param {HTMLElement} el\n * @param {Object<string, 'boolean'|'number'|'string'>} schema - camelCase option key to type.\n * @returns {Object} Only the options actually present on the element.\n */\nexport function readOptions(el, schema) {\n  const options = {};\n  for (const key in schema) {\n    const kebab = key.replace(/[A-Z]/g, (m) => '-' + m.toLowerCase());\n    const raw = el.dataset[key] != null ? el.dataset[key] : el.getAttribute(kebab);\n    if (raw == null) continue;\n\n    if (schema[key] === 'boolean') {\n      // A bare attribute reads as '', which means \"on\".\n      options[key] = raw !== 'false' && raw !== '0';\n    } else if (schema[key] === 'number') {\n      const num = parseFloat(raw);\n      if (!Number.isNaN(num)) options[key] = num;\n    } else {\n      options[key] = raw;\n    }\n  }\n  return options;\n}\n\n/**\n * Register a custom element - in the browser only, and only once, so the module\n * is safe to import twice or to import under Node.\n * @param {string} tag\n * @param {Function} ctor\n */\nexport function define(tag, ctor) {\n  if (typeof customElements === 'undefined' || customElements.get(tag)) return;\n  customElements.define(tag, ctor);\n}\n", "import { ElementBase, readOptions, define } from '../../core.js';\n\n/**\n * Compute the header to move focus to for a roving-arrow key press.\n * @param {number} current - Index of the currently focused header.\n * @param {string} key - KeyboardEvent.key value.\n * @param {number} length - Number of headers in the group.\n * @returns {number|null} Target index, or null if the key is unhandled.\n */\nexport function nextIndex(current, key, length) {\n  if (length === 0) return null;\n  switch (key) {\n    case 'ArrowDown':\n      return (current + 1) % length;\n    case 'ArrowUp':\n      return (current - 1 + length) % length;\n    case 'Home':\n      return 0;\n    case 'End':\n      return length - 1;\n    default:\n      return null;\n  }\n}\n\nconst OPTIONS = { exclusive: 'boolean' };\n\n// Monotonic counter for generating unique `name` values for exclusive groups.\nlet groupCount = 0;\n\n/**\n * `<accordion-elemental>` custom element.\n *\n * A thin coordinator over native `<details>`/`<summary>` rather than a\n * reimplementation of the APG Accordion pattern. Native already provides the\n * disclosure semantics, Enter/Space activation, screen-reader announcement and\n * find-in-page expansion. This element only adds what native leaves out:\n *\n * - `exclusive`: assigns a shared `name` so only one panel stays open\n * - arrow/Home/End navigation between headers (APG accordion, optional but recommended)\n * - opening the panel that contains the current URL fragment\n * - an `accordion-toggle` event on the group, since `toggle` does not bubble\n *\n * Light DOM, no shadow root, so every part stays stylable by the page author.\n *\n * @see https://www.w3.org/WAI/ARIA/apg/patterns/accordion/\n */\nexport class AccordionElemental extends ElementBase {\n  /** Direct-child panels only, so a nested accordion is not swallowed. */\n  get panels() {\n    return Array.from(this.querySelectorAll(':scope > details'));\n  }\n\n  /** The `<summary>` of each panel, in document order. */\n  get headers() {\n    return this.panels\n      .map((panel) => panel.querySelector(':scope > summary'))\n      .filter(Boolean);\n  }\n\n  connectedCallback() {\n    // Wait until the light-DOM panels have been parsed. The bundle is loaded\n    // deferred or at the end of the body, so by upgrade time they are there.\n    if (this.initialized || !this.panels.length) return;\n    this.initialized = true;\n\n    this.options = Object.assign({ exclusive: false }, readOptions(this, OPTIONS));\n\n    this.onKeyDown = this.onKeyDown.bind(this);\n    this.onToggle = this.onToggle.bind(this);\n    this.onHashChange = this.onHashChange.bind(this);\n\n    if (this.options.exclusive) this.applyExclusive();\n    this.addCarets();\n\n    this.addEventListener('keydown', this.onKeyDown);\n    // `toggle` does not bubble, but non-bubbling events still run the capture\n    // phase through ancestors - so capture is how the group hears its panels.\n    this.addEventListener('toggle', this.onToggle, true);\n    window.addEventListener('hashchange', this.onHashChange);\n\n    this.openFromHash();\n  }\n\n  disconnectedCallback() {\n    if (!this.initialized) return;\n    this.removeEventListener('keydown', this.onKeyDown);\n    this.removeEventListener('toggle', this.onToggle, true);\n    window.removeEventListener('hashchange', this.onHashChange);\n    this.initialized = false;\n  }\n\n  /**\n   * Give every panel the same `name`, which is what makes native `<details>`\n   * mutually exclusive.\n   */\n  applyExclusive() {\n    const panels = this.panels;\n\n    // Close extras *before* naming them: assigning a shared name to several\n    // already-open panels leaves it to the browser which one survives. Doing it\n    // here means the first authored `open` wins, deterministically.\n    let seenOpen = false;\n    for (const panel of panels) {\n      if (!panel.open) continue;\n      if (seenOpen) panel.open = false;\n      seenOpen = true;\n    }\n\n    // Remember the generated name so moving the group in the DOM re-uses it\n    // instead of minting a new one on every reconnect.\n    if (!this.groupName) {\n      this.groupName = this.getAttribute('name') || 'accordion-elemental-' + (++groupCount);\n    }\n    for (const panel of panels) panel.name = this.groupName;\n  }\n\n  /**\n   * Append the caret to every header that has not got one, so authors write\n   * plain `<summary>` and still get a marker. Writing the span yourself is\n   * respected and left alone - that is also how you keep the caret without\n   * JavaScript.\n   */\n  addCarets() {\n    for (const header of this.headers) {\n      if (header.querySelector(':scope > .' + CARET_CLASS)) continue;\n      header.insertAdjacentHTML('beforeend', CARET);\n    }\n  }\n\n  onKeyDown(e) {\n    const summary = e.target.closest && e.target.closest('summary');\n    if (!summary) return;\n    const headers = this.headers;\n    const current = headers.indexOf(summary);\n    // -1 means the summary belongs to a nested accordion; let it handle itself.\n    if (current === -1) return;\n\n    const next = nextIndex(current, e.key, headers.length);\n    if (next === null) return;\n    e.preventDefault();\n    headers[next].focus();\n  }\n\n  onToggle(e) {\n    const panel = e.target;\n    if (!this.panels.includes(panel)) return;\n    this.dispatchEvent(new CustomEvent('accordion-toggle', {\n      bubbles: true,\n      detail: { panel: panel, open: panel.open }\n    }));\n  }\n\n  onHashChange() {\n    this.openFromHash();\n  }\n\n  /**\n   * Open the panel containing the element the URL fragment points at, so a link\n   * to a single question lands on it opened.\n   *\n   * ponytail: Chrome already auto-expands `<details>` on fragment navigation;\n   * this covers the browsers that do not. Drop it once that is everywhere.\n   */\n  openFromHash() {\n    const id = decodeURIComponent(window.location.hash.slice(1));\n    if (!id) return;\n    const target = document.getElementById(id);\n    if (!target || !this.contains(target)) return;\n\n    // Walk up so a nested panel opens its ancestors too.\n    let panel = target.closest('details');\n    while (panel && this.contains(panel)) {\n      panel.open = true;\n      panel = panel.parentElement && panel.parentElement.closest('details');\n    }\n  }\n}\n\ndefine('accordion-elemental', AccordionElemental);\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/elementals/accordion.min.css

@@ -0,0 +1,2 @@
+/* book-of-elementals v0.1.0 | https://stamat.github.io/book-of-elementals/ | MIT License */
+:root{--accordion-elemental-duration: .25s;--accordion-elemental-easing: ease}accordion-elemental{display:block}accordion-elemental>details{interpolate-size:allow-keywords}accordion-elemental>details>summary{cursor:pointer}accordion-elemental>details::details-content{block-size:0;overflow:hidden;transition:block-size var(--accordion-elemental-duration) var(--accordion-elemental-easing),content-visibility var(--accordion-elemental-duration) var(--accordion-elemental-easing) allow-discrete}accordion-elemental>details[open]::details-content{block-size:auto}@media(prefers-reduced-motion:reduce){accordion-elemental>details::details-content{transition:none}}

package/dist/elementals/accordion.min.js

@@ -0,0 +1,2 @@
+/* book-of-elementals v0.1.0 | https://stamat.github.io/book-of-elementals/ | MIT License */
+(()=>{var r=typeof HTMLElement<"u"?HTMLElement:class{};function l(e,n){const t={};for(const s in n){const i=s.replace(/[A-Z]/g,a=>"-"+a.toLowerCase()),o=e.dataset[s]!=null?e.dataset[s]:e.getAttribute(i);if(o!=null)if(n[s]==="boolean")t[s]=o!=="false"&&o!=="0";else if(n[s]==="number"){const a=parseFloat(o);Number.isNaN(a)||(t[s]=a)}else t[s]=o}return t}function c(e,n){typeof customElements>"u"||customElements.get(e)||customElements.define(e,n)}function h(e,n,t){if(t===0)return null;switch(n){case"ArrowDown":return(e+1)%t;case"ArrowUp":return(e-1+t)%t;case"Home":return 0;case"End":return t-1;default:return null}}var u={exclusive:"boolean"},d=0,f=class extends r{get panels(){return Array.from(this.querySelectorAll(":scope > details"))}get headers(){return this.panels.map(e=>e.querySelector(":scope > summary")).filter(Boolean)}connectedCallback(){this.initialized||!this.panels.length||(this.initialized=!0,this.options=Object.assign({exclusive:!1},l(this,u)),this.onKeyDown=this.onKeyDown.bind(this),this.onToggle=this.onToggle.bind(this),this.onHashChange=this.onHashChange.bind(this),this.options.exclusive&&this.applyExclusive(),this.addCarets(),this.addEventListener("keydown",this.onKeyDown),this.addEventListener("toggle",this.onToggle,!0),window.addEventListener("hashchange",this.onHashChange),this.openFromHash())}disconnectedCallback(){this.initialized&&(this.removeEventListener("keydown",this.onKeyDown),this.removeEventListener("toggle",this.onToggle,!0),window.removeEventListener("hashchange",this.onHashChange),this.initialized=!1)}applyExclusive(){const e=this.panels;let n=!1;for(const t of e)t.open&&(n&&(t.open=!1),n=!0);this.groupName||(this.groupName=this.getAttribute("name")||"accordion-elemental-"+ ++d);for(const t of e)t.name=this.groupName}addCarets(){for(const e of this.headers)e.querySelector(":scope > ."+CARET_CLASS)||e.insertAdjacentHTML("beforeend",CARET)}onKeyDown(e){const n=e.target.closest&&e.target.closest("summary");if(!n)return;const t=this.headers,s=t.indexOf(n);if(s===-1)return;const i=h(s,e.key,t.length);i!==null&&(e.preventDefault(),t[i].focus())}onToggle(e){const n=e.target;this.panels.includes(n)&&this.dispatchEvent(new CustomEvent("accordion-toggle",{bubbles:!0,detail:{panel:n,open:n.open}}))}onHashChange(){this.openFromHash()}openFromHash(){const e=decodeURIComponent(window.location.hash.slice(1));if(!e)return;const n=document.getElementById(e);if(!n||!this.contains(n))return;let t=n.closest("details");for(;t&&this.contains(t);)t.open=!0,t=t.parentElement&&t.parentElement.closest("details")}};c("accordion-elemental",f)})();

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "book-of-elementals",
+  "version": "0.1.0",
+  "description": "📓 Stamat's Book of Elementals — custom elements, accessible, dependency-free, light DOM.",
+  "type": "module",
+  "main": "src/index.js",
+  "style": "src/styles/index.scss",
+  "exports": {
+    ".": "./src/index.js",
+    "./core": "./src/core.js",
+    "./accordion": "./src/elementals/accordion/index.js",
+    "./accordion/style.scss": "./src/elementals/accordion/index.scss",
+    "./accordion/style.css": "./dist/elementals/accordion.css",
+    "./styles/*": "./src/styles/*",
+    "./dist/*": "./dist/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src/core.js",
+    "src/index.js",
+    "src/iife.js",
+    "src/elementals",
+    "src/styles/index.scss",
+    "dist",
+    "!src/**/*.test.js"
+  ],
+  "homepage": "https://stamat.github.io/book-of-elementals/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stamat/book-of-elementals.git"
+  },
+  "keywords": [
+    "custom-elements",
+    "web-components",
+    "accessibility",
+    "a11y",
+    "aria",
+    "apg",
+    "accordion",
+    "details",
+    "javascript",
+    "esm"
+  ],
+  "author": "Nikola Stamatovic <@stamat>",
+  "contributors": [],
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/stamat/book-of-elementals/issues"
+  },
+  "scripts": {
+    "dev": "poops",
+    "build": "poops -b",
+    "prepack": "poops -b",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
+    "lint": "eslint . && stylelint \"{src,docs}/**/*.scss\""
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.7.0",
+    "jest": "^30.4.2",
+    "poops": "^1.9.5",
+    "poops-docs-theme": "^1.1.2",
+    "stylelint": "^17.14.1",
+    "stylelint-config-standard-scss": "^17.0.0"
+  }
+}

package/src/core.js

@@ -0,0 +1,48 @@
+/**
+ * Shared plumbing for every element in the book. Deliberately three small
+ * functions and no base class - a base class would have to guess at a lifecycle
+ * before there are enough elements to know what the lifecycle is.
+ */
+
+// Fall back to a plain base when HTMLElement is absent (e.g. Node under test),
+// so element modules stay importable outside the browser.
+export const ElementBase = typeof HTMLElement !== 'undefined' ? HTMLElement : class {};
+
+/**
+ * Read options off an element's attributes, accepting bare, `data-*` and
+ * kebab-case forms. `data-*` wins when both are present.
+ *
+ * @param {HTMLElement} el
+ * @param {Object<string, 'boolean'|'number'|'string'>} schema - camelCase option key to type.
+ * @returns {Object} Only the options actually present on the element.
+ */
+export function readOptions(el, schema) {
+  const options = {};
+  for (const key in schema) {
+    const kebab = key.replace(/[A-Z]/g, (m) => '-' + m.toLowerCase());
+    const raw = el.dataset[key] != null ? el.dataset[key] : el.getAttribute(kebab);
+    if (raw == null) continue;
+
+    if (schema[key] === 'boolean') {
+      // A bare attribute reads as '', which means "on".
+      options[key] = raw !== 'false' && raw !== '0';
+    } else if (schema[key] === 'number') {
+      const num = parseFloat(raw);
+      if (!Number.isNaN(num)) options[key] = num;
+    } else {
+      options[key] = raw;
+    }
+  }
+  return options;
+}
+
+/**
+ * Register a custom element - in the browser only, and only once, so the module
+ * is safe to import twice or to import under Node.
+ * @param {string} tag
+ * @param {Function} ctor
+ */
+export function define(tag, ctor) {
+  if (typeof customElements === 'undefined' || customElements.get(tag)) return;
+  customElements.define(tag, ctor);
+}

package/src/elementals/accordion/index.js

@@ -0,0 +1,180 @@
+import { ElementBase, readOptions, define } from '../../core.js';
+
+/**
+ * Compute the header to move focus to for a roving-arrow key press.
+ * @param {number} current - Index of the currently focused header.
+ * @param {string} key - KeyboardEvent.key value.
+ * @param {number} length - Number of headers in the group.
+ * @returns {number|null} Target index, or null if the key is unhandled.
+ */
+export function nextIndex(current, key, length) {
+  if (length === 0) return null;
+  switch (key) {
+    case 'ArrowDown':
+      return (current + 1) % length;
+    case 'ArrowUp':
+      return (current - 1 + length) % length;
+    case 'Home':
+      return 0;
+    case 'End':
+      return length - 1;
+    default:
+      return null;
+  }
+}
+
+const OPTIONS = { exclusive: 'boolean' };
+
+// Monotonic counter for generating unique `name` values for exclusive groups.
+let groupCount = 0;
+
+/**
+ * `<accordion-elemental>` custom element.
+ *
+ * A thin coordinator over native `<details>`/`<summary>` rather than a
+ * reimplementation of the APG Accordion pattern. Native already provides the
+ * disclosure semantics, Enter/Space activation, screen-reader announcement and
+ * find-in-page expansion. This element only adds what native leaves out:
+ *
+ * - `exclusive`: assigns a shared `name` so only one panel stays open
+ * - arrow/Home/End navigation between headers (APG accordion, optional but recommended)
+ * - opening the panel that contains the current URL fragment
+ * - an `accordion-toggle` event on the group, since `toggle` does not bubble
+ *
+ * Light DOM, no shadow root, so every part stays stylable by the page author.
+ *
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/accordion/
+ */
+export class AccordionElemental extends ElementBase {
+  /** Direct-child panels only, so a nested accordion is not swallowed. */
+  get panels() {
+    return Array.from(this.querySelectorAll(':scope > details'));
+  }
+
+  /** The `<summary>` of each panel, in document order. */
+  get headers() {
+    return this.panels
+      .map((panel) => panel.querySelector(':scope > summary'))
+      .filter(Boolean);
+  }
+
+  connectedCallback() {
+    // Wait until the light-DOM panels have been parsed. The bundle is loaded
+    // deferred or at the end of the body, so by upgrade time they are there.
+    if (this.initialized || !this.panels.length) return;
+    this.initialized = true;
+
+    this.options = Object.assign({ exclusive: false }, readOptions(this, OPTIONS));
+
+    this.onKeyDown = this.onKeyDown.bind(this);
+    this.onToggle = this.onToggle.bind(this);
+    this.onHashChange = this.onHashChange.bind(this);
+
+    if (this.options.exclusive) this.applyExclusive();
+    this.addCarets();
+
+    this.addEventListener('keydown', this.onKeyDown);
+    // `toggle` does not bubble, but non-bubbling events still run the capture
+    // phase through ancestors - so capture is how the group hears its panels.
+    this.addEventListener('toggle', this.onToggle, true);
+    window.addEventListener('hashchange', this.onHashChange);
+
+    this.openFromHash();
+  }
+
+  disconnectedCallback() {
+    if (!this.initialized) return;
+    this.removeEventListener('keydown', this.onKeyDown);
+    this.removeEventListener('toggle', this.onToggle, true);
+    window.removeEventListener('hashchange', this.onHashChange);
+    this.initialized = false;
+  }
+
+  /**
+   * Give every panel the same `name`, which is what makes native `<details>`
+   * mutually exclusive.
+   */
+  applyExclusive() {
+    const panels = this.panels;
+
+    // Close extras *before* naming them: assigning a shared name to several
+    // already-open panels leaves it to the browser which one survives. Doing it
+    // here means the first authored `open` wins, deterministically.
+    let seenOpen = false;
+    for (const panel of panels) {
+      if (!panel.open) continue;
+      if (seenOpen) panel.open = false;
+      seenOpen = true;
+    }
+
+    // Remember the generated name so moving the group in the DOM re-uses it
+    // instead of minting a new one on every reconnect.
+    if (!this.groupName) {
+      this.groupName = this.getAttribute('name') || 'accordion-elemental-' + (++groupCount);
+    }
+    for (const panel of panels) panel.name = this.groupName;
+  }
+
+  /**
+   * Append the caret to every header that has not got one, so authors write
+   * plain `<summary>` and still get a marker. Writing the span yourself is
+   * respected and left alone - that is also how you keep the caret without
+   * JavaScript.
+   */
+  addCarets() {
+    for (const header of this.headers) {
+      if (header.querySelector(':scope > .' + CARET_CLASS)) continue;
+      header.insertAdjacentHTML('beforeend', CARET);
+    }
+  }
+
+  onKeyDown(e) {
+    const summary = e.target.closest && e.target.closest('summary');
+    if (!summary) return;
+    const headers = this.headers;
+    const current = headers.indexOf(summary);
+    // -1 means the summary belongs to a nested accordion; let it handle itself.
+    if (current === -1) return;
+
+    const next = nextIndex(current, e.key, headers.length);
+    if (next === null) return;
+    e.preventDefault();
+    headers[next].focus();
+  }
+
+  onToggle(e) {
+    const panel = e.target;
+    if (!this.panels.includes(panel)) return;
+    this.dispatchEvent(new CustomEvent('accordion-toggle', {
+      bubbles: true,
+      detail: { panel: panel, open: panel.open }
+    }));
+  }
+
+  onHashChange() {
+    this.openFromHash();
+  }
+
+  /**
+   * Open the panel containing the element the URL fragment points at, so a link
+   * to a single question lands on it opened.
+   *
+   * ponytail: Chrome already auto-expands `<details>` on fragment navigation;
+   * this covers the browsers that do not. Drop it once that is everywhere.
+   */
+  openFromHash() {
+    const id = decodeURIComponent(window.location.hash.slice(1));
+    if (!id) return;
+    const target = document.getElementById(id);
+    if (!target || !this.contains(target)) return;
+
+    // Walk up so a nested panel opens its ancestors too.
+    let panel = target.closest('details');
+    while (panel && this.contains(panel)) {
+      panel.open = true;
+      panel = panel.parentElement && panel.parentElement.closest('details');
+    }
+  }
+}
+
+define('accordion-elemental', AccordionElemental);

package/src/elementals/accordion/index.scss

@@ -0,0 +1,39 @@
+:root {
+  --accordion-elemental-duration: 250ms;
+  --accordion-elemental-easing: ease;
+}
+
+accordion-elemental {
+  display: block;
+
+  > details {
+    // Lets `block-size` animate to and from the `auto` keyword. Scoped here
+    // rather than on :root so the library does not change how the whole page
+    // interpolates sizes.
+    interpolate-size: allow-keywords;
+  }
+
+  > details > summary {
+    cursor: pointer;
+  }
+
+  // Open/close animation. Browsers without ::details-content drop this rule and
+  // fall back to native instant toggling, which is correct, just unanimated.
+  > details::details-content {
+    block-size: 0;
+    overflow: hidden;
+    transition:
+      block-size var(--accordion-elemental-duration) var(--accordion-elemental-easing),
+      content-visibility var(--accordion-elemental-duration) var(--accordion-elemental-easing) allow-discrete;
+  }
+
+  > details[open]::details-content {
+    block-size: auto;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    > details::details-content {
+      transition: none;
+    }
+  }
+}

package/src/iife.js

@@ -0,0 +1,6 @@
+// The "whole book" script-tag build. Importing an element module registers it,
+// so including this file is all there is to it - nothing lands on `window` and
+// there is no instantiation call, because there is no API to call.
+//
+// For one element, include its own bundle instead: dist/elementals/accordion.min.js
+import './elementals/accordion/index.js';

package/src/index.js

@@ -0,0 +1,4 @@
+// The "give me everything" entry: importing it registers every element in the
+// book. Import a subpath (`book-of-elementals/accordion`) to register just one.
+export * from './core.js';
+export * from './elementals/accordion/index.js';

package/src/styles/index.scss

@@ -0,0 +1,3 @@
+// Every element's styles. Import one component's stylesheet directly
+// (`book-of-elementals/accordion/style.scss`) to avoid paying for the rest.
+@use "../elementals/accordion";