@charcuterie/ui 3.13.0 → 3.14.1

package/src/markdownEditorCodeMirror/MarkdownView.mdx

@@ -0,0 +1,173 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as MarkdownViewStories from "./MarkdownView.stories";
+
+<Meta of={MarkdownViewStories} />
+
+# MarkdownView
+
+Rendered markdown, with **no toolbar in the DOM** and nothing to type into. The same
+document, drawn the same way, as the editor beside it.
+
+It is **opt-in**, from the same subpath as the editor:
+
+```tsx
+import { MarkdownView } from "@charcuterie/ui/markdown-editor-codemirror"
+```
+
+<Canvas of={MarkdownViewStories.Default} />
+
+## Props
+
+<Controls />
+
+## Which of the three you want
+
+| | `MarkdownEditor` | `MarkdownEditorCodeMirror` | `MarkdownView` |
+| --- | --- | --- | --- |
+| For | typing markdown | typing markdown, rendered | **reading** markdown |
+| Surface | `<textarea>` + painted layer | CodeMirror 6 | CodeMirror 6 |
+| New dependency | none | ~176 KB gz, optional peer | the same one |
+| Toolbar | nine buttons | nine buttons + a switch | **none, ever** |
+| Value | `defaultValue` | `defaultValue` | **`value`, controlled** |
+| Content role | `textbox` | `textbox` | **`article`** |
+
+`isReadOnly` on either editor is **not** this. It means *an editor you cannot type in*: the
+nine formatting buttons are still there, still in the accessibility tree, drawn in their
+disabled colours above a document nobody is editing. That is right for a form field that is
+temporarily locked, and wrong for reading a file — which is what this exists for.
+
+## No toolbar means no toolbar
+
+`queryAllByRole("toolbar")` returns nothing here, and so does `queryAllByRole("button")`.
+That is asserted rather than described, because the workaround it replaces was a CSS rule
+in a consuming app keyed on `role="toolbar"`, and CSS is a poor place to keep a promise:
+`visibility: hidden` leaves the buttons in the accessibility tree, `opacity: 0` leaves them
+in the tab order, and even `display: none` leaves the *overflow menu button* the toolbar
+collapses into at narrow widths.
+
+## It renders what the editor renders
+
+<Canvas of={MarkdownViewStories.SameAsTheEditor} />
+
+One string, two surfaces, side by side. They agree because they **are the same code** —
+`livePreviewRanges.ts` decides what every construct looks like and both call it, over the
+same GFM parse, under the same theme.
+
+That is the whole reason this lives in the CodeMirror subpath instead of being a
+`react-markdown` reader in the main barrel. A second renderer agrees on the day it is
+written and drifts afterwards, one construct at a time, and the bug arrives six months later
+as *"the table changed when I saved it"*. There is no second renderer here to drift.
+
+The cost is honest and worth stating: a consumer who wants **only** the reader still installs
+CodeMirror. For an app that renders markdown in three places and edits it in one, that is the
+right way round — the dependency is paid once.
+
+## It is controlled, and the editors are not
+
+`value` in, and that is it. Fetch a file at a different commit hash, pass the new string, and
+the page changes — no `key`, no remount, no stale document sitting above a new title.
+
+The editors take `defaultValue` because reassigning an `EditorView`'s document from outside
+throws away the undo history that belonged to it, which is a real cost and is why they ask
+for a `key` instead. A view has no undo history and no caret to protect, so it has nothing to
+lose by simply rendering what it is given.
+
+## A `- [ ]` box is inert unless you say where the tick goes
+
+<Canvas of={MarkdownViewStories.AllStates} />
+
+Pass `onToggleTask` and the checkboxes are operable; leave it out and they render
+**disabled**. The state is still on screen either way — that is a fact about the document
+and belongs there — but nothing pretends the reader can change it.
+
+This is the same shape as `onUploadImage` on the editors: omit the handler and the capability
+is simply not offered, which beats offering one that half works. Two of the three surfaces
+this component was built for — a rendered comment, and a repo file fetched at a commit hash —
+have nowhere to put a tick, and a box that visibly toggles and then loses the change on
+reload is worse than one that says up front it cannot.
+
+`onToggleTask` hands back the **whole next markdown document**, exactly like the editors'
+`onChange`, so one autosave wires to both. The view applies the tick to its own document
+immediately so the box responds under the pointer; if the consumer rejects the change, the
+next `value` puts it back.
+
+## Link text that carries its own markup
+
+<Canvas of={MarkdownViewStories.NestedLinkText} />
+
+A link whose text is a code span, a bolded phrase or an emphasised one is ordinary in a
+docs file, and until 2026-08-24 one of them took the whole surface down. The closing `]`
+was read as *the sibling after the opening bracket*, which is true only while the text is
+plain words — put an `InlineCode` in it and that sibling is the code span, so
+``[`a`](url)`` produced a link-text mark with `from === to`. CodeMirror refuses an empty
+mark decoration and throws out of the whole `ViewPlugin`, so **every** decoration in the
+document is lost and the reader gets raw markdown.
+
+The failure looks nothing like a link bug, which is why the story is here: one frame where
+every link is a link, and a heading above them that has nothing to do with links and
+stopped rendering anyway.
+
+## Hostile markdown
+
+This will render files fetched from a git host, so the document is untrusted by default.
+
+<Canvas of={MarkdownViewStories.HostileMarkdown} />
+
+**Raw HTML in the source is never parsed as HTML.** There is no `innerHTML` in this subpath,
+no `dangerouslySetInnerHTML`, and no sanitiser to have a bug in. CodeMirror's state holds the
+source as *text* and every rendered node is `createElement` plus `textContent`, so a
+`<script>` in a fetched README is drawn as the characters `<script>`. It is not stripped,
+not escaped and not "sanitised" — there is simply no code path that would turn it into an
+element.
+
+**A URL is checked before it is used as one.** That was the one place the document reached the
+platform, and it was live in the editor too: `[click](javascript:…)` concealed its markup,
+painted as a link, and `window.open` ran it in this origin. Both components now go through an
+allowlist that normalises the way a browser does, so `JaVaScript:` and a tab in the middle of
+the word are the same URL to it. A rejected link is **left as source** — brackets, parentheses
+and all — rather than repainted as a link-coloured word that silently refuses to work.
+Images take `http:`, `https:` and `data:image/*` only; `data:text/html` is not an image.
+
+**The reader is not a beacon.** Remote images carry `referrerpolicy="no-referrer"`, so an
+image in somebody else's file cannot learn which page loaded it.
+
+What is *not* claimed: nothing here stops a document linking somewhere unpleasant, and the
+images the markdown names are still fetched — that is what rendering them means.
+
+## Accessibility
+
+The content is `role="article"`, not the `role="textbox"` CodeMirror writes by default, and
+that swap is the difference between reading a document and being trapped in a text field: a
+screen reader entering a textbox switches to forms mode and reads the contents as one flat
+string, with no heading navigation and no table navigation.
+
+So the structure has to be real, and two pieces of it are:
+
+- **Headings carry `role="heading"` and an `aria-level`**, so the H key steps between
+  sections. The editor deliberately has none of this — ARIA flattens a textbox's contents, so
+  a heading role inside one would be a decoration that lies about what it does.
+- **Links are real `<a href>` elements**, in the tab order, activated by Enter, with an
+  address the browser will show and copy. The editor cannot have these: an anchor inside a
+  `contenteditable` competes with the caret for its line, which is why the editor paints a
+  span and translates a `mousedown` instead — and why clicking link text *there* cannot place
+  a caret.
+
+<Canvas of={MarkdownViewStories.Interactive} />
+
+**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.
+Every link inside it is reachable, in document order.
+
+List structure is **visual only**, and worth knowing rather than discovering: the `-` bullet
+is drawn as a dimmed marker rather than concealed, the same way it is in the editor, so a
+list reads as a list on screen but is not a `<ul>` in the tree. Tables are real `<table>`
+elements with real `<th>`s, because the table widget builds one.
+
+## The Narrow View
+
+<Canvas of={MarkdownViewStories.Responsive} />
+
+A table too wide for its column scrolls **inside its own block** rather than pushing the
+column sideways, and an image is capped at the width it is given. Nothing here is keyed to a
+viewport width; a column in a three-up board is narrow on a 4K display.

package/src/markdownEditorCodeMirror/MarkdownView.stories.tsx

@@ -0,0 +1,362 @@
+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
+`
+
+/**
+ * Link text with inline markup in it — the shape that used to take
+ * the **whole document** down to raw source.
+ *
+ * The closing bracket was read as the node right after `[`, which
+ * is the bracket only while the link text is plain prose. A code
+ * span or a `**bold**` run becomes that node instead, the link text
+ * measures zero characters, `Decoration.mark` refuses an empty
+ * range, and the throw destroys the view plugin — so every
+ * decoration in the file disappears at once, not just this link's.
+ *
+ * Invented, like every fixture here, but the shape is not invented:
+ * agent-written task descriptions are full of ``[`file.md`](path)``.
+ */
+const NESTED_LINK_TEXT = `## Where the fix landed
+
+The range walk lives in [\`livePreviewRanges.ts\`](https://example.invalid/ranges)
+and the decorations in [\`livePreview.ts\`](https://example.invalid/preview).
+
+- A code span: [\`AGENTS.md\`](https://example.invalid/agents)
+- Strong: [**the runbook**](https://example.invalid/runbook)
+- Emphasis: [*the older note*](https://example.invalid/note)
+- Struck through: [~~the retired page~~](https://example.invalid/retired)
+- Mixed: [read \`this\` **first**](https://example.invalid/first)
+
+Plain links still work: [the index](https://example.invalid/index).
+`
+
+/**
+ * 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>
+  ),
+}
+
+/**
+ * The regression frame.
+ *
+ * Every line here is a link whose text carries inline markup, and
+ * the assertion a reader can make from the picture is the one that
+ * matters: the document is **drawn**. Before the fix this frame was
+ * the markdown source, brackets and parentheses and all, because
+ * one empty mark decoration killed the plugin for the whole file.
+ *
+ * The last line is the control. A plain `[text](url)` never had the
+ * bug, so if it renders and the ones above it do not, the failure
+ * is this and not something else.
+ */
+export const NestedLinkText: Story = {
+  args: {
+    label: "Where the fix landed",
+    value: NESTED_LINK_TEXT,
+  },
+}