From 9240acddb6d60e6dfaaa6f947d9c84e1b76f2562 Mon Sep 17 00:00:00 2001
From: hsiegeln <37154749+hsiegeln@users.noreply.github.com>
Date: Thu, 2 Apr 2026 18:30:27 +0200
Subject: [PATCH] docs: update CLAUDE.md and COMPONENT_GUIDE.md for composable
 Sidebar

- Add Sidebar, SidebarTree, useStarred to import paths
- Update navigation decision tree with compound component entries
- Replace old Sidebar props description with compound API
- Add standard page layout composition pattern for new Sidebar

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md          |  8 ++++++++
 COMPONENT_GUIDE.md | 30 ++++++++++++++++++++++++++----
 2 files changed, 34 insertions(+), 4 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 6ec38d5..cad545a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -40,6 +40,10 @@ import { Button, Input } from '../design-system/primitives'
 import { Modal, DataTable, KpiStrip, SplitPane, EntityList, LogViewer } from '../design-system/composites'
 import type { Column, KpiItem, LogEntry } from '../design-system/composites'
 import { AppShell } from '../design-system/layout/AppShell'
+import { Sidebar } from '../design-system/layout/Sidebar/Sidebar'
+import { SidebarTree } from '../design-system/layout/Sidebar/SidebarTree'
+import type { SidebarTreeNode } from '../design-system/layout/Sidebar/SidebarTree'
+import { useStarred } from '../design-system/layout/Sidebar/useStarred'
 import { ThemeProvider } from '../design-system/providers/ThemeProvider'
 ```
 
@@ -93,6 +97,10 @@ import { Button, AppShell, ThemeProvider } from '@cameleer/design-system'
 // All components from single entry
 import { Button, Input, Modal, DataTable, KpiStrip, SplitPane, EntityList, LogViewer, StatusText, AppShell } from '@cameleer/design-system'
 
+// Sidebar (compound component — compose your own navigation)
+import { Sidebar, SidebarTree, useStarred } from '@cameleer/design-system'
+import type { SidebarTreeNode } from '@cameleer/design-system'
+
 // Types
 import type { Column, DataTableProps, SearchResult, KpiItem, LogEntry } from '@cameleer/design-system'
 
diff --git a/COMPONENT_GUIDE.md b/COMPONENT_GUIDE.md
index 6aad328..2299d5d 100644
--- a/COMPONENT_GUIDE.md
+++ b/COMPONENT_GUIDE.md
@@ -38,10 +38,12 @@
 - Removable label → **Tag**
 
 ### "I need navigation"
-- App-level sidebar nav → **Sidebar** (via AppShell) — hierarchical trees with starring
+- App-level sidebar nav → **Sidebar** (compound component — compose sections, trees, footer links)
+- Sidebar tree section → **SidebarTree** (data-driven tree with expand/collapse, starring, keyboard nav)
+- Starred items persistence → **useStarred** hook (localStorage-backed)
 - Breadcrumb trail → **Breadcrumb**
 - Paginated data → **Pagination** (standalone) or **DataTable** (built-in pagination)
-- Hierarchical tree navigation → **TreeView** (generic) or **SidebarTree** (sidebar-specific, internal)
+- Hierarchical tree navigation → **TreeView** (generic)
 
 ### "I need floating content"
 - Tooltip on hover → **Tooltip**
@@ -99,7 +101,21 @@
 
 ### Standard page layout
 ```
-AppShell → Sidebar + TopBar + main content + optional DetailPanel
+AppShell → Sidebar (compound) + TopBar + main content + optional DetailPanel
+
+Sidebar compound API:
+  <Sidebar collapsed={bool} onCollapseToggle={fn} searchValue={str} onSearchChange={fn}>
+    <Sidebar.Header logo={node} title="str" version="str" />
+    <Sidebar.Section label="str" icon={node} open={bool} onToggle={fn} active={bool}>
+      <SidebarTree nodes={[...]} selectedPath="..." filterQuery="..." ... />
+    </Sidebar.Section>
+    <Sidebar.Footer>
+      <Sidebar.FooterLink icon={node} label="str" onClick={fn} active={bool} />
+    </Sidebar.Footer>
+  </Sidebar>
+
+The app controls all content — sections, order, tree data, collapse state.
+Sidebar provides the frame, search input, and icon-rail collapse mode.
 ```
 
 ### Data page pattern
@@ -284,7 +300,9 @@ import {
 | Component | Purpose |
 |-----------|---------|
 | AppShell | Page shell: sidebar + topbar + main + optional detail panel |
-| Sidebar | Hierarchical navigation with Applications/Agents/Routes trees, starring, search filter, bottom links. Props: `apps: SidebarApp[]` (hierarchical — apps contain routes and agents) |
+| Sidebar | Composable compound sidebar shell with icon-rail collapse mode. Sub-components: `Sidebar.Header`, `Sidebar.Section`, `Sidebar.Footer`, `Sidebar.FooterLink`. The app controls all content via children — the DS provides the frame. |
+| SidebarTree | Data-driven tree for sidebar sections. Accepts `nodes: SidebarTreeNode[]` with expand/collapse, starring, keyboard nav, search filter, and path-based selection highlighting. |
+| useStarred | Hook for localStorage-backed starred item IDs. Returns `{ starredIds, isStarred, toggleStar }`. |
 | TopBar | Header bar with breadcrumb, search trigger, ButtonGroup status filters, time range selector, theme toggle, environment badge, user avatar |
 
 ## Import Paths
@@ -296,6 +314,10 @@ import { Button, Input, Badge } from './design-system/primitives'
 import { DataTable, Modal, Toast } from './design-system/composites'
 import type { Column, SearchResult, FeedEvent } from './design-system/composites'
 import { AppShell } from './design-system/layout/AppShell'
+import { Sidebar } from './design-system/layout/Sidebar/Sidebar'
+import { SidebarTree } from './design-system/layout/Sidebar/SidebarTree'
+import type { SidebarTreeNode } from './design-system/layout/Sidebar/SidebarTree'
+import { useStarred } from './design-system/layout/Sidebar/useStarred'
 import { ThemeProvider, useTheme } from './design-system/providers/ThemeProvider'
 ```