@adatechnology/conversations-ui 0.1.0-rc.2 → 0.1.0-rc.21

package/src/settings/TranscriptionSettingsForm.tsx

@@ -0,0 +1,189 @@
+import type { FormEvent } from 'react'
+import { AudioLines, Save } from 'lucide-react'
+import type { TranscriptionMode } from '../types'
+
+export interface TranscriptionSettingsFormLabels {
+  sectionTitle: string
+  enabled: string
+  enabledHint: string
+  modeTitle: string
+  modeAuto: string
+  modeAutoHint: string
+  modeOnDemand: string
+  modeOnDemandHint: string
+  unavailable: string
+  save: string
+  saving: string
+  saveSuccess: string
+}
+
+const DEFAULT_LABELS: TranscriptionSettingsFormLabels = {
+  sectionTitle: 'Transcrição de áudio',
+  enabled: 'Transcrever notas de voz',
+  enabledHint: 'Converte o áudio do cliente em texto, que o atendente lê e copia direto da conversa.',
+  modeTitle: 'Quando transcrever',
+  modeAuto: 'Automaticamente',
+  modeAutoHint: 'Toda nota de voz recebida é transcrita na hora. Mais cômodo, consome mais cota.',
+  modeOnDemand: 'Quando o atendente pedir',
+  modeOnDemandHint: 'Transcreve só ao clicar no botão da conversa. Consome cota apenas com áudio que alguém vai ler.',
+  unavailable: 'Transcrição não está disponível neste ambiente — fale com quem administra a instalação.',
+  save: 'Salvar',
+  saving: 'Salvando...',
+  saveSuccess: 'Configuração de transcrição salva.',
+}
+
+export interface TranscriptionSettingsFormProps {
+  enabled: boolean
+  onEnabledChange: (value: boolean) => void
+  mode: TranscriptionMode
+  onModeChange: (value: TranscriptionMode) => void
+  onSave: (event: FormEvent) => void
+  /**
+   * A capacidade existe no servidor (engine e credencial configurados)?
+   *
+   * Distinto de `enabled`: isto é "o ambiente consegue", aquilo é "esta empresa quer". Sem a
+   * distinção, um lojista ligaria o interruptor num ambiente sem engine e concluiria que o produto
+   * está quebrado — o texto nunca apareceria e nada explicaria por quê.
+   */
+  isAvailable?: boolean
+  saving?: boolean
+  saveSuccess?: boolean
+  labels?: Partial<TranscriptionSettingsFormLabels>
+}
+
+/**
+ * Interruptor de transcrição por empresa, para a tela de configurações.
+ *
+ * Puramente apresentacional, como os outros forms daqui: quem persiste é o host. O pacote não sabe a
+ * rota, e a política vive nas configurações do módulo (`settings.transcriptionEnabled`), não em
+ * variável de ambiente — mudar de ideia sobre transcrever não deveria exigir deploy.
+ */
+export function TranscriptionSettingsForm({
+  enabled,
+  onEnabledChange,
+  mode,
+  onModeChange,
+  onSave,
+  isAvailable = true,
+  saving = false,
+  saveSuccess = false,
+  labels: labelsOverride,
+}: TranscriptionSettingsFormProps) {
+  const labels = { ...DEFAULT_LABELS, ...labelsOverride }
+
+  return (
+    <section className="bg-white dark:bg-gray-800 rounded-xl border border-gray-200 dark:border-gray-700 overflow-hidden">
+      <div className="px-6 py-4 border-b border-gray-100 dark:border-gray-700">
+        <h2 className="text-sm font-semibold text-gray-900 dark:text-gray-100 flex items-center gap-1.5">
+          <AudioLines size={14} className="text-blue-600 dark:text-blue-400" />
+          {labels.sectionTitle}
+        </h2>
+      </div>
+
+      <form onSubmit={onSave} className="p-6 space-y-5">
+        {!isAvailable && (
+          <div className="bg-amber-50 dark:bg-amber-950/40 border border-amber-200 dark:border-amber-800 rounded-xl px-4 py-3 text-sm text-amber-800 dark:text-amber-300">
+            {labels.unavailable}
+          </div>
+        )}
+
+        <label className="flex items-start gap-3 cursor-pointer">
+          <input
+            type="checkbox"
+            checked={enabled}
+            onChange={(event) => onEnabledChange(event.target.checked)}
+            disabled={!isAvailable}
+            className="mt-0.5 h-4 w-4 rounded border-gray-300 text-blue-600 focus:ring-blue-500 disabled:opacity-50"
+          />
+          <span>
+            <span className="block text-sm font-medium text-gray-700 dark:text-gray-300">{labels.enabled}</span>
+            <span className="block text-xs text-gray-500 dark:text-gray-400">{labels.enabledHint}</span>
+          </span>
+        </label>
+
+        {/* O modo só aparece quando ligado: escolher "quando transcrever" sem transcrever nada é uma
+            pergunta sem consequência, e ler as duas opções gasta atenção do operador à toa. */}
+        {enabled && (
+          <fieldset disabled={!isAvailable} className="space-y-2.5">
+            <legend className="text-sm font-medium text-gray-700 dark:text-gray-300 mb-1">{labels.modeTitle}</legend>
+
+            <ModeOption
+              value="onDemand"
+              current={mode}
+              onSelect={onModeChange}
+              title={labels.modeOnDemand}
+              hint={labels.modeOnDemandHint}
+            />
+            <ModeOption
+              value="auto"
+              current={mode}
+              onSelect={onModeChange}
+              title={labels.modeAuto}
+              hint={labels.modeAutoHint}
+            />
+          </fieldset>
+        )}
+
+        {saveSuccess && (
+          <div className="bg-green-50 dark:bg-green-950/40 border border-green-200 dark:border-green-800 rounded-xl px-4 py-3 text-sm text-green-700 dark:text-green-400">
+            {labels.saveSuccess}
+          </div>
+        )}
+
+        <div className="flex justify-end">
+          <button
+            type="submit"
+            disabled={saving || !isAvailable}
+            className="flex items-center gap-2 bg-blue-600 hover:bg-blue-700 disabled:bg-blue-400 text-white font-semibold px-5 py-2.5 rounded-xl transition-colors text-sm"
+          >
+            {saving ? (
+              <span className="w-4 h-4 border-2 border-white/40 border-t-white rounded-full animate-spin" />
+            ) : (
+              <Save size={14} />
+            )}
+            {saving ? labels.saving : labels.save}
+          </button>
+        </div>
+      </form>
+    </section>
+  )
+}
+
+function ModeOption({
+  value,
+  current,
+  onSelect,
+  title,
+  hint,
+}: {
+  value: TranscriptionMode
+  current: TranscriptionMode
+  onSelect: (value: TranscriptionMode) => void
+  title: string
+  hint: string
+}) {
+  const isSelected = current === value
+
+  return (
+    <label
+      className={`flex items-start gap-3 cursor-pointer rounded-xl border px-4 py-3 transition-colors ${
+        isSelected
+          ? 'border-blue-500 bg-blue-50 dark:border-blue-500 dark:bg-blue-950/30'
+          : 'border-gray-200 hover:border-gray-300 dark:border-gray-700 dark:hover:border-gray-600'
+      }`}
+    >
+      <input
+        type="radio"
+        name="transcription-mode"
+        value={value}
+        checked={isSelected}
+        onChange={() => onSelect(value)}
+        className="mt-0.5 h-4 w-4 border-gray-300 text-blue-600 focus:ring-blue-500"
+      />
+      <span>
+        <span className="block text-sm font-medium text-gray-700 dark:text-gray-300">{title}</span>
+        <span className="block text-xs text-gray-500 dark:text-gray-400">{hint}</span>
+      </span>
+    </label>
+  )
+}

package/src/settings/WhatsAppCreateTemplateForm.tsx

@@ -24,6 +24,7 @@ export interface WhatsAppCreateTemplateFormLabels {
   sectionDescription: string
   nameLabel: string
   nameHint: string
+  namePlaceholder: string
   categoryLabel: string
   languageLabel: string
   headerLabel: string
@@ -57,6 +58,7 @@ const DEFAULT_LABELS: WhatsAppCreateTemplateFormLabels = {
   sectionDescription: 'Envia um template para aprovação da Meta.',
   nameLabel: 'Nome do template',
   nameHint: 'Somente letras minúsculas, números e underscore.',
+  namePlaceholder: 'reengajamento_cliente',
   categoryLabel: 'Categoria',
   languageLabel: 'Idioma',
   headerLabel: 'Cabeçalho',
@@ -142,7 +144,7 @@ export function WhatsAppCreateTemplateForm({
             type="text"
             value={value.name}
             onChange={(e) => set('name', e.target.value.toLowerCase().replace(/[^a-z0-9_]/g, '_'))}
-            placeholder="reengajamento_cliente"
+            placeholder={labels.namePlaceholder}
             className="w-full border border-gray-200 dark:border-gray-600 dark:bg-gray-700 dark:text-gray-100 rounded-xl px-3 py-2.5 text-sm focus:outline-none focus:ring-2 focus:ring-blue-400 focus:border-transparent transition-all"
             required
           />

package/src/settings/WhatsAppTemplatesSettings.tsx

@@ -0,0 +1,106 @@
+/**
+ * Configurações de template do WhatsApp, com submenu próprio.
+ *
+ * Junta as duas telas que já existiam soltas — escolher o template de reengajamento e criar um novo
+ * para aprovação da Meta — porque na cabeça de quem opera é um só assunto. Cada host montava esse
+ * agrupamento por conta, e é justamente o tipo de composição que deve nascer no pacote.
+ *
+ * Segue presentacional: nenhuma chamada de rede aqui. Templates, estado e handlers vêm por props.
+ */
+
+import { useState, type FormEvent } from 'react'
+import {
+  WhatsAppTemplateSettingsForm,
+  type WhatsAppTemplateSummary,
+  type WhatsAppTemplateVariableSuggestion,
+} from './WhatsAppTemplateSettingsForm'
+import {
+  WhatsAppCreateTemplateForm,
+  type WhatsAppCreateTemplateResult,
+  type WhatsAppCreateTemplateState,
+} from './WhatsAppCreateTemplateForm'
+
+export const TEMPLATE_SETTINGS_TAB = {
+  SELECT: 'select',
+  CREATE: 'create',
+} as const
+export type TemplateSettingsTab = (typeof TEMPLATE_SETTINGS_TAB)[keyof typeof TEMPLATE_SETTINGS_TAB]
+
+export interface WhatsAppTemplatesSettingsLabels {
+  selectTab: string
+  createTab: string
+}
+
+export const DEFAULT_TEMPLATES_SETTINGS_LABELS: WhatsAppTemplatesSettingsLabels = {
+  selectTab: 'Template de reengajamento',
+  createTab: 'Criar template',
+}
+
+export interface WhatsAppTemplatesSettingsProps {
+  templates: WhatsAppTemplateSummary[]
+  loadingTemplates?: boolean
+  templatesError?: boolean
+  onRefreshTemplates?: () => void
+  selectedTemplateName: string
+  onSelectTemplate: (name: string, template: WhatsAppTemplateSummary | undefined) => void
+  variables: string[]
+  onVariablesChange: (variables: string[]) => void
+  availableVariables?: WhatsAppTemplateVariableSuggestion[]
+  saving?: boolean
+  saveSuccess?: boolean
+  onSave: (event: FormEvent) => void
+  /** Ausente = host não sabe criar template; a aba de criação nem aparece. */
+  create?: {
+    value: WhatsAppCreateTemplateState
+    onChange: (value: WhatsAppCreateTemplateState) => void
+    onSubmit: (event: FormEvent) => void
+    submitting?: boolean
+    result?: WhatsAppCreateTemplateResult | null
+  }
+  labels?: Partial<WhatsAppTemplatesSettingsLabels>
+}
+
+export function WhatsAppTemplatesSettings({
+  labels: labelsOverride,
+  create,
+  ...settingsProps
+}: WhatsAppTemplatesSettingsProps) {
+  const labels = { ...DEFAULT_TEMPLATES_SETTINGS_LABELS, ...labelsOverride }
+  const [tab, setTab] = useState<TemplateSettingsTab>(TEMPLATE_SETTINGS_TAB.SELECT)
+
+  return (
+    <div className="space-y-4">
+      <nav className="flex gap-1 border-b" role="tablist">
+        <button
+          type="button"
+          role="tab"
+          aria-selected={tab === TEMPLATE_SETTINGS_TAB.SELECT}
+          onClick={() => setTab(TEMPLATE_SETTINGS_TAB.SELECT)}
+          className={`cv-subtab ${tab === TEMPLATE_SETTINGS_TAB.SELECT ? 'cv-subtab--active' : ''}`}
+        >
+          {labels.selectTab}
+        </button>
+
+        {/* A aba de criação só existe se o host souber criar: sem handler, ela seria um formulário
+            que não leva a nada. */}
+        {create ? (
+          <button
+            type="button"
+            role="tab"
+            aria-selected={tab === TEMPLATE_SETTINGS_TAB.CREATE}
+            onClick={() => setTab(TEMPLATE_SETTINGS_TAB.CREATE)}
+            className={`cv-subtab ${tab === TEMPLATE_SETTINGS_TAB.CREATE ? 'cv-subtab--active' : ''}`}
+          >
+            {labels.createTab}
+          </button>
+        ) : null}
+      </nav>
+
+      {tab === TEMPLATE_SETTINGS_TAB.SELECT ? (
+        <WhatsAppTemplateSettingsForm {...settingsProps} />
+      ) : create ? (
+        <WhatsAppCreateTemplateForm {...create} />
+      ) : null}
+    </div>
+  )
+}

package/src/styles.css

@@ -19,3 +19,176 @@
   background-color: #0b141a;
   background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='100' height='100' viewBox='0 0 100 100'%3E%3Cg fill='none' stroke='%2319232a' stroke-width='1.2' opacity='0.9'%3E%3Ccircle cx='15' cy='15' r='3'/%3E%3Cpath d='M40 10 q5 8 0 16 q-5 -8 0 -16z'/%3E%3Ccircle cx='70' cy='28' r='2'/%3E%3Cpath d='M18 55 l6 6 m-6 0 l6 -6'/%3E%3Ccircle cx='55' cy='68' r='2.5'/%3E%3Cpath d='M85 58 q6 6 0 12 q-6 -6 0 -12z'/%3E%3Ccircle cx='8' cy='85' r='2'/%3E%3Cpath d='M65 90 l5 5 m-5 0 l5 -5'/%3E%3C/g%3E%3C/svg%3E");
 }
+
+/* Botão de ação do cabeçalho de conversa e do aviso de janela. Vive no stylesheet, como o
+   .cv-wallpaper, para não depender da configuração de Tailwind do consumidor. */
+.cv-header-action {
+  border: 1px solid rgb(203 213 225);
+  border-radius: 0.375rem;
+  padding: 0.375rem 0.75rem;
+  font-size: 0.8125rem;
+  background: transparent;
+  cursor: pointer;
+}
+.cv-header-action:disabled { opacity: 0.5; cursor: not-allowed; }
+.dark .cv-header-action { border-color: rgb(71 85 105); color: rgb(226 232 240); }
+
+.cv-header-icon {
+  border: 1px solid rgb(203 213 225);
+  border-radius: 0.5rem;
+  padding: 0.375rem 0.5rem;
+  background: transparent;
+  cursor: pointer;
+  line-height: 1;
+}
+.cv-header-icon--active { background: rgb(241 245 249); border-color: rgb(148 163 184); }
+.cv-header-icon:disabled { opacity: 0.5; cursor: not-allowed; }
+.dark .cv-header-icon { border-color: rgb(71 85 105); }
+.dark .cv-header-icon--active { background: rgb(51 65 85); }
+
+.cv-header-action--primary {
+  background: rgb(37 99 235);
+  border-color: rgb(37 99 235);
+  color: white;
+  font-weight: 500;
+}
+.cv-header-action--danger {
+  background: rgb(239 68 68);
+  border-color: rgb(239 68 68);
+  color: white;
+  font-weight: 500;
+}
+
+.cv-subtab {
+  padding: 0.5rem 0.75rem;
+  font-size: 0.8125rem;
+  color: rgb(100 116 139);
+  background: transparent;
+  border: 0;
+  border-bottom: 2px solid transparent;
+  cursor: pointer;
+}
+.cv-subtab--active { color: inherit; font-weight: 500; border-bottom-color: rgb(37 99 235); }
+
+/* Pills de estado da conversa. No stylesheet, como os demais cv-*, para não depender do Tailwind
+   do consumidor. */
+.cv-pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  font-size: 0.6875rem;
+  font-weight: 500;
+  line-height: 1;
+  padding: 0.25rem 0.5rem;
+  border-radius: 9999px;
+  background: rgb(241 245 249);
+  color: rgb(71 85 105);
+}
+.cv-pill--success { background: rgb(220 252 231); color: rgb(21 128 61); }
+.cv-pill--warning { background: rgb(254 243 199); color: rgb(146 64 14); }
+.cv-pill--danger { background: rgb(255 237 213); color: rgb(194 65 12); }
+.dark .cv-pill { background: rgb(51 65 85); color: rgb(203 213 225); }
+.dark .cv-pill--success { background: rgb(20 83 45); color: rgb(187 247 208); }
+.dark .cv-pill--warning { background: rgb(120 53 15); color: rgb(253 230 138); }
+.dark .cv-pill--danger { background: rgb(124 45 18); color: rgb(254 215 170); }
+
+/* Linha da inbox: realce e hover cobrem a linha toda, incluindo checkbox, barra de janela e pills. */
+.cv-row:hover { background: #f0f2f5; }
+.cv-row--active, .cv-row--active:hover { background: #f0f2f5; }
+.dark .cv-row:hover { background: rgb(30 41 59); }
+.dark .cv-row--active, .dark .cv-row--active:hover { background: rgb(30 41 59); }
+
+/* Voltar do master/detail: existe só onde lista e conversa não cabem lado a lado. */
+.cv-back {
+  border: 1px solid rgb(203 213 225);
+  border-radius: 0.5rem;
+  padding: 0.25rem 0.5rem;
+  background: transparent;
+  cursor: pointer;
+  line-height: 1;
+}
+@media (min-width: 1024px) { .cv-back { display: none; } }
+.dark .cv-back { border-color: rgb(71 85 105); color: rgb(226 232 240); }
+
+/* Utilitários de densidade: em tela estreita o texto das ações vira ícone, porque rótulo longo
+   empilha e come a altura útil da conversa. */
+.cv-only-wide { display: none; }
+@media (min-width: 1024px) { .cv-only-wide { display: inline; } }
+.cv-only-narrow { display: inline-flex; }
+@media (min-width: 1024px) { .cv-only-narrow { display: none; } }
+
+.cv-menu { position: relative; }
+.cv-menu-panel {
+  position: absolute;
+  right: 0;
+  top: calc(100% + 0.25rem);
+  z-index: 20;
+  min-width: 12rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+  padding: 0.375rem;
+  border: 1px solid rgb(203 213 225);
+  border-radius: 0.5rem;
+  background: #fff;
+  box-shadow: 0 10px 15px -3px rgb(0 0 0 / 0.1);
+}
+.dark .cv-menu-panel { background: rgb(30 41 59); border-color: rgb(71 85 105); }
+.cv-menu-panel .cv-header-action { text-align: left; }
+
+/* Área de toque mínima do padrão de responsividade (44px). Só em tela estreita: no desktop o
+   cursor é preciso e botões de 44px viram blocos desproporcionais. */
+@media (max-width: 1023px) {
+  .cv-touch { min-width: 44px; min-height: 44px; }
+  .cv-back { min-width: 44px; min-height: 44px; }
+  .cv-menu-panel .cv-touch { min-height: 44px; }
+}
+
+/* Em tela estreita o painel do menu ancora na viewport, não no botão: ancorado ao botão ele
+   escapava pela borda quando o gatilho ficava perto da esquerda, e o texto era cortado. */
+@media (max-width: 1023px) {
+  .cv-menu-panel {
+    position: fixed;
+    right: 0.75rem;
+    left: auto;
+    top: auto;
+    max-width: calc(100vw - 1.5rem);
+  }
+}
+
+/**
+ * Scrollbar fina — paridade com `.scrollbar-thin` de
+ * financiamento-imobiliario-bot/apps/web/src/index.css.
+ *
+ * Prefixo `cv-` porque o host pode ter a própria `.scrollbar-thin` (plugin do Tailwind ou CSS
+ * próprio): colidir no nome faria o painel herdar regra alheia sem ninguém entender por quê.
+ *
+ * Usada onde a área rola dentro de um bloco de altura limitada, como o grid de "Suas Seleções":
+ * a barra padrão do sistema ocupa ~15px e, num card de 3 colunas, come uma coluna inteira.
+ */
+.cv-scrollbar-thin {
+  scrollbar-width: thin;
+  scrollbar-color: rgba(0, 0, 0, 0.15) transparent;
+}
+.cv-scrollbar-thin::-webkit-scrollbar { width: 4px; height: 4px; }
+.cv-scrollbar-thin::-webkit-scrollbar-track { background: transparent; }
+.cv-scrollbar-thin::-webkit-scrollbar-thumb { background: rgba(0, 0, 0, 0.15); border-radius: 2px; }
+.cv-scrollbar-thin::-webkit-scrollbar-thumb:hover { background: rgba(0, 0, 0, 0.3); }
+.dark .cv-scrollbar-thin { scrollbar-color: rgba(255, 255, 255, 0.15) transparent; }
+.dark .cv-scrollbar-thin::-webkit-scrollbar-thumb { background: rgba(255, 255, 255, 0.15); }
+.dark .cv-scrollbar-thin::-webkit-scrollbar-thumb:hover { background: rgba(255, 255, 255, 0.3); }
+
+/**
+ * Mãozinha no que é clicável.
+ *
+ * O Preflight do Tailwind v3 punha `cursor: pointer` em `button`; o v4 removeu, e sem regra
+ * explícita o botão herda o `cursor: default` do browser — os componentes deste pacote deixam de
+ * parecer clicáveis num host v4. São 91 botões aqui: carimbar a classe em cada um seria ruído que o
+ * próximo componente esqueceria de repetir.
+ *
+ * `:where()` zera a especificidade de propósito: a regra vence o UA stylesheet (autor sempre vence)
+ * mas perde de qualquer regra do host, então quem quiser outro cursor não precisa de `!important`.
+ */
+:where(button:not(:disabled), [role='button']:not(:disabled), summary) {
+  cursor: pointer;
+}

package/src/types.ts

@@ -20,9 +20,46 @@ export interface ConversationsFeatures {
   darkMode?: boolean
 }
 
+/**
+ * Recorte do bloco `interactive` da Meta que a UI precisa para desenhar o menu. Fica solto (e não
+ * espelhando o contrato inteiro) porque o que chega do banco é o payload cru já enviado ao
+ * WhatsApp: qualquer campo que a UI não conheça é ignorado, nunca causa erro de render.
+ */
+export interface InteractiveOption {
+  id: string
+  title: string
+  description?: string
+}
+
+export interface InteractiveSection {
+  title?: string
+  rows?: InteractiveOption[]
+}
+
+export interface InteractivePayload {
+  type?: 'button' | 'list' | string
+  header?: { text?: string }
+  body?: { text?: string }
+  footer?: { text?: string }
+  action?: {
+    /** Rótulo do botão que abre a lista — só existe em `type: 'list'`. */
+    button?: string
+    sections?: InteractiveSection[]
+    buttons?: { reply?: InteractiveOption }[]
+  }
+}
+
+/** Como o cliente respondeu a um menu: por botão ou por item de lista. */
+export type InteractiveSelection = {
+  readonly kind: 'button' | 'list'
+  readonly option: InteractiveOption
+}
+
 export interface MessagePayload {
   id: string
-  type: 'text' | 'image' | 'video' | 'audio' | 'document' | 'sticker' | 'template'
+  type: 'text' | 'image' | 'video' | 'audio' | 'document' | 'sticker' | 'template' | 'interactive'
+  /** Payload cru da mensagem. Em `type: 'interactive'`, carrega o menu que o cliente vê. */
+  payload?: InteractivePayload | null
   content?: string
   caption?: string
   mediaUrl?: string
@@ -39,6 +76,40 @@ export interface MessagePayload {
   readAt?: string
   agentName?: string | null
   templateName?: string
+  /**
+   * Veredito de moderação vindo do backend — a UI só exibe, nunca calcula. Dicionário no browser
+   * seria peso morto e daria veredito diferente por versão de cliente.
+   *
+   * `null`/ausente = não avaliado (moderação desligada, ou mensagem anterior ao recurso), que é
+   * diferente de avaliado e limpo.
+   */
+  moderation?: { isOffensive: boolean; terms: string[] } | null
+  /**
+   * Transcrição do áudio, vinda do backend — a UI só exibe, nunca transcreve. Rodar STT no browser
+   * exigiria baixar modelo por aba e daria resultado diferente por versão de cliente.
+   *
+   * `null`/ausente = não avaliado, que é diferente de `'done'` com texto vazio (áudio em silêncio,
+   * já processado). É essa distinção que decide se o balão oferece "transcrever" ou "sem fala
+   * detectada".
+   */
+  transcription?: MessageTranscription | null
   isFirstInGroup?: boolean
   isLastInGroup?: boolean
 }
+
+export type TranscriptionStatus = 'pending' | 'done' | 'failed' | 'unsupported'
+
+/**
+ * Quando transcrever, escolhido nas configurações da empresa. Espelha o
+ * `TranscriptionMode` de `@adatechnology/meta-whatsapp-contracts`; declarado aqui para o pacote de
+ * UI não obrigar quem só desenha telas a instalar os contratos do backend.
+ */
+export type TranscriptionMode = 'auto' | 'onDemand'
+
+export interface MessageTranscription {
+  status: TranscriptionStatus
+  text?: string | null
+  /** ISO 639-1 ou nome do idioma, conforme o engine. Exibido como dica, não interpretado. */
+  language?: string | null
+  engine?: string | null
+}

package/src/useDarkMode.ts

@@ -13,6 +13,32 @@ function getInitialDark(): boolean {
   return window.matchMedia('(prefers-color-scheme: dark)').matches
 }
 
+/**
+ * Leitura passiva do tema do host: observa a classe `dark` no `<html>` e não escreve nada.
+ *
+ * Existe porque `useDarkMode` é um controlador — ele grava a classe e persiste a preferência. Um
+ * componente que só precisa escolher cor não pode usá-lo: bastava renderizar o mapa de fluxos
+ * para o app inteiro do host trocar de tema, seguindo o `prefers-color-scheme` do sistema em vez
+ * da configuração da aplicação.
+ */
+export function useIsDarkTheme(): boolean {
+  const [isDark, setIsDark] = useState(
+    () => typeof document !== 'undefined' && document.documentElement.classList.contains('dark'),
+  )
+
+  useEffect(() => {
+    const root = document.documentElement
+    const observer = new MutationObserver(() => setIsDark(root.classList.contains('dark')))
+
+    observer.observe(root, { attributes: true, attributeFilter: ['class'] })
+    setIsDark(root.classList.contains('dark'))
+
+    return () => observer.disconnect()
+  }, [])
+
+  return isDark
+}
+
 export function useDarkMode(): { isDark: boolean; toggle: () => void } {
   const [isDark, setIsDark] = useState(getInitialDark)
 

package/src/useIsNarrow.ts

@@ -0,0 +1,29 @@
+/**
+ * Detecta tela estreita para decisões que CSS não resolve — como abrir ou não um painel por padrão.
+ *
+ * O breakpoint é o mesmo das classes `cv-only-*` e `.cv-back` (1024px). Duplicado aqui porque
+ * JavaScript não lê media query do stylesheet; se um dia divergirem, o sintoma é painel abrindo
+ * numa largura onde o resto da UI já mudou de modo.
+ */
+
+import { useEffect, useState } from 'react'
+
+export const NARROW_MAX_WIDTH_PX = 1023
+
+export function useIsNarrow(): boolean {
+  const [isNarrow, setIsNarrow] = useState(
+    () => typeof window !== 'undefined' && window.matchMedia(`(max-width: ${NARROW_MAX_WIDTH_PX}px)`).matches,
+  )
+
+  useEffect(() => {
+    const query = window.matchMedia(`(max-width: ${NARROW_MAX_WIDTH_PX}px)`)
+    const handleChange = (event: MediaQueryListEvent): void => setIsNarrow(event.matches)
+
+    query.addEventListener('change', handleChange)
+    setIsNarrow(query.matches)
+
+    return () => query.removeEventListener('change', handleChange)
+  }, [])
+
+  return isNarrow
+}