@mk-kit/ui 0.34.0

package/types/mk-kit-ui-rich-text.d.ts

@@ -0,0 +1,187 @@
+import * as _angular_core from '@angular/core';
+import { OnDestroy } from '@angular/core';
+import { ControlValueAccessor } from '@angular/forms';
+import * as _mk_kit_ui_core from '@mk-kit/ui/core';
+
+/**
+ * Rich text — a small WYSIWYG form control over a sanitised HTML string, for
+ * single "description"-style fields where the full block editor is overkill.
+ * Renders a textarea-like surface with the floating inline formatting toolbar
+ * (Bold, Italic, Underline, Strikethrough, Inline code, Link, Clear) on text
+ * selection; Enter inserts a line break.
+ *
+ * Implements `ControlValueAccessor` with a two-way `value` model, so it works
+ * with `[(ngModel)]`, reactive forms and `[(value)]`. Every value — written or
+ * emitted — passes through {@link sanitizeInlineHtml}, and a visually empty
+ * surface (whitespace / lone `<br>`s) normalises to `''` so `required`
+ * validation behaves.
+ *
+ * ```html
+ * <mk-rich-text [(ngModel)]="description" placeholder="Describe it…" />
+ * <mk-rich-text [(value)]="html" minHeight="8rem" />
+ * ```
+ */
+declare class MkRichText implements ControlValueAccessor {
+    private readonly field;
+    private readonly i18n;
+    /** Two-way HTML string value (sanitised; `''` when visually empty). */
+    readonly value: _angular_core.ModelSignal<string>;
+    /** Placeholder shown when empty. */
+    readonly placeholder: _angular_core.InputSignal<string>;
+    /** Disable the control. */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Force the invalid visual + `aria-invalid` when used standalone. */
+    readonly invalid: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Minimum height of the editable area (any CSS length). */
+    readonly minHeight: _angular_core.InputSignal<string>;
+    /** Accessible label when not labelled by an `mk-form-field`. */
+    readonly ariaLabel: _angular_core.InputSignal<string>;
+    private readonly cvaDisabled;
+    private onChange;
+    private onTouched;
+    protected readonly isDisabled: _angular_core.Signal<boolean>;
+    protected readonly isInvalid: _angular_core.Signal<boolean>;
+    protected readonly labelledBy: string | null;
+    protected readonly describedBy: _angular_core.Signal<string | null>;
+    protected readonly effectiveAriaLabel: _angular_core.Signal<string>;
+    /** Sanitised view of the model, rendered into the engine. */
+    protected readonly safeHtml: _angular_core.Signal<string>;
+    /** User edit: sanitise, normalise the empty state, propagate. */
+    protected onContentChange(html: string): void;
+    protected onFocusChange(focused: boolean): void;
+    writeValue(value: unknown): void;
+    registerOnChange(fn: (value: string) => void): void;
+    registerOnTouched(fn: () => void): void;
+    setDisabledState(isDisabled: boolean): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkRichText, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MkRichText, "mk-rich-text", never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "minHeight": { "alias": "minHeight"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "aria-label"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; }, never, never, true, never>;
+}
+
+/** Payload for a split (Enter) event: text before/after the caret. */
+interface MkRichTextSplit {
+    before: string;
+    after: string;
+}
+/** A formatting command exposed by the floating toolbar. */
+interface MkInlineTool {
+    id: string;
+    label: string;
+    icon: string;
+    shortcut?: string;
+}
+/**
+ * Rich-text engine — an accessible contenteditable surface with a floating
+ * inline formatting toolbar (Bold, Italic, Underline, Strikethrough, Inline
+ * code, Link, Clear). Built on the native Selection API +
+ * `document.execCommand` (deprecated but universally supported and
+ * dependency-free — the only practical way to do inline formatting without a
+ * heavyweight editor engine).
+ *
+ * This is the low-level building block: it emits HTML via `contentChange`, and
+ * structural intents (`splitAt`, `removeEmpty`, `arrowOut`) so a block-editor
+ * host can create, merge or navigate blocks. For a standalone form control use
+ * {@link MkRichText} (`<mk-rich-text>`), which wraps this engine in a CVA over
+ * a sanitised HTML string.
+ */
+declare class MkRichTextEngine implements OnDestroy {
+    private readonly document;
+    private readonly host;
+    private readonly editableRef;
+    protected readonly i18n: _mk_kit_ui_core.MkI18nStrings;
+    /** Pending toolbar-hide delay from `onBlur`; cleared on destroy. */
+    private blurTimer;
+    /** Current HTML content. */
+    readonly html: _angular_core.InputSignal<string>;
+    /** Placeholder shown when empty. */
+    readonly placeholder: _angular_core.InputSignal<string>;
+    /** Disable editing. */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Allow soft line breaks (Shift+Enter). Plain Enter always splits. */
+    readonly multiline: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Emit `splitAt` on Enter (block-editor hosts). When `false` — standalone
+     * field usage — Enter inserts a line break inside this surface instead.
+     */
+    readonly splitOnEnter: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Minimum height of the editable surface (any CSS length). */
+    readonly minHeight: _angular_core.InputSignal<string | null>;
+    /** Accessible label for the editable region. */
+    readonly ariaLabel: _angular_core.InputSignal<string>;
+    /** Id of an external label element, for `aria-labelledby`. */
+    readonly labelledBy: _angular_core.InputSignal<string | null>;
+    /** Space-separated id list for `aria-describedby`. */
+    readonly describedBy: _angular_core.InputSignal<string | null>;
+    /** Reflect an invalid state via `aria-invalid`. */
+    readonly invalid: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Fired on every edit with the sanitised-by-construction HTML. */
+    readonly contentChange: _angular_core.OutputEmitterRef<string>;
+    /** Enter pressed: `before` stays in this block, `after` starts a new one. */
+    readonly splitAt: _angular_core.OutputEmitterRef<MkRichTextSplit>;
+    /** Backspace at the very start of an empty block. */
+    readonly removeEmpty: _angular_core.OutputEmitterRef<void>;
+    /** Caret tried to leave the top/bottom edge with an arrow key. */
+    readonly arrowOut: _angular_core.OutputEmitterRef<"up" | "down">;
+    /** Focus/blur bubbled so the wrapper can show selection chrome. */
+    readonly focusChange: _angular_core.OutputEmitterRef<boolean>;
+    protected readonly isEmpty: _angular_core.WritableSignal<boolean>;
+    protected readonly toolbar: _angular_core.WritableSignal<{
+        visible: boolean;
+        top: number;
+        left: number;
+    }>;
+    protected readonly activeFormats: _angular_core.WritableSignal<Set<string>>;
+    protected readonly tools: MkInlineTool[];
+    protected readonly showPlaceholder: _angular_core.Signal<boolean>;
+    constructor();
+    /** Places the caret and focuses (called by the host for navigation). */
+    focus(position?: 'start' | 'end'): void;
+    protected onInput(): void;
+    protected onFocus(): void;
+    ngOnDestroy(): void;
+    protected onBlur(): void;
+    protected onSelectionChange(): void;
+    protected onKeydown(event: KeyboardEvent): void;
+    /** Escape inside the toolbar returns focus to the text; arrows move tools. */
+    protected onToolbarKeydown(event: KeyboardEvent): void;
+    /** Runs a toolbar command, keeping the model + toolbar state in sync. */
+    protected runTool(id: string): void;
+    protected isActive(id: string): boolean;
+    private emitSplit;
+    /** Inserts a `<br>` at the caret (Enter in `splitOnEnter=false` mode). */
+    private insertLineBreak;
+    /** Extracts markup after the caret so the host can start a new block with it. */
+    private splitHtmlAtCaret;
+    private wrapInlineCode;
+    private applyLink;
+    private updateToolbar;
+    private computeEmpty;
+    private setCaret;
+    private isSelectionCollapsed;
+    private isCaretAtStart;
+    private isCaretAtEnd;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkRichTextEngine, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MkRichTextEngine, "mk-rich-text-engine", never, { "html": { "alias": "html"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "multiline": { "alias": "multiline"; "required": false; "isSignal": true; }; "splitOnEnter": { "alias": "splitOnEnter"; "required": false; "isSignal": true; }; "minHeight": { "alias": "minHeight"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "labelledBy": { "alias": "labelledBy"; "required": false; "isSignal": true; }; "describedBy": { "alias": "describedBy"; "required": false; "isSignal": true; }; "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; }, { "contentChange": "contentChange"; "splitAt": "splitAt"; "removeEmpty": "removeEmpty"; "arrowOut": "arrowOut"; "focusChange": "focusChange"; }, never, never, true, never>;
+}
+
+/**
+ * Allow-list sanitiser for inline rich-text HTML — the security backbone of
+ * both `<mk-rich-text>` and the block editor's text blocks.
+ *
+ * SECURITY MODEL: rich-text surfaces store HTML authored through the editor's
+ * restricted formatting commands. Before that markup is emitted, persisted or
+ * re-rendered it is passed through {@link sanitizeInlineHtml}, an allow-list
+ * cleaner that strips scripts, event handlers and dangerous URLs. Angular's
+ * `DomSanitizer` re-sanitises at display time where applicable. This module is
+ * dependency-free so it can run on a server (SSG/SSR) — never feed its output
+ * back into `innerHTML` without sanitising again.
+ */
+/**
+ * Allow-list cleaner for inline rich text. Keeps a small set of formatting
+ * tags, strips everything else's tags (preserving their text), removes event
+ * handler attributes and unsafe `href`s. Not a substitute for `DomSanitizer`,
+ * but makes the serialised string safe by construction.
+ */
+declare function sanitizeInlineHtml(html: string): string;
+
+export { MkRichText, MkRichTextEngine, sanitizeInlineHtml };
+export type { MkRichTextSplit };