@y14e/disclosure-css 1.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yusuke Kamiyamane
+
+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,62 @@
+# Disclosure (CSS)
+
+WAI-ARIA compliant [disclosure](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/) pattern implementation in TypeScript. Using the `<details>` and `<summary>` element.
+
+## Install
+
+```bash
+npm i @y14e/disclosure-css
+```
+
+```ts
+// npm
+import Disclosure from '@y14e/disclosure-css';
+
+// CDNs
+import Disclosure from 'https://esm.sh/@y14e/disclosure-css'
+// or
+import Disclosure from 'https://cdn.jsdelivr.net/npm/@y14e/disclosure-css/+esm';
+// or
+import Disclosure from 'https://unpkg.com/@y14e/disclosure-css/dist/index.js';
+```
+
+## Usage
+
+```ts
+new Disclosure(root);
+// => Disclosure
+
+```
+
+## 📦 APIs
+
+### `open`
+
+```ts
+disclosure.open(details);
+// => void
+//
+// details: HTMLDetailsElement
+```
+
+### `close`
+
+```ts
+disclosure.close(details);
+// => void
+//
+// details: HTMLDetailsElement
+```
+
+### `destroy`
+
+Destroys the instance and cleans up all event listeners.
+
+```ts
+disclosure.destroy();
+// => void
+```
+
+## Demo
+
+- https://y14e.github.io/disclosure-css/

package/dist/index.cjs

@@ -0,0 +1,172 @@
+'use strict';
+
+// src/index.ts
+var Disclosure = class {
+  #rootElement;
+  #detailsElements;
+  #summaryElements;
+  #contentElements;
+  #bindings = /* @__PURE__ */ new WeakMap();
+  #controller = null;
+  #isDestroyed = false;
+  constructor(root) {
+    if (!(root instanceof HTMLElement)) {
+      throw new TypeError("Invalid root element");
+    }
+    if (root.hasAttribute("data-disclosure-initialized")) {
+      console.warn("Already initialized");
+      return;
+    }
+    this.#rootElement = root;
+    const NOT_NESTED = ":not(:scope summary + * *)";
+    this.#detailsElements = [
+      ...this.#rootElement.querySelectorAll(
+        `details${NOT_NESTED}`
+      )
+    ];
+    if (!this.#detailsElements.length) {
+      console.warn("Missing <details> elements");
+      return;
+    }
+    this.#summaryElements = [
+      ...this.#rootElement.querySelectorAll(
+        `summary${NOT_NESTED}`
+      )
+    ];
+    if (!this.#summaryElements.length) {
+      console.warn("Missing <summary> elements");
+      return;
+    }
+    this.#contentElements = [
+      ...this.#rootElement.querySelectorAll(
+        `summary${NOT_NESTED} + *`
+      )
+    ];
+    if (!this.#contentElements.length) {
+      console.warn("Missing content elements");
+      return;
+    }
+    this.#detailsElements.forEach((details, i) => {
+      const summary = this.#summaryElements[i];
+      const content = this.#contentElements[i];
+      if (!summary || !content) {
+        return;
+      }
+      const binding = createBinding(details, summary, content);
+      this.#bindings.set(details, binding);
+      this.#bindings.set(summary, binding);
+      this.#bindings.set(content, binding);
+    });
+    this.#initialize();
+  }
+  open(details) {
+    if (this.#isDestroyed) {
+      return;
+    }
+    if (!(details instanceof HTMLDetailsElement) || !this.#bindings.has(details)) {
+      console.warn("Invalid <details> element");
+      return;
+    }
+    this.#toggle(details, true);
+  }
+  close(details) {
+    if (this.#isDestroyed) {
+      return;
+    }
+    if (!(details instanceof HTMLDetailsElement) || !this.#bindings.has(details)) {
+      console.warn("Invalid <details> element");
+      return;
+    }
+    this.#toggle(details, false);
+  }
+  destroy() {
+    if (this.#isDestroyed) {
+      return;
+    }
+    this.#isDestroyed = true;
+    this.#controller?.abort();
+    this.#controller = null;
+    this.#detailsElements.length = 0;
+    this.#summaryElements.length = 0;
+    this.#contentElements.length = 0;
+    this.#rootElement.removeAttribute("data-disclosure-initialized");
+  }
+  #initialize() {
+    this.#controller = new AbortController();
+    const { signal } = this.#controller;
+    this.#detailsElements.forEach((details, i) => {
+      const summary = this.#summaryElements[i];
+      if (!summary) {
+        return;
+      }
+      if (!isFocusable(details)) {
+        summary.setAttribute("aria-disabled", "true");
+        summary.setAttribute("tabindex", "-1");
+        summary.style.setProperty("pointer-events", "none");
+      }
+      summary.addEventListener("keydown", this.#onSummaryKeyDown, { signal });
+    });
+    this.#rootElement.setAttribute("data-disclosure-initialized", "");
+  }
+  #onSummaryKeyDown = (event) => {
+    const { key } = event;
+    if (!["End", "Home", "ArrowUp", "ArrowDown"].includes(key)) {
+      return;
+    }
+    event.preventDefault();
+    event.stopPropagation();
+    const focusables = this.#summaryElements.filter(isFocusable);
+    const active = getActiveElement();
+    if (!(active instanceof HTMLElement)) {
+      return;
+    }
+    const currentIndex = focusables.indexOf(active);
+    let newIndex = currentIndex;
+    switch (key) {
+      case "End":
+        newIndex = -1;
+        break;
+      case "Home":
+        newIndex = 0;
+        break;
+      case "ArrowUp":
+        newIndex = currentIndex - 1;
+        break;
+      case "ArrowDown":
+        newIndex = (currentIndex + 1) % focusables.length;
+        break;
+    }
+    focusables.at(newIndex)?.focus();
+  };
+  #toggle(details, isOpen) {
+    if (details.open !== isOpen) {
+      details.open = isOpen;
+    }
+  }
+};
+function createBinding(details, summary, content) {
+  return { details, summary, content };
+}
+function getActiveElement() {
+  let current = document.activeElement;
+  while (current?.shadowRoot?.activeElement) {
+    current = current.shadowRoot.activeElement;
+  }
+  return current;
+}
+function isFocusable(element) {
+  return element.tabIndex >= 0;
+}
+/**
+ * Disclosure (CSS)
+ * WAI-ARIA compliant disclosure pattern implementation in TypeScript.
+ * Using the <details> and <summary> element.
+ *
+ * @version 1.2.2
+ * @author Yusuke Kamiyamane
+ * @license MIT
+ * @copyright Copyright (c) Yusuke Kamiyamane
+ * @see {@link https://github.com/y14e/disclosure-css}
+ */
+
+module.exports = Disclosure;

package/dist/index.d.cts

@@ -0,0 +1,20 @@
+/**
+ * Disclosure (CSS)
+ * WAI-ARIA compliant disclosure pattern implementation in TypeScript.
+ * Using the <details> and <summary> element.
+ *
+ * @version 1.2.2
+ * @author Yusuke Kamiyamane
+ * @license MIT
+ * @copyright Copyright (c) Yusuke Kamiyamane
+ * @see {@link https://github.com/y14e/disclosure-css}
+ */
+declare class Disclosure {
+    #private;
+    constructor(root: HTMLElement);
+    open(details: HTMLDetailsElement): void;
+    close(details: HTMLDetailsElement): void;
+    destroy(): void;
+}
+
+export { Disclosure as default };

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Disclosure (CSS)
+ * WAI-ARIA compliant disclosure pattern implementation in TypeScript.
+ * Using the <details> and <summary> element.
+ *
+ * @version 1.2.2
+ * @author Yusuke Kamiyamane
+ * @license MIT
+ * @copyright Copyright (c) Yusuke Kamiyamane
+ * @see {@link https://github.com/y14e/disclosure-css}
+ */
+declare class Disclosure {
+    #private;
+    constructor(root: HTMLElement);
+    open(details: HTMLDetailsElement): void;
+    close(details: HTMLDetailsElement): void;
+    destroy(): void;
+}
+
+export { Disclosure as default };

package/dist/index.js

@@ -0,0 +1,170 @@
+// src/index.ts
+var Disclosure = class {
+  #rootElement;
+  #detailsElements;
+  #summaryElements;
+  #contentElements;
+  #bindings = /* @__PURE__ */ new WeakMap();
+  #controller = null;
+  #isDestroyed = false;
+  constructor(root) {
+    if (!(root instanceof HTMLElement)) {
+      throw new TypeError("Invalid root element");
+    }
+    if (root.hasAttribute("data-disclosure-initialized")) {
+      console.warn("Already initialized");
+      return;
+    }
+    this.#rootElement = root;
+    const NOT_NESTED = ":not(:scope summary + * *)";
+    this.#detailsElements = [
+      ...this.#rootElement.querySelectorAll(
+        `details${NOT_NESTED}`
+      )
+    ];
+    if (!this.#detailsElements.length) {
+      console.warn("Missing <details> elements");
+      return;
+    }
+    this.#summaryElements = [
+      ...this.#rootElement.querySelectorAll(
+        `summary${NOT_NESTED}`
+      )
+    ];
+    if (!this.#summaryElements.length) {
+      console.warn("Missing <summary> elements");
+      return;
+    }
+    this.#contentElements = [
+      ...this.#rootElement.querySelectorAll(
+        `summary${NOT_NESTED} + *`
+      )
+    ];
+    if (!this.#contentElements.length) {
+      console.warn("Missing content elements");
+      return;
+    }
+    this.#detailsElements.forEach((details, i) => {
+      const summary = this.#summaryElements[i];
+      const content = this.#contentElements[i];
+      if (!summary || !content) {
+        return;
+      }
+      const binding = createBinding(details, summary, content);
+      this.#bindings.set(details, binding);
+      this.#bindings.set(summary, binding);
+      this.#bindings.set(content, binding);
+    });
+    this.#initialize();
+  }
+  open(details) {
+    if (this.#isDestroyed) {
+      return;
+    }
+    if (!(details instanceof HTMLDetailsElement) || !this.#bindings.has(details)) {
+      console.warn("Invalid <details> element");
+      return;
+    }
+    this.#toggle(details, true);
+  }
+  close(details) {
+    if (this.#isDestroyed) {
+      return;
+    }
+    if (!(details instanceof HTMLDetailsElement) || !this.#bindings.has(details)) {
+      console.warn("Invalid <details> element");
+      return;
+    }
+    this.#toggle(details, false);
+  }
+  destroy() {
+    if (this.#isDestroyed) {
+      return;
+    }
+    this.#isDestroyed = true;
+    this.#controller?.abort();
+    this.#controller = null;
+    this.#detailsElements.length = 0;
+    this.#summaryElements.length = 0;
+    this.#contentElements.length = 0;
+    this.#rootElement.removeAttribute("data-disclosure-initialized");
+  }
+  #initialize() {
+    this.#controller = new AbortController();
+    const { signal } = this.#controller;
+    this.#detailsElements.forEach((details, i) => {
+      const summary = this.#summaryElements[i];
+      if (!summary) {
+        return;
+      }
+      if (!isFocusable(details)) {
+        summary.setAttribute("aria-disabled", "true");
+        summary.setAttribute("tabindex", "-1");
+        summary.style.setProperty("pointer-events", "none");
+      }
+      summary.addEventListener("keydown", this.#onSummaryKeyDown, { signal });
+    });
+    this.#rootElement.setAttribute("data-disclosure-initialized", "");
+  }
+  #onSummaryKeyDown = (event) => {
+    const { key } = event;
+    if (!["End", "Home", "ArrowUp", "ArrowDown"].includes(key)) {
+      return;
+    }
+    event.preventDefault();
+    event.stopPropagation();
+    const focusables = this.#summaryElements.filter(isFocusable);
+    const active = getActiveElement();
+    if (!(active instanceof HTMLElement)) {
+      return;
+    }
+    const currentIndex = focusables.indexOf(active);
+    let newIndex = currentIndex;
+    switch (key) {
+      case "End":
+        newIndex = -1;
+        break;
+      case "Home":
+        newIndex = 0;
+        break;
+      case "ArrowUp":
+        newIndex = currentIndex - 1;
+        break;
+      case "ArrowDown":
+        newIndex = (currentIndex + 1) % focusables.length;
+        break;
+    }
+    focusables.at(newIndex)?.focus();
+  };
+  #toggle(details, isOpen) {
+    if (details.open !== isOpen) {
+      details.open = isOpen;
+    }
+  }
+};
+function createBinding(details, summary, content) {
+  return { details, summary, content };
+}
+function getActiveElement() {
+  let current = document.activeElement;
+  while (current?.shadowRoot?.activeElement) {
+    current = current.shadowRoot.activeElement;
+  }
+  return current;
+}
+function isFocusable(element) {
+  return element.tabIndex >= 0;
+}
+/**
+ * Disclosure (CSS)
+ * WAI-ARIA compliant disclosure pattern implementation in TypeScript.
+ * Using the <details> and <summary> element.
+ *
+ * @version 1.2.2
+ * @author Yusuke Kamiyamane
+ * @license MIT
+ * @copyright Copyright (c) Yusuke Kamiyamane
+ * @see {@link https://github.com/y14e/disclosure-css}
+ */
+
+export { Disclosure as default };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@y14e/disclosure-css",
+  "version": "1.2.2",
+  "description": "WAI-ARIA compliant disclosure pattern implementation in TypeScript",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build",
+    "lint": "tsc --noEmit"
+  },
+  "keywords": [
+    "a11y",
+    "accessibility",
+    "disclosure",
+    "collapsible",
+    "component",
+    "typescript",
+    "utility"
+  ],
+  "author": "Yusuke Kamiyamane",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/y14e/disclosure-css.git"
+  },
+  "bugs": {
+    "url": "https://github.com/y14e/disclosure-css/issues"
+  },
+  "homepage": "https://github.com/y14e/disclosure-css#readme",
+  "devDependencies": {
+    "bun-types": "latest",
+    "tsup": "^8.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}