@luminix/mui-cms 0.2.13 → 1.1.0

package/docs/extensibilidade.md

@@ -0,0 +1,261 @@
+# Extensibilidade
+
+O `@luminix/mui-cms` foi projetado para ser profundamente customizável sem exigir fork ou modificação do código-fonte. O mecanismo central é o padrão **Reducible** de `@luminix/support`.
+
+## O padrão Reducible
+
+Um serviço `Reducible` expõe "pontos de extensão" chamados **redutores**. Cada redutor é uma cadeia de funções que transforma um valor. O resultado final é a composição de todas as funções registradas, aplicadas em ordem de prioridade.
+
+```ts
+// assinatura geral
+ServiceFacade.reducer(
+    'nomeDoReducer',         // string — nome do ponto de extensão
+    (valorAtual, ...args) => novoValor,  // função transformadora
+    prioridade               // number — menor número roda primeiro (padrão: 10)
+);
+```
+
+Os redutores internos do `CmsServiceProvider` usam prioridade `0`. Registre os seus com prioridade maior para rodar depois (comportamento aditivo) ou menor para rodar antes (comportamento de pré-processamento).
+
+---
+
+## Onde registrar redutores
+
+Os redutores devem ser registrados **antes** da aplicação inicializar. O lugar ideal é dentro de um `ServiceProvider` customizado:
+
+```ts
+// src/providers/AppServiceProvider.ts
+import { ServiceProvider } from '@luminix/support';
+import { Cms, Icon, Filter } from '@luminix/mui-cms';
+import { Star } from '@mui/icons-material';
+
+class AppServiceProvider extends ServiceProvider {
+    register() {
+        // registre ícones aqui
+        Icon.registerIcon('Star', Star);
+    }
+
+    boot() {
+        // registre redutores aqui
+        Cms.reducer('menuItems', (items) => [
+            ...items,
+            {
+                key: 'relatorios',
+                text: 'Relatórios',
+                to: '/relatorios',
+                icon: Icon.render('Star'),
+            },
+        ]);
+    }
+}
+
+export default AppServiceProvider;
+```
+
+E passe o provider para o `LuminixCms`:
+
+```tsx
+import { LuminixCms } from '@luminix/mui-cms';
+import AppServiceProvider from './providers/AppServiceProvider';
+
+<LuminixCms providers={[AppServiceProvider]} />
+```
+
+---
+
+## Redutores do CmsService
+
+### componentMap
+
+Substitui componentes internos do painel:
+
+```ts
+import MeuLayout from './components/MeuLayout';
+
+Cms.reducer('componentMap', (map) => ({
+    ...map,
+    Layout: MeuLayout,
+}));
+```
+
+### menuItems
+
+Personaliza o menu lateral:
+
+```ts
+Cms.reducer('menuItems', (items, models) => {
+    // remove modelos do menu
+    return items.filter(item => item.key !== 'user');
+});
+```
+
+### cmsRoutes
+
+Adiciona rotas customizadas ao painel. A estrutura de rotas é um array com **um único elemento raiz** que envolve o `Layout` e os providers. Todas as páginas são filhas desse elemento raiz via `children`. Para que o layout (AppBar, Drawer, Notification, Dialog) seja aplicado na nova página, a rota deve ser adicionada em `routes[0].children`:
+
+```ts
+import Relatorios from './views/Relatorios';
+
+Cms.reducer('cmsRoutes', (routes, components) => {
+    const [root, ...rest] = routes;
+    return [
+        {
+            ...root,
+            children: [
+                ...(root.children ?? []),
+                {
+                    path: '/relatorios',
+                    element: <Relatorios />,
+                },
+            ],
+        },
+        ...rest,
+    ];
+});
+```
+
+> Adicionar a rota fora de `routes[0].children` (ex.: `[...routes, { path: '...' }]`) faz a página renderizar sem o Layout do painel.
+
+### LogoutButton
+
+O botão de logout no rodapé do drawer pode ser personalizado de duas formas:
+
+**1. Apenas o comportamento ao clicar** — via `Cms.logoutUsing()` no `boot()` do seu `ServiceProvider`:
+
+```ts
+class AppServiceProvider extends ServiceProvider {
+    boot() {
+        Cms.logoutUsing(() => {
+            // lógica de logout customizada
+            window.location.href = '/login';
+        });
+    }
+}
+```
+
+**2. Aparência e comportamento completos** — substituindo o componente `'Layout.Drawer.LogoutButton'`:
+
+```tsx
+import React from 'react';
+import { ListItem, ListItemButton, ListItemIcon, ListItemText } from '@mui/material';
+import { ExitToApp } from '@mui/icons-material';
+import type { LogoutButtonProps } from '@luminix/mui-cms';
+
+const MeuLogout: React.FC<LogoutButtonProps> = ({ collapsed }) => (
+    <ListItem disablePadding>
+        <ListItemButton onClick={() => { /* minha lógica */ }}>
+            <ListItemIcon><ExitToApp /></ListItemIcon>
+            {!collapsed && <ListItemText primary="Sair do sistema" />}
+        </ListItemButton>
+    </ListItem>
+);
+
+// No boot() do seu ServiceProvider:
+Cms.reducer('componentMap', (map) => ({
+    ...map,
+    'Layout.Drawer.LogoutButton': MeuLogout,
+}));
+```
+
+O componente recebe a prop `collapsed: boolean` — `true` quando o drawer está recolhido no modo desktop.
+
+---
+
+### wireModelFormProps
+
+Personaliza o formulário de modelo:
+
+```ts
+import { Cms } from '@luminix/mui-cms';
+
+Cms.reducer('wireModelFormProps', (props, item) => {
+    if (item?.getType() === 'post') {
+        return {
+            ...props,
+            // adicione campos confirmados, campos ocultos, etc.
+        };
+    }
+    return props;
+});
+```
+
+### model{Name}Columns
+
+Define as colunas da tabela para um modelo específico:
+
+```ts
+Cms.reducer('modelPostColumns', () => [
+    { key: 'title',      label: 'Título',     scope: 'row', component: 'th' },
+    { key: 'author',     label: 'Autor',      align: 'right' },
+    { key: 'created_at', label: 'Criado em',  align: 'right', size: 'small' },
+]);
+```
+
+> A convenção de nome é `model` + nome do modelo em StudlyCase + `Columns`.  
+> Ex.: `modelBlogPostColumns` para o modelo `blog_post`.
+
+---
+
+## Redutores do FilterService
+
+### filterableColumns
+
+Adiciona ou remove colunas do painel de filtros:
+
+```ts
+import { Filter } from '@luminix/mui-cms';
+
+Filter.reducer('filterableColumns', (columns, ModelClass) => {
+    if (ModelClass.getSchemaName() === 'post') {
+        return [
+            ...columns,
+            {
+                key: 'category_id',
+                label: 'Categoria',
+                type: 'autocomplete',
+                nullable: true,
+                is_relation: true,
+            },
+        ];
+    }
+    return columns;
+});
+```
+
+---
+
+## Redutores do Model (@luminix/core)
+
+O `@luminix/core` expõe o redutor `model` (e `model{Name}`) para customizar a classe de modelo:
+
+```ts
+import { Model } from '@luminix/core';
+
+Model.reducer('modelPost', (Base) => {
+    return class extends Base {
+        static plural() { return 'Posts do Blog'; }
+        static icon()   { return Icon.render('Article'); }
+    };
+});
+```
+
+Consulte a documentação do `@luminix/core` para a lista completa de redutores de modelo.
+
+---
+
+## Prioridades
+
+| Prioridade | Quando usar |
+|---|---|
+| `0` | Valores padrão da biblioteca (já usados internamente) |
+| `1`–`9` | Extensões do pacote `luminix/admin` ou integrações |
+| `10` (padrão) | Customizações da aplicação |
+| `> 10` | Overrides que precisam sobrescrever customizações anteriores |
+
+---
+
+## Próximos passos
+
+- [Ações](acoes.md) — exemplos práticos de redutores de ações
+- [Facades](facades.md) — referência completa dos redutores disponíveis por serviço
+- [Volta ao índice](index.md)

package/docs/facades.md

@@ -0,0 +1,195 @@
+# Facades
+
+As facades são a interface pública dos serviços internos da biblioteca. Elas seguem o padrão `Reducible`, o que significa que qualquer método pode ser extendido via redutores.
+
+## Cms
+
+Facade do `CmsService`. Gerencia rotas, menu, componentes e ações do painel.
+
+```ts
+import { Cms } from '@luminix/mui-cms';
+```
+
+### Métodos
+
+#### `Cms.getRoutes(): RouteObject[]`
+
+Retorna as rotas registradas no painel (formato do `react-router-dom`).
+
+#### `Cms.getMenuItems(): MenuItem[]`
+
+Retorna os itens do menu lateral. Por padrão inclui o Dashboard e um item para cada modelo do manifesto.
+
+#### `Cms.getComponents(): Record<string, React.ComponentType>`
+
+Retorna o mapa de componentes registrados (ver [Componentes](componentes.md)).
+
+#### `Cms.getComponent(name: string): React.ComponentType`
+
+Retorna um componente pelo nome.
+
+#### `Cms.getModelFormProps(item: ModelType): ModelFormProps`
+
+Retorna as props do `ModelForm` para um item específico.
+
+#### `Cms.getMassActions(ModelClass, currentTab): MassAction[]`
+
+Retorna as ações em massa disponíveis para o modelo e aba ativos.
+
+#### `Cms.getInstanceActions(ModelClass, currentTab): InstanceAction[]`
+
+Retorna as ações de instância (por linha) disponíveis.
+
+#### `Cms.getStaticActions(ModelClass, currentTab): StaticAction[]`
+
+Retorna as ações estáticas (nível de listagem, ex.: "Criar novo").
+
+#### `Cms.logoutUsing(callback: () => void): void`
+
+Registra um callback customizado para o botão de logout do menu lateral. Substitui o comportamento padrão de `auth().logout()`.
+
+```ts
+Cms.logoutUsing(() => {
+    window.location.href = '/login';
+});
+```
+
+Deve ser chamado no `boot()` de um `ServiceProvider`. Veja mais em [Extensibilidade — LogoutButton](extensibilidade.md#logoutbutton).
+
+### Redutores disponíveis
+
+| Redutor | Assinatura | Uso |
+|---|---|---|
+| `cmsRoutes` | `(routes, components, models) => routes` | Adicionar/modificar rotas |
+| `componentMap` | `(map) => map` | Substituir componentes internos |
+| `menuItems` | `(items, models) => items` | Personalizar o menu lateral |
+| `wireModelFormProps` | `(props, item) => props` | Alterar props do formulário por modelo |
+| `massActions` | `(actions, ModelClass, tab) => actions` | Adicionar/remover ações em massa |
+| `instanceActions` | `(actions, ModelClass, tab) => actions` | Adicionar/remover ações de instância |
+| `staticActions` | `(actions, ModelClass, tab) => actions` | Adicionar/remover ações estáticas |
+| `model{Name}Columns` | `() => Column[]` | Definir colunas da tabela por modelo |
+| `mass{Name}Actions` | idem massActions | Ações em massa específicas por modelo |
+| `instance{Name}Actions` | idem instanceActions | Ações de instância específicas por modelo |
+| `static{Name}Actions` | idem staticActions | Ações estáticas específicas por modelo |
+
+> `{Name}` é o nome do modelo em StudlyCase. Ex.: `modelPostColumns`, `massPostActions`.
+
+---
+
+## Filter
+
+Facade do `FilterService`. Gerencia os filtros avançados da tabela.
+
+```ts
+import { Filter } from '@luminix/mui-cms';
+```
+
+### Métodos
+
+#### `Filter.getInputType(type: string): string`
+
+Converte o tipo PHP/Eloquent do atributo no tipo de input HTML correspondente.
+
+| Tipo do modelo | Input retornado |
+|---|---|
+| `int`, `float`, `number` | `number` |
+| `date` | `date` |
+| `datetime`, `timestamp` | `datetime-local` |
+| `bool`, `boolean` | `boolean` |
+| `autocomplete` | `autocomplete` |
+| demais | `text` |
+
+#### `Filter.getOperators(): string[]`
+
+Retorna a lista de operadores configurada em `luminix.admin.filter.operators`.
+
+#### `Filter.getMatchingOperators(column: FilterColumn): InputOption[]`
+
+Retorna os operadores aplicáveis a uma coluna específica, filtrando por tipo e nullable.
+
+#### `Filter.getFilterableColumns(ModelClass): FilterColumn[]`
+
+Retorna as colunas filtráveis do modelo (atributos não ocultos e relacionamentos).
+
+#### `Filter.checkIfCanApplyFilters(columnsFilter: FilteredColumn[]): boolean`
+
+Verifica se o estado atual dos filtros é válido para envio (retorna `true` se houver filtro incompleto).
+
+### Redutores disponíveis
+
+| Redutor | Assinatura | Uso |
+|---|---|---|
+| `filterableColumns` | `(columns, ModelClass) => columns` | Adicionar/remover colunas filtráveis |
+
+---
+
+## Icon
+
+Serviço de gerenciamento de ícones. **Não** é uma facade `Reducible`; é um singleton instanciado diretamente.
+
+```ts
+import { Icon } from '@luminix/mui-cms';
+```
+
+### Ícones registrados por padrão
+
+A biblioteca pré-registra os seguintes ícones do `@mui/icons-material`:
+
+`Add`, `AddCircleOutline`, `ArrowDownward`, `ArrowDropDown`, `ArrowUpward`, `CategoryOutlined`, `ChevronLeft`, `ChevronRight`, `Close`, `DashboardOutlined`, `ExpandLess`, `ExpandMore`, `FilterList`, `FirstPage`, `HighlightOffOutlined`, `LastPage`, `Menu`, `MoreVert`, `PeopleOutlined`, `Search`, `SwapVert`
+
+### Métodos
+
+#### `Icon.registerIcon(name, component)`
+
+Registra um ícone individual:
+
+```ts
+import { Icon } from '@luminix/mui-cms';
+import { Star } from '@mui/icons-material';
+
+Icon.registerIcon('Star', Star);
+```
+
+#### `Icon.registerIcon(iconMap)`
+
+Registra múltiplos ícones de uma vez:
+
+```ts
+import { Star, Home } from '@mui/icons-material';
+
+Icon.registerIcon({ Star, Home });
+```
+
+#### `Icon.make(name: string): React.ComponentType`
+
+Retorna o componente do ícone pelo nome.
+
+#### `Icon.render(name: string, props?): React.ReactNode`
+
+Renderiza o ícone como nó React:
+
+```ts
+Icon.render('Star', { fontSize: 'small', color: 'primary' })
+```
+
+#### `Icon.forModel(model: string, icon: string)`
+
+Associa um ícone a um modelo. O nome do modelo deve ser o `schemaName` (snake_case):
+
+```ts
+Icon.forModel('post', 'Article');
+Icon.forModel('user', 'PeopleOutlined'); // já registrado por padrão
+```
+
+#### `Icon.all(): string[]`
+
+Lista os nomes de todos os ícones registrados.
+
+---
+
+## Próximos passos
+
+- [Hooks](hooks.md) — hooks para uso em componentes customizados
+- [Ações](acoes.md) — como definir ações para os modelos
+- [Extensibilidade](extensibilidade.md) — redutores em profundidade
+- [Volta ao índice](index.md)