@charcuterie/ui 3.13.0 → 3.14.0

package/src/markdownEditorCodeMirror/MarkdownView.stories.tsx

@@ -0,0 +1,314 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { useState } from "react"
+
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+} from "../board.storyHelpers.tsx"
+import { Card } from "../Card/Card.tsx"
+import { MarkdownEditorCodeMirror } from "./MarkdownEditorCodeMirror.tsx"
+import { MarkdownView } from "./MarkdownView.tsx"
+
+/**
+ * Invented, like every fixture in this repo — a task in a made-up
+ * homelab project, and deliberately the **same string** the editor's
+ * stories use.
+ *
+ * That is what makes the `SameAsTheEditor` story an argument rather
+ * than an illustration: the two surfaces are handed one document and
+ * a reader compares the frames.
+ */
+const SAMPLE = `# Rack move, phase two
+
+The **short** version: pull the _old_ switch, land the new one, and
+keep the ~~three~~ two uplinks live throughout.
+
+## Before the window
+
+- [x] Label every patch lead
+- [ ] Photograph the current cabling
+- [ ] Cut over at 02:00
+
+1. Power down the shelf
+2. Swap the rails
+3. Bring it back up
+
+> Nothing here touches the storage pool.
+
+Run \`ping -c 3 gateway.invalid\` before and after, and read
+[the runbook](https://example.invalid/runbook) first.
+
+| Port | Goes to |
+| --- | --- |
+| 1 | uplink |
+| 2 | shelf |
+
+\`\`\`sh
+ip -br addr show
+\`\`\`
+
+Replacement rails ordered from https://example.invalid/product?id=1234
+`
+
+/**
+ * A drawing rather than a fetched file, so the story needs no
+ * network and the frame is the same on every machine. The same
+ * technique `Avatar`'s portrait uses, and one of the few things
+ * `data:` is genuinely good for.
+ */
+const DIAGRAM_URL = `data:image/svg+xml;utf8,${encodeURIComponent(
+  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 240 60"><rect width="240" height="60" rx="6" fill="#2F6F4E"/><rect x="12" y="14" width="96" height="32" rx="4" fill="#F2E8CF"/><rect x="132" y="14" width="96" height="32" rx="4" fill="#F2E8CF"/><path d="M108 30h24" stroke="#F2E8CF" stroke-width="4"/></svg>',
+)}`
+
+const WITH_IMAGE = `## Rack inventory
+
+![Two shelves and the uplink between them](${DIAGRAM_URL})
+
+| Port | Goes to | **Speed** |
+| :--- | :---: | ---: |
+| 1 | uplink | 10G |
+| 2 | shelf | 1G |
+`
+
+/**
+ * The document nobody in this house wrote: what a fetched file looks
+ * like when its author would rather it did something else.
+ *
+ * Every line here is a thing that used to work. The `javascript:`
+ * link opened and ran; the `<script>` was never a script but is
+ * worth showing anyway; the `data:text/html` image was an `src` this
+ * component wrote verbatim.
+ */
+const HOSTILE = `# A file fetched from somewhere else
+
+[Looks like a link](javascript:alert(document.domain)) — and is not one.
+
+<script>alert("this is four coloured characters, not a script")</script>
+
+<img src=x onerror="alert(1)">
+
+![Not an image](data:text/html,<script>alert(1)</script>)
+
+[This one is fine](https://example.invalid/runbook), and so is ./RELEASING.md.
+`
+
+const CHECKLIST = `## Before the window
+
+- [x] Label every patch lead
+- [ ] Photograph the current cabling
+- [ ] Cut over at 02:00
+`
+
+/**
+ * A second list rather than the same one twice, and the difference
+ * is load bearing: two checkboxes with the same accessible name on
+ * one page are two things `getByRole("checkbox", { name })` cannot
+ * tell apart — which is the drivability property this library gates
+ * on, failing in a *story* rather than in a component.
+ */
+const TICKABLE_CHECKLIST = `## After the window
+
+- [x] Bring the shelf back up
+- [ ] Re-check both uplinks
+- [ ] Close the change record
+`
+
+/**
+ * The state the checkbox story cannot show without one: a tick that
+ * goes somewhere.
+ *
+ * `onToggleTask` hands back the whole next markdown document, which
+ * is the same shape the editors' `onChange` uses — so a consumer
+ * wires one autosave and points both at it.
+ */
+const TickableChecklist = () => {
+  const [value, setValue] = useState(TICKABLE_CHECKLIST)
+
+  return (
+    <MarkdownView
+      label="Tickable checklist"
+      onToggleTask={setValue}
+      value={value}
+    />
+  )
+}
+
+const meta = {
+  title: "Components/Data/MarkdownView",
+  component: MarkdownView,
+  parameters: { layout: "padded" },
+  args: {
+    label: "Description",
+    onToggleTask: undefined,
+    value: SAMPLE,
+  },
+} satisfies Meta<typeof MarkdownView>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * The whole point in one frame: the document is drawn, and there is
+ * **no toolbar above it**. Not a disabled one, not a hidden one —
+ * `getAllByRole("toolbar")` returns nothing, because nothing in this
+ * component can render one.
+ */
+export const Default: Story = {}
+
+/**
+ * The same string, in both surfaces, side by side.
+ *
+ * This is the requirement the component exists to meet, and it is
+ * the one a screenshot can actually check: the heading is the same
+ * size, the table has the same borders and the same alignment, the
+ * checkboxes are in the same places, and the bare URL is a link in
+ * both. They agree because they are the same code — one parser, one
+ * set of range rules, one theme — rather than because somebody kept
+ * two renderers in step.
+ */
+export const SameAsTheEditor: Story = {
+  render: (viewProps) => (
+    <StoryGrid columns={2}>
+      <StoryCell align="stretch" label="MarkdownView">
+        <MarkdownView {...viewProps} />
+      </StoryCell>
+
+      <StoryCell
+        align="stretch"
+        label="MarkdownEditorCodeMirror"
+      >
+        <MarkdownEditorCodeMirror
+          defaultValue={SAMPLE}
+          label="Description"
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * Everything the reader can be shown, including the two states that
+ * are easy to get wrong: an empty document, and a checkbox nobody
+ * may tick.
+ */
+export const AllStates: Story = {
+  render: (viewProps) => (
+    <StoryGrid columns={2}>
+      <StoryCell
+        align="stretch"
+        label="checkboxes are inert without onToggleTask"
+      >
+        <MarkdownView
+          {...viewProps}
+          label="Read-only checklist"
+          value={CHECKLIST}
+        />
+      </StoryCell>
+
+      <StoryCell
+        align="stretch"
+        label="…and operable with one"
+      >
+        <TickableChecklist />
+      </StoryCell>
+
+      <StoryCell
+        align="stretch"
+        label="an image and a table"
+      >
+        <MarkdownView
+          {...viewProps}
+          label="Rack inventory"
+          value={WITH_IMAGE}
+        />
+      </StoryCell>
+
+      <StoryCell align="stretch" label="an empty document">
+        <MarkdownView
+          {...viewProps}
+          label="Nothing written yet"
+          value=""
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * A file from a git host, rendering as the characters it contains.
+ *
+ * The `javascript:` link keeps its brackets and its parentheses on
+ * purpose. A link-coloured word that silently refuses to work tells
+ * the reader nothing; the source tells them exactly what the file
+ * tried to do.
+ */
+export const HostileMarkdown: Story = {
+  args: {
+    label: "README.md at 9f3c1ab",
+    value: HOSTILE,
+  },
+}
+
+/**
+ * The three container widths. A table that will not fit scrolls
+ * inside its own block rather than pushing the column sideways, and
+ * an image is capped at the width it is given — which is what keeps
+ * the Narrow View readable instead of merely small.
+ */
+export const Responsive: Story = {
+  render: (viewProps) => (
+    <ContainerBoard>
+      {(width) => (
+        <Card heading={`Rack inventory (${width})`}>
+          <MarkdownView
+            {...viewProps}
+            label={`Rack inventory at ${width}`}
+            value={WITH_IMAGE}
+          />
+        </Card>
+      )}
+    </ContainerBoard>
+  ),
+}
+
+/**
+ * The complete keyboard path, which for a reader is short and is the
+ * point.
+ *
+ * The document itself is **not** a tab stop — there is nothing in it
+ * to operate, and a reading surface that swallowed a Tab would be
+ * one more thing between the reader and the next control. What *is*
+ * reachable is every link in it, in document order, because they are
+ * real anchors rather than painted spans: Tab to one, Enter to open
+ * it, and the context menu will copy its address.
+ *
+ * The buttons on either side are there so the path is visible — Tab
+ * from the first lands on each link in turn and ends on the second.
+ */
+export const Interactive: Story = {
+  args: {
+    label: "Rack move, phase two",
+    value: SAMPLE,
+  },
+  render: (viewProps) => (
+    <div className="flex flex-col items-start gap-3">
+      <button
+        className="rounded-md border border-border-default px-3 py-1 text-content-primary text-sm"
+        type="button"
+      >
+        {"Before"}
+      </button>
+
+      <MarkdownView {...viewProps} />
+
+      <button
+        className="rounded-md border border-border-default px-3 py-1 text-content-primary text-sm"
+        type="button"
+      >
+        {"After"}
+      </button>
+    </div>
+  ),
+}

package/src/markdownEditorCodeMirror/MarkdownView.test.tsx

@@ -0,0 +1,288 @@
+import { composeStories } from "@storybook/react"
+import { expect, userEvent, waitFor } from "storybook/test"
+import { test } from "vitest"
+
+import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import * as stories from "./MarkdownView.stories.tsx"
+
+const {
+  AllStates,
+  Default,
+  HostileMarkdown,
+  Interactive,
+  SameAsTheEditor,
+} = composeStories(stories)
+
+/**
+ * The gap this component was built to close, as a red/green fact.
+ *
+ * `isReadOnly` on either editor leaves nine disabled buttons in a
+ * `role="toolbar"` above the document — findable by a screen reader,
+ * findable by an agent, and useless to both. A CSS `display: none`
+ * in the consuming app was the workaround; an element that is not
+ * there is the fix.
+ */
+test("there is no toolbar, not a hidden one", async () => {
+  const { canvas } = await mountStory(Default)
+
+  await expect(canvas.queryAllByRole("toolbar")).toEqual([])
+
+  await expect(canvas.queryAllByRole("button")).toEqual([])
+
+  // The side the CSS workaround could never reach: the editor's
+  // toolbar collapses into an overflow **menu** at narrow widths, so
+  // "hide the toolbar" left a menu button behind.
+  await expect(canvas.queryAllByRole("menu")).toEqual([])
+})
+
+/**
+ * A reader, not a text field.
+ *
+ * The role is the difference between heading navigation and being
+ * dropped into forms mode with the whole document read as one flat
+ * string — and the headings are the reason it matters, so both are
+ * asserted together.
+ */
+test("it is an article whose headings are headings", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const article = expectAgentDrivable(canvas, {
+    name: "Description",
+    role: "article",
+  })
+
+  await expect(article).toHaveAttribute(
+    "contenteditable",
+    "false",
+  )
+
+  await expect(
+    canvas.getByRole("heading", {
+      name: "Rack move, phase two",
+    }),
+  ).toHaveAttribute("aria-level", "1")
+
+  await expect(
+    canvas.getByRole("heading", {
+      name: "Before the window",
+    }),
+  ).toHaveAttribute("aria-level", "2")
+
+  await expectNoAxeViolations(article)
+})
+
+/**
+ * The requirement that made this a component in the CodeMirror
+ * subpath rather than a `react-markdown` reader in the barrel.
+ *
+ * Both surfaces get one string. The assertion is not "they look
+ * similar" — it is that the constructs a second renderer would get
+ * subtly wrong come out identical: the same table, the same cells,
+ * the same task boxes, the same autolink.
+ */
+test("it renders what the editor renders", async () => {
+  const { canvas } = await mountStory(SameAsTheEditor)
+
+  const [viewTable, editorTable] =
+    canvas.getAllByRole("table")
+
+  await expect(viewTable).toBeDefined()
+
+  await expect(editorTable).toBeDefined()
+
+  const toCellText = (table: HTMLElement) =>
+    Array.from(table.querySelectorAll("th, td")).map(
+      (cell) => cell.textContent,
+    )
+
+  await expect(
+    toCellText(viewTable as HTMLElement),
+  ).toEqual(toCellText(editorTable as HTMLElement))
+
+  // Three task boxes in each, and the first one ticked in each.
+  const checkboxes: HTMLInputElement[] =
+    canvas.getAllByRole("checkbox")
+
+  await expect(checkboxes).toHaveLength(6)
+
+  await expect(
+    checkboxes.filter((checkbox) => checkbox.checked),
+  ).toHaveLength(2)
+
+  // The bare URL, autolinked on both sides with nothing typed
+  // around it.
+  await expect(
+    canvas.getAllByText(
+      "https://example.invalid/product?id=1234",
+    ).length,
+  ).toBe(2)
+})
+
+/**
+ * A link a reader can reach, which the editor's cannot be.
+ *
+ * The editor paints a `<span>` and translates a `mousedown` into a
+ * navigation, because an anchor inside a `contenteditable` fights
+ * the caret for the line. A document has no caret, so the link is an
+ * anchor: in the tab order, with an address the browser will show,
+ * copy and open.
+ */
+test("a link is a real anchor in the tab order", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const link = expectAgentDrivable(canvas, {
+    name: "the runbook",
+    role: "link",
+  })
+
+  await expect(link.tagName).toBe("A")
+
+  await expect(link).toHaveAttribute(
+    "href",
+    "https://example.invalid/runbook",
+  )
+
+  // `target="_blank"` without `noopener` hands the opened page a
+  // live handle back into this one.
+  await expect(link).toHaveAttribute(
+    "rel",
+    "noopener noreferrer",
+  )
+
+  // The document itself is not a tab stop — there is nothing in it
+  // to operate — but every link in it is. Tab from the button above
+  // lands on the first link rather than on the article.
+  canvas.getByRole("button", { name: "Before" }).focus()
+
+  await userEvent.tab()
+
+  await expect(document.activeElement?.tagName).toBe("A")
+})
+
+/**
+ * The answer to "is a checkbox interactive in a read-only view?",
+ * asserted from both sides.
+ *
+ * Not offered by default, because two of the three surfaces this was
+ * built for have nowhere to put a tick. Offered when the consumer
+ * says where it goes, which is the same shape `onUploadImage` uses
+ * on the editors.
+ */
+test("a checkbox is inert until a consumer says where the tick goes", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  const inert = canvas.getByRole("checkbox", {
+    name: "Photograph the current cabling",
+  })
+
+  await expect(inert).toBeDisabled()
+
+  const tickable = canvas.getByRole("checkbox", {
+    name: "Close the change record",
+  })
+
+  await expect(tickable).not.toBeDisabled()
+
+  await userEvent.click(tickable)
+
+  // The tick reaches the *markdown* and comes back as state, which
+  // is the round trip that matters: the box is a view over the
+  // document, and the document is what the consumer stores.
+  await waitFor(async () => {
+    await expect(
+      canvas.getByRole("checkbox", {
+        name: "Close the change record",
+      }),
+    ).toBeChecked()
+  })
+})
+
+/**
+ * The document this thing will actually be pointed at.
+ *
+ * Three separate claims, and each one used to be false or was one
+ * refactor away from it: a `javascript:` URL is not a link, a
+ * `<script>` is text, and a `data:text/html` is not an image.
+ */
+test("hostile markdown renders as characters, not as behaviour", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(HostileMarkdown)
+
+  const hrefs = canvas
+    .getAllByRole("link")
+    .map((link: HTMLElement) => link.getAttribute("href"))
+
+  await expect(hrefs).toEqual([
+    "https://example.invalid/runbook",
+  ])
+
+  await expect(
+    canvasElement.querySelector('[href^="javascript:"]'),
+  ).toBeNull()
+
+  // The whole `[text](javascript:…)` construct is left as source, so
+  // the reader can see what the file tried to do.
+  await expect(canvasElement.textContent).toContain(
+    "[Looks like a link](javascript:",
+  )
+
+  // A `<script>` in the source is characters. There is no
+  // `innerHTML` in this subpath for it to be anything else.
+  await expect(
+    canvasElement.querySelector("script"),
+  ).toBeNull()
+
+  await expect(canvasElement.textContent).toContain(
+    "<script>",
+  )
+
+  // `<img src=x onerror=…>` — the tag is text, so there is no
+  // element to fail to load.
+  await expect(
+    canvasElement.querySelector("img[onerror]"),
+  ).toBeNull()
+
+  // The only image markdown in the document names a
+  // `data:text/html` URL, which is not an image URL. `[src]` and not
+  // `img`, because CodeMirror parks its own source-less
+  // `.cm-widgetBuffer` spacer beside every widget.
+  await expect(
+    canvasElement.querySelector("img[src]"),
+  ).toBeNull()
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * Selectable, which is most of what a reader does with a document.
+ *
+ * A `contenteditable="false"` surface can very easily be an
+ * unselectable one — CodeMirror's own base theme is what makes it
+ * not, and a theme rule here could take it away without anything
+ * else noticing.
+ */
+test("the text can be selected", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const article = canvas.getByRole("article")
+
+  await expect(
+    getComputedStyle(article).userSelect,
+  ).not.toBe("none")
+
+  const range = document.createRange()
+
+  range.selectNodeContents(article)
+
+  const selection = window.getSelection()
+
+  selection?.removeAllRanges()
+
+  selection?.addRange(range)
+
+  await expect(selection?.toString()).toContain(
+    "Rack move, phase two",
+  )
+})