@flamingo-stack/openframe-frontend-core 0.0.212 → 0.0.213-snapshot.20260528174436

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.

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

@@ -1,47 +1,46 @@
-<!-- source-hash: 8c6b1731317ceb2fdadddd784b3f86f1 -->
-A responsive navigation sidebar component that adapts to different screen sizes with collapsible functionality and mobile overlay support.
+<!-- source-hash: 6f802a22aab4156f34b7564f49df9553 -->
+Responsive navigation sidebar component that renders a collapsible, accessible side navigation panel with distinct behavior for tablet (overlay/floating) and desktop (push layout) viewports.
 
 ## Key Components
 
-- **NavigationSidebar**: Main component that renders a collapsible sidebar with navigation items
-- **NavigationSidebarProps**: Interface defining the configuration prop
-- **renderNavigationItem**: Renders individual navigation items with active states and badges
-- **renderSidebarContent**: Renders the complete sidebar content structure
-- **Constants**: `MINIMIZED_WIDTH` (56px) and `EXPANDED_WIDTH` (224px) for responsive sizing
+| Export | Type | Description |
+|--------|------|-------------|
+| `NavigationSidebar` | Component | Main sidebar component with responsive layout logic |
+| `NavigationSidebarProps` | Interface | Props: `config: NavigationSidebarConfig`, `disabled?: boolean` |
+| `MINIMIZED_WIDTH` | Constant | Collapsed width: `56px` |
+| `EXPANDED_WIDTH` | Constant | Expanded width: `224px` |
+| `STORAGE_KEY` | Constant | localStorage key for desktop minimized state |
+
+### Behavior by Breakpoint
+
+| Viewport | Behavior | State Persistence |
+|----------|----------|-------------------|
+| `< md` | Hidden | — |
+| `md` (tablet) | Floating overlay, starts minimized | In-memory only |
+| `≥ lg` (desktop) | Push layout | localStorage |
+
+### Key Internal Logic
+
+- **`minimized`** — resolves to `tabletMinimized` or `desktopMinimized` based on viewport
+- **`transitionsEnabled`** — deferred via `requestAnimationFrame` to prevent flash of wrong width on hydration
+- **`isOverlayOpen`** — drives backdrop scrim visibility and `Escape` key dismissal
+- **`primaryItems` / `secondaryItems`** — items split by `section !== 'secondary'` filter
 
 ## Usage Example
 
 ```typescript
 import { NavigationSidebar } from './navigation-sidebar'
-import { HomeIcon, SettingsIcon } from '../icons'
+import { NavigationSidebarConfig } from '../../types/navigation'
 
-const sidebarConfig = {
+const config: NavigationSidebarConfig = {
+  minimized: false,
   items: [
-    {
-      id: 'home',
-      label: 'Home',
-      icon: <HomeIcon />,
-      path: '/',
-      isActive: true
-    },
-    {
-      id: 'settings',
-      label: 'Settings',
-      icon: <SettingsIcon />,
-      path: '/settings',
-      section: 'secondary',
-      badge: '2'
-    }
+    { id: 'dashboard', label: 'Dashboard', path: '/dashboard', icon: HomeIcon },
+    { id: 'settings', label: 'Settings', path: '/settings', icon: SettingsIcon, section: 'secondary' },
   ],
-  onNavigate: (path: string) => router.push(path),
-  onToggleMinimized: () => console.log('Sidebar toggled')
-}
-
-function App() {
-  return (
-    <NavigationSidebar config={sidebarConfig} />
-  )
+  onNavigate: (path) => router.push(path),
+  onToggleMinimized: () => console.log('toggled'),
 }
-```
 
-The component automatically handles minimization state persistence via localStorage, responsive behavior across screen sizes, and provides accessibility features including ARIA labels and keyboard navigation support.
+<NavigationSidebar config={config} disabled={false} />
+```