react-native-marcus 0.1.1 → 0.2.0

package/src/MarkdownText.web.tsx

@@ -0,0 +1,668 @@
+import { StyleSheet, Text } from "react-native"
+import React from "react"
+import { createPortal } from "react-dom"
+import type { TextProps } from "react-native"
+
+import "./web/MarkdownElements.css"
+
+import { atomsOf, NO_ATOMS, sourceOf } from "./atomUtils"
+import { available as mathAvailable, renderMath, speakMath } from "./math"
+import { flattenText } from "./childrenUtils"
+import { OBJECT_REPLACEMENT, stripSyntax } from "./stripUtils"
+import { createTextMeasurer } from "./web/utils/measureUtils"
+import { parseRangesToHTMLNodes } from "./web/utils/parserUtils"
+import { processMarkdownStyle } from "./web/utils/webStyleUtils"
+import { createParser } from "./parser"
+import type { PartialMarkdownStyle } from "./styleUtils"
+import type { MarkdownLink } from "./stripUtils"
+import type { TreeNode } from "./web/utils/treeUtils"
+
+/**
+ * What to show in place of an image.
+ *
+ * The native contract asks for a view with a definite size, because the text
+ * layout has to know how much room to leave before it lays the line out. The
+ * web has no such requirement -- the browser reflows around whatever turns up
+ * -- but the same callback runs on both, so write it for the stricter one.
+ *
+ * `inline` says whether the image shares its line with anything else, which is
+ * usually what decides how big it should be: alone on a line it is a figure,
+ * and in the middle of a sentence it is a badge. A block marker does not count
+ * as company, and another image does.
+ *
+ * Every string is always a string: an image written without a title is handed
+ * an empty one rather than nothing, so a caller never has to tell the two
+ * apart.
+ */
+type RenderEmbed = (
+  uri: string,
+  alt: string,
+  title: string,
+  inline: boolean,
+) => React.ReactElement | null | undefined
+
+/**
+ * What to draw an SVG with.
+ *
+ * Handed a complete SVG document and the box it belongs in, and expected to
+ * return a view of exactly that size. There is deliberately nothing else in the
+ * signature: everything a picture needs -- the colour, the glyph outlines, the
+ * baseline it sits on -- is either inside the XML already or has been taken
+ * care of by the time this is called, so `<SvgXml xml={xml} width={width}
+ * height={height} />` is the whole of a correct implementation.
+ *
+ * It exists because a renderer for SVG is a dependency, and which one is not
+ * this library's business: `react-native-svg` on native, whatever you like on
+ * the web.
+ *
+ * Returning nothing leaves the drawing out, and the span it stood for still
+ * costs its one character either way.
+ */
+type RenderSVG = (
+  xml: string,
+  width: number,
+  height: number,
+) => React.ReactElement | null | undefined
+
+/**
+ * What to do when a link is pressed.
+ *
+ * The label is the text the link was rendered as, which is all a reader saw of
+ * it: the destination is not in the document any more. Reference links are not
+ * covered -- their destination is written somewhere else and is not resolved
+ * yet -- so they render as links and do nothing.
+ *
+ * Opening the URL is deliberately not done for you: what a link means is the
+ * application's to decide, and a message from a stranger is the last place to
+ * hand an arbitrary URL to `Linking.openURL` without looking at it first.
+ *
+ * Every string is always a string: a link written without a title is handed an
+ * empty one rather than nothing.
+ */
+type OnLinkPress = (uri: string, label: string, title: string) => void
+
+interface MarkdownTextProps extends TextProps {
+  markdownStyle?: PartialMarkdownStyle
+  /**
+   * GFM's strikethrough (`~~a~~`) and bare autolinks (`www.example.com`).
+   *
+   * @default false
+   */
+  gfm?: boolean
+  /**
+   * `@name` mentions, which no flavour of markdown has a notion of.
+   *
+   * @default false
+   */
+  mention?: boolean
+  /**
+   * LaTeX between double dollar signs: `$$x^2$$` inline, and the same on lines
+   * of its own for a block.
+   *
+   * @default false
+   */
+  math?: boolean
+  renderEmbed?: RenderEmbed
+  /**
+   * What to draw a maths span with. Nothing is drawn without it, and `$$x^2$$`
+   * is left on the screen as it was written.
+   */
+  renderSVG?: RenderSVG
+  /**
+   * The language a drawn equation is read out in, as the speech engine names
+   * it: `af`, `ca`, `da`, `de`, `en`, `es`, `fr`, `hi`, `it`, `ko`, `nb`, `nn`
+   * or `sv`.
+   *
+   * What a document is written in and what its reader speaks are two different
+   * questions, and only the application knows the answer to the second, so this
+   * is usually whatever the rest of the interface is translated into. It
+   * changes only how the maths is *said*: the prose around it is read in the
+   * language it was written in, and the drawing itself is the same picture in
+   * every language.
+   *
+   * The rules for one language are around 300KB, so only the ones named in
+   * `withMath(config, { locales })` are in the bundle. A language that is not
+   * is read in English, with a warning in the console saying which line of
+   * Metro config would fix it.
+   *
+   * @default "en"
+   */
+  mathAccessibilityLocale?: string
+  onLinkPress?: OnLinkPress
+}
+
+type MarkdownText = Text & React.Component<MarkdownTextProps>
+
+// `useLayoutEffect` warns when it runs during a server render, and there is no layout to be before
+// on a server anyway. Same seam the input uses.
+const useClientEffect = typeof window === "undefined" ? React.useEffect : React.useLayoutEffect
+
+const NO_SLOTS: HTMLElement[] = []
+
+/**
+ * What maths is sized against when the caller set no size at all, matching what
+ * the native component assumes so the two agree.
+ */
+const DEFAULT_FONT_SIZE = 14
+
+/**
+ * Replaces each placeholder character in the built markup with an empty element
+ * to render an embed or a maths span into.
+ *
+ * The elements have to be made here rather than rendered, because everything
+ * under the host is raw DOM this component built and React knows nothing about
+ * -- so the embeds are portalled into these afterwards, which is the one way to
+ * put a React subtree somewhere React did not put it.
+ *
+ * Text nodes are collected before any of them is split: splitting rewrites the
+ * tree the walker is walking.
+ */
+function mountSlots(host: HTMLElement): HTMLElement[] {
+  const walker = document.createTreeWalker(host, NodeFilter.SHOW_TEXT)
+  // `globalThis` because `Text` in this file is the react-native one.
+  const texts: globalThis.Text[] = []
+
+  while (walker.nextNode()) {
+    texts.push(walker.currentNode as globalThis.Text)
+  }
+
+  const slots: HTMLElement[] = []
+
+  for (const text of texts) {
+    let node = text
+    let index = node.data.indexOf(OBJECT_REPLACEMENT)
+
+    while (index !== -1) {
+      const placeholder = node.splitText(index)
+      const rest = placeholder.splitText(OBJECT_REPLACEMENT.length)
+      const slot = document.createElement("span")
+
+      // Inline-block so the embed sits in the line the way an attachment does
+      // on native, on the baseline and taking the width it asks for.
+      slot.style.display = "inline-block"
+      // `text-indent` is inherited, and an inline-block lays out its own first
+      // line -- so a list item's hanging indent, which is a negative
+      // `text-indent` on the item, shifted the drawing left out of its box and
+      // over the word before it. Nothing in here is a first line of anything.
+      slot.style.textIndent = "0"
+      slot.setAttribute("data-atom", String(slots.length))
+
+      placeholder.replaceWith(slot)
+      slots.push(slot)
+
+      node = rest
+      index = node.data.indexOf(OBJECT_REPLACEMENT)
+    }
+  }
+
+  return slots.length > 0 ? slots : NO_SLOTS
+}
+
+/**
+ * How the list markers are drawn, read off the element they will be drawn in.
+ *
+ * A display renders them rather than showing them, and their size comes from the base font --
+ * whatever the wrapped `Text` resolved to, so it is asked rather than assumed.
+ */
+function markerRendering(host: HTMLElement) {
+  return { display: true, fontSize: parseFloat(window.getComputedStyle(host).fontSize) || 0 }
+}
+
+/** Anything with a scheme this does not name is left without an `href`. */
+const SAFE_SCHEME = /^(?:https?|mailto|tel):/i
+const SCHEME = /^[a-z][a-z0-9+.\-]*:/i
+
+/**
+ * The destination as an `href`, or nothing if it must not become one.
+ *
+ * A browser strips whitespace and control characters before it reads a scheme,
+ * so `java\nscript:alert(1)` is `javascript:` as far as it is concerned, and it
+ * has to be here too. Anything carrying a scheme that is not one of the four
+ * safe ones is refused outright rather than guessed at; a destination with no
+ * scheme is a relative URL and is left to resolve the way any other relative
+ * link on the page does.
+ */
+function hrefFor(uri: string) {
+  const bare = uri.replace(/[\u0000-\u0020]/g, "")
+
+  if (bare === "" || (SCHEME.test(bare) && !SAFE_SCHEME.test(bare))) {
+    return null
+  }
+
+  return uri
+}
+
+/**
+ * Marks the elements a link was built into with the link they belong to, and hands them the
+ * destination when it is one a browser may follow.
+ *
+ * The markup is not one element per link: a label split over two lines is built
+ * into one element per line, and a label with emphasis in it is an element with
+ * more elements inside. So the press is caught on the host and walked back up to
+ * the nearest marked ancestor, and all this has to do is put the mark on every
+ * element that a link's own range produced.
+ *
+ * They are anchors already -- that is the tag `link` is built as, in the input
+ * too, where a link being typed has no destination yet. What is added here is
+ * the `href`, which comes from the document's destinations rather than from its
+ * ranges. With one, the browser shows the destination in the status bar, offers
+ * it to the context menu, opens it in a new tab on a modified click, and a
+ * screen reader announces it; the click handler stops it navigating, because
+ * what a link means is the application's to decide. A destination that cannot
+ * safely become an href gets none -- and an anchor without one is neither in the
+ * tab order nor a link to a screen reader, so those two are said outright.
+ */
+function markLinks(node: TreeNode, links: MarkdownLink[]) {
+  if (node.type === "link") {
+    const index = links.findIndex(
+      (link) => node.start >= link.start && node.start < link.start + link.length,
+    )
+
+    // A reference link has no destination yet, so its label is styled as a link
+    // and left inert rather than marked.
+    if (index !== -1) {
+      const link = links[index]!
+      const href = hrefFor(link.uri)
+      const element = node.element
+
+      if (href !== null) {
+        element.setAttribute("href", href)
+        // Untrusted markdown opened in a new tab has no business reaching back.
+        element.setAttribute("rel", "noopener noreferrer")
+
+        if (link.title !== "") {
+          element.setAttribute("title", link.title)
+        }
+      } else {
+        // Nothing else on the page is reachable by keyboard, and a link a
+        // pointer can press and a keyboard cannot is not a link.
+        element.setAttribute("role", "link")
+        element.setAttribute("tabindex", "0")
+        element.style.cursor = "pointer"
+      }
+
+      element.setAttribute("data-link", String(index))
+    }
+  }
+
+  node.childNodes.forEach((child) => markLinks(child, links))
+}
+
+/**
+ * `Text`, with the markdown in its content rendered rather than shown.
+ *
+ * Built by the same DOM builder the input uses, from the same ranges, so a message and the composer
+ * it was typed in agree by construction -- which on the web means agreeing about indents, about
+ * ribbons drawn as background layers, and about the marker widths those are measured from. The only
+ * difference is the input, where the syntax is still there to be edited.
+ *
+ * Rendered as a real `Text` whose children are then replaced. React only ever writes the stripped
+ * string into the host element -- a lone string child is set with `textContent`, never as a node it
+ * holds on to -- so the effect below is free to put the built markup there instead, and a render
+ * that changes the text simply wipes it and lets the effect rebuild before the frame is painted.
+ * Rendering the plain string rather than nothing also means a prerendered page carries the prose:
+ * `expo export` runs every route through Node, where there is no DOM to build markup with.
+ */
+const MarkdownText = React.forwardRef<MarkdownText, MarkdownTextProps>((props, ref) => {
+  const {
+    markdownStyle: markdownStyleProp,
+    gfm,
+    mention,
+    math,
+    renderEmbed,
+    renderSVG,
+    mathAccessibilityLocale,
+    onLinkPress,
+    children,
+    ...textProps
+  } = props
+
+  const hostRef = React.useRef<HTMLElement | null>(null)
+  const [slots, setSlots] = React.useState<HTMLElement[]>(NO_SLOTS)
+
+  // Whether there is a handler, not which one: a caller who writes the callback
+  // inline would otherwise re-parse the document on every render.
+  const withEmbeds = renderEmbed !== undefined
+  // Maths is only taken out of the text when there is both something to draw it
+  // with and a backend to typeset it -- see `./math`. Left in, `$$x^2$$` is
+  // shown as it was written.
+  const withMath = renderSVG !== undefined && mathAvailable
+  const withLinks = onLinkPress !== undefined
+
+  // The same worklet for as long as the flavour is the same one, so the
+  // document is only re-parsed when the document itself changes.
+  const parser = createParser({ gfm, mention, math })
+
+  const markdown = React.useMemo(() => {
+    const text = flattenText(children)
+
+    return text === null
+      ? null
+      : stripSyntax(text, parser(text), {
+          embeds: withEmbeds,
+          math: withMath,
+          links: withLinks,
+        })
+  }, [children, parser, withEmbeds, withMath, withLinks])
+
+  // Both kinds of placeholder in the order they stand in the text, which is the
+  // order `mountSlots` makes the slots in.
+  const atoms = React.useMemo(
+    () => (markdown === null ? NO_ATOMS : atomsOf(markdown)),
+    [markdown],
+  )
+
+  // Read off this element's own style rather than the computed one, so the
+  // numbers the maths is drawn at are the numbers the native component would
+  // draw it at.
+  const { fontSize, color } = React.useMemo(() => {
+    const flattened = StyleSheet.flatten(textProps.style)
+
+    return {
+      fontSize:
+        typeof flattened?.fontSize === "number" ? flattened.fontSize : DEFAULT_FONT_SIZE,
+      color: typeof flattened?.color === "string" ? flattened.color : undefined,
+    }
+  }, [textProps.style])
+
+  // Drawn during render rather than at portal time, because the depth a maths
+  // span reports has to be on its slot before the frame is painted.
+  const drawn = React.useMemo(
+    () =>
+      atoms.map((atom) => {
+        if (atom.kind === "embed") {
+          return {
+            element: renderEmbed?.(atom.uri, atom.alt, atom.title, atom.inline) ?? null,
+            depth: 0,
+            // Whatever the caller's element measures: only it knows how big an
+            // embed is, and that is what `renderEmbed` promises to say.
+            box: null as { width: number; height: number } | null,
+            // An image's `alt` is its accessible name by every spec there is,
+            // and left empty it declares the image decorative.
+            label: atom.alt,
+            role: "img",
+            // Nothing: an image's alt text is prose, written in the language
+            // the document is written in, and saying otherwise would have a
+            // screen reader read it in the wrong voice.
+            lang: "",
+            source: sourceOf(atom),
+          }
+        }
+
+        const rendered = renderMath(atom.tex, atom.display, fontSize, color)
+
+        return {
+          element:
+            rendered === null
+              ? null
+              : renderSVG?.(rendered.svg, rendered.width, rendered.height),
+          depth: rendered?.depth ?? 0,
+          box: rendered === null ? null : { width: rendered.width, height: rendered.height },
+          // What the picture says, rather than the TeX it was written as: a
+          // reader who asked for a document did not ask for its source code.
+          label: speakMath(atom.tex, atom.display, mathAccessibilityLocale) ?? atom.tex,
+          role: "math",
+          // The language the label is in, which is the one thing on the page
+          // that may differ from the document's own: a screen reader picks its
+          // voice from this, and French read in an English voice is worse than
+          // no voice at all.
+          lang: mathAccessibilityLocale ?? "",
+          // What a copy puts on the clipboard in place of the picture: the
+          // markdown it was written as, so that pasting it back gives the
+          // document it came from rather than a hole where an equation was.
+          source: sourceOf(atom),
+        }
+      }),
+    [atoms, renderEmbed, renderSVG, fontSize, color, mathAccessibilityLocale],
+  )
+
+  const markdownStyle = React.useMemo(
+    () => processMarkdownStyle(markdownStyleProp),
+    [markdownStyleProp],
+  )
+
+  // What React writes into the host, and so what a prerendered page carries. The placeholders go:
+  // they only mean anything to the markup the effect builds, and a page rendered in Node -- where
+  // there is no DOM to build that markup with -- would otherwise show a row of tofu.
+  const content = React.useMemo(() => {
+    if (markdown === null) {
+      return null
+    }
+
+    return markdown.text.includes(OBJECT_REPLACEMENT)
+      ? markdown.text.split(OBJECT_REPLACEMENT).join("")
+      : markdown.text
+  }, [markdown])
+
+  useClientEffect(() => {
+    const host = hostRef.current
+    if (!host || markdown === null) {
+      return
+    }
+
+    const { dom, tree } = parseRangesToHTMLNodes(
+      markdown.text,
+      markdown.ranges,
+      true,
+      markdownStyle,
+      false,
+      // Measured against this element, so marker widths come out in the font the text is actually
+      // drawn in rather than the document's default.
+      createTextMeasurer(host),
+      // A display renders the list markers rather than showing them, sized from the font this
+      // element renders at: the base font, which is the wrapped `Text`'s own.
+      markerRendering(host),
+    )
+
+    if (markdown.links.length > 0) {
+      markLinks(tree, markdown.links)
+    }
+
+    host.replaceChildren(...Array.from(dom.childNodes))
+
+    const next = atoms.length > 0 ? mountSlots(host) : NO_SLOTS
+
+    // Both empty is the overwhelmingly common case, and setting state there would re-render every
+    // document that has no embeds in it for nothing.
+    setSlots((previous) => (previous === NO_SLOTS && next === NO_SLOTS ? previous : next))
+    // React wipes the host with `textContent` whenever the string child changes, which is exactly
+    // when `markdown` does, so these two are all it takes to be sure the markup is back before the
+    // frame is painted.
+  }, [markdown, markdownStyle, atoms])
+
+  // Everything about a slot that is the slot's own business rather than the
+  // caller's: it is the inline-level box, so aligning anything inside it would
+  // only move that box's contents, and it is the element in the accessibility
+  // tree, so it is the one thing that can be given a name. Its own effect, so
+  // that a caller redrawing from state brings all three with it.
+  useClientEffect(() => {
+    slots.forEach((slot, index) => {
+      const content = drawn[index]
+      const depth = content?.depth ?? 0
+
+      // The depth the maths hangs below the baseline, which on the web is the
+      // same displacement by another name.
+      slot.style.verticalAlign = depth === 0 ? "" : `${-depth}px`
+
+      // The box the drawing was measured for, stated rather than shrink-wrapped.
+      // An inline-block with no width of its own is shrink-to-fit, and
+      // shrink-to-fit is capped by what is left of the line -- so a wide
+      // expression near a margin got a box narrower than its own picture and the
+      // picture hung out of it, over the words beside it. Native reserves the
+      // measured box; this is the same thing said in CSS.
+      if (content?.box) {
+        slot.style.width = `${content.box.width}px`
+        slot.style.height = `${content.box.height}px`
+      } else {
+        slot.style.width = ""
+        slot.style.height = ""
+      }
+
+      if (content === undefined || content.label === "") {
+        slot.removeAttribute("role")
+        slot.removeAttribute("aria-label")
+      } else {
+        // `math` and `img` both take a name from the author, so the label wins
+        // over whatever glyph outlines are underneath it.
+        slot.setAttribute("role", content.role)
+        slot.setAttribute("aria-label", content.label)
+      }
+
+      if (content?.lang) {
+        slot.setAttribute("lang", content.lang)
+      } else {
+        slot.removeAttribute("lang")
+      }
+
+      if (content?.source) {
+        slot.setAttribute("data-tex", content.source)
+      } else {
+        slot.removeAttribute("data-tex")
+      }
+    })
+  }, [slots, drawn])
+
+  // Copying maths gives back the markdown it was written as.
+  //
+  // A selection dragged across a drawing copies whatever text is under it,
+  // which for an SVG is nothing at all -- so a message copied out of a chat
+  // arrives with a hole where its equation was. The clipboard is the one place
+  // the source is worth more than the picture, and this is the only hook the
+  // web offers: the copy is intercepted, the fragment the browser was about to
+  // serialise is walked, and every slot in it is swapped for the `$$…$$` it
+  // stands for.
+  //
+  // On the document rather than the host, because that is where a copy lands
+  // when the selection reaches past this element. It is left alone unless the
+  // fragment actually holds one of these slots.
+  useClientEffect(() => {
+    const host = hostRef.current
+
+    if (!host || !drawn.some((content) => content.source !== "")) {
+      return undefined
+    }
+
+    const onCopy = (event: ClipboardEvent) => {
+      const selection = window.getSelection()
+
+      if (!selection || selection.isCollapsed || selection.rangeCount === 0) {
+        return
+      }
+
+      const fragment = selection.getRangeAt(0).cloneContents()
+      const maths = fragment.querySelectorAll("[data-tex]")
+
+      if (maths.length === 0) {
+        return
+      }
+
+      for (const element of Array.from(maths)) {
+        element.replaceWith(document.createTextNode(element.getAttribute("data-tex") ?? ""))
+      }
+
+      event.clipboardData?.setData("text/plain", fragment.textContent ?? "")
+      event.preventDefault()
+    }
+
+    document.addEventListener("copy", onCopy)
+
+    return () => document.removeEventListener("copy", onCopy)
+  }, [drawn])
+
+  // On the host rather than on each link: the markup underneath is rebuilt from
+  // scratch whenever the text changes, and a listener per element would have to
+  // be attached again every time.
+  useClientEffect(() => {
+    const host = hostRef.current
+
+    if (
+      !host ||
+      markdown === null ||
+      onLinkPress === undefined ||
+      markdown.links.length === 0
+    ) {
+      return undefined
+    }
+
+    const { links } = markdown
+
+    const linkAt = (target: EventTarget | null) => {
+      const element = target instanceof Element ? target.closest("[data-link]") : null
+
+      return element === null ? undefined : links[Number(element.getAttribute("data-link"))]
+    }
+
+    const press = (event: MouseEvent | KeyboardEvent) => {
+      const link = linkAt(event.target)
+
+      if (link === undefined) {
+        return
+      }
+
+      // A modified click belongs to the browser: on an anchor it opens the
+      // destination in a new tab or a new window, which is what the reader
+      // asked for and something no callback can do for them.
+      if (
+        "button" in event &&
+        (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+      ) {
+        return
+      }
+
+      event.preventDefault()
+      onLinkPress(link.uri, link.label, link.title)
+    }
+
+    const onKeyDown = (event: KeyboardEvent) => {
+      // Enter and not Space: Space activates a button, and scrolls everywhere
+      // else, which is what a reader who has tabbed onto a link expects of it.
+      if (event.key === "Enter") {
+        press(event)
+      }
+    }
+
+    host.addEventListener("click", press as EventListener)
+    host.addEventListener("keydown", onKeyDown as EventListener)
+
+    return () => {
+      host.removeEventListener("click", press as EventListener)
+      host.removeEventListener("keydown", onKeyDown as EventListener)
+    }
+  }, [markdown, onLinkPress])
+
+  const setRef = React.useCallback(
+    (node: unknown) => {
+      hostRef.current = node as HTMLElement | null
+
+      if (typeof ref === "function") {
+        ref(node as MarkdownText)
+      } else if (ref) {
+        // eslint-disable-next-line no-param-reassign
+        ref.current = node as MarkdownText
+      }
+    },
+    [ref],
+  )
+
+  return (
+    <>
+      <Text {...textProps} ref={setRef as never}>
+        {markdown === null ? children : content}
+      </Text>
+      {slots.map((slot, index) => {
+        const content = drawn[index]
+
+        // The slots were made from this very `markdown`, so they line up -- but a render between a
+        // text change and the effect that follows it can still see the previous set, one entry
+        // longer than the new document has placeholders.
+        return content?.element == null
+          ? null
+          : createPortal(content.element, slot, String(index))
+      })}
+    </>
+  )
+})
+
+export type { MarkdownTextProps, OnLinkPress, RenderEmbed, RenderSVG }
+
+export default MarkdownText