@cratis/scene.primereact 4.6.0 → 4.8.0

package/dist/esm/useResettingState.d.ts

@@ -0,0 +1,3 @@
+import { Dispatch, SetStateAction } from 'react';
+export declare function useResettingState<TState>(source: unknown, initial: () => TState): [TState, Dispatch<SetStateAction<TState>>];
+//# sourceMappingURL=useResettingState.d.ts.map

package/dist/esm/useResettingState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useResettingState.d.ts","sourceRoot":"","sources":["../../useResettingState.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAyB,MAAM,OAAO,CAAC;AAgBxE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,CAc5H"}

package/dist/esm/useResettingState.js

@@ -0,0 +1,45 @@
+import { useState, useCallback } from 'react';
+import { useStructuralValue } from './useStructuralValue.js';
+
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+/**
+ * State that starts from authored data and starts over when that data really changes.
+ *
+ * A control's selection or expansion is runtime state the user changes, yet it is also authored on the
+ * element. Reading the authored value once (`useState(() => authored)`) ignores a later edit of the document;
+ * resetting on every render discards what the user did. This does neither: the state follows `source` when
+ * its content changes, compared structurally because every document edit clones the data, and is otherwise
+ * left alone - so an unrelated property edit does not undo the user's choice.
+ *
+ * @param source The authored data the state derives from.
+ * @param initial Derives the starting state from the authored data.
+ * @returns The state and its setter, like `useState`.
+ */ function useResettingState(source, initial) {
+    const stable = useStructuralValue(source);
+    const [held, setHeld] = useState(()=>({
+            source: stable,
+            value: initial()
+        }));
+    let current = held;
+    if (held.source !== stable) {
+        current = {
+            source: stable,
+            value: initial()
+        };
+        setHeld(current);
+    }
+    const update = useCallback((action)=>{
+        setHeld((previous)=>({
+                source: previous.source,
+                value: typeof action === 'function' ? action(previous.value) : action
+            }));
+    }, []);
+    return [
+        current.value,
+        update
+    ];
+}
+
+export { useResettingState };
+//# sourceMappingURL=useResettingState.js.map

package/dist/esm/useResettingState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useResettingState.js","sources":["../../useResettingState.ts"],"sourcesContent":["// Copyright (c) Cratis. All rights reserved.\n// Licensed under the MIT license. See LICENSE file in the project root for full license information.\n\nimport { Dispatch, SetStateAction, useCallback, useState } from 'react';\nimport { useStructuralValue } from './useStructuralValue';\n\n/**\n * State that starts from authored data and starts over when that data really changes.\n *\n * A control's selection or expansion is runtime state the user changes, yet it is also authored on the\n * element. Reading the authored value once (`useState(() => authored)`) ignores a later edit of the document;\n * resetting on every render discards what the user did. This does neither: the state follows `source` when\n * its content changes, compared structurally because every document edit clones the data, and is otherwise\n * left alone - so an unrelated property edit does not undo the user's choice.\n *\n * @param source The authored data the state derives from.\n * @param initial Derives the starting state from the authored data.\n * @returns The state and its setter, like `useState`.\n */\nexport function useResettingState<TState>(source: unknown, initial: () => TState): [TState, Dispatch<SetStateAction<TState>>] {\n    const stable = useStructuralValue(source);\n    const [held, setHeld] = useState(() => ({ source: stable, value: initial() }));\n    let current = held;\n    if (held.source !== stable) {\n        current = { source: stable, value: initial() };\n        setHeld(current);\n    }\n\n    const update = useCallback((action: SetStateAction<TState>) => {\n        setHeld(previous => ({ source: previous.source, value: typeof action === 'function' ? (action as (state: TState) => TState)(previous.value) : action }));\n    }, []);\n\n    return [current.value, update];\n}\n"],"names":["useResettingState","source","initial","stable","useStructuralValue","held","setHeld","useState","value","current","update","useCallback","action","previous"],"mappings":";;;AAAA;AACA;AAKA;;;;;;;;;;;;AAYC,IACM,SAASA,iBAAAA,CAA0BC,MAAe,EAAEC,OAAqB,EAAA;AAC5E,IAAA,MAAMC,SAASC,kBAAAA,CAAmBH,MAAAA,CAAAA;AAClC,IAAA,MAAM,CAACI,IAAAA,EAAMC,OAAAA,CAAQ,GAAGC,QAAAA,CAAS,KAAO;YAAEN,MAAAA,EAAQE,MAAAA;YAAQK,KAAAA,EAAON,OAAAA;SAAU,CAAA,CAAA;AAC3E,IAAA,IAAIO,OAAAA,GAAUJ,IAAAA;IACd,IAAIA,IAAAA,CAAKJ,MAAM,KAAKE,MAAAA,EAAQ;QACxBM,OAAAA,GAAU;YAAER,MAAAA,EAAQE,MAAAA;YAAQK,KAAAA,EAAON,OAAAA;AAAU,SAAA;QAC7CI,OAAAA,CAAQG,OAAAA,CAAAA;AACZ,IAAA;IAEA,MAAMC,MAAAA,GAASC,YAAY,CAACC,MAAAA,GAAAA;QACxBN,OAAAA,CAAQO,CAAAA,YAAa;AAAEZ,gBAAAA,MAAAA,EAAQY,SAASZ,MAAM;AAAEO,gBAAAA,KAAAA,EAAO,OAAOI,MAAAA,KAAW,UAAA,GAAa,MAACA,CAAqCC,QAAAA,CAASL,KAAK,CAAA,GAAII;aAAO,CAAA,CAAA;AACzJ,IAAA,CAAA,EAAG,EAAE,CAAA;IAEL,OAAO;AAACH,QAAAA,OAAAA,CAAQD,KAAK;AAAEE,QAAAA;AAAO,KAAA;AAClC;;"}

package/editor/PrimeEditor.tsx

@@ -0,0 +1,83 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { booleanProperty, stringProperty } from '../properties';
+import { QuillLoaderContext } from './QuillLoaderContext';
+import { htmlToPlainText } from './htmlToPlainText';
+import { renderSafeNodes } from './renderSafeNodes';
+import { sanitizeHtml } from './sanitizeHtml';
+import { useQuillEditor } from './useQuillEditor';
+
+/**
+ * The `PrimeReact:editor` rich-text control.
+ *
+ * Authored HTML is untrusted data and is never injected as markup. Everywhere it is shown it first goes
+ * through an allowlist (see {@link sanitizeHtml}): into Quill as a Delta, or into the read-only view as React
+ * elements. Where there is no DOM - server rendering, and the first client render so hydration matches - it is
+ * shown as plain text. `element.properties.value` itself is never changed.
+ *
+ * Editing needs Quill, which this package does not import. A host provides it with `QuillLoaderProvider`
+ * (the loader `loadQuill` lives in the `@cratis/scene.primereact/quill` entry point). Without a loader, or if
+ * loading fails, the content stays visible read-only and a status says why; the control never pretends to be
+ * editable.
+ *
+ * `readOnly: true` and `isEnabled: false` both stop editing. Edits are runtime state: `interactions.onChange`
+ * is called when the user edits, but the new HTML is not written back to the document or a binding.
+ */
+export function PrimeEditor({ element, interactions }: RegisteredComponentProps) {
+    const loader = useContext(QuillLoaderContext);
+    const host = useRef<HTMLDivElement>(null);
+    const interactionReference = useRef(interactions);
+    interactionReference.current = interactions;
+    const [mounted, setMounted] = useState(false);
+    const html = stringProperty(element, 'value', '');
+    const readOnly = booleanProperty(element, 'readOnly', false);
+    const editable = !readOnly && element.isEnabled;
+    const ariaLabel = stringProperty(element, 'ariaLabel', 'Rich text editor');
+
+    useEffect(() => setMounted(true), []);
+
+    const editor = useQuillEditor({
+        loader,
+        host,
+        html,
+        showHeader: booleanProperty(element, 'showHeader', true),
+        editable,
+        placeholder: stringProperty(element, 'placeholder'),
+        ariaLabel,
+        onUserChange: () => interactionReference.current?.onChange?.(),
+    });
+
+    const readOnlyView = useMemo(() => {
+        if (!mounted || typeof DOMParser === 'undefined') return htmlToPlainText(html);
+        return renderSafeNodes(sanitizeHtml(html));
+    }, [mounted, html]);
+
+    const status = !editor.ready ? undefined : editable ? `${editor.characters} characters` : readOnly ? 'Read only' : 'Disabled';
+
+    return (
+        <section data-scene-id={element.id} data-scene-component='editor' onClick={interactions?.onClick} onDoubleClick={interactions?.onDoubleClick}>
+            <div ref={host} />
+            {!editor.ready && (
+                <div
+                    key={typeof readOnlyView}
+                    role='textbox'
+                    tabIndex={0}
+                    aria-multiline='true'
+                    aria-readonly='true'
+                    aria-label={ariaLabel}
+                    data-scene-part='read-only-content'
+                    style={typeof readOnlyView === 'string' ? { whiteSpace: 'pre-wrap' } : undefined}>
+                    {readOnlyView}
+                </div>
+            )}
+            {editor.failure !== undefined && <p role='alert' data-scene-state='unavailable'>{`Rich-text editing could not be loaded: ${editor.failure}`}</p>}
+            {!editor.ready && editor.failure === undefined && loader === undefined && (
+                <p role='status' data-scene-state='read-only'>Rich-text editing is not available in this application. The content is shown read-only.</p>
+            )}
+            {status !== undefined && <output aria-live='polite'>{status}</output>}
+        </section>
+    );
+}

package/editor/QuillConstructor.ts

@@ -0,0 +1,8 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { QuillInstance } from './QuillInstance';
+import { QuillOptions } from './QuillOptions';
+
+/** Quill's constructor, as this package calls it. */
+export type QuillConstructor = new (container: HTMLElement, options: QuillOptions) => QuillInstance;

package/editor/QuillEditorOptions.ts

@@ -0,0 +1,29 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { RefObject } from 'react';
+import { QuillLoader } from './QuillLoader';
+
+/** What {@link useQuillEditor} builds an editor from. */
+export interface QuillEditorOptions {
+    /** Loads Quill. Without one no editor is built. */
+    loader: QuillLoader | undefined;
+
+    /** The element the editor is built inside. React must render it with no children. */
+    host: RefObject<HTMLElement | null>;
+
+    /** The authored HTML. A change in it replaces the content; no other change does. */
+    html: string;
+
+    /** Whether the toolbar is shown. It is fixed when Quill is constructed, so a change rebuilds the editor. */
+    showHeader: boolean;
+
+    /** Whether the user can edit: not read only and not disabled. */
+    editable: boolean;
+
+    placeholder: string | undefined;
+    ariaLabel: string;
+
+    /** Called when the user, not the document, changed the content. */
+    onUserChange(): void;
+}

package/editor/QuillEditorState.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** What {@link useQuillEditor} reports about the editor it manages. */
+export interface QuillEditorState {
+    /** Whether the editor is built and showing the content. */
+    ready: boolean;
+
+    /** Why the editor could not be built, once loading failed. */
+    failure: string | undefined;
+
+    /** The number of characters of text, `0` until ready. */
+    characters: number;
+}

package/editor/QuillInstance.ts

@@ -0,0 +1,27 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The part of a Quill editor this package uses.
+ *
+ * It is declared here instead of imported from `quill` so that this package's public types never name a
+ * module the consumer may not have installed.
+ */
+export interface QuillInstance {
+    /** The editable surface. */
+    root: HTMLElement;
+
+    clipboard: {
+        /** Converts HTML to a Delta. Quill drops formats it does not know while doing so. */
+        convert(content: { html?: string; text?: string }): unknown;
+    };
+
+    /** Replaces the content. `'silent'` suppresses the `text-change` event. */
+    setContents(delta: unknown, source?: 'user' | 'api' | 'silent'): unknown;
+
+    enable(enabled?: boolean): void;
+    getText(): string;
+    getModule(name: string): unknown;
+    on(event: 'text-change', handler: (delta: unknown, previous: unknown, source: string) => void): unknown;
+    off(event: 'text-change', handler: (delta: unknown, previous: unknown, source: string) => void): unknown;
+}

package/editor/QuillLoader.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { QuillConstructor } from './QuillConstructor';
+
+/**
+ * Loads Quill when the first editor needs it.
+ *
+ * It resolves to Quill's constructor, or to the module that has it as its default export, so a dynamic
+ * import of the quill package is a loader. The host provides it with `QuillLoaderProvider`; the package
+ * never imports that package itself, so a host that renders no rich text needs no `quill` to build.
+ */
+export type QuillLoader = () => Promise<QuillConstructor | { default: QuillConstructor }>;

package/editor/QuillLoaderContext.ts

@@ -0,0 +1,8 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { createContext } from 'react';
+import { QuillLoader } from './QuillLoader';
+
+/** Without a provider there is no loader, and the editor shows its content read-only. */
+export const QuillLoaderContext = createContext<QuillLoader | undefined>(undefined);

package/editor/QuillLoaderProvider.tsx

@@ -0,0 +1,24 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ReactNode } from 'react';
+import { QuillLoader } from './QuillLoader';
+import { QuillLoaderContext } from './QuillLoaderContext';
+
+export interface QuillLoaderProviderProps {
+    /** Loads Quill. `loadQuill` from `@cratis/scene.primereact/quill` is the ready-made one. */
+    loader: QuillLoader;
+
+    /** The surface whose editors the loader serves. */
+    children: ReactNode;
+}
+
+/**
+ * Makes editable rich text available to the `editor` controls inside it.
+ *
+ * The loader must be a stable reference - define it at module level or memoize it - because the editor
+ * rebuilds when it changes.
+ */
+export function QuillLoaderProvider({ loader, children }: QuillLoaderProviderProps) {
+    return <QuillLoaderContext.Provider value={loader}>{children}</QuillLoaderContext.Provider>;
+}

package/editor/QuillOptions.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** The options this package passes when it constructs Quill. */
+export interface QuillOptions {
+    theme: 'snow';
+    modules: { toolbar: (string | Record<string, unknown>)[][] | false };
+    placeholder?: string;
+    readOnly: boolean;
+}

package/editor/SafeElement.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SafeNode } from './SafeNode';
+
+/** An element of authored HTML that the allowlist kept, with only the attributes the allowlist kept. */
+export interface SafeElement {
+    /** A tag from the allowlist, lower case. */
+    tag: string;
+
+    /** The kept attributes, already validated. */
+    attributes: Record<string, string>;
+
+    children: SafeNode[];
+}

package/editor/SafeNode.ts

@@ -0,0 +1,7 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { SafeElement } from './SafeElement';
+
+/** Authored HTML after the allowlist: text, or an element that is safe to render. */
+export type SafeNode = string | SafeElement;

package/editor/applyHtml.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { QuillInstance } from './QuillInstance';
+import { sanitizeHtml } from './sanitizeHtml';
+import { serializeSafeNodes } from './serializeSafeNodes';
+
+/**
+ * Puts authored HTML into a Quill editor, silently.
+ *
+ * The HTML first goes through the allowlist, and what is left is converted by Quill's clipboard into a Delta
+ * that `setContents` applies. The authored string is never assigned to `innerHTML`, so nothing in it can run;
+ * and because the change is `'silent'` it raises no `text-change`, so loading a document is not reported as
+ * the user editing it.
+ *
+ * @param quill The editor.
+ * @param html The authored HTML.
+ */
+export function applyHtml(quill: QuillInstance, html: string): void {
+    quill.setContents(quill.clipboard.convert({ html: serializeSafeNodes(sanitizeHtml(html)) }), 'silent');
+}

package/editor/characterCount.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { QuillInstance } from './QuillInstance';
+
+/** The number of characters of text in the editor, not counting the newline Quill always ends with. */
+export function characterCount(quill: QuillInstance): number {
+    return Math.max(quill.getText().length - 1, 0);
+}

package/editor/htmlToPlainText.ts

@@ -0,0 +1,74 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Elements dropped together with their content, as `sanitizeHtml` does. */
+const discardedWithContent = new Set(['script', 'style', 'template', 'noscript', 'iframe', 'object', 'embed', 'svg', 'math', 'textarea', 'title', 'head']);
+
+/** Elements after which a line break reads naturally. */
+const breaking = new Set(['p', 'div', 'br', 'hr', 'li', 'tr', 'blockquote', 'pre', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6']);
+
+const namedEntities: Record<string, string> = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' };
+
+/**
+ * Reads authored HTML as plain text, without a DOM.
+ *
+ * This is what server rendering shows, where there is no `DOMParser` to build safe markup with. The result
+ * is only ever rendered as text, which React escapes, so it cannot carry markup however the input is built.
+ * It scans once, left to right: tags are dropped, script, style and similar elements go with their content,
+ * and block elements become line breaks.
+ *
+ * @param html The authored HTML.
+ * @returns The text, with line breaks between blocks.
+ */
+export function htmlToPlainText(html: string): string {
+    const lower = html.toLowerCase();
+    let text = '';
+    let position = 0;
+    while (position < html.length) {
+        const open = html.indexOf('<', position);
+        if (open === -1) {
+            text += html.slice(position);
+            break;
+        }
+
+        text += html.slice(position, open);
+        if (!/[a-z/!?]/i.test(html[open + 1] ?? '')) {
+            text += '<';
+            position = open + 1;
+            continue;
+        }
+
+        if (lower.startsWith('<!--', open)) {
+            const close = html.indexOf('-->', open + 4);
+            position = close === -1 ? html.length : close + 3;
+            continue;
+        }
+
+        const close = html.indexOf('>', open);
+        if (close === -1) {
+            text += html.slice(open);
+            break;
+        }
+
+        const name = /^<\/?([a-z][a-z0-9]*)/.exec(lower.slice(open, close + 1))?.[1];
+        position = close + 1;
+        if (name === undefined) continue;
+        if (lower[open + 1] !== '/' && discardedWithContent.has(name)) {
+            const end = lower.indexOf(`</${name}`, position);
+            const endClose = end === -1 ? -1 : html.indexOf('>', end);
+            position = endClose === -1 ? html.length : endClose + 1;
+        } else if (breaking.has(name) && (lower[open + 1] === '/' || name === 'br' || name === 'hr')) {
+            text += '\n';
+        }
+    }
+
+    return decodeEntities(text).replace(/\n{3,}/g, '\n\n').trim();
+}
+
+function decodeEntities(text: string): string {
+    return text.replace(/&(#x[0-9a-f]{1,6}|#[0-9]{1,7}|[a-z]+);/gi, (match, entity: string) => {
+        if (entity[0] !== '#') return namedEntities[entity.toLowerCase()] ?? match;
+        const code = entity[1].toLowerCase() === 'x' ? parseInt(entity.slice(2), 16) : parseInt(entity.slice(1), 10);
+        return code > 0 && code <= 0x10ffff && !(code >= 0xd800 && code <= 0xdfff) ? String.fromCodePoint(code) : match;
+    });
+}

package/editor/index.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './PrimeEditor';
+export * from './QuillConstructor';
+export * from './QuillInstance';
+export * from './QuillLoader';
+export * from './QuillLoaderProvider';
+export * from './QuillOptions';
+export * from './htmlToPlainText';
+export * from './renderSafeNodes';
+export * from './SafeElement';
+export * from './SafeNode';
+export * from './safeUrls';
+export * from './sanitizeHtml';
+export * from './serializeSafeNodes';

package/editor/renderSafeNodes.tsx

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { createElement, ReactNode } from 'react';
+import { SafeNode } from './SafeNode';
+
+const voidTags = new Set(['br', 'hr', 'img']);
+
+/**
+ * Renders safe nodes as React elements.
+ *
+ * Nothing is ever injected as markup: each node becomes an element created from the allowlisted tag name with
+ * the validated attributes, and text goes through React's escaping. Links are made `noopener noreferrer` and
+ * open in the same context.
+ *
+ * @param nodes The nodes `sanitizeHtml` returned.
+ */
+export function renderSafeNodes(nodes: SafeNode[]): ReactNode[] {
+    return nodes.map((node, index) => {
+        if (typeof node === 'string') return node;
+        const { class: className, ...attributes } = node.attributes;
+        const properties: Record<string, string | undefined> = { key: String(index), className, ...attributes };
+        if (node.tag === 'a') properties.rel = 'noopener noreferrer';
+        return createElement(node.tag, properties, ...(voidTags.has(node.tag) ? [] : renderSafeNodes(node.children)));
+    });
+}

package/editor/safeUrls.ts

@@ -0,0 +1,43 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Schemes a link may use. Anything else, `javascript:` and `data:` above all, is dropped. */
+const linkProtocols = new Set(['http:', 'https:', 'mailto:', 'tel:']);
+
+/** The only images that are kept: small raster data URLs. A remote image is a request made just by rendering. */
+const rasterDataUrl = /^data:image\/(png|jpeg|gif|webp);base64,[a-z0-9+/]+={0,2}$/i;
+
+/** Resolved against, to learn which scheme a browser would act on. It is never sent to. */
+const placeholderOrigin = 'https://editor.invalid';
+
+/**
+ * Returns a link target a browser may follow, or `undefined`.
+ *
+ * Browsers strip tabs and newlines from inside a scheme, so the address is judged by what `URL` resolves it to
+ * and not by its text: `java\tscript:` is a `javascript:` link. Relative links and fragments resolve against
+ * an http origin and are kept.
+ *
+ * @param value The authored `href`.
+ */
+export function safeLinkUrl(value: string): string | undefined {
+    const trimmed = value.trim();
+    if (trimmed === '') return undefined;
+    try {
+        return linkProtocols.has(new URL(trimmed, placeholderOrigin).protocol) ? trimmed : undefined;
+    } catch {
+        return undefined;
+    }
+}
+
+/**
+ * Returns an image source that may be rendered, or `undefined`.
+ *
+ * Only base64 PNG, JPEG, GIF and WebP data URLs pass. SVG is refused because it can carry script, and an
+ * `http(s)` image is refused because rendering it would contact a server the author named.
+ *
+ * @param value The authored `src`.
+ */
+export function safeImageUrl(value: string): string | undefined {
+    const trimmed = value.trim();
+    return rasterDataUrl.test(trimmed) ? trimmed : undefined;
+}

package/editor/sanitizeHtml.ts

@@ -0,0 +1,94 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SafeElement } from './SafeElement';
+import { SafeNode } from './SafeNode';
+import { safeImageUrl, safeLinkUrl } from './safeUrls';
+
+/** Elements that are kept. Every other element is unwrapped: its children stay, the element does not. */
+const keptTags = new Set([
+    'p', 'div', 'span', 'br', 'hr', 'strong', 'b', 'em', 'i', 'u', 's', 'strike', 'del', 'sub', 'sup', 'code', 'pre', 'blockquote',
+    'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'ul', 'ol', 'li', 'a', 'img',
+]);
+
+/** Elements whose content is never text to show - script, style, embedded documents and form controls. */
+const discardedWithContent = new Set([
+    'script', 'style', 'template', 'noscript', 'iframe', 'frame', 'frameset', 'object', 'embed', 'applet', 'svg', 'math',
+    'audio', 'video', 'canvas', 'textarea', 'select', 'option', 'button', 'input', 'form', 'head', 'title', 'meta', 'link', 'base',
+]);
+
+/** Quill's own formatting classes. They name CSS rules, so a fixed vocabulary is safe and anything else is not kept. */
+const formattingClass = /^ql-(align-(center|right|justify)|indent-[1-8]|size-(small|large|huge)|font-(serif|monospace)|direction-rtl)$/;
+
+const listKinds = new Set(['bullet', 'ordered', 'checked', 'unchecked']);
+
+/** Deeper than any real document nests. Anything below is flattened to its text. */
+const maximumDepth = 64;
+
+/**
+ * Reduces authored HTML to the part that is safe to render.
+ *
+ * It parses with `DOMParser`, which builds an inert document: nothing in it loads, runs or paints while it is
+ * walked. The walk then keeps only elements from an allowlist and, on those, only the attributes listed
+ * here - a validated `href` or image `src`, Quill's formatting classes and list kind. Event handlers,
+ * `style`, `srcdoc`, unknown elements' attributes and every URL that is not allowed are dropped, and script,
+ * style, SVG, frames and form controls are removed together with their content.
+ *
+ * The result is plain data. Render it with `renderSafeNodes` or serialize it with `serializeSafeNodes`; the
+ * authored string itself is never put into the document.
+ *
+ * @param html The authored HTML.
+ * @returns The safe nodes.
+ * @throws When there is no `DOMParser`. Use `htmlToPlainText` where there is no DOM.
+ */
+export function sanitizeHtml(html: string): SafeNode[] {
+    if (typeof DOMParser === 'undefined') throw new Error('Sanitizing HTML needs a DOM. Use htmlToPlainText where there is none.');
+    return sanitizeChildren(new DOMParser().parseFromString(html, 'text/html').body, 0);
+}
+
+function sanitizeChildren(parent: Node, depth: number): SafeNode[] {
+    const nodes: SafeNode[] = [];
+    for (const child of Array.from(parent.childNodes)) {
+        if (child.nodeType === Node.TEXT_NODE) {
+            if (child.textContent !== null && child.textContent !== '') nodes.push(child.textContent);
+        } else if (child.nodeType === Node.ELEMENT_NODE) {
+            nodes.push(...sanitizeElement(child as Element, depth));
+        }
+    }
+    return nodes;
+}
+
+function sanitizeElement(element: Element, depth: number): SafeNode[] {
+    const tag = element.tagName.toLowerCase();
+    if (discardedWithContent.has(tag)) return [];
+    if (depth >= maximumDepth) return [element.textContent ?? ''];
+
+    const children = sanitizeChildren(element, depth + 1);
+    if (!keptTags.has(tag)) return children;
+
+    const attributes = keptAttributes(tag, element);
+    if (tag === 'img' && attributes.src === undefined) return [];
+    if (tag === 'a' && attributes.href === undefined) return children;
+    return [{ tag, attributes, children } satisfies SafeElement];
+}
+
+function keptAttributes(tag: string, element: Element): Record<string, string> {
+    const attributes: Record<string, string> = {};
+
+    const href = tag === 'a' ? safeLinkUrl(element.getAttribute('href') ?? '') : undefined;
+    if (href !== undefined) attributes.href = href;
+
+    const source = tag === 'img' ? safeImageUrl(element.getAttribute('src') ?? '') : undefined;
+    if (source !== undefined) {
+        attributes.src = source;
+        attributes.alt = element.getAttribute('alt') ?? '';
+    }
+
+    const classes = (element.getAttribute('class') ?? '').split(/\s+/).filter(name => formattingClass.test(name));
+    if (classes.length > 0) attributes.class = classes.join(' ');
+
+    const listKind = element.getAttribute('data-list');
+    if (tag === 'li' && listKind !== null && listKinds.has(listKind)) attributes['data-list'] = listKind;
+
+    return attributes;
+}

package/editor/serializeSafeNodes.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SafeNode } from './SafeNode';
+
+const voidTags = new Set(['br', 'hr', 'img']);
+
+const escapes: Record<string, string> = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' };
+
+const escape = (text: string) => text.replace(/[&<>"]/g, character => escapes[character]);
+
+/**
+ * Writes safe nodes back out as an HTML string, for an editor that reads HTML.
+ *
+ * Text and attribute values are escaped, and only tags and attributes the allowlist produced are written, so
+ * the string can contain nothing the allowlist did not already accept.
+ *
+ * @param nodes The nodes `sanitizeHtml` returned.
+ */
+export function serializeSafeNodes(nodes: SafeNode[]): string {
+    return nodes.map(node => {
+        if (typeof node === 'string') return escape(node);
+        const attributes = Object.entries(node.attributes).map(([name, value]) => ` ${name}="${escape(value)}"`).join('');
+        return voidTags.has(node.tag) ? `<${node.tag}${attributes}>` : `<${node.tag}${attributes}>${serializeSafeNodes(node.children)}</${node.tag}>`;
+    }).join('');
+}

package/editor/toolbarLayout.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** The formats the toolbar offers. Content in other formats is still shown, but cannot be produced here. */
+export const toolbarLayout: (string | Record<string, unknown>)[][] = [
+    ['bold', 'italic', 'underline'],
+    [{ header: [1, 2, 3, false] }],
+    [{ list: 'ordered' }, { list: 'bullet' }],
+    ['link'],
+];