@devries-cameron20 / composio Mirror · read-only / commits / c0935ff34
Fork 0

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

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 16:00 UTC

docs: fix sidebar click gating and make position a visible row index

Review follow-ups on the docs_sidebar_click instrumentation. usePostHog() resolves to the posthog-js module singleton whether or not a provider is mounted, so the `!posthog` guard never fired: with no NEXT_PUBLIC_POSTHOG_KEY the listener still attached and every sidebar click called capture() on an uninitialized instance, logging "You must initialize PostHog before calling posthog.capture". Gate the effect on the same env var components/posthog-provider.tsx gates on. position threaded through folder recursion, so a collapsed folder's hidden children counted as rows: Triggers is the 4th visible row under Core concepts but reported 11, which would inflate any "clicks land in the top N rows" reading — the same inference error this instrumentation exists to remove. Count per level instead, so a folder occupies one row for its siblings and its children get their own 1..n sequence. Making group and position per-level locals also removes the latent collision where a separator nested in a folder reset the counter for the folder's siblings; a test pins that case. Also: capture auxclick (middle button only) so sidebar links opened in a new tab are not missing while Cmd/Ctrl+click ones are counted; a folder with a non-string name now reports folder: null rather than inheriting its parent's label; and both reference layouts memoize the index instead of rebuilding it on every render. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Kshitij Jhunjhunwala committed Aug 16, 2026 at 15:20 UTC c0935ff3485f52d04989cd609f72928db87c08e0
5 files changed +124 -37
docs/app/(home)/reference/(v31)/layout.tsx
+12 -2
@@ -2,8 +2,18 @@ import { getReferenceSource } from '@/lib/source';
2 import { DocsLayout } from 'fumadocs-ui/layouts/docs';
3 import type { ReactNode } from 'react';
4 import { prepareTree } from '@/lib/filter-api-version';
5 -import { buildSidebarNavIndex } from '@/lib/sidebar-nav-index';
5 +import { buildSidebarNavIndex, type SidebarNavIndex } from '@/lib/sidebar-nav-index';
6 import { SidebarAnalytics } from '@/components/sidebar-analytics';
7 +import type { Root } from 'fumadocs-core/page-tree';
8 +
9 +// The reference tree is only reachable after an await, so it is memoized here
10 +// rather than hoisted to module scope like the docs and examples sidebars.
11 +let navIndex: SidebarNavIndex | undefined;
12 +
13 +function getNavIndex(tree: Root): SidebarNavIndex {
14 + navIndex ??= buildSidebarNavIndex(tree);
15 + return navIndex;
16 +}
17
18 export default async function Layout({ children }: { children: ReactNode }) {
19 const source = await getReferenceSource();
@@ -31,7 +41,7 @@ export default async function Layout({ children }: { children: ReactNode }) {
41 sidebar={{ collapsible: false, footer: null, tabs: false }}
42 themeSwitch={{ enabled: false }}
43 >
34 - <SidebarAnalytics index={buildSidebarNavIndex(pageTree)} />
44 + <SidebarAnalytics index={getNavIndex(pageTree)} />
45 {children}
46 </DocsLayout>
47 );
docs/app/(home)/reference/v3/layout.tsx
+12 -2
@@ -2,8 +2,18 @@ import { getReferenceSource } from '@/lib/source';
2 import { DocsLayout } from 'fumadocs-ui/layouts/docs';
3 import type { ReactNode } from 'react';
4 import { prepareTree } from '@/lib/filter-api-version';
5 -import { buildSidebarNavIndex } from '@/lib/sidebar-nav-index';
5 +import { buildSidebarNavIndex, type SidebarNavIndex } from '@/lib/sidebar-nav-index';
6 import { SidebarAnalytics } from '@/components/sidebar-analytics';
7 +import type { Root } from 'fumadocs-core/page-tree';
8 +
9 +// The reference tree is only reachable after an await, so it is memoized here
10 +// rather than hoisted to module scope like the docs and examples sidebars.
11 +let navIndex: SidebarNavIndex | undefined;
12 +
13 +function getNavIndex(tree: Root): SidebarNavIndex {
14 + navIndex ??= buildSidebarNavIndex(tree);
15 + return navIndex;
16 +}
17
18 export default async function Layout({ children }: { children: ReactNode }) {
19 const source = await getReferenceSource();
@@ -17,7 +27,7 @@ export default async function Layout({ children }: { children: ReactNode }) {
27 sidebar={{ collapsible: false, footer: null, tabs: false }}
28 themeSwitch={{ enabled: false }}
29 >
20 - <SidebarAnalytics index={buildSidebarNavIndex(tree)} />
30 + <SidebarAnalytics index={getNavIndex(tree)} />
31 {children}
32 </DocsLayout>
33 );
docs/components/sidebar-analytics.tsx
+14 -2
@@ -16,9 +16,17 @@ export function SidebarAnalytics({ index }: { index: SidebarNavIndex }) {
16 const posthog = usePostHog();
17
18 useEffect(() => {
19 - if (!posthog) return;
19 + // `usePostHog()` falls back to the module singleton when no provider is
20 + // mounted, so it is truthy even with no key — capturing on it would only
21 + // log "You must initialize PostHog before calling posthog.capture". Gate on
22 + // the same env var `components/posthog-provider.tsx` gates on; Next inlines it.
23 + if (!posthog || !process.env.NEXT_PUBLIC_POSTHOG_KEY) return;
24
25 function handleClick(event: MouseEvent) {
26 + // `click` skips middle-click, which would drop every sidebar link opened
27 + // in a new tab while keeping the Cmd/Ctrl+click ones.
28 + if (event.type === 'auxclick' && event.button !== 1) return;
29 +
30 const target = event.target;
31 if (!(target instanceof Element)) return;
32
@@ -54,7 +62,11 @@ export function SidebarAnalytics({ index }: { index: SidebarNavIndex }) {
62 }
63
64 document.addEventListener('click', handleClick, true);
57 - return () => document.removeEventListener('click', handleClick, true);
65 + document.addEventListener('auxclick', handleClick, true);
66 + return () => {
67 + document.removeEventListener('click', handleClick, true);
68 + document.removeEventListener('auxclick', handleClick, true);
69 + };
70 }, [index, posthog]);
71
72 return null;
docs/lib/sidebar-nav-index.ts
+26 -25
@@ -19,7 +19,12 @@ export interface SidebarNavEntry {
19 folder: string | null;
20 /** 1 = top-level row, 2 = folder child, 3 = nested. */
21 depth: number;
22 - /** 1-based position within the group, in top-to-bottom sidebar order. */
22 + /**
23 + * 1-based position among sibling rows, counting only this level: a folder
24 + * occupies one row whether or not it is expanded, and its children get their
25 + * own 1..n sequence. Counting through folders instead would report a
26 + * collapsed folder's hidden children as rows the reader had to scroll past.
27 + */
28 position: number;
29 }
30
@@ -32,53 +37,49 @@ function nodeText(name: ReactNode): string | null {
37 return null;
38 }
39
35 -interface WalkState {
36 - group: string | null;
37 - position: number;
38 -}
39 -
40 +/**
41 + * `group` and `position` are per-level locals, so a separator nested inside a
42 + * folder can only affect that folder's own children — it cannot reset the
43 + * counter or the heading for the folder's siblings.
44 + */
45 function walkNodes(
46 nodes: Node[],
47 folder: string | null,
48 depth: number,
44 - state: WalkState,
49 + parentGroup: string | null,
50 index: SidebarNavIndex
51 ): void {
52 + let group = parentGroup;
53 + let position = 0;
54 +
55 for (const node of nodes) {
56 if (node.type === 'separator') {
49 - state.group = nodeText(node.name);
50 - state.position = 0;
57 + group = nodeText(node.name);
58 + position = 0;
59 continue;
60 }
61
62 + position += 1;
63 +
64 if (node.type === 'page') {
55 - state.position += 1;
56 - index[node.url] = { group: state.group, folder, depth, position: state.position };
65 + index[node.url] = { group, folder, depth, position };
66 continue;
67 }
68
60 - const folderName = nodeText(node.name) ?? folder;
69 + const folderName = nodeText(node.name);
70
62 - // A folder's index page is the folder's own row, so it keeps the folder's depth.
71 + // A folder's index page is reached by clicking the folder's own row, so it
72 + // keeps the folder's depth and position rather than its children's.
73 if (node.index) {
64 - state.position += 1;
65 - index[node.index.url] = {
66 - group: state.group,
67 - folder: folderName,
68 - depth,
69 - position: state.position,
70 - };
74 + index[node.index.url] = { group, folder: folderName, depth, position };
75 }
76
73 - // A separator nested in a folder must not leak into the folder's siblings.
74 - const outerGroup = state.group;
75 - walkNodes(node.children, folderName, depth + 1, state, index);
76 - state.group = outerGroup;
77 + walkNodes(node.children, folderName, depth + 1, group, index);
78 }
79 }
80
81 export function buildSidebarNavIndex(tree: Root): SidebarNavIndex {
82 const index: SidebarNavIndex = {};
82 - walkNodes(tree.children, null, 1, { group: null, position: 0 }, index);
83 + walkNodes(tree.children, null, 1, null, index);
84 return index;
85 }
docs/tests/static/sidebar-nav-index.test.ts
+60 -6
@@ -21,14 +21,14 @@ describe('buildSidebarNavIndex', () => {
21 group: 'Core concepts',
22 folder: 'Authentication',
23 depth: 2,
24 - position: expect.any(Number),
24 + position: 7,
25 });
26
27 expect(index['/docs/extending-sessions/shared-connections']).toEqual({
28 group: 'Guides',
29 folder: 'Extend sessions',
30 depth: 2,
31 - position: expect.any(Number),
31 + position: 3,
32 });
33 });
34
@@ -37,7 +37,7 @@ describe('buildSidebarNavIndex', () => {
37 group: 'Get Started',
38 folder: null,
39 depth: 1,
40 - position: expect.any(Number),
40 + position: 2,
41 });
42 });
43
@@ -46,15 +46,69 @@ describe('buildSidebarNavIndex', () => {
46 group: 'Core concepts',
47 folder: 'Authentication',
48 depth: 1,
49 - position: expect.any(Number),
49 + position: 3,
50 });
51 });
52
53 - test('position increases down a group and resets at the next separator', () => {
54 - expect(index['/docs/quickstart'].position).toBeGreaterThan(index['/docs'].position);
53 + test('position resets at the next separator', () => {
54 + expect(index['/docs'].position).toBe(1);
55 + expect(index['/docs/quickstart'].position).toBe(2);
56 expect(index['/docs/how-composio-works'].position).toBe(1);
57 });
58
59 + test("a folder's children start their own sequence", () => {
60 + expect(index['/docs/authentication/manually-authenticating'].position).toBe(1);
61 + expect(index['/docs/extending-sessions/proxy-execute'].position).toBe(1);
62 + });
63 +
64 + test('a folder counts as one row for its siblings', () => {
65 + // Authentication is row 3 in Core concepts and holds 7 children. Counting
66 + // through them would report Triggers as row 11 while it renders as row 4.
67 + expect(index['/docs/triggers'].position).toBe(4);
68 + expect(index['/docs/skills'].position).toBe(5);
69 + });
70 +
71 + test('nested folders restart the sequence at each level', () => {
72 + expect(index['/docs/providers/custom-providers']).toEqual({
73 + group: 'Get Started',
74 + folder: 'Custom providers',
75 + depth: 2,
76 + position: 12,
77 + });
78 + expect(index['/docs/providers/custom-providers/typescript'].position).toBe(1);
79 + });
80 +
81 + test('a separator nested in a folder does not leak into the folder siblings', () => {
82 + // No meta.json nests a separator today, but fumadocs allows it: the group
83 + // and the counter are per-level, so "Inner" and its numbering stay inside
84 + // the folder instead of resuming Outer's siblings mid-sequence.
85 + const nested = buildSidebarNavIndex({
86 + name: 'root',
87 + children: [
88 + { type: 'separator', name: 'Outer' },
89 + { type: 'page', name: 'First', url: '/a' },
90 + {
91 + type: 'folder',
92 + name: 'Folder',
93 + children: [
94 + { type: 'separator', name: 'Inner' },
95 + { type: 'page', name: 'Child', url: '/a/child' },
96 + ],
97 + },
98 + { type: 'page', name: 'Last', url: '/b' },
99 + ],
100 + });
101 +
102 + expect(nested['/a']).toEqual({ group: 'Outer', folder: null, depth: 1, position: 1 });
103 + expect(nested['/a/child']).toEqual({
104 + group: 'Inner',
105 + folder: 'Folder',
106 + depth: 2,
107 + position: 1,
108 + });
109 + expect(nested['/b']).toEqual({ group: 'Outer', folder: null, depth: 1, position: 3 });
110 + });
111 +
112 test('every page in the sidebar tree resolves to a non-null group', () => {
113 const missing = flattenTree(source.pageTree.children)
114 .map(page => page.url)