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

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

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