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 'ei-core';
import { setupQualiexCore } from 'ei-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 | |---|---|---| | ei-core (UI) | shadcn-based components (Button, Dialog, Combobox, Tabs, ...) | docs/design-system/ | | ei-core (CRUD) | createCrudPage, CrudTable, BaseForm, services hook | docs/design-system/crud.md | | ei-core/auth | OAuth + PKCE, multi-tenant alias routing, useAuth | lib/auth/README.md | | ei-core/services | BaseService, createSimpleService, Email, Error | lib/services/README.md | | ei-core/places | Hierarchical Org Units (UO) selectors and tree view | lib/places/README.md | | ei-core/approval-flow | Approval sidebar, dialogs and types | lib/approval-flow/README.md | | ei-core/media | VideoEditor, ImageEditor with pluggable upload | lib/media/README.md | | ei-core/integrations | Supabase client | lib/integrations/README.md |

Modular imports

Subpath exports keep bundles lean:

import { Button } from 'ei-core/ui';
import { createCrudPage } from 'ei-core/crud';
import { createSecurityHeadersPlugin } from 'ei-core/vite';
import { forlogicTailwindPreset } from 'ei-core/tailwind';

The flat ei-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').

// ✅ 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 ei-core. Se criou componente local que existe na lib, refatore imediatamente.