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

npm install forlogic-core

Quick Start

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 | | forlogic-core/services | BaseService, createSimpleService, Email, Error | lib/services/README.md | | forlogic-core/approval-flow | Approval sidebar, dialogs and types | lib/approval-flow/README.md | | forlogic-core/media | VideoEditor, ImageEditor with pluggable upload | lib/media/README.md | | forlogic-core/integrations | Clarity, Supabase client | lib/integrations/README.md | | forlogic-core/sign | DocumentSigner (Clicksign + D4Sign) — requer Supabase | lib/sign/ | | forlogic-core/audit-trail | AuditTrailPage e diff drawers — requer Supabase | lib/audit-trail/ | | forlogic-core/action-plans | Planos de ação 5W2H — requer Supabase | lib/action-plans/ | | forlogic-core/leadership | Gestão de líderes/equipes — requer Supabase | lib/leadership/ | | forlogic-core/places | Hierarchical Org Units (UO) — requer Supabase | lib/places/README.md |

Backend opcional (Supabase)

A partir da versão com CoreProviders backend="...", o Supabase deixou de ser obrigatório:

• backend="supabase" (default, retrocompat) — exige SUPABASE_URL + SUPABASE_PUBLISHABLE_KEY (ou VITE_SUPABASE_* legadas; o vite.config.ts consolida ambos).
• backend="dotnet" — autentica apenas com tokens OAuth do Qualiex; não lê envs do Supabase.

Breaking change: os módulos sign, audit-trail, action-plans, leadership e places foram removidos do barrel principal e só podem ser importados via subpath (ex.: import { DocumentSigner } from 'forlogic-core/sign'). Eles continuam exigindo Supabase em runtime mesmo quando o app usa backend="dotnet".

Detalhes e exemplos: docs/design-system/patterns/core-providers.md.

Modular imports

Subpath exports keep bundles lean:

import { Button } from 'forlogic-core/ui';
import { createCrudPage } from 'forlogic-core/crud';
import { createSecurityHeadersPlugin } from 'forlogic-core/vite';
import { forlogicTailwindPreset } from 'forlogic-core/tailwind';
import { DocumentSigner } from 'forlogic-core/sign';            // requer Supabase
import { AuditTrailPage } from 'forlogic-core/audit-trail';     // requer Supabase
import { ActionPlanList } from 'forlogic-core/action-plans';    // requer Supabase
import { LeadershipManager } from 'forlogic-core/leadership';   // requer Supabase
import { PlacesTree } from 'forlogic-core/places';              // requer Supabase

O barrel forlogic-core re-exporta os módulos não-Supabase para conveniência.

Schema do Projeto

⚠️ SCHEMA = common

Este é o único local onde o schema é definido. Toda query Supabase DEVE usar .schema('common').

// ✅ 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 | 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.