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

package/src/stories/.TicketKnowledgeBaseList.stories.md

@@ -0,0 +1,36 @@
+<!-- source-hash: 2eebf27815f5533ea1acd099d63702ec -->
+Storybook stories for the `TicketKnowledgeBaseList` component, providing interactive UI development and documentation for a clickable knowledge base article list used in the ticket workflow.
+
+## Key Components
+
+- **`Default`** — Four populated articles showcasing typical MSP knowledge base content (setup guides, migration docs, training programs, checklists)
+- **`SingleArticle`** — Minimal single-item variant for edge case testing
+- **`Empty`** — Zero-state render when no articles are available
+
+## Usage Example
+
+```typescript
+import { TicketKnowledgeBaseList } from '../components/ui/ticket-knowledge-base-list';
+
+<TicketKnowledgeBaseList
+  articles={[
+    {
+      id: '1',
+      title: 'OpenFrame Initial Setup Guide',
+      description: 'Complete platform configuration including SSO integration.',
+      onClick: () => router.push(`/knowledge/${id}`),
+    },
+  ]}
+/>
+```
+
+## Story Configuration
+
+| Parameter | Value |
+|-----------|-------|
+| Storybook path | `Tickets/TicketKnowledgeBaseList` |
+| Layout | `padded` |
+| Viewport width | `600px` (decorator-constrained) |
+| Auto-docs | Enabled via `autodocs` tag |
+
+Each article item expects `id`, `title`, `description`, and an optional `onClick` handler — the component renders a chevron navigation indicator per item.

package/src/stories/.TicketNotesSection.stories.md

@@ -0,0 +1,50 @@
+<!-- source-hash: 60dbe61d194b4cd2145ee7d06610135a -->
+Storybook stories for the `TicketNotesSection` component, providing visual development and testing scenarios for the ticket notes UI including note cards with author info, edit/delete actions, and note input.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `Default` | Story | Renders a populated notes section with 3 mock notes (mix of own and others) |
+| `Interactive` | Story | Fully stateful story with live add/delete note functionality |
+| `ReadOnly` | Story | Notes list without `onAddNote` handler — hides the input field |
+| `Empty` | Story | Zero-note state with add input available |
+| `mockNotes` | `TicketNote[]` | Reusable fixture with 3 notes across 2 authors |
+
+## Usage Example
+
+```typescript
+// Interactive story demonstrates real state management pattern
+export const Interactive: Story = {
+  render: function InteractiveNotes() {
+    const [notes, setNotes] = useState<TicketNote[]>(mockNotes);
+
+    return (
+      <TicketNotesSection
+        notes={notes}
+        onAddNote={(text) => {
+          setNotes(prev => [...prev, {
+            id: String(Date.now()),
+            text,
+            authorName: 'You',
+            createdAt: new Date().toLocaleString(),
+            isOwn: true,
+          }]);
+        }}
+        onDeleteNote={(id) => setNotes(prev => prev.filter(n => n.id !== id))}
+      />
+    );
+  },
+};
+```
+
+## Story Coverage
+
+| Scenario | `notes` | `onAddNote` | `onEditNote` / `onDeleteNote` |
+|----------|---------|-------------|-------------------------------|
+| `Default` | 3 mock notes | ✅ | ✅ |
+| `Interactive` | Stateful | ✅ live | ✅ live delete |
+| `ReadOnly` | 3 mock notes | ❌ hidden | ❌ |
+| `Empty` | `[]` | ✅ | ❌ |
+
+> Stories are rendered at `600px` width via a decorator, matching a typical ticket sidebar layout.

package/src/stories/.Toaster.stories.md

@@ -0,0 +1,40 @@
+<!-- source-hash: 8385ab6a043167836b17b6b41deb0581 -->
+Storybook stories for the `Toaster` / `ToastCard` component system, covering static previews, interactive playground, command-approval flows, and live Sonner-powered triggers.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `AllVariants` | Story | Static grid of every `ToastVariant` (`default`, `success`, `warning`, `error`, `info`) plus edge cases (title-only, description-only, non-dismissible, persistent) |
+| `Playground` | Story | Arg-driven interactive card — use Storybook Controls to tweak `variant`, `title`, `description`, `duration`, and `dismissible` |
+| `CommandApprovalCollapsed` | Story | `CommandApprovalToast` in its default collapsed state |
+| `CommandApprovalExpanded` | Story | `CommandApprovalToast` with `defaultExpanded` showing the command preview and Approve/Reject actions |
+| `CommandApprovalPerTool` | Story | One expanded approval toast per supported tool type (`FLEET_MDM`, `TACTICAL_RMM`, `MESHCENTRAL`, `AUTHENTIK`, `OSQUERY`, `OPENFRAME`) to verify icon mapping |
+| `CommandApprovalLive` | Story | Fires real Sonner toasts via `showCommandApprovalToast()` with `onApprove`/`onReject` callbacks |
+| `LiveTriggers` | Story | Button panel that fires every variant as a live Sonner toast using both `toast()` and `showToast()` |
+
+## Usage Example
+
+```typescript
+// Render once near your app root
+import { Toaster } from '@/components/ui/toaster';
+<Toaster />
+
+// Fire a standard toast from anywhere
+import { toast } from '@/hooks/use-toast';
+toast({ variant: 'success', title: 'Saved', description: 'All changes committed.' });
+
+// Fire a command-approval toast requiring tech sign-off
+import { showCommandApprovalToast } from '@/components/ui/toaster';
+showCommandApprovalToast({
+  title: 'Tech Required',
+  description: 'Approval is required to execute the command.',
+  command: 'fleetctl query --hosts mac-* "SELECT * FROM system_info"',
+  toolType: ToolTypeValues.FLEET_MDM,
+  approvalDescription: 'Queries system info across all macOS endpoints.',
+  onApprove: () => toast({ variant: 'success', title: 'Command approved' }),
+  onReject:  () => toast({ variant: 'error',   title: 'Command rejected' }),
+});
+```
+
+> **Note:** `<Toaster />` must be mounted in the render tree for live stories (`CommandApprovalLive`, `LiveTriggers`) — both stories include it inline so the Storybook canvas is self-contained.

package/src/stories/.ToolExecutionDisplay.stories.md

@@ -0,0 +1,41 @@
+<!-- source-hash: 5d594bd4947331ddd5432015be5899f2 -->
+Storybook stories for the `ToolExecutionDisplay` chat component, covering executing, success, and failure states in a constrained-width layout.
+
+## Key Components
+
+| Export | Description |
+|--------|-------------|
+| `CollapsedExecuting` | Spinner state while a tool (e.g. `run_script` via Tactical RMM) is in progress |
+| `CollapsedSuccess` | Green check state after successful tool execution, with result output |
+| `CollapsedFailure` | Red error icon state after a failed tool execution (e.g. Fleet MDM profile deploy) |
+| `constrainedDecorator` | Helper decorator that wraps stories in a `max-width` container (default 400px) |
+
+## Usage Example
+
+```typescript
+import { ToolExecutionDisplay } from "../components/chat/tool-execution-display";
+import type { ToolExecutionData } from "../components/chat/types";
+
+const message: ToolExecutionData = {
+  type: "EXECUTED_TOOL",
+  integratedToolType: "TACTICAL_RMM",
+  toolFunction: "run_script",
+  parameters: { RunAsUser: "False", timeoutSeconds: 60 },
+  result: "Script output here...",
+  success: true,
+};
+
+<ToolExecutionDisplay message={message} />
+```
+
+## Story Data
+
+Three fixture payloads cover the core display states:
+
+| Fixture | `type` | `integratedToolType` | `success` |
+|---------|--------|----------------------|-----------|
+| `executingMessage` | `EXECUTING_TOOL` | `TACTICAL_RMM` | — |
+| `executedSuccessMessage` | `EXECUTED_TOOL` | `TACTICAL_RMM` | `true` |
+| `executedFailureMessage` | `EXECUTED_TOOL` | `FLEET_MDM` | `false` |
+
+The component renders a collapsed card by default; clicking toggles full details including parameters and result output.

package/src/stories/.Tooltip.stories.md

@@ -0,0 +1,41 @@
+<!-- source-hash: cde6b3206d9d2b1da2994e1fb8b1fb77 -->
+Storybook stories for the `Tooltip` UI component, demonstrating usage patterns, placement options, and interactive states.
+
+## Key Components
+
+| Story | Description |
+|---|---|
+| `Default` | Basic tooltip on a settings icon button |
+| `InfoHelper` | Info icon with explanatory tooltip for forms/dashboards |
+| `Placement` | All four tooltip positions: `top`, `bottom`, `left`, `right` |
+| `IconToolbar` | Action bar with tooltips on Copy, Download, Share, and Delete icons |
+| `DisabledButton` | Tooltip on a disabled button via wrapper `<span>` to preserve hover events |
+| `TruncatedText` | Reveals full text on hover when content is visually clipped |
+| `RichContent` | Multi-line tooltip with icon, heading, and keyboard shortcut badge |
+| `CopyButton` | Interactive copy button that toggles tooltip text and icon on click |
+
+## Usage Example
+
+```typescript
+// Basic tooltip
+<TooltipProvider delayDuration={200}>
+  <Tooltip>
+    <TooltipTrigger asChild>
+      <button>Hover me</button>
+    </TooltipTrigger>
+    <TooltipContent side="top">Tooltip text</TooltipContent>
+  </Tooltip>
+</TooltipProvider>
+
+// Tooltip on a disabled button — wrap in span to capture hover
+<Tooltip>
+  <TooltipTrigger asChild>
+    <span tabIndex={0} className="inline-block">
+      <Button disabled>Deploy</Button>
+    </span>
+  </TooltipTrigger>
+  <TooltipContent>You need admin permissions to deploy.</TooltipContent>
+</Tooltip>
+```
+
+> `TooltipProvider` must wrap all `Tooltip` instances. Use `delayDuration` to control hover delay in milliseconds.

package/src/stories/.UserSummary.stories.md

@@ -0,0 +1,41 @@
+<!-- source-hash: 0eb9d42ebd2c94e50a4a59a1b4f5779d -->
+Storybook stories for the `UserSummary` component, covering all display variants from minimal to fully-featured configurations.
+
+## Key Components
+
+- **`makeAvatar`** — Helper that generates inline SVG avatar data URIs with initials and a background color, used to produce deterministic test fixtures without external image dependencies.
+- **`meta`** — Storybook metadata block configuring controls for `compact`, `avatarSize`, `showEditButton`, and `editablePhoto`.
+- **Story exports** — 14 named stories grouped by feature area:
+
+| Group | Stories |
+|---|---|
+| Default (Full) | `Default`, `NoAvatar`, `WithSubtitle` |
+| Auth Providers | `WithAuthProviders` |
+| MSP Preview | `WithMSP`, `WithMSPNoLogo` |
+| Edit Button | `WithEditButton` |
+| Full Featured | `FullFeatured` |
+| Compact Variant | `Compact`, `CompactNoAvatar`, `CompactWithSubtitle`, `CompactWithMSP`, `CompactLargeAvatar` |
+
+## Usage Example
+
+```typescript
+// Reuse the avatar helper in other story files
+const avatar = makeAvatar('AB', '#14b8a6')
+
+export const MyStory: Story = {
+  args: {
+    name: 'Alice Brown',
+    email: 'alice@example.com',
+    avatarUrl: avatar,
+    compact: true,
+    mspPreview: {
+      name: 'Acme MSP',
+      seatCount: 300,
+      technicianCount: 8,
+      annualRevenue: 750_000,
+    },
+  },
+}
+```
+
+The `FullFeatured` story serves as the canonical reference combining avatar, MSP badge, auth provider icons, and the edit button in a single configuration.

package/src/stories/.WaitlistForm.stories.md

@@ -0,0 +1,42 @@
+<!-- source-hash: ceae4576eb21b2903f71a060a6972f7f -->
+Storybook stories for the `WaitlistForm` component, covering default states, edge cases, theming, and interaction scenarios for visual and functional testing.
+
+## Key Components
+
+| Export | Description |
+|---|---|
+| `Default` | Base form with no pre-filled values |
+| `WithDefaultEmail` | Form pre-filled with a business email |
+| `GenericEmailWarning` | Triggers the consumer-domain (e.g. `gmail.com`) warning hint |
+| `Submitting` | Button in loading/spinner state |
+| `Success` | Post-submission success label state |
+| `CustomLabels` | All configurable text props overridden |
+| `NarrowContainer` | 360px constrained layout for mobile testing |
+| `FailingRegistration` | `onRegister` throws to exercise toast error handling |
+| `FlamingoWithCheckboxError` | Flamingo-themed variant; auto-clicks submit to expose checkbox validation error |
+
+## Usage Example
+
+```typescript
+// Run a specific story in isolation
+import { FlamingoWithCheckboxError } from './WaitlistForm.stories';
+
+// Meta-level defaults shared across all stories
+// - layout: 'padded', dark background
+// - Toaster decorator for toast notifications
+// - 1.5s simulated async onRegister
+// - placeholder privacy/terms URLs
+
+// Override args per-story
+export const WithDefaultEmail: Story = {
+  args: {
+    defaultEmail: 'john@acme-msp.com',
+  },
+};
+```
+
+## Notes
+
+- All stories wrap `<Story />` with `<Toaster />` via a global decorator so toast notifications render correctly.
+- `FlamingoWithCheckboxError` uses `useRef` + `useEffect` to programmatically click the submit button on mount, simulating an immediate validation failure without manual interaction.
+- The `data-app-type="flamingo"` attribute on the wrapper activates the pink accent theme variant.

package/src/stories/BlogCard.stories.tsx

@@ -0,0 +1,61 @@
+import type { Meta, StoryObj } from '@storybook/nextjs-vite'
+import { BlogCard } from '../components/chat/entity-cards'
+import { ChatColumnDecorator } from './__fixtures__/chat-card-decorator'
+import { blogPostSummary } from './__fixtures__/chat-cards'
+
+const meta: Meta<typeof BlogCard> = {
+  title: 'Chat/EntityCards/BlogCard',
+  component: BlogCard,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Card for the `blog_post` doc type. Has two densities — `sm` is the compact horizontal chat-inline form (~80px tall), `default` is the full vertical catalog card. The card composes its own `<a>` from `href`; callers resolve the URL via `buildContentURL` or `useNavLink`.',
+      },
+    },
+  },
+  decorators: [(Story) => <ChatColumnDecorator><Story /></ChatColumnDecorator>],
+}
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const ChatInlineSm: Story = {
+  args: {
+    post: blogPostSummary,
+    href: '/blog/' + blogPostSummary.slug,
+    size: 'sm',
+    target: '_blank',
+    rel: 'noopener noreferrer',
+  },
+}
+
+export const ChatInlineWithVideoBadge: Story = {
+  args: {
+    post: blogPostSummary,
+    href: '/blog/' + blogPostSummary.slug,
+    size: 'sm',
+    target: '_blank',
+    rel: 'noopener noreferrer',
+    hasEmbeddedVideo: true,
+  },
+}
+
+export const Default: Story = {
+  args: {
+    post: blogPostSummary,
+    href: '/blog/' + blogPostSummary.slug,
+    size: 'default',
+    target: '_blank',
+    rel: 'noopener noreferrer',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Full vertical catalog card. Not used inline in chat (the chat dispatch always passes `size="sm"`), but the card supports it for the related-content rail.',
+      },
+    },
+  },
+}

package/src/stories/CampaignCardAdmin.stories.tsx

@@ -0,0 +1,52 @@
+import type { Meta, StoryObj } from '@storybook/nextjs-vite'
+import { CampaignCardAdmin } from '../components/chat/entity-cards'
+import {
+  ChatColumnDecorator,
+  makeAnchorProps,
+} from './__fixtures__/chat-card-decorator'
+import { campaignItem } from './__fixtures__/chat-cards'
+
+const meta: Meta<typeof CampaignCardAdmin> = {
+  title: 'Chat/EntityCards/CampaignCardAdmin',
+  component: CampaignCardAdmin,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Compact chat-inline card for the `marketing_campaign` doc type. Shows the campaign name, start date, goal count and a one-line description. The full admin card (with delete/manage buttons) lives in the hub; this is the chat-only projection.',
+      },
+    },
+  },
+  decorators: [(Story) => <ChatColumnDecorator><Story /></ChatColumnDecorator>],
+}
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: {
+    campaign: campaignItem,
+    anchorProps: makeAnchorProps('/admin/campaigns/' + campaignItem.id),
+  },
+}
+
+export const NoDescription: Story = {
+  args: {
+    campaign: {
+      ...campaignItem,
+      description: null,
+    },
+    anchorProps: makeAnchorProps('/admin/campaigns/' + campaignItem.id),
+  },
+}
+
+export const NoGoals: Story = {
+  args: {
+    campaign: {
+      ...campaignItem,
+      goals: [],
+    },
+    anchorProps: makeAnchorProps('/admin/campaigns/' + campaignItem.id),
+  },
+}

package/src/stories/CaseStudyCard.stories.tsx

@@ -0,0 +1,42 @@
+import type { Meta, StoryObj } from '@storybook/nextjs-vite'
+import { CaseStudyCard } from '../components/chat/entity-cards'
+import { ChatColumnDecorator } from './__fixtures__/chat-card-decorator'
+import { caseStudy } from './__fixtures__/chat-cards'
+
+const meta: Meta<typeof CaseStudyCard> = {
+  title: 'Chat/EntityCards/CaseStudyCard',
+  component: CaseStudyCard,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Card for the `case_study` doc type. `sm` size renders the chat-inline compact card; `default` is the catalog grid card. User + MSP badge overlay is shown in both sizes.',
+      },
+    },
+  },
+  decorators: [(Story) => <ChatColumnDecorator><Story /></ChatColumnDecorator>],
+}
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const ChatInlineSm: Story = {
+  args: {
+    study: caseStudy,
+    href: '/case-studies/' + caseStudy.slug,
+    size: 'sm',
+    target: '_blank',
+    rel: 'noopener noreferrer',
+  },
+}
+
+export const Default: Story = {
+  args: {
+    study: caseStudy,
+    href: '/case-studies/' + caseStudy.slug,
+    size: 'default',
+    target: '_blank',
+    rel: 'noopener noreferrer',
+  },
+}

package/src/stories/ChatContainer.stories.tsx

@@ -0,0 +1,186 @@
+import type { Meta, StoryObj } from '@storybook/nextjs-vite'
+import React, { useState } from 'react'
+
+import {
+  ChatContainer,
+  ChatContent,
+  ChatFooter,
+  ChatHeader,
+} from '../components/chat/chat-container'
+import { ChatInput } from '../components/chat/chat-input'
+import { ChatMessageList } from '../components/chat/chat-message-list'
+import type { Message } from '../components/chat/types/message.types'
+
+// =============================================================================
+// Mock messages — sample client-facing Fae conversation
+// =============================================================================
+
+const FAE_MESSAGES: Message[] = [
+  {
+    id: '1',
+    role: 'assistant',
+    name: 'Fae',
+    assistantType: 'fae',
+    content: "Hi! I'm Fae, your personal assistant. How can I help you today?",
+    timestamp: new Date('2026-05-28T10:00:00Z'),
+  },
+  {
+    id: '2',
+    role: 'user',
+    name: 'You',
+    content: "My printer stopped working this morning — can you open a ticket?",
+    timestamp: new Date('2026-05-28T10:00:30Z'),
+  },
+  {
+    id: '3',
+    role: 'assistant',
+    name: 'Fae',
+    assistantType: 'fae',
+    content:
+      "Of course — I'll get that opened right away. Could you tell me which printer it is (model or location) and what happens when you try to print?",
+    timestamp: new Date('2026-05-28T10:00:45Z'),
+  },
+  {
+    id: '4',
+    role: 'user',
+    name: 'You',
+    content: "It's the HP LaserJet by the front desk. It blinks orange and nothing prints.",
+    timestamp: new Date('2026-05-28T10:01:10Z'),
+  },
+]
+
+// =============================================================================
+// StoryShell — wires up controlled `ChatInput` and `ChatMessageList` so the
+// story is interactive: typing & sending pushes a new user bubble into the
+// message list. No transport — the assistant doesn't reply.
+// =============================================================================
+
+function FaeChatShell({
+  withTicketInfo = false,
+  bare = false,
+  fullWidth = false,
+}: {
+  withTicketInfo?: boolean
+  bare?: boolean
+  fullWidth?: boolean
+}) {
+  const [messages, setMessages] = useState<Message[]>(FAE_MESSAGES)
+
+  const handleSend = (text: string) => {
+    if (!text.trim()) return
+    setMessages((prev) => [
+      ...prev,
+      {
+        id: `local-${prev.length + 1}`,
+        role: 'user',
+        name: 'You',
+        content: text,
+        timestamp: new Date(),
+      },
+    ])
+  }
+
+  const handleNewChat = () => setMessages([FAE_MESSAGES[0]])
+
+  return (
+    <ChatContainer>
+      <ChatHeader
+        userName='Grace "Fae" Meadows'
+        userTitle="Your Personal Assistant"
+        connectionStatus="connected"
+        serverUrl="mcp.flamingo.run"
+        showNewChat
+        onNewChat={handleNewChat}
+        onClose={() => {
+          // eslint-disable-next-line no-console
+          console.log('[story] close clicked')
+        }}
+        fullWidth={fullWidth}
+        bare={bare}
+        ticketInfo={
+          withTicketInfo
+            ? {
+                title: 'Printer offline — Ticket #4821',
+                meta: 'Assigned to: J. Smith',
+                status: 'in-progress',
+              }
+            : undefined
+        }
+      />
+      <ChatContent>
+        <ChatMessageList
+          messages={messages}
+          assistantType="fae"
+          fullWidth={fullWidth}
+          className="flex-1"
+        />
+      </ChatContent>
+      <ChatFooter fullWidth={fullWidth}>
+        <ChatInput
+          onSend={handleSend}
+          placeholder="Message Fae..."
+          fullWidth={fullWidth}
+        />
+      </ChatFooter>
+    </ChatContainer>
+  )
+}
+
+// =============================================================================
+// Meta
+// =============================================================================
+
+const meta = {
+  title: 'Chat/ChatContainer',
+  component: ChatContainer,
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta<typeof ChatContainer>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+// =============================================================================
+// Fae — client-facing chat shell
+// =============================================================================
+
+/**
+ * The Fae client-app chat: the default `ChatContainer` + `ChatHeader` shell
+ * used by the OpenFrame customer-facing application. Header carries
+ * `Grace "Fae" Meadows` as the assistant persona (pink avatar via the
+ * default `bg-ods-flamingo-pink`); message list renders with
+ * `assistantType="fae"` so AI bubbles use the matching Fae styling.
+ */
+export const Fae: Story = {
+  render: () => <FaeChatShell />,
+}
+
+/**
+ * Same Fae shell with `ticketInfo` populated on the header — adds a
+ * secondary row beneath the avatar/name showing the active ticket title,
+ * meta and status tag. This is the in-conversation state once a support
+ * ticket has been opened from the chat.
+ */
+export const FaeWithTicket: Story = {
+  render: () => <FaeChatShell withTicketInfo />,
+}
+
+/**
+ * Full-width variant — drops the centered 600px content column on header,
+ * message list and footer. Use when embedding the Fae chat in a narrow
+ * side panel (e.g. mobile, slide-in drawer) where the centered column
+ * would float in the middle of the panel.
+ */
+export const FaeFullWidth: Story = {
+  render: () => <FaeChatShell fullWidth />,
+}
+
+/**
+ * Bare header — drops the card chrome (background, border, shadow, ring)
+ * so the header blends flush with its container. Pair with a host-
+ * supplied floating card / drawer that already provides the chrome.
+ */
+export const FaeBareHeader: Story = {
+  render: () => <FaeChatShell bare fullWidth />,
+}