@agencecinq/disclosure-button 1.1.0

package/README.md

@@ -0,0 +1,198 @@
+[![](https://img.shields.io/npm/v/@agencecinq/disclosure-button)](https://www.npmjs.com/package/@agencecinq/disclosure-button)
+[![](https://img.shields.io/npm/dm/@agencecinq/disclosure-button)](https://www.npmjs.com/package/@agencecinq/disclosure-button)
+
+# @agencecinq/disclosure-button
+
+> Accessible WAI-ARIA disclosure button Web Component.
+
+A disclosure button shows or hides a section of content. `<cinq-disclosure-button>`
+wraps a trigger, wires up the `aria-expanded` / `aria-controls` relationship,
+toggles the `hidden` attribute on controlled regions, and dispatches open/close
+events.
+
+Implementation follows the
+[WAI-ARIA Authoring Practices disclosure pattern](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/).
+Inspired by [`@19h47/disclosure-button`](https://github.com/19h47/19h47-disclosure-button/).
+
+## Installation
+
+```bash
+pnpm add @agencecinq/disclosure-button
+```
+
+## Usage
+
+```js
+import '@agencecinq/disclosure-button';
+```
+
+```html
+<cinq-disclosure-button>
+  <button
+    type="button"
+    aria-expanded="false"
+    aria-controls="details-1"
+  >
+    Show more
+  </button>
+</cinq-disclosure-button>
+
+<div id="details-1" class="foo" hidden>
+  Disclosure content
+</div>
+```
+
+```css
+.foo[hidden] {
+  display: none;
+}
+
+.foo {
+  display: flex;
+}
+```
+
+### Required markup
+
+| Attribute / element | Required | Role |
+| ------------------- | -------- | ---- |
+| Inner `<button>`    | **Yes**  | Focusable trigger inside `<cinq-disclosure-button>`. |
+| `aria-expanded`     | **Yes**  | Current disclosure state on the trigger. |
+| `aria-controls`     | **Yes**  | Space-separated IDs of the controlled regions. |
+| `hidden`            | **Yes**  | Set on each controlled region in its collapsed initial state. |
+
+Use `[data-button]` instead of `<button>` when you need a different focusable
+element as the trigger.
+
+### API
+
+| Attribute | Required | Description |
+| --------- | -------- | ----------- |
+| `expanded` | No | Reflected state on the host — useful for styling the wrapper. |
+
+| Method | Description |
+| ------ | ----------- |
+| `open(emit?)` | Opens the disclosure. |
+| `close(emit?)` | Closes the disclosure. |
+| `toggle()` | Toggles open/closed. |
+| `destroy()` | Detaches listeners. |
+
+### Keyboard & focus
+
+The trigger must be a native focusable control — typically
+`<button type="button">`. Enter and Space activate the button through browser
+defaults; the component listens for `click`, which those keys dispatch on
+buttons.
+
+| Key | Function |
+| --- | -------- |
+| `Enter` | Toggle the disclosure (native button behavior). |
+| `Space` | Toggle the disclosure (native button behavior). |
+
+The component does **not** move focus into the controlled region on open, nor
+restore focus on close — focus stays on the trigger. Once open, users can tab
+into focusable elements inside the region if you include any.
+
+While collapsed, `hidden` keeps the region out of the tab order and accessibility
+tree.
+
+On `focus` / `blur`, a `.focus` class is toggled on the inner trigger:
+
+```css
+cinq-disclosure-button button.focus {
+  outline: 2px solid currentColor;
+  outline-offset: 2px;
+}
+```
+
+### One button, multiple targets
+
+`aria-controls` accepts several space-separated IDs — all matched regions open
+and close together.
+
+### Multiple buttons, one target
+
+Several triggers can share the same `aria-controls` ID. Use one
+`<cinq-disclosure-button>` per trigger — each instance listens for bubbling
+open/close events and syncs when `event.detail.elements` references a shared DOM
+node.
+
+### Programmatic API
+
+```js
+const $host = document.querySelector('cinq-disclosure-button');
+
+$host.open();
+$host.close();
+```
+
+`open()` and `close()` accept an optional `emit` argument (default `true`). Pass
+`false` to update state without dispatching an event. Linked triggers only sync
+when the event is dispatched.
+
+```js
+$openLink.addEventListener("click", () => {
+  $host.open();
+});
+
+$dismissButton.addEventListener("click", () => {
+  $host.close();
+});
+```
+
+Call `destroy()` when removing the element from the DOM to detach listeners.
+
+## Events
+
+| Event | Cancelable | Detail | Description |
+| ----- | ---------- | ------ | ----------- |
+| `disclosure-button:open` | Yes | `{ ids, elements, el }` | Fired before the disclosure opens. Cancel to abort. |
+| `disclosure-button:close` | Yes | `{ ids, elements, el }` | Fired before the disclosure closes. Cancel to abort. |
+
+```js
+import { EVENTS } from "@agencecinq/utils";
+
+$host.addEventListener(EVENTS.DISCLOSURE_BUTTON_OPEN, (event) => {
+  if (!userMayOpen()) {
+    event.preventDefault();
+  }
+});
+```
+
+`event.detail` carries `{ ids, elements, el }`.
+
+### Updating the button label
+
+The component does not change the trigger's visible text. Listen to the open/close
+events and update the label in your app — useful for Show/Hide copy, i18n, or
+custom designs:
+
+```js
+import { EVENTS } from "@agencecinq/utils";
+
+const labels = { closed: "Show details", open: "Hide details" };
+
+$button.addEventListener(EVENTS.DISCLOSURE_BUTTON_OPEN, () => {
+  $button.textContent = labels.open;
+});
+
+$button.addEventListener(EVENTS.DISCLOSURE_BUTTON_CLOSE, () => {
+  $button.textContent = labels.closed;
+});
+```
+
+### Read more / Read less
+
+Keep a short excerpt visible and hide the rest. Style the trigger as inline text
+and swap between Read more / Read less on open/close events.
+
+## Build setup
+
+```bash
+pnpm -C packages/disclosure-button build
+```
+
+## Acknowledgments
+
+- [Disclosure Pattern (WAI-ARIA Practices)](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/)
+- [`@19h47/disclosure-button`](https://github.com/19h47/19h47-disclosure-button/) — original implementation

package/dist/disclosure-button.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Disclosure button Web Component wrapping a slotted trigger.
+ *
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/
+ */
+export declare class DisclosureButton extends HTMLElement {
+    static observedAttributes: string[];
+    $button: HTMLButtonElement | null;
+    elements: HTMLElement[];
+    private controlIds;
+    private observer;
+    private reflectingAttribute;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+    get button(): HTMLButtonElement | null;
+    get expanded(): boolean;
+    toggle(): boolean;
+    close(emit?: boolean): void;
+    open(emit?: boolean): void;
+    destroy(): void;
+    private initEvents;
+    private onClick;
+    private onFocus;
+    private onBlur;
+    private onLinkedChange;
+    private get detail();
+    private isExpanded;
+    private updateExpandedFromElements;
+    private reflectExpandedAttribute;
+}
+//# sourceMappingURL=disclosure-button.d.ts.map

package/dist/disclosure-button.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disclosure-button.d.ts","sourceRoot":"","sources":["../src/disclosure-button.ts"],"names":[],"mappings":"AAiDA;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,WAAW;IAC/C,MAAM,CAAC,kBAAkB,WAAgB;IAEzC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAQ;IACzC,QAAQ,EAAE,WAAW,EAAE,CAAM;IAE7B,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,QAAQ,CAAiC;IACjD,OAAO,CAAC,mBAAmB,CAAS;IAEpC,iBAAiB,IAAI,IAAI;IA+BzB,oBAAoB,IAAI,IAAI;IAO5B,wBAAwB,CACtB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,IAAI;IAiBP,IAAI,MAAM,IAAI,iBAAiB,GAAG,IAAI,CAErC;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,MAAM,IAAI,OAAO;IAoBjB,KAAK,CAAC,IAAI,UAAO,GAAG,IAAI;IAaxB,IAAI,CAAC,IAAI,UAAO,GAAG,IAAI;IAavB,OAAO,IAAI,IAAI;IAaf,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,OAAO,CAEb;IAEF,OAAO,CAAC,OAAO,CAEb;IAEF,OAAO,CAAC,MAAM,CAEZ;IAEF,OAAO,CAAC,cAAc,CAUpB;IAEF,OAAO,KAAK,MAAM,GAEjB;IAED,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,0BAA0B;IAYlC,OAAO,CAAC,wBAAwB;CAajC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { DisclosureButton } from './disclosure-button.js';
+export { DisclosureButton };
+export type { DisclosureButtonDetail } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAC5B,YAAY,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,143 @@
+//#region ../utils/dist/index.js
+var e = {
+	DRAWER_CLOSE: "drawer-close",
+	DRAWER_OPEN: "drawer-open",
+	DRAWER_TOGGLE: "drawer-toggle",
+	MODAL_CLOSE: "modal-close",
+	MODAL_OPEN: "modal-open",
+	MODAL_TOGGLE: "modal-toggle",
+	SPINBUTTON_CHANGE: "spinbutton-change",
+	DISCLOSURE_BUTTON_OPEN: "disclosure-button:open",
+	DISCLOSURE_BUTTON_CLOSE: "disclosure-button:close",
+	TAB_BEFORE_ACTIVATE: "tab-before-activate",
+	TAB_ACTIVATE: "tab-activate",
+	TAB_DELETE: "tab-delete",
+	CART_BEFORE_ADD: "cart-before-add",
+	CART_BEFORE_UPDATE: "cart-before-update",
+	CART_UPDATE: "cart-update",
+	VARIANT_CHANGE: "variant-change"
+}, t = (e, t) => {
+	let n = null, r = null, i = () => {
+		r && e(...r), n = null;
+	};
+	return (...e) => {
+		r = e, n ||= setTimeout(i, t);
+	};
+}, n = document.documentElement, { body: r } = document;
+n.hasAttribute("data-debug");
+var i = {
+	x: 0,
+	y: 0
+};
+window.addEventListener("pointermove", t(({ x: e, y: t }) => {
+	i.x = e, i.y = t;
+}, 100), { passive: !0 }), window.matchMedia("(width >= 64rem)"), window.matchMedia("(min-width: 1280px)"), window.matchMedia("(min-width: 1440px)"), window.matchMedia("(min-width: 1920px)");
+//#endregion
+//#region src/disclosure-button.ts
+var a = (e, t, n) => e.dispatchEvent(new CustomEvent(n, {
+	bubbles: !0,
+	cancelable: !0,
+	detail: t
+})), o = (e, t) => {
+	e.hidden = !t;
+}, s = (e) => {
+	e.forEach((e) => {
+		o(e, !0);
+	});
+}, c = (e) => {
+	e.forEach((e) => {
+		o(e, !1);
+	});
+}, l = (e) => !e.hidden, u = (e) => e ? e.trim().split(/\s+/).map((e) => e.trim()).filter(Boolean) : [], d = (e, t) => e.elements.some((e) => t.includes(e)), f = class extends HTMLElement {
+	static observedAttributes = ["expanded"];
+	$button = null;
+	elements = [];
+	controlIds = [];
+	observer = null;
+	reflectingAttribute = !1;
+	connectedCallback() {
+		if (this.$button = this.querySelector("[data-button]") || this.querySelector("button"), !this.$button) throw Error("DisclosureButton: button element not found");
+		if (this.controlIds = u(this.$button.getAttribute("aria-controls")), this.controlIds.length === 0) return;
+		let e = this.controlIds.map((e) => `#${e}`).join(",");
+		this.elements = [...document.querySelectorAll(e)], this.initEvents(), this.updateExpandedFromElements(), this.observer = new MutationObserver(() => {
+			this.reflectingAttribute || this.reflectExpandedAttribute();
+		}), this.observer.observe(this.$button, {
+			attributes: !0,
+			attributeFilter: ["aria-expanded"]
+		}), this.reflectExpandedAttribute();
+	}
+	disconnectedCallback() {
+		this.destroy(), this.$button = null, this.elements = [], this.controlIds = [];
+	}
+	attributeChangedCallback(e, t, n) {
+		if (e !== "expanded" || !this.$button || this.reflectingAttribute) return;
+		let r = this.$button.getAttribute("aria-expanded") === "true";
+		if (n !== null && !r) {
+			this.open();
+			return;
+		}
+		n === null && r && this.close();
+	}
+	get button() {
+		return this.$button;
+	}
+	get expanded() {
+		return this.$button?.getAttribute("aria-expanded") === "true";
+	}
+	toggle() {
+		return this.$button ? this.isExpanded() ? a(this.$button, this.detail, e.DISCLOSURE_BUTTON_CLOSE) ? (this.close(!1), !0) : !1 : a(this.$button, this.detail, e.DISCLOSURE_BUTTON_OPEN) ? (this.open(!1), !0) : !1 : !1;
+	}
+	close(t = !0) {
+		this.$button && (t && this.isExpanded() && !a(this.$button, this.detail, e.DISCLOSURE_BUTTON_CLOSE) || (c(this.elements), this.updateExpandedFromElements()));
+	}
+	open(t = !0) {
+		this.$button && (t && !this.isExpanded() && !a(this.$button, this.detail, e.DISCLOSURE_BUTTON_OPEN) || (s(this.elements), this.updateExpandedFromElements()));
+	}
+	destroy() {
+		this.$button && (this.$button.removeEventListener("click", this.onClick), this.$button.removeEventListener("focus", this.onFocus), this.$button.removeEventListener("blur", this.onBlur), document.removeEventListener(e.DISCLOSURE_BUTTON_OPEN, this.onLinkedChange), document.removeEventListener(e.DISCLOSURE_BUTTON_CLOSE, this.onLinkedChange), this.observer?.disconnect(), this.observer = null);
+	}
+	initEvents() {
+		this.$button && (this.$button.addEventListener("click", this.onClick), this.$button.addEventListener("focus", this.onFocus), this.$button.addEventListener("blur", this.onBlur), document.addEventListener(e.DISCLOSURE_BUTTON_OPEN, this.onLinkedChange), document.addEventListener(e.DISCLOSURE_BUTTON_CLOSE, this.onLinkedChange));
+	}
+	onClick = () => {
+		this.toggle();
+	};
+	onFocus = () => {
+		this.$button?.classList.add("focus");
+	};
+	onBlur = () => {
+		this.$button?.classList.remove("focus");
+	};
+	onLinkedChange = (e) => {
+		if (!(e instanceof CustomEvent) || !this.$button) return;
+		let t = e.detail;
+		t.el !== this.$button && d(t, this.elements) && queueMicrotask(() => {
+			this.updateExpandedFromElements();
+		});
+	};
+	get detail() {
+		return {
+			ids: this.controlIds,
+			elements: this.elements,
+			el: this.$button
+		};
+	}
+	isExpanded() {
+		return this.$button?.getAttribute("aria-expanded") === "true";
+	}
+	updateExpandedFromElements() {
+		if (!this.$button) return;
+		if (this.elements.length === 0) {
+			this.$button.setAttribute("aria-expanded", "false");
+			return;
+		}
+		let e = this.elements.every((e) => l(e));
+		this.$button.setAttribute("aria-expanded", e ? "true" : "false");
+	}
+	reflectExpandedAttribute() {
+		this.$button && (this.reflectingAttribute = !0, this.$button.getAttribute("aria-expanded") === "true" ? this.setAttribute("expanded", "") : this.removeAttribute("expanded"), this.reflectingAttribute = !1);
+	}
+};
+customElements.get("cinq-disclosure-button") || customElements.define("cinq-disclosure-button", f);
+//#endregion
+export { f as DisclosureButton };

package/dist/types.d.ts

@@ -0,0 +1,8 @@
+export interface DisclosureButtonDetail {
+    /** Raw tokens from the trigger's `aria-controls` attribute. */
+    ids: string[];
+    /** Controlled elements resolved from the DOM at `init()`. */
+    elements: HTMLElement[];
+    el: HTMLElement;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,sBAAsB;IACrC,+DAA+D;IAC/D,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,6DAA6D;IAC7D,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,EAAE,EAAE,WAAW,CAAC;CACjB"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@agencecinq/disclosure-button",
+  "version": "1.1.0",
+  "description": "Accessible WAI-ARIA disclosure button Web Component.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Jérémy Levron <jeremy@agencecinq.com> (https://agencecinq.com)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agencecinq/shopify.git",
+    "directory": "packages/disclosure-button"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@agencecinq/utils": "*"
+  },
+  "devDependencies": {
+    "vite": "^8.1.3",
+    "vite-plugin-dts": "^5.0.3",
+    "@agencecinq/utils": "5.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch"
+  }
+}