@charcuterie/ui 3.19.2 → 3.20.0

package/src/MarkdownLine/MarkdownLine.tsx

@@ -0,0 +1,331 @@
+import type { ReactNode } from "react"
+import { Fragment } from "react"
+
+import {
+  FOCUS_RING_CLASS,
+  INTENT_CONTENT_CLASS,
+} from "../intentStyles.ts"
+import { useRouterLink } from "../RouterLink/RouterLinkProvider.tsx"
+import { getIsRoutedHref } from "../RouterLink/routerLink.ts"
+import { toClassName } from "../toClassName.ts"
+import type { InlineMarkdownRun } from "./inlineMarkdown.ts"
+import { toInlineMarkdownRuns } from "./inlineMarkdown.ts"
+
+export type MarkdownLineProps = {
+  className?: string
+  /**
+   * Where the text that is **not** itself a link points — the task
+   * a card opens, usually.
+   *
+   * Given one, every plain run becomes its own anchor to it and a
+   * markdown link stays a separate anchor beside them. That is the
+   * whole reason this prop exists rather than the caller wrapping
+   * the component in an `<a>`: an anchor inside an anchor is invalid
+   * HTML, the browser closes the outer one, and the second half of
+   * the title silently stops opening the task.
+   *
+   * Left out, the runs are plain text and only the markdown links
+   * are clickable — which is right for a heading, a table cell, or
+   * anywhere the line is not itself a destination.
+   *
+   * ⚠️ **A markdown link splits this into more than one anchor**, and
+   * each one is named by the words it actually covers — `Ship`, then
+   * `#53`, then `tonight`. That is honest (what is announced is what
+   * is on screen, per WCAG 2.5.3) and it is not *good*: `tonight` is
+   * a poor name for a link to a task. Giving them all one name was
+   * tried and is worse — two links with the same name are ambiguous
+   * to anything driving the page by name, which this library's own
+   * `expectAgentDrivable` refuses outright. The conclusion is a
+   * design one: a link usually belongs in a task's **description**,
+   * where it has a sentence around it, rather than in its title.
+   */
+  href?: string
+  /**
+   * The caller has already wrapped this line in a link — so draw the
+   * marks and emit **no anchors at all**, not even for a markdown
+   * link.
+   *
+   * The third and last answer to "who owns the link here", after
+   * `href` (this component does) and neither (the markdown links do,
+   * and nothing else is clickable). It exists because a whole-card
+   * link is a real and common shape — Docket's triage cards wrap the
+   * title *and* the body, so middle-click opens the proposal — and
+   * inside one, an anchor of any kind is an anchor inside an anchor.
+   *
+   * That trap has teeth even when no author ever typed a link: a
+   * **bare URL autolinks**, so a captured note whose title ends in
+   * `https://…` would nest one without anybody writing `[]()`.
+   *
+   * A markdown link's text still renders, with its marks; it simply
+   * does not navigate on its own. The card's link is what a click
+   * follows.
+   */
+  isInsideLink?: boolean
+  /**
+   * The markdown. **Inline constructs only** — see
+   * `inlineMarkdown.ts`; a `#` or a `- ` is a literal character
+   * here, and a newline collapses to a space.
+   */
+  value: string
+}
+
+/**
+ * The link paint, matched to `.cm-md-link` in the CodeMirror
+ * surface's theme rather than to `TextLink`'s.
+ *
+ * `TextLink` would be the obvious reach and it is the wrong one: it
+ * declares `rounded-xs`, a cursor and a hover rule that belong to a
+ * link in a paragraph, and — the deciding one — it has no way to
+ * inherit the title's own weight, so a link inside a bold title
+ * would un-bold itself. Two rules is the whole of what is shared
+ * with `.cm-md-link`, and sharing them by value is what keeps the
+ * editor and the card showing one answer.
+ */
+const LINK_CLASS = toClassName(
+  INTENT_CONTENT_CLASS.accent,
+  "underline decoration-1 underline-offset-2 hover:decoration-2",
+  FOCUS_RING_CLASS,
+)
+
+/**
+ * `0.9em` and not a step on the type scale.
+ *
+ * A monospace face at the same `font-size` as the text around it
+ * reads bigger — fixed advance width, taller x-height — so a file
+ * name in a title would shout. `em` rather than a fixed size so a
+ * code span in a 24px heading and one in a 13px card row are both
+ * proportional to their line. This is `.cm-md-code`'s rule, copied
+ * by value for the same reason as the link's.
+ */
+const CODE_CLASS =
+  "font-mono text-[0.9em] text-intent-info-content"
+
+/**
+ * Position IS the identity here, which is why every `key` in this
+ * file is an index.
+ *
+ * The usual objection to an index key does not reach this component.
+ * The list is a **pure function of `value`** — nothing inserts,
+ * removes or re-orders a run, and no run holds component state for a
+ * key to preserve — so two renders of the same string produce the
+ * same runs in the same order, and two renders of different strings
+ * are a different line entirely. Content cannot stand in for it: a
+ * title like `**Ship** it **Ship**` has two runs with identical text
+ * and identical marks, and keying by either would collide.
+ */
+const toMarkedContent = (
+  run: InlineMarkdownRun,
+  key: number,
+): ReactNode => {
+  /**
+   * AN UNMARKED RUN IS A TEXT NODE, NOT A WRAPPED ONE — and this is
+   * an accessibility fix rather than a saving.
+   *
+   * Every run used to come back inside a keyed `<span>`. It looked
+   * identical, and it silently broke every accessible name on the
+   * page: the name computation **trims** each element child's
+   * contribution before joining them, so
+   * `<span>Deduplicate </span><code>~/archive</code><span> by</span>`
+   * announces as `Deduplicate~/archiveby`. A text node keeps its
+   * spaces, so the same line as text-node / `<code>` / text-node
+   * announces correctly.
+   *
+   * Caught by `Board`'s move handle, which is named after the card's
+   * title. On screen the two are indistinguishable — the spaces are
+   * still painted either way — which is why `MarkdownLine.test.tsx`
+   * asserts the NAME rather than the text.
+   */
+  if (
+    !run.isCode &&
+    !run.isEmphasis &&
+    !run.isStrikethrough &&
+    !run.isStrong
+  ) {
+    return run.text
+  }
+
+  // Innermost first: the element that carries the text, then the
+  // marks wrapped around it. `<code>` is innermost because it is the
+  // only one that changes the *face* rather than a variation of it.
+  let content: ReactNode = run.isCode ? (
+    <code className={CODE_CLASS}>{run.text}</code>
+  ) : (
+    run.text
+  )
+
+  if (run.isEmphasis) {
+    content = <em>{content}</em>
+  }
+
+  if (run.isStrong) {
+    content = <strong>{content}</strong>
+  }
+
+  if (run.isStrikethrough) {
+    // `<s>`, not `<del>`. `<del>` means "removed from the document"
+    // and carries an editorial history a title does not have; `<s>`
+    // is "no longer accurate", which is what a struck-through task
+    // name says.
+    content = (
+      <s className="text-content-secondary">{content}</s>
+    )
+  }
+
+  // A `Fragment` rather than a `<span>`: it carries the key React
+  // needs for an array child and adds no element to the DOM, so the
+  // mark element sits directly inside the anchor and the name
+  // computation sees no extra boundary to trim.
+  return <Fragment key={key}>{content}</Fragment>
+}
+
+/**
+ * One line of markdown, drawn with its inline marks and nothing
+ * else.
+ *
+ * A **title** is what this is for. Docket's cards carry names like
+ * ``Ingest 53 movies from `Downloads/MOVIES` into `G:\Movies` ``,
+ * and a grid of them set in one flat weight is a wall the eye cannot
+ * scan — the parts that differ between two cards are exactly the
+ * parts markdown would have marked. So the marks earn their place
+ * by making a list of names *scannable*, which is the same argument
+ * as the priority bar and the project colour, one layer down.
+ *
+ * ### It is not a small `MarkdownView`
+ *
+ * `MarkdownView` renders a document, through CodeMirror, from the
+ * optional `@charcuterie/ui/markdown-editor-codemirror` entry point.
+ * Neither half of that suits a name: an editor state and a syntax
+ * tree per card is an absurd price for forty characters, and the
+ * main entry may not reach the CodeMirror stack at all. This parses
+ * the inline grammar directly and returns spans.
+ *
+ * The two therefore have to agree, and `inlineMarkdown.ts` says how
+ * that is kept true — most importantly that both call the **same**
+ * URL guard, `safeUrls.ts`, which moved up out of the CodeMirror
+ * subpath when this landed.
+ *
+ * ### The `href` prop is the load-bearing one
+ *
+ * A card title is usually itself a link. A title may also *contain*
+ * one. Nested anchors are invalid HTML and the browser silently
+ * closes the outer element, so `href` makes the component emit
+ * **siblings** — the plain runs anchored to `href`, the markdown
+ * links anchored to their own destination — which reads as one
+ * continuous line and behaves as two different destinations.
+ *
+ * ```tsx
+ * <MarkdownLine href={`/tasks/${task.id}`} value={task.title} />
+ * ```
+ *
+ * Anywhere a *string* is required — an `aria-label`, a `title`
+ * attribute, `document.title` — call `toPlainMarkdownText` rather
+ * than re-stripping the markup with a regex of your own. It is the
+ * same parse, so it cannot drift from what is on screen.
+ */
+export const MarkdownLine = ({
+  className,
+  href,
+  isInsideLink = false,
+  value,
+}: MarkdownLineProps): ReactNode => {
+  const RouterLink = useRouterLink()
+
+  const runs = toInlineMarkdownRuns(value)
+
+  /**
+   * Consecutive runs that share a destination become **one** anchor.
+   *
+   * Not cosmetic: an anchor per run would make `**Ship** it` two tab
+   * stops and two entries in a screen reader's link list for one
+   * destination, and would break the hover underline into pieces at
+   * every mark boundary.
+   */
+  const groups: {
+    href?: string
+    runs: InlineMarkdownRun[]
+  }[] = []
+
+  for (const run of runs) {
+    const last = groups.at(-1)
+
+    if (last && last.href === run.href) {
+      last.runs.push(run)
+
+      continue
+    }
+
+    groups.push({
+      ...(run.href === undefined ? {} : { href: run.href }),
+      runs: [run],
+    })
+  }
+
+  return (
+    <span className={className}>
+      {groups.map((group, groupIndex) => {
+        const content = group.runs.map(toMarkedContent)
+
+        if (isInsideLink) {
+          // No anchor, and no link paint either: a word painted as
+          // a link that cannot be followed is worse than plain text.
+          return (
+            <Fragment
+              // biome-ignore lint/suspicious/noArrayIndexKey: position is the identity — see `toMarkedContent`
+              key={groupIndex}
+            >
+              {content}
+            </Fragment>
+          )
+        }
+
+        if (group.href !== undefined) {
+          // A destination the injected router cannot serve opens in
+          // a new tab rather than replacing the app: a title that
+          // names a pull request is a reference, and following it
+          // should not lose the board the reader was on.
+          const isRouted = getIsRoutedHref(group.href)
+
+          const LinkElement = isRouted ? RouterLink : "a"
+
+          return (
+            <LinkElement
+              className={LINK_CLASS}
+              href={group.href}
+              // biome-ignore lint/suspicious/noArrayIndexKey: position is the identity — see `toMarkedContent`
+              key={groupIndex}
+              rel={
+                isRouted ? undefined : "noopener noreferrer"
+              }
+              target={isRouted ? undefined : "_blank"}
+            >
+              {content}
+            </LinkElement>
+          )
+        }
+
+        if (href === undefined) {
+          // biome-ignore lint/suspicious/noArrayIndexKey: position is the identity — see `toMarkedContent`
+          return <span key={groupIndex}>{content}</span>
+        }
+
+        const isRouted = getIsRoutedHref(href)
+
+        const LinkElement = isRouted ? RouterLink : "a"
+
+        return (
+          <LinkElement
+            className={toClassName(
+              "hover:underline",
+              FOCUS_RING_CLASS,
+            )}
+            href={href}
+            // biome-ignore lint/suspicious/noArrayIndexKey: position is the identity — see `toMarkedContent`
+            key={groupIndex}
+          >
+            {content}
+          </LinkElement>
+        )
+      })}
+    </span>
+  )
+}

package/src/MarkdownLine/inlineMarkdown.test.ts

@@ -0,0 +1,253 @@
+/**
+ * The inline grammar, asserted as data.
+ *
+ * Kept away from React on purpose: what `MarkdownLine` renders is a
+ * question about elements, and what the markdown *means* is a
+ * question about runs. Mixing them is how a parser bug gets
+ * diagnosed as a styling bug.
+ *
+ * Fixture strings are INVENTED. This repo is published.
+ */
+
+import { describe, expect, test } from "vitest"
+
+import {
+  toInlineMarkdownRuns,
+  toPlainMarkdownText,
+} from "./inlineMarkdown.ts"
+
+/** The runs, with the marks that are off left out — signal only. */
+const toShape = (value: string) =>
+  toInlineMarkdownRuns(value).map((run) => ({
+    ...(run.href === undefined ? {} : { href: run.href }),
+    ...(run.isCode ? { isCode: true } : {}),
+    ...(run.isEmphasis ? { isEmphasis: true } : {}),
+    ...(run.isStrikethrough
+      ? { isStrikethrough: true }
+      : {}),
+    ...(run.isStrong ? { isStrong: true } : {}),
+    text: run.text,
+  }))
+
+describe("marks", () => {
+  test("bold, italic, code and strikethrough each mark their run", () => {
+    expect(toShape("**bold**")).toEqual([
+      { isStrong: true, text: "bold" },
+    ])
+
+    expect(toShape("*italic*")).toEqual([
+      { isEmphasis: true, text: "italic" },
+    ])
+
+    expect(toShape("`code`")).toEqual([
+      { isCode: true, text: "code" },
+    ])
+
+    expect(toShape("~~gone~~")).toEqual([
+      { isStrikethrough: true, text: "gone" },
+    ])
+  })
+
+  test("`__` is bold and `_` is italic, the same as their asterisks", () => {
+    expect(toShape("__bold__")).toEqual([
+      { isStrong: true, text: "bold" },
+    ])
+
+    expect(toShape("_italic_")).toEqual([
+      { isEmphasis: true, text: "italic" },
+    ])
+  })
+
+  test("marks nest, and the inner run carries both", () => {
+    expect(toShape("**bold and *both* here**")).toEqual([
+      { isStrong: true, text: "bold and " },
+      { isEmphasis: true, isStrong: true, text: "both" },
+      { isStrong: true, text: " here" },
+    ])
+  })
+
+  test("an unclosed marker is literal text", () => {
+    expect(toShape("2 * 3 is 6")).toEqual([
+      { text: "2 * 3 is 6" },
+    ])
+
+    expect(toShape("**not closed")).toEqual([
+      { text: "**not closed" },
+    ])
+  })
+
+  test("a backslash escapes a marker", () => {
+    expect(toShape(String.raw`\*not italic\*`)).toEqual([
+      { text: "*not italic*" },
+    ])
+  })
+})
+
+describe("the file-name cases this was built for", () => {
+  /**
+   * The owner's own example, and the reason the feature exists:
+   *
+   *   *"Ingest 53 movies from `Downloads/MOVIES` into `G:\Movies`"*
+   */
+  test("a Windows path in a code span keeps its backslash", () => {
+    expect(
+      toShape(
+        String.raw`Ingest 53 movies from \`Downloads/MOVIES\` into \`G:\Movies\``.replaceAll(
+          String.raw`\``,
+          "`",
+        ),
+      ),
+    ).toEqual([
+      { text: "Ingest 53 movies from " },
+      { isCode: true, text: "Downloads/MOVIES" },
+      { text: " into " },
+      { isCode: true, text: String.raw`G:\Movies` },
+    ])
+  })
+
+  test("snake_case survives — an underscore inside a word marks nothing", () => {
+    expect(
+      toShape("Run ingest_the_files.sh nightly"),
+    ).toEqual([{ text: "Run ingest_the_files.sh nightly" }])
+  })
+
+  test("a bare backslash before a letter stays a backslash", () => {
+    expect(toShape(String.raw`G:\Movies`)).toEqual([
+      { text: String.raw`G:\Movies` },
+    ])
+  })
+
+  test("a fence of two holds a literal backtick", () => {
+    expect(toShape("`` ` ``")).toEqual([
+      { isCode: true, text: "`" },
+    ])
+  })
+})
+
+describe("links", () => {
+  test("link text becomes runs that carry the destination", () => {
+    expect(
+      toShape("see [the PR](/pulls/53) first"),
+    ).toEqual([
+      { text: "see " },
+      { href: "/pulls/53", text: "the PR" },
+      { text: " first" },
+    ])
+  })
+
+  test("marks inside link text survive, and stay linked", () => {
+    expect(toShape("[**PR** 53](/pulls/53)")).toEqual([
+      { href: "/pulls/53", isStrong: true, text: "PR" },
+      { href: "/pulls/53", text: " 53" },
+    ])
+  })
+
+  test("a destination's title is not part of the URL", () => {
+    expect(
+      toShape('[x](/pulls/53 "The pull request")'),
+    ).toEqual([{ href: "/pulls/53", text: "x" }])
+  })
+
+  test("a bare URL is a link, and a trailing full stop is not part of it", () => {
+    expect(
+      toShape("Read https://example.invalid/notes."),
+    ).toEqual([
+      { text: "Read " },
+      {
+        href: "https://example.invalid/notes",
+        text: "https://example.invalid/notes",
+      },
+      { text: "." },
+    ])
+  })
+
+  test("a parenthesis the URL opened is kept", () => {
+    expect(
+      toShape("https://example.invalid/Rack_(shelf)"),
+    ).toEqual([
+      {
+        href: "https://example.invalid/Rack_(shelf)",
+        text: "https://example.invalid/Rack_(shelf)",
+      },
+    ])
+  })
+
+  test("`www.` autolinks, because the CodeMirror surface does", () => {
+    expect(toShape("www.example.invalid/x")).toEqual([
+      {
+        href: "https://www.example.invalid/x",
+        text: "www.example.invalid/x",
+      },
+    ])
+  })
+
+  test("an angle autolink is its own text", () => {
+    expect(toShape("<https://example.invalid/x>")).toEqual([
+      {
+        href: "https://example.invalid/x",
+        text: "https://example.invalid/x",
+      },
+    ])
+  })
+
+  /**
+   * The guard is `../safeUrls.ts`, shared with the CodeMirror
+   * surface. What is asserted here is the *response* to a refusal:
+   * every character of the source stays on screen, so a reader can
+   * see the trap rather than being shown a link-coloured word that
+   * quietly does nothing.
+   */
+  test("a refused scheme keeps its whole source and links nothing", () => {
+    expect(
+      toShape("[click me](javascript:alert(1))"),
+    ).toEqual([{ text: "[click me](javascript:alert(1))" }])
+  })
+
+  test("a link inside link text does not nest", () => {
+    expect(toShape("[a [b](/b) c](/a)")).toEqual([
+      { href: "/a", text: "a [b](/b) c" },
+    ])
+  })
+})
+
+describe("it is a line, and it is inline-only", () => {
+  test("block markup is literal", () => {
+    expect(toShape("# Not a heading")).toEqual([
+      { text: "# Not a heading" },
+    ])
+
+    expect(toShape("- Not a list item")).toEqual([
+      { text: "- Not a list item" },
+    ])
+
+    expect(toShape("> Not a quote")).toEqual([
+      { text: "> Not a quote" },
+    ])
+  })
+
+  test("a newline collapses to a space", () => {
+    expect(toShape("first\n  second")).toEqual([
+      { text: "first second" },
+    ])
+  })
+
+  test("an empty string is no runs at all", () => {
+    expect(toShape("")).toEqual([])
+  })
+})
+
+describe("toPlainMarkdownText", () => {
+  test("gives the words with every marker gone", () => {
+    expect(
+      toPlainMarkdownText(
+        "Ingest **53** movies into `G:/Movies` — [see the plan](/plan)",
+      ),
+    ).toBe("Ingest 53 movies into G:/Movies — see the plan")
+  })
+
+  test("leaves a string with no markup exactly as it was", () => {
+    expect(toPlainMarkdownText("Buy more filament")).toBe(
+      "Buy more filament",
+    )
+  })
+})