forlogic-core 2.1.3 → 2.1.5

package/dist/utils/color.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Gera uma cor de fundo pastel a partir de uma cor hex semântica.
+ * Útil para StatusBadge e outros componentes que precisam de fundo suave.
+ *
+ * @param hex - Cor em formato hex (ex: '#2E7D5B')
+ * @param opacity - Opacidade do fundo (0-1, default 0.1)
+ * @returns String rgba (ex: 'rgba(46, 125, 91, 0.1)')
+ */
+export declare function generatePastelBg(hex: string, opacity?: number): string;
+/**
+ * Calcula a luminância relativa de uma cor hex (WCAG 2.0).
+ * Retorna um valor entre 0 (preto) e 1 (branco).
+ *
+ * @param hex - Cor em formato hex (ex: '#2E7D5B')
+ * @returns Luminância relativa (0-1)
+ */
+export declare function getLuminance(hex: string): number;
+/**
+ * Calcula a razão de contraste entre duas cores (WCAG 2.0).
+ * Razão >= 4.5 atende AA para texto normal; >= 7 atende AAA.
+ *
+ * @param hex1 - Primeira cor hex
+ * @param hex2 - Segunda cor hex
+ * @returns Razão de contraste (1-21)
+ */
+export declare function getContrastRatio(hex1: string, hex2: string): number;

package/dist/utils/index.d.ts

@@ -5,4 +5,5 @@ export { formatDatetime, formatDate } from './formatters/dateFormatters';
 export { formatCurrency } from './formatters/currencyFormatters';
 export declare const debounce: <T extends (...args: any[]) => any>(func: T, wait: number) => ((...args: Parameters<T>) => void);
 export declare const slugify: (text: string) => string;
+export { generatePastelBg, getLuminance, getContrastRatio } from './color';
 export { handleExternalLink, buildModuleUrl } from './linkHelpers';

package/docs/PUBLISH.md

@@ -0,0 +1,168 @@
+# 📦 Como Publicar a Biblioteca forlogic-core
+
+> **Nota:** Para documentação de uso e instalação da biblioteca, consulte [README.md](../README.md)
+
+## Configuração Inicial
+
+A biblioteca está configurada para ser publicada no NPM como `forlogic-core`.
+
+### Arquivos de Configuração
+
+- `package.json` - Configuração principal com campos de biblioteca
+- `rollup.config.js` - Configuração de build
+- `tsconfig.json` - Configuração TypeScript unificada
+- `.npmignore` - Arquivos excluídos da publicação (inclui `docs/` - não publicada no NPM)
+- `README.md` - Documentação principal (copiada para dist/)
+
+## Comandos Disponíveis
+
+### 1. Build da Biblioteca
+
+```bash
+npm run build:lib
+```
+
+### 2. Teste de Publicação (Dry Run)
+
+```bash
+npm publish --dry-run
+```
+
+### 3. Release Automatizado (Recomendado)
+
+**Script JavaScript**
+
+```bash
+# Release patch (1.0.0 → 1.0.1)
+node scripts/publish.js patch
+
+# Release minor (1.0.0 → 1.1.0)
+node scripts/publish.js minor
+
+# Release major (1.0.0 → 2.0.0)
+node scripts/publish.js major
+```
+
+### 4. Publicação Manual (Legado)
+
+```bash
+# Incrementar versão e publicar manualmente
+npm version patch   # 1.0.0 → 1.0.1
+npm version minor   # 1.0.0 → 1.1.0
+npm version major   # 1.0.0 → 2.0.0
+
+# Publicar versão atual
+npm publish
+```
+
+## Processo de Release Automatizado
+
+### Scripts Automatizados
+
+Os scripts `scripts/publish/release.js` e `scripts/publish/release.sh` executam automaticamente:
+
+1. **Verificação**: Confere se não há mudanças pendentes no Git
+2. **Build**: Executa `npm run build:lib` com Rollup
+3. **Versão**: Incrementa versão no `package.json`
+4. **Publicação**: Publica no NPM
+5. **Tags**: Envia tags para o GitHub
+
+### Processo Manual (Legado)
+
+1. **Build**: Executa `npm run build:lib` com Rollup
+2. **Geração**: Cria arquivos CJS, ESM e declarações TypeScript
+3. **Publicação**: Usa `npm publish` diretamente
+
+## Estrutura da Publicação
+
+```
+dist/
+├── index.js           # CommonJS
+├── index.esm.js       # ES Modules
+├── index.d.ts         # TypeScript declarations
+├── index.css          # CSS da biblioteca
+├── package.json       # Configuração da lib
+└── README.md          # Documentação
+```
+
+## Documentação para Usuários
+
+A documentação completa está **consolidada no README.md** e disponível publicamente no repositório GitHub:
+
+- **[📖 README.md](../README.md)** - Guia completo (~350 linhas)
+  - ✅ Regras críticas e checklist
+  - ✅ Quick start CRUD
+  - ✅ Migrations e RLS
+  - ✅ Troubleshooting
+  - ✅ Referência rápida
+
+### ⚙️ Documentação no Pacote NPM
+
+O `README.md` é incluído no pacote NPM publicado (`dist/README.md`) e contém toda a documentação necessária em um único arquivo otimizado para leitura por IA e desenvolvedores.
+
+#### Documentações Modulares
+
+Algumas features possuem documentação detalhada em arquivos específicos para desenvolvimento local:
+
+- `lib/crud/components/CUSTOM_FIELDS.md` - Campos customizados do BaseForm
+- `lib/qualiex/places/README.md` - Sistema de gestores de locais
+
+**Importante:** Essas documentações **não são publicadas no NPM**. O conteúdo consolidado está no `README.md` principal que é copiado para `dist/README.md`.
+
+## Verificação antes da Publicação
+
+1. ✅ Build bem-sucedido (`npm run build:lib`)
+2. ✅ Dry-run sem erros (`npm publish --dry-run`)
+3. ✅ Versão correta no `package.json`
+4. ✅ README atualizado
+5. ✅ Changelog documentado (se aplicável)
+
+## Troubleshooting
+
+### Erro de Permissão NPM
+
+```bash
+npm login
+```
+
+### Build Falha
+
+Verifique se todas as dependências estão instaladas:
+
+```bash
+npm install
+```
+
+### Rollup Errors
+
+Confirme que o `rollup.config.js` está correto e que o `lib/index.ts` existe e exporta tudo necessário.
+
+### CSS Import Issues
+
+Se houver erro ao importar CSS, use:
+
+```tsx
+import 'forlogic-core/index.css';
+```
+
+O CSS é extraído para `index.css` durante o build da biblioteca.
+
+# Comandos Disponíveis
+
+## Instalar a última versão do forlogic-core
+
+```bash
+npm i forlogic-core@latest
+```
+
+## Build do projeto
+
+```bash
+npm run build
+```
+
+## Limpar cache do NPM
+
+```bash
+npm cache clean --force
+```

package/docs/WORKSPACE_KNOWLEDGE.md

@@ -1,119 +1,119 @@
-# forlogic-core — Workspace Knowledge
-
-> **Documento para colar no Lovable Workspace Knowledge** de projetos consumidores.
-> Funciona como mapa de referências cruzadas entre os projetos.
-
----
-
-## Projetos do Ecossistema
-
-| Projeto | Alias | Responsabilidade |
-|---------|-------|-----------------|
-| **forlogic-docs** | `@forlogic-docs` | Fonte canônica de regras, padrões, templates e documentação |
-| **qualiex-admin** | `@Admin` | Código-fonte da lib `forlogic-core`, Design System e docs gerados |
-
----
-
-## Onde buscar cada informação
-
-### Regras e Padrões → `@forlogic-docs`
-
-| O que | Caminho |
-|-------|---------|
-| Constituição (regras canônicas) | `docs/engenharia/padroes/constitution.md` |
-| Guia de migração de ícones | `docs/engenharia/padroes/icon-migration.md` |
-| Guia de publicação da lib | `docs/engenharia/devops/publish.md` |
-| Prompt: auditoria | `docs/templates/prompts/audit.md` |
-| Prompt: criação de tela | `docs/templates/prompts/new-screen.md` |
-| Prompt: starter template | `docs/templates/prompts/starter.md` |
-| ADRs (decisões de arquitetura) | `docs/adrs/` |
-| Specs de API | `docs/apis/` |
-
-### Código-fonte e Design System → `@Admin`
-
-| O que | Caminho |
-|-------|---------|
-| Código dos componentes UI | `lib/components/ui/` |
-| Sistema CRUD | `lib/crud/` |
-| Barrel exports (lista completa) | `lib/exports/ui.ts`, `lib/exports/index.ts` |
-| Documentação MD do Design System | `docs/design-system/` |
-| Golden snippets (exemplos) | `docs/design-system/examples.md` |
-| Docs interativos (código-fonte) | `src/design-system/docs/` |
-| Hooks compartilhados | `lib/hooks/` |
-| Providers (CoreProviders) | `lib/providers/` |
-| Serviços (Base, Email, Error) | `lib/services/` |
-| Config Vite/Tailwind | `lib/vite/`, `lib/tailwind/` |
-| Spec do módulo Queries | `spec/queries.md` |
-
----
-
-## Schema do Projeto
-
-> ⚠️ **O schema é definido no `README.md` de cada projeto consumidor.** Consulte-o antes de qualquer query.
-
-```ts
-// ✅ CORRETO — substituir pelo schema do projeto
-supabase.schema('SCHEMA_DO_PROJETO').from('tabela').select('*');
-
-// ❌ ERRADO
-supabase.from('tabela').select('*');
-```
-
----
-
-## Regras Invioláveis (resumo)
-
-> Fonte canônica: `@forlogic-docs docs/engenharia/padroes/constitution.md`
-
-| Regra | Detalhe |
-|-------|---------|
-| Schema obrigatório | `.schema('...')` em toda query Supabase |
-| Sem DELETE físico | Soft delete com `deleted_at` |
-| Lib-first | Usar `forlogic-core` antes de criar componente |
-| Import do Supabase | `getSupabaseClient()` de `forlogic-core` |
-| Import de i18n | `useTranslation` de `forlogic-core`, nunca de `react-i18next` |
-| Sem hardcoded admin | Nunca localStorage/sessionStorage para roles |
-
----
-
-## Design System — Categorias
-
-> Para ver props e exemplos: `@Admin docs/design-system/<arquivo>.md`
-
-| Categoria | Arquivo |
-|-----------|---------|
-| Fundação | `foundation.md` |
-| Botões & Ações | `buttons-actions.md` |
-| Inputs | `inputs.md` |
-| Seletores | `selectors.md` |
-| Data Display | `data-display.md` |
-| Data Grid | `tables-grids.md` |
-| Navegação | `navigation.md` |
-| Dialogs | `dialogs.md` |
-| Layout | `layout.md` |
-| CRUD | `crud.md` |
-
-### Aliases
-
-| Original | Alias(es) |
-|----------|-----------|
-| Combobox | SelectSearch, MultiSelect, EntitySelect |
-| ComboTree | TreeSelect |
-| ActionButton | ActionMenu, RowActions |
-| CrudPrimitiveTable | DataTable |
-
----
-
-## Instrução para IA — Leitura Obrigatória
-
-**QUANDO** criar ou modificar qualquer arquivo `.tsx`:
-
-- **SE** contém tabela/CRUD → **LER** `@Admin docs/design-system/crud.md` ANTES
-- **SE** contém formulário → **LER** `@Admin docs/design-system/inputs.md` ANTES
-- **SE** contém modal → **LER** `@Admin docs/design-system/dialogs.md` ANTES
-- **SE** contém botões/ações → **LER** `@Admin docs/design-system/buttons-actions.md` ANTES
-- **SE** é layout → **LER** `@Admin docs/design-system/layout.md` ANTES
-
-**SEMPRE** consultar `@Admin docs/design-system/examples.md` como referência.
-
-**VALIDAÇÃO**: Todo import de componente visual DEVE vir de `forlogic-core`.
+# forlogic-core — Workspace Knowledge
+
+> **Documento para colar no Lovable Workspace Knowledge** de projetos consumidores.
+> Funciona como mapa de referências cruzadas entre os projetos.
+
+---
+
+## Projetos do Ecossistema
+
+| Projeto | Alias | Responsabilidade |
+|---------|-------|-----------------|
+| **forlogic-docs** | `@forlogic-docs` | Fonte canônica de regras, padrões, templates e documentação |
+| **qualiex-admin** | `@Admin` | Código-fonte da lib `forlogic-core`, Design System e docs gerados |
+
+---
+
+## Onde buscar cada informação
+
+### Regras e Padrões → `@forlogic-docs`
+
+| O que | Caminho |
+|-------|---------|
+| Constituição (regras canônicas) | `docs/engenharia/padroes/constitution.md` |
+| Guia de migração de ícones | `docs/engenharia/padroes/icon-migration.md` |
+| Guia de publicação da lib | `docs/engenharia/devops/publish.md` |
+| Prompt: auditoria | `docs/templates/prompts/audit.md` |
+| Prompt: criação de tela | `docs/templates/prompts/new-screen.md` |
+| Prompt: starter template | `docs/templates/prompts/starter.md` |
+| ADRs (decisões de arquitetura) | `docs/adrs/` |
+| Specs de API | `docs/apis/` |
+
+### Código-fonte e Design System → `@Admin`
+
+| O que | Caminho |
+|-------|---------|
+| Código dos componentes UI | `lib/components/ui/` |
+| Sistema CRUD | `lib/crud/` |
+| Barrel exports (lista completa) | `lib/exports/ui.ts`, `lib/exports/index.ts` |
+| Documentação MD do Design System | `docs/design-system/` |
+| Golden snippets (exemplos) | `docs/design-system/examples.md` |
+| Docs interativos (código-fonte) | `src/design-system/docs/` |
+| Hooks compartilhados | `lib/hooks/` |
+| Providers (CoreProviders) | `lib/providers/` |
+| Serviços (Base, Email, Error) | `lib/services/` |
+| Config Vite/Tailwind | `lib/vite/`, `lib/tailwind/` |
+| Spec do módulo Queries | `spec/queries.md` |
+
+---
+
+## Schema do Projeto
+
+> ⚠️ **O schema é definido no `README.md` de cada projeto consumidor.** Consulte-o antes de qualquer query.
+
+```ts
+// ✅ CORRETO — substituir pelo schema do projeto
+supabase.schema('SCHEMA_DO_PROJETO').from('tabela').select('*');
+
+// ❌ ERRADO
+supabase.from('tabela').select('*');
+```
+
+---
+
+## Regras Invioláveis (resumo)
+
+> Fonte canônica: `@forlogic-docs docs/engenharia/padroes/constitution.md`
+
+| Regra | Detalhe |
+|-------|---------|
+| Schema obrigatório | `.schema('...')` em toda query Supabase |
+| Sem DELETE físico | Soft delete com `deleted_at` |
+| Lib-first | Usar `forlogic-core` antes de criar componente |
+| Import do Supabase | `getSupabaseClient()` de `forlogic-core` |
+| Import de i18n | `useTranslation` de `forlogic-core`, nunca de `react-i18next` |
+| Sem hardcoded admin | Nunca localStorage/sessionStorage para roles |
+
+---
+
+## Design System — Categorias
+
+> Para ver props e exemplos: `@Admin docs/design-system/<arquivo>.md`
+
+| Categoria | Arquivo |
+|-----------|---------|
+| Fundação | `foundation.md` |
+| Botões & Ações | `buttons-actions.md` |
+| Inputs | `inputs.md` |
+| Seletores | `selectors.md` |
+| Data Display | `data-display.md` |
+| Data Grid | `tables-grids.md` |
+| Navegação | `navigation.md` |
+| Dialogs | `dialogs.md` |
+| Layout | `layout.md` |
+| CRUD | `crud.md` |
+
+### Aliases
+
+| Original | Alias(es) |
+|----------|-----------|
+| Combobox | SelectSearch, MultiSelect, EntitySelect |
+| ComboTree | TreeSelect |
+| ActionButton | ActionMenu, RowActions |
+| CrudPrimitiveTable | DataTable |
+
+---
+
+## Instrução para IA — Leitura Obrigatória
+
+**QUANDO** criar ou modificar qualquer arquivo `.tsx`:
+
+- **SE** contém tabela/CRUD → **LER** `@Admin docs/design-system/crud.md` ANTES
+- **SE** contém formulário → **LER** `@Admin docs/design-system/inputs.md` ANTES
+- **SE** contém modal → **LER** `@Admin docs/design-system/dialogs.md` ANTES
+- **SE** contém botões/ações → **LER** `@Admin docs/design-system/buttons-actions.md` ANTES
+- **SE** é layout → **LER** `@Admin docs/design-system/layout.md` ANTES
+
+**SEMPRE** consultar `@Admin docs/design-system/examples.md` como referência.
+
+**VALIDAÇÃO**: Todo import de componente visual DEVE vir de `forlogic-core`.

package/docs/design-system/README.md

@@ -3,7 +3,7 @@
 
 # Design System — forlogic-core
 
-> Gerado automaticamente em 2026-04-10
+> Gerado automaticamente em 2026-04-14
 > Total: 92 componentes documentados em 15 categorias
 
 ## Categorias