feat(text-editor): add removeEmptyParagraphs prop

To enable consumer to keep or remove empty paragraphs
from their HTML `value` input, before rendering the content.

Author: Kiarokh

etc/lime-elements.api.md

@@ -560,6 +560,7 @@ export namespace Components {
     }
     export interface LimelMarkdown {
         "lazyLoadImages": boolean;
+        "removeEmptyParagraphs": boolean;
         "value": string;
         // @alpha
         "whitelist"?: CustomElementDefinition[];
@@ -1752,6 +1753,7 @@ export namespace JSX {
     }
     export interface LimelMarkdown {
         "lazyLoadImages"?: boolean;
+        "removeEmptyParagraphs"?: boolean;
         "value"?: string;
         // @alpha
         "whitelist"?: CustomElementDefinition[];

src/components/markdown/examples/markdown-remove-empty-paragraphs.scss

@@ -0,0 +1,10 @@
+:host(limel-example-markdown-remove-empty-paragraphs) {
+    display: grid;
+    gap: 1rem;
+    grid-template-columns: repeat(auto-fit, minmax(10rem, 1fr));
+}
+
+limel-markdown {
+    display: block;
+    padding: 0.5rem 1rem;
+}

src/components/markdown/examples/markdown-remove-empty-paragraphs.tsx

@@ -0,0 +1,73 @@
+import { Component, h, Host } from '@stencil/core';
+
+const markdownWithEmptyParagraphs = `
+<p>In some use cases, empty paragraphs may be desired to keep certain spacing
+in the content, while in other cases they may be unwanted and just add
+unnecessary vertical space.</p>
+<p></p>
+<p><p></p></p>
+<p>Having an empty paragraph like the above, or like the one below this paragraph</p>
+<p>&nbsp;</p>
+<p>can easily happen when the <code>value</code> is simply some HTML output
+that comes for instance from an email.</p>
+<p class="something"><br></p>
+<p>Many email editors do not have standard typographic margins between paragraphs,
+which force users to manually add empty spaces between their lines,
+by pressing the <kbd>Enter</kbd> key multiple times, while typing an email.</p>
+<p><span style="font-size:10.5pt; color:#333333">&nbsp;</span></p>
+<p><span></span></p>
+<p> </p>
+<p>Rendering all the empty paragraphs that you see in this example would just add lots
+of vertical scrolling to large content.</p>
+`;
+
+/**
+ * Removing empty paragraphs
+ *
+ * Sometimes, when a `value` in HTML format is imported from an external source, it
+ * may contain undesired data. This could be for instance malicious scripts,
+ * or styles that may be used to visually hide unwanted content from the reader.
+ *
+ * This component does its best to sanitize the input HTML, and clean it up
+ * before rendering the content.
+ *
+ * However, one of the things that the component cannot fully decide by its own is
+ * rendering empty paragraphs. Empty paragraphs are paragraphs that do not contain
+ * any meaningful content (text, images, etc.), or only contain whitespace
+ * (`<br />` or `&nbsp;`).
+ *
+ * By setting the `removeEmptyParagraphs` property to `false`, all empty paragraphs
+ * will be preserved before rendering the content.
+ */
+@Component({
+    tag: 'limel-example-markdown-remove-empty-paragraphs',
+    shadow: true,
+    styleUrl: 'markdown-remove-empty-paragraphs.scss',
+})
+export class MarkdownRemoveEmptyParagraphsExample {
+    public render() {
+        return (
+            <Host>
+                <section>
+                    <limel-header
+                        icon="multiline_text"
+                        heading="Default rendering"
+                        subheading="Empty paragraphs removed"
+                    />
+                    <limel-markdown value={markdownWithEmptyParagraphs} />
+                </section>
+                <section>
+                    <limel-header
+                        icon="space_after_paragraph"
+                        heading="Empty paragraphs preserved"
+                        subheading="`removeEmptyParagraphs={false}`"
+                    />
+                    <limel-markdown
+                        value={markdownWithEmptyParagraphs}
+                        removeEmptyParagraphs={false}
+                    />
+                </section>
+            </Host>
+        );
+    }
+}

src/components/markdown/markdown-parser.ts

@@ -13,6 +13,7 @@ import { Schema } from 'rehype-sanitize/lib';
 import { createLazyLoadImagesPlugin } from './image-markdown-plugin';
 import { CustomElementDefinition } from '../../global/shared-types/custom-element.types';
 import { createLinksPlugin } from './link-markdown-plugin';
+import { createRemoveEmptyParagraphsPlugin } from './remove-empty-paragraphs-plugin';
 
 /**
  * Takes a string as input and returns a new string
@@ -52,6 +53,7 @@ export async function markdownToHTML(
                 visit(tree, 'element', sanitizeStyle);
             };
         })
+        .use(createRemoveEmptyParagraphsPlugin(options?.removeEmptyParagraphs))
         .use(createLazyLoadImagesPlugin(options?.lazyLoadImages))
         .use(rehypeStringify)
         .process(text);
@@ -129,4 +131,5 @@ export interface MarkdownToHTMLOptions {
     forceHardLineBreaks?: boolean;
     whitelist?: CustomElementDefinition[];
     lazyLoadImages?: boolean;
+    removeEmptyParagraphs?: boolean;
 }

src/components/markdown/markdown.tsx

@@ -20,8 +20,9 @@ import { ImageIntersectionObserver } from './image-intersection-observer';
  * @exampleComponent limel-example-markdown-keys
  * @exampleComponent limel-example-markdown-blockquotes
  * @exampleComponent limel-example-markdown-horizontal-rule
- * @exampleComponent limel-example-markdown-composite
  * @exampleComponent limel-example-markdown-custom-component
+ * @exampleComponent limel-example-markdown-remove-empty-paragraphs
+ * @exampleComponent limel-example-markdown-composite
  */
 @Component({
     tag: 'limel-markdown',
@@ -55,6 +56,15 @@ export class Markdown {
     @Prop({ reflect: true })
     public lazyLoadImages = false;
 
+    /**
+     * Set to `false` to preserve empty paragraphs before rendering.
+     * Empty paragraphs are paragraphs that do not contain
+     * any meaningful content (text, images, etc.), or only contain
+     * whitespace (`<br />` or `&nbsp;`).
+     */
+    @Prop({ reflect: true })
+    public removeEmptyParagraphs = true;
+
     @Watch('value')
     public async textChanged() {
         try {
@@ -64,6 +74,7 @@ export class Markdown {
                 forceHardLineBreaks: true,
                 whitelist: this.whitelist ?? [],
                 lazyLoadImages: this.lazyLoadImages,
+                removeEmptyParagraphs: this.removeEmptyParagraphs,
             });
 
             this.rootElement.innerHTML = html;
@@ -74,6 +85,11 @@ export class Markdown {
         }
     }
 
+    @Watch('removeEmptyParagraphs')
+    public handleRemoveEmptyParagraphsChange() {
+        return this.textChanged();
+    }
+
     private rootElement: HTMLDivElement;
     private imageIntersectionObserver: ImageIntersectionObserver | null = null;
 

src/components/markdown/remove-empty-paragraphs-plugin.spec.ts

@@ -0,0 +1,90 @@
+import { createRemoveEmptyParagraphsPlugin } from './remove-empty-paragraphs-plugin';
+
+describe('remove empty paragraphs plugin', () => {
+    it('keeps empty paragraphs when disabled', () => {
+        const tree = createRoot([createParagraph()]);
+
+        runPlugin(tree, false);
+
+        expect(tree.children).toHaveLength(1);
+    });
+
+    it('removes empty paragraphs with only whitespace content', () => {
+        const tree = createRoot([
+            createParagraph(),
+            createParagraph([createText('   ')]),
+            createParagraph([createText('\n')]),
+            createParagraph([createText('\u00A0')]),
+            createParagraph([createElement('span')]),
+            createParagraph([createElement('span', [createText('\u00A0')])]),
+        ]);
+
+        runPlugin(tree, true);
+
+        expect(tree.children).toHaveLength(0);
+    });
+
+    it('keeps paragraphs with meaningful content', () => {
+        const paragraph = createParagraph([
+            createElement('img', undefined, { src: 'test.jpg' }),
+        ]);
+        const tree = createRoot([paragraph]);
+
+        runPlugin(tree, true);
+
+        expect(tree.children).toHaveLength(1);
+        expect(tree.children[0]).toBe(paragraph);
+    });
+
+    it('keeps text content inside paragraphs', () => {
+        const paragraph = createParagraph([
+            createElement('span', [createText('Meaningful text')]),
+        ]);
+        const tree = createRoot([paragraph]);
+
+        runPlugin(tree, true);
+
+        expect(tree.children).toHaveLength(1);
+        expect(tree.children[0]).toBe(paragraph);
+    });
+});
+
+const runPlugin = (tree: any, enabled: boolean) => {
+    const plugin = createRemoveEmptyParagraphsPlugin(enabled);
+    const transformer = plugin.call(mockProcessor);
+
+    if (typeof transformer === 'function') {
+        transformer(tree);
+    }
+};
+
+const mockProcessor: any = {};
+mockProcessor.data = () => mockProcessor;
+
+const createRoot = (children: any[] = []) => ({
+    type: 'root',
+    children,
+});
+
+const createParagraph = (children: any[] = []) => ({
+    type: 'element',
+    tagName: 'p',
+    properties: {},
+    children,
+});
+
+const createElement = (
+    tagName: string,
+    children: any[] = [],
+    properties: Record<string, any> = {}
+) => ({
+    type: 'element',
+    tagName,
+    properties,
+    children,
+});
+
+const createText = (value: string) => ({
+    type: 'text',
+    value,
+});

src/components/markdown/remove-empty-paragraphs-plugin.ts

@@ -0,0 +1,119 @@
+import { Plugin, Transformer } from 'unified';
+import { Node } from 'unist';
+
+export const createRemoveEmptyParagraphsPlugin = (enabled = false): Plugin => {
+    return (): Transformer => {
+        if (!enabled) {
+            return (tree: Node) => tree;
+        }
+
+        return (tree: Node) => {
+            pruneEmptyParagraphs(tree, null);
+
+            return tree;
+        };
+    };
+};
+
+const NBSP_REGEX = /\u00A0/g;
+const MEANINGFUL_VOID_ELEMENTS = new Set([
+    'audio',
+    'canvas',
+    'embed',
+    'iframe',
+    'img',
+    'input',
+    'object',
+    'svg',
+    'video',
+]);
+
+const TREAT_AS_EMPTY_ELEMENTS = new Set(['br']);
+
+const pruneEmptyParagraphs = (node: any, parent: any) => {
+    if (!node || typeof node !== 'object') {
+        return;
+    }
+
+    if (
+        node.type === 'element' &&
+        node.tagName === 'p' &&
+        parent &&
+        isParagraphEffectivelyEmpty(node) &&
+        Array.isArray(parent.children)
+    ) {
+        const index = parent.children.indexOf(node);
+
+        if (index !== -1) {
+            parent.children.splice(index, 1);
+            return;
+        }
+    }
+
+    if (!Array.isArray(node.children) || node.children.length === 0) {
+        return;
+    }
+
+    for (let i = node.children.length - 1; i >= 0; i--) {
+        pruneEmptyParagraphs(node.children[i], node);
+    }
+};
+
+const isParagraphEffectivelyEmpty = (element: any): boolean => {
+    if (!Array.isArray(element.children) || element.children.length === 0) {
+        return true;
+    }
+
+    return element.children.every((child: any) =>
+        isNodeEffectivelyEmpty(child)
+    );
+};
+
+const isNodeEffectivelyEmpty = (node: any): boolean => {
+    if (!node) {
+        return true;
+    }
+
+    if (node.type === 'text') {
+        return isWhitespace(typeof node.value === 'string' ? node.value : '');
+    }
+
+    if (node.type === 'comment') {
+        return true;
+    }
+
+    if (node.type === 'element') {
+        const element = node;
+        const tagName = element.tagName;
+
+        if (typeof tagName !== 'string') {
+            return true;
+        }
+
+        if (MEANINGFUL_VOID_ELEMENTS.has(tagName)) {
+            return false;
+        }
+
+        if (TREAT_AS_EMPTY_ELEMENTS.has(tagName)) {
+            return true;
+        }
+
+        if (!Array.isArray(element.children) || element.children.length === 0) {
+            return true;
+        }
+
+        return element.children.every((child: any) =>
+            isNodeEffectivelyEmpty(child)
+        );
+    }
+
+    return true;
+};
+
+const isWhitespace = (value: string): boolean => {
+    if (!value) {
+        return true;
+    }
+
+    return value.replaceAll(NBSP_REGEX, ' ').trim() === '';
+};