feat: add TOC to docs

Author: wangdicoder

apps/docs/src/components/table-of-contents/index.tsx

@@ -0,0 +1,61 @@
+import React from 'react';
+import { Anchor } from '@tiny-design/react';
+import { useHeadings, HeadingItem } from '../../hooks/use-headings';
+import './table-of-contents.scss';
+
+interface TocNode {
+  heading: HeadingItem;
+  children: HeadingItem[];
+}
+
+const buildTree = (headings: HeadingItem[]): TocNode[] => {
+  const tree: TocNode[] = [];
+  let current: TocNode | null = null;
+
+  for (const heading of headings) {
+    if (heading.level === 2) {
+      current = { heading, children: [] };
+      tree.push(current);
+    } else if (heading.level === 3) {
+      if (current) {
+        current.children.push(heading);
+      } else {
+        // h3 without a preceding h2 — treat as top-level
+        tree.push({ heading, children: [] });
+      }
+    }
+  }
+
+  return tree;
+};
+
+export const TableOfContents = (): React.ReactElement | null => {
+  const headings = useHeadings();
+
+  if (headings.length === 0) {
+    return null;
+  }
+
+  const tree = buildTree(headings);
+
+  return (
+    <div className="doc-toc">
+      <Anchor type="line" offsetTop={80}>
+        {tree.map((node) => (
+          <Anchor.Link
+            key={node.heading.id}
+            href={`#${node.heading.id}`}
+            title={node.heading.text}>
+            {node.children.map((child) => (
+              <Anchor.Link
+                key={child.id}
+                href={`#${child.id}`}
+                title={child.text}
+              />
+            ))}
+          </Anchor.Link>
+        ))}
+      </Anchor>
+    </div>
+  );
+};

apps/docs/src/components/table-of-contents/table-of-contents.scss

@@ -0,0 +1,15 @@
+@use '../../variables' as *;
+
+.doc-toc {
+  position: fixed;
+  top: 100px;
+  right: 20px;
+  width: 180px;
+  max-height: calc(100vh - 120px);
+  overflow-y: auto;
+  font-size: 13px;
+
+  @media (max-width: $size-xl) {
+    display: none;
+  }
+}

apps/docs/src/containers/components/index.tsx

@@ -4,6 +4,7 @@ import { getComponentMenu, RouterItem } from '../../routers';
 import { SidebarMenu } from '../../components/sidebar-menu';
 import { Layout, Loader, Divider } from '@tiny-design/react';
 import { DocFooter } from '../../components/doc-footer';
+import { TableOfContents } from '../../components/table-of-contents';
 import { useLocaleContext } from '../../context/locale-context';
 import ComponentOverview from './overview';
 
@@ -52,6 +53,7 @@ const ComponentsPage = (): React.ReactElement => {
           <Divider className="doc-container__divider" />
           <DocFooter routers={flattenedRouters} />
         </Content>
+        <TableOfContents />
       </Layout>
     </Layout>
   );

apps/docs/src/containers/guide/index.tsx

@@ -4,6 +4,7 @@ import { getGuideMenu } from '../../routers';
 import { SidebarMenu } from '../../components/sidebar-menu';
 import { Layout, Loader, Divider } from '@tiny-design/react';
 import { DocFooter } from '../../components/doc-footer';
+import { TableOfContents } from '../../components/table-of-contents';
 import { useLocaleContext } from '../../context/locale-context';
 
 const { Content } = Layout;
@@ -41,6 +42,7 @@ const GuidePage = (): React.ReactElement => {
           <Divider className="doc-container__divider" />
           <DocFooter routers={guideMenu} />
         </Content>
+        <TableOfContents />
       </Layout>
     </Layout>
   );

apps/docs/src/containers/theme/index.tsx

@@ -4,6 +4,7 @@ import { getThemeMenu } from '../../routers';
 import { SidebarMenu } from '../../components/sidebar-menu';
 import { Layout, Loader, Divider } from '@tiny-design/react';
 import { DocFooter } from '../../components/doc-footer';
+import { TableOfContents } from '../../components/table-of-contents';
 import { useLocaleContext } from '../../context/locale-context';
 
 const { Content } = Layout;
@@ -41,6 +42,7 @@ const ThemePage = (): React.ReactElement => {
           <Divider className="doc-container__divider" />
           <DocFooter routers={themeMenu} />
         </Content>
+        <TableOfContents />
       </Layout>
     </Layout>
   );

apps/docs/src/hooks/use-headings.ts

@@ -0,0 +1,51 @@
+import { useState, useEffect } from 'react';
+import { useLocation } from 'react-router-dom';
+
+export interface HeadingItem {
+  id: string;
+  text: string;
+  level: 2 | 3;
+}
+
+const queryHeadings = (): HeadingItem[] => {
+  const elements = document.querySelectorAll('.markdown h2[id], .markdown h3[id]');
+  return Array.from(elements).map((el) => ({
+    id: el.id,
+    text: el.textContent?.replace(/\s*#$/, '') ?? '',
+    level: (el.tagName === 'H2' ? 2 : 3) as 2 | 3,
+  }));
+};
+
+export const useHeadings = (): HeadingItem[] => {
+  const { pathname } = useLocation();
+  const [headings, setHeadings] = useState<HeadingItem[]>([]);
+
+  useEffect(() => {
+    setHeadings([]);
+
+    // Try immediately in case content is already rendered
+    const initial = queryHeadings();
+    if (initial.length > 0) {
+      setHeadings(initial);
+      return;
+    }
+
+    // Otherwise observe DOM changes until headings appear
+    const container = document.querySelector('.doc-container__layout');
+    if (!container) return;
+
+    const observer = new MutationObserver(() => {
+      const found = queryHeadings();
+      if (found.length > 0) {
+        setHeadings(found);
+        observer.disconnect();
+      }
+    });
+
+    observer.observe(container, { childList: true, subtree: true });
+
+    return () => observer.disconnect();
+  }, [pathname]);
+
+  return headings;
+};

apps/docs/src/index.scss

@@ -27,9 +27,13 @@ body {
   }
 
   &__layout {
-    padding: 30px 30px 30px 280px;
+    padding: 30px 230px 30px 280px;
     overflow-x: hidden;
 
+    @media (max-width: $size-xl) {
+      padding: 30px 30px 30px 280px;
+    }
+
     @media (max-width: $size-md) {
       padding: 20px 16px;
     }

packages/react/src/anchor/anchor.tsx

@@ -71,9 +71,12 @@ const Anchor = (props: AnchorProps): JSX.Element => {
         const container = getContainer();
         const containerRect = container.getBoundingClientRect();
         const elementRect = element.getBoundingClientRect();
-        container.scrollTop += elementRect.top - containerRect.top;
+        container.scrollTo({
+          top: container.scrollTop + elementRect.top - containerRect.top,
+          behavior: 'smooth',
+        });
       } else {
-        element.scrollIntoView(true);
+        element.scrollIntoView({ behavior: 'smooth', block: 'start' });
       }
     },
     [getContainer]
@@ -117,10 +120,24 @@ const Anchor = (props: AnchorProps): JSX.Element => {
       ? container.getBoundingClientRect().top
       : 0;
 
+    // Check if scrolled to the bottom
+    let isAtBottom = false;
+    if (container) {
+      isAtBottom = container.scrollTop + container.clientHeight >= container.scrollHeight - 1;
+    } else {
+      isAtBottom =
+        window.innerHeight + window.scrollY >= document.documentElement.scrollHeight - 1;
+    }
+
     let newActiveId = '';
     let maxTop = -Infinity;
     let firstId = '';
     let firstTop = Infinity;
+    // Track the last heading visible in the viewport (for bottom-of-page case)
+    let lastVisibleId = '';
+    let lastVisibleTop = -Infinity;
+    const viewportHeight = container ? container.clientHeight : window.innerHeight;
+
     links.forEach((href) => {
       const id = href.replace('#', '');
       const el = document.getElementById(id);
@@ -134,8 +151,17 @@ const Anchor = (props: AnchorProps): JSX.Element => {
         maxTop = elTop;
         newActiveId = id;
       }
+      // Track headings visible in the viewport
+      if (elTop >= 0 && elTop <= viewportHeight && elTop > lastVisibleTop) {
+        lastVisibleTop = elTop;
+        lastVisibleId = id;
+      }
     });
-    if (!newActiveId && firstId) {
+
+    // When scrolled to the bottom, use the last visible heading
+    if (isAtBottom && lastVisibleId) {
+      newActiveId = lastVisibleId;
+    } else if (!newActiveId && firstId) {
       newActiveId = firstId;
     }
 

packages/react/src/layout/sidebar.tsx

@@ -20,6 +20,7 @@ const Sidebar = React.forwardRef<HTMLDivElement, SidebarProps>(
       className,
       style,
       children,
+      collapsed: _collapsed,
       prefixCls: customisedCls,
       ...otherProps
     } = props;