feat(DualScrollSync)!: adopt compound-components API alongside items prop (#15)

BREAKING CHANGE: DualScrollSync now supports a declarative compound-components API in addition to the existing `items` prop pattern.

feat(DualScrollSync): add DualScrollSyncContent component

feat(DualScrollSync): add DualScrollSyncContentSection component

feat(DualScrollSync): add DualScrollSyncNav component

feat(DualScrollSync): add DualScrollSyncNavItem component

feat(DualScrollSync): add DualScrollSyncLabel component

feat(hooks): add useDualScrollSyncContext for accessing scroll synchronization context

feat(hooks): implement useValidateChildren to validate Nav and Content sections

feat(types): introduce types for content, navigation, and labels

perf(DualScrollSync): refactor component structure and improve test coverage

style(DualScrollSync): add new SCSS modules for content, navigation, and labels

refactor(hooks): simplify type definitions and improve key handling in IntersectionObserver

Author: dorixdev

.github/workflows/release-please.yml

@@ -12,4 +12,5 @@ jobs:
       - uses: googleapis/release-please-action@v4
         with:
           token: ${{ secrets.RELEASE_PLEASE_TOKEN }}
-          release-type: node
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json

CHANGELOG.md

@@ -2,38 +2,36 @@
 
 ## [1.2.3](https://github.com/dorixdev/react-dual-scroll-sync/compare/v1.2.2...v1.2.3) (2025-08-27)
 
+### ⚡ Performance Improvements
 
-### Performance Improvements
-
-* dual-scroll-styles ([#13](https://github.com/dorixdev/react-dual-scroll-sync/issues/13)) ([d3d4855](https://github.com/dorixdev/react-dual-scroll-sync/commit/d3d48551a0f07a9c4fe75a92838ea56a06c6d5f6))
+- dual-scroll-styles ([#13](https://github.com/dorixdev/react-dual-scroll-sync/issues/13)) ([d3d4855](https://github.com/dorixdev/react-dual-scroll-sync/commit/d3d48551a0f07a9c4fe75a92838ea56a06c6d5f6))
 
 ## [1.2.2](https://github.com/dorixdev/react-dual-scroll-sync/compare/v1.2.1...v1.2.2) (2025-08-27)
 
+### 🐛 Bug Fixes
 
-### Bug Fixes
-
-* sort versions and add title ([#11](https://github.com/dorixdev/react-dual-scroll-sync/issues/11)) ([2b22b66](https://github.com/dorixdev/react-dual-scroll-sync/commit/2b22b66a08c4b0c372c03c5e6a4c5d3349667d15))
+- sort versions and add title ([#11](https://github.com/dorixdev/react-dual-scroll-sync/issues/11)) ([2b22b66](https://github.com/dorixdev/react-dual-scroll-sync/commit/2b22b66a08c4b0c372c03c5e6a4c5d3349667d15))
 
 ## [1.2.1](https://github.com/dorixdev/react-dual-scroll-sync/compare/v1.2.0...v1.2.1) (2025-08-27)
 
-### Bug Fixes
+### 🐛 Bug Fixes
 
 - remove --if-present flag ([#9](https://github.com/dorixdev/react-dual-scroll-sync/issues/9)) ([b6b9a10](https://github.com/dorixdev/react-dual-scroll-sync/commit/b6b9a101d28c4eb0dd0b7f34e02ce0efbb3a59c5))
 
 ## [1.2.0](https://github.com/dorixdev/react-dual-scroll-sync/compare/v1.1.2...v1.2.0) (2025-08-27)
 
-### Features
+### ✨ Features
 
 - add Storybook manager config and improve component previews ([#3](https://github.com/dorixdev/react-dual-scroll-sync/issues/3)) ([6a13f9f](https://github.com/dorixdev/react-dual-scroll-sync/commit/6a13f9f311c9eaff823569e24e99f6c758af5f94))
 
-### Bug Fixes
+### 🐛 Bug Fixes
 
 - **ci:** replace GITHUB_TOKEN to RELEASE_PLEASE_TOKEN ([#4](https://github.com/dorixdev/react-dual-scroll-sync/issues/4)) ([df8e4d1](https://github.com/dorixdev/react-dual-scroll-sync/commit/df8e4d1159c3be7f28bbb5196a0cfa7c773ab9c8))
 - **CI:** update release-please action ([#7](https://github.com/dorixdev/react-dual-scroll-sync/issues/7)) ([8e35746](https://github.com/dorixdev/react-dual-scroll-sync/commit/8e357464505bdf716115566dab70348205511045))
 - **DualScrollSync:** add title attribute for better accessibility ([6a13f9f](https://github.com/dorixdev/react-dual-scroll-sync/commit/6a13f9f311c9eaff823569e24e99f6c758af5f94))
 - **DualScrollSync:** refine nav item styles and active indicator ([6a13f9f](https://github.com/dorixdev/react-dual-scroll-sync/commit/6a13f9f311c9eaff823569e24e99f6c758af5f94))
 
-### Performance Improvements
+### ⚡ Performance Improvements
 
 - **storybook:** update stories with new mock data (internal only) ([6a13f9f](https://github.com/dorixdev/react-dual-scroll-sync/commit/6a13f9f311c9eaff823569e24e99f6c758af5f94))
 

README.md

@@ -8,6 +8,17 @@ A lightweight React library to synchronize a vertical navigation menu with scrol
 [![bundle size](https://img.shields.io/bundlephobia/minzip/@dorixdev/react-dual-scroll-sync?label=size&logo=webpack)](https://bundlephobia.com/package/@dorixdev/react-dual-scroll-sync)
 [![license](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
 
+## 📑 Table of Contents
+
+- [Features](#-features)
+- [Demo](#-demo)
+- [Installation](#-installation)
+- [Styles](#-styles)
+- [Quick Start](#-quick-start)
+- [Props Overview](#-props-overview)
+- [Customization](#-customization)
+- [Docs](#-documentation)
+
 ## 💡 Features
 
 - 🔗 **Sync state** between a vertical nav and the currently visible content section
@@ -49,17 +60,55 @@ const items = [
 ];
 
 export default function Demo() {
-	return (
-		<DualScrollSync
-			id="filters"
-			items={items}
-			maxVisibleItems={6}
-			onItemClick={(key) => console.log('Selected', key)}
-		/>
-	);
+	return <DualScrollSync items={items} />;
 }
 ```
 
+## 🧩 Usage Patterns
+
+DualScrollSync can be used in two main ways: **data-driven** and **declarative**.
+
+### Data-Driven
+
+Define your sections in an array and let the component generate both nav items and content.
+
+✅ Best for dynamic data (e.g. from CMS or API).
+
+```tsx
+const items = [
+	{ sectionKey: 'intro', label: 'Introduction', children: <p>...</p> },
+	{ sectionKey: 'details', label: 'Details', children: <p>...</p> }
+];
+
+<DualScrollSync items={items} onItemClick={(k) => console.log(k)} />;
+```
+
+### Declarative
+
+Write the structure directly in JSX using `DualScrollSync.NavItem` and `DualScrollSync.ContentSection`.
+
+✅ 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>
+```
+
+## ⚖️ When to use
+
+✅ Long scrollable pages with sticky nav  
+✅ Catalog filters, docs sidebars, multi-section layouts  
+❌ Very short pages (anchors may suffice)
+
 ## 📘 Documentation
 
 Explore all props, variations, and usage guidelines in the [Storybook docs](https://react-dual-scroll-sync.vercel.app).

eslint.config.js

@@ -11,33 +11,34 @@ import tseslint from 'typescript-eslint';
 import { globalIgnores } from 'eslint/config';
 
 export default tseslint.config(
-  [
-    globalIgnores(['dist']),
-    {
-      files: ['**/*.{ts,tsx}'],
-      plugins: {
-        import: importPlugin,
-        'simple-import-sort': simpleImportSort
-      },
-      extends: [
-        js.configs.recommended,
-        tseslint.configs.recommended,
-        reactHooks.configs['recommended-latest'],
-        reactRefresh.configs.vite
-      ],
-      languageOptions: {
-        ecmaVersion: 2020,
-        globals: globals.browser
-      },
-      rules: {
-        'import/extensions': 'off',
-        'import/first': 'error',
-        'import/newline-after-import': 'error',
-        'import/no-duplicates': 'error',
-        'simple-import-sort/exports': 'error',
-        'simple-import-sort/imports': 'error'
-      }
-    }
-  ],
-  storybook.configs['flat/recommended']
+	[
+		globalIgnores(['dist', 'storybook-static']),
+		{
+			files: ['**/*.{ts,tsx}'],
+			plugins: {
+				import: importPlugin,
+				'simple-import-sort': simpleImportSort
+			},
+			extends: [
+				js.configs.recommended,
+				tseslint.configs.recommended,
+				reactHooks.configs['recommended-latest'],
+				reactRefresh.configs.vite
+			],
+			languageOptions: {
+				ecmaVersion: 2020,
+				globals: globals.browser
+			},
+			rules: {
+				'import/extensions': 'off',
+				'import/first': 'error',
+				'import/newline-after-import': 'error',
+				'import/no-duplicates': 'error',
+				'simple-import-sort/exports': 'error',
+				'simple-import-sort/imports': 'error',
+				'@typescript-eslint/consistent-type-imports': 'error'
+			}
+		}
+	],
+	storybook.configs['flat/recommended']
 );

lib/components/DualScrollSync/DualScrollSync.module.scss

@@ -1,4 +1,4 @@
-@use '../../scss/tokens.scss' as *;
+@use '@/scss/tokens.scss' as *;
 
 .scrollSync {
 	overflow: hidden;
@@ -8,116 +8,3 @@
 	border: 1px solid var(--dual-scroll-sync-border-color, #{$border-color});
 	border-radius: var(--dual-scroll-sync-border-radius, #{$border-radius});
 }
-
-.scrollSyncNav {
-	overflow-y: auto;
-	width: 100%;
-	max-width: var(--dual-scroll-sync-max-width-nav, #{$max-width-nav});
-
-	&::-webkit-scrollbar {
-		display: none;
-	}
-}
-
-.scrollSyncNavItem {
-	cursor: pointer;
-
-	display: flex;
-	align-items: center;
-
-	width: 100%;
-	height: calc(100% / var(--menu-nav-visible-count));
-	padding: var(--dual-scroll-sync-space-m, #{$space-m}) var(--dual-scroll-sync-space-s, #{$space-s});
-	border: none;
-	border-bottom: 1px solid var(--dual-scroll-sync-border-color, #{$border-color});
-
-	text-align: left;
-
-	background-color: var(
-		--dual-scroll-sync-inactive-background-color,
-		#{$inactive-background-color}
-	);
-
-	transition: var(--dual-scroll-sync-transition, #{$transition});
-
-	&:first-child {
-		border-top-left-radius: var(--dual-scroll-sync-border-radius, #{$border-radius});
-	}
-
-	&:last-child {
-		border-bottom: none;
-		border-bottom-left-radius: var(--dual-scroll-sync-border-radius, #{$border-radius});
-	}
-}
-
-.scrollSyncNavItemLabel,
-.scrollSyncContentSectionLabel {
-	overflow: hidden;
-	display: -webkit-box;
-	-webkit-box-orient: vertical;
-	-webkit-line-clamp: 2;
-	line-clamp: 2;
-}
-
-.scrollSyncNavItemLabel {
-	margin: auto 0;
-	padding: 0 var(--dual-scroll-sync-space-m, #{$space-m});
-	font-size: smaller;
-}
-
-.scrollSyncContentSectionLabel {
-	padding: var(--dual-scroll-sync-space-s, #{$space-s}) 0;
-	font-weight: bold;
-}
-
-.scrollSyncNavItemActive {
-	position: relative;
-	background-color: var(
-		--dual-scroll-sync-highlight-background-color,
-		#{$highlight-background-color}
-	);
-
-	span {
-		font-weight: bold;
-		color: var(--dual-scroll-sync-highlight-foreground-color, #{$highlight-foreground-color});
-
-		&::before {
-			content: '';
-
-			position: absolute;
-			top: 0;
-			left: 0;
-
-			height: 100%;
-			border-left: 4px solid
-				var(--dual-scroll-sync-highlight-foreground-color, #{$highlight-foreground-color});
-		}
-	}
-}
-
-.scrollSyncContent {
-	overflow-x: hidden;
-	overflow-y: auto;
-	flex: 1;
-	gap: var(--dual-scroll-sync-space-m, #{$space-m});
-
-	height: 100%;
-	padding: var(--dual-scroll-sync-space-s, #{$space-s});
-
-	background-color: var(
-		--dual-scroll-sync-highlight-background-color,
-		#{$highlight-background-color}
-	);
-}
-
-.scrollSyncContentSection {
-	display: flex;
-	flex-direction: column;
-	gap: var(--dual-scroll-sync-space-l, #{$space-l});
-
-	height: auto;
-	padding: var(--dual-scroll-sync-space-m, #{$space-m});
-	border-radius: var(--dual-scroll-sync-border-radius, #{$border-radius});
-
-	transition: background-color 0.3s ease-in-out;
-}