react-native-marcus 0.1.0 → 0.2.0

package/src/MarkdownTextInput.tsx

@@ -1,14 +1,14 @@
-import { StyleSheet, TextInput, processColor } from "react-native"
+import { StyleSheet, TextInput } from "react-native"
 import React from "react"
 import type { TextInputProps } from "react-native"
 import { createSerializable, createWorkletRuntime } from "react-native-worklets"
 import type { SerializableRef, WorkletFunction, WorkletRuntime } from "react-native-worklets"
 import MarcusTextInputDecoratorViewNativeComponent from "./MarcusTextInputDecoratorViewNativeComponent"
-import type { MarkdownStyle } from "./MarcusTextInputDecoratorViewNativeComponent"
 import NativeMarcusModule from "./NativeMarcusModule"
-import { mergeMarkdownStyleWithDefault } from "./styleUtils"
+import { processMarkdownStyle } from "./styleUtils"
 import type { PartialMarkdownStyle } from "./styleUtils"
-import type { MarkdownRange } from "./commonTypes"
+import { createParser } from "./parser"
+import type { MarkdownParser, MarkdownRange } from "./commonTypes"
 
 declare global {
   // eslint-disable-next-line no-var
@@ -48,7 +48,7 @@ function initializeMarcusIfNeeded() {
   initialized = true
 }
 
-function registerParser(parser: (input: string) => MarkdownRange[]): number {
+function registerParser(parser: MarkdownParser): number {
   initializeMarcusIfNeeded()
   const serializableWorklet = createSerializable(
     parser as WorkletFunction<[string], MarkdownRange[]>,
@@ -63,52 +63,56 @@ function unregisterParser(parserId: number) {
 
 interface MarkdownTextInputProps extends TextInputProps {
   markdownStyle?: PartialMarkdownStyle
-  parser: (value: string) => MarkdownRange[]
+  /**
+   * 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.
+   *
+   * An input shows what was typed, so the maths stays as written -- what this
+   * turns on is recognising it, which greys the dollars as the markup they are
+   * and leaves the TeX between them alone.
+   *
+   * @default false
+   */
+  math?: boolean
 }
 
 type MarkdownTextInput = TextInput & React.Component<MarkdownTextInputProps>
 
-function processColorsInMarkdownStyle(input: MarkdownStyle): MarkdownStyle {
-  const output = JSON.parse(JSON.stringify(input))
-
-  Object.keys(output).forEach((key) => {
-    const obj = output[key]
-    Object.keys(obj).forEach((prop) => {
-      // TODO: use ReactNativeStyleAttributes from 'react-native/Libraries/Components/View/ReactNativeStyleAttributes'
-      if (!(prop === "color" || prop.endsWith("Color"))) {
-        return
-      }
-      obj[prop] = processColor(obj[prop])
-    })
-  })
-
-  return output as MarkdownStyle
-}
-
-function processMarkdownStyle(input: PartialMarkdownStyle | undefined): MarkdownStyle {
-  return processColorsInMarkdownStyle(mergeMarkdownStyleWithDefault(input))
-}
-
 const MarkdownTextInput = React.forwardRef<MarkdownTextInput, MarkdownTextInputProps>(
   (props, ref) => {
+    const { markdownStyle: markdownStyleProp, gfm, mention, math, ...textInputProps } = props
+
     const markdownStyle = React.useMemo(
-      () => processMarkdownStyle(props.markdownStyle),
-      [props.markdownStyle],
+      () => processMarkdownStyle(markdownStyleProp),
+      [markdownStyleProp],
     )
 
-    if (props.parser === undefined) {
-      throw new Error("[react-native-marcus] `parser` is undefined")
-    }
+    // The same worklet for as long as the flavour is the same one, so the id
+    // below is registered once and the native side keeps the parser it has.
+    const parser = createParser({ gfm, mention, math })
 
     // eslint-disable-next-line no-underscore-dangle
-    const workletHash = (props.parser as { __workletHash?: number }).__workletHash
-    if (workletHash === undefined) {
-      throw new Error("[react-native-marcus] `parser` is not a worklet")
+    if ((parser as { __workletHash?: number }).__workletHash === undefined) {
+      throw new Error(
+        "[react-native-marcus] the parser is not a worklet. Add `react-native-worklets/plugin` to the project's Babel config.",
+      )
     }
 
     const parserId = React.useMemo(() => {
-      return registerParser(props.parser)
-    }, [props.parser])
+      return registerParser(parser)
+    }, [parser])
 
     React.useEffect(() => {
       return () => unregisterParser(parserId)
@@ -120,7 +124,7 @@ const MarkdownTextInput = React.forwardRef<MarkdownTextInput, MarkdownTextInputP
         markdownStyle={markdownStyle}
         parserId={parserId}
       >
-        <TextInput {...props} ref={ref} />
+        <TextInput {...textInputProps} ref={ref} />
       </MarcusTextInputDecoratorViewNativeComponent>
     )
   },

package/src/MarkdownTextInput.web.tsx

@@ -33,8 +33,9 @@ import {
   removeSelection,
   setCursorPosition,
 } from "./web/utils/cursorUtils"
+import "./web/MarkdownElements.css"
 import "./web/MarkdownTextInput.css"
-import type { MarkdownStyle } from "./MarcusTextInputDecoratorViewNativeComponent"
+import type { PartialMarkdownStyle, ResolvedMarkdownStyle } from "./styleUtils"
 import {
   getElementHeight,
   getPlaceholderValue,
@@ -47,13 +48,36 @@ import {
   parseToReactDOMStyle,
   processMarkdownStyle,
 } from "./web/utils/webStyleUtils"
-import type { MarkdownRange } from "./commonTypes"
+import { createParser } from "./parser"
+import type { MarkdownParser } from "./commonTypes"
 
 const useClientEffect = typeof window === "undefined" ? useEffect : useLayoutEffect
 
 interface MarkdownTextInputProps extends TextInputProps {
-  markdownStyle?: MarkdownStyle
-  parser: (text: string) => MarkdownRange[]
+  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.
+   *
+   * An input shows what was typed, so the maths stays as written -- what this
+   * turns on is recognising it, which greys the dollars as the markup they are
+   * and leaves the TeX between them alone.
+   *
+   * @default false
+   */
+  math?: boolean
   onClick?: (e: MouseEvent<HTMLDivElement>) => void
   dir?: string
   disabled?: boolean
@@ -114,7 +138,9 @@ const MarkdownTextInput = React.forwardRef<MarkdownTextInput, MarkdownTextInputP
       numberOfLines,
       multiline = false,
       markdownStyle,
-      parser,
+      gfm,
+      mention,
+      math,
       onBlur,
       onChange,
       onChangeText,
@@ -139,12 +165,9 @@ const MarkdownTextInput = React.forwardRef<MarkdownTextInput, MarkdownTextInputP
     },
     ref,
   ) => {
-    if (parser === undefined) {
-      throw new Error("[react-native-marcus] `parser` is undefined")
-    }
-    if (typeof parser !== "function") {
-      throw new Error("[react-native-marcus] `parser` is not a function")
-    }
+    // The same function for as long as the flavour is the same one, so every
+    // callback below that holds on to it keeps its identity too.
+    const parser = createParser({ gfm, mention, math })
 
     const divRef = useRef<MarkdownTextInputElement | null>(null)
     const currentlyFocusedField = useRef<HTMLDivElement | null>(null)
@@ -185,10 +208,10 @@ const MarkdownTextInput = React.forwardRef<MarkdownTextInput, MarkdownTextInputP
 
     const parseText = useCallback(
       (
-        parserFunction: (input: string) => MarkdownRange[],
+        parserFunction: MarkdownParser,
         target: MarkdownTextInputElement,
         text: string | null,
-        customMarkdownStyles: MarkdownStyle,
+        customMarkdownStyles: ResolvedMarkdownStyle,
         cursorPosition: number | null = null,
         shouldAddToHistory = true,
         shouldForceDOMUpdate = false,

package/src/atomUtils.ts

@@ -0,0 +1,112 @@
+import type { MarkdownEmbed, MarkdownMath, StrippedMarkdown } from "./stripUtils"
+
+// An image and a maths span are the same problem to a display: a run of
+// markdown that is drawn rather than read, that the strip has already replaced
+// with a single placeholder character, and that something has to be mounted
+// over. `stripSyntax` reports them apart because what a caller needs to know
+// about each is different; the two components need them together, in the one
+// order the placeholders appear in.
+
+type Atom = ({ kind: "embed" } & MarkdownEmbed) | ({ kind: "math" } & MarkdownMath)
+
+/**
+ * How a maths span is said out loud, or nothing for one that cannot be said.
+ *
+ * Passed in rather than imported so that this module knows nothing about
+ * typesetting: it is `./math`'s `speakMath` at both call sites, and a display
+ * with no maths backend passes one that always declines.
+ */
+type SpeakMath = (tex: string, display: boolean, locale?: string) => string | null
+
+const NO_ATOMS: Atom[] = []
+
+/**
+ * Every placeholder in the stripped text, in the order it stands there.
+ *
+ * Sorting is enough to interleave the two kinds correctly: each index is a
+ * distinct character in the same string, so no two atoms can share one.
+ */
+function atomsOf(markdown: StrippedMarkdown): Atom[] {
+  const { embeds, maths } = markdown
+
+  if (embeds.length === 0 && maths.length === 0) {
+    return NO_ATOMS
+  }
+
+  const atoms: Atom[] = []
+
+  for (const embed of embeds) {
+    atoms.push({ kind: "embed", ...embed })
+  }
+
+  for (const math of maths) {
+    atoms.push({ kind: "math", ...math })
+  }
+
+  return atoms.length > 1 ? atoms.sort((a, b) => a.index - b.index) : atoms
+}
+
+/**
+ * The text as it should be read out, with every placeholder written back out
+ * as what it stands for.
+ *
+ * A drawing costs exactly one character in the string the platform lays out --
+ * U+FFFC, the object replacement character -- and there is nothing in that
+ * character for a screen reader to say. An image's `alt` is its accessible name
+ * by every spec there is, and left empty it declares the image decorative, so
+ * it is used as written. A maths span is read as what was drawn, which is what
+ * `speak` answers; the TeX behind it is the fallback, because an expression
+ * read out as its source is still better than a sentence with a hole in it.
+ *
+ * `locale` is the language the maths is said in, and is passed straight
+ * through: the prose around it is in whatever language it was written in, and
+ * nothing here can or should change that.
+ */
+function describeAtoms(markdown: StrippedMarkdown, speak: SpeakMath, locale?: string): string {
+  const atoms = atomsOf(markdown)
+
+  if (atoms.length === 0) {
+    return markdown.text
+  }
+
+  let described = ""
+  let cursor = 0
+
+  for (const atom of atoms) {
+    described += markdown.text.slice(cursor, atom.index)
+    described +=
+      atom.kind === "embed" ? atom.alt : speak(atom.tex, atom.display, locale) ?? atom.tex
+    cursor = atom.index + 1
+  }
+
+  return described + markdown.text.slice(cursor)
+}
+
+/**
+ * What a placeholder puts on the clipboard, which is the markdown it was
+ * written as.
+ *
+ * A copy of rendered text is plain text: `**bold**` comes off the screen as
+ * "bold", because that is what a copy of styled text has always been. A drawing
+ * has no plain text at all -- it is one U+FFFC, which pastes as a box -- and
+ * the source is the only honest thing to put there. Written back out with its
+ * dollar signs, a copied paragraph is markdown again and goes back into an
+ * editor as the document it came from.
+ *
+ * An image copies as nothing, the way an `<img>` does on the web: its alt text
+ * describes the picture for someone who cannot see it, and pasting a
+ * description where a picture was is not what anyone asked for.
+ */
+function sourceOf(atom: Atom): string {
+  if (atom.kind === "embed") {
+    return ""
+  }
+
+  // A display equation is written on lines of its own, and lands in the
+  // clipboard that way: pasted back, it is a display equation again.
+  return atom.display ? `$$\n${atom.tex}\n$$` : `$$${atom.tex}$$`
+}
+
+export type { Atom, SpeakMath }
+
+export { NO_ATOMS, atomsOf, describeAtoms, sourceOf }

package/src/childrenUtils.ts

@@ -0,0 +1,39 @@
+import type React from "react"
+
+/**
+ * Flattens children into the string they render as, or null if they are not
+ * text.
+ *
+ * Only strings and numbers are markdown. An element child is content there are
+ * no parser offsets for and no way to strip syntax out of, so a subtree
+ * containing one renders unformatted rather than half formatted.
+ */
+function flattenText(children: React.ReactNode): string | null {
+  const parts: string[] = []
+
+  return collect(children, parts) ? parts.join("") : null
+}
+
+function collect(children: React.ReactNode, parts: string[]): boolean {
+  if (children === null || children === undefined || typeof children === "boolean") {
+    return true
+  }
+
+  if (typeof children === "string") {
+    parts.push(children)
+    return true
+  }
+
+  if (typeof children === "number") {
+    parts.push(String(children))
+    return true
+  }
+
+  if (Array.isArray(children)) {
+    return children.every((child) => collect(child, parts))
+  }
+
+  return false
+}
+
+export { flattenText }

package/src/commonTypes.ts

@@ -1,13 +1,26 @@
 type MarkdownType =
-  | "bold"
-  | "italic"
+  | "strong"
+  | "emphasis"
   | "strikethrough"
   | "emoji"
-  | "mention-here"
-  | "mention-user"
-  | "mention-short"
-  | "mention-report"
+  // One type. A mention is a name with an `@` in front of it; who it names is
+  // the application's business, not the parser's, and nothing here can tell a
+  // person from a room from a report.
+  | "mention"
   | "link"
+  // The text between a link's brackets. Its own type rather than `link`: no
+  // formatter styles it, so it stays plain while it is being edited, and only
+  // the display renderer -- which has removed the brackets -- turns it into one.
+  | "label"
+  // The text between an image's brackets. Content rather than text: CommonMark
+  // flattens it to a string only when it renders the `alt` attribute, and
+  // micromark keeps the structure, so emphasis, code, a link or another image
+  // nested in there all arrive as ranges of their own inside this one.
+  | "alt"
+  // The title a link or image carries after its destination. Metadata rather
+  // than content: no formatter styles it, and a display renderer removes it
+  // along with the destination it belongs to.
+  | "title"
   | "code"
   | "pre"
   | "blockquote"
@@ -16,15 +29,62 @@ type MarkdownType =
   | "block-prefix"
   | "heading"
   | "syntax"
-  | "inline-image"
+  | "image"
   | "codeblock"
+  // An inline `$$...$$` span, delimiters and all. One range over the whole
+  // thing rather than one over its content: what is between the dollars is TeX,
+  // not markdown, and nothing downstream has any business styling parts of it.
+  | "math"
+  // A `$$` block, which is the same thing set on lines of its own.
+  | "math-block"
+  // The language a fenced block declares. Metadata rather than content: no
+  // formatter styles it and the display renderer removes it outright.
+  | "language"
 
 interface MarkdownRange {
   type: MarkdownType
   start: number
   length: number
   depth?: number
-  syntaxType?: "opening" | "closing"
 }
 
-export type { MarkdownType, MarkdownRange }
+/**
+ * What the parser recognises beyond CommonMark.
+ *
+ * Every one of them is off unless it is asked for. Each changes what an
+ * ordinary character means -- a tilde, an `@`, a dollar sign -- and a document
+ * written somewhere else, by someone who never heard of this library, is the
+ * one place where guessing at that is least recoverable. They are the whole of
+ * the parser's configuration: a caller chooses a flavour, not a parser, and the
+ * components take these as props of their own.
+ */
+interface ParserOptions {
+  /**
+   * 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.
+   *
+   * Two dollars, never one: `$5 and $6` is a price list in every document that
+   * has ever been written, and single-dollar maths would quietly turn it into a
+   * picture of the word "and".
+   *
+   * @default false
+   */
+  math?: boolean
+}
+
+/** A parser, as the components hold one: text in, ranges out. */
+type MarkdownParser = (markdown: string) => MarkdownRange[]
+
+export type { MarkdownType, MarkdownRange, ParserOptions, MarkdownParser }

package/src/index.tsx

@@ -1,4 +1,5 @@
 export { default as MarkdownTextInput, getWorkletRuntime } from "./MarkdownTextInput"
 export type { MarkdownTextInputProps, MarkdownStyle } from "./MarkdownTextInput"
+export { default as MarkdownText } from "./MarkdownText"
+export type { MarkdownTextProps, OnLinkPress, RenderEmbed, RenderSVG } from "./MarkdownText"
 export type { MarkdownType, MarkdownRange } from "./commonTypes"
-export { parse as parser } from "./parser"

package/src/math/environment.ts

@@ -0,0 +1,68 @@
+/**
+ * What MathJax and SRE assume about their host that React Native does not
+ * provide. Imported before either of them, and first, because `import`
+ * statements are hoisted and run in the order they are written.
+ */
+
+/**
+ * MathJax guesses the operating system from `window.navigator.appVersion`,
+ * behind nothing but a `typeof window !== "undefined"` check
+ * (`@mathjax/src/mjs/util/context.js`). React Native defines `window` and
+ * `navigator` but not `appVersion`, so the check passes and the read throws
+ * `Cannot read property 'includes' of undefined` before a line of MathJax's own
+ * code runs.
+ *
+ * What it is guessing at is only ever used to rewrite Windows file paths, which
+ * nothing here does, so an empty string is both harmless and enough.
+ */
+const nav = (globalThis as unknown as { navigator?: Record<string, unknown> }).navigator
+
+for (const key of ["appVersion", "userAgent"]) {
+  if (nav && nav[key] === undefined) {
+    try {
+      nav[key] = ""
+    } catch {
+      Object.defineProperty(nav, key, { value: "", configurable: true })
+    }
+  }
+}
+
+/**
+ * The file system, which SRE reaches for before anything has had a chance to
+ * tell it not to.
+ *
+ * `speech-rule-engine/js/common/system_external.js` decides at import time how
+ * it will read its rule tables, and on anything that is not a browser it
+ * settles on Node's `fs` and a path worked out from `require.resolve` or
+ * `process.cwd()`. React Native has neither: `require` is the bundler's, which
+ * throws on a name it was not built with, and `process` is a stub with no
+ * `cwd`. Either one is an exception thrown from the top level of a module, so
+ * SRE cannot even be imported.
+ *
+ * None of it is wanted in any case -- the rules are bundled and handed over by
+ * a loader of our own -- so both routes are stubbed out here rather than fixed.
+ * `__non_webpack_require__` is the escape hatch SRE checks first, and a
+ * function that returns nothing for every name satisfies it, leaves `fs` null,
+ * and makes the path guessing fail its way harmlessly to the end.
+ */
+const scope = globalThis as unknown as {
+  __non_webpack_require__?: unknown
+  process?: { cwd?: () => string }
+}
+
+if (scope.__non_webpack_require__ === undefined) {
+  try {
+    scope.__non_webpack_require__ = () => null
+  } catch {
+    Object.defineProperty(scope, "__non_webpack_require__", {
+      value: () => null,
+      configurable: true,
+    })
+  }
+}
+
+if (scope.process !== undefined && scope.process.cwd === undefined) {
+  scope.process.cwd = () => ""
+}
+
+export {}

package/src/math/index.ts

@@ -0,0 +1,78 @@
+/**
+ * The maths backend, in its "there isn't one" form.
+ *
+ * Typesetting TeX takes a library an order of magnitude larger than this one,
+ * and most applications will never draw an equation. So the real backend --
+ * `./mathjax.ts`, right beside this -- is never imported by anything: a
+ * bundler would follow the import and pull MathJax into every app that has
+ * ever installed this package, whether or not it renders maths.
+ *
+ * Instead the two are swapped at build time. `react-native-marcus/metro`'s
+ * `withMath()` resolves this module to that one, so an application opts in by
+ * editing its `metro.config.js` and the default bundle carries nothing.
+ *
+ * What the swap has to preserve is this shape and nothing else.
+ */
+
+/** One expression, drawn, with the box it needs. */
+interface RenderedMath {
+  /**
+   * A standalone SVG document: glyph outlines inline, no `<use>`, no `<defs>`,
+   * and the colour already substituted in.
+   */
+  svg: string
+  /** Points, at the font size that was asked for. */
+  width: number
+  height: number
+  /**
+   * How far below the baseline the drawing hangs -- zero for `x^2`, real for
+   * `\frac{a}{b}`. Part of the picture rather than of the size: `height`
+   * already covers it.
+   */
+  depth: number
+}
+
+/**
+ * Whether maths can be drawn at all.
+ *
+ * Read by the display components, which leave a maths span exactly as it was
+ * written when this is false. Showing `$$x^2$$` is a good deal better than
+ * showing an empty box where an equation should be, and it is the one hint an
+ * application will get that its Metro config is missing a line.
+ */
+const available = false
+
+function renderMath(
+  _tex: string,
+  _display: boolean,
+  _fontSize: number,
+  _color: string | undefined,
+): RenderedMath | null {
+  return null
+}
+
+/**
+ * The expression as it should be read out, or nothing.
+ *
+ * A drawn equation is a picture, and the TeX behind it is source code: an
+ * author reading `\frac{a}{b}` knows what it means, and a reader who asked
+ * for a document rather than for its markup hears three words of punctuation.
+ * So a display says what it drew -- "StartFraction a Over b EndFraction" --
+ * while an input, where the TeX is what is on the screen and what the caret
+ * moves through, keeps the TeX.
+ *
+ * `locale` is the language it should be said in, as a name the backend knows;
+ * nothing means the backend's own default. 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.
+ *
+ * Returning nothing means the caller falls back to the TeX, which is what the
+ * stub does and what a backend does for an expression it cannot say.
+ */
+function speakMath(_tex: string, _display: boolean, _locale?: string): string | null {
+  return null
+}
+
+export type { RenderedMath }
+
+export { available, renderMath, speakMath }