feat(dx): configurable loop behavior to focus-managed components (rad-ui#1934)

Author: kotAPI

.changeset/green-pigs-repeat.md

@@ -0,0 +1,5 @@
+---
+"@radui/ui": patch
+---
+
+Add configurable `loop` focus-wrapping options for Tabs, Disclosure, Tree, and NavigationMenu, including NavigationMenu content panels.

docs/app/docs/components/disclosure/docs/component_api/root.tsx

@@ -8,7 +8,8 @@ const data = {
     ],
     data: [
         { prop: { name: "items", info_tooltips: "Array of { title, content } for the convenience wrapper." }, type: "{ title: string, content: ReactNode }[]", default: "--" },
-        { prop: { name: "className", info_tooltips: "Additional CSS classes." }, type: "string", default: '""' }
+        { prop: { name: "className", info_tooltips: "Additional CSS classes." }, type: "string", default: '""' },
+        { prop: { name: "loop", info_tooltips: "Whether arrow key navigation wraps between disclosure triggers." }, type: "boolean", default: "true" }
     ]
 }
 

docs/app/docs/components/navigation-menu/docs/component_api/root.tsx

@@ -8,6 +8,8 @@ const data = {
     ],
     data: [
         { prop: { name: "value", info_tooltips: "Controlled open item value." }, type: "string", default: "--" },
+        { prop: { name: "loop", info_tooltips: "Whether arrow key navigation wraps between top-level triggers." }, type: "boolean", default: "true" },
+        { prop: { name: "contentLoop", info_tooltips: "Default wrap behavior for roving focus inside opened content panels." }, type: "boolean", default: "true" },
         { prop: { name: "orientation", info_tooltips: "Layout orientation of the menu." }, type: "enum", enum_values: ["horizontal", "vertical"], default: "horizontal" },
         { prop: { name: "onValueChange", info_tooltips: "Callback when the active item changes." }, type: "function", default: "--" }
     ]

docs/app/docs/components/tabs/docs/component_api/root.tsx

@@ -90,6 +90,14 @@ const data = {
         enum_values : ['ltr', 'rtl'],
         default : "ltr",
        },
+       {
+        prop : {
+            name : "loop",
+            info_tooltips : "Whether arrow key navigation wraps from the last trigger to the first, and from the first to the last."
+        },
+        type : "boolean",
+        default : "true",
+       },
        {
         prop : {
             name : "activationMode",

docs/app/docs/components/tree/docs/codeUsage.js

@@ -1,4 +1,5 @@
 import { getSourceCodeFromPath } from '@/utils/parseSourceCode';
+import root_api from './component_api/root.tsx';
 import item_api from './component_api/item.tsx';
 
 const example_1_SourceCode = await getSourceCodeFromPath('docs/app/docs/components/tree/docs/example_1.tsx');
@@ -13,6 +14,7 @@ export const code = {
 export const anatomy = { code: anatomy_SourceCode };
 
 export const api_documentation = {
+    root: root_api,
     item: item_api
 };
 

docs/app/docs/components/tree/docs/component_api/root.tsx

@@ -0,0 +1,16 @@
+const data = {
+    name: "Root",
+    description: "The root Tree component.",
+    columns: [
+        { name: "Prop", id: "prop" },
+        { name: "Type", id: "type" },
+        { name: "Default", id: "default" }
+    ],
+    data: [
+        { prop: { name: "aria-label", info_tooltips: "Accessible label for the tree when no visible label is present." }, type: "string", default: "--" },
+        { prop: { name: "aria-labelledby", info_tooltips: "ID of an element that labels the tree." }, type: "string", default: "--" },
+        { prop: { name: "loop", info_tooltips: "Whether arrow key navigation wraps from the last visible item to the first, and from the first to the last." }, type: "boolean", default: "true" }
+    ]
+}
+
+export default data

src/components/ui/Disclosure/fragments/DisclosureRoot.tsx

@@ -10,9 +10,10 @@ const COMPONENT_NAME = 'Disclosure';
 export type DisclosureRootProps = React.ComponentPropsWithoutRef<'div'> & {
      customRootClass?: string;
      defaultOpen?: number | null;
+     loop?: boolean;
 };
 
-const DisclosureRoot = React.forwardRef<React.ElementRef<'div'>, DisclosureRootProps>(({ children, customRootClass, 'aria-label': ariaLabel, ...props }, forwardedRef) => {
+const DisclosureRoot = React.forwardRef<React.ElementRef<'div'>, DisclosureRootProps>(({ children, customRootClass, 'aria-label': ariaLabel, loop = true, ...props }, forwardedRef) => {
     const disclosureRef = useRef<React.ElementRef<'div'> | null>(null);
     const rootClass = useComponentClass(customRootClass, COMPONENT_NAME);
 
@@ -37,7 +38,7 @@ const DisclosureRoot = React.forwardRef<React.ElementRef<'div'>, DisclosureRootP
                 disclosureRef
 
             }}>
-            <RovingFocusGroup.Root>
+            <RovingFocusGroup.Root loop={loop}>
                 <RovingFocusGroup.Group className={clsx(rootClass && `${rootClass}-root`)}>
                     <div
                         {...props}

src/components/ui/Disclosure/tests/Disclosure.test.tsx

@@ -1,5 +1,6 @@
 import React from 'react';
 import { fireEvent, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import Disclosure from '../Disclosure';
 
 const items = [
@@ -55,6 +56,38 @@ describe('Disclosure', () => {
         expect(screen.getByText('Content 1')).toBeInTheDocument();
     });
 
+    test('loop={false} stops focus wrap between triggers', async() => {
+        const user = userEvent.setup();
+
+        render(
+            <Disclosure.Root aria-label="test" loop={false}>
+                <Disclosure.Item value={0}>
+                    <Disclosure.Trigger>Item 1</Disclosure.Trigger>
+                    <Disclosure.Content>Content 1</Disclosure.Content>
+                </Disclosure.Item>
+                <Disclosure.Item value={1}>
+                    <Disclosure.Trigger>Item 2</Disclosure.Trigger>
+                    <Disclosure.Content>Content 2</Disclosure.Content>
+                </Disclosure.Item>
+            </Disclosure.Root>
+        );
+
+        const item1 = screen.getByText('Item 1');
+        const item2 = screen.getByText('Item 2');
+
+        await user.tab();
+        expect(item1).toHaveFocus();
+
+        await user.keyboard('{ArrowLeft}');
+        expect(item1).toHaveFocus();
+
+        await user.keyboard('{ArrowRight}');
+        expect(item2).toHaveFocus();
+
+        await user.keyboard('{ArrowRight}');
+        expect(item2).toHaveFocus();
+    });
+
     test('hides content when the same item is clicked again', () => {
         render(<Disclosure items={items} aria-label="test" />);
         const button = screen.getByText('Item 1');

src/components/ui/NavigationMenu/contexts/NavigationMenuRootContext.tsx

@@ -4,12 +4,14 @@ export interface NavigationMenuRootContextProps {
     isOpen: string;
     setIsOpen: React.Dispatch<React.SetStateAction<string>>;
     rootClass: string;
+    contentLoop: boolean;
 }
 
 const NavigationMenuRootContext = React.createContext<NavigationMenuRootContextProps>({
     isOpen: '',
     setIsOpen: () => {},
-    rootClass: ''
+    rootClass: '',
+    contentLoop: true
 });
 
 export default NavigationMenuRootContext;

src/components/ui/NavigationMenu/fragments/NavigationMenuContent.tsx

@@ -8,13 +8,15 @@ export type NavigationMenuContentElement = React.ElementRef<'div'>;
 
 export interface NavigationMenuContentProps extends React.ComponentPropsWithoutRef<'div'> {
     children: React.ReactNode;
+    loop?: boolean;
 }
 
 const NavigationMenuContent = React.forwardRef<NavigationMenuContentElement, NavigationMenuContentProps>(
-    ({ children, className, ...props }, ref) => {
+    ({ children, className, loop, ...props }, ref) => {
         const { itemOpen } = React.useContext(NavigationMenuItemContext);
-        const { rootClass } = React.useContext(NavigationMenuRootContext);
+        const { rootClass, contentLoop } = React.useContext(NavigationMenuRootContext);
         const contentRef = React.useRef<HTMLDivElement>(null);
+        const resolvedLoop = loop ?? contentLoop;
 
         React.useImperativeHandle(ref, () => contentRef.current as HTMLDivElement);
 
@@ -30,7 +32,7 @@ const NavigationMenuContent = React.forwardRef<NavigationMenuContentElement, Nav
                 data-state={itemOpen ? 'open' : 'closed'}
                 {...props}
             >
-                <RovingFocusGroup.Root>
+                <RovingFocusGroup.Root loop={resolvedLoop}>
                     <RovingFocusGroup.Group>{children}</RovingFocusGroup.Group>
                 </RovingFocusGroup.Root>
             </div>