@charcuterie/ui 3.3.0 → 3.4.0

package/src/MarkdownEditor/markdownCommands.ts

@@ -394,6 +394,66 @@ export const insertLink = (
   })
 }
 
+/**
+ * Does this pasted string want to become a link?
+ *
+ * Deliberately strict. A paste that is *mostly* a URL — a sentence
+ * with one in it, two URLs on two lines — is left alone, because
+ * the cost of guessing wrong is silently mangling something the
+ * user meant to paste literally. One absolute `http(s)` URL, no
+ * inner whitespace, nothing either side of it.
+ *
+ * `mailto:` and bare `www.` are excluded on the same principle:
+ * they are the cases where "did they mean a link?" genuinely has
+ * two answers.
+ */
+export const isLinkPaste = (pasted: string): boolean =>
+  /^https?:\/\/[^\s<>]+$/.test(pasted.trim())
+
+/**
+ * Paste a URL over selected text and get `[selected](url)`.
+ *
+ * Every editor the owner uses does this — Outline, Notion, Slack,
+ * GitHub — and its absence is why a link pasted into Docket stayed
+ * flat text nobody could click. It is the one paste behaviour worth
+ * intercepting, and it is still markdown in and markdown out.
+ *
+ * Unlike `insertLink`, the caret lands **after** the whole
+ * insertion rather than inside the destination: the URL is already
+ * known, so parking the selection in it would ask the user to
+ * replace what they just pasted.
+ *
+ * With an empty selection this is a plain insertion of the URL —
+ * autolink renders a bare URL as a link anyway, so wrapping it in
+ * `[](…)` with no text would produce an empty link instead.
+ */
+export const wrapSelectionInLink = (
+  state: MarkdownSelection,
+  url: string,
+): MarkdownSelection => {
+  const selected = state.text.slice(
+    state.selectionStart,
+    state.selectionEnd,
+  )
+
+  if (selected === "") {
+    return insertText(state, url)
+  }
+
+  const insertion = `[${selected}](${url})`
+
+  const caret = state.selectionStart + insertion.length
+
+  return replaceRange({
+    end: state.selectionEnd,
+    insertion,
+    selectionEnd: caret,
+    selectionStart: caret,
+    start: state.selectionStart,
+    text: state.text,
+  })
+}
+
 /**
  * What Enter should do inside a list, a task list or a blockquote —
  * or `null` when it should do the ordinary thing and the component

package/src/MarkdownEditor/markdownSpans.test.ts

@@ -215,3 +215,68 @@ test("the caret's line is found from its offset", () => {
 
   expect(toLineIndex(text, 9999)).toBe(2)
 })
+
+/**
+ * Gap 2 of Docket's markdown handoff. A URL pasted into a
+ * description used to tokenize as prose — no `url` span, nothing to
+ * paint, and indistinguishable from the words around it.
+ */
+test("a bare URL paints as a URL without being marked up", () => {
+  expect(
+    toInlineSpans("see https://example.com now"),
+  ).toEqual([
+    { kind: "plain", text: "see " },
+    { kind: "url", text: "https://example.com" },
+    { kind: "plain", text: " now" },
+  ])
+})
+
+test("a sentence's full stop is not part of the URL", () => {
+  expect(
+    toInlineSpans("read https://example.com/a."),
+  ).toEqual([
+    { kind: "plain", text: "read " },
+    { kind: "url", text: "https://example.com/a" },
+    { kind: "plain", text: "." },
+  ])
+})
+
+test("a parenthesised URL does not swallow the paren", () => {
+  expect(
+    toInlineSpans("(see https://example.com)"),
+  ).toEqual([
+    { kind: "plain", text: "(see " },
+    { kind: "url", text: "https://example.com" },
+    { kind: "plain", text: ")" },
+  ])
+})
+
+/**
+ * The destination inside an explicit link is already a `url` span
+ * emitted by the link rule, and the link rule runs first. If
+ * autolink won here, the `](` and `)` would stop being markers.
+ */
+test("an explicit link still tokenizes as a link", () => {
+  expect(
+    toInlineSpans("[docs](https://example.com)"),
+  ).toEqual([
+    { kind: "marker", text: "[" },
+    { kind: "link", text: "docs" },
+    { kind: "marker", text: "](" },
+    { kind: "url", text: "https://example.com" },
+    { kind: "marker", text: ")" },
+  ])
+})
+
+/**
+ * Autolink runs before emphasis, which fixes a bug that predates
+ * it: the stretch between two underscores in a URL used to paint
+ * as italic text.
+ */
+test("underscores inside a URL are not emphasis", () => {
+  expect(
+    toInlineSpans("https://example.com/a_b_c"),
+  ).toEqual([
+    { kind: "url", text: "https://example.com/a_b_c" },
+  ])
+})

package/src/MarkdownEditor/markdownSpans.ts

@@ -121,8 +121,22 @@ const TASK_MARKER_PATTERN = /^\[[ xX]\][ \t]*/
  *  - **Image before link**, because `![alt](url)` starts with a
  *    valid link at index 1.
  *  - **Strong before emphasis**, because `**` starts with `*`.
+ *  - **Link before autolink**, because the `https://…` inside
+ *    `[text](https://…)` is a destination, not a bare URL, and
+ *    matching it as one would paint the parentheses as link text.
  */
 const INLINE_PATTERNS = {
+  /**
+   * A bare URL, as GFM autolinks it.
+   *
+   * Trailing punctuation is excluded from the match rather than
+   * trimmed after: `see https://example.com.` ends a sentence, and
+   * the full stop belongs to the prose. The closing paren is
+   * likewise left out so `(see https://example.com)` does not
+   * swallow it — at the cost of clipping a URL that genuinely ends
+   * in one, which is the rarer and less annoying failure.
+   */
+  autolink: /https?:\/\/[^\s<>[\]()]+[^\s<>[\]().,;:!?'"]/y,
   code: /(`+)([^\n]*?)\1/y,
   emphasis: /([*_])(?=[^\s*_])([^\n*_]*?[^\s*_])\1/y,
   escape: /\\([\\`*_{}[\]()#+\-.!>~|])/y,
@@ -243,6 +257,27 @@ export const toInlineSpans = (
       continue
     }
 
+    INLINE_PATTERNS.autolink.lastIndex = index
+
+    const autolinked = INLINE_PATTERNS.autolink.exec(text)
+
+    if (autolinked) {
+      // One span, no markers — there is no syntax to dim, because
+      // the user typed none. It paints as a URL so that a pasted
+      // link reads as a link, which is the whole complaint this
+      // answers: a URL dropped into a description used to be
+      // indistinguishable from prose.
+      //
+      // Running before `emphasis` also fixes a bug nobody filed:
+      // a URL with two underscores in it used to italicise the
+      // stretch between them.
+      pushSpan(spans, "url", autolinked[0])
+
+      index += autolinked[0].length
+
+      continue
+    }
+
     INLINE_PATTERNS.strong.lastIndex = index
 
     const strong = INLINE_PATTERNS.strong.exec(text)

package/src/markdownEditorCodeMirror/MarkdownEditorCodeMirror.mdx

@@ -0,0 +1,144 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as MarkdownEditorCodeMirrorStories from "./MarkdownEditorCodeMirror.stories";
+
+<Meta of={MarkdownEditorCodeMirrorStories} />
+
+# MarkdownEditorCodeMirror
+
+Obsidian-style live preview: markers conceal themselves once the caret leaves, headings are
+genuinely larger, images render in place, task boxes are real checkboxes — and the stored
+value is still markdown, byte for byte.
+
+It is **opt-in**, from a subpath:
+
+```tsx
+import { MarkdownEditorCodeMirror } from "@charcuterie/ui/markdown-editor-codemirror"
+```
+
+<Canvas of={MarkdownEditorCodeMirrorStories.Default} />
+
+## Props
+
+<Controls />
+
+## Which of the two editors you want
+
+`MarkdownEditor` is still the default, and most consumers should keep it.
+
+| | `MarkdownEditor` | `MarkdownEditorCodeMirror` |
+| --- | --- | --- |
+| Surface | `<textarea>` + painted layer | CodeMirror 6 |
+| New dependency | **none** | ~176 KB gz, optional peer |
+| Markers | dimmed, never hidden | **concealed** until the caret arrives |
+| Headings | weight and colour only | **actually larger** |
+| Images | shown as `![alt](url)` | **rendered in place** |
+| Tasks | shown as `- [ ]` | **checkbox you can click** |
+| Bare URLs | painted as a URL | **clickable link** |
+| Undo, IME, spellcheck | the platform's own | CodeMirror's |
+
+Take the subpath when the description field is a **primary** surface of the app and the
+bundle has room. Keep the default when it is one field on a form — a component library that
+makes every consumer install an editor core to render a description has made the wrong
+trade, and `castkit/packages/slatecast` has 60 KB gz of total budget to prove it.
+
+## Markdown is still the stored value
+
+This is the part worth being exact about, because "WYSIWYG" usually means the opposite.
+
+There is **no document model here and no serialiser**. CodeMirror's state holds the markdown
+*text*. Live preview is a set of decorations *over* that text: concealing `**` hides two
+characters that are still in the document, still in `onChange`, and still in whatever you
+save. Replacing `![alt](url)` with an image does not rewrite the line — move the caret into
+it and the markup is simply there again.
+
+That is why this is not TipTap or Lexical. An editor core inverts the relationship: its
+document model becomes authoritative and markdown becomes a lossy *export*, so any construct
+the serialiser does not know about is silently dropped or silently becomes HTML. Docket
+exists partly because HTML in a description field destroyed a previous tracker's data, and
+an editor core would have been the easier build and the one thing that could not be allowed.
+
+The [decision record][decision] has the measured bundle table and the full argument.
+
+[decision]: https://github.com/Sawtaytoes/charcuterie/blob/master/docs/decisions/2026-08-19-the-markdown-editor-is-a-textarea-with-a-painted-layer.md
+
+## Concealment is the caret's answer, not the parser's
+
+<Canvas of={MarkdownEditorCodeMirrorStories.CaretReveal} />
+
+A construct reveals its markers when the selection **touches** it, and hides them again when
+the selection leaves. Two consequences that are easy to mistake for bugs:
+
+- **An unfocused editor reveals nothing.** There is no caret in a document nobody is editing,
+  so the resting offset of `0` deliberately does not count as "inside" the first construct.
+  Without this, a description that opens with a heading rendered its `#` on load and no other
+  heading's.
+- **Reveal is per-construct, not per-line.** Two bold runs on one line reveal independently.
+
+## The "Markdown source" toggle
+
+<Canvas of={MarkdownEditorCodeMirrorStories.RawMode} />
+
+Nothing is concealed, nothing is replaced by a widget, no line is rescaled, and the surface
+switches to monospace — because a source view is code. The syntax stays **coloured**: the
+point of the toggle is to see the markup, not to lose the highlighting.
+
+It is a `Switch` rather than a toolbar button because it is state, not a verb, and a
+`ToolbarAction` renders a `Button` that announces nothing about being on.
+
+## What a mark does when it is hidden
+
+Not every marker conceals, and the rule is narrower than "block marks stay":
+
+> **A mark persists unless something else already says what it said.**
+
+A blockquote gets an accent bar down its inline start, so its `>` is redundant and hides. A
+fenced code block keeps its ` ``` ` and its language tag, because concealing them leaves a
+blank line at the top and bottom of the block that reads as a rendering bug. A list bullet
+stays, because hiding `-` turns an unordered list into indented prose — Obsidian substitutes
+a `•`, which means choosing a width, and this component has no business choosing one.
+
+## Clicking a link opens it
+
+Obsidian's behaviour, not VS Code's: where the markup is hidden, a link that looks like a
+link should act like one. Bare URLs count — GFM autolinks them, so a URL pasted into a
+description is clickable with nothing typed around it.
+
+The trade is real and worth stating: **you cannot click into link text to edit it.** Arrow in
+from either edge, or flip the Markdown source toggle, which is exactly what it is for.
+
+## Pasting
+
+- **An image** (or a drop) runs `onUploadImage` and inserts `![alt](url)` at the caret, then
+  renders it in place. The component does not own storage — it hands you a `File`.
+- **A URL over selected text** becomes `[selection](url)`, the way it does in every other
+  editor. Deliberately strict: one absolute `http(s)` URL and nothing else, because mangling
+  a literal paste is worse than not linkifying one.
+- **Anything else** is left to the browser.
+
+## Accessibility, and the honest cost
+
+The `<textarea>` sibling gets caret movement, IME composition, spellcheck, the platform undo
+stack and `role="textbox"` from the browser, tested by the vendors. A `contenteditable`
+re-earns every one of those, and CodeMirror is the reason that is acceptable rather than
+reckless — it is the most heavily exercised implementation of that re-earning there is. It is
+still a re-implementation, and that is what this subpath costs beyond its bytes.
+
+`Tab` is **never** captured, at any time. Indenting a list with Tab is the convention in
+editors that own the whole page, and inside a form it is a keyboard trap — WCAG 2.1.2 wants
+focus to leave every component with the standard gesture. Indent and outdent are `Ctrl+]` and
+`Ctrl+[`. `indentWithTab` is the extension that would change this, and it is deliberately not
+installed.
+
+<Canvas of={MarkdownEditorCodeMirrorStories.AllStates} />
+
+## It is uncontrolled
+
+`defaultValue` in, `onChange` out — the same contract as `Select` and as the sibling editor.
+An `EditorView` owns the caret, the selection, the scroll position and the undo history, and
+rebuilding it throws all four away, so the view is built exactly **once**. Props that can
+legitimately change afterwards reach it through a compartment (`isReadOnly`, `isDisabled`) or
+through a ref (the callbacks); the rest are frozen at mount.
+
+To swap documents — Docket opening a different task — remount with a `key`. That is one line,
+and it is honest about the old undo history belonging to the old document.

package/src/markdownEditorCodeMirror/MarkdownEditorCodeMirror.stories.tsx

@@ -0,0 +1,147 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import {
+  StoryCell,
+  StoryGrid,
+} from "../board.storyHelpers.tsx"
+import { Field } from "../Field/Field.tsx"
+import { MarkdownEditorCodeMirror } from "./MarkdownEditorCodeMirror.tsx"
+
+/**
+ * Invented, like every fixture in this repo — a task in a made-up
+ * homelab project, exercising each construct the live-preview layer
+ * knows about.
+ *
+ * The bare URL on the last line is the point of the whole exercise:
+ * nobody typed `[](…)` around it, and it is a link anyway.
+ */
+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
+`
+
+const meta = {
+  title: "Components/MarkdownEditorCodeMirror",
+  component: MarkdownEditorCodeMirror,
+  parameters: { layout: "padded" },
+  args: {
+    isDisabled: false,
+    isReadOnly: false,
+    label: "Description",
+    placeholder: "Write it in markdown…",
+  },
+} satisfies Meta<typeof MarkdownEditorCodeMirror>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * The whole argument for this subpath, in one frame: the heading is
+ * genuinely larger, `**` is nowhere on screen, the checkboxes are
+ * checkboxes, and the bare URL is a link.
+ */
+export const Default: Story = {
+  args: {
+    defaultValue: SAMPLE,
+    label: "Description",
+  },
+}
+
+/**
+ * The "edit Markdown" toggle, flipped.
+ *
+ * Nothing is concealed and no line is rescaled — but the syntax is
+ * still coloured, because the point of the toggle is to see the
+ * markup, not to lose the highlighting.
+ */
+export const RawMode: Story = {
+  args: {
+    defaultValue: SAMPLE,
+    isRawModeDefault: true,
+    label: "Description",
+  },
+}
+
+export const AllStates: Story = {
+  args: { label: "Description" },
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell align="stretch" label="empty">
+        <MarkdownEditorCodeMirror
+          label="Empty description"
+          placeholder="Write it in markdown…"
+        />
+      </StoryCell>
+
+      <StoryCell align="stretch" label="read only">
+        <MarkdownEditorCodeMirror
+          defaultValue={
+            "A **done** description.\n\n- [x] shipped"
+          }
+          isReadOnly
+          label="Read-only description"
+        />
+      </StoryCell>
+
+      <StoryCell align="stretch" label="disabled">
+        <MarkdownEditorCodeMirror
+          defaultValue={"You cannot edit _this_ one."}
+          isDisabled
+          label="Disabled description"
+        />
+      </StoryCell>
+
+      <StoryCell align="stretch" label="in a Field">
+        <Field
+          description="Markdown. Paste a screenshot straight in."
+          label="Description"
+        >
+          <MarkdownEditorCodeMirror defaultValue="Wired through `SlotProps`." />
+        </Field>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * Concealment is per-construct, and the caret is what reveals it.
+ *
+ * This story exists because the behaviour is invisible in a static
+ * frame: click into the bold run and the `**` comes back, in the
+ * flow, without the line reflowing around it.
+ */
+export const CaretReveal: Story = {
+  args: {
+    defaultValue:
+      "Click into the **bold run** and its markers come back.\n\nLeave, and they go again.",
+    label: "Description",
+  },
+}