@lmfaole/basics 0.3.0 → 0.4.0

package/components/basic-accordion/index.d.ts

@@ -21,7 +21,7 @@ export function getInitialOpenAccordionIndexes(
 ): number[];
 
 /**
- * Returns the next enabled accordion trigger index, wrapping around the list
+ * Returns the next enabled accordion item index, wrapping around the list
  * when needed.
  */
 export function findNextEnabledAccordionIndex(
@@ -31,12 +31,12 @@ export function findNextEnabledAccordionIndex(
 ): number;
 
 /**
- * Custom element that upgrades existing trigger-and-panel markup into an
- * accessible accordion interface.
+ * Custom element that coordinates direct child `details` items into an
+ * accordion interface.
  *
  * Attributes:
- * - `data-multiple`: allows multiple panels to stay open
- * - `data-collapsible`: allows the last open panel in single mode to close
+ * - `data-multiple`: allows multiple items to stay open
+ * - `data-collapsible`: allows the last open item in single mode to close
  */
 export class AccordionElement extends HTMLElement {
     static observedAttributes: string[];

package/components/basic-accordion/index.js

@@ -1,22 +1,49 @@
 const ElementBase = globalThis.Element ?? class {};
 const HTMLElementBase = globalThis.HTMLElement ?? class {};
-const HTMLButtonElementBase = globalThis.HTMLButtonElement ?? class {};
+const HTMLDetailsElementBase = globalThis.HTMLDetailsElement ?? class {};
 
 export const ACCORDION_TAG_NAME = "basic-accordion";
 
-const TRIGGER_SELECTOR = "[data-accordion-trigger]";
-const PANEL_SELECTOR = "[data-accordion-panel]";
+const SUMMARY_TAG_NAME = "SUMMARY";
 
-let nextAccordionInstanceId = 1;
+function findDirectAccordionSummary(details) {
+    return Array.from(details.children).find(
+        (child) => child instanceof HTMLElementBase && child.tagName === SUMMARY_TAG_NAME,
+    ) ?? null;
+}
+
+function collectOwnedAccordionItems(root) {
+    return Array.from(root.children).flatMap((child) => {
+        if (!(child instanceof HTMLDetailsElementBase)) {
+            return [];
+        }
+
+        const summary = findDirectAccordionSummary(child);
+
+        if (!(summary instanceof HTMLElementBase)) {
+            return [];
+        }
 
-function collectOwnedElements(root, scope, selector) {
-    return Array.from(scope.querySelectorAll(selector)).filter(
-        (element) => element instanceof HTMLElementBase && element.closest(ACCORDION_TAG_NAME) === root,
-    );
+        return [{ details: child, summary }];
+    });
 }
 
-function isAccordionItemDisabled(trigger) {
-    return trigger.hasAttribute("disabled") || trigger.getAttribute("aria-disabled") === "true";
+function isAccordionItemDisabled(details) {
+    return details.hasAttribute("data-disabled")
+        || details.hasAttribute("disabled")
+        || details.getAttribute("aria-disabled") === "true";
+}
+
+function getOpenAccordionIndexes(itemStates) {
+    const openIndexes = [];
+
+    for (let index = 0; index < itemStates.length; index += 1) {
+        if (itemStates[index]?.open && !itemStates[index]?.disabled) {
+            openIndexes.push(index);
+        }
+    }
+
+    return openIndexes;
 }
 
 function findFirstEnabledAccordionIndex(itemStates) {
@@ -97,12 +124,9 @@ export function findNextEnabledAccordionIndex(itemStates, startIndex, direction)
 export class AccordionElement extends HTMLElementBase {
     static observedAttributes = ["data-collapsible", "data-multiple"];
 
-    #instanceId = `${ACCORDION_TAG_NAME}-${nextAccordionInstanceId++}`;
-    #triggers = [];
-    #panels = [];
-    #openIndexes = new Set();
-    #focusIndex = -1;
+    #items = [];
     #eventsBound = false;
+    #isSyncingState = false;
 
     connectedCallback() {
         if (!this.#eventsBound) {
@@ -115,13 +139,17 @@ export class AccordionElement extends HTMLElementBase {
     }
 
     disconnectedCallback() {
-        if (!this.#eventsBound) {
-            return;
+        if (this.#eventsBound) {
+            this.removeEventListener("click", this.#handleClick);
+            this.removeEventListener("keydown", this.#handleKeyDown);
+            this.#eventsBound = false;
         }
 
-        this.removeEventListener("click", this.#handleClick);
-        this.removeEventListener("keydown", this.#handleKeyDown);
-        this.#eventsBound = false;
+        for (const { details } of this.#items) {
+            details.removeEventListener("toggle", this.#handleToggle);
+        }
+
+        this.#items = [];
     }
 
     attributeChangedCallback() {
@@ -133,22 +161,28 @@ export class AccordionElement extends HTMLElementBase {
             return;
         }
 
-        const trigger = event.target.closest(TRIGGER_SELECTOR);
+        const summary = event.target.closest("summary");
+        const summaryIndex = this.#findSummaryIndex(summary);
 
-        if (
-            !(trigger instanceof HTMLElementBase)
-            || trigger.closest(ACCORDION_TAG_NAME) !== this
-        ) {
+        if (summaryIndex === -1) {
             return;
         }
 
-        const triggerIndex = this.#triggers.indexOf(trigger);
+        const itemStates = this.#getItemStates();
 
-        if (triggerIndex === -1) {
+        if (itemStates[summaryIndex]?.disabled) {
+            event.preventDefault();
             return;
         }
 
-        this.#toggleIndex(triggerIndex, { focus: true });
+        if (
+            !this.#isMultiple()
+            && !this.#isCollapsible()
+            && itemStates[summaryIndex]?.open
+            && getOpenAccordionIndexes(itemStates).length === 1
+        ) {
+            event.preventDefault();
+        }
     };
 
     #handleKeyDown = (event) => {
@@ -156,17 +190,9 @@ export class AccordionElement extends HTMLElementBase {
             return;
         }
 
-        const currentTrigger = event.target.closest(TRIGGER_SELECTOR);
-
-        if (
-            !(currentTrigger instanceof HTMLElementBase)
-            || currentTrigger.closest(ACCORDION_TAG_NAME) !== this
-        ) {
-            return;
-        }
-
+        const currentSummary = event.target.closest("summary");
+        const currentIndex = this.#findSummaryIndex(currentSummary);
         const itemStates = this.#getItemStates();
-        const currentIndex = this.#triggers.indexOf(currentTrigger);
         let nextIndex = -1;
 
         if (currentIndex === -1 || currentIndex >= itemStates.length) {
@@ -189,7 +215,21 @@ export class AccordionElement extends HTMLElementBase {
             case " ":
             case "Enter":
                 event.preventDefault();
-                this.#toggleIndex(currentIndex, { focus: true });
+
+                if (itemStates[currentIndex]?.disabled) {
+                    return;
+                }
+
+                if (
+                    !this.#isMultiple()
+                    && !this.#isCollapsible()
+                    && itemStates[currentIndex]?.open
+                    && getOpenAccordionIndexes(itemStates).length === 1
+                ) {
+                    return;
+                }
+
+                this.#items[currentIndex].details.open = !this.#items[currentIndex].details.open;
                 return;
             default:
                 return;
@@ -200,19 +240,30 @@ export class AccordionElement extends HTMLElementBase {
         }
 
         event.preventDefault();
-        this.#focusIndex = nextIndex;
-        this.#applyState({ focus: true });
+        this.#items[nextIndex]?.summary.focus();
     };
 
-    #getItemStates() {
-        const pairCount = Math.min(this.#triggers.length, this.#panels.length);
+    #handleToggle = (event) => {
+        if (this.#isSyncingState) {
+            return;
+        }
 
-        return this.#triggers.slice(0, pairCount).map((trigger, index) => ({
-            disabled: isAccordionItemDisabled(trigger),
-            open: trigger.hasAttribute("data-open")
-                || trigger.getAttribute("aria-expanded") === "true"
-                || this.#panels[index]?.hasAttribute("data-open"),
-        }));
+        const details = event.currentTarget;
+        const preferredIndex = this.#items.findIndex((item) => item.details === details);
+
+        if (preferredIndex === -1) {
+            return;
+        }
+
+        this.#sync({ preferredIndex });
+    };
+
+    #findSummaryIndex(summary) {
+        if (!(summary instanceof HTMLElementBase)) {
+            return -1;
+        }
+
+        return this.#items.findIndex((item) => item.summary === summary);
     }
 
     #isCollapsible() {
@@ -223,154 +274,107 @@ export class AccordionElement extends HTMLElementBase {
         return this.hasAttribute("data-multiple");
     }
 
-    #getNextFocusableIndex(itemStates) {
-        for (const openIndex of this.#openIndexes) {
-            if (!itemStates[openIndex]?.disabled) {
-                return openIndex;
+    #getItemStates({ includeDataOpen = false } = {}) {
+        return this.#items.map(({ details }) => ({
+            disabled: isAccordionItemDisabled(details),
+            open: details.hasAttribute("open")
+                || (includeDataOpen && details.hasAttribute("data-open")),
+        }));
+    }
+
+    #sync({ resetOpen = false, preferredIndex = -1 } = {}) {
+        const previousDetails = this.#items.map((item) => item.details);
+        const nextItems = collectOwnedAccordionItems(this);
+        const nextDetails = nextItems.map((item) => item.details);
+
+        for (const details of previousDetails) {
+            if (!nextDetails.includes(details)) {
+                details.removeEventListener("toggle", this.#handleToggle);
             }
         }
 
-        return findFirstEnabledAccordionIndex(itemStates);
-    }
+        for (const details of nextDetails) {
+            if (!previousDetails.includes(details)) {
+                details.addEventListener("toggle", this.#handleToggle);
+            }
+        }
 
-    #sync({ resetOpen = false } = {}) {
-        this.#triggers = collectOwnedElements(this, this, TRIGGER_SELECTOR);
-        this.#panels = collectOwnedElements(this, this, PANEL_SELECTOR);
+        this.#items = nextItems;
+        this.#normalizeOpenState({
+            itemStates: this.#getItemStates({ includeDataOpen: resetOpen }),
+            resetOpen,
+            preferredIndex,
+        });
+        this.#applyState();
+    }
 
-        const itemStates = this.#getItemStates();
+    #normalizeOpenState({ itemStates, resetOpen = false, preferredIndex = -1 }) {
+        let openIndexes = [];
 
         if (resetOpen) {
-            this.#openIndexes = new Set(
-                getInitialOpenAccordionIndexes(itemStates, {
-                    multiple: this.#isMultiple(),
-                    collapsible: this.#isCollapsible(),
-                }),
-            );
+            openIndexes = getInitialOpenAccordionIndexes(itemStates, {
+                multiple: this.#isMultiple(),
+                collapsible: this.#isCollapsible(),
+            });
+        } else if (this.#isMultiple()) {
+            openIndexes = getOpenAccordionIndexes(itemStates);
         } else {
-            const nextOpenIndexes = Array.from(this.#openIndexes).filter(
-                (index) => index >= 0 && index < itemStates.length && !itemStates[index]?.disabled,
-            );
-
-            if (!this.#isMultiple() && nextOpenIndexes.length > 1) {
-                nextOpenIndexes.splice(1);
-            }
+            openIndexes = getOpenAccordionIndexes(itemStates);
 
             if (
-                !this.#isMultiple()
-                && nextOpenIndexes.length === 0
-                && !this.#isCollapsible()
+                preferredIndex !== -1
+                && openIndexes.includes(preferredIndex)
+                && !itemStates[preferredIndex]?.disabled
             ) {
+                openIndexes = [preferredIndex];
+            } else if (openIndexes.length > 0) {
+                openIndexes = [openIndexes[0]];
+            } else if (!this.#isCollapsible()) {
                 const fallbackIndex = findFirstEnabledAccordionIndex(itemStates);
 
                 if (fallbackIndex !== -1) {
-                    nextOpenIndexes.push(fallbackIndex);
+                    openIndexes = [fallbackIndex];
                 }
             }
-
-            this.#openIndexes = new Set(nextOpenIndexes);
-        }
-
-        if (resetOpen || itemStates[this.#focusIndex]?.disabled || this.#focusIndex >= itemStates.length) {
-            this.#focusIndex = this.#getNextFocusableIndex(itemStates);
         }
 
-        this.#applyState();
-    }
+        const openIndexSet = new Set(openIndexes);
 
-    #applyState({ focus = false } = {}) {
-        const pairCount = Math.min(this.#triggers.length, this.#panels.length);
-        const baseId = this.id || this.#instanceId;
-
-        for (let index = 0; index < this.#triggers.length; index += 1) {
-            const trigger = this.#triggers[index];
-            const panel = index < pairCount ? this.#panels[index] : null;
-            const disabled = index >= pairCount || isAccordionItemDisabled(trigger);
-            const open = !disabled && this.#openIndexes.has(index);
-            const focusable = !disabled && index === this.#focusIndex;
-
-            if (!trigger.id) {
-                trigger.id = `${baseId}-trigger-${index + 1}`;
-            }
-
-            if (trigger instanceof HTMLButtonElementBase && !trigger.hasAttribute("type")) {
-                trigger.type = "button";
-            }
+        this.#isSyncingState = true;
 
-            trigger.setAttribute("aria-expanded", String(open));
-            trigger.tabIndex = focusable ? 0 : -1;
-            trigger.toggleAttribute("data-open", open);
+        try {
+            for (let index = 0; index < this.#items.length; index += 1) {
+                const details = this.#items[index].details;
+                const open = !itemStates[index]?.disabled && openIndexSet.has(index);
 
-            if (panel) {
-                if (!panel.id) {
-                    panel.id = `${baseId}-panel-${index + 1}`;
+                if (details.open !== open) {
+                    details.open = open;
                 }
-
-                trigger.setAttribute("aria-controls", panel.id);
-            } else {
-                trigger.removeAttribute("aria-controls");
-            }
-        }
-
-        for (let index = 0; index < this.#panels.length; index += 1) {
-            const panel = this.#panels[index];
-            const trigger = this.#triggers[index];
-            const open = index < pairCount
-                && !isAccordionItemDisabled(trigger)
-                && this.#openIndexes.has(index);
-
-            if (!panel.id) {
-                panel.id = `${baseId}-panel-${index + 1}`;
             }
-
-            panel.setAttribute("role", "region");
-
-            if (trigger?.id) {
-                panel.setAttribute("aria-labelledby", trigger.id);
-            } else {
-                panel.removeAttribute("aria-labelledby");
-            }
-
-            panel.hidden = !open;
-            panel.toggleAttribute("data-open", open);
-        }
-
-        if (focus && this.#focusIndex !== -1) {
-            this.#triggers[this.#focusIndex]?.focus();
+        } finally {
+            this.#isSyncingState = false;
         }
     }
 
-    #toggleIndex(index, { focus = false } = {}) {
-        const itemStates = this.#getItemStates();
+    #applyState() {
+        for (const { details, summary } of this.#items) {
+            const disabled = isAccordionItemDisabled(details);
+            const open = !disabled && details.open;
 
-        if (index < 0 || index >= itemStates.length || itemStates[index]?.disabled) {
-            return;
-        }
+            if (disabled && details.open) {
+                details.open = false;
+            }
 
-        const nextOpenIndexes = new Set(this.#openIndexes);
-        const isOpen = nextOpenIndexes.has(index);
+            details.toggleAttribute("data-open", open);
 
-        if (this.#isMultiple()) {
-            if (isOpen) {
-                nextOpenIndexes.delete(index);
+            if (disabled) {
+                summary.setAttribute("aria-disabled", "true");
+                summary.tabIndex = -1;
             } else {
-                nextOpenIndexes.add(index);
+                summary.removeAttribute("aria-disabled");
+                summary.tabIndex = 0;
             }
-        } else if (isOpen) {
-            if (!this.#isCollapsible()) {
-                this.#focusIndex = index;
-                this.#applyState({ focus });
-                return;
-            }
-
-            nextOpenIndexes.clear();
-        } else {
-            nextOpenIndexes.clear();
-            nextOpenIndexes.add(index);
         }
-
-        this.#openIndexes = nextOpenIndexes;
-        this.#focusIndex = index;
-        this.#applyState({ focus });
     }
 }
 

package/components/basic-alert/index.d.ts

@@ -0,0 +1,53 @@
+export const ALERT_TAG_NAME: "basic-alert";
+
+/**
+ * Normalizes unsupported or empty labels back to the default `"Alert"`.
+ */
+export function normalizeAlertLabel(
+    value?: string | null,
+): string;
+
+/**
+ * Normalizes unsupported live-region values back to `"assertive"`.
+ */
+export function normalizeAlertLive(
+    value?: string | null,
+): "assertive" | "polite";
+
+/**
+ * Maps an alert live setting to the matching ARIA role.
+ */
+export function getAlertRoleForLive(
+    value?: string | null,
+): "alert" | "status";
+
+/**
+ * Normalizes the optional `data-open` attribute into a boolean flag, using the
+ * current `hidden` state as a fallback.
+ */
+export function normalizeAlertOpen(
+    value?: string | null,
+    hidden?: boolean,
+): boolean;
+
+/**
+ * Custom element that upgrades inline content into a dismissible live-region
+ * alert.
+ *
+ * Attributes:
+ * - `data-label`: fallback accessible name when the alert has no title
+ * - `data-live`: chooses between `alert` and `status` semantics
+ * - `data-open`: optional managed visibility flag
+ */
+export class AlertElement extends HTMLElement {
+    static observedAttributes: string[];
+    show(): boolean;
+    hide(): boolean;
+}
+
+/**
+ * Registers the `basic-alert` custom element if it is not already defined.
+ */
+export function defineAlert(
+    registry?: CustomElementRegistry,
+): typeof AlertElement;