@seniorsistemas/angular-components 19.5.5 → 19.6.0

package/editor/README.md

@@ -0,0 +1,229 @@
+# Editor
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Editor de texto rico (WYSIWYG) construído sobre o **Tiptap/ProseMirror** (licença MIT). Substitui o `p-editor` do PrimeNG sem dependências comerciais e implementa `ControlValueAccessor` para integração nativa com Angular Forms.
+
+## Quando usar
+
+- Campos de formulário que exigem formatação de texto (descrições, observações, contratos, e-mails)
+- Substituição do `p-editor` do PrimeNG em formulários existentes
+- Exibição de conteúdo HTML salvo em modo somente leitura
+
+## Quando não usar
+
+- Entrada de texto simples sem formatação — use `<textarea>` ou `s-text-area`
+- Edição colaborativa em tempo real — o componente não possui suporte a operações concorrentes
+
+## Instalação
+
+```typescript
+import { EditorComponent } from '@seniorsistemas/angular-components/editor';
+
+@Component({
+    standalone: true,
+    imports: [EditorComponent],
+})
+export class MeuComponent {}
+```
+
+## Uso básico
+
+```html
+<s-editor [(ngModel)]="htmlContent" />
+```
+
+```html
+<s-editor formControlName="descricao" />
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `readonly` | `boolean` | `false` | Não | Desabilita edição e oculta a toolbar |
+| `formats` | `EditorFormat[]` | `undefined` | Não | Lista de formatos exibidos na toolbar. Quando omitido, todos os formatos são exibidos |
+| `style` | `{ [klass: string]: unknown }` | `undefined` | Não | Estilos inline aplicados ao container do editor (ex: `{ 'min-height': '200px' }`) |
+| `extensions` | `Extension[]` | `[]` | Não | Extensões Tiptap adicionais para estender o comportamento padrão |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `editorInit` | `OutputEmitterRef<Editor>` | Emitido quando o editor está inicializado e pronto para uso. Entrega a instância do Tiptap `Editor` |
+| `textChange` | `OutputEmitterRef<EditorTextChangeEvent>` | Emitido sempre que o conteúdo é alterado pelo usuário |
+
+### Tipos
+
+```typescript
+type EditorFormat =
+    | 'header'       // Dropdown de títulos (Normal, Título 1, 2, 3)
+    | 'bold'         // Negrito (Ctrl+B)
+    | 'italic'       // Itálico (Ctrl+I)
+    | 'underline'    // Sublinhado (Ctrl+U)
+    | 'strike'       // Tachado
+    | 'color'        // Cor do texto (seletor nativo do sistema)
+    | 'list'         // Listas com marcadores e numeradas
+    | 'align'        // Alinhamento (esquerda, centro, direita)
+    | 'blockquote'   // Citação
+    | 'code-block'   // Código inline
+    | 'link'         // Inserir/editar link
+    | 'image'        // Inserir imagem (base64)
+    | 'subscript'    // Subscrito
+    | 'superscript'  // Sobrescrito
+    | 'clean';       // Limpar toda a formatação
+
+interface EditorTextChangeEvent {
+    htmlValue: string;  // Conteúdo como HTML
+    textValue: string;  // Conteúdo como texto plano
+}
+```
+
+## Exemplos
+
+### Com todos os formatos (padrão)
+
+```html
+<s-editor [(ngModel)]="content" />
+```
+
+### Toolbar simplificada
+
+Use o input `formats` para exibir apenas os formatos necessários:
+
+```html
+<s-editor
+    [(ngModel)]="content"
+    [formats]="['bold', 'italic', 'underline', 'list']"
+/>
+```
+
+### Modo somente leitura
+
+```html
+<s-editor [(ngModel)]="content" [readonly]="true" />
+```
+
+### Com altura personalizada
+
+```html
+<s-editor
+    [(ngModel)]="content"
+    [style]="{ 'min-height': '300px' }"
+/>
+```
+
+### Reactive Forms
+
+```html
+<form [formGroup]="form">
+    <s-editor formControlName="descricao" />
+</form>
+```
+
+```typescript
+form = new FormGroup({
+    descricao: new FormControl(''),
+});
+```
+
+### Reagindo à inicialização do editor
+
+```html
+<s-editor [(ngModel)]="content" (editorInit)="onEditorReady($event)" />
+```
+
+```typescript
+onEditorReady(editor: Editor): void {
+    // instância Tiptap disponível para operações programáticas
+    editor.commands.focus();
+}
+```
+
+### Reagindo a mudanças de conteúdo
+
+```html
+<s-editor [(ngModel)]="content" (textChange)="onTextChange($event)" />
+```
+
+```typescript
+onTextChange(event: EditorTextChangeEvent): void {
+    console.log(event.htmlValue); // '<p>Texto com <strong>negrito</strong></p>'
+    console.log(event.textValue); // 'Texto com negrito'
+}
+```
+
+### Com extensões Tiptap customizadas
+
+```typescript
+import CharacterCount from '@tiptap/extension-character-count';
+
+extensions = [CharacterCount.configure({ limit: 500 })];
+```
+
+```html
+<s-editor [(ngModel)]="content" [extensions]="extensions" />
+```
+
+## Toolbar
+
+Os botões de **Desfazer** e **Refazer** são sempre exibidos quando a toolbar está visível, independente do input `formats`.
+
+| Formato | Valor em `formats` | Atalho | Descrição |
+|---------|-------------------|--------|-----------|
+| Títulos | `'header'` | — | Dropdown: Normal, Título 1, 2, 3 |
+| Negrito | `'bold'` | Ctrl+B | |
+| Itálico | `'italic'` | Ctrl+I | |
+| Sublinhado | `'underline'` | Ctrl+U | |
+| Tachado | `'strike'` | — | |
+| Cor do texto | `'color'` | — | Abre o seletor de cores nativo do sistema |
+| Subscrito | `'subscript'` | — | |
+| Sobrescrito | `'superscript'` | — | |
+| Listas | `'list'` | — | Com marcadores e numerada |
+| Alinhamento | `'align'` | — | Esquerda, centro, direita |
+| Citação | `'blockquote'` | — | |
+| Código | `'code-block'` | — | Código inline |
+| Link | `'link'` | — | Abre dialog para inserir/editar URL |
+| Imagem | `'image'` | — | Seleciona arquivo local e insere como base64 |
+| Limpar formatação | `'clean'` | — | Remove toda a formatação do texto selecionado |
+| Desfazer | sempre visível | Ctrl+Z | |
+| Refazer | sempre visível | Ctrl+Y | |
+
+## Formato de dados
+
+O componente produz e consome **HTML**. O valor salvo em `ngModel` ou `FormControl` é a string HTML gerada pelo Tiptap, compatível com o HTML produzido pelo `p-editor` do PrimeNG para os formatos comuns.
+
+## Migração do `p-editor`
+
+### Substituição do import e seletor
+
+```html
+<!-- Antes (p-editor) -->
+<p-editor formControlName="descricao" [formats]="formats" />
+
+<!-- Depois (s-editor) -->
+<s-editor formControlName="descricao" [formats]="formats" />
+```
+
+### Diferença semântica do input `formats`
+
+No `p-editor`, `formats` era uma whitelist de formatos permitidos **no conteúdo** (comportamento do Quill). No `s-editor`, `formats` controla a **visibilidade dos botões na toolbar**. O efeito prático é equivalente: o usuário não consegue aplicar formatos que não estão listados.
+
+### Input `modules` removido
+
+O input `modules` do `p-editor` era específico do Quill e não tem equivalente no Tiptap. Use o input `extensions` para adicionar extensões Tiptap customizadas.
+
+## Acessibilidade
+
+- A área editável recebe `role="textbox"` e `aria-multiline="true"` automaticamente
+- O `aria-label` da área editável é traduzível via `@ngx-translate`
+- A toolbar tem `role="toolbar"` com `aria-label` traduzível
+- O controle fica `touched` ao perder o foco (comportamento correto com formulários reativos e validação)
+- O seletor de títulos tem `aria-label` traduzível
+
+## Componentes relacionados
+
+- [`DynamicFormComponent`](../dynamic-form/README.md) — use `provideEditorField()` para integrar o editor como campo do formulário dinâmico
+- [`DialogComponent`](../dialog/README.md) — usado internamente para o dialog de inserção de links

package/editor/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generated bundle index. Do not edit.
+ */
+/// <amd-module name="@seniorsistemas/angular-components/editor" />
+export * from './public-api';

package/editor/lib/editor/editor.component.d.ts

@@ -0,0 +1,127 @@
+import { AfterViewInit, OnDestroy } from '@angular/core';
+import { ControlValueAccessor } from '@angular/forms';
+import { Editor } from '@tiptap/core';
+import { EditorFormat, EditorSelectionChangeEvent, EditorTextChangeEvent, Extension } from './models';
+import * as i0 from "@angular/core";
+/**
+ * @description Componente de editor de texto rico (WYSIWYG) construído sobre o Tiptap/ProseMirror.
+ * Substitui o `p-editor` do PrimeNG sem dependência externa de licença comercial.
+ * Implementa {@link ControlValueAccessor} para integração com Angular Forms.
+ *
+ * @example
+ * ```html
+ * <s-editor
+ *   formControlName="descricao"
+ *   [readonly]="false"
+ *   (textChange)="onTextChange($event)" />
+ * ```
+ */
+export declare class EditorComponent implements AfterViewInit, OnDestroy, ControlValueAccessor {
+    private readonly cdr;
+    private readonly dialogService;
+    private readonly translateService;
+    private readonly destroyRef;
+    /**
+     * @description Coloca o editor em modo somente leitura.
+     * @default false
+     */
+    readonly: import("@angular/core").InputSignal<boolean>;
+    /**
+     * @description Lista de formatos habilitados na toolbar. Quando vazio, todos os formatos são exibidos.
+     */
+    formats: import("@angular/core").InputSignal<EditorFormat[] | undefined>;
+    /**
+     * @description Texto de dica exibido quando o editor está vazio.
+     */
+    placeholder: import("@angular/core").InputSignal<string | undefined>;
+    /**
+     * @description Estilos inline aplicados ao container do editor.
+     */
+    style: import("@angular/core").InputSignal<{
+        [klass: string]: unknown;
+    } | undefined>;
+    /**
+     * @description Classes CSS adicionais aplicadas ao container do editor.
+     */
+    styleClass: import("@angular/core").InputSignal<string | undefined>;
+    /**
+     * @description Extensões Tiptap adicionais para estender o comportamento padrão do editor.
+     */
+    extensions: import("@angular/core").InputSignal<Extension<any, any>[]>;
+    /**
+     * @description Emitido quando o editor é inicializado e está pronto para uso.
+     */
+    editorInit: import("@angular/core").OutputEmitterRef<Editor>;
+    /**
+     * @description Emitido sempre que o conteúdo do editor é alterado.
+     */
+    textChange: import("@angular/core").OutputEmitterRef<EditorTextChangeEvent>;
+    /**
+     * @description Emitido quando a seleção de texto no editor muda.
+     */
+    selectionChange: import("@angular/core").OutputEmitterRef<EditorSelectionChangeEvent>;
+    private editorContainer;
+    private imageInput;
+    private editor?;
+    private _formDisabled;
+    private _currentPlaceholder;
+    activeStates: {
+        isBold: boolean;
+        isItalic: boolean;
+        isUnderline: boolean;
+        isStrike: boolean;
+        isBulletList: boolean;
+        isOrderedList: boolean;
+        isBlockquote: boolean;
+        isCode: boolean;
+        isSubscript: boolean;
+        isSuperscript: boolean;
+        isAlignLeft: boolean;
+        isAlignCenter: boolean;
+        isAlignRight: boolean;
+        currentHeading: number;
+        currentColor: string;
+        currentHighlight: string;
+        canUndo: boolean;
+        canRedo: boolean;
+    };
+    private _value;
+    private _onChange;
+    private _onTouched;
+    constructor();
+    ngAfterViewInit(): void;
+    ngOnDestroy(): void;
+    writeValue(value: string): void;
+    registerOnChange(fn: (value: string) => void): void;
+    registerOnTouched(fn: () => void): void;
+    setDisabledState(isDisabled: boolean): void;
+    isFormatAllowed(format: EditorFormat): boolean;
+    hasAnyFormatBeforeUndoRedo(): boolean;
+    toggleBold(): void;
+    toggleItalic(): void;
+    toggleUnderline(): void;
+    toggleStrike(): void;
+    toggleBulletList(): void;
+    toggleOrderedList(): void;
+    toggleBlockquote(): void;
+    toggleCode(): void;
+    toggleSubscript(): void;
+    toggleSuperscript(): void;
+    setTextAlign(align: 'left' | 'center' | 'right'): void;
+    setColor(color: string): void;
+    setHighlight(color: string): void;
+    clearFormatting(): void;
+    onHeadingChange(event: Event): void;
+    setLink(): void;
+    setImage(): void;
+    onImageFileSelected(event: Event): void;
+    undo(): void;
+    redo(): void;
+    onToolbarKeydown(event: KeyboardEvent): void;
+    onToolbarFocusIn(event: FocusEvent): void;
+    private getToolbarFocusable;
+    private initEditor;
+    private syncActiveStates;
+    static ɵfac: i0.ɵɵFactoryDeclaration<EditorComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<EditorComponent, "s-editor", never, { "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "formats": { "alias": "formats"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "style": { "alias": "style"; "required": false; "isSignal": true; }; "styleClass": { "alias": "styleClass"; "required": false; "isSignal": true; }; "extensions": { "alias": "extensions"; "required": false; "isSignal": true; }; }, { "editorInit": "editorInit"; "textChange": "textChange"; "selectionChange": "selectionChange"; }, never, never, true, never>;
+}

package/editor/lib/editor/link-dialog/link-dialog.component.d.ts

@@ -0,0 +1,18 @@
+import { OnInit } from '@angular/core';
+import { FormControl, FormGroup } from '@angular/forms';
+import { DynamicStructure } from '@seniorsistemas/angular-components/dynamic-form';
+import * as i0 from "@angular/core";
+export declare class LinkDialogComponent implements OnInit {
+    private readonly activeDialog;
+    private readonly translateService;
+    initialUrl: string;
+    form: FormGroup<{
+        url: FormControl<string | null>;
+    }>;
+    configs: DynamicStructure[];
+    ngOnInit(): void;
+    confirm(): void;
+    cancel(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<LinkDialogComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<LinkDialogComponent, "ng-component", never, {}, {}, never, never, true, never>;
+}

package/editor/lib/editor/models/index.d.ts

@@ -0,0 +1,12 @@
+import { Extension } from '@tiptap/core';
+export type EditorFormat = 'header' | 'bold' | 'italic' | 'underline' | 'strike' | 'color' | 'highlight' | 'list' | 'align' | 'blockquote' | 'code-block' | 'link' | 'image' | 'subscript' | 'superscript' | 'clean';
+export interface EditorTextChangeEvent {
+    htmlValue: string;
+    textValue: string;
+}
+export interface EditorSelectionChangeEvent {
+    from: number;
+    to: number;
+    empty: boolean;
+}
+export { Extension };

package/editor/lib/editor/toolbar-button/editor-toolbar-button.component.d.ts

@@ -0,0 +1,10 @@
+import * as i0 from "@angular/core";
+export declare class EditorToolbarButtonComponent {
+    icon: import("@angular/core").InputSignal<string>;
+    label: import("@angular/core").InputSignal<string>;
+    active: import("@angular/core").InputSignal<boolean>;
+    disabled: import("@angular/core").InputSignal<boolean>;
+    clicked: import("@angular/core").OutputEmitterRef<void>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<EditorToolbarButtonComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<EditorToolbarButtonComponent, "s-editor-toolbar-button", never, { "icon": { "alias": "icon"; "required": true; "isSignal": true; }; "label": { "alias": "label"; "required": true; "isSignal": true; }; "active": { "alias": "active"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, { "clicked": "clicked"; }, never, never, true, never>;
+}

package/editor/public-api.d.ts

@@ -0,0 +1,2 @@
+export * from './lib/editor/editor.component';
+export * from './lib/editor/models';