npm - @celke/kole-react - Versions diffs - 0.4.1 → 0.6.0 - Mend

@celke/kole-react 0.4.1 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (82) hide show

package/LICENSE +22 -22
package/README.md +968 -525
package/dist/components/Avaliacao/Avaliacao.d.ts +1 -1
package/dist/components/Avatar/GrupoAvatares.d.ts +16 -0
package/dist/components/BlocoCodigo/BlocoCodigo.d.ts +15 -0
package/dist/components/BotaoFechar/BotaoFechar.d.ts +1 -1
package/dist/components/Busca/Busca.d.ts +1 -1
package/dist/components/Calendario/Calendario.d.ts +100 -0
package/dist/components/Calendario/MiniCalendario.d.ts +27 -0
package/dist/components/Calendario/datasCalendario.d.ts +27 -0
package/dist/components/Calendario/repetirEvento.d.ts +26 -0
package/dist/components/Campo/Campo.d.ts +1 -0
package/dist/components/CampoBusca/CampoBusca.d.ts +1 -1
package/dist/components/CampoBusca/CampoCidade.d.ts +1 -1
package/dist/components/CampoMensagem/CampoMensagem.d.ts +20 -1
package/dist/components/Carregando/Carregando.d.ts +1 -1
package/dist/components/ChatFlutuante/ChatFlutuante.d.ts +31 -0
package/dist/components/Conversa/Conversa.d.ts +1 -1
package/dist/components/Estrutura/Estrutura.d.ts +13 -2
package/dist/components/Form/Form.d.ts +1 -1
package/dist/components/Girador/Girador.d.ts +1 -1
package/dist/components/Grafico/GraficoRosca.d.ts +31 -0
package/dist/components/Grafico/MolduraGrafico.d.ts +36 -1
package/dist/components/Grafico/escalas.d.ts +3 -0
package/dist/components/InicioConversa/InicioConversa.d.ts +29 -0
package/dist/components/Kanban/CartaoKanban.d.ts +35 -0
package/dist/components/Kanban/Kanban.d.ts +62 -0
package/dist/components/Kanban/Pecas.d.ts +30 -0
package/dist/components/Kanban/tipos.d.ts +35 -0
package/dist/components/ListaCards/ListaCards.d.ts +1 -1
package/dist/components/ListaConversas/ListaConversas.d.ts +40 -0
package/dist/components/ListaTarefas/ListaTarefas.d.ts +52 -0
package/dist/components/Mensagem/Mensagem.d.ts +1 -1
package/dist/components/NavegadorPeriodo/NavegadorPeriodo.d.ts +28 -0
package/dist/components/Picklist/Picklist.d.ts +1 -1
package/dist/components/Preferencias/Preferencias.d.ts +25 -2
package/dist/components/QuadroArrastavel/QuadroArrastavel.d.ts +59 -6
package/dist/components/Referencias/Referencias.d.ts +1 -1
package/dist/components/SeletorContexto/SeletorContexto.d.ts +32 -0
package/dist/components/SeletorIdioma/Bandeira.d.ts +10 -0
package/dist/components/SeletorIdioma/SeletorIdioma.d.ts +23 -0
package/dist/components/Site/CabecalhoSecao.d.ts +18 -0
package/dist/components/Site/CampoPesquisa.d.ts +15 -0
package/dist/components/Site/CardConteudo.d.ts +28 -0
package/dist/components/Site/CardDepoimento.d.ts +14 -0
package/dist/components/Site/CardPlano.d.ts +22 -0
package/dist/components/Site/CardRecurso.d.ts +22 -0
package/dist/components/Site/ConteudoArtigo.d.ts +12 -0
package/dist/components/Site/DestaqueSite.d.ts +27 -0
package/dist/components/Site/EstruturaSite.d.ts +60 -0
package/dist/components/Site/FaixaChamada.d.ts +14 -0
package/dist/components/Site/FaixaNumeros.d.ts +20 -0
package/dist/components/Site/FiltroPilulas.d.ts +17 -0
package/dist/components/Site/ListaNumerada.d.ts +21 -0
package/dist/components/Site/Newsletter.d.ts +16 -0
package/dist/components/Site/SecaoSite.d.ts +15 -0
package/dist/components/Site/SumarioPagina.d.ts +17 -0
package/dist/components/Site/linkSite.d.ts +18 -0
package/dist/components/Tabela/Tabela.d.ts +1 -1
package/dist/components/TelaLogin/TelaLogin.d.ts +1 -1
package/dist/components/Valor/Valor.d.ts +53 -0
package/dist/estilos.css +1 -1
package/dist/i18n/contexto.d.ts +15 -0
package/dist/i18n/en.d.ts +3 -0
package/dist/i18n/es.d.ts +3 -0
package/dist/i18n/idiomas.d.ts +41 -0
package/dist/i18n/pt-BR.d.ts +545 -0
package/dist/i18n/textos.d.ts +17 -0
package/dist/index.d.ts +46 -2
package/dist/index.js +9325 -3670
package/dist/index.js.map +1 -1
package/dist/tailwind.css +96 -82
package/dist/tokens.css +489 -461
package/dist/utils/dinheiro.d.ts +49 -0
package/dist/utils/entidade.d.ts +3 -2
package/dist/utils/periodo.d.ts +36 -0
package/dist/utils/senha.d.ts +2 -1
package/dist/utils/tempo.d.ts +32 -0
package/dist/utils/texto.d.ts +12 -5
package/dist/utils/tiposCampo.d.ts +3 -1
package/dist/utils/validadores.d.ts +4 -2
package/package.json +93 -91

package/README.md CHANGED Viewed

@@ -1,525 +1,968 @@
-# @celke/kole-react
-Biblioteca de componentes **React** para sistemas administrativos. Design tokens
-próprios (cores, raios, densidade, tema claro/escuro), CSS puro e sem dependência
-de Tailwind.
-## Instalação
-```bash
-npm i @celke/kole-react
-```
-Requisitos: React 18.2+ ou 19. A fonte Inter já vem dentro do pacote (o
-`estilos.css` carrega só os alfabetos que a página usa). O pacote é só ESM, traz
-os tipos TypeScript e já vem marcado com `'use client'`, então funciona no App
-Router do Next.js.
-## Uso
-```tsx
-// main.tsx
-import { createRoot } from 'react-dom/client';
-import '@celke/kole-react/estilos.css';
-import { ProvedorUi } from '@celke/kole-react';
-import { App } from './App';
-createRoot(document.getElementById('root')!).render(
-  <ProvedorUi>
-    <App />
-  </ProvedorUi>,
-);
-```
-`ProvedorUi` liga tema/densidade (lembrados no navegador), toasts (`useToast`) e
-confirmação (`useConfirmacao`).
-### Tema sem piscar ao abrir
-O `ProvedorUi` só aplica o tema depois que o React monta, e quem salvou o tema
-escuro vê a página clara piscar por um instante. Para evitar, aplique o tema no
-`<head>`, antes do CSS da página pintar:
-```html
-<!-- index.html -->
-<head>
-  <script>(function(){var p={};try{p=JSON.parse(localStorage.getItem("lp-preferencias")||"{}")||{}}catch(e){}var t=p.tema||"sistema";var h=document.documentElement;h.setAttribute("data-theme",{"claro":"light","escuro":"dark","sistema":"system"}[t]||"light");var d={"compacta":"density-compact","confortavel":"density-comfortable","espacosa":"density-cozy"}[p.densidade||"confortavel"];if(d)h.classList.add(d)})();</script>
-</head>
-```
-Com Content-Security-Policy sem `'unsafe-inline'` em `script-src`, o script
-inline é bloqueado: salve o mesmo conteúdo num arquivo (por exemplo,
-`public/tema.js`) e carregue com `<script src="/tema.js"></script>` no
-`<head>`, sem `type="module"` nem `defer`, para rodar antes da pintura.
-Esse é o resultado de `scriptTemaInicial()`. Com SSR (Next.js, React Router em
-modo framework), gere pela função, com o mesmo `temaInicial`/`densidadeInicial`
-passado ao `ProvedorUi`:
-```tsx
-import { scriptTemaInicial } from '@celke/kole-react';
-<head>
-  <script dangerouslySetInnerHTML={{ __html: scriptTemaInicial({ temaInicial: 'sistema' }) }} />
-</head>
-```
-### Layout com React Router
-```tsx
-import { Link, Outlet, useLocation, useNavigate } from 'react-router-dom';
-import { Estrutura } from '@celke/kole-react';
-export function Layout({ sair }: { sair: () => void }) {
-  const { pathname } = useLocation();
-  const navigate = useNavigate();
-  return (
-    <Estrutura
-      marca={{ nome: 'Gestor', subtitulo: 'Gestão comercial', logo: '/logo.svg' }}
-      nav={[
-        { itens: [{ rotulo: 'Painel', icone: 'house', rota: '/' }] },
-        {
-          rotulo: 'Cadastros',
-          itens: [
-            { rotulo: 'Pedidos', icone: 'shopping-cart', rota: '/pedidos' },
-            { rotulo: 'Tabelas', icone: 'table', filhos: [{ rotulo: 'Categorias', rota: '/categorias' }] },
-          ],
-        },
-      ]}
-      rotaAtual={pathname}
-      aoNavegar={navigate}
-      usuario={{ nome: 'Gabrielly Ribeiro', cargo: 'Gerente comercial' }}
-      menuUsuario={[{ id: 'sair', rotulo: 'Sair', icone: 'log-out', destrutivo: true }]}
-      aoEscolherMenuUsuario={(id) => id === 'sair' && sair()}
-    >
-      <Outlet />
-    </Estrutura>
-  );
-}
-```
-Para links de verdade do roteador (ctrl+clique abre em nova aba), passe
-`renderLink={(p) => <Link to={p.href} className={p.className} onClick={p.onClick} aria-current={p['aria-current']}>{p.children}</Link>}`.
-### Páginas fora do React no mesmo app (Inertia + Blade)
-Num app Laravel com páginas Inertia e páginas Blade, o `<Link>` do Inertia só
-serve para as páginas Inertia. Marque as outras com `recarregar: true`: o link
-vira um `<a>` comum (sem `renderLink` nem `aoNavegar`) e abre com recarga
-completa. Vale para o menu, a busca do menu e a trilha. Se a marca aponta para
-uma página Blade, use `marca={{ …, recarregar: true }}`.
-```tsx
-import { Link, router, usePage } from '@inertiajs/react';
-<Estrutura
-  nav={[
-    {
-      itens: [
-        { rotulo: 'Painel', icone: 'house', rota: '/painel' },                    // Inertia
-        { rotulo: 'Relatórios', icone: 'file-text', rota: '/relatorios', recarregar: true }, // Blade
-      ],
-    },
-  ]}
-  rotaAtual={usePage().url}
-  aoNavegar={(rota) => router.visit(rota)}
-  renderLink={(p) => <Link href={p.href} className={p.className} onClick={p.onClick} aria-current={p['aria-current']}>{p.children}</Link>}
-  …
-/>
-```
-Do Blade para o Inertia não precisa de nada: um link comum abre a página
-Inertia. Para as telas Blade com o mesmo layout, veja o pacote Composer
-[`celke/kole-laravel`](https://github.com/celkecursos/kole-laravel).
-## Componentes
-| Grupo | Componentes |
-|---|---|
-| Layout | `Estrutura`, `Busca`, `CabecalhoPagina`, `BoasVindas`, `TelaLogin`, `Abas`/`Aba`, `Card` |
-| Ações | `Botao`, `AcaoLinha`, `Dica` |
-| Formulário | `Form` (página ou modal, `entidade`/`modo`), `FormSecao`, `Campo`, `CampoTexto`, `CampoTextarea`, `CampoSenha`, `CampoSelect`, `CampoSelectMultiplo`, `CampoMarcacao`, `Escolha`, `Picklist`, `Filtros` |
-| Campos prontos | `CampoCpf`, `CampoCnpj`, `CampoCpfCnpj`, `CampoCep`, `CampoTelefone`, `CampoPlaca`, `CampoRenavam`, `CampoChassi`, `CampoCnh`, `CampoImei`, `CampoEmail`, `CampoData`, `CampoHora`, `CampoDataHora`, `CampoMoeda`, `CampoInteiro`, `CampoUf`, `CampoUfMultiplo`, `CampoTipoPessoa` |
-| Busca remota | `CampoBusca`, `CampoCidade`, `useBuscaAssincrona` |
-| Arquivos | `CampoAnexo`, `VisualizadorArquivo`, `DialogoArquivo`, `Foto` |
-| Dados | `Tabela`, `ListaCards`, `Paginacao`, `Indicador`/`Indicadores`, `Detalhes`, `Status`, `Chip`, `Avatar`, `Placa` |
-| Feedback | `Alerta`, `Dialogo` (central ou `lateral`), `useConfirmacao` (+ `.remover()`, `.avisar()`), `useToast`, `Vazio`, `Skeleton`, `Carregando` |
-| Conversa | `Conversa`, `Mensagem`, `CampoMensagem`, `Referencias` |
-| Gráficos | `GraficoLinha`, `GraficoBarras`, `GraficoCombinado`, `GraficoDispersao`, `MapaCalor`, `Minigrafico` (e `tendencia` no `Indicador`), `regressaoLinear` |
-### Conversa (chat)
-`Conversa` é a área rolável (acompanha o fim durante o streaming e para de
-puxar se a pessoa rolar para cima); `Mensagem` é a bolha; `CampoMensagem` é o
-campo de envio (Enter envia, Shift+Enter quebra a linha); `Referencias` lista
-as fontes de uma resposta. A conversa ocupa a altura do contêiner pai, e a
-busca da resposta (rede, streaming, Markdown) fica com o app.
-```tsx
-import { useState } from 'react';
-import {
-  CampoMensagem,
-  Conversa,
-  Mensagem,
-  Referencias,
-  type AutorMensagem,
-  type EstadoMensagem,
-  type ItemReferencia,
-} from '@celke/kole-react';
-interface ItemChat {
-  id: string;
-  autor: AutorMensagem;
-  estado: EstadoMensagem;
-  texto: string;
-  hora: Date;
-  fontes?: ItemReferencia[]; // { id, titulo, detalhe?, trecho?, href? }
-}
-interface ChatProps {
-  mensagens: ItemChat[];
-  gerando: boolean;
-  enviar: (texto: string) => void;
-  parar: () => void;
-}
-export function Chat({ mensagens, gerando, enviar, parar }: ChatProps) {
-  const [texto, setTexto] = useState('');
-  return (
-    <div style={{ height: '32rem' }}>
-      <Conversa
-        campo={
-          <CampoMensagem
-            valor={texto}
-            aoMudar={setTexto}
-            aoEnviar={(t) => {
-              enviar(t);
-              setTexto('');
-            }}
-            gerando={gerando}
-            aoParar={parar}
-          />
-        }
-      >
-        {mensagens.map((m) => (
-          <Mensagem
-            key={m.id}
-            autor={m.autor} // 'usuario' | 'assistente' | 'sistema'
-            estado={m.estado} // 'enviando' | 'gerando' | 'concluida' | 'erro'
-            hora={m.hora}
-            copiavel={m.autor === 'assistente'}
-            rodape={m.fontes && <Referencias itens={m.fontes} />}
-          >
-            {m.texto}
-          </Mensagem>
-        ))}
-      </Conversa>
-    </div>
-  );
-}
-```
-### Gráficos
-Desenhados em SVG próprio, sem biblioteca de gráficos. A largura
-acompanha o container (o desenho é refeito no tamanho novo, sem esticar o texto),
-os números e as datas saem em pt-BR (`1.234,5`, `jan/21`) e as cores vêm dos
-tokens `--graf-*`, então funcionam nos temas claro, escuro e sistema.
-Comum a todos: `titulo` (obrigatório; vira o nome acessível), `descricao` (resumo
-para leitor de tela), `altura` (padrão `280` px), `legenda` (padrão `true`; clicar
-esconde ou mostra a série), `carregando`, `textoVazio` e `verDados` (padrão
-`true`; alterna entre o gráfico e uma `Tabela` com os mesmos valores, o caminho
-completo para quem não enxerga o gráfico). Passe o mouse, toque ou foque o
-gráfico e use as setas do teclado: uma caixa mostra o valor de cada série. `null`
-é "sem dado": falha na linha, barra ausente, célula hachurada, nunca zero.
-**Animação** (`animacao`, padrão `false`): na entrada, as linhas se desenham da
-esquerda para a direita, as barras crescem a partir do zero e os pontos e as
-células surgem; rótulos e referências chegam depois. É só CSS e roda uma vez,
-quando o gráfico aparece: dados que chegam depois (atualização periódica, por
-exemplo) não reiniciam a animação. Com "reduzir movimento" ligado no sistema
-(`prefers-reduced-motion`), nada se mexe. O `Indicador` também aceita `animacao`
-para o minigráfico da `tendencia`. Prefira deixar desligado em painéis abertos
-todo dia: a animação ajuda em apresentações, mas atrasa a leitura.
-```tsx
-import {
-  GraficoBarras,
-  GraficoCombinado,
-  GraficoDispersao,
-  GraficoLinha,
-  Indicador,
-  MapaCalor,
-  regressaoLinear,
-} from '@celke/kole-react';
-const reais = (v: number) => v.toLocaleString('pt-BR', { style: 'currency', currency: 'BRL', maximumFractionDigits: 0 });
-// séries no tempo: faixa sombreada no eixo X e linha de referência
-<GraficoLinha
-  titulo="Faturamento mensal"
-  dados={[{ mes: '2025-10', valor: 248000 }, { mes: '2025-11', valor: null }, { mes: '2025-12', valor: 342000 }]}
-  eixoX={{ chave: 'mes', tipo: 'data' }}
-  eixoY={{ rotulo: 'Faturamento', formatar: reais }}
-  series={[{ chave: 'valor', rotulo: 'Faturamento' }]}
-  area
-  faixas={[{ de: '2025-11', ate: '2025-12', rotulo: 'Fim de ano' }]}
-  referencias={[{ valor: 260000, rotulo: 'Média mensal' }]}
-/>;
-// barras: várias séries ficam agrupadas; `divergente` pinta acima e abaixo de zero;
-// `orientacao="horizontal"` serve para rankings (rótulo longo quebra em duas linhas)
-<GraficoBarras
-  titulo="Faturamento acima ou abaixo da meta"
-  dados={[{ mes: '2026-05', diferenca: -12 }, { mes: '2026-06', diferenca: 8.5 }]}
-  eixoX={{ chave: 'mes', tipo: 'data' }}
-  eixoY={{ unidade: 'mil R$' }}
-  series={[{ chave: 'diferenca', rotulo: 'Diferença para a meta' }]}
-  divergente
-/>;
-// dois eixos: a legenda diz o eixo de cada série ("Ticket médio (R$, eixo direito)")
-<GraficoCombinado
-  titulo="Pedidos e ticket médio"
-  dados={[{ mes: '2026-05', pedidos: 1420, ticket: 198.4 }, { mes: '2026-06', pedidos: 1510, ticket: 203.1 }]}
-  eixoX={{ chave: 'mes', tipo: 'data' }}
-  eixoY={{ rotulo: 'Pedidos' }}
-  eixoYDireito={{ rotulo: 'Ticket médio', unidade: 'R$' }}
-  barras={[{ chave: 'pedidos', rotulo: 'Pedidos' }]}
-  linhas={[{ chave: 'ticket', rotulo: 'Ticket médio' }]}
-/>;
-// um ponto por item; `regressao` desenha a reta e mostra r, r² e n
-<GraficoDispersao
-  titulo="Preço × unidades vendidas"
-  dados={produtos} // [{ produto: 'Café torrado — 500 g', preco: 18.9, unidades: 610, promocao: false }, …]
-  eixoX={{ rotulo: 'Preço', unidade: 'R$' }}
-  eixoY={{ rotulo: 'Unidades vendidas' }}
-  chaveX="preco"
-  chaveY="unidades"
-  chaveRotulo="produto"
-  chaveDestaque="promocao"
-  regressao
-  nota="Estatísticas a mais (como o p-valor) são calculadas pelo app."
-/>;
-// grade de células (ex.: hora × dia da semana); com muitas linhas, rola com os rótulos das colunas presos no topo
-<MapaCalor
-  titulo="Pedidos por hora e dia da semana"
-  linhas={['08h', '09h']}
-  colunas={['seg', 'ter']}
-  valores={[{ linha: '08h', coluna: 'seg', valor: 72 }, { linha: '08h', coluna: 'ter', valor: null }]}
-  unidade="pedidos"
-/>;
-// minigráfico abaixo do valor, na cor do indicador
-<Indicador rotulo="Pedidos em junho" valor={1510} cor="var(--graf-3)" tendencia={[1180, 1240, 1320, 1290, 1420, 1510]} />;
-// a mesma conta da dispersão, para usar no app: { inclinacao, intercepto, r, r2, n } ou null
-const reta = regressaoLinear([{ x: 4.99, y: 880 }, { x: 18.9, y: 610 }, { x: 39.9, y: 190 }]);
-```
-Tipos do eixo X: `categoria` (texto, uma faixa por item), `data` (`Date`,
-timestamp ou texto `aaaa-mm-dd`/`aaaa-mm`; o rótulo se ajusta a dados diários,
-mensais ou anuais) e `numero`. Os rótulos do eixo X nunca se sobrepõem: se não
-couberem, aparece um a cada N. `eixo.formatar` troca o formato dos números
-(eixo, caixa de detalhes e tabela).
-Tokens (definidos nos dois temas; redefina no CSS do app para mudar a paleta):
-| Token | Uso |
-|---|---|
-| `--graf-1` a `--graf-6` | Cores das séries, nessa ordem (contraste de 3:1 ou mais contra `--surface`) |
-| `--graf-pos` / `--graf-neg` | Barras divergentes, acima e abaixo de zero |
-| `--graf-seq-1` a `--graf-seq-5` | Escala do mapa de calor, do valor mais baixo ao mais alto |
-| `--graf-grade`, `--graf-eixo`, `--graf-texto` | Linhas de grade, eixos e rótulos |
-| `--graf-faixa` | Faixa sombreada de destaque |
-**Volume de pontos:** cada gráfico é fluido até cerca de 2.000 pontos. Séries
-maiores devem chegar agregadas (por exemplo, os pedidos de anos somados por mês
-em vez de um ponto por pedido, ou o mapa de calor em vez de uma linha só).
-Utilitários (lógica pura, também exportados): validadores BR (`isCpf`, `isCnpj`,
-`isCnh`, `isImei`, `validar(tipo, valor)`…), `TIPOS_CAMPO` (máscara +
-placeholder + regra por tipo), `ESTADOS`/`TIPOS_PESSOA`, por extenso
-(`numeroPorExtenso`, `valorMonetarioPorExtenso`, `listaPorExtenso`), texto
-(`normalizar`, `nomeProprio`, `nomeCurto`, `iniciais`, `formatCpfCnpj`), datas
-pt-BR (`parseDataBr`, `formatDataBr`…), `tituloDeEntidade`/`nomeDeArquivo`,
-anexos (`formatBytes`, `tipoDeArquivo`, `iconeArquivo`), senha
-(`validarSenha`, `forcaSenha`), picklist, JWT (`decodificarJwt`, `jwtExpirado`…)
-e `severidadeCor`. A demo do repositório tem uma página interativa de cada um
-(`#/utilitarios`).
-Convenções:
-- Campos são controlados por `valor` + `aoMudar`; aceitam `rotulo`, `dica`,
-  `erro`, `aviso`, `obrigatorio` e `variante="inline"` (pílula com rótulo dentro,
-  para barras de filtro).
-- Severidades: `ok`, `info`, `warn`, `err`, `neutral` (botão: `pri`, `secundario`,
-  `ok`, `warn`, `err`).
-- Ícones: [Lucide](https://lucide.dev/icons) (SVG, já incluso no pacote). Passe o
-  nome (`icone="save"`, `icone="trash-2"`) ou o componente
-  (`import { Rocket } from 'lucide-react'` → `icone={<Rocket />}`). Só os ícones
-  registrados entram no bundle; para usar outro pelo nome, registre uma vez:
-  `registrarIcones({ rocket: Rocket })`. Um nome não registrado avisa no console
-  em desenvolvimento.
-- Pendência de campo: o erro aparece ao **sair** do campo depois de digitar, ou
-  quando o `Form` tenta salvar (todos os campos acusam). Um valor carregado de
-  fora que não atende ao formato não é recusado: vira aviso âmbar.
-- Grade do `FormSecao`: 4 colunas na página, 3 no modal; `className="lp-col-2"`,
-  `lp-col-3` ou `lp-col-full` alarga o campo.
-- Cadastro com vários formulários: passe `menu` (itens com `id`, `rotulo`,
-  `icone`, `href`) e `menuAtivo` ao `Form` de cada página; o menu lateral liga
-  os formulários entre si, cada um com o próprio Salvar.
-## Tema e tokens
-Toda cor/medida vem de variáveis CSS (os tokens). Para mudar a marca, redefina
-os tokens no CSS do app (a ordem dos imports não importa, veja [CSS](#css)) — por exemplo
-`--navy` (marinho da sidebar), `--pri` (azul de ação) e `--acento-claro` (laranja
-do item ativo). O tema escuro tem valores próprios, então redefina lá também:
-```css
-:root {
-  --pri: #0f766e;
-  --pri-ink: #115e59;
-}
-[data-theme='dark'] {
-  --pri: #2dd4bf;
-  --pri-ink: #5eead4;
-}
-```
-O tema vem do atributo `data-theme` no `<html>`: `light`, `dark` ou `system`
-(segue o modo do sistema operacional, inclusive se ele mudar com a página
-aberta). No `ProvedorUi`, são os temas `claro`, `escuro` e `sistema`
-(`temaInicial`, `definirTema`). Enquanto a pessoa não escolhe, vale o
-`temaInicial`, e sem ele o `sistema`. `escuro` no `usePreferencias()` diz o que
-está na tela. A densidade usa as classes `density-compact`, `density-comfortable` e
-`density-cozy` no `<body>`. O `ProvedorUi` cuida de tudo isso. A lista
-completa de tokens, com os valores dos dois temas, está em
-`@celke/kole-react/tokens.css`.
-Para usar só os tokens fora do React: `@import '@celke/kole-react/tokens.css';`
-e `<html data-theme="system">` (ou `light`/`dark`) para escolher o tema sem JS.
-## CSS
-Classes CSS usam o prefixo `lp-`, e todo o CSS da biblioteca fica na camada
-`@layer kole`. CSS fora de camada sempre vence CSS em camada, então o CSS do
-app personaliza o kole sem disputar especificidade nem depender da ordem dos
-imports. O lado oposto: uma regra global do app (`a { color: … }`,
-`h1 { font-size: … }`) também atinge os componentes, por isso escope as regras
-de elemento do app (por exemplo, `.conteudo-artigo h1`).
-### Com Tailwind 4
-A ordem das camadas precisa ser declarada **antes** de qualquer CSS, então o
-CSS do app (com o Tailwind) é importado antes do `estilos.css`:
-```css
-/* app.css — esta linha vem antes do @import do Tailwind */
-@layer theme, base, kole, components, utilities;
-@import 'tailwindcss';
-@import '@celke/kole-react/tailwind.css'; /* opcional: a ponte abaixo */
-```
-```tsx
-// main.tsx
-import './app.css';
-import '@celke/kole-react/estilos.css';
-```
-Assim o kole vence o preflight do Tailwind (botões e campos mantêm o estilo) e
-os utilitários vencem o kole (`<Botao className="mt-4" />` funciona). Se o
-`estilos.css` vier primeiro, a camada `kole` fica abaixo do preflight e os
-componentes perdem o estilo.
-A ponte `@celke/kole-react/tailwind.css` faz duas coisas:
-- o `dark:` do Tailwind segue o tema do kole (`data-theme`), e não o do sistema
-  operacional, então uma tela com os dois não fica metade clara e metade escura;
-- os tokens viram utilitários com o mesmo nome: `bg-surface`, `text-ink`,
-  `text-t3`, `border-border`, `bg-pri`, `text-ok-fg`, `bg-err-bg`,
-  `rounded-card`, `rounded-pill`… Como apontam para os tokens, trocam de tema
-  junto com o kole. `font-sans` e `font-mono` passam a ser as fontes do kole.
-A densidade não chega aos utilitários: `p-4` e `h-10` são fixos, só os
-componentes `lp-*` mudam com ela.
-## Desenvolvimento
-```bash
-npm install
-npm run dev          # http://localhost:5173 — demo com todos os componentes
-npm run typecheck
-npm run build        # dist/index.js + tipos (.d.ts) + dist/estilos.css + dist/tokens.css + dist/tailwind.css
-```
-A demo usa o mesmo CSS do pacote (na camada `kole`, com o tema `sistema`), e o
-`demo/demo.css` fica fora da camada, como o CSS de um app.
-### Teste visual
-Captura cada página do menu da demo (`demo/nav.ts`) nos temas claro e escuro e
-compara pixel a pixel com uma referência. Também confere que o tema `sistema`,
-com o sistema operacional no escuro, sai igual ao tema escuro. Página nova no
-menu entra no teste sozinha.
-O print muda de um sistema operacional para outro, então a referência fica em
-`tests/visual/__referencia__/<sistema>/`. Só a de Linux vai para o git: é a que
-o CI usa (`.github/workflows/visual.yml`, na imagem Docker do Playwright), em
-todo PR e na `main`.
-**Mudança visual de propósito:** o CI do PR vai falhar apontando as páginas que
-mudaram (o relatório com as diferenças fica nos artefatos do workflow). Confira
-e grave a referência nova: Actions → Teste visual → Run workflow, na branch do
-PR, com "atualizar" marcado. O workflow faz o commit da referência na branch.
-No Windows ou no macOS, o teste usa uma referência local, fora do git:
-```bash
-npx playwright install chromium   # uma vez
-npm run visual:referencia         # ANTES de mexer no CSS: grava a referência
-npm run visual                    # depois: aponta cada página que mudou
-npx playwright show-report        # diferenças lado a lado
-```
-Para comparar com uma versão já publicada, sirva a demo dela noutra porta (por
-exemplo, num `git worktree` da tag) e gere a referência com
-`KOLE_URL=http://localhost:5181 npm run visual:referencia`.
-Para testar uma versão que ainda não está no npm, instale direto do GitHub
-(o `prepare` gera o `dist/` na instalação) ou de um pacote local:
-```bash
-npm i github:celkecursos/kole-react
-# ou: gere o .tgz na pasta da biblioteca e instale no app
-npm pack                                   # → celke-kole-react-<versão>.tgz
-npm i ../kole-react/celke-kole-react-<versão>.tgz
-```
-Evite `npm i ../kole-react` (pasta): o npm cria um link e o bundler
-pega o React do `node_modules` da biblioteca — dois Reacts no app quebram os hooks
-(_Invalid hook call_). Se precisar do link durante o desenvolvimento, use
-`resolve: { dedupe: ['react', 'react-dom'] }` no `vite.config` do app.
-Publicar uma versão nova: `npm version patch` (só correção) ou `npm version minor`
-(muda a aparência ou a API — antes da 1.0, o `^0.x` dos apps não pega a minor
-sozinho), registre no [CHANGELOG](CHANGELOG.md) e confira o conteúdo com
-`npm pack --dry-run`. Depois do merge na `main`, publique pelo GitHub: Actions →
-Publicar → Run workflow (`.github/workflows/publish.yml`). O npm confia nesse
-workflow pela publicação confiável (Trusted Publisher, sem token) e o pacote
-sai com o atestado de procedência. O workflow só deixa a versão em espera
-(`npm stage publish`): ela vai ao ar depois que um mantenedor aprova com o
-segundo fator, com `npm stage list @celke/kole-react` e `npm stage approve <id>`
-(ou pelo site do npm). O workflow recusa versão que já está no npm.
-## Autor
-Criado por **Cesar Szpak**.
-## Licença
-MIT © 2026 Celke — veja o arquivo [LICENSE](https://github.com/celkecursos/kole-react/blob/main/LICENSE).
+# @celke/kole-react
+Biblioteca de componentes **React** para sistemas administrativos. Design tokens
+próprios (cores, raios, densidade, tema claro/escuro), CSS puro e sem dependência
+de Tailwind.
+## Instalação
+```bash
+npm i @celke/kole-react
+```
+Requisitos: React 18.2+ ou 19. A fonte Inter já vem dentro do pacote (o
+`estilos.css` carrega só os alfabetos que a página usa). O pacote é só ESM, traz
+os tipos TypeScript e já vem marcado com `'use client'`, então funciona no App
+Router do Next.js.
+## Uso
+```tsx
+// main.tsx
+import { createRoot } from 'react-dom/client';
+import '@celke/kole-react/estilos.css';
+import { ProvedorUi } from '@celke/kole-react';
+import { App } from './App';
+createRoot(document.getElementById('root')!).render(
+  <ProvedorUi>
+    <App />
+  </ProvedorUi>,
+);
+```
+`ProvedorUi` liga tema/densidade (lembrados no navegador), toasts (`useToast`) e
+confirmação (`useConfirmacao`).
+### Idioma
+Os textos da própria biblioteca saem em português do Brasil (padrão), inglês ou
+espanhol. Ligue o seletor na topbar com `idiomas` e sincronize o i18n do seu
+sistema em `aoMudarIdioma` (chamado ao montar e a cada troca). A biblioteca não
+traduz os textos do sistema: ela só informa o idioma escolhido.
+```tsx
+<ProvedorUi idiomaInicial={usuario.locale} aoMudarIdioma={(idioma) => i18n.changeLanguage(idioma)}>
+  <Estrutura idiomas={['pt-BR', 'en', 'es']} {...props}>…</Estrutura>
+</ProvedorUi>
+```
+Prioridade dos textos: prop passada > dicionário do idioma > pt-BR. Para trocar
+um texto ou acrescentar um idioma, passe `textos` ao provedor
+(`{ 'pt-BR': { tabela: { rotulo: 'Lista' } } }`). Regras brasileiras (máscaras e
+validação de CPF, CNPJ, CEP e telefone) e a moeda não mudam com o idioma; só a
+formatação e as mensagens. A demo traz a página Idioma com os exemplos de
+react-i18next e Laravel.
+### Tema sem piscar ao abrir
+O `ProvedorUi` só aplica o tema depois que o React monta, e quem salvou o tema
+escuro vê a página clara piscar por um instante. Para evitar, aplique o tema no
+`<head>`, antes do CSS da página pintar:
+```html
+<!-- index.html -->
+<head>
+  <script>(function(){var p={};try{p=JSON.parse(localStorage.getItem("lp-preferencias")||"{}")||{}}catch(e){}var t=p.tema||"sistema";var h=document.documentElement;h.setAttribute("data-theme",{"claro":"light","escuro":"dark","sistema":"system"}[t]||"light");var l=p.idioma||"";if(l)h.lang=l;var d={"compacta":"density-compact","confortavel":"density-comfortable","espacosa":"density-cozy"}[p.densidade||"confortavel"];if(d)h.classList.add(d)})();</script>
+</head>
+```
+Com Content-Security-Policy sem `'unsafe-inline'` em `script-src`, o script
+inline é bloqueado: salve o mesmo conteúdo num arquivo (por exemplo,
+`public/tema.js`) e carregue com `<script src="/tema.js"></script>` no
+`<head>`, sem `type="module"` nem `defer`, para rodar antes da pintura.
+Esse é o resultado de `scriptTemaInicial()`. Com SSR (Next.js, React Router em
+modo framework), gere pela função, com o mesmo `temaInicial`/`densidadeInicial`
+passado ao `ProvedorUi`:
+```tsx
+import { scriptTemaInicial } from '@celke/kole-react';
+<head>
+  <script dangerouslySetInnerHTML={{ __html: scriptTemaInicial({ temaInicial: 'sistema' }) }} />
+</head>
+```
+### Layout com React Router
+```tsx
+import { Link, Outlet, useLocation, useNavigate } from 'react-router-dom';
+import { Estrutura } from '@celke/kole-react';
+export function Layout({ sair }: { sair: () => void }) {
+  const { pathname } = useLocation();
+  const navigate = useNavigate();
+  return (
+    <Estrutura
+      marca={{ nome: 'Gestor', subtitulo: 'Gestão comercial', logo: '/logo.svg' }}
+      nav={[
+        { itens: [{ rotulo: 'Painel', icone: 'house', rota: '/' }] },
+        {
+          rotulo: 'Cadastros',
+          itens: [
+            { rotulo: 'Pedidos', icone: 'shopping-cart', rota: '/pedidos' },
+            { rotulo: 'Tabelas', icone: 'table', filhos: [{ rotulo: 'Categorias', rota: '/categorias' }] },
+          ],
+        },
+      ]}
+      rotaAtual={pathname}
+      aoNavegar={navigate}
+      usuario={{ nome: 'Gabrielly Ribeiro', cargo: 'Gerente comercial' }}
+      menuUsuario={[{ id: 'sair', rotulo: 'Sair', icone: 'log-out', destrutivo: true }]}
+      aoEscolherMenuUsuario={(id) => id === 'sair' && sair()}
+    >
+      <Outlet />
+    </Estrutura>
+  );
+}
+```
+Para links de verdade do roteador (ctrl+clique abre em nova aba), passe
+`renderLink={(p) => <Link to={p.href} className={p.className} onClick={p.onClick} aria-current={p['aria-current']}>{p.children}</Link>}`.
+### Páginas fora do React no mesmo app (Inertia + Blade)
+Num app Laravel com páginas Inertia e páginas Blade, o `<Link>` do Inertia só
+serve para as páginas Inertia. Marque as outras com `recarregar: true`: o link
+vira um `<a>` comum (sem `renderLink` nem `aoNavegar`) e abre com recarga
+completa. Vale para o menu, a busca do menu e a trilha. Se a marca aponta para
+uma página Blade, use `marca={{ …, recarregar: true }}`.
+```tsx
+import { Link, router, usePage } from '@inertiajs/react';
+<Estrutura
+  nav={[
+    {
+      itens: [
+        { rotulo: 'Painel', icone: 'house', rota: '/painel' },                    // Inertia
+        { rotulo: 'Relatórios', icone: 'file-text', rota: '/relatorios', recarregar: true }, // Blade
+      ],
+    },
+  ]}
+  rotaAtual={usePage().url}
+  aoNavegar={(rota) => router.visit(rota)}
+  renderLink={(p) => <Link href={p.href} className={p.className} onClick={p.onClick} aria-current={p['aria-current']}>{p.children}</Link>}
+  …
+/>
+```
+Do Blade para o Inertia não precisa de nada: um link comum abre a página
+Inertia. Para as telas Blade com o mesmo layout, veja o pacote Composer
+[`celke/kole-laravel`](https://github.com/celkecursos/kole-laravel).
+## Componentes
+| Grupo | Componentes |
+|---|---|
+| Layout | `Estrutura`, `Busca`, `CabecalhoPagina`, `BoasVindas`, `TelaLogin`, `Abas`/`Aba`, `Card` |
+| Ações | `Botao`, `AcaoLinha`, `Dica` |
+| Formulário | `Form` (página ou modal, `entidade`/`modo`), `FormSecao`, `Campo`, `CampoTexto`, `CampoTextarea`, `CampoSenha`, `CampoSelect`, `CampoSelectMultiplo`, `CampoMarcacao`, `Escolha`, `Picklist`, `Filtros` |
+| Campos prontos | `CampoCpf`, `CampoCnpj`, `CampoCpfCnpj`, `CampoCep`, `CampoTelefone`, `CampoPlaca`, `CampoRenavam`, `CampoChassi`, `CampoCnh`, `CampoImei`, `CampoEmail`, `CampoData`, `CampoHora`, `CampoDataHora`, `CampoMoeda`, `CampoInteiro`, `CampoUf`, `CampoUfMultiplo`, `CampoTipoPessoa` |
+| Busca remota | `CampoBusca`, `CampoCidade`, `useBuscaAssincrona` |
+| Arquivos | `CampoAnexo`, `VisualizadorArquivo`, `DialogoArquivo`, `Foto` |
+| Dados | `Tabela`, `ListaCards`, `Paginacao`, `Indicador`/`Indicadores`, `Detalhes`, `Status`, `Chip`, `Avatar`, `GrupoAvatares`, `Placa` |
+| Feedback | `Alerta`, `Dialogo` (central ou `lateral`), `useConfirmacao` (+ `.remover()`, `.avisar()`), `useToast`, `Vazio`, `Skeleton`, `Carregando` |
+| Conversa | `Conversa`, `Mensagem`, `CampoMensagem`, `Referencias`, `ListaConversas`, `InicioConversa`, `BlocoCodigo`, `ChatFlutuante` |
+| Site público | `EstruturaSite`, `RodapeSite`, `SecaoSite`, `DestaqueSite`, `CabecalhoSecao`, `CampoPesquisa`, `CardConteudo`, `CardRecurso`, `CardDepoimento`, `CardPlano`, `FaixaNumeros`, `FaixaChamada`, `ListaNumerada`, `FiltroPilulas`, `ConteudoArtigo`, `SumarioPagina`, `Newsletter` |
+| Calendário | `Calendario` (visões mês, semana, dia e lista, com arrastar), `MiniCalendario`, `repetirEvento` |
+| Kanban e tarefas | `Kanban`, `CartaoKanban`, `ListaTarefas`, `QuadroArrastavel`, `SeloPrioridade`, `SeloPrazo`, `Etiqueta`, `tempoRelativo`, `situacaoPrazo` |
+| Gráficos | `GraficoLinha`, `GraficoBarras`, `GraficoCombinado`, `GraficoDispersao`, `GraficoRosca`, `MapaCalor`, `Minigrafico` (e `tendencia` no `Indicador`), `regressaoLinear` |
+| Idioma | `SeletorIdioma`, `Bandeira`, `useTextos`, `useIdioma`, `textosPtBR`, `textosEn`, `textosEs`, `interpolar`, `pluralizar` (e `idiomas` na `Estrutura`) |
+| Finanças | `Valor`, `ProvedorValores`, `BotaoOcultarValores`, `NavegadorPeriodo`, `SeletorContexto`, `formatarMoeda`, `formatarPercentual`, `dividirEmParcelas`, `periodoDe`, `noPeriodo` |
+### Conversa (chat)
+`Conversa` é a área rolável (acompanha o fim durante o streaming e para de
+puxar se a pessoa rolar para cima); `Mensagem` é a bolha; `CampoMensagem` é o
+campo de envio (Enter envia, Shift+Enter quebra a linha); `Referencias` lista
+as fontes de uma resposta. A conversa ocupa a altura do contêiner pai, e a
+busca da resposta (rede, streaming, Markdown) fica com o app.
+```tsx
+import { useState } from 'react';
+import {
+  CampoMensagem,
+  Conversa,
+  Mensagem,
+  Referencias,
+  type AutorMensagem,
+  type EstadoMensagem,
+  type ItemReferencia,
+} from '@celke/kole-react';
+interface ItemChat {
+  id: string;
+  autor: AutorMensagem;
+  estado: EstadoMensagem;
+  texto: string;
+  hora: Date;
+  fontes?: ItemReferencia[]; // { id, titulo, detalhe?, trecho?, href? }
+}
+interface ChatProps {
+  mensagens: ItemChat[];
+  gerando: boolean;
+  enviar: (texto: string) => void;
+  parar: () => void;
+}
+export function Chat({ mensagens, gerando, enviar, parar }: ChatProps) {
+  const [texto, setTexto] = useState('');
+  return (
+    <div style={{ height: '32rem' }}>
+      <Conversa
+        campo={
+          <CampoMensagem
+            valor={texto}
+            aoMudar={setTexto}
+            aoEnviar={(t) => {
+              enviar(t);
+              setTexto('');
+            }}
+            gerando={gerando}
+            aoParar={parar}
+          />
+        }
+      >
+        {mensagens.map((m) => (
+          <Mensagem
+            key={m.id}
+            autor={m.autor} // 'usuario' | 'assistente' | 'sistema'
+            estado={m.estado} // 'enviando' | 'gerando' | 'concluida' | 'erro'
+            hora={m.hora}
+            copiavel={m.autor === 'assistente'}
+            rodape={m.fontes && <Referencias itens={m.fontes} />}
+          >
+            {m.texto}
+          </Mensagem>
+        ))}
+      </Conversa>
+    </div>
+  );
+}
+```
+#### Assistente de IA
+A demo tem a página modelo **Assistente** (Advanced UI): histórico ao lado,
+tela inicial com sugestões, anexos, ferramentas, seletor de modo e respostas com
+tabela e código. As peças:
+- `ListaConversas`: histórico agrupado por data (Fixadas, Hoje, Ontem, Últimos 7
+  dias, Últimos 30 dias e os meses), busca sem acento, renomear no próprio item
+  (Enter salva, Esc cancela), fixar e excluir. Ocupa a altura do pai.
+- `InicioConversa`: saudação e sugestões, no `vazio` da `Conversa`. Em painel
+  estreito, `aparencia="pilulas"`.
+- `CampoMensagem` com `anexos` (chips com `progresso` e `erro`), `aoRemoverAnexo`
+  e `aoAdicionarArquivos` (arrastar para o campo ou colar). Com anexos, dá para
+  enviar sem texto; enquanto um anexo sobe, o Enviar espera.
+- `BlocoCodigo`: código com a linguagem e o botão de copiar. A `Mensagem` já
+  estiliza o Markdown renderizado pelo app (listas, tabelas, citações).
+```tsx
+import ReactMarkdown from 'react-markdown';
+import { BlocoCodigo, InicioConversa, ListaConversas, type AnexoMensagem } from '@celke/kole-react';
+<ListaConversas
+  itens={conversas} // { id, titulo, data, fixada? }
+  ativa={ativa}
+  aoEscolher={setAtiva}
+  aoNova={() => setAtiva(null)}
+  aoRenomear={(id, titulo) => api.renomear(id, titulo)}
+  aoExcluir={(id) => api.excluir(id)}
+/>;
+<Conversa
+  vazio={<InicioConversa titulo="Como posso ajudar?" sugestoes={[{ titulo: 'Resumir as vendas do mês', icone: 'chart-line' }]} aoEscolher={(s) => enviar(s.titulo)} />}
+  campo={<CampoMensagem valor={texto} aoMudar={setTexto} aoEnviar={enviar} anexos={anexos} aoRemoverAnexo={remover} aoAdicionarArquivos={subir} />}
+>
+  {mensagens.map((m) => (
+    <Mensagem key={m.id} autor={m.autor} estado={m.estado}>
+      <ReactMarkdown
+        components={{
+          code: ({ className, children }) =>
+            className ? <BlocoCodigo linguagem={className.replace('language-', '')} codigo={String(children).trimEnd()} /> : <code>{children}</code>,
+        }}
+      >
+        {m.texto}
+      </ReactMarkdown>
+    </Mensagem>
+  ))}
+</Conversa>;
+```
+A chamada à API (streaming), o histórico salvo, o envio dos anexos e o
+Markdown ficam com o app.
+#### Chat flutuante (site)
+`ChatFlutuante` é o atendimento de site: botão fixo no canto ("Fale com a
+gente", com `naoLidas`) que abre um painel com a conversa. Esc fecha e o foco
+volta ao botão; no celular, o painel ocupa a tela. As páginas modelo do site da
+demo já trazem um, com as perguntas frequentes como sugestões.
+```tsx
+<ChatFlutuante titulo="Fale com a gente" subtitulo="Respondemos em poucos minutos" naoLidas={1}>
+  <Conversa
+    vazio={<InicioConversa aparencia="pilulas" titulo="Olá! Como podemos ajudar?" sugestoes={faq} aoEscolher={(s) => enviar(s.titulo)} />}
+    campo={<CampoMensagem valor={texto} aoMudar={setTexto} aoEnviar={enviar} />}
+  >
+    {mensagens}
+  </Conversa>
+</ChatFlutuante>
+```
+### Site público
+Para a parte aberta do sistema (site institucional, loja, portal) há uma moldura
+própria, sem o menu lateral: `EstruturaSite`, com barra de aviso opcional,
+cabeçalho fixo (marca, menu horizontal, botão de tema e as `acoes`), conteúdo e
+`RodapeSite`. No celular, o menu vai para um painel aberto pelo botão Menu. Os
+links são `<a href>` de verdade: dentro da `EstruturaSite`, os cartões, as listas e
+a `Trilha` navegam pelo `aoNavegar`/`renderLink` do app, e Ctrl+clique ou o botão
+do meio abrem em nova aba. A demo tem as páginas modelo de um site genérico (menu
+**Site**): Home (faixa escura ou clara), Sobre, Serviços e planos, Blog, Post (sem
+e com coluna lateral), Contato e as páginas legais (Termos de uso, Política de Privacidade e Política de
+Cookies, com texto de exemplo a ser revisado por um advogado).
+```tsx
+import { Link, Outlet, useLocation } from 'react-router-dom';
+import {
+  Botao,
+  CabecalhoSecao,
+  CardConteudo,
+  CardDepoimento,
+  CardPlano,
+  CardRecurso,
+  DestaqueSite,
+  EstruturaSite,
+  FaixaChamada,
+  FaixaNumeros,
+  ListaNumerada,
+  Newsletter,
+  RodapeSite,
+  SecaoSite,
+} from '@celke/kole-react';
+export function LayoutSite() {
+  const { pathname } = useLocation();
+  return (
+    <EstruturaSite
+      marca={{ nome: 'Sua Marca', href: '/', logo: '/logo.svg' }}
+      nav={[
+        { rotulo: 'Home', rota: '/' },
+        { rotulo: 'Serviços', rota: '/servicos' },
+        { rotulo: 'Contato', rota: '/contato' },
+      ]}
+      rotaAtual={pathname}
+      renderLink={(p) => (
+        <Link to={p.href} className={p.className} onClick={p.onClick} aria-current={p['aria-current']}>
+          {p.children}
+        </Link>
+      )}
+      aviso={<><b>Novidade:</b> conheça a nova versão.</>}
+      acoes={<Botao rotulo="Fale conosco" />}
+      rodape={
+        <RodapeSite
+          nome="Sua Marca"
+          descricao="O que a empresa faz e para quem."
+          extra={<Newsletter aparencia="linha" rotuloBotao="Assinar" aoInscrever={async (email) => { /* envie ao servidor */ }} />}
+          colunas={[{ titulo: 'Navegação', links: [{ rotulo: 'Serviços', rota: '/servicos' }] }]}
+          copyright="© 2026 Sua Marca"
+          redes={[{ rotulo: 'Instagram', rota: 'https://instagram.com/suamarca' }]}
+        />
+      }
+    >
+      <Outlet />
+    </EstruturaSite>
+  );
+}
+export function Home() {
+  return (
+    <>
+      {/* aparencia="claro" centraliza o texto e põe a `midia` embaixo */}
+      <DestaqueSite selo="Seu slogan" titulo="Uma frase forte sobre o seu negócio." realce="negócio" lateral={<img src="/produto.png" alt="" />}>
+        <Botao rotulo="Começar agora" severidade="destaque" tamanho="grande" />
+        <FaixaNumeros aparencia="simples" itens={[{ valor: '+1.200', rotulo: 'clientes' }]} />
+      </DestaqueSite>
+      <SecaoSite>
+        <CabecalhoSecao sobretitulo="Diferenciais" titulo="Por que escolher a Sua Marca" />
+        <CardRecurso icone="shield" titulo="Seguro e confiável">Garantias e cuidados com o cliente.</CardRecurso>
+        <ListaNumerada itens={[{ titulo: 'Contato inicial', descricao: 'O cliente conta o que precisa.' }]} />
+        <FaixaNumeros itens={[{ valor: '98', sufixo: '%', rotulo: 'de satisfação' }]} />
+        <CardDepoimento texto="O atendimento foi rápido e o resultado veio." nome="Nome do Cliente" cargo="Cargo · Empresa" />
+        <CardConteudo href="/blog/post" midia={<img src="/post.jpg" alt="" />} titulo="Título do post" />
+        <CardPlano nome="Profissional" preco="99" periodo="/mês" itens={['Suporte prioritário']} destaque acao={<Botao rotulo="Assinar" bloco />} />
+        <FaixaChamada titulo="Pronto para começar?" acoes={<Botao rotulo="Solicitar contato" severidade="destaque" />} />
+      </SecaoSite>
+    </>
+  );
+}
+```
+`CardConteudo` tem cinco formatos: `vertical` (grade de posts), `destaque`,
+`horizontal` (post em destaque), `compacto` e `linha` (listagem com quadro à
+direita). `CardRecurso` serve para diferenciais, serviços (`formato="horizontal"`),
+valores (`numero`) e canais de contato (`sobretitulo`). `ConteudoArtigo` estiliza o
+texto de posts e páginas como termos de uso; HTML vindo de Markdown deve chegar
+sanitizado. `SumarioPagina` lista as seções de uma página longa (pelo `id` dos
+títulos), marca a seção em leitura e rola até ela sem trocar o endereço, então
+funciona também em app com rotas no `#hash`. `Newsletter` confere o e-mail antes de chamar `aoInscrever`. Para
+perguntas frequentes, use o `Acordeao` (`icone="mais"`).
+Tokens próprios do site: `--site-largura`, `--r-site`, `--r-site-2`,
+`--sombra-site`, `--fs-site-hero`, `--fs-site-titulo`, `--fs-site-secao` e os tons
+sobre o marinho (`--site-escuro-*`). A cor de ação é o `--pri` de sempre: para a cor
+da marca do cliente, redefina `--pri`, `--pri-ink`, `--pri-bg` e `--pri-bd` (veja
+"Tema e tokens").
+### Calendário
+`Calendario` mostra eventos na visão **mês** (grade de 6 semanas, hoje em
+destaque, até `maxPorDia` eventos por dia e "+N mais", que abre a lista do dia),
+nas visões **semana** e **dia** (faixa de horários de `horaInicio` a `horaFim`,
+eventos posicionados pela hora, os que se sobrepõem lado a lado, faixa de dia
+inteiro no topo e a linha vermelha do "agora") e na visão **lista** (eventos
+agrupados por dia, a melhor no celular). O app guarda
+e busca os eventos: o componente avisa o período visível em `aoMudarPeriodo` e os
+cliques em `aoClicarDia` (ex.: criar evento) e `aoClicarEvento`.
+```tsx
+import { Calendario, type EventoCalendario } from '@celke/kole-react';
+const eventos: EventoCalendario[] = [
+  { id: 1, titulo: 'Reunião de vendas', inicio: new Date(2026, 10, 9, 8, 30), fim: new Date(2026, 10, 9, 9, 30), cor: 'pri', categoria: 'Reunião' },
+  { id: 2, titulo: 'Promoção de Pix', inicio: new Date(2026, 10, 12), fim: new Date(2026, 10, 18), diaInteiro: true, cor: 'graf-2' },
+];
+<Calendario
+  eventos={eventos}
+  inicioSemana={1} // 0 = domingo (padrão), 1 = segunda
+  aoMudarPeriodo={({ inicio, fim }) => {
+    /* buscar os eventos de [inicio, fim) */
+  }}
+  aoClicarDia={(dia) => {
+    /* abrir o formulário de novo evento */
+  }}
+  aoClicarEvento={(evento) => {
+    /* abrir o evento */
+  }}
+  horaInicio={7} // semana e dia: faixa de horários (padrão 7h às 21h)
+  horaFim={21}
+  aoClicarHorario={(dataHora) => {
+    /* semana e dia: clique num horário vazio, arredondado para a meia hora */
+  }}
+/>;
+```
+Cores do evento pelos tokens: `pri`, `ok`, `warn`, `err`, `info`, `destaque` e
+`graf-1` a `graf-6`. Teclado na visão mês: setas andam pelos dias, Home/End vão
+ao começo e ao fim da semana, Page Up/Down trocam de mês e Enter equivale ao
+clique no dia. Na semana e no dia, um cursor de 30 minutos: ↑/↓ mudam o horário,
+←/→ o dia (passando para a semana ou o dia vizinho), Home/End vão ao primeiro e
+ao último horário e Enter chama `aoClicarHorario` (sem ele, abre o evento daquele
+horário). O leitor de tela ouve o dia, a hora e os eventos do horário. `visoes` escolhe quais visões aparecem na barra (padrão: as quatro).
+#### Arrastar e esticar
+Com `aoAlterarEvento`, o evento é arrastado para outro dia (mês e faixa de dia
+inteiro) ou horário (semana e dia, de 15 em 15 minutos), e a borda de baixo do
+bloco estica a duração. No toque, segure o evento antes de arrastar; Esc cancela.
+Pelo teclado, Alt+setas movem (←/→ um dia; ↑/↓ uma semana no mês ou 15 minutos na
+semana e no dia) e Alt+Shift+↑/↓ esticam. O calendário só avisa: o app grava e
+devolve a lista nova em `eventos`. `fixo: true` trava um evento.
+```tsx
+<Calendario
+  eventos={eventos}
+  aoAlterarEvento={(evento, { inicio, fim, tipo }) => {
+    // tipo: 'mover' (mesma duração) ou 'esticar' (só o fim mudou)
+    setEventos((l) => l.map((e) => (e.id === evento.id ? { ...e, inicio, fim } : e)));
+  }}
+/>
+```
+#### Cadastrar: intervalo e rascunho
+Na semana e no dia, `aoSelecionarHorario` recebe `{ inicio, fim }`: arrastar sobre
+horários vazios escolhe o intervalo (de 15 em 15 minutos) e um clique escolhe a
+meia hora. No cursor do teclado, Shift+↑/↓ aumentam o intervalo e Enter
+confirma. Com ele, o clique na faixa de horários não chama o `aoClicarHorario`.
+Abra o formulário do app e passe os dados em `rascunho`: o evento aparece
+tracejado, em qualquer visão, enquanto o formulário está aberto.
+```tsx
+const [novo, setNovo] = useState<{ inicio: Date; fim: Date; titulo: string } | null>(null);
+<Calendario
+  eventos={eventos}
+  aoSelecionarHorario={({ inicio, fim }) => setNovo({ inicio, fim, titulo: '' })}
+  rascunho={novo} // { inicio, fim?, titulo?, cor?, diaInteiro? }
+/>;
+```
+O formulário fica no app (cada sistema tem seus campos). A documentação da demo
+traz um pronto para copiar, com título, categoria, dia inteiro, data, horários,
+"Repete" e excluir só um dia ou a série toda.
+#### Eventos que se repetem
+A série fica no app (o evento base e a regra), e `repetirEvento` calcula as
+ocorrências do período visível. Cada ocorrência ganha `id` `"<id>@aaaa-mm-dd"`,
+`repete: true` (ícone de repetição) e `serie` com o id da base. Mensal no dia 31
+pula os meses sem esse dia.
+```tsx
+import { repetirEvento, type PeriodoCalendario } from '@celke/kole-react';
+const [periodo, setPeriodo] = useState<PeriodoCalendario | null>(null);
+const ocorrencias = periodo
+  ? repetirEvento(
+      { id: 'vendas', titulo: 'Reunião de vendas', inicio: new Date(2026, 10, 2, 9), fim: new Date(2026, 10, 2, 10) },
+      { frequencia: 'semanal', diasSemana: [1, 4], ate: new Date(2026, 11, 31), excecoes: [new Date(2026, 10, 19)] },
+      periodo,
+    )
+  : [];
+<Calendario eventos={[...ocorrencias, ...avulsos]} aoMudarPeriodo={setPeriodo} />;
+```
+Regra: `frequencia` (`diaria`, `semanal`, `mensal`, `anual`), `intervalo` (a cada
+N), `diasSemana` (semanal, `0` = domingo), `ate`, `vezes` e `excecoes` (dias que a
+série pula). Para mudar só uma ocorrência arrastada, ponha o dia dela em
+`excecoes` e crie um evento avulso com o horário novo.
+#### MiniCalendario
+Mês pequeno para a coluna lateral: escolhe o dia, mostra bolinhas nos dias com
+evento e destaca a semana visível. Ligue o dia escolhido à prop `data` do
+`Calendario`, que leva a agenda até ele.
+```tsx
+<MiniCalendario
+  valor={dia}
+  aoEscolher={setDia}
+  marcados={diasComEvento} // Date[]
+  destaque={periodo} // { inicio, fim } com fim exclusivo, ex.: a semana do Calendario
+  aoMudarMes={(mes) => {
+    /* buscar os marcados do mês */
+  }}
+/>
+<Calendario eventos={eventos} data={dia} aoMudarPeriodo={setPeriodo} />
+```
+No celular, a semana mostra os eventos como faixas de cor; use dia ou lista para
+ler os títulos.
+### Kanban e tarefas
+`Kanban` é o quadro pronto: colunas com cor, contagem, `limite` de cartões e
+menu (renomear, recolher, excluir), cartões que se arrastam entre colunas (mouse,
+toque e teclado), "Adicionar cartão", "Adicionar coluna", rolagem horizontal e
+tela vazia. Cada ação aparece quando o callback dela é passado. Durante o
+arraste o quadro mostra uma prévia; ao soltar, `aoMudar` recebe as colunas e
+`aoSoltar` o movimento, que é o que o servidor precisa para gravar.
+```tsx
+import { CartaoKanban, Kanban, type ColunaKanban } from '@celke/kole-react';
+const [colunas, setColunas] = useState<ColunaKanban<Cartao>[]>(inicial);
+<Kanban
+  colunas={colunas}
+  aoMudar={setColunas}
+  aoSoltar={({ item, de, para }) => api.moverCartao(item.id, para.coluna, para.indice)}
+  aoSoltarColuna={({ colunas }) => api.ordenarColunas(colunas.map((c) => c.id))} // liga o arraste das colunas
+  filtro={busca ? (c) => c.titulo.includes(busca) : undefined} // esconde sem tirar do lugar
+  nomeItem={(c) => c.titulo}
+  renderCartao={(c, alca) => (
+    <CartaoKanban
+      titulo={c.titulo}
+      etiquetas={c.etiquetas}
+      prioridade={c.prioridade} // 'baixa' | 'media' | 'alta' | 'critica'
+      vencimento={c.vencimento} // 'AAAA-MM-DD': atrasado, hoje, em breve
+      subtarefas={{ feitas: 2, total: 5 }}
+      responsaveis={c.pessoas}
+      alca={alca}
+      aoAbrir={() => abrirDetalhe(c)}
+    />
+  )}
+  aoAdicionarCartao={(colunaId, titulo) => criarCartao(colunaId, titulo)}
+  aoAdicionarColuna={(titulo) => criarColuna(titulo)}
+  aoRenomearColuna={renomear}
+  aoRecolherColuna={recolher}
+  aoExcluirColuna={async (id) => (await confirmar.remover()) && excluir(id)}
+/>
+```
+`ListaTarefas` mostra tarefas em linhas: marcar como feita (`aoConcluir`),
+situação, prioridade, prazo, etiquetas e responsáveis; `aoReordenar` liga o
+arraste e recebe a lista na ordem nova; `filtro` faz as visões (hoje,
+atrasadas, uma lista) sem perder a ordem das escondidas.
+Os dois são montados sobre o `QuadroArrastavel`, que também serve sozinho:
+`layout="faixa"`, `podeSoltar` (regra de destino), `visivel`,
+`colunasArrastaveis` e rolagem automática perto das bordas. A demo traz as telas
+completas em Aplicativos › Kanban (listagem de quadros, quadro com filtros e
+detalhe do cartão) e Aplicativos › Tarefas.
+### Finanças
+`Valor` mostra dinheiro com o sentido certo: guarde o valor sempre positivo e
+diga o `tipo` (`receita` em verde com `+`, `despesa` em vermelho com `−`,
+`neutro` para transferência). Dentro de um `ProvedorValores`, o
+`BotaoOcultarValores` esconde todos de uma vez, como nos apps de banco.
+```tsx
+import { BotaoOcultarValores, NavegadorPeriodo, ProvedorValores, Valor, periodoDe } from '@celke/kole-react';
+const [periodo, setPeriodo] = useState(() => periodoDe('mes')); // { tipo, de: 'AAAA-MM-DD', ate }
+<ProvedorValores chave="financas-ocultos">
+  <NavegadorPeriodo valor={periodo} aoMudar={setPeriodo} /> {/* ‹ Novembro de 2026 › */}
+  <BotaoOcultarValores />
+  <Valor valor={2200} tipo="despesa" forte /> {/* −R$ 2.200,00 */}
+</ProvedorValores>
+```
+`GraficoRosca` faz o "despesas por categoria" (com `maxFatias` e `aoEscolher`
+para abrir os lançamentos da fatia) e o `SeletorContexto`, na prop `contexto`
+da `Estrutura`, troca o sistema inteiro entre pessoal e empresa (ou filiais).
+`formatarMoeda`, `dividirEmParcelas` e `somarMoeda` cuidam do sinal de menos,
+dos centavos das parcelas e do erro de ponto flutuante. A demo traz a solução
+completa em Soluções › Finanças.
+### Gráficos
+Desenhados em SVG próprio, sem biblioteca de gráficos. A largura
+acompanha o container (o desenho é refeito no tamanho novo, sem esticar o texto),
+os números e as datas saem em pt-BR (`1.234,5`, `jan/21`) e as cores vêm dos
+tokens `--graf-*`, então funcionam nos temas claro, escuro e sistema.
+Comum a todos: `titulo` (obrigatório; vira o nome acessível), `descricao` (resumo
+para leitor de tela), `altura` (padrão `280` px), `legenda` (padrão `true`; clicar
+esconde ou mostra a série), `carregando`, `textoVazio` e `verDados` (padrão
+`true`; alterna entre o gráfico e uma `Tabela` com os mesmos valores, o caminho
+completo para quem não enxerga o gráfico). Passe o mouse, toque ou foque o
+gráfico e use as setas do teclado: uma caixa mostra o valor de cada série. `null`
+é "sem dado": falha na linha, barra ausente, célula hachurada, nunca zero.
+**Animação** (`animacao`, padrão `false`): na entrada, as linhas se desenham da
+esquerda para a direita, as barras crescem a partir do zero e os pontos e as
+células surgem; rótulos e referências chegam depois. É só CSS e roda uma vez,
+quando o gráfico aparece: dados que chegam depois (atualização periódica, por
+exemplo) não reiniciam a animação. Com "reduzir movimento" ligado no sistema
+(`prefers-reduced-motion`), nada se mexe. O `Indicador` também aceita `animacao`
+para o minigráfico da `tendencia`. Prefira deixar desligado em painéis abertos
+todo dia: a animação ajuda em apresentações, mas atrasa a leitura.
+```tsx
+import {
+  GraficoBarras,
+  GraficoCombinado,
+  GraficoDispersao,
+  GraficoLinha,
+  Indicador,
+  MapaCalor,
+  regressaoLinear,
+} from '@celke/kole-react';
+const reais = (v: number) => v.toLocaleString('pt-BR', { style: 'currency', currency: 'BRL', maximumFractionDigits: 0 });
+// séries no tempo: faixa sombreada no eixo X e linha de referência
+<GraficoLinha
+  titulo="Faturamento mensal"
+  dados={[{ mes: '2025-10', valor: 248000 }, { mes: '2025-11', valor: null }, { mes: '2025-12', valor: 342000 }]}
+  eixoX={{ chave: 'mes', tipo: 'data' }}
+  eixoY={{ rotulo: 'Faturamento', formatar: reais }}
+  series={[{ chave: 'valor', rotulo: 'Faturamento' }]}
+  area
+  faixas={[{ de: '2025-11', ate: '2025-12', rotulo: 'Fim de ano' }]}
+  referencias={[{ valor: 260000, rotulo: 'Média mensal' }]}
+/>;
+// barras: várias séries ficam agrupadas; `divergente` pinta acima e abaixo de zero;
+// `orientacao="horizontal"` serve para rankings (rótulo longo quebra em duas linhas)
+<GraficoBarras
+  titulo="Faturamento acima ou abaixo da meta"
+  dados={[{ mes: '2026-05', diferenca: -12 }, { mes: '2026-06', diferenca: 8.5 }]}
+  eixoX={{ chave: 'mes', tipo: 'data' }}
+  eixoY={{ unidade: 'mil R$' }}
+  series={[{ chave: 'diferenca', rotulo: 'Diferença para a meta' }]}
+  divergente
+/>;
+// dois eixos: a legenda diz o eixo de cada série ("Ticket médio (R$, eixo direito)")
+<GraficoCombinado
+  titulo="Pedidos e ticket médio"
+  dados={[{ mes: '2026-05', pedidos: 1420, ticket: 198.4 }, { mes: '2026-06', pedidos: 1510, ticket: 203.1 }]}
+  eixoX={{ chave: 'mes', tipo: 'data' }}
+  eixoY={{ rotulo: 'Pedidos' }}
+  eixoYDireito={{ rotulo: 'Ticket médio', unidade: 'R$' }}
+  barras={[{ chave: 'pedidos', rotulo: 'Pedidos' }]}
+  linhas={[{ chave: 'ticket', rotulo: 'Ticket médio' }]}
+/>;
+// um ponto por item; `regressao` desenha a reta e mostra r, r² e n
+<GraficoDispersao
+  titulo="Preço × unidades vendidas"
+  dados={produtos} // [{ produto: 'Café torrado — 500 g', preco: 18.9, unidades: 610, promocao: false }, …]
+  eixoX={{ rotulo: 'Preço', unidade: 'R$' }}
+  eixoY={{ rotulo: 'Unidades vendidas' }}
+  chaveX="preco"
+  chaveY="unidades"
+  chaveRotulo="produto"
+  chaveDestaque="promocao"
+  regressao
+  nota="Estatísticas a mais (como o p-valor) são calculadas pelo app."
+/>;
+// grade de células (ex.: hora × dia da semana); com muitas linhas, rola com os rótulos das colunas presos no topo
+<MapaCalor
+  titulo="Pedidos por hora e dia da semana"
+  linhas={['08h', '09h']}
+  colunas={['seg', 'ter']}
+  valores={[{ linha: '08h', coluna: 'seg', valor: 72 }, { linha: '08h', coluna: 'ter', valor: null }]}
+  unidade="pedidos"
+/>;
+// minigráfico abaixo do valor, na cor do indicador
+<Indicador rotulo="Pedidos em junho" valor={1510} cor="var(--graf-3)" tendencia={[1180, 1240, 1320, 1290, 1420, 1510]} />;
+// a mesma conta da dispersão, para usar no app: { inclinacao, intercepto, r, r2, n } ou null
+const reta = regressaoLinear([{ x: 4.99, y: 880 }, { x: 18.9, y: 610 }, { x: 39.9, y: 190 }]);
+```
+Tipos do eixo X: `categoria` (texto, uma faixa por item), `data` (`Date`,
+timestamp ou texto `aaaa-mm-dd`/`aaaa-mm`; o rótulo se ajusta a dados diários,
+mensais ou anuais) e `numero`. Os rótulos do eixo X nunca se sobrepõem: se não
+couberem, aparece um a cada N. `eixo.formatar` troca o formato dos números
+(eixo, caixa de detalhes e tabela).
+Tokens (definidos nos dois temas; redefina no CSS do app para mudar a paleta):
+| Token | Uso |
+|---|---|
+| `--graf-1` a `--graf-6` | Cores das séries, nessa ordem (contraste de 3:1 ou mais contra `--surface`) |
+| `--graf-pos` / `--graf-neg` | Barras divergentes, acima e abaixo de zero |
+| `--graf-seq-1` a `--graf-seq-5` | Escala do mapa de calor, do valor mais baixo ao mais alto |
+| `--graf-grade`, `--graf-eixo`, `--graf-texto` | Linhas de grade, eixos e rótulos |
+| `--graf-faixa` | Faixa sombreada de destaque |
+**Volume de pontos:** cada gráfico é fluido até cerca de 2.000 pontos. Séries
+maiores devem chegar agregadas (por exemplo, os pedidos de anos somados por mês
+em vez de um ponto por pedido, ou o mapa de calor em vez de uma linha só).
+Utilitários (lógica pura, também exportados): validadores BR (`isCpf`, `isCnpj`,
+`isCnh`, `isImei`, `validar(tipo, valor)`…), `TIPOS_CAMPO` (máscara +
+placeholder + regra por tipo), `ESTADOS`/`TIPOS_PESSOA`, por extenso
+(`numeroPorExtenso`, `valorMonetarioPorExtenso`, `listaPorExtenso`), texto
+(`normalizar`, `nomeProprio`, `nomeCurto`, `iniciais`, `formatCpfCnpj`), datas
+pt-BR (`parseDataBr`, `formatDataBr`…), `tituloDeEntidade`/`nomeDeArquivo`,
+anexos (`formatBytes`, `tipoDeArquivo`, `iconeArquivo`), senha
+(`validarSenha`, `forcaSenha`), picklist, JWT (`decodificarJwt`, `jwtExpirado`…)
+e `severidadeCor`. A demo do repositório tem uma página interativa de cada um
+(`#/utilitarios`).
+Convenções:
+- Campos são controlados por `valor` + `aoMudar`; aceitam `rotulo`, `dica`,
+  `erro`, `aviso`, `obrigatorio` e `variante="inline"` (pílula com rótulo dentro,
+  para barras de filtro).
+- Severidades: `ok`, `info`, `warn`, `err`, `neutral` (botão: `pri`, `secundario`,
+  `ok`, `warn`, `err`).
+- Ícones: [Lucide](https://lucide.dev/icons) (SVG, já incluso no pacote). Passe o
+  nome (`icone="save"`, `icone="trash-2"`) ou o componente
+  (`import { Rocket } from 'lucide-react'` → `icone={<Rocket />}`). Só os ícones
+  registrados entram no bundle; para usar outro pelo nome, registre uma vez:
+  `registrarIcones({ rocket: Rocket })`. Um nome não registrado avisa no console
+  em desenvolvimento.
+- Pendência de campo: o erro aparece ao **sair** do campo depois de digitar, ou
+  quando o `Form` tenta salvar (todos os campos acusam). Um valor carregado de
+  fora que não atende ao formato não é recusado: vira aviso âmbar.
+- Grade do `FormSecao`: 4 colunas na página, 3 no modal; `className="lp-col-2"`,
+  `lp-col-3` ou `lp-col-full` alarga o campo.
+- Cadastro com vários formulários: passe `menu` (itens com `id`, `rotulo`,
+  `icone`, `href`) e `menuAtivo` ao `Form` de cada página; o menu lateral liga
+  os formulários entre si, cada um com o próprio Salvar.
+## Tema e tokens
+Toda cor/medida vem de variáveis CSS (os tokens). Para mudar a marca, redefina
+os tokens no CSS do app (a ordem dos imports não importa, veja [CSS](#css)) — por exemplo
+`--navy` (marinho da sidebar), `--pri` (azul de ação) e `--acento-claro` (laranja
+do item ativo). O tema escuro tem valores próprios, então redefina lá também:
+```css
+:root {
+  --pri: #0f766e;
+  --pri-ink: #115e59;
+}
+[data-theme='dark'] {
+  --pri: #2dd4bf;
+  --pri-ink: #5eead4;
+}
+```
+O tema vem do atributo `data-theme` no `<html>`: `light`, `dark` ou `system`
+(segue o modo do sistema operacional, inclusive se ele mudar com a página
+aberta). No `ProvedorUi`, são os temas `claro`, `escuro` e `sistema`
+(`temaInicial`, `definirTema`). Enquanto a pessoa não escolhe, vale o
+`temaInicial`, e sem ele o `sistema`. `escuro` no `usePreferencias()` diz o que
+está na tela. A densidade usa as classes `density-compact`, `density-comfortable` e
+`density-cozy` no `<body>`. O `ProvedorUi` cuida de tudo isso. A lista
+completa de tokens, com os valores dos dois temas, está em
+`@celke/kole-react/tokens.css`.
+Para usar só os tokens fora do React: `@import '@celke/kole-react/tokens.css';`
+e `<html data-theme="system">` (ou `light`/`dark`) para escolher o tema sem JS.
+## CSS
+Classes CSS usam o prefixo `lp-`, e todo o CSS da biblioteca fica na camada
+`@layer kole`. CSS fora de camada sempre vence CSS em camada, então o CSS do
+app personaliza o kole sem disputar especificidade nem depender da ordem dos
+imports. O lado oposto: uma regra global do app (`a { color: … }`,
+`h1 { font-size: … }`) também atinge os componentes, por isso escope as regras
+de elemento do app (por exemplo, `.conteudo-artigo h1`).
+### Com Tailwind 4
+A ordem das camadas precisa ser declarada **antes** de qualquer CSS, então o
+CSS do app (com o Tailwind) é importado antes do `estilos.css`:
+```css
+/* app.css — esta linha vem antes do @import do Tailwind */
+@layer theme, base, kole, components, utilities;
+@import 'tailwindcss';
+@import '@celke/kole-react/tailwind.css'; /* opcional: a ponte abaixo */
+```
+```tsx
+// main.tsx
+import './app.css';
+import '@celke/kole-react/estilos.css';
+```
+Assim o kole vence o preflight do Tailwind (botões e campos mantêm o estilo) e
+os utilitários vencem o kole (`<Botao className="mt-4" />` funciona). Se o
+`estilos.css` vier primeiro, a camada `kole` fica abaixo do preflight e os
+componentes perdem o estilo.
+A ponte `@celke/kole-react/tailwind.css` faz duas coisas:
+- o `dark:` do Tailwind segue o tema do kole (`data-theme`), e não o do sistema
+  operacional, então uma tela com os dois não fica metade clara e metade escura;
+- os tokens viram utilitários com o mesmo nome: `bg-surface`, `text-ink`,
+  `text-t3`, `border-border`, `bg-pri`, `text-ok-fg`, `bg-err-bg`,
+  `rounded-card`, `rounded-pill`… Como apontam para os tokens, trocam de tema
+  junto com o kole. `font-sans` e `font-mono` passam a ser as fontes do kole.
+  Para o site público: `max-w-site`, `rounded-site`, `rounded-site-2`,
+  `shadow-site`, `text-site-hero`, `text-site-titulo`, `text-site-secao` e, sobre
+  o marinho, `bg-navy text-site-escuro-t3`.
+A densidade não chega aos utilitários: `p-4` e `h-10` são fixos, só os
+componentes `lp-*` mudam com ela.
+Vale igual para o site e para o sistema: os componentes de site (`EstruturaSite`,
+`DestaqueSite`…) estão no mesmo `estilos.css`, na mesma camada `kole`, então
+`<SecaoSite className="mt-8" />` funciona e o preflight não desfaz o estilo deles.
+## Desenvolvimento
+```bash
+npm install
+npm run dev          # http://localhost:5173 — demo com todos os componentes
+npm run typecheck
+npm run build        # dist/index.js + tipos (.d.ts) + dist/estilos.css + dist/tokens.css + dist/tailwind.css
+```
+A demo usa o mesmo CSS do pacote (na camada `kole`, com o tema `sistema`), e o
+`demo/demo.css` fica fora da camada, como o CSS de um app.
+### Documentação
+A demo tem a seção **Documentação** (`/#/docs/...`): Instalação, Tema e tokens,
+Tailwind, Carregamento, Changelog e 60 páginas de componente, com exemplos ao vivo, o código
+de cada exemplo e a tabela de props. Fica em `demo/docs/`:
+- `nav.ts`: o catálogo (categoria → componente). O menu, o índice
+  (`/#/docs/componentes`) e as rotas saem dele.
+- `paginas/componentes/<slug>.tsx`: a página de cada componente (`export
+  default`), montada com `PaginaComponente`. Componente novo = uma linha no
+  catálogo + este arquivo.
+- `exemplos/<slug>/<Nome>.tsx`: cada arquivo é ao mesmo tempo o exemplo que roda
+  e o código que a página mostra (os imports de `src` aparecem como
+  `@celke/kole-react`). Na página: `<Exemplo id="botao/Cores" titulo="Cores" />`.
+  As classes `demo-*` dos exemplos são só de layout da demo.
+- `props.gerado.json`: as props de todas as interfaces exportadas (`BotaoProps`
+  vira `Botao`; `OpcoesToast`, `Coluna`… ficam com o próprio nome), lidas dos
+  tipos TypeScript: nome, tipo, obrigatória, padrão e o comentário `/** … */` da
+  prop como descrição. É gerado por `npm run docs:props`, que já roda no `dev` e
+  no `build:demo`; `npm run docs:conferir` falha se estiver desatualizado.
+### Teste visual
+Captura cada página do menu da demo (`demo/nav.ts`) nos temas claro e escuro e
+compara pixel a pixel com uma referência. Também confere que o tema `sistema`,
+com o sistema operacional no escuro, sai igual ao tema escuro. Página nova no
+menu entra no teste sozinha.
+O print muda de um sistema operacional para outro, então a referência fica em
+`tests/visual/__referencia__/<sistema>/`. Só a de Linux vai para o git: é a que
+o CI usa (`.github/workflows/visual.yml`, na imagem Docker do Playwright), em
+todo PR e na `main`.
+**Mudança visual de propósito:** o CI do PR vai falhar apontando as páginas que
+mudaram (o relatório com as diferenças fica nos artefatos do workflow). Confira
+e grave a referência nova: Actions → Teste visual → Run workflow, na branch do
+PR, com "atualizar" marcado. O workflow faz o commit da referência na branch.
+No Windows ou no macOS, o teste usa uma referência local, fora do git:
+```bash
+npx playwright install chromium   # uma vez
+npm run visual:referencia         # ANTES de mexer no CSS: grava a referência
+npm run visual                    # depois: aponta cada página que mudou
+npx playwright show-report        # diferenças lado a lado
+```
+Para comparar com uma versão já publicada, sirva a demo dela noutra porta (por
+exemplo, num `git worktree` da tag) e gere a referência com
+`KOLE_URL=http://localhost:5181 npm run visual:referencia`.
+Para testar uma versão que ainda não está no npm, instale direto do GitHub
+(o `prepare` gera o `dist/` na instalação) ou de um pacote local:
+```bash
+npm i github:celkecursos/kole-react
+# ou: gere o .tgz na pasta da biblioteca e instale no app
+npm pack                                   # → celke-kole-react-<versão>.tgz
+npm i ../kole-react/celke-kole-react-<versão>.tgz
+```
+Evite `npm i ../kole-react` (pasta): o npm cria um link e o bundler
+pega o React do `node_modules` da biblioteca — dois Reacts no app quebram os hooks
+(_Invalid hook call_). Se precisar do link durante o desenvolvimento, use
+`resolve: { dedupe: ['react', 'react-dom'] }` no `vite.config` do app.
+Publicar uma versão nova: `npm version patch` (só correção) ou `npm version minor`
+(muda a aparência ou a API — antes da 1.0, o `^0.x` dos apps não pega a minor
+sozinho), registre no [CHANGELOG](CHANGELOG.md) e confira o conteúdo com
+`npm pack --dry-run`. Depois do merge na `main`, publique pelo GitHub: Actions →
+Publicar → Run workflow (`.github/workflows/publish.yml`). O npm confia nesse
+workflow pela publicação confiável (Trusted Publisher, sem token) e o pacote
+sai com o atestado de procedência. O workflow só deixa a versão em espera
+(`npm stage publish`): ela vai ao ar depois que um mantenedor aprova com o
+segundo fator, com `npm stage list @celke/kole-react` e `npm stage approve <id>`
+(ou pelo site do npm). O workflow recusa versão que já está no npm.
+## Autor
+Criado por **Cesar Szpak**.
+## Licença
+MIT © 2026 Celke — veja o arquivo [LICENSE](https://github.com/celkecursos/kole-react/blob/main/LICENSE).