Toolkit accessibility/usability fixes

mdx-components.jsx

@@ -1,5 +1,4 @@
 import Image from "next/image";
-import DocsLayout from "@/components/docs-layout";
 import Heading from "@/components/heading";
 import CustomLink from "@/components/link";
 
@@ -18,7 +17,6 @@ export function useMDXComponents(components) {
 			/>
 		),
 		a: (props) => <CustomLink {...props} />,
-		wrapper: DocsLayout,
 		h1: (props) => <Heading level={1} {...props} />,
 		h2: (props) => <Heading level={2} {...props} />,
 		h3: (props) => <Heading level={3} {...props} />,

src/components/docs-breadcrumbs.jsx

@@ -55,7 +55,7 @@ export default function DocsBreadcrumbs({ routes }) {
 					) : (
 						<Link
 							key={index}
-							className="font-normal text-gray-500 no-underline transition duration-200 ease-in hover:text-white focus:text-white"
+							className="font-normal text-gray-400 no-underline transition duration-200 ease-in hover:text-white focus:text-white"
 							href={breadcrumb.route}
 							noDefaultStyles
 							aria-label={breadcrumb.title}

src/components/docs-layout.jsx

@@ -55,17 +55,27 @@ export default function DocumentPage({ children, metadata }) {
 					<DocsNav
 						className="container-main h-screen max-h-screen overflow-y-scroll"
 						routes={routes}
+						isMobileMenu
 					/>
 				</DisclosurePanel>
 			</Disclosure>
-			<main className="relative mx-auto flex max-w-full grid-cols-[1fr_auto_1fr] flex-col gap-6 md:grid">
+			<main
+				id="main-content"
+				className="relative mx-auto flex max-w-full grid-cols-[1fr_auto_1fr] flex-col gap-6 md:grid"
+			>
 				<nav className="custom-scrollbar sticky top-[84px] hidden h-[calc(100vh-84px)] w-64 overflow-y-auto p-4 md:block">
+					<a href="#docs-article" className="faust-skip-link">
+						Skip navigation
+					</a>
 					<DocsNav routes={routes} />
 				</nav>
 				<nav className="sticky top-[84px] order-last hidden h-[calc(100vh-84px)] w-[240px] overflow-y-auto p-6 lg:block">
 					<OnThisPageNav>{children}</OnThisPageNav>
 				</nav>
-				<article className="container-main xs:py-20 prose prose-invert min-h-[calc(100vh-120px)] max-w-full py-0 sm:max-w-[80ch] sm:py-20 md:py-8">
+				<article
+					id="docs-article"
+					className="container-main xs:py-20 prose prose-invert min-h-[calc(100vh-120px)] max-w-full py-0 sm:max-w-[80ch] sm:py-20 md:py-8"
+				>
 					<DocsBreadcrumbs routes={flatRoutes} />
 					{metadata?.title && (
 						<h1 className="article-title break-words">{metadata.title}</h1>

src/components/docs-nav.jsx

@@ -1,9 +1,13 @@
-import { Fragment } from "react";
+import { CloseButton } from "@headlessui/react";
 import Link from "@/components/link";
 import { normalizeHref, classNames } from "@/utils/strings";
 
-export default function DocsNav({ as, routes, level = 0, className }) {
-	const As = as || Fragment;
+export default function DocsNav({
+	isMobileMenu,
+	routes,
+	level = 0,
+	className,
+}) {
 	return (
 		<ul
 			className={classNames(className, "my-1", {
@@ -12,32 +16,42 @@ export default function DocsNav({ as, routes, level = 0, className }) {
 			data-doc-nav-level={level}
 		>
 			{routes.map((item) => (
-				<As key={item.title}>
-					<NavItem item={item} level={level} />
-				</As>
+				<NavItem
+					key={item.title}
+					item={item}
+					level={level}
+					isMobileMenu={isMobileMenu}
+				/>
 			))}
 		</ul>
 	);
 }
 
-function NavItem({ item, level, ...props }) {
+function NavItem({ item, level, isMobileMenu, ...props }) {
 	if (!item?.route) {
 		throw new Error("Item must have a route");
 	}
 
+	const Component = isMobileMenu ? CloseButton : Link;
+
 	return (
 		<li className="py-2 text-gray-400">
-			<Link
+			<Component
+				as={isMobileMenu ? Link : undefined}
 				data-doc-nav-level={level}
 				href={normalizeHref(item.route)}
 				noDefaultStyles
 				activeClassName="text-blue-500 active"
 				{...props}
 			>
 				{item.title}
-			</Link>
+			</Component>
 			{item.children && (
-				<DocsNav as="ul" level={level + 1} routes={item.children} />
+				<DocsNav
+					isMobileMenu={isMobileMenu}
+					level={level + 1}
+					routes={item.children}
+				/>
 			)}
 		</li>
 	);

src/components/footer.jsx

@@ -7,26 +7,26 @@ export default function Footer() {
 				<div className="grid grid-cols-1 gap-8 pt-14 sm:grid-cols-2 lg:grid-cols-3 lg:pt-24">
 					<FooterColumns />
 				</div>
-				<div className="mt-2 text-gray-500 lg:mt-24">
+				<div className="mt-2 text-gray-400 lg:mt-24">
 					<p>
 						Powered by{" "}
 						<Link
-							className="font-normal text-gray-300 no-underline"
+							className="font-normal text-gray-200 no-underline"
 							href="/"
 							noDefaultStyles
 						>
 							Faust.js
 						</Link>{" "}
 						&amp; WP Engine&apos;s{" "}
 						<Link
-							className="font-normal text-gray-300 no-underline"
+							className="font-normal text-gray-200 no-underline"
 							href="https://wpengine.com/headless-wordpress/"
 							noDefaultStyles
 						>
 							Headless platform
 						</Link>
 					</p>
-					<p className="text-gray-600">
+					<p className="text-gray-400">
 						&copy; 2013-{new Date().getFullYear()} WP Engine, Inc. All rights
 						reserved.
 					</p>

src/components/layout.jsx

@@ -13,6 +13,10 @@ export default function Layout({ children }) {
 		<div
 			className={`${inter.variable} font-inter flex min-h-screen flex-col selection:bg-purple-700`}
 		>
+			<a href="#main-content" className="faust-skip-link">
+				Skip to main content
+			</a>
+
 			<Header />
 			{children}
 			<Footer />

src/components/search-bar.jsx

@@ -138,7 +138,7 @@ export default function SearchBar({ setIsSearchOpen }) {
 				<MagnifyingGlassIcon className="h-6 w-6 text-gray-400 md:hidden" />
 				<span className="hidden md:inline">
 					<span className="pl-3">Search docs...</span>
-					<kbd className="ml-8 rounded-sm bg-gray-700 px-2 py-1 text-gray-400">
+					<kbd className="ml-8 rounded-sm bg-gray-700 px-2 py-1 text-gray-300">
 						⌘K
 					</kbd>
 				</span>

src/pages/404.jsx

@@ -1,4 +1,5 @@
 import CustomLink from "@/components/link";
+import Seo from "@/components/seo";
 
 export default function Custom404() {
 	const suggestions = [
@@ -12,7 +13,10 @@ export default function Custom404() {
 			className="p-16 text-center font-sans"
 			role="main"
 			aria-labelledby="page-title"
+			id="main-content"
 		>
+			<Seo title="Page not found" />
+
 			<h1 id="page-title" className="text-5xl text-white">
 				Oops! Lost in the Web...
 			</h1>

src/pages/_app.jsx

@@ -2,6 +2,7 @@ import { WordPressBlocksProvider } from "@faustwp/blocks";
 import { FaustProvider } from "@faustwp/core";
 import { useRouter } from "next/router";
 import { useEffect } from "react";
+import DocsLayout from "@/components/docs-layout";
 import Layout from "@/components/layout";
 import { logPageview } from "@/lib/gtag.js";
 import blocks from "@/wp-blocks";
@@ -11,6 +12,7 @@ import "@faustwp/core/dist/css/toolbar.css";
 
 export default function MyApp({ Component, pageProps }) {
 	const router = useRouter();
+	const isDocsRoute = router.pathname.startsWith("/docs");
 
 	// Record a Google Analytics pageview on route change
 	useEffect(() => {
@@ -27,7 +29,13 @@ export default function MyApp({ Component, pageProps }) {
 			{/*  eslint-disable-next-line unicorn/no-null */}
 			<WordPressBlocksProvider config={{ blocks, theme: null }}>
 				<Layout>
-					<Component {...pageProps} />
+					{isDocsRoute ? (
+						<DocsLayout metadata={pageProps.metadata}>
+							<Component {...pageProps} />
+						</DocsLayout>
+					) : (
+						<Component {...pageProps} />
+					)}
 				</Layout>
 			</WordPressBlocksProvider>
 		</FaustProvider>

src/pages/blog/index.jsx

@@ -83,7 +83,10 @@ export default function BlogIndex() {
 	};
 
 	return (
-		<main className="container-main container-max prose prose-invert prose-h2:mt-0 prose-h2:text-lg container px-8 py-14 lg:px-16 lg:py-24">
+		<main
+			id="main-content"
+			className="container-main container-max prose prose-invert prose-h2:mt-0 prose-h2:text-lg container px-8 py-14 lg:px-16 lg:py-24"
+		>
 			<Seo
 				title="News"
 				description="Faust.js blog feed with the latest news."
@@ -120,7 +123,7 @@ export default function BlogIndex() {
 				<div className="mt-8 flex justify-center">
 					<button
 						type="button"
-						className="flex items-center rounded-sm bg-purple-500 px-4 py-2 text-white transition ease-in-out hover:bg-purple-800"
+						className="flex items-center rounded-sm bg-purple-700 px-4 py-2 text-white transition ease-in-out hover:bg-purple-800"
 						onClick={loadMorePosts}
 						disabled={loadingMore}
 					>

src/pages/docs/explanation/deploy-your-app/index.mdx

@@ -14,7 +14,7 @@ Faust.js uses the `package.json` [engines field](https://docs.npmjs.com/cli/v9/c
 
 ## Building Your App
 
-Since Faust.js is built on top of Next.js, it shares the same build process. For details on how Next.js generates optimized production builds, refer to the [Next.js Build API](https://nextjs.org/docs/pages/building-your-application/deploying#nextjs-build-api) documentation. Additionally, you can explore the Headless Platform framework guide for Next.js apps [here](https://developers.wpengine.com/docs/atlas/framework-guides/next-js/next/).
+Since Faust.js is built on top of Next.js, it shares the same build process. For details on how Next.js generates optimized production builds, refer to the [Next.js Build API](<(https://nextjs.org/docs/pages/building-your-application/deploying#nextjs-build-api)>) documentation. Additionally, you can explore the Headless Platform [framework guide](https://developers.wpengine.com/docs/atlas/framework-guides/next-js/next/) for Next.js apps.
 
 ## Deploying to WP Engine's Headless Platform
 
@@ -29,7 +29,7 @@ The Headless Platform is the most effortless way to deploy a Faust.js app. Conne
 
 Deploy your Faust.js app and try for the [Headless Platform](https://wpengine.com/headless-wordpress/#form) for free!
 
-For further reference, please check out the Headless Platform framework guide docs on Deploying Next.js [here](https://developers.wpengine.com/docs/atlas/framework-guides/next-js/next/).
+For further reference, please check out the Headless Platform [framework guide](https://developers.wpengine.com/docs/atlas/framework-guides/next-js/next/) docs on Deploying Next.js.
 
 > [!NOTE]
 > If deploying from the WP Engine portal using your own repository (without beginning with a blueprint), you will need to set your environment variables manually. Learn how by taking a look at our [platform docs](https://developers.wpengine.com/docs/atlas/getting-started/deploy-from-existing-repo/#set-environment-variables-optional).

src/pages/docs/nav.json

@@ -15,6 +15,10 @@
 				"title": "Basic Setup",
 				"route": "/docs/how-to/basic-setup/"
 			},
+			{
+				"title": "Authentication",
+				"route": "/docs/how-to/authentication/"
+			},
 			{
 				"title": "Customize the Toolbar",
 				"route": "/docs/how-to/customize-the-toolbar/"
@@ -31,10 +35,6 @@
 				"title": "Custom Blocks",
 				"route": "/docs/how-to/custom-blocks/"
 			},
-			{
-				"title": "Authentication",
-				"route": "/docs/how-to/authentication/"
-			},
 			{
 				"title": "Post Previews",
 				"route": "/docs/how-to/post-previews/"

src/pages/global.css

@@ -147,7 +147,7 @@
 		@apply outline-teal-800;
 	}
 
-	:target {
+	:target:not(#main-content):not(#docs-article) {
 		@apply scroll-mt-[100px] bg-teal-600/50;
 		@apply animate-bounce motion-reduce:animate-none;
 	}
@@ -272,3 +272,25 @@ figcaption[data-language]::after {
 figure[data-rehype-pretty-code-figure] pre {
 	tab-size: 2;
 }
+
+/*
+* - Skip link for accessibility
+*/
+
+.faust-skip-link {
+	position: absolute;
+	width: 1px;
+	height: 1px;
+	top: -1px;
+	left: -1px;
+	overflow: hidden;
+}
+
+.faust-skip-link:focus {
+	position: static;
+	padding: calc(var(--spacing) * 2) 0;
+	width: auto;
+	height: auto;
+	text-align: center;
+	color: var(--color-blue-500);
+}

src/pages/index.jsx

@@ -12,7 +12,7 @@ import Seo from "@/components/seo";
 
 export default function Index() {
 	return (
-		<main>
+		<main id="main-content">
 			<Seo
 				title="Home"
 				description="The Next.js Headless Toolkit for WordPress."

src/pages/showcase/index.jsx

@@ -28,7 +28,10 @@ const showcases = [
 
 export default function Showcase() {
 	return (
-		<main className="container-main container-max prose prose-invert md:prose-lg lg:prose-xl prose-h1:mb-2 prose-h1:font-semibold prose-h1:leading-tight prose-img:my-0 container px-8 py-14 lg:px-16 lg:py-24">
+		<main
+			id="main-content"
+			className="container-main container-max prose prose-invert md:prose-lg lg:prose-xl prose-h1:mb-2 prose-h1:font-semibold prose-h1:leading-tight prose-img:my-0 container px-8 py-14 lg:px-16 lg:py-24"
+		>
 			<Seo
 				title="Showcase"
 				description="Sites powered by Faust.js."

src/wp-templates/page.jsx

@@ -1,15 +1,20 @@
 import { gql } from "@apollo/client";
+import { useRouter } from "next/router";
+import Seo from "@/components/seo";
 
 export default function Component(props) {
+	const { asPath } = useRouter();
+	const { title, content } = props.data?.page ?? { title: "" };
+
 	return (
 		<div className="mx-auto w-full max-w-5xl p-6">
-			<h1 className="mb-6 text-center text-4xl font-bold">
-				{props.data.page.title}
-			</h1>
+			<Seo title={title} url={asPath} />
+
+			<h1 className="mb-6 text-center text-4xl font-bold">{title}</h1>
 			<div
 				className="prose prose-lg prose-invert mx-auto"
 				// eslint-disable-next-line react/no-danger
-				dangerouslySetInnerHTML={{ __html: props.data.page.content }}
+				dangerouslySetInnerHTML={{ __html: content }}
 			/>
 		</div>
 	);