feature(simulator): Add support for details/summary

accessibility-checker-engine/src/v4/simulator/SRNavigator.ts

@@ -362,6 +362,31 @@ export namespace SRNavigator {
             if (elem && elem.nodeName.toUpperCase() === "MSUP") {
                 return retVal = { skipCurrent: false, skipChildren: true };
             }
+
+            // <summary> is a self-announcing disclosure button — its children
+            // are folded into the ["label", button, collapsed] announcement,
+            // so skip traversal into them.
+            if (!cursor.isEndTag() && elem.nodeName.toUpperCase() === "SUMMARY") {
+                const detailsParent = elem.parentElement;
+                if (detailsParent && detailsParent.nodeName.toUpperCase() === "DETAILS") {
+                    return retVal = { skipCurrent: false, skipChildren: true };
+                }
+            }
+
+            // Skip non-summary children of a closed <details> element.
+            // Browsers hide those children via UA stylesheet (display:none), so
+            // they must not appear as reading stops when the widget is collapsed.
+            // Exempt the <details> element itself and <summary> (always visible).
+            if (!cursor.isEndTag()
+                && elem.nodeName.toUpperCase() !== "DETAILS"
+                && !elem.closest("summary")
+            ) {
+                const detailsAncestor = elem.closest("details");
+                if (detailsAncestor && !detailsAncestor.hasAttribute("open")) {
+                    return retVal = { skipCurrent: true, skipChildren: true };
+                }
+            }
+
             if (elem.closest(".ibma-sr-overlay")) {
                 return retVal = { skipCurrent: true, skipChildren: true };
             }

accessibility-checker-engine/src/v4/simulator/render_rules/common.ts

@@ -1329,6 +1329,45 @@ export const RULES: SRRendererRule[] = [
         ]
     }),
 
+    // Summary element — the disclosure button for a <details> widget.
+    // <summary> has implicitRole: null in ARIADefinitions so no role-based
+    // button rule fires.  We add an explicit element rule that announces it as
+    // a button with the collapsed / expanded state from the parent <details>.
+    new SRRendererRule({
+        roles: [],
+        elems: ["SUMMARY"],
+        modes: ["item", "button", "tab_focus"],
+        tests: [
+            (cursor: SRCursor, _oldCursor?: SRCursor, mode?: string) => {
+                if (cursor.isEndTag()) return "";
+                const summaryElem = cursor.getElement();
+                if (!summaryElem) return null;
+                // Only the first <summary> that is a direct child of <details>
+                // acts as the disclosure button.
+                const detailsParent = summaryElem.parentElement;
+                if (!detailsParent || detailsParent.nodeName.toUpperCase() !== "DETAILS") return null;
+                const firstSummary = Array.from(detailsParent.children).find(
+                    c => c.nodeName.toUpperCase() === "SUMMARY"
+                );
+                if (!firstSummary || !firstSummary.isSameNode(summaryElem)) return null;
+                const stateStr = detailsParent.hasAttribute("open") ? "expanded" : "collapsed";
+                // <summary> has implicitRole: null so AccNameUtil may not compute a name;
+                // read aria-label first, then fall back to visible text content.
+                const ariaLabel = summaryElem.getAttribute("aria-label")?.trim();
+                const textContent = summaryElem.textContent?.trim() || "";
+                const label = ariaLabel || textContent;
+                const labelStr = label ? `"${label}", ` : "";
+                // Description: prefer explicit aria-describedby; when aria-label is the
+                // name source, the subtree text becomes the description (accname-1.2 §4.3).
+                let descStr = getDescribedByAnnouncements(summaryElem, mode);
+                if (!descStr && ariaLabel && textContent) {
+                    descStr = mode === "item" ? `, \u0001${textContent}\u0002` : `, "${textContent}"`;
+                }
+                return `[${labelStr}button, ${stateStr}${descStr}]`;
+            }
+        ]
+    }),
+
     // Multiple roles rules - placed at the bottom
 
     // Default mode rules - Container elements (multiple roles)

accessibility-checker-engine/src/v4/simulator/render_rules/container_enter.ts

@@ -170,15 +170,26 @@ export let RULES: SRRendererRule[] = [
         modes: ["item", "region"],
         tests: [
             (cursor: SRCursor) => {
+                if (cursor.getNode().nodeName.toUpperCase() === "DETAILS") {
+                    const elem = cursor.getElement();
+                    const hasSummary = Array.from(elem.children).some(
+                        c => c.nodeName.toUpperCase() === "SUMMARY"
+                    );
+                    if (hasSummary) {
+                        // The <summary> child speaks as the disclosure button; suppress
+                        // the container-enter announcement entirely.
+                        return "";
+                    }
+                    // No explicit <summary>: in a real browser the UA injects a default
+                    // "Details" summary.  jsdom does not, so we announce the widget here
+                    // as a fallback using the same default label a real browser would use.
+                    return `["Details", button, ${elem.hasAttribute("open") ? "expanded" : "collapsed"}]`;
+                }
                 if (cursor.getNameInfo() === null) return null;
                 if (cursor.getCurrentOrParentByRoleClone(["combobox"], ["select"])?.getNode().nodeName.toUpperCase() === "SELECT") {
                     return "";
                 }
-                if (cursor.getNode().nodeName.toUpperCase() === "DETAILS") {
-                    return `[button, ${cursor.getElement().hasAttribute("open") ? "expanded": "collapsed"}]`;
-                } else {
-                    return `[grouping${quoteNamePadBefore(cursor)}]`;
-                }
+                return `[grouping${quoteNamePadBefore(cursor)}]`;
             }
         ]
     }),
@@ -190,15 +201,23 @@ export let RULES: SRRendererRule[] = [
         modes: ["tab_focus"],
         tests: [
             (cursor: SRCursor) => {
+                if (cursor.getNode().nodeName.toUpperCase() === "DETAILS") {
+                    const elem = cursor.getElement();
+                    const hasSummary = Array.from(elem.children).some(
+                        c => c.nodeName.toUpperCase() === "SUMMARY"
+                    );
+                    if (hasSummary) {
+                        // <summary> is the tab stop, not <details> itself.
+                        return null;
+                    }
+                    // No <summary>: <details> itself is focusable (UA default behaviour).
+                    return `["Details", button, ${elem.hasAttribute("open") ? "expanded" : "collapsed"}]`;
+                }
                 if (cursor.getNameInfo() === null) return null;
                 if (cursor.getCurrentOrParentByRoleClone(["combobox"], ["select"])?.getNode().nodeName.toUpperCase() === "SELECT") {
                     return "";
                 }
-                if (cursor.getNode().nodeName.toUpperCase() === "DETAILS") {
-                    return `[button, ${cursor.getElement().hasAttribute("open") ? "expanded": "collapsed"}]`;
-                } else {
-                    return ``;
-                }
+                return ``;
             }
         ]
     }),

accessibility-checker-engine/src/v4/simulator/render_rules/containter_exit.ts

@@ -110,11 +110,16 @@ export let RULES: SRRendererRule[] = [
         modes: ["item"],
         tests: [
             (cursor: SRCursor) => {
+                // <details> uses the group role but has its own disclosure widget semantics;
+                // SRs do not announce "out of grouping" when leaving a details element.
+                if (cursor.getNode().nodeName.toUpperCase() === "DETAILS") {
+                    return "";
+                }
                 if (cursor.getNameInfo() === null) return null;
                 if (cursor.getCurrentOrParentByRoleClone(["combobox"], ["select"])?.getNode().nodeName.toUpperCase() === "SELECT") {
                     return "";
                 }
-                else return "[out of grouping]";
+                return "[out of grouping]";
             }
         ]
     }),