{"id":40726684,"url":"https://github.com/edsonmartins/archbase-react","last_synced_at":"2026-06-03T00:01:48.523Z","repository":{"id":183435658,"uuid":"669237389","full_name":"edsonmartins/archbase-react","owner":"edsonmartins","description":"Biblioteca de componentes React","archived":false,"fork":false,"pushed_at":"2026-05-25T22:14:08.000Z","size":370517,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-26T00:35:24.026Z","etag":null,"topics":["agile-development","hooks","react","typescript","ui-components"],"latest_commit_sha":null,"homepage":"https://react.archbase.com.br","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/edsonmartins.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-07-21T17:24:56.000Z","updated_at":"2026-05-25T22:14:10.000Z","dependencies_parsed_at":"2025-12-28T15:06:44.354Z","dependency_job_id":null,"html_url":"https://github.com/edsonmartins/archbase-react","commit_stats":{"total_commits":476,"total_committers":3,"mean_commits":"158.66666666666666","dds":0.4873949579831933,"last_synced_commit":"867bc06873b9fd01630c432ab11f1d7ed99d6248"},"previous_names":["edsonmartins/archbase-react"],"tags_count":145,"template":false,"template_full_name":null,"purl":"pkg:github/edsonmartins/archbase-react","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edsonmartins%2Farchbase-react","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edsonmartins%2Farchbase-react/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edsonmartins%2Farchbase-react/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edsonmartins%2Farchbase-react/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/edsonmartins","download_url":"https://codeload.github.com/edsonmartins/archbase-react/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edsonmartins%2Farchbase-react/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33841996,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agile-development","hooks","react","typescript","ui-components"],"created_at":"2026-01-21T14:09:23.445Z","updated_at":"2026-06-03T00:01:48.516Z","avatar_url":"https://github.com/edsonmartins.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Archbase React v4 🚀\n\nUma biblioteca moderna de componentes React TypeScript com arquitetura modular para desenvolvimento rápido de aplicações SAAS.\n\n## ✨ Principais Melhorias\n\n- **🔧 Stack Moderna**: React 19, TypeScript 5.7+, Vite 6, Vitest\n- **🎨 Mantine 9.2.1**: design system atualizado, novo runtime de estilos\n- **📦 Arquitetura Modular**: 12 pacotes independentes com tree-shaking otimizado\n- **⚡ Performance**: Build 5x mais rápido com Vite 6 e bundles otimizados\n- **🎯 Type Safety**: TypeScript rigoroso com inferência melhorada\n- **🧪 Testing**: Vitest nativo com cobertura completa\n- **🏗️ Monorepo**: pnpm workspaces com Turbo para builds paralelos\n- **🚀 Scripts Simplificados**: Build, empacotamento e publicação automatizados\n\n## 🆕 Novidades na v4\n\nReleases 4.0.x trouxeram, além da migração para Mantine 9, várias melhorias acumulativas:\n\n- **AG-Grid como engine padrão do `ArchbaseDataGrid`** (`@archbase/components`).\n  A implementação MUI X continua disponível para compatibilidade, mas o export\n  default agora vem do AG-Grid Community 35+.\n- **Scroll perf** (release 4.0.25): `AgGridReact` envolvido em `React.memo`,\n  `getRowId` estabilizado, `useStableChildren` evita rebuild de `columnDefs`\n  quando as colunas são estruturalmente iguais; objeto `sx` da DataGrid (MUI X)\n  movido para `useMemo`. Recomendações da [doc oficial AG-Grid](https://www.ag-grid.com/javascript-data-grid/scrolling-performance/).\n- **`truncate` em colunas** (4.0.25): nova prop `truncate?: boolean` em\n  `ArchbaseDataGridColumn` que ativa ellipsis + tooltip nativo do browser,\n  contornando o overflow horizontal causado pelo wrapper flex do AG-Grid.\n- **`actionsColumnWidth` default 120px** (4.0.24): antes era 60px, espremia 3+ ícones.\n- **KeepAlive migrado para `keepalive-for-react`** (4.0.0): preserva estado das\n  tabs entre navegações; expõe `useKeepAliveVisibility`, `useArchbaseRouteParams`,\n  `useKeepAliveCache`.\n- **Feedback visual ao fechar uma aba** (4.0.26): o `X` da aba vira um Loader\n  enquanto o close está em andamento e a barra de progresso (`NavigationProgress`)\n  dispara imediatamente; fallback timeout do reducer reduzido de 100ms para 0ms.\n- **`ArchbaseAdminMainLayout`** ganhou variantes de sidebar (`standard`, `rail`,\n  `minimal`) via `ArchbaseMantineSidebar`.\n- **~60 novos componentes** documentados em [RELEASE_NOTES_v4.0.0.md](./RELEASE_NOTES_v4.0.0.md).\n\n## 🔧 Scripts Rápidos\n\n```bash\n# Build produção\npnpm run build\n\n# Build debug\npnpm run build:debug\n\n# Build + publicação (produção)\npnpm run build:publish\n\n# Build + publicação (debug no Verdaccio)\npnpm run build:publish:debug\n\n# Limpar projeto\npnpm run clean\n```\n\n\u003e 📖 **Documentação completa**: [BUILD-DEBUG.md](./BUILD-DEBUG.md)\n\n## 📁 Estrutura de Pacotes\n\n```\n@archbase/core          # Fundação (contexts, error handling, IOC, validator)\n@archbase/data          # Camada de dados (datasource, service, hooks)\n@archbase/components    # Componentes base (editors, buttons, containers)\n@archbase/layout        # Layouts avançados (spaces, masonry, tabs)\n@archbase/security      # Sistema de segurança (auth, users, permissions)\n@archbase/security-ui   # Componentes UI de segurança (forms, modals, views)\n@archbase/feature-flags # Feature flags com Unleash\n@archbase/admin         # Layout administrativo completo\n@archbase/advanced      # Componentes avançados (querybuilder, datagrid)\n@archbase/template      # Templates CRUD (form, panel, masonry, space)\n@archbase/tools         # Ferramentas para desenvolvedores (debug, performance, dev-utils)\n@archbase/ssr           # Utilitários SSR para TanStack Start e Next.js\n```\n\n## 🛠️ Tecnologias\n\n- **React 19** com React Compiler\n- **TypeScript 5.7+** \n- **Vite 6** (build system)\n- **Vitest** (testing framework)\n- **pnpm workspaces** (monorepo)\n- **Turbo** (build pipeline)\n- **Mantine 9.2.1** (UI components)\n- **AG-Grid Community 35+** (DataGrid engine)\n- **Tabler Icons 3.x** (iconografia)\n- **TanStack Query v5** (data fetching)\n- **Zustand 5** (state management)\n- **i18next** (internacionalização)\n\n## 🚀 Instalação\n\n### Dependências Obrigatórias\n\nTodos os pacotes requerem React e Mantine como peer dependencies:\n\n```bash\n# Instalar dependências base\npnpm install react react-dom @mantine/core @mantine/hooks\n```\n\n### Instalação por Pacote\n\n```bash\n# Pacote básico\npnpm install @archbase/core\n\n# Componentes com dependências específicas\npnpm install @archbase/components @mantine/form @mantine/dates @mantine/notifications @mantine/modals @mantine/spotlight @mantine/dropzone @mantine/emotion @mantine/tiptap @tabler/icons-react\n\n# Segurança\npnpm install @archbase/security @mantine/modals @mantine/notifications @tabler/icons-react\n\n# Layout\npnpm install @archbase/layout @mantine/modals @mantine/notifications @tabler/icons-react\n\n# Administrativo\npnpm install @archbase/admin @mantine/modals @mantine/notifications @tabler/icons-react\n```\n\n### Instalação Completa\n\n```bash\n# Instalar todos os pacotes com dependências\npnpm install @archbase/core @archbase/data @archbase/components @archbase/layout @archbase/security @archbase/security-ui @archbase/feature-flags @archbase/admin @archbase/advanced @archbase/template @archbase/tools @archbase/ssr\npnpm install @mantine/core @mantine/hooks @mantine/form @mantine/dates @mantine/notifications @mantine/modals @mantine/spotlight @mantine/dropzone @mantine/emotion @mantine/tiptap @tabler/icons-react\n```\n\n## 📊 Performance dos Builds\n\n| Pacote | Bundle Size | Compressão | Melhoria |\n|---|---|---|---|\n| @archbase/core | 280KB | 93KB gzip | ⬇️ 51% menor |\n| @archbase/data | 105KB | 17KB gzip | ⬇️ 28% menor |\n| @archbase/layout | 51KB | 13KB gzip | ⬇️ 46% menor |\n| @archbase/security | 109KB | 24KB gzip | ≈ Otimizado |\n| @archbase/template | 40KB | 9KB gzip | ⬇️ 2% menor |\n| @archbase/admin | 218KB | 70KB gzip | ⬇️ 15% menor |\n| @archbase/advanced | 258KB | 57KB gzip | ⬇️ 3% menor |\n| @archbase/tools | 71KB | 15KB gzip | ⬇️ 3% menor |\n| @archbase/ssr | 85KB | 17KB gzip | ⬇️ 2% menor |\n| @archbase/components | TBD* | TBD* | ⬇️ 99%+ menor* |\n\n**Total**: ~1.17MB → ~315KB após compressão  \n🎯 **Redução de 78% no tamanho total** com dependências externas otimizadas\n\n*\\*Components requer rebuild completo para tamanho final\n\n## 🏗️ Status do Projeto\n\n✅ **Atual: v4.0.26** — Mantine 9, AG-Grid como engine padrão da DataGrid,\notimizações de performance e UX (close de tabs com feedback visual).\n\n✅ Migração v3 → v4 estável e em produção. Para detalhes consulte\n[RELEASE_NOTES_v4.0.0.md](./RELEASE_NOTES_v4.0.0.md).\n\n### ✅ Implementado\n\n- ✅ Estrutura base do monorepo com pnpm workspaces\n- ✅ Configuração Vite 6 + TypeScript 5.7\n- ✅ Package @archbase/core com IOC, contexts, validação\n- ✅ Package @archbase/data com datasources e hooks\n- ✅ Package @archbase/components com 80+ componentes\n- ✅ Package @archbase/layout com layouts avançados\n- ✅ Package @archbase/security com sistema de autenticação\n- ✅ Package @archbase/security-ui com componentes UI de segurança\n- ✅ Package @archbase/feature-flags com integração Unleash\n- ✅ Package @archbase/admin com layout administrativo\n- ✅ Package @archbase/advanced com componentes avançados\n- ✅ Package @archbase/template com templates CRUD\n- ✅ Package @archbase/tools com ferramentas para desenvolvedores\n- ✅ Package @archbase/ssr com suporte SSR para TanStack Start\n- ✅ Build pipeline com Turbo\n- ✅ Dependências externas (Mantine como peerDependencies)\n- ✅ Resolução de dependências circulares\n- ✅ Configuração de externals otimizada para todas as dependências\n- ✅ Bundle size reduzido em 76% com vite-plugin-external\n- ✅ Inversify e dependências DI tratadas como externas\n- ✅ Todos os packages compilando sem erros\n\n### 🔧 Arquitetura\n\n#### DataSource Pattern\n```typescript\n// Exemplo de uso do DataSource v2\nconst dataSource = useArchbaseDataSource\u003cPerson, string\u003e({\n  records: people,\n  validator: personValidator\n});\n\n// Binding automático com componentes\n\u003cArchbaseEdit \n  dataSource={dataSource}\n  dataField=\"name\"\n  label=\"Nome\"\n/\u003e\n```\n\n#### Dependency Injection\n```typescript\n// IoC Container configurado\nimport { ARCHBASE_IOC_API_TYPE } from '@archbase/core';\nimport { container } from '@archbase/core';\n\nconst apiService = container.get\u003cArchbaseRemoteApiService\u003e(\n  ARCHBASE_IOC_API_TYPE.RemoteApiService\n);\n```\n\n#### Componentes Modulares\n```typescript\n// Importação seletiva\nimport { ArchbaseEdit, ArchbaseButton } from '@archbase/components';\nimport { ArchbaseSpaceTemplate } from '@archbase/template';\nimport { ArchbaseLogin } from '@archbase/security';\nimport { UserModal, GroupModal } from '@archbase/security-ui';\nimport { useFlag } from '@archbase/feature-flags';\nimport { ArchbaseDebugPanel, logger } from '@archbase/tools';\n```\n\n## 🛠️ @archbase/tools - Ferramentas para Desenvolvedores\n\nO pacote **@archbase/tools** oferece uma suíte completa de ferramentas para debugging, monitoramento de performance e análise durante o desenvolvimento:\n\n### 🐛 **Ferramentas de Debug**\n- **ArchbaseConsoleLogger**: Logger avançado com cores e grupos\n- **ArchbaseDebugPanel**: Painel de debug em tempo real com filtros\n\n### ⚡ **Monitoramento de Performance**\n- **ArchbasePerformanceMonitor**: Monitor de performance com estatísticas detalhadas\n- **useArchbaseRenderTracker**: Hook para rastrear renders de componentes\n- **useArchbaseWhyDidYouRender**: Detector de causas de re-renders\n\n### 🔍 **Ferramentas de Desenvolvimento**\n- **ArchbaseLocalStorageViewer**: Visualizador de localStorage com export/import\n- **ArchbaseNetworkMonitor**: Monitor de requisições de rede em tempo real\n- **ArchbaseStateInspector**: Inspetor de estado com comparação e histórico\n- **ArchbaseErrorBoundary**: Error boundary aprimorado com debugging\n- **ArchbaseMemoryLeakDetector**: Detector de vazamentos de memória\n- **ArchbaseDataSourceInspector**: Debug avançado de DataSource (V1/V2) com monitoramento em tempo real\n\n### 💡 **Exemplo de Uso**\n\n```typescript\nimport { \n  ArchbaseDebugPanel, \n  ArchbaseErrorBoundary,\n  logger,\n  memoryLeakDetector \n} from '@archbase/tools';\n\n// Configuração completa para desenvolvimento\nfunction App() {\n  // Iniciar monitoramento de memória\n  React.useEffect(() =\u003e {\n    if (process.env.NODE_ENV === 'development') {\n      memoryLeakDetector.startMonitoring(10000);\n    }\n  }, []);\n\n  return (\n    \u003cArchbaseErrorBoundary\u003e\n      \u003cdiv\u003e\n        \u003cYourAppContent /\u003e\n        \u003cArchbaseDebugPanel position=\"bottom-right\" /\u003e\n      \u003c/div\u003e\n    \u003c/ArchbaseErrorBoundary\u003e\n  );\n}\n\n// Logger avançado\nlogger.info('Aplicação iniciada', { timestamp: Date.now() });\nlogger.group('API Operations');\nlogger.success('Dados carregados com sucesso');\nlogger.groupEnd();\n```\n\n**📖 Documentação Completa**: [packages/tools/README.md](./packages/tools/README.md)\n\n## 🌐 @archbase/ssr - Suporte Server-Side Rendering\n\nO pacote **@archbase/ssr** oferece suporte completo a **SSR (Server-Side Rendering)** para frameworks modernos como **TanStack Start** e **Next.js**:\n\n### 🚀 **Principais Recursos**\n- **TanStack Start** integração completa com roteamento tipado\n- **DataSource SSR** com serialização/deserialização automática  \n- **Hidratação otimizada** com estado consistente servidor/cliente\n- **Hooks SSR-safe** que funcionam em qualquer ambiente\n- **Performance otimizada** com payload mínimo\n\n### 💡 **Exemplo de Uso com TanStack Start**\n\n```typescript\n// app.tsx\nimport { ArchbaseSSRProvider, ArchbaseTanStackProvider } from '@archbase/ssr';\n\nfunction App() {\n  return (\n    \u003cArchbaseSSRProvider\u003e\n      \u003cArchbaseTanStackProvider\u003e\n        \u003cRouter /\u003e\n      \u003c/ArchbaseTanStackProvider\u003e\n    \u003c/ArchbaseSSRProvider\u003e\n  );\n}\n\n// routes/users.tsx  \nimport { useArchbaseSSRDataSource } from '@archbase/ssr';\n\nexport const Route = createFileRoute('/users')({\n  component: UsersPage,\n  loader: async ({ context }) =\u003e {\n    // Dados pré-carregados no servidor\n    const users = await fetchUsers();\n    return { users };\n  }\n});\n\nfunction UsersPage() {\n  const { users } = Route.useLoaderData();\n  \n  const { dataSource, isHydrated } = useArchbaseSSRDataSource('users', {\n    initialRecords: users,\n    autoHydrate: true\n  });\n\n  return (\n    \u003cdiv\u003e\n      {dataSource.getRecords().map(user =\u003e (\n        \u003cArchbaseEdit key={user.id} dataSource={dataSource} dataField=\"name\" /\u003e\n      ))}\n    \u003c/div\u003e\n  );\n}\n```\n\n### 🎯 **Vantagens**\n- **Zero configuração** para casos básicos\n- **100% compatível** com componentes Archbase existentes\n- **Type-safe** com TypeScript completo\n- **Performance superior** com hidratação otimizada\n- **Fallbacks automáticos** para ambientes sem SSR\n\n**📖 Documentação Completa**: [packages/ssr/README.md](./packages/ssr/README.md)\n\n## 🔐 @archbase/security-ui - Componentes UI de Segurança\n\nO pacote **@archbase/security-ui** oferece componentes de interface prontos para gestão de segurança:\n\n### 🚀 **Principais Recursos**\n\n- **UserModal**: Modal completo para criação/edição de usuários\n- **GroupModal**: Modal para gestão de grupos e permissões\n- **ArchbaseSecurityView**: Visualização de configurações de segurança\n- **Formulários validados**: Com integração automática com DataSource\n\n### 💡 **Exemplo de Uso**\n\n```typescript\nimport { UserModal, GroupModal } from '@archbase/security-ui';\n\nfunction SecurityPage() {\n  const [isUserModalOpen, setUserModalOpen] = useState(false);\n  const [isGroupModalOpen, setGroupModalOpen] = useState(false);\n\n  return (\n    \u003c\u003e\n      \u003cButton onClick={() =\u003e setUserModalOpen(true)}\u003eNovo Usuário\u003c/Button\u003e\n      \u003cButton onClick={() =\u003e setGroupModalOpen(true)}\u003eNovo Grupo\u003c/Button\u003e\n\n      \u003cUserModal\n        opened={isUserModalOpen}\n        onClose={() =\u003e setUserModalOpen(false)}\n        dataSource={userDataSource}\n      /\u003e\n\n      \u003cGroupModal\n        opened={isGroupModalOpen}\n        onClose={() =\u003e setGroupModalOpen(false)}\n        dataSource={groupDataSource}\n      /\u003e\n    \u003c/\u003e\n  );\n}\n```\n\n## 🚦 @archbase/feature-flags - Feature Flags com Unleash\n\nO pacote **@archbase/feature-flags** integra o sistema de feature flags **Unleash** ao Archbase React:\n\n### 🚀 **Principais Recursos**\n\n- **Integração Unleash**: Cliente proxy do Unleash para React\n- **Hooks otimizados**: `useFlag` e `useVariant` para feature flags\n- **Type-safe**: Tipagem completa para flags e variantes\n- **Performance otimizada**: Cache inteligente de flags\n\n### 💡 **Exemplo de Uso**\n\n```typescript\nimport { useFlag, useVariant } from '@archbase/feature-flags';\n\nfunction NewFeature() {\n  const isEnabled = useFlag('new-feature');\n  const variant = useVariant('new-feature');\n\n  if (!isEnabled) {\n    return \u003cLegacyFeature /\u003e;\n  }\n\n  return \u003cModernFeature variant={variant} /\u003e;\n}\n```\n\n### 🎯 **Vantagens**\n- **Rollout control**: Libere recursos gradualmente\n- **A/B testing**: Teste diferentes variantes\n- **Kill switch**: Desative recursos instantaneamente\n- **Targeting**: Habilite recursos para usuários específicos\n\n## 🚀 DataSource v2 - Nova Geração\n\n### **✨ Revolução no Gerenciamento de Dados**\n\nO **DataSource v2** representa uma evolução completa do sistema de dados do Archbase React, oferecendo **100% compatibilidade** com v1 e benefícios significativos:\n\n#### **🎯 Principais Benefícios**\n\n| Recurso | V1 | V2 | Impacto |\n|---------|----|----|---------|\n| **Imutabilidade** | ❌ Mutável | ✅ Immer integrado | 50% menos re-renders |\n| **Type Safety** | Básica | ✅ Completa com generics | Zero erros de tipo |\n| **Array Operations** | Manual | ✅ Nativo tipo-seguro | Desenvolvimento 3x mais rápido |\n| **React Integration** | Listeners manuais | ✅ Hooks otimizados | Código mais limpo |\n| **TanStack Query** | Não integrado | ✅ Suporte nativo | Cache inteligente |\n| **Backward Compatibility** | - | ✅ 100% compatível | Zero breaking changes |\n\n#### **🔄 Compatibilidade Total - Zero Breaking Changes**\n\n```typescript\n// ✅ V1: Continua funcionando exatamente igual\nconst dataSourceV1 = new ArchbaseDataSource('pessoas', options);\n\n// ✅ V2: Nova implementação com benefícios extras\nconst dataSourceV2 = new ArchbaseDataSourceV2({\n  name: 'pessoas',\n  records: pessoasList\n});\n\n// ✅ Ambos funcionam com os mesmos componentes\n\u003cArchbaseEdit dataSource={dataSourceV1} dataField=\"nome\" /\u003e\n\u003cArchbaseEdit dataSource={dataSourceV2} dataField=\"nome\" /\u003e\n```\n\n#### **🏆 91 Componentes Migrados**\n\n**Todos os componentes principais foram migrados com detecção automática V1/V2:**\n\n- **📝 Editores (22/22)**: ArchbaseEdit, ArchbaseSelect, ArchbaseCheckbox, ArchbaseAsyncSelect, etc.\n- **🔐 Segurança (6/6)**: UserModal, GroupModal, ArchbaseSecurityView, etc.\n- **🔍 QueryBuilder (4/4)**: ArchbaseAdvancedFilter, ArchbaseCompositeFilter, etc.\n- **📊 Templates (7/7)**: ArchbaseFormTemplate, ArchbaseGridTemplate, etc.\n- **🗂️ Diversos (5/5)**: ArchbaseList, ArchbaseImage, ArchbaseThemeEditor, etc.\n\n#### **📚 Documentação Completa**\n\nConsulte a documentação detalhada do DataSource v2:\n\n- **[📖 Visão Geral](./docs/datasource-v2.mdx)** - Introdução e conceitos\n- **[🚀 Guia de Migração](./docs/datasource-v2-migration.mdx)** - Estratégias de migração\n- **[📋 API Reference](./docs/datasource-v2-api.mdx)** - Documentação completa da API\n- **[💡 Exemplos Práticos](./docs/datasource-v2-examples.mdx)** - Casos de uso reais\n- **[🎯 Executive Summary](./docs/datasource-v2-executive-summary.mdx)** - Resumo executivo\n- **[🔗 TanStack Integration](./docs/datasource-v2-tanstack-examples.mdx)** - Integração com TanStack Query\n- **[🛠️ Padrões de Compatibilidade](./docs/datasource-v2-compatibility-pattern.mdx)** - Detalhes técnicos\n\n#### **⚡ Performance Otimizada**\n\n```typescript\n// Exemplo de operação otimizada no V2\nconst dataSource = useArchbaseDataSourceV2\u003cPessoa\u003e({\n  name: 'pessoas',\n  records: pessoasList,\n  // Imutabilidade automática com Immer\n  // 50% menos re-renders\n  // Type safety completa\n});\n\n// Operações em arrays são tipo-seguras\ndataSource.appendToFieldArray('enderecos', novoEndereco);\ndataSource.removeFromFieldArray('enderecos', index);\n```\n\n#### **🎯 Estratégia de Adoção**\n\n**Para Projetos Novos**: Use V2 desde o início  \n**Para Projetos Existentes**: Migração gradual com feature flags  \n**Zero Riscos**: V1 continua funcionando normalmente\n\n## 🌍 Sistema de Localização\n\nO Archbase React v3 inclui um sistema de localização robusto e flexível baseado em i18next:\n\n### 🚀 Configuração Rápida\n\n```typescript\n// main.tsx\nimport { initArchbaseI18nEarly } from '@archbase/core'\nimport translation_en from './locales/en/translation.json'\nimport translation_ptbr from './locales/pt-BR/translation.json'\n\n// Inicializar antes de renderizar\ninitArchbaseI18nEarly('minha-app', {\n  en: translation_en,\n  'pt-BR': translation_ptbr\n})\n\n// App.tsx\n\u003cArchbaseGlobalProvider\n  translationName=\"minha-app\"\n  translationResource={{\n    en: translation_en,\n    'pt-BR': translation_ptbr\n  }}\n\u003e\n  \u003cMinhaAplicacao /\u003e\n\u003c/ArchbaseGlobalProvider\u003e\n```\n\n### 💡 Uso em Componentes\n\n```typescript\n// React Components\nimport { useArchbaseTranslation } from '@archbase/core'\n\nfunction MeuComponente() {\n  const { t } = useArchbaseTranslation()\n  \n  return (\n    \u003cdiv\u003e\n      \u003ch1\u003e{t('Bem-vindo')}\u003c/h1\u003e\n      \u003cbutton\u003e{t('archbase:signIn')}\u003c/button\u003e\n    \u003c/div\u003e\n  )\n}\n\n// Funções e Classes\nimport { archbaseI18next } from '@archbase/core'\n\nconst message = archbaseI18next.t('minha-app:Dashboard')\n```\n\n### 🎯 Principais Recursos\n\n- ✅ **Inicialização Precoce**: Traduções disponíveis antes da renderização\n- ✅ **Híbrido**: Suporte para componentes React e funções utilitárias\n- ✅ **Namespaces**: Separação clara entre traduções da lib e aplicação\n- ✅ **Performance**: Sem overhead de contexto React\n- ✅ **TypeScript**: Suporte completo com tipagem\n\n**📖 Documentação Completa**: [LOCALIZATION.md](./LOCALIZATION.md)\n\n## 🔄 Migração da v3 para v4\n\n### Principais Breaking Changes\n\n1. **Mantine 8 → 9**: peer dependencies sobem para `9.2.1`.\n   ```bash\n   pnpm add @mantine/core@9.2.1 @mantine/hooks@9.2.1 \\\n            @mantine/dates@9.2.1 @mantine/form@9.2.1 \\\n            @mantine/notifications@9.2.1 @mantine/modals@9.2.1 \\\n            @mantine/spotlight@9.2.1 @mantine/charts@9.2.1 \\\n            @mantine/code-highlight@9.2.1\n   ```\n\n2. **Renomes de props do Mantine 9** (aplicar no seu código consumidor):\n   - `\u003cGrid gutter=\u003e` → `\u003cGrid gap=\u003e`\n   - `\u003cCollapse in=\u003e` → `\u003cCollapse expanded=\u003e`\n   - `useFullscreen()` → `useFullscreenDocument()`\n   - `\u003cText color=\"...\"\u003e` continua funcionando mas `c=` é o atalho preferido.\n\n3. **`@tabler/icons-react` 2.x → 3.x**: peer dep agora `^3.27.0`.\n\n4. **DataGrid passa a ser AG-Grid** (`@archbase/components`).\n   A API de `\u003cArchbaseDataGrid\u003e` + `\u003cColumns\u003e` + `\u003cArchbaseDataGridColumn\u003e` foi\n   preservada e funciona como antes. Cell renderers e value formatters\n   continuam funcionando.\n\n5. **KeepAlive interno**: troca de implementação custom para\n   `keepalive-for-react`. Se você usava apenas `keepAlive: true` no\n   `ArchbaseNavigationItem`, nada muda. Se você dependia de APIs internas como\n   `register`/`unregister`/`touchAccess`, migre para `useKeepAliveCache()` —\n   agora exposta com `destroy(cacheKey)`, `destroyAll()`, `destroyOther(...)`.\n\n6. **`actionsColumnWidth` default**: 60 → 120. Caso tenha um override explícito\n   `actionsColumnWidth={60}`, remova para usar o novo default.\n\n### Migração da v2 (legado)\n\n```typescript\n// v2\nimport { ArchbaseEdit } from 'archbase-react';\n\n// v4\nimport { ArchbaseEdit } from '@archbase/components';\n```\n\nPara mais detalhes consulte [RELEASE_NOTES_v4.0.0.md](./RELEASE_NOTES_v4.0.0.md).\n\n## 🎯 Próximos Passos\n\n- [ ] Documentação detalhada completa\n- [ ] Testes de integração completos\n- [ ] Exemplos de uso prático\n- [ ] Migração assistida da v2\n\n## 🧭 Portal editorial (Docusaurus)\n\nO `docs-site` monta um portal com Getting Started, guias (Forms, DataGrid, Templates, Security, Migração) e receitas que referenciam o `component-catalog.json` (links canônicos).\n\n### Comandos úteis\n\n```bash\n# Desenvolvimento da documentação\npnpm --filter docs-site install\npnpm --filter docs-site dev\n\n# Build da documentação\npnpm --filter docs-site build\n\n# Gerar catálogo de componentes\npnpm generate:catalog\n```\n\n## 🚀 Releases e Publicação\n\n### Criando um Release\n\nExistem duas formas de criar releases:\n\n#### Opção 1: Via Git Tag\n\n```bash\n# Criar e pushar tag (dispara workflow automático)\ngit tag v4.0.27\ngit push origin v4.0.27\n```\n\n\u003e ⚠️ A tag DEVE começar com `v` para os workflows (`publish-npm.yml` e\n\u003e `build-and-publish.yml`) dispararem. Eles têm trigger `tags: 'v*'`.\n\n#### Opção 2: Via GitHub Actions (Manual)\n\n1. Vá para: https://github.com/edsonmartins/archbase-react/actions/workflows/release.yml\n2. Clique em \"Run workflow\"\n3. Informe a versão (ex: 4.0.27)\n4. Selecione se é pre-release\n\n### O que acontece no Release\n\nO workflow `.github/workflows/release.yml` executa:\n\n1. **Build**: Compila todos os pacotes\n2. **Pack**: Gera arquivos `.tgz` de cada pacote\n3. **Release Notes**: Gera notas com commits desde a última versão\n4. **GitHub Release**: Cria release com artefatos\n5. **Deploy Docs**: Publica documentação em react.archbase.dev (apenas releases estáveis)\n\n### Estrutura de Versões\n\n- `v4.0.26` - Release estável\n- `v4.0.26-beta.1` - Pre-release (beta)\n- `v4.0.26-alpha.1` - Pre-release (alpha)\n\n### Deploy Automático da Documentação\n\nA cada push na branch `main` ou `archbase-react-develop`, o workflow `.github/workflows/deploy-docs-vps.yml`:\n\n1. Build dos pacotes\n2. Build da documentação Next.js\n3. Deploy no VPS via Self-Hosted Runner\n4. Atualização do container Docker Swarm\n\n**Documentação disponível em**: https://react.archbase.dev\n\n## 🤝 Desenvolvimento\n\n### 🔧 Scripts Simplificados\n\nO projeto foi completamente reorganizado com scripts modernos e simplificados:\n\n```bash\n# Atualizar versão de todos os packages\npnpm run version:update 4.0.26\n\n# Build de todos os packages\npnpm run build              # Modo release\npnpm run build:debug        # Modo debug (com timestamp)\n\n# Empacotar packages\npnpm run pack               # Modo release\npnpm run pack:debug         # Modo debug\n\n# Publicar no Verdaccio\npnpm run publish:verdaccio\n\n# Limpar projeto\npnpm run clean\n\n# Outros comandos úteis\npnpm run format             # Formatar código\npnpm run lint               # Verificar código\n```\n\n### 📋 Fluxo de Trabalho Completo\n\n```bash\n# 1. Atualizar versão (quando necessário)\npnpm run version:update 4.0.26\n\n# 2. Build completo\npnpm run build\n\n# 3. Empacotar packages\npnpm run pack\n\n# 4. Publicar no Verdaccio\npnpm run publish:verdaccio\n```\n\n### 🎯 Como Funciona\n\n#### **Gestão de Dependências**\n- **Desenvolvimento**: Usa `workspace:*` para sempre usar a versão local\n- **Build/Pack**: Converte automaticamente para versões específicas\n- **Zero conflitos**: Sem problemas de versionamento circular\n\n#### **Build Inteligente**\n- Compila packages em ordem de dependência\n- Valida se todos os arquivos foram gerados\n- Modo debug adiciona timestamp nas versões\n- Estatísticas detalhadas de tamanho\n\n#### **Empacotamento Otimizado**\n- Atualiza package.json automaticamente\n- Configura exports corretamente\n- Gera arquivos .tgz prontos para publicação\n- Backup automático em caso de erro\n\n### 📖 Documentação dos Scripts\n\nConsulte [SCRIPTS.md](./SCRIPTS.md) para documentação completa de todos os scripts disponíveis.\n\n## 🔧 Configuração do Verdaccio\n\n### Instalação e Configuração\n```bash\n# Instalar Verdaccio globalmente\npnpm install -g verdaccio\n\n# Iniciar Verdaccio\nverdaccio\n\n# Em outro terminal, configurar registry\npnpm config set registry http://localhost:4873\n\n# Ou configurar apenas para @archbase\npnpm config set @archbase:registry http://localhost:4873\n```\n\n### Publicação\n```bash\n# Publicar todos os packages\npnpm run publish:verdaccio\n```\n\n## 📄 Licença\n\nMIT © Edson Martins e Mayker Miyanaga \n\n---\n\n**Archbase React v4** - Desenvolvido com ❤️ para acelerar o desenvolvimento de aplicações SAAS modernas.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedsonmartins%2Farchbase-react","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedsonmartins%2Farchbase-react","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedsonmartins%2Farchbase-react/lists"}