@vertigis/react-ui 9.2.2 → 9.3.0

package/Markdown/Markdown.d.ts

@@ -0,0 +1,39 @@
+import { FC } from "react";
+import { BoxProps } from "../Box";
+/**
+ * Properties for the `Markdown` component.
+ */
+export interface MarkdownProps extends BoxProps {
+    /**
+     * The markdown text to render.
+     */
+    markdown: string;
+    /**
+     * A caller-supplied sanitization function to ensure that the resulting HTML
+     * is safe to insert into the DOM. Required.
+     */
+    sanitize: (unsafeHtml: string) => string;
+    /**
+     * If specified, produces HTML that is valid for contexts where only inline
+     * content is allowed (e.g. inside `<h1>`>` or `<span>` tags). HTML tags for
+     * block-level elements will be removed, but any text content will be
+     * preserved.
+     */
+    inline?: boolean;
+    /**
+     * If true, any HTML in the markdown will be escaped rather than passed
+     * through directly to the output as normal (since Markdown is a superset of
+     * HTML). This is useful in situations where you wish to only support pure
+     * Markdown syntax without also supporting HTML syntax. The default is
+     * `false`.
+     *
+     * IMPORTANT: The resulting HTML still needs to be sanitized whether or not
+     * this option is set.
+     */
+    escapeHtml?: boolean;
+}
+/**
+ * A component that renders markdown as HTML.
+ */
+declare const Markdown: FC<MarkdownProps>;
+export default Markdown;

package/Markdown/Markdown.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import clsx from "clsx";
+import Box from "../Box";
+import { markdownToHtml } from "../utils/markdown";
+/**
+ * A component that renders markdown as HTML.
+ */
+const Markdown = ({ markdown, inline, escapeHtml, sanitize, className, ...otherProps }) => {
+    return (_jsx(Box, Object.assign({ component: inline ? "span" : "div", className: clsx("GcxMarkdown", className), dangerouslySetInnerHTML: {
+            __html: sanitize(markdownToHtml(markdown, { inline, escapeHtml })),
+        } }, otherProps), void 0));
+};
+export default Markdown;

package/Markdown/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./Markdown";
+export { default } from "./Markdown";

package/Markdown/index.js

@@ -0,0 +1,2 @@
+export * from "./Markdown";
+export { default } from "./Markdown";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vertigis/react-ui",
-    "version": "9.2.2",
+    "version": "9.3.0",
     "description": "Utilities and React components used in VertiGIS applications.",
     "keywords": [
         "vertigis",
@@ -22,6 +22,7 @@
         "@mui/material": "5.2.8",
         "clsx": "^1.1.1",
         "lodash": "^4.17.21",
+        "marked": "^4.0.12",
         "tslib": "^2.1.0"
     },
     "devDependencies": {
@@ -29,6 +30,7 @@
         "@testing-library/react": "^12.1.2",
         "@testing-library/user-event": "^13.5.0",
         "@types/lodash": "^4.14.168",
+        "@types/marked": "^4.0.2",
         "@types/react": "^17.0.34",
         "@types/react-dom": "^17.0.11",
         "react": "^17.0.2",

package/utils/markdown.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Options for the markdownToHtml() function.
+ */
+export interface MarkdownToHtmlOptions {
+    /**
+     * If specified, produces HTML that is valid to place within an HTML element
+     * that only supports inline content (called "phrasing content" in the HTML5
+     * spec). Example elements that only support phrasing content are <span> and
+     * <h2>. In this mode, any block-level elements resulting from the Markdown
+     * conversion will be stripped. The default is `false`.
+     */
+    inline?: boolean;
+    /**
+     * If true, any HTML in the markdown will be escaped rather than passed
+     * through directly to the output (since Markdown is a superset of HTML).
+     * This is useful in situations where you wish to only support pure Markdown
+     * syntax without also supporting HTML syntax. The default is `false`.
+     *
+     * IMPORTANT: The resulting HTML still needs to be sanitized whether or not
+     * this option is set.
+     */
+    escapeHtml?: boolean;
+}
+/**
+ * Converts markdown text into HTML.
+ *
+ * NOTE: The resulting HTML is NOT sanitized by this function. It is the
+ * caller's responsibility to sanitize the resulting HTML prior to inserting it
+ * into the DOM. You must do this even if `escapeHtml` is set to true.
+ *
+ * @param markdown The markdown text to convert.
+ * @param options Options that affect how the text is converted.
+ */
+export declare function markdownToHtml(markdown: string | undefined, options?: MarkdownToHtmlOptions): string;

package/utils/markdown.js

@@ -0,0 +1,44 @@
+import escapeHtml from "lodash/escape";
+import { marked } from "marked";
+/**
+ * A custom marked renderer that escapes HTML in the original markdown.
+ */
+class EscapeHtmlRenderer extends marked.Renderer {
+    html(html) {
+        return escapeHtml(html);
+    }
+}
+EscapeHtmlRenderer.instance = new EscapeHtmlRenderer();
+/**
+ * Converts markdown text into HTML.
+ *
+ * NOTE: The resulting HTML is NOT sanitized by this function. It is the
+ * caller's responsibility to sanitize the resulting HTML prior to inserting it
+ * into the DOM. You must do this even if `escapeHtml` is set to true.
+ *
+ * @param markdown The markdown text to convert.
+ * @param options Options that affect how the text is converted.
+ */
+export function markdownToHtml(markdown, options) {
+    if (!markdown) {
+        return "";
+    }
+    const { inline, escapeHtml } = { inline: false, escapeHtml: false, ...options };
+    const markedOptions = {
+        ...(escapeHtml && {
+            renderer: EscapeHtmlRenderer.instance,
+        }),
+    };
+    const html = marked(markdown, markedOptions);
+    return inline ? stripBlockElements(html) : html;
+}
+/**
+ * Strips all HTML elements that are not suitable for placing within an inline
+ * HTML element.
+ *
+ * @param html The HTML to process.
+ */
+function stripBlockElements(html) {
+    // Derived from here: https://html.spec.whatwg.org/multipage/dom.html#phrasing-content
+    return html.replace(/(?:<(\/?))(?!(?:\/|a|abbr|area|audio|b|bdi|bdo|br|button|canvas|cite|code|data|datalist|del|dfn|em|embed|i|iframe|img|input|ins|kbd|label|link|map|mark|math|meta|meter|noscript|object|output|picture|progress|q|ruby|s|samp|script|select|slot|small|span|strong|sub|sup|svg|template|textarea|time|u|var|video|wbr)\b)[^>]*>/gi, (match, s1) => (s1 === "/" ? " " : ""));
+}