Fix: highlight a TOC link entry when on the page or section it points to (RND-11155)

.changeset/toc-link-active-highlight.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Highlight a table-of-contents link entry as active when it points to the page — or the section of a page — you are currently viewing.

packages/gitbook/src/components/TableOfContents/PageLinkItem.tsx

@@ -3,6 +3,7 @@
 import { SiteInsightsLinkPosition } from '@gitbook/api';
 import { Icon } from '@gitbook/icons';
 
+import { useCurrentPagePath, useHash } from '../hooks';
 import type { ClientTOCPageLink } from './encodeClientTableOfContents';
 import { TOCPageIcon } from './TOCPageIcon';
 import { Link } from '@/components/primitives';
@@ -13,11 +14,24 @@ export function PageLinkItem(props: { page: ClientTOCPageLink }) {
 
     const isExternal = page.target.kind === 'url';
 
+    const currentPagePath = useCurrentPagePath();
+    const hash = useHash();
+    const isOnTargetPage =
+        page.pathnames?.some((pathname) => pathname === currentPagePath) ?? false;
+    // A link to a section only lights up once the reader is at that section, so sibling links
+    // pointing at other sections of the same page don't all highlight together.
+    const isActive = isOnTargetPage && (!page.anchor || page.anchor === hash);
+
     return (
         <li className="page-link-item flex flex-col [.page-group-item+&]:mt-4">
             <Link
                 href={page.href ?? '#'}
-                classNames={['ToCLinkItemStyles']}
+                data-active={isActive}
+                aria-current={isActive ? 'page' : undefined}
+                classNames={[
+                    'ToCLinkItemStyles',
+                    ...(isActive ? ['ToCLinkItemActiveStyles' as const] : []),
+                ]}
                 insights={{
                     type: 'link_click',
                     link: {

packages/gitbook/src/components/TableOfContents/encodeClientTableOfContents.ts

@@ -18,6 +18,10 @@ export type ClientTOCPageLink = {
     emoji?: string;
     icon?: string;
     target: ContentRef;
+    /** Paths of the page this link points to, when it resolves to a page in the current space. */
+    pathnames?: string[];
+    /** Anchor the link points to on that page, when the target is a section of it. */
+    anchor?: string;
 };
 
 export type ClientTOCPageDocument = {
@@ -96,6 +100,15 @@ export async function encodeClientTableOfContents(
             }
             case 'link': {
                 const resolved = await resolveContentRef(page.target, context);
+                // Links to a page (or a section of one) in the current space compute their active
+                // state the same way page entries do. Cross-space and external targets are left out
+                // to avoid over-highlighting.
+                const targetPage =
+                    (page.target.kind === 'page' || page.target.kind === 'anchor') &&
+                    resolved?.page &&
+                    resolved.space?.id === context.space.id
+                        ? resolved.page
+                        : undefined;
                 result.push(
                     removeUndefined({
                         id: page.id,
@@ -104,6 +117,13 @@ export async function encodeClientTableOfContents(
                         emoji: page.emoji,
                         icon: page.icon,
                         target: page.target,
+                        pathnames: targetPage
+                            ? getSiteSpacePagePaths(context.siteSpace, rootPages, targetPage)
+                            : undefined,
+                        anchor:
+                            targetPage && page.target.kind === 'anchor'
+                                ? page.target.anchor
+                                : undefined,
                         type: 'link',
                     })
                 );