@xoong/richtext 0.0.39 → 0.0.42

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "@xoong/richtext",
-  "version": "0.0.39",
+  "version": "0.0.42",
   "description": "A small rich text editor for xoong forms: contenteditable, no dependencies besides @xoong/core, sanitised HTML in and out. Toolbar, headings, bold, italic, lists, quote, links (http, https, mailto, tel only), media hook.",
   "type": "module",
   "main": "src/index.js",
   "exports": {
     ".": {
+      "types": "./src/index.d.ts",
       "default": "./src/index.js"
     },
-    "./sanitize": "./src/sanitize.js",
+    "./sanitize": {
+      "types": "./src/sanitize.d.ts",
+      "default": "./src/sanitize.js"
+    },
     "./richtext.css": "./src/richtext.css"
   },
   "sideEffects": true,
@@ -32,9 +36,9 @@
   "bugs": {
     "url": "https://github.com/fpt-duongtx/xoong/issues"
   },
-  "homepage": "https://github.com/fpt-duongtx/xoong#readme",
+  "homepage": "https://fpt-duongtx.github.io/xoong/",
   "dependencies": {
-    "@xoong/core": "0.0.39"
+    "@xoong/core": "0.0.42"
   },
   "publishConfig": {
     "access": "public"

package/src/index.d.ts

@@ -0,0 +1,61 @@
+// Types for @xoong/richtext. Importing the package registers <xo-richtext>; these types describe the element, its tag, its events and the sanitiser.
+// To add an element or event: an interface, a line in `XoRichtextTagMap` / `XoRichtextEventMap`.
+import type { XoControl } from '@xoong/core';
+
+export { sanitizeHtml, isSafeLink, isSafeImage, textOf } from './sanitize.js';
+
+/** What `detail.insert` of `xo-pick-media` takes: a URL, or `{ src, alt }` (a string second argument is the alt text for a URL). */
+export type XoRichtextInsert = (media: { src: string; alt?: string } | string, alt?: string) => void;
+
+/** `<xo-richtext>`: a small rich text editor and a form control. Its value is sanitised HTML (p, h2, h3, strong, em, u, ul, ol, li, blockquote, br, a, img). */
+export interface XoRichtextElement extends XoControl {
+  value: string;
+  label: string;
+  placeholder: string;
+  /** Space separated tools, in order: `undo redo style bold italic underline h2 ul ol quote link image`. `image` shows only with `media`. */
+  tools: string;
+  /** `full` or `compact` forces a toolbar size; by default the editor's own width decides. */
+  toolbar: string;
+  /** Shows the image tool, which fires `xo-pick-media`. */
+  media: boolean;
+  /** Most text characters allowed (0 is no limit). */
+  maxlength: number;
+  /** Whether the editor is open in its dialog. */
+  readonly expanded: boolean;
+  /** Open the same editor in a large dialog. Fires `xo-richtext-expand`. */
+  expand(): void;
+  /** Close the dialog (what Done and Escape do). Fires `xo-richtext-done`. */
+  collapse(): void;
+  /** Insert an image (http, https or a relative URL) at the caret, or at the range `at`. Returns false when it was refused (read-only, disabled, unsafe URL). */
+  insertImage(src: string, alt?: string, at?: Range | null): boolean;
+}
+
+/** The class behind `<xo-richtext>` (`customElements.get('xo-richtext')`). */
+export interface XoRichtextConstructor {
+  new (): XoRichtextElement;
+  /** A typed address made into a link target: `a@b.test` becomes `mailto:`, `example.com` becomes `https://`. */
+  linkTarget(raw: string): string;
+}
+
+/** Every element of this package by tag name. */
+export interface XoRichtextTagMap {
+  'xo-richtext': XoRichtextElement;
+}
+
+/** The events that carry data, by name. */
+export interface XoRichtextEventMap {
+  /**
+   * The image tool was used. Open your media library in a listener, call `preventDefault()`, and call `detail.insert` when the person has chosen
+   * (now or later). Without `preventDefault()` nothing is inserted.
+   */
+  'xo-pick-media': CustomEvent<{ insert: XoRichtextInsert }>;
+  'xo-richtext-expand': CustomEvent<null>;
+  'xo-richtext-done': CustomEvent<null>;
+}
+
+declare global {
+  interface HTMLElementTagNameMap extends XoRichtextTagMap {}
+  interface HTMLElementEventMap extends XoRichtextEventMap {}
+  // The events bubble, so a listener on the document is typed too.
+  interface DocumentEventMap extends XoRichtextEventMap {}
+}

package/src/sanitize.d.ts

@@ -0,0 +1,16 @@
+// Types for @xoong/richtext/sanitize: the allow-list sanitiser behind <xo-richtext>. It needs a DOM (browser, happy-dom).
+
+/** A link target the editor allows: http, https, mailto or tel. */
+export function isSafeLink(url: string): boolean;
+
+/** An image source the editor allows: http, https, or a URL without a scheme (relative or root-relative). */
+export function isSafeImage(url: string): boolean;
+
+/**
+ * Sanitise HTML to the editor's subset: p, h2, h3, strong, em, u, ul, ol, li, blockquote, br, a (safe links only), img (safe sources only).
+ * `images: false` removes `<img>`.
+ */
+export function sanitizeHtml(html: string, options?: { images?: boolean }): string;
+
+/** The text of sanitised or raw HTML, for "is it empty" checks and length limits. */
+export function textOf(html: string): string;