Fix: highlight TOC link entry when on the page 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 you are currently viewing.

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

@@ -7,18 +7,27 @@ import { Link } from '@/components/primitives';
 import { tcls } from '@/lib/tailwind';
 
 import { SiteInsightsLinkPosition } from '@gitbook/api';
+import { useCurrentPagePath } from '../hooks';
 import { TOCPageIcon } from './TOCPageIcon';
 
 export function PageLinkItem(props: { page: ClientTOCPageLink }) {
     const { page } = props;
 
     const isExternal = page.target.kind === 'url';
 
+    const currentPagePath = useCurrentPagePath();
+    const isActive = page.pathnames?.some((pathname) => pathname === currentPagePath) ?? false;
+
     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

@@ -15,6 +15,8 @@ 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[];
 };
 
 export type ClientTOCPageDocument = {
@@ -93,6 +95,15 @@ export async function encodeClientTableOfContents(
             }
             case 'link': {
                 const resolved = await resolveContentRef(page.target, context);
+                // Highlight the link when it points to a page in the current space, matching how
+                // page entries compute their active state. Restricted to page targets (no anchors,
+                // no cross-space refs) to avoid over-highlighting.
+                const pathnames =
+                    page.target.kind === 'page' &&
+                    resolved?.page &&
+                    resolved.space?.id === context.space.id
+                        ? getPagePaths(rootPages, resolved.page)
+                        : undefined;
                 result.push(
                     removeUndefined({
                         id: page.id,
@@ -101,6 +112,7 @@ export async function encodeClientTableOfContents(
                         emoji: page.emoji,
                         icon: page.icon,
                         target: page.target,
+                        pathnames,
                         type: 'link',
                     })
                 );