@seniorsistemas/angular-components-mcp 1.0.0-beta.3 → 1.0.0

package/dist/data/component-rules/button.md

@@ -0,0 +1,37 @@
+# Button — Regras de UX
+
+**Seletor:** `s-button`  
+**Package:** `@seniorsistemas/angular-components/button`
+
+---
+
+## Variantes
+
+| Variante    | Quando usar                                                                  |
+| ----------- | ---------------------------------------------------------------------------- |
+| `primary`   | Ação principal da página — máximo 1 por página/diálogo                       |
+| `secondary` | Ações complementares à ação principal                                        |
+| `link`      | Navegação secundária ou ações de baixa importância visual                    |
+| `select`    | Quando houver menu de ações — obrigatório usar ícone de chevron pré-definido |
+
+---
+
+## Regras
+
+### ⛔ Hierarquia (error)
+
+Use no máximo 1 botão `primary` por página/diálogo. Os demais devem ser `secondary` ou `link`.
+
+### ⚠️ Ícones (warning)
+
+Use no máximo 1 ícone por botão (esquerda ou direita). Nunca 2 ícones no mesmo botão.
+
+### ⛔ Tamanho `small` (error)
+
+Permitido **somente** em células de tabela e section title.  
+Proibido em formulários, navegação primária ou qualquer outro contexto.
+
+### ⛔ Labels
+
+Use labels acionáveis e específicos. Prefira `"Salvar Cadastro"` a `"OK"`.
+

package/dist/data/component-rules/checkbox.md

@@ -0,0 +1,30 @@
+# Checkbox — Regras de UX
+
+## Variantes
+
+| Variante       | Quando usar                                                     |
+| -------------- | --------------------------------------------------------------- |
+| **Horizontal** | Quando todos os itens possuem textos curtos ou palavras únicas. |
+| **Vertical**   | Quando um ou mais itens possuem textos longos.                  |
+
+---
+
+## Regras de uso
+
+- **SEMPRE** use alinhamento vertical em telas pequenas.
+- Cada checkbox deve possuir um label descrevendo a sua ação.
+- Coloque opções importantes no topo.
+
+## ⛔ Regras de erro
+
+- Não use checkbox para escolhas mutuamente exclusivas. Nesses casos use Radio Button.
+- Não use checkbox para ações que se aplicam imediatamente e alteram a interface em tempo real — isso é papel do Switch.
+- Não apresente checkbox horizontalmente em dispositivos móveis.
+- Não utilize checkbox sem um label claro e explícito.
+- Não agrupe muitas opções horizontalmente. Neste caso use alinhamento vertical.
+
+---
+
+## ⚠️ Regras de recomendação
+
+- Prefira usar checkbox em formulários ou contextos de escolha múltipla de forma persistente.

package/dist/data/component-rules/confirm-dialog.md

@@ -0,0 +1,86 @@
+# Dialog — Regras de UX
+
+## Variantes
+
+| Variante                       | Quando usar                                                                   |
+| ------------------------------ | ----------------------------------------------------------------------------- |
+| **Confirmação simples**        | Utilizar quando há apenas uma ação possível e não existe reversão.            |
+| **Confirmação + Cancelamento** | Utilizar quando o usuário deve ter a opção de prosseguir ou desistir da ação. |
+
+# Regras
+
+## ⛔ Regras de erro
+
+- Não utilizar Dialog para formulários complexos ou com múltiplos campos.
+- Não inserir no Dialog componentes além de título, texto e botões.
+- Não exibir conteúdo secundário ou informações que não interrompam o fluxo do usuário.
+- Não deixar o Dialog sem uma ação clara ou sem possibilidade de fechamento.
+- Não usar quando a mensagem não for importante ou não exigir decisão imediata.
+
+## ⚠️ Regras de recomendação
+
+- Utilizar o Dialog apenas para interromper o usuário quando necessário.
+- Manter o conteúdo sempre claro, objetivo e focado na decisão.
+- A ação principal deve responder diretamente à pergunta apresentada no título.
+- Usar confirmação única quando não houver alternativa reversível.
+- Em casos críticos, destacar visualmente a ação verdadeira.
+
+# Layout e Alinhamento
+
+- O Dialog deve ser centralizado na tela em todos os dispositivos.
+- A estrutura deve seguir a ordem: título → texto → ações.
+- Em telas menores, o espaçamento interno pode ser reduzido, mantendo legibilidade.
+
+# Responsividade
+
+- Deve se adaptar a diferentes larguras sem comprometer a leitura.
+- O fechamento deve ser possível em qualquer tamanho de dispositivo.
+
+# Estados
+
+| Estado                                   | Descrição                                      |
+| ---------------------------------------- | ---------------------------------------------- |
+| **Default (confirmação simples)**        | Exibe texto e um botão de confirmação.         |
+| **Default (confirmação + cancelamento)** | Exibe dois botões: confirmar e cancelar.       |
+| **Focus**                                | O foco deve estar no botão principal ao abrir. |
+
+# Labels
+
+- O título deve apresentar claramente a ação ou decisão.
+- O texto deve complementar o título e reforçar o impacto da ação.
+- Os botões devem usar verbos claros e diretos.
+
+# Acessibilidade
+
+- O foco deve ser direcionado automaticamente ao botão principal ao abrir o Dialog.
+- Deve permitir navegação por teclado.
+- O overlay deve bloquear interações com o conteúdo principal.
+- O conteúdo deve ser textual e acessível para leitores de tela.
+
+# Do’s
+
+- Usar para confirmar ações importantes, como exclusões.
+- Manter estrutura simples e objetiva.
+- Garantir mensagens curtas e diretas.
+- Interromper o usuário apenas quando necessário para validação crítica.
+
+# Don’ts
+
+- Não usar para formulários longos.
+- Não inserir múltiplos componentes ou conteúdos complexos.
+- Não usar para mensagens informativas que não exigem ação.
+- Não deixar ações ambíguas ou pouco claras.
+
+# Boas práticas de UX
+
+- Escrever mensagens diretas e sem redundância.
+- Formular perguntas como “Deseja excluir este item?”.
+- A ação principal deve refletir a escolha mais esperada pelo usuário.
+- Evitar gerar ansiedade: comunicação simples, calma e objetiva.
+
+# Anti-patterns
+
+- Usar Dialog como substituto de modais complexos.
+- Criar sequências de Dialogs em cadeia.
+- Exibir feedback simples que poderia ser apresentado inline ou como toast.
+- Interromper o usuário para ações triviais.

package/dist/data/component-rules/index.json

@@ -0,0 +1,3 @@
+{
+  "components": ["button", "checkbox", "confirm-dialog", "radio-button"]
+}

package/dist/data/component-technical/confirm-dialog.md

@@ -0,0 +1,117 @@
+# ConfirmDialog — Guia Técnico
+
+**Seletor:** `s-confirm-dialog`  
+**Package:** `@seniorsistemas/angular-components/confirm-dialog`
+
+## Exports e Imports
+
+| Tipo    | Símbolo                |
+| ------- | ---------------------- |
+| Service | `ConfirmDialogService` |
+| Type    | `ConfirmDialog`        |
+
+```typescript
+import { ConfirmDialogService } from '@seniorsistemas/angular-components/confirm-dialog';
+import type { ConfirmDialog } from '@seniorsistemas/angular-components/confirm-dialog';
+```
+
+> **Erro comum:** `Module has no exported member 'ConfirmDialogModule'` — use `ConfirmDialogService` diretamente; não existe `ConfirmDialogModule` público nesta versão.
+
+---
+
+O ConfirmDialog é **SEMPRE** utilizado via `ConfirmDialogService`. O componente `s-confirm-dialog` **não deve ser instanciado diretamente** no template — ele é renderizado internamente pelo serviço.
+
+---
+
+## Padrão único: Via `ConfirmDialogService` ✅ ÚNICO PADRÃO SUPORTADO
+
+Abre um dialog de confirmação com mensagem, título e botões configuráveis. Retorna uma `Promise<boolean>` que resolve com `true` se o usuário confirmar e `false` se cancelar.
+
+### Regras obrigatórias
+
+- **NUNCA** adicionar `<s-confirm-dialog>` diretamente no template — o serviço gerencia isso automaticamente
+- Importar `ConfirmDialogModule` no módulo ou componente raiz para registrar o componente
+
+### Exemplo
+
+```typescript
+import { ConfirmDialogModule, ConfirmDialogService } from '@seniorsistemas/angular-components/confirm-dialog';
+
+@Component({
+    imports: [ConfirmDialogModule],
+    template: `
+        <s-button
+            label="Deletar"
+            (clicked)="delete()"
+        />
+    `,
+})
+export class MyComponent {
+    private readonly confirmDialog = inject(ConfirmDialogService);
+
+    protected async delete(): Promise<void> {
+        const confirmed = await this.confirmDialog.open({
+            header: 'Confirmar exclusão',
+            message: 'Tem certeza que deseja excluir este registro? Esta ação não pode ser desfeita.',
+            acceptLabel: 'Excluir',
+            rejectLabel: 'Cancelar',
+        });
+
+        if (confirmed) {
+            // prosseguir com a exclusão
+        }
+    }
+}
+```
+
+---
+
+## Notas de integração
+
+- `ConfirmDialogService.open()` retorna `Promise<boolean>`: use `async/await` ou `.then()` para aguardar a resposta do usuário.
+- Personalize os labels dos botões via `acceptLabel` e `rejectLabel` para dar clareza à ação (ex: `'Excluir'` ao invés de `'Ok'`).
+
+---
+
+## Erros Comuns
+
+### `Property 'open' does not exist on type 'ConfirmDialogService'`
+
+**Tipo:** method  
+**Solução:** Use `confirm()` em vez de `open()`.
+
+```typescript
+// ❌ Incorreto
+await this.confirmDialogService.open({ ... })
+
+// ✅ Correto
+this.confirmDialogService.confirm({ ... })
+```
+
+> `ConfirmDialogService` desta versão expõe o método `confirm(confirmDialog)`.
+
+---
+
+### `Type 'Promise<boolean>' is not assignable...`
+
+**Tipo:** return-type  
+**Solução:** Não use `await` no retorno de `confirm()`; o fluxo ocorre via callbacks `accept`/`reject`.
+
+```typescript
+// ❌ Incorreto
+const ok = await confirmDialogService.confirm(config);
+
+// ✅ Correto
+confirmDialogService.confirm({
+    ...config,
+    accept: () => {
+        /* ação confirmada */
+    },
+    reject: () => {
+        /* ação cancelada */
+    },
+});
+```
+
+> O método `confirm()` não retorna `Promise` nesta implementação.
+

package/dist/data/component-technical/dialog.md

@@ -0,0 +1,202 @@
+# Dialog — Guia Técnico
+
+**Seletor:** `s-dialog`  
+**Package:** `@seniorsistemas/angular-components/dialog`
+
+## Exports e Imports
+
+| Tipo      | Símbolo                      |
+| --------- | ---------------------------- |
+| Component | `DialogComponent`            |
+| Service   | `DialogService`              |
+| Class     | `ActiveDialog`               |
+| Types     | `DialogOptions`, `DialogRef` |
+
+```typescript
+import { DialogComponent } from '@seniorsistemas/angular-components/dialog';
+import { DialogService } from '@seniorsistemas/angular-components/dialog';
+import { ActiveDialog } from '@seniorsistemas/angular-components/dialog';
+import type { DialogOptions, DialogRef } from '@seniorsistemas/angular-components/dialog';
+```
+
+> **Erros comuns:**
+>
+> - `Module has no exported member 'DialogModule'` → use `DialogComponent` standalone
+> - `Module has no exported member 'DynamicDialogRef'` → use `DialogRef` e `ActiveDialog`
+> - `Module has no exported member 'DIALOG_DATA'` → use padrão `ActiveDialog`/`DialogRef`
+
+---
+
+O Dialog pode ser controlado de forma declarativa via binding de propriedade ou de forma programática via `DialogService`. A forma de uso deve ser escolhida conforme o contexto de onde o dialog será aberto.
+
+---
+
+## Padrão 1: Declarativo via `[(visible)]`
+
+**Preferido:** Não (use apenas para casos simples)
+
+O estado de abertura é controlado por uma propriedade booleana no componente pai, vinculada via two-way binding `[(visible)]`.
+
+### Exemplo
+
+```typescript
+import { DialogModule } from '@seniorsistemas/angular-components/dialog';
+
+@Component({
+    imports: [DialogModule],
+    template: `
+        <s-button
+            label="Abrir"
+            (clicked)="isOpen = true"
+        />
+        <s-dialog
+            [(visible)]="isOpen"
+            header="Título"
+        >
+            <ng-template sTemplate="body"> Conteúdo do dialog </ng-template>
+            <ng-template sTemplate="footer">
+                <s-button
+                    label="Fechar"
+                    (clicked)="isOpen = false"
+                />
+            </ng-template>
+        </s-dialog>
+    `,
+})
+export class MyComponent {
+    protected isOpen = false;
+}
+```
+
+---
+
+## Padrão 2: Programático via `DialogService` ✅ PREFERIDO
+
+O dialog é aberto injetando o `DialogService`, que cria e renderiza o componente dinamicamente. Permite abrir dialogs de qualquer lugar da aplicação, inclusive de serviços.
+
+### Exemplo
+
+```typescript
+import { DialogComponent, DialogService } from '@seniorsistemas/angular-components/dialog';
+
+
+// No componente ou serviço que abre o dialog
+@Component({ ... })
+export class MyComponent {
+  private readonly dialogService = inject(DialogService);
+
+  protected openDialog(): void {
+    this.dialogService.open(MyDialogContentComponent, {
+      header: 'Título do Dialog',
+      data: { id: 1 }
+    });
+  }
+}
+
+// Componente de conteúdo do dialog
+@Component({
+  imports: [DialogComponent, TemplateModule]
+  template: `
+    <s-dialog header="Dialog Header">
+        <!-- TODO: Campo opcional, utilizar quando [header] não for provido, caso queira HTML Customizado para o header. -->
+        <ng-template sTemplate="header"></ng-template>
+
+        <p>Id recebido: {{ data.id }}</p>
+        <!-- TODO: Campo opcional. -->
+        <ng-template
+            sTemplate="footer"
+            let-activeDialog="activeDialog">
+        <div class="grid grid-cols-12">
+            <div class="col-span-12 flex justify-around">
+                <s-button
+                    label="Ação terciária"
+                    priority="link"
+                />
+                <s-button
+                    (clicked)="activeDialog.dismiss('Dismissed dialog demo footer')"
+                    label="Ação secundária"
+                />
+                <s-button
+                    label="Ação primária"
+                    (clicked)="activeDialog.close('Closed dialog demo footer')"
+                    priority="primary"
+                />
+            </div>
+        </div>
+      </ng-template>
+
+    </s-dialog>
+
+  `
+})
+export class MyDialogContentComponent {
+  readonly activeDialog = inject(ActiveDialog);
+
+  // Função opcional, caso utilize let-activeDialog no ng-template nao precisa fechar por aqui, ambos possuem o mesmo valor de activeDialog
+  protected close(): void {
+    this.activeDialog.close('resultado opcional');
+  }
+}
+```
+
+---
+
+## Notas de integração
+
+- O `<s-dialog>` deve existir no template para que o `DialogService` possa renderizar conteúdo nele. Coloque-o em um componente de layout de nível superior.
+- Para receber dados no componente de conteúdo, use `inject(DIALOG_DATA)` importado de `@seniorsistemas/angular-components/dialog`.
+- Para fechar o dialog de dentro do componente de conteúdo, injete `DynamicDialogRef` e chame `ref.close(resultado)`.
+
+---
+
+## Erros Comuns
+
+### `Module has no exported member 'DialogModule'`
+
+**Tipo:** import  
+**Solução:** Use standalone import com `DialogComponent`.
+
+```typescript
+// ❌ Incorreto
+imports: [DialogModule];
+
+// ✅ Correto
+imports: [DialogComponent];
+```
+
+> Nesta versão, o public API expõe `DialogComponent` para uso declarativo.
+
+---
+
+### `Property 'onClose' does not exist on type 'DialogRef'`
+
+**Tipo:** property  
+**Solução:** Use o observable `closed`.
+
+```typescript
+// ❌ Incorreto
+ref.onClose.subscribe(...)
+
+// ✅ Correto
+ref.closed.subscribe(...)
+```
+
+> `DialogRef` expõe `closed` e `dismissed`.
+
+---
+
+### `Object literal may only specify known properties, and 'header' does not exist in type 'DialogOptions'`
+
+**Tipo:** parameter  
+**Solução:** Use apenas as `DialogOptions` suportadas (`destroyClickOutside`, `escapeOnEsc`, `size`).
+
+```typescript
+// ❌ Incorreto
+dialogService.open(MyDialogComponent, { header: 'Título' });
+
+// ✅ Correto
+dialogService.open(MyDialogComponent, { size: 'md' });
+```
+
+> `DialogOptions` nesta versão não inclui `header`/`data` no tipo público.
+