fix(accordion): inert on closed content, tests and docstrings

Author: KrotovM

packages/ui/src/components/Accordion/Accordion.test.tsx

@@ -283,7 +283,7 @@ describe("Components / Accordion", () => {
       const firstContent = content()[0];
 
       expect(firstContent).not.toHaveStyle("transition: max-height 400ms ease-out");
-      expect(firstContent).not.toHaveAttribute("aria-hidden", "false");
+      expect(firstContent).not.toHaveAttribute("aria-hidden");
     });
 
     it("should use the default `animationDuration` when `animate` is enabled and `animationDuration` is not provided", () => {
@@ -294,6 +294,46 @@ describe("Components / Accordion", () => {
       expect(firstContent).toHaveStyle("transition: max-height 300ms ease-out");
       expect(firstContent).toHaveAttribute("aria-hidden", "false");
     });
+
+    it("should set inert on closed animated content to suppress focus", () => {
+      render(<TestAccordion animate collapseAll />);
+
+      const firstContent = content()[0];
+
+      expect(firstContent).toHaveAttribute("aria-hidden", "true");
+      expect(firstContent).toHaveAttribute("inert");
+    });
+
+    it("should set inert when closed and remove when open; focusable descendants reachable when open", async () => {
+      const user = userEvent.setup();
+      render(
+        <Accordion animate>
+          <AccordionPanel>
+            <AccordionTitle>First</AccordionTitle>
+            <AccordionContent>
+              <a href="#link">Link inside</a>
+            </AccordionContent>
+          </AccordionPanel>
+          <AccordionPanel>
+            <AccordionTitle>Second</AccordionTitle>
+            <AccordionContent>
+              <p>Content</p>
+            </AccordionContent>
+          </AccordionPanel>
+        </Accordion>,
+      );
+
+      const link = screen.getByText("Link inside");
+      const firstTitle = screen.getByRole("button", { name: "First" });
+
+      await user.click(screen.getByRole("button", { name: "Second" }));
+      expect(content()[0]).toHaveAttribute("inert");
+
+      await user.click(firstTitle);
+      expect(content()[0]).not.toHaveAttribute("inert");
+      await user.tab();
+      expect(link).toHaveFocus();
+    });
   });
 });
 

packages/ui/src/components/Accordion/Accordion.tsx

@@ -27,7 +27,9 @@ export interface AccordionRootTheme {
 
 export interface AccordionProps extends ComponentProps<"div">, ThemingProps<AccordionRootTheme> {
   alwaysOpen?: boolean;
+  /** Enable smooth open/close animation for panel content. */
   animate?: boolean;
+  /** Duration of the open/close animation in milliseconds. Only used when `animate` is true. Defaults to 300. */
   animationDuration?: number;
   arrowIcon?: FC<ComponentProps<"svg">>;
   children: ReactElement<AccordionPanelProps> | ReactElement<AccordionPanelProps>[];

packages/ui/src/components/Accordion/AccordionContent.tsx

@@ -20,6 +20,7 @@ export interface AccordionContentProps extends ComponentProps<"div">, ThemingPro
 export function AccordionContent(props: AccordionContentProps) {
   const { isOpen, animate = false, animationDuration = 300 } = useAccordionContext();
   const contentRef = useRef<HTMLDivElement>(null);
+  const wrapperRef = useRef<HTMLDivElement>(null);
   const [height, setHeight] = useState<number>(0);
 
   useLayoutEffect(() => {
@@ -28,6 +29,18 @@ export function AccordionContent(props: AccordionContentProps) {
     if (el) setHeight(el.scrollHeight);
   }, [animate, isOpen]);
 
+  /** When closed, set inert on the wrapper so descendants are not focusable. */
+  useLayoutEffect(() => {
+    if (!animate) return;
+    const wrapper = wrapperRef.current;
+    if (!wrapper) return;
+    if (isOpen) {
+      wrapper.removeAttribute("inert");
+    } else {
+      wrapper.setAttribute("inert", "");
+    }
+  }, [animate, isOpen]);
+
   const provider = useThemeProvider();
   const theme = useResolveTheme(
     [accordionTheme.content, provider.theme?.accordion?.content, props.theme],
@@ -50,6 +63,7 @@ export function AccordionContent(props: AccordionContentProps) {
     />
   ) : (
     <div
+      ref={wrapperRef}
       data-testid="flowbite-accordion-content"
       aria-hidden={!isOpen}
       style={{