@flamingo-stack/openframe-frontend-core 0.0.213 → 0.0.214-snapshot.20260528192313

package/src/components/navigation/.app-layout.md

@@ -1,44 +1,39 @@
-<!-- source-hash: 044075e8eda2a0ce2427ef7e529ff9f3 -->
-A responsive application layout component that provides a structured shell with navigation sidebar, header, and mobile menu functionality for Flamingo Stack applications.
+<!-- source-hash: 4a7aa4db8bec1fcce07d28f27fea4092 -->
+Orchestrates the top-level application shell, combining the sidebar, header, mobile menu, and notification drawer into a single full-screen layout with managed mobile menu state.
 
 ## Key Components
 
-- **`AppLayout`** - Main layout component that orchestrates the entire application shell
-- **`AppLayoutProps`** - TypeScript interface defining all layout configuration options
-- **Mobile menu state management** - Handles toggle and close functionality for mobile navigation
-- **Responsive design** - Combines desktop sidebar with mobile burger menu
-- **Suspense integration** - Built-in loading state handling for async content
+| Export | Type | Description |
+|--------|------|-------------|
+| `AppLayout` | Component | Root layout wrapper rendering all chrome elements and the main content area |
+| `AppLayoutProps` | Interface | Configuration interface for the layout component |
+
+**Key props:**
+- `sidebarConfig` — Navigation structure passed to both `NavigationSidebar` and `MobileBurgerMenu`
+- `headerProps` — Forwarded to `AppHeader` (mobile menu state/toggle are managed internally)
+- `mobileBurgerMenuProps` — Forwarded to `MobileBurgerMenu` (open/close/config are managed internally)
+- `disabled` — Freezes header and sidebar interactions without affecting `children`
+- `loadingFallback` — Custom `Suspense` fallback for the main content area
 
 ## Usage Example
 
 ```typescript
 import { AppLayout } from './app-layout'
-import { NavigationSidebarConfig } from '../../types/navigation'
-
-const sidebarConfig: NavigationSidebarConfig = {
-  sections: [
-    {
-      title: 'Dashboard',
-      items: [
-        { label: 'Overview', href: '/dashboard', icon: 'dashboard' }
-      ]
-    }
-  ]
-}
+import { sidebarConfig } from '../config/navigation'
 
-function MyApp({ children }: { children: React.ReactNode }) {
+export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
     <AppLayout
       sidebarConfig={sidebarConfig}
       headerProps={{
-        title: 'Flamingo MSP',
-        user: { name: 'John Doe', avatar: '/avatar.jpg' }
+        logo: <Logo />,
+        actions: <UserMenu />,
       }}
       mobileBurgerMenuProps={{
-        className: 'custom-mobile-menu'
+        footerContent: <SupportLink />,
       }}
-      loadingFallback={<div>Loading...</div>}
-      mainClassName="custom-main-styles"
+      loadingFallback={<PageSkeleton />}
+      mainClassName="p-6"
     >
       {children}
     </AppLayout>
@@ -46,4 +41,8 @@ function MyApp({ children }: { children: React.ReactNode }) {
 }
 ```
 
-The component uses Tailwind CSS classes for styling and implements a flex-based layout with overflow handling for proper scrolling behavior on both desktop and mobile devices.
+## Notes
+
+- Mobile menu open/close state is fully self-contained — consumers only provide content-level props via `mobileBurgerMenuProps`
+- `children` are wrapped in `Suspense`, enabling async page transitions out of the box
+- `disabled` is intended for loading or onboarding states where navigation should be temporarily locked

package/src/components/navigation/.header-global-search.md

@@ -1,46 +1,43 @@
-<!-- source-hash: 87e72e6e65d4632e153a3f9d171549d4 -->
-A React component that provides a global search input field with a search icon, designed for header navigation areas in the OpenFrame platform.
+<!-- source-hash: d02572a5b408584db5dc8403984b5d76 -->
+A controlled/uncontrolled global search input component for the OpenFrame header, supporting both controlled (via `onChange`) and uncontrolled usage patterns.
 
 ## Key Components
 
-- **HeaderGlobalSearch**: Main functional component that renders a search form with an input field and search icon
-- **HeaderGlobalSearchProps**: TypeScript interface defining component props including value, onChange, onSubmit callbacks, and styling options
-- **Internal state management**: Handles both controlled and uncontrolled input modes depending on whether onChange prop is provided
+### `HeaderGlobalSearch`
+A form-based search input that renders a search icon alongside a text field. Automatically toggles between controlled and uncontrolled modes based on whether `onChange` is provided.
+
+### `HeaderGlobalSearchProps`
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | `''` | Current search value |
+| `onChange` | `(value: string) => void` | — | Enables controlled mode |
+| `onSubmit` | `(value: string) => void` | — | Fires on form submit or Enter key |
+| `placeholder` | `string` | `'Global Search'` | Input placeholder text |
+| `className` | `string` | — | Additional CSS classes |
 
 ## Usage Example
 
+**Controlled:**
 ```typescript
-import { HeaderGlobalSearch } from './header-global-search'
-
-// Controlled mode with external state
-function App() {
-  const [searchQuery, setSearchQuery] = useState('')
-
-  const handleSearch = (query: string) => {
-    console.log('Searching for:', query)
-    // Perform search logic
-  }
-
-  return (
-    <HeaderGlobalSearch
-      value={searchQuery}
-      onChange={setSearchQuery}
-      onSubmit={handleSearch}
-      placeholder="Search across all modules..."
-      className="max-w-md"
-    />
-  )
-}
-
-// Uncontrolled mode with internal state
-function SimpleSearch() {
-  return (
-    <HeaderGlobalSearch
-      onSubmit={(query) => performSearch(query)}
-      placeholder="Quick search..."
-    />
-  )
-}
+const [query, setQuery] = React.useState('')
+
+<HeaderGlobalSearch
+  value={query}
+  onChange={setQuery}
+  onSubmit={(val) => console.log('Search:', val)}
+  placeholder="Search tickets, clients..."
+/>
 ```
 
-The component supports both Enter key and form submission for triggering searches, uses OpenFrame design system classes (ods-*), and automatically manages focus states and responsive styling.
+**Uncontrolled:**
+```typescript
+<HeaderGlobalSearch
+  onSubmit={(val) => console.log('Search:', val)}
+/>
+```
+
+## Notes
+
+- Submission triggers on both **form submit** and **Enter keydown**
+- Without `onChange`, component manages its own internal state
+- Styled with ODS design tokens (`ods-card`, `ods-text-primary`, `ods-text-secondary`) for consistent theming across OpenFrame

package/src/components/navigation/.header-organization-filter.md

@@ -1,35 +1,36 @@
-<!-- source-hash: ddff72d1c680d353e286136f90d4f686 -->
-A React component that provides a dropdown filter for switching between organizations in a header layout, displaying the selected organization name and device count.
+<!-- source-hash: dec1eb29c513b449612c49f5b36f6f9d -->
+A client-side dropdown filter component for switching between organizations in the OpenFrame header, displaying the selected organization's name and device count.
 
 ## Key Components
 
-- **`HeaderOrganizationFilterOrganization`** - Interface defining organization structure with id, name, and optional device count
-- **`HeaderOrganizationFilterProps`** - Props interface supporting organization list, selection state, change callbacks, and styling
-- **`HeaderOrganizationFilter`** - Main component rendering a dropdown trigger button with organization selection menu
+### Interfaces
+- **`HeaderOrganizationFilterOrganization`** — Shape for each organization entry (`id`, `name`, `deviceCount?`)
+- **`HeaderOrganizationFilterProps`** — Component props including `organizations`, `selectedOrgId`, `onOrgChange`, `totalDeviceCount`, and `className`
+
+### Component
+- **`HeaderOrganizationFilter`** — Renders a styled trigger button with a filter icon, organization name, and device count, wired to a dropdown menu listing all organizations plus an "All Organizations" reset option
 
 ## Usage Example
 
 ```typescript
 import { HeaderOrganizationFilter } from './header-organization-filter'
 
-const organizations = [
-  { id: 'org1', name: 'Acme Corp', deviceCount: 150 },
-  { id: 'org2', name: 'TechStart Inc', deviceCount: 75 }
+const orgs = [
+  { id: 'org-1', name: 'Acme Corp', deviceCount: 42 },
+  { id: 'org-2', name: 'Globex Inc', deviceCount: 17 },
 ]
 
-function Header() {
-  const [selectedOrgId, setSelectedOrgId] = useState('')
-  
-  return (
-    <HeaderOrganizationFilter
-      organizations={organizations}
-      selectedOrgId={selectedOrgId}
-      onOrgChange={setSelectedOrgId}
-      totalDeviceCount={225}
-      className="border-r"
-    />
-  )
-}
+<HeaderOrganizationFilter
+  organizations={orgs}
+  selectedOrgId="org-1"
+  totalDeviceCount={59}
+  onOrgChange={(id) => console.log('Selected org:', id)}
+/>
 ```
 
-The component displays "All Organizations" when no specific organization is selected, shows individual organization names when selected, and includes device counts below the organization name. It uses a fixed width design (240px) with hover effects and proper text truncation for long organization names.
+## Behavior Notes
+
+- When no `selectedOrgId` matches, defaults to **"All Organizations"** and shows `totalDeviceCount`
+- Selecting "All Organizations" from the dropdown calls `onOrgChange('')`
+- Device count is formatted with `toLocaleString()` (e.g., `1,234 Devices`)
+- Fixed width of `240px` with `border-l` separator, designed for header toolbar placement

package/src/components/navigation/.header.md

@@ -1,66 +1,62 @@
-<!-- source-hash: 28b90e91239d0079021b0b62fbf4abf8 -->
-A responsive header component for React/Next.js applications that provides auto-hide scrolling behavior, dropdown navigation, and mobile menu support with customizable styling.
+<!-- source-hash: 1a8c2c67117a2cb265b878e7d99e1a25 -->
+A responsive, sticky navigation header component with auto-hide on scroll, dropdown menus, and configurable layout zones (logo, navigation, actions).
 
 ## Key Components
 
-**Main Export:**
-- `Header` - Primary header component with navigation and mobile support
-- `HeaderProps` - Interface for component props
-- `HeaderConfig` - Re-exported type for header configuration
+### `Header`
+The primary exported component that renders a full-width sticky header. Accepts a `HeaderConfig` object to control all visual and behavioral aspects.
 
-**Core Features:**
-- Auto-hide on scroll (configurable)
-- Dropdown navigation menus with click-outside handling
-- Mobile responsive design with hamburger menu
-- Keyboard navigation (Escape key support)
-- Active state management for navigation items
+**Props:**
+| Prop | Type | Description |
+|------|------|-------------|
+| `config` | `HeaderConfig` | Full layout/behavior configuration |
+| `platform` | `string` | Optional platform identifier |
 
-**Internal Functions:**
-- `renderNavigationItem()` - Renders different navigation item types (links, dropdowns, custom elements)
-- Scroll event handling for auto-hide functionality
-- Dropdown state management with refs for DOM manipulation
+### Behaviors
+
+- **Auto-hide on scroll** — Hides when scrolling down past 50px, reappears on scroll up. Controlled via `config.autoHide`.
+- **Dropdown menus** — Custom-built dropdowns using `inert` (not `aria-hidden`) for proper a11y/focus management. Closes on outside click or `Escape`.
+- **Mobile menu toggle** — Shows a hamburger icon button on small screens, hidden on `md+` breakpoints.
+
+### Layout Zones
+| Zone | Description |
+|------|-------------|
+| Left | Logo link + optional `config.actions.left` slot |
+| Center/Right | Navigation items (positioned via `config.navigation.position`) |
+| Right | Desktop action slot + mobile menu toggle |
 
 ## Usage Example
 
 ```typescript
-import { Header, HeaderConfig } from './components/header'
-import { Logo } from './components/logo'
-import { Button } from './components/ui/button'
+import { Header, HeaderConfig } from './header'
 
-const headerConfig: HeaderConfig = {
+const config: HeaderConfig = {
   logo: {
     href: '/',
-    element: <Logo />
+    element: <img src="/logo.svg" alt="Flamingo" />,
   },
   navigation: {
     position: 'center',
     items: [
+      { id: 'docs', label: 'Docs', href: '/docs' },
       {
         id: 'products',
         label: 'Products',
         children: [
           { id: 'openframe', label: 'OpenFrame', href: '/openframe' },
-          { id: 'flamingo', label: 'Flamingo MSP', href: '/msp' }
-        ]
+          { id: 'mingo', label: 'Mingo AI', href: '/mingo' },
+        ],
       },
-      {
-        id: 'docs',
-        label: 'Documentation',
-        href: '/docs'
-      }
-    ]
+    ],
   },
   actions: {
-    right: <Button variant="primary">Get Started</Button>
+    right: <Button href="/login">Sign In</Button>,
   },
   autoHide: true,
-  mobile: {
-    enabled: true,
-    onToggle: () => setMobileMenuOpen(!mobileMenuOpen)
-  }
+  mobile: { enabled: true, onToggle: () => setMenuOpen(v => !v) },
 }
 
 export default function Layout() {
-  return <Header config={headerConfig} platform="openframe" />
+  return <Header config={config} />
 }
 ```

package/src/components/navigation/.mobile-burger-menu.md

@@ -1,58 +1,50 @@
-<!-- source-hash: 7e2ac30fc88e2a98c0dfef3cab4d783c -->
-A mobile burger menu component that provides a full-screen overlay navigation interface for mobile devices, featuring user profile display, grid-based navigation items, and smooth slide animations.
+<!-- source-hash: 5b93029e90f2707d4d17ae7b8abe09dc -->
+A mobile slide-down navigation menu component that renders a full-screen overlay panel with user profile card, primary/secondary navigation items in a responsive grid layout, and optional action buttons (logout, edit profile, search user).
 
 ## Key Components
 
-- **MobileBurgerMenu** - Main component that renders a slide-down mobile menu with backdrop blur
-- **MobileBurgerMenuProps** - Interface defining menu configuration, user data, and callback functions
-- **Navigation Grid System** - Renders primary navigation items in a 2-column grid layout
-- **User Profile Card** - Displays user avatar, name, email, role badge, and action buttons
-- **Keyboard & Scroll Management** - Handles ESC key closing and prevents body scroll when open
+**`MobileBurgerMenu`** — Memoized React component (`React.memo`) with the following behavior:
+- Locks body scroll and traps `Escape` key while open
+- Renders a blur backdrop and animated slide-down panel below the fixed header (`48px` offset)
+- Splits `config.items` into **primary** (2-column grid) and **secondary** (full-width list) sections
+- Supports a `disabled` prop that freezes all interactive items while keeping close/backdrop functional
+
+**`MobileBurgerMenuProps`** — Exported interface defining all props:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `isOpen` | `boolean` | Controls visibility and animation |
+| `onClose` | `() => void` | Close handler (backdrop click, Escape key) |
+| `config` | `NavigationSidebarConfig` | Nav items and `onNavigate` callback |
+| `user` | `object` | Optional user card data (name, email, avatar, role) |
+| `onSearchUser` | `() => void` | Optional search user action button |
+| `onEditProfile` | `() => void` | Optional edit profile action button |
+| `onLogout` | `() => void` | Optional logout button at bottom |
+| `disabled` | `boolean` | Disables all interactive items |
 
 ## Usage Example
 
 ```typescript
 import { MobileBurgerMenu } from './mobile-burger-menu'
-import { HomeIcon, SettingsIcon } from '../icons'
 
-function MobileNav() {
-  const [isMenuOpen, setIsMenuOpen] = useState(false)
-  
-  const navigationConfig = {
+const [menuOpen, setMenuOpen] = useState(false)
+
+<MobileBurgerMenu
+  isOpen={menuOpen}
+  onClose={() => setMenuOpen(false)}
+  config={{
     items: [
-      {
-        id: 'home',
-        label: 'Dashboard',
-        icon: <HomeIcon />,
-        path: '/dashboard',
-        isActive: true
-      },
-      {
-        id: 'settings',
-        label: 'Settings',
-        icon: <SettingsIcon />,
-        path: '/settings',
-        section: 'secondary'
-      }
+      { id: 'dashboard', label: 'Dashboard', path: '/dashboard', isActive: true },
+      { id: 'settings', label: 'Settings', section: 'secondary', path: '/settings' },
     ],
-    onNavigate: (path: string) => router.push(path)
-  }
-
-  return (
-    <MobileBurgerMenu
-      isOpen={isMenuOpen}
-      onClose={() => setIsMenuOpen(false)}
-      config={navigationConfig}
-      user={{
-        userName: "John Doe",
-        userEmail: "john@example.com",
-        userRole: "admin"
-      }}
-      onLogout={() => signOut()}
-      onEditProfile={() => router.push('/profile')}
-    />
-  )
-}
-```
-
-The component automatically positions itself below the header (48px), provides smooth slide-down animations, and includes accessibility features like keyboard navigation and ARIA labels.
+    onNavigate: (path) => router.push(path),
+  }}
+  user={{
+    userName: 'Jane Smith',
+    userEmail: 'jane@example.com',
+    userRole: 'Admin',
+  }}
+  onLogout={() => signOut()}
+  onEditProfile={() => router.push('/profile')}
+/>
+```

package/src/components/navigation/.mobile-nav-panel.md

@@ -1,45 +1,64 @@
-<!-- source-hash: aa14a70d25a79da695aa0b3293e38dfc -->
-A React component that renders a mobile-optimized navigation panel with backdrop overlay, scrollable content sections, and accessibility features including keyboard navigation and focus management.
+<!-- source-hash: 22dc571f86ff6412c173e898a5bebb85 -->
+A client-side React component that renders a full-featured mobile navigation panel with backdrop overlay, keyboard support, and scroll locking.
 
 ## Key Components
 
-- **MobileNavPanel** - Main component rendering a modal-style navigation panel
-- **MobileNavPanelProps** - Interface defining component props including open state and configuration
-- **renderNavigationItem** - Internal function handling different navigation item types (links, buttons, custom elements)
-- **Backdrop overlay** - Click-outside-to-close functionality with z-index layering
-- **Responsive positioning** - Mobile-first design with breakpoint-specific sizing and positioning
+### `MobileNavPanel`
+The primary export — a modal-style slide-in navigation panel controlled by `isOpen`.
+
+**Props (`MobileNavPanelProps`):**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `isOpen` | `boolean` | Controls panel visibility |
+| `config` | `MobileNavConfig` | Navigation structure and callbacks |
+
+**Behaviors:**
+- Locks `document.body` scroll while open
+- Closes on `Escape` key press (via `config.onClose`)
+- Closes on backdrop click; prevents propagation inside panel
+- Renders `null` when closed (no DOM presence)
+
+**Layout structure:**
+- **Backdrop** — full-screen overlay (`z-[9998]`) that closes the panel on click
+- **Panel** — floating card (`z-[9999]`), full-width on mobile / `400px` on `md+`, anchored top-right with scroll-locked content area
+- **Header** — fixed close (`X`) button
+- **Body** — scrollable section list with optional section titles and nav items
+- **Footer** — optional sticky footer from `config.footer`
+
+### `renderNavigationItem` (internal)
+Handles three `NavigationItem` render modes:
+1. **Custom element** — renders `item.element` directly
+2. **Link** — `<Button href=...>` with icon, badge, and active state
+3. **Action** — `<Button onClick=...>` with inline badge support
 
 ## Usage Example
 
 ```typescript
 import { MobileNavPanel } from './mobile-nav-panel'
-import { MobileNavConfig } from '../../types/navigation'
-
-function App() {
-  const [isNavOpen, setIsNavOpen] = useState(false)
-  
-  const navConfig: MobileNavConfig = {
-    onClose: () => setIsNavOpen(false),
-    sections: [
-      {
-        title: "Main Navigation",
-        items: [
-          { id: '1', label: 'Home', href: '/', icon: <HomeIcon /> },
-          { id: '2', label: 'About', href: '/about' },
-          { id: '3', label: 'Contact', onClick: () => openContact() }
-        ]
-      }
-    ],
-    footer: <Button>Sign Out</Button>
-  }
+import { useState } from 'react'
+import { Home, Settings } from 'lucide-react'
+
+export function AppShell() {
+  const [menuOpen, setMenuOpen] = useState(false)
 
   return (
-    <MobileNavPanel 
-      isOpen={isNavOpen} 
-      config={navConfig} 
+    <MobileNavPanel
+      isOpen={menuOpen}
+      config={{
+        onClose: () => setMenuOpen(false),
+        sections: [
+          {
+            title: 'Main',
+            items: [
+              { id: 'home', label: 'Home', href: '/', icon: <Home />, isActive: true },
+              { id: 'settings', label: 'Settings', href: '/settings', icon: <Settings /> },
+            ],
+          },
+        ],
+        footer: <button onClick={() => setMenuOpen(false)}>Sign Out</button>,
+      }}
     />
   )
 }
-```
-
-The component automatically handles body scroll prevention, escape key closing, and renders different navigation item types including links, buttons, and custom React elements.
+```

package/src/components/navigation/.navigation-sidebar-header.md

@@ -0,0 +1,36 @@
+<!-- source-hash: e8725ed939f32a658cd8720c67e49da2 -->
+Header component for the navigation sidebar displaying the OpenFrame logo and text, with animated show/hide behavior based on the sidebar's minimized state.
+
+## Key Components
+
+### `NavigationSidebarHeaderProps`
+| Prop | Type | Description |
+|------|------|-------------|
+| `minimized` | `boolean` | Controls whether the sidebar is in collapsed state |
+
+### `NavigationSidebarHeader`
+Renders a fixed-height (`h-14`) header containing:
+- **`OpenFrameLogo`** — Always visible; uses CSS design tokens for primary text and accent colors
+- **`OpenFrameText`** — Fades in/out with a smooth `opacity` + `margin-left` CSS transition (300ms); hidden from accessibility tree via `aria-hidden` when minimized
+
+## Usage Example
+
+```typescript
+import { NavigationSidebarHeader } from './navigation-sidebar-header'
+
+function Sidebar() {
+  const [minimized, setMinimized] = useState(false)
+
+  return (
+    <aside>
+      <NavigationSidebarHeader minimized={minimized} />
+      {/* rest of sidebar content */}
+    </aside>
+  )
+}
+```
+
+## Notes
+- Uses `cn()` utility for conditional class merging
+- Relies on CSS design tokens (`--color-text-primary`, `--color-accent-primary`, `--spacing-system-m`, `--spacing-system-xs`) for theming — ensure these variables are defined in the global stylesheet
+- The text element uses `overflow-hidden` + `min-w-0` to prevent layout shift during the collapse transition

package/src/components/navigation/.navigation-sidebar-item.md

@@ -0,0 +1,45 @@
+<!-- source-hash: c8f7676bd726a51b4cf502a4fd6cee17 -->
+Renders an individual navigation sidebar button with support for active state, disabled state, icon rendering, collapsible label visibility, and optional badge display.
+
+## Key Components
+
+### `NavigationSidebarItemButtonProps`
+| Prop | Type | Description |
+|------|------|-------------|
+| `item` | `NavigationSidebarItem` | Navigation item data (label, icon, badge, isActive) |
+| `showLabel` | `boolean` | Controls label and badge visibility (collapsed/expanded sidebar) |
+| `disabled` | `boolean` | Disables interaction and applies reduced-opacity styling |
+| `onClick` | `(item, event?) => void` | Click handler receiving the item and optional mouse event |
+
+### `NavigationSidebarItemButton`
+The primary exported component. Applies four distinct visual states via `cn()`:
+
+| State | Appearance |
+|-------|-----------|
+| Default | Primary text, secondary icon fill |
+| Hover (not active) | `ods-bg-hover` background |
+| Active | Yellow-light background, accent text/icon, left accent border |
+| Disabled | 50% opacity, `not-allowed` cursor |
+
+## Usage Example
+
+```typescript
+import { NavigationSidebarItemButton } from './navigation-sidebar-item'
+import { HomeIcon } from '../icons'
+
+const item = {
+  label: 'Dashboard',
+  icon: <HomeIcon />,
+  isActive: true,
+  badge: '3',
+}
+
+<NavigationSidebarItemButton
+  item={item}
+  showLabel={true}
+  disabled={false}
+  onClick={(item, event) => console.log('Navigating to', item.label)}
+/>
+```
+
+> **Note:** The icon is rendered via `cloneElement` to inject the appropriate `color` prop based on active/disabled state. Ensure icons accept an `IconProps`-compatible interface (`color`, `className`).

package/src/components/navigation/.navigation-sidebar-toggle.md

@@ -0,0 +1,38 @@
+<!-- source-hash: 239b864e6e86694ea92908db743917ff -->
+A client-side toggle button component for collapsing/expanding the navigation sidebar, with animated chevron icon and a fade-in/out label.
+
+## Key Components
+
+### `NavigationSidebarToggleProps`
+| Prop | Type | Description |
+|------|------|-------------|
+| `minimized` | `boolean` | Whether the sidebar is currently collapsed; rotates the chevron 180° |
+| `showLabel` | `boolean` | Controls opacity/margin animation of the "Hide Menu" label |
+| `onToggle` | `() => void` | Callback fired when the button is clicked |
+
+### `NavigationSidebarToggle`
+A full-width button rendered inside a top-bordered container. Uses `Chevrons03LeftIcon` with a CSS rotation transform when minimized, and a `<span>` label that transitions opacity and margin-left based on `showLabel`.
+
+## Usage Example
+
+```typescript
+import { NavigationSidebarToggle } from './navigation-sidebar-toggle'
+import { useState } from 'react'
+
+export function Sidebar() {
+  const [minimized, setMinimized] = useState(false)
+
+  return (
+    <nav className={minimized ? 'w-16' : 'w-64'}>
+      {/* sidebar content */}
+      <NavigationSidebarToggle
+        minimized={minimized}
+        showLabel={!minimized}
+        onToggle={() => setMinimized(prev => !prev)}
+      />
+    </nav>
+  )
+}
+```
+
+> **Note:** `showLabel` and `minimized` are intentionally separate props — this allows the label fade-out animation to complete before the sidebar fully collapses, decoupling visual transitions from layout state.