@luminix/mui-cms 0.2.13 → 1.0.0

package/docs/facades.md

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

package/docs/hooks.md

@@ -0,0 +1,307 @@
+# Hooks
+
+Todos os hooks abaixo são exportados de `@luminix/mui-cms` e devem ser usados dentro da árvore de componentes do `LuminixCms`.
+
+```ts
+import { useNotify, useDialog, useTable, /* ... */ } from '@luminix/mui-cms';
+```
+
+---
+
+## Navegação e página
+
+### usePageTitle
+
+Retorna o título atual da página.
+
+```ts
+const title = usePageTitle(); // string
+```
+
+### useSetPageTitle
+
+Recebe um `title` como argumento e define o título da página enquanto o componente está montado. Remove o título automaticamente no unmount.
+
+```ts
+useSetPageTitle('Meus Posts');
+```
+
+Não retorna valor.
+
+### useSearch
+
+Torna a barra de busca visível enquanto o componente está montado. Esconde-a automaticamente no unmount.
+
+```ts
+useSearch();
+```
+
+Não recebe parâmetros nem retorna valor. Para ler o valor atual da busca (query string), use diretamente `useSearchParams` do `react-router-dom`.
+
+### useHasSearch
+
+Retorna `true` se a barra de busca está visível no momento.
+
+```ts
+const hasSearch = useHasSearch(); // boolean
+```
+
+### useBackButton
+
+Torna o botão voltar visível enquanto o componente está montado. Esconde-o automaticamente no unmount.
+
+```ts
+useBackButton();
+```
+
+Não recebe parâmetros nem retorna valor.
+
+### useHasBackButton
+
+Retorna `true` se o botão voltar está visível no momento.
+
+```ts
+const hasBack = useHasBackButton(); // boolean
+```
+
+---
+
+## Estado da tabela
+
+### useTable
+
+Retorna o valor completo do `TableContext`. Disponível dentro de componentes filhos do `TableProvider`.
+
+```ts
+const {
+    columns,      // Column[]
+    columnCount,  // number
+    massActions,  // MassAction[]
+    items,        // Collection<Model> | undefined
+    loading,      // boolean | undefined
+    error,        // Error | null
+    Model,        // typeof ModelType
+    selected,     // Collection<Model>
+} = useTable();
+```
+
+### useSelection
+
+Retorna utilitários para gerenciar a seleção de linhas da tabela.
+
+```ts
+const {
+    selected,                // Collection<Model> — itens selecionados (reativo)
+    indeterminate,           // boolean — true se parte dos itens está selecionada
+    allSelected,             // boolean — true se todos os itens da página estão selecionados
+    isSelected,              // (item: Model) => boolean
+    handleClearSelected,     // () => void
+    handleSelectToggle,      // (item: Model) => void
+    handleSelectToggleAll,   // () => void
+} = useSelection();
+```
+
+### useCurrentModel
+
+Retorna a classe do modelo ativo na tela atual. Disponível dentro de um `ModelProvider`.
+
+```ts
+const ModelClass = useCurrentModel(); // typeof ModelType
+```
+
+---
+
+## Notificações
+
+### useNotify
+
+Retorna a função `notify` para exibir notificações toast.
+
+```ts
+const notify = useNotify();
+
+// forma simplificada
+notify('Salvo com sucesso!');
+
+// com objeto completo
+notify({
+    message:  'Post publicado.',
+    severity: 'success',      // 'success' | 'error' | 'warning' | 'info'
+    title:    'Sucesso',      // opcional
+    actions: [                // opcional — botões de ação no toast
+        { label: 'Desfazer', callback: () => { /* ... */ } },
+    ],
+});
+```
+
+A assinatura completa:
+
+```ts
+type NotifyFunction = (notification: string | Notification) => void;
+
+type Notification = {
+    message:   React.ReactNode;
+    severity?: 'success' | 'error' | 'warning' | 'info';
+    title?:    React.ReactNode;
+    actions?:  { label: React.ReactNode; callback: () => void }[];
+};
+```
+
+### useNotifications
+
+Acessa o estado interno do `NotificationContext`. Útil para criar providers de notificação customizados.
+
+```ts
+const {
+    isOpen,
+    notify,
+    dismissNotification,
+    notifications,   // Notification[]
+    current,         // Notification | undefined — notificação sendo exibida
+    displacement,    // string — deslocamento CSS atual do Snackbar
+} = useNotifications();
+```
+
+### useDisplaceNotifications
+
+Define o deslocamento (offset) do Snackbar de notificações. Útil para evitar sobreposição com elementos fixos como FABs ou rodapés.
+
+```ts
+useDisplaceNotifications(value);
+```
+
+- `value: string | number | false` — número de unidades de espaçamento MUI, string CSS ou `false` para restaurar o valor padrão.
+- O deslocamento é restaurado automaticamente no unmount.
+
+```ts
+// desloca 8 unidades de espaçamento MUI acima do padrão
+useDisplaceNotifications(8);
+
+// restaura o deslocamento padrão
+useDisplaceNotifications(false);
+```
+
+---
+
+## Diálogos
+
+### useDialog
+
+Retorna a função `dialog` para abrir diálogos modais. Retorna uma `Promise` que resolve com o resultado da interação do usuário.
+
+```ts
+const dialog = useDialog();
+
+// forma simplificada — abre um alerta
+const confirmed = await dialog('Tem certeza?');
+
+// com objeto completo
+const result = await dialog({
+    title:        'Confirmar exclusão',
+    message:      'Esta ação não pode ser desfeita.',
+    type:         'confirm',   // 'alert' | 'confirm' | 'prompt'
+    dismissable:  true,        // permite fechar clicando fora
+    confirmText:  'Excluir',
+    cancelText:   'Cancelar',
+    // para type: 'prompt':
+    defaultValue: '',
+    textFieldProps: { label: 'Nome do arquivo' },
+});
+// result: true (confirmou) | false (cancelou) | string (prompt)
+```
+
+A assinatura completa:
+
+```ts
+type DialogFunction = (message: string | DialogMessage) => Promise<boolean | string>;
+
+type DialogMessage = {
+    title?:          React.ReactNode;
+    message:         React.ReactNode;
+    type?:           'alert' | 'confirm' | 'prompt';
+    dismissable?:    boolean;
+    confirmText?:    string;
+    cancelText?:     string;
+    defaultValue?:   string;           // valor inicial para type 'prompt'
+    dialogProps?:    Partial<DialogProps>;
+    textFieldProps?: Partial<TextFieldProps>;
+};
+```
+
+---
+
+## Layout
+
+### useLayoutConfig
+
+Lê um valor da configuração de layout (`CmsConfig['layout']`) pelo caminho (dot notation).
+
+```ts
+const drawerWidth = useLayoutConfig('drawer.width', 240);
+const appBarColor = useLayoutConfig('appBar.color');
+```
+
+Parâmetros:
+- `path: string` — caminho no objeto de layout (ex.: `'drawer.width'`, `'appBar.height'`)
+- `defaultValue?: unknown` — valor retornado se o caminho não estiver definido
+
+### useIsDesktopMode
+
+Retorna `true` quando a largura da tela está acima do breakpoint configurado em `layout.breakpoint`.
+
+```ts
+const isDesktop = useIsDesktopMode(); // boolean
+```
+
+### useMenu
+
+Retorna o estado de abertura do Drawer lateral e funções para controlá-lo.
+
+```ts
+const {
+    open,                // boolean — true se o Drawer está aberto
+    handleDrawerOpen,    // () => void
+    handleDrawerClose,   // () => void
+    toggle,              // () => void
+} = useMenu();
+```
+
+---
+
+## Eventos e ações
+
+### useActionEvent
+
+Monta o objeto `ActionCallbackEvent` — útil para chamar manualmente callbacks de ações em componentes customizados.
+
+```ts
+const event = useActionEvent();
+
+event.navigate('/posts');
+event.refresh();
+event.notify('Salvo!');
+await event.dialog({ message: 'Confirmar?' });
+event.t('chave.de.traducao');
+```
+
+### useHandleError
+
+Retorna uma função que trata erros de requisição e os exibe como notificação.
+
+```ts
+const handleError = useHandleError();
+
+try {
+    await model.save();
+} catch (err) {
+    handleError(err);
+}
+```
+
+---
+
+## Próximos passos
+
+- [Ações](acoes.md) — como definir ações estáticas, de instância e em massa
+- [Extensibilidade](extensibilidade.md) — customizações via redutores
+- [Volta ao índice](index.md)

package/docs/index.md

@@ -0,0 +1,25 @@
+# Documentação — @luminix/mui-cms
+
+Bem-vindo à documentação da biblioteca `@luminix/mui-cms`.
+
+## Páginas
+
+| Página | Descrição |
+|---|---|
+| [Introdução](introducao.md) | O que é a biblioteca, visão geral do ecossistema Luminix |
+| [Instalação](instalacao.md) | Como instalar e configurar o ambiente |
+| [Configuração](configuracao.md) | Opções de configuração do layout e tema |
+| [Componentes](componentes.md) | `LuminixCms`, `Link` e providers de contexto |
+| [Facades](facades.md) | `Cms`, `Filter` e `Icon` |
+| [Hooks](hooks.md) | Todos os hooks exportados pela biblioteca |
+| [Ações](acoes.md) | Ações estáticas, de instância e em massa |
+| [Extensibilidade](extensibilidade.md) | Como customizar via redutores |
+| [Referência de tipos](tipos.md) | Tipos TypeScript exportados |
+
+---
+
+## Próximos passos
+
+- Comece pela [Introdução](introducao.md) para entender o ecossistema.
+- Se já conhece o Luminix, vá direto para [Instalação](instalacao.md).
+- Para customizar o painel, consulte [Extensibilidade](extensibilidade.md).

package/docs/instalacao.md

@@ -0,0 +1,95 @@
+# Instalação
+
+## Via luminix/admin (recomendado)
+
+O caminho mais simples é usar o pacote Laravel `luminix/admin`, que instala e configura todas as dependências automaticamente:
+
+```bash
+composer require luminix/admin
+php artisan luminix:admin-ui
+```
+
+O comando `luminix:admin-ui` publica os arquivos JavaScript em `resources/js/`, instala as dependências npm e configura o Vite. Após isso, basta compilar:
+
+```bash
+npm run build
+# ou, em desenvolvimento:
+npm run dev
+```
+
+O painel estará disponível em `/admin`.
+
+> Consulte a documentação do `luminix/admin` para detalhes sobre middleware, permissões e configuração do servidor.
+
+---
+
+## Instalação manual
+
+Se preferir integrar a biblioteca em um projeto React existente, instale as dependências:
+
+```bash
+npm install @luminix/mui-cms \
+  @luminix/core \
+  @luminix/react \
+  @luminix/support \
+  @mui/material \
+  @mui/icons-material \
+  @emotion/react \
+  @emotion/styled \
+  @fontsource/roboto \
+  i18next \
+  react-i18next \
+  react-router-dom@6.25.1
+```
+
+### Ponto de entrada
+
+```tsx
+// src/main.tsx
+import '@fontsource/roboto/300.css';
+import '@fontsource/roboto/400.css';
+import '@fontsource/roboto/500.css';
+import '@fontsource/roboto/700.css';
+
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { LuminixCms } from '@luminix/mui-cms';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+    <React.StrictMode>
+        <LuminixCms />
+    </React.StrictMode>
+);
+```
+
+### Pré-requisitos no backend
+
+A instalação manual requer que o backend Laravel já tenha os pacotes `luminix/backend` e `luminix/frontend` configurados, com `@luminixEmbed()` presente no template Blade que carrega o JavaScript.
+
+---
+
+## Dependências peer
+
+| Pacote | Versão mínima |
+|---|---|
+| `react` | ^18.3.1 |
+| `react-dom` | ^18.3.1 |
+| `react-router-dom` | 6.25.1 |
+| `@mui/material` | ^5.16.5 |
+| `@mui/icons-material` | ^5.16.5 |
+| `@emotion/react` | ^11.13.0 |
+| `@emotion/styled` | ^11.13.0 |
+| `@fontsource/roboto` | ^5.0.12 |
+| `@luminix/core` | ^1.0.0 |
+| `@luminix/react` | ^1.0.0 |
+| `@luminix/support` | ^1.0.1 |
+| `i18next` | ^23.12.2 |
+| `react-i18next` | ^15.0.1 |
+
+---
+
+## Próximos passos
+
+- [Configuração](configuracao.md) — personalize o tema e o layout
+- [Componentes](componentes.md) — conheça o `LuminixCms` e os providers
+- [Volta ao índice](index.md)

package/docs/introducao.md

@@ -0,0 +1,72 @@
+# Introdução
+
+`@luminix/mui-cms` é a camada de interface do ecossistema Luminix: uma biblioteca de componentes React construída sobre o Material-UI que entrega um painel administrativo (CMS) completo e extensível, pronto para ser integrado a qualquer aplicação Laravel.
+
+## O ecossistema Luminix
+
+O Luminix é composto por pacotes que cooperam em camadas bem definidas:
+
+```
+Laravel (servidor)
+├── luminix/backend    → Gera endpoints REST automáticos para modelos Eloquent
+└── luminix/frontend   → Injeta dados de boot no HTML via @luminixEmbed()
+
+    ↓ dados chegam ao navegador
+
+JavaScript (cliente)
+├── @luminix/support   → Utilitários, padrões Reducible/Macroable, cliente HTTP
+├── @luminix/core      → Contêiner de app, sistema de modelos, roteamento
+├── @luminix/react     → Hooks e componentes React base (formulários, paginação)
+└── @luminix/mui-cms   → Interface MUI: layout, tabelas, filtros, notificações
+```
+
+O pacote `luminix/admin` (Laravel) orquestra toda a integração: publica os arquivos React, configura o Vite e serve o painel em `/admin`.
+
+## Responsabilidades de cada camada
+
+### luminix/backend
+Aplica a trait `LuminixModel` nos modelos Eloquent e expõe automaticamente endpoints REST em `/luminix-api/*`. Suporta filtros avançados, paginação, ordenação, soft deletes e controle de acesso via Laravel Gates.
+
+Documentação: `luminix/backend/docs/`
+
+### luminix/frontend
+Fornece a diretiva Blade `@luminixEmbed()` que injeta no HTML o manifesto de modelos e rotas, configuração da aplicação, usuário autenticado e token CSRF — tudo o que o frontend JavaScript precisa para inicializar.
+
+Documentação: `luminix/frontend/docs/`
+
+### @luminix/support
+Base de infraestrutura: coleções, manipulação de strings/objetos/arrays, cliente HTTP com axios, container de aplicação e os padrões `Reducible` e `Macroable` usados em toda a stack.
+
+Documentação: `@luminix/support/docs/`
+
+### @luminix/core
+Fachadas de alto nível (`App`, `Auth`, `Config`, `Model`, `Route`) e o sistema de modelos com suporte a relacionamentos e queries encadeadas.
+
+Documentação: `@luminix/core/docs/`
+
+### @luminix/react
+Camada React: `LuminixProvider`, `ModelForm`, hooks de formulário (`useForm`), paginação (`usePagination`), requisições (`useQuery`) e acesso a coleções (`useCollection`).
+
+Documentação: `@luminix/react/docs/`
+
+### @luminix/mui-cms _(esta biblioteca)_
+Interface completa: layout responsivo com AppBar e Drawer, tabelas com filtros, ações (estáticas, de instância, em massa), sistema de notificações, diálogos e todas as extensões via redutores.
+
+### luminix/admin _(não documentado ainda)_
+Pacote Laravel que integra tudo: publica os arquivos React em `resources/js/`, configura o Vite, registra as rotas do painel e serve a SPA em `/admin`. É o ponto de entrada recomendado para quem quer usar o Luminix CMS em um projeto Laravel sem precisar configurar cada peça manualmente.
+
+## Fluxo de dados
+
+1. O Laravel renderiza o HTML com `@luminixEmbed()` — que injeta boot data e manifesto.
+2. O JavaScript inicializa o contêiner de aplicação via `@luminix/core`.
+3. O `LuminixCms` monta a SPA com `react-router-dom` e Material-UI.
+4. O painel descobre os modelos pelo manifesto e gera rotas, menus e telas automaticamente.
+5. Toda requisição de dados passa pelo cliente HTTP de `@luminix/support` com o token CSRF já configurado.
+
+---
+
+## Próximos passos
+
+- [Instalação](instalacao.md) — como instalar e configurar o ambiente de desenvolvimento
+- [Configuração](configuracao.md) — tema MUI, layout e opções disponíveis
+- [Volta ao índice](index.md)