@proteos/ui 0.50.1 → 0.51.0

package/src/components/conversation-brief-card/conversation-brief-review.test.tsx

@@ -0,0 +1,214 @@
+import type { Contact, ConversationBrief } from '@proteos/sdk'
+import { render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+
+import { ConversationBriefCard } from './conversation-brief-card'
+import { ConversationBriefPreview } from './conversation-brief-preview'
+import { ConversationBriefReview } from './conversation-brief-review'
+import { type ConversationBriefClient, contactPhoneNumbers } from './types'
+
+function brief(overrides: Partial<ConversationBrief> = {}): ConversationBrief {
+  return {
+    id: 'brief-1',
+    org_id: 'org-1',
+    contact_ids: ['contact-1'],
+    subject: '',
+    type_key: 'renewal',
+    status: 'prepared',
+    content: 'Ask about the renewal.\nMention the Q4 discount.',
+    created_at: '2026-09-09T10:00:00Z',
+    created_by: { type: 'agent', id: 'agent-1' },
+    updated_at: '2026-09-09T10:00:00Z',
+    updated_by: { type: 'agent', id: 'agent-1' },
+    ...overrides,
+  }
+}
+
+function contact(overrides: Partial<Contact> = {}): Contact {
+  return {
+    id: 'contact-1',
+    name: 'Alice Example',
+    addresses: [
+      { id: 'a1', kind: 'email', value: 'alice@example.com' },
+      { id: 'a2', kind: 'phone', value: '+4930123456' },
+      { id: 'a3', kind: 'phone', value: '+4917612345' },
+    ],
+    ...overrides,
+  } as Contact
+}
+
+function mockClient(overrides: Partial<ConversationBriefClient> = {}): ConversationBriefClient {
+  return {
+    getConversationBrief: vi.fn().mockResolvedValue(brief()),
+    getContact: vi.fn().mockResolvedValue(contact()),
+    ...overrides,
+  }
+}
+
+describe('contactPhoneNumbers', () => {
+  it('keeps only phone addresses, deduplicated', () => {
+    expect(contactPhoneNumbers(contact())).toEqual(['+4930123456', '+4917612345'])
+    expect(contactPhoneNumbers(null)).toEqual([])
+  })
+})
+
+describe('ConversationBriefCard', () => {
+  it('renders the action while open and the outcome label once terminal', () => {
+    const onOpen = vi.fn()
+    const { rerender } = render(
+      <ConversationBriefCard title="Alice" summary="renewal" onOpen={onOpen} />,
+    )
+    expect(screen.getByRole('button', { name: 'Open Brief' })).toBeInTheDocument()
+    rerender(<ConversationBriefCard title="Alice" outcome="used" />)
+    expect(screen.queryByRole('button', { name: 'Open Brief' })).not.toBeInTheDocument()
+    expect(screen.getByText('Call held')).toBeInTheDocument()
+  })
+})
+
+describe('ConversationBriefReview', () => {
+  it('loads the brief + contact and hands Open Brief to the host seam', async () => {
+    const onOpenCall = vi.fn()
+    render(
+      <ConversationBriefReview
+        conversationBriefId="brief-1"
+        client={mockClient()}
+        onOpenCall={onOpenCall}
+      />,
+    )
+    expect(await screen.findByText('Alice Example')).toBeInTheDocument()
+    expect(screen.getByText('renewal · Ask about the renewal.')).toBeInTheDocument()
+    await userEvent.click(screen.getByRole('button', { name: 'Open Brief' }))
+    expect(onOpenCall).toHaveBeenCalledWith('brief-1')
+  })
+
+  it('opens the built-in preview and dials through onCall', async () => {
+    const onCall = vi.fn()
+    render(
+      <ConversationBriefReview
+        conversationBriefId="brief-1"
+        client={mockClient()}
+        onCall={onCall}
+      />,
+    )
+    await userEvent.click(await screen.findByRole('button', { name: 'Open Brief' }))
+    expect(await screen.findByRole('dialog')).toBeInTheDocument()
+    expect(screen.getByText(/Mention the Q4 discount/)).toBeInTheDocument()
+    await userEvent.click(screen.getByRole('button', { name: 'Call' }))
+    expect(onCall).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'brief-1' }),
+      expect.objectContaining({ id: 'contact-1' }),
+      '+4930123456',
+    )
+  })
+
+  it('settles immediately when the brief is already used', async () => {
+    const onOutcome = vi.fn()
+    const client = mockClient({
+      getConversationBrief: vi.fn().mockResolvedValue(brief({ status: 'used' })),
+    })
+    render(
+      <ConversationBriefReview
+        conversationBriefId="brief-1"
+        client={client}
+        onOutcome={onOutcome}
+      />,
+    )
+    await waitFor(() => expect(onOutcome).toHaveBeenCalledTimes(1))
+    expect(onOutcome).toHaveBeenCalledWith('used', expect.objectContaining({ status: 'used' }))
+    expect(screen.getByText('Call held')).toBeInTheDocument()
+  })
+
+  it('reports a load error and renders nothing', async () => {
+    const onLoadError = vi.fn()
+    const client = mockClient({
+      getConversationBrief: vi.fn().mockRejectedValue(new Error('nope')),
+    })
+    const { container } = render(
+      <ConversationBriefReview
+        conversationBriefId="brief-1"
+        client={client}
+        onLoadError={onLoadError}
+      />,
+    )
+    await waitFor(() => expect(onLoadError).toHaveBeenCalled())
+    expect(container).toBeEmptyDOMElement()
+  })
+})
+
+describe('ConversationBriefReview subject + channel', () => {
+  it('leads with the subject and labels a meeting brief Open Brief', async () => {
+    const client = mockClient({
+      getConversationBrief: vi
+        .fn()
+        .mockResolvedValue(brief({ subject: 'Renewal on Zoom', channel: 'zoom-meeting' })),
+    })
+    render(
+      <ConversationBriefReview conversationBriefId="brief-1" client={client} onCall={vi.fn()} />,
+    )
+    expect(await screen.findByText('Renewal on Zoom')).toBeInTheDocument()
+    expect(
+      screen.getByText('Alice Example · zoom-meeting · renewal · Ask about the renewal.'),
+    ).toBeInTheDocument()
+    await userEvent.click(screen.getByRole('button', { name: 'Open Brief' }))
+    expect(await screen.findByRole('dialog')).toBeInTheDocument()
+    // A meeting brief is not dialable from the platform — no Call button.
+    expect(screen.queryByRole('button', { name: 'Call' })).not.toBeInTheDocument()
+  })
+})
+
+describe('ConversationBriefPreview', () => {
+  it('offers a who-to-call pick for several contacts', async () => {
+    const onCall = vi.fn()
+    const tom = contact({
+      id: 'contact-2',
+      name: 'Tom Example',
+      addresses: [{ id: 'b1', kind: 'phone', value: '+4915500000' }],
+    } as Partial<Contact>)
+    render(
+      <ConversationBriefPreview
+        brief={brief({ contact_ids: ['contact-1', 'contact-2'] })}
+        contacts={[contact(), tom]}
+        onCall={onCall}
+      />,
+    )
+    expect(screen.getByRole('button', { name: /Who to call/ })).toBeInTheDocument()
+    await userEvent.click(screen.getByRole('button', { name: 'Call' }))
+    expect(onCall).toHaveBeenCalledWith(expect.objectContaining({ id: 'contact-1' }), '+4930123456')
+  })
+
+  it('can hide its Call button and report the target to the host', () => {
+    const onSelectionChange = vi.fn()
+    render(
+      <ConversationBriefPreview
+        brief={brief()}
+        contacts={[contact()]}
+        onCall={vi.fn()}
+        isCallButtonHidden
+        onSelectionChange={onSelectionChange}
+      />,
+    )
+    expect(screen.queryByRole('button', { name: 'Call' })).not.toBeInTheDocument()
+    expect(onSelectionChange).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'contact-1' }),
+      '+4930123456',
+    )
+  })
+
+  it('is read-only without onCall', () => {
+    render(<ConversationBriefPreview brief={brief()} contacts={[contact()]} />)
+    expect(screen.queryByRole('button', { name: 'Call' })).not.toBeInTheDocument()
+  })
+
+  it('disables Call when the contact has no number', () => {
+    render(
+      <ConversationBriefPreview
+        brief={brief()}
+        contacts={[contact({ addresses: [] })]}
+        onCall={vi.fn()}
+      />,
+    )
+    expect(screen.getByRole('button', { name: 'Call' })).toBeDisabled()
+    expect(screen.getByText(/no phone number/)).toBeInTheDocument()
+  })
+})

package/src/components/conversation-brief-card/conversation-brief-review.tsx

@@ -0,0 +1,192 @@
+import type { Contact, ConversationBrief } from '@proteos/sdk'
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import { ModalBody, ModalContent, ModalHeader, ModalTitle } from '../modal'
+import { ConversationBriefCard } from './conversation-brief-card'
+import { ConversationBriefPreview } from './conversation-brief-preview'
+import {
+  type ConversationBriefClient,
+  type ConversationBriefOutcome,
+  conversationBriefOutcomeFor,
+  isDialableConversationBrief,
+} from './types'
+
+/* =========================================================================
+   ConversationBriefReview — the connected prepared-call entry point: loads the brief
+   (and its contact) through the injected client, renders ConversationBriefCard, and
+   owns what "Open Brief" does.
+
+   The open action is the seam. Left alone it opens a modal with the
+   ConversationBriefPreview — a read-only preview unless the host passes `onCall`
+   (the web app does: it dials through its softphone). Passed `onOpenCall`,
+   it hands the whole interaction to the host: the built-in modal is never
+   rendered. That is how a sandboxed custom component opens a prepared call —
+   an iframe cannot dial, so it asks the host (useOpenCall) to preview + dial.
+
+   A brief that is ALREADY terminal when it loads (used on a call, discarded)
+   settles the card immediately and reports `onOutcome` once.
+   ========================================================================= */
+
+export interface ConversationBriefReviewProps {
+  conversationBriefId: string
+  /** Injected fetch surface — see createConversationBriefClient. */
+  client: ConversationBriefClient
+  /**
+   * FULL REPLACEMENT for the open action's default (the built-in preview
+   * modal). When supplied the built-in modal is never rendered.
+   */
+  onOpenCall?: (conversationBriefId: string) => void
+  /** Built-in modal only: place the call to this contact + number (the
+   *  host's dial). Absent ⇒ the modal is a read-only preview. */
+  onCall?: (brief: ConversationBrief, contact: Contact, phoneNumber: string) => void
+  /** Built-in modal only: disable the Call button + explain why. */
+  isCallDisabled?: boolean
+  callDisabledReason?: string
+  /** Fires at most once, when the brief is (or becomes) terminal. */
+  onOutcome?: (outcome: ConversationBriefOutcome, brief: ConversationBrief) => void
+  /** The brief could not be loaded. The card renders nothing in that case. */
+  onLoadError?: (error: Error) => void
+  /** Built-in modal heading. Default 'Prepared conversation'. */
+  modalTitle?: string
+  modalClassName?: string
+  /** Built-in modal overlay classes — where a host raises the z tier. */
+  overlayClassName?: string
+  openLabel?: string
+  className?: string
+}
+
+export function ConversationBriefReview({
+  conversationBriefId,
+  client,
+  onOpenCall,
+  onCall,
+  isCallDisabled = false,
+  callDisabledReason,
+  onOutcome,
+  onLoadError,
+  modalTitle = 'Prepared conversation',
+  modalClassName = 'max-w-2xl',
+  overlayClassName,
+  openLabel,
+  className,
+}: ConversationBriefReviewProps) {
+  const [brief, setBrief] = useState<ConversationBrief | null>(null)
+  const [contacts, setContacts] = useState<Contact[]>([])
+  const [isOpen, setIsOpen] = useState(false)
+  const [outcome, setOutcome] = useState<ConversationBriefOutcome | null>(null)
+
+  const onOutcomeRef = useRef(onOutcome)
+  onOutcomeRef.current = onOutcome
+  const onLoadErrorRef = useRef(onLoadError)
+  onLoadErrorRef.current = onLoadError
+
+  const hasSettledRef = useRef(false)
+  const settle = useCallback((next: ConversationBriefOutcome, settled: ConversationBrief) => {
+    setOutcome(next)
+    setIsOpen(false)
+    if (hasSettledRef.current) return
+    hasSettledRef.current = true
+    onOutcomeRef.current?.(next, settled)
+  }, [])
+
+  useEffect(() => {
+    let cancelled = false
+    void (async () => {
+      try {
+        const loaded = await client.getConversationBrief(conversationBriefId)
+        if (cancelled) return
+        setBrief(loaded)
+        const terminal = conversationBriefOutcomeFor(loaded.status)
+        if (terminal) settle(terminal, loaded)
+        const people = await Promise.all(
+          loaded.contact_ids.map((contactId) => client.getContact(contactId).catch(() => null)),
+        )
+        if (!cancelled) setContacts(people.filter((person): person is Contact => person !== null))
+      } catch (error) {
+        if (cancelled) return
+        onLoadErrorRef.current?.(error instanceof Error ? error : new Error(String(error)))
+      }
+    })()
+    return () => {
+      cancelled = true
+    }
+  }, [client, conversationBriefId, settle])
+
+  const open = () => {
+    if (onOpenCall) {
+      onOpenCall(conversationBriefId)
+      return
+    }
+    setIsOpen(true)
+  }
+
+  if (!brief) return null
+
+  return (
+    <>
+      <ConversationBriefCard
+        title={brief.subject || namesOf(contacts) || 'Prepared conversation'}
+        summary={summaryFor(brief, contacts)}
+        outcome={outcome}
+        onOpen={open}
+        {...(openLabel !== undefined ? { openLabel } : {})}
+        {...(className !== undefined ? { className } : {})}
+      />
+      {onOpenCall ? null : (
+        <ModalContent
+          isOpen={isOpen}
+          onOpenChange={setIsOpen}
+          modalClassName={modalClassName}
+          {...(overlayClassName !== undefined ? { className: overlayClassName } : {})}
+        >
+          <ModalHeader>
+            <ModalTitle>{modalTitle}</ModalTitle>
+          </ModalHeader>
+          <ModalBody className="min-h-0 overflow-y-auto">
+            <ConversationBriefPreview
+              brief={brief}
+              contacts={contacts}
+              contentClassName="max-h-[50dvh]"
+              isCallDisabled={isCallDisabled}
+              {...(callDisabledReason !== undefined ? { callDisabledReason } : {})}
+              {...(onCall && isDialableConversationBrief(brief)
+                ? {
+                    onCall: (contact: Contact, phoneNumber: string) => {
+                      setIsOpen(false)
+                      onCall(brief, contact, phoneNumber)
+                    },
+                  }
+                : {})}
+            />
+          </ModalBody>
+        </ModalContent>
+      )}
+    </>
+  )
+}
+
+/** The people's names, comma-joined. */
+export function namesOf(contacts: Contact[]): string {
+  return contacts
+    .map((contact) => contact.name)
+    .filter(Boolean)
+    .join(', ')
+}
+
+/** Who + where + what: the people (when the subject took the headline),
+ *  the channel, the type, then the opening line. */
+export function summaryFor(brief: ConversationBrief, contacts: Contact[]): string {
+  const firstLine =
+    brief.content
+      .split('\n')
+      .find((line) => line.trim() !== '')
+      ?.trim() ?? ''
+  return [
+    brief.subject ? namesOf(contacts) : '',
+    brief.channel ?? '',
+    brief.type_key ?? '',
+    firstLine,
+  ]
+    .filter(Boolean)
+    .join(' · ')
+}

package/src/components/conversation-brief-card/create-conversation-brief-client.ts

@@ -0,0 +1,18 @@
+import type { ConversationClient } from '@proteos/sdk'
+
+import type { ConversationBriefClient } from './types'
+
+/**
+ * One-liner adapter from the sdk ConversationClient (web app:
+ * `useSdk().conversation`; custom components: `useSdk().conversations`) to
+ * the conversation-brief surfaces' injected client. Type-only sdk import.
+ */
+export function createConversationBriefClient(
+  conversation: Pick<ConversationClient, 'conversationBriefs' | 'contacts'>,
+): ConversationBriefClient {
+  return {
+    getConversationBrief: (conversationBriefId) =>
+      conversation.conversationBriefs.get(conversationBriefId),
+    getContact: (contactId) => conversation.contacts.get(contactId),
+  }
+}

package/src/components/conversation-brief-card/index.ts

@@ -0,0 +1,24 @@
+export {
+  CONVERSATION_BRIEF_OUTCOME_LABEL,
+  ConversationBriefCard,
+  type ConversationBriefCardProps,
+  conversationBriefCardStyles,
+} from './conversation-brief-card'
+export {
+  ConversationBriefPreview,
+  type ConversationBriefPreviewProps,
+} from './conversation-brief-preview'
+export {
+  ConversationBriefReview,
+  type ConversationBriefReviewProps,
+  namesOf,
+  summaryFor,
+} from './conversation-brief-review'
+export { createConversationBriefClient } from './create-conversation-brief-client'
+export {
+  type ConversationBriefClient,
+  type ConversationBriefOutcome,
+  contactPhoneNumbers,
+  conversationBriefOutcomeFor,
+  isDialableConversationBrief,
+} from './types'

package/src/components/conversation-brief-card/types.ts

@@ -0,0 +1,50 @@
+import type { Contact, ConversationBrief } from '@proteos/sdk'
+
+/* =========================================================================
+   ConversationBriefReview contracts — types-only @proteos/sdk imports, so the lib
+   stays fetch-agnostic (the DraftMessageComposer precedent): the host injects
+   the client, the component never talks to the network itself.
+   ========================================================================= */
+
+/**
+ * The minimal fetch surface the conversation-brief surfaces need, injected per host:
+ * the web app builds it from `useSdk().conversation`, custom components from
+ * `useSdk().conversations` — both via {@link createConversationBriefClient}.
+ */
+export interface ConversationBriefClient {
+  /** One brief — also resolves terminal states (used / discarded) by id. */
+  getConversationBrief(conversationBriefId: string): Promise<ConversationBrief>
+  /** One of the brief's contacts: name + addresses (the phone numbers to dial). */
+  getContact(contactId: string): Promise<Contact>
+}
+
+/** A brief's terminal state — what the card shows once it can no longer be
+ *  opened for a call. */
+export type ConversationBriefOutcome = 'used' | 'discarded'
+
+/** The terminal outcome for a brief status, or null while it is open. */
+export function conversationBriefOutcomeFor(
+  status: ConversationBrief['status'],
+): ConversationBriefOutcome | null {
+  if (status === 'used' || status === 'discarded') return status
+  return null
+}
+
+/** Whether a brief can be turned into a phone call from the platform: pinned
+ *  to the phone channel, or not pinned at all (any channel). */
+export function isDialableConversationBrief(brief: Pick<ConversationBrief, 'channel'>): boolean {
+  return !brief.channel || brief.channel === 'phone'
+}
+
+/** The dialable numbers of a contact: its phone addresses, canonical (E.164)
+ *  value first-served, deduplicated. */
+export function contactPhoneNumbers(
+  contact: Pick<Contact, 'addresses'> | null | undefined,
+): string[] {
+  const numbers: string[] = []
+  for (const address of contact?.addresses ?? []) {
+    if (address.kind !== 'phone' || !address.value) continue
+    if (!numbers.includes(address.value)) numbers.push(address.value)
+  }
+  return numbers
+}

package/src/components/data-table/data-table.test.tsx

@@ -110,3 +110,65 @@ describe('DataTable selection', () => {
     expect(onRowClick).not.toHaveBeenCalled()
   })
 })
+
+describe('DataTable grouping', () => {
+  type GroupedRow = Row & { module: string }
+
+  const GROUPED: GroupedRow[] = [
+    { id: 'g-1', name: 'Alpha', module: '' },
+    { id: 'g-2', name: 'Beta', module: 'crm' },
+    { id: 'g-3', name: 'Gamma', module: 'crm' },
+    { id: 'g-4', name: 'Delta', module: 'billing' },
+  ]
+
+  function groupedQuery(): InfiniteQueryLike<GroupedRow> {
+    return {
+      data: { pages: [{ data: GROUPED, meta: { items_total: GROUPED.length } }] },
+      isLoading: false,
+      isFetchingNextPage: false,
+      hasNextPage: false,
+      error: null,
+      fetchNextPage: vi.fn(),
+    }
+  }
+
+  const groupedColumns = [{ id: 'name', accessorKey: 'name', header: 'Name', size: 160 }]
+
+  function renderGrouped() {
+    render(
+      <DataTable<GroupedRow>
+        query={groupedQuery()}
+        columns={groupedColumns}
+        ariaLabel="Records"
+        groupBy={(row) => (row.module ? { id: row.module, label: row.module } : null)}
+      />,
+    )
+  }
+
+  it('emits one heading per group and none for ungrouped rows', () => {
+    renderGrouped()
+
+    expect(screen.getByText('crm')).toBeInTheDocument()
+    expect(screen.getByText('billing')).toBeInTheDocument()
+    // Every data row still renders alongside the headings.
+    for (const row of GROUPED) {
+      expect(screen.getByText(row.name)).toBeInTheDocument()
+    }
+  })
+
+  it('places each heading directly above its own rows', () => {
+    renderGrouped()
+
+    const text = document.body.textContent ?? ''
+    expect(text.indexOf('crm')).toBeLessThan(text.indexOf('Beta'))
+    expect(text.indexOf('Beta')).toBeLessThan(text.indexOf('billing'))
+    expect(text.indexOf('billing')).toBeLessThan(text.indexOf('Delta'))
+  })
+
+  it('renders no headings when groupBy is omitted', () => {
+    render(
+      <DataTable<GroupedRow> query={groupedQuery()} columns={groupedColumns} ariaLabel="Records" />,
+    )
+    expect(screen.queryByText('crm')).toBeNull()
+  })
+})