@besaitech/ng-design-system 0.0.71 → 0.0.73

package/rich-text/index.d.ts

@@ -0,0 +1,363 @@
+import * as _angular_core from '@angular/core';
+import { InjectionToken } from '@angular/core';
+import { ControlValueAccessor } from '@angular/forms';
+import { SdsIconName, SdsLocalizedValue } from '@besaitech/ng-design-system';
+
+/** A toolbar action of {@link SdsRichTextEditor}. The tools also decide what the document may contain. */
+type SdsRichTextTool = 'paragraph' | 'heading2' | 'heading3' | 'bold' | 'italic' | 'underline' | 'strike' | 'bulletList' | 'orderedList' | 'blockquote' | 'link' | 'table' | 'horizontalRule' | 'clearFormatting' | 'undo' | 'redo';
+/** The toolbar shown when `[tools]` is not set. */
+declare const SDS_RICH_TEXT_DEFAULT_TOOLS: readonly SdsRichTextTool[];
+type SdsRichTextAppearance = 'default' | 'filled';
+/** Every string the editor shows or speaks. Translate them in a multi-language app. */
+interface SdsRichTextLabels {
+    /** Accessible name of the toolbar. */
+    toolbar: string;
+    paragraph: string;
+    heading2: string;
+    heading3: string;
+    bold: string;
+    italic: string;
+    underline: string;
+    strike: string;
+    bulletList: string;
+    orderedList: string;
+    blockquote: string;
+    link: string;
+    /** Insert a table (3 × 3, header row). */
+    table: string;
+    horizontalRule: string;
+    clearFormatting: string;
+    undo: string;
+    redo: string;
+    /** Label of the link address field. */
+    linkUrl: string;
+    linkPlaceholder: string;
+    linkApply: string;
+    linkRemove: string;
+    linkCancel: string;
+    /** Shown under the address field when it is not an http(s), mailto, tel, relative or anchor link. */
+    linkInvalid: string;
+    /** Accessible name of the table bar shown while the caret is in a table. */
+    tableTools: string;
+    tableAddRow: string;
+    tableAddColumn: string;
+    tableDeleteRow: string;
+    tableDeleteColumn: string;
+    /** Toggles the first row between header and data cells. */
+    tableHeaderRow: string;
+    tableDelete: string;
+    /**
+     * Warning when the loaded HTML holds elements the enabled tools cannot keep; token `{elements}` (e.g.
+     * `<img>, <iframe>`).
+     */
+    unsupportedContent: string;
+    /** Spoken counter with a `[maxLength]`; tokens `{count}` and `{max}`. */
+    countLimit: string;
+    /** Spoken counter without a limit; token `{count}`. */
+    count: string;
+}
+declare const SDS_RICH_TEXT_LABELS_EN: SdsRichTextLabels;
+/**
+ * App-wide label overrides for every {@link SdsRichTextEditor} — provide a (partial) translation once, e.g.
+ * `{ provide: SDS_RICH_TEXT_LABELS, useValue: { bold: 'Gras', … } }`. A component's own `[labels]` win over it.
+ * For an app that switches language at runtime, bind `[labels]` instead.
+ */
+declare const SDS_RICH_TEXT_LABELS: InjectionToken<Partial<SdsRichTextLabels>>;
+/**
+ * The link target the editor accepts for `raw`, normalised — or `null` when it is not safe to link to.
+ * Accepted: `http(s):`, `mailto:` and `tel:` URLs, site-relative paths (`/formations`) and anchors (`#faq`);
+ * a bare domain (`example.ch/page`) gets `https://`, a bare e-mail address gets `mailto:`. Everything else —
+ * `javascript:`, `data:`, protocol-relative `//host`, whitespace — is refused. The editor applies the same
+ * rule to pasted and loaded HTML, so an unsafe link never survives in its output.
+ */
+declare function sdsSafeHref(raw: string | null | undefined): string | null;
+
+interface ToolDef {
+    tool: SdsRichTextTool;
+    icon: SdsIconName;
+    group: number;
+    /** A formatting state the button reflects with `aria-pressed`. */
+    toggle: boolean;
+    /** Tiptap's keyboard shortcut, shown in the tooltip (`Mod` = ⌘ on Apple, Ctrl elsewhere). */
+    shortcut?: string;
+}
+type TableAction = 'addRow' | 'addColumn' | 'deleteRow' | 'deleteColumn' | 'headerRow' | 'delete';
+/**
+ * Marks content projected at the END of an {@link SdsRichTextEditor}'s toolbar — a language switcher (as in
+ * {@link SdsLocalizedRichTextEditor}), an "insert variable" menu… It stays visible in `readonly` mode, where
+ * the formatting buttons are hidden: `<div sdsRichTextToolbarEnd>…</div>`.
+ */
+declare class SdsRichTextToolbarEnd {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SdsRichTextToolbarEnd, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SdsRichTextToolbarEnd, "[sdsRichTextToolbarEnd]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * A rich-text field — headings, bold / italic / underline / strike, lists, quotes, links, dividers, undo/redo —
+ * for content that is stored and shown as HTML (course pages, instructions, articles). Built on Tiptap
+ * (ProseMirror), so the HTML it emits is always clean and structured: no inline styles, no `<font>`/`<span>`
+ * soup from Word or web pages, nothing outside the enabled tools.
+ *
+ * **The tools are the schema.** `[tools]` chooses the toolbar AND what the document may contain: drop
+ * `heading2`/`heading3` and pasted headings become paragraphs; drop `link` and links are unwrapped. Links
+ * only accept http(s), mailto, tel, site-relative paths and anchors ({@link sdsSafeHref}) — `javascript:`
+ * and friends are stripped from typed, pasted and loaded HTML alike, and links open in a new tab with
+ * `rel="noopener noreferrer nofollow"`. Still sanitise on display, as for any stored HTML.
+ *
+ * Implements ControlValueAccessor over an HTML string — use with reactive forms or `[(ngModel)]`. An empty
+ * document is `''` (not `<p></p>`), so `Validators.required` works. Writing a value never marks the control
+ * dirty. Keyboard: the usual shortcuts (⌘/Ctrl+B, I, U, K for a link, ⌘/Ctrl+Alt+2/3 for headings, Markdown
+ * shortcuts like `## ` or `- `); the toolbar is one Tab stop, arrows move inside it.
+ *
+ * Strings are English by default: pass `[labels]` (or provide {@link SDS_RICH_TEXT_LABELS}) in another
+ * language. Import from the secondary entry point `@besaitech/ng-design-system/rich-text`.
+ */
+declare class SdsRichTextEditor implements ControlValueAccessor {
+    readonly fieldId: string;
+    readonly label: _angular_core.InputSignal<string>;
+    /** Accessible name used when no visible [label] is provided. */
+    readonly ariaLabel: _angular_core.InputSignal<string>;
+    /** Shown in the empty document. */
+    readonly placeholder: _angular_core.InputSignal<string>;
+    readonly hint: _angular_core.InputSignal<string>;
+    readonly error: _angular_core.InputSignal<string>;
+    /** Mark the field invalid (danger frame + `aria-invalid`) without showing an [error] message. */
+    readonly invalid: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Language of the content (`lang` on the editable document), so the browser spell-checks it in the right
+     * language — e.g. `'de'` for the German version of a translated text.
+     */
+    readonly contentLanguage: _angular_core.InputSignal<string>;
+    /** Asterisk after the [label] (hidden from screen readers) + `aria-required`. It does not validate. */
+    readonly required: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Shows the content without the toolbar; it can be selected and copied but not changed. */
+    readonly readonly: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * The toolbar, in display order (groups are fixed: block, text, lists, insert, clear, history) — and the
+     * content the document may hold. Defaults to {@link SDS_RICH_TEXT_DEFAULT_TOOLS}. Set once: changing it
+     * rebuilds the editor (the content is kept, minus what the new tools no longer allow).
+     */
+    readonly tools: _angular_core.InputSignal<readonly SdsRichTextTool[]>;
+    /** Minimum visible lines of the editing area. */
+    readonly rows: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Lines after which the area scrolls instead of growing; 0 (default) grows with the content. */
+    readonly maxRows: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Cap on the plain-text length (markup is not counted); 0 means no limit. Typing stops at the cap. */
+    readonly maxLength: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Show the character counter (always shown with a [maxLength]). */
+    readonly showCount: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** `filled`: a borderless field on a muted ground, like `sds-textarea`'s. */
+    readonly appearance: _angular_core.InputSignal<SdsRichTextAppearance>;
+    /** Per-instance strings (merged over {@link SDS_RICH_TEXT_LABELS} and the English defaults). */
+    readonly labels: _angular_core.InputSignal<Partial<SdsRichTextLabels>>;
+    private readonly cdr;
+    private readonly host;
+    private readonly appLabels;
+    private readonly contentHost;
+    private readonly linkInput;
+    private readonly toolButtons;
+    protected readonly toolbarEnd: _angular_core.Signal<SdsRichTextToolbarEnd | undefined>;
+    private editor;
+    /** The HTML last written to or emitted by the control — '' for an empty document. */
+    private html;
+    private builtTools;
+    private readonly ready;
+    private readonly cvaDisabled;
+    /** Formatting active at the selection, per tool (refreshed on every transaction). */
+    private readonly activeTools;
+    private readonly history;
+    /** The first row of the table holding the caret is a header row. */
+    protected readonly headerRow: _angular_core.WritableSignal<boolean>;
+    /** Elements of the loaded HTML the enabled tools could not keep (see {@link LOSSY_TAGS}). */
+    protected readonly lostElements: _angular_core.WritableSignal<string[]>;
+    protected readonly tableActions: readonly {
+        action: TableAction;
+        label: keyof SdsRichTextLabels;
+        icon: SdsIconName | null;
+    }[];
+    protected readonly characters: _angular_core.WritableSignal<number>;
+    protected readonly rovingTool: _angular_core.WritableSignal<SdsRichTextTool | null>;
+    protected readonly linkOpen: _angular_core.WritableSignal<boolean>;
+    protected readonly linkDraft: _angular_core.WritableSignal<string>;
+    protected readonly linkError: _angular_core.WritableSignal<boolean>;
+    protected readonly l: _angular_core.Signal<SdsRichTextLabels>;
+    protected readonly isDisabled: _angular_core.Signal<boolean>;
+    /** The document can be changed (and the toolbar used). */
+    protected readonly interactive: _angular_core.Signal<boolean>;
+    protected readonly showToolbar: _angular_core.Signal<boolean>;
+    private readonly toolSet;
+    protected readonly groups: _angular_core.Signal<ToolDef[][]>;
+    protected readonly hasCounter: _angular_core.Signal<boolean>;
+    protected readonly lostLabel: _angular_core.Signal<string>;
+    protected readonly atLimit: _angular_core.Signal<boolean>;
+    protected readonly countLabel: _angular_core.Signal<string>;
+    protected readonly maxHeight: _angular_core.Signal<string | null>;
+    private readonly danger;
+    protected readonly frameClasses: _angular_core.Signal<string>;
+    private readonly describedBy;
+    /** Attributes of the contenteditable document (ProseMirror's own element). */
+    private readonly documentAttributes;
+    private readonly isApple;
+    constructor();
+    /** Move the caret into the document. */
+    focus(): void;
+    /**
+     * Insert plain text at the caret (replacing the selection) — for an "insert variable" button in the
+     * {@link SdsRichTextToolbarEnd} slot, say. The text is inserted as text, never parsed as HTML. No-op while
+     * disabled or read-only.
+     */
+    insertText(text: string): void;
+    private onChange;
+    private onTouched;
+    writeValue(value: string | null): void;
+    registerOnChange(fn: (value: string) => void): void;
+    registerOnTouched(fn: () => void): void;
+    setDisabledState(isDisabled: boolean): void;
+    protected isOn(tool: SdsRichTextTool): boolean;
+    protected canRun(tool: SdsRichTextTool): boolean;
+    protected buttonClass(def: ToolDef): string;
+    protected tooltip(def: ToolDef): string;
+    protected run(tool: SdsRichTextTool): void;
+    /** Roving focus inside the toolbar: one Tab stop, arrows / Home / End move between the buttons. */
+    protected onToolbarKeydown(event: KeyboardEvent): void;
+    /** A click in the blank area under the last line still places the caret (at the end). */
+    protected onAreaClick(event: MouseEvent): void;
+    protected tableButtonClass(action: TableAction): string;
+    protected runTable(action: TableAction): void;
+    protected openLink(): void;
+    protected onLinkInput(event: Event): void;
+    protected onLinkKeydown(event: KeyboardEvent): void;
+    protected applyLink(): void;
+    protected removeLink(): void;
+    protected closeLink(refocus: boolean): void;
+    private build;
+    private extensions;
+    private editorProps;
+    /**
+     * ⌘/Ctrl+K opens the link field. The editor owns the shortcut while it has focus: the event is stopped
+     * so an app-wide ⌘K (a command palette such as `sds-search-command`) does not open on top of it.
+     */
+    private onDocumentKeydown;
+    /**
+     * The control's value for the editor's document: '' when it is empty, and without the editor's own
+     * scaffolding — the empty paragraphs kept after a final list / quote / table so the caret can leave it
+     * (Tiptap's trailing node), and the table layout hints (`<colgroup>`, `style="min-width…"`, the default
+     * `colspan="1" rowspan="1"`) that columns no one resized do not need.
+     */
+    private currentHtml;
+    /** Flags the elements of `source` whose content the schema could not keep (shown under the field). */
+    private detectLoss;
+    private emit;
+    private refresh;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SdsRichTextEditor, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SdsRichTextEditor, "sds-rich-text-editor", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "hint": { "alias": "hint"; "required": false; "isSignal": true; }; "error": { "alias": "error"; "required": false; "isSignal": true; }; "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "contentLanguage": { "alias": "contentLanguage"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "tools": { "alias": "tools"; "required": false; "isSignal": true; }; "rows": { "alias": "rows"; "required": false; "isSignal": true; }; "maxRows": { "alias": "maxRows"; "required": false; "isSignal": true; }; "maxLength": { "alias": "maxLength"; "required": false; "isSignal": true; }; "showCount": { "alias": "showCount"; "required": false; "isSignal": true; }; "appearance": { "alias": "appearance"; "required": false; "isSignal": true; }; "labels": { "alias": "labels"; "required": false; "isSignal": true; }; }, {}, ["toolbarEnd"], ["[sdsRichTextToolbarEnd]"], true, never>;
+}
+
+/**
+ * The translatable twin of {@link SdsRichTextEditor}: one rich-text field over a {@link SdsLocalizedValue} —
+ * `{ fr: '<p>…</p>', de: '<p>…</p>', en: … }` — for content stored per language (course pages, homework
+ * instructions, articles). It works like `sds-localized-input`: one language is edited at a time, a compact
+ * switcher at the end of the toolbar flips the language, and a dot marks the languages that already have
+ * content (green), a required one that is still empty (danger) or a missing translation (faint). Empty
+ * translations are pruned from the emitted value, so an untouched language never appears in the map.
+ *
+ * Each language has its own editor underneath, kept alive while hidden: undo / redo, the caret and the
+ * scroll position stay per language, and undoing after a switch can never bring another language's text
+ * back. The document carries its `lang`, so the browser spell-checks each translation in its language.
+ *
+ * The active language defaults to {@link currentLanguage} when it is one of {@link languages}, otherwise the
+ * first accepted language. Everything else — `[tools]` (the schema), safe links, `rows` / `maxRows`,
+ * `maxLength` (per language), labels — behaves as in {@link SdsRichTextEditor}.
+ *
+ * Implements ControlValueAccessor over the map — use with reactive forms or `[(ngModel)]`:
+ * `<sds-localized-rich-text-editor [languages]="['fr','de','en']" formControlName="description" />`.
+ * Import from `@besaitech/ng-design-system/rich-text`.
+ */
+declare class SdsLocalizedRichTextEditor implements ControlValueAccessor {
+    protected readonly baseId: string;
+    readonly label: _angular_core.InputSignal<string>;
+    /** Accessible name when there is no visible {@link label}; each language's editor adds its code. */
+    readonly ariaLabel: _angular_core.InputSignal<string>;
+    readonly placeholder: _angular_core.InputSignal<string>;
+    readonly hint: _angular_core.InputSignal<string>;
+    /** Error message under the field (danger frame + `aria-invalid`); replaces the hint. */
+    readonly error: _angular_core.InputSignal<string>;
+    /** Mark the field invalid (danger frame + `aria-invalid`) without showing an [error] message. */
+    readonly invalid: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** An asterisk after the [label] and `aria-required`. It does not validate — keep your own validator. */
+    readonly required: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Languages that must be filled (e.g. the site's main language): while empty, their switcher dot shows in the
+     * danger colour and its title says {@link requiredLanguageLabel}. Display only — validate in the form.
+     */
+    readonly requiredLanguages: _angular_core.InputSignal<string[]>;
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Every translation can be read (the switcher still works) but none changed; the toolbar is hidden. */
+    readonly readonly: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** The accepted language codes, in display order (e.g. `['fr','de','en']`). */
+    readonly languages: _angular_core.InputSignal<string[]>;
+    /** Language to open on; used when it is one of {@link languages}, else the first accepted language. */
+    readonly currentLanguage: _angular_core.InputSignal<string | null>;
+    /** The toolbar and the schema, as on {@link SdsRichTextEditor}. */
+    readonly tools: _angular_core.InputSignal<readonly SdsRichTextTool[]>;
+    readonly rows: _angular_core.InputSignalWithTransform<number, unknown>;
+    readonly maxRows: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Cap on each language's plain-text length; 0 means no limit. */
+    readonly maxLength: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Show the character counter of the language being edited (always shown with a [maxLength]). */
+    readonly showCount: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly appearance: _angular_core.InputSignal<SdsRichTextAppearance>;
+    /** Editor strings, as on {@link SdsRichTextEditor}. */
+    readonly labels: _angular_core.InputSignal<Partial<SdsRichTextLabels>>;
+    /**
+     * Accessible name of the language switcher, and the title suffixes of an empty language. English defaults;
+     * translate them in a multi-language app (the tabs show only the language code).
+     */
+    readonly languageSwitcherLabel: _angular_core.InputSignal<string>;
+    readonly untranslatedLabel: _angular_core.InputSignal<string>;
+    /** Title suffix of a required language that is still empty (see {@link requiredLanguages}). */
+    readonly requiredLanguageLabel: _angular_core.InputSignal<string>;
+    private readonly host;
+    private readonly cdr;
+    private readonly editors;
+    protected readonly valueMap: _angular_core.WritableSignal<SdsLocalizedValue>;
+    /** Language chosen with the switcher; null means "follow currentLanguage / the first language". */
+    private readonly manual;
+    private readonly cvaDisabled;
+    protected readonly isDisabled: _angular_core.Signal<boolean>;
+    /** The language being edited. */
+    protected readonly activeLang: _angular_core.Signal<string>;
+    /** Move the caret into the active language's document. */
+    focus(): void;
+    protected filled(lang: string): boolean;
+    /** A required language (see {@link requiredLanguages}) that is still empty. */
+    protected mustFill(lang: string): boolean;
+    protected editorName(lang: string): string;
+    protected placeholderFor(lang: string): string;
+    protected tabTitle(lang: string): string;
+    protected tabClass(lang: string): string;
+    protected dotClass(lang: string): string;
+    /**
+     * Switch language. From a click, the caret goes into the new language's document (ready to type); from the
+     * arrow keys, focus follows to the new language's tab. Rendered at once so focus never lands on the
+     * editor that was just hidden.
+     */
+    protected select(lang: string, focusTarget: 'editor' | 'tab'): void;
+    /** The switcher is one Tab stop; arrows / Home / End change the language (automatic activation). */
+    protected onTabsKeydown(event: KeyboardEvent): void;
+    protected write(lang: string, html: string): void;
+    /** Touched once focus leaves the whole field (moving between toolbar, link field and document is not leaving). */
+    protected onFocusOut(event: FocusEvent): void;
+    private editorFor;
+    private onChange;
+    private onTouched;
+    writeValue(value: SdsLocalizedValue | null): void;
+    registerOnChange(fn: (value: SdsLocalizedValue) => void): void;
+    registerOnTouched(fn: () => void): void;
+    setDisabledState(isDisabled: boolean): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SdsLocalizedRichTextEditor, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SdsLocalizedRichTextEditor, "sds-localized-rich-text-editor", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "hint": { "alias": "hint"; "required": false; "isSignal": true; }; "error": { "alias": "error"; "required": false; "isSignal": true; }; "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "requiredLanguages": { "alias": "requiredLanguages"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "languages": { "alias": "languages"; "required": false; "isSignal": true; }; "currentLanguage": { "alias": "currentLanguage"; "required": false; "isSignal": true; }; "tools": { "alias": "tools"; "required": false; "isSignal": true; }; "rows": { "alias": "rows"; "required": false; "isSignal": true; }; "maxRows": { "alias": "maxRows"; "required": false; "isSignal": true; }; "maxLength": { "alias": "maxLength"; "required": false; "isSignal": true; }; "showCount": { "alias": "showCount"; "required": false; "isSignal": true; }; "appearance": { "alias": "appearance"; "required": false; "isSignal": true; }; "labels": { "alias": "labels"; "required": false; "isSignal": true; }; "languageSwitcherLabel": { "alias": "languageSwitcherLabel"; "required": false; "isSignal": true; }; "untranslatedLabel": { "alias": "untranslatedLabel"; "required": false; "isSignal": true; }; "requiredLanguageLabel": { "alias": "requiredLanguageLabel"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+export { SDS_RICH_TEXT_DEFAULT_TOOLS, SDS_RICH_TEXT_LABELS, SDS_RICH_TEXT_LABELS_EN, SdsLocalizedRichTextEditor, SdsRichTextEditor, SdsRichTextToolbarEnd, sdsSafeHref };
+export type { SdsRichTextAppearance, SdsRichTextLabels, SdsRichTextTool };