@charcuterie/ui 3.19.1 → 3.20.0

package/src/MarkdownLine/MarkdownLine.mdx

@@ -0,0 +1,135 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as MarkdownLineStories from "./MarkdownLine.stories";
+
+<Meta of={MarkdownLineStories} />
+
+# MarkdownLine
+
+**One line of markdown, drawn with its inline marks and nothing else.** Reach for it
+wherever a stored string is a *name* rather than a document — a card title, a lane heading,
+a table cell, a breadcrumb.
+
+<Canvas of={MarkdownLineStories.Default} />
+
+## Props
+
+<Controls />
+
+## Why marks belong in a title
+
+A grid of task names set in one flat weight is a wall. The parts that tell two cards apart —
+the path, the urgency, the thing that is already done — are exactly the parts markdown would
+have marked, so the marks are doing the same job the priority bar and the project colour do
+one layer up: making a list **scannable**.
+
+<Canvas of={MarkdownLineStories.WhyItHelps} />
+
+## It is inline-only, and it is one line
+
+| Rendered | Literal text |
+| --- | --- |
+| `**bold**`, `__bold__` | `# heading` |
+| `*italic*`, `_italic_` | `- list item`, `1. list item` |
+| `` `code` `` | `> blockquote` |
+| `~~strikethrough~~` | `\| table \| row \|` |
+| `[text](url)`, `<url>`, bare `https://…` and `www.…` | `![image](url)` |
+
+A newline collapses to a space. Every surface that draws one of these clamps to one or two
+lines anyway, so a hard break would only push the second half of a title out of a box that
+was measured for one line.
+
+## File names are not markup
+
+The case this component is most often asked to get wrong.
+
+<Canvas of={MarkdownLineStories.FileNames} />
+
+`ingest_the_files.sh` keeps its underscores because CommonMark's flanking rules say an
+underscore **inside a word** opens nothing — the rule that makes `_` and `*` genuinely
+different characters, and the one a hand-rolled "strip the markdown" regex always misses.
+`2 * 3 * 4` is arithmetic for the same reason: a delimiter followed by a space cannot open.
+
+## `href` — a link inside a link
+
+<Canvas of={MarkdownLineStories.AsALink} />
+
+A card title is usually a link to the card, and a title may also *contain* a link. An anchor
+inside an anchor is invalid HTML: the parser closes the outer one at the inner one's start
+tag, so the text after the inner link silently stops opening the card. It looks completely
+correct and half of it does not work.
+
+So `href` is a prop rather than something you wrap the component in. Given one, the plain
+runs become anchors to `href` and a markdown link stays a **sibling** anchor with its own
+destination:
+
+```tsx
+<MarkdownLine href={`/tasks/${task.id}`} value={task.title} />
+```
+
+Consecutive runs sharing a destination are merged into one anchor, so `**Ship** it` is a
+single tab stop and one entry in a screen reader's link list.
+
+A markdown link **splits** the line into more than one anchor, and each is named by the words
+it covers — `Ship`, `#53`, `tonight`. That is honest, and it is not good: `tonight` is a poor
+name for a link to a task. Naming all three after the whole line was tried and is worse — two
+links with the same name are ambiguous to anything driving the page by name, and this
+library's own `expectAgentDrivable` refuses it. The conclusion is a design one rather than an
+API one: **a link usually belongs in a task's description**, where it has a sentence around
+it, rather than in its title.
+
+<Canvas of={MarkdownLineStories.Routed} />
+
+An in-app destination goes through the injected `RouterLinkProvider`; an off-origin one
+does not, and opens in a new tab. A title that names a pull request is a reference, and
+following it should not lose the board the reader was on.
+
+## `isInsideLink` — when the card is already the link
+
+<Canvas of={MarkdownLineStories.InsideACardLink} />
+
+The third and last answer to *who owns the link here*. `href` says this component does;
+neither says the markdown links do; `isInsideLink` says **nobody** — draw the marks and emit
+no anchor at all.
+
+Reach for it whenever the line sits inside a link the caller already owns, which is what a
+whole-card link is. The trap it closes 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 an
+anchor without anybody writing `[]()`.
+
+## Anywhere a string is required
+
+`aria-label`, `title`, `document.title`, a confirmation sentence — call `toPlainMarkdownText`
+rather than writing a regex that strips the markup:
+
+```ts
+import { toPlainMarkdownText } from "@charcuterie/ui"
+
+document.title = `${toPlainMarkdownText(task.title)} — Docket`
+```
+
+It is the **same parse** the component renders from, so it cannot drift. A second stripper is
+how a card comes to read `Ingest 53 movies` while its own tooltip reads
+``Ingest 53 movies from `Downloads/MOVIES` ``.
+
+## A refused URL keeps its source
+
+<Canvas of={MarkdownLineStories.RefusedUrl} />
+
+URLs cross `safeUrls.ts` — an allowlist of `http`, `https`, `mailto` and `tel` — before they
+reach an `href`, the same module `MarkdownView` and the CodeMirror editor use. A scheme that
+does not survive it produces **no anchor at all**, and every character of the source stays on
+screen. A reader who can see `[click me](javascript:…)` is better served than one shown a
+confident blue word that silently refuses to work.
+
+## Not a small `MarkdownView`
+
+`MarkdownView` renders a *document*, through CodeMirror, from the optional
+`@charcuterie/ui/markdown-editor-codemirror` entry point. Neither half suits a name: an
+editor state, a syntax tree and a decoration set per card is an absurd price for forty
+characters, and the main entry may not reach the CodeMirror stack at all.
+
+So this is a second parser, which is worth being nervous about — two parsers are two answers
+to "what does this markdown mean". Three things keep them honest: this one is **inline-only**,
+so there is no block level to disagree about; both call the **same** URL guard; and the
+flanking rules here are CommonMark's rather than a convenient approximation.

package/src/MarkdownLine/MarkdownLine.stories.tsx

@@ -0,0 +1,290 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import type { ReactNode } from "react"
+
+import {
+  StoryCell,
+  StoryGrid,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import { RouterLinkProvider } from "../RouterLink/RouterLinkProvider.tsx"
+import type { RouterLinkProps } from "../RouterLink/routerLink.ts"
+import { MarkdownLine } from "./MarkdownLine.tsx"
+
+/**
+ * A stand-in for react-router's `<Link>`, the same one
+ * `TextLink.stories.tsx` uses. The marker attribute is how the
+ * boards show which destinations the injected router was handed and
+ * which went straight to the platform.
+ */
+const SoftRouterLink = ({
+  href,
+  ...linkProps
+}: RouterLinkProps): ReactNode => (
+  <a {...linkProps} data-router="soft" href={href} />
+)
+
+/**
+ * Task names, invented. Every string in this file is fixture data —
+ * this package is published, and a screenshot of a story is not
+ * greppable by anybody checking for household detail later.
+ */
+const CARD_TITLES = [
+  String.raw`Ingest 53 movies from \`Downloads/MOVIES\` into \`G:\Movies\``.replaceAll(
+    String.raw`\``,
+    "`",
+  ),
+  "**Urgent:** the rack fans are running at 100%",
+  "Re-tag the *Halloween* playlist before October",
+  "~~Buy a second spool~~ — arrived Tuesday",
+  "Run ingest_the_files.sh nightly, not hourly",
+]
+
+const meta = {
+  title: "Components/Content/MarkdownLine",
+  component: MarkdownLine,
+  parameters: { layout: "padded" },
+  args: {
+    value: CARD_TITLES[0] ?? "",
+  },
+} satisfies Meta<typeof MarkdownLine>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {}
+
+/**
+ * The four marks, each in the shape a title actually uses it for.
+ * Code is the one that earns its place most often — an agent-written
+ * task name is a third file paths by volume.
+ */
+export const AllMarks: Story = {
+  render: () => (
+    <StorySection title="Inline marks only. A heading, a list marker and a table pipe are literal characters here.">
+      <StoryGrid columns={2}>
+        <StoryCell label="code">
+          <MarkdownLine value={CARD_TITLES[0] ?? ""} />
+        </StoryCell>
+
+        <StoryCell label="strong">
+          <MarkdownLine value={CARD_TITLES[1] ?? ""} />
+        </StoryCell>
+
+        <StoryCell label="emphasis">
+          <MarkdownLine value={CARD_TITLES[2] ?? ""} />
+        </StoryCell>
+
+        <StoryCell label="strikethrough">
+          <MarkdownLine value={CARD_TITLES[3] ?? ""} />
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * WHY THE MARKS ARE WORTH HAVING AT ALL.
+ *
+ * Five names in one flat weight against the same five with their
+ * marks drawn. The argument is not decoration: in the flat column
+ * the eye has to read every title to the end to tell two of them
+ * apart, and in the marked one the part that *differs* is the part
+ * that is drawn differently.
+ */
+export const WhyItHelps: Story = {
+  render: () => (
+    <StorySection title="The same five task names, as source and as a line.">
+      <StoryGrid columns={2}>
+        <StoryCell align="stretch" label="raw markdown">
+          <ul className="flex flex-col gap-2 text-content-primary text-md">
+            {CARD_TITLES.map((title) => (
+              <li key={title}>{title}</li>
+            ))}
+          </ul>
+        </StoryCell>
+
+        <StoryCell align="stretch" label="MarkdownLine">
+          <ul className="flex flex-col gap-2 text-content-primary text-md">
+            {CARD_TITLES.map((title) => (
+              <li key={title}>
+                <MarkdownLine value={title} />
+              </li>
+            ))}
+          </ul>
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * A file name is the case this component is most often asked to get
+ * *wrong*. `ingest_the_files.sh` has two underscores and is not
+ * italic, because CommonMark's flanking rules say an underscore
+ * inside a word opens nothing — and a Windows path keeps its
+ * backslashes.
+ */
+export const FileNames: Story = {
+  render: () => (
+    <StorySection title="Markup that is not markup. None of these lines has a mark in it.">
+      <StoryGrid columns={1}>
+        <StoryCell align="stretch" label="left alone">
+          <ul className="flex flex-col gap-2 font-mono text-content-primary text-sm">
+            <li>
+              <MarkdownLine value="Run ingest_the_files.sh nightly" />
+            </li>
+
+            <li>
+              <MarkdownLine
+                value={String.raw`Copy to G:\Movies\Kids`}
+              />
+            </li>
+
+            <li>
+              <MarkdownLine value="2 * 3 * 4 is twenty-four" />
+            </li>
+
+            <li>
+              <MarkdownLine value="# 4 in the queue" />
+            </li>
+          </ul>
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * THE `href` CASE, and the one that is easy to get wrong.
+ *
+ * A card title is usually a link to the card. When the title also
+ * *contains* a link, `href` makes the component emit siblings —
+ * plain runs anchored to the card, the markdown link anchored to its
+ * own destination. Nesting them would be invalid HTML, and the
+ * browser would silently drop the second half of the card's link.
+ */
+export const AsALink: Story = {
+  render: () => (
+    <StorySection title="`href` anchors the plain text. A link inside the line keeps its own destination.">
+      <StoryGrid columns={1}>
+        <StoryCell
+          align="stretch"
+          label="the whole line opens the task"
+        >
+          <MarkdownLine
+            href="/tasks/7"
+            value="Ingest **53** movies overnight"
+          />
+        </StoryCell>
+
+        <StoryCell
+          align="stretch"
+          label="two destinations, three sibling anchors"
+        >
+          <MarkdownLine
+            href="/tasks/7"
+            value="Ship [#53](https://example.invalid/pulls/53) tonight"
+          />
+        </StoryCell>
+
+        <StoryCell
+          align="stretch"
+          label="no href — only the markdown link is clickable"
+        >
+          <MarkdownLine value="Ship [#53](https://example.invalid/pulls/53) tonight" />
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * With a router injected, an in-app destination goes through it and
+ * an off-origin one does not — `data-router="soft"` marks the ones
+ * the router was handed. Off-origin links open in a new tab, because
+ * a title that names a pull request is a reference and following it
+ * should not lose the board the reader was on.
+ */
+export const Routed: Story = {
+  decorators: [
+    (Story) => (
+      <RouterLinkProvider link={SoftRouterLink}>
+        <Story />
+      </RouterLinkProvider>
+    ),
+  ],
+  render: () => (
+    <StorySection title="The injected router gets `/tasks/7`. It never gets the pull request.">
+      <StoryGrid columns={1}>
+        <StoryCell
+          align="stretch"
+          label="routed and unrouted, in one line"
+        >
+          <MarkdownLine
+            href="/tasks/7"
+            value="Ship [#53](https://example.invalid/pulls/53) tonight"
+          />
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * A URL whose scheme is not on `safeUrls.ts`'s allowlist keeps
+ * **every character of its source** and becomes no link at all. A
+ * reader who can see the trap is better served than one shown a
+ * confident blue word that silently refuses to work.
+ */
+/**
+ * A whole card title as one link, with a code span inside it — the
+ * shape Docket's backlog rows and board cards are.
+ *
+ * It exists so a test can assert the link's **accessible name**,
+ * which is where a mark's surrounding spaces go missing without
+ * anything on screen changing.
+ */
+export const TitleAsALink: Story = {
+  render: () => (
+    <MarkdownLine
+      href="/tasks/7"
+      value="Ingest 53 movies from `Downloads/MOVIES` tonight"
+    />
+  ),
+}
+
+/**
+ * INSIDE A WHOLE-CARD LINK.
+ *
+ * The card is the link — middle-click opens it, like anything else
+ * on the web — so the line inside it emits no anchor of its own. The
+ * marks still draw; a markdown link's text still reads; nothing
+ * inside navigates separately.
+ *
+ * The bare URL is the case that makes this a prop rather than a
+ * convention. It autolinks, so a captured note ending in a URL would
+ * nest an anchor without anybody having typed `[]()`.
+ */
+export const InsideACardLink: Story = {
+  render: () => (
+    <a
+      className="block max-w-sm rounded-lg border border-border-subtle bg-surface-raised p-3 hover:bg-surface-sunken"
+      href="/triage/7"
+    >
+      <MarkdownLine
+        className="block font-medium text-content-primary"
+        isInsideLink
+        value="Ingest 53 movies from `Downloads/MOVIES` — https://example.invalid/list"
+      />
+
+      <span className="mt-1 block text-content-secondary text-sm">
+        Filed from the capture inbox
+      </span>
+    </a>
+  ),
+}
+
+export const RefusedUrl: Story = {
+  args: { value: "[click me](javascript:alert(1))" },
+}

package/src/MarkdownLine/MarkdownLine.test.tsx

@@ -0,0 +1,241 @@
+/**
+ * What the runs become in the DOM — the half `inlineMarkdown.test.ts`
+ * deliberately does not assert.
+ *
+ * The load-bearing test here is the nesting one. Every other
+ * assertion in this file would still pass if the component wrapped
+ * itself in an anchor, the page would look exactly right, and half
+ * of each title would quietly stop opening the task.
+ *
+ * Subjects are the composed **stories**, per this package's
+ * story/test split — so what is asserted is what a reader sees.
+ */
+
+import { composeStories } from "@storybook/react"
+import { expect, userEvent } from "storybook/test"
+import { test } from "vitest"
+
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import * as stories from "./MarkdownLine.stories.tsx"
+
+const {
+  AllMarks,
+  AsALink,
+  Default,
+  FileNames,
+  InsideACardLink,
+  RefusedUrl,
+  Routed,
+  TitleAsALink,
+} = composeStories(stories)
+
+test("a code span is a `code` element, and the backticks are gone", async () => {
+  const { canvasElement } = await mountStory(Default)
+
+  await expect(
+    [...canvasElement.querySelectorAll("code")].map(
+      (element) => element.textContent,
+    ),
+  ).toEqual(["Downloads/MOVIES", String.raw`G:\Movies`])
+
+  await expect(canvasElement.textContent).toBe(
+    String.raw`Ingest 53 movies from Downloads/MOVIES into G:\Movies`,
+  )
+})
+
+test("each mark renders its own element", async () => {
+  const { canvasElement } = await mountStory(AllMarks)
+
+  await expect(
+    canvasElement.querySelector("strong")?.textContent,
+  ).toBe("Urgent:")
+
+  await expect(
+    canvasElement.querySelector("em")?.textContent,
+  ).toBe("Halloween")
+
+  await expect(
+    canvasElement.querySelector("s")?.textContent,
+  ).toBe("Buy a second spool")
+})
+
+/**
+ * The rule that keeps a file name a file name. Asserted on the DOM
+ * rather than only on the runs because this is the one a reader
+ * reports — *"why is half my path in italics"* — and the story is
+ * what they would be looking at.
+ */
+test("an underscore inside a word marks nothing", async () => {
+  const { canvasElement } = await mountStory(FileNames)
+
+  await expect(canvasElement.querySelector("em")).toBe(null)
+  await expect(canvasElement.querySelector("strong")).toBe(
+    null,
+  )
+
+  await expect(canvasElement.textContent).toContain(
+    "ingest_the_files.sh",
+  )
+})
+
+test("a line with no href has nothing to click", async () => {
+  const { canvasElement } = await mountStory(Default)
+
+  await expect(canvasElement.querySelector("a")).toBe(null)
+})
+
+/**
+ * `<a><a/></a>` is not something React refuses and not something the
+ * browser reports. The HTML parser closes the outer anchor at the
+ * inner one's start tag, so the text *after* the inner link stops
+ * being part of the card's link — it looks correct and half of it
+ * does not work.
+ */
+test("a link inside the line is a SIBLING anchor, never a nested one", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AsALink)
+
+  await expect(canvasElement.querySelector("a a")).toBe(
+    null,
+  )
+
+  await expect(
+    canvas
+      .getAllByRole("link")
+      .map((link: HTMLElement) =>
+        link.getAttribute("href"),
+      ),
+  ).toEqual([
+    "/tasks/7",
+    "/tasks/7",
+    "https://example.invalid/pulls/53",
+    "/tasks/7",
+    "https://example.invalid/pulls/53",
+  ])
+})
+
+/**
+ * Each anchor is named by the words it covers, and the names are
+ * therefore DISTINCT.
+ *
+ * Naming all three after the whole line was tried first and is
+ * worse: two links with one name are ambiguous to anything driving
+ * the page by name, and `expectAgentDrivable` refuses it outright.
+ * What is announced now matches what is on screen, which is also
+ * WCAG 2.5.3.
+ */
+test("split anchors are named by their own words", async () => {
+  const { canvas } = await mountStory(Routed)
+
+  const link = expectAgentDrivable(canvas, {
+    name: "Ship",
+    role: "link",
+  })
+
+  await expect(link).toHaveAttribute("href", "/tasks/7")
+
+  await expect(
+    expectAgentDrivable(canvas, {
+      name: "tonight",
+      role: "link",
+    }),
+  ).toHaveAttribute("href", "/tasks/7")
+})
+
+test("Tab reaches every anchor in the line", async () => {
+  const { canvas } = await mountStory(Routed)
+
+  const links = canvas.getAllByRole("link")
+
+  await userEvent.tab()
+
+  await expect(links[0]).toHaveFocus()
+
+  await userEvent.tab()
+
+  await expect(links[1]).toHaveFocus()
+})
+
+/**
+ * The injected router gets the in-app destination and never gets the
+ * off-origin one, which would push a route the SPA does not have
+ * onto its history stack.
+ */
+test("the router is handed the in-app destination only", async () => {
+  const { canvas } = await mountStory(Routed)
+
+  const [task, pullRequest] = canvas.getAllByRole("link")
+
+  await expect(task).toHaveAttribute("data-router", "soft")
+  await expect(pullRequest).not.toHaveAttribute(
+    "data-router",
+  )
+  await expect(pullRequest).toHaveAttribute(
+    "target",
+    "_blank",
+  )
+  await expect(pullRequest).toHaveAttribute(
+    "rel",
+    "noopener noreferrer",
+  )
+})
+
+/**
+ * The guard itself lives in `safeUrls.ts` and is tested there. What
+ * matters here is the *response* to a refusal: no anchor at all,
+ * rather than a dead one.
+ */
+test("a refused scheme renders its source as text", async () => {
+  const { canvasElement } = await mountStory(RefusedUrl)
+
+  await expect(canvasElement.querySelector("a")).toBe(null)
+
+  await expect(canvasElement.textContent).toBe(
+    "[click me](javascript:alert(1))",
+  )
+})
+
+/**
+ * THE SPACES AROUND A MARK SURVIVE INTO THE ACCESSIBLE NAME.
+ *
+ * The name computation trims each **element** child's contribution
+ * before joining them, so a line whose every run was wrapped in a
+ * `<span>` announced as `Ingest 53 movies fromDownloads/MOVIESinto`
+ * — painted correctly, announced as one run-on word, and invisible
+ * to any assertion that reads `textContent`.
+ *
+ * Found through `Board`'s move handle, which is named after the
+ * card's title. The fix is that an unmarked run is a text node
+ * rather than a wrapped one; this is the guard that keeps it.
+ */
+test("the accessible name keeps the spaces around a mark", async () => {
+  const { canvas } = await mountStory(TitleAsALink)
+
+  await expect(
+    canvas.getByRole("link", {
+      name: "Ingest 53 movies from Downloads/MOVIES tonight",
+    }),
+  ).toBeInTheDocument()
+})
+
+/**
+ * `isInsideLink` emits no anchor of its own — not even for a bare
+ * URL, which is the case that makes it a prop rather than a
+ * convention. A captured note ending in a URL would otherwise nest
+ * an anchor inside the card's link with nobody having typed `[]()`.
+ */
+test("isInsideLink draws the marks and adds no anchor", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(InsideACardLink)
+
+  await expect(canvasElement.querySelector("a a")).toBe(
+    null,
+  )
+
+  await expect(canvas.getAllByRole("link")).toHaveLength(1)
+
+  await expect(
+    canvasElement.querySelector("code")?.textContent,
+  ).toBe("Downloads/MOVIES")
+})