@player-ui/markdown-plugin 0.3.1--canary.193.5900

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@player-ui/markdown-plugin",
+  "version": "0.3.1--canary.193.5900",
+  "private": false,
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "peerDependencies": {
+    "@player-ui/player": "0.3.1--canary.193.5900",
+    "@player-ui/types": "0.3.1--canary.193.5900"
+  },
+  "dependencies": {
+    "tapable-ts": "^0.2.3",
+    "mdast-util-from-markdown": "^2.0.0",
+    "@babel/runtime": "7.15.4"
+  },
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.esm.js",
+  "typings": "dist/index.d.ts",
+  "sideEffects": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/player-ui/player-ui"
+  },
+  "bugs": {
+    "url": "https://github.com/player-ui/player-ui/issues"
+  },
+  "homepage": "https://player-ui.github.io",
+  "contributors": [
+    {
+      "name": "Adam Dierkens",
+      "url": "https://github.com/adierkens"
+    },
+    {
+      "name": "Spencer Hamm",
+      "url": "https://github.com/spentacular"
+    },
+    {
+      "name": "Harris Borawski",
+      "url": "https://github.com/hborawski"
+    },
+    {
+      "name": "Jeremiah Zucker",
+      "url": "https://github.com/sugarmanz"
+    },
+    {
+      "name": "Ketan Reddy",
+      "url": "https://github.com/KetanReddy"
+    },
+    {
+      "name": "Brocollie08",
+      "url": "https://github.com/brocollie08"
+    },
+    {
+      "name": "Kelly Harrop",
+      "url": "https://github.com/kharrop"
+    },
+    {
+      "name": "Alejandro Fimbres",
+      "url": "https://github.com/lexfm"
+    },
+    {
+      "name": "Rafael Campos",
+      "url": "https://github.com/rafbcampos"
+    }
+  ],
+  "bundle": "./dist/markdown-plugin.prod.js"
+}

package/src/index.ts

@@ -0,0 +1,50 @@
+import type { Player, PlayerPlugin } from '@player-ui/player';
+import { resolveDataRefsInString, NodeType } from '@player-ui/player';
+import type { Mappers } from './types';
+import { parseAssetMarkdownContent } from './utils';
+
+export * from './types';
+
+/**
+ * A plugin that parses markdown written into text assets using the given converters for markdown features into existing assets.
+ */
+export class MarkdownPlugin implements PlayerPlugin {
+  name = 'MarkdownPlugin';
+
+  private mappers: Mappers;
+
+  constructor(mappers: Mappers) {
+    this.mappers = mappers;
+  }
+
+  apply(player: Player) {
+    player.hooks.view.tap(this.name, (view) => {
+      view.hooks.resolver.tap(this.name, (resolver) => {
+        resolver.hooks.beforeResolve.tap(this.name, (node, options) => {
+          if (node?.type === NodeType.Asset && node.value.type === 'markdown') {
+            const resolvedContent = resolveDataRefsInString(
+              node.value.value as string,
+              {
+                evaluate: options.evaluate,
+                model: options.data.model,
+              }
+            );
+
+            const parsed = parseAssetMarkdownContent({
+              asset: {
+                ...node.value,
+                value: resolvedContent,
+              },
+              mappers: this.mappers,
+              parser: options.parseNode,
+            });
+
+            return parsed;
+          }
+
+          return node;
+        });
+      });
+    });
+  }
+}

package/src/types.ts

@@ -0,0 +1,144 @@
+import type { Asset } from '@player-ui/types';
+
+export interface BaseArgs {
+  /**
+   * Unparsed Asset
+   */
+  originalAsset: Asset;
+}
+
+export type LiteralMapper<T extends object = object> = (
+  args: {
+    /**
+     * markdown element value
+     */
+    value: string;
+  } & BaseArgs &
+    T
+) => Asset;
+
+export type CompositeMapper<T extends object = object> = (
+  args: {
+    /**
+     * array of assets resulted from the recursion over the AST node children
+     */
+    value: Asset[];
+  } & BaseArgs &
+    T
+) => Asset;
+
+export type FallbackMapper = (
+  args: {
+    /**
+     * markdown element value
+     */
+    value: string | Asset[];
+  } & BaseArgs
+) => Asset;
+
+export interface Mappers {
+  /**
+   * required text Asset
+   */
+  text: LiteralMapper;
+  /**
+   * required paragraph (composite) Asset
+   */
+  paragraph: CompositeMapper;
+  /**
+   * required collection Asset to wrap arrays of assets
+   */
+  collection: CompositeMapper;
+  /**
+   * strong markdown (e.g. **bold**)
+   */
+  strong?: CompositeMapper;
+  /**
+   * emphasis markdown (e.g. *italic*)
+   */
+  emphasis?: CompositeMapper;
+  /**
+   * blockquote markdown (e.g. > blockquote)
+   */
+  blockquote?: CompositeMapper;
+  /**
+   * ordered or unordered list markdown (e.g. 1. item\n2. item, - item\n- item)
+   */
+  list?: CompositeMapper<{
+    /**
+     * Whether the list is ordered or not.
+     */
+    ordered: boolean;
+    /**
+     * The starting list number.
+     */
+    start?: number;
+  }>;
+  /**
+   * horizontalRule markdown (e.g. ---)
+   */
+  horizontalRule?: LiteralMapper;
+  /**
+   * link markdown (e.g. `[text](url)`)
+   */
+  link?: CompositeMapper<{
+    /**
+     * Link URL
+     */
+    href: string;
+  }>;
+  /**
+   * image markdown (e.g. `![alt](url)`)
+   */
+  image?: LiteralMapper<{
+    /**
+     * Image source URL
+     */
+    src: string;
+  }>;
+  /**
+   * code block markdown (e.g. ```code```)
+   */
+  code?: LiteralMapper<{
+    /**
+     * The language of the code block.
+     */
+    lang?: string;
+  }>;
+  /**
+   * heading markdown (e.g. # heading)
+   */
+  heading?: CompositeMapper<{
+    /**
+     * The heading depth.
+     */
+    depth: number;
+  }>;
+  /**
+   * inline code markdown (e.g. `code`)
+   */
+  inlineCode?: LiteralMapper;
+  /**
+   * list item markdown (e.g. - item)
+   */
+  listItem?: CompositeMapper;
+}
+
+export type Transformer<T = any> = (args: {
+  /**
+   * AST Node (e.g. Link)
+   */
+  astNode: T;
+  /**
+   * Player Asset
+   */
+  asset: Asset;
+  /**
+   * Record off mappers (markdown element -> Asset)
+   */
+  mappers: Mappers;
+  /**
+   * Record of parsers (e.g., { link :linkParser })
+   */
+  transformers: Record<string, Transformer>;
+}) => Asset;

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './markdownParser';
+export * from './transformers';

package/src/utils/markdownParser.ts

@@ -0,0 +1,67 @@
+import type { Node, ParseObjectOptions } from '@player-ui/player';
+import { NodeType } from '@player-ui/player';
+import type { Asset } from '@player-ui/types';
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import type { Mappers } from '../types';
+import { transformers } from './transformers';
+
+/**
+ * Parses markdown content using a provided mappers record.
+ */
+export function parseAssetMarkdownContent({
+  asset,
+  mappers,
+  parser,
+}: {
+  /**
+   * Asset to be parsed
+   */
+  asset: Asset;
+  /**
+   * Mappers record of AST Node to Player Content
+   *
+   * @see {@link Mappers}
+   */
+  mappers: Mappers;
+  /**
+   * Parser object to AST
+   */
+  parser?: (
+    obj: object,
+    type?: Node.ChildrenTypes,
+    options?: ParseObjectOptions
+  ) => Node.Node | null;
+}): Node.Node | null {
+  const { children } = fromMarkdown(asset.value as string);
+  const isMultiParagraph = children.length > 1;
+
+  if (isMultiParagraph) {
+    const value = children.map((node) => {
+      const transformer = transformers[node.type as keyof typeof transformers];
+      return transformer({
+        astNode: node as any,
+        asset,
+        mappers,
+        transformers,
+      });
+    });
+
+    const collection = mappers.collection({
+      originalAsset: asset,
+      value,
+    });
+
+    return parser?.(collection, NodeType.Asset) || null;
+  }
+
+  const transformer =
+    transformers[children[0].type as keyof typeof transformers];
+  const content = transformer({
+    astNode: children[0] as any,
+    asset,
+    mappers,
+    transformers,
+  });
+
+  return parser?.(content, NodeType.Asset) || null;
+}

package/src/utils/transformers.ts

@@ -0,0 +1,327 @@
+import type { Asset } from '@player-ui/types';
+import type {
+  Blockquote,
+  Code,
+  Emphasis,
+  Heading,
+  Image,
+  InlineCode,
+  Link,
+  List,
+  ListItem,
+  Paragraph,
+  Strong,
+  Text,
+  ThematicBreak,
+} from 'mdast-util-from-markdown/lib';
+import type { Transformer } from '../types';
+
+/**
+ * Swap markdown type to text
+ */
+function swapMarkdownType(asset: Asset): Asset {
+  return { ...asset, type: 'text' };
+}
+
+/**
+ * Transforms Text AST Node into Player Content
+ */
+const textTransformer: Transformer<Text> = ({ astNode, asset, mappers }) => {
+  const { value } = astNode;
+
+  return mappers.text({
+    originalAsset: asset,
+    value,
+  });
+};
+
+/**
+ * Transforms Emphasis AST Node into Player Content
+ */
+const emphasisTransformer: Transformer<Emphasis> = ({
+  astNode,
+  asset,
+  mappers,
+  transformers,
+}) => {
+  if (mappers.emphasis) {
+    const { children } = astNode;
+
+    const value = children.map((node) =>
+      transformers[node.type]({ astNode: node, asset, mappers, transformers })
+    );
+
+    return mappers.emphasis({
+      originalAsset: asset,
+      value,
+    });
+  }
+
+  return swapMarkdownType(asset);
+};
+
+/**
+ * Transforms Strong AST Node into Player Content
+ */
+const strongTransformer: Transformer<Strong> = ({
+  astNode,
+  asset,
+  mappers,
+  transformers,
+}) => {
+  if (mappers.strong) {
+    const { children } = astNode;
+
+    const value = children.map((node) =>
+      transformers[node.type]({ astNode: node, asset, mappers, transformers })
+    );
+
+    return mappers.strong({
+      originalAsset: asset,
+      value,
+    });
+  }
+
+  return swapMarkdownType(asset);
+};
+
+/**
+ * Transforms Paragraph AST Node into Player Content
+ */
+const paragraphTransformer: Transformer<Paragraph> = ({
+  astNode,
+  asset,
+  mappers,
+  transformers,
+}) => {
+  const { children } = astNode;
+
+  if (
+    children.every(({ type }) => Boolean(mappers[type as keyof typeof mappers]))
+  ) {
+    const value = children.map((node) =>
+      transformers[node.type]({ astNode: node, asset, mappers, transformers })
+    );
+
+    return mappers.paragraph({
+      originalAsset: asset,
+      value,
+    });
+  }
+
+  return swapMarkdownType(asset);
+};
+
+/**
+ * Transforms List AST Node into Player Content
+ */
+const listTransformer: Transformer<List> = ({
+  astNode,
+  asset,
+  mappers,
+  transformers,
+}) => {
+  if (mappers.list) {
+    const { children, ordered, start } = astNode;
+
+    const value = children.map((node) =>
+      transformers[node.type]({ astNode: node, asset, mappers, transformers })
+    );
+
+    return mappers.list({
+      originalAsset: asset,
+      value,
+      ordered: Boolean(ordered),
+      start: start || undefined,
+    });
+  }
+
+  return swapMarkdownType(asset);
+};
+
+/**
+ * Transforms ListItem AST Node into Player Content
+ */
+const listItemTransformer: Transformer<ListItem> = ({
+  astNode,
+  asset,
+  mappers,
+  transformers,
+}) => {
+  const { children } = astNode;
+
+  const value = children.map((node) =>
+    transformers[node.type]({ astNode: node, asset, mappers, transformers })
+  );
+
+  const mapper = mappers.listItem || mappers.paragraph;
+
+  return mapper({
+    originalAsset: asset,
+    value,
+  });
+};
+
+/**
+ * Transforms Link AST Node into Player Content
+ */
+const linkTransformer: Transformer<Link> = ({
+  astNode,
+  asset,
+  mappers,
+  transformers,
+}) => {
+  if (mappers.link) {
+    const { children, url } = astNode;
+
+    const value = children.map((node) =>
+      transformers[node.type]({ astNode: node, asset, mappers, transformers })
+    );
+
+    return mappers.link({
+      originalAsset: asset,
+      href: url,
+      value,
+    });
+  }
+
+  return swapMarkdownType(asset);
+};
+
+/**
+ * Transforms Image AST Node into Player Content
+ */
+const imageTransformer: Transformer<Image> = ({ astNode, asset, mappers }) => {
+  if (mappers.image) {
+    const { title, url, alt } = astNode;
+
+    return mappers.image({
+      originalAsset: asset,
+      src: url,
+      value: title || alt || '',
+    });
+  }
+
+  return swapMarkdownType(asset);
+};
+
+/**
+ * Transforms Blockquote AST Node into Player Content
+ */
+const blockquoteTransformer: Transformer<Blockquote> = ({
+  astNode,
+  asset,
+  mappers,
+  transformers,
+}) => {
+  if (mappers.blockquote) {
+    const { children } = astNode;
+
+    const value = children.map((node) =>
+      transformers[node.type]({ astNode: node, asset, mappers, transformers })
+    );
+
+    return mappers.blockquote({
+      originalAsset: asset,
+      value,
+    });
+  }
+
+  return swapMarkdownType(asset);
+};
+
+/**
+ * Transforms InlineCode AST Node into Player Content
+ */
+const inlineCodeTransformer: Transformer<InlineCode> = ({
+  astNode,
+  asset,
+  mappers,
+}) => {
+  if (mappers.inlineCode) {
+    const { value } = astNode;
+
+    return mappers.inlineCode({
+      originalAsset: asset,
+      value,
+    });
+  }
+
+  return swapMarkdownType(asset);
+};
+
+/**
+ * Transforms Code block AST Node into Player Content
+ */
+const codeTransformer: Transformer<Code> = ({ astNode, asset, mappers }) => {
+  if (mappers.code) {
+    const { value, lang } = astNode;
+
+    return mappers.code({
+      originalAsset: asset,
+      value,
+      lang: lang || undefined,
+    });
+  }
+
+  return swapMarkdownType(asset);
+};
+
+/**
+ * Transforms Horizontal Rule (Thematic Break) AST Node into Player Content
+ */
+const horizontalRuleTransformer: Transformer<ThematicBreak> = ({
+  asset,
+  mappers,
+}) => {
+  if (mappers.horizontalRule) {
+    return mappers.horizontalRule({
+      originalAsset: asset,
+      value: '---',
+    });
+  }
+
+  return swapMarkdownType(asset);
+};
+
+/**
+ * Transforms Heading AST Node into Player Content
+ */
+const headingTransformer: Transformer<Heading> = ({
+  astNode,
+  asset,
+  mappers,
+  transformers,
+}) => {
+  if (mappers.heading) {
+    const { children, depth } = astNode;
+
+    const value = children.map((node) =>
+      transformers[node.type]({ astNode: node, asset, mappers, transformers })
+    );
+
+    return mappers.heading({
+      originalAsset: asset,
+      value,
+      depth,
+    });
+  }
+
+  return swapMarkdownType(asset);
+};
+
+export const transformers: Record<string, Transformer> = {
+  horizontalRule: horizontalRuleTransformer,
+  text: textTransformer,
+  emphasis: emphasisTransformer,
+  strong: strongTransformer,
+  blockquote: blockquoteTransformer,
+  list: listTransformer,
+  listItem: listItemTransformer,
+  link: linkTransformer,
+  image: imageTransformer,
+  paragraph: paragraphTransformer,
+  code: codeTransformer,
+  heading: headingTransformer,
+  inlineCode: inlineCodeTransformer,
+};