@iclips/ui 3.0.0 → 3.1.0

package/docs/overlays.md

@@ -0,0 +1,192 @@
+# Qual overlay usar
+
+Todos flutuam acima da página, mas resolvem problemas diferentes. A pergunta que separa é: **o conteúdo exige uma ação do usuário** (então prende o foco) ou **só complementa** (então some ao clicar fora)?
+
+## Tabela de decisão
+
+| Overlay | Escolha quando | Evite quando |
+| --- | --- | --- |
+| Tooltip | rótulo curto para um ícone ou controle sem texto — aparece no hover/foco, some sozinho. | o conteúdo tem link, botão ou texto que o usuário precise ler com calma → `Popover`. |
+| HoverCard | prévia rica e não-essencial de algo já visível (card de usuário, resumo de projeto). | a informação é necessária para a tarefa, ou o gatilho é em mobile (não há hover) → `Popover`. |
+| Popover | um pequeno painel ancorado a um botão: filtro, seletor de cor, mini-formulário, menu de ações. | há mais de ~6 campos ou o fluxo tem etapas → `Dialog` ou `Sheet`. |
+| Dialog | uma tarefa focada que interrompe o fluxo: editar um registro, confirmar com contexto, wizard curto. | é só um aviso de sim/não destrutivo → `AlertDialog`. Formulário longo → `Sheet`. |
+| AlertDialog | confirmação de ação destrutiva ou irreversível (excluir, cancelar assinatura). Trava até o usuário decidir. | a ação não é perigosa e é desfazível → use um Toast com "Desfazer". |
+| Sheet | painel lateral para formulário longo, detalhes ou configurações sem perder o contexto da lista atrás. | a tarefa é curta e centrada → `Dialog`. Navegação primária do app → não é overlay. |
+| Drawer | o mesmo papel do Sheet, mas puxado de baixo — padrão em telas de toque/mobile. | desktop com espaço de sobra → `Sheet` lateral. |
+
+## Trilha rápida
+
+Responda de cima para baixo e pare na primeira que servir.
+
+1. **A ação é destrutiva/irreversível e precisa de confirmação?** Sim: `AlertDialog`. Não: continue.
+2. **É só um rótulo de texto para um ícone?** Sim: `Tooltip`. Não: continue.
+3. **É uma prévia opcional de algo que já está na tela?** Sim: `HoverCard` (desktop) — mas garanta um caminho por clique no mobile. Não: continue.
+4. **Cabe em um painelzinho de até ~6 campos ancorado ao gatilho?** Sim: `Popover`. Não: continue.
+5. **O usuário precisa ver a lista/tela de trás enquanto preenche?** Sim: `Sheet` (desktop) ou `Drawer` (toque). Não: `Dialog`.
+
+## Exemplos
+
+### Tooltip — rótulo de ícone
+
+Some ao tirar o mouse ou o foco. Sem conteúdo interativo dentro. Balão neutro invertido: é informação, não ação. Precisa de um `TooltipProvider` acima (uma vez, na raiz).
+
+```tsx
+import { Button, Tooltip, TooltipContent, TooltipTrigger } from "@iclips/ui";
+import { Archive } from "lucide-react";
+
+<Tooltip>
+  <TooltipTrigger asChild>
+    <Button variant="outline" size="icon" aria-label="Arquivar">
+      <Archive className="size-4" />
+    </Button>
+  </TooltipTrigger>
+  <TooltipContent>Arquivar</TooltipContent>
+</Tooltip>
+```
+
+### Popover — mini-formulário
+
+Fecha ao clicar fora. Bom para 1–6 campos.
+
+```tsx
+import { Button, Input, Label, Popover, PopoverContent, PopoverTrigger } from "@iclips/ui";
+
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="outline">Renomear</Button>
+  </PopoverTrigger>
+  <PopoverContent className="w-64 space-y-2">
+    <Label htmlFor="novo-nome">Novo nome</Label>
+    <Input id="novo-nome" defaultValue="Campanha Q3" />
+  </PopoverContent>
+</Popover>
+```
+
+### Dialog — tarefa focada
+
+Prende o foco. Título + descrição + ações.
+
+```tsx
+import {
+  Button, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle,
+  DialogTrigger, Input, Label,
+} from "@iclips/ui";
+
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>Editar perfil</Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Editar perfil</DialogTitle>
+      <DialogDescription>As alterações são salvas ao confirmar.</DialogDescription>
+    </DialogHeader>
+    <div className="grid gap-1.5 py-2">
+      <Label htmlFor="nome">Nome</Label>
+      <Input id="nome" defaultValue="Ana Souza" />
+    </div>
+    <DialogFooter>
+      <DialogClose asChild><Button variant="outline">Cancelar</Button></DialogClose>
+      <Button>Salvar</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+### AlertDialog — confirmação destrutiva
+
+Sem clicar-fora-para-fechar. Uma escolha explícita.
+
+```tsx
+import {
+  AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription,
+  AlertDialogFooter, AlertDialogHeader, AlertDialogTitle, AlertDialogTrigger, Button,
+} from "@iclips/ui";
+
+<AlertDialog>
+  <AlertDialogTrigger asChild>
+    <Button variant="destructive">Excluir projeto</Button>
+  </AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Excluir “Campanha Q3”?</AlertDialogTitle>
+      <AlertDialogDescription>
+        Esta ação não pode ser desfeita. Todos os itens do projeto serão removidos.
+      </AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Cancelar</AlertDialogCancel>
+      <AlertDialogAction>Excluir</AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+### Sheet — formulário longo
+
+A lista de trás continua visível como contexto.
+
+```tsx
+import {
+  Button, Input, Label, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle,
+  SheetTrigger,
+} from "@iclips/ui";
+
+<Sheet>
+  <SheetTrigger asChild>
+    <Button variant="outline">Nova tarefa</Button>
+  </SheetTrigger>
+  <SheetContent className="w-full sm:max-w-md">
+    <SheetHeader>
+      <SheetTitle>Nova tarefa</SheetTitle>
+      <SheetDescription>Preencha os campos e salve.</SheetDescription>
+    </SheetHeader>
+    <div className="grid gap-3 px-4">
+      <div className="grid gap-1.5"><Label htmlFor="titulo">Título</Label><Input id="titulo" /></div>
+      <div className="grid gap-1.5"><Label htmlFor="responsavel">Responsável</Label><Input id="responsavel" /></div>
+      <div className="grid gap-1.5"><Label htmlFor="prazo">Prazo</Label><Input id="prazo" type="date" /></div>
+    </div>
+    <SheetFooter>
+      <Button>Criar tarefa</Button>
+      <SheetClose asChild><Button variant="outline">Cancelar</Button></SheetClose>
+    </SheetFooter>
+  </SheetContent>
+</Sheet>
+```
+
+### HoverCard — prévia opcional
+
+Só complementa. Nunca coloque aqui algo que a tarefa exige.
+
+```tsx
+import { Button, HoverCard, HoverCardContent, HoverCardTrigger } from "@iclips/ui";
+
+<HoverCard>
+  <HoverCardTrigger asChild>
+    <Button variant="link">@ana.souza</Button>
+  </HoverCardTrigger>
+  <HoverCardContent className="text-sm">
+    <p className="font-medium">Ana Souza</p>
+    <p className="text-muted-foreground">Designer · entrou em 2023</p>
+  </HoverCardContent>
+</HoverCard>
+```
+
+## Faça / evite
+
+#### Faça
+
+- Dê a todo `Dialog`/`Sheet`/`AlertDialog` um título — é o rótulo que o leitor de tela anuncia.
+- Reserve o `AlertDialog` para o que dói desfazer; para o resto, aja e ofereça "Desfazer" num Toast.
+- No mobile, troque `Sheet` lateral por `Drawer` e `HoverCard` por `Popover` (toque não tem hover).
+- Empilhe no máximo um overlay. Se precisar de outro, provavelmente o fluxo deveria ser uma página.
+
+#### Evite
+
+- Colocar um formulário de 15 campos num `Popover`.
+- Usar `Tooltip` para conteúdo que tem link ou botão — o usuário não consegue alcançar.
+- Pintar o `Tooltip` com a cor da marca (`bg-primary`) — overlay informativo não se veste de ação.
+- Abrir um `Dialog` dentro de outro `Dialog`.
+- Trocar toast de sucesso por `Dialog` "OK" — interrompe sem motivo.
+
+**Acessibilidade:** `Dialog`, `AlertDialog`, `Sheet` e `Popover` vêm do Radix — prendem o foco, fecham no Esc e devolvem o foco ao gatilho de graça. O que você precisa garantir: um `Title` em todo painel modal, e `aria-label` em gatilhos que são só ícone.

package/docs/status.md

@@ -0,0 +1,71 @@
+# Status
+
+Status é **estado**: feedback, nunca decoração. Vermelho, verde, amarelo e azul só aparecem para dizer algo sobre um item. Status nunca é roxo (roxo é ação) e sempre vem com ícone ou rótulo — cor sozinha não identifica nada.
+
+A receita é sempre suave: `bg-<status>/10 text-<status>-emphasis border-<status>/20`. Os componentes já a aplicam — use o componente em vez de montar as classes.
+
+| Status | `variant` | Quando |
+| --- | --- | --- |
+| Sucesso | `success` | aprovado, pago, concluído, ativo |
+| Aviso | `warning` | pendente, aguardando, vence em breve |
+| Informação | `info` | em análise, rascunho enviado, novidade |
+| Erro | `destructive` | recusado, vencido, falhou, cancelado |
+
+## Status de um item
+
+Use `Badge` com a variante do status e um ícone ou rótulo claro.
+
+```tsx
+import { Badge } from "@iclips/ui";
+import { Check, CircleAlert, Clock, Info } from "lucide-react";
+
+<Badge variant="success"><Check /> Aprovado</Badge>
+<Badge variant="warning"><Clock /> Aguardando</Badge>
+<Badge variant="info"><Info /> Em análise</Badge>
+<Badge variant="destructive"><CircleAlert /> Recusado</Badge>
+```
+
+Status que vem da API vira um mapa, não um `if` por status:
+
+```tsx
+import { Badge } from "@iclips/ui";
+
+const STATUS = {
+  pago: { variant: "success", rotulo: "Pago" },
+  pendente: { variant: "warning", rotulo: "Pendente" },
+  vencido: { variant: "destructive", rotulo: "Vencido" },
+} as const;
+
+function StatusParcela({ status }: { status: keyof typeof STATUS }) {
+  const { variant, rotulo } = STATUS[status];
+  return <Badge variant={variant}>{rotulo}</Badge>;
+}
+```
+
+Status neutro (sem juízo de bom ou ruim, como "Arquivado" ou "Inativo") usa `variant="muted"` ou `variant="outline"`, não uma cor de estado.
+
+## Valor positivo ou negativo
+
+Número que sobe ou desce (variação, saldo, meta) usa o texto `-emphasis` do status, com sinal ou ícone — nunca só a cor.
+
+```tsx
+import { TrendingDown, TrendingUp } from "lucide-react";
+
+<span className="inline-flex items-center gap-1 text-success-emphasis">
+  <TrendingUp className="size-4" aria-hidden="true" /> +12,4%
+</span>
+<span className="inline-flex items-center gap-1 text-destructive-emphasis">
+  <TrendingDown className="size-4" aria-hidden="true" /> −3,1%
+</span>
+```
+
+## Condição que vale para a tela toda
+
+Se o status é da página e não de um item (plano expirando, modo somente-leitura), é um `Alert` — ver [Mensagens](mensagens.md).
+
+## Regras
+
+- Status **nunca é roxo** e nunca é `text-<status>` cru em texto: use `text-<status>-emphasis`, que passa contraste AA nos dois temas.
+- Não pinte **fundo de seção** ou card com cor de estado — o badge carrega o estado, não o card.
+- Nunca fundo sólido de estado (`bg-success` sem `/10`): a cor cheia fica só no ícone e na borda de campo inválido.
+- Mais regras de cor em [Linguagem visual](../DESIGN.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iclips/ui",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Design system da iClips — componentes React sobre Radix UI + Tailwind v4, paleta #7F26BF",
   "author": "iclipsbr",
   "license": "MIT",
@@ -49,6 +49,8 @@
     "LICENSE",
     "MIGRATION-v2.md",
     "MIGRATION-v3.md",
+    "DESIGN.md",
+    "docs",
     "scripts/check-colors.mjs"
   ],
   "peerDependencies": {