@flamingo-stack/openframe-frontend-core 0.0.213 → 0.0.214

package/src/components/loading/.index.md

@@ -1,55 +1,48 @@
-<!-- source-hash: 766a56f3c8aa7fc2b9d10d145974687d -->
-A comprehensive index file that exports all skeleton loading components and filtering utilities from the Flamingo UI system, providing a centralized entry point for loading states and content filtering functionality.
+<!-- source-hash: 6f6dc44a9f25ba3b463f1c1d0d5381af -->
+Barrel export file for the skeleton/loading component library, consolidating all skeleton UI components used across the Flamingo/OpenFrame platform into a single import surface.
 
 ## Key Components
 
-**Page Layout Skeletons:**
-- `AnnouncementBarSkeleton`, `HeroSkeleton`, `SearchContainerSkeleton` - Main page structure loading states
-- `TwoColumnLayoutSkeleton`, `ArticleLayoutSkeleton`, `VendorDetailLayoutSkeleton` - Content layout skeletons
-- `CategorySidebarSkeleton`, `BreadcrumbSkeleton`, `ResultsHeaderSkeleton` - Navigation and header skeletons
+### Page Layout Skeletons
+| Export | Source |
+|--------|--------|
+| `AnnouncementBarSkeleton`, `HeroSkeleton`, `SearchContainerSkeleton` | `./page-layout-skeleton` |
+| `TwoColumnLayoutSkeleton`, `ArticleLayoutSkeleton`, `VendorDetailLayoutSkeleton` | `./page-layout-skeleton` |
+| `BlogCardGridSkeleton`, `VendorGridSkeleton`, `StatsSectionSkeleton` | `./page-layout-skeleton` |
+
+### Card & Content Skeletons
+- **`CardSkeleton`, `CardSkeletonGrid`** — Generic card placeholders
+- **`ParagraphSkeleton`, `ListSkeleton`, `TableSkeleton`, `FormSkeleton`** — Content-type specific loaders
+- **`ProfileSkeleton`, `CommentSkeleton`, `TimelineSkeleton`, `PricingSkeleton`** — Specialized content skeletons
+
+### Unified / Dynamic Systems
+- **`UnifiedSkeleton`, `TextSkeleton`, `MediaSkeleton`, `InteractiveSkeleton`** — Composable primitives
+- **`DynamicSkeleton`, `SkeletonPresets`, `PlatformSkeletonContainer`, `ProgressiveSkeleton`** — ODS-aware adaptive skeletons
+- **`ContentLoadingContainer`, `useContentLoading`** — Hook + container for loading state management
+
+### Domain-Specific Skeletons
+- **`ProfileLoadingSkeleton`, `MspProfileFormSkeleton`** — MSP profile flows
+- **`OrganizationCardSkeleton`, `OrganizationCardSkeletonGrid`** — Organization management
+- **`DeviceCardSkeleton`, `DeviceCardSkeletonGrid`** — Device listing views
+- **`WizardLayoutSkeleton`**, **`MarginReportSkeleton`**, **`UsersGridSkeleton`** — Wizard, reporting, and admin views
 
-**Card Components:**
-- `CardSkeleton`, `CardSkeletonGrid` - Basic card loading states
-- `CategoryCardSkeleton`, `OrganizationCardSkeleton`, `DeviceCardSkeleton` - Specialized card skeletons
-
-**Unified Components:**
-- `UnifiedSkeleton`, `TextSkeleton`, `MediaSkeleton` - Flexible skeleton building blocks
-- `DynamicSkeleton`, `SkeletonPresets` - ODS-aware adaptive loading states
+## Usage Example
 
-**Content & Form Skeletons:**
-- `ParagraphSkeleton`, `ListSkeleton`, `TableSkeleton`, `FormSkeleton` - Text content loading states
-- `MspProfileFormSkeleton`, `ProfileLoadingSkeleton` - Profile-specific skeletons
+```typescript
+// Import any skeleton from a single entry point
+import {
+  TwoColumnLayoutSkeleton,
+  DynamicSkeleton,
+  useContentLoading
+} from '@/components/skeletons'
 
-**Filtering & Pagination:**
-- `useUnifiedFiltering`, `FilterState`, `FilterConfig` - Content filtering logic
-- `PersistentFilterControls`, `PersistentPagination` - Filter UI components
-- `vendorFilterConfig`, `blogFilterConfig` - Pre-configured filter sets
+export default function PageShell() {
+  const { isLoading } = useContentLoading()
 
-## Usage Example
+  if (isLoading) return <TwoColumnLayoutSkeleton />
 
-```typescript
-import { 
-  CardSkeletonGrid,
-  useUnifiedFiltering,
-  vendorFilterConfig,
-  PersistentFilterControls 
-} from '@/components/loading/skeletons'
-
-function VendorListPage() {
-  const { filters, updateFilter, isLoading } = useUnifiedFiltering(vendorFilterConfig)
-  
-  if (isLoading) {
-    return <CardSkeletonGrid count={12} />
-  }
-  
-  return (
-    <div>
-      <PersistentFilterControls 
-        filters={filters}
-        onFilterChange={updateFilter}
-      />
-      {/* Vendor content */}
-    </div>
-  )
+  return <MainContent />
 }
-```
+```
+
+> ⚠️ **Important:** `OpenmspHeartbeatLoader` is intentionally **excluded** from this barrel — it is client-only and must be imported directly from `./openmsp-heartbeat` in client components to avoid breaking server-side rendering.

package/src/components/loading/.margin-report-skeleton.md

@@ -1,43 +1,54 @@
-<!-- source-hash: ef376aa2ee23a24d8bff5b1fb35578a0 -->
-A React component that renders a skeleton loading state for a margin report page, mimicking the layout structure while data loads or when displaying placeholder content with optional overlay functionality.
+<!-- source-hash: a465f87f85ec79ae37576015929fe094 -->
+A full-page loading skeleton for the Margin Report view, rendering animated placeholder blocks that mirror the report's layout sections while optionally displaying an overlay with a CTA or status message.
 
 ## Key Components
 
-- **MarginReportSkeleton** - Main component that renders the complete skeleton UI
-- **MarginReportSkeletonProps** - Interface defining component configuration options
-  - `animate` - Controls pulse animation (default: true)
-  - `description` - Optional explanatory text above overlay
-  - `overlayContent` - Optional React node displayed over skeleton
+| Export | Type | Description |
+|--------|------|-------------|
+| `MarginReportSkeleton` | `React.FC` | Main skeleton component with pulse animation and optional overlay |
+| `MarginReportSkeletonProps` | `interface` | Props contract for the skeleton component |
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `animate` | `boolean` | `true` | Toggles CSS `animate-pulse` on the root element |
+| `description` | `React.ReactNode` | — | Explanatory text rendered above the overlay content |
+| `overlayContent` | `React.ReactNode` | — | Node rendered in a centered fixed overlay (e.g. button, spinner) |
+
+### Skeleton Sections Rendered
+
+```text
+├── Header (title + subtitle bars)
+├── Summary cards (3-column grid)
+├── MSP Profile + Report Info (2-column grid)
+├── Vendor lists — Commercial & Open-Source stacks (2-column, 5 rows each)
+├── Strategic Recommendations header + cards (3-column grid)
+└── OpenFrame value section (header + 3 value cards)
+```
 
 ## Usage Example
 
 ```typescript
-import { MarginReportSkeleton } from './margin-report-skeleton';
-
-// Basic loading skeleton
-function LoadingReport() {
-  return <MarginReportSkeleton />;
-}
-
-// With overlay content
-function ReportWithCTA() {
-  return (
-    <MarginReportSkeleton
-      animate={true}
-      description="Generate your custom margin report"
-      overlayContent={
-        <button className="btn-primary">
-          Start Analysis
-        </button>
-      }
-    />
-  );
-}
-
-// Static skeleton without animation
-function StaticPlaceholder() {
-  return <MarginReportSkeleton animate={false} />;
-}
+// Basic animated skeleton while data loads
+<MarginReportSkeleton />
+
+// Static skeleton with a gated CTA overlay
+<MarginReportSkeleton
+  animate={false}
+  description="Generate your free Margin Report to unlock insights."
+  overlayContent={
+    <Button onClick={handleGenerate}>
+      Generate Report
+    </Button>
+  }
+/>
+
+// Skeleton with a loading spinner overlay
+<MarginReportSkeleton
+  description="Calculating your margins…"
+  overlayContent={<Spinner size="lg" />}
+/>
 ```
 
-The component creates a comprehensive skeleton layout including header sections, summary cards, MSP profile cards, vendor solution lists (commercial and open-source), strategic recommendations grid, and an OpenFrame value section. The optional overlay feature allows displaying CTAs or loading indicators centered over the skeleton content.
+> **Note:** When `overlayContent` is provided, a semi-transparent overlay (`bg-ods-card/80`) covers the entire skeleton. The overlay content is viewport-centered via `fixed` positioning with pointer-events re-enabled only on the CTA container.

package/src/components/loading/.organization-card-skeleton.md

@@ -1,51 +1,46 @@
-<!-- source-hash: 336012723d59d92058cb1b5e5d7f331f -->
-A React component that provides loading skeleton placeholders for organization cards, designed to match the exact layout and dimensions of actual organization cards to prevent layout shifts during data loading.
+<!-- source-hash: 254d5d86afe2187734cde56c533fc995 -->
+Loading skeleton component that renders a placeholder matching the exact layout and dimensions of an `OrganizationCard`, preventing layout shifts during data fetching.
 
 ## Key Components
 
-- **OrganizationCardSkeleton** - Main skeleton component with configurable sections (header, description, footer)
-- **OrganizationCardSkeletonGrid** - Grid wrapper for displaying multiple skeleton cards with responsive layout
-- **OrganizationCardSkeletonProps** - TypeScript interface defining customization options
+### `OrganizationCardSkeleton`
+Single card skeleton with three configurable sections:
+- **Header** — 60×60px org logo placeholder + title/subtitle text skeletons
+- **Description** — Fixed 48px height with two-line body text skeletons (toggled via `showDescription`)
+- **Footer** — Two stat items (icon + caption) and a tag/badge placeholder (toggled via `showFooter`)
+
+### `OrganizationCardSkeletonGrid`
+Renders a responsive grid of `OrganizationCardSkeleton` instances:
+- Mobile: 1 column | Tablet (`md`): 2 columns | Desktop (`lg`): 3 columns
+
+### `OrganizationCardSkeletonProps`
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | — | Additional CSS classes |
+| `containerClassName` | `string` | — | Overrides card background & border |
+| `showFooter` | `boolean` | `true` | Renders footer stats area |
+| `showDescription` | `boolean` | `true` | Renders description area |
 
 ## Usage Example
 
 ```typescript
-import { OrganizationCardSkeleton, OrganizationCardSkeletonGrid } from "./organization-card-skeleton"
-
-// Single skeleton card
-function LoadingCard() {
-  return (
-    <OrganizationCardSkeleton 
-      showDescription={true}
-      showFooter={true}
-      className="max-w-sm"
-    />
-  )
-}
-
-// Grid of skeleton cards
-function LoadingGrid() {
-  return (
-    <OrganizationCardSkeletonGrid 
-      count={9}
-      showDescription={false}
-      containerClassName="bg-gray-100"
-    />
-  )
-}
-
-// Conditional loading state
-function OrganizationList({ isLoading, organizations }) {
-  if (isLoading) {
-    return <OrganizationCardSkeletonGrid count={12} />
-  }
-  
-  return (
-    <div className="grid grid-cols-1 md:grid-cols-2 xl:grid-cols-3 gap-4">
-      {organizations.map(org => <OrganizationCard key={org.id} {...org} />)}
-    </div>
-  )
-}
-```
-
-The skeleton maintains visual parity with the actual OrganizationCard component, including a 60x60px logo area, text placeholders for title/subtitle, optional description section, and footer with stats and badges.
+// Single card skeleton
+<OrganizationCardSkeleton
+  showDescription={true}
+  showFooter={true}
+/>
+
+// Full grid skeleton during data load
+<OrganizationCardSkeletonGrid
+  count={9}
+  showFooter={true}
+  showDescription={false}
+  className="my-4"
+/>
+
+// Custom container styling
+<OrganizationCardSkeleton
+  containerClassName="bg-gray-900 border border-gray-700"
+  showFooter={false}
+/>
+```

package/src/components/loading/.page-layout-skeleton.md

@@ -1,57 +1,46 @@
-<!-- source-hash: 404cf3b17445eee0f8d6345f40405c01 -->
-A React component that provides skeleton loading states for various page layout sections, designed to match the actual UI components during loading.
+<!-- source-hash: d81e064ec80f99a3beddcfc15467f602 -->
+Skeleton loading components for the page layout, providing animated placeholders that match the structure of major UI sections including headers, heroes, sidebars, articles, and vendor detail pages.
 
 ## Key Components
 
-**Main Layout Skeletons:**
-- `PageLayoutSkeletonProps` - Base interface for skeleton components
-- `AnnouncementBarSkeleton` - Skeleton for announcement bar with logo, text, and close button
-- `HeaderSkeleton` - Navigation header skeleton with logo, nav items, and action buttons
-- `HeroSkeleton` - Hero section skeleton with title, subtitle, and CTA button
-- `TwoColumnLayoutSkeleton` - Flexible two-column layout with configurable sidebar position
-- `ArticleLayoutSkeleton` - Full article/blog post layout with header, metadata, and content
-- `VendorDetailLayoutSkeleton` - Detailed vendor page layout (truncated in example)
-
-**Search & Navigation Skeletons:**
-- `SearchContainerSkeleton` - Search input with optional filter chips
-- `CategorySidebarSkeleton` - Sidebar with categories and filter sections
-- `BreadcrumbSkeleton` - Breadcrumb navigation trail
-- `ResultsHeaderSkeleton` - Results count and sorting controls
+| Export | Description |
+|--------|-------------|
+| `AnnouncementBarSkeleton` | Matches `AnnouncementBar` with logo, text lines, and close button placeholders |
+| `HeaderSkeleton` | Sticky header with logo, nav links, and action button skeletons |
+| `HeroSkeleton` | Full-width hero section with title, subtitle, and CTA placeholders |
+| `SearchContainerSkeleton` | Search input with optional filter chip row |
+| `CategorySidebarSkeleton` | Sidebar mimicking `MultiLevelNavigation` with folder/file icons and README badges |
+| `BreadcrumbSkeleton` | Horizontal breadcrumb trail with separator dots |
+| `ResultsHeaderSkeleton` | Results count and sort controls placeholder |
+| `TwoColumnLayoutSkeleton` | Responsive grid wrapper accepting custom sidebar/main content with configurable `sidebarPosition` |
+| `ArticleLayoutSkeleton` | Full article page skeleton with header, featured image, and paragraph blocks |
+| `VendorDetailLayoutSkeleton` | Vendor detail page with breadcrumb, hero logo/title area, and responsive layout |
 
 ## Usage Example
 
 ```typescript
-import { 
-  HeaderSkeleton, 
-  HeroSkeleton, 
+import {
+  HeaderSkeleton,
   TwoColumnLayoutSkeleton,
-  SearchContainerSkeleton 
-} from './page-layout-skeleton'
-
-// Loading state for a search page
-function SearchPageSkeleton() {
-  return (
-    <>
-      <HeaderSkeleton />
-      <div className="container mx-auto p-6">
-        <SearchContainerSkeleton showFilters={true} />
-        <TwoColumnLayoutSkeleton 
+  CategorySidebarSkeleton,
+} from "./page-layout-skeleton"
+
+// Drop-in loading state for a browse page
+function BrowsePage() {
+  if (isLoading) {
+    return (
+      <>
+        <HeaderSkeleton />
+        <TwoColumnLayoutSkeleton
+          sidebarContent={<CategorySidebarSkeleton />}
           sidebarPosition="left"
-          className="mt-8"
         />
-      </div>
-    </>
-  )
-}
-
-// Loading state for article page
-function ArticlePageSkeleton() {
-  return (
-    <div className="container mx-auto px-4">
-      <ArticleLayoutSkeleton />
-    </div>
-  )
+      </>
+    )
+  }
+  return <ActualContent />
 }
-```
 
-The skeletons use the unified skeleton components and maintain responsive design patterns with proper animations and semantic structure.
+// Inline search skeleton with filters hidden
+<SearchContainerSkeleton showFilters={false} className="my-4" />
+```

package/src/components/loading/.unified-skeleton.md

@@ -1,43 +1,69 @@
-<!-- source-hash: f42b8a7e1d3731949a7e184cfd3799e1 -->
-A comprehensive React skeleton loading component system with consistent styling and accessibility features for displaying loading states across the application.
+<!-- source-hash: 8c0e5c74de8bbbd5020de8b54978e503 -->
+Accessible loading placeholder component providing a base `UnifiedSkeleton` with specialized sub-components for consistent skeleton UI across the application.
 
 ## Key Components
 
-- **UnifiedSkeleton** - Base skeleton component with customizable variants (default, text, circular, rectangular)
-- **TextSkeleton** - Pre-configured text skeleton variants for headings, body text, and captions
-- **InteractiveSkeleton** - Skeleton components for interactive elements like buttons, inputs, and chips
-- **MediaSkeleton** - Specialized skeletons for images, avatars, and icons with proper aspect ratios
+### `UnifiedSkeleton` (base component)
+Core skeleton element with dark theme styling (`#2A2A2A` base), pulse animation, and full accessibility support.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'default' \| 'text' \| 'circular' \| 'rectangular'` | `'default'` | Shape/border-radius style |
+| `width` | `string \| number` | — | Custom width override |
+| `height` | `string \| number` | — | Custom height override |
+| `animate` | `boolean` | `true` | Toggle pulse animation (respects `prefers-reduced-motion`) |
+| `aria-label` | `string` | `"Loading content"` | Screen reader label |
+
+### `TextSkeleton` namespace
+| Export | Use Case |
+|--------|----------|
+| `TextSkeleton.Heading` | H1/H2 placeholders (`h-8` → `h-12`) |
+| `TextSkeleton.Subheading` | H3/H4 placeholders (`h-6` → `h-8`) |
+| `TextSkeleton.Body` | Paragraph text (`h-4` → `h-5`) |
+| `TextSkeleton.Caption` | Metadata/captions (`h-3` → `h-4`) |
+
+### `InteractiveSkeleton` namespace
+| Export | Use Case |
+|--------|----------|
+| `InteractiveSkeleton.Button` | Fixed-width button placeholder |
+| `InteractiveSkeleton.Input` | Full-width input field placeholder |
+| `InteractiveSkeleton.Chip` | Pill-shaped filter chip placeholder |
+
+### `MediaSkeleton` namespace
+| Export | Use Case |
+|--------|----------|
+| `MediaSkeleton.Avatar` | Circular avatar (`sm/md/lg`) |
+| `MediaSkeleton.CardImage` | `1200×630` aspect-ratio image (matches OG card, prevents layout shift) |
+| `MediaSkeleton.Icon` | Square icon placeholder (`sm/md/lg`) |
 
 ## Usage Example
 
 ```typescript
-import { UnifiedSkeleton, TextSkeleton, MediaSkeleton } from './unified-skeleton'
-
-// Basic skeleton with custom dimensions
-<UnifiedSkeleton width={200} height={100} variant="rectangular" />
-
-// Text loading states
-<TextSkeleton.Heading className="mb-4" />
-<TextSkeleton.Body className="mb-2" />
-<TextSkeleton.Caption />
-
-// Media elements
-<MediaSkeleton.Avatar size="lg" />
-<MediaSkeleton.CardImage className="mb-4" />
-
-// Interactive elements
-<InteractiveSkeleton.Button />
-<InteractiveSkeleton.Input className="mb-3" />
-
-// Custom styling and accessibility
-<UnifiedSkeleton 
-  variant="circular"
-  width={60}
-  height={60}
-  animate={false}
-  aria-label="Loading user profile"
-  className="mx-auto"
-/>
-```
-
-The component system includes mobile-responsive sizing, respects user motion preferences, and provides proper ARIA labels for screen reader accessibility.
+import {
+  UnifiedSkeleton,
+  TextSkeleton,
+  InteractiveSkeleton,
+  MediaSkeleton,
+} from "./unified-skeleton"
+
+// Basic usage
+<UnifiedSkeleton variant="rectangular" height={200} />
+
+// Composing a card loading state
+function TicketCardSkeleton() {
+  return (
+    <div className="flex gap-3 p-4">
+      <MediaSkeleton.Avatar size="md" />
+      <div className="flex-1 space-y-2">
+        <TextSkeleton.Heading className="w-3/4" />
+        <TextSkeleton.Body />
+        <TextSkeleton.Caption className="w-1/2" />
+      </div>
+      <InteractiveSkeleton.Button />
+    </div>
+  )
+}
+
+// Disable animation (e.g. for snapshot tests)
+<UnifiedSkeleton animate={false} aria-label="Loading ticket list" />
+```

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

@@ -1,47 +1,58 @@
-<!-- source-hash: a1b3156cdf394cc3dd5a1c35f3e88dd9 -->
-A responsive application header component that provides navigation, search, notifications, and user management functionality with mobile-first design and conditional feature rendering.
+<!-- source-hash: 898258d76810df35b3a9175ed9b09824 -->
+Responsive application header component for the OpenFrame platform, providing navigation controls, search, organization filtering, notifications, and user account management across mobile and desktop breakpoints.
 
 ## Key Components
 
-- **AppHeader**: Main header component with responsive layout switching between mobile and desktop views
-- **AppHeaderProps**: TypeScript interface defining all configurable props including search, organizations, notifications, and user settings
-- **Mobile Menu Integration**: Hamburger menu toggle with open/close state management
-- **Conditional Rendering**: Feature flags for search, organizations, notifications, and user sections
-- **User Dropdown**: Desktop-only dropdown menu with profile and logout actions
-- **Responsive Icons**: Different icon sizes and layouts for mobile vs desktop breakpoints
+| Export | Type | Description |
+|--------|------|-------------|
+| `AppHeader` | `React.memo` component | Main header component with full prop-driven configuration |
+| `AppHeaderProps` | Interface | Full prop contract for the header |
+| `NotificationsHeaderButton` | Internal component | Bell icon button with unread badge, integrates with `NotificationsContext` |
+
+## Props Overview
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `isMobileMenuOpen` | `boolean` | Required; controls burger menu icon state |
+| `onToggleMobileMenu` | `() => void` | Callback to toggle the mobile sidebar |
+| `disabled` | `boolean` | Dims all controls except the mobile burger toggle |
+| `showSearch` | `boolean` | Renders global search (desktop) or search button (mobile) |
+| `showOrganizations` | `boolean` | Renders org filter dropdown (large screens only) |
+| `showNotifications` | `boolean` | Renders notification bell with unread badge |
+| `showUser` | `boolean` | Renders user avatar + dropdown (desktop only) |
 
 ## Usage Example
 
 ```typescript
 import { AppHeader } from './app-header'
 
-function Layout() {
-  const [isMobileMenuOpen, setIsMobileMenuOpen] = useState(false)
-  
+export function Shell() {
+  const [mobileOpen, setMobileOpen] = React.useState(false)
+
   return (
     <AppHeader
-      showSearch={true}
-      onSearch={(query) => console.log('Search:', query)}
-      showOrganizations={true}
-      organizations={[
-        { id: '1', name: 'Acme Corp' },
-        { id: '2', name: 'Tech Solutions' }
-      ]}
-      selectedOrgId="1"
-      onOrgChange={(id) => console.log('Org changed:', id)}
-      showNotifications={true}
+      isMobileMenuOpen={mobileOpen}
+      onToggleMobileMenu={() => setMobileOpen(prev => !prev)}
+      showSearch
+      onSearch={(query) => console.log(query)}
+      showOrganizations
+      organizations={[{ id: 'org-1', name: 'Acme Corp' }]}
+      selectedOrgId="org-1"
+      onOrgChange={(id) => console.log(id)}
+      showNotifications
       unreadCount={3}
-      showUser={true}
-      userName="John Doe"
-      userEmail="john@example.com"
-      userAvatarUrl="/avatar.jpg"
-      onProfile={() => navigate('/profile')}
+      showUser
+      userName="Jane Doe"
+      userEmail="jane@acme.com"
+      onProfile={() => router.push('/profile')}
       onLogout={() => signOut()}
-      isMobileMenuOpen={isMobileMenuOpen}
-      onToggleMobileMenu={() => setIsMobileMenuOpen(!isMobileMenuOpen)}
     />
   )
 }
 ```
 
-The header automatically adapts its layout based on screen size using the `useMdUp` hook, showing a compact mobile version with essential actions and an expanded desktop version with full feature visibility.
+## Behavior Notes
+
+- **Responsive layout:** Mobile renders a burger icon + logo; desktop shows the full search bar and org filter
+- **Disabled state:** Setting `disabled={true}` applies `pointer-events-none opacity-50` to all controls except the mobile menu toggle
+- **Notifications:** Prefers live unread count from `NotificationsContext` when available, falls back to the `unreadCount` prop; switches between `BellIcon` and `BellRingingIcon` based on count