@celke/kole-react 0.5.0 → 0.6.0

package/dist/utils/dinheiro.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Dinheiro e porcentagem. Os formatadores ficam em cache por idioma e
+ * combinação de opções: criar um `Intl.NumberFormat` a cada célula pesa.
+ * O idioma muda só a formatação (`R$ 1.234,50` · `R$1,234.50`); a moeda vem
+ * de `moeda` (BRL por padrão).
+ */
+import { type Idioma } from '../i18n/idiomas.js';
+export interface OpcoesMoeda {
+    /** Código ISO 4217. Padrão `BRL`. */
+    moeda?: string;
+    /** `+ R$ 10,00` nos positivos (os negativos sempre levam `−`). */
+    sinal?: boolean;
+    /** `R$ 12,4 mil` · `R$ 1,2 mi` (deixe o valor cheio no `title`). */
+    compacto?: boolean;
+    /** Padrão `true`. `false` arredonda para reais inteiros. */
+    centavos?: boolean;
+    /** Sem o símbolo: `1.234,56`. */
+    semSimbolo?: boolean;
+    /** Idioma da formatação. Padrão `pt-BR`. */
+    idioma?: Idioma;
+}
+/** O sinal de menos tipográfico (U+2212): mais legível que o hífen em colunas de valores. */
+export declare const MENOS = "\u2212";
+/**
+ * `1234.5` → `R$ 1.234,50` · `-80` → `−R$ 80,00` · com `sinal`: `+R$ 10,00`.
+ * O espaço depois de `R$` é inseparável (não quebra a linha no meio do valor).
+ */
+export declare function formatarMoeda(valor: number, opcoes?: OpcoesMoeda): string;
+export interface OpcoesPercentual {
+    /** Casas decimais. Padrão `1`. */
+    casas?: number;
+    /** `+12,5%` nos positivos. */
+    sinal?: boolean;
+    /** `valor` já está em fração (`0.125` = 12,5%). Padrão: em pontos (`12.5`). */
+    fracao?: boolean;
+    /** Idioma da formatação. Padrão `pt-BR`. */
+    idioma?: Idioma;
+}
+/** `12.5` → `12,5%` · `-3` → `−3,0%` · com `fracao`: `0.125` → `12,5%`. */
+export declare function formatarPercentual(valor: number, opcoes?: OpcoesPercentual): string;
+/** Variação de `anterior` para `atual`, em pontos (`10 → 12` = `20`). `null` quando `anterior` é zero. */
+export declare function variacaoPercentual(atual: number, anterior: number): number | null;
+/**
+ * Divide `total` em `n` parcelas com centavos exatos: a diferença do
+ * arredondamento vai para a primeira (`100 / 3` → `33,34 · 33,33 · 33,33`).
+ */
+export declare function dividirEmParcelas(total: number, n: number): number[];
+/** Soma sem o erro de ponto flutuante (`0.1 + 0.2` = `0.3`), arredondando em centavos. */
+export declare function somarMoeda(valores: readonly number[]): number;

package/dist/utils/entidade.d.ts

@@ -1,3 +1,4 @@
+import type { Idioma } from '../i18n/idiomas.js';
 /**
  * Vocabulário de entidade e títulos de tela: verbo no infinitivo + substantivo
  * (`Cadastrar veículo`), sem artigo — nunca precisa saber o gênero.
@@ -13,7 +14,7 @@ export interface Entidade {
     readonly editar?: string;
     readonly leitura?: string;
 }
-/** Título da tela: a frase declarada do modo ou `Verbo nome`. */
-export declare function tituloDeEntidade(entidade: string | Entidade, modo: Modo): string;
+/** Título da tela: a frase declarada do modo ou `Verbo nome` (o verbo no `idioma`, padrão `pt-BR`). */
+export declare function tituloDeEntidade(entidade: string | Entidade, modo: Modo, idioma?: Idioma): string;
 /** Troca `\ / : * ? " < > |` por `-` e junta espaços — nome seguro para "Salvar como PDF". */
 export declare function nomeDeArquivo(texto: string): string;

package/dist/utils/periodo.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Períodos de relatório (mês, trimestre, ano ou intervalo livre) com datas
+ * `AAAA-MM-DD` no fuso local — as mesmas do `CampoData` e do `paraData`.
+ */
+import { type Idioma } from '../i18n/idiomas.js';
+export type TipoPeriodo = 'mes' | 'trimestre' | 'ano' | 'personalizado';
+export interface Periodo {
+    tipo: TipoPeriodo;
+    /** Primeiro dia, `AAAA-MM-DD`. */
+    de: string;
+    /** Último dia (inclusive), `AAAA-MM-DD`. */
+    ate: string;
+}
+/** `Date` → `AAAA-MM-DD` no fuso local. */
+export declare function dataIso(d: Date): string;
+/** O mês, o trimestre ou o ano que contém `data` (padrão: hoje). */
+export declare function periodoDe(tipo: Exclude<TipoPeriodo, 'personalizado'>, data?: Date | string): Periodo;
+/**
+ * Anda `passos` períodos para a frente (ou para trás, se negativo). O
+ * personalizado anda pelo próprio tamanho: 10 dias viram os 10 seguintes.
+ */
+export declare function moverPeriodo(p: Periodo, passos: number): Periodo;
+/** `data` cai dentro do período (as pontas contam). */
+export declare function noPeriodo(data: Date | string, p: Periodo): boolean;
+/**
+ * "novembro de 2026" · "3º trimestre de 2026" · "2026" · "5 de nov. a 14 de nov. de 2026".
+ * `curto` tira o ano do mês e do trimestre quando é o ano de `agora`.
+ * `idioma` (padrão `pt-BR`): "November 2026", "Q3 2026", "Nov 5 – Nov 14, 2026".
+ */
+export declare function rotuloPeriodo(p: Periodo, opcoes?: {
+    curto?: boolean;
+    agora?: Date;
+    idioma?: Idioma;
+}): string;
+/** Cada mês do período, como o primeiro dia (`AAAA-MM-01`): o eixo X de um gráfico mensal. */
+export declare function mesesDoPeriodo(p: Periodo): string[];

package/dist/utils/senha.d.ts

@@ -1,3 +1,4 @@
+import { type Idioma } from '../i18n/idiomas.js';
 /** Política de senha: o app declara só o que muda sobre `POLITICA_PADRAO`. */
 export interface PoliticaSenha {
     minimo: number;
@@ -15,7 +16,7 @@ export interface ForcaSenha {
 /** Padrão da biblioteca: só o tamanho. */
 export declare const POLITICA_PADRAO: PoliticaSenha;
 /** Primeira regra violada (tamanho → minúscula → maiúscula → dígito → símbolo), ou `''`. */
-export declare function validarSenha(senha: string, politica?: PoliticaSenha): string;
+export declare function validarSenha(senha: string, politica?: PoliticaSenha, idioma?: Idioma): string;
 /** Heurística barata: +1 por classe de caractere, +1 com `minimo + 4` de tamanho. */
 export declare function forcaSenha(senha: string, politica?: PoliticaSenha): ForcaSenha;
 export declare function senhasIguais(a: string, b: string): boolean;

package/dist/utils/tempo.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Tempo relativo em pt-BR ("há 5 min", "ontem", "em 3 dias") e situação de
+ * um prazo (atrasado, vence hoje, em breve). Datas `AAAA-MM-DD` valem no fuso
+ * local (não em UTC, como o `new Date('2026-11-13')` faria).
+ */
+import { type Idioma } from '../i18n/idiomas.js';
+/** `Date`, ISO completo ou só a data (`AAAA-MM-DD`, lida no fuso local). */
+export declare function paraData(valor: Date | string): Date;
+/** Dias de calendário de `de` até `ate` (negativo se `ate` é antes), ignorando a hora. */
+export declare function diasEntre(de: Date | string, ate: Date | string): number;
+/** `13/11` no mesmo ano de `agora`; `13/11/2025` em outro. */
+export declare function dataCurta(valor: Date | string, agora?: Date, idioma?: Idioma): string;
+/**
+ * Quanto tempo falta ou passou: "agora mesmo", "há 5 min", "há 2 h",
+ * "ontem", "há 3 dias", "há 2 meses", "em 10 min", "amanhã", "em 4 dias"…
+ */
+export declare function tempoRelativo(valor: Date | string, agora?: Date, idioma?: Idioma): string;
+export type SituacaoPrazo = 'atrasado' | 'hoje' | 'em-breve' | 'no-prazo';
+export interface Prazo {
+    situacao: SituacaoPrazo;
+    /** Dias de hoje até o vencimento (negativo = atrasado). */
+    dias: number;
+    /** Curto, para o selo: "Atrasado", "Hoje", "Amanhã", "13/11". */
+    rotulo: string;
+    /** Por extenso, para dica e leitor de tela: "Venceu há 2 dias (11/11/2026)". */
+    descricao: string;
+}
+/**
+ * Situação de um vencimento em relação a hoje. `emBreve` = quantos dias
+ * antes passa a ser "em breve" (padrão: 2).
+ */
+export declare function situacaoPrazo(vencimento: Date | string, agora?: Date, emBreve?: number, idioma?: Idioma): Prazo;

package/dist/utils/texto.d.ts

@@ -1,21 +1,28 @@
 /**
  * Texto e número: listas e valores por extenso (documentos), leitura de
  * caminho, formatação, saudação, iniciais, normalização para busca.
+ * Os números e valores por extenso seguem as regras do português (documentos
+ * brasileiros) e não mudam com o idioma.
  */
-/** `['A']` → `A` · `['A','B']` → `A e B` · `['A','B','C']` → `A, B e C`. */
-export declare function listaPorExtenso(itens: readonly string[]): string;
+import { type Idioma } from '../i18n/idiomas.js';
+/**
+ * `['A']` → `A` · `['A','B']` → `A e B` · `['A','B','C']` → `A, B e C`.
+ * Em outro `idioma`, a conjunção dele (`A, B and C`).
+ */
+export declare function listaPorExtenso(itens: readonly string[], idioma?: Idioma): string;
 /** Inteiro por extenso (trunca decimais): `1500` → `mil e quinhentos`. */
 export declare function numeroPorExtenso(num: number): string;
 /** Valor em reais por extenso: `1500.5` → `mil e quinhentos reais e cinquenta centavos`. */
 export declare function valorMonetarioPorExtenso(valor: number): string;
 /** Lê um caminho com ponto (`a.b.c`); `undefined` se algum trecho faltar. */
 export declare function lerCampo(obj: unknown, caminho: string): unknown;
-/** `1243` → `1.243` · compacto: `12400` → `12,4 mil` (deixe o valor cheio no `title`). */
+/** `1243` → `1.243` · compacto: `12400` → `12,4 mil` (deixe o valor cheio no `title`). `idioma` padrão: `pt-BR`. */
 export declare function formatarNumero(valor: number, opcoes?: {
     compacto?: boolean;
+    idioma?: Idioma;
 }): string;
-/** 5–11h Bom dia · 12–17h Boa tarde · demais Boa noite. */
-export declare function saudacaoPorHora(agora?: Date): string;
+/** 5–11h Bom dia · 12–17h Boa tarde · demais Boa noite (no `idioma`, padrão `pt-BR`). */
+export declare function saudacaoPorHora(agora?: Date, idioma?: Idioma): string;
 /** Primeira letra das duas primeiras palavras: `Gabrielly Ribeiro da Silva` → `GR`. */
 export declare function iniciais(nome: string): string;
 /** Sem acento e em minúsculas — a comparação de toda busca/filtro. */

package/dist/utils/tiposCampo.d.ts

@@ -1,10 +1,12 @@
 import { type Mascara } from './mascara.js';
+import type { Idioma } from '../i18n/idiomas.js';
 import { type TipoDeCampo } from './validadores.js';
 /** Descritor de um tipo de campo: máscara, placeholder, validação e caixa alta. */
 export interface MetaTipoCampo {
     mascara?: Mascara;
     placeholder?: string;
-    validar: (valor: string) => string;
+    /** Mensagem do erro (vazia se válido), no `idioma` (padrão `pt-BR`). */
+    validar: (valor: string, idioma?: Idioma) => string;
     /** `true` = sempre maiúscula (placa) · `false` = nunca (e-mail). */
     caixaAlta?: boolean;
 }

package/dist/utils/validadores.d.ts

@@ -1,7 +1,9 @@
 /**
  * Validadores de dados brasileiros: predicados `is*` + o despachante `validar()`.
  * Lógica pura, sem React. A máscara de cada tipo mora em `tiposCampo.ts`.
+ * As regras são as brasileiras em qualquer idioma; só a mensagem é traduzida.
  */
+import type { Idioma } from '../i18n/idiomas.js';
 export declare const TIPOS_DE_CAMPO: readonly ["cpf", "cnpj", "cpfCnpj", "email", "cep", "telefone", "placa", "renavam", "chassi", "cnh", "imei", "hora", "data", "dataHora"];
 export type TipoDeCampo = (typeof TIPOS_DE_CAMPO)[number];
 /** CPF com os dois dígitos verificadores; rejeita sequências repetidas. */
@@ -34,9 +36,9 @@ export declare function isDataHora(v: string): boolean;
  * Telefone, opcionalmente restrito a um formato. Vazio é válido
  * (obrigatoriedade é assunto do campo, não do validador).
  */
-export declare function validarTelefone(v: string, tipo?: 'fixo' | 'celular'): string;
+export declare function validarTelefone(v: string, tipo?: 'fixo' | 'celular', idioma?: Idioma): string;
 /**
  * Mensagem de validação do tipo, ou `''` quando vazio ou válido.
  * Separa "incompleto" (ainda digitando) de "inválido" (errado).
  */
-export declare function validar(tipo: TipoDeCampo, valor: string): string;
+export declare function validar(tipo: TipoDeCampo, valor: string, idioma?: Idioma): string;

package/package.json

@@ -1,91 +1,93 @@
-{
-  "name": "@celke/kole-react",
-  "version": "0.5.0",
-  "description": "Biblioteca de componentes React para sistemas administrativos.",
-  "license": "MIT",
-  "author": "Cesar Szpak",
-  "homepage": "https://github.com/celkecursos/kole-react#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/celkecursos/kole-react.git"
-  },
-  "bugs": {
-    "url": "https://github.com/celkecursos/kole-react/issues"
-  },
-  "keywords": [
-    "react",
-    "ui",
-    "componentes",
-    "design-system",
-    "layout",
-    "admin",
-    "dashboard",
-    "formulario",
-    "tabela",
-    "pt-br",
-    "celke"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "type": "module",
-  "sideEffects": [
-    "**/*.css"
-  ],
-  "files": [
-    "dist"
-  ],
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./estilos.css": {
-      "types": "./dist/css.d.ts",
-      "default": "./dist/estilos.css"
-    },
-    "./tokens.css": {
-      "types": "./dist/css.d.ts",
-      "default": "./dist/tokens.css"
-    },
-    "./tailwind.css": {
-      "types": "./dist/css.d.ts",
-      "style": "./dist/tailwind.css",
-      "default": "./dist/tailwind.css"
-    },
-    "./package.json": "./package.json"
-  },
-  "scripts": {
-    "dev": "vite",
-    "build": "vite build && tsc -p tsconfig.build.json && node scripts/ajustar-tipos.mjs && node scripts/embutir-fonte.mjs",
-    "build:demo": "vite build --mode demo",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "visual": "playwright test",
-    "visual:referencia": "playwright test --update-snapshots --project=claro --project=escuro",
-    "prepare": "npm run build"
-  },
-  "peerDependencies": {
-    "react": "^18.2.0 || ^19.0.0",
-    "react-dom": "^18.2.0 || ^19.0.0"
-  },
-  "devDependencies": {
-    "@fontsource-variable/inter": "^5.2.8",
-    "@playwright/test": "^1.64.1",
-    "@types/react": "^19.2.0",
-    "@types/react-dom": "^19.2.0",
-    "@vitejs/plugin-react": "^6.0.0",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
-    "typescript": "~6.0.3",
-    "vite": "^8.0.0"
-  },
-  "dependencies": {
-    "lucide-react": "^1.60.0"
-  }
-}
+{
+  "name": "@celke/kole-react",
+  "version": "0.6.0",
+  "description": "Biblioteca de componentes React para sistemas administrativos.",
+  "license": "MIT",
+  "author": "Cesar Szpak",
+  "homepage": "https://github.com/celkecursos/kole-react#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/celkecursos/kole-react.git"
+  },
+  "bugs": {
+    "url": "https://github.com/celkecursos/kole-react/issues"
+  },
+  "keywords": [
+    "react",
+    "ui",
+    "componentes",
+    "design-system",
+    "layout",
+    "admin",
+    "dashboard",
+    "formulario",
+    "tabela",
+    "pt-br",
+    "celke"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./estilos.css": {
+      "types": "./dist/css.d.ts",
+      "default": "./dist/estilos.css"
+    },
+    "./tokens.css": {
+      "types": "./dist/css.d.ts",
+      "default": "./dist/tokens.css"
+    },
+    "./tailwind.css": {
+      "types": "./dist/css.d.ts",
+      "style": "./dist/tailwind.css",
+      "default": "./dist/tailwind.css"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "dev": "node scripts/gerar-props.mjs && vite",
+    "build": "vite build && tsc -p tsconfig.build.json && node scripts/ajustar-tipos.mjs && node scripts/embutir-fonte.mjs",
+    "build:demo": "node scripts/gerar-props.mjs && vite build --mode demo",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "visual": "playwright test",
+    "visual:referencia": "playwright test --update-snapshots --project=claro --project=escuro --project=en",
+    "prepare": "npm run build",
+    "docs:props": "node scripts/gerar-props.mjs",
+    "docs:conferir": "node scripts/gerar-props.mjs --conferir"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@fontsource-variable/inter": "^5.2.8",
+    "@playwright/test": "^1.64.1",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^6.0.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "~6.0.3",
+    "vite": "^8.0.0"
+  },
+  "dependencies": {
+    "lucide-react": "^1.60.0"
+  }
+}