feat!: create data dictionary table cell for displaying markdown (#453)

package.json

@@ -62,6 +62,11 @@
     "jest-fetch-mock": "^3.0.3",
     "prettier": "^2.8.3",
     "prettier-plugin-organize-imports": "^3.2.2",
+    "rehype-raw": "^7.0.0",
+    "rehype-react": "^8.0.0",
+    "rehype-sanitize": "^6.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-rehype": "^11.1.2",
     "storybook": "^8.6.4",
     "ts-jest": "^29.2.5",
     "typescript": "^5.5.4"

src/components/MarkdownRenderer/components/Anchor/anchor.tsx

@@ -0,0 +1,34 @@
+import React, { AnchorHTMLAttributes, ClassAttributes } from "react";
+import { Link } from "../../../Links/components/Link/link";
+import { BaseComponentProps } from "../../../types";
+
+/**
+ * rehype-sanitize's default schema allows only a limited set of attributes on <a> elements:
+ * - aria-*
+ * - className
+ * - data-footnote-backref
+ * - data-footnote-ref
+ * - href
+ *
+ * By default, attributes such as:
+ * - download
+ * - rel
+ * - target
+ * are not permitted and will be stripped from anchor tags during sanitization.
+ *
+ * Note: This component currently does not support these excluded attributes.
+ */
+
+export const Anchor = (
+  props: BaseComponentProps &
+    ClassAttributes<HTMLAnchorElement> &
+    AnchorHTMLAttributes<HTMLAnchorElement>
+): JSX.Element => {
+  return (
+    <Link
+      className={props.className}
+      label={props.children}
+      url={props.href || ""}
+    />
+  );
+};

src/components/MarkdownRenderer/components/Table/table.styles.ts

@@ -0,0 +1,41 @@
+import styled from "@emotion/styled";
+import { PALETTE } from "../../../../styles/common/constants/palette";
+import { textBody500 } from "../../../../styles/common/mixins/fonts";
+
+export const StyledTable = styled("table")`
+  border-collapse: collapse;
+  margin: 16px 0;
+  table-layout: fixed;
+  width: 100%;
+
+  thead {
+    all: unset;
+    display: table-header-group;
+  }
+
+  tbody {
+    all: unset;
+    display: table-row-group;
+  }
+
+  tr {
+    all: unset;
+    display: table-row;
+  }
+
+  td,
+  th {
+    display: table-cell;
+    padding: 2px 4px;
+  }
+
+  th {
+    ${textBody500}
+    border-bottom: 1px solid ${PALETTE.SMOKE_MAIN};
+  }
+
+  td {
+    font: inherit;
+    overflow-wrap: break-word;
+  }
+`;

src/components/MarkdownRenderer/components/Table/table.tsx

@@ -0,0 +1,13 @@
+import { BaseComponentProps } from "components/types";
+import React, { ClassAttributes, TableHTMLAttributes } from "react";
+import { StyledTable } from "./table.styles";
+
+export const Table = (
+  props: BaseComponentProps &
+    ClassAttributes<HTMLTableElement> &
+    TableHTMLAttributes<HTMLTableElement>
+): JSX.Element => {
+  return (
+    <StyledTable className={props.className}>{props.children}</StyledTable>
+  );
+};

src/components/MarkdownRenderer/constants.ts

@@ -0,0 +1,8 @@
+import { Components } from "rehype-react";
+import { Anchor } from "./components/Anchor/anchor";
+import { Table } from "./components/Table/table";
+
+export const COMPONENTS: Partial<Components> = {
+  a: Anchor,
+  table: Table,
+};

src/components/MarkdownRenderer/markdownRenderer.styles.ts

@@ -0,0 +1,16 @@
+import styled from "@emotion/styled";
+
+// See https://github.com/emotion-js/emotion/issues/1105.
+// See https://github.com/emotion-js/emotion/releases/tag/%40emotion%2Fcache%4011.10.2.
+const ignoreSsrWarning =
+  "/* emotion-disable-server-rendering-unsafe-selector-warning-please-do-not-use-this-the-warning-exists-for-a-reason */";
+
+export const StyledContainer = styled("div")`
+  > *:first-child:not(style)${ignoreSsrWarning} {
+    margin-top: 0;
+  }
+
+  > *:last-child:not(style)${ignoreSsrWarning} {
+    margin-bottom: 0;
+  }
+`;

src/components/MarkdownRenderer/markdownRenderer.tsx

@@ -0,0 +1,62 @@
+import { Typography } from "@mui/material";
+import React, { useEffect, useState } from "react";
+import * as production from "react/jsx-runtime";
+import rehypeRaw from "rehype-raw";
+import rehypeReact, { Components } from "rehype-react";
+import rehypeSanitize, { defaultSchema } from "rehype-sanitize";
+import remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import remarkRehype from "remark-rehype";
+import { unified } from "unified";
+import { TYPOGRAPHY_PROPS } from "../../styles/common/mui/typography";
+import { COMPONENTS } from "./constants";
+import { StyledContainer } from "./markdownRenderer.styles";
+import { MarkdownRendererProps } from "./types";
+
+export const MarkdownRenderer = ({
+  className,
+  components = COMPONENTS,
+  value,
+}: MarkdownRendererProps): JSX.Element => {
+  const [element, setElement] = useState<JSX.Element | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [componentOptions] = useState<Partial<Components>>(components);
+
+  useEffect(() => {
+    let cancelled = false;
+    setError(null);
+
+    const processor = unified()
+      .use(remarkParse)
+      .use(remarkGfm)
+      .use(remarkRehype, { allowDangerousHtml: true })
+      .use(rehypeRaw)
+      .use(rehypeSanitize, defaultSchema)
+      .use(rehypeReact, { ...production, components: componentOptions });
+
+    processor
+      .process(value)
+      .then((file) => {
+        if (!cancelled) setElement(file?.result);
+      })
+      .catch((err) => {
+        if (!cancelled) setError(err.message);
+      });
+
+    return (): void => {
+      cancelled = true;
+    };
+  }, [componentOptions, value]);
+
+  if (error)
+    return (
+      <Typography
+        color={TYPOGRAPHY_PROPS.COLOR.ERROR}
+        variant={TYPOGRAPHY_PROPS.VARIANT.TEXT_BODY_SMALL_400}
+      >
+        {error}
+      </Typography>
+    );
+
+  return <StyledContainer className={className}>{element}</StyledContainer>;
+};

src/components/MarkdownRenderer/types.ts

@@ -0,0 +1,7 @@
+import { Components } from "rehype-react";
+import { BaseComponentProps } from "../types";
+
+export interface MarkdownRendererProps extends BaseComponentProps {
+  components?: Partial<Components>;
+  value: string;
+}

src/components/Table/components/TableCell/components/MarkdownCell/markdownCell.styles.ts

@@ -0,0 +1,31 @@
+import styled from "@emotion/styled";
+import { PALETTE } from "../../../../../../styles/common/constants/palette";
+import { MarkdownRenderer } from "../../../../../MarkdownRenderer/markdownRenderer";
+
+export const StyledMarkdownRenderer = styled(MarkdownRenderer)`
+  align-self: flex-start;
+
+  code {
+    all: unset;
+    font: inherit;
+    font-family: Roboto Mono, monospace;
+  }
+
+  h2,
+  h3,
+  h4,
+  h5,
+  h6 {
+    margin: 8px 0;
+  }
+
+  hr {
+    border: none;
+    border-bottom: 1px solid ${PALETTE.SMOKE_MAIN};
+    margin: 16px 0;
+  }
+
+  p {
+    font: inherit;
+  }
+`;

src/components/Table/components/TableCell/components/MarkdownCell/markdownCell.tsx

@@ -0,0 +1,29 @@
+import { CellContext, RowData } from "@tanstack/react-table";
+import { BaseComponentProps } from "components/types";
+import React from "react";
+import { COMPONENTS } from "../../../../../MarkdownRenderer/constants";
+import { StyledMarkdownRenderer } from "./markdownCell.styles";
+import { MarkdownCellProps } from "./types";
+
+export const MarkdownCell = <
+  T extends RowData,
+  TValue extends MarkdownCellProps = MarkdownCellProps
+>({
+  className,
+  column,
+  getValue,
+}: BaseComponentProps & CellContext<T, TValue>): JSX.Element | null => {
+  const props = getValue();
+  if (!props) return null;
+  const { values } = props;
+  const columnDef = column?.columnDef;
+  const columnMeta = columnDef?.meta;
+  const components = columnMeta?.components;
+  return (
+    <StyledMarkdownRenderer
+      className={className}
+      components={{ ...COMPONENTS, ...components }}
+      value={values}
+    />
+  );
+};

src/components/Table/components/TableCell/components/MarkdownCell/stories/args.ts

@@ -0,0 +1,17 @@
+import { ComponentProps } from "react";
+import { MarkdownCell } from "../markdownCell";
+import { GetValue } from "./types";
+
+export const DEFAULT_ARGS: Partial<ComponentProps<typeof MarkdownCell>> = {
+  getValue: (() => ({
+    values:
+      '| Key | Annotator | Value |\n| --- | --- | --- |\n| `tissue_ontology_term_id` | Curator | categorical with `str` categories. This **MUST** be the UBERON or CL term that best describes the tissue the cell was derived from, depending on the sample type. |\n\n**Mapping guidance**\n\n| For | Use |\n| --- | --- |\n| Tissue | STRONGLY RECOMMENDED to be an UBERON term&nbsp;<br />(e.g. [`UBERON:0008930`](http://purl.obolibrary.org/obo/UBERON_0008930) for a *somatosensory cortex* tissue sample) |\n| Cell culture | MUST be a CL term appended with \\" (cell culture)\\"&nbsp;<br />(e.g. [`CL:0000057`](http://purl.obolibrary.org/obo/CL_0000057) **(cell culture)** for the *WTC-11* cell line) |\n| Organoid | MUST be an UBERON term appended with \\" (organoid)\\"&nbsp;<br />(e.g. [`UBERON:0000955`](http://purl.obolibrary.org/obo/UBERON_0000955) **(organoid)** for a *brain organoid*) |\n| Enriched / sorted / isolated cells from a tissue | MUST be an UBERON or CL term and **SHOULD NOT** use terms that do not capture the tissue of origin.<br /><br />• *CD3+ kidney cells* → [`UBERON:0002113`](https://www.ebi.ac.uk/ols/ontologies/uberon/terms?iri=http://purl.obolibrary.org/obo/UBERON_0002113) (*kidney*) instead of [`CL:000084`](https://www.ebi.ac.uk/ols/ontologies/cl/terms?iri=http://purl.obolibrary.org/obo/CL_0000084) (*T cell*).<br />• *EPCAM+ cervical cells* → [`CL:0000066`](https://www.ebi.ac.uk/ols/ontologies/cl/terms?iri=http://purl.obolibrary.org/obo/CL_0000066) (*epithelial cell* of the cervix). |\n\n---\n\nWhen a dataset is uploaded, the **cellxgene Data Portal** MUST automatically add the matching human-readable name for the corresponding ontology term to the `obs` dataframe. Curators **MUST NOT** annotate the following columns.\n\n### `assay`\n\n| Key | Annotator | Value |\n| --- | --- | --- |\n| `assay` | Data Portal | categorical with `str` categories. This **MUST** be the human-readable name assigned to the value of `assay_ontology_term_id`. |',
+  })) as GetValue,
+};
+
+export const WITH_HTML_ARGS: Partial<ComponentProps<typeof MarkdownCell>> = {
+  getValue: (() => ({
+    values:
+      "Hello <br />World <a href='https://www.example.com'>example link</a>",
+  })) as GetValue,
+};

src/components/Table/components/TableCell/components/MarkdownCell/stories/constants.ts

@@ -0,0 +1,11 @@
+import styled from "@emotion/styled";
+import { Anchor } from "../../../../../../MarkdownRenderer/components/Anchor/anchor";
+
+/**
+ * Styled anchor component for testing purposes.
+ */
+
+export const STYLED_ANCHOR = styled(Anchor)`
+  background-color: green;
+  color: white;
+` as typeof Anchor;

src/components/Table/components/TableCell/components/MarkdownCell/stories/markdownCell.stories.tsx

@@ -0,0 +1,37 @@
+import { Box } from "@mui/material";
+import { Meta, StoryObj } from "@storybook/react";
+import React from "react";
+import { PALETTE } from "../../../../../../../styles/common/constants/palette";
+import { MarkdownCell } from "../markdownCell";
+import { DEFAULT_ARGS, WITH_HTML_ARGS } from "./args";
+
+const meta: Meta<typeof MarkdownCell> = {
+  component: MarkdownCell,
+  decorators: [
+    (Story): JSX.Element => (
+      <Box
+        sx={{
+          backgroundColor: PALETTE.COMMON_WHITE,
+          fontSize: "14px",
+          lineHeight: "20px",
+          padding: 3,
+          width: 480,
+        }}
+      >
+        <Story />
+      </Box>
+    ),
+  ],
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: DEFAULT_ARGS,
+};
+
+export const WithHtml: Story = {
+  args: WITH_HTML_ARGS,
+};

src/components/Table/components/TableCell/components/MarkdownCell/stories/types.ts

@@ -0,0 +1,4 @@
+import { CellContext, RowData } from "@tanstack/react-table";
+import { MarkdownCellProps } from "../types";
+
+export type GetValue = CellContext<RowData, MarkdownCellProps>["getValue"];

src/components/Table/components/TableCell/components/MarkdownCell/types.ts

@@ -0,0 +1,3 @@
+export type MarkdownCellProps = {
+  values: string;
+};

src/styles/common/mui/typography.ts

@@ -6,6 +6,7 @@ type TypographyPropsOptions = {
 };
 
 const COLOR: Record<string, TypographyOwnProps["color"]> = {
+  ERROR: "error",
   INHERIT: "inherit",
   INK_LIGHT: "ink.light",
   INK_MAIN: "ink.main",