Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

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.tsx
index 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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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)