@luminix/mui-cms 0.2.13 → 1.0.0

package/docs/acoes.md

@@ -0,0 +1,196 @@
+# Ações
+
+O sistema de ações permite adicionar comportamentos às telas de listagem dos modelos. Existem três tipos:
+
+| Tipo | Contexto | Exemplo de uso |
+|---|---|---|
+| **Estáticas** | Nível de listagem, sem item selecionado | "Criar novo post" |
+| **De instância** | Por linha da tabela | "Editar", "Excluir" |
+| **Em massa** | Múltiplos itens selecionados | "Excluir selecionados", "Restaurar" |
+
+---
+
+## ActionCallbackEvent
+
+Todo callback de ação recebe um objeto `ActionCallbackEvent` com utilitários prontos:
+
+```ts
+type ActionCallbackEvent = {
+    navigate: (path: string) => void;  // navega para uma rota interna
+    refresh:  () => void;              // recarrega a listagem atual
+    notify:   NotifyFunction;          // (notification: string | Notification) => void
+    dialog:   DialogFunction;          // (message: string | DialogMessage) => Promise<boolean | string>
+    t:        TFunction;               // função de tradução (i18next)
+};
+```
+
+Ações de instância recebem também `item: ModelType` (o registro da linha):
+
+```ts
+type InstanceActionCallbackEvent = ActionCallbackEvent & {
+    item: Model;
+};
+```
+
+Ações em massa recebem `selected: Collection<Model>` (todos os itens selecionados):
+
+```ts
+type MassActionCallbackEvent = ActionCallbackEvent & {
+    selected: Collection<Model>;
+};
+```
+
+---
+
+## Ações estáticas (StaticAction)
+
+Aparecem na barra de ferramentas da listagem (ex.: botão "Criar").
+
+```ts
+type StaticAction = {
+    key?:     string;
+    label:    string;
+    icon?:    React.ReactNode;
+    callback: (e: ActionCallbackEvent) => void;
+};
+```
+
+**Padrão registrado:** "Create {Model}" — navega para a rota de criação quando a aba ativa não é "trashed".
+
+### Adicionar uma ação estática global
+
+```ts
+import { Cms } from '@luminix/mui-cms';
+
+Cms.reducer('staticActions', (actions, ModelClass, tab) => [
+    ...actions,
+    {
+        key: 'export',
+        label: 'Exportar CSV',
+        callback: ({ notify }) => {
+            // lógica de exportação
+            notify('Exportação iniciada!', 'info');
+        },
+    },
+]);
+```
+
+### Adicionar ação apenas para um modelo específico
+
+```ts
+Cms.reducer('staticPostActions', (actions, ModelClass, tab) => [
+    ...actions,
+    {
+        key: 'publish-all',
+        label: 'Publicar todos',
+        callback: async ({ refresh, notify }) => {
+            await fetch('/api/posts/publish-all', { method: 'POST' });
+            refresh();
+            notify('Posts publicados!', 'success');
+        },
+    },
+]);
+```
+
+---
+
+## Ações de instância (InstanceAction)
+
+Aparecem no menu de contexto de cada linha da tabela.
+
+```ts
+type InstanceAction = {
+    key?:     string;
+    label:    string;
+    icon?:    React.ReactNode;
+    callback: (e: InstanceActionCallbackEvent) => void;
+};
+```
+
+**Padrão registrado:**
+- "Send to trash" / "Delete permanently" — para modelos com/sem soft deletes.
+- "Restore" + "Delete permanently" — quando a aba ativa é "trashed".
+
+### Adicionar ação de instância
+
+```ts
+import { Cms } from '@luminix/mui-cms';
+
+Cms.reducer('instanceActions', (actions, ModelClass, tab) => [
+    ...actions,
+    {
+        label: 'Ver detalhes',
+        callback: ({ item, navigate }) => {
+            navigate(`/posts/${item.getKey()}/detalhes`);
+        },
+    },
+]);
+```
+
+---
+
+## Ações em massa (MassAction)
+
+Aparecem quando um ou mais itens estão selecionados na tabela.
+
+```ts
+type MassAction = {
+    key:      string;        // obrigatório — identificador único
+    label:    string;
+    callback: (e: MassActionCallbackEvent) => void;
+};
+```
+
+**Padrão registrado:**
+- "Send to trash" / "Delete permanently" — conforme soft deletes e aba ativa.
+- "Restore" + "Delete permanently" — na aba "trashed".
+
+### Adicionar ação em massa
+
+```ts
+import { Cms } from '@luminix/mui-cms';
+import { Http } from '@luminix/core';
+
+Cms.reducer('massActions', (actions, ModelClass, tab) => [
+    ...actions,
+    {
+        key: 'archive',
+        label: 'Arquivar selecionados',
+        callback: async ({ selected, refresh, notify, dialog }) => {
+            const confirmed = await dialog({
+                title:   'Arquivar itens',
+                message: `Deseja arquivar ${selected.count()} itens?`,
+                type:    'confirm',
+            });
+            if (confirmed) {
+                const ids = selected.map(item => item.getKey()).toArray();
+                await Http.post('/api/posts/archive', { ids });
+                refresh();
+                notify('Itens arquivados!');
+            }
+        },
+    },
+]);
+```
+
+---
+
+## Ações padrão (comportamento automático)
+
+O `CmsServiceProvider` registra automaticamente as ações padrão com prioridade `0`. Suas ações customizadas podem ser adicionadas com prioridade maior (padrão `undefined`) para aparecerem antes ou depois das padrão.
+
+Para remover uma ação padrão, filtre pelo `key`:
+
+```ts
+Cms.reducer('staticActions', (actions) =>
+    actions.filter(a => a.key !== 'create')
+);
+```
+
+---
+
+## Próximos passos
+
+- [Extensibilidade](extensibilidade.md) — redutores em profundidade e como encadear transformações
+- [Hooks](hooks.md) — `useActionEvent` para montar o evento manualmente em componentes customizados
+- [Volta ao índice](index.md)

package/docs/componentes.md

@@ -0,0 +1,147 @@
+# Componentes
+
+## LuminixCms
+
+Componente raiz da aplicação. Deve ser renderizado uma única vez no ponto de entrada do projeto.
+
+```tsx
+import { LuminixCms } from '@luminix/mui-cms';
+
+<LuminixCms
+    theme={themeOptions}       // ThemeOptions (MUI) — opcional
+    themeArgs={[extraTheme]}   // object[] — argumentos adicionais para createTheme
+    providers={[MyProvider]}   // ServiceProvider[] — providers adicionais
+/>
+```
+
+Internamente, o `LuminixCms`:
+1. Cria o tema MUI com suporte automático a modo escuro.
+2. Registra `CmsServiceProvider` e `i18NextServiceProvider`.
+3. Delega a renderização ao `LuminixProvider` de `@luminix/react`, que inicializa o contêiner de aplicação e o roteador.
+
+---
+
+## Link
+
+Componente de navegação interna. Equivale ao `Link` do `react-router-dom`, mas integrado ao sistema de layout da biblioteca.
+
+```tsx
+import { Link } from '@luminix/mui-cms';
+
+<Link to="/posts">Ver posts</Link>
+```
+
+---
+
+## Providers de contexto
+
+Os providers a seguir são usados internamente pelas views e componentes da biblioteca. Em cenários avançados, você pode usá-los para acessar os contextos em componentes customizados.
+
+### DialogProvider
+
+Fornece o contexto de diálogos modais. Necessário para que `useDialog` funcione.
+
+```tsx
+import { DialogProvider } from '@luminix/mui-cms';
+
+<DialogProvider>
+    {/* seus componentes */}
+</DialogProvider>
+```
+
+### NotificationProvider
+
+Fornece o contexto de notificações toast. Necessário para `useNotify`.
+
+```tsx
+import { NotificationProvider } from '@luminix/mui-cms';
+
+<NotificationProvider
+    anchorOrigin={{ vertical: 'bottom', horizontal: 'right' }} // SnackbarProps
+    variant="filled" // 'filled' | 'outlined' | 'standard'
+>
+    {/* seus componentes */}
+</NotificationProvider>
+```
+
+### LayoutProvider
+
+Gerencia o estado do layout (drawer aberto/fechado, breakpoint, título da página).
+
+```tsx
+import { LayoutProvider } from '@luminix/mui-cms';
+
+<LayoutProvider>
+    {/* seus componentes */}
+</LayoutProvider>
+```
+
+### ModelProvider
+
+Disponibiliza a classe de modelo atual para os componentes filhos (ex.: dentro de uma tela de listagem).
+
+```tsx
+import { ModelProvider } from '@luminix/mui-cms';
+
+<ModelProvider Model={PostModel}>
+    {/* seus componentes */}
+</ModelProvider>
+```
+
+### TableProvider
+
+Fornece o estado da tabela (seleção, ordenação, paginação) para os componentes de `ModelIndex`.
+
+```tsx
+import { TableProvider } from '@luminix/mui-cms';
+
+<TableProvider>
+    {/* seus componentes */}
+</TableProvider>
+```
+
+---
+
+## Componentes internos (registrados via redutor)
+
+O `CmsServiceProvider` registra um mapa de componentes acessível via `Cms.getComponent(name)`. Esses componentes podem ser substituídos por customizados usando o redutor `componentMap`.
+
+| Chave | Componente padrão |
+|---|---|
+| `Layout` | Layout raiz da aplicação |
+| `Dashboard` | Tela inicial |
+| `ModelIndex` | Tela de listagem de modelos |
+| `ModelItem` | Tela de criação/edição |
+| `Error` | Tela de erro |
+| `Layout.AppBar` | Barra superior |
+| `Layout.AppLogo` | Logo no drawer |
+| `Layout.Drawer` | Menu lateral |
+| `Layout.SearchBar` | Campo de busca |
+| `Layout.BackButton` | Botão voltar |
+| `ModelIndex.Filter` | Painel de filtros avançados |
+| `ModelIndex.Table` | Tabela de dados |
+| `ModelIndex.Pagination` | Paginação |
+| `ModelIndex.MassActions` | Ações em massa |
+| `ModelIndex.InstanceActions` | Ações por linha |
+| `ModelIndex.StaticActions` | Ações globais (ex.: "Criar") |
+| `ModelIndex.Tabs` | Abas de filtro (ex.: lixeira) |
+
+Para substituir um componente:
+
+```ts
+import { Cms } from '@luminix/mui-cms';
+import MeuDashboard from './MeuDashboard';
+
+Cms.reducer('componentMap', (map) => ({
+    ...map,
+    Dashboard: MeuDashboard,
+}));
+```
+
+---
+
+## Próximos passos
+
+- [Facades](facades.md) — como usar `Cms`, `Filter` e `Icon`
+- [Hooks](hooks.md) — hooks disponíveis para uso em componentes customizados
+- [Volta ao índice](index.md)

package/docs/configuracao.md

@@ -0,0 +1,117 @@
+# Configuração
+
+## Tema MUI
+
+O `LuminixCms` aceita uma prop `theme` do tipo `ThemeOptions` (Material-UI). O tema padrão é:
+
+```ts
+{
+    palette: {
+        primary:   { main: '#1d9798' },
+        secondary: { main: '#fa510c' },
+    },
+}
+```
+
+Para sobrescrever, passe seu próprio objeto:
+
+```tsx
+<LuminixCms
+    theme={{
+        palette: {
+            primary:   { main: '#3f51b5' },
+            secondary: { main: '#f50057' },
+        },
+        typography: {
+            fontFamily: 'Inter, sans-serif',
+        },
+    }}
+/>
+```
+
+O modo escuro (`dark`) é ativado automaticamente quando o sistema operacional do usuário preferir `prefers-color-scheme: dark`.
+
+### themeArgs
+
+Para argumentos adicionais do `createTheme` (ex.: variáveis de componentes):
+
+```tsx
+<LuminixCms
+    theme={{ palette: { primary: { main: '#1d9798' } } }}
+    themeArgs={[{ components: { MuiButton: { defaultProps: { disableElevation: true } } } }]}
+/>
+```
+
+---
+
+## Layout
+
+O layout é configurado via chave `luminix.admin.layout` na configuração da aplicação (injetada pelo `luminix/frontend`). As opções disponíveis são definidas pelo tipo `CmsConfig`:
+
+```ts
+type CmsConfig = {
+    layout?: {
+        breakpoint?: 'xs' | 'sm' | 'md' | 'lg' | 'xl'; // padrão: 'md'
+        drawer?: {
+            width?: number; // largura do Drawer em px
+        };
+        appBar?: {
+            height?: number; // altura da AppBar em px
+            color?: string;  // cor de fundo da AppBar
+        };
+    };
+};
+```
+
+No Laravel, publique e edite o arquivo de configuração do `luminix/admin` para definir esses valores.
+
+---
+
+## URL base do painel
+
+Por padrão, o painel é montado em `/admin`. Para alterar, configure `luminix.admin.url` no backend:
+
+```php
+// config/luminix.php
+'admin' => [
+    'url' => '/painel',
+],
+```
+
+O `CmsServiceProvider` lê esse valor e configura o `basename` do `react-router-dom` automaticamente.
+
+---
+
+## Operadores de filtro disponíveis
+
+Os operadores usados nos filtros da tabela também são configuráveis via `luminix.admin.filter.operators`. O conjunto padrão inclui:
+
+`equals`, `notEquals`, `contains`, `startsWith`, `endsWith`, `greaterThan`, `greaterThanOrEquals`, `lessThan`, `lessThanOrEquals`, `between`, `notBetween`, `null`, `notNull`, `relation`
+
+---
+
+## Providers customizados
+
+Para registrar providers adicionais na inicialização da aplicação, use a prop `providers` do `LuminixCms`:
+
+```tsx
+import { LuminixCms } from '@luminix/mui-cms';
+import { ServiceProvider } from '@luminix/support';
+
+class MyProvider extends ServiceProvider {
+    register() { /* ... */ }
+    boot()     { /* ... */ }
+}
+
+<LuminixCms providers={[MyProvider]} />
+```
+
+Os providers `CmsServiceProvider` e `i18NextServiceProvider` são sempre incluídos automaticamente.
+
+---
+
+## Próximos passos
+
+- [Componentes](componentes.md) — `LuminixCms`, `Link` e providers de contexto
+- [Extensibilidade](extensibilidade.md) — customizações via redutores
+- [Volta ao índice](index.md)

package/docs/extensibilidade.md

@@ -0,0 +1,216 @@
+# 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.
+
+### 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)