@proteos/ui 0.42.1 → 0.42.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteos/ui",
-  "version": "0.42.1",
+  "version": "0.42.3",
   "license": "FSL-1.1-Apache-2.0",
   "description": "Proteos React component library (React Aria Components + Tailwind v4).",
   "repository": {
@@ -55,7 +55,7 @@
     "tailwind-merge": "^3.5.0",
     "tailwind-variants": "^3.2.2",
     "tailwindcss": "^4.2.4",
-    "@proteos/sdk": "0.42.1"
+    "@proteos/sdk": "0.42.3"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.13",
@@ -77,8 +77,8 @@
     "typescript": "^6.0.3",
     "vite": "^8.0.10",
     "vitest": "^3.2.4",
-    "@proteos/biome-config": "0.0.0",
-    "@proteos/tsconfig": "0.0.0"
+    "@proteos/tsconfig": "0.0.0",
+    "@proteos/biome-config": "0.0.0"
   },
   "scripts": {
     "lint": "biome check .",

package/src/components/channel-icon/channel-icon.stories.tsx

@@ -0,0 +1,44 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+
+import { ChannelIcon } from './channel-icon'
+
+const meta: Meta<typeof ChannelIcon> = {
+  title: 'Components/ChannelIcon',
+  component: ChannelIcon,
+  tags: ['autodocs'],
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj<typeof ChannelIcon>
+
+const CHANNELS = [
+  'email',
+  'slack',
+  'whatsapp',
+  'linkedin',
+  'telegram',
+  'instagram',
+  'messenger',
+  'x',
+  'meeting',
+  'zoom-meeting',
+  'google-meet',
+  'teams-meeting',
+  'webex-meeting',
+  'adhoc',
+  'carrier-pigeon',
+]
+
+/* ===== Every channel, plus the unknown-channel fallback at the end ===== */
+export const AllChannels: Story = {
+  render: () => (
+    <div className="flex flex-wrap gap-4">
+      {CHANNELS.map((channel) => (
+        <div key={channel} className="flex w-28 flex-col items-center gap-1.5 text-ink-3">
+          <ChannelIcon channel={channel} className="size-5 text-ink" />
+          <span className="font-mono text-[11px]">{channel}</span>
+        </div>
+      ))}
+    </div>
+  ),
+}

package/src/components/channel-icon/channel-icon.test.tsx

@@ -0,0 +1,26 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+
+import { ChannelIcon, channelIcon } from './channel-icon'
+
+describe('channelIcon', () => {
+  it('returns a distinct glyph per known channel', () => {
+    expect(channelIcon('email')).not.toBe(channelIcon('slack'))
+  })
+
+  it('falls back to the generic glyph for an unknown channel', () => {
+    expect(channelIcon('carrier-pigeon')).toBe(channelIcon('messenger'))
+  })
+})
+
+describe('ChannelIcon', () => {
+  it('is decorative by default', () => {
+    render(<ChannelIcon channel="email" />)
+    expect(screen.queryByRole('img')).toBeNull()
+  })
+
+  it('exposes an accessible name when labelled', () => {
+    render(<ChannelIcon channel="email" label="Email" />)
+    expect(screen.getByRole('img', { name: 'Email' })).toBeInTheDocument()
+  })
+})

package/src/components/channel-icon/channel-icon.tsx

@@ -0,0 +1,67 @@
+import {
+  AtSign,
+  AudioLines,
+  Camera,
+  Hash,
+  type LucideIcon,
+  Linkedin,
+  Mail,
+  MessageCircle,
+  MessagesSquare,
+  Mic,
+  Send,
+  Video,
+} from 'lucide-react'
+
+import { cn } from '../../lib/cn'
+
+/* =========================================================================
+   Channel glyphs — the one lucide lookup for a conversation channel, shared
+   by every surface that shows where a message came from (hub sidebar,
+   compose picker, draft-review card, custom components). Channels the
+   platform gained but this map hasn't fall back to the generic conversation
+   glyph rather than rendering nothing.
+
+   Deliberately keyed by a loose `string`: `Message['channel']` widens over
+   time and callers routinely hold a raw slug from the wire.
+   ========================================================================= */
+
+const CHANNEL_ICONS: Readonly<Record<string, LucideIcon>> = {
+  slack: Hash,
+  email: Mail,
+  whatsapp: MessageCircle,
+  linkedin: Linkedin,
+  telegram: Send,
+  instagram: Camera,
+  messenger: MessagesSquare,
+  x: AtSign,
+  meeting: Mic,
+  'zoom-meeting': Video,
+  'google-meet': Video,
+  'teams-meeting': Video,
+  'webex-meeting': Video,
+  adhoc: AudioLines,
+}
+
+/** The channel's glyph component. Unknown channels get the generic one. */
+export function channelIcon(channel: string): LucideIcon {
+  return CHANNEL_ICONS[channel] ?? MessagesSquare
+}
+
+export interface ChannelIconProps {
+  channel: string
+  className?: string
+  /** Accessible name. Omitted (the default) renders the glyph aria-hidden —
+   *  correct whenever the channel is already named in adjacent text. */
+  label?: string
+}
+
+/** Thin wrapper over {@link channelIcon} for the common inline case. */
+export function ChannelIcon({ channel, className, label }: ChannelIconProps) {
+  const Icon = channelIcon(channel)
+  return label !== undefined ? (
+    <Icon className={cn('size-4', className)} role="img" aria-label={label} />
+  ) : (
+    <Icon className={cn('size-4', className)} aria-hidden />
+  )
+}

package/src/components/channel-icon/index.ts

@@ -0,0 +1,2 @@
+export type { ChannelIconProps } from './channel-icon'
+export { ChannelIcon, channelIcon } from './channel-icon'

package/src/components/draft-message-card/draft-message-card.stories.tsx

@@ -0,0 +1,94 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import type { Conversation, Message } from '@proteos/sdk'
+
+import type { DraftMessageClient } from '../draft-message-composer'
+import { DraftMessageCard } from './draft-message-card'
+import { DraftMessageReview } from './draft-message-review'
+
+const meta: Meta<typeof DraftMessageCard> = {
+  title: 'Components/DraftMessageCard',
+  component: DraftMessageCard,
+  tags: ['autodocs'],
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj<typeof DraftMessageCard>
+
+/* ===== The three card states, side by side ===== */
+
+export const AwaitingReview: Story = {
+  args: {
+    channel: 'email',
+    title: 'Re: Q3 freight tender — revised lane pricing',
+    recipients: ['Dana Ruiz', 'ops@northline.example'],
+  },
+}
+
+export const Sent: Story = {
+  args: { ...AwaitingReview.args, outcome: 'sent' } as Story['args'],
+}
+
+export const DeliveryFailed: Story = {
+  args: { ...AwaitingReview.args, outcome: 'failed' } as Story['args'],
+}
+
+export const ChatChannelNoSubject: Story = {
+  args: {
+    channel: 'slack',
+    title: 'Confirming the Tuesday pickup window at the Dallas yard',
+  },
+}
+
+/* ===== Connected: DraftMessageReview against a stubbed client ===== */
+
+const draft = {
+  id: 'draft-1',
+  org_id: 'org-1',
+  conversation_id: 'conv-1',
+  connection_id: 'conn-1',
+  channel: 'email',
+  direction: 'outbound',
+  external_message_id: '',
+  sender: { name: 'Ava' },
+  recipients: [{ external_id: 'dana@northline.example', name: 'Dana Ruiz', role: 'to' }],
+  content: [{ type: 'text', text: 'Hi Dana — revised lane pricing attached.' }],
+  status: 'draft',
+  occurred_at: '2026-07-22T10:00:00Z',
+  metadata: {},
+  error: '',
+  created_at: '2026-07-22T10:00:00Z',
+  created_by: { type: 'agent', id: 'ava' },
+  updated_at: '2026-07-22T10:00:00Z',
+  updated_by: { type: 'agent', id: 'ava' },
+} as Message
+
+const stubClient: DraftMessageClient = {
+  getMessage: async () => draft,
+  getConversation: async () =>
+    ({ id: 'conv-1', subject: 'Q3 freight tender', status: 'draft', channel: 'email' }) as Conversation,
+  updateDraft: async () => draft,
+  sendDraft: async () => ({ ...draft, status: 'sent' }) as Message,
+  rejectDraft: async () => ({ ...draft, status: 'rejected' }) as Message,
+  searchRecipients: async () => [],
+}
+
+/** Default seam: Review opens the built-in modal around DraftMessageComposer. */
+export const ReviewWithBuiltInModal: StoryObj<typeof DraftMessageReview> = {
+  render: () => <DraftMessageReview messageId="draft-1" client={stubClient} />,
+}
+
+/** Overridden seam: `onPreview` replaces the modal entirely — this is the shape
+ *  a sandboxed custom component uses, delegating to the host via postMessage. */
+export const ReviewWithHostedPreview: StoryObj<typeof DraftMessageReview> = {
+  render: () => (
+    <DraftMessageReview
+      messageId="draft-1"
+      client={stubClient}
+      previewLabel="Open in host"
+      onPreview={async () => {
+        window.alert('The host would open the review modal here (e.g. useComponentModal).')
+        return 'sent'
+      }}
+    />
+  ),
+}

package/src/components/draft-message-card/draft-message-card.test.tsx

@@ -0,0 +1,43 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+
+import { DraftMessageCard } from './draft-message-card'
+
+describe('DraftMessageCard', () => {
+  it('renders the headline and the To line', () => {
+    render(
+      <DraftMessageCard channel="email" title="quarterly numbers" recipients={['Alice', 'Bob']} />,
+    )
+    expect(screen.getByText('quarterly numbers')).toBeInTheDocument()
+    expect(screen.getByText('To Alice, Bob')).toBeInTheDocument()
+  })
+
+  it('omits the To line when there are no recipients', () => {
+    render(<DraftMessageCard channel="slack" title="ping" recipients={[]} />)
+    expect(screen.queryByText(/^To /)).toBeNull()
+  })
+
+  it('fires onPreview from the action', async () => {
+    const onPreview = vi.fn()
+    render(<DraftMessageCard channel="email" title="draft" onPreview={onPreview} />)
+    await userEvent.click(screen.getByRole('button', { name: 'Review' }))
+    expect(onPreview).toHaveBeenCalledOnce()
+  })
+
+  it('replaces the action with a status label once decided', () => {
+    render(<DraftMessageCard channel="email" title="draft" outcome="rejected" />)
+    expect(screen.queryByRole('button')).toBeNull()
+    expect(screen.getByText('Rejected')).toBeInTheDocument()
+  })
+
+  it('spells out that a failure happened AFTER approval', () => {
+    render(<DraftMessageCard channel="email" title="draft" outcome="failed" />)
+    expect(screen.getByText('Approved, but delivery failed')).toBeInTheDocument()
+  })
+
+  it('disables the action while a preview is in flight', () => {
+    render(<DraftMessageCard channel="email" title="draft" isPreviewDisabled />)
+    expect(screen.getByRole('button', { name: 'Review' })).toBeDisabled()
+  })
+})

package/src/components/draft-message-card/draft-message-card.tsx

@@ -0,0 +1,111 @@
+import type { ReactNode } from 'react'
+import { Button as AriaButton } from 'react-aria-components'
+import { tv } from 'tailwind-variants'
+
+import { cn } from '../../lib/cn'
+import { ChannelIcon } from '../channel-icon'
+import type { DraftReviewOutcome } from '../draft-message-composer'
+
+/* =========================================================================
+   DraftMessageCard — the compact entry point to reviewing an agent-drafted
+   outbound message: channel glyph, eyebrow, headline (subject or first body
+   line), the To line, and one action. Pure chrome — it neither fetches nor
+   decides anything, so it can sit in a chat flow, a record page, a task list
+   or a custom component alike. DraftMessageReview is the connected wrapper;
+   reach for this one only when the host already holds the draft.
+
+   Once decided the action is replaced by a status label rather than removed:
+   the row keeps its shape, and the reader keeps the record of what happened.
+   ========================================================================= */
+
+export const draftMessageCardStyles = tv({
+  slots: {
+    root: [
+      'flex items-center gap-2.5 rounded-md border border-accent/40 px-3 py-2',
+      'bg-[color-mix(in_oklab,var(--color-accent)_6%,var(--color-surface))]',
+    ],
+    icon: [
+      'grid size-8 shrink-0 place-items-center rounded-full text-accent',
+      'bg-[color-mix(in_oklab,var(--color-accent)_12%,transparent)]',
+    ],
+    body: 'min-w-0 flex-1',
+    eyebrow: 'font-mono text-[10px] uppercase tracking-[0.08em] text-accent',
+    title: 'truncate text-[13px] font-medium text-ink',
+    recipients: 'truncate text-[12px] text-ink-3',
+    action: [
+      'shrink-0 cursor-pointer rounded-sm border border-accent/50 px-2.5 py-1',
+      'font-mono text-[11px] text-accent outline-none',
+      'hover:bg-[color-mix(in_oklab,var(--color-accent)_12%,transparent)]',
+      'focus-visible:shadow-[var(--shadow-focus)]',
+      'disabled:cursor-default disabled:opacity-50',
+    ],
+    outcome: 'shrink-0 font-mono text-[11px] text-ink-3',
+  },
+})
+
+const styles = draftMessageCardStyles()
+
+/** Terminal-state wording. `failed` is deliberately explicit: the human DID
+ *  approve the send, and hiding that behind a bare "Failed" reads as though
+ *  the review itself failed. */
+export const DRAFT_OUTCOME_LABEL: Record<DraftReviewOutcome, string> = {
+  sent: 'Sent',
+  rejected: 'Rejected',
+  failed: 'Approved, but delivery failed',
+}
+
+export interface DraftMessageCardProps {
+  /** Channel slug driving the glyph — see channelIcon. */
+  channel: string
+  /** Headline: the conversation subject, or the draft's first body line. */
+  title: string
+  /** Rendered as "To a, b". Empty or omitted hides the row. */
+  recipients?: string[]
+  /** Default 'Draft — awaiting review'. */
+  eyebrow?: ReactNode
+  /** Default 'Review'. */
+  previewLabel?: string
+  /** Terminal outcome. Set ⇒ the action is replaced by its status label. */
+  outcome?: DraftReviewOutcome | null
+  onPreview?: () => void
+  isPreviewDisabled?: boolean
+  className?: string
+}
+
+export function DraftMessageCard({
+  channel,
+  title,
+  recipients,
+  eyebrow = 'Draft — awaiting review',
+  previewLabel = 'Review',
+  outcome,
+  onPreview,
+  isPreviewDisabled = false,
+  className,
+}: DraftMessageCardProps) {
+  return (
+    <div className={cn(styles.root(), className)}>
+      <span className={styles.icon()}>
+        <ChannelIcon channel={channel} />
+      </span>
+      <div className={styles.body()}>
+        <p className={styles.eyebrow()}>{eyebrow}</p>
+        <p className={styles.title()}>{title}</p>
+        {recipients && recipients.length > 0 ? (
+          <p className={styles.recipients()}>To {recipients.join(', ')}</p>
+        ) : null}
+      </div>
+      {outcome ? (
+        <span className={styles.outcome()}>{DRAFT_OUTCOME_LABEL[outcome]}</span>
+      ) : (
+        <AriaButton
+          onPress={onPreview ?? (() => {})}
+          isDisabled={isPreviewDisabled}
+          className={styles.action()}
+        >
+          {previewLabel}
+        </AriaButton>
+      )}
+    </div>
+  )
+}

package/src/components/draft-message-card/draft-message-review.test.tsx

@@ -0,0 +1,170 @@
+import type { Conversation, Message } from '@proteos/sdk'
+import { render, screen, waitFor, within } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import {
+  __resetDraftMessageActions,
+  __resetDraftMessageOutcomes,
+  type DraftMessageClient,
+  publishDraftMessageOutcome,
+} from '../draft-message-composer'
+import { DraftMessageReview } from './draft-message-review'
+
+function draftMessage(overrides: Partial<Message> = {}): Message {
+  return {
+    id: 'draft-1',
+    org_id: 'org-1',
+    conversation_id: 'conv-1',
+    connection_id: 'conn-1',
+    channel: 'email',
+    direction: 'outbound',
+    external_message_id: '',
+    sender: { name: 'Ava Agent' },
+    recipients: [{ external_id: 'a@x.io', name: 'Alice', role: 'to' }],
+    content: [{ type: 'text', text: 'agent draft body\nsecond line' }],
+    status: 'draft',
+    occurred_at: '2026-07-22T10:00:00Z',
+    metadata: {},
+    error: '',
+    created_at: '2026-07-22T10:00:00Z',
+    created_by: { type: 'agent', id: 'agent-1' },
+    updated_at: '2026-07-22T10:00:00Z',
+    updated_by: { type: 'agent', id: 'agent-1' },
+    ...overrides,
+  }
+}
+
+function draftConversation(overrides: Partial<Conversation> = {}): Conversation {
+  return { id: 'conv-1', subject: 'quarterly numbers', status: 'draft', channel: 'email', ...overrides } as Conversation
+}
+
+function mockClient(overrides: Partial<DraftMessageClient> = {}): DraftMessageClient {
+  return {
+    getMessage: vi.fn().mockResolvedValue(draftMessage()),
+    getConversation: vi.fn().mockResolvedValue(draftConversation()),
+    updateDraft: vi.fn().mockResolvedValue(draftMessage()),
+    sendDraft: vi.fn().mockResolvedValue(draftMessage({ status: 'sent' })),
+    rejectDraft: vi.fn().mockResolvedValue(draftMessage({ status: 'rejected' })),
+    searchRecipients: vi.fn().mockResolvedValue([]),
+    ...overrides,
+  }
+}
+
+describe('DraftMessageReview', () => {
+  beforeEach(() => {
+    __resetDraftMessageOutcomes()
+    __resetDraftMessageActions()
+  })
+
+  it('renders the card from the loaded draft, subject first', async () => {
+    render(<DraftMessageReview messageId="draft-1" client={mockClient()} />)
+    expect(await screen.findByText('quarterly numbers')).toBeInTheDocument()
+    expect(screen.getByText('To Alice')).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Review' })).toBeInTheDocument()
+  })
+
+  it('falls back to the first body line when the conversation has no subject', async () => {
+    const client = mockClient({
+      getConversation: vi.fn().mockResolvedValue(draftConversation({ subject: '' })),
+    })
+    render(<DraftMessageReview messageId="draft-1" client={client} />)
+    expect(await screen.findByText('agent draft body')).toBeInTheDocument()
+  })
+
+  it('settles immediately for a draft that was already decided elsewhere', async () => {
+    const onOutcome = vi.fn()
+    const client = mockClient({
+      getMessage: vi.fn().mockResolvedValue(draftMessage({ status: 'rejected' })),
+    })
+    render(<DraftMessageReview messageId="draft-1" client={client} onOutcome={onOutcome} />)
+
+    expect(await screen.findByText('Rejected')).toBeInTheDocument()
+    expect(screen.queryByRole('button', { name: 'Review' })).toBeNull()
+    expect(onOutcome).toHaveBeenCalledExactlyOnceWith('rejected', expect.objectContaining({ status: 'rejected' }))
+    // Terminal on load ⇒ no need for the conversation.
+    expect(client.getConversation).not.toHaveBeenCalled()
+  })
+
+  it('reports a load failure and renders nothing', async () => {
+    const onLoadError = vi.fn()
+    const client = mockClient({ getMessage: vi.fn().mockRejectedValue(new Error('boom')) })
+    const { container } = render(
+      <DraftMessageReview messageId="draft-1" client={client} onLoadError={onLoadError} />,
+    )
+    await waitFor(() => expect(onLoadError).toHaveBeenCalledOnce())
+    expect(onLoadError.mock.calls[0]?.[0]).toBeInstanceOf(Error)
+    expect(container).toBeEmptyDOMElement()
+  })
+
+  it('opens the built-in composer modal when no override is given', async () => {
+    render(<DraftMessageReview messageId="draft-1" client={mockClient()} />)
+    await userEvent.click(await screen.findByRole('button', { name: 'Review' }))
+
+    const dialog = await screen.findByRole('dialog', { name: 'Review draft' })
+    // The composer itself is mounted inside, loaded and editable.
+    expect(await within(dialog).findByText('Draft · awaiting review')).toBeInTheDocument()
+    expect(within(dialog).getByRole('button', { name: 'Reject' })).toBeInTheDocument()
+  })
+
+  it('settles the card when the built-in composer rejects the draft', async () => {
+    const onOutcome = vi.fn()
+    render(<DraftMessageReview messageId="draft-1" client={mockClient()} onOutcome={onOutcome} />)
+    await userEvent.click(await screen.findByRole('button', { name: 'Review' }))
+
+    // Two-step confirm inside the composer.
+    await userEvent.click(await screen.findByRole('button', { name: 'Reject' }))
+    await userEvent.click(await screen.findByRole('button', { name: /confirm reject/i }))
+
+    await waitFor(() => expect(onOutcome).toHaveBeenCalledExactlyOnceWith('rejected', expect.anything()))
+    expect(await screen.findByText('Rejected')).toBeInTheDocument()
+  })
+
+  it('hands the whole interaction to onPreview and never renders its own modal', async () => {
+    const onPreview = vi.fn().mockResolvedValue('sent')
+    const onOutcome = vi.fn()
+    render(
+      <DraftMessageReview
+        messageId="draft-1"
+        client={mockClient()}
+        onPreview={onPreview}
+        onOutcome={onOutcome}
+      />,
+    )
+    await userEvent.click(await screen.findByRole('button', { name: 'Review' }))
+
+    expect(onPreview).toHaveBeenCalledExactlyOnceWith('draft-1')
+    expect(screen.queryByRole('dialog')).toBeNull()
+    await waitFor(() => expect(onOutcome).toHaveBeenCalledExactlyOnceWith('sent', undefined))
+    expect(await screen.findByText('Sent')).toBeInTheDocument()
+  })
+
+  it('leaves the card reviewable when onPreview resolves null (dismissed)', async () => {
+    const onPreview = vi.fn().mockResolvedValue(null)
+    const onOutcome = vi.fn()
+    render(
+      <DraftMessageReview
+        messageId="draft-1"
+        client={mockClient()}
+        onPreview={onPreview}
+        onOutcome={onOutcome}
+      />,
+    )
+    await userEvent.click(await screen.findByRole('button', { name: 'Review' }))
+
+    await waitFor(() => expect(onPreview).toHaveBeenCalledOnce())
+    expect(onOutcome).not.toHaveBeenCalled()
+    expect(await screen.findByRole('button', { name: 'Review' })).toBeEnabled()
+  })
+
+  it('settles from a composer elsewhere in the realm, once', async () => {
+    const onOutcome = vi.fn()
+    render(<DraftMessageReview messageId="draft-1" client={mockClient()} onOutcome={onOutcome} />)
+    await screen.findByRole('button', { name: 'Review' })
+
+    publishDraftMessageOutcome('draft-1', { type: 'sent', message: draftMessage({ status: 'sent' }) })
+
+    expect(await screen.findByText('Sent')).toBeInTheDocument()
+    expect(onOutcome).toHaveBeenCalledOnce()
+  })
+})