@adatechnology/conversations-ui 0.1.0 → 0.2.0

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, ')
+  })
+})

package/src/quickReplies/resolveConversationVariables.ts

@@ -0,0 +1,41 @@
+import type { RichComposerVariable } from '../RichMessageComposer'
+import type { ConversationVariable } from './quickReply.types'
+
+export type ResolveConversationVariablesParams = {
+  readonly conversationVariables?: readonly ConversationVariable[] | undefined
+  /** @deprecated Use `conversationVariables`. */
+  readonly quickReplyVariables?: Readonly<Record<string, string>> | undefined
+  /** @deprecated Use `conversationVariables`. */
+  readonly composerVariables?: readonly RichComposerVariable[] | undefined
+}
+
+export type ResolveConversationVariablesResult = {
+  readonly quickReplyVariables: Readonly<Record<string, string>> | undefined
+  readonly composerVariables: readonly RichComposerVariable[] | undefined
+}
+
+const MARKER_PATTERN = /^\{\{\s*([\w.]+)\s*\}\}$/
+
+/** Nome que `applyQuickReplyVariables` casa; marcador fora do formato cai no `id`. */
+function variableNameOf(variable: ConversationVariable): string {
+  return MARKER_PATTERN.exec(variable.marker)?.[1] ?? variable.id
+}
+
+/**
+ * Deriva os dois formatos antigos da lista nova. Quando a lista vem, ela manda — misturar as fontes
+ * faria o chip e o botão de variáveis mostrarem valores diferentes. Sem ela, as props antigas seguem
+ * valendo para os produtos que ainda não migraram.
+ */
+export function resolveConversationVariables({
+  conversationVariables,
+  quickReplyVariables,
+  composerVariables,
+}: ResolveConversationVariablesParams): ResolveConversationVariablesResult {
+  if (!conversationVariables) return { quickReplyVariables, composerVariables }
+  // Valor vazio não é oferecido: inserir o nada no texto só esconde que o dado falta.
+  const known = conversationVariables.filter((variable) => variable.value !== '')
+  return {
+    quickReplyVariables: Object.fromEntries(known.map((variable) => [variableNameOf(variable), variable.value])),
+    composerVariables: known.map(({ id, label, value }) => ({ id, label, value })),
+  }
+}

package/src/quickReplies/useQuickRepliesPicker.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'bun:test'
+
+import { nextHighlightedIndex } from './useQuickRepliesPicker'
+
+describe('nextHighlightedIndex', () => {
+  it('avança e roda para o começo no fim da lista (ArrowDown)', () => {
+    expect(nextHighlightedIndex(0, 3, 1)).toBe(1)
+    expect(nextHighlightedIndex(2, 3, 1)).toBe(0)
+  })
+
+  it('volta e roda para o fim no começo da lista (ArrowUp)', () => {
+    expect(nextHighlightedIndex(1, 3, -1)).toBe(0)
+    expect(nextHighlightedIndex(0, 3, -1)).toBe(2)
+  })
+
+  it('lista vazia sempre fica em zero', () => {
+    expect(nextHighlightedIndex(0, 0, 1)).toBe(0)
+    expect(nextHighlightedIndex(0, 0, -1)).toBe(0)
+  })
+})

package/src/quickReplies/useQuickRepliesPicker.ts

@@ -0,0 +1,121 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { filterQuickReplies } from './quickReplySearch'
+import type { QuickReply } from './quickReply.types'
+
+export type UseQuickRepliesPickerParams = {
+  readonly isOpen: boolean
+  readonly search: string
+  readonly listQuickReplies?: (params?: { search?: string }) => Promise<QuickReply[]>
+  readonly quickReplyVariables?: Readonly<Record<string, string>>
+  readonly onSelect: (quickReply: QuickReply) => void
+  readonly onClose: () => void
+}
+
+/** Extraída para ser testável sem montar o hook: a aritmética do círculo é o que a tecla decide. */
+export function nextHighlightedIndex(current: number, length: number, delta: 1 | -1): number {
+  if (length === 0) return 0
+  return (current + delta + length) % length
+}
+
+export type UseQuickRepliesPickerResult = {
+  readonly items: readonly QuickReply[]
+  readonly isLoading: boolean
+  /** Sinalizador puro — a mensagem exibida é sempre a do rótulo do host, nunca `caught.message` cru. */
+  readonly hasError: boolean
+  readonly highlightedIndex: number
+  readonly setHighlightedIndex: (index: number) => void
+  readonly handleKeyDown: (event: { key: string; preventDefault: () => void }) => void
+  /** Refaz a busca ignorando o cache — usado quando o host quer forçar atualização da lista. */
+  readonly refetch: () => void
+}
+
+/**
+ * Estado do picker do atalho `/` e do botão de raio. A lista é da instalação inteira, não por
+ * conversa — carregada uma vez por instância do hook (`cacheRef`, sobrevive a fechar/abrir o
+ * picker) e nunca reconsultada só porque a conversa mudou. `requestIdRef` descarta resposta de
+ * pedido antigo: trocar de conversa ou reabrir rápido não pode deixar `isLoading` preso em `true`
+ * nem aplicar um resultado que não é mais o mais recente.
+ */
+export function useQuickRepliesPicker({
+  isOpen,
+  search,
+  listQuickReplies,
+  quickReplyVariables,
+  onSelect,
+  onClose,
+}: UseQuickRepliesPickerParams): UseQuickRepliesPickerResult {
+  const cacheRef = useRef<QuickReply[] | undefined>(undefined)
+  const requestIdRef = useRef(0)
+  const [items, setItems] = useState<QuickReply[]>([])
+  const [isLoading, setIsLoading] = useState(false)
+  const [hasError, setHasError] = useState(false)
+  const [highlightedIndex, setHighlightedIndex] = useState(0)
+
+  const load = useCallback(() => {
+    if (!listQuickReplies) return
+    const requestId = ++requestIdRef.current
+    setIsLoading(true)
+    setHasError(false)
+    listQuickReplies()
+      .then((result) => {
+        if (requestIdRef.current !== requestId) return
+        cacheRef.current = result
+        setItems(result)
+        setIsLoading(false)
+      })
+      .catch(() => {
+        if (requestIdRef.current !== requestId) return
+        setHasError(true)
+        setIsLoading(false)
+      })
+  }, [listQuickReplies])
+
+  useEffect(() => {
+    if (!isOpen || !listQuickReplies) return
+    if (cacheRef.current) {
+      setItems(cacheRef.current)
+      return
+    }
+    load()
+  }, [isOpen, listQuickReplies, load])
+
+  const refetch = useCallback(() => {
+    cacheRef.current = undefined
+    load()
+  }, [load])
+
+  const filtered = filterQuickReplies({ quickReplies: items, search, variables: quickReplyVariables })
+
+  useEffect(() => {
+    setHighlightedIndex(0)
+  }, [search, filtered.length])
+
+  const handleKeyDown = useCallback(
+    (event: { key: string; preventDefault: () => void }) => {
+      if (event.key === 'ArrowDown') {
+        event.preventDefault()
+        setHighlightedIndex((index) => nextHighlightedIndex(index, filtered.length, 1))
+        return
+      }
+      if (event.key === 'ArrowUp') {
+        event.preventDefault()
+        setHighlightedIndex((index) => nextHighlightedIndex(index, filtered.length, -1))
+        return
+      }
+      if (event.key === 'Enter') {
+        const selected = filtered[highlightedIndex]
+        if (!selected) return
+        event.preventDefault()
+        onSelect(selected)
+        return
+      }
+      if (event.key === 'Escape') {
+        event.preventDefault()
+        onClose()
+      }
+    },
+    [filtered, highlightedIndex, onSelect, onClose],
+  )
+
+  return { items: filtered, isLoading, hasError, highlightedIndex, setHighlightedIndex, handleKeyDown, refetch }
+}