@iclips/ui 3.0.0 → 4.0.0

package/dist/index.d.cts

@@ -171,7 +171,7 @@ export declare interface AdvancedDataTableProps<T extends object> {
 }
 
 export declare const Alert: React_2.ForwardRefExoticComponent<Omit<React_2.ClassAttributes<HTMLDivElement> & React_2.HTMLAttributes<HTMLDivElement> & VariantProps<(props?: ({
-    variant?: "default" | "destructive" | "success" | "info" | "warning" | null | undefined;
+    variant?: "default" | "destructive" | "success" | "warning" | "info" | null | undefined;
 } & ClassProp) | undefined) => string>, "ref"> & React_2.RefAttributes<HTMLDivElement>>;
 
 export declare const AlertDescription: React_2.ForwardRefExoticComponent<Omit<React_2.DetailedHTMLProps<React_2.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & React_2.RefAttributes<HTMLDivElement>>;
@@ -234,7 +234,7 @@ export declare const AvatarFallback: React_2.ForwardRefExoticComponent<PropsAvat
 export declare const AvatarImage: React_2.ForwardRefExoticComponent<Omit<AvatarPrimitive.AvatarImageProps & React_2.RefAttributes<HTMLImageElement>, "ref"> & React_2.RefAttributes<HTMLImageElement>>;
 
 export declare const Badge: React_2.ForwardRefExoticComponent<Omit<React_2.DetailedHTMLProps<React_2.HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & VariantProps<(props?: ({
-    variant?: "default" | "destructive" | "outline" | "secondary" | "muted" | null | undefined;
+    variant?: "default" | "destructive" | "outline" | "secondary" | "success" | "warning" | "info" | "muted" | null | undefined;
     size?: "default" | "xs" | null | undefined;
     dashed?: boolean | null | undefined;
 } & ClassProp) | undefined) => string> & {
@@ -244,7 +244,7 @@ export declare const Badge: React_2.ForwardRefExoticComponent<Omit<React_2.Detai
 } & React_2.RefAttributes<HTMLSpanElement>>;
 
 export declare const badgeVariants: (props?: ({
-    variant?: "default" | "destructive" | "outline" | "secondary" | "muted" | null | undefined;
+    variant?: "default" | "destructive" | "outline" | "secondary" | "success" | "warning" | "info" | "muted" | null | undefined;
     size?: "default" | "xs" | null | undefined;
     dashed?: boolean | null | undefined;
 } & ClassProp) | undefined) => string;

package/dist/index.d.ts

@@ -171,7 +171,7 @@ export declare interface AdvancedDataTableProps<T extends object> {
 }
 
 export declare const Alert: React_2.ForwardRefExoticComponent<Omit<React_2.ClassAttributes<HTMLDivElement> & React_2.HTMLAttributes<HTMLDivElement> & VariantProps<(props?: ({
-    variant?: "default" | "destructive" | "success" | "info" | "warning" | null | undefined;
+    variant?: "default" | "destructive" | "success" | "warning" | "info" | null | undefined;
 } & ClassProp) | undefined) => string>, "ref"> & React_2.RefAttributes<HTMLDivElement>>;
 
 export declare const AlertDescription: React_2.ForwardRefExoticComponent<Omit<React_2.DetailedHTMLProps<React_2.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & React_2.RefAttributes<HTMLDivElement>>;
@@ -234,7 +234,7 @@ export declare const AvatarFallback: React_2.ForwardRefExoticComponent<PropsAvat
 export declare const AvatarImage: React_2.ForwardRefExoticComponent<Omit<AvatarPrimitive.AvatarImageProps & React_2.RefAttributes<HTMLImageElement>, "ref"> & React_2.RefAttributes<HTMLImageElement>>;
 
 export declare const Badge: React_2.ForwardRefExoticComponent<Omit<React_2.DetailedHTMLProps<React_2.HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & VariantProps<(props?: ({
-    variant?: "default" | "destructive" | "outline" | "secondary" | "muted" | null | undefined;
+    variant?: "default" | "destructive" | "outline" | "secondary" | "success" | "warning" | "info" | "muted" | null | undefined;
     size?: "default" | "xs" | null | undefined;
     dashed?: boolean | null | undefined;
 } & ClassProp) | undefined) => string> & {
@@ -244,7 +244,7 @@ export declare const Badge: React_2.ForwardRefExoticComponent<Omit<React_2.Detai
 } & React_2.RefAttributes<HTMLSpanElement>>;
 
 export declare const badgeVariants: (props?: ({
-    variant?: "default" | "destructive" | "outline" | "secondary" | "muted" | null | undefined;
+    variant?: "default" | "destructive" | "outline" | "secondary" | "success" | "warning" | "info" | "muted" | null | undefined;
     size?: "default" | "xs" | null | undefined;
     dashed?: boolean | null | undefined;
 } & ClassProp) | undefined) => string;

package/dist/preset.css

@@ -349,3 +349,93 @@ html {
     @apply pb-2.5;
   }
 }
+
+/* ==========================================================
+   TipTap — editor (DocumentEditor / CommentThread)
+   Estilos que as extensoes exigem para funcionar visualmente:
+   o placeholder so aparece via ::before, e a lista de tarefas
+   precisa perder o marcador para alinhar o checkbox. As regras de
+   taskList nao sao presas ao .ProseMirror porque o comentario ja
+   postado e renderizado como HTML puro, fora do editor.
+   ========================================================== */
+
+.ProseMirror p.is-editor-empty:first-child::before {
+  content: attr(data-placeholder);
+  @apply text-muted-foreground pointer-events-none float-left h-0;
+}
+
+ul[data-type="taskList"] {
+  @apply list-none pl-0;
+}
+
+ul[data-type="taskList"] li {
+  @apply flex items-start gap-2;
+}
+
+ul[data-type="taskList"] li > label {
+  @apply mt-1 shrink-0 select-none;
+}
+
+ul[data-type="taskList"] li > div {
+  @apply min-w-0 flex-1;
+}
+
+ul[data-type="taskList"] li[data-checked="true"] > div {
+  @apply text-muted-foreground line-through;
+}
+
+.ProseMirror mark, .prose mark {
+  @apply bg-primary/25 rounded-sm px-0.5;
+}
+
+/* Tabela e bloco recolhivel: so aparecem quando o consumidor liga
+   `features.table` / `features.details`, mas o CSS e global porque o
+   comentario ja postado tambem renderiza essas tags. */
+
+.ProseMirror table {
+  @apply w-full table-fixed border-collapse;
+}
+
+.ProseMirror table td,
+.ProseMirror table th {
+  @apply border-border relative min-w-24 border p-2 align-top;
+}
+
+.ProseMirror table th {
+  @apply bg-muted/50 text-left font-semibold;
+}
+
+.ProseMirror table .selectedCell::after {
+  @apply bg-primary/15 pointer-events-none absolute inset-0 z-10 content-[''];
+}
+
+.ProseMirror table .column-resize-handle {
+  @apply bg-primary absolute -bottom-0.5 -right-0.5 top-0 w-1 cursor-col-resize;
+}
+
+/* O tiptap nao usa <details> nativo: monta <div data-type="details"> com um
+   botao de toggle sem conteudo, que ganha o triangulo aqui. Aberto = .is-open */
+
+.ProseMirror [data-type="details"] {
+  @apply border-border my-2 flex gap-2 rounded-md border p-2;
+}
+
+.ProseMirror [data-type="details"] > button {
+  @apply text-muted-foreground mt-0.5 h-4 w-4 shrink-0 cursor-pointer leading-none;
+}
+
+.ProseMirror [data-type="details"] > button::before {
+  content: "▸";
+}
+
+.ProseMirror [data-type="details"].is-open > button::before {
+  content: "▾";
+}
+
+.ProseMirror [data-type="details"] > div {
+  @apply min-w-0 flex-1;
+}
+
+.ProseMirror [data-type="details"] summary {
+  @apply cursor-pointer font-medium;
+}

package/docs/README.md

@@ -0,0 +1,44 @@
+# @iclips/ui — como usar
+
+Leia isto antes de montar uma tela com a `@iclips/ui`. Os guias abaixo dizem **qual componente usar em cada situação** e trazem código pronto para copiar. Eles vêm no pacote, então descrevem exatamente a versão instalada.
+
+Todo import vem do barrel: `import { Button } from "@iclips/ui"`. Os componentes de edição rica (`DocumentEditor`, `CommentThread`, `EditorialCalendar`, `MentionList`) vêm de `@iclips/ui/editor`. Importe `@iclips/ui/styles.css` uma vez na raiz do app.
+
+## Guias
+
+- [Ações e navegação](acoes.md) — botão, link ou ícone; hierarquia de variantes.
+- [Escolha em lista](escolha.md) — Select, Combobox, RadioGroup, Checkbox, Switch, ToggleGroup.
+- [Formulários](formularios.md) — anatomia do campo, validação, layout, react-hook-form.
+- [Mensagens ao usuário](mensagens.md) — erro de campo, Alert, Toast, AlertDialog.
+- [Overlays](overlays.md) — Tooltip, HoverCard, Popover, Dialog, AlertDialog, Sheet, Drawer.
+- [Status](status.md) — badge de status, valor positivo/negativo.
+- [Linguagem visual](../DESIGN.md) — as quatro camadas de cor, tipografia, raio, botões e superfícies.
+
+## Troque isto por aquilo
+
+As classes cruas da paleta do Tailwind **não geram CSS** na `@iclips/ui` 3.x: o elemento fica sem cor, em silêncio. Use o token semântico ou o componente.
+
+| Em vez de | Use |
+| --- | --- |
+| `text-gray-500` | `text-muted-foreground` |
+| `text-gray-600` | `text-muted-foreground` |
+| `text-gray-900` | `text-foreground` |
+| `border-gray-200` | `border-border` |
+| `border-gray-300` | `border-input` |
+| `text-red-500` | `text-destructive-emphasis` |
+| `text-green-500` | `text-success-emphasis` |
+| `bg-green-50` | `Badge` ou `Alert` com `variant="success"` — ver [Status](status.md) |
+| `bg-orange-100` | `Badge` ou `Alert` com `variant="warning"` — ver [Status](status.md) |
+| `<button>` | `Button` — ver [Ações](acoes.md) |
+| `<input>` | `Input` (ou `NumberInput`, `CurrencyInput`, `DatePicker`, `PasswordInput`) |
+| `<select>` | `Select` (ou `Combobox` para lista longa) — ver [Escolha](escolha.md) |
+
+Para achar cor crua no app: `node node_modules/@iclips/ui/scripts/check-colors.mjs src`.
+
+## Quando não houver guia
+
+1. Procure o componente no barrel antes de montar um na mão. Elemento HTML cru (`<button>`, `<input>`, `<select>`, `<div onClick>`) quase sempre tem equivalente.
+2. Cor sempre por token semântico: `bg-background`, `bg-card`, `bg-muted`, `text-foreground`, `text-muted-foreground`, `border-border`, `bg-primary`. Nunca cor crua da paleta.
+3. Espaçamento e tamanho pela escala (`gap-4`, `p-6`, `max-w-sm`). Nunca valor arbitrário (`p-[13px]`) nem `style={{}}` com valor literal.
+4. Ícones de `lucide-react`.
+5. Estado (erro, sucesso, aviso, informação) segue a receita suave: `bg-<status>/10 text-<status>-emphasis border-<status>/20` — de preferência pelo componente que já a aplica (`Badge`, `Alert`, `Button`).

package/docs/acoes.md

@@ -0,0 +1,103 @@
+# Botão, link ou ícone
+
+A regra de ouro: **link leva a algum lugar** (muda a URL), **botão faz alguma coisa** (dispara uma ação na página). Escolher errado quebra abrir-em-nova-aba, o botão voltar e o leitor de tela.
+
+## Elemento certo
+
+| Elemento | Escolha quando | Evite quando |
+| --- | --- | --- |
+| `<a>` / `<Link>` | o clique navega para outra rota, âncora ou recurso externo. Suporta Ctrl+clique, botão do meio, "copiar link". | o clique só muda estado na tela (abrir modal, submeter, alternar) → `<button>`. |
+| `Button` | dispara uma ação: salvar, abrir overlay, adicionar item, filtrar. É o padrão para quase tudo que não é navegação. | o destino é uma URL → renderize um link (use `asChild`). |
+| `Button variant="link"` | uma ação secundária que precisa parecer texto ("Esqueci a senha", "ver todos") dentro de um parágrafo ou rodapé. | é a ação principal do bloco → `default`/`secondary`. É navegação de verdade → `<a>` estilizado. |
+| `Button size="icon"` | ação repetida numa linha/toolbar onde o texto polui (excluir linha, favoritar). Sempre com `aria-label`. | a ação é rara ou ambígua — aí o texto ajuda. Ou é a ação primária de um formulário. |
+| `SocialButton` | login/conexão com provedor (Google, Facebook…) — já traz ícone e rótulo do provedor. | qualquer outra ação. |
+
+## Hierarquia de variantes
+
+Uma ação primária por bloco. O resto desce na escala.
+
+### Ordem de ênfase
+
+Rótulo em peso 600 (semibold) — no sistema, 600 significa ação. Hover de `outline` e `ghost` é cinza; lavanda fica para selecionado.
+
+```tsx
+import { Button } from "@iclips/ui";
+
+<Button>Primária — salvar, confirmar, criar</Button>
+<Button variant="secondary">Secundária — ação alternativa</Button>
+<Button variant="outline">Terciária — cancelar, voltar</Button>
+<Button variant="ghost">Discreta — em toolbars, dentro de cards</Button>
+<Button variant="link">Link — ação textual inline</Button>
+```
+
+### Semânticas
+
+`destructive` só para remoção/irreversível. `success` é raro — normalmente o `default` basta.
+
+```tsx
+import { Button } from "@iclips/ui";
+import { Trash2 } from "lucide-react";
+
+<Button variant="destructive"><Trash2 /> Excluir</Button>
+<Button variant="success">Aprovar</Button>
+```
+
+### Com ícone
+
+Ícone à esquerda reforça o verbo; à direita sugere avanço/navegação.
+
+```tsx
+import { Button } from "@iclips/ui";
+import { ArrowRight, Download, Plus } from "lucide-react";
+
+<Button><Plus /> Nova campanha</Button>
+<Button variant="outline">Exportar <Download /></Button>
+<Button variant="link">Ver relatório <ArrowRight /></Button>
+```
+
+## Trilha rápida
+
+1. **O clique muda a URL / abre outra página?** Sim: é um link. Renderize `<a>` (ou `<Link>` do router) — via `Button asChild` se quiser o visual de botão. Não: continue.
+2. **É a ação principal deste bloco/formulário?** Sim: `Button variant="default"`. Não: continue.
+3. **Remove ou desfaz algo de forma difícil de reverter?** Sim: `variant="destructive"` + confirmação (ver [Overlays](overlays.md)). Não: continue.
+4. **Está numa linha de tabela / toolbar densa e o verbo é óbvio pelo ícone?** Sim: `size="icon"` + `aria-label`. Não: variant `secondary` / `outline` / `ghost` conforme a ênfase.
+
+## Link com aparência de botão
+
+Quando o destino é uma URL mas o design pede um botão, use `asChild` — o elemento vira `<a>`, o estilo continua.
+
+### asChild
+
+Renderiza `<a href>` com as classes do `Button`. Mantém Ctrl+clique e menu de contexto.
+
+```tsx
+import { Button } from "@iclips/ui";
+import { ArrowRight } from "lucide-react";
+
+<Button asChild>
+  <a href="/projetos/42">Abrir projeto</a>
+</Button>
+<Button asChild variant="outline">
+  <a href="https://iclips.com.br" target="_blank" rel="noreferrer">
+    Site da iClips <ArrowRight />
+  </a>
+</Button>
+```
+
+## Faça / evite
+
+#### Faça
+
+- Comece o rótulo com um verbo: "Salvar alterações", não "OK".
+- Toda ação só-ícone leva `aria-label` com o mesmo verbo que um Tooltip mostraria.
+- Use `isLoading` para travar o botão durante a requisição — ele já seta `aria-busy` e bloqueia o clique.
+- Um `<a>` para navegação mesmo que estilizado como botão — o usuário espera Ctrl+clique.
+
+#### Evite
+
+- `onClick={() => navigate("/rota")}` num `<button>` — quebra abrir em nova aba e o histórico.
+- Dois botões primários lado a lado — o olho não sabe qual é o caminho feliz.
+- `<div onClick>` — sem foco, sem Enter/Espaço, invisível para leitor de tela.
+- `variant="link"` para a ação principal de um formulário.
+
+**Acessibilidade:** o `Button` já traz anel de foco visível, `active:scale` e trata `disabled`. Um link precisa de `href` real para ser focável e anunciado como link — `role="button"` num `<a>` ou vice-versa confunde a tecnologia assistiva. Ícone sem texto *sempre* com `aria-label`.

package/docs/escolha.md

@@ -0,0 +1,171 @@
+# Como o usuário escolhe de uma lista
+
+Duas perguntas resolvem quase tudo: **uma opção ou várias?** e **quantas opções existem** — porque abaixo de ~7 vale mostrar todas, e acima disso é preciso busca.
+
+## Uma única escolha
+
+| Componente | Escolha quando | Evite quando |
+| --- | --- | --- |
+| RadioGroup | 2 a 5 opções que valem ser vistas todas de uma vez, e a escolha é importante (plano, forma de pagamento). | mais de ~6 opções, ou espaço vertical apertado → `Select`. |
+| Select | 6 a ~25 opções conhecidas e curtas (estado, categoria, status). Economiza espaço. | a lista é longa ou o usuário sabe o nome do que quer → `Combobox`. |
+| Combobox | lista longa (>25) ou dinâmica: cidade, cliente, produto. Filtra enquanto digita. | são poucas opções fixas — o campo de busca vira fricção → `Select` ou Radio. |
+| ToggleGroup (single) | 2 a 4 opções mutuamente exclusivas que mudam a visão na hora: alinhamento, período (dia/semana/mês), modo de exibição. | é um dado do formulário a ser submetido, não uma alternância de UI → Radio. |
+
+## Várias escolhas (ou liga/desliga)
+
+| Componente | Escolha quando | Evite quando |
+| --- | --- | --- |
+| Checkbox (grupo) | 2 a ~8 opções independentes visíveis de uma vez: permissões, dias da semana, filtros marcáveis. | a lista é longa → `MultiSelect`. É uma única opção booleana isolada → Checkbox sozinho ou `Switch`. |
+| MultiSelect | escolher vários de uma lista longa: responsáveis, tags, canais. Mostra chips do que foi escolhido + busca. | poucas opções fixas → grupo de Checkbox mostra tudo sem cliques extras. |
+| ToggleGroup (multiple) | conjunto pequeno de formatações/filtros que ligam e desligam juntos: negrito/itálico, tipos de mídia. | opções com rótulos longos, ou muitas → Checkbox. |
+| Checkbox (isolado) | uma afirmação que o usuário aceita ou não: "Aceito os termos", "Lembrar de mim". Faz parte de um envio. | liga um comportamento imediatamente, sem submit → `Switch`. |
+| Switch | liga/desliga uma configuração com efeito imediato: notificações, modo escuro, tema. | o efeito só acontece ao salvar o formulário → Checkbox. |
+
+## Trilha rápida
+
+1. **O usuário pode escolher mais de uma opção?** Sim: poucas e fixas → grupo de `Checkbox`; muitas/dinâmicas → `MultiSelect`. Não: continue.
+2. **É um liga/desliga com efeito imediato (sem salvar)?** Sim: `Switch`. Não: continue.
+3. **A escolha muda a visão da tela na hora (período, layout)?** Sim: `ToggleGroup type="single"`. Não: continue.
+4. **Quantas opções?** Até 5 e importantes → `RadioGroup` · 6 a 25 → `Select` · mais que isso ou dinâmica → `Combobox`.
+
+## Exemplos
+
+Os exemplos usam esta lista:
+
+```tsx
+const canais = [
+  { value: "ig", label: "Instagram" },
+  { value: "fb", label: "Facebook" },
+  { value: "li", label: "LinkedIn" },
+  { value: "tt", label: "TikTok" },
+  { value: "yt", label: "YouTube" },
+];
+```
+
+### RadioGroup — poucas, todas visíveis
+
+```tsx
+import { Label, RadioGroup, RadioGroupItem } from "@iclips/ui";
+
+<RadioGroup defaultValue="anual" className="gap-2">
+  {["mensal", "anual", "vitalício"].map((v) => (
+    <div key={v} className="flex items-center gap-2">
+      <RadioGroupItem value={v} id={`plano-${v}`} />
+      <Label htmlFor={`plano-${v}`} className="capitalize">{v}</Label>
+    </div>
+  ))}
+</RadioGroup>
+```
+
+### Select — lista média conhecida
+
+```tsx
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@iclips/ui";
+
+<Select>
+  <SelectTrigger className="w-56" aria-label="Canal"><SelectValue placeholder="Selecione o canal" /></SelectTrigger>
+  <SelectContent>
+    {canais.map((c) => (
+      <SelectItem key={c.value} value={c.value}>{c.label}</SelectItem>
+    ))}
+  </SelectContent>
+</Select>
+```
+
+### Combobox — busca em lista longa
+
+```tsx
+import { Combobox } from "@iclips/ui";
+
+const [canal, setCanal] = React.useState("");
+
+<Combobox options={canais} value={canal} onValueChange={setCanal} placeholder="Buscar canal" aria-label="Canal" />
+```
+
+### MultiSelect — vários, com chips
+
+```tsx
+import { MultiSelect } from "@iclips/ui";
+
+const [selecionados, setSelecionados] = React.useState<string[]>(["ig"]);
+
+<MultiSelect
+  options={canais}
+  value={selecionados}
+  onValueChange={setSelecionados}
+  placeholder="Canais da campanha"
+  aria-label="Canais da campanha"
+/>
+```
+
+### Checkbox (grupo) — independentes, visíveis
+
+```tsx
+import { Checkbox } from "@iclips/ui";
+
+<div className="space-y-2">
+  {["Ler", "Escrever", "Excluir"].map((p) => (
+    <label key={p} className="flex items-center gap-2 text-sm">
+      <Checkbox defaultChecked={p === "Ler"} /> {p}
+    </label>
+  ))}
+</div>
+```
+
+### Switch — efeito imediato
+
+Muda algo agora. Checkbox seria para um valor a ser salvo.
+
+```tsx
+import { Switch } from "@iclips/ui";
+
+<label className="flex items-center gap-2 text-sm">
+  <Switch defaultChecked /> Notificações por e-mail
+</label>
+```
+
+### ToggleGroup — troca de visão
+
+```tsx
+import { ToggleGroup, ToggleGroupItem } from "@iclips/ui";
+
+<ToggleGroup type="single" defaultValue="semana">
+  <ToggleGroupItem value="dia">Dia</ToggleGroupItem>
+  <ToggleGroupItem value="semana">Semana</ToggleGroupItem>
+  <ToggleGroupItem value="mes">Mês</ToggleGroupItem>
+</ToggleGroup>
+```
+
+## Estados do item: selecionado > focado > sob o cursor
+
+Os três podem coexistir no mesmo item e cada um usa um sinal diferente, para continuarem legíveis empilhados. `Combobox` e `MultiSelect` já seguem essa regra; siga-a em listas próprias.
+
+| Estado | Como se pinta | Por quê |
+| --- | --- | --- |
+| Selecionado | `bg-secondary text-secondary-foreground font-medium` | matiz + tinta + peso: três sinais, sobrevive ao hover por cima. |
+| Focado por teclado | `focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset` | anel, não fundo — sobrevive sobre qualquer fundo. |
+| Sob o cursor | `hover:bg-accent` | cinza, transitório, sem peso. |
+
+Hover e seleção são ambos `bg-*`: quem vence é a ordem do CSS gerado, não a do `className`. Guarde o hover pelo estado (`not-aria-selected:hover:bg-accent`) ou inclua `hover:bg-secondary` na classe de selecionado, para o `cn` descartar o hover conflitante.
+
+### Ilustração estática — os três estados na mesma lista
+
+Numa mesma lista, o item selecionado fica lavanda com peso maior, o focado ganha só o anel e o que está sob o cursor fica cinza — nunca lavanda, que significa selecionado.
+
+## Faça / evite
+
+#### Faça
+
+- Todo controle com `<Label htmlFor>` — clicar no texto ativa o controle.
+- `Combobox` e `MultiSelect` quando a lista vem da API ou passa de ~25 itens.
+- `RadioGroup` com um default sensato já selecionado (evita estado "nada escolhido").
+- `Switch` só para o que aplica na hora; se tem botão "Salvar", é `Checkbox`.
+
+#### Evite
+
+- `Select` com 3 opções — `RadioGroup` mostra as 3 sem um clique a mais.
+- Grupo de `Checkbox` com 40 itens — vira uma parede; use `MultiSelect`.
+- Radio e Checkbox trocados: Radio = uma; Checkbox = zero ou mais.
+- `Combobox` para sim/não.
+
+**Acessibilidade:** `Select`, `Combobox`, `RadioGroup`, `Checkbox` e `Switch` já trazem navegação por seta, Home/End, digitar-para-focar e os papéis ARIA. O `MultiSelect` é custom: ele já trata teclado, mas confirme o `aria-label` quando não houver rótulo visível.

package/docs/formularios.md

@@ -0,0 +1,137 @@
+# Montando um formulário
+
+Um formulário bom é **previsível**: label sempre acima do campo, erro sempre logo abaixo, ação primária sempre no mesmo canto. As decisões abaixo são o que muda de tela pra tela.
+
+## Anatomia de um campo
+
+A ordem é sempre esta, de cima para baixo:
+
+1. **Label** acima, sempre visível (nunca só placeholder).
+2. **Campo**.
+3. **Ajuda** (opcional), ligada por `aria-describedby`.
+4. **Erro** no lugar da ajuda quando houver, com `aria-invalid` no campo.
+
+### Campo completo
+
+```tsx
+import { Input, Label } from "@iclips/ui";
+
+<div className="grid w-full max-w-xs gap-1.5">
+  <Label htmlFor="site">
+    Site <span className="text-muted-foreground">(opcional)</span>
+  </Label>
+  <Input id="site" placeholder="https://" aria-describedby="site-ajuda" />
+  <p id="site-ajuda" className="text-sm text-muted-foreground">
+    Aparece no rodapé das propostas.
+  </p>
+</div>
+```
+
+### Com erro
+
+```tsx
+import { Input, Label } from "@iclips/ui";
+
+<div className="grid w-full max-w-xs gap-1.5">
+  <Label htmlFor="email">E-mail</Label>
+  <Input id="email" defaultValue="ana@" aria-invalid aria-describedby="email-erro" />
+  <p id="email-erro" className="text-sm text-destructive-emphasis">Informe um e-mail válido.</p>
+</div>
+```
+
+## Obrigatório ou opcional?
+
+Marque a minoria. Nunca os dois.
+
+| Caso | Escolha | Evite |
+| --- | --- | --- |
+| maioria obrigatória | marque só os opcionais com "(opcional)" em texto ao lado do label. | asterisco em quase todos os campos — vira ruído e ninguém lê. |
+| maioria opcional | marque os obrigatórios com "*" (ou "obrigatório") e explique o "*" uma vez no topo. | marcar "(opcional)" em 15 campos. |
+
+## Quando é validação inline vs no envio
+
+1. **O erro só pode ser sabido pelo servidor (e-mail já existe, saldo insuficiente)?** Sim: valide no envio (ou no blur com debounce, se a API aguentar). Mostre no campo. Não: continue.
+2. **É formato/obrigatoriedade que dá pra checar no cliente?** Sim: valide no blur (`mode: "onTouched"`) — erra cedo, sem incomodar quem ainda está digitando. Não: continue.
+3. **O formulário é curto (1–3 campos, ex: login)?** Sim: pode validar só no envio — o usuário vê tudo de uma vez. Não: blur + um resumo no topo (`Alert`) ao tentar enviar com erros. Foque o primeiro campo inválido.
+
+## Layout
+
+| Layout | Escolha quando | Evite quando |
+| --- | --- | --- |
+| uma coluna | o padrão. Fluxo de leitura vertical, funciona em qualquer largura, não confunde a ordem de tab. | quase nunca — só saia disso com motivo. |
+| duas colunas | pares que andam juntos e são curtos: cidade/UF, início/fim, DDD/telefone. Agrupe visualmente. | campos longos ou não relacionados lado a lado — a leitura zigue-zagueia. |
+| seções (fieldset) | formulário longo com blocos temáticos: Dados da conta / Endereço / Preferências. Título por bloco. | wizard de várias telas quando tudo cabe numa página com rolagem. |
+
+## Botões de ação
+
+#### Faça
+
+- Ação primária à direita (ou sozinha, largura total no mobile). Uma só.
+- Rótulo com o verbo da ação: "Criar projeto", "Salvar alterações" — não "Enviar" / "OK".
+- Cancelar/Voltar como variante `outline` ou `ghost`, à esquerda da primária.
+- Durante o envio: `isLoading` no botão (trava e mostra spinner) — não um overlay na tela toda.
+
+#### Evite
+
+- Dois botões com o mesmo peso visual (dois primários).
+- "Limpar" ao lado de "Salvar" — o acidente é caro; se precisar, deixe longe e peça confirmação.
+- Desabilitar o botão de envio enquanto há erro — o usuário não descobre o que falta. Deixe habilitado e valide no clique.
+
+## react-hook-form + os componentes
+
+Use `FormField` para amarrar tudo pelos ids certos automaticamente.
+
+### FormField
+
+`FormControl` injeta `id`/`aria-invalid`/`aria-describedby`; `FormMessage` some quando não há erro.
+
+```tsx
+import { useForm } from "react-hook-form";
+import {
+  Button, Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, Input, Textarea,
+} from "@iclips/ui";
+
+type Campos = { nome: string; obs: string };
+
+function NovoProjeto() {
+  const form = useForm<Campos>({ mode: "onTouched", defaultValues: { nome: "", obs: "" } });
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(salvar)} className="grid w-full max-w-sm gap-4" noValidate>
+        <FormField
+          control={form.control}
+          name="nome"
+          rules={{ required: "Informe o nome." }}
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Nome do projeto</FormLabel>
+              <FormControl><Input placeholder="Rebranding Aurora" {...field} /></FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <FormField
+          control={form.control}
+          name="obs"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Observações <span className="text-muted-foreground">(opcional)</span></FormLabel>
+              <FormControl><Textarea rows={3} {...field} /></FormControl>
+              <FormDescription>Visível só para a equipe.</FormDescription>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <div className="flex justify-end gap-2">
+          <Button type="button" variant="outline">Cancelar</Button>
+          <Button type="submit">Criar projeto</Button>
+        </div>
+      </form>
+    </Form>
+  );
+}
+```
+
+**Qual input para cada dado?** Está em [Escolha em lista](escolha.md) (Select vs Combobox vs Radio…). Para valores: `NumberInput`/`CurrencyInput` para números, `DatePicker`/`DateRangePicker` para datas, `PasswordInput` para senha, `InputOTP` para código, `InputGroup` quando o campo tem prefixo/sufixo (R$, .com, botão).
+
+**Acessibilidade:** todo campo com `Label htmlFor` apontando pro `id` — clicar no texto foca o campo e o leitor de tela anuncia o rótulo. `aria-describedby` liga ajuda e erro. Ao enviar com erros, mova o foco para o resumo ou para o primeiro campo inválido.