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

package/src/stories/.Input.stories.md

@@ -1,37 +1,55 @@
-<!-- source-hash: a3859660c7d3a8b22e6e69ab0562e5b2 -->
-Storybook stories file that demonstrates various configurations and states of the Input component, including different adornment combinations, disabled/invalid states, and preview modes.
+<!-- source-hash: 07edf12b9aece7d3d65330a955505e1f -->
+Storybook stories for the `Input` UI component, demonstrating all supported variants, adornments, states, and compositions.
 
 ## Key Components
 
-- **meta**: Storybook metadata defining the component path and configuration
-- **Story exports**: Individual story variants showcasing different Input component states:
-  - `Default` - Basic input without adornments
-  - `WithEndAdornmentText` - Input with text suffix (e.g., "Seconds")
-  - `WithStartAdornmentIcon` - Input with leading icon
-  - `WithBothAdornments` - Input with both start and end adornments
-  - `WithEndAdornmentIcon` - Input with trailing icon
-  - `DisabledWithAdornments` - Disabled state with adornments
-  - `InvalidWithAdornments` - Error state with adornments
-  - `WithValueAndEndAdornment` - Pre-filled input with suffix
-  - `NumberWithUnit` - Numeric input with unit display
-  - `Preview` - Non-interactive display mode
-  - `PreviewWithBothAdornments` - Preview with start/end adornments
-  - `AllVariants` - Comparison view of multiple states
+| Export | Description |
+|--------|-------------|
+| `Default` | Basic input with placeholder text |
+| `WithEndAdornmentText` | Input with trailing text label (e.g., "Seconds") |
+| `WithStartAdornmentIcon` | Input with leading icon/emoji |
+| `WithBothAdornments` | Input with both start and end adornments (e.g., currency) |
+| `DisabledWithAdornments` | Disabled state with adornments |
+| `InvalidWithAdornments` | Error/invalid state with adornments |
+| `WithLabel` | Input with a visible label |
+| `WithLabelAndError` | Input with label and validation error message |
+| `SearchInput` | Controlled input with `SearchIcon` start adornment |
+| `Loading` | Input with loading spinner state |
+| `WithButton` | Input paired with a submit `Button` |
+| `AllVariants` | Side-by-side showcase of all input states |
 
 ## Usage Example
 
 ```typescript
-// Import stories in Storybook
-import { Default, WithEndAdornmentText } from './Input.stories';
-
-// Each story demonstrates specific Input configurations
-export const MyStory = {
-  args: {
-    placeholder: 'Custom placeholder',
-    disabled: true,
-    className: 'max-w-md'
-  }
-};
-```
-
-The stories cover the full range of Input component functionality including adornments, validation states, preview modes, and accessibility considerations for comprehensive UI testing and documentation.
+// Basic input
+<Input placeholder="Enter text..." />
+
+// With adornments
+<Input
+  placeholder="0.00"
+  startAdornment="$"
+  endAdornment="USD"
+/>
+
+// With label and error
+<Input
+  label="Username"
+  placeholder="Enter text..."
+  error="This field is required"
+/>
+
+// Controlled search input with icon
+const [value, setValue] = useState('');
+<Input
+  value={value}
+  onChange={(e) => setValue(e.target.value)}
+  placeholder="Search..."
+  startAdornment={<SearchIcon size={20} />}
+/>
+
+// Disabled state
+<Input placeholder="90" endAdornment="Seconds" disabled />
+
+// Loading state
+<Input placeholder="Searching..." loading={true} startAdornment={<SearchIcon size={20} />} />
+```

package/src/stories/.ListPageLayout.stories.md

@@ -1,54 +1,67 @@
-<!-- source-hash: 42fb809c51041597bb10508f1fbd13f5 -->
-A comprehensive Storybook configuration file that showcases the `ListPageLayout` component through multiple interactive stories and usage examples. This file demonstrates different layout configurations, states, and real-world implementations for standardized list-based pages in the OpenFrame application.
+<!-- source-hash: 5bd98e591bdfac5e0da78b79f15c4945 -->
+Storybook stories for the `ListPageLayout` component, showcasing layout variants, interactive states, and real-world page examples used across the OpenFrame application.
 
 ## Key Components
 
-- **Story Configuration**: Complete Storybook meta configuration with layout documentation
-- **Sample Data**: Mock device data and table column definitions for realistic examples
-- **Story Variants**: 15+ different story configurations covering various use cases
-- **Interactive Examples**: Working search functionality and state management demonstrations
-- **Real-world Examples**: Scripts page and Logs page layout implementations
+| Story | Description |
+|---|---|
+| `Basic` | Minimal layout with title, search bar, and table |
+| `WithHeaderActions` | Layout with Refresh and Add Device action buttons |
+| `WithViewToggle` | Layout with list/grid view switcher |
+| `WithError` | Error state rendering |
+| `WithSearchValue` | Pre-filled search input |
+| `EmptyState` | Table with no data and empty message |
+| `SmallPadding` / `LargePadding` | Padding size variants (`sm`, `lg`) |
+| `CardBackground` | Card-style background variant |
+| `Interactive` | Fully functional search with live filtering |
+| `ScriptsPageExample` | Real-world Scripts page layout mock |
+| `LogsPageExample` | Real-world Logs page layout mock |
 
 ## Usage Example
 
 ```typescript
-// Basic story implementation
-export const Basic: Story = {
-  args: {
-    title: 'Devices',
-    searchPlaceholder: 'Search devices...',
-    searchValue: '',
-    onSearch: () => {},
-    children: (
-      <Table
-        data={sampleDevices}
-        columns={deviceColumns}
-        rowKey="id"
-      />
-    )
-  }
-}
+import { ListPageLayout } from '../components/layout/list-page-layout'
+import { Table } from '../components/ui/table'
+import { Button } from '../components/ui/button'
+import { useState } from 'react'
+
+function DevicesPage() {
+  const [searchValue, setSearchValue] = useState('')
+
+  const filtered = devices.filter(d =>
+    d.name.toLowerCase().includes(searchValue.toLowerCase())
+  )
 
-// Interactive story with state management
-export const Interactive: Story = {
-  render: function InteractiveStory() {
-    const [searchValue, setSearchValue] = useState('')
-    
-    const filteredDevices = sampleDevices.filter(device =>
-      device.name.toLowerCase().includes(searchValue.toLowerCase())
-    )
-
-    return (
-      <ListPageLayout
-        title="Devices"
-        searchValue={searchValue}
-        onSearch={setSearchValue}
-      >
-        <Table data={filteredDevices} columns={deviceColumns} rowKey="id" />
-      </ListPageLayout>
-    )
-  }
+  return (
+    <ListPageLayout
+      title="Devices"
+      headerActions={
+        <Button variant="accent" size="small-legacy">
+          Add Device
+        </Button>
+      }
+      searchPlaceholder="Search devices..."
+      searchValue={searchValue}
+      onSearch={setSearchValue}
+      padding="md"
+      background="default"
+    >
+      <Table data={filtered} columns={deviceColumns} rowKey="id" />
+    </ListPageLayout>
+  )
 }
 ```
 
-The file includes comprehensive documentation showing the layout structure, key features like responsive design and accessibility support, and demonstrates various states including error handling, empty states, and different padding/background configurations.
+## Layout Structure
+
+```text
+┌──────────────────────────────────────────────────┐
+│ Title (left)          │   Header Actions (right) │
+├──────────────────────────────────────────────────┤
+│              Search Bar (full width)             │
+├──────────────────────────────────────────────────┤
+│           Table / Grid (main content)            │
+└──────────────────────────────────────────────────┘
+```
+
+**Props:** `padding` (`none` | `sm` | `md` | `lg`), `background` (`default` | `card` | `transparent`), `error` (string), `headerActions` (ReactNode), `searchPlaceholder`, `searchValue`, `onSearch`.

package/src/stories/.MingoOnboardingCard.stories.md

@@ -0,0 +1,42 @@
+<!-- source-hash: 3d1f4ac24e4bcadba43f4bdf62347d8d -->
+Storybook stories for `MingoOnboardingCard`, the single-row card used in Mingo's chat empty-state list. Covers isolated prop variants and a full stacked list mirroring the Figma empty-state layout.
+
+## Key Components
+
+| Export | Description |
+|--------|-------------|
+| `Default` | Base card with icon, title, slash command, and description |
+| `WithoutDescription` | Card omitting the description field |
+| `WithoutSlashCommand` | Card omitting the slash command badge |
+| `LongTitleTruncates` | Validates truncation behavior for long titles and commands |
+| `Clickable` | Card with an `onClick` handler wired to console output |
+| `WithActions` | Card with multiple outline-chip action buttons (Recent, Search, Find) |
+| `ChipCommands` | Full stacked list of 13 cards driven by `SAMPLE_CHIP_COMMANDS`, mirroring Figma node `7363:205938` |
+
+## Usage Example
+
+```typescript
+// Single card with actions
+<MingoOnboardingCard
+  icon={<CompassIcon size={16} />}
+  title="ClickUp Roadmap"
+  slashCommand="/roadmap"
+  description="Public product roadmap with upcoming features and releases"
+  actions={[
+    { id: 'recent', label: 'Recent', onClick: () => {} },
+    { id: 'search', label: 'Search', onClick: () => {} },
+  ]}
+/>
+
+// Stacked list — icons resolved from the shared registry
+const Icon = resolveOnboardingIcon('rocket-02')
+<MingoOnboardingCard
+  icon={<Icon size={16} />}
+  title="Product Releases"
+  slashCommand="/release-notes"
+  description="OpenFrame version releases, changelogs, and update notes"
+  actions={[{ id: 'recent', label: 'Recent', onClick: () => {} }]}
+/>
+```
+
+> **Decorator context:** All stories wrap cards inside a `rounded-md` border container. The bottom border on each card acts as a 1-px divider between siblings, collapsed on the last row via `last:border-b-0`.

package/src/stories/.MingoOnboardingCardSkeleton.stories.md

@@ -0,0 +1,35 @@
+<!-- source-hash: 0762ecc460541acf4d69c0515fbfa03a -->
+Storybook stories for the `MingoOnboardingCardSkeleton` and `MingoOnboardingListSkeleton` loading-state components, covering list variants by row count and individual card configurations.
+
+## Key Components
+
+| Story | Description |
+|---|---|
+| `Default` | List skeleton with 6 rows (standard empty-state replacement) |
+| `FewRows` | List skeleton with 3 rows |
+| `ManyRows` | List skeleton with 13 rows |
+| `SingleRowDefault` | Isolated single card skeleton with default props |
+| `SingleRowOneLine` | Single card with one description line |
+| `SingleRowNoChips` | Single card with chip placeholders removed |
+| `SingleRowCustomWidths` | Single card with custom `titleWidth`, `slashWidth`, and `chipWidths` |
+
+## Usage Example
+
+```typescript
+// List skeleton — drop-in for the resolved onboarding card stack
+<MingoOnboardingListSkeleton rows={6} />
+
+// Single card skeleton with custom placeholder widths
+<MingoOnboardingCardSkeleton
+  titleWidth="w-48"
+  slashWidth="w-28"
+  descriptionLines={1}
+  chipWidths={['w-20', 'w-16', 'w-14']}
+/>
+```
+
+## Notes
+
+- Stories are wrapped in a `w-[520px]` container with `bg-ods-bg` to simulate the live empty-state shell.
+- `MingoOnboardingCardSkeleton` mirrors `MingoOnboardingCard` markup pixel-for-pixel (Figma node `7363:205938`), including `p-[var(--spacing-system-s)]`, `bg-ods-card`, `border-b` dividers, `size-4` icon slots, and `h-7` chip placeholders.
+- `MingoOnboardingListSkeleton` wraps N rows in the same `rounded-md border overflow-hidden` shell used by the live component.

package/src/stories/.Modal.stories.md

@@ -1,40 +1,49 @@
-<!-- source-hash: 92deb6f495f4d960c222f426fbbf3406 -->
-Storybook configuration file that defines interactive stories for the Modal component, demonstrating different use cases including basic modals and modals containing autocomplete functionality.
+<!-- source-hash: a814b843aeaf82abd73ff945b405ef13 -->
+Storybook stories for the `Modal` UI component, demonstrating two interaction patterns: a basic modal with header/content/footer, and a modal containing an `Autocomplete` dropdown with portal-aware rendering.
 
 ## Key Components
 
-- **Default Story** - Basic modal with header, content, and footer sections
-- **WithAutocomplete Story** - Modal containing an autocomplete dropdown with proper z-index handling
-- **Meta Configuration** - Storybook metadata with component controls for `isOpen` and `className` props
-- **AutocompleteOptions** - Sample data for industry selection in the autocomplete story
+| Export | Description |
+|---|---|
+| `Default` | Basic modal story with open/close toggle, header, body text, and Cancel/Confirm footer buttons |
+| `WithAutocomplete` | Modal story embedding an `Autocomplete` multi-select with `overflow-visible` and a `ref` callback to capture the modal DOM node for portal containment |
 
 ## Usage Example
 
 ```typescript
-// Basic modal story structure
-export const MyModalStory: Story = {
-  args: {
-    isOpen: true,
-    onClose: fn(),
-  },
-  render: function Render(args) {
-    const [isOpen, setIsOpen] = useState(args.isOpen)
-    
-    return (
-      <Modal isOpen={isOpen} onClose={() => setIsOpen(false)}>
-        <ModalHeader>
-          <ModalTitle>Example Modal</ModalTitle>
-        </ModalHeader>
-        <ModalContent className="px-6 py-4">
-          <p>Modal content goes here</p>
-        </ModalContent>
-        <ModalFooter>
-          <Button onClick={() => setIsOpen(false)}>Close</Button>
-        </ModalFooter>
-      </Modal>
-    )
-  }
-}
+// Default modal pattern
+<Modal isOpen={isOpen} onClose={() => setIsOpen(false)}>
+  <ModalHeader>
+    <ModalTitle>Modal Title</ModalTitle>
+  </ModalHeader>
+  <ModalContent className="px-6 py-4">
+    <p>Modal body content</p>
+  </ModalContent>
+  <ModalFooter>
+    <Button variant="outline" onClick={() => setIsOpen(false)}>Cancel</Button>
+    <Button variant="accent" onClick={() => setIsOpen(false)}>Confirm</Button>
+  </ModalFooter>
+</Modal>
+
+// Autocomplete inside modal — capture modal ref to avoid z-index conflicts
+const [modalElement, setModalElement] = useState<HTMLDivElement | null>(null)
+const modalRef = useCallback((node: HTMLDivElement | null) => {
+  setModalElement(node)
+}, [])
+
+<Modal ref={modalRef} isOpen={isOpen} onClose={...} className="max-w-lg overflow-visible">
+  <ModalContent className="px-6 py-4">
+    <Autocomplete
+      options={options}
+      value={selected}
+      onChange={setSelected}
+      placeholder="Search..."
+    />
+  </ModalContent>
+</Modal>
 ```
 
-The stories demonstrate proper modal state management, portal rendering for dropdowns, and responsive design patterns within the Flamingo design system.
+## Notes
+
+- `WithAutocomplete` uses `useCallback` ref to capture the modal DOM node, enabling dropdown portals to render inside the modal's subtree and avoid z-index stacking issues.
+- Both stories manage `isOpen` via local `useState`, decoupled from Storybook's `args.isOpen` control after initial render.

package/src/stories/.NotificationDrawer.stories.md

@@ -0,0 +1,55 @@
+<!-- source-hash: fd9f374934342611a000534ff097b06e -->
+Storybook stories for the `NotificationDrawer` feature, providing interactive visual tests for notification tile variants, drawer states, and live notification dispatching via the `useNotifications` hook.
+
+## Key Components
+
+| Export | Description |
+|---|---|
+| `AllTileVariants` | Static preview of all five `NotificationVariant` tile styles (`default`, `success`, `error`, `warning`, `info`) in a settled/read state |
+| `LiveTile` | Demonstrates the animated progress-bar lifecycle of a freshly arrived tile, with a replay button |
+| `DrawerEmpty` | Drawer rendered with zero notifications (empty state), auto-opened on mount |
+| `DrawerWithSeedData` | Drawer pre-seeded with six notifications mirroring the Figma reference design |
+| `LivePlayground` | Interactive sandbox for firing notifications of any variant, toggling the drawer, and testing `markAllRead`/`clear` |
+
+## Usage Example
+
+```typescript
+// Minimal setup mirroring how stories bootstrap the notification system
+import {
+  NotificationsProvider,
+  NotificationDrawer,
+  useNotifications,
+} from '../components/features/notifications';
+
+function App() {
+  return (
+    <NotificationsProvider
+      initialNotifications={[]}
+      onHistoryClick={() => router.push('/notifications')}
+      onShowPopupsChange={(enabled) => console.log('popups:', enabled)}
+    >
+      <NotificationDrawer />
+      <FireButton />
+    </NotificationsProvider>
+  );
+}
+
+function FireButton() {
+  const { addNotification } = useNotifications();
+  return (
+    <button
+      onClick={() =>
+        addNotification({
+          variant: 'success',
+          title: 'Deployment Complete',
+          description: 'HP EliteBook deployed to Marketing Dept',
+        })
+      }
+    >
+      Fire notification
+    </button>
+  );
+}
+```
+
+> Mount `<NotificationsProvider>` once at the app root. The `<NotificationDrawer>` can be placed anywhere within the provider tree; the bell button in `AppHeader` toggles it automatically.

package/src/stories/.OnboardingStepCard.stories.md

@@ -0,0 +1,41 @@
+<!-- source-hash: d74b86d195ef9df34ce86e9fde4c0258 -->
+Storybook stories for the `OnboardingStepCard` component, covering all visual states and a full list layout as seen on the Get Started page.
+
+## Key Components
+
+| Export | Description |
+|--------|-------------|
+| `Default` | Pending state — shows **Skip Step** + primary action button |
+| `Completed` | Success state — shows completed badge + **Manage** button |
+| `Skipped` | Skipped state — shows only the **SKIPPED** badge |
+| `CheckingCompletion` | Loading skeleton while completion status is being fetched |
+| `List` | Full multi-step list replicating the Get Started page layout |
+
+## Usage Example
+
+```typescript
+// Render a pending onboarding step
+<OnboardingStepCard
+  step={{
+    id: 'invite-users',
+    title: 'Company & Team',
+    description: 'Invite team members and set up roles',
+    actionIcon: (color?) => <UserPlusIcon color={color} size={20} />,
+    actionText: 'Invite Users',
+    completedText: 'Manage Users',
+    onAction: () => console.log('action'),
+    onSkip: () => console.log('skip'),
+  }}
+  isCompleted={false}
+  isSkipped={false}
+  isCheckingCompletion={false}
+  onAction={() => console.log('action')}
+  onSkip={() => console.log('skip')}
+/>
+```
+
+## Notes
+
+- The card itself has **no hover state or click handler** — only the inner buttons (`Skip Step`, `Action`, `Manage`) are interactive.
+- The `List` story is useful for verifying that hovering a row does **not** change its border or background.
+- Stories use `layout: 'padded'` and are tagged with `autodocs` for automatic documentation generation.

package/src/stories/.OrganizationCard.stories.md

@@ -0,0 +1,61 @@
+<!-- source-hash: ce4a821de2f69b4718eaed524e6db5f1 -->
+Storybook stories for the `OrganizationCard` UI component, demonstrating all supported props and visual variants for displaying organizations with logos, stats, navigation links, and action buttons.
+
+## Key Components
+
+| Story | Description |
+|---|---|
+| `Default` | Basic card with full organization data and no extras |
+| `WithImage` | Card with organization logo, link, and device count |
+| `WithLink` | Card rendered as a clickable anchor |
+| `WithDeviceCount` | Badge showing total device count in the top-right corner |
+| `WithFooterStats` | Footer row with icon/value/label stat items (devices, MRR) |
+| `WithActionButton` | Destructive action button (e.g. Remove) via `actionButton` prop |
+| `WithPrimaryAction` | Primary variant action button (e.g. Deploy) |
+| `Minimal` | Card with only `id` and `name` populated |
+| `NoDescription` | Card with industry/tier but no description |
+| `WithCustomFooter` | Arbitrary JSX injected as a custom footer slot |
+
+## Usage Example
+
+```typescript
+import { OrganizationCard } from '../components/ui/organization-card'
+import { Server } from 'lucide-react'
+
+// Basic card
+<OrganizationCard
+  organization={{
+    id: '1',
+    name: 'Acme Corporation',
+    industry: 'Technology',
+    description: 'Enterprise cloud infrastructure provider.',
+    totalDevices: 142,
+    activeDevices: 138,
+    mrrUsd: 12500,
+  }}
+  href="/organizations/details/1"
+  deviceCount={142}
+  footerStats={[
+    { icon: <Server className="h-4 w-4" />, value: 142, label: 'devices' },
+  ]}
+  showActionButton
+  actionButton={{
+    icon: <Server className="h-4 w-4" />,
+    label: 'Deploy',
+    onClick: (org) => console.log('Deploy:', org.id),
+    variant: 'primary',
+  }}
+/>
+```
+
+## ArgTypes Reference
+
+| Prop | Type | Description |
+|---|---|---|
+| `organization` | `Organization` | Core data object (id, name, industry, description, stats) |
+| `href` | `string` | Makes the card a navigable link |
+| `fetchedImageUrl` | `string` | Pre-fetched logo URL from `useBatchImages` |
+| `deviceCount` | `number` | Badge count shown in the top-right corner |
+| `showActionButton` | `boolean` | Toggles the action button visibility |
+| `footerStats` | `FooterStat[]` | Icon + value + label rows in the card footer |
+| `customFooter` | `ReactNode` | Arbitrary JSX rendered in the footer slot |

package/src/stories/.PageActions.stories.md

@@ -1,57 +1,60 @@
-<!-- source-hash: 4657c4764fe08f50aea5c6e9ef6be715 -->
-Storybook configuration file for the PageActions UI component, demonstrating its three main variants: icon buttons for list pages, primary buttons for forms, and a menu+primary combination for complex actions.
+<!-- source-hash: cad0666dc893f948d0160200a40d9384 -->
+Storybook stories file for the `PageActions` component, documenting all interactive variants and states for use in the Flamingo/OpenFrame UI library.
 
 ## Key Components
 
-- **Meta Configuration**: Storybook metadata defining component parameters, layout settings, and documentation
-- **Story Variants**: Multiple story examples showcasing different PageActions configurations:
-  - `IconButtons` - Icon-based actions that collapse to dropdown on mobile
-  - `PrimaryButtons` - Primary and outline button combinations
-  - `MenuPrimary` - MoreActionsMenu with primary button setup
-- **Component Props**: Demonstrates `variant`, `actions`, `menuActions`, `gap`, and responsive behavior
-- **State Examples**: Loading states, disabled states, and mobile-only actions
+**Exported Stories:**
+
+| Story | Variant | Description |
+|---|---|---|
+| `IconButtons` | `icon-buttons` | Icon + label buttons, collapses to dropdown on mobile |
+| `PrimaryButtons` | `primary-buttons` | Accent + outline buttons, fixed bottom bar on mobile |
+| `PrimaryButtonsWithIcons` | `primary-buttons` | Primary buttons with leading icons |
+| `SinglePrimaryButton` | `primary-buttons` | Single accent CTA |
+| `SingleIconButton` | `icon-buttons` | Single icon button (stays visible on mobile, no menu collapse) |
+| `ThreeIconButtons` | `icon-buttons` | Three-action icon row |
+| `WithStates` | `primary-buttons` | `loading` and `disabled` prop states |
+| `MenuPrimary` | `menu-primary` | `...` overflow menu + primary button |
+| `MenuPrimaryLoading` | `menu-primary` | Loading state on primary button |
+| `MobileOnlyActions` | `icon-buttons` | `showOnlyMobile` prop — hides specific actions on desktop |
+| `LinkActions` | `menu-primary` | `href`-based actions rendering as `<a>` elements |
+| `SplitButtonWithMenu` | `menu-primary` | `submenu` chevron split button pattern |
+| `SplitButtonTwoActions` | `menu-primary` | `iconAction` dual-target split button |
 
 ## Usage Example
 
 ```typescript
-// Basic icon buttons story
-export const IconButtons: Story = {
-  args: {
-    variant: 'icon-buttons',
-    actions: [
-      {
-        label: 'Edit Categories',
-        onClick: fn(),
-        icon: <ColorsIcon size={24} />,
-      },
-      {
-        label: 'Add Script', 
-        onClick: fn(),
-        icon: <PlusCircleIcon size={24} />,
-      },
-    ],
-  },
-}
+// Basic icon-buttons usage in a page header
+<PageActions
+  variant="icon-buttons"
+  actions={[
+    { label: 'Add Script', onClick: handleAdd, icon: <PlusCircleIcon size={24} /> },
+    { label: 'Edit Categories', onClick: handleEdit, icon: <ColorsIcon size={24} /> },
+  ]}
+/>
+
+// menu-primary with split button and overflow menu
+<PageActions
+  variant="menu-primary"
+  actions={[
+    {
+      label: 'Remote Shell',
+      variant: 'outline',
+      submenu: [
+        { id: 'cmd', label: 'CMD', onClick: openCmd, icon: <TerminalIcon size={24} /> },
+        { id: 'powershell', label: 'Power Shell', onClick: openPs, icon: <TerminalIcon size={24} /> },
+      ],
+    },
+  ]}
+  menuActions={[
+    {
+      items: [
+        { id: 'edit', label: 'Edit Device', onClick: handleEdit, icon: <PenEditIcon size={24} /> },
+        { id: 'delete', label: 'Delete Device', onClick: handleDelete, icon: <TrashIcon size={24} /> },
+      ],
+    },
+  ]}
+/>
+```
 
-// Menu + primary variant with dropdown actions
-export const MenuPrimary: Story = {
-  args: {
-    variant: 'menu-primary',
-    actions: [
-      {
-        label: 'Run Script',
-        onClick: fn(),
-        variant: 'primary',
-        icon: <PlayCircleIcon size={24} />,
-      },
-    ],
-    menuActions: [
-      {
-        label: 'Edit Script',
-        onClick: fn(),
-        icon: <PenEditIcon size={24} />,
-      },
-    ],
-  },
-}
-```
+> **Tip:** Use `PageActions` via the `headerActions` prop on `PageContainer` for consistent page-level layouts across the Flamingo platform.