@snksergio/design-system 0.61.0 → 0.63.0

package/dist-lib/ai/componentes/ConversationListItem.md

@@ -0,0 +1,90 @@
+# ConversationListItem
+
+Item de **lista de conversa** (Atendimento / Chat) — uma linha clicável que
+representa um ticket/conversa. **Composto** (categoria: composite): combina
+`Avatar` + `Chip` (slot `badges`) + `Button`/`Icon` (slot `actions`) +
+`MarkdownText` (prévia inline). NÃO é uma célula de DataTable.
+
+## Quando usar
+
+- Coluna lateral de tickets/conversas do Atendimento (variant `ticket`).
+- Lista de conversas estilo DM/chat (variant `chat`).
+- Qualquer lista vertical de conversas com avatar + prévia + hora + metadados.
+
+Para tabelas de dados com colunas/sort/filtros → use `DataTable`, não este.
+
+## Props essenciais
+
+| Prop        | Tipo                                                     | Default        | Descrição |
+|-------------|----------------------------------------------------------|----------------|-----------|
+| `title`     | `string` (req)                                           | —              | Nome do contato/conversa. Truncado. |
+| `avatar`    | `{ src?, name?, colorHex? }` \| `ReactNode`              | —              | Objeto-atalho monta o `Avatar` do DS (iniciais do nome; `src` vira `<img>`); ou nó custom. |
+| `preview`   | `string`                                                 | —              | Última mensagem (markdown WA) → `MarkdownText` inline, `line-clamp-1`. |
+| `time`      | `string`                                                 | —              | Hora já formatada (`14:32` / `21/06`). Tabular, caption. |
+| `badges`    | `ReactNode`                                              | —              | Slot de `<Chip>`s coloridos (protocolo/conexão/agente/fila/tags). |
+| `unread`    | `number`                                                 | —              | `> 0` → badge `bg-bg-danger`/`text-fg-on-danger` (mostra `99+`). |
+| `actions`   | `ReactNode`                                              | —              | Slot de ações revelado no hover/focus (ex `<Button>` Pencil/Trash ou menu). |
+| `onClick`   | `() => void`                                             | —              | Clique na linha (Enter/Space também disparam). |
+| `selected`  | `boolean`                                                | `false`        | Stripe brand 3px à esquerda + `bg-bg-muted`. |
+| `disabled`  | `boolean`                                                | `false`        | Desabilita interação. |
+| `className` | `string`                                                 | —              | Classe extra no root. |
+
+## Variants
+
+| Variant       | Valores                          | Default         | Efeito |
+|---------------|----------------------------------|-----------------|--------|
+| `variant`     | `ticket` \| `chat`               | `ticket`        | `chat` aperta o espaçamento vertical do corpo. |
+| `density`     | `comfortable` \| `compact`       | `comfortable`   | Padding vertical da linha. |
+| `selected`    | `boolean`                        | `false`         | Stripe brand + bg muted. |
+| `unread`(>0)  | derivado de `unread`             | —               | Título em bold + prévia mais forte. |
+| `disabled`    | `boolean`                        | `false`         | Último compoundVariant (L-006). |
+
+## Exemplo mínimo
+
+```tsx
+import { ConversationListItem } from "@/components/ui/ConversationListItem";
+import { Chip } from "@/components/ui/Chip";
+import { Button } from "@/components/ui/Button";
+import { Icon } from "@/components/ui/Icon";
+
+<ConversationListItem
+  title="Maria Silva"
+  avatar={{ name: "Maria Silva", colorHex: "#8754ec" }}
+  preview="*Olá!* Gostaria de saber sobre a fatura ```#A12```"
+  time="14:32"
+  unread={3}
+  selected={selectedId === ticket.id}
+  onClick={() => selectTicket(ticket.id)}
+  badges={
+    <>
+      <Chip size="sm" color="info" variant="soft">#PROTO-1024</Chip>
+      <Chip size="sm" color="success" variant="soft">WHATSAPP</Chip>
+      <Chip size="sm" color="primary" variant="soft">SUPORTE</Chip>
+    </>
+  }
+  actions={
+    <>
+      <Button size="xs" variant="ghost" iconLeft={<Icon name="line-pencil" />} aria-label="Editar" />
+      <Button size="xs" variant="ghost" color="critical" iconLeft={<Icon name="line-bin" />} aria-label="Excluir" />
+    </>
+  }
+/>
+```
+
+## Gotchas / cuidados
+
+- **Renderiza `div[role="button"]`**, não `<button>` — porque o slot `actions`
+  costuma conter `<button>` (botão aninhado é HTML inválido). A11y por teclado:
+  `tabIndex=0` + Enter/Space disparam `onClick`. `role`/`tabIndex` só existem
+  quando há `onClick` e não está `disabled`.
+- O `Avatar` do DS exibe **iniciais**; quando você passa `avatar.src`, a imagem
+  é renderizada como `<img>` DENTRO do Avatar (que já é `rounded-full overflow-hidden`).
+  Sem `src`, as iniciais derivam de `name` (fallback: `title`).
+- `preview` passa por `MarkdownText inline` — markdown WA (`*bold*` `_italic_`
+  `~strike~` ` ```mono``` `) é sanitizado e truncado em 1 linha. Não passe HTML cru.
+- `unread` só desenha o badge quando `> 0`; valores `> 99` viram `99+`.
+- Cliques dentro de `actions` têm `stopPropagation` — não disparam o `onClick`
+  da linha.
+- Visual 100% via tokens DS. Única exceção de hardcode: `before:w-[3px]` da stripe
+  e as dimensões finas do count-badge (`min-w-[18px] h-[18px] px-[5px]`) — mesmo
+  padrão dos contadores de Chip/Table.

package/dist-lib/ai/componentes/DataList.md

@@ -0,0 +1,111 @@
+# DataList — USAGE
+
+**O que é:** componente **inteligente** sobre o `List` (como `DataTable` é sobre o
+`Table`). Toolbar enxuta + busca + filtros + saved-views + persistência + seleção/
+bulk + server/async + virtualização + lazy-load. _Categoria: List Components._
+
+**Quando usar:** lista de cards que precisa de busca/filtro/views/seleção. Para
+cards "crus" sem toolbar, use `List`. Para tabela densa, `DataTable`.
+
+## Toolbar (enxuta — sem colunas)
+
+Visões (ou `title`) · refresh · search · filtro · `⋯`. **Não tem** toggle de visão
+nem menu de configurações de colunas (é cards, não tabela). Reusa o `<TableToolbar>`
+(dumb): as **visões viram abas** (1ª aba = `title`/"Todos", igual à DataTable) e os
+filtros aplicados aparecem como **chips** (`<ToolbarApplied>`) abaixo da toolbar —
+o drawer de filtro é o MESMO `<ToolbarSimpleFilterDrawer>` da tabela. Os **chips são
+clicáveis**: abrem o fast-filter do column-type (via `columnTypeRegistry`) pra editar o
+valor inline — mesma UX do DataTable (sem precisar reabrir o drawer).
+
+## Exemplo
+
+```tsx
+<DataList
+  title="Membros"
+  items={people}
+  searchable
+  filterFields={[
+    {
+      id: "role",
+      label: "Papel",
+      type: "select",
+      accessor: (i) => i.data.role,
+      options: [
+        { label: "Admin", value: "admin" },
+        { label: "Editor", value: "editor" },
+      ],
+    },
+    {
+      id: "status",
+      label: "Status",
+      type: "select",
+      accessor: (i) => i.data.status,
+      options: [
+        { label: "Ativo", value: "active" },
+        { label: "Pendente", value: "pending" },
+      ],
+    },
+  ]}
+  views={[
+    {
+      id: "admins",
+      label: "Admins",
+      query: {
+        search: "",
+        filterModel: {
+          logicOperator: "AND",
+          items: [
+            { id: "v1", field: "role", operator: "equals", value: "admin" },
+          ],
+        },
+      },
+    },
+  ]}
+  selectable
+  bulkActions={[{ label: "Arquivar", onClick: (ids) => archive(ids) }]}
+  onRefresh={refetch}
+  persistKey="members"
+/>
+```
+
+## Props essenciais
+
+| Prop                                                                            | Nota                                                                                                                                                                                                                    |
+| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `items` / `layout` / `groups`                                                   | repassados ao `List` (layout é fixo, não troca na toolbar)                                                                                                                                                              |
+| `title` · `searchable` · `filterFields` · `views` · `onRefresh` · `moreActions` | toolbar                                                                                                                                                                                                                 |
+| `toolbarActions`                                                                | `ToolbarAction[]` — ações custom no toolbar (`button`/`dropdown`/`input`, ex.: seletor de período). Inline no desktop (entre Filtros e ⋯); no **mobile colapsam num ⋯** junto com `moreActions`. Ver `<ToolbarActions>` |
+| `filterFields`                                                                  | `{ id, label, accessor, type: text/select/boolean/number/date, options? }`                                                                                                                                              |
+| `mode` `"client"`/`"server"` + `onQueryChange` · `loading` · `total`            | dados server/async                                                                                                                                                                                                      |
+| `onLoadMore` + `hasMore` + `loadingMore`                                        | infinite scroll (sentinel IntersectionObserver + cards skeleton) — **não virtualizado**                                                                                                                                 |
+| `virtualized` (+ `estimateItemSize`)                                            | listas grandes — **só layout standard**                                                                                                                                                                                 |
+| `onLoadChildren(id)`                                                            | lazy-load de filhos (hierarchical)                                                                                                                                                                                      |
+| `defaultExpandedIds`                                                            | `Set<string>` — nós abertos no mount (hierarchical/grouped)                                                                                                                                                             |
+| `branchHighlight`                                                               | destaque de família (hierárquico, passa pro List): `none` · `block` (painéis) · `active` (ramo do último aberto)                                                                                                        |
+| `selectable` + `onSelectionChange` + `bulkActions`                              | seleção + bulk bar                                                                                                                                                                                                      |
+| `enableDnD` + `onReorder`/`onMove`                                              | DnD (passa pro List)                                                                                                                                                                                                    |
+| `persistKey`                                                                    | persiste a query (search+filtros) em localStorage                                                                                                                                                                       |
+| `fillHeight`                                                                    | ocupa 100% da altura do pai e faz **só a lista rolar** (toolbar/chips/bulk fixos). Dê altura ao pai + `className="flex-1 min-h-0"`. Não combinar com `virtualized`                                                      |
+
+## Gotchas
+
+- **`virtualized` desliga o DnD** (mutuamente exclusivos: o `@hello-pangea/dnd` precisa
+  de todos os cards montados; a virtualização desmonta os fora da viewport). Virtualização
+  só no layout `standard`.
+- **Modo server:** o DataList NÃO filtra localmente — emite `onQueryChange({search, filters})`
+  (debounce no search) e renderiza o que vier em `items` (use `loading`/`total`).
+- **Filtros por campos** (não colunas): o consumer declara `filterFields`. Busca textual
+  cobre title/subtitle/description + accessors dos campos.
+- **Infinite scroll** (`onLoadMore`/`hasMore`/`loadingMore`): o consumer controla os `items`
+  (append da próxima página) — o DataList só dispara `onLoadMore` quando o sentinel entra na
+  viewport (rootMargin 200px) e mostra skeletons enquanto `loadingMore`. Incompatível com
+  `virtualized` (use um, não os dois).
+- **`toolbarActions`** (ações custom no toolbar): formato `ToolbarAction[]`. Inline no
+  desktop; no mobile colapsam num único ⋯ (junto com `moreActions`). Shapes:
+  ```ts
+  { kind: "button",   id, label, icon?, onClick, isActive?, disabled? }
+  { kind: "dropdown", id, label, icon?, items: { label, icon?, onClick, active?, separator?, destructive? }[] }
+  { kind: "input",    id, label, icon?, value, onChange, placeholder? }
+  ```
+  Ex.: seletor de período → `{ kind:"dropdown", id:"periodo", label:mes, items:[...] }`.
+- A doc viva é o showcase `#/data-list` e `#/list-standard` (exemplo do seletor de período).