Text Editors

Libreria che rende disponibile <es-editor>, un editor rich-text basato su tiptap che produce il proprio valore in HTML, Markdown o testo semplice.

Installazione

npm install @esfaenza/text-editors

Dipendenze: i pacchetti @tiptap/* (versione 3.17.1), @floating-ui/dom e marked sono peerDependencies a versione fissa: vedere package.json per l'elenco completo e installarli alle stesse versioni.

Setup

Il componente è standalone: non c'è un modulo da configurare, basta importarlo dove serve.

import { EditorComponent } from "@esfaenza/text-editors";

@Component({
    ...,
    imports: [FormsModule, EditorComponent]
})
export class MyComponent { }

In un modulo non standalone si aggiunge EditorComponent agli imports del modulo.

Utilizzo

Il componente è un ControlValueAccessor: il valore si legge e si scrive tramite ngModel o un form reattivo.

<es-editor Mode="html" name="body" [(ngModel)]="model.body"
           [BulletListSupport]="true" [TablesSupport]="true"></es-editor>

<es-editor Mode="markdown" name="note" [(ngModel)]="model.note"
           [MentionEntities]="users"></es-editor>

<es-editor readonly Mode="html" name="preview" [(ngModel)]="model.body"></es-editor>

Input

| Input | Tipo | Default | Descrizione | |---|---|---|---| | Mode | 'html' \| 'markdown' \| 'text' | — (obbligatorio) | Formato del valore prodotto e accettato dall'editor | | name | string | — (obbligatorio) | Nome del controllo | | readonly | boolean | false | Nasconde la toolbar e rende il contenuto non modificabile | | BulletListSupport | boolean | false | Mostra il pulsante per gli elenchi puntati | | TablesSupport | boolean | false | Abilita le tabelle e i relativi pulsanti (solo con Mode="html") | | EmojiSupport | boolean | false | Mostra il selettore di emoji | | MentionEntities | { id: string, description: string }[] | [] | Se valorizzato abilita le menzioni con @ | | style | string | "" | Stile inline applicato al contenitore dell'editor |

Mode, readonly, TablesSupport e MentionEntities vengono letti una sola volta, all'inizializzazione del componente: cambiarli in seguito non riconfigura l'editor. Per cambiarli va ricreato il componente (ad esempio con un @if).

Gli input disabled e required e gli output inputChange, inputFocus e inputFinalized sono dichiarati ma al momento non hanno alcun effetto.

Comportamento come controllo di form

• Il caricamento di un valore (da ngModel o da setValue/patchValue) non emette un cambio di valore: il controllo resta pristine finché l'utente non modifica il contenuto. Di conseguenza il valore nel modello resta quello caricato (ad esempio senza la rimozione del prefisso descritta sotto) fino alla prima modifica.
• Il controllo diventa touched quando l'editor perde il focus.

Modalità

• html: il valore è l'HTML generato dall'editor. Un editor vuoto produce "" (non <p></p>). La toolbar include la scelta del carattere (font "web safe": Arial, Verdana, Tahoma, Trebuchet MS, Georgia, Times New Roman, Courier New) e della dimensione (da 10px a 32px), salvati come <span style="font-family: …; font-size: …">. L'opzione vuota ("Carattere" / "Dimensione") rimuove lo stile. Carattere e dimensione presenti nell'HTML caricato o incollato vengono mantenuti (i pt vengono convertiti in px).
• markdown: il valore è Markdown. Le immagini con larghezza o allineamento personalizzati vengono salvate come tag <img> HTML all'interno del Markdown. Carattere, dimensione e colore del testo non sono rappresentabili in Markdown: la toolbar non li offre e, se presenti nel testo incollato, vanno persi al salvataggio.
• text: il valore è il solo testo, senza formattazione.

Un valore null o undefined in ingresso viene trattato come stringa vuota. Un eventuale prefisso iniziale ****** o ** viene rimosso.

Menzioni

Con MentionEntities valorizzato, digitando @ compare un elenco (massimo 5 voci) filtrato per inizio della description; si naviga con le frecce e si conferma con Invio o con un click.

In Markdown una menzione viene salvata come @<id> e riconosciuta in rilettura solo se l'id è composto da esattamente 7 lettere (come i codici utente, ad es. @GHETTIE). Menzioni con id diversi non sopravvivono a un salvataggio e successivo caricamento in Markdown.

Immagini

Le immagini incollate o trascinate nell'editor vengono incorporate nel valore come data URI base64: tenerne conto per la dimensione dei dati salvati. Una volta inserita, un'immagine può essere ridimensionata con la maniglia e allineata a sinistra, al centro o a destra.

Stili

Il componente usa ViewEncapsulation.None: le sue regole CSS (.editor-shell, .editor-toolbar, .ProseMirror, .suggestion-popup, …) sono globali e possono essere sovrascritte dall'applicazione che lo ospita.

I colori della toolbar e dei controlli sulle immagini passano da custom property definite su .editor-shell, sovrascrivibili senza toccare le regole:

es-editor .editor-shell {
    --es-editor-border: #e2e4e9;        /* bordi, divisori */
    --es-editor-toolbar-bg: #fafbfc;    /* sfondo della toolbar */
    --es-editor-text: #1f2328;
    --es-editor-icon: #4b5563;          /* icone dei pulsanti */
    --es-editor-hover: #eef0f3;         /* sfondo al passaggio del mouse */
    --es-editor-accent: #2342c0;        /* pulsante attivo, focus, selezione immagine */
    --es-editor-accent-soft: #e5ebff;   /* sfondo del pulsante attivo */
    --es-editor-focus: rgba(35, 66, 192, 0.28);
}