@charcuterie/ui 3.12.0 → 3.14.0

package/src/MarkdownEditor/MarkdownEditor.mdx

@@ -15,6 +15,11 @@ stored string.
 
 <Canvas of={MarkdownEditorStories.Default} />
 
+> **Reading rather than editing?** `isReadOnly` here leaves the toolbar on screen, because it
+> means "an editor you cannot type in". A surface with no toolbar in the DOM is
+> [`MarkdownView`](?path=/docs/components-data-markdownview--docs), in the
+> `@charcuterie/ui/markdown-editor-codemirror` subpath.
+
 ## Props
 
 <Controls />

package/src/index.ts

@@ -63,6 +63,11 @@ export type {
   AlertSize,
 } from "./Alert/Alert.tsx"
 export { Alert } from "./Alert/Alert.tsx"
+export type {
+  AvatarProps,
+  AvatarSize,
+} from "./Avatar/Avatar.tsx"
+export { Avatar } from "./Avatar/Avatar.tsx"
 export type { BadgeProps } from "./Badge/Badge.tsx"
 export { Badge } from "./Badge/Badge.tsx"
 export type { BadgeShapeProps } from "./Badge/useBadgeShape.tsx"

package/src/markdownEditorCodeMirror/MarkdownEditorCodeMirror.mdx

@@ -22,6 +22,17 @@ import { MarkdownEditorCodeMirror } from "@charcuterie/ui/markdown-editor-codemi
 
 <Controls />
 
+## Reading, not editing
+
+`isReadOnly` here means *an editor you cannot type in*: the toolbar stays, drawn in its
+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.
+
+For reading, take **[`MarkdownView`](?path=/docs/components-data-markdownview--docs)** from
+this same subpath. It has no toolbar in the DOM at all, it is controlled rather than
+uncontrolled, its content is a `role="article"` instead of a `role="textbox"`, and it renders
+**identically** to this component because it is the same code — same range rules, same theme.
+
 ## Which of the two editors you want
 
 `MarkdownEditor` is still the default, and most consumers should keep it.

package/src/markdownEditorCodeMirror/MarkdownView.mdx

@@ -0,0 +1,157 @@
+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.
+
+## 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,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>
+  ),
+}