Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs: fix sidebar click gating and make position a visible row index
Kshitij Jhunjhunwalac0935ff3485f
diff --git a/docs/app/(home)/reference/(v31)/layout.tsx b/docs/app/(home)/reference/(v31)/layout.tsxindex cb42b31f6..267acfde8 100644--- a/docs/app/(home)/reference/(v31)/layout.tsx+++ b/docs/app/(home)/reference/(v31)/layout.tsx@@ -2,8 +2,18 @@ import { getReferenceSource } from '@/lib/source';import { DocsLayout } from 'fumadocs-ui/layouts/docs';import type { ReactNode } from 'react';import { prepareTree } from '@/lib/filter-api-version';-import { buildSidebarNavIndex } from '@/lib/sidebar-nav-index';+import { buildSidebarNavIndex, type SidebarNavIndex } from '@/lib/sidebar-nav-index';import { SidebarAnalytics } from '@/components/sidebar-analytics';+import type { Root } from 'fumadocs-core/page-tree';++// The reference tree is only reachable after an await, so it is memoized here+// rather than hoisted to module scope like the docs and examples sidebars.+let navIndex: SidebarNavIndex | undefined;++function getNavIndex(tree: Root): SidebarNavIndex {+ navIndex ??= buildSidebarNavIndex(tree);+ return navIndex;+}export default async function Layout({ children }: { children: ReactNode }) {const source = await getReferenceSource();@@ -31,7 +41,7 @@ export default async function Layout({ children }: { children: ReactNode }) {sidebar={{ collapsible: false, footer: null, tabs: false }}themeSwitch={{ enabled: false }}>- <SidebarAnalytics index={buildSidebarNavIndex(pageTree)} />+ <SidebarAnalytics index={getNavIndex(pageTree)} />{children}</DocsLayout>);diff --git a/docs/app/(home)/reference/v3/layout.tsx b/docs/app/(home)/reference/v3/layout.tsxindex 465afe415..a5b961c3c 100644--- a/docs/app/(home)/reference/v3/layout.tsx+++ b/docs/app/(home)/reference/v3/layout.tsx@@ -2,8 +2,18 @@ import { getReferenceSource } from '@/lib/source';import { DocsLayout } from 'fumadocs-ui/layouts/docs';import type { ReactNode } from 'react';import { prepareTree } from '@/lib/filter-api-version';-import { buildSidebarNavIndex } from '@/lib/sidebar-nav-index';+import { buildSidebarNavIndex, type SidebarNavIndex } from '@/lib/sidebar-nav-index';import { SidebarAnalytics } from '@/components/sidebar-analytics';+import type { Root } from 'fumadocs-core/page-tree';++// The reference tree is only reachable after an await, so it is memoized here+// rather than hoisted to module scope like the docs and examples sidebars.+let navIndex: SidebarNavIndex | undefined;++function getNavIndex(tree: Root): SidebarNavIndex {+ navIndex ??= buildSidebarNavIndex(tree);+ return navIndex;+}export default async function Layout({ children }: { children: ReactNode }) {const source = await getReferenceSource();@@ -17,7 +27,7 @@ export default async function Layout({ children }: { children: ReactNode }) {sidebar={{ collapsible: false, footer: null, tabs: false }}themeSwitch={{ enabled: false }}>- <SidebarAnalytics index={buildSidebarNavIndex(tree)} />+ <SidebarAnalytics index={getNavIndex(tree)} />{children}</DocsLayout>);diff --git a/docs/components/sidebar-analytics.tsx b/docs/components/sidebar-analytics.tsxindex 4c2fc3c13..8c3cf9be8 100644--- a/docs/components/sidebar-analytics.tsx+++ b/docs/components/sidebar-analytics.tsx@@ -16,9 +16,17 @@ export function SidebarAnalytics({ index }: { index: SidebarNavIndex }) {const posthog = usePostHog();useEffect(() => {- if (!posthog) return;+ // `usePostHog()` falls back to the module singleton when no provider is+ // mounted, so it is truthy even with no key — capturing on it would only+ // log "You must initialize PostHog before calling posthog.capture". Gate on+ // the same env var `components/posthog-provider.tsx` gates on; Next inlines it.+ if (!posthog || !process.env.NEXT_PUBLIC_POSTHOG_KEY) return;function handleClick(event: MouseEvent) {+ // `click` skips middle-click, which would drop every sidebar link opened+ // in a new tab while keeping the Cmd/Ctrl+click ones.+ if (event.type === 'auxclick' && event.button !== 1) return;+const target = event.target;if (!(target instanceof Element)) return;@@ -54,7 +62,11 @@ export function SidebarAnalytics({ index }: { index: SidebarNavIndex }) {}document.addEventListener('click', handleClick, true);- return () => document.removeEventListener('click', handleClick, true);+ document.addEventListener('auxclick', handleClick, true);+ return () => {+ document.removeEventListener('click', handleClick, true);+ document.removeEventListener('auxclick', handleClick, true);+ };}, [index, posthog]);return null;diff --git a/docs/lib/sidebar-nav-index.ts b/docs/lib/sidebar-nav-index.tsindex fe9076126..6d99f38b4 100644--- a/docs/lib/sidebar-nav-index.ts+++ b/docs/lib/sidebar-nav-index.ts@@ -19,7 +19,12 @@ export interface SidebarNavEntry {folder: string | null;/** 1 = top-level row, 2 = folder child, 3 = nested. */depth: number;- /** 1-based position within the group, in top-to-bottom sidebar order. */+ /**+ * 1-based position among sibling rows, counting only this level: a folder+ * occupies one row whether or not it is expanded, and its children get their+ * own 1..n sequence. Counting through folders instead would report a+ * collapsed folder's hidden children as rows the reader had to scroll past.+ */position: number;}@@ -32,53 +37,49 @@ function nodeText(name: ReactNode): string | null {return null;}-interface WalkState {- group: string | null;- position: number;-}-+/**+ * `group` and `position` are per-level locals, so a separator nested inside a+ * folder can only affect that folder's own children — it cannot reset the+ * counter or the heading for the folder's siblings.+ */function walkNodes(nodes: Node[],folder: string | null,depth: number,- state: WalkState,+ parentGroup: string | null,index: SidebarNavIndex): void {+ let group = parentGroup;+ let position = 0;+for (const node of nodes) {if (node.type === 'separator') {- state.group = nodeText(node.name);- state.position = 0;+ group = nodeText(node.name);+ position = 0;continue;}+ position += 1;+if (node.type === 'page') {- state.position += 1;- index[node.url] = { group: state.group, folder, depth, position: state.position };+ index[node.url] = { group, folder, depth, position };continue;}- const folderName = nodeText(node.name) ?? folder;+ const folderName = nodeText(node.name);- // A folder's index page is the folder's own row, so it keeps the folder's depth.+ // A folder's index page is reached by clicking the folder's own row, so it+ // keeps the folder's depth and position rather than its children's.if (node.index) {- state.position += 1;- index[node.index.url] = {- group: state.group,- folder: folderName,- depth,- position: state.position,- };+ index[node.index.url] = { group, folder: folderName, depth, position };}- // A separator nested in a folder must not leak into the folder's siblings.- const outerGroup = state.group;- walkNodes(node.children, folderName, depth + 1, state, index);- state.group = outerGroup;+ walkNodes(node.children, folderName, depth + 1, group, index);}}export function buildSidebarNavIndex(tree: Root): SidebarNavIndex {const index: SidebarNavIndex = {};- walkNodes(tree.children, null, 1, { group: null, position: 0 }, index);+ walkNodes(tree.children, null, 1, null, index);return index;}diff --git a/docs/tests/static/sidebar-nav-index.test.ts b/docs/tests/static/sidebar-nav-index.test.tsindex 750fa0d81..4022a06a6 100644--- a/docs/tests/static/sidebar-nav-index.test.ts+++ b/docs/tests/static/sidebar-nav-index.test.ts@@ -21,14 +21,14 @@ describe('buildSidebarNavIndex', () => {group: 'Core concepts',folder: 'Authentication',depth: 2,- position: expect.any(Number),+ position: 7,});expect(index['/docs/extending-sessions/shared-connections']).toEqual({group: 'Guides',folder: 'Extend sessions',depth: 2,- position: expect.any(Number),+ position: 3,});});@@ -37,7 +37,7 @@ describe('buildSidebarNavIndex', () => {group: 'Get Started',folder: null,depth: 1,- position: expect.any(Number),+ position: 2,});});@@ -46,15 +46,69 @@ describe('buildSidebarNavIndex', () => {group: 'Core concepts',folder: 'Authentication',depth: 1,- position: expect.any(Number),+ position: 3,});});- test('position increases down a group and resets at the next separator', () => {- expect(index['/docs/quickstart'].position).toBeGreaterThan(index['/docs'].position);+ test('position resets at the next separator', () => {+ expect(index['/docs'].position).toBe(1);+ expect(index['/docs/quickstart'].position).toBe(2);expect(index['/docs/how-composio-works'].position).toBe(1);});+ test("a folder's children start their own sequence", () => {+ expect(index['/docs/authentication/manually-authenticating'].position).toBe(1);+ expect(index['/docs/extending-sessions/proxy-execute'].position).toBe(1);+ });++ test('a folder counts as one row for its siblings', () => {+ // Authentication is row 3 in Core concepts and holds 7 children. Counting+ // through them would report Triggers as row 11 while it renders as row 4.+ expect(index['/docs/triggers'].position).toBe(4);+ expect(index['/docs/skills'].position).toBe(5);+ });++ test('nested folders restart the sequence at each level', () => {+ expect(index['/docs/providers/custom-providers']).toEqual({+ group: 'Get Started',+ folder: 'Custom providers',+ depth: 2,+ position: 12,+ });+ expect(index['/docs/providers/custom-providers/typescript'].position).toBe(1);+ });++ test('a separator nested in a folder does not leak into the folder siblings', () => {+ // No meta.json nests a separator today, but fumadocs allows it: the group+ // and the counter are per-level, so "Inner" and its numbering stay inside+ // the folder instead of resuming Outer's siblings mid-sequence.+ const nested = buildSidebarNavIndex({+ name: 'root',+ children: [+ { type: 'separator', name: 'Outer' },+ { type: 'page', name: 'First', url: '/a' },+ {+ type: 'folder',+ name: 'Folder',+ children: [+ { type: 'separator', name: 'Inner' },+ { type: 'page', name: 'Child', url: '/a/child' },+ ],+ },+ { type: 'page', name: 'Last', url: '/b' },+ ],+ });++ expect(nested['/a']).toEqual({ group: 'Outer', folder: null, depth: 1, position: 1 });+ expect(nested['/a/child']).toEqual({+ group: 'Inner',+ folder: 'Folder',+ depth: 2,+ position: 1,+ });+ expect(nested['/b']).toEqual({ group: 'Outer', folder: null, depth: 1, position: 3 });+ });+test('every page in the sidebar tree resolves to a non-null group', () => {const missing = flattenTree(source.pageTree.children).map(page => page.url)