@adatechnology/conversations-ui 0.1.1 → 0.2.1

package/src/quickReplies/quickReplyAttachments.ts

@@ -0,0 +1,328 @@
+import { QUICK_REPLY_ATTACHMENT_LIMIT } from './quickReply.types'
+import type { QueuedAttachment, QuickReply, StoredAttachmentSendResult } from './quickReply.types'
+
+/**
+ * Anexos de uma mensagem pronta escolhida no picker, prontos para entrar na fila como `stored`
+ * (QR-32). Vazio sem `hasAttachmentsCapability` — sem `sendStoredAttachments` no host, empurrar o
+ * item só encalharia na fila sem jeito de sair; a linha do picker já avisou disso antes do clique.
+ */
+export function queuedAttachmentsFromQuickReply(
+  quickReply: Pick<QuickReply, 'attachments'>,
+  hasAttachmentsCapability: boolean,
+): readonly QueuedAttachment[] {
+  if (!hasAttachmentsCapability || !quickReply.attachments?.length) return []
+  return quickReply.attachments.map(
+    (attachment): QueuedAttachment => ({
+      kind: 'stored',
+      uploadId: attachment.uploadId,
+      filename: attachment.filename,
+      mimeType: attachment.mimeType,
+      sizeBytes: attachment.sizeBytes,
+    }),
+  )
+}
+
+/**
+ * Chave estável do item na fila — `uploadId` para guardado, `localId` gerado para local. A
+ * identidade do `File` (nome+tamanho+data) não bastava: duas cópias do mesmo arquivo colidiam na
+ * mesma chave e removê-la de uma removia as duas.
+ */
+export function attachmentKey(item: QueuedAttachment): string {
+  return item.kind === 'stored' ? item.uploadId : item.localId
+}
+
+export type AttachmentSendStatus = 'waiting' | 'sending' | 'sent' | 'failed' | 'skipped'
+
+/** Espelha os tetos da API; o host sobrescreve quando o backend dele aceita outro tamanho. */
+export const DEFAULT_MAX_ATTACHMENT_SIZE_BYTES = {
+  document: 100 * 1024 * 1024,
+  image: 5 * 1024 * 1024,
+  audio: 16 * 1024 * 1024,
+  video: 16 * 1024 * 1024,
+} as const
+
+export type MaxAttachmentSizeBytes = {
+  readonly document: number
+  readonly image: number
+  readonly audio: number
+  readonly video: number
+}
+
+export type OutgoingItems = {
+  readonly text: string
+  readonly attachments: readonly QueuedAttachment[]
+}
+
+/**
+ * Texto primeiro, depois os guardados na ordem do cadastro, por último os locais: o cliente lê a
+ * explicação antes do arquivo, e o que o atendente anexou na hora é complemento do roteiro.
+ */
+export function orderOutgoingItems(text: string, queue: readonly QueuedAttachment[]): OutgoingItems {
+  const stored = queue.filter((item) => item.kind === 'stored')
+  const local = queue.filter((item) => item.kind === 'local')
+  return { text, attachments: [...stored, ...local] }
+}
+
+/** Tira da fila só o que foi enviado; falha e pulado ficam para o atendente tentar de novo. */
+export function applySendResults(
+  queue: readonly QueuedAttachment[],
+  results: readonly StoredAttachmentSendResult[],
+): readonly QueuedAttachment[] {
+  const sentUploadIds = new Set(results.filter((result) => result.status === 'sent').map((result) => result.uploadId))
+  return queue.filter((item) => item.kind === 'local' || !sentUploadIds.has(item.uploadId))
+}
+
+export function canAddAttachments(current: number, adding: number): boolean {
+  return current + adding <= QUICK_REPLY_ATTACHMENT_LIMIT
+}
+
+export function resolveMaxAttachmentSizeBytes(
+  mimeType: string,
+  limits: MaxAttachmentSizeBytes = DEFAULT_MAX_ATTACHMENT_SIZE_BYTES,
+): number {
+  if (mimeType.startsWith('image/')) return limits.image
+  if (mimeType.startsWith('audio/')) return limits.audio
+  if (mimeType.startsWith('video/')) return limits.video
+  return limits.document
+}
+
+export type IdempotencyKeyState = {
+  readonly key: string
+  /** Conjunto ORDENADO de `uploadId` desta tentativa — a chave só sobrevive enquanto for igual. */
+  readonly uploadIds: readonly string[]
+}
+
+/**
+ * Decide se a chave de idempotência de `previous` ainda serve (M3): serve quando o conjunto
+ * ORDENADO de `uploadIds` não mudou desde a tentativa anterior. Mudou — um anexo saiu, entrou, ou
+ * trocou de posição — vira uma tentativa diferente perante o backend, e precisa de chave nova; a
+ * mesma chave reenviaria o lote antigo como se fosse o novo (ou o servidor recusaria por conflito).
+ */
+export function resolveIdempotencyKey(
+  previous: IdempotencyKeyState | undefined,
+  uploadIds: readonly string[],
+  generateKey: () => string = () => crypto.randomUUID(),
+): IdempotencyKeyState {
+  if (previous && sameUploadIds(previous.uploadIds, uploadIds)) return previous
+  return { key: generateKey(), uploadIds }
+}
+
+function sameUploadIds(a: readonly string[], b: readonly string[]): boolean {
+  if (a.length !== b.length) return false
+  return a.every((id, index) => id === b[index])
+}
+
+/**
+ * Decide se a chave de idempotência pode ser descartada depois de um envio (M3-bug): todo
+ * `uploadId` da tentativa saiu com sucesso. `setState` com updater NÃO roda de forma síncrona
+ * dentro do handler — uma variável `let` atualizada por ele e lida logo em seguida sempre lê o
+ * valor antigo. Esta decisão usa só os parâmetros da própria tentativa (nunca o estado da fila),
+ * então não depende de nenhum `setState` ter aplicado.
+ */
+export function hasSentEveryStoredUpload(
+  storedUploadIds: readonly string[],
+  sentAttachmentKeys: readonly string[],
+): boolean {
+  if (storedUploadIds.length === 0) return true
+  const sentKeys = new Set(sentAttachmentKeys)
+  return storedUploadIds.every((uploadId) => sentKeys.has(uploadId))
+}
+
+export type ShouldResetRetryKeyParams = {
+  /** Valor corrente do ref no momento da checagem — lido depois do `await`. */
+  readonly current: IdempotencyKeyState | undefined
+  /** Estado usado NESTA tentativa, capturado antes do `await`. */
+  readonly attempted: IdempotencyKeyState
+  readonly sentAttachmentKeys: readonly string[]
+  readonly uploadId: string
+}
+
+/**
+ * Decide se a chave de idempotência do retry avulso pode ser descartada (M3-retry-bug): o item
+ * saiu com sucesso E ninguém trocou o ref por identidade desde então. A checagem de identidade
+ * (`current === attempted`) importa porque um retry avulso reusa `uploadId` de itens guardados
+ * (mensagens prontas) — um segundo retry do MESMO `uploadId` pode começar e sobrescrever o ref
+ * antes desta tentativa terminar; sem a checagem, o `undefined` desta tentativa apagaria a chave
+ * da tentativa mais nova, e o próximo envio dela reusaria uma chave já consumida pelo servidor.
+ */
+export function shouldResetRetryKey(params: ShouldResetRetryKeyParams): boolean {
+  const { current, attempted, sentAttachmentKeys, uploadId } = params
+  if (!sentAttachmentKeys.includes(uploadId)) return false
+  return current === attempted
+}
+
+export type SendQueuedMessageParams = {
+  readonly text: string
+  readonly queue: readonly QueuedAttachment[]
+  /** Uma por clique, reusada em cada tentativa de reenvio do que sobrou (QR-38). */
+  readonly idempotencyKey: string
+  /** Devolve se o texto saiu — falso interrompe o pipeline antes de qualquer anexo (QR-43). */
+  readonly sendText: (text: string) => Promise<boolean>
+  /** Ausente, itens `stored` continuam na fila — o produto não sabe mandar por referência. */
+  readonly sendStoredAttachments?: (params: {
+    uploadIds: readonly string[]
+    idempotencyKey: string
+  }) => Promise<{ results: readonly StoredAttachmentSendResult[] }>
+  /** Ausente, itens `local` continuam na fila — o mesmo comportamento de hoje sem a porta. */
+  readonly sendLocalAttachments?: (files: readonly File[]) => Promise<void>
+  readonly onAttachmentStatus?: (key: string, status: AttachmentSendStatus) => void
+}
+
+export type SendQueuedMessageResult = {
+  readonly textSent: boolean
+  /** O que não foi enviado — falha, pulado ou sem porta — para o atendente tentar de novo. */
+  readonly remainingQueue: readonly QueuedAttachment[]
+  /** Chaves (`attachmentKey`) dos itens que saíram — para o chamador remover por chave de um estado
+   * corrente, em vez de sobrescrever a fila com este `remainingQueue` (calculado sobre uma fila
+   * capturada antes do `await`, que já pode estar desatualizada). */
+  readonly sentAttachmentKeys: readonly string[]
+}
+
+type SendStoredAttachmentsPort = NonNullable<SendQueuedMessageParams['sendStoredAttachments']>
+type StoredQueuedAttachment = Extract<QueuedAttachment, { kind: 'stored' }>
+
+/** Traduz o status do resultado do servidor para o status visual do item na fila. */
+function attachmentSendStatusOf(status: StoredAttachmentSendResult['status']): AttachmentSendStatus {
+  if (status === 'sent') return 'sent'
+  if (status === 'skipped') return 'skipped'
+  return 'failed'
+}
+
+/**
+ * Manda um lote de itens `stored` e traduz a resposta em status por item — usado tanto pelo envio
+ * normal quanto pelo retry avulso (M5): guardado sem resultado no lote é tratado como falha, e o
+ * lote inteiro falhando (rede, 500) marca cada item como falha em vez de sumir da tela sem explicação.
+ * `skipped` (o servidor parou antes de tentar este arquivo, por causa de uma falha anterior no
+ * mesmo lote) fica distinto de `failed` — o item não falhou, só não chegou a ser tentado.
+ */
+async function sendStoredBatch(
+  stored: readonly StoredQueuedAttachment[],
+  idempotencyKey: string,
+  sendStoredAttachments: SendStoredAttachmentsPort,
+  onAttachmentStatus?: (key: string, status: AttachmentSendStatus) => void,
+): Promise<readonly StoredAttachmentSendResult[]> {
+  for (const item of stored) onAttachmentStatus?.(attachmentKey(item), 'sending')
+  try {
+    const response = await sendStoredAttachments({ uploadIds: stored.map((item) => item.uploadId), idempotencyKey })
+    let results = response.results
+    const resultedUploadIds = new Set(results.map((result) => result.uploadId))
+    for (const item of stored) {
+      if (!resultedUploadIds.has(item.uploadId)) results = [...results, { uploadId: item.uploadId, status: 'failed' }]
+    }
+    for (const result of results) {
+      onAttachmentStatus?.(result.uploadId, attachmentSendStatusOf(result.status))
+    }
+    return results
+  } catch {
+    for (const item of stored) onAttachmentStatus?.(attachmentKey(item), 'failed')
+    return stored.map((item) => ({ uploadId: item.uploadId, status: 'failed' as const }))
+  }
+}
+
+export type RetryStoredAttachmentsParams = {
+  readonly queue: readonly QueuedAttachment[]
+  /** Só este subconjunto é reenviado — o resto da fila (texto já mandado) fica intocado. */
+  readonly uploadIds: readonly string[]
+  readonly idempotencyKey: string
+  readonly sendStoredAttachments: SendStoredAttachmentsPort
+  readonly onAttachmentStatus?: (key: string, status: AttachmentSendStatus) => void
+}
+
+export type RetryStoredAttachmentsResult = {
+  readonly remainingQueue: readonly QueuedAttachment[]
+  /** Chaves (`uploadId`) dos itens que saíram — ver `SendQueuedMessageResult.sentAttachmentKeys`. */
+  readonly sentAttachmentKeys: readonly string[]
+}
+
+/**
+ * Reenvia só os `stored` de `uploadIds` — nunca o texto do rascunho (M3): o botão "Tentar de novo"
+ * de um item é sobre aquele anexo, não sobre a mensagem inteira que já foi lida ou já saiu.
+ */
+export async function retryStoredAttachments(
+  params: RetryStoredAttachmentsParams,
+): Promise<RetryStoredAttachmentsResult> {
+  const { queue, uploadIds, idempotencyKey, sendStoredAttachments, onAttachmentStatus } = params
+  const targetIds = new Set(uploadIds)
+  const targets = queue.filter(
+    (item): item is StoredQueuedAttachment => item.kind === 'stored' && targetIds.has(item.uploadId),
+  )
+  if (targets.length === 0) return { remainingQueue: queue, sentAttachmentKeys: [] }
+  const results = await sendStoredBatch(targets, idempotencyKey, sendStoredAttachments, onAttachmentStatus)
+  const sentAttachmentKeys = results.filter((result) => result.status === 'sent').map((result) => result.uploadId)
+  return { remainingQueue: applySendResults(queue, results), sentAttachmentKeys }
+}
+
+export type ResolveRetryOutcomeParams = {
+  readonly conversationIdAtRetry: string
+  readonly currentConversationId: string
+  readonly sentAttachmentKeys: readonly string[]
+  readonly queue: readonly QueuedAttachment[]
+}
+
+/**
+ * Decide o que gravar na fila depois de um retry avulso resolver (H2/M5): `undefined` quando a
+ * conversa trocou no meio do retry — o resultado é de outra thread e o chamador deve ignorá-lo,
+ * mantendo a fila corrente intocada. Na mesma conversa, tira só as chaves enviadas — nunca
+ * sobrescreve com uma fila capturada antes do `await`, que perderia item adicionado durante o envio.
+ */
+export function resolveRetryOutcome(params: ResolveRetryOutcomeParams): readonly QueuedAttachment[] | undefined {
+  const { conversationIdAtRetry, currentConversationId, sentAttachmentKeys, queue } = params
+  if (conversationIdAtRetry !== currentConversationId) return undefined
+  const sentKeys = new Set(sentAttachmentKeys)
+  return queue.filter((item) => !sentKeys.has(attachmentKey(item)))
+}
+
+/** Tira da fila de um envio completo os itens com retry avulso em voo (M-retry-race): a chave de
+ * idempotência do retry é outra, e mandar o mesmo item nos dois pipelines ao mesmo tempo deixa o
+ * servidor sem jeito de deduplicar. */
+export function excludeRetryingItems(
+  queue: readonly QueuedAttachment[],
+  retryingKeys: ReadonlySet<string>,
+): readonly QueuedAttachment[] {
+  if (retryingKeys.size === 0) return queue
+  return queue.filter((item) => !retryingKeys.has(attachmentKey(item)))
+}
+
+/**
+ * Orquestra QR-34/QR-37/QR-43: texto primeiro; se falhar, nada de anexo sai. Depois os `stored` (em
+ * lote, um resultado por arquivo) e por último os `local` (sem legenda — o texto já foi mandado).
+ * Pura para ser testável sem montar componente: os efeitos colaterais são só as três portas recebidas.
+ */
+export async function sendQueuedMessage(params: SendQueuedMessageParams): Promise<SendQueuedMessageResult> {
+  const { text, queue, idempotencyKey, sendText, sendStoredAttachments, sendLocalAttachments, onAttachmentStatus } =
+    params
+
+  if (text.trim()) {
+    const textSent = await sendText(text)
+    if (!textSent) return { textSent: false, remainingQueue: queue, sentAttachmentKeys: [] }
+  }
+
+  const { attachments } = orderOutgoingItems(text, queue)
+  const stored = attachments.filter((item): item is StoredQueuedAttachment => item.kind === 'stored')
+  const local = attachments.filter(
+    (item): item is Extract<QueuedAttachment, { kind: 'local' }> => item.kind === 'local',
+  )
+
+  const results =
+    stored.length > 0 && sendStoredAttachments
+      ? await sendStoredBatch(stored, idempotencyKey, sendStoredAttachments, onAttachmentStatus)
+      : []
+
+  let remainingQueue = applySendResults(queue, results)
+  const sentAttachmentKeys = results.filter((result) => result.status === 'sent').map((result) => result.uploadId)
+
+  if (local.length > 0 && sendLocalAttachments) {
+    for (const item of local) onAttachmentStatus?.(attachmentKey(item), 'sending')
+    try {
+      await sendLocalAttachments(local.map((item) => item.file))
+      for (const item of local) onAttachmentStatus?.(attachmentKey(item), 'sent')
+      const sentKeys = new Set(local.map((item) => attachmentKey(item)))
+      remainingQueue = remainingQueue.filter((item) => item.kind !== 'local' || !sentKeys.has(attachmentKey(item)))
+      sentAttachmentKeys.push(...sentKeys)
+    } catch {
+      for (const item of local) onAttachmentStatus?.(attachmentKey(item), 'failed')
+    }
+  }
+
+  return { textSent: true, remainingQueue, sentAttachmentKeys }
+}

package/src/quickReplies/quickReplySearch.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'bun:test'
+
+import { filterQuickReplies, highlightMatch, normalizeForSearch } from './quickReplySearch'
+import type { QuickReply } from './quickReply.types'
+
+const GREETING: QuickReply = { id: '1', title: 'Saudação', shortcut: 'ola', body: 'Olá {{nome}}, tudo bem?' }
+const DOCS: QuickReply = { id: '2', title: 'Pedido de documento', shortcut: 'doc', body: 'Envie seu RG e CPF.' }
+
+describe('normalizeForSearch', () => {
+  it('remove acento e ignora caixa', () => {
+    expect(normalizeForSearch('Saudação')).toBe('saudacao')
+    expect(normalizeForSearch('VOCÊ')).toBe('voce')
+  })
+})
+
+describe('filterQuickReplies', () => {
+  it('busca sem acento no título', () => {
+    const result = filterQuickReplies({ quickReplies: [GREETING, DOCS], search: 'saudacao' })
+    expect(result).toEqual([GREETING])
+  })
+
+  it('busca no atalho', () => {
+    const result = filterQuickReplies({ quickReplies: [GREETING, DOCS], search: 'doc' })
+    expect(result).toEqual([DOCS])
+  })
+
+  it('busca no corpo já com a variável trocada', () => {
+    const result = filterQuickReplies({ quickReplies: [GREETING], search: 'marina', variables: { nome: 'Marina' } })
+    expect(result).toEqual([GREETING])
+  })
+
+  it('termo vazio devolve tudo', () => {
+    expect(filterQuickReplies({ quickReplies: [GREETING, DOCS], search: '  ' })).toEqual([GREETING, DOCS])
+  })
+
+  it('sem correspondência devolve lista vazia', () => {
+    expect(filterQuickReplies({ quickReplies: [GREETING, DOCS], search: 'boleto' })).toEqual([])
+  })
+
+  it('termo só de marca combinante normaliza para vazio e não filtra nada', () => {
+    // "́" sozinho (acento agudo combinante, sem base) normaliza para string vazia.
+    expect(filterQuickReplies({ quickReplies: [GREETING, DOCS], search: '́' })).toEqual([GREETING, DOCS])
+  })
+})
+
+describe('highlightMatch', () => {
+  it('destaca o trecho encontrado preservando o texto original', () => {
+    const segments = highlightMatch('Pedido de documento', 'documento')
+    expect(segments).toEqual([
+      { text: 'Pedido de ', isMatch: false },
+      { text: 'documento', isMatch: true },
+    ])
+  })
+
+  it('casa mesmo com acento diferente entre busca e texto', () => {
+    const segments = highlightMatch('Saudação', 'saudacao')
+    expect(segments.some((segment) => segment.isMatch)).toBe(true)
+    expect(segments.map((segment) => segment.text).join('')).toBe('Saudação')
+  })
+
+  it('sem termo, devolve o texto inteiro sem destaque', () => {
+    expect(highlightMatch('Saudação', '')).toEqual([{ text: 'Saudação', isMatch: false }])
+  })
+
+  it('sem correspondência, devolve um único segmento sem destaque', () => {
+    expect(highlightMatch('Saudação', 'boleto')).toEqual([{ text: 'Saudação', isMatch: false }])
+  })
+
+  it('casa e recorta certo quando o texto vem em NFD (acento como combinante separado)', () => {
+    const nfdText = 'José'.normalize('NFD') // "José" com o acento como caractere combinante
+    const segments = highlightMatch(nfdText, 'jose')
+    expect(segments.map((segment) => segment.text).join('')).toBe(nfdText)
+    expect(segments.some((segment) => segment.isMatch)).toBe(true)
+  })
+
+  it('casa e recorta certo quando minúscula tem mais caracteres que a maiúscula (İ)', () => {
+    const text = 'İstanbul'
+    const segments = highlightMatch(text, 'istanbul')
+    expect(segments.map((segment) => segment.text).join('')).toBe(text)
+    expect(segments.some((segment) => segment.isMatch)).toBe(true)
+  })
+
+  it('termo só de marca combinante normaliza para vazio — não trava em loop e devolve o texto inteiro', () => {
+    // Sem o guard, `indexOf('')` sempre acha posição 0 e o cursor nunca avança: loop infinito.
+    const segments = highlightMatch('Saudação', '́')
+    expect(segments).toEqual([{ text: 'Saudação', isMatch: false }])
+  })
+})

package/src/quickReplies/quickReplySearch.ts

@@ -0,0 +1,104 @@
+import { applyQuickReplyVariables } from '../MessageComposer'
+import type { QuickReply } from './quickReply.types'
+
+const DIACRITIC_PATTERN = /[\u0300-\u036f]/g
+
+export type NormalizedIndexMap = {
+  readonly normalized: string
+  /** `normalized[i]` veio do caractere original que começa em `originalIndexOf[i]` (UTF-16). */
+  readonly originalIndexOf: readonly number[]
+}
+
+/**
+ * Normaliza caractere a caractere (não a string inteira) e guarda, para cada posição do resultado,
+ * de qual índice do texto original ela veio. Um caractere de entrada não produz sempre um único
+ * caractere de saída: `'İ'.toLowerCase()` vira dois (`'i̇'`), e um acento em NFD normaliza para uma
+ * base sem o combinante. Sem o mapa, `highlightMatch` recorta o texto original no índice errado
+ * assim que a entrada tem um desses casos — foi o que quebrava com "José" em NFD e com maiúscula
+ * que cresce ao virar minúscula.
+ */
+export function normalizeForSearchWithMap(value: string): NormalizedIndexMap {
+  let normalized = ''
+  const originalIndexOf: number[] = []
+  let originalCursor = 0
+  for (const char of value) {
+    const piece = char.normalize('NFD').replace(DIACRITIC_PATTERN, '').toLowerCase()
+    for (let i = 0; i < piece.length; i++) originalIndexOf.push(originalCursor)
+    normalized += piece
+    originalCursor += char.length
+  }
+  return { normalized, originalIndexOf }
+}
+
+export function normalizeForSearch(value: string): string {
+  return normalizeForSearchWithMap(value).normalized
+}
+
+export type FilterQuickRepliesParams = {
+  readonly quickReplies: readonly QuickReply[]
+  readonly search: string
+  /** Resolve `{{marcador}}` antes de comparar — buscar "joão" deve achar quem cita o nome no corpo. */
+  readonly variables?: Readonly<Record<string, string>>
+}
+
+/** Busca por título, atalho e corpo (com as variáveis já aplicadas). Termo vazio devolve tudo. */
+export function filterQuickReplies({
+  quickReplies,
+  search,
+  variables,
+}: FilterQuickRepliesParams): readonly QuickReply[] {
+  // Termo composto só de marcas combinantes (ex.: "́" sozinho) normaliza para string vazia —
+  // tratar como termo vazio, senão `indexOf('')` em `highlightMatch` casaria em todo índice.
+  const term = normalizeForSearch(search.trim())
+  if (!term) return quickReplies
+  return quickReplies.filter((quickReply) => {
+    const body = applyQuickReplyVariables(quickReply.body, variables)
+    return (
+      normalizeForSearch(quickReply.title).includes(term) ||
+      normalizeForSearch(quickReply.shortcut).includes(term) ||
+      normalizeForSearch(body).includes(term)
+    )
+  })
+}
+
+export type MatchSegment = {
+  readonly text: string
+  readonly isMatch: boolean
+}
+
+/**
+ * Segmenta o texto ao redor do termo buscado para o chamador destacar sem HTML — quem cadastrou a
+ * mensagem não deve conseguir injetar marcação pelo próprio corpo ou título.
+ */
+export function highlightMatch(text: string, search: string): readonly MatchSegment[] {
+  const term = search.trim()
+  if (!term) return [{ text, isMatch: false }]
+  const { normalized: normalizedText, originalIndexOf } = normalizeForSearchWithMap(text)
+  const normalizedTerm = normalizeForSearch(term)
+  // Termo só de marcas combinantes (ex.: "́") normaliza para "" — `indexOf('')` sempre acha
+  // posição 0 e o laço abaixo nunca avança o cursor, travando a aba num loop infinito.
+  if (!normalizedTerm) return [{ text, isMatch: false }]
+  // Índice original correspondente a uma posição do texto normalizado — o comprimento do texto
+  // original fecha o mapa para quando a posição cai depois do último caractere normalizado.
+  const originalIndexAt = (normalizedIndex: number): number =>
+    normalizedIndex < originalIndexOf.length ? originalIndexOf[normalizedIndex]! : text.length
+
+  const segments: MatchSegment[] = []
+  let normalizedCursor = 0
+  let originalCursor = 0
+  while (normalizedCursor < normalizedText.length) {
+    const matchIndex = normalizedText.indexOf(normalizedTerm, normalizedCursor)
+    if (matchIndex === -1) break
+    const matchOriginalStart = originalIndexAt(matchIndex)
+    if (matchOriginalStart > originalCursor) {
+      segments.push({ text: text.slice(originalCursor, matchOriginalStart), isMatch: false })
+    }
+    const matchNormalizedEnd = matchIndex + normalizedTerm.length
+    const matchOriginalEnd = originalIndexAt(matchNormalizedEnd)
+    segments.push({ text: text.slice(matchOriginalStart, matchOriginalEnd), isMatch: true })
+    normalizedCursor = matchNormalizedEnd
+    originalCursor = matchOriginalEnd
+  }
+  if (originalCursor < text.length) segments.push({ text: text.slice(originalCursor), isMatch: false })
+  return segments
+}

package/src/quickReplies/quickReplyShortcut.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'bun:test'
+
+import { detectQuickReplyShortcut, replaceQuickReplyShortcut } from './quickReplyShortcut'
+
+describe('detectQuickReplyShortcut', () => {
+  it('acha o atalho no início do texto', () => {
+    expect(detectQuickReplyShortcut('/doc')).toEqual({ start: 0, term: 'doc' })
+  })
+
+  it('acha o atalho depois de espaço', () => {
+    expect(detectQuickReplyShortcut('Olá, /doc')).toEqual({ start: 5, term: 'doc' })
+  })
+
+  it('acha o atalho vazio (só a barra, ainda sem termo)', () => {
+    expect(detectQuickReplyShortcut('/')).toEqual({ start: 0, term: '' })
+  })
+
+  it('apagar a barra some com o atalho', () => {
+    expect(detectQuickReplyShortcut('Olá, doc')).toBeUndefined()
+  })
+
+  it('barra no meio da palavra não é atalho', () => {
+    expect(detectQuickReplyShortcut('km/h')).toBeUndefined()
+  })
+})
+
+describe('replaceQuickReplyShortcut', () => {
+  it('troca o atalho pelo corpo resolvido e devolve onde o cursor cai', () => {
+    const result = replaceQuickReplyShortcut({
+      text: 'Olá, /doc',
+      start: 5,
+      caret: 9,
+      replacement: 'Envie seu RG, Marina.',
+    })
+    expect(result.text).toBe('Olá, Envie seu RG, Marina.')
+    expect(result.caret).toBe(5 + 'Envie seu RG, Marina.'.length)
+  })
+})

package/src/quickReplies/quickReplyShortcut.ts

@@ -0,0 +1,46 @@
+/**
+ * Detecção e inserção do atalho `/termo` — compartilhado entre `MessageComposer` e
+ * `RichMessageComposer` para os dois campos abrirem e fecharem o picker do mesmo jeito.
+ */
+
+/** Casa `/termo` no início do texto ou depois de espaço, sempre no fim da string. */
+const QUICK_REPLY_SHORTCUT_PATTERN = /(?:^|\s)\/([a-z0-9-]*)$/i
+
+export type QuickReplyShortcutMatch = {
+  /** Índice do primeiro caractere da "/", para a inserção saber onde trocar. */
+  readonly start: number
+  readonly term: string
+}
+
+/** Sem correspondência (ou depois de apagar a "/"), devolve `undefined` — é o que fecha o picker. */
+export function detectQuickReplyShortcut(text: string): QuickReplyShortcutMatch | undefined {
+  const match = QUICK_REPLY_SHORTCUT_PATTERN.exec(text)
+  if (!match) return undefined
+  return { start: match.index + (match[0].startsWith('/') ? 0 : 1), term: match[1] ?? '' }
+}
+
+export type ReplaceQuickReplyShortcutParams = {
+  readonly text: string
+  readonly start: number
+  readonly caret: number
+  readonly replacement: string
+}
+
+export type ReplaceQuickReplyShortcutResult = {
+  readonly text: string
+  /** Onde o cursor deve ficar depois — logo após o texto inserido. */
+  readonly caret: number
+}
+
+/** Troca o `/termo` (de `start` até `caret`) pelo corpo já resolvido. */
+export function replaceQuickReplyShortcut({
+  text,
+  start,
+  caret,
+  replacement,
+}: ReplaceQuickReplyShortcutParams): ReplaceQuickReplyShortcutResult {
+  return {
+    text: text.slice(0, start) + replacement + text.slice(caret),
+    caret: start + replacement.length,
+  }
+}

package/src/quickReplies/resolveConversationVariables.test.ts

@@ -0,0 +1,63 @@
+/**
+ * Guarda o adaptador entre a lista nova de variáveis e as duas props antigas. O caso que decide o
+ * desenho: com a lista nova presente, as antigas são ignoradas — duas fontes dariam valores
+ * diferentes no chip e no botão de variáveis.
+ */
+
+import { describe, expect, it } from 'bun:test'
+
+import { applyQuickReplyVariables } from '../MessageComposer'
+import { resolveConversationVariables } from './resolveConversationVariables'
+
+const CUSTOMER_NAME = { id: 'customerName', label: 'Nome', marker: '{{nome}}', value: 'Marina' }
+const EMPTY_EMAIL = { id: 'email', label: 'E-mail', marker: '{{email}}', value: '' }
+
+describe('resolveConversationVariables', () => {
+  it('deriva o mapa e a lista do composer a partir da lista nova', () => {
+    const result = resolveConversationVariables({ conversationVariables: [CUSTOMER_NAME] })
+    expect(result.quickReplyVariables).toEqual({ nome: 'Marina' })
+    expect(result.composerVariables).toEqual([{ id: 'customerName', label: 'Nome', value: 'Marina' }])
+  })
+
+  it('não oferece variável sem valor', () => {
+    const result = resolveConversationVariables({ conversationVariables: [CUSTOMER_NAME, EMPTY_EMAIL] })
+    expect(result.quickReplyVariables).toEqual({ nome: 'Marina' })
+    expect(result.composerVariables).toHaveLength(1)
+  })
+
+  it('a lista nova manda sobre as props antigas', () => {
+    const result = resolveConversationVariables({
+      conversationVariables: [CUSTOMER_NAME],
+      quickReplyVariables: { nome: 'Outro' },
+      composerVariables: [{ id: 'x', label: 'X', value: 'y' }],
+    })
+    expect(result.quickReplyVariables).toEqual({ nome: 'Marina' })
+    expect(result.composerVariables).toEqual([{ id: 'customerName', label: 'Nome', value: 'Marina' }])
+  })
+
+  it('sem a lista nova, devolve as props antigas intactas', () => {
+    const quickReplyVariables = { nome: 'Marina' }
+    const composerVariables = [{ id: 'x', label: 'X', value: 'y' }]
+    const result = resolveConversationVariables({ quickReplyVariables, composerVariables })
+    expect(result.quickReplyVariables).toBe(quickReplyVariables)
+    expect(result.composerVariables).toBe(composerVariables)
+  })
+
+  it('sem nada, devolve ausência', () => {
+    expect(resolveConversationVariables({})).toEqual({ quickReplyVariables: undefined, composerVariables: undefined })
+  })
+
+  it('marcador fora do formato cai no id', () => {
+    const result = resolveConversationVariables({
+      conversationVariables: [{ ...CUSTOMER_NAME, marker: 'nome' }],
+    })
+    expect(result.quickReplyVariables).toEqual({ customerName: 'Marina' })
+  })
+
+  it('o mapa derivado alimenta applyQuickReplyVariables sem mudança', () => {
+    const { quickReplyVariables } = resolveConversationVariables({
+      conversationVariables: [CUSTOMER_NAME, EMPTY_EMAIL],
+    })
+    expect(applyQuickReplyVariables('Olá {{nome}}, {{email}}', quickReplyVariables)).toBe('Olá Marina, ')
+  })
+})