@charcuterie/ui 3.17.0 → 3.19.1

package/src/Overlay/usePanelItemSize.ts

@@ -0,0 +1,71 @@
+import { useMediaQuery } from "@charcuterie/logic"
+import { matchMediaMatcher } from "@charcuterie/logic/browser"
+import type { ControlSize } from "@charcuterie/tokens"
+
+/**
+ * The requested row size, stepped down when the window is too short
+ * to spend the height.
+ *
+ * A fat option row is a bigger click target, which is the whole point
+ * of `itemSize` — but a nine-item menu at `lg` is 400px of panel, and
+ * on a half-height window that is the difference between a menu you
+ * read at a glance and a menu you scroll. So the size a panel asks
+ * for is a *ceiling*: below 40rem of viewport height it drops one
+ * step, and below 30rem it drops to the floor.
+ *
+ * ### Why a hook and not a media query in CSS
+ *
+ * Both were written. CSS is the library's usual answer — the density
+ * axis rewrites `--control-height-*` and nothing re-renders — but it
+ * cannot step *`text-sm` to `text-md`*: those are Tailwind bridges
+ * onto `--font-size-*` rather than variables a media query can
+ * reassign, and the alternative (`text-(length:--panel-item-font-size-lg)`
+ * everywhere, over nine new tokens) is the indirection
+ * `buildCss.ts` explicitly argues against. Stepping the whole
+ * `ControlSize` in JS keeps one literal class string per size, which
+ * is also what `tailwindCandidates.test.ts` can see.
+ *
+ * The re-render this costs happens on a window resize, not on a
+ * scheme or density flip — those stay repaints.
+ *
+ * ### `height`, not `width`
+ *
+ * Rows stack down the panel, so height is the axis that runs out.
+ * The Narrow View is a separate question and this is not it: a 390px
+ * phone held upright has plenty of height, and its menu stays fat.
+ */
+const SHORT_VIEWPORT_QUERY = "(height <= 40rem)"
+
+const VERY_SHORT_VIEWPORT_QUERY = "(height <= 30rem)"
+
+const STEP_DOWN: Record<ControlSize, ControlSize> = {
+  sm: "sm",
+  md: "sm",
+  lg: "md",
+}
+
+export const usePanelItemSize = (
+  itemSize: ControlSize,
+): ControlSize => {
+  // Both hooks run unconditionally and the *narrower* one wins, so
+  // the two queries never disagree about which step applies.
+  const { isMatching: isShortViewport } = useMediaQuery({
+    matcher: matchMediaMatcher(SHORT_VIEWPORT_QUERY),
+  })
+
+  const { isMatching: isVeryShortViewport } = useMediaQuery(
+    {
+      matcher: matchMediaMatcher(VERY_SHORT_VIEWPORT_QUERY),
+    },
+  )
+
+  if (isVeryShortViewport) {
+    return "sm"
+  }
+
+  if (isShortViewport) {
+    return STEP_DOWN[itemSize]
+  }
+
+  return itemSize
+}

package/src/controlStyles.ts

@@ -38,6 +38,44 @@ export const CONTROL_SIZE_CLASS: Record<
   lg: "h-(--control-height-lg) gap-(--control-gap-lg) px-(--control-padding-inline-lg) text-lg",
 }
 
+/**
+ * A row inside an overlay panel — a `Menu` item, a `Listbox` option,
+ * a `Combobox` option. The same three sizes as a control, read from
+ * the same density-aware tokens, so a `md` option row and a `md`
+ * `Button` are the same height.
+ *
+ * ### Why this is not `CONTROL_SIZE_CLASS`
+ *
+ * Two differences, and both are load-bearing.
+ *
+ * `min-h-`, not `h-`. A control on a form row holds one line by
+ * contract; an option may be rich — an icon, two lines, a trailing
+ * badge — and a fixed height clips it. The token is a **floor** here,
+ * which is what makes the row at least as big as the button that
+ * opened it while still growing for a label that wraps.
+ *
+ * `py-*`, which a control has none of. It is what a wrapped second
+ * line breathes on once `min-h-` stops being the binding constraint.
+ *
+ * ### The sizes are click targets, not decoration
+ *
+ * The owner's request is the whole reason this exists: *"I personally
+ * like larger click areas because it makes it easier to not mess up a
+ * click. I can be much faster the less precise I need to be when
+ * clicking."* At `comfortable` density `lg` is 2.75rem — 44px, the
+ * WCAG 2.5.5 target — and on the kiosk density it is 3.75rem with no
+ * prop change. See
+ * `docs/decisions/2026-08-25-a-panel-row-is-sized-by-itemsize-and-menus-default-to-lg.md`.
+ */
+export const PANEL_ITEM_SIZE_CLASS: Record<
+  ControlSize,
+  string
+> = {
+  sm: "min-h-(--control-height-sm) gap-(--control-gap-sm) px-(--control-padding-inline-sm) py-1 text-sm",
+  md: "min-h-(--control-height-md) gap-(--control-gap-md) px-(--control-padding-inline-md) py-1.5 text-md",
+  lg: "min-h-(--control-height-lg) gap-(--control-gap-lg) px-(--control-padding-inline-lg) py-2 text-lg",
+}
+
 /**
  * Square, and sized by the *height* token on both axes so an icon
  * button lines up with the text button beside it in a toolbar. No

package/src/markdownEditorCodeMirror/MarkdownEditorCodeMirror.test.tsx

@@ -0,0 +1,185 @@
+import { composeStories } from "@storybook/react"
+import { expect, userEvent, waitFor } from "storybook/test"
+import { test } from "vitest"
+
+import { mountStory } from "../mountStory.testHelpers.ts"
+import * as stories from "./MarkdownEditorCodeMirror.stories.tsx"
+
+const { AllStates, CaretReveal, Default } =
+  composeStories(stories)
+
+/**
+ * The two ways this surface stopped behaving like the `<textarea>`
+ * it replaced. Both are invisible to every other gate: the stories
+ * render, the toolbar works, axe is clean, and the field is still
+ * one you cannot see the caret in and cannot click into.
+ */
+
+/**
+ * Every `caret-color` this element is actually told, in cascade
+ * order, ignoring the suite's own override.
+ *
+ * A computed style cannot answer this question **here**:
+ * `FREEZE_MOTION_CSS` forces `caret-color: transparent !important`
+ * on `*` for the whole `ui-dom` suite, deliberately, because a
+ * blinking caret is a pixel diff that means nothing. So the test
+ * reads the declarations instead — which is the honest subject
+ * anyway, since what regressed is *whose rule wins*.
+ */
+const caretDeclarationsFor = (element: Element) => {
+  const declarations: string[] = []
+
+  for (const sheet of Array.from(document.styleSheets)) {
+    let rules: CSSRuleList | null = null
+
+    try {
+      rules = sheet.cssRules
+    } catch {
+      // A cross-origin sheet throws on access and has nothing to
+      // say about a CodeMirror caret.
+      continue
+    }
+
+    for (const rule of Array.from(rules ?? [])) {
+      if (!(rule instanceof CSSStyleRule)) {
+        continue
+      }
+
+      const value =
+        rule.style.getPropertyValue("caret-color")
+
+      if (
+        value === "" ||
+        // The suite's own freeze, which is not part of the
+        // component's cascade.
+        rule.selectorText.includes("*")
+      ) {
+        continue
+      }
+
+      if (element.matches(rule.selectorText)) {
+        declarations.push(value)
+      }
+    }
+  }
+
+  return declarations
+}
+
+/**
+ * CodeMirror hard-codes the caret **black** for any editor whose
+ * theme did not declare itself dark — and Charcuterie's is one
+ * theme for both schemes, because every colour in it is a token. So
+ * the editor is always `cm-light`, and in dark mode the caret was
+ * black on `surface-base`:
+ *
+ *   *"this comments area has a black blinking cursor in dark mode
+ *   that I can't see."*
+ *
+ * It is `caret-color` and not `.cm-cursor` because `drawSelection`
+ * is **not** installed on this surface: the caret is the browser's
+ * own, so the property the browser reads is the only lever. Last
+ * declaration wins at equal specificity — two classes each — and
+ * the base theme is `Prec.lowest`, which is what puts it first in
+ * the sheet.
+ */
+test("the caret is a token, not CodeMirror's black", async () => {
+  const { canvas } = await mountStory(CaretReveal)
+
+  const content = canvas.getByRole("textbox", {
+    name: "Description",
+  })
+
+  const declarations = caretDeclarationsFor(content)
+
+  await expect(declarations.at(-1)).toBe(
+    "var(--color-content-primary)",
+  )
+})
+
+/**
+ * The whole box takes a click, because the whole box IS the text
+ * field:
+ *
+ *   *"the markdown box isn't a textarea, it's an input field or
+ *   something. It should be the whole box that's clickable to type
+ *   into."*
+ *
+ * `.cm-content` is the `contenteditable`, and it used to be as tall
+ * as its text — one line, in an empty field inside an 8rem frame.
+ * Everything below it belonged to the wrapper `<div>`, so the
+ * bottom three quarters of a text field focused nothing.
+ *
+ * The number is the frame's own minimum (`min-h-32`), so this fails
+ * on any change that puts the minimum back on a box the caret does
+ * not live in.
+ */
+test("an empty field's text area fills the frame", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  const content = canvas.getByRole("textbox", {
+    name: "Empty description",
+  })
+
+  await waitFor(() => {
+    expect(
+      content.getBoundingClientRect().height,
+    ).toBeGreaterThanOrEqual(128)
+  })
+})
+
+/** And the point three quarters of the way down an empty field
+ * belongs to the document rather than to the frame around it. */
+test("a click low in an empty field lands in the document", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  const content = canvas.getByRole("textbox", {
+    name: "Empty description",
+  })
+
+  const box = content.getBoundingClientRect()
+
+  const hit = document.elementFromPoint(
+    box.left + box.width / 2,
+    box.bottom - 8,
+  )
+
+  await expect(content.contains(hit)).toBe(true)
+
+  await userEvent.click(content)
+
+  await expect(
+    content === document.activeElement ||
+      content.contains(document.activeElement),
+  ).toBe(true)
+})
+
+/**
+ * The other end of the same change: filling the frame must not
+ * turn the frame into a scroll box.
+ *
+ * A description is read in place, and an editor that keeps its own
+ * 8rem window over a 40-line document is the shape this surface
+ * exists to avoid. The frame grows instead — which is what
+ * `min-height: auto` on a flex item preserves, and what a `height`
+ * anywhere in this stack would have quietly taken away.
+ */
+test("a document taller than the frame grows it", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const content = canvas.getByRole("textbox", {
+    name: "Description",
+  })
+
+  const scroller = content.parentElement as HTMLElement
+
+  await waitFor(() => {
+    expect(
+      content.getBoundingClientRect().height,
+    ).toBeGreaterThan(128)
+  })
+
+  await expect(scroller.scrollHeight).toBe(
+    scroller.clientHeight,
+  )
+})

package/src/markdownEditorCodeMirror/MarkdownEditorCodeMirror.tsx

@@ -834,8 +834,49 @@ export const MarkdownEditorCodeMirror = ({
         />
       </div>
 
+      {/*
+        The frame's height reaches the `contenteditable`, so the
+        whole box takes a click.
+
+        A `<textarea>` is one box: it is as tall as you make it and
+        every pixel of it accepts the caret. CodeMirror is a stack
+        — `.cm-editor` in this host, `.cm-scroller` in that, and
+        the `contenteditable` `.cm-content` in that — and each of
+        those was only as tall as the text. A frame with a
+        `min-height` and a two-line document therefore had a large
+        band that belonged to *this div*, and pressing it focused
+        nothing:
+
+          *"the markdown box isn't a textarea, it's an input field
+          or something. It should be the whole box that's clickable
+          to type into."*
+
+        So the height is handed down the stack, one utility per
+        step, and each one is there because the step above it does
+        not arrive on its own:
+
+         1. `flex flex-col` + `[&>.cm-editor]:flex-1` — a
+            `min-height` is not a definite height, so nothing
+            inside the editor could be a percentage *of* it.
+         2. `[&_.cm-scroller]:flex-1` — CodeMirror's base theme
+            gives the scroller `height: 100%`, and that percentage
+            does not resolve against a parent whose own height came
+            out of flexing. Stretching it by flex does.
+         3. `[&_.cm-content]:self-stretch` — the scroller is a flex
+            ROW pinned to `align-items: flex-start !important`, so
+            the content sits at its natural height. `align-self` is
+            the item's own property and is not what that
+            `!important` is on, which is why this is the one line
+            that reaches the box the caret actually lives in.
+
+        Everything here grows, and nothing clips: a document taller
+        than the frame still makes the frame taller rather than
+        scrolling inside it, which is what `min-height: auto` on a
+        flex item preserves. Measured both ways in
+        `MarkdownEditorCodeMirror.test.tsx`.
+      */}
       <div
-        className="min-h-32 px-1 text-md cq-md:min-h-48"
+        className="flex min-h-32 flex-col px-1 text-md cq-md:min-h-48 [&>.cm-editor]:flex-1 [&_.cm-scroller]:flex-1 [&_.cm-content]:self-stretch"
         ref={hostRef}
       />
 

package/src/markdownEditorCodeMirror/MarkdownView.tsx

@@ -50,6 +50,29 @@ export type MarkdownViewProps = SlotProps & {
    * back.
    */
   onToggleTask?: (nextValue: string) => void
+  /**
+   * Re-point a link before it becomes an `href`, for a document
+   * whose paths mean something only the app knows.
+   *
+   * The case it exists for is a **relative** path in a fetched or
+   * imported file. `[the runbook](../docs/runbook.md)` is resolved
+   * by the browser against the page the reader is on — the app —
+   * so it lands on nothing. Return the URL it should point at
+   * instead, or `undefined` to leave the link exactly as written.
+   *
+   * The document's own URL has already been through the scheme
+   * guard when it arrives, so `javascript:` never reaches this.
+   * What comes back is the app's own string and is used as given.
+   *
+   * **Links only.** An image's `src` is deliberately not offered:
+   * an app that maps a document path to a page URL would turn a
+   * working image into a broken one.
+   *
+   * Read once, at mount, through a ref — so a resolver defined
+   * inline in a render does not rebuild the view and lose the
+   * reader's scroll position.
+   */
+  resolveUrl?: (url: string) => string | undefined
   /**
    * The markdown to render, and **controlled** — unlike either
    * editor.
@@ -170,6 +193,7 @@ export const MarkdownView = ({
   className,
   label,
   onToggleTask,
+  resolveUrl,
   value,
   ...receivedSlotProps
 }: MarkdownViewProps): ReactNode => {
@@ -193,6 +217,16 @@ export const MarkdownView = ({
 
   handlerRef.current = onToggleTask
 
+  /**
+   * Same treatment, and for the same reason: a resolver written
+   * inline in the consumer's render is a new function every time,
+   * and rebuilding the view on it would throw away the scroll
+   * position of whatever the reader was reading.
+   */
+  const resolveUrlRef = useRef(resolveUrl)
+
+  resolveUrlRef.current = resolveUrl
+
   /**
    * Frozen at mount, and named so rather than read from the render
    * closure, because the build-once effect below is honestly
@@ -224,7 +258,12 @@ export const MarkdownView = ({
           // component exists to avoid.
           markdown({ base: markdownLanguage }),
           EditorView.lineWrapping,
-          livePreview({ hasDocumentSemantics: true }),
+          livePreview({
+            hasDocumentSemantics: true,
+            // Stable by construction — the ref is what changes.
+            resolveUrl: (url) =>
+              resolveUrlRef.current?.(url),
+          }),
           /**
            * The one answer that can change after mount, and only
            * that answer.

package/src/markdownEditorCodeMirror/livePreview.ts

@@ -104,6 +104,13 @@ export type LivePreviewOptions = {
   hasDocumentSemantics?: boolean
   /** Whether a `- [ ]` checkbox can be ticked. Defaults to `true`. */
   isTaskListInteractive?: boolean
+  /**
+   * Re-point a link before it becomes an `href` — see
+   * `ToLivePreviewRangesOptions.resolveUrl`, which this is handed
+   * to. Links only, and the document's URL has already been through
+   * the scheme guard when it arrives.
+   */
+  resolveUrl?: (url: string) => string | undefined
 }
 
 /**
@@ -130,10 +137,12 @@ export const livePreviewOptions = Facet.define<
         isTaskListInteractive:
           value.isTaskListInteractive ??
           merged.isTaskListInteractive,
+        resolveUrl: value.resolveUrl ?? merged.resolveUrl,
       }),
       {
         hasDocumentSemantics: false,
         isTaskListInteractive: true,
+        resolveUrl: () => undefined,
       },
     ),
 })
@@ -672,8 +681,11 @@ const toDecorations = (view: EditorView): DecorationSet => {
     false,
   )
 
-  const { hasDocumentSemantics, isTaskListInteractive } =
-    toOptions(view.state)
+  const {
+    hasDocumentSemantics,
+    isTaskListInteractive,
+    resolveUrl,
+  } = toOptions(view.state)
 
   const text = view.state.doc.toString()
 
@@ -709,6 +721,7 @@ const toDecorations = (view: EditorView): DecorationSet => {
     for (const range of toLivePreviewRanges({
       from: visible.from,
       isRawMode: isRawMode ?? false,
+      resolveUrl,
       selections,
       text,
       to: visible.to,
@@ -838,7 +851,8 @@ const toTableDecorations = (state: EditorState) => {
     false,
   )
 
-  const { hasDocumentSemantics } = toOptions(state)
+  const { hasDocumentSemantics, resolveUrl } =
+    toOptions(state)
 
   const selections =
     state.field(isEditorFocusedField, false) &&
@@ -854,6 +868,7 @@ const toTableDecorations = (state: EditorState) => {
   return Decoration.set(
     toLivePreviewTableRanges({
       isRawMode: isRawMode ?? false,
+      resolveUrl,
       selections,
       text,
       tree: syntaxTree(state),
@@ -1138,6 +1153,28 @@ const livePreviewTheme = EditorView.theme({
    * it.
    */
   ".cm-content": {
+    /**
+     * The caret, which CodeMirror hard-codes **black**.
+     *
+     * `drawSelection` is not installed, so the caret is the
+     * browser's own and `caret-color` decides what it looks like.
+     * The base theme sets that per light/dark class — `&light .cm-
+     * content { caret-color: black }` — and those classes track
+     * whether a *CodeMirror theme* declared `dark: true`, not what
+     * scheme the page is painted in. Charcuterie has one theme for
+     * both schemes because every colour in it is a token, so the
+     * editor is always `cm-light` and the caret was always black:
+     * invisible on `surface-base` in dark mode, which is a text
+     * field you cannot find the insertion point in.
+     *
+     * The token is the same one the text uses, so it follows the
+     * scheme by construction and cannot be black on black again.
+     * Same specificity as the base rule it replaces (two classes),
+     * and later in the sheet — a theme's rules are inserted after
+     * the base theme's, which is what CodeMirror's `Prec.lowest`
+     * on the base module guarantees.
+     */
+    caretColor: "var(--color-content-primary)",
     lineHeight: "1.6",
   },
   /**

package/src/markdownEditorCodeMirror/livePreviewRanges.test.ts

@@ -1003,3 +1003,140 @@ describe("toLivePreviewRanges", () => {
     })
   })
 })
+
+describe("resolveUrl", () => {
+  const toResolved = (
+    text: string,
+    resolveUrl: (url: string) => string | undefined,
+  ) =>
+    toLivePreviewRanges({
+      isRawMode: false,
+      resolveUrl,
+      selections: [],
+      text,
+      tree: markdownLanguage.parser.parse(text),
+    })
+
+  /**
+   * The case the option exists for: a relative path in a document
+   * the app fetched from somewhere else. The browser resolves it
+   * against the page the reader is ON, which is the app, so it
+   * lands on nothing. Only the app knows what the path means.
+   */
+  test("re-points a link the consumer claims", () => {
+    const text = "see [the runbook](../docs/runbook.md)"
+
+    const linkText = toRanges(text).find(
+      (range) =>
+        range.type === "mark" &&
+        range.markKind === "linkText",
+    )
+
+    expect(linkText).toMatchObject({
+      url: "../docs/runbook.md",
+    })
+
+    const resolved = toResolved(text, (url) =>
+      url.startsWith("../")
+        ? `/files?path=${url.slice(3)}`
+        : undefined,
+    ).find(
+      (range) =>
+        range.type === "mark" &&
+        range.markKind === "linkText",
+    )
+
+    expect(resolved).toMatchObject({
+      url: "/files?path=docs/runbook.md",
+    })
+  })
+
+  test("leaves a link alone when the consumer returns undefined", () => {
+    const text = "see [the docs](https://example.invalid/a)"
+
+    expect(
+      toResolved(text, () => undefined).find(
+        (range) =>
+          range.type === "mark" &&
+          range.markKind === "linkText",
+      ),
+    ).toMatchObject({ url: "https://example.invalid/a" })
+  })
+
+  test("re-points a bare URL too", () => {
+    const text = "see https://example.invalid/a for more"
+
+    expect(
+      toResolved(text, () => "/elsewhere").find(
+        (range) =>
+          range.type === "mark" &&
+          range.markKind === "autolink",
+      ),
+    ).toMatchObject({ url: "/elsewhere" })
+  })
+
+  /**
+   * The guard runs FIRST, so a refused URL never reaches the
+   * consumer — it is not a link at all by then, and offering an app
+   * the chance to resurrect one would undo `safeUrls.ts`.
+   */
+  test("never offers a URL the scheme guard refused", () => {
+    const seen: string[] = []
+
+    const text = "[click me](javascript:alert(1))"
+
+    toResolved(text, (url) => {
+      seen.push(url)
+
+      return undefined
+    })
+
+    expect(seen).toEqual([])
+  })
+
+  /**
+   * An image is deliberately not offered. An app that maps a
+   * document path to a PAGE url would turn a working image into a
+   * broken one, and the image's `src` is the one URL here that has
+   * to stay fetchable.
+   */
+  test("does not offer an image's src", () => {
+    const seen: string[] = []
+
+    const text = "![a diagram](../docs/a.png)"
+
+    const image = toResolved(text, (url) => {
+      seen.push(url)
+
+      return "/elsewhere.png"
+    }).find((range) => range.type === "image")
+
+    expect(seen).toEqual([])
+
+    expect(image).toMatchObject({
+      url: "../docs/a.png",
+    })
+  })
+
+  test("re-points a link inside a table cell", () => {
+    const text = [
+      "| Port | Notes |",
+      "| --- | --- |",
+      "| 1 | see [the runbook](../docs/runbook.md) |",
+    ].join("\n")
+
+    const cell = toLivePreviewTableRanges({
+      isRawMode: false,
+      resolveUrl: () => "/files?path=docs/runbook.md",
+      selections: [],
+      text,
+      tree: markdownLanguage.parser.parse(text),
+    })[0]?.rows[1]?.cells[1]
+
+    expect(toFound(cell).segments).toContainEqual(
+      expect.objectContaining({
+        url: "/files?path=docs/runbook.md",
+      }),
+    )
+  })
+})