@celke/kole-react 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Celke
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,255 @@
-# Temporary Holding Version
+# @celke/kole-react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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`).
+
+### 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>}`.
+
+## 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` |
+
+### 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>
+  );
+}
+```
+
+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, carregado **depois** do `estilos.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 escuro usa `<html data-theme="dark">`; a densidade, as classes
+`density-compact`, `density-comfortable` e `density-cozy` no `<body>` (o
+`ProvedorUi` cuida das duas). 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';`.
+
+## CSS
+
+Classes CSS usam o prefixo `lp-`.
+
+## 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
+```
+
+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` e `npm publish` (o `prepare` roda o
+build; confira o conteúdo antes com `npm pack --dry-run`).
+
+## Autor
+
+Criado por **Cesar Szpak**.
+
+## Licença
+
+MIT © 2026 Celke — veja o arquivo [LICENSE](https://github.com/celkecursos/kole-react/blob/main/LICENSE).

package/dist/components/Abas/Abas.d.ts

@@ -0,0 +1,55 @@
+import { type ReactNode } from 'react';
+import { type IconeProp } from '../../utils/Icone.js';
+export interface AbaProps {
+    valor: string;
+    rotulo: string;
+    icone?: IconeProp;
+    desabilitada?: boolean;
+    /** Número de pendências (chip âmbar na aba). */
+    pendentes?: number;
+    /** Selo livre depois do rótulo (ex.: `<Badge>`). */
+    badge?: ReactNode;
+    /** Abas vizinhas com o mesmo grupo viram uma aba com menu suspenso. */
+    grupo?: string;
+    children?: ReactNode;
+}
+/** Painel de uma aba. Só funciona dentro de `<Abas>`. */
+export declare function Aba(_props: AbaProps): null;
+/**
+ * `sublinhado` (padrão) · `classica` = aba com borda colada no painel ·
+ * `pilulas` = ativa sólida · `suave` = ativa em fundo claro · `contorno` =
+ * todas com borda, ativa sólida · `segmentado` = trilho cinza com a ativa
+ * destacada · `passos` = círculos numerados · `cartao` = ativa e painel na
+ * mesma cor · `blocos` = caixas com ícone em cima e seta para o painel.
+ */
+export type VarianteAbas = 'sublinhado' | 'classica' | 'pilulas' | 'suave' | 'contorno' | 'segmentado' | 'passos' | 'cartao' | 'blocos';
+/** `preencher` = abas crescem conforme o rótulo · `justificado` = todas da mesma largura. */
+export type AlinhamentoAbas = 'inicio' | 'centro' | 'fim' | 'preencher' | 'justificado';
+export interface AbasProps {
+    /** Aba ativa (controlado). Sem ele, começa na primeira. */
+    ativa?: string;
+    aoMudar?: (valor: string) => void;
+    /** Nome acessível da lista de abas. */
+    rotulo?: string;
+    variante?: VarianteAbas;
+    /** Padrão: `preencher` no sublinhado, `inicio` nas demais. */
+    alinhamento?: AlinhamentoAbas;
+    /** `responsiva` = empilha as abas abaixo de 36rem. */
+    orientacao?: 'horizontal' | 'vertical' | 'responsiva';
+    /** Ícone acima do rótulo. */
+    iconeAcima?: boolean;
+    /** `caixa` = painel com borda e respiro. */
+    painel?: 'livre' | 'caixa';
+    /** `base` = abas abaixo do painel (rodapé). */
+    posicaoBarra?: 'topo' | 'base';
+    /** Título à esquerda, na mesma linha das abas. */
+    cabecalho?: ReactNode;
+    /** Modo página: cabeçalho com Voltar + título acima das abas. */
+    titulo?: string;
+    identidade?: string;
+    aoVoltar?: () => void;
+    acoes?: ReactNode;
+    children: ReactNode;
+    className?: string;
+}
+export declare function Abas({ ativa, aoMudar, rotulo, variante, alinhamento, orientacao, iconeAcima, painel, posicaoBarra, cabecalho, titulo, identidade, aoVoltar, acoes, children, className, }: AbasProps): import("react").JSX.Element;

package/dist/components/AcaoLinha/AcaoLinha.d.ts

@@ -0,0 +1,12 @@
+import type { ButtonHTMLAttributes } from 'react';
+import { type IconeProp } from '../../utils/Icone.js';
+export interface AcaoLinhaProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+    icone: IconeProp;
+    /** Nome da ação: vira dica e aria-label. */
+    rotulo: string;
+    /** `pri` = azul · `destaque` = laranja · `err` = vermelho. */
+    severidade?: 'neutra' | 'pri' | 'destaque' | 'err';
+    carregando?: boolean;
+}
+/** Botão-ícone compacto para ações de linha de tabela/card. */
+export declare function AcaoLinha({ icone, rotulo, severidade, carregando, disabled, className, type, ...resto }: AcaoLinhaProps): import("react").JSX.Element;

package/dist/components/Acordeao/Acordeao.d.ts

@@ -0,0 +1,42 @@
+import { type ReactNode } from 'react';
+import { type IconeProp } from '../../utils/Icone.js';
+export type CorAcordeao = 'pri' | 'secundario' | 'ok' | 'warn' | 'err' | 'info' | 'destaque' | 'escuro';
+/**
+ * `padrao` = caixa com borda · `sem-borda` = encostado no container ·
+ * `solido` = cabeçalho aberto na cor · `suave` = cabeçalho aberto em tom
+ * claro · `contorno` = borda na cor.
+ */
+export type VarianteAcordeao = 'padrao' | 'sem-borda' | 'solido' | 'suave' | 'contorno';
+export interface AcordeaoProps {
+    children: ReactNode;
+    /** Vários itens abertos ao mesmo tempo. */
+    multiplo?: boolean;
+    /** Itens abertos (controlado). */
+    abertos?: string[];
+    /** Itens abertos de início (não controlado). */
+    padraoAbertos?: string[];
+    aoMudar?: (abertos: string[]) => void;
+    variante?: VarianteAcordeao;
+    cor?: CorAcordeao;
+    /** Itens soltos, com espaço entre eles. */
+    separado?: boolean;
+    /** `seta` (padrão) · `mais` = + / − · `nenhum`. */
+    icone?: 'seta' | 'mais' | 'nenhum';
+    /** Lado do ícone. */
+    posicaoIcone?: 'fim' | 'inicio';
+    className?: string;
+}
+/** Lista de seções que abrem e fecham (acordeão). */
+export declare function Acordeao({ children, multiplo, abertos: controlado, padraoAbertos, aoMudar, variante, cor, separado, icone, posicaoIcone, className, }: AcordeaoProps): import("react").JSX.Element;
+export interface ItemAcordeaoProps {
+    valor: string;
+    titulo: ReactNode;
+    /** Ícone antes do título. */
+    icone?: IconeProp;
+    /** Cor só deste item (sobrepõe a do acordeão). */
+    cor?: CorAcordeao;
+    desabilitado?: boolean;
+    children: ReactNode;
+}
+/** Seção de um `Acordeao`. */
+export declare function ItemAcordeao({ valor, titulo, icone, cor, desabilitado, children }: ItemAcordeaoProps): import("react").JSX.Element;

package/dist/components/Alerta/Alerta.d.ts

@@ -0,0 +1,39 @@
+import { type ReactNode } from 'react';
+import { type IconeProp } from '../../utils/Icone.js';
+import type { Severidade } from '../../utils/tipos.js';
+/** Cores do alerta: as severidades + `pri` (azul de ação) e `destaque` (laranja da marca). */
+export type CorAlerta = Severidade | 'pri' | 'destaque';
+export type AparenciaAlerta = 'suave' | 'solido' | 'contorno' | 'destaque' | 'faixa' | 'cartao';
+export interface AlertaProps {
+    severidade?: CorAlerta;
+    /**
+     * `suave` (padrão) = fundo claro · `solido` = fundo cheio · `contorno` =
+     * só a borda · `destaque` = fundo neutro com filete lateral colorido ·
+     * `faixa` = título numa faixa sólida sobre o texto · `cartao` = bloco
+     * centralizado com ícone grande (avisos de página, confirmações).
+     */
+    aparencia?: AparenciaAlerta;
+    /** `pilula` = cantos totalmente arredondados. */
+    formato?: 'padrao' | 'pilula';
+    sombra?: 'pequena' | 'media' | 'grande';
+    /** Linha em negrito acima da mensagem. */
+    titulo?: ReactNode;
+    mensagem?: ReactNode;
+    children?: ReactNode;
+    /** Ícone da severidade por padrão; outro ícone, ou `false` para nenhum. */
+    icone?: IconeProp | false;
+    /** Imagem/avatar no lugar do ícone. */
+    midia?: ReactNode;
+    /** Botões ou links. */
+    acoes?: ReactNode;
+    /** `lado` = à direita da mensagem (padrão) · `abaixo` = sob o texto. */
+    posicaoAcoes?: 'lado' | 'abaixo';
+    /** Mostra o "×" e some ao clicar (sem controle externo). */
+    dispensavel?: boolean;
+    /** Mostra o "×" e avisa o app (que decide se o alerta sai da tela). */
+    aoFechar?: () => void;
+    /** `circulo` = "×" num círculo sólido da cor do alerta. */
+    botaoFechar?: 'simples' | 'circulo';
+    className?: string;
+}
+export declare function Alerta({ severidade, aparencia, formato, sombra, titulo, mensagem, children, icone, midia, acoes, posicaoAcoes, dispensavel, aoFechar, botaoFechar, className, }: AlertaProps): import("react").JSX.Element | null;

package/dist/components/Arquivo/CampoAnexo.d.ts

@@ -0,0 +1,27 @@
+import { type Anexo } from '../../utils/anexos.js';
+import { type CampoBaseProps } from '../Campo/Campo.js';
+export interface CampoAnexoProps extends Omit<CampoBaseProps, 'variante' | 'obrigatorio'> {
+    /** Lista serializável de anexos (sem o `File`). */
+    valor?: Anexo[];
+    aoMudar?: (valor: Anexo[]) => void;
+    /** Filtro do seletor nativo (ex.: `image/*,.pdf`). */
+    accept?: string;
+    /** Vários arquivos (padrão: sim). Com `false`, a nova escolha substitui. */
+    multiple?: boolean;
+    /** Tamanho máximo por arquivo, em bytes (0 = sem limite). */
+    maxTamanho?: number;
+    /** Mínimo de anexos; acima de zero o campo é obrigatório. */
+    minimo?: number;
+    disabled?: boolean;
+    id?: string;
+}
+/** O que a `ref` do `CampoAnexo` expõe. */
+export interface CampoAnexoRef {
+    /** O `File` da sessão por trás do anexo, ou `null` (anexo já salvo no backend). */
+    arquivoDe: (anexo: Pick<Anexo, 'nome' | 'tamanho'>) => File | null;
+}
+/**
+ * Zona de anexos (clicar ou arrastar). O valor é `Anexo[]`; o `File` real fica
+ * na sessão e sai por `ref.current.arquivoDe(anexo)` na hora do upload.
+ */
+export declare const CampoAnexo: import("react").ForwardRefExoticComponent<CampoAnexoProps & import("react").RefAttributes<CampoAnexoRef>>;

package/dist/components/Arquivo/DialogoArquivo.d.ts

@@ -0,0 +1,11 @@
+import { type Anexo } from '../../utils/anexos.js';
+export interface DialogoArquivoProps {
+    aberto: boolean;
+    aoFechar: () => void;
+    /** A lista INTEIRA; aponte o item clicado com `indice`. */
+    arquivos: readonly Anexo[];
+    indice: number;
+    aoMudarIndice: (indice: number) => void;
+}
+/** Visualizador em tela cheia que folheia uma lista de anexos (botões ou ← →). */
+export declare function DialogoArquivo({ aberto, aoFechar, arquivos, indice, aoMudarIndice }: DialogoArquivoProps): import("react").JSX.Element;

package/dist/components/Arquivo/Foto.d.ts

@@ -0,0 +1,29 @@
+import { type ReactNode } from 'react';
+import type { Anexo } from '../../utils/anexos.js';
+export type EntradaFoto = string | Anexo | readonly (string | Anexo)[] | null | undefined;
+export interface FotoProps {
+    /** A foto ou a coleção: URL, `Anexo` ou lista misturando os dois. */
+    fotos?: EntradaFoto;
+    /** De quem é a foto: vira o `alt` e as iniciais do avatar sem foto. */
+    nome: string;
+    tamanho?: 'sm' | 'md' | 'lg';
+    /** Válvulas de escape da escala (ex.: `13rem`). */
+    altura?: string;
+    largura?: string;
+    /** Clique abre a galeria em tela cheia. Não use dentro de outro alvo clicável. */
+    ampliavel?: boolean;
+    /** Qual foto da coleção (padrão: 0). */
+    indice?: number;
+    aoMudarIndice?: (indice: number) => void;
+    aoAmpliar?: (indice: number) => void;
+    /** Substitui o avatar padrão quando não há foto (ex.: "Foto indisponível"). */
+    semFoto?: ReactNode;
+    /** Conteúdo sobre a imagem (selo, marca d'água). */
+    sobreposto?: ReactNode;
+    className?: string;
+}
+/**
+ * Moldura de foto em tamanho de leitura: fundo desfocado da própria foto,
+ * sombra e anel. Entre o `Avatar` (miniatura) e o `DialogoArquivo` (tela cheia).
+ */
+export declare function Foto({ fotos, nome, tamanho, altura, largura, ampliavel, indice: indiceExterno, aoMudarIndice, aoAmpliar, semFoto, sobreposto, className, }: FotoProps): import("react").JSX.Element;

package/dist/components/Arquivo/VisualizadorArquivo.d.ts

@@ -0,0 +1,12 @@
+import { type Anexo } from '../../utils/anexos.js';
+export interface VisualizadorArquivoProps {
+    arquivo: Anexo | null;
+    /** A imagem/vídeo/áudio falhou ao carregar (URL expirada, 404, codec). */
+    aoFalhar?: (arquivo: Anexo) => void;
+    className?: string;
+}
+/**
+ * Superfície de exibição de UM anexo: imagem (zoom, giro, arrasto), PDF,
+ * vídeo e áudio nativos; o resto cai num estado com botão "Baixar".
+ */
+export declare function VisualizadorArquivo({ arquivo, aoFalhar, className }: VisualizadorArquivoProps): import("react").JSX.Element;

package/dist/components/Avaliacao/Avaliacao.d.ts

@@ -0,0 +1,30 @@
+export interface AvaliacaoProps {
+    /** Nota atual (0 = sem nota). */
+    valor: number;
+    /**
+     * Muda a nota. Se devolver uma Promise (ex.: salvar no servidor), o
+     * componente fica ocupado até ela terminar.
+     */
+    aoMudar?: (valor: number) => void | Promise<unknown>;
+    /** Quantidade de estrelas. */
+    max?: number;
+    /** `1` = estrelas inteiras · `0.5` = meias estrelas. */
+    passo?: 1 | 0.5;
+    /** Só mostra a nota (aceita fração, ex.: 3.7). */
+    somenteLeitura?: boolean;
+    /** Nome para leitor de tela (ex.: "Avaliação do produto"). */
+    rotulo: string;
+    icone?: 'star' | 'heart';
+    tamanho?: 'pequeno' | 'medio' | 'grande';
+    /** Texto para cada nota inteira (índice 0 = 1 estrela), mostrado ao lado. */
+    mensagens?: string[];
+    /** Chamado ao passar o mouse (com a nota sob o ponteiro, ou `null` ao sair). */
+    aoPassar?: (valor: number | null) => void;
+    /** Botão para limpar a nota. */
+    limpavel?: boolean;
+    /** Texto enquanto `aoMudar` não termina. */
+    textoOcupado?: string;
+    className?: string;
+}
+/** Avaliação por estrelas (ou corações): editável, com meias estrelas, ou só leitura. */
+export declare function Avaliacao({ valor, aoMudar, max, passo, somenteLeitura, rotulo, icone, tamanho, mensagens, aoPassar, limpavel, textoOcupado, className, }: AvaliacaoProps): import("react").JSX.Element;

package/dist/components/Avatar/Avatar.d.ts

@@ -0,0 +1,12 @@
+export interface AvatarProps {
+    foto?: string;
+    /** Nome completo — gera as iniciais quando não há foto. */
+    nome?: string;
+    iniciais?: string;
+    tom?: 'claro' | 'escuro';
+    formato?: 'circulo' | 'quadrado';
+    /** Tamanho CSS (ex.: `2rem`). */
+    tamanho?: string;
+    className?: string;
+}
+export declare function Avatar({ foto, nome, iniciais, tom, formato, tamanho, className }: AvatarProps): import("react").JSX.Element;

package/dist/components/Badge/Badge.d.ts

@@ -0,0 +1,43 @@
+import type { ReactNode } from 'react';
+import { type IconeProp } from '../../utils/Icone.js';
+import type { Severidade } from '../../utils/tipos.js';
+/** Mesmas cores do `Alerta`: severidades + `pri` (azul) e `destaque` (laranja). */
+export type CorBadge = Severidade | 'pri' | 'destaque';
+export interface BadgeProps {
+    cor?: CorBadge;
+    /**
+     * `solido` (padrão) · `suave` = fundo claro · `contorno` = só a borda ·
+     * `gradiente` · `inverso` = fundo da superfície com texto colorido (para
+     * usar dentro de um botão sólido da mesma cor).
+     */
+    aparencia?: 'solido' | 'suave' | 'contorno' | 'gradiente' | 'inverso';
+    /** `pilula` = cantos totalmente arredondados. */
+    formato?: 'padrao' | 'pilula';
+    /** `herdar` = acompanha o tamanho do texto em volta (títulos). */
+    tamanho?: 'pequeno' | 'medio' | 'herdar';
+    icone?: IconeProp;
+    /** Texto do badge (ou use `children`). */
+    rotulo?: ReactNode;
+    children?: ReactNode;
+    className?: string;
+}
+/** Etiqueta curta: contagem, rótulo de novidade, categoria. */
+export declare function Badge({ cor, aparencia, formato, tamanho, icone, rotulo, children, className }: BadgeProps): import("react").JSX.Element;
+export interface ComBadgeProps {
+    /** Elemento que recebe o badge (avatar, botão, ícone). */
+    children: ReactNode;
+    /** Contagem ou texto no canto; com `ponto`, é ignorado. */
+    conteudo?: ReactNode;
+    /** Acima disto vira "N+" (só para números; padrão: 99). */
+    max?: number;
+    /** Só um ponto (ex.: "online", "não lido"). */
+    ponto?: boolean;
+    cor?: CorBadge;
+    /** Canto do badge (padrão: superior direito). */
+    posicao?: 'superior-direita' | 'inferior-direita' | 'superior-esquerda' | 'inferior-esquerda';
+    /** Texto para leitor de tela (ex.: "99 mensagens não lidas"). */
+    descricao?: string;
+    className?: string;
+}
+/** Posiciona um badge (ou ponto) no canto de outro elemento. */
+export declare function ComBadge({ children, conteudo, max, ponto, cor, posicao, descricao, className }: ComBadgeProps): import("react").JSX.Element;

package/dist/components/Balao/Balao.d.ts

@@ -0,0 +1,30 @@
+import { type ReactNode } from 'react';
+export type PosicaoBalao = 'cima' | 'direita' | 'baixo' | 'esquerda';
+export type CorBalao = 'pri' | 'secundario' | 'ok' | 'warn' | 'err' | 'info' | 'destaque' | 'escuro';
+/** `padrao` · `cabecalho` = só o título na cor · `solido` = balão todo na cor · `suave` = fundo claro da cor. */
+export type AparenciaBalao = 'padrao' | 'cabecalho' | 'solido' | 'suave';
+/**
+ * `clique` = abre/fecha no clique; fecha também ao clicar fora ou Esc ·
+ * `foco` = fecha no próximo clique em qualquer lugar · `passar` = abre com o
+ * mouse em cima ou com o foco do teclado.
+ */
+export type GatilhoBalao = 'clique' | 'foco' | 'passar';
+export interface BalaoProps {
+    /** O elemento que abre o balão (botão, ícone, avatar…). */
+    children: ReactNode;
+    titulo?: ReactNode;
+    conteudo: ReactNode;
+    /** Lado preferido; vira para o oposto se não couber. */
+    posicao?: PosicaoBalao;
+    cor?: CorBalao;
+    aparencia?: AparenciaBalao;
+    gatilho?: GatilhoBalao;
+    /** Largura máxima (padrão `17rem`). */
+    largura?: string;
+    className?: string;
+}
+/**
+ * Balão com título e conteúdo (popover), ancorado num elemento. Abre no
+ * clique, no foco ou ao passar o mouse; nas 4 direções e em cores.
+ */
+export declare function Balao({ children, titulo, conteudo, posicao, cor, aparencia, gatilho, largura, className, }: BalaoProps): import("react").JSX.Element;

package/dist/components/BoasVindas/BoasVindas.d.ts

@@ -0,0 +1,19 @@
+import { type ReactNode } from 'react';
+export interface BoasVindasProps {
+    /** Nome completo (a saudação usa primeiro + último). */
+    nome: string;
+    cargo?: string;
+    /** Sigla da unidade (ex.: RH). */
+    sigla?: string;
+    foto?: string;
+    /** Último acesso; sem ele a linha some. */
+    ultimoAcesso?: Date | null;
+    /** Ações da página inicial (ex.: "Novo cadastro"). */
+    children?: ReactNode;
+    className?: string;
+}
+/**
+ * Cabeçalho de sessão da página inicial: foto, data por extenso, saudação
+ * pela hora, cargo · unidade e último acesso. Substitui o `CabecalhoPagina` na home.
+ */
+export declare function BoasVindas({ nome, cargo, sigla, foto, ultimoAcesso, children, className }: BoasVindasProps): import("react").JSX.Element;