@limetech/lime-elements 40.5.4 → 40.6.0

package/dist/collection/components/markdown/markdown-exporter.js

@@ -0,0 +1,186 @@
+import { fromDom } from "hast-util-from-dom";
+import { defaultHandlers } from "hast-util-to-mdast";
+import { defaultHandlers as defaultMarkdownHandlers, } from "mdast-util-to-markdown";
+import rehypeRemark from "rehype-remark";
+import remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import remarkStringify from "remark-stringify";
+import { unified } from "unified";
+/**
+ * Convert rendered markdown content back to markdown, replacing each
+ * whitelisted custom element with the markdown it describes itself as.
+ *
+ * Elements that do not implement {@link MarkdownDescribable} are
+ * converted like any unknown element: their light DOM children are kept,
+ * and an element without children disappears.
+ *
+ * @param container - The element holding the rendered content.
+ * @param whitelist - The custom elements allowed in the content.
+ * @returns The content as GitHub Flavored Markdown.
+ */
+export async function exportMarkdown(container, whitelist) {
+    const tagNames = new Set(whitelist
+        .map((definition) => definition.tagName)
+        .filter(isDescribableTag));
+    // The tree is captured before any description is awaited, so that
+    // content rendered in the meantime cannot end up in the export without
+    // its description.
+    const describableElements = new Map();
+    const tree = fromDom(container, {
+        afterTransform: (domNode, hastNode) => {
+            if (hastNode.type !== 'element') {
+                return;
+            }
+            restoreDeferredImage(hastNode);
+            hideFootnoteBackReference(hastNode);
+            if (domNode instanceof Element && tagNames.has(domNode.localName)) {
+                describableElements.set(hastNode, domNode);
+            }
+        },
+    });
+    await describeElements(describableElements);
+    const handlers = {
+        sup: handleSup,
+        section: handleSection,
+    };
+    for (const tagName of tagNames) {
+        handlers[tagName] = handleCustomElement;
+    }
+    const processor = unified()
+        .use(rehypeRemark, { handlers })
+        .use(remarkGfm)
+        .use(remarkStringify, {
+        bullet: '-',
+        handlers: { break: handleBreak },
+    });
+    const mdast = await processor.run({
+        type: 'root',
+        children: tree.children,
+    });
+    return processor.stringify(mdast).trimEnd();
+}
+/**
+ * The description is kept on the node itself, since `rehype-remark`
+ * works on a clone of the tree. It also becomes the node's only child, so
+ * that whitespace minification treats the element as content and keeps
+ * the spaces around it. An element whose description fails is converted
+ * as if it did not describe itself.
+ * @param elements
+ */
+async function describeElements(elements) {
+    await Promise.all([...elements].map(async ([node, element]) => {
+        try {
+            const description = await element.toMarkdown();
+            node.properties.dataMarkdownDescription = description;
+            node.children = [{ type: 'text', value: description }];
+        }
+        catch (error) {
+            console.error('Failed to describe element as markdown', error);
+        }
+    }));
+}
+const handleCustomElement = (state, node) => {
+    const description = node.properties.dataMarkdownDescription;
+    if (typeof description === 'string') {
+        return parseMarkdown(description);
+    }
+    return state.all(node);
+};
+/**
+ * Write hard line breaks as two trailing spaces rather than a backslash,
+ * since the export is also read as plain text, where the spaces are
+ * invisible.
+ * @param args
+ */
+const handleBreak = (...args) => {
+    const markdown = defaultMarkdownHandlers.break(...args);
+    return markdown === '\\\n' ? '  \n' : markdown;
+};
+/**
+ * Parse a description into mdast nodes. A description that is a single
+ * paragraph gives phrasing content, so that an element inside a
+ * paragraph or list item stays inline.
+ * @param markdown
+ */
+function parseMarkdown(markdown) {
+    const { children } = unified()
+        .use(remarkParse)
+        .use(remarkGfm)
+        .parse(markdown);
+    if (children.length === 1 && children[0].type === 'paragraph') {
+        return children[0].children;
+    }
+    return children;
+}
+/**
+ * An image that has not been scrolled into view yet keeps its URL in
+ * `data-src`, until the lazy loading moves it to `src`.
+ * @param node
+ */
+function restoreDeferredImage(node) {
+    const deferredSrc = node.properties.dataSrc;
+    if (node.tagName === 'img' && !node.properties.src && deferredSrc) {
+        node.properties.src = deferredSrc;
+    }
+}
+/**
+ * The links from a footnote back to its references are recreated when the
+ * markdown is rendered again.
+ * @param node
+ */
+function hideFootnoteBackReference(node) {
+    if (node.tagName === 'a' &&
+        node.properties.dataFootnoteBackref !== undefined) {
+        node.properties.dataMdast = 'ignore';
+    }
+}
+/**
+ * Footnotes are labelled with their rendered numbers. The ids only keep an
+ * encoded, lowercased form of the original labels, which cannot be turned
+ * back into them reliably. A reference shows its footnote's number, and
+ * the definitions are listed in the same order.
+ * @param state
+ * @param node
+ */
+const handleSup = (state, node) => {
+    const link = node.children.find((child) => isElement(child, 'a') &&
+        child.properties.dataFootnoteRef !== undefined);
+    if (!link) {
+        return defaultHandlers.sup(state, node);
+    }
+    const identifier = link.children
+        .map((child) => (child.type === 'text' ? child.value : ''))
+        .join('');
+    return { type: 'footnoteReference', identifier, label: identifier };
+};
+const handleSection = (state, node) => {
+    if (node.properties.dataFootnotes === undefined) {
+        return defaultHandlers.section(state, node);
+    }
+    const list = node.children.find((child) => isElement(child, 'ol'));
+    const items = list === null || list === void 0 ? void 0 : list.children.filter((child) => isElement(child, 'li'));
+    return (items !== null && items !== void 0 ? items : []).map((item, index) => {
+        const identifier = String(index + 1);
+        return {
+            type: 'footnoteDefinition',
+            identifier,
+            label: identifier,
+            children: state.toFlow(state.all(item)),
+        };
+    });
+};
+function isElement(node, tagName) {
+    return node.type === 'element' && node.tagName === tagName;
+}
+/**
+ * Whether the custom element registered for the tag implements
+ * {@link MarkdownDescribable}. Stencil defines a component's methods on
+ * the element's prototype when the tag is registered, before the
+ * component itself has loaded.
+ * @param tagName
+ */
+function isDescribableTag(tagName) {
+    var _a;
+    const prototype = (_a = customElements.get(tagName)) === null || _a === void 0 ? void 0 : _a.prototype;
+    return typeof (prototype === null || prototype === void 0 ? void 0 : prototype.toMarkdown) === 'function';
+}

package/dist/collection/components/markdown/markdown-parser.js

@@ -2,6 +2,7 @@ import { unified } from "unified";
 import remarkParse from "remark-parse";
 import remarkRehype from "remark-rehype";
 import remarkGfm from "remark-gfm";
+import remarkBreaks from "remark-breaks";
 import rehypeParse from "rehype-parse";
 import rehypeSanitize, { defaultSchema } from "rehype-sanitize";
 import rehypeStringify from "rehype-stringify";
@@ -27,12 +28,10 @@ import { createRemoveEmptyParagraphsPlugin } from "./remove-empty-paragraphs-plu
  */
 export async function markdownToHTML(text, options) {
     var _a;
-    if (options === null || options === void 0 ? void 0 : options.forceHardLineBreaks) {
-        text = text.replaceAll(/(?<!\\)([\n\r])/g, '  $1');
-    }
     const file = await unified()
         .use(remarkParse)
         .use(remarkGfm)
+        .use((options === null || options === void 0 ? void 0 : options.forceHardLineBreaks) ? [remarkBreaks] : [])
         .use(remarkRehype, { allowDangerousHtml: true })
         .use(rehypeRaw)
         .use(createLinksPlugin())

package/dist/collection/components/markdown/markdown.js

@@ -39,6 +39,7 @@ import { adaptColorContrast } from "../../util/adapt-color-contrast";
  * @exampleComponent limel-example-markdown-custom-component-with-json-props
  * @exampleComponent limel-example-markdown-remove-empty-paragraphs
  * @exampleComponent limel-example-markdown-adapt-color-contrast
+ * @exampleComponent limel-example-markdown-to-markdown
  * @exampleComponent limel-example-markdown-composite
  */
 export class Markdown {
@@ -97,7 +98,31 @@ export class Markdown {
         this.adaptColorContrast = false;
         this.imageIntersectionObserver = null;
     }
-    async textChanged() {
+    /**
+     * Returns the content as markdown, with every whitelisted custom
+     * element replaced by the markdown it describes itself as.
+     *
+     * Use this to hand the content to a target that cannot render custom
+     * elements, such as the clipboard. An element describes itself by
+     * implementing `MarkdownDescribable`; elements that do not keep
+     * their child content, or are removed if they have none.
+     *
+     * The markdown is generated from the rendered content, so it may be
+     * formatted differently from `value`.
+     *
+     * @alpha
+     * @returns The content as markdown.
+     */
+    async toMarkdown() {
+        await this.rendering;
+        const { exportMarkdown } = await import('./markdown-exporter');
+        return exportMarkdown(this.rootElement, this.cachedCombinedWhitelist);
+    }
+    textChanged() {
+        this.rendering = this.renderMarkdown();
+        return this.rendering;
+    }
+    async renderMarkdown() {
         try {
             this.cleanupImageIntersectionObserver();
             // The whitelist merge and default import live here (not in
@@ -145,7 +170,7 @@ export class Markdown {
         this.cleanupImageIntersectionObserver();
     }
     render() {
-        return (h(Host, { key: 'd10bcceddc2844e43817d406965155f282e21549' }, h("div", { key: '4253c517b72dbd21081e5fe26aaa0e75a91cb7db', id: "markdown", ref: (el) => (this.rootElement = el) })));
+        return (h(Host, { key: '86a21b8636af14891a657e136a9dceae4acb3b23' }, h("div", { key: '5f53c998000e2f197953232a63b2deb8ee1878bf', id: "markdown", ref: (el) => (this.rootElement = el) })));
     }
     setupImageIntersectionObserver() {
         if (this.lazyLoadImages) {
@@ -282,6 +307,33 @@ export class Markdown {
             }
         };
     }
+    static get methods() {
+        return {
+            "toMarkdown": {
+                "complexType": {
+                    "signature": "() => Promise<string>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<string>"
+                },
+                "docs": {
+                    "text": "Returns the content as markdown, with every whitelisted custom\nelement replaced by the markdown it describes itself as.\n\nUse this to hand the content to a target that cannot render custom\nelements, such as the clipboard. An element describes itself by\nimplementing `MarkdownDescribable`; elements that do not keep\ntheir child content, or are removed if they have none.\n\nThe markdown is generated from the rendered content, so it may be\nformatted differently from `value`.",
+                    "tags": [{
+                            "name": "alpha",
+                            "text": undefined
+                        }, {
+                            "name": "returns",
+                            "text": "The content as markdown."
+                        }]
+                }
+            }
+        };
+    }
     static get watchers() {
         return [{
                 "propName": "value",