fix(DualScrollSync): add maxVisibleItems support with docs and tests (#27)

refactor(types): improve type definitions for DualScrollSync components

fix(context): add maxVisibleItems to DualScrollSyncContextProps interface

fix(DualScrollSync): ensure maxVisibleItems is correctly passed from context

test(DualScrollSyncNav): update tests to use context mock for maxVisibleItems

docs(README): update usage patterns and examples for DualScrollSync component

Author: dorixdev

README.md

@@ -15,6 +15,7 @@ A lightweight React library to synchronize a vertical navigation menu with scrol
 - [Installation](#-installation)
 - [Styles](#-styles)
 - [Quick Start](#-quick-start)
+- [Usage Patterns](#-usage-patterns)
 - [Props Overview](#-props-overview)
 - [Customization](#-customization)
 - [Docs](#-documentation)
@@ -76,11 +77,11 @@ Define your sections in an array and let the component generate both nav items a
 
 ```tsx
 const items = [
-	{ sectionKey: 'intro', label: 'Introduction', children: <p>...</p> },
-	{ sectionKey: 'details', label: 'Details', children: <p>...</p> }
+	{ sectionKey: 'intro', label: 'Introduction', children: <div>...</div> },
+	{ sectionKey: 'details', label: 'Details', children: <div>...</div> }
 ];
 
-<DualScrollSync items={items} onItemClick={(k) => console.log(k)} />;
+return <DualScrollSync items={items} onItemClick={handleClick} />;
 ```
 
 ### Declarative
@@ -90,24 +91,36 @@ Write the structure directly in JSX using `DualScrollSync.NavItem` and `DualScro
 ✅ Best for static pages where you want **full control**.
 
 ```tsx
-<DualScrollSync>
-	<DualScrollSync.Nav>
-		<DualScrollSync.NavItem sectionKey="a">Section A</DualScrollSync.NavItem>
-		<DualScrollSync.NavItem sectionKey="b">Section B</DualScrollSync.NavItem>
-	</DualScrollSync.Nav>
-
-	<DualScrollSync.Content>
-		<DualScrollSync.ContentSection sectionKey="a">...</DualScrollSync.ContentSection>
-		<DualScrollSync.ContentSection sectionKey="b">...</DualScrollSync.ContentSection>
-	</DualScrollSync.Content>
-</DualScrollSync>
+return (
+	<DualScrollSync onItemClick={handleClick}>
+		<DualScrollSync.Nav>
+			<DualScrollSync.NavItem sectionKey="intro">Introduction</DualScrollSync.NavItem>
+			<DualScrollSync.NavItem sectionKey="details">Details</DualScrollSync.NavItem>
+		</DualScrollSync.Nav>
+
+		<DualScrollSync.Content>
+			<DualScrollSync.ContentSection sectionKey="intro">
+				<DualScrollSync.Label>Introduction</DualScrollSync.Label>
+				<div>...</div>
+			</DualScrollSync.ContentSection>
+			<DualScrollSync.ContentSection sectionKey="details">
+				<DualScrollSync.Label>Details</DualScrollSync.Label>
+				<div>...</div>
+			</DualScrollSync.ContentSection>
+		</DualScrollSync.Content>
+	</DualScrollSync>
+);
 ```
 
 ## ⚖️ When to use
 
-✅ Long scrollable pages with sticky nav  
-✅ Catalog filters, docs sidebars, multi-section layouts  
-❌ Very short pages (anchors may suffice)
+✅ Long scrollable pages with sticky nav
+
+✅ Catalog filters, docs sidebars, multi-section layouts
+
+❌ Very short content (no scrolling needed)
+
+❌ Complex nested navs (not supported)
 
 ## 📘 Documentation
 

lib/components/DualScrollSync/DualScrollSync.tsx

@@ -20,9 +20,10 @@ export const DualScrollSyncBase: FC<DualScrollSyncProps> = ({
 	id,
 	items,
 	onItemClick,
+	maxVisibleItems = 6,
 	style = {}
 }) => {
-	const baseId = id ?? 'dual-scroll-sync';
+	const baseId = id || 'dual-scroll-sync';
 	const navId = `${baseId}-nav`;
 	const contentId = `${baseId}-content`;
 
@@ -39,6 +40,7 @@ export const DualScrollSyncBase: FC<DualScrollSyncProps> = ({
 			sectionRefs,
 			navItemRefs,
 			navRef,
+			maxVisibleItems,
 			onMenuItemSelect,
 			onItemClick
 		}),
@@ -51,6 +53,7 @@ export const DualScrollSyncBase: FC<DualScrollSyncProps> = ({
 			sectionRefs,
 			navItemRefs,
 			navRef,
+			maxVisibleItems,
 			onMenuItemSelect,
 			onItemClick
 		]

lib/components/DualScrollSync/DualScrollSync.types.ts

@@ -18,30 +18,32 @@ export type DualScrollSyncOptions = {
 
 export type DualScrollSyncItem = PropsWithChildren<DualScrollSyncOptions>;
 
-export type DualScrollSyncProps = PropsWithChildren<DualScrollSyncStyleProps> & {
-	/**
-	 * Unique identifier for the DualScrollSync component. (Optional)
-	 * @default 'dual-scroll-sync'
-	 */
-	id?: string;
-	/**
-	 * Array of `DualScrollSyncItem` objects.
-	 * If provided, the component will auto-generate the navigation menu and content sections and ignore any children passed directly to it. (Optional)
-	 * @default []
-	 */
-	items?: DualScrollSyncItem[];
-	/**
-	 * Maximum visible items in the navigation menu. If the number of items exceeds this value, scrolling is activated. (Optional)
-	 * @default 6
-	 */
-	maxVisibleItems?: number;
-	/**
-	 * Callback function triggered when active section changes.
-	 * @param activeKey - The key of the active section.
-	 * @default () => {}
-	 */
-	onItemClick?: (activeKey: string) => void;
-};
+export type DualScrollSyncProps = PropsWithChildren<
+	DualScrollSyncStyleProps & {
+		/**
+		 * Unique identifier for the DualScrollSync component. (Optional)
+		 * @default 'dual-scroll-sync'
+		 */
+		id?: string;
+		/**
+		 * Array of `DualScrollSyncItem` objects.
+		 * If provided, the component will auto-generate the navigation menu and content sections and ignore any children passed directly to it. (Optional)
+		 * @default []
+		 */
+		items?: DualScrollSyncItem[];
+		/**
+		 * Maximum visible items in the navigation menu. If the number of items exceeds this value, scrolling is activated. (Optional)
+		 * @default 6
+		 */
+		maxVisibleItems?: number;
+		/**
+		 * Callback function triggered when active section changes.
+		 * @param activeKey - The key of the active section.
+		 * @default () => {}
+		 */
+		onItemClick?: (activeKey: string) => void;
+	}
+>;
 
 export type DualScrollSyncType = FC<DualScrollSyncProps> & {
 	Nav: FC<DualScrollSyncNavProps>;

lib/components/DualScrollSync/DualScrollSyncContentSection/DualScrollSyncContentSection.types.ts

@@ -1,4 +1,7 @@
-import type { DualScrollSyncItem, DualScrollSyncStyleProps } from '../DualScrollSync.types';
+import type { PropsWithChildren } from 'react';
 
-export type DualScrollSyncContentSectionProps = Omit<DualScrollSyncItem, 'label'> &
-	DualScrollSyncStyleProps;
+import type { DualScrollSyncOptions, DualScrollSyncStyleProps } from '../DualScrollSync.types';
+
+export type DualScrollSyncContentSectionProps = PropsWithChildren<
+	DualScrollSyncStyleProps & Pick<DualScrollSyncOptions, 'sectionKey'>
+>;

lib/components/DualScrollSync/DualScrollSyncNav/DualScrollSyncNav.test.tsx

@@ -1,6 +1,8 @@
 import { render } from '@testing-library/react';
 import { vi } from 'vitest';
 
+import { mockScrollSyncContextProps, spyUseDualScrollSyncContext } from '@/setupTests';
+
 import { DualScrollSyncNav } from './DualScrollSyncNav';
 
 describe('DualScrollSyncNav', () => {
@@ -19,8 +21,13 @@ describe('DualScrollSyncNav', () => {
 	});
 
 	it('should apply maxVisibleItems correctly', () => {
+		spyUseDualScrollSyncContext.mockReturnValueOnce({
+			...mockScrollSyncContextProps,
+			maxVisibleItems: 3
+		});
+
 		const { getByTestId } = render(
-			<DualScrollSyncNav maxVisibleItems={3}>
+			<DualScrollSyncNav>
 				<div>Item 1</div>
 				<div>Item 2</div>
 				<div>Item 3</div>
@@ -34,7 +41,7 @@ describe('DualScrollSyncNav', () => {
 
 	it('should limit visible items to the number of children if fewer than maxVisibleItems', () => {
 		const { getByTestId } = render(
-			<DualScrollSyncNav maxVisibleItems={5}>
+			<DualScrollSyncNav>
 				<div>Item 1</div>
 				<div>Item 2</div>
 				<div>Item 3</div>

lib/components/DualScrollSync/DualScrollSyncNav/DualScrollSyncNav.tsx

@@ -10,10 +10,9 @@ import type { DualScrollSyncNavProps } from './DualScrollSyncNav.types';
 export const DualScrollSyncNav: FC<DualScrollSyncNavProps> = ({
 	children,
 	className,
-	maxVisibleItems = 6,
 	style = {}
 }) => {
-	const { navId, navRef } = useDualScrollSyncContext();
+	const { navId, navRef, maxVisibleItems } = useDualScrollSyncContext();
 	const navItemCount = Children.count(children);
 	const visibleItemsCount = Math.min(maxVisibleItems, navItemCount);
 

lib/components/DualScrollSync/DualScrollSyncNav/DualScrollSyncNav.types.ts

@@ -2,5 +2,4 @@ import type { PropsWithChildren } from 'react';
 
 import type { DualScrollSyncStyleProps } from '../DualScrollSync.types';
 
-export type DualScrollSyncNavProps = DualScrollSyncStyleProps &
-	PropsWithChildren<{ maxVisibleItems?: number }>;
+export type DualScrollSyncNavProps = PropsWithChildren<DualScrollSyncStyleProps>;

lib/components/DualScrollSync/DualScrollSyncNavItem/DualScrollSyncNavItem.types.ts

@@ -2,5 +2,6 @@ import type { PropsWithChildren } from 'react';
 
 import type { DualScrollSyncOptions, DualScrollSyncStyleProps } from '../DualScrollSync.types';
 
-export type DualScrollSyncNavItemProps = Pick<DualScrollSyncOptions, 'sectionKey'> &
-	PropsWithChildren<DualScrollSyncStyleProps>;
+export type DualScrollSyncNavItemProps = PropsWithChildren<
+	DualScrollSyncStyleProps & Pick<DualScrollSyncOptions, 'sectionKey'>
+>;

lib/contexts/DualScrollSyncContext.ts

@@ -6,6 +6,7 @@ export interface DualScrollSyncContextProps extends UseScrollSyncObserverReturn
 	baseId: string;
 	navId: string;
 	contentId: string;
+	maxVisibleItems: number;
 	onItemClick?: (activeKey: string) => void;
 }
 

lib/hooks/useDualScrollSyncContext.test.tsx

@@ -15,7 +15,9 @@ const mockValue = {
 	navItemRefs: { current: {} },
 	navRef: { current: null },
 	sectionRefs: { current: {} },
-	onMenuItemSelect: vi.fn()
+	onMenuItemSelect: vi.fn(),
+	onItemClick: vi.fn(),
+	maxVisibleItems: 6
 };
 
 const Wrapper: FC<PropsWithChildren> = ({ children }) => {