@arsedizioni/ars-utils 22.5.9 → 22.5.12

package/types/arsedizioni-ars-utils-ui.tinymce.d.ts

@@ -1,63 +1,275 @@
+import { RawEditorOptions, TinyMCE, Editor } from 'tinymce';
 import * as _angular_core from '@angular/core';
+import { OnInit, OnDestroy } from '@angular/core';
+import { ControlValueAccessor } from '@angular/forms';
 
+/**
+ * The editor profiles the applications ask for, ready to be handed to
+ * `[tinymceConfig]` on {@link TinymceEditorDirective}.
+ *
+ * They describe **what the editor offers** — plugins, toolbar, formats, link and image
+ * behaviour — and nothing else. Everything about *loading* TinyMCE (`base_url`, `suffix`,
+ * `language`, `language_url`, `license_key`) and about the *theme* (`skin`, `content_css`)
+ * belongs to `TinymceLoaderService` and to the directive, which resolve them against the
+ * document base href and against `ThemeService`: a preset repeating them could only get them
+ * wrong, and used to — the old ones pinned a relative `assets/tinymce` that broke under a
+ * sub-path, and read the skin from `prefers-color-scheme` instead of the theme the user chose.
+ *
+ * Uploads are the same story: `automatic_uploads`, `paste_data_images` and `file_picker_types`
+ * follow the `tinymceImageUploader` input, so an editor without a handler cannot end up
+ * offering an upload tab that leads nowhere.
+ *
+ * Each accessor returns a **fresh deep copy**: a caller that tweaks a returned object — as the
+ * editor dialog does with its toolbar — cannot corrupt the preset for everyone else.
+ */
 declare class TinymceUtils {
     /**
-     * Returns `true` when the user agent currently prefers a dark color scheme.
-     * Evaluated on demand (not frozen at module load) and SSR-safe.
+     * Everything TinyMCE 8 open source has to offer, for a full-page editor.
+     *
+     * Adapted from the TinyMCE 5 profile the library used to ship: `paste`, `print`, `hr`,
+     * `textpattern` and the `fullpage_*` options no longer exist (paste and text patterns moved
+     * into the core, `fullpage` and `print` were dropped in v6), and `checklist`,
+     * `openCodeMirrorButton` and `insertMediaButton` are premium or application-specific buttons
+     * that a self-hosted GPL build has no way to render.
      */
-    private static prefersDark;
-    /** URL of the TinyMCE script hosted on the Tiny Cloud CDN. */
-    static readonly CDN_URL = "https://cdn.tiny.cloud/1/5lnoc6ohmpjau6zyzgqyhyf52cueoennkcs8v1yfoak57ku9/tinymce/7/tinymce.min.js";
-    /** URL of the locally bundled TinyMCE script. */
-    static readonly LOCAL_URL = "/assets/tinymce/tinymce.min.js";
+    private static readonly FULL;
     /**
-     * Full-featured TinyMCE base configuration with all standard plugins and toolbar.
+     * The one for a field inside a form: it grows with the text instead of owning the page, the
+     * toolbar sits under it and collapses into groups, and there is no status bar or context menu
+     * to compete with the form around it.
      */
-    static TinymceConfig: Record<string, any>;
+    private static readonly COMPACT;
+    /** The compact one plus full screen, the insert group and the source view. */
+    private static readonly COMPACT_EXTENDED;
     /**
-     * Compact TinyMCE configuration with autoresize, bottom toolbar, and grouped toolbar buttons.
-     * Extends `TinymceConfig` with reduced height and a simplified toolbar.
+     * The full-page profile.
+     * @returns A fresh copy of the configuration, safe to modify.
      */
-    static TinymceCompactConfig: Record<string, any>;
+    static get TinymceConfig(): RawEditorOptions;
     /**
-     * Extended compact TinyMCE configuration that adds fullscreen support and an insert group.
-     * Extends `TinymceCompactConfig`.
+     * The in-form profile.
+     * @returns A fresh copy of the configuration, safe to modify.
      */
-    static TinymceCompactExtendedConfig: Record<string, any>;
+    static get TinymceCompactConfig(): RawEditorOptions;
     /**
-     * Inject the TinyMCE script tag into the document head if it is not already present.
-     * @param useCDN - When `true`, loads from the Tiny Cloud CDN; otherwise uses the local asset.
+     * The in-form profile with full screen and source view.
+     * @returns A fresh copy of the configuration, safe to modify.
      */
-    static loadTinyMCEScript(useCDN?: boolean): void;
+    static get TinymceCompactExtendedConfig(): RawEditorOptions;
 }
 
-interface FullScreenEditorDialogData {
+declare global {
+    interface Window {
+        tinymce?: TinyMCE;
+    }
+}
+/**
+ * Loads the self-hosted TinyMCE bundle on demand.
+ *
+ * TinyMCE is deliberately NOT imported by any module: a static import would pull ~500 kB into
+ * whichever chunk referenced it, and the editor is needed by exactly one dialog. The library is
+ * copied to `assets/tinymce` by the build (see `angular.json`) and injected here as a plain
+ * `<script>` the first time an editor is created, so it costs nothing until then and is served
+ * from the browser cache afterwards. Loading it this way also lets TinyMCE resolve its own theme,
+ * model, plugins and skin relative to `base_url`, which is how the self-hosted distribution
+ * expects to work.
+ */
+declare class TinymceLoaderService {
+    /** The in-flight (or completed) load, so concurrent editors share a single script tag. */
+    private pending?;
+    /**
+     * The absolute URL of the TinyMCE asset folder, resolved against the document base href so the
+     * app keeps working when it is served from a sub-path.
+     * @returns The base URL, without a trailing slash.
+     */
+    get baseUrl(): string;
+    /**
+     * Loads TinyMCE, reusing the script already injected by a previous call.
+     * @returns A promise resolving with the global TinyMCE instance.
+     */
+    load(): Promise<TinyMCE>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TinymceLoaderService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<TinymceLoaderService>;
+}
+
+/** Uploads one image and resolves with the URL to reference it by. */
+type TinymceImageUploader = (file: File) => Promise<string>;
+/**
+ * How the editor presents itself.
+ *
+ * `fixed` is the classic editor: the content lives in an iframe and the toolbar sits above it,
+ * pinned so it stays reachable while the surrounding container scrolls.
+ *
+ * `inline` edits the host element in place, with no iframe and no chrome until the user focuses
+ * it, at which point the toolbar floats over the content. It needs an ordinary element to edit —
+ * a `<div>` — because there is nothing to render inside a `<textarea>`.
+ */
+type TinymceToolbarMode = 'fixed' | 'inline';
+/**
+ * Turns a `<textarea>` into a rich text editor backed by the self-hosted TinyMCE bundle, and wires
+ * it to Angular forms as a `ControlValueAccessor`, so `[(ngModel)]`, `required` and the
+ * pristine/dirty state keep working exactly as they do on a plain control.
+ *
+ * The library itself is fetched on demand by <see cref="TinymceLoaderService"/>: nothing about
+ * TinyMCE reaches the bundle until an editor is actually created.
+ *
+ * Usage: `<textarea tinymceEditor [(ngModel)]="item.text" name="text" required></textarea>`
+ *
+ */
+declare class TinymceEditorDirective implements ControlValueAccessor, OnInit, OnDestroy {
+    /** Extra TinyMCE options, merged over (and able to override) the defaults below. */
+    readonly tinymceConfig: _angular_core.InputSignal<RawEditorOptions>;
+    /** Whether the toolbar is pinned above the content (`fixed`) or floats on focus (`inline`). */
+    readonly tinymceToolbarMode: _angular_core.InputSignal<TinymceToolbarMode>;
+    /**
+     * Handler invoked for every image dropped, pasted or picked in the editor. When not provided
+     * the upload tab is hidden and only images referenced by URL can be inserted.
+     */
+    readonly tinymceImageUploader: _angular_core.InputSignal<TinymceImageUploader>;
+    /** Emitted once the editor is up, for callers that want to enable UI only when it is usable. */
+    readonly ready: _angular_core.OutputEmitterRef<Editor>;
+    /** Emitted when the editor could not be loaded or initialised. */
+    readonly failed: _angular_core.OutputEmitterRef<Error>;
+    private readonly host;
+    private readonly loader;
+    private readonly themeService;
+    private readonly changeDetector;
+    private editor?;
+    /** True while the editor is showing itself full screen. */
+    private fullscreen;
+    /** True once the directive has been destroyed, so a late init resolves into a no-op. */
+    private destroyed;
+    /**
+     * True while the directive itself is pushing a value into the editor. TinyMCE raises the same
+     * content events for a programmatic `setContent` as for a keystroke, so without this flag
+     * `writeValue` would immediately echo back through `onChange` and mark a freshly loaded form
+     * as dirty.
+     */
+    private writingValue;
+    /** The value received before the editor existed, applied as soon as it does. */
+    private value;
+    private disabled;
+    private onChange;
+    private onTouched;
+    /**
+     * Leaves full screen on Escape, for the keystrokes that happen outside the content: with the
+     * classic editor the content is an iframe, and a keydown in there never reaches this document.
+     * Bound on the capture phase and stopped, so a dialog hosting the editor does not take the
+     * Escape and close, throwing the edit away when the user only meant to leave full screen.
+     */
+    private readonly onDocumentKeydown;
+    /**
+     * Loads TinyMCE and initialises the editor over the host textarea.
+     * @returns A promise that completes once the editor is ready (or has failed).
+     */
+    ngOnInit(): Promise<void>;
+    /**
+     * Tears the editor down. TinyMCE keeps global state per instance, so leaving it behind when a
+     * dialog closes leaks both DOM and editor registrations.
+     * @returns void
+     */
+    ngOnDestroy(): void;
+    /**
+     * Decides whether an Escape press means "leave full screen": it does whenever the editor is
+     * full screen, full stop. While full screen the editor owns Escape, and the press is stopped
+     * here so it can never reach the dialog hosting it — leaving full screen must not also throw
+     * away what is being written.
+     * @param event The keyboard event, from the document or from the editor's content.
+     * @returns True when full screen should be left.
+     */
+    private shouldEscapeLeaveFullscreen;
+    /**
+     * Asks the editor to leave full screen. Safe to call when it is not in full screen.
+     * @returns void
+     */
+    private exitFullscreen;
+    /**
+     * Attaches or detaches everything that only makes sense while the editor is full screen.
+     * @param state True when the editor has just entered full screen.
+     * @returns void
+     */
+    private handleFullscreenChanged;
+    /**
+     * Detaches the listener that only makes sense while the editor is full screen.
+     * @returns void
+     */
+    private releaseFullscreen;
+    /**
+     * Pushes a value coming from the form into the editor.
+     * @param value The new content, or null/undefined for an empty editor.
+     * @returns void
+     */
+    writeValue(value: string | null | undefined): void;
+    /**
+     * Registers the callback used to report content changes to the form.
+     * @param fn The callback supplied by Angular forms.
+     * @returns void
+     */
+    registerOnChange(fn: (value: string) => void): void;
+    /**
+     * Registers the callback used to report the first blur to the form.
+     * @param fn The callback supplied by Angular forms.
+     * @returns void
+     */
+    registerOnTouched(fn: () => void): void;
+    /**
+     * Enables or disables editing.
+     * @param isDisabled True to switch the editor to read-only.
+     * @returns void
+     */
+    setDisabledState(isDisabled: boolean): void;
+    /**
+     * Writes content into the editor when it exists, guarding against the echo described on
+     * <see cref="writingValue"/>.
+     * @param value The content to write.
+     * @returns void
+     */
+    private applyValue;
+    /**
+     * Applies the disabled state to the editor when it exists.
+     * @param isDisabled True to switch the editor to read-only.
+     * @returns void
+     */
+    private applyDisabled;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TinymceEditorDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<TinymceEditorDirective, "textarea[tinymceEditor], div[tinymceEditor]", never, { "tinymceConfig": { "alias": "tinymceConfig"; "required": false; "isSignal": true; }; "tinymceToolbarMode": { "alias": "tinymceToolbarMode"; "required": false; "isSignal": true; }; "tinymceImageUploader": { "alias": "tinymceImageUploader"; "required": false; "isSignal": true; }; }, { "ready": "ready"; "failed": "failed"; }, never, never, true, never>;
+}
+
+interface TinyMceEditorDialogData {
     text: string;
-    configuration: Record<string, any>;
+    configuration: RawEditorOptions;
     infoButtonLabel?: string;
     onShowInfo?: Function;
     disabled?: boolean;
 }
-declare class FullScreenEditorComponent {
+/**
+ * A dialog that is nothing but an editor: the caller hands it a text and gets the edited one
+ * back through {@link saving}.
+ *
+ * The editor is {@link TinymceEditorDirective} on a plain `<textarea>`, so this dialog costs
+ * exactly what any other editor in the application costs — the TinyMCE bundle is fetched on
+ * first use and nothing about it reaches the initial chunk.
+ */
+declare class TinyMceEditorComponent {
     /** Emitted with the edited text when the user saves. */
     readonly saving: _angular_core.OutputEmitterRef<string>;
     private readonly dialogRef;
     /** Dialog configuration, injected and exposed as a signal. */
-    protected readonly dialogData: _angular_core.WritableSignal<FullScreenEditorDialogData>;
+    protected readonly dialogData: _angular_core.WritableSignal<TinyMceEditorDialogData>;
     /** Whether the editor is in read-only mode. */
     protected readonly disabled: _angular_core.WritableSignal<boolean>;
     /** Current editor content, kept as a plain field for [(ngModel)] two-way binding. */
     protected text: string;
-    /** TinyMCE editor configuration. */
-    protected tinymceConfig: Record<string, any>;
+    /** The profile handed to the editor directive, merged over its defaults. */
+    protected tinymceConfig: RawEditorOptions;
     constructor();
     /**
      * Save the current editor content and close the dialog.
      */
     protected ok(): void;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<FullScreenEditorComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FullScreenEditorComponent, "ng-component", never, {}, { "saving": "saving"; }, never, never, true, never>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TinyMceEditorComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TinyMceEditorComponent, "ng-component", never, {}, { "saving": "saving"; }, never, never, true, never>;
 }
 
-export { FullScreenEditorComponent, TinymceUtils };
-export type { FullScreenEditorDialogData };
+export { TinyMceEditorComponent, TinymceEditorDirective, TinymceLoaderService, TinymceUtils };
+export type { TinyMceEditorDialogData, TinymceImageUploader, TinymceToolbarMode };

package/ui.tinymce/README.md

@@ -1,12 +1,82 @@
-in application:
-1) install tinymce (npm install tinymce)
-1) install @tinymce/tinymce-angular (npm install @tinymce/tinymce-angular)
-2) setup assets in angular.json
-    {
-        "glob": "**/*",
-        "input": "node_modules/tinymce",
-        "output": "assets/tinymce"
-    }
-3) download language from 
-https://github.com/tinymce/tinymce/blob/develop/modules/tinymce/src/langs/it.js and put it in
-"assets/tinymce/langs/it.js"
+# ui.tinymce
+
+L'editor ricco della libreria: la direttiva `[tinymceEditor]`, il caricatore a runtime e i
+profili di configurazione.
+
+Non c'e' nessun wrapper Angular di mezzo. `@tinymce/tinymce-angular` era una dipendenza in piu'
+da tenere allineata ad Angular ad ogni major, e in cambio dava un componente `<editor>` che non
+sa fare il `ControlValueAccessor` come lo vogliamo noi: la direttiva sta su una `<textarea>`
+normale, quindi `[(ngModel)]`, `required` e lo stato pristine/dirty funzionano come su qualunque
+altro controllo.
+
+## Nell'applicazione
+
+1) `npm install tinymce` (peer dependency opzionale, versione 8)
+
+2) pubblicare il pacchetto fra gli asset, in `angular.json`:
+
+```json
+{
+  "glob": "**/*",
+  "input": "node_modules/tinymce",
+  "output": "assets/tinymce"
+}
+```
+
+3) la lingua italiana non sta dentro il pacchetto npm: `langs/it.js` e' committato in questo
+   entry point, va copiato in `src/assets/tinymce/langs/it.js`.
+
+Nient'altro: **non** serve nessun `<script>` in `index.html`. `TinymceLoaderService` inietta
+`assets/tinymce/tinymce.min.js` la prima volta che un editor viene creato, risolvendo l'URL
+contro il base href del documento (quindi funziona anche se l'applicazione e' servita da un
+sotto-percorso), e le chiamate successive riusano lo stesso script.
+
+## Uso
+
+```html
+<textarea tinymceEditor [(ngModel)]="item.text" name="text" required></textarea>
+```
+
+Con un profilo e un uploader di immagini:
+
+```html
+<textarea tinymceEditor
+          [tinymceConfig]="config"
+          [tinymceImageUploader]="upload"
+          (ready)="onReady($event)"
+          (failed)="onFailed($event)"
+          [(ngModel)]="item.text" name="text"></textarea>
+```
+
+```typescript
+protected readonly config = TinymceUtils.TinymceCompactConfig;
+protected readonly upload = (file: File) => this.api.upload(file); // torna l'URL dell'immagine
+```
+
+`tinymceToolbarMode="inline"` edita l'elemento sul posto invece di sostituirlo: richiede un
+`<div>`, non una `<textarea>`, e la direttiva lo dice esplicitamente se ci si sbaglia.
+
+## Profili
+
+`TinymceUtils` espone tre configurazioni, ognuna restituita come copia fresca ad ogni lettura:
+
+| Profilo | Per cosa |
+|---|---|
+| `TinymceConfig` | editor a tutta pagina, tutti i plugin open source di TinyMCE 8 |
+| `TinymceCompactConfig` | campo dentro una form: cresce col testo, toolbar in basso raggruppata |
+| `TinymceCompactExtendedConfig` | come sopra, piu' schermo intero, gruppo inserisci e vista sorgente |
+
+Descrivono **cosa offre l'editor** e nient'altro: caricamento (`base_url`, `language`,
+`license_key`) e tema (`skin`, `content_css`) li decidono il loader e la direttiva, che li
+risolvono contro il base href e contro `ThemeService`. Anche le opzioni di upload seguono
+`tinymceImageUploader`, cosi' un editor senza handler non puo' mostrare una scheda di caricamento
+che non porta da nessuna parte.
+
+I profili si passano a `[tinymceConfig]` e vincono sui default della direttiva; restano suoi
+`target`, `base_url`, `inline` e `setup`, che e' quello che tiene l'editor agganciato alla form.
+
+## Il dialog
+
+`TinyMceEditorComponent` e' un dialog che contiene solo un editor: riceve un testo, ne
+restituisce uno modificato tramite l'output `saving`. Usa il profilo compatto esteso, con la
+toolbar senza schermo intero — il dialog e' gia' tutto lo spazio disponibile.