Skip to content

Commit ea58b71

Browse files
fix: make community navigation accessible on mobile (#1445)
Add an accessible mobile community navigation dialog with focus restoration and route-aware dismissal. Simplify desktop sidebar props and preserve the existing navigation categories.
1 parent 8907667 commit ea58b71

8 files changed

Lines changed: 298 additions & 37 deletions

File tree

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
open Vitest
2+
3+
@module("vitest/browser") @scope("userEvent")
4+
external keyboard: string => promise<unit> = "keyboard"
5+
6+
@send external toHaveFocus: element => promise<unit> = "toHaveFocus"
7+
8+
let categories: array<SidebarNav.Category.t> = [
9+
{
10+
name: "Resources",
11+
items: [
12+
{name: "Overview", href: "/community/overview"},
13+
{name: "Code of Conduct", href: "/community/code-of-conduct"},
14+
],
15+
},
16+
]
17+
18+
let entries: array<TableOfContents.entry> = [
19+
{header: "Official Channels", href: "#official-channels"},
20+
]
21+
22+
module CurrentPage = {
23+
@react.component
24+
let make = () => {
25+
let {pathname} = ReactRouter.useLocation()
26+
<div dataTestId="current-page"> {React.string((pathname :> string))} </div>
27+
}
28+
}
29+
30+
module Redirect = {
31+
@module("react-router") @react.component
32+
external make: (~to: string) => React.element = "Navigate"
33+
}
34+
35+
let community = (~redirect=false, ()) =>
36+
<React.StrictMode>
37+
<ReactRouter.MemoryRouter initialEntries=["/community/overview"]>
38+
{redirect ? <Redirect to="/community/code-of-conduct" /> : React.null}
39+
<CommunityLayout categories entries>
40+
<div>
41+
<CurrentPage />
42+
<h2 id="official-channels"> {React.string("Official channels content")} </h2>
43+
</div>
44+
</CommunityLayout>
45+
</ReactRouter.MemoryRouter>
46+
</React.StrictMode>
47+
48+
let renderCommunity = () => render(community())
49+
50+
test("mobile community navigation opens and closes", async () => {
51+
await viewport(390, 844)
52+
let screen = await renderCommunity()
53+
let trigger = await screen->getByText("Community navigation")
54+
let dialog = await screen->getByTestId("community-mobile-sidebar")
55+
56+
await element(trigger)->toBeVisible
57+
await element(trigger)->toHaveAttribute("aria-expanded", "false")
58+
await element(dialog)->notToBeInTheDocument
59+
await trigger->click
60+
61+
await element(trigger)->toHaveAttribute("aria-expanded", "true")
62+
await element(dialog)->toBeVisible
63+
let resources = await dialog->getByText("Resources")
64+
await element(resources)->toBeVisible
65+
let close = await dialog->getByLabelText("Close community navigation")
66+
await close->click
67+
await element(dialog)->notToBeInTheDocument
68+
await element(trigger)->toHaveAttribute("aria-expanded", "false")
69+
await element(trigger)->toHaveFocus
70+
})
71+
72+
test("Escape closes community navigation and returns focus to the opener", async () => {
73+
await viewport(390, 844)
74+
let screen = await renderCommunity()
75+
let trigger = await screen->getByText("Community navigation")
76+
let dialog = await screen->getByTestId("community-mobile-sidebar")
77+
await trigger->click
78+
await element(dialog)->toBeVisible
79+
80+
await keyboard("{Escape}")
81+
await element(dialog)->notToBeInTheDocument
82+
await element(trigger)->toHaveAttribute("aria-expanded", "false")
83+
await element(trigger)->toHaveFocus
84+
})
85+
86+
test("community page links close the drawer, including the current page link", async () => {
87+
await viewport(390, 844)
88+
let screen = await renderCommunity()
89+
let trigger = await screen->getByText("Community navigation")
90+
let dialog = await screen->getByTestId("community-mobile-sidebar")
91+
await trigger->click
92+
let link = await dialog->getByText("Code of Conduct")
93+
await link->click
94+
95+
let currentPage = await screen->getByTestId("current-page")
96+
await element(currentPage)->toHaveTextContent("/community/code-of-conduct")
97+
await element(dialog)->notToBeInTheDocument
98+
99+
await trigger->click
100+
let currentPageLink = await dialog->getByText("Code of Conduct")
101+
await currentPageLink->click
102+
await element(dialog)->notToBeInTheDocument
103+
})
104+
105+
test("community table of contents links close the mobile drawer", async () => {
106+
await viewport(390, 844)
107+
let screen = await renderCommunity()
108+
let trigger = await screen->getByText("Community navigation")
109+
let dialog = await screen->getByTestId("community-mobile-sidebar")
110+
await trigger->click
111+
let tocLink = await dialog->getByText("Official Channels")
112+
await tocLink->click
113+
await element(dialog)->notToBeInTheDocument
114+
})
115+
116+
test(
117+
"desktop community navigation stays visible and resizing dismisses an open drawer",
118+
async () => {
119+
await viewport(390, 844)
120+
let screen = await renderCommunity()
121+
let trigger = await screen->getByText("Community navigation")
122+
let dialog = await screen->getByTestId("community-mobile-sidebar")
123+
await trigger->click
124+
await element(dialog)->toBeVisible
125+
126+
await viewport(900, 900)
127+
await element(dialog)->notToBeInTheDocument
128+
await element(trigger)->notToBeVisible
129+
let resources = await screen->getByText("Resources")
130+
await element(resources)->toBeVisible
131+
132+
await viewport(390, 844)
133+
await element(trigger)->toBeVisible
134+
await element(trigger)->toHaveAttribute("aria-expanded", "false")
135+
},
136+
)
137+
138+
test("rerendering community layout preserves the open dialog and keyboard focus", async () => {
139+
await viewport(390, 844)
140+
let screen = await renderCommunity()
141+
let trigger = await screen->getByText("Community navigation")
142+
let dialog = await screen->getByTestId("community-mobile-sidebar")
143+
await trigger->click
144+
await element(dialog)->toBeVisible
145+
await keyboard("{Tab}")
146+
let overview = await dialog->getByText("Overview")
147+
await element(overview)->toHaveFocus
148+
149+
await screen->rerender(community())
150+
await element(dialog)->toBeVisible
151+
await element(overview)->toHaveFocus
152+
})
153+
154+
test("route changes outside the drawer reset mobile navigation", async () => {
155+
await viewport(390, 844)
156+
let screen = await renderCommunity()
157+
let trigger = await screen->getByText("Community navigation")
158+
let dialog = await screen->getByTestId("community-mobile-sidebar")
159+
await trigger->click
160+
await element(dialog)->toBeVisible
161+
162+
await screen->rerender(community(~redirect=true, ()))
163+
let currentPage = await screen->getByTestId("current-page")
164+
await element(currentPage)->toHaveTextContent("/community/code-of-conduct")
165+
await element(dialog)->notToBeInTheDocument
166+
await element(trigger)->toHaveAttribute("aria-expanded", "false")
167+
await trigger->click
168+
await element(dialog)->toBeVisible
169+
})

‎apps/docs/__tests__/DocsLayoutBehavior_.test.res‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,3 +64,23 @@ test("docs layout marks the textual content for DocSearch crawling", async () =>
6464

6565
expect(lvl0->textContent)->toBe("Manual")
6666
})
67+
68+
test("following a desktop docs link keeps the in-page sidebar hidden on mobile", async () => {
69+
await viewport(1440, 900)
70+
71+
let screen = await render(
72+
<MemoryRouter initialEntries=["/docs/manual/introduction"]>
73+
<DocsLayout categories=mockCategories>
74+
<div> {React.string("Documentation content")} </div>
75+
</DocsLayout>
76+
</MemoryRouter>,
77+
)
78+
79+
let sidebar = await screen->getByTestId("sidebar-content")
80+
await element(sidebar)->toBeVisible
81+
let installation = await sidebar->getByText("Installation")
82+
await installation->click
83+
84+
await viewport(390, 844)
85+
await element(sidebar)->notToBeVisible
86+
})
2.02 KB
Loading
Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
external elementToDialog: Dom.element => WebAPI.DOMAPI.htmlDialogElement = "%identity"
2+
3+
@react.component
4+
let make = (~categories: array<SidebarNav.Category.t>, ~activeToc, ~route) => {
5+
let currentRoute = route->Url.normalizePath
6+
let (isOpen, setOpen) = React.useState(_ => false)
7+
let close = () => setOpen(_ => false)
8+
9+
let attachDialog = React.useCallback(node => {
10+
switch node {
11+
| Nullable.Value(element) =>
12+
let dialog = element->elementToDialog
13+
let breakpoint = window->WebAPI.Window.matchMedia("(min-width: 768px)")
14+
let handleClose = _ => {
15+
// StrictMode can reopen the dialog before a cleanup's close event arrives.
16+
if !dialog.open_ {
17+
setOpen(_ => false)
18+
}
19+
}
20+
let handleBreakpointChange = _ => {
21+
if breakpoint.matches {
22+
setOpen(_ => false)
23+
}
24+
}
25+
dialog->WebAPI.HTMLDialogElement.addEventListener(Close, handleClose)
26+
breakpoint->WebAPI.MediaQueryList.addEventListener(Change, handleBreakpointChange)
27+
if breakpoint.matches {
28+
setOpen(_ => false)
29+
} else {
30+
dialog->WebAPI.HTMLDialogElement.showModal
31+
}
32+
Some(
33+
() => {
34+
dialog->WebAPI.HTMLDialogElement.removeEventListener(Close, handleClose)
35+
breakpoint->WebAPI.MediaQueryList.removeEventListener(Change, handleBreakpointChange)
36+
dialog->WebAPI.HTMLDialogElement.close
37+
},
38+
)
39+
| Nullable.Null | Nullable.Undefined => None
40+
}
41+
}, [setOpen])
42+
43+
<>
44+
<div className="md:hidden border-b border-gray-20 px-4">
45+
<button
46+
type_="button"
47+
className="flex items-center gap-3 h-12 text-14 font-medium text-gray-80"
48+
ariaControls=?{isOpen ? Some("community-mobile-sidebar") : None}
49+
ariaExpanded=isOpen
50+
onClick={_ => setOpen(_ => true)}
51+
>
52+
<img className="h-4" src="/ic_sidebar_drawer.svg" alt="" />
53+
{React.string("Community navigation")}
54+
</button>
55+
</div>
56+
{isOpen
57+
? <dialog
58+
ref={ReactDOM.Ref.callbackDomRef(attachDialog)}
59+
id="community-mobile-sidebar"
60+
dataTestId="community-mobile-sidebar"
61+
ariaLabel="Community navigation"
62+
onClick={event => {
63+
if event->ReactEvent.Mouse.target == event->ReactEvent.Mouse.currentTarget {
64+
close()
65+
}
66+
}}
67+
className="fixed inset-x-0 top-16 bottom-0 m-0 w-full max-w-none max-h-none h-[calc(100dvh-4rem)] bg-white px-4 py-4 overflow-y-auto backdrop:bg-gray-90/40"
68+
>
69+
<div className="flex items-center justify-between">
70+
<span className="text-16 font-medium"> {React.string("Community")} </span>
71+
<button
72+
type_="button"
73+
ariaLabel="Close community navigation"
74+
className="flex items-center justify-center h-12 w-12"
75+
onClick={_ => close()}
76+
>
77+
<Icon.Close />
78+
</button>
79+
</div>
80+
<nav ariaLabel="Community pages">
81+
{categories
82+
->Array.map(category =>
83+
<SidebarNav.Category
84+
key=category.name
85+
category
86+
isItemActive={item => item.href->Url.normalizePath === currentRoute}
87+
getActiveToc={item =>
88+
item.href->Url.normalizePath === currentRoute ? Some(activeToc) : None}
89+
onClick=close
90+
/>
91+
)
92+
->React.array}
93+
</nav>
94+
</dialog>
95+
: React.null}
96+
</>
97+
}

‎apps/docs/src/components/SidebarNav.res‎

Lines changed: 4 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@ module NavItem = {
7171
<Link.String
7272
to=m.href
7373
prefetch={#intent}
74+
onClick={_ => onClick()}
7475
className={"block py-1 md:h-auto tracking-tight text-gray-60 rounded-sm hover:bg-gray-20 hover:-ml-2 hover:py-1 hover:pl-2 " ++
7576
active}
7677
>
@@ -101,7 +102,7 @@ module Category = {
101102
~category: t,
102103
~getActiveToc=?,
103104
~isItemActive: option<NavItem.t => bool>=?,
104-
~onClick,
105+
~onClick=() => (),
105106
) =>
106107
<div key=category.name className="my-10">
107108
<Title> {React.string(category.name)} </Title>
@@ -118,8 +119,6 @@ let make = (
118119
~title as _: option<string>=?,
119120
~preludeSection=React.null,
120121
~activeToc: option<TableOfContents.t>=?,
121-
~isOpen: bool,
122-
~toggle: unit => unit,
123122
) => {
124123
let currentRoute = (route :> string)->Url.normalizePath
125124
let isItemActive = (navItem: NavItem.t) => navItem.href->Url.normalizePath === currentRoute
@@ -135,24 +134,13 @@ let make = (
135134
<>
136135
<div
137136
id="sidebar"
138-
className={(
139-
isOpen ? "fixed w-full left-0 h-full z-20 min-w-320" : "hidden "
140-
) ++ " md:block md:w-48 md:-ml-4 lg:w-1/5 h-auto md:relative overflow-y-visible bg-white md:mt-0 min-w-48"}
137+
className="hidden md:block md:w-48 md:-ml-4 lg:w-1/5 h-auto md:relative overflow-y-visible bg-white md:mt-0 min-w-48"
141138
>
142139
<aside
143140
id="sidebar-content"
144141
dataTestId="sidebar-content"
145142
className="h-full relative top-0 px-4 w-full block md:top-40 md:sticky border-r border-gray-20 overflow-y-auto pb-24 max-h-[calc(100vh-10rem)] pt-8"
146143
>
147-
<button
148-
onClick={evt => {
149-
ReactEvent.Mouse.preventDefault(evt)
150-
toggle()
151-
}}
152-
className="md:hidden h-16 flex pt-2 right-4 absolute"
153-
>
154-
<Icon.Close />
155-
</button>
156144
<div className="flex justify-between" dataTestId="sidebar-toplevel-nav">
157145
<div className="w-3/4 md:w-full"> toplevelNav </div>
158146
</div>
@@ -167,7 +155,7 @@ let make = (
167155
{categories
168156
->Array.map(category => {
169157
<div key=category.name>
170-
<Category getActiveToc isItemActive category onClick=toggle />
158+
<Category getActiveToc isItemActive category />
171159
</div>
172160
})
173161
->React.array}

‎apps/docs/src/components/SidebarNav.resi‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ module Category: {
2424
~category: t,
2525
~getActiveToc: NavItem.t => option<TableOfContents.t>=?,
2626
~isItemActive: NavItem.t => bool=?,
27-
~onClick: unit => unit,
27+
~onClick: unit => unit=?,
2828
) => React.element
2929
}
3030

@@ -36,6 +36,4 @@ let make: (
3636
~title: string=?,
3737
~preludeSection: React.element=?,
3838
~activeToc: TableOfContents.t=?,
39-
~isOpen: bool,
40-
~toggle: unit => unit,
4139
) => React.element

‎apps/docs/src/layouts/CommunityLayout.res‎

Lines changed: 5 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -11,19 +11,14 @@ let make = (~children, ~categories, ~entries) => {
1111
->String.replaceAll("-", " ")
1212
->Util.String.capitalizeSentence
1313

14-
let (isSidebarOpen, setSidebarOpen) = React.useState(_ => false)
14+
let activeToc: TableOfContents.t = {title: "Overview", entries}
1515
<>
1616
<Meta title={`${activePage} | ReScript Community`} />
17+
<CommunityMobileSidebar
18+
key={(pathname :> string)} route={(pathname :> string)} categories activeToc
19+
/>
1720
<SidebarPageLayout
18-
sidebar={<SidebarNav
19-
categories
20-
isOpen={isSidebarOpen}
21-
route=pathname
22-
toggle={() => setSidebarOpen(prev => !prev)}
23-
activeToc={title: "Overview", entries}
24-
/>}
25-
sidebarState=(isSidebarOpen, setSidebarOpen)
26-
docSearchLvl0="Community"
21+
sidebar={<SidebarNav categories route=pathname activeToc />} docSearchLvl0="Community"
2722
>
2823
children
2924
</SidebarPageLayout>

0 commit comments

Comments
 (0)