@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

package/src/nats/.use-nats-subscription.md

@@ -0,0 +1,57 @@
+<!-- source-hash: ec30097feafd8e14e66c0760d7da51a3 -->
+React hooks for subscribing to NATS subjects via the shared connection provided by `<NatsProvider>`, with support for both raw byte messages and JSON-decoded payloads.
+
+## Key Components
+
+### `useNatsSubscription`
+Core hook that subscribes to a NATS subject using the shared connection from `<NatsProvider>`. Automatically resubscribes when the subject changes, the connection becomes ready, or a reconnection occurs.
+
+**Parameters:**
+- `subject` — NATS subject string, or `null` to disable
+- `onMessage` — callback receiving raw `Msg` objects
+- `options` — optional `NatsSubscribeOptions` plus `enabled` flag
+
+**Returns:** `{ isSubscribed, isReady }`
+
+### `useNatsJsonSubscription`
+Convenience wrapper around `useNatsSubscription` that automatically decodes incoming message bytes as JSON and passes the parsed payload to the callback. Malformed payloads are silently ignored.
+
+**Parameters:**
+- `subject` — NATS subject string, or `null` to disable
+- `onPayload` — callback receiving `(payload: T, msg: Msg)`
+- `options` — same options as `useNatsSubscription`
+
+### `UseNatsSubscriptionOptions`
+Extends `NatsSubscribeOptions` with an `enabled?: boolean` flag to conditionally pause subscriptions without unmounting the component.
+
+## Usage Example
+
+```typescript
+// Raw byte subscription
+function MyComponent() {
+  const { isSubscribed } = useNatsSubscription(
+    'events.updates',
+    (msg) => console.log('raw bytes:', msg.data),
+    { queue: 'workers', enabled: true },
+  )
+
+  return <span>{isSubscribed ? 'Listening' : 'Disconnected'}</span>
+}
+
+// JSON subscription with typed payload
+interface TickerEvent {
+  symbol: string
+  price: number
+}
+
+function TickerDisplay() {
+  const { isReady } = useNatsJsonSubscription<TickerEvent>(
+    'market.ticker',
+    (payload, msg) => {
+      console.log(`${payload.symbol}: $${payload.price}`)
+    },
+  )
+}
+```
+
+> Both hooks stabilize the message handler via `useRef` so the subscription is not torn down on every render when an inline callback is passed.

package/src/stories/.ActionsMenu.stories.md

@@ -0,0 +1,57 @@
+<!-- source-hash: 42e64113d86d5eae0ead175437c52358 -->
+Storybook stories file for the `ActionsMenu` and `ActionsMenuDropdown` components, providing interactive visual documentation of all supported menu variants and item types.
+
+## Key Components
+
+**Stories exported:**
+
+| Story | Description |
+|---|---|
+| `Default` | Single-group menu with icon items |
+| `GroupedWithDanger` | Multi-group menu with separator and destructive delete row |
+| `WithCheckboxes` | Checkbox-type items with checked/unchecked states |
+| `WithSubmenu` | Nested submenu via `ActionsMenuDropdown` (requires Radix DropdownMenu context) |
+| `WithDisabledItem` | Dimmed, non-interactive disabled row |
+| `WithSecondaryAction` | Row with an independently clickable secondary icon button (e.g. open in new tab) |
+| `Dropdown` | `ActionsMenuDropdown` with an ellipsis trigger button |
+
+**Key props documented:**
+
+- `groups` — Array of `ActionsMenuGroup` objects, each containing an array of items
+- `className` — Additional CSS classes for the menu panel
+- `onItemClick` — Callback fired when any item is activated
+
+## Usage Example
+
+```typescript
+import { ActionsMenu, ActionsMenuDropdown } from '../components/ui/actions-menu';
+
+// Inline panel
+<ActionsMenu
+  groups={[
+    {
+      id: 'primary',
+      separator: true,
+      items: [
+        { id: 'edit', label: 'Edit', icon: <PencilIcon />, onClick: handleEdit },
+        { id: 'download', label: 'Download', icon: <Download01Icon />, onClick: handleDownload },
+      ],
+    },
+    {
+      id: 'destructive',
+      items: [
+        { id: 'delete', label: 'Delete', icon: <TrashBlankIcon />, danger: true, onClick: handleDelete },
+      ],
+    },
+  ]}
+/>
+
+// Trigger-attached dropdown
+<ActionsMenuDropdown groups={dropdownGroups} onItemClick={handleItemClick} />
+```
+
+> **Note:** Submenu items (`type: 'submenu'`) require `ActionsMenuDropdown` — the inline `ActionsMenu` panel has no Radix DropdownMenu context.
+
+## Source
+
+[`ActionsMenu.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ActionsMenu.stories.tsx)

package/src/stories/.Alert.stories.md

@@ -0,0 +1,46 @@
+<!-- source-hash: dc7266b2b4457b06de407dc273e1e31e -->
+Storybook stories for the `Alert` UI component, showcasing all available variants and a real-world usage example.
+
+## Key Components
+
+| Export | Variant | Description |
+|---|---|---|
+| `Default` | `default` | Neutral informational alert |
+| `Destructive` | `destructive` | Error state alert (e.g. session expired) |
+| `Warning` | `warning` | Caution state alert |
+| `EmailVerification` | `warning` | Real-world example mirroring the Settings page email-verification banner |
+| `AllVariants` | — | Renders all three variants stacked for visual comparison |
+
+## Usage Example
+
+```typescript
+import { Alert, AlertDescription, AlertTitle } from '../components/ui/alert';
+
+// Basic usage
+<Alert variant="default">
+  <AlertTitle>Heads up!</AlertTitle>
+  <AlertDescription>You can add components to your app using the CLI.</AlertDescription>
+</Alert>
+
+// With icon and custom layout (email verification banner pattern)
+import { AlertTriangleIcon } from '../components/icons-v2-generated/interface/alert-triangle-icon';
+
+<Alert
+  variant="warning"
+  className="flex items-center justify-center gap-[var(--spacing-system-m)] p-[var(--spacing-system-s)]"
+>
+  <span className="shrink-0">
+    <AlertTriangleIcon size={24} />
+  </span>
+  <p className="flex-1 text-h4 font-bold">Verify your email to keep access to system.</p>
+  <button type="button" className="shrink-0 text-h4 font-medium underline whitespace-nowrap">
+    Resend Verification Mail
+  </button>
+</Alert>
+```
+
+## Notes
+
+- The `variant` prop accepts `'default'`, `'destructive'`, or `'warning'` and is controlled via a Storybook `select` control.
+- `EmailVerification` is pinned to the `warning` variant and demonstrates composing `Alert` with an icon, bold message text, and an inline action button — matching the Figma design for the Settings page banner.
+- Source: [`Alert.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/Alert.stories.tsx)

package/src/stories/.AnnouncementBar.stories.md

@@ -1,45 +1,72 @@
-<!-- source-hash: cf04b71bf17cf6b35fdcdc036bdc8b09 -->
-Storybook stories for the `AnnouncementBar` component, providing isolated visual variants with mocked API responses and localStorage state to simulate the full announcement lifecycle without a real backend.
+<!-- source-hash: 73d3a98384e609c3fd1b1b5c733bdc5f -->
+Storybook stories for the `AnnouncementBar` component, covering SSR-seeded, client-fetched, and admin preview rendering paths across multiple visual configurations.
 
 ## Key Components
 
 | Export | Description |
-|--------|-------------|
-| `mockAnnouncement()` | Helper that intercepts `window.fetch` to return mock announcement data and clears dismiss flags from `localStorage` |
-| `Default` | Basic announcement with icon and description using the Flamingo yellow (`#FFD951`) background |
-| `WithCTA` | Announcement with a fully configured call-to-action button opening in a new tab |
-| `WithCTASameTab` | CTA variant targeting `_self` for same-tab navigation |
+|---|---|
+| `Default` | Basic announcement with icon and description |
+| `WithCTA` | Announcement with a styled call-to-action button (new tab) |
+| `WithoutCloseButton` | Non-dismissible bar (`dismissible={false}`) |
+| `WithCTASameTab` | CTA that navigates within the same tab |
+| `DarkBackground` | Validates contrast-aware text color via `pickReadableTextColor` |
 | `BlueBackground` / `GreenBackground` | Color theme variants |
-| `WithOpenFrameLogo` | Uses the `openframe-logo` SVG icon with a branded CTA |
-| `WithPNGIcon` | Tests PNG icon rendering via `icon_png_url` |
-| `LongContent` | Stress-tests truncation behavior on long titles and descriptions |
-| `NoAnnouncement` | Renders with `null` announcement to verify the bar hides itself |
+| `WithOpenFrameLogo` | Uses the `openframe-logo` named icon |
+| `WithPNGIcon` | Icon sourced from an external `icon_url` |
+| `LongContent` | Truncation behavior under long titles and descriptions |
+| `PreviewMode` | Admin live-preview — renders bar inert; no storage/fetch side effects |
+| `NoAnnouncement` | Null announcement; bar renders nothing |
+| `ClientOnlyEmbed` | Mounts an `EndpointsRuntimeContext` provider and mocks `window.fetch` to simulate client-only embedding without SSR |
 
 ## Usage Example
 
 ```typescript
-// How the fetch mock works in each story decorator
-const cleanup = mockAnnouncement({
-  id: 'story-1',
-  title: 'New Feature Released',
-  description: 'Check out our latest updates.',
-  background_color: '#FFD951',
-  icon_type: 'svg',
-  icon_svg_name: 'rocket',
-  platform_id: 'openframe',
-  is_active: true,
-  created_at: new Date().toISOString(),
-  updated_at: new Date().toISOString(),
-})
-
-// The mock intercepts /api/announcements/active
-// and returns the provided announcement object.
-// Pass null to simulate no active announcement.
-mockAnnouncement(null)
+// Replicate the SSR-seeded path used by most stories
+import { AnnouncementBar } from '../components/announcement-bar'
+
+export const WithCTA: Story = {
+  args: {
+    initialAnnouncement: {
+      id: 'example-1',
+      title: 'OpenFrame v2.0 is here!',
+      description: 'Explore the new dashboard.',
+      background_color: '#FFD951',
+      icon_name: 'star',
+      is_active: true,
+      cta_enabled: true,
+      cta_text: 'Learn More',
+      cta_url: 'https://example.com',
+      cta_target: '_blank',
+    },
+  },
+}
+
+// Replicate the client-only embed path (mocks fetch, no SSR prop)
+export const ClientOnlyEmbed: Story = {
+  args: {},
+  decorators: [
+    (Story) => {
+      window.fetch = async (input) => {
+        if (input.toString().includes('/api/announcements/active')) {
+          return new Response(JSON.stringify({ announcement: { ...} }), {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+          })
+        }
+        return originalFetch(input)
+      }
+      return (
+        <EndpointsRuntimeContext.Provider value={embedEndpoints}>
+          <Story />
+        </EndpointsRuntimeContext.Provider>
+      )
+    },
+  ],
+}
 ```
 
 ## Notes
 
-- All stories use the `fullscreen` layout to replicate the top-of-page bar context
-- The `mockAnnouncement` helper automatically restores `window.fetch` and removes `localStorage` dismiss keys to prevent state leaking between story renders
-- `autodocs` is enabled, generating a component API table from the `Announcement` type
+- Every story's decorator calls `clearAnnouncementDismissals(getAppType())` before rendering, ensuring each story starts with the bar visible regardless of prior interactions.
+- Without an `EndpointsRuntimeContext` provider mounted, the bar never issues a fetch — stories remain self-contained and require no network mocking unless explicitly testing the embed path (`ClientOnlyEmbed`).
+- Source: [`AnnouncementBar.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/AnnouncementBar.stories.tsx)

package/src/stories/.AppLayoutDrawer.stories.md

@@ -0,0 +1,60 @@
+<!-- source-hash: eb65307855df2f5b364327378b10b165 -->
+Storybook stories for the `AppLayoutDrawer` component, demonstrating an in-layout drawer panel that renders within `AppLayout`'s main content area without covering the global chrome (header and sidebar).
+
+## Key Components
+
+| Export | Description |
+|---|---|
+| `Right` | Default right-side drawer, persistent (does not close on chrome clicks) |
+| `ResizableRight` | Right-side drawer with drag-to-resize handle, clamped to the main content area |
+| `Left` | Left-side drawer variant, suitable for filters or secondary navigation |
+| `DashboardChildren` | Internal helper rendering a mock dashboard with a button to trigger the drawer |
+
+## Usage Example
+
+```typescript
+import {
+  AppLayout,
+  AppLayoutDrawer,
+  AppLayoutDrawerBody,
+  AppLayoutDrawerContent,
+  AppLayoutDrawerHeader,
+  AppLayoutDrawerTitle,
+} from '../components/navigation'
+
+function Page() {
+  const [open, setOpen] = useState(false)
+
+  return (
+    <AppLayout
+      sidebarConfig={{ items: navigationItems, onNavigate: handleNav, onToggleMinimized: handleToggle }}
+      drawer={
+        <AppLayoutDrawer open={open} onOpenChange={setOpen}>
+          <AppLayoutDrawerContent
+            side="right"
+            resizable
+            minSize={360}
+            defaultSize={560}
+            storageKey="my-app:drawer:right"
+          >
+            <AppLayoutDrawerHeader>
+              <AppLayoutDrawerTitle>Panel Title</AppLayoutDrawerTitle>
+            </AppLayoutDrawerHeader>
+            <AppLayoutDrawerBody>
+              <p>Panel content here.</p>
+            </AppLayoutDrawerBody>
+          </AppLayoutDrawerContent>
+        </AppLayoutDrawer>
+      }
+    >
+      <button onClick={() => setOpen(true)}>Open Panel</button>
+    </AppLayout>
+  )
+}
+```
+
+> **When to use `AppLayoutDrawer` vs `Drawer`:** Use `AppLayoutDrawer` for page-level panels (chat, details, filters) that should coexist with the app chrome. Use the standard `Drawer` from `components/ui` for viewport-covering overlays such as notifications or auth modals.
+
+## Source
+
+[`AppLayoutDrawer.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/AppLayoutDrawer.stories.tsx)

package/src/stories/.AppLayoutSidebar.stories.md

@@ -0,0 +1,45 @@
+<!-- source-hash: 99e6880161138f9d238720bc80b322d2 -->
+Storybook stories for the `AppLayoutSidebar` component, demonstrating how `AppLayout` integrates with `AppLayoutDrawer` to render a toggleable right-side AI chat panel within the main content area.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `Default` | `Story` | Toggle-driven sidebar that opens/closes via the Mingo AI header button |
+| `Resizable` | `Story` | Starts open with a draggable resize handle; persists width via `storageKey` |
+| `DashboardChildren` | Internal component | Mock dashboard UI used as page content behind the drawer |
+| `navigationItems` | `NavigationSidebarConfig['items']` | Sample nav config with Dashboard, Customers, Devices, Scripts, and Settings |
+
+## Usage Example
+
+```typescript
+// Minimal AppLayout with a toggleable Mingo AI drawer
+const [open, setOpen] = useState(false)
+
+<AppLayout
+  sidebarConfig={{ items: navigationItems, onNavigate: fn(), onToggleMinimized: fn() }}
+  headerProps={{
+    showMingoAI: true,
+    onMingoAI: () => setOpen((prev) => !prev),
+    isMingoAIActive: open,
+  }}
+  drawer={
+    <AppLayoutDrawer open={open} onOpenChange={setOpen}>
+      <AppLayoutDrawerContent side="right">
+        <AppLayoutDrawerHeader>
+          <AppLayoutDrawerTitle>Mingo AI</AppLayoutDrawerTitle>
+        </AppLayoutDrawerHeader>
+        <AppLayoutDrawerBody>
+          <p>Chat content goes here.</p>
+        </AppLayoutDrawerBody>
+      </AppLayoutDrawerContent>
+    </AppLayoutDrawer>
+  }
+>
+  <PageContent />
+</AppLayout>
+```
+
+For a resizable drawer, add `resizable`, `minSize`, `defaultSize`, and `storageKey` to `AppLayoutDrawerContent`. The navigation sidebar and header remain fully interactive while the drawer is open; close via the X button or Escape key.
+
+**Source:** [`AppLayoutSidebar.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/AppLayoutSidebar.stories.tsx)

package/src/stories/.ApprovalBatchMessage.stories.md

@@ -0,0 +1,46 @@
+<!-- source-hash: 42e35c13ea5f57f4bad0c0ee1df57d09 -->
+Storybook stories for the `ApprovalBatchMessage` chat component, covering all approval lifecycle states (pending, executing, done, rejected, cancelled) for the "Command Block" UI pattern from Figma node 1092-2807.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `Pending` | `Story` | Shows Approve/Reject buttons; row is expandable to reveal call arguments |
+| `ApprovedExecuting` | `Story` | Approved state with a grey loader while the tool call runs |
+| `ApprovedDone` | `Story` | Approved and finished; green check with an expandable Result block |
+| `Rejected` | `Story` | Red status tag, no execution initiated |
+| `Cancelled` | `Story` | Grey status tag, no execution initiated |
+| `AllStates` | `Story` | All five states rendered vertically for side-by-side Figma comparison |
+
+**Helpers:**
+
+- `toolCall` — a `PendingToolCallData` fixture for a `run_script` RMM tool requiring admin approval
+- `makeData()` — factory producing `ApprovalBatchData` with optional per-call `ApprovalBatchExecutionState` overrides
+- `constrainedDecorator()` — wraps stories in a `max-width` container (default 400 px) to match chat panel dimensions
+
+## Usage Example
+
+```typescript
+import { ApprovalBatchMessage } from "../components/chat/approval-batch-message";
+
+// Pending approval
+<ApprovalBatchMessage
+  data={{
+    approvalRequestId: "batch-1",
+    approvalType: "ADMIN",
+    toolCalls: [toolCall],
+  }}
+  status="pending"
+  onApprove={() => handleApprove()}
+  onReject={() => handleReject()}
+/>
+
+// Approved and finished
+<ApprovalBatchMessage
+  data={doneData}
+  status="approved"
+  resolvedByName="Michael Johnson"
+/>
+```
+
+**Source:** [`ApprovalBatchMessage.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ApprovalBatchMessage.stories.tsx)

package/src/stories/.ApprovalBatchMessageClient.stories.md

@@ -0,0 +1,55 @@
+<!-- source-hash: 97d757bd7f6ce826c293b7cabfdf5f49 -->
+Storybook stories for the **client-facing (Fae end-user)** variant of `ApprovalBatchMessage`, demonstrating all approval states a client can encounter.
+
+## Key Components
+
+| Export | Description |
+|---|---|
+| `Pending` | Title + Approve/Reject buttons; no command details exposed |
+| `Approved` | Full-text green status pill with resolver name |
+| `Rejected` | Full-text red status pill with resolver name |
+| `Cancelled` | Full-text grey status pill with resolver name |
+| `AllStates` | Composite story rendering all four states stacked vertically |
+
+## Usage Example
+
+```typescript
+import { ApprovalBatchMessage } from "../components/chat/approval-batch-message";
+
+// Pending state — client sees only the BE-generated title + action buttons
+<ApprovalBatchMessage
+  variant="client"
+  data={{
+    approvalRequestId: "batch-1",
+    approvalType: "CLIENT",
+    toolCalls: [{
+      toolExecutionRequestId: "req-1",
+      toolName: "run_script",
+      toolTitle: "Run Script",
+      toolExplanation: "Exports today's event logs to CSV.",
+      toolType: "OPENFRAME_RMM",
+      requiresApproval: true,
+      approvalType: "CLIENT",
+      toolCallArguments: { command: "...", timeoutSeconds: 60 },
+    }],
+  }}
+  status="pending"
+  onApprove={() => {}}
+  onReject={() => {}}
+/>
+
+// Resolved state — client sees a status pill only
+<ApprovalBatchMessage
+  variant="client"
+  data={data}
+  status="approved"
+  resolvedByName="Michael Johnson"
+/>
+```
+
+## Notes
+
+- Gated by `variant="client"` — commands, scripts, expandable args/results, and execution icons are **never rendered** in this variant.
+- The client sees only the BE-generated `toolExplanation` field as the card title.
+- Mirrors Figma node `203-11947` ("fae-approval-block") and frames `1-6575`, `1-6621`, `1-6637`, `1-6653`.
+- Source: [`ApprovalBatchMessageClient.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ApprovalBatchMessageClient.stories.tsx)

package/src/stories/.ApprovalRequestMessage.stories.md

@@ -0,0 +1,50 @@
+<!-- source-hash: 2177d7e46f18605feaab85e2a98af352 -->
+Storybook stories for the `ApprovalRequestMessage` component, covering all approval states (pending, approved, rejected, cancelled) and content variants (structured fields vs. explanation prose).
+
+## Key Components
+
+| Export | Description |
+|---|---|
+| `Pending` | Default state with Approve/Reject action buttons visible |
+| `Approved` | Resolved state showing a green status tag |
+| `Rejected` | Resolved state showing a red status tag |
+| `Cancelled` | Resolved state showing a grey status tag |
+| `WithExplanation` | Pending state using free-text explanation instead of structured fields |
+| `constrainedDecorator` | Local helper that wraps each story in a `400px`-wide container to simulate chat bubble constraints |
+
+## Usage Example
+
+```typescript
+import { ApprovalRequestMessage } from "../components/chat/approval-request-message";
+import type { ApprovalRequestData } from "../components/chat/types";
+
+const data: ApprovalRequestData = {
+  command: `Get-CimInstance Win32_Process | Select-Object ProcessId, Name`,
+  requestId: "req-1",
+  approvalType: "ADMIN",
+  fields: [
+    { label: "Tool", value: "OpenFrame RMM" },
+    { label: "RunAsUser", value: "False" },
+    { label: "timeoutSeconds", value: "60" },
+  ],
+};
+
+// Pending — shows Approve / Reject buttons
+<ApprovalRequestMessage
+  data={data}
+  status="pending"
+  onApprove={() => handleApprove()}
+  onReject={() => handleReject()}
+/>
+
+// Resolved — buttons replaced by a status tag
+<ApprovalRequestMessage data={data} status="approved" />
+```
+
+## Notes
+
+- This is the **legacy single-command variant**. For new surfaces, prefer `ApprovalBatchMessage`, which additionally tracks per-tool execution results.
+- The `fields` array and `explanation` string are mutually exclusive — use one or the other to provide context below the command bar.
+- Stories are registered under `Chat/Admin/ApprovalRequestMessage` in the Storybook sidebar.
+
+**Source:** [`ApprovalRequestMessage.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ApprovalRequestMessage.stories.tsx)

package/src/stories/.ApprovalRequestMessageClient.stories.md

@@ -0,0 +1,41 @@
+<!-- source-hash: 3206ceb65aad5349f453e11274a069c1 -->
+Storybook stories for the **client-facing (Fae end-user) variant** of the `ApprovalRequestMessage` component, covering all approval lifecycle states as seen by the end client — where only the BE-generated explanation title is shown, never the raw command.
+
+## Key Components
+
+- **`meta`** — Storybook metadata configuring the story group under `Chat/Client/ApprovalRequestMessage`, with `variant="client"` applied globally via `args`
+- **`baseData`** — Shared `ApprovalRequestData` fixture (`approvalType: "CLIENT"`, `command`, `explanation`, `requestId`) used across all stories
+- **`plainDecorator`** — Wrapper utility that constrains story width and applies the CSS background token
+
+## Exported Stories
+
+| Story | Status | Description |
+|---|---|---|
+| `Pending` | `pending` | Title + Approve/Reject buttons; no command block rendered |
+| `ApprovedByUser` | `approved` | Green `APPROVED BY JOHN SMITH` pill |
+| `Approved` | `approved` | Plain `APPROVED` pill (no resolver name) |
+| `RejectedByUser` | `rejected` | Red `REJECTED BY JOHN SMITH` pill |
+| `Cancelled` | `cancelled` | Grey status pill |
+| `NoTitleFallback` | `pending` | `explanation: undefined` triggers `"Approval required"` placeholder |
+
+## Usage Example
+
+```typescript
+// Render the client approval card in pending state
+import { ApprovalRequestMessage } from "../components/chat/approval-request-message";
+
+<ApprovalRequestMessage
+  variant="client"
+  data={{
+    command: "brew install --cask slack",
+    requestId: "req-client-1",
+    approvalType: "CLIENT",
+    explanation: "Install Slack via Homebrew Cask on macOS",
+  }}
+  status="pending"
+  onApprove={() => handleApprove()}
+  onReject={() => handleReject()}
+/>
+```
+
+> **Note:** With `variant="client"`, the raw `command` string is never rendered — only the `explanation` title is visible to the end user, per Figma node 203-11947 (`fae-approval-block`).

package/src/stories/.BlogCard.stories.md

@@ -0,0 +1,52 @@
+<!-- source-hash: f25255e37142438b85c6b2df6de4a52f -->
+Storybook story file for the `BlogCard` entity card component, providing interactive visual stories for both compact chat-inline and full vertical catalog display densities.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `meta` | `Meta<typeof BlogCard>` | Storybook configuration for `Chat/EntityCards/BlogCard` |
+| `ChatInlineSm` | `Story` | Compact horizontal card (`size="sm"`, ~80px tall) for chat-inline rendering |
+| `ChatInlineWithVideoBadge` | `Story` | Compact card variant with `hasEmbeddedVideo` badge overlay |
+| `Default` | `Story` | Full vertical catalog card (`size="default"`) for related-content rail use |
+
+## Usage Example
+
+```typescript
+import { BlogCard } from '../components/chat/entity-cards'
+
+// Chat-inline compact form (dispatched by chat with size="sm")
+<BlogCard
+  post={blogPostSummary}
+  href={`/blog/${blogPostSummary.slug}`}
+  size="sm"
+  target="_blank"
+  rel="noopener noreferrer"
+/>
+
+// Full vertical catalog card (e.g. related-content rail)
+<BlogCard
+  post={blogPostSummary}
+  href={`/blog/${blogPostSummary.slug}`}
+  size="default"
+  target="_blank"
+  rel="noopener noreferrer"
+/>
+
+// With embedded video badge
+<BlogCard
+  post={blogPostSummary}
+  href={`/blog/${blogPostSummary.slug}`}
+  size="sm"
+  hasEmbeddedVideo
+/>
+```
+
+## Notes
+
+- All stories are wrapped in `ChatColumnDecorator` to simulate the chat column layout context.
+- `href` should be resolved by the caller via `buildContentURL` or `useNavLink`; the card renders its own `<a>` internally.
+- `size="sm"` is the standard chat dispatch variant; `size="default"` is reserved for catalog/rail contexts.
+- Fixture data (`blogPostSummary`) is sourced from `./__fixtures__/chat-cards`.
+
+**Source:** [`BlogCard.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/BlogCard.stories.tsx)