@charcuterie/ui 3.16.0 → 3.18.0

package/src/Combobox/Combobox.tsx

@@ -286,32 +286,40 @@ export const Combobox = ({
 
   const hasSeededOnOpen = useRef(false)
 
-  // The seed sets the index and the in-view effect further down scrolls
-  // to it, one commit later — the virtualizer measures its scroll
-  // element in an effect of its own, so a `scrollToIndex` issued any
-  // earlier has nothing to scroll and is dropped. That effect must not
-  // scroll the *stale* highlight in the meantime, which would undo the
-  // centring, so it is told which index to wait for and skips every pass
-  // short of it.
-  const pendingSeedIndex = useRef<null | number>(null)
-
-  // Retrying the seed's centring scroll. `useAnchoredOverlay` caps the
-  // panel's height by writing `style.maxHeight` straight onto the
-  // floating element inside floating-ui's `size` middleware —
-  // deliberately outside the `floatingStyles` React manages, so a
-  // keystroke cannot wipe it. The cost lands here: it arrives a frame
-  // after the open seed, announces itself with no re-render, and until
-  // it does the list stands at its full content height with **nothing to
-  // scroll**. A seed scroll issued then is dropped without a trace,
-  // which is how the first build of this fix highlighted the chosen row
-  // and still left it off screen in a real app.
-  const [seedScrollAttempt, setSeedScrollAttempt] =
-    useState(0)
+  /**
+   * The open seed's outstanding scroll — the row to centre, and how many
+   * frames it has waited for a panel it can move.
+   *
+   * **State, and a fresh object on every open.** The obvious build hangs
+   * the scroll off `activeIndex` changing, and that is a bug the second
+   * time the same picker opens: `activeIndex` still holds the index the
+   * *last* open seeded, so setting it again is a no-op, React re-renders
+   * nothing, and the effect that would have scrolled never runs. The
+   * first open worked and every reopen showed the top of the list.
+   *
+   * A new object per open cannot be a no-op, so the scroll no longer
+   * depends on the highlight having moved.
+   *
+   * The wait exists because `useAnchoredOverlay` caps the panel's height
+   * by writing `style.maxHeight` straight onto the floating element
+   * inside floating-ui's `size` middleware — deliberately outside the
+   * `floatingStyles` React manages, so a keystroke cannot wipe it. It
+   * lands a frame after the seed and re-renders nothing to announce
+   * itself, and until it does the list stands at its full content height
+   * with **nothing to scroll**, so a scroll issued then is dropped
+   * without a trace.
+   */
+  const [seedScroll, setSeedScroll] = useState<null | {
+    attempt: number
+    index: number
+    value: string
+  }>(null)
 
   useEffect(() => {
     if (!isVisible) {
       hasSeededOnOpen.current = false
-      pendingSeedIndex.current = null
+
+      setSeedScroll(null)
 
       return
     }
@@ -337,9 +345,15 @@ export const Combobox = ({
 
     hasSeededOnOpen.current = true
 
-    pendingSeedIndex.current = openSeedIndex
-
-    setSeedScrollAttempt(0)
+    setSeedScroll({
+      attempt: 0,
+      index: openSeedIndex,
+      // Carried rather than looked up in the effect. `filtered` is a new
+      // array on every render, and as a dependency it would cancel and
+      // reschedule the pending frame each time — a wait that can never
+      // end while anything else re-renders.
+      value: seedValue,
+    })
 
     setActiveIndex(openSeedIndex)
   }, [
@@ -540,38 +554,41 @@ export const Combobox = ({
     }
   }
 
-  // Keep the active row in view — a real bug in every fleet picker:
-  // arrowing past the panel edge did not scroll.
+  // The open seed's own scroll, centred, and the only one allowed to run
+  // until it lands — an arrow move's `block: "nearest"` would drag the
+  // list straight back off the chosen row.
   useEffect(() => {
-    if (!isVisible) {
+    if (!isVisible || seedScroll === null) {
       return
     }
 
-    const isSeeding = pendingSeedIndex.current !== null
+    const list = listElement.current
 
-    if (
-      isSeeding &&
-      pendingSeedIndex.current !== resolvedActiveIndex
-    ) {
-      // The seeded index has not reached this render yet. Scrolling the
-      // stale highlight now would drag the list off the chosen row.
+    if (list === null) {
       return
     }
 
-    const list = listElement.current
-
     if (
-      isSeeding &&
-      seedScrollAttempt < SEED_SCROLL_ATTEMPTS &&
-      list !== null &&
-      list.scrollHeight <= list.clientHeight
+      seedScroll.attempt < SEED_SCROLL_ATTEMPTS &&
+      (seedScroll.attempt === 0 ||
+        list.scrollHeight <= list.clientHeight)
     ) {
-      // Nothing to scroll yet — the panel is still at its full height.
-      // Hold the seed and look again next frame rather than scroll a
-      // container that cannot move. Bounded, so a list that genuinely
-      // fits its panel stops instead of spinning.
+      // Never scroll on the opening commit. Two separate things are
+      // still missing then, and each drops the scroll silently: the
+      // panel has no height cap yet, so the list stands at full height
+      // with nothing to move; and the virtualizer measures its scroll
+      // element in an effect of its own, so `scrollToIndex` has nothing
+      // to measure against. One frame settles both.
+      //
+      // After that, keep waiting only while the list cannot move.
+      // Bounded, so a list that genuinely fits its panel stops instead
+      // of spinning.
       const frame = requestAnimationFrame(() => {
-        setSeedScrollAttempt((attempt) => attempt + 1)
+        setSeedScroll({
+          attempt: seedScroll.attempt + 1,
+          index: seedScroll.index,
+          value: seedScroll.value,
+        })
       })
 
       return () => {
@@ -579,17 +596,43 @@ export const Combobox = ({
       }
     }
 
-    pendingSeedIndex.current = null
+    // Centred, where an arrow move only pulls the next row just into
+    // view. "nearest" on open would park the chosen row against the
+    // panel's bottom edge with nothing after it, so the neighbours the
+    // list was reopened to reach would still be off screen.
+    if (isWindowed) {
+      rowVirtualizer.scrollToIndex(seedScroll.index, {
+        align: "center",
+      })
+    } else {
+      list
+        .querySelector(
+          `#${CSS.escape(`${listboxId}-opt-${seedScroll.value}`)}`,
+        )
+        ?.scrollIntoView({ block: "center" })
+    }
+
+    setSeedScroll(null)
+  }, [
+    seedScroll,
+    isVisible,
+    isWindowed,
+    listboxId,
+    rowVirtualizer.scrollToIndex,
+  ])
+
+  // Keep the active row in view — a real bug in every fleet picker:
+  // arrowing past the panel edge did not scroll.
+  useEffect(() => {
+    // While the seed is outstanding the row it wants is not on screen
+    // yet, and pulling the highlight into view with `nearest` would
+    // settle the list somewhere the seed then has to undo.
+    if (!isVisible || seedScroll !== null) {
+      return
+    }
 
-    // The open seed centres its row; an arrow move only pulls the next
-    // one just into view. "nearest" on open would park the chosen row
-    // against the panel's bottom edge with nothing after it, so the
-    // neighbours the list was reopened to reach stay off screen.
     if (isWindowed) {
-      rowVirtualizer.scrollToIndex(
-        resolvedActiveIndex,
-        isSeeding ? { align: "center" } : undefined,
-      )
+      rowVirtualizer.scrollToIndex(resolvedActiveIndex)
 
       return
     }
@@ -599,9 +642,7 @@ export const Combobox = ({
         ?.querySelector(
           `#${CSS.escape(`${listboxId}-opt-${activeValue}`)}`,
         )
-        ?.scrollIntoView({
-          block: isSeeding ? "center" : "nearest",
-        })
+        ?.scrollIntoView({ block: "nearest" })
     }
   }, [
     resolvedActiveIndex,
@@ -610,7 +651,7 @@ export const Combobox = ({
     isWindowed,
     listboxId,
     rowVirtualizer.scrollToIndex,
-    seedScrollAttempt,
+    seedScroll,
   ])
 
   // ─── Attached mode: drive the consumer's input ──────────────────────

package/src/MarkdownEditor/MarkdownEditor.mdx

@@ -156,6 +156,18 @@ has to keep taking clicks as caret placement. So the editor handles its own drop
 
 <Canvas of={MarkdownEditorStories.Responsive} />
 
+## The toolbar is words until you bring icons
+
+The bar defaults to word buttons because this package ships **no icons**, and words render
+in every font on every target. Pass an `icons` bag and the row fits as glyphs, keeping the
+words as the accessible names and as the labels of whatever still collapses into the menu.
+
+`icons.overflow` is the tenth key. It is the **bar's own** trigger rather than a markdown
+command, and it is in the same bag so that an app cannot pass nine glyphs and be left with
+the words "More actions" at the end of the row.
+
+<Canvas of={MarkdownEditorStories.IconToolbar} />
+
 ## Keyboard
 
 | Key | Does |

package/src/MarkdownEditor/MarkdownEditor.stories.tsx

@@ -7,6 +7,7 @@ import {
   StoryGrid,
 } from "../board.storyHelpers.tsx"
 import { Field } from "../Field/Field.tsx"
+import { MARKDOWN_ICONS } from "../icons.storyHelpers.tsx"
 import { MarkdownEditor } from "./MarkdownEditor.tsx"
 
 /**
@@ -265,3 +266,19 @@ export const Blank: Story = {
     placeholder: "Write it in markdown…",
   },
 }
+
+/**
+ * The bar with an app's icon set, and the `overflow` glyph that
+ * finishes it.
+ *
+ * This editor's overflow is a `Menu` rather than a `Popover`, so
+ * the collapsed actions keep their words in the menu rows — the
+ * icons buy width in the bar without costing the names anywhere.
+ */
+export const IconToolbar: Story = {
+  args: {
+    defaultValue: SAMPLE,
+    icons: MARKDOWN_ICONS,
+    label: "Description",
+  },
+}

package/src/MarkdownEditor/MarkdownEditor.tsx

@@ -50,6 +50,12 @@ export type MarkdownImageUpload = {
  * everywhere and collapses into the overflow menu early; an app
  * that brings lucide gets a compact bar and keeps the words as the
  * accessible names.
+ *
+ * `overflow` is the odd one out: it is not a markdown command, it
+ * is the **bar's own** trigger. It lives here because an app that
+ * passes the nine and not the tenth gets nine icons followed by
+ * the words *"More actions"* — which is the one width where an
+ * icon bar looks unfinished, and there was no prop to fix it with.
  */
 export type MarkdownEditorIcons = Partial<
   Record<
@@ -60,6 +66,7 @@ export type MarkdownEditorIcons = Partial<
     | "italic"
     | "link"
     | "numberedList"
+    | "overflow"
     | "quote"
     | "taskList",
     ReactNode
@@ -746,6 +753,7 @@ export const MarkdownEditor = ({
           ]}
           label={toolbarLabel}
           overflow="menu"
+          overflowIcon={icons?.overflow}
         />
       </div>
 

package/src/icons.storyHelpers.tsx

@@ -191,3 +191,111 @@ export const MoreIcon = (): ReactNode => (
     <circle cx="12" cy="19" r="1.75" />
   </svg>
 )
+
+/**
+ * The markdown toolbar's nine, plus the bar's own overflow above.
+ *
+ * They are here rather than in the editor's story file because the
+ * two editors — the textarea one and the CodeMirror one — take the
+ * same `icons` bag and both boards want it. `MARKDOWN_ICONS` below
+ * is the whole bag, so a story passes one object instead of nine
+ * props and cannot demonstrate a half-iconed bar by accident.
+ */
+export const BoldIcon = (): ReactNode => (
+  <svg {...iconProps} aria-hidden="true">
+    <path d="M7 5h6.5a3.5 3.5 0 0 1 0 7H7z" />
+
+    <path d="M7 12h7.5a3.5 3.5 0 0 1 0 7H7z" />
+  </svg>
+)
+
+export const ItalicIcon = (): ReactNode => (
+  <svg {...iconProps} aria-hidden="true">
+    <path d="M19 5h-8M13 19H5M15 5l-4 14" />
+  </svg>
+)
+
+export const HeadingIcon = (): ReactNode => (
+  <svg {...iconProps} aria-hidden="true">
+    <path d="M6 5v14M18 5v14M6 12h12" />
+  </svg>
+)
+
+export const BulletedListIcon = (): ReactNode => (
+  <svg {...iconProps} aria-hidden="true">
+    <path d="M9 6h12M9 12h12M9 18h12" />
+
+    <path d="M4.5 6h.01M4.5 12h.01M4.5 18h.01" />
+  </svg>
+)
+
+export const TaskListIcon = (): ReactNode => (
+  <svg {...iconProps} aria-hidden="true">
+    <path d="M3 6.5l1.8 1.8L8 5M3 16.5l1.8 1.8L8 15" />
+
+    <path d="M12 7h9M12 17h9" />
+  </svg>
+)
+
+export const NumberedListIcon = (): ReactNode => (
+  <svg {...iconProps} aria-hidden="true">
+    <path d="M11 6h10M11 12h10M11 18h10" />
+
+    <path d="M4 5.5l1.5-.5V10M4 10h3" />
+
+    <path d="M4 15.2a1.6 1.6 0 1 1 2.6 1.3L4 19h3" />
+  </svg>
+)
+
+/**
+ * Two quote marks, not an indented bar. An indent bar is what the
+ * *result* looks like; the marks are what the button does.
+ *
+ * Filled, and closed rather than an open stroke. The stroked
+ * version of this shape drew as a pair of `s` characters at
+ * `size-[1.15em]` — a curve that reads as a letter is worse than
+ * no icon, because the eye stops to read it.
+ */
+export const QuoteIcon = (): ReactNode => (
+  <svg
+    {...iconProps}
+    aria-hidden="true"
+    fill="currentColor"
+    stroke="none"
+  >
+    <path d="M10 6.2a6.6 6.6 0 0 0-4.7 6.2c0 2.1 1.3 3.6 3.2 3.6 1.7 0 2.9-1.2 2.9-2.8 0-1.6-1.1-2.7-2.6-2.7h-.5c.4-1.4 1.4-2.5 2.8-3.1z" />
+
+    <path d="M19 6.2a6.6 6.6 0 0 0-4.7 6.2c0 2.1 1.3 3.6 3.2 3.6 1.7 0 2.9-1.2 2.9-2.8 0-1.6-1.1-2.7-2.6-2.7h-.5c.4-1.4 1.4-2.5 2.8-3.1z" />
+  </svg>
+)
+
+export const CodeIcon = (): ReactNode => (
+  <svg {...iconProps} aria-hidden="true">
+    <path d="M16 18l6-6-6-6M8 6l-6 6 6 6" />
+  </svg>
+)
+
+export const LinkIcon = (): ReactNode => (
+  <svg {...iconProps} aria-hidden="true">
+    <path d="M10.5 13.5a4.5 4.5 0 0 0 6.8.5l2.5-2.5a4.5 4.5 0 0 0-6.4-6.4l-1.4 1.4" />
+
+    <path d="M13.5 10.5a4.5 4.5 0 0 0-6.8-.5l-2.5 2.5a4.5 4.5 0 0 0 6.4 6.4l1.4-1.4" />
+  </svg>
+)
+
+/**
+ * The whole `MarkdownEditorIcons` bag, ready to spread into either
+ * editor's `icons` prop.
+ */
+export const MARKDOWN_ICONS = {
+  bold: <BoldIcon />,
+  bulletedList: <BulletedListIcon />,
+  code: <CodeIcon />,
+  heading: <HeadingIcon />,
+  italic: <ItalicIcon />,
+  link: <LinkIcon />,
+  numberedList: <NumberedListIcon />,
+  overflow: <MoreIcon />,
+  quote: <QuoteIcon />,
+  taskList: <TaskListIcon />,
+}

package/src/markdownEditorCodeMirror/MarkdownEditorCodeMirror.mdx

@@ -155,6 +155,22 @@ from either edge, or flip the Markdown source toggle, which is exactly what it i
   a literal paste is worse than not linkifying one.
 - **Anything else** is left to the browser.
 
+## The toolbar is words until you bring icons
+
+This package ships **no icons**, so the bar defaults to ten word buttons — which is a bar
+that has already collapsed most of itself into "More actions" at the width a description
+field actually gets. Pass an `icons` bag and the whole row fits, with the words kept as the
+accessible names.
+
+<Canvas of={MarkdownEditorCodeMirrorStories.IconsVersusWords} />
+
+`icons.overflow` is the tenth key and the odd one out — it is the **bar's own** trigger,
+not a markdown command. It is in the same bag because an app that passes the nine and not
+the tenth gets nine glyphs followed by the words "More actions", and until now there was no
+prop to fix that with.
+
+<Canvas of={MarkdownEditorCodeMirrorStories.IconToolbar} />
+
 ## Accessibility, and the honest cost
 
 The `<textarea>` sibling gets caret movement, IME composition, spellcheck, the platform undo

package/src/markdownEditorCodeMirror/MarkdownEditorCodeMirror.stories.tsx

@@ -5,6 +5,7 @@ import {
   StoryGrid,
 } from "../board.storyHelpers.tsx"
 import { Field } from "../Field/Field.tsx"
+import { MARKDOWN_ICONS } from "../icons.storyHelpers.tsx"
 import { MarkdownEditorCodeMirror } from "./MarkdownEditorCodeMirror.tsx"
 
 /**
@@ -187,3 +188,57 @@ export const Tables: Story = {
     label: "Description",
   },
 }
+
+/**
+ * The same bar, with an app's icon set.
+ *
+ * Words are the default because the library ships no icons
+ * ([decision](../../../../docs/decisions/2026-07-29-ship-no-icons-and-no-symbol-glyphs.md)),
+ * and nine words is a bar that has already overflowed at the width
+ * a description field actually gets. Ten glyphs fit, so the
+ * overflow trigger is not drawn at all — and the words survive as
+ * the accessible names, which is what the toolbar test asserts.
+ *
+ * `overflow` is in the bag for the width where the bar *does* still
+ * collapse. Without it the row reads as nine icons and then the
+ * words "More actions".
+ */
+export const IconToolbar: Story = {
+  args: {
+    defaultValue: SAMPLE,
+    icons: MARKDOWN_ICONS,
+    label: "Description",
+  },
+}
+
+/**
+ * Icons and words at the width that separates them.
+ *
+ * Same component, same items, same container — the only difference
+ * is the `icons` bag. The word bar has collapsed most of its
+ * actions into "More actions"; the icon bar still shows all ten.
+ */
+export const IconsVersusWords: Story = {
+  args: { label: "Description" },
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell
+        align="stretch"
+        label="words (no icons passed)"
+      >
+        <MarkdownEditorCodeMirror
+          defaultValue="The default bar."
+          label="Words"
+        />
+      </StoryCell>
+
+      <StoryCell align="stretch" label="icons">
+        <MarkdownEditorCodeMirror
+          defaultValue="The same bar, iconed."
+          icons={MARKDOWN_ICONS}
+          label="Icons"
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}

package/src/markdownEditorCodeMirror/MarkdownEditorCodeMirror.tsx

@@ -830,6 +830,7 @@ export const MarkdownEditorCodeMirror = ({
           ]}
           label={toolbarLabel}
           overflow="panel"
+          overflowIcon={icons?.overflow}
         />
       </div>
 

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),