@aquera/nile-elements 1.8.5 → 1.8.7

package/package.json

@@ -3,7 +3,7 @@
   "description": "Webcomponent nile-elements following open-wc recommendations",
   "license": "MIT",
   "author": "nile-elements",
-  "version": "1.8.5",
+  "version": "1.8.7",
   "main": "dist/src/index.js",
   "type": "module",
   "module": "dist/src/index.js",
@@ -167,6 +167,7 @@
     "element-internals-polyfill": "^1.1.20",
     "figlet": "1.7.0",
     "lit": "^3.0.0",
+    "marked": "^15.0.12",
     "tippy.js": "^6.3.7"
   },
   "devDependencies": {

package/src/index.ts

@@ -131,4 +131,6 @@ export { NileContextMenu } from './nile-context-menu';
 export { NileContextMenuGroup } from './nile-context-menu-group';
 export { NileContextMenuItem } from './nile-context-menu-item';
 export { NileInlineSidebarItemHeader } from './nile-inline-sidebar-item-header';
-export { NileInlineSidebarItemBody } from './nile-inline-sidebar-item-body';
+export { NileInlineSidebarItemBody } from './nile-inline-sidebar-item-body';
+export { NileMarkdown } from './nile-markdown';
+export { NileMarkdownEditor } from './nile-markdown-editor';

package/src/nile-markdown/index.ts

@@ -0,0 +1 @@
+export { NileMarkdown } from './nile-markdown';

package/src/nile-markdown/nile-markdown.css.ts

@@ -0,0 +1,164 @@
+/**
+ * Copyright Aquera Inc 2023
+ *
+ * This source code is licensed under the BSD-3-Clause license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { css } from 'lit';
+
+/**
+ * Markdown CSS
+ */
+export const styles = css`
+  :host {
+    display: block;
+    -webkit-font-smoothing: var(
+      --nile-webkit-font-smoothing,
+      var(--ng-webkit-font-smoothing)
+    );
+    -moz-osx-font-smoothing: var(
+      --nile-moz-osx-font-smoothing,
+      var(--ng-moz-osx-font-smoothing)
+    );
+    text-rendering: var(--nile-text-rendering, var(--ng-text-rendering));
+  }
+
+  .markdown {
+    font-family: var(--nile-font-family-serif, var(--ng-font-family-body));
+    font-size: var(--nile-type-scale-3, var(--ng-font-size-text-md));
+    line-height: var(--nile-line-height-medium, var(--ng-line-height-text-md));
+    color: var(--nile-colors-dark-900, var(--ng-colors-text-primary-900));
+    word-wrap: break-word;
+  }
+
+  .markdown > :first-child {
+    margin-top: 0;
+  }
+
+  .markdown > :last-child {
+    margin-bottom: 0;
+  }
+
+  .markdown h1,
+  .markdown h2,
+  .markdown h3,
+  .markdown h4,
+  .markdown h5,
+  .markdown h6 {
+    margin: 1.5em 0 0.5em;
+    font-weight: var(--nile-font-weight-medium, var(--ng-font-weight-semibold));
+    line-height: 1.25;
+    color: var(--nile-colors-dark-900, var(--ng-colors-text-primary-900));
+  }
+
+  .markdown h1 {
+    font-size: var(--nile-type-scale-7, var(--ng-font-size-display-sm));
+  }
+
+  .markdown h2 {
+    font-size: var(--nile-type-scale-6, var(--ng-font-size-text-xl));
+  }
+
+  .markdown h3 {
+    font-size: var(--nile-type-scale-5, var(--ng-font-size-text-lg));
+  }
+
+  .markdown h4 {
+    font-size: var(--nile-type-scale-3, var(--ng-font-size-text-md));
+  }
+
+  .markdown h5 {
+    font-size: var(--nile-type-scale-2, var(--ng-font-size-text-sm));
+  }
+
+  .markdown h6 {
+    font-size: var(--nile-type-scale-2, var(--ng-font-size-text-sm));
+    color: var(--nile-colors-neutral-700, var(--ng-colors-text-secondary-700));
+  }
+
+  .markdown p {
+    margin: 0 0 1em;
+  }
+
+  .markdown a {
+    color: var(--nile-colors-link-primary, var(--ng-colors-text-brand-secondary-700)
+    );
+    text-decoration: underline;
+  }
+
+  .markdown a:hover {
+    color: var(--nile-colors-link-hover, var(--ng-colors-text-brand-secondary-hover));
+  }
+
+  .markdown ul,
+  .markdown ol {
+    margin: 0 0 1em;
+    padding-inline-start: 2em;
+  }
+
+  .markdown li > ul,
+  .markdown li > ol {
+    margin-bottom: 0;
+  }
+
+  .markdown blockquote {
+    margin: 0 0 1em;
+    padding: 0 1em;
+    border-inline-start: 4px solid var(--nile-colors-neutral-400, var(--ng-colors-fg-quaternary-400));
+    color: var(--nile-colors-neutral-700, var(--ng-colors-text-secondary-700));
+  }
+
+  .markdown code {
+    font-family: var(--nile-font-family-mono, monospace);
+    font-size: var(--nile-type-scale-2, var(--ng-font-size-text-sm));
+    background: var(--nile-colors-dark-100, var(--ng-colors-bg-secondary));
+    border-radius: var(--nile-radius-sm, var(--ng-radius-sm));
+    padding: 0.125em 0.375em;
+  }
+
+  .markdown pre {
+    margin: 0 0 1em;
+    padding: var(--nile-spacing-md, var(--ng-spacing-md));
+    background: var(--nile-colors-dark-100, var(--ng-colors-bg-secondary));
+    border-radius: var(--nile-radius-md, var(--ng-radius-md));
+    overflow-x: auto;
+  }
+
+  .markdown pre code {
+    background: none;
+    border-radius: 0;
+    padding: 0;
+  }
+
+  .markdown table {
+    margin: 0 0 1em;
+    border-collapse: collapse;
+    width: max-content;
+    max-width: 100%;
+  }
+
+  .markdown th,
+  .markdown td {
+    border: 1px solid var(--nile-colors-gray-300, var(--ng-colors-gray-300));
+    padding: var(--nile-spacing-xs, var(--ng-spacing-xs))
+      var(--nile-spacing-md, var(--ng-spacing-md));
+  }
+
+  .markdown th {
+    background: var(--nile-colors-dark-100, var(--ng-colors-bg-secondary));
+    font-weight: var(--nile-font-weight-medium, var(--ng-font-weight-semibold));
+    text-align: left;
+  }
+
+  .markdown img {
+    max-width: 100%;
+  }
+
+  .markdown hr {
+    height: 1px;
+    margin: 1.5em 0;
+    border: none;
+    background: var(--nile-colors-dark-200, var(--ng-colors-border-secondary));
+  }
+`;

package/src/nile-markdown/nile-markdown.test.ts

@@ -0,0 +1,252 @@
+import { expect, fixture, html, oneEvent } from '@open-wc/testing';
+import './nile-markdown';
+import NileMarkdown from './nile-markdown';
+
+describe('NileMarkdown', () => {
+  // === RENDERING ===
+  it('1. should render without errors', async () => {
+    const el = await fixture<NileMarkdown>(
+      html`<nile-markdown></nile-markdown>`
+    );
+    expect(el).to.exist;
+  });
+
+  it('2. should have a shadow root', async () => {
+    const el = await fixture<NileMarkdown>(
+      html`<nile-markdown></nile-markdown>`
+    );
+    expect(el.shadowRoot).to.not.be.null;
+  });
+
+  it('3. should have base part', async () => {
+    const el = await fixture<NileMarkdown>(
+      html`<nile-markdown></nile-markdown>`
+    );
+    const base = el.shadowRoot!.querySelector('[part~="base"]');
+    expect(base).to.exist;
+  });
+
+  it('4. should be instance of NileMarkdown', async () => {
+    const el = await fixture<NileMarkdown>(
+      html`<nile-markdown></nile-markdown>`
+    );
+    expect(el).to.be.instanceOf(NileMarkdown);
+  });
+
+  it('5. should have correct tag name', async () => {
+    const el = await fixture<NileMarkdown>(
+      html`<nile-markdown></nile-markdown>`
+    );
+    expect(el.tagName.toLowerCase()).to.equal('nile-markdown');
+  });
+
+  // === DEFAULT PROPERTIES ===
+  it('6. should have value default to empty string', async () => {
+    const el = await fixture<NileMarkdown>(
+      html`<nile-markdown></nile-markdown>`
+    );
+    expect(el.value).to.equal('');
+  });
+
+  it('7. should have tabSize default to 4', async () => {
+    const el = await fixture<NileMarkdown>(
+      html`<nile-markdown></nile-markdown>`
+    );
+    expect(el.tabSize).to.equal(4);
+  });
+
+  // === VALUE PROPERTY ===
+  it('8. should render markdown from value property', async () => {
+    const el = await fixture<NileMarkdown>(
+      html`<nile-markdown value="# Heading"></nile-markdown>`
+    );
+    await el.updateComplete;
+    const h1 = el.shadowRoot!.querySelector('h1');
+    expect(h1).to.exist;
+    expect(h1!.textContent).to.equal('Heading');
+  });
+
+  it('9. should render bold text', async () => {
+    const el = await fixture<NileMarkdown>(
+      html`<nile-markdown value="This is **bold**"></nile-markdown>`
+    );
+    await el.updateComplete;
+    const strong = el.shadowRoot!.querySelector('strong');
+    expect(strong).to.exist;
+    expect(strong!.textContent).to.equal('bold');
+  });
+
+  it('10. should render links', async () => {
+    const el = await fixture<NileMarkdown>(
+      html`<nile-markdown value="[link](https://example.com)"></nile-markdown>`
+    );
+    await el.updateComplete;
+    const a = el.shadowRoot!.querySelector('a');
+    expect(a).to.exist;
+    expect(a!.getAttribute('href')).to.equal('https://example.com');
+  });
+
+  it('11. should render lists', async () => {
+    const el = await fixture<NileMarkdown>(
+      html`<nile-markdown></nile-markdown>`
+    );
+    el.value = '- one\n- two\n- three';
+    await el.updateComplete;
+    const items = el.shadowRoot!.querySelectorAll('li');
+    expect(items.length).to.equal(3);
+  });
+
+  it('12. should render code blocks', async () => {
+    const el = await fixture<NileMarkdown>(
+      html`<nile-markdown></nile-markdown>`
+    );
+    el.value = '```\nconst a = 1;\n```';
+    await el.updateComplete;
+    const pre = el.shadowRoot!.querySelector('pre code');
+    expect(pre).to.exist;
+  });
+
+  it('13. should render GFM tables', async () => {
+    const el = await fixture<NileMarkdown>(
+      html`<nile-markdown></nile-markdown>`
+    );
+    el.value = '| a | b |\n| - | - |\n| 1 | 2 |';
+    await el.updateComplete;
+    const table = el.shadowRoot!.querySelector('table');
+    expect(table).to.exist;
+  });
+
+  it('14. should render blockquotes', async () => {
+    const el = await fixture<NileMarkdown>(
+      html`<nile-markdown></nile-markdown>`
+    );
+    el.value = '> quoted';
+    await el.updateComplete;
+    const quote = el.shadowRoot!.querySelector('blockquote');
+    expect(quote).to.exist;
+  });
+
+  // === SCRIPT CHILD ===
+  it('15. should render markdown from a script child', async () => {
+    const el = await fixture<NileMarkdown>(html`
+      <nile-markdown>
+        <script type="text/markdown">
+          # From Script
+        </script>
+      </nile-markdown>
+    `);
+    await el.updateComplete;
+    const h1 = el.shadowRoot!.querySelector('h1');
+    expect(h1).to.exist;
+    expect(h1!.textContent).to.equal('From Script');
+  });
+
+  it('16. should normalize indented script content', async () => {
+    const el = await fixture<NileMarkdown>(html`
+      <nile-markdown>
+        <script type="text/markdown">
+          # Title
+
+          Paragraph text, indented to match the HTML.
+        </script>
+      </nile-markdown>
+    `);
+    await el.updateComplete;
+    // Indented content must not be treated as a code block
+    expect(el.shadowRoot!.querySelector('pre')).to.not.exist;
+    expect(el.shadowRoot!.querySelector('h1')).to.exist;
+    expect(el.shadowRoot!.querySelector('p')).to.exist;
+  });
+
+  it('17. value should take precedence over script child', async () => {
+    const el = await fixture<NileMarkdown>(html`
+      <nile-markdown value="# From Value">
+        <script type="text/markdown">
+          # From Script
+        </script>
+      </nile-markdown>
+    `);
+    await el.updateComplete;
+    const h1 = el.shadowRoot!.querySelector('h1');
+    expect(h1!.textContent).to.equal('From Value');
+  });
+
+  // === DYNAMIC UPDATES ===
+  it('18. should re-render when value changes', async () => {
+    const el = await fixture<NileMarkdown>(
+      html`<nile-markdown value="# One"></nile-markdown>`
+    );
+    await el.updateComplete;
+    el.value = '# Two';
+    await el.updateComplete;
+    await el.updateComplete;
+    const h1 = el.shadowRoot!.querySelector('h1');
+    expect(h1!.textContent).to.equal('Two');
+  });
+
+  it('19. should re-render when script content changes', async () => {
+    const el = await fixture<NileMarkdown>(html`
+      <nile-markdown>
+        <script type="text/markdown">
+          # Before
+        </script>
+      </nile-markdown>
+    `);
+    await el.updateComplete;
+    const script = el.querySelector('script')!;
+    script.textContent = '# After';
+    // MutationObserver fires async
+    await new Promise(resolve => setTimeout(resolve, 0));
+    await el.updateComplete;
+    const h1 = el.shadowRoot!.querySelector('h1');
+    expect(h1!.textContent).to.equal('After');
+  });
+
+  it('20. renderMarkdown() should re-parse manually', async () => {
+    const el = await fixture<NileMarkdown>(
+      html`<nile-markdown value="# Manual"></nile-markdown>`
+    );
+    await el.updateComplete;
+    el.renderMarkdown();
+    await el.updateComplete;
+    expect(el.shadowRoot!.querySelector('h1')!.textContent).to.equal('Manual');
+  });
+
+  // === EVENTS ===
+  it('21. should emit nile-markdown-rendered after rendering', async () => {
+    const el = document.createElement('nile-markdown') as NileMarkdown;
+    const listener = oneEvent(el, 'nile-markdown-rendered');
+    el.value = '# Event';
+    document.body.appendChild(el);
+    const event = await listener;
+    expect(event).to.exist;
+    el.remove();
+  });
+
+  // === STATIC API ===
+  it('22. getMarked() should return a shared instance', () => {
+    const a = NileMarkdown.getMarked();
+    const b = NileMarkdown.getMarked();
+    expect(a).to.equal(b);
+  });
+
+  it('23. updateAll() should not throw', async () => {
+    await fixture<NileMarkdown>(
+      html`<nile-markdown value="# A"></nile-markdown>`
+    );
+    expect(() => NileMarkdown.updateAll()).to.not.throw();
+  });
+
+  // === EDGE CASES ===
+  it('24. should handle empty content', async () => {
+    const el = await fixture<NileMarkdown>(
+      html`<nile-markdown></nile-markdown>`
+    );
+    const base = el.shadowRoot!.querySelector('[part~="base"]');
+    expect(base!.textContent!.trim()).to.equal('');
+  });
+
+  it('25. should have static styles', () => {
+    expect(NileMarkdown.styles).to.exist;
+  });
+});

package/src/nile-markdown/nile-markdown.ts

@@ -0,0 +1,179 @@
+/**
+ * Copyright Aquera Inc 2023
+ *
+ * This source code is licensed under the BSD-3-Clause license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { html } from 'lit';
+import { customElement, property, state } from 'lit/decorators.js';
+import { unsafeHTML } from 'lit/directives/unsafe-html.js';
+import { Marked } from 'marked';
+import { styles } from './nile-markdown.css';
+import NileElement from '../internal/nile-element';
+import type { CSSResultGroup, PropertyValues, TemplateResult } from 'lit';
+
+/**
+ * Nile markdown component.
+ *
+ * @tag nile-markdown
+ */
+
+/**
+ * @summary Renders markdown content as HTML in the browser using GitHub Flavored Markdown.
+ * @status experimental
+ *
+ * Content can be provided either through the `value` property or through a
+ * `<script type="text/markdown">` element placed as a direct child:
+ *
+ * ```html
+ * <nile-markdown>
+ *   <script type="text/markdown">
+ *     # Hello
+ *     This is **markdown**.
+ *   </script>
+ * </nile-markdown>
+ * ```
+ *
+ * Leading whitespace common to all lines is stripped, so the markdown can be
+ * indented to match the surrounding HTML without rendering as a code block.
+ *
+ * All instances share a single Marked parser. Use `NileMarkdown.getMarked()`
+ * to customize it (extensions, renderers, etc.) and `NileMarkdown.updateAll()`
+ * to re-render existing instances after changing the configuration.
+ *
+ * WARNING: The markdown is converted to HTML without sanitization. Do not
+ * render unsanitized user input, as this can expose users to XSS attacks.
+ *
+ * @event nile-markdown-rendered - Emitted after the markdown has been parsed and rendered.
+ *
+ * @csspart base - The component's base wrapper containing the rendered HTML.
+ */
+
+@customElement('nile-markdown')
+export class NileMarkdown extends NileElement {
+  static styles: CSSResultGroup = styles;
+
+  /** The shared Marked instance used by every nile-markdown on the page. */
+  private static marked: Marked | undefined;
+
+  /** All connected instances, used by `updateAll()`. */
+  private static instances = new Set<NileMarkdown>();
+
+  /**
+   * Returns the shared Marked instance so it can be configured with custom
+   * options, extensions, or renderers. Changes affect all instances; call
+   * `NileMarkdown.updateAll()` afterwards to re-render existing ones.
+   */
+  static getMarked(): Marked {
+    if (!NileMarkdown.marked) {
+      NileMarkdown.marked = new Marked({ gfm: true, async: false });
+    }
+    return NileMarkdown.marked;
+  }
+
+  /** Re-renders every connected nile-markdown instance. */
+  static updateAll(): void {
+    NileMarkdown.instances.forEach(instance => instance.renderMarkdown());
+  }
+
+  /**
+   * The markdown to render. Takes precedence over a
+   * `<script type="text/markdown">` child when set.
+   */
+  @property() value = '';
+
+  /** Number of spaces a tab is converted to during whitespace normalization. */
+  @property({ type: Number, attribute: 'tab-size' }) tabSize = 4;
+
+  @state() private renderedHtml = '';
+
+  /** Re-renders automatically when the markdown script child changes. */
+  private mutationObserver = new MutationObserver(() => this.renderMarkdown());
+
+  connectedCallback(): void {
+    super.connectedCallback();
+    NileMarkdown.instances.add(this);
+    this.mutationObserver.observe(this, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+    });
+    this.renderMarkdown();
+  }
+
+  disconnectedCallback(): void {
+    this.mutationObserver.disconnect();
+    NileMarkdown.instances.delete(this);
+    super.disconnectedCallback();
+  }
+
+  protected willUpdate(changed: PropertyValues): void {
+    super.willUpdate(changed);
+    if (changed.has('value') || changed.has('tabSize')) {
+      this.computeHtml();
+    }
+  }
+
+  protected updated(changed: PropertyValues): void {
+    super.updated(changed);
+    if (changed.has('renderedHtml')) {
+      this.emit('nile-markdown-rendered', undefined, true, true);
+    }
+  }
+
+  /** Reads the markdown source from `value` or the script child. */
+  private getSource(): string {
+    if (this.value) return this.value;
+    const script = this.querySelector(':scope > script[type="text/markdown"]');
+    return script?.textContent ?? '';
+  }
+
+  /**
+   * Converts tabs to spaces and removes the leading indentation common to all
+   * lines, so markdown indented to match the HTML doesn't render as code.
+   */
+  private normalizeWhitespace(text: string): string {
+    const tab = ' '.repeat(Math.max(1, this.tabSize));
+    const lines = text.replace(/\t/g, tab).split('\n');
+
+    let minIndent = Infinity;
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      const indent = line.length - line.trimStart().length;
+      minIndent = Math.min(minIndent, indent);
+    }
+    if (!Number.isFinite(minIndent) || minIndent === 0) {
+      return text.trim();
+    }
+    return lines
+      .map(line => line.slice(minIndent))
+      .join('\n')
+      .trim();
+  }
+
+  /** Parses the markdown source into `renderedHtml`. */
+  private computeHtml(): void {
+    const source = this.normalizeWhitespace(this.getSource());
+    this.renderedHtml = NileMarkdown.getMarked().parse(source) as string;
+  }
+
+  /** Parses the markdown source and renders the resulting HTML. */
+  renderMarkdown(): void {
+    this.computeHtml();
+  }
+
+  render(): TemplateResult {
+    return html`
+      <div class="markdown" part="base">${unsafeHTML(this.renderedHtml)}</div>
+    `;
+  }
+}
+
+export default NileMarkdown;
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'nile-markdown': NileMarkdown;
+  }
+}

package/src/nile-markdown-editor/index.ts

@@ -0,0 +1 @@
+export { NileMarkdownEditor } from './nile-markdown-editor';