Add 'Jump to' functionality to Braid Docs

packages/braid-design-system/src/lib/components/Divider/Divider.docs.tsx

@@ -19,6 +19,7 @@ const docs: ComponentDocs = {
       </Stack>,
     ),
   alternatives: [],
+  accessibility: [],
 };
 
 export default docs;

packages/docs-ui/src/components/HeaderNavigation/HeaderNavigation.css.ts

@@ -0,0 +1,8 @@
+import { style } from '@vanilla-extract/css';
+import { vars } from 'braid-design-system/css';
+
+export const searchButton = style({
+  ':hover': {
+    background: vars.backgroundColor.neutralSoft,
+  },
+});

packages/docs-ui/src/components/HeaderNavigation/HeaderNavigation.tsx

@@ -1,11 +1,24 @@
-import { Box, Hidden, HiddenVisually, Link, Text } from 'braid-design-system';
+import {
+  Bleed,
+  Box,
+  Hidden,
+  HiddenVisually,
+  IconSearch,
+  Link,
+  Stack,
+  Text,
+} from 'braid-design-system';
 import type { ReactNode } from 'react';
 
+import { KeyboardShortcut } from '../KeyboardShortcut/KeyboardShortcut';
 import { MenuButton } from '../MenuButton/MenuButton';
 
+import { searchButton } from './HeaderNavigation.css';
+
 interface HeaderNavigationProps {
   menuOpen?: boolean;
   menuClick?: () => void;
+  onSearchClick?: () => void;
   logo: ReactNode;
   logoLabel: string;
   logoHref?: string;
@@ -15,6 +28,7 @@ interface HeaderNavigationProps {
 export const HeaderNavigation = ({
   menuOpen = false,
   menuClick = () => {},
+  onSearchClick = () => {},
   logo,
   logoLabel,
   logoHref = '/',
@@ -41,6 +55,31 @@ export const HeaderNavigation = ({
         </Link>
       </Text>
     </Box>
-    {themeToggle}
+    <Stack space="none">
+      <Box>{themeToggle}</Box>
+      <Bleed horizontal="xxsmall" bottom="xxsmall">
+        <Box
+          component="button"
+          padding="xxsmall"
+          paddingRight="xsmall"
+          borderRadius="standard"
+          className={searchButton}
+          onClick={onSearchClick}
+        >
+          <KeyboardShortcut
+            keys={[
+              navigator.platform.startsWith('Mac') ||
+              navigator.platform === 'iPhone' ||
+              navigator.platform === 'iPad' ||
+              navigator.platform === 'iPod'
+                ? '⌘'
+                : 'Ctrl',
+              'K',
+            ]}
+            shortcutLabel={<IconSearch />}
+          />
+        </Box>
+      </Bleed>
+    </Stack>
   </Box>
 );

packages/docs-ui/src/components/KeyboardShortcut/KeyboardShortcut.tsx

@@ -0,0 +1,36 @@
+import { Box, Text } from 'braid-design-system';
+import type { ReactElement } from 'react';
+
+interface KeyboardShortcutProps {
+  keys: string[];
+  shortcutLabel: ReactElement | string;
+}
+
+export const KeyboardIcon = ({ children }: { children: React.ReactNode }) => (
+  <Box
+    display="flex"
+    padding="xxsmall"
+    background="neutralLight"
+    borderRadius="standard"
+    alignItems="center"
+    justifyContent="center"
+  >
+    <Text tone="secondary" size="xsmall">
+      {children}
+    </Text>
+  </Box>
+);
+
+export const KeyboardShortcut = ({
+  keys,
+  shortcutLabel,
+}: KeyboardShortcutProps) => (
+  <Box display="flex" alignItems="center" gap="xxsmall">
+    {keys.map((key) => (
+      <KeyboardIcon key={key}>{key}</KeyboardIcon>
+    ))}
+    <Text tone="secondary" size="xsmall">
+      {shortcutLabel}
+    </Text>
+  </Box>
+);

packages/docs-ui/src/index.ts

@@ -2,3 +2,7 @@ export { LinkableHeading } from './components/LinkableHeading/LinkableHeading';
 export { MenuButton } from './components/MenuButton/MenuButton';
 export { SideNavigationSection } from './components/SideNavigation/SideNavigationSection';
 export { HeaderNavigation } from './components/HeaderNavigation/HeaderNavigation';
+export {
+  KeyboardShortcut,
+  KeyboardIcon,
+} from './components/KeyboardShortcut/KeyboardShortcut';

site/src/App/CategoryHeading/CategoryHeading.tsx

@@ -0,0 +1,13 @@
+import { Box, Text } from 'braid-src/index';
+
+export const CategoryHeading = ({
+  children,
+}: {
+  children: React.ReactNode;
+}) => (
+  <Box style={{ textTransform: 'uppercase' }} component="li">
+    <Text size="xsmall" weight="medium" component="h2">
+      {children}
+    </Text>
+  </Box>
+);

site/src/App/DocNavigation/DocDetails.tsx

@@ -162,7 +162,7 @@ export const DocDetails = () => {
                 </PlayroomStateProvider>
               ) : null}
 
-              {'accessibility' in docs ? (
+              {'accessibility' in docs && docs.accessibility ? (
                 <Stack space={headingSpacing}>
                   <LinkableHeading level="3">Accessibility</LinkableHeading>
                   {docs.accessibility}
@@ -201,7 +201,7 @@ export const DocDetails = () => {
                 />
               ))}
 
-              {'alternatives' in docs ? (
+              {'alternatives' in docs && docs.alternatives.length > 0 ? (
                 <Stack space={headingSpacing}>
                   <LinkableHeading level="3">Alternatives</LinkableHeading>
                   <List space="medium">

site/src/App/JumpToModal/JumpToModal.tsx

@@ -0,0 +1,177 @@
+import {
+  Box,
+  Dialog,
+  TextField,
+  IconSearch,
+  Bleed,
+} from 'braid-src/lib/components';
+import { ScrollContainer } from 'braid-src/lib/components/private/ScrollContainer/ScrollContainer';
+import { useEffect, useRef, useState, useMemo } from 'react';
+import { useNavigate } from 'react-router';
+
+import { SearchResults } from './SearchResults';
+import {
+  getSearchItems,
+  groupSearchResults,
+  type SearchItem,
+} from './getSearchItems';
+
+interface JumpToModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+}
+
+export const JumpToModal = ({ isOpen, onClose }: JumpToModalProps) => {
+  const [searchQuery, setSearchQuery] = useState('');
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const resultsRef = useRef<HTMLElement>(null);
+  const navigate = useNavigate();
+
+  const searchItems = useMemo(() => getSearchItems(), []);
+
+  const filteredItems = useMemo(() => {
+    if (!searchQuery.trim()) {
+      return [];
+    }
+
+    const query = searchQuery.toLowerCase();
+    return searchItems.filter((item) =>
+      item.name.toLowerCase().includes(query),
+    );
+  }, [searchQuery, searchItems]);
+
+  const groupedResults = useMemo(
+    () => groupSearchResults(filteredItems),
+    [filteredItems],
+  );
+
+  const flatResults = useMemo(() => {
+    const results: SearchItem[] = [];
+    const categoryOrder = [
+      'Foundations',
+      'Components',
+      'CSS',
+      'Logic',
+    ] as const;
+
+    categoryOrder.forEach((category) => {
+      results.push(...groupedResults[category]);
+    });
+
+    return results;
+  }, [groupedResults]);
+
+  useEffect(() => {
+    if (isOpen) {
+      setSearchQuery('');
+      setSelectedIndex(0);
+      // Wait for Dialog animation to complete before focusing
+      const timer = setTimeout(() => {
+        inputRef.current?.focus();
+      }, 100);
+      return () => clearTimeout(timer);
+    }
+  }, [isOpen]);
+
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (!isOpen) {
+        return;
+      }
+
+      switch (e.key) {
+        case 'Escape':
+          onClose();
+          e.preventDefault();
+          break;
+        case 'ArrowDown':
+          e.preventDefault();
+          setSelectedIndex((prev) =>
+            flatResults.length === 0 ? 0 : (prev + 1) % flatResults.length,
+          );
+          break;
+        case 'ArrowUp':
+          e.preventDefault();
+          setSelectedIndex((prev) => {
+            if (flatResults.length === 0) {
+              return 0;
+            }
+            if (prev === 0) {
+              return flatResults.length - 1;
+            }
+            return prev - 1;
+          });
+          break;
+        case 'Enter':
+          if (flatResults[selectedIndex]) {
+            const selectedItem = flatResults[selectedIndex];
+            const targetPath =
+              e.shiftKey && selectedItem.hasProps
+                ? `${selectedItem.path}/props`
+                : selectedItem.path;
+            navigate(targetPath);
+            onClose();
+          }
+          e.preventDefault();
+          break;
+      }
+    };
+
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, [isOpen, flatResults, selectedIndex, navigate, onClose]);
+
+  // Scroll the selected item into view
+  useEffect(() => {
+    if (resultsRef.current && flatResults.length > 0) {
+      const selectedElement = resultsRef.current.querySelector(
+        `[data-index="${selectedIndex}"]`,
+      );
+      if (selectedElement) {
+        selectedElement.scrollIntoView({ block: 'nearest' });
+      }
+    }
+  }, [selectedIndex, flatResults.length]);
+
+  return (
+    <Dialog
+      open={isOpen}
+      onClose={onClose}
+      width="medium"
+      title="Jump to a page"
+      closeLabel="Close search"
+    >
+      <TextField
+        icon={<IconSearch />}
+        ref={inputRef}
+        label=""
+        placeholder="Jump to Foundations, Components, CSS, Logic..."
+        value={searchQuery}
+        onChange={(e) => {
+          setSearchQuery(e.target.value);
+          setSelectedIndex(0);
+        }}
+      />
+      <Bleed horizontal="large">
+        <ScrollContainer direction="vertical">
+          <Box ref={resultsRef} paddingY="small" style={{ height: '40vh' }}>
+            <Box paddingX="large" height="full">
+              <SearchResults
+                searchQuery={searchQuery}
+                groupedResults={groupedResults}
+                flatResults={flatResults}
+                selectedIndex={selectedIndex}
+                onSelectIndex={setSelectedIndex}
+                onNavigate={(path) => {
+                  navigate(path);
+                  onClose();
+                }}
+              />
+            </Box>
+          </Box>
+        </ScrollContainer>
+      </Bleed>
+    </Dialog>
+  );
+};