react-native-marcus 0.1.0 → 0.2.0

package/src/web/utils/blockUtils.ts

@@ -1,6 +1,10 @@
-import type { PartialMarkdownStyle } from "../../styleUtils"
-import { toNumber } from "./blockLayout"
-import type { LineLayout } from "./blockLayout"
+import type {
+  MarkdownBoxStyle,
+  MarkdownTextStyle,
+} from "../../MarcusTextInputDecoratorViewNativeComponent"
+import type { ResolvedMarkdownStyle } from "../../styleUtils"
+import { SHOWN_MARKERS, toNumber } from "./blockLayout"
+import type { LineLayout, MarkerRendering } from "./blockLayout"
 import type { NodeType } from "./treeUtils"
 
 /**
@@ -22,17 +26,109 @@ function applyStyle(node: HTMLElement, styles: Record<string, string | number |
   })
 }
 
+/**
+ * Everything a `MarkdownTextStyle` says, in CSS.
+ *
+ * One place rather than a line per entry in the switch below, because every styled type now carries
+ * the same set of text attributes: the difference between a mention and a heading is the box around
+ * it and the size it is given, not which properties it understands. `MarkdownFormatter` reads the
+ * same struct into attributed-string attributes on iOS and into spans on Android.
+ *
+ * Undefined properties are dropped by `applyStyle`, so a run inherits whatever the prose around it
+ * is drawn in -- which is what an unset text attribute means on all three platforms.
+ */
+function textStyle(style: Partial<MarkdownTextStyle> | undefined) {
+  if (!style) {
+    return {}
+  }
+
+  return {
+    color: style.color as string | undefined,
+    fontFamily: style.fontFamily,
+    fontSize: style.fontSize,
+    fontStyle: style.fontStyle,
+    fontWeight: style.fontWeight,
+    letterSpacing: style.letterSpacing,
+    lineHeight: style.lineHeight,
+    textDecorationLine: style.textDecorationLine,
+    textDecorationColor: style.textDecorationColor as string | undefined,
+    textDecorationStyle: style.textDecorationStyle,
+    textShadow: textShadow(style),
+  }
+}
+
+/**
+ * React Native's three shadow properties as the one CSS declaration they add up to.
+ *
+ * The offset and the radius stay raw numbers through `processMarkdownStyle` -- an offset is an
+ * object rather than a length, and half a shadow carrying units would not compose -- so the units
+ * are put on here.
+ */
+function textShadow(style: Partial<MarkdownTextStyle>): string | undefined {
+  const color = style.textShadowColor as string | undefined
+  const radius = toNumber(style.textShadowRadius)
+  const x = toNumber(style.textShadowOffset?.width)
+  const y = toNumber(style.textShadowOffset?.height)
+
+  if (!color && radius <= 0 && x === 0 && y === 0) {
+    return undefined
+  }
+
+  return `${x}px ${y}px ${radius}px ${color || "currentColor"}`
+}
+
+/**
+ * The room a boxed run holds open on one axis: the axis value where it is set, and the value for
+ * both axes where it is not.
+ *
+ * A fenced block usually wants more above and below than beside it, and the single `padding` a
+ * style used to carry could not say that. The native formatters resolve the pair the same way.
+ */
+function axis(both: unknown, axisValue: unknown): number {
+  return axisValue === undefined || axisValue === null || axisValue === ""
+    ? toNumber(both as string | number | undefined)
+    : toNumber(axisValue as string | number | undefined)
+}
+
+/**
+ * The box a run of code or a mention sits in: its fill, its border, and the room inside and around
+ * it, written as the two-value shorthands so the horizontal halves stay direction-agnostic.
+ */
+function boxStyle(style: Partial<MarkdownBoxStyle> | undefined) {
+  if (!style) {
+    return {}
+  }
+
+  const borderWidth = toNumber(style.borderWidth)
+
+  return {
+    backgroundColor: style.backgroundColor as string | undefined,
+    borderRadius: style.borderRadius,
+    borderWidth: borderWidth > 0 ? `${borderWidth}px` : undefined,
+    borderStyle: borderWidth > 0 ? "solid" : undefined,
+    borderColor: borderWidth > 0 ? (style.borderColor as string) || "currentColor" : undefined,
+    padding: `${axis(style.padding, style.paddingVertical)}px ${axis(
+      style.padding,
+      style.paddingHorizontal,
+    )}px`,
+    margin: `${axis(style.margin, style.marginVertical)}px ${axis(
+      style.margin,
+      style.marginHorizontal,
+    )}px`,
+  }
+}
+
 /**
  * Applies the layout the block walk computed for one line.
  *
- * Everything a container contributes lands here rather than on the container's own span: its gutter
+ * Everything a container contributes lands here rather than on the container's own element: its gutter
  * is part of the paragraph's indent, and its ribbon is painted behind the whole paragraph. That is
  * how the native formatters do it too, and on the web it is the only placement that works -- a
- * container's span begins before the markers of the containers outside it, so a border drawn on it
+ * container's element begins before the markers of the containers outside it, so a border drawn on it
  * would sit in front of a bullet that is meant to precede it, and a gutter set on it would open
  * before that bullet rather than after.
  *
- * `padding-left` holds every line of the paragraph at the indent, and the negative `text-indent`
+ * `padding-inline-start` holds every line of the paragraph at the indent, and the negative `text-indent`
  * pulls the first one back to where its own marker starts -- `firstLineHeadIndent` and `headIndent`,
  * spelled in CSS. A line that wraps, or a line continuing the block with no marker of its own, then
  * lines up with the text above it instead of with the marker.
@@ -40,7 +136,7 @@ function applyStyle(node: HTMLElement, styles: Record<string, string | number |
 function addLineLayout(
   node: HTMLElement,
   layout: LineLayout | undefined,
-  markdownStyle: PartialMarkdownStyle,
+  markdownStyle: ResolvedMarkdownStyle,
 ) {
   applyStyle(node, {
     margin: "0",
@@ -53,7 +149,10 @@ function addLineLayout(
 
   if (layout.indent > 0) {
     applyStyle(node, {
-      paddingLeft: `${layout.indent}px`,
+      // Logical rather than `padding-left`, because a container's gutter opens on the line's
+      // leading edge -- which is what `marginStart` and `paddingStart` name, and what both native
+      // platforms already indent from.
+      paddingInlineStart: `${layout.indent}px`,
       textIndent: `${layout.firstLineIndent - layout.indent}px`,
     })
   }
@@ -64,17 +163,87 @@ function addLineLayout(
   }
 
   // One background layer per ribbon, each a solid bar of its own. They are painted on the paragraph
-  // rather than on any span so that they run its full height -- a quote that wraps gets one
-  // unbroken bar, exactly as `MarkdownTextLayoutFragment` draws it over the whole fragment.
+  // rather than on anything inside it so that they run its full height -- a quote that wraps gets
+  // one unbroken bar, exactly as `MarkdownTextLayoutFragment` draws it over the whole fragment.
+  //
+  // The offsets are distances from the line's leading edge -- the same numbers `getLeadingMargin`
+  // is handed on Android -- so the edge they are measured from has to move with the line's own
+  // direction. `RIBBON_EDGE` leaves that edge to be named later, by `setRibbonEdge`.
   const color = (markdownStyle.blockquote?.borderColor as string) || "transparent"
+  const radius = toNumber(markdownStyle.blockquote?.borderRadius)
+
   applyStyle(node, {
-    backgroundImage: layout.ribbons.map(() => `linear-gradient(${color}, ${color})`).join(", "),
-    backgroundPosition: layout.ribbons.map((x) => `${x}px 0`).join(", "),
+    backgroundImage: layout.ribbons.map(() => bar(color, radius)).join(", "),
+    backgroundPositionX: layout.ribbons.map((x) => `${RIBBON_EDGE} ${x}px`).join(", "),
+    // One value for every layer: a shorter list is repeated to cover them all.
+    backgroundPositionY: "0",
     backgroundSize: layout.ribbons.map(() => `${width}px 100%`).join(", "),
     backgroundRepeat: "no-repeat",
   })
 }
 
+/**
+ * The custom property naming the edge a ribbon's offset is measured from, and the reference to it
+ * the offsets are written against.
+ *
+ * `background-position` is the one part of a line still spelled physically: it has no logical form.
+ * So the edge is named indirectly and `setRibbonEdge` fills it in once the line has its text --
+ * which is also why it is a custom property rather than a value written straight into the offsets:
+ * the offsets are known while building the line, the direction only after.
+ *
+ * The fallback in the reference is what a line gets before then, and what one gets in a browser
+ * that cannot answer the question at all.
+ */
+const RIBBON_EDGE_PROPERTY = "--marcus-ribbon-edge"
+const RIBBON_EDGE = `var(${RIBBON_EDGE_PROPERTY}, left)`
+
+/**
+ * Turns a line's ribbons round when the line reads right to left.
+ *
+ * Asked of the browser rather than worked out from the text, because the browser is what lays the
+ * line out: whatever it resolved `dir="auto"` to is where it put the gutter, and the bars belong on
+ * that side whether or not a bidi rule written here would have agreed. `:dir()` is unsupported in
+ * browsers older than Safari 16.4, where `matches` throws and the fallback edge stands.
+ *
+ * Called once the line holds its text, since that is what a line's own direction is read from, and
+ * only for a line that has ribbons: nothing else on a line is measured from an edge.
+ */
+function setRibbonEdge(node: HTMLElement, layout: LineLayout | undefined) {
+  if (!layout || layout.ribbons.length === 0) {
+    return
+  }
+
+  try {
+    if (node.matches(":dir(rtl)")) {
+      node.style.setProperty(RIBBON_EDGE_PROPERTY, "right")
+    }
+  } catch {
+    // A browser without `:dir()`. Left is the fallback the offsets already carry.
+  }
+}
+
+/**
+ * One quote bar, as a background layer.
+ *
+ * A gradient has no corners, so a bar that is asked to round its ends is drawn as an SVG rectangle
+ * instead. The SVG carries no `viewBox`, which means its user units are the pixels the layer is
+ * sized to and `rx` is the radius that was asked for rather than a radius stretched by the height
+ * of the line. `MarkdownTextLayoutFragment` and `MarkdownBlockIndentSpan` round the same bar with a
+ * rounded-rect path.
+ */
+function bar(color: string, radius: number): string {
+  if (radius <= 0) {
+    return `linear-gradient(${color}, ${color})`
+  }
+
+  const svg =
+    `<svg xmlns="http://www.w3.org/2000/svg" width="100%" height="100%">` +
+    `<rect width="100%" height="100%" rx="${radius}" ry="${radius}" fill="${color}"/>` +
+    `</svg>`
+
+  return `url("data:image/svg+xml,${encodeURIComponent(svg)}")`
+}
+
 /**
  * Opens the space a marker holds for the container that follows it.
  *
@@ -83,30 +252,49 @@ function addLineLayout(
  */
 function addBlockPrefixGap(node: HTMLElement, gap: number | undefined) {
   if (gap) {
-    node.style.marginRight = `${gap}px`
+    // Logical: the room belongs after the marker in reading order, which is its left in a
+    // right-to-left line. `MarkdownFormatter` kerns the marker's last character, and kerning
+    // follows the run's own direction for the same reason.
+    node.style.marginInlineEnd = `${gap}px`
   }
 }
 
 function addStyleToBlock(
   targetElement: HTMLElement,
   type: NodeType,
-  markdownStyle: PartialMarkdownStyle,
+  markdownStyle: ResolvedMarkdownStyle,
   isMultiline = true,
+  rendering: MarkerRendering = SHOWN_MARKERS,
 ) {
   const node = targetElement
 
   switch (type) {
+    // A fenced block's language is its own type so that something can read it,
+    // but in an input it is part of the fence you are typing and reads as
+    // markup, so it is coloured like the rest of it.
     case "syntax":
-      applyStyle(node, { color: markdownStyle.syntax?.color as string })
+    case "language": {
+      // A list's marker is the one syntax a display keeps, and it is drawn there
+      // rather than shown -- everything else the colour is for has been stripped
+      // out by the time a display is built, so this is the only case where the
+      // two components part company.
+      const list = rendering.display && type === "syntax" ? markerList(node) : null
+
+      if (list) {
+        addMarkerStyle(node, list, markdownStyle, rendering)
+      } else {
+        applyStyle(node, textStyle(markdownStyle.syntax))
+      }
       break
-    case "bold":
-      node.style.fontWeight = "bold"
+    }
+    case "strong":
+      applyStyle(node, textStyle(markdownStyle.strong))
       break
-    case "italic":
-      node.style.fontStyle = "italic"
+    case "emphasis":
+      applyStyle(node, textStyle(markdownStyle.emphasis))
       break
     case "strikethrough":
-      node.style.textDecoration = "line-through"
+      applyStyle(node, textStyle(markdownStyle.strikethrough))
       break
     case "emoji":
       applyStyle(node, {
@@ -117,43 +305,42 @@ function addStyleToBlock(
         verticalAlign: "middle",
       })
       break
-    case "mention-here":
-      addMentionStyle(node, markdownStyle.mentionHere)
-      break
-    case "mention-user":
-      addMentionStyle(node, markdownStyle.mentionUser)
-      break
-    case "mention-report":
-      addMentionStyle(node, markdownStyle.mentionReport)
+    // A pill: the same inline box an inline run of code sits in, and drawn the same way. The
+    // padding and margin push the words either side of it apart, the padding grows into the
+    // line's own spacing above and below rather than pushing the lines apart, and a mention that
+    // wraps is rounded only where it begins and ends.
+    case "mention":
+      applyStyle(node, textStyle(markdownStyle.mention))
+      applyStyle(node, boxStyle(markdownStyle.mention))
       break
     case "link":
-      applyStyle(node, {
-        color: markdownStyle.link?.color as string,
-        textDecoration: "underline",
-      })
+      applyStyle(node, textStyle(markdownStyle.link))
       break
-    // Both carry a font, a colour and a background, and nothing else: native draws no border, no
-    // corner radius and no padding around either, so neither does this.
+    // An inline box, which is what the platforms draw by hand: the padding and margin push the
+    // words either side of it apart, the padding grows into the line's own spacing above and
+    // below rather than pushing the lines apart, and a run that wraps is rounded only where it
+    // begins and ends. All three are what CSS does with an inline element by default.
     case "code":
-      applyStyle(node, {
-        fontFamily: markdownStyle.code?.fontFamily,
-        fontSize: markdownStyle.code?.fontSize,
-        color: markdownStyle.code?.color as string,
-        backgroundColor: markdownStyle.code?.backgroundColor as string,
-      })
+      applyStyle(node, textStyle(markdownStyle.code))
+      applyStyle(node, boxStyle(markdownStyle.code))
       break
+    // Only the text attributes of a block; the box it sits in is `codeblock`, which is the range
+    // that covers the whole thing rather than only the code inside it.
     case "pre":
-      applyStyle(node, {
-        fontFamily: markdownStyle.pre?.fontFamily,
-        fontSize: markdownStyle.pre?.fontSize,
-        color: markdownStyle.pre?.color as string,
-        backgroundColor: markdownStyle.pre?.backgroundColor as string,
-      })
+      applyStyle(node, textStyle(markdownStyle.pre))
       break
-    // Block containers hold no box of their own: their gutters and ribbons belong to the
-    // paragraph, in `addLineLayout`. All that is left is letting a long unbroken word inside one
+    case "codeblock":
+      addCodeBlockStyle(node, markdownStyle, isMultiline)
+      break
+    // A quoted block holds no box of its own: its gutter and its ribbons belong to the paragraph,
+    // in `addLineLayout`. What is left is the text inside it, and letting a long unbroken word
     // break rather than push the line past the input's edge.
     case "blockquote":
+      applyStyle(node, textStyle(markdownStyle.blockquote))
+      applyStyle(node, { overflowWrap: "anywhere" })
+      break
+    // Neither do the list containers, and their markers are styled from the `syntax` range inside
+    // their prefix rather than from here.
     case "list-ordered":
     case "list-unordered":
       applyStyle(node, { overflowWrap: "anywhere" })
@@ -174,32 +361,150 @@ function addStyleToBlock(
   }
 }
 
-function addMentionStyle(
+/**
+ * The box behind a fenced or indented block: one fill for the whole thing, from the first line to
+ * the last, which is what the native formatters draw.
+ *
+ * `codeblock` covers the block including its fences, and the builder merges all of its lines into
+ * one element, so here the box is a real box rather than the several line rects each platform has
+ * to fill by hand. What that costs is the one thing an element cannot do: a block opened after a
+ * bullet or a quote's `>` shares that line in the buffer but not on screen, because a block-level
+ * box drops below the marker in front of it.
+ *
+ * A singleline input has no room for a block at all -- every line of it is drawn on one -- so there
+ * the background stays an inline one, painted behind the text.
+ */
+function addCodeBlockStyle(
   node: HTMLElement,
-  style:
-    | { color?: unknown; backgroundColor?: unknown; borderRadius?: string | number }
-    | undefined,
+  markdownStyle: ResolvedMarkdownStyle,
+  isMultiline: boolean,
 ) {
+  const style = markdownStyle.pre
+  const box = boxStyle(style)
+
+  applyStyle(node, {
+    backgroundColor: box.backgroundColor,
+    borderRadius: box.borderRadius,
+    borderWidth: box.borderWidth,
+    borderStyle: box.borderStyle,
+    borderColor: box.borderColor,
+  })
+
+  if (!isMultiline) {
+    return
+  }
+
   applyStyle(node, {
-    color: style?.color as string,
-    backgroundColor: style?.backgroundColor as string,
-    borderRadius: style?.borderRadius,
+    display: "block",
+    // The padding is inside the box, so the box still spans the line rather than overflowing it.
+    boxSizing: "border-box",
+    padding: box.padding,
+    margin: box.margin,
+  })
+}
+
+/**
+ * The list whose marker `node` is, or null if this syntax is something else.
+ *
+ * A marker is a `syntax` inside the `block-prefix` of a list container, which is a shape only a
+ * list has: a quote's `>` is removed with the rest of the markup before a display is built.
+ */
+function markerList(node: HTMLElement): "list-ordered" | "list-unordered" | null {
+  let current = node.parentNode as HTMLElement | null
+  let inPrefix = false
+
+  while (current && current.contentEditable !== "true") {
+    const type = current.getAttribute?.("data-type")
+
+    if (type === "block-prefix") {
+      inPrefix = true
+    } else if (type === "list-ordered" || type === "list-unordered") {
+      return inPrefix ? type : null
+    }
+
+    current = current.parentNode as HTMLElement | null
+  }
+
+  return null
+}
+
+/**
+ * Draws a list's marker: a bullet for an unordered item, the number at its own scale for an
+ * ordered one.
+ *
+ * Both are sized from the base font rather than from a length of their own, so a list marks itself
+ * in proportion to the prose it marks, and both are drawn from the list's own `marker` style over
+ * `syntax` -- which, in a display where every other piece of syntax has been removed, is where a
+ * marker's colour came from before lists could name one. `MarkdownFormatter` draws the same two
+ * shapes from the same numbers on iOS and Android.
+ *
+ * The bullet keeps the marker character inside it, boxed and invisible: it is what a reader copies
+ * and what a screen reader announces, and the box is exactly the width `layoutBlocks` indented the
+ * text past.
+ */
+function addMarkerStyle(
+  node: HTMLElement,
+  type: "list-ordered" | "list-unordered",
+  markdownStyle: ResolvedMarkdownStyle,
+  rendering: MarkerRendering,
+) {
+  const list = type === "list-ordered" ? markdownStyle.orderedList : markdownStyle.unorderedList
+  // What the list says about its marker, over what `syntax` says about markup in general. Before
+  // lists had a `marker` entry this was `syntax.color` and nothing else, which is what an unset
+  // `marker` still resolves to.
+  const style = { ...markdownStyle.syntax, ...list?.marker }
+  const color = (style.color as string) || ""
+  const { fontSize } = rendering
+  const scale = toNumber(list?.markerScale)
+
+  if (scale <= 0 || fontSize <= 0) {
+    applyStyle(node, textStyle(style))
+    return
+  }
+
+  if (type === "list-ordered") {
+    applyStyle(node, textStyle(style))
+    applyStyle(node, { fontSize: fontSize * scale })
+    return
+  }
+
+  const diameter = fontSize * scale
+
+  // A box one line high, aligned to the top of the line, with the circle painted in the middle of
+  // it: that is what centres the bullet on the line rather than on the text, which is where both
+  // native platforms draw it. The height is the marker character's own line box -- an inline block
+  // holding one line of text is exactly one line high -- so it follows the line height without
+  // having to be told it.
+  applyStyle(node, textStyle(style))
+  applyStyle(node, {
+    display: "inline-block",
+    width: diameter,
+    verticalAlign: "top",
+    backgroundImage: `radial-gradient(circle closest-side, ${
+      color || "currentColor"
+    } 100%, transparent 100%)`,
+    backgroundSize: `${diameter}px ${diameter}px`,
+    backgroundPosition: "center",
+    backgroundRepeat: "no-repeat",
+    // The character is still in the box, and stays out of sight of everything but a selection.
+    color: "transparent",
+    overflow: "hidden",
   })
 }
 
 /**
  * Sizes a heading the way native does: level N is the base size scaled N-1 times.
  *
- * The level does not reach here -- `ungroupRanges` turns it into one nested span per level -- so
+ * The level does not reach here -- `ungroupRanges` turns it into one nested element per level -- so
  * the scaling is expressed in `em` and compounds down the nesting to the same number. This runs
- * once the span is in the tree, which is what lets it tell an inner level from the outermost one.
+ * once the element is in the tree, which is what lets it tell an inner level from the outermost one.
  */
-function addHeadingStyle(node: HTMLElement, markdownStyle: PartialMarkdownStyle) {
+function addHeadingStyle(node: HTMLElement, markdownStyle: ResolvedMarkdownStyle) {
   const nested = isChildOfMarkdownElement(node, "heading")
   const scale = markdownStyle.heading?.scale
 
+  applyStyle(node, textStyle(markdownStyle.heading))
   applyStyle(node, {
-    fontWeight: "bold",
     fontSize: nested ? `${scale === undefined ? 1 : scale}em` : markdownStyle.heading?.fontSize,
   })
 }
@@ -237,6 +542,7 @@ function isChildOfMultilineMarkdownElement(node: HTMLElement): boolean {
 export {
   addStyleToBlock,
   addLineLayout,
+  setRibbonEdge,
   addBlockPrefixGap,
   isMultilineMarkdownType,
   isChildOfMarkdownElement,

package/src/web/utils/elementUtils.ts

@@ -0,0 +1,87 @@
+import type { HTMLMarkdownElement } from "../../MarkdownTextInput.web"
+import type { NodeType } from "./treeUtils"
+
+/**
+ * The tag each markdown type is built as.
+ *
+ * A range says what a run of text *is*; the element it becomes should say the same thing to
+ * everything that reads the document rather than looking at it. A screen reader announces a
+ * `<strong>` and a `<blockquote>` and says nothing about a span; text copied out of the input
+ * arrives in another editor still emphasised; and the page `expo export` prerenders carries the
+ * structure rather than a wall of undifferentiated spans.
+ *
+ * `data-type` stays on every one of them regardless -- it is what the styling, the CSS and the
+ * render-model baselines are keyed on, and it distinguishes the several types that share a tag.
+ *
+ * Two pairings are worth spelling out. A fenced or indented block is `<pre>` from `codeblock`, the
+ * range covering the whole thing including its fences, with `<code>` inside it from `pre`, the
+ * range covering only the code -- which is the nesting HTML asks for, in the opposite naming to
+ * ours. And `link` is an anchor even in the input, where it has no `href` yet: an anchor without
+ * one is exactly what HTML has for a link whose destination is not resolved.
+ *
+ * Everything absent from here is a span, because HTML has nothing that means it: markdown's own
+ * punctuation, the parts of a link's markup, a mention, an emoji run.
+ */
+/** Marks an element as one of ours, for the rules that undo the tag's browser defaults. */
+const ELEMENT_CLASS = "react-native-marcus"
+
+const TAGS: Partial<Record<NodeType, string>> = {
+  "strong": "strong",
+  "emphasis": "em",
+  // GFM renders `~~x~~` as `<del>`, and so does this. `<s>` is for text that is no longer accurate
+  // rather than text that was taken out.
+  "strikethrough": "del",
+  "code": "code",
+  "pre": "code",
+  "codeblock": "pre",
+  "blockquote": "blockquote",
+  "list-ordered": "ol",
+  "list-unordered": "ul",
+  "list-item": "li",
+  "link": "a",
+}
+
+/**
+ * The types that become a block-level element, and so cannot sit in a `<p>`.
+ *
+ * `pre` is not among them: it is built as `<code>`, which is phrasing content whatever it is
+ * displayed as. Its enclosing `codeblock` is the `<pre>`, and that is.
+ */
+const BLOCK_LEVEL_TYPES = new Set<NodeType>([
+  "blockquote",
+  "codeblock",
+  "heading",
+  "list-ordered",
+  "list-unordered",
+])
+
+function isBlockLevelType(type: NodeType) {
+  return BLOCK_LEVEL_TYPES.has(type)
+}
+
+/**
+ * Builds the element for a range, tagged and typed.
+ *
+ * `level` applies to headings only, and is the ATX level: `1` through `6` produce that heading,
+ * and `0` produces a span. A level arrives as one nested range per level -- `ungroupRanges` is what
+ * turns `depth` into the nesting the size scaling compounds down -- so only the outermost of them
+ * can be the heading itself, and the copies inside it are spans. `<h2><h2>` is not a thing.
+ */
+function createMarkdownElement(type: NodeType, level = 0): HTMLMarkdownElement {
+  const tag =
+    type === "heading" ? (level > 0 ? `h${Math.min(level, 6)}` : "span") : TAGS[type] ?? "span"
+  const element = document.createElement(tag) as HTMLMarkdownElement
+
+  element.setAttribute("data-type", type)
+
+  // Every tag but the span brings the browser's own idea of how it looks, and `MarkdownElements.css`
+  // hands that back. The class is what scopes those rules to elements this library built, rather
+  // than to every `<blockquote data-type>` on the page.
+  if (tag !== "span") {
+    element.className = ELEMENT_CLASS
+  }
+
+  return element
+}
+
+export { createMarkdownElement, isBlockLevelType, ELEMENT_CLASS }