@luminix/mui-cms 0.2.13 → 1.1.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,166 @@
+# 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>
+```
+
+---
+
+## LogoutButton
+
+Botão de logout exibido no rodapé do menu lateral. Pode ser importado diretamente quando precisar ser usado fora do contexto do Drawer padrão.
+
+```tsx
+import { LogoutButton } from '@luminix/mui-cms';
+
+<LogoutButton collapsed={false} />
+```
+
+| Prop | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `collapsed` | `boolean` | `false` | Quando `true`, exibe apenas o ícone (modo recolhido do drawer) com um Tooltip |
+
+O comportamento padrão ao clicar é chamar `auth().logout()` do `@luminix/core`. Veja [Extensibilidade](extensibilidade.md#logoutbutton) para formas de customização.
+
+---
+
+## 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.Drawer.LogoutButton` | Botão de logout no rodapé do drawer |
+| `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)