@coreui/react-pro 5.24.1 → 5.26.0

package/src/components/nav/CNavGroup.tsx

@@ -4,8 +4,11 @@ import React, {
   forwardRef,
   HTMLAttributes,
   ReactNode,
+  useCallback,
   useContext,
   useEffect,
+  useId,
+  useMemo,
   useRef,
   useState,
 } from 'react'
@@ -16,8 +19,7 @@ import type { TransitionStatus } from 'react-transition-group'
 
 import { PolymorphicRefForwardingComponent } from '../../helpers'
 
-import { CSidebarNavContext } from '../sidebar/CSidebarNavContext'
-
+import { CNavGroupContext, CNavGroupContextValue } from './CNavGroupContext'
 export interface CNavGroupProps extends HTMLAttributes<HTMLDivElement | HTMLLIElement> {
   /**
    * Component used for the root node. Either a string to use a HTML element or a component.
@@ -34,140 +36,229 @@ export interface CNavGroupProps extends HTMLAttributes<HTMLDivElement | HTMLLIEl
    */
   compact?: boolean
   /**
-   * Set group toggler label.
+   * Callback fired when the user toggles the group. Receives the requested visibility. Provide
+   * it together with `visible` for controlled mode—update `visible` from here, or ignore the
+   * change to keep the group as is.
+   *
+   * @since 5.12.0
    */
-  toggler?: string | ReactNode
+  onVisibleChange?: (visible: boolean) => void
   /**
-   * Show nav group items.
+   * Set group toggler label.
    */
-  visible?: boolean
+  toggler?: string | ReactNode | (({ visible }: { visible: boolean }) => ReactNode)
   /**
-   * @ignore
+   * Show nav group items. Acts as the initial state when used on its own, or as the controlled
+   * value when paired with `onVisibleChange`.
    */
-  idx?: string
-}
-
-const isInVisibleGroup = (el1: string, el2: string) => {
-  const array1 = el1.toString().split('.')
-  const array2 = el2.toString().split('.')
-
-  return array2.every((item, index) => item === array1[index])
+  visible?: boolean
 }
 
 export const CNavGroup: PolymorphicRefForwardingComponent<'li', CNavGroupProps> = forwardRef<
   HTMLDivElement | HTMLLIElement,
   CNavGroupProps
->(({ children, as: Component = 'li', className, compact, idx, toggler, visible, ...rest }, ref) => {
-  const [height, setHeight] = useState<number | string>(0)
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const navItemsRef = useRef<any>(null)
+>(
+  (
+    {
+      children,
+      as: Component = 'li',
+      className,
+      compact,
+      onVisibleChange,
+      toggler,
+      visible,
+      ...rest
+    },
+    ref
+  ) => {
+    const id = useId()
+
+    // Accordion of the parent level: lets this group read whether it is the open one and request
+    // its own open/close. `null` when rendered outside a `CSidebarNav`.
+    const parentContext = useContext(CNavGroupContext)
+    const parentContextRef = useRef(parentContext)
+    parentContextRef.current = parentContext
+
+    const [height, setHeight] = useState<number | string>(0)
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const navItemsRef = useRef<any>(null)
+
+    const [uncontrolledVisible, setUncontrolledVisible] = useState(Boolean(visible))
+    // This group's own accordion state for its children. It survives the group being collapsed,
+    // so reopening the group restores whichever child was previously open.
+    const [activeChildId, setActiveChildId] = useState<string | undefined>()
+
+    const controlled = visible !== undefined && onVisibleChange !== undefined
+
+    const _visible = controlled
+      ? Boolean(visible)
+      : parentContext
+        ? parentContext.activeId === id
+        : uncontrolledVisible
+
+    // Sync the accordion with the `visible` prop: seeds default-open groups and follows later
+    // changes (and keeps controlled groups in sync). Watching only `visible` keeps this from
+    // re-running on unrelated accordion updates—so a default-open group can be collapsed manually.
+    useEffect(() => {
+      if (visible === undefined) {
+        return
+      }
+
+      const parentSetActiveId = parentContextRef.current?.setActiveId
+      if (parentSetActiveId) {
+        if (visible) {
+          parentSetActiveId(id)
+        } else {
+          parentSetActiveId((prev) => (prev === id ? undefined : prev))
+        }
+      } else {
+        setUncontrolledVisible(visible)
+      }
+    }, [visible, id])
 
-  const { visibleGroup, setVisibleGroup } = useContext(CSidebarNavContext)
+    // Accordion: when another branch opens, a controlled group must close too. As its visibility
+    // is owned by the parent, request the change through `onVisibleChange`.
+    useEffect(() => {
+      if (!controlled || !visible) {
+        return
+      }
 
-  const [_visible, setVisible] = useState(
-    Boolean(visible || (idx && visibleGroup && isInVisibleGroup(visibleGroup, idx)))
-  )
+      const activeId = parentContext?.activeId
+      if (activeId !== undefined && activeId !== id) {
+        onVisibleChange?.(false)
+      }
+    }, [controlled, visible, parentContext?.activeId, id, onVisibleChange])
 
-  useEffect(() => {
-    setVisible(Boolean(idx && visibleGroup && isInVisibleGroup(visibleGroup, idx)))
-  }, [visibleGroup])
+    // Open this group within its parent level and cascade up to the root, revealing the whole
+    // branch. Used by an active nav link and by nested groups to bubble the request upwards.
+    const openBranch = useCallback(() => {
+      const parent = parentContextRef.current
+      if (!parent) {
+        return
+      }
 
-  const handleTogglerOnCLick = (event: React.MouseEvent<HTMLElement>) => {
-    event.preventDefault()
-    setVisibleGroup(
-      _visible ? (idx?.toString().includes('.') ? idx.slice(0, idx.lastIndexOf('.')) : '') : idx
+      parent.setActiveId(id)
+      parent.openBranch()
+    }, [id])
+
+    const childContextValue = useMemo<CNavGroupContextValue>(
+      () => ({ activeId: activeChildId, setActiveId: setActiveChildId, openBranch }),
+      [activeChildId, openBranch]
     )
-    setVisible(!_visible)
-  }
 
-  const style: CSSProperties = {
-    height: 0,
-  }
+    const handleTogglerOnClick = (event: React.MouseEvent<HTMLElement>) => {
+      event.preventDefault()
+      const next = !_visible
 
-  const onEntering = () => {
-    navItemsRef.current && setHeight(navItemsRef.current.scrollHeight)
-  }
+      if (!controlled) {
+        if (parentContext) {
+          parentContext.setActiveId(next ? id : undefined)
+        } else {
+          setUncontrolledVisible(next)
+        }
+      }
 
-  const onEntered = () => {
-    setHeight('auto')
-  }
+      onVisibleChange?.(next)
+    }
 
-  const onExit = () => {
-    navItemsRef.current && setHeight(navItemsRef.current.scrollHeight)
-  }
+    const style: CSSProperties = {
+      height: 0,
+    }
 
-  const onExiting = () => {
-    // @ts-expect-error reflow is necessary to get correct height of the element
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    const reflow = navItemsRef.current?.offsetHeight
-    setHeight(0)
-  }
+    const onEntering = () => {
+      if (navItemsRef.current) {
+        setHeight(navItemsRef.current.scrollHeight)
+      }
+    }
 
-  const onExited = () => {
-    setHeight(0)
-  }
+    const onEntered = () => {
+      setHeight('auto')
+    }
 
-  const transitionStyles = {
-    entering: { display: 'block', height: height },
-    entered: { display: 'block', height: height },
-    exiting: { display: 'block', height: height },
-    exited: { height: height },
-    unmounted: {},
-  }
+    const onExit = () => {
+      if (navItemsRef.current) {
+        setHeight(navItemsRef.current.scrollHeight)
+      }
+    }
+
+    const onExiting = () => {
+      // @ts-expect-error reflow is necessary to get correct height of the element
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      const reflow = navItemsRef.current?.offsetHeight
+      setHeight(0)
+    }
+
+    const onExited = () => {
+      setHeight(0)
+    }
+
+    const transitionStyles = {
+      entering: { display: 'block', height: height },
+      entered: { display: 'block', height: height },
+      exiting: { display: 'block', height: height },
+      exited: { height: height },
+      unmounted: {},
+    }
 
-  const NavGroupItemsComponent = Component === 'li' ? 'ul' : 'div'
-
-  return (
-    <Component
-      className={classNames('nav-group', { show: _visible }, className)}
-      {...rest}
-      ref={ref}
-    >
-      {toggler && (
-        <a
-          className="nav-link nav-group-toggle"
-          href="#"
-          onClick={(event) => handleTogglerOnCLick(event)}
+    const NavGroupItemsComponent = Component === 'li' ? 'ul' : 'div'
+    const togglerContent = typeof toggler === 'function' ? toggler({ visible: _visible }) : toggler
+
+    return (
+      <CNavGroupContext.Provider value={childContextValue}>
+        <Component
+          className={classNames('nav-group', { show: _visible }, className)}
+          {...rest}
+          ref={ref}
         >
-          {toggler}
-        </a>
-      )}
-      <Transition
-        in={_visible}
-        nodeRef={navItemsRef}
-        onEntering={onEntering}
-        onEntered={onEntered}
-        onExit={onExit}
-        onExiting={onExiting}
-        onExited={onExited}
-        timeout={300}
-      >
-        {(state) => (
-          <NavGroupItemsComponent
-            className={classNames('nav-group-items', {
-              compact: compact,
-            })}
-            style={{
-              ...style,
-              ...transitionStyles[state as TransitionStatus],
-            }}
-            ref={navItemsRef}
+          {toggler && (
+            <a
+              aria-expanded={_visible}
+              className="nav-link nav-group-toggle"
+              href="#"
+              onClick={handleTogglerOnClick}
+            >
+              {togglerContent}
+            </a>
+          )}
+          <Transition
+            appear
+            in={_visible}
+            nodeRef={navItemsRef}
+            onEntering={onEntering}
+            onEntered={onEntered}
+            onExit={onExit}
+            onExiting={onExiting}
+            onExited={onExited}
+            timeout={300}
           >
-            {children}
-          </NavGroupItemsComponent>
-        )}
-      </Transition>
-    </Component>
-  )
-})
+            {(state) => (
+              <NavGroupItemsComponent
+                className={classNames('nav-group-items', {
+                  compact: compact,
+                })}
+                style={{
+                  ...style,
+                  ...transitionStyles[state as TransitionStatus],
+                }}
+                ref={navItemsRef}
+              >
+                {children}
+              </NavGroupItemsComponent>
+            )}
+          </Transition>
+        </Component>
+      </CNavGroupContext.Provider>
+    )
+  }
+)
 
 CNavGroup.propTypes = {
   as: PropTypes.elementType,
   children: PropTypes.node,
   className: PropTypes.string,
   compact: PropTypes.bool,
-  idx: PropTypes.string,
-  toggler: PropTypes.oneOfType([PropTypes.string, PropTypes.node]),
+  onVisibleChange: PropTypes.func,
+  toggler: PropTypes.oneOfType([PropTypes.string, PropTypes.node, PropTypes.func]),
   visible: PropTypes.bool,
 }
 

package/src/components/nav/CNavGroupContext.ts

@@ -0,0 +1,27 @@
+import { createContext, Dispatch, SetStateAction } from 'react'
+
+export interface CNavGroupContextValue {
+  /**
+   * The id of the currently open child group at this level, or `undefined` when none is open.
+   * Each `CNavGroup` keeps its own accordion state, so collapsing an ancestor never discards the
+   * open/closed state of its descendants—reopening the ancestor restores them.
+   */
+  activeId: string | undefined
+  /**
+   * Open (or, with `undefined`, close) a child group at this level. Opening a group collapses its
+   * siblings, mirroring the vanilla `groupsAutoCollapse` behavior.
+   */
+  setActiveId: Dispatch<SetStateAction<string | undefined>>
+  /**
+   * Open the whole branch from the parent group up to the root. Used by an active nav link to
+   * reveal every ancestor group.
+   */
+  openBranch: () => void
+}
+
+/**
+ * Provides the per-level accordion state to the direct children (`CNavGroup`, `CNavLink`) of a
+ * `CSidebarNav` or a parent `CNavGroup`. `null` means the consumer is rendered outside a sidebar
+ * navigation, in which case groups fall back to their own local state.
+ */
+export const CNavGroupContext = createContext<CNavGroupContextValue | null>(null)

package/src/components/nav/CNavLink.tsx

@@ -3,16 +3,12 @@ import PropTypes from 'prop-types'
 import classNames from 'classnames'
 
 import { CLinkProps, CLink } from '../link/CLink'
-import { CSidebarNavContext } from '../sidebar/CSidebarNavContext'
+import { CNavGroupContext } from './CNavGroupContext'
 
 import { PolymorphicRefForwardingComponent } from '../../helpers'
 import { useForkedRef } from '../../hooks'
 
-export interface CNavLinkProps extends Omit<CLinkProps, 'idx'> {
-  /**
-   * @ignore
-   */
-  idx?: string
+export interface CNavLinkProps extends CLinkProps {
   /**
    * @ignore
    */
@@ -22,16 +18,35 @@ export interface CNavLinkProps extends Omit<CLinkProps, 'idx'> {
 export const CNavLink: PolymorphicRefForwardingComponent<'a', CNavLinkProps> = forwardRef<
   HTMLButtonElement | HTMLAnchorElement,
   CNavLinkProps
->(({ children, className, idx, ...rest }, ref) => {
+>(({ children, className, ...rest }, ref) => {
   const navLinkRef = useRef<HTMLAnchorElement>(null)
   const forkedRef = useForkedRef(ref, navLinkRef)
 
-  const { setVisibleGroup } = useContext(CSidebarNavContext)
+  const openBranch = useContext(CNavGroupContext)?.openBranch
 
   useEffect(() => {
-    rest.active = navLinkRef.current?.classList.contains('active')
-    idx && rest.active && setVisibleGroup(idx)
-  }, [rest.active, className])
+    const element = navLinkRef.current
+
+    if (!element || !openBranch) {
+      return
+    }
+
+    let wasActive = false
+    const sync = () => {
+      const active = element.classList.contains('active')
+      if (active && !wasActive) {
+        openBranch()
+      }
+
+      wasActive = active
+    }
+
+    sync()
+    const observer = new MutationObserver(sync)
+    observer.observe(element, { attributes: true, attributeFilter: ['class'] })
+
+    return () => observer.disconnect()
+  }, [openBranch])
 
   return (
     <CLink className={classNames('nav-link', className)} {...rest} ref={forkedRef}>
@@ -46,7 +61,6 @@ CNavLink.propTypes = {
   children: PropTypes.node,
   className: PropTypes.string,
   disabled: PropTypes.bool,
-  idx: PropTypes.string,
 }
 
 CNavLink.displayName = 'CNavLink'

package/src/components/nav/__tests__/CNavGroup.spec.tsx

@@ -1,7 +1,8 @@
 import * as React from 'react'
-import { render } from '@testing-library/react'
+import { fireEvent, render, screen } from '@testing-library/react'
 import '@testing-library/jest-dom'
-import { CNavGroup } from '../index'
+import { CNavGroup, CNavItem } from '../index'
+import { CSidebarNav } from '../../sidebar/CSidebarNav'
 
 test('loads and displays CNavGroup component', async () => {
   const { container } = render(<CNavGroup toggler="anchorText" />)
@@ -10,16 +11,218 @@ test('loads and displays CNavGroup component', async () => {
 
 test('CNavGroup customize', async () => {
   const { container } = render(
-    <CNavGroup className="bazinga" toggler="anchorText" visible={true} idx="1" />
+    <CNavGroup className="bazinga" toggler="anchorText" visible={true} />
   )
   expect(container).toMatchSnapshot()
   expect(container.firstChild).toHaveClass('nav-group')
   expect(container.firstChild).toHaveClass('bazinga')
   const arr = container.getElementsByClassName('nav-link')
   if (arr.length > 0) {
-    //expect(arr[0].innerText).toHaveTextContent('anchorText')
     expect(arr[0].innerHTML).toBe('anchorText')
   } else {
     expect(true).toBe(false)
   }
 })
+
+test('CNavGroup toggles its own visibility when uncontrolled', async () => {
+  const { container } = render(
+    <CSidebarNav>
+      <CNavGroup toggler="anchorText">
+        <CNavItem href="#">Item</CNavItem>
+      </CNavGroup>
+    </CSidebarNav>
+  )
+
+  const group = container.querySelector('.nav-group') as HTMLElement
+  expect(group).not.toHaveClass('show')
+
+  fireEvent.click(container.querySelector('.nav-group-toggle') as HTMLElement)
+  expect(group).toHaveClass('show')
+
+  fireEvent.click(container.querySelector('.nav-group-toggle') as HTMLElement)
+  expect(group).not.toHaveClass('show')
+})
+
+test('CNavGroup follows the visible prop in controlled mode', async () => {
+  const { container, rerender } = render(<CNavGroup toggler="anchorText" visible={true} />)
+  expect(container.querySelector('.nav-group')).toHaveClass('show')
+
+  rerender(<CNavGroup toggler="anchorText" visible={false} />)
+  expect(container.querySelector('.nav-group')).not.toHaveClass('show')
+})
+
+test('CNavGroup stays open when the parent rejects the collapse (controlled)', async () => {
+  const onVisibleChange = jest.fn()
+  const { container } = render(
+    <CNavGroup toggler="anchorText" visible={true} onVisibleChange={onVisibleChange} />
+  )
+
+  expect(container.querySelector('.nav-group')).toHaveClass('show')
+
+  // Parent keeps `visible` at `true` (rejects the collapse).
+  fireEvent.click(container.querySelector('.nav-group-toggle') as HTMLElement)
+
+  expect(onVisibleChange).toHaveBeenCalledWith(false)
+  expect(container.querySelector('.nav-group')).toHaveClass('show')
+})
+
+test('CNavGroup toggler render function receives visible state', async () => {
+  render(<CNavGroup toggler={({ visible }) => <span>{visible ? 'expanded' : 'collapsed'}</span>} />)
+
+  expect(screen.getByText('collapsed')).toBeInTheDocument()
+
+  fireEvent.click(screen.getByRole('link'))
+
+  expect(screen.getByText('expanded')).toBeInTheDocument()
+})
+
+test('an active nav link opens its parent group', async () => {
+  const { container } = render(
+    <CSidebarNav>
+      <CNavGroup toggler="anchorText">
+        <CNavItem href="#" active>
+          Item
+        </CNavItem>
+      </CNavGroup>
+    </CSidebarNav>
+  )
+
+  expect(container.querySelector('.nav-group')).toHaveClass('show')
+})
+
+test('opening another group closes a controlled group when the parent accepts', async () => {
+  const Wrapper = () => {
+    const [visible, setVisible] = React.useState(true)
+    return (
+      <CSidebarNav>
+        <CNavGroup toggler="Controlled" visible={visible} onVisibleChange={setVisible}>
+          <CNavItem href="#">A</CNavItem>
+        </CNavGroup>
+        <CNavGroup toggler="Other">
+          <CNavItem href="#">B</CNavItem>
+        </CNavGroup>
+      </CSidebarNav>
+    )
+  }
+
+  const { container } = render(<Wrapper />)
+  const [controlled, other] = Array.from(container.querySelectorAll('.nav-group'))
+  expect(controlled).toHaveClass('show')
+
+  fireEvent.click(container.querySelectorAll('.nav-group-toggle')[1] as HTMLElement)
+
+  expect(other).toHaveClass('show')
+  expect(controlled).not.toHaveClass('show')
+})
+
+test('a locked controlled group stays open when another group opens', async () => {
+  const Wrapper = () => {
+    const [visible, setVisible] = React.useState(true)
+    const onVisibleChange = (value: boolean) => {
+      if (value) {
+        setVisible(true)
+      }
+    }
+    return (
+      <CSidebarNav>
+        <CNavGroup toggler="Locked" visible={visible} onVisibleChange={onVisibleChange}>
+          <CNavItem href="#">A</CNavItem>
+        </CNavGroup>
+        <CNavGroup toggler="Other">
+          <CNavItem href="#">B</CNavItem>
+        </CNavGroup>
+      </CSidebarNav>
+    )
+  }
+
+  const { container } = render(<Wrapper />)
+  const [locked, other] = Array.from(container.querySelectorAll('.nav-group'))
+  expect(locked).toHaveClass('show')
+
+  fireEvent.click(container.querySelectorAll('.nav-group-toggle')[1] as HTMLElement)
+
+  expect(other).toHaveClass('show')
+  expect(locked).toHaveClass('show')
+})
+
+test('opening an uncontrolled group collapses its sibling', async () => {
+  const { container } = render(
+    <CSidebarNav>
+      <CNavGroup toggler="A">
+        <CNavItem href="#">Item</CNavItem>
+      </CNavGroup>
+      <CNavGroup toggler="B">
+        <CNavItem href="#">Item</CNavItem>
+      </CNavGroup>
+    </CSidebarNav>
+  )
+
+  const [groupA, groupB] = Array.from(container.querySelectorAll('.nav-group'))
+  const [togglerA, togglerB] = Array.from(container.querySelectorAll('.nav-group-toggle'))
+
+  fireEvent.click(togglerA as HTMLElement)
+  expect(groupA).toHaveClass('show')
+  expect(groupB).not.toHaveClass('show')
+
+  fireEvent.click(togglerB as HTMLElement)
+  expect(groupA).not.toHaveClass('show')
+  expect(groupB).toHaveClass('show')
+})
+
+test('reopening a parent restores the open state of its nested subgroups', async () => {
+  const { container } = render(
+    <CSidebarNav>
+      <CNavGroup toggler="A" visible>
+        <CNavGroup toggler="B" visible>
+          <CNavGroup toggler="C" visible>
+            <CNavItem href="#">Item</CNavItem>
+          </CNavGroup>
+        </CNavGroup>
+      </CNavGroup>
+    </CSidebarNav>
+  )
+
+  const [groupA, groupB, groupC] = Array.from(container.querySelectorAll('.nav-group'))
+  expect(groupA).toHaveClass('show')
+  expect(groupB).toHaveClass('show')
+  expect(groupC).toHaveClass('show')
+
+  const outerToggler = container.querySelectorAll('.nav-group-toggle')[0] as HTMLElement
+
+  // Collapse the parent: the whole branch is hidden.
+  fireEvent.click(outerToggler)
+  expect(groupA).not.toHaveClass('show')
+
+  // Reopen the parent: nested subgroups come back open (matches vanilla/Vue).
+  fireEvent.click(outerToggler)
+  expect(groupA).toHaveClass('show')
+  expect(groupB).toHaveClass('show')
+  expect(groupC).toHaveClass('show')
+})
+
+test('nested default-open groups render open and stay independently toggleable', async () => {
+  const { container } = render(
+    <CSidebarNav>
+      <CNavGroup toggler="Group A" visible>
+        <CNavGroup toggler="Group B" visible>
+          <CNavItem href="#">Item</CNavItem>
+        </CNavGroup>
+      </CNavGroup>
+    </CSidebarNav>
+  )
+
+  const [groupA, groupB] = Array.from(container.querySelectorAll('.nav-group'))
+  expect(groupA).toHaveClass('show')
+  expect(groupB).toHaveClass('show')
+
+  // Collapsing the inner group keeps the outer one open.
+  const innerToggler = container.querySelectorAll('.nav-group-toggle')[1] as HTMLElement
+  fireEvent.click(innerToggler)
+  expect(groupA).toHaveClass('show')
+  expect(groupB).not.toHaveClass('show')
+
+  // Collapsing the outer group closes the whole branch.
+  const outerToggler = container.querySelectorAll('.nav-group-toggle')[0] as HTMLElement
+  fireEvent.click(outerToggler)
+  expect(groupA).not.toHaveClass('show')
+})