forlogic-core 2.2.5 → 2.2.7

package/README.md

@@ -1,120 +1,120 @@
-# forlogic-core
-
-Shared React component library, hooks, services, and configuration for Forlogic / Qualiex projects. Built on Vite + React 18 + Tailwind + shadcn primitives, opinionated for multi-tenant SaaS with Supabase.
-
-## Install
-
-```bash
-npm install forlogic-core
-```
-
-## Quick Start
-
-```tsx
-import { CoreProviders, Button } from 'forlogic-core';
-import { setupQualiexCore } from 'forlogic-core/setup';
-import ptBR from './i18n/pt-BR.json';
-
-setupQualiexCore(); // injects fonts, favicon, etc.
-
-function App() {
-  return (
-    <CoreProviders moduleAlias="my-module" appTranslations={{ 'pt-BR': ptBR }}>
-      <Button variant="primary">Hello</Button>
-    </CoreProviders>
-  );
-}
-```
-
-`CoreProviders` wires up auth, React Query, i18n and tooltip providers in the right order.
-
-## Modules
-
-| Module | What it provides | README |
-|---|---|---|
-| `forlogic-core` (UI) | shadcn-based components (`Button`, `Dialog`, `Combobox`, `Tabs`, ...) | `docs/design-system/` |
-| `forlogic-core` (CRUD) | `createCrudPage`, `CrudTable`, `BaseForm`, services hook | `docs/design-system/crud.md` |
-| `forlogic-core/auth` | OAuth + PKCE, multi-tenant alias routing, `useAuth` | [`lib/auth/README.md`](lib/auth/README.md) |
-| `forlogic-core/services` | `BaseService`, `createSimpleService`, Email, Error | [`lib/services/README.md`](lib/services/README.md) |
-| `forlogic-core/places` | Hierarchical Org Units (UO) selectors and tree view | [`lib/places/README.md`](lib/places/README.md) |
-| `forlogic-core/approval-flow` | Approval sidebar, dialogs and types | [`lib/approval-flow/README.md`](lib/approval-flow/README.md) |
-| `forlogic-core/media` | `VideoEditor`, `ImageEditor` with pluggable upload | [`lib/media/README.md`](lib/media/README.md) |
-| `forlogic-core/integrations` | Clarity, Supabase client | [`lib/integrations/README.md`](lib/integrations/README.md) |
-
-## Modular imports
-
-Subpath exports keep bundles lean:
-
-```ts
-import { Button } from 'forlogic-core/ui';
-import { createCrudPage } from 'forlogic-core/crud';
-import { createSecurityHeadersPlugin } from 'forlogic-core/vite';
-import { forlogicTailwindPreset } from 'forlogic-core/tailwind';
-```
-
-The flat `forlogic-core` export re-exports everything for convenience.
-
----
-
-## Schema do Projeto
-
-> ⚠️ **SCHEMA = `common`**
->
-> Este é o **único local** onde o schema é definido. Toda query Supabase **DEVE** usar `.schema('common')`.
-
-```ts
-// ✅ CORRETO
-supabase.schema('common').from('tabela').select('*');
-
-// ❌ ERRADO (vai falhar em produção)
-supabase.from('tabela').select('*');
-```
-
----
-
-## Documentação
-
-| Documento | Caminho | Conteúdo |
-|-----------|---------|----------|
-| **Constituição** | [`spec/constitution.md`](spec/constitution.md) | Regras, convenções e melhores práticas obrigatórias |
-| **Design System** | `docs/design-system/` | Documentação de componentes, props e exemplos |
-| **Design System (visual)** | Rota `/ds` no app | Documentação interativa |
-
----
-
-## Cross-Project: Projeto Admin (DS + Lib)
-
-> Para consultar componentes, props, tipos, exemplos e implementação: use cross-project (`@Admin`).
-
-| O que procurar | Caminho no Admin |
-|----------------|------------------|
-| Código-fonte 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/` |
-| 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/` |
-| Prompt template | `docs/PROMPT_TEMPLATE.md` |
-| Project Knowledge template | `docs/PROJECT_KNOWLEDGE_TEMPLATE.md` |
-| Starter template | `docs/STARTER_TEMPLATE.md` |
-| Prompt de auditoria | `docs/AUDIT_PROMPT.md` |
-| Golden snippets | `docs/design-system/examples.md` |
-
----
-
-## Instrução para IA
-
-**QUANDO** criar ou modificar qualquer arquivo `.tsx` com JSX:
-
-- **SE** contém tabela, listagem ou CRUD → **LER** `@Admin docs/design-system/crud.md` e `@Admin docs/design-system/tables-grids.md` ANTES
-- **SE** contém formulário, input ou campo → **LER** `@Admin docs/design-system/inputs.md` e `@Admin docs/design-system/selectors.md` ANTES
-- **SE** contém modal ou confirmação → **LER** `@Admin docs/design-system/dialogs.md` ANTES
-- **SE** contém botões ou ações de linha → **LER** `@Admin docs/design-system/buttons-actions.md` ANTES
-- **SE** é estrutura de página/layout → **LER** `@Admin docs/design-system/layout.md` ANTES
-
-**SEMPRE** consultar `@Admin docs/design-system/examples.md` como referência de implementação.
-
-**VALIDAÇÃO pós-geração**: Todo import de componente visual DEVE vir de `forlogic-core`. Se criou componente local que existe na lib, refatore imediatamente.
+# forlogic-core
+
+Shared React component library, hooks, services, and configuration for Forlogic / Qualiex projects. Built on Vite + React 18 + Tailwind + shadcn primitives, opinionated for multi-tenant SaaS with Supabase.
+
+## Install
+
+```bash
+npm install forlogic-core
+```
+
+## Quick Start
+
+```tsx
+import { CoreProviders, Button } from 'forlogic-core';
+import { setupQualiexCore } from 'forlogic-core/setup';
+import ptBR from './i18n/pt-BR.json';
+
+setupQualiexCore(); // injects fonts, favicon, etc.
+
+function App() {
+  return (
+    <CoreProviders moduleAlias="my-module" appTranslations={{ 'pt-BR': ptBR }}>
+      <Button variant="primary">Hello</Button>
+    </CoreProviders>
+  );
+}
+```
+
+`CoreProviders` wires up auth, React Query, i18n and tooltip providers in the right order.
+
+## Modules
+
+| Module | What it provides | README |
+|---|---|---|
+| `forlogic-core` (UI) | shadcn-based components (`Button`, `Dialog`, `Combobox`, `Tabs`, ...) | `docs/design-system/` |
+| `forlogic-core` (CRUD) | `createCrudPage`, `CrudTable`, `BaseForm`, services hook | `docs/design-system/crud.md` |
+| `forlogic-core/auth` | OAuth + PKCE, multi-tenant alias routing, `useAuth` | [`lib/auth/README.md`](lib/auth/README.md) |
+| `forlogic-core/services` | `BaseService`, `createSimpleService`, Email, Error | [`lib/services/README.md`](lib/services/README.md) |
+| `forlogic-core/places` | Hierarchical Org Units (UO) selectors and tree view | [`lib/places/README.md`](lib/places/README.md) |
+| `forlogic-core/approval-flow` | Approval sidebar, dialogs and types | [`lib/approval-flow/README.md`](lib/approval-flow/README.md) |
+| `forlogic-core/media` | `VideoEditor`, `ImageEditor` with pluggable upload | [`lib/media/README.md`](lib/media/README.md) |
+| `forlogic-core/integrations` | Clarity, Supabase client | [`lib/integrations/README.md`](lib/integrations/README.md) |
+
+## Modular imports
+
+Subpath exports keep bundles lean:
+
+```ts
+import { Button } from 'forlogic-core/ui';
+import { createCrudPage } from 'forlogic-core/crud';
+import { createSecurityHeadersPlugin } from 'forlogic-core/vite';
+import { forlogicTailwindPreset } from 'forlogic-core/tailwind';
+```
+
+The flat `forlogic-core` export re-exports everything for convenience.
+
+---
+
+## Schema do Projeto
+
+> ⚠️ **SCHEMA = `common`**
+>
+> Este é o **único local** onde o schema é definido. Toda query Supabase **DEVE** usar `.schema('common')`.
+
+```ts
+// ✅ CORRETO
+supabase.schema('common').from('tabela').select('*');
+
+// ❌ ERRADO (vai falhar em produção)
+supabase.from('tabela').select('*');
+```
+
+---
+
+## Documentação
+
+| Documento | Caminho | Conteúdo |
+|-----------|---------|----------|
+| **Constituição** | [`spec/constitution.md`](spec/constitution.md) | Regras, convenções e melhores práticas obrigatórias |
+| **Design System** | `docs/design-system/` | Documentação de componentes, props e exemplos |
+| **Design System (visual)** | Rota `/ds` no app | Documentação interativa |
+
+---
+
+## Cross-Project: Projeto Admin (DS + Lib)
+
+> Para consultar componentes, props, tipos, exemplos e implementação: use cross-project (`@Admin`).
+
+| O que procurar | Caminho no Admin |
+|----------------|------------------|
+| Código-fonte 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/` |
+| 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/` |
+| Prompt template | `docs/PROMPT_TEMPLATE.md` |
+| Project Knowledge template | `docs/PROJECT_KNOWLEDGE_TEMPLATE.md` |
+| Starter template | `docs/STARTER_TEMPLATE.md` |
+| Prompt de auditoria | `docs/AUDIT_PROMPT.md` |
+| Golden snippets | `docs/design-system/examples.md` |
+
+---
+
+## Instrução para IA
+
+**QUANDO** criar ou modificar qualquer arquivo `.tsx` com JSX:
+
+- **SE** contém tabela, listagem ou CRUD → **LER** `@Admin docs/design-system/crud.md` e `@Admin docs/design-system/tables-grids.md` ANTES
+- **SE** contém formulário, input ou campo → **LER** `@Admin docs/design-system/inputs.md` e `@Admin docs/design-system/selectors.md` ANTES
+- **SE** contém modal ou confirmação → **LER** `@Admin docs/design-system/dialogs.md` ANTES
+- **SE** contém botões ou ações de linha → **LER** `@Admin docs/design-system/buttons-actions.md` ANTES
+- **SE** é estrutura de página/layout → **LER** `@Admin docs/design-system/layout.md` ANTES
+
+**SEMPRE** consultar `@Admin docs/design-system/examples.md` como referência de implementação.
+
+**VALIDAÇÃO pós-geração**: Todo import de componente visual DEVE vir de `forlogic-core`. Se criou componente local que existe na lib, refatore imediatamente.