@adatechnology/conversations-ui 0.1.1 → 0.2.1

package/src/quickReplies/useQuickRepliesWorkspace.ts

@@ -0,0 +1,426 @@
+import { useCallback, useEffect, useState } from 'react'
+import { filterQuickReplies } from './quickReplySearch'
+import { moveAttachment } from './quickReplyAttachmentUpload'
+import { useQuickReplyAttachmentUploads } from './useQuickReplyAttachmentUploads'
+import type { PendingAttachmentUpload } from './useQuickReplyAttachmentUploads'
+import type { AttachmentFileRejection } from './quickReplyAttachmentUpload'
+import type { MaxAttachmentSizeBytes } from './quickReplyAttachments'
+import type { QuickReply, QuickReplyAttachment, QuickReplyInput } from './quickReply.types'
+import type { QuickRepliesWorkspaceLabels } from './labels'
+
+export type { PendingAttachmentUpload } from './useQuickReplyAttachmentUploads'
+
+/**
+ * Portas que a tela de cadastro precisa. `create`/`update`/`delete` ausentes não impedem a leitura
+ * — só tiram a ação correspondente, a mesma regra de capacidade do resto do pacote.
+ */
+export interface QuickRepliesWorkspaceApi {
+  readonly listQuickReplies?: (params?: { search?: string }) => Promise<QuickReply[]>
+  readonly createQuickReply?: (input: QuickReplyInput) => Promise<QuickReply>
+  readonly updateQuickReply?: (id: string, input: QuickReplyInput) => Promise<QuickReply>
+  readonly deleteQuickReply?: (id: string) => Promise<void>
+  /** Sem esta porta, a seção de anexos não aparece — nem no formulário. */
+  readonly uploadQuickReplyAttachment?: (
+    file: File,
+    options?: { onProgress?: (fraction: number) => void; signal?: AbortSignal },
+  ) => Promise<QuickReplyAttachment>
+}
+
+export type QuickReplyFormField = 'title' | 'shortcut' | 'body'
+export type QuickRepliesWorkspaceFieldErrors = Partial<Record<QuickReplyFormField, string>>
+
+export type QuickRepliesWorkspaceEditing = {
+  /** `null` é a criação; presente é edição do registro com este id. */
+  readonly id: string | null
+  readonly title: string
+  readonly shortcut: string
+  readonly body: string
+  /** Já subidos — a ordem daqui é a ordem de envio salva (QR-30). */
+  readonly attachments: readonly QuickReplyAttachment[]
+}
+
+const TITLE_MAX_LENGTH = 40
+const BODY_MAX_LENGTH = 1000
+const SHORTCUT_PATTERN = /^[a-z0-9-]{1,20}$/
+
+/** Casca genérica de erro de API com `code` e `details[]` (`apis.md`) — sem acoplar a um cliente HTTP específico. */
+type ApiErrorShape = { readonly code?: unknown; readonly details?: unknown }
+
+/**
+ * Desembrulha a casca `{ code, details }` de onde quer que o cliente HTTP do host a tenha
+ * pendurado. `apis.md` define o envelope `{ error: { code, message, details } }`, mas cada cliente
+ * (fetch cru, axios, o `Error` que o `ConversationsProvider` relança) expõe o objeto lançado de um
+ * jeito diferente — `error.error`, `error.response.data.error` (axios) ou `error.body.error`
+ * (alguns wrappers de fetch). Sem isto, a rejeição real do servidor nunca chega ao formulário e o
+ * operador só vê "não foi possível salvar", mesmo quando a API já mandou o campo certo.
+ */
+const MAX_ERROR_ENVELOPE_DEPTH = 3
+
+/**
+ * Desce no máximo `MAX_ERROR_ENVELOPE_DEPTH` níveis: um erro que se referencia (`error.error ===
+ * error`, comum em `Error` customizado com `cause` circular) faria a recursão nunca terminar.
+ */
+function apiErrorEnvelopeOf(error: unknown, depth = 0): ApiErrorShape | undefined {
+  if (depth >= MAX_ERROR_ENVELOPE_DEPTH) return undefined
+  if (!error || typeof error !== 'object') return undefined
+  const candidate = error as Record<string, unknown>
+  if ('code' in candidate || 'details' in candidate) return candidate as ApiErrorShape
+  const nested =
+    (candidate.error as unknown) ??
+    (candidate.response as Record<string, unknown> | undefined)?.data ??
+    (candidate.body as unknown)
+  if (nested && typeof nested === 'object') return apiErrorEnvelopeOf(nested, depth + 1)
+  return undefined
+}
+
+function fieldErrorsOf(error: unknown): QuickRepliesWorkspaceFieldErrors {
+  const envelope = apiErrorEnvelopeOf(error)
+  if (!envelope) return {}
+  const details = envelope.details
+  if (!Array.isArray(details)) return {}
+  const result: QuickRepliesWorkspaceFieldErrors = {}
+  for (const detail of details) {
+    if (!detail || typeof detail !== 'object') continue
+    const field = (detail as { field?: unknown }).field
+    const message = (detail as { message?: unknown }).message
+    if (typeof field === 'string' && typeof message === 'string' && isFormField(field)) {
+      result[field] = message
+    }
+  }
+  return result
+}
+
+function isFormField(value: string): value is QuickReplyFormField {
+  return value === 'title' || value === 'shortcut' || value === 'body'
+}
+
+function errorCodeOf(error: unknown): string | undefined {
+  const code = apiErrorEnvelopeOf(error)?.code
+  return typeof code === 'string' ? code : undefined
+}
+
+/** Regras de formato — as mesmas do backend (`QR-08`), verificadas antes de gastar uma chamada. */
+export function validateQuickReplyInput(
+  input: QuickReplyInput,
+  labels: QuickRepliesWorkspaceLabels,
+): QuickRepliesWorkspaceFieldErrors {
+  const errors: QuickRepliesWorkspaceFieldErrors = {}
+  if (!input.title.trim() || input.title.length > TITLE_MAX_LENGTH) errors.title = labels.fieldTitleInvalid
+  if (!SHORTCUT_PATTERN.test(input.shortcut)) errors.shortcut = labels.fieldShortcutInvalid
+  if (!input.body.trim() || input.body.length > BODY_MAX_LENGTH) errors.body = labels.fieldBodyInvalid
+  return errors
+}
+
+export type SubmitQuickReplyParams = {
+  readonly api: QuickRepliesWorkspaceApi
+  readonly editing: QuickRepliesWorkspaceEditing
+  readonly labels: QuickRepliesWorkspaceLabels
+}
+
+export type SubmitQuickReplyResult =
+  | { readonly outcome: 'saved'; readonly quickReply: QuickReply }
+  | { readonly outcome: 'invalid'; readonly fieldErrors: QuickRepliesWorkspaceFieldErrors }
+  | {
+      readonly outcome: 'rejected'
+      readonly fieldErrors: QuickRepliesWorkspaceFieldErrors
+      readonly formError?: string
+    }
+
+/**
+ * Toda a lógica de salvar num único lugar testável sem montar o hook: valida, chama a porta certa
+ * (criar ou atualizar) e traduz a rejeição — 409 com `code: 'QUICK_REPLY_SHORTCUT_TAKEN'` ou
+ * `error.details[]` — no campo que errou.
+ */
+export async function submitQuickReply({
+  api,
+  editing,
+  labels,
+}: SubmitQuickReplyParams): Promise<SubmitQuickReplyResult> {
+  const input: QuickReplyInput = {
+    title: editing.title.trim(),
+    shortcut: editing.shortcut.trim(),
+    body: editing.body,
+    // Só manda a lista quando o host oferece a porta de upload — ausente, `attachmentUploadIds`
+    // some do payload e o backend não mexe nos anexos já gravados (contrato do tipo).
+    ...(api.uploadQuickReplyAttachment
+      ? { attachmentUploadIds: editing.attachments.map((attachment) => attachment.uploadId) }
+      : {}),
+  }
+  const validationErrors = validateQuickReplyInput(input, labels)
+  if (Object.keys(validationErrors).length > 0) return { outcome: 'invalid', fieldErrors: validationErrors }
+
+  const editingId = editing.id
+  if (editingId === null && !api.createQuickReply) {
+    return { outcome: 'rejected', fieldErrors: {}, formError: labels.saveUnavailable }
+  }
+  if (editingId !== null && !api.updateQuickReply) {
+    return { outcome: 'rejected', fieldErrors: {}, formError: labels.saveUnavailable }
+  }
+  const save =
+    editingId === null
+      ? (api.createQuickReply as NonNullable<QuickRepliesWorkspaceApi['createQuickReply']>)
+      : (input: QuickReplyInput) =>
+          (api.updateQuickReply as NonNullable<QuickRepliesWorkspaceApi['updateQuickReply']>)(editingId, input)
+
+  try {
+    const quickReply = await save(input)
+    if (!quickReply) return { outcome: 'invalid', fieldErrors: {} }
+    return { outcome: 'saved', quickReply }
+  } catch (caught: unknown) {
+    const detailErrors = fieldErrorsOf(caught)
+    const code = errorCodeOf(caught)
+    const shortcutMessage =
+      detailErrors.shortcut ?? (code === 'QUICK_REPLY_SHORTCUT_TAKEN' ? labels.shortcutTaken : undefined)
+    if (shortcutMessage || Object.keys(detailErrors).length > 0) {
+      return {
+        outcome: 'rejected',
+        fieldErrors: { ...detailErrors, ...(shortcutMessage ? { shortcut: shortcutMessage } : {}) },
+      }
+    }
+    // Nunca `caught.message` cru: é texto de exceção interna (rede, parsing), não algo que o
+    // operador deva ler — a mensagem exibida é sempre o rótulo do host (QR-10).
+    return {
+      outcome: 'rejected',
+      fieldErrors: {},
+      formError: labels.saveError,
+    }
+  }
+}
+
+export type InsertAtCursorResult = {
+  readonly text: string
+  readonly caret: number
+}
+
+/** Insere `marker` na posição do cursor (ou troca a seleção) — usado pelo botão "Inserir variável". */
+export function insertAtCursor(text: string, start: number, end: number, marker: string): InsertAtCursorResult {
+  return { text: text.slice(0, start) + marker + text.slice(end), caret: start + marker.length }
+}
+
+export type UseQuickRepliesWorkspaceParams = {
+  readonly api: QuickRepliesWorkspaceApi
+  readonly labels: QuickRepliesWorkspaceLabels
+  /** Sobrescreve o teto por tipo de arquivo. Ausente, usa `DEFAULT_MAX_ATTACHMENT_SIZE_BYTES`. */
+  readonly attachmentSizeLimits?: MaxAttachmentSizeBytes
+}
+
+export type UseQuickRepliesWorkspaceResult = {
+  readonly quickReplies: readonly QuickReply[]
+  readonly filtered: readonly QuickReply[]
+  readonly isLoading: boolean
+  readonly loadError: string | undefined
+  readonly search: string
+  readonly setSearch: (value: string) => void
+  /** Sem `createQuickReply`, a tela só mostra a tabela — nada de criar, editar ou excluir. */
+  readonly readOnly: boolean
+  readonly canEdit: boolean
+  readonly canDelete: boolean
+  readonly editing: QuickRepliesWorkspaceEditing | undefined
+  readonly startCreate: () => void
+  readonly startEdit: (quickReply: QuickReply) => void
+  readonly cancelEdit: () => void
+  readonly updateField: (field: QuickReplyFormField, value: string) => void
+  readonly fieldErrors: QuickRepliesWorkspaceFieldErrors
+  readonly isSaving: boolean
+  readonly saveError: string | undefined
+  readonly submit: () => Promise<void>
+  readonly remove: (id: string) => Promise<void>
+  /** Excluindo agora — para o botão da linha mostrar o spinner certo (QR-47). */
+  readonly deletingId: string | undefined
+  /** Sem `uploadQuickReplyAttachment`, a seção de anexos não aparece no formulário (QR-31). */
+  readonly hasAttachmentsCapability: boolean
+  readonly pendingUploads: readonly PendingAttachmentUpload[]
+  readonly addAttachmentFiles: (files: FileList | readonly File[]) => void
+  readonly retryAttachmentUpload: (localId: string) => void
+  readonly cancelAttachmentUpload: (localId: string) => void
+  readonly removeAttachment: (uploadId: string) => void
+  readonly moveAttachmentAt: (index: number, direction: -1 | 1) => void
+  readonly attachmentRejections: readonly AttachmentFileRejection[]
+  readonly dismissAttachmentRejections: () => void
+}
+
+/** Estado da tela de cadastro: lista, busca, formulário de criação/edição, anexos e exclusão. */
+export function useQuickRepliesWorkspace({
+  api,
+  labels,
+  attachmentSizeLimits,
+}: UseQuickRepliesWorkspaceParams): UseQuickRepliesWorkspaceResult {
+  const [quickReplies, setQuickReplies] = useState<QuickReply[]>([])
+  const [isLoading, setIsLoading] = useState(false)
+  const [loadError, setLoadError] = useState<string | undefined>(undefined)
+  const [search, setSearch] = useState('')
+  const [editing, setEditing] = useState<QuickRepliesWorkspaceEditing | undefined>(undefined)
+  const [fieldErrors, setFieldErrors] = useState<QuickRepliesWorkspaceFieldErrors>({})
+  const [isSaving, setIsSaving] = useState(false)
+  const [saveError, setSaveError] = useState<string | undefined>(undefined)
+  const [deletingId, setDeletingId] = useState<string | undefined>(undefined)
+
+  const uploadAttachment = useCallback((attachment: QuickReplyAttachment): void => {
+    setEditing((current) => (current ? { ...current, attachments: [...current.attachments, attachment] } : current))
+  }, [])
+
+  const {
+    pendingUploads,
+    attachmentRejections,
+    addAttachmentFiles,
+    retryAttachmentUpload,
+    cancelAttachmentUpload,
+    dismissAttachmentRejections,
+    abortAllUploads,
+  } = useQuickReplyAttachmentUploads({
+    ...(api.uploadQuickReplyAttachment ? { upload: api.uploadQuickReplyAttachment } : {}),
+    labels,
+    ...(attachmentSizeLimits ? { attachmentSizeLimits } : {}),
+    attachmentsCount: editing?.attachments.length ?? 0,
+    onUploaded: uploadAttachment,
+  })
+
+  useEffect(() => {
+    if (!api.listQuickReplies) return
+    let cancelled = false
+    setIsLoading(true)
+    setLoadError(undefined)
+    api
+      .listQuickReplies()
+      .then((result) => {
+        if (!cancelled) setQuickReplies(result)
+      })
+      .catch((caught: unknown) => {
+        if (!cancelled) setLoadError(caught instanceof Error ? caught.message : labels.failure)
+      })
+      .finally(() => {
+        if (!cancelled) setIsLoading(false)
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [api.listQuickReplies])
+
+  const filtered = filterQuickReplies({ quickReplies, search })
+
+  const startCreate = useCallback(() => {
+    abortAllUploads()
+    dismissAttachmentRejections()
+    setEditing({ id: null, title: '', shortcut: '', body: '', attachments: [] })
+    setFieldErrors({})
+    setSaveError(undefined)
+  }, [abortAllUploads, dismissAttachmentRejections])
+
+  const startEdit = useCallback(
+    (quickReply: QuickReply) => {
+      abortAllUploads()
+      dismissAttachmentRejections()
+      setEditing({
+        id: quickReply.id,
+        title: quickReply.title,
+        shortcut: quickReply.shortcut,
+        body: quickReply.body,
+        attachments: quickReply.attachments ?? [],
+      })
+      setFieldErrors({})
+      setSaveError(undefined)
+    },
+    [abortAllUploads, dismissAttachmentRejections],
+  )
+
+  const cancelEdit = useCallback(() => {
+    abortAllUploads()
+    dismissAttachmentRejections()
+    setEditing(undefined)
+    setFieldErrors({})
+    setSaveError(undefined)
+  }, [abortAllUploads, dismissAttachmentRejections])
+
+  const updateField = useCallback((field: QuickReplyFormField, value: string) => {
+    setEditing((current) => (current ? { ...current, [field]: value } : current))
+    // Editar o campo limpa o erro dele — a mensagem antiga não deve sobreviver à correção.
+    setFieldErrors((current) => {
+      if (!(field in current)) return current
+      const next = { ...current }
+      delete next[field]
+      return next
+    })
+  }, [])
+
+  const submit = useCallback(async () => {
+    // Rede de segurança: o botão já fica desabilitado com upload em voo (QR-47), mas salvar antes
+    // da resposta chegar mandaria a mensagem sem o anexo que o operador acabou de anexar.
+    if (!editing || pendingUploads.length > 0) return
+    setIsSaving(true)
+    setSaveError(undefined)
+    setFieldErrors({})
+    const result = await submitQuickReply({ api, editing, labels })
+    setIsSaving(false)
+    if (result.outcome === 'saved') {
+      setQuickReplies((current) =>
+        editing.id === null
+          ? [result.quickReply, ...current]
+          : current.map((item) => (item.id === result.quickReply.id ? result.quickReply : item)),
+      )
+      setEditing(undefined)
+      return
+    }
+    setFieldErrors(result.fieldErrors)
+    if (result.outcome === 'rejected') setSaveError(result.formError)
+  }, [editing, api, labels, pendingUploads.length])
+
+  const remove = useCallback(
+    async (id: string) => {
+      if (!api.deleteQuickReply) return
+      setDeletingId(id)
+      try {
+        await api.deleteQuickReply(id)
+        setQuickReplies((current) => current.filter((item) => item.id !== id))
+      } finally {
+        setDeletingId(undefined)
+      }
+    },
+    [api],
+  )
+
+  const removeAttachment = useCallback((uploadId: string) => {
+    setEditing((current) =>
+      current
+        ? { ...current, attachments: current.attachments.filter((attachment) => attachment.uploadId !== uploadId) }
+        : current,
+    )
+  }, [])
+
+  const moveAttachmentAt = useCallback((index: number, direction: -1 | 1) => {
+    setEditing((current) =>
+      current ? { ...current, attachments: moveAttachment(current.attachments, index, direction) } : current,
+    )
+  }, [])
+
+  return {
+    quickReplies,
+    filtered,
+    isLoading,
+    loadError,
+    search,
+    setSearch,
+    readOnly: !api.createQuickReply,
+    canEdit: Boolean(api.updateQuickReply),
+    canDelete: Boolean(api.deleteQuickReply),
+    editing,
+    startCreate,
+    startEdit,
+    cancelEdit,
+    updateField,
+    fieldErrors,
+    isSaving,
+    saveError,
+    submit,
+    remove,
+    deletingId,
+    hasAttachmentsCapability: Boolean(api.uploadQuickReplyAttachment),
+    pendingUploads,
+    addAttachmentFiles,
+    retryAttachmentUpload,
+    cancelAttachmentUpload,
+    removeAttachment,
+    moveAttachmentAt,
+    attachmentRejections,
+    dismissAttachmentRejections,
+  }
+}

package/src/quickReplies/useQuickReplyAttachmentUploads.ts

@@ -0,0 +1,159 @@
+/**
+ * Fila de upload de anexo do formulário de cadastro (QR-31/M1), extraída de
+ * `useQuickRepliesWorkspace`: até 3 uploads em voo por vez, progresso real por arquivo, e
+ * cancelamento de tudo ao trocar de registro (M2) sem `setState` órfão depois do unmount.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { createUploadQueue } from './createUploadQueue'
+import { validateAttachmentFiles, type AttachmentFileRejection } from './quickReplyAttachmentUpload'
+import type { MaxAttachmentSizeBytes } from './quickReplyAttachments'
+import type { QuickReplyAttachment } from './quickReply.types'
+import type { QuickRepliesWorkspaceLabels } from './labels'
+
+/** Item em upload no formulário: estado local, nunca persistido — some ao terminar ou ser removido. */
+export type PendingAttachmentUpload = {
+  readonly localId: string
+  readonly file: File
+  readonly status: 'uploading' | 'error'
+  readonly progress: number
+  readonly error?: string
+}
+
+export type UseQuickReplyAttachmentUploadsParams = {
+  readonly upload?: (
+    file: File,
+    options?: { onProgress?: (fraction: number) => void; signal?: AbortSignal },
+  ) => Promise<QuickReplyAttachment>
+  readonly labels: QuickRepliesWorkspaceLabels
+  /** Sobrescreve o teto por tipo de arquivo. Ausente, usa `DEFAULT_MAX_ATTACHMENT_SIZE_BYTES`. */
+  readonly attachmentSizeLimits?: MaxAttachmentSizeBytes
+  /** Quantos anexos já confirmados (`editing.attachments.length`) — entra no teto de 10 (QR-31). */
+  readonly attachmentsCount: number
+  /** Onde o item entra assim que o upload resolve — o hook não sabe de `editing`, só devolve o resultado. */
+  readonly onUploaded: (attachment: QuickReplyAttachment) => void
+}
+
+export type UseQuickReplyAttachmentUploadsResult = {
+  readonly pendingUploads: readonly PendingAttachmentUpload[]
+  readonly attachmentRejections: readonly AttachmentFileRejection[]
+  readonly addAttachmentFiles: (files: FileList | readonly File[]) => void
+  readonly retryAttachmentUpload: (localId: string) => void
+  readonly cancelAttachmentUpload: (localId: string) => void
+  readonly dismissAttachmentRejections: () => void
+  /** Cancela todo upload em voo — trocar de registro sem isso deixaria um `fetch` órfão terminando
+   * sozinho e tentando atualizar um estado que já não existe mais. */
+  readonly abortAllUploads: () => void
+}
+
+/** Estado e orquestração do upload de anexo — sem saber de `editing`, só de arquivos e resultado. */
+export function useQuickReplyAttachmentUploads({
+  upload,
+  labels,
+  attachmentSizeLimits,
+  attachmentsCount,
+  onUploaded,
+}: UseQuickReplyAttachmentUploadsParams): UseQuickReplyAttachmentUploadsResult {
+  const [pendingUploads, setPendingUploads] = useState<readonly PendingAttachmentUpload[]>([])
+  const [attachmentRejections, setAttachmentRejections] = useState<readonly AttachmentFileRejection[]>([])
+  /** Fila compartilhada (M1): no máximo 3 uploads em voo ao mesmo tempo, somando o que
+   * `addAttachmentFiles` e `retryAttachmentUpload` enfileiram — nenhum dos dois abre janela própria. */
+  const uploadQueueRef = useRef(createUploadQueue(3))
+  /** M2: depois do unmount, nenhuma promessa de upload em voo pode chamar setState — só aborta. */
+  const isMountedRef = useRef(true)
+
+  useEffect(
+    () => () => {
+      isMountedRef.current = false
+      uploadQueueRef.current.abortAll()
+    },
+    [],
+  )
+
+  const abortAllUploads = useCallback(() => {
+    uploadQueueRef.current.abortAll()
+    setPendingUploads([])
+  }, [])
+
+  const dismissAttachmentRejections = useCallback(() => setAttachmentRejections([]), [])
+
+  const cancelAttachmentUpload = useCallback((localId: string) => {
+    uploadQueueRef.current.abort(localId)
+    setPendingUploads((current) => current.filter((item) => item.localId !== localId))
+  }, [])
+
+  const updatePendingUpload = useCallback((localId: string, patch: Partial<PendingAttachmentUpload>) => {
+    setPendingUploads((current) => current.map((item) => (item.localId === localId ? { ...item, ...patch } : item)))
+  }, [])
+
+  /** Sobe um arquivo já validado, através da fila compartilhada (M1): progresso real por
+   * `onProgress`, e o resultado vira `onUploaded` na ordem de chegada assim que a promessa
+   * resolve. Enfileira e retorna — quem chama não espera. */
+  const uploadOneFile = useCallback(
+    (localId: string, file: File) => {
+      if (!upload) return
+      uploadQueueRef.current.enqueue(localId, async (signal) => {
+        try {
+          const attachment = await upload(file, {
+            onProgress: (fraction) => {
+              if (isMountedRef.current) updatePendingUpload(localId, { progress: fraction })
+            },
+            signal,
+          })
+          if (!isMountedRef.current) return
+          onUploaded(attachment)
+          setPendingUploads((current) => current.filter((item) => item.localId !== localId))
+        } catch (caught: unknown) {
+          if (signal.aborted || !isMountedRef.current) return
+          updatePendingUpload(localId, {
+            status: 'error',
+            error: caught instanceof Error ? caught.message : labels.saveError,
+          })
+        }
+      })
+    },
+    [upload, updatePendingUpload, onUploaded, labels.saveError],
+  )
+
+  const retryAttachmentUpload = useCallback(
+    (localId: string) => {
+      const item = pendingUploads.find((pending) => pending.localId === localId)
+      if (!item) return
+      updatePendingUpload(localId, { status: 'uploading', progress: 0, error: undefined })
+      uploadOneFile(localId, item.file)
+    },
+    [pendingUploads, updatePendingUpload, uploadOneFile],
+  )
+
+  /** Valida (teto de 10, tamanho por tipo) ANTES de subir (QR-31) — só o aceito vira upload; o
+   * recusado fica em `attachmentRejections` para a tela explicar por quê, sem gastar rede nele. */
+  const addAttachmentFiles = useCallback(
+    (files: FileList | readonly File[]) => {
+      if (!upload) return
+      const currentCount = attachmentsCount + pendingUploads.length
+      const { accepted, rejected } = validateAttachmentFiles(Array.from(files), currentCount, attachmentSizeLimits)
+      setAttachmentRejections(rejected)
+      if (accepted.length === 0) return
+      const newItems: PendingAttachmentUpload[] = accepted.map((file) => ({
+        localId: `${file.name}-${file.size}-${file.lastModified}-${Math.random().toString(36).slice(2)}`,
+        file,
+        status: 'uploading',
+        progress: 0,
+      }))
+      setPendingUploads((current) => [...current, ...newItems])
+      // Até 3 em paralelo (QR-31), somando com retries em voo — a fila compartilhada decide (M1).
+      for (const item of newItems) uploadOneFile(item.localId, item.file)
+    },
+    [upload, attachmentsCount, pendingUploads.length, uploadOneFile, attachmentSizeLimits],
+  )
+
+  return {
+    pendingUploads,
+    attachmentRejections,
+    addAttachmentFiles,
+    retryAttachmentUpload,
+    cancelAttachmentUpload,
+    dismissAttachmentRejections,
+    abortAllUploads,
+  }
+}

package/src/styles.css

@@ -818,6 +818,93 @@
   border-color: rgb(51 65 85);
 }
 
+/* Item da fila com miniatura, estado de envio (QR-47) e saída com transição curta. */
+.cv-attachment-item {
+  max-width: 16rem;
+}
+.cv-attachment-item__thumbnail {
+  display: block;
+  flex: none;
+  width: 2rem;
+  height: 2rem;
+  overflow: hidden;
+  border-radius: 0.375rem;
+  background: rgb(226 232 240);
+}
+.dark .cv-attachment-item__thumbnail { background: rgb(51 65 85); }
+.cv-attachment-item__thumbnail img { width: 100%; height: 100%; object-fit: cover; }
+.cv-attachment-item__info {
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  min-width: 0;
+}
+.cv-attachment-item__name { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-weight: 500; }
+.cv-attachment-item__meta { font-size: 0.6875rem; color: rgb(100 116 139); }
+.dark .cv-attachment-item__meta { color: rgb(148 163 184); }
+.cv-attachment-item--failed .cv-attachment-item__meta { color: rgb(220 38 38); }
+.dark .cv-attachment-item--failed .cv-attachment-item__meta { color: rgb(248 113 113); }
+.cv-attachment-item--sent .cv-attachment-item__meta { color: rgb(22 163 74); }
+.dark .cv-attachment-item--sent .cv-attachment-item__meta { color: rgb(74 222 128); }
+.cv-attachment-item--skipped .cv-attachment-item__meta { color: rgb(180 83 9); }
+.dark .cv-attachment-item--skipped .cv-attachment-item__meta { color: rgb(251 191 36); }
+.cv-attachment-item__retry {
+  flex: none;
+  border: 0;
+  background: none;
+  padding: 0;
+  font-size: 0.6875rem;
+  text-decoration: underline;
+  color: rgb(37 99 235);
+  cursor: pointer;
+}
+.cv-attachment-item {
+  transition: opacity 200ms ease, transform 200ms ease;
+  opacity: 1;
+  transform: scale(1);
+}
+.cv-attachment-item--departing {
+  opacity: 0;
+  transform: scale(0.92);
+}
+@media (prefers-reduced-motion: reduce) {
+  .cv-attachment-item { transition: none; }
+}
+
+/* Esqueleto de linha — usado no painel de mensagens prontas e na tabela de cadastro (QR-47): nunca
+   "Carregando…" solto, e o conteúdo nunca aparece de uma vez. */
+.cv-skeleton-line {
+  border-radius: 0.25rem;
+  background: linear-gradient(90deg, rgb(226 232 240) 25%, rgb(241 245 249) 50%, rgb(226 232 240) 75%);
+  background-size: 200% 100%;
+  animation: cv-skeleton-shimmer 1.4s ease-in-out infinite;
+}
+.dark .cv-skeleton-line {
+  background: linear-gradient(90deg, rgb(51 65 85) 25%, rgb(71 85 105) 50%, rgb(51 65 85) 75%);
+  background-size: 200% 100%;
+}
+@keyframes cv-skeleton-shimmer {
+  0% { background-position: 200% 0; }
+  100% { background-position: -200% 0; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .cv-skeleton-line { animation: none; }
+}
+/* Larguras da linha de esqueleto da tabela de mensagens prontas: uma por coluna, porque colunas
+   diferentes leem melhor com proporções diferentes em vez de todas do mesmo tamanho. */
+.cv-skeleton-line--title { width: 70%; height: 0.75rem; }
+.cv-skeleton-line--shortcut { width: 50%; height: 0.75rem; }
+.cv-skeleton-line--body { width: 90%; height: 0.75rem; }
+
+/* Linha excluída sai com transição curta em vez de sumir de repente (QR-47). */
+.cv-row-departing {
+  transition: opacity 200ms ease;
+  opacity: 0;
+}
+@media (prefers-reduced-motion: reduce) {
+  .cv-row-departing { transition: none; }
+}
+
 /* Peças de listagem (documentos, mensagens): tabela com filtros, seleção em lote e paginação. */
 .cv-filter-count {
   display: inline-flex;