nexus-shared 1.1.21 → 3.0.0

package/dist/Helpers/RichTextHelpers.d.ts

@@ -0,0 +1,77 @@
+/** How a template token is written in the text: `|Key|` (reports) or `{{Key}}` (messages). */
+export type RichTextTokenFormat = "|key|" | "{{key}}";
+/** A value a template fills in, such as the guest's name. */
+export interface RichTextToken {
+    /** The key the template engine fills, e.g. "CustomerName": letters, digits, `_`, and `.`, starting with a letter or `_`. */
+    key: string;
+    /** Shown on the chip in the editor and in its menu. Default: the key. */
+    label?: string;
+    /** A second line in the menu, e.g. "The guest's full name". */
+    description?: string;
+    /** A heading the menu groups tokens under, e.g. "Guest". */
+    group?: string;
+}
+export interface RichTextOptions {
+    /** Keeps images (`<img>` with an http, https, relative, or `data:image` address). Default false: images are removed. */
+    images?: boolean;
+}
+export interface RichTextRenderOptions extends RichTextOptions {
+    /** Links to other sites open in a new tab. The stored HTML never has a target; it is added when shown. */
+    newTab?: boolean;
+    /** How tokens are written, for `values`. */
+    tokenFormat?: RichTextTokenFormat;
+    /** Fills tokens with these values, as text. Tokens without a value stay as they are. */
+    values?: Readonly<Record<string, string | number | null | undefined>>;
+}
+export interface RichTextEditorHtmlOptions extends RichTextOptions {
+    /** Tokens written this way show as chips. */
+    tokenFormat?: RichTextTokenFormat;
+    /** The known tokens: their labels go on the chips, and other keys are marked unknown. */
+    tokens?: readonly RichTextToken[];
+}
+/** Rules for rich text. Lengths count the characters a reader sees, not the HTML. */
+export interface RichTextRules {
+    required?: boolean;
+    /** Fewest characters of text. Not checked on empty text; use `required` for that. */
+    minLength?: number;
+    /** Most characters of text. */
+    maxLength?: number;
+    /** Runs after the other rules pass, with the HTML and its plain text. */
+    validate?: (html: string, text: string) => string | null | undefined;
+}
+/**
+ * The HTML a rich text editor stores: only the tags, attributes, and styles it makes, rebuilt from scratch, so script,
+ * event handlers, `javascript:` links, and foreign styles cannot pass. Pastes from Word and Google Docs keep their
+ * bold, italic, underline, colors, lists, and tables. Empty text gives "".
+ *
+ * @example sanitizeRichText('<p onclick="x()">Hi <b>there</b><script>alert(1)</script></p>') // '<p>Hi <strong>there</strong></p>'
+ */
+export declare function sanitizeRichText(html: string | null | undefined, options?: RichTextOptions): string;
+/** The same HTML as `sanitizeRichText`, one block per line and indented, for a source view. */
+export declare function formatRichTextHtml(html: string | null | undefined, options?: RichTextOptions): string;
+/**
+ * The text a reader sees: one line per paragraph, heading, or list item, line breaks kept, table cells separated by
+ * tabs, and spaces collapsed. Tokens stay as written.
+ */
+export declare function richTextToPlainText(html: string | null | undefined): string;
+/** Whether rich text has nothing a reader sees: no text and no image. A rule or an empty table counts as empty. */
+export declare function isRichTextEmpty(html: string | null | undefined): boolean;
+/**
+ * HTML for display (`RichTextView`): sanitized, with tokens filled from `values` and, with `newTab`, links to other
+ * sites opening in a new tab.
+ */
+export declare function renderRichTextHtml(html: string | null | undefined, options?: RichTextRenderOptions): string;
+/** HTML for the editor itself: sanitized, with each token shown as a chip that is edited as one piece. */
+export declare function richTextToEditorHtml(html: string | null | undefined, options?: RichTextEditorHtmlOptions): string;
+/** The HTML of one token chip, as the editor inserts it. */
+export declare function richTextTokenChip(key: string, format: RichTextTokenFormat, token?: RichTextToken | null, known?: boolean): string;
+/** A token as the template engine reads it: `|Key|` or `{{Key}}`. */
+export declare function formatRichTextToken(key: string, format: RichTextTokenFormat): string;
+/** The keys of the tokens in the text, each once, in the order they first appear. */
+export declare function findRichTextTokens(html: string | null | undefined, format: RichTextTokenFormat): string[];
+/** Fills the tokens in sanitized HTML with values, as text. Tokens without a value stay as they are. */
+export declare function fillRichTextTokens(html: string | null | undefined, values: Readonly<Record<string, string | number | null | undefined>>, format?: RichTextTokenFormat): string;
+/** Checks rich text against its rules and returns the first message, or `null`. Lengths count the plain text. */
+export declare function validateRichText(html: string | null | undefined, rules: RichTextRules, fieldName?: string): string | null;
+/** A CSS color as `#rrggbb`: hex, `rgb()`, `rgba()`, or a common name. Transparent and unknown colors give `null`. */
+export declare function parseColor(value: string): string | null;