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

package/src/preview/previewStore.ts

@@ -0,0 +1,193 @@
+/**
+ * Estado em memória que alimenta o preview de atendimento humano. Mock de API e mock de SSE
+ * compartilham este store de propósito: se cada um tivesse dados próprios, um evento anunciaria
+ * mensagem nova e o refetch da lista devolveria o estado antigo — a inbox pareceria funcionar e
+ * estaria mentindo, que é exatamente o defeito que o preview deveria expor.
+ *
+ * Os nomes de canal e de evento espelham o servidor (`conv:<whatsappNumber>`, `global`,
+ * `message`/`message-status`/`mode-changed`/`data-changed`). Fidelidade de vocabulário é o que
+ * permite trocar mock por servidor real sem tocar na UI.
+ */
+
+import type { MessagePayload } from '../types'
+import type { ConversationSummary } from '../providers/types'
+
+export const GLOBAL_CHANNEL = 'global'
+
+export function conversationChannel(conversationId: string): string {
+  return `conv:${conversationId}`
+}
+
+export type PreviewEmission = {
+  readonly channel: string
+  readonly event: string
+  readonly payload: Record<string, unknown>
+}
+
+export type PreviewStoreListener = (emission: PreviewEmission) => void
+
+export type AppendMessageParams = {
+  readonly conversationId: string
+  readonly content: string
+  readonly direction: MessagePayload['direction']
+  readonly sender: MessagePayload['sender']
+}
+
+export type SetModeParams = {
+  readonly conversationId: string
+  readonly mode: ConversationSummary['mode']
+  readonly assignedUserId?: string | undefined
+}
+
+export type ListConversationsFilters = {
+  readonly waitingHuman?: boolean
+  readonly search?: string
+}
+
+export type PreviewStore = {
+  listConversations(filters?: ListConversationsFilters): ConversationSummary[]
+  listMessages(conversationId: string): MessagePayload[]
+  appendMessage(params: AppendMessageParams): MessagePayload
+  setMode(params: SetModeParams): void
+  requestHuman(conversationId: string): void
+  markRead(conversationId: string): void
+  subscribe(channel: string, listener: PreviewStoreListener): () => void
+}
+
+export type CreatePreviewStoreParams = {
+  readonly conversations: readonly ConversationSummary[]
+  readonly messages: Readonly<Record<string, readonly MessagePayload[]>>
+  // Injetável para o teste conseguir asserir timestamps sem depender do relógio.
+  readonly now?: () => Date
+}
+
+export function createPreviewStore(params: CreatePreviewStoreParams): PreviewStore {
+  const conversations = params.conversations.map((conversation) => ({ ...conversation }))
+  const messages = new Map<string, MessagePayload[]>(
+    Object.entries(params.messages).map(([conversationId, list]) => [conversationId, [...list]]),
+  )
+  const listeners = new Map<string, Set<PreviewStoreListener>>()
+  const now = params.now ?? ((): Date => new Date())
+
+  let messageSequence = 0
+
+  function emit(emission: PreviewEmission): void {
+    for (const listener of listeners.get(emission.channel) ?? []) listener(emission)
+  }
+
+  // Toda mutação avisa o canal global: é o sinal de "refaça a query" que mantém a lista coerente
+  // com o que o canal da conversa acabou de anunciar.
+  function emitDataChanged(): void {
+    emit({ channel: GLOBAL_CHANNEL, event: 'data-changed', payload: {} })
+  }
+
+  function findConversation(conversationId: string): ConversationSummary | undefined {
+    return conversations.find((conversation) => conversation.id === conversationId)
+  }
+
+  return {
+    listConversations(filters?: ListConversationsFilters): ConversationSummary[] {
+      return conversations
+        .filter((conversation) => (filters?.waitingHuman ? conversation.waitingHuman : true))
+        .filter((conversation) => {
+          const search = filters?.search?.toLowerCase()
+          if (!search) return true
+          return (
+            conversation.whatsappNumber.includes(search) ||
+            (conversation.clientName?.toLowerCase().includes(search) ?? false)
+          )
+        })
+        .map((conversation) => ({ ...conversation }))
+        .sort((left, right) => right.lastAt.localeCompare(left.lastAt))
+    },
+
+    listMessages(conversationId: string): MessagePayload[] {
+      return [...(messages.get(conversationId) ?? [])]
+    },
+
+    appendMessage(appendParams: AppendMessageParams): MessagePayload {
+      messageSequence += 1
+      const timestamp = now().toISOString()
+      const message: MessagePayload = {
+        id: `preview-${messageSequence}`,
+        type: 'text',
+        content: appendParams.content,
+        direction: appendParams.direction,
+        sender: appendParams.sender,
+        timestamp,
+        status: appendParams.direction === 'outbound' ? 'sent' : undefined,
+      }
+
+      const conversationMessages = messages.get(appendParams.conversationId) ?? []
+      messages.set(appendParams.conversationId, [...conversationMessages, message])
+
+      const conversation = findConversation(appendParams.conversationId)
+      if (conversation) {
+        conversation.lastContent = appendParams.content
+        conversation.lastDirection = appendParams.direction
+        conversation.lastAt = timestamp
+        if (appendParams.direction === 'inbound') {
+          conversation.lastInboundAt = timestamp
+          conversation.unread += 1
+        }
+      }
+
+      // O servidor emite APENAS `{ direction, sender }` neste evento — é ping de "refaça a
+      // query", não entrega de dados. Emitir a mensagem inteira aqui deixaria o mock mais
+      // generoso que a realidade, e uma UI que lesse `event.data.content` funcionaria no preview
+      // e quebraria em produção.
+      emit({
+        channel: conversationChannel(appendParams.conversationId),
+        event: 'message',
+        payload: { direction: message.direction, sender: message.sender },
+      })
+      emitDataChanged()
+
+      return message
+    },
+
+    setMode(modeParams: SetModeParams): void {
+      const conversation = findConversation(modeParams.conversationId)
+      if (!conversation) return
+
+      conversation.mode = modeParams.mode
+      conversation.assignedUserId = modeParams.assignedUserId ?? null
+      // Assumir a conversa é o que atende ao pedido de humano — deixar a flag acesa manteria a
+      // conversa na fila de espera para sempre.
+      if (modeParams.mode === 'human') conversation.waitingHuman = false
+
+      emit({
+        channel: conversationChannel(modeParams.conversationId),
+        event: 'mode-changed',
+        payload: { mode: conversation.mode, assignedUserId: conversation.assignedUserId },
+      })
+      emitDataChanged()
+    },
+
+    requestHuman(conversationId: string): void {
+      const conversation = findConversation(conversationId)
+      if (!conversation) return
+
+      conversation.waitingHuman = true
+      emitDataChanged()
+    },
+
+    markRead(conversationId: string): void {
+      const conversation = findConversation(conversationId)
+      if (!conversation) return
+
+      conversation.unread = 0
+      emitDataChanged()
+    },
+
+    subscribe(channel: string, listener: PreviewStoreListener): () => void {
+      const channelListeners = listeners.get(channel) ?? new Set<PreviewStoreListener>()
+      channelListeners.add(listener)
+      listeners.set(channel, channelListeners)
+
+      return () => {
+        channelListeners.delete(listener)
+      }
+    },
+  }
+}

package/src/preview/startPreviewScript.ts

@@ -0,0 +1,60 @@
+/**
+ * Roteiro que mantém o preview vivo: sem tráfego chegando, a inbox é uma tela estática e as
+ * transições que o atendente precisa testar (fila de espera enchendo, handoff, devolução ao bot)
+ * nunca acontecem.
+ *
+ * O roteiro é cíclico e determinístico — mesma ordem a cada execução. Aleatoriedade tornaria um
+ * defeito visto uma vez difícil de reencontrar.
+ */
+
+import type { PreviewStore } from './previewStore'
+
+export type PreviewScriptStep = (store: PreviewStore) => void
+
+export const DEFAULT_PREVIEW_SCRIPT: readonly PreviewScriptStep[] = [
+  (store) =>
+    store.appendMessage({
+      conversationId: '5511988887777',
+      content: 'pode trocar o óleo por azeite?',
+      direction: 'inbound',
+      sender: 'customer',
+    }),
+  (store) => store.requestHuman('5511988887777'),
+  (store) =>
+    store.appendMessage({
+      conversationId: '5511955554444',
+      content: 'e o troco?',
+      direction: 'inbound',
+      sender: 'customer',
+    }),
+  (store) => store.setMode({ conversationId: '5511977776666', mode: 'human', assignedUserId: 'agent-2' }),
+  (store) =>
+    store.appendMessage({
+      conversationId: '5511977776666',
+      content: 'Oi Diego, sou a Ana. Já vi seu pedido.',
+      direction: 'outbound',
+      sender: 'agent',
+    }),
+  (store) => store.setMode({ conversationId: '5511966665555', mode: 'bot' }),
+]
+
+export type StartPreviewScriptParams = {
+  readonly store: PreviewStore
+  readonly intervalMs?: number
+  readonly steps?: readonly PreviewScriptStep[]
+}
+
+const DEFAULT_INTERVAL_MS = 4000
+
+export function startPreviewScript(params: StartPreviewScriptParams): () => void {
+  const steps = params.steps ?? DEFAULT_PREVIEW_SCRIPT
+  const intervalMs = params.intervalMs ?? DEFAULT_INTERVAL_MS
+  let index = 0
+
+  const timer = setInterval(() => {
+    steps[index % steps.length]?.(params.store)
+    index += 1
+  }, intervalMs)
+
+  return () => clearInterval(timer)
+}

package/src/providers/types.ts

@@ -1,4 +1,5 @@
 import type { MessagePayload } from '../types'
+import type { ConversationChannel } from '../conversationChannel'
 
 export interface ConversationsApi {
   fetchMessages(conversationId: string, params?: { limit?: number; before?: string }): Promise<MessagePayload[]>
@@ -24,14 +25,47 @@ export interface ConversationsApi {
   getMediaProxyUrl(mediaId: string): Promise<{ mimeType: string; data: string }>
 }
 
+/**
+ * Superfície mínima de stream que o pacote consome — exatamente o que `useConversationRealtime`
+ * usa: assinar 'message', desassinar e fechar. Deliberadamente estrutural em vez de
+ * `EventSource`: sem servidor HTTP não existe `EventSource`, e é isso que impediria alimentar a
+ * inbox com dados mockados em desenvolvimento. Um `EventSource` nativo satisfaz este tipo, então
+ * quem já implementa `SSEProvider` continua válido sem mudança.
+ */
+export interface ConversationEventSource {
+  addEventListener(type: string, listener: (event: MessageEvent) => void): void
+  removeEventListener(type: string, listener: (event: MessageEvent) => void): void
+  close(): void
+}
+
+/**
+ * Eventos nomeados que o servidor realmente emite (`event: <nome>` no fio). O canal por conversa
+ * é `conv:<whatsappNumber>`; o global só emite `data-changed`, como sinal de "refaça a query".
+ * Tipar `addEventListener` como `string` em vez de `'message'` existe por isto: quem assina
+ * precisa alcançar `message-status` e `mode-changed`, não só `message`.
+ */
+export const CONVERSATION_STREAM_EVENTS = ['message', 'message-status', 'mode-changed'] as const
+export type ConversationStreamEvent = (typeof CONVERSATION_STREAM_EVENTS)[number]
+
+export const GLOBAL_STREAM_EVENTS = ['data-changed'] as const
+export type GlobalStreamEvent = (typeof GLOBAL_STREAM_EVENTS)[number]
+
 export interface SSEProvider {
-  connectConversationStream(conversationId: string): EventSource
-  connectGlobalStream(): EventSource
+  connectConversationStream(conversationId: string): ConversationEventSource
+  connectGlobalStream(): ConversationEventSource
 }
 
 export interface ConversationSummary {
   id: string
+  /**
+   * @deprecated Use `contactId` com `channel`. Mantido obrigatório para não quebrar quem já
+   * consome; some quando o segundo canal entrar em produção.
+   */
   whatsappNumber: string
+  /** Identificador neutro do contato. Ausente = usa `whatsappNumber`. */
+  contactId?: string
+  /** Ausente = `whatsapp`, o comportamento de antes desta mudança. */
+  channel?: ConversationChannel
   clientName?: string
   lastContent?: string
   lastDirection?: 'inbound' | 'outbound'

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,139 @@
   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);
+  }
+}

package/src/types.ts

@@ -39,6 +39,14 @@ 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
   isFirstInGroup?: boolean
   isLastInGroup?: boolean
 }

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
+}