Add breadcrumb navigation to page titles (#26)

Author: kylemclaren

cypress/e2e/features/code-tabs.cy.ts

@@ -37,9 +37,7 @@ describe('Code Tabs', () => {
       .within(() => {
         cy.get('[role="tab"]').then(($tabs) => {
           if ($tabs.length >= 2) {
-            // Get text of second tab
-            const tabText = $tabs[1].textContent;
-            // Click it
+            // Click second tab
             cy.wrap($tabs[1]).click();
           }
         });

src/components/PageTitle.astro

@@ -1,17 +1,23 @@
 ---
 import StarlightPageTitle from '@astrojs/starlight/components/PageTitle.astro';
 import CopyPageButton from './CopyPageButton.astro';
+import { ContentBreadcrumbs } from './react/Breadcrumbs';
+
+const currentPath = Astro.url.pathname;
+const sidebar = Astro.locals.starlightRoute?.sidebar ?? [];
 ---
 
-<div class="copy-page-row">
+<div class="page-nav-container">
+	<ContentBreadcrumbs client:load currentPath={currentPath} sidebar={sidebar} />
 	<CopyPageButton />
 </div>
 <StarlightPageTitle />
 
 <style>
-	.copy-page-row {
+	.page-nav-container {
 		display: flex;
-		justify-content: flex-end;
+		justify-content: space-between;
+		align-items: center;
 		margin-bottom: 0.5rem;
 	}
 </style>

src/components/react/Breadcrumbs.tsx

@@ -0,0 +1,97 @@
+'use client';
+
+import { Fragment } from 'react';
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from '@/components/ui/breadcrumb';
+
+type BreadcrumbData = { title: string; href: string };
+
+type SidebarEntry =
+  | { type: 'link'; label: string; href: string }
+  | { type: 'group'; label: string; entries: SidebarEntry[] };
+
+// Normalize paths to avoid mismatches due to trailing slashes
+function normalizePath(path: string) {
+  return path.endsWith('/') ? path : `${path}/`;
+}
+
+export function findBreadcrumbTrail(
+  sidebarEntry: SidebarEntry[],
+  targetPath: string,
+  includeCurrentPage: boolean,
+  trail: BreadcrumbData[] = [],
+): BreadcrumbData[] | null {
+  const normalizedTarget = normalizePath(targetPath);
+
+  for (const entry of sidebarEntry) {
+    if (entry.type === 'link') {
+      const normalizedHref = normalizePath(entry.href);
+      if (normalizedHref === normalizedTarget) {
+        const fullTrail = [...trail, { title: entry.label, href: entry.href }];
+        if (includeCurrentPage || fullTrail.length === 1) {
+          return fullTrail;
+        } else {
+          return fullTrail.slice(0, -1);
+        }
+      }
+    } else if (entry.type === 'group') {
+      const groupBreadcrumb: BreadcrumbData = { title: entry.label, href: '' };
+      const result = findBreadcrumbTrail(
+        entry.entries,
+        targetPath,
+        includeCurrentPage,
+        [...trail, groupBreadcrumb],
+      );
+      if (result) return result;
+    }
+  }
+
+  return null;
+}
+
+export function ContentBreadcrumbs({
+  currentPath,
+  sidebar,
+}: {
+  currentPath: string;
+  sidebar: SidebarEntry[];
+}) {
+  const breadcrumbs = findBreadcrumbTrail(sidebar, currentPath, true);
+
+  if (!breadcrumbs || breadcrumbs.length === 0) {
+    return null;
+  }
+
+  return (
+    <Breadcrumb>
+      <BreadcrumbList>
+        {breadcrumbs.map((crumb, index) => {
+          const isLast = index === breadcrumbs.length - 1;
+
+          return (
+            <Fragment key={crumb.title}>
+              {index > 0 && <BreadcrumbSeparator />}
+              <BreadcrumbItem>
+                {isLast ? (
+                  <BreadcrumbPage>{crumb.title}</BreadcrumbPage>
+                ) : crumb.href ? (
+                  <BreadcrumbLink href={crumb.href}>
+                    {crumb.title}
+                  </BreadcrumbLink>
+                ) : (
+                  <span className="text-muted-foreground">{crumb.title}</span>
+                )}
+              </BreadcrumbItem>
+            </Fragment>
+          );
+        })}
+      </BreadcrumbList>
+    </Breadcrumb>
+  );
+}

src/components/react/index.ts

@@ -9,6 +9,7 @@ export {
 export { APIBody, APIEndpoint } from './APIEndpoint';
 export { BillingCalculator } from './BillingCalculator';
 export { BillingFAQ } from './BillingFAQ';
+export { ContentBreadcrumbs } from './Breadcrumbs';
 export { Callout } from './Callout';
 export { CodeTabs, Snippet } from './CodeTabs';
 export { CopyPageButton } from './CopyPageButton';

src/components/ui/breadcrumb.tsx

@@ -0,0 +1,107 @@
+import { Slot } from '@radix-ui/react-slot';
+import { ChevronRight, MoreHorizontal } from 'lucide-react';
+import type * as React from 'react';
+
+import { cn } from '@/lib/utils';
+
+function Breadcrumb({ ...props }: React.ComponentProps<'nav'>) {
+  return <nav aria-label="breadcrumb" data-slot="breadcrumb" {...props} />;
+}
+
+function BreadcrumbList({ className, ...props }: React.ComponentProps<'ol'>) {
+  return (
+    <ol
+      data-slot="breadcrumb-list"
+      className={cn(
+        'text-muted-foreground flex flex-wrap items-center gap-1.5 text-sm break-words sm:gap-2.5',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function BreadcrumbItem({ className, ...props }: React.ComponentProps<'li'>) {
+  return (
+    <li
+      data-slot="breadcrumb-item"
+      className={cn('inline-flex items-center gap-1.5', className)}
+      {...props}
+    />
+  );
+}
+
+function BreadcrumbLink({
+  asChild,
+  className,
+  ...props
+}: React.ComponentProps<'a'> & {
+  asChild?: boolean;
+}) {
+  const Comp = asChild ? Slot : 'a';
+
+  return (
+    <Comp
+      data-slot="breadcrumb-link"
+      className={cn('hover:text-foreground transition-colors', className)}
+      {...props}
+    />
+  );
+}
+
+function BreadcrumbPage({ className, ...props }: React.ComponentProps<'span'>) {
+  return (
+    <span
+      data-slot="breadcrumb-page"
+      aria-current="page"
+      className={cn('text-foreground font-normal', className)}
+      {...props}
+    />
+  );
+}
+
+function BreadcrumbSeparator({
+  children,
+  className,
+  ...props
+}: React.ComponentProps<'li'>) {
+  return (
+    <li
+      data-slot="breadcrumb-separator"
+      role="presentation"
+      aria-hidden="true"
+      className={cn('[&>svg]:size-3.5', className)}
+      {...props}
+    >
+      {children ?? <ChevronRight />}
+    </li>
+  );
+}
+
+function BreadcrumbEllipsis({
+  className,
+  ...props
+}: React.ComponentProps<'span'>) {
+  return (
+    <span
+      data-slot="breadcrumb-ellipsis"
+      role="presentation"
+      aria-hidden="true"
+      className={cn('flex size-9 items-center justify-center', className)}
+      {...props}
+    >
+      <MoreHorizontal className="size-4" />
+      <span className="sr-only">More</span>
+    </span>
+  );
+}
+
+export {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+  BreadcrumbEllipsis,
+};