Files
supabase/apps/docs/components/Navigation/NavigationMenu/NavigationMenuGuideListItems.tsx
T
Anthony Lio bdd4b8d369 fix(docs): guides sidebar a11y elements (#49942)
## What kind of change does this PR introduce?

bug fix (accessibility) + test coverage

## What is the current behavior?

the guides sidebar renders invalid list markup: group headers and
dividers sit directly under the root `ul`, and accordion links render as
`li` elements without an owning list

fixes
[DOCS-1279](https://linear.app/supabase/issue/DOCS-1279/guides-sidebar-put-li-elements-directly-in-the-ul)

## What is the new behavior?

- sidebar renders a semantic hierarchy: every `ul` has only `li`
children, every `li` has an immediate list parent, and the menu header
sits outside the item list. pure markup change,
- docs e2e scans the guide navigation separately from the article and
blocks the `list` and `listitem` axe rules there against sample pages
that include different usages (flat links, grouped links, nested
accordion)

## How to test?

run the docs dev server, then the scoped a11y suite:

```bash
pnpm dev:docs
pnpm e2e:docs:a11y
```

## Follow up
visuals and behavior are unchanged here but better parity between
guide/reference is handled in the stacked pr

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Bug Fixes**
* Improved documentation navigation rendering for nested guide items,
active states, and disabled entries.
* Ensured navigation groups and child links use valid, testable list
structures.

* **Tests**
* Added coverage verifying that guide navigation changes run the
appropriate documentation pages.
* Confirmed unrelated documentation changes can be skipped by the
end-to-end workflow.

* **Chores**
* Updated documentation test scope detection to include guide navigation
changes.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2026-09-10 15:03:55 +03:00

240 lines
7.7 KiB
TypeScript

import { ChevronDown } from 'lucide-react'
import { useTheme } from 'next-themes'
import Image from 'next/legacy/image'
import Link from 'next/link'
import { usePathname } from 'next/navigation'
import { Accordion } from 'radix-ui'
import React, { useEffect, useRef } from 'react'
import MenuIconPicker from './MenuIconPicker'
type NavAccordionItem = {
url?: string
items?: NavAccordionItem[]
}
function hasActiveDescendant(item: NavAccordionItem, pathname: string): boolean {
if (item.url === pathname) return true
return item.items?.some((child) => hasActiveDescendant(child, pathname)) ?? false
}
const HeaderLink = React.memo(function HeaderLink(props: {
title: string
id: string
url: string
}) {
const pathname = usePathname()
return (
<span
className={[
' ',
!props.title && 'capitalize',
props.url === pathname ? 'text-brand-link' : 'hover:text-brand-link text-foreground',
].join(' ')}
>
{props.title ?? props.id}
</span>
)
})
const ContentAccordionLink = React.memo(function ContentAccordionLink(props: any) {
const pathname = usePathname()
const { resolvedTheme } = useTheme()
const activeItem = props.subItem.url === pathname
const activeItemRef = useRef<HTMLLIElement>(null)
const hasChildren = props.subItem.items && props.subItem.items.length > 0
const isChildActive =
hasChildren &&
props.subItem.items.some((child: NavAccordionItem) => hasActiveDescendant(child, pathname))
const LinkContainer = (props) => {
const isExternal = props.url.startsWith('https://')
return (
<Link
href={props.url}
className={props.className}
target={isExternal ? '_blank' : undefined}
rel={isExternal ? 'noopener noreferrer' : undefined}
>
{props.children}
</Link>
)
}
useEffect(() => {
// scroll to active item
if (activeItem && activeItemRef.current) {
// this is a hack, but seems a common one on Stackoverflow
setTimeout(() => {
activeItemRef.current?.scrollIntoView({ behavior: 'smooth', block: 'nearest' })
}, 0)
}
})
return (
<li ref={!hasChildren && activeItem ? activeItemRef : null}>
{hasChildren ? (
<Accordion.Root
collapsible
type="single"
className="space-y-0.5"
defaultValue={isChildActive ? props.subItem.url : undefined}
>
<Accordion.Item key={props.subItem.url || props.subItem.name} value={props.subItem.url}>
<Accordion.Trigger
className={[
'flex items-center gap-2 w-full',
'cursor-pointer transition text-sm',
activeItem
? 'text-brand-link font-medium'
: 'hover:text-foreground text-foreground-lighter',
].join(' ')}
>
<span className="flex items-center justify-between w-full">
<div className="flex items-center gap-2">
{props.subItem.icon && (
<Image
alt={props.subItem.name}
src={`${props.subItem.icon}${!resolvedTheme?.includes('dark') ? '-light' : ''}.svg`}
width={15}
height={15}
/>
)}
{props.subItem.name}
</div>
<ChevronDown className="w-4 h-4 transition-transform data-open-parent:rotate-180" />
</span>
</Accordion.Trigger>
<Accordion.Content className="transition data-open:animate-slide-down data-closed:animate-slide-up ml-2">
<ul>
{props.subItem.items
.filter((subItem) => subItem.enabled !== false)
.map((subSubItem) => {
if (subSubItem.items && subSubItem.items.length > 0) {
return <ContentAccordionLink key={subSubItem.name} subItem={subSubItem} />
}
return (
<li key={`${props.subItem.name}-${subSubItem.url}`}>
<Link
href={`${subSubItem.url}`}
className={[
'cursor-pointer transition text-sm',
subSubItem.url === pathname
? 'text-brand-link'
: 'hover:text-brand-link text-foreground-lighter',
].join(' ')}
>
{subSubItem.name}
</Link>
</li>
)
})}
</ul>
</Accordion.Content>
</Accordion.Item>
</Accordion.Root>
) : (
<LinkContainer
url={props.subItem.url}
className={[
'flex items-center gap-2',
'cursor-pointer transition text-sm',
activeItem
? 'text-brand-link font-medium'
: 'hover:text-foreground text-foreground-lighter',
].join(' ')}
parent={props.subItem.parent}
>
<div className="flex items-center gap-2">
{props.subItem.icon && (
<Image
alt={props.subItem.name}
src={`${props.subItem.icon}${!resolvedTheme?.includes('dark') ? '-light' : ''}.svg`}
width={15}
height={15}
/>
)}
{props.subItem.name}
</div>
</LinkContainer>
)}
</li>
)
})
const ContentLink = React.memo(function ContentLink(props: any) {
const pathname = usePathname()
return (
<li className="mb-1.5">
<Link
href={props.url}
className={[
'cursor-pointer transition text-sm',
props.url === pathname
? 'text-brand-link'
: 'hover:text-foreground text-foreground-lighter',
].join(' ')}
>
{props.icon && (
<Image alt={props.icon} width={12} height={12} src={`${pathname}${props.icon}`} />
)}
{props.name}
</Link>
</li>
)
})
const Content = (props) => {
const { menu, id } = props
if (menu.enabled === false) {
return null
}
return (
<div className="relative w-full flex flex-col gap-0 pb-5">
<Link href={menu.url ?? ''}>
<div className="flex items-center gap-3 my-3 text-brand-link">
<MenuIconPicker icon={menu.icon} />
<HeaderLink title={menu.title} url={menu.url} id={id} />
</div>
</Link>
<ul data-testid="docs-guide-navigation-list" className="flex flex-col gap-0">
{menu.items.map((x) => {
if (x.enabled === false) return null
if (x.items && x.items.length > 0) {
const enabledItems = x.items.filter((item) => item.enabled !== false)
if (enabledItems.length === 0) return null
return (
<li key={x.name}>
<div className="flex flex-col gap-2.5">
<div className="h-px w-full bg-border my-3"></div>
<span className="font-mono text-xs uppercase text-foreground font-medium tracking-wider">
{x.name}
</span>
<ul className="flex flex-col gap-2.5">
{enabledItems.map((subItem) => {
return <ContentAccordionLink key={subItem.name} subItem={subItem} />
})}
</ul>
</div>
</li>
)
}
return x.url ? <ContentLink url={x.url} icon={x.icon} name={x.name} key={x.name} /> : null
})}
</ul>
</div>
)
}
export default React.memo(Content)