@covalent/markdown 0.0.0-COVALENT

package/.browserslistrc

@@ -0,0 +1,16 @@
+# This file is used by the build system to adjust CSS and JS output to support the specified browsers below.
+# For additional information regarding the format and rule options, please see:
+# https://github.com/browserslist/browserslist#queries
+
+# For the full list of supported browsers by the Angular framework, please see:
+# https://angular.dev/reference/versions#browser-support
+
+# You can see what browsers were selected by your queries by running:
+#   npx browserslist
+
+last 1 Chrome version
+last 1 Firefox version
+last 2 Edge major versions
+last 2 Safari major versions
+last 2 iOS major versions
+Firefox ESR

package/.eslintrc.json

@@ -0,0 +1,36 @@
+{
+  "extends": ["../../.eslintrc.json"],
+  "ignorePatterns": ["!**/*"],
+  "overrides": [
+    {
+      "files": ["*.ts"],
+      "extends": [
+        "plugin:@nx/angular",
+        "plugin:@angular-eslint/template/process-inline-templates"
+      ],
+      "rules": {
+        "@angular-eslint/directive-selector": [
+          "error",
+          {
+            "type": "attribute",
+            "prefix": "td",
+            "style": "camelCase"
+          }
+        ],
+        "@angular-eslint/component-selector": [
+          "error",
+          {
+            "type": "element",
+            "prefix": "td",
+            "style": "kebab-case"
+          }
+        ]
+      }
+    },
+    {
+      "files": ["*.html"],
+      "extends": ["plugin:@nx/angular-template"],
+      "rules": {}
+    }
+  ]
+}

package/README.md

@@ -0,0 +1,103 @@
+## TdMarkdownComponent: td-markdown
+
+`<td-markdown>` is a component that parses and renders Github flavored markdown. It is based on the [showdown](https://github.com/showdownjs/showdown/) library.
+
+**Note:** This module uses the **DomSanitizer** service to sanitize the parsed html from the showdown lib to avoid **XSS** issues.
+
+By default, `--dev` build will log the following message in the console to let you know:
+
+`WARNING: sanitizing HTML stripped some content (see http://g.co/ng/security#xss).`
+
+## API Summary
+
+#### Inputs
+
+- content?: string
+
+  - Markdown format content to be parsed as html markup.
+  - Used to load data dynamically. e.g. `README.md` content.
+
+- simpleLineBreaks?: string
+
+  - Sets whether newline characters inside paragraphs and spans are parsed as <br/>.
+  - Defaults to false.
+
+- hostedUrl?: string
+
+  - If markdown contains relative paths, this is required to generate correct urls.
+
+- anchor?: string
+
+  - Anchor to jump to.
+
+- fileLinkExtensions?: string[]
+  - The file extensions to monitor within anchor tags.
+  - Clicking links that end with these extensions will prevent the default action and emit 'fileClicked' event.
+
+#### Events
+
+- contentReady: undefined
+
+  - Event emitted after the markdown content rendering is finished.
+
+- fileLinkClicked: URL
+  - Emitted when an anchor tag is clicked and its 'href' matches one of the extensions in 'fileLinkExtensions'.
+
+## Installation
+
+This component can be installed as an npm package.
+
+```bash
+npm i -save @covalent/markdown
+```
+
+## Setup
+
+Then, import the **CovalentMarkdownModule** in your NgModule:
+
+```typescript
+import { CovalentMarkdownModule } from '@covalent/markdown';
+@NgModule({
+  imports: [
+    CovalentMarkdownModule,
+    ...
+  ],
+  ...
+})
+export class MyModule {}
+```
+
+### Theming
+
+This module comes with its own Covalent theme which uses the material theme which is used by importing our theme scss file.
+
+```scss
+@use '@angular/material/theming' as mat;
+@use '@covalent/markdown/markdown-theme' as markdown;
+
+@include mat.core();
+
+$primary: mat.define-palette($mat-orange, 800);
+$accent: mat.define-palette($mat-light-blue, 600, A100, A400);
+$warn: mat.define-palette($mat-red, 600);
+
+$theme: mat.define-light-theme($primary, $accent, $warn);
+
+@include markdown.covalent-markdown-theme($theme);
+```
+
+## Example
+
+**Html:**
+
+```html
+<td-markdown> # Heading ## Sub Heading (H2) ### Steps (H2) </td-markdown>
+```
+
+**Output:**
+
+# Heading
+
+## Sub Heading (H2)
+
+### Steps (H2)

package/_markdown-theme.scss

@@ -0,0 +1,72 @@
+@use '@angular/material' as mat;
+
+@mixin covalent-markdown-theme($theme) {
+  $accent: map-get($theme, accent);
+  $foreground: map-get($theme, foreground);
+  $background: map-get($theme, background);
+
+  td-markdown {
+    a {
+      color: mat.m2-get-color-from-palette($accent);
+    }
+
+    h1,
+    h2 {
+      border-bottom-color: mat.m2-get-color-from-palette($foreground, divider);
+    }
+
+    h3,
+    h4,
+    h5,
+    h6 {
+      color: mat.m2-get-color-from-palette($foreground, secondary-text);
+    }
+
+    hr {
+      border-color: mat.m2-get-color-from-palette($foreground, divider);
+    }
+
+    blockquote {
+      color: mat.m2-get-color-from-palette($foreground, secondary-text);
+      border-left-color: mat.m2-get-color-from-palette($foreground, divider);
+    }
+
+    table {
+      th,
+      td {
+        border-color: mat.m2-get-color-from-palette($foreground, dividers);
+      }
+
+      tr {
+        border-top-color: mat.m2-get-color-from-palette($foreground, dividers);
+
+        &:nth-child(2n) {
+          background-color: mat.m2-get-color-from-palette(
+            $foreground,
+            dividers
+          );
+        }
+      }
+    }
+
+    img {
+      background-color: mat.m2-get-color-from-palette($background, card);
+    }
+
+    code {
+      background-color: mat.m2-get-color-from-palette($background, hover);
+    }
+
+    .highlight pre,
+    pre {
+      background-color: mat.m2-get-color-from-palette($background, app-bar);
+    }
+
+    kbd {
+      color: mat.m2-get-color-from-palette($foreground, secondary-text);
+      background-color: mat.m2-get-color-from-palette($background, app-bar);
+      border-color: mat.m2-get-color-from-palette($foreground, divider);
+      border-bottom-color: mat.m2-get-color-from-palette($foreground, disabled);
+    }
+  }
+}

package/jest.config.js

@@ -0,0 +1,23 @@
+module.exports = {
+  displayName: 'markdown',
+  preset: '../../jest.preset.js',
+  setupFilesAfterEnv: ['<rootDir>/src/test-setup.ts'],
+  globals: {},
+  coverageDirectory: '../../coverage/libs/markdown',
+  testEnvironment: 'jsdom',
+  transform: {
+    '^.+\\.(ts|mjs|js|html)$': [
+      'jest-preset-angular',
+      {
+        tsconfig: '<rootDir>/tsconfig.spec.json',
+        stringifyContentPathRegex: '\\.(html|svg)$',
+      },
+    ],
+  },
+  transformIgnorePatterns: ['node_modules/(?!.*\\.mjs$)'],
+  snapshotSerializers: [
+    'jest-preset-angular/build/serializers/no-ng-attributes',
+    'jest-preset-angular/build/serializers/ng-snapshot',
+    'jest-preset-angular/build/serializers/html-comment',
+  ],
+};

package/ng-package.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "../../dist/libs/markdown",
+  "assets": ["./**/*theme.scss"]
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@covalent/markdown",
+  "version": "0.0.0-COVALENT",
+  "description": "Teradata UI Platform Markdown Module",
+  "keywords": [
+    "angular",
+    "components",
+    "reusable",
+    "markdown"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/teradata/covalent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/teradata/covalent/issues"
+  },
+  "license": "MIT",
+  "author": "Teradata UX",
+  "peerDependencies": {
+    "showdown": "0.0.0-SHOWDOWN",
+    "@angular/common": "0.0.0-NG",
+    "@angular/core": "0.0.0-NG",
+    "@angular/platform-browser": "0.0.0-NG"
+  },
+  "dependencies": {
+    "tslib": "0.0.0-TSLIB"
+  },
+  "exports": {
+    "./markdown-theme": {
+      "sass": "./_markdown-theme.scss"
+    }
+  }
+}

package/project.json

@@ -0,0 +1,64 @@
+{
+  "name": "markdown",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "projectType": "library",
+  "sourceRoot": "libs/markdown/src",
+  "prefix": "covalent",
+  "targets": {
+    "build": {
+      "executor": "@angular-devkit/build-angular:ng-packagr",
+      "outputs": ["{workspaceRoot}/dist/libs/markdown"],
+      "options": {
+        "project": "libs/markdown/ng-package.json"
+      },
+      "configurations": {
+        "production": {
+          "tsConfig": "libs/markdown/tsconfig.lib.prod.json"
+        },
+        "development": {
+          "tsConfig": "libs/markdown/tsconfig.lib.json"
+        }
+      },
+      "defaultConfiguration": "production",
+      "dependsOn": [
+        {
+          "projects": ["angular", "angular-highlight"],
+          "target": "build",
+          "params": "ignore"
+        }
+      ]
+    },
+    "test": {
+      "executor": "@nrwl/jest:jest",
+      "outputs": ["{workspaceRoot}/coverage/libs/markdown"],
+      "options": {
+        "jestConfig": "libs/markdown/jest.config.js",
+        "passWithNoTests": true
+      }
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint",
+      "options": {
+        "lintFilePatterns": [
+          "libs/markdown/src/**/*.ts",
+          "libs/markdown/src/**/*.html",
+          "libs/markdown/flavored/**/*.ts",
+          "libs/markdown/flavored/**/*.html",
+          "libs/markdown/navigator/**/*.ts",
+          "libs/markdown/navigator/**/*.html"
+        ]
+      }
+    },
+    "scsslint": {
+      "executor": "nx:run-commands",
+      "options": {
+        "commands": [
+          {
+            "command": "./node_modules/.bin/stylelint --allow-empty-input 'libs/markdown/**/*.scss'"
+          }
+        ]
+      }
+    }
+  },
+  "tags": []
+}

package/src/lib/markdown-loader/markdown-loader.service.spec.ts

@@ -0,0 +1,101 @@
+import { TestBed, inject, waitForAsync } from '@angular/core/testing';
+import { TdMarkdownLoaderService } from './markdown-loader.service';
+import { CovalentMarkdownModule } from '../markdown.module';
+
+const SAMPLE_HEADING = 'Covalent Design System';
+
+const RAW_GH_URL =
+  'https://raw.githubusercontent.com/Teradata/covalent/main/README.md';
+const GH_URL = 'https://github.com/Teradata/covalent/blob/main/README.md';
+const BRANCH_GH_URL =
+  'https://github.com/Teradata/covalent/blob/main/README.md';
+const RAW_GH_BRANCH_URL =
+  'https://raw.githubusercontent.com/Teradata/covalent/main/README.md';
+const NON_MARKDOWN_URL = 'https://teradata.github.io/covalent/#/';
+const UNREACHABLE_URL = 'https://github.com/Teradata/covalent/tree/main/src';
+
+describe('Service: MarkdownLoader', () => {
+  beforeEach(waitForAsync(() => {
+    TestBed.configureTestingModule({
+      imports: [CovalentMarkdownModule],
+    });
+  }));
+
+  it('should fetch from a raw github url', waitForAsync(
+    inject(
+      [TdMarkdownLoaderService],
+      async (_markdownLoaderService: TdMarkdownLoaderService) => {
+        const markdown: string = await _markdownLoaderService.load(RAW_GH_URL);
+        expect(markdown).toContain(SAMPLE_HEADING);
+      }
+    )
+  ));
+
+  it('should fetch from a non-raw github url', waitForAsync(
+    inject(
+      [TdMarkdownLoaderService],
+      async (_markdownLoaderService: TdMarkdownLoaderService) => {
+        const markdown: string = await _markdownLoaderService.load(GH_URL);
+        expect(markdown).toContain(SAMPLE_HEADING);
+      }
+    )
+  ));
+
+  it('should fetch from a raw branch github url', waitForAsync(
+    inject(
+      [TdMarkdownLoaderService],
+      async (_markdownLoaderService: TdMarkdownLoaderService) => {
+        const markdown: string = await _markdownLoaderService.load(
+          RAW_GH_BRANCH_URL
+        );
+        expect(markdown).toContain(SAMPLE_HEADING);
+      }
+    )
+  ));
+
+  it('should fetch from a non-raw branch github url', waitForAsync(
+    inject(
+      [TdMarkdownLoaderService],
+      async (_markdownLoaderService: TdMarkdownLoaderService) => {
+        const markdown: string = await _markdownLoaderService.load(
+          BRANCH_GH_URL
+        );
+        expect(markdown).toContain(SAMPLE_HEADING);
+      }
+    )
+  ));
+
+  it('should throw error if content response type is not plain or markdown', waitForAsync(
+    inject(
+      [TdMarkdownLoaderService],
+      async (_markdownLoaderService: TdMarkdownLoaderService) => {
+        let failed = false;
+        try {
+          await _markdownLoaderService.load(NON_MARKDOWN_URL);
+        } catch (error) {
+          failed = true;
+        } finally {
+          expect(failed).toBeTruthy();
+        }
+      }
+    )
+  ));
+
+  it('should throw error if url is not reachable', waitForAsync(
+    inject(
+      [TdMarkdownLoaderService],
+      async (_markdownLoaderService: TdMarkdownLoaderService) => {
+        let failed = false;
+        try {
+          await _markdownLoaderService.load(UNREACHABLE_URL);
+        } catch (error) {
+          failed = true;
+        } finally {
+          expect(failed).toBeTruthy();
+        }
+      }
+    )
+  ));
+
+  // TODO: test http params
+});

package/src/lib/markdown-loader/markdown-loader.service.ts

@@ -0,0 +1,35 @@
+import { Injectable, SecurityContext } from '@angular/core';
+import { DomSanitizer } from '@angular/platform-browser';
+import { HttpClient, HttpResponse } from '@angular/common/http';
+import { isGithubHref, rawGithubHref } from '../markdown-utils/markdown-utils';
+
+@Injectable()
+export class TdMarkdownLoaderService {
+  constructor(private _http: HttpClient, private _sanitizer: DomSanitizer) {}
+
+  async load(url: string, httpOptions: object = {}): Promise<string> {
+    const sanitizedUrl: string =
+      this._sanitizer.sanitize(SecurityContext.URL, url) ?? '';
+    let urlToGet: string = sanitizedUrl;
+    if (isGithubHref(sanitizedUrl)) {
+      urlToGet = rawGithubHref(sanitizedUrl);
+    }
+
+    const response: HttpResponse<string> | undefined = await this._http
+      .get(urlToGet, {
+        ...httpOptions,
+        responseType: 'text',
+        observe: 'response',
+      })
+      .toPromise();
+    const contentType: string = response?.headers.get('Content-Type') ?? '';
+    if (
+      contentType.includes('text/plain') ||
+      contentType.includes('text/markdown')
+    ) {
+      return response?.body ?? '';
+    } else {
+      throw Error(`${contentType} is not a handled content type`);
+    }
+  }
+}

package/src/lib/markdown-utils/markdown-utils.spec.ts

@@ -0,0 +1,189 @@
+import {
+  removeLeadingHash,
+  removeTrailingHash,
+  genHeadingId,
+  isAnchorLink,
+  isGithubHref,
+  rawGithubHref,
+  scrollToAnchor,
+  isRawGithubHref,
+} from './markdown-utils';
+import { Component } from '@angular/core';
+import { TestBed, ComponentFixture, waitForAsync } from '@angular/core/testing';
+import { By } from '@angular/platform-browser';
+
+// Implementing scrollIntoView since its not implemented JSDOM
+window.HTMLElement.prototype.scrollIntoView = function () {
+  // noop
+};
+
+@Component({
+  selector: 'td-jump-to-anchor-test-component',
+  template: `
+    <main>
+      <section id="s1">
+        <article id="a1">
+          <h1 id="heading1">heading 1</h1>
+          <h1 id="heading2">heading 2</h1>
+        </article>
+        <article id="a2">
+          <h1 id="heading3">heading 3</h1>
+          <h1 id="heading4">heading 4</h1>
+        </article>
+      </section>
+
+      <section id="s2">
+        <article id="a3">
+          <h1 id="heading5">heading 5</h1>
+          <h1 id="heading6">heading 6</h1>
+        </article>
+        <article id="a4">
+          <h1 id="heading7">heading 7</h1>
+          <h1 id="heading8">heading 8</h1>
+        </article>
+      </section>
+    </main>
+  `,
+})
+class JumpToAnchorTestComponent {}
+
+describe('Markdown utils', () => {
+  beforeEach(
+    waitForAsync(() => {
+      TestBed.configureTestingModule({
+        imports: [JumpToAnchorTestComponent],
+      }).compileComponents();
+    })
+  );
+
+  it('removeLeadingHash should remove leading hashes', () => {
+    expect(removeLeadingHash('')).toBe('');
+    expect(removeLeadingHash('#')).toBe('');
+    expect(removeLeadingHash('#anchor')).toBe('anchor');
+    expect(removeLeadingHash('##anchor')).toBe('anchor');
+    expect(removeLeadingHash('#anchor#')).toBe('anchor#');
+    expect(removeLeadingHash('#before#anchor')).toBe('before#anchor');
+  });
+
+  it('removeTrailingHash should remove trailing hashes', () => {
+    expect(removeTrailingHash('')).toBe('');
+    expect(removeTrailingHash('#')).toBe('');
+    expect(removeTrailingHash('#anchor')).toBe('');
+    expect(removeTrailingHash('before#')).toBe('before');
+    expect(removeTrailingHash('even-before#before#')).toBe('even-before');
+    expect(removeTrailingHash('before##')).toBe('before');
+  });
+
+  it('genHeadingId should generate proper heading id', () => {
+    expect(genHeadingId('')).toBe('');
+    expect(genHeadingId('Markdown Utils')).toBe('markdownutils');
+    expect(genHeadingId('Markdown-Utils')).toBe('markdownutils');
+    expect(genHeadingId('Markdown_Utils')).toBe('markdownutils');
+    expect(genHeadingId('(component/module/utility)')).toBe(
+      'componentmoduleutility'
+    );
+    expect(genHeadingId('Markdown Utils!?')).toBe('markdownutils');
+    expect(genHeadingId('#markdown_utils')).toBe('markdownutils');
+    expect(genHeadingId('#markdown-utils')).toBe('markdownutils');
+    expect(genHeadingId('#markdown utils')).toBe('markdownutils');
+    expect(genHeadingId('#(component/module/utility)')).toBe(
+      'componentmoduleutility'
+    );
+    expect(genHeadingId('#')).toBe('');
+  });
+
+  it('isAnchorLink should generate proper heading id', () => {
+    expect(isAnchorLink(undefined)).toBe(false);
+    const anchor: HTMLAnchorElement = document.createElement('a');
+    expect(isAnchorLink(anchor)).toBe(false);
+    anchor.setAttribute('href', '');
+    expect(isAnchorLink(anchor)).toBe(false);
+    anchor.setAttribute('href', 'github.com');
+    expect(isAnchorLink(anchor)).toBe(false);
+    anchor.setAttribute('href', '#anchor');
+    expect(isAnchorLink(anchor)).toBe(true);
+  });
+
+  it('rawGithubHref should generate raw github href', () => {
+    expect(rawGithubHref('')).toBe('');
+    expect(rawGithubHref(undefined)).toBe('');
+    expect(rawGithubHref('invalid-href')).toBe('');
+    expect(rawGithubHref('http://non-github-url.com')).toBe('');
+
+    const something = `https://github.com/Teradata/covalent/blob/`;
+    const somethingElse =
+      'https://raw.githubusercontent.com/Teradata/covalent/';
+    const path = '/docs/CONTRIBUTING.md';
+    const developBranch = 'develop';
+    const mainBranch = 'main';
+    const anchor = '#anchor';
+
+    const DEVELOP_NON_RAW_HREF = `${something}${developBranch}${path}`;
+    const DEVELOP_RAW_HREF = `${somethingElse}${developBranch}${path}`;
+    const MAIN_NON_RAW_HREF = `${something}${mainBranch}${path}`;
+    const MAIN_RAW_HREF = `${somethingElse}${mainBranch}${path}`;
+    const DEVELOP_NON_RAW_HREF_WITH_ANCHOR = `${something}${developBranch}${path}${anchor}`;
+    const DEVELOP_RAW_HREF_WITH_ANCHOR = `${somethingElse}${developBranch}${path}${anchor}`;
+
+    expect(rawGithubHref(anchor)).toBe('');
+    expect(rawGithubHref(DEVELOP_NON_RAW_HREF)).toBe(DEVELOP_RAW_HREF);
+    expect(rawGithubHref(DEVELOP_RAW_HREF)).toBe(DEVELOP_RAW_HREF);
+    expect(rawGithubHref(MAIN_NON_RAW_HREF)).toBe(MAIN_RAW_HREF);
+    expect(rawGithubHref(MAIN_RAW_HREF)).toBe(MAIN_RAW_HREF);
+    expect(rawGithubHref(DEVELOP_NON_RAW_HREF_WITH_ANCHOR)).toBe(
+      DEVELOP_RAW_HREF_WITH_ANCHOR
+    );
+    expect(rawGithubHref(DEVELOP_RAW_HREF_WITH_ANCHOR)).toBe(
+      DEVELOP_RAW_HREF_WITH_ANCHOR
+    );
+  });
+
+  it('isGithubHref should check whether an href is from github.com', () => {
+    expect(isGithubHref('')).toBe(false);
+    expect(isGithubHref(undefined)).toBe(false);
+    expect(isGithubHref('github.com')).toBe(false);
+    expect(isGithubHref('subdomain.github.com')).toBe(false);
+    expect(isGithubHref('https://raw.githubusercontent.com')).toBe(false);
+    expect(isGithubHref('http://github.com')).toBe(true);
+    expect(isGithubHref('https://github.com')).toBe(true);
+    expect(isGithubHref('https://github.com/something')).toBe(true);
+  });
+
+  it('isRawGithubHref should check whether an href is from raw.githubusercontent.com', () => {
+    expect(isRawGithubHref('')).toBe(false);
+    expect(isRawGithubHref(undefined)).toBe(false);
+    expect(isRawGithubHref('raw.githubusercontent.com')).toBe(false);
+    expect(isRawGithubHref('https://raw.githubusercontent.com')).toBe(true);
+    expect(isRawGithubHref('http://raw.githubusercontent.com')).toBe(true);
+    expect(isRawGithubHref('https://raw.githubusercontent.com')).toBe(true);
+    expect(isRawGithubHref('https://raw.githubusercontent.com/something')).toBe(
+      true
+    );
+  });
+
+  it('scrollToAnchor should scroll to anchor within provided element, or parent if tryParent is true', async () => {
+    const fixture: ComponentFixture<JumpToAnchorTestComponent> =
+      TestBed.createComponent(JumpToAnchorTestComponent);
+
+    fixture.detectChanges();
+    await fixture.whenRenderingDone();
+    await fixture.whenStable();
+
+    const a1: HTMLDivElement = fixture.debugElement.query(
+      By.css('#a1')
+    ).nativeElement;
+
+    expect(scrollToAnchor(a1, 'heading 1', false)).toBeTruthy();
+    expect(scrollToAnchor(a1, 'heading 1', true)).toBeTruthy();
+    expect(scrollToAnchor(a1, 'heading 3', false)).toBeFalsy();
+    expect(scrollToAnchor(a1, 'heading 3', true)).toBeTruthy();
+
+    expect(scrollToAnchor(a1, 'heading 5', false)).toBeFalsy();
+    expect(scrollToAnchor(a1, 'heading 5', true)).toBeFalsy();
+
+    expect(scrollToAnchor(a1, 'heading1', false)).toBeTruthy();
+    expect(scrollToAnchor(a1, 'heading-1', false)).toBeTruthy();
+    expect(scrollToAnchor(a1, 'heading_1', false)).toBeTruthy();
+    expect(scrollToAnchor(a1, 'heading 1!', false)).toBeTruthy();
+  });
+});