@elasticias/ui 1.0.53 → 1.0.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elasticias/ui",
-  "version": "1.0.53",
+  "version": "1.0.54",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
     "@angular/core": "^21.0.0",
@@ -15,7 +15,13 @@
     "chart.js": "^4.5.0",
     "primeng": "^21.0.0",
     "rxjs": "~7.8.0",
-    "@angular/platform-browser": "21.2"
+    "@angular/platform-browser": "21.2",
+    "quill": "^2.0.3"
+  },
+  "peerDependenciesMeta": {
+    "quill": {
+      "optional": true
+    }
   },
   "sideEffects": false,
   "repository": {
@@ -36,6 +42,10 @@
     ".": {
       "types": "./types/elasticias-ui.d.ts",
       "default": "./fesm2022/elasticias-ui.mjs"
+    },
+    "./rich-text": {
+      "types": "./types/elasticias-ui-rich-text.d.ts",
+      "default": "./fesm2022/elasticias-ui-rich-text.mjs"
     }
   },
   "type": "module",

package/types/elasticias-ui-rich-text.d.ts

@@ -0,0 +1,151 @@
+import * as _angular_core from '@angular/core';
+import { DoCheck, EventEmitter, Provider } from '@angular/core';
+import { ControlValueAccessor, NgControl } from '@angular/forms';
+import { EditorInitEvent } from 'primeng/editor';
+import { AbstractEfFormControl } from '@elasticias/ui';
+
+/**
+ * A rich text field: PrimeNG's Editor (Quill 2) with a small toolbar (bold,
+ * italic, underline, bulleted and numbered lists, link, clear formatting) and
+ * sanitised HTML out (`sanitizeRichHtml`): the toolbar's tags only, safe links,
+ * no script, style, class or event attribute, and `''` for an empty editor.
+ *
+ * It lives in `@elasticias/ui/rich-text` so that only apps that use it bundle
+ * the editor and need `quill` (a peer dependency of this entry). PrimeNG loads
+ * Quill with a dynamic import the first time an editor renders, so a screen
+ * without one never downloads it. `ef-localized-input`'s `rich` mode renders
+ * it through `EF_RICH_TEXT`; provide that with `provideEfRichText()`.
+ *
+ * - `dir` and `lang` apply to the editing area only; the toolbar is page chrome.
+ * - Disabled by `[disabled]`, a form's `disable()` or `[efReadOnly]`; `readonly`
+ *   keeps the text selectable. The toolbar is disabled with it.
+ * - The editing area is a `role="textbox"` named by the label and described
+ *   by the hint, the errors and `describedByExtra`.
+ * - An incoming value equal to what it last emitted is ignored, so binding
+ *   the output back never resets the caret.
+ *
+ * i18n keys the app's bundles must define (toolbar names and the link bubble,
+ * whose Quill texts are otherwise hardcoded English):
+ *
+ * | key | fr | ar | en |
+ * |---|---|---|---|
+ * | `ef_rich_text_bold` | Gras | غامق | Bold |
+ * | `ef_rich_text_italic` | Italique | مائل | Italic |
+ * | `ef_rich_text_underline` | Souligné | تسطير | Underline |
+ * | `ef_rich_text_bullet_list` | Liste à puces | قائمة نقطية | Bulleted list |
+ * | `ef_rich_text_ordered_list` | Liste numérotée | قائمة مرقمة | Numbered list |
+ * | `ef_rich_text_link` | Lien | رابط | Link |
+ * | `ef_rich_text_clean` | Effacer la mise en forme | مسح التنسيق | Clear formatting |
+ * | `ef_rich_text_toolbar` | Mise en forme | التنسيق | Formatting |
+ * | `ef_rich_text_link_enter` | Adresse du lien : | عنوان الرابط: | Link address: |
+ * | `ef_rich_text_link_visit` | Ouvrir : | فتح: | Open: |
+ * | `ef_rich_text_link_edit` | Modifier | تعديل | Edit |
+ * | `ef_rich_text_link_remove` | Retirer | إزالة | Remove |
+ * | `ef_rich_text_link_save` | Enregistrer | حفظ | Save |
+ *
+ * ```html
+ * <ef-rich-text name="description" labelKey="product_description" dir="rtl" lang="ar"
+ *     [value]="html()" (valueChangeEvent)="html.set($event)" />
+ * ```
+ */
+declare class EfRichTextComponent extends AbstractEfFormControl implements ControlValueAccessor, DoCheck {
+    readonly value: _angular_core.InputSignal<string | null | undefined>;
+    /** Direction of the text (`rtl` for Arabic), on the editing area only. */
+    readonly dir: _angular_core.InputSignal<"ltr" | "rtl" | "auto" | null>;
+    /** Language of the text, on the editing area only. */
+    readonly lang: _angular_core.InputSignal<string | null>;
+    /** Id(s) naming the editing area when the label is rendered elsewhere
+     *  (`ef-localized-input` draws one label above its culture tabs). */
+    readonly labelledBy: _angular_core.InputSignal<string | null>;
+    /** Visible height of the editing area, in lines. */
+    readonly rows: _angular_core.InputSignal<number>;
+    /** Sanitised HTML, `''` when the editor holds no text. */
+    readonly valueChangeEvent: EventEmitter<string>;
+    readonly ngControl: NgControl | null;
+    private readonly host;
+    protected readonly formats: string[];
+    protected readonly modules: {
+        keyboard: {
+            bindings: {
+                tab: {
+                    key: string;
+                    handler: () => boolean;
+                };
+                'indent code-block': null;
+                'outdent code-block': null;
+                'remove tab': null;
+                indent: {
+                    format: string[];
+                    key: string;
+                    handler: () => boolean;
+                };
+                outdent: {
+                    shiftKey: boolean;
+                    format: string[];
+                    key: string;
+                    handler: () => boolean;
+                };
+            };
+        };
+    };
+    protected readonly labelId: string;
+    private readonly current;
+    private readonly quill;
+    private lastEmitted;
+    private onChange;
+    private onTouched;
+    constructor();
+    get isInvalid(): boolean;
+    get serverErrors(): string[] | null;
+    get showRequired(): boolean;
+    /** Read-only or disabled: Quill and the toolbar stop editing. */
+    protected locked(): boolean;
+    protected onInit(event: EditorInitEvent): void;
+    protected onTextChange(): void;
+    protected handleBlur(): void;
+    ngDoCheck(): void;
+    writeValue(v: string | null): void;
+    registerOnChange(fn: (v: string) => void): void;
+    registerOnTouched(fn: () => void): void;
+    setDisabledState(disabled: boolean): void;
+    /** Replaces the content unless it is our own echo or the same HTML. */
+    private apply;
+    /** Role, name, state, direction and language: everything that follows signals. */
+    private decorateFromInputs;
+    /** Validity and what describes the field, which follow the form control. */
+    private decorateFromForm;
+    /** Quill's link bubble texts are hardcoded English in its CSS; ours come from attributes. */
+    private translateBubble;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<EfRichTextComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<EfRichTextComponent, "ef-rich-text", never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "dir": { "alias": "dir"; "required": false; "isSignal": true; }; "lang": { "alias": "lang"; "required": false; "isSignal": true; }; "labelledBy": { "alias": "labelledBy"; "required": false; "isSignal": true; }; "rows": { "alias": "rows"; "required": false; "isSignal": true; }; }, { "valueChangeEvent": "valueChangeEvent"; }, never, never, true, never>;
+}
+
+/**
+ * Turns on `ef-localized-input`'s `rich` mode for the app. Quill still loads
+ * lazily, the first time an editor renders.
+ *
+ * ```ts
+ * providers: [provideEfRichText()]
+ * ```
+ */
+declare function provideEfRichText(): Provider;
+
+/**
+ * Whitelists the HTML an ef-rich-text produces: the toolbar's tags, a link's
+ * `href` when it is http(s), mailto or tel (with `rel` and `target` set by us),
+ * and no other attribute, so no style, class or event handler leaves the
+ * browser. Other tags are unwrapped, keeping their text; script, style and
+ * frames go with their content. Quill's non-breaking spaces between words
+ * become spaces. An editor holding no text returns `''`, never `<p><br></p>`.
+ *
+ * Browser only: it parses into a `<template>` and so needs `document`.
+ *
+ * Security note: `npm audit` flags quill 2.0.3 (GHSA-v3m3-f69x-jf25, XSS via
+ * HTML export; low severity, no patched release). It is mitigated here
+ * because every value ef-rich-text emits goes through this function, and
+ * incoming HTML goes through it before Quill parses it. Never render
+ * `getSemanticHTML()` without it.
+ */
+declare function sanitizeRichHtml(html: string | null | undefined): string;
+
+export { EfRichTextComponent, provideEfRichText, sanitizeRichHtml };