@charcuterie/ui 4.9.0 → 4.10.0

package/src/Breadcrumbs/Breadcrumbs.tsx

@@ -0,0 +1,179 @@
+import type { Key, ReactNode } from "react"
+
+import { FOCUS_RING_CLASS } from "../intentStyles.ts"
+import { TextLink } from "../TextLink/TextLink.tsx"
+import { toClassName } from "../toClassName.ts"
+
+/**
+ * One rung of the trail.
+ *
+ * Which of the three it becomes is read off the fields it carries, so
+ * a caller mapping a path to items never has to say what the rung
+ * *is* — only where it goes:
+ *
+ *  - `href` — a real `<a href>`, through `TextLink`, so an in-app path
+ *    goes through the injected router exactly as every other link in
+ *    the library does.
+ *  - `onSelect` and no `href` — a `<button>` painted as the same link.
+ *    For a trail over state that has no URL: image-viewer's folder
+ *    path and mux-magic's file-explorer modal both move a browser
+ *    around a disk without touching the address bar.
+ *  - neither — plain text. On the **last** item that is the current
+ *    page, and it carries `aria-current="page"`.
+ */
+export type BreadcrumbItem = {
+  href?: string
+  /**
+   * React's list key. Optional, because `label` is a node and cannot
+   * be one; the fallback is `href`, then the position. Pass it when
+   * two rungs can share an `href` or the trail reorders.
+   */
+  key?: Key
+  label: ReactNode
+  /**
+   * Runs on activation. With an `href` it runs alongside the
+   * navigation (closing a drawer, say); without one it IS the
+   * navigation.
+   */
+  onSelect?: () => void
+}
+
+export type BreadcrumbsProps = {
+  className?: string
+  items: readonly BreadcrumbItem[]
+  /**
+   * The `<nav>` landmark's name. Two trails on one page need two
+   * different names, or axe's `landmark-unique` fails.
+   */
+  label?: string
+  /**
+   * Drawn between rungs, always `aria-hidden`. The default is a
+   * chevron drawn in CSS borders rather than a `›` character: the
+   * library ships no symbol glyphs in a default, because a font that
+   * lacks one paints nothing
+   * (`docs/decisions/2026-07-29-ship-no-icons-and-no-symbol-glyphs.md`).
+   * Folio's `/` is a fine override — it is the app's choice to make.
+   */
+  separator?: ReactNode
+}
+
+/**
+ * The link paint without the `<a>`: `TextLink`'s standalone look,
+ * restated for the `onSelect` rung so a button crumb and a link crumb
+ * are indistinguishable at rest, on hover, and under focus.
+ */
+const BUTTON_CRUMB_CLASS =
+  "inline cursor-pointer rounded-xs border-0 bg-transparent p-0 text-start font-medium text-intent-accent-content underline-offset-2 hover:underline"
+
+/**
+ * `wrap-anywhere` on every label, and no `truncate`: a trail that cuts
+ * a folder name to `Office Sh…` hides the one word the reader came to
+ * find. A long unbroken segment — a hash, a file name — breaks inside
+ * itself instead of pushing the row wider than its container.
+ */
+const LABEL_CLASS = "min-w-0 wrap-anywhere"
+
+/**
+ * Right-pointing in a left-to-right page, left-pointing in a
+ * right-to-left one: the two borders are logical (`border-e`), and the
+ * rotation flips with the direction so the corner always points the
+ * way the trail reads.
+ */
+const DEFAULT_SEPARATOR = (
+  <span className="inline-block size-1.5 shrink-0 rotate-45 border-e-[1.5px] border-t-[1.5px] border-current rtl:-rotate-45" />
+)
+
+const getItemKey = (
+  item: BreadcrumbItem,
+  index: number,
+): Key => item.key ?? item.href ?? index
+
+/**
+ * A path back up a hierarchy: `Places › Office › Office Shelves`.
+ *
+ * Folio, image-viewer and mux-magic each hand-rolled one, and they
+ * disagreed on everything a shared shape should settle — one was a
+ * `<nav>` of bare links with no list, two were `<div>`s of buttons
+ * with no landmark, one truncated the current segment, one gave the
+ * current folder no `aria-current`. This is the WAI-ARIA APG
+ * breadcrumb pattern: a `<nav>` landmark around an `<ol>`, because
+ * the order is the meaning.
+ *
+ * The current page is the **last item with nowhere to go**. A trail
+ * that sits above a heading already naming the page — Whereabouts'
+ * `Places › Office` over an `Office Shelves` heading — gives every
+ * item an `href`, and then no rung is current, which is correct: the
+ * page is named once, by the heading.
+ */
+export const Breadcrumbs = ({
+  className,
+  items,
+  label = "Breadcrumb",
+  separator,
+}: BreadcrumbsProps): ReactNode => (
+  <nav aria-label={label} className={className}>
+    <ol className="m-0 flex list-none flex-wrap items-center gap-x-2 gap-y-1 p-0 text-content-secondary text-sm">
+      {items.map((item, index) => {
+        const isLast = index === items.length - 1
+
+        const isCurrent =
+          isLast &&
+          item.href === undefined &&
+          item.onSelect === undefined
+
+        return (
+          <li
+            className="inline-flex min-w-0 items-center gap-x-2"
+            key={getItemKey(item, index)}
+          >
+            {index > 0 ? (
+              <span
+                aria-hidden="true"
+                className="inline-flex shrink-0 items-center text-content-muted"
+              >
+                {separator ?? DEFAULT_SEPARATOR}
+              </span>
+            ) : null}
+
+            {item.href !== undefined ? (
+              <TextLink
+                appearance="standalone"
+                className={LABEL_CLASS}
+                href={item.href}
+                onClick={item.onSelect}
+              >
+                {item.label}
+              </TextLink>
+            ) : item.onSelect !== undefined ? (
+              <button
+                className={toClassName(
+                  BUTTON_CRUMB_CLASS,
+                  FOCUS_RING_CLASS,
+                  LABEL_CLASS,
+                )}
+                onClick={item.onSelect}
+                type="button"
+              >
+                {item.label}
+              </button>
+            ) : (
+              <span
+                aria-current={
+                  isCurrent ? "page" : undefined
+                }
+                className={toClassName(
+                  LABEL_CLASS,
+                  isCurrent
+                    ? "font-medium text-content-primary"
+                    : undefined,
+                )}
+              >
+                {item.label}
+              </span>
+            )}
+          </li>
+        )
+      })}
+    </ol>
+  </nav>
+)

package/src/index.ts

@@ -37,6 +37,8 @@ export type {
   AccordionProps,
 } from "./Accordion/Accordion.tsx"
 export { Accordion } from "./Accordion/Accordion.tsx"
+export type { ActionMenuProps } from "./ActionMenu/ActionMenu.tsx"
+export { ActionMenu } from "./ActionMenu/ActionMenu.tsx"
 export type {
   ActionTileItem,
   ActionTilesAccent,
@@ -99,6 +101,11 @@ export {
   getIsMoveMeaningful,
   toSettledIndex,
 } from "./Board/boardMove.ts"
+export type {
+  BreadcrumbItem,
+  BreadcrumbsProps,
+} from "./Breadcrumbs/Breadcrumbs.tsx"
+export { Breadcrumbs } from "./Breadcrumbs/Breadcrumbs.tsx"
 export type { ButtonProps } from "./Button/Button.tsx"
 export { Button } from "./Button/Button.tsx"
 export type { ButtonLinkProps } from "./ButtonLink/ButtonLink.tsx"

package/src/markdownEditorCodeMirror/livePreview.test.ts

@@ -0,0 +1,88 @@
+import {
+  markdown,
+  markdownLanguage,
+} from "@codemirror/lang-markdown"
+import { Language, syntaxTree } from "@codemirror/language"
+import {
+  EditorState,
+  type Transaction,
+} from "@codemirror/state"
+import { expect, test } from "vitest"
+
+import {
+  isInlineDecorationStale,
+  livePreview,
+} from "./livePreview.ts"
+
+const toUpdate = (transaction: Transaction) => ({
+  docChanged: transaction.docChanged,
+  selectionSet: transaction.selection !== undefined,
+  viewportChanged: false,
+  focusChanged: false,
+  transactions: [transaction],
+  startState: transaction.startState,
+  state: transaction.state,
+})
+
+/**
+ * A parse step with nothing else in it, the way CodeMirror's own
+ * background worker delivers one: `Language.setState` carrying a new
+ * `LanguageState` over the same, further-advanced parse context.
+ *
+ * Both are internal to `@codemirror/language`, which is why this is
+ * spelled out rather than hidden in a helper. The alternative — a
+ * real `EditorView` racing a real idle callback — is what made the
+ * VRT story flake, and a test that only fails when the runner is
+ * slow is the same flake with a different name.
+ */
+const parseFurther = (state: EditorState) => {
+  const internals = Language as unknown as {
+    setState: { of: (value: unknown) => never }
+    state: Parameters<EditorState["field"]>[0]
+  }
+  const current = state.field(internals.state) as {
+    constructor: new (context: unknown) => unknown
+    context: {
+      work: (time: number, upto: number) => boolean
+    }
+  }
+  current.context.work(5000, state.doc.length)
+
+  return state.update({
+    effects: internals.setState.of(
+      new current.constructor(current.context),
+    ),
+  })
+}
+
+test("a parse step alone makes the inline decorations stale", () => {
+  const doc =
+    "Read [the runbook](https://example.invalid) first.\n\n".repeat(
+      3000,
+    )
+  const state = EditorState.create({
+    doc,
+    extensions: [
+      markdown({ base: markdownLanguage }),
+      livePreview(),
+    ],
+  })
+
+  // The precondition the whole test rests on: the first parse stops
+  // short of the end, as it does on any long document.
+  expect(syntaxTree(state).length).toBeLessThan(doc.length)
+
+  const idle = state.update({})
+
+  expect(isInlineDecorationStale(toUpdate(idle))).toBe(
+    false,
+  )
+
+  const parsed = parseFurther(state)
+
+  expect(parsed.docChanged).toBe(false)
+  expect(syntaxTree(parsed.state).length).toBe(doc.length)
+  expect(isInlineDecorationStale(toUpdate(parsed))).toBe(
+    true,
+  )
+})

package/src/markdownEditorCodeMirror/livePreview.ts

@@ -957,6 +957,50 @@ const toSafeDecorations = (
   }
 }
 
+/**
+ * Whether the inline decorations are stale after `update`.
+ *
+ * Exported for its test: the tree clause was missing here for months
+ * while `livePreviewTableField` had it. Without it, a document whose
+ * background parse finished after mount painted its last lines raw —
+ * a fence and a link as plain text — until the reader clicked, and a
+ * busy VRT runner photographed exactly that.
+ */
+export const isInlineDecorationStale = (
+  update: Pick<
+    ViewUpdate,
+    | "docChanged"
+    | "selectionSet"
+    | "viewportChanged"
+    | "focusChanged"
+    | "transactions"
+    | "startState"
+    | "state"
+  >,
+) =>
+  // Selection is in the list because concealment depends on the
+  // caret: moving it with an arrow key changes what is painted
+  // even though the document did not change.
+  update.docChanged ||
+  update.selectionSet ||
+  update.viewportChanged ||
+  // Focus is a decoration input now — see `toDecorations`.
+  update.focusChanged ||
+  update.transactions.some((transaction) =>
+    transaction.effects.some((effect) =>
+      effect.is(setLivePreviewRawMode),
+    ),
+  ) ||
+  // The same `Compartment` reconfigure the block pass watches
+  // for: a checkbox that just became operable is a widget
+  // that has to be rebuilt.
+  update.startState.facet(livePreviewOptions) !==
+    update.state.facet(livePreviewOptions) ||
+  // Parsing is incremental and time-sliced — the same reason the
+  // table field compares the tree. A parse step arrives as a
+  // transaction that changes nothing else.
+  syntaxTree(update.state) !== syntaxTree(update.startState)
+
 const livePreviewPlugin = ViewPlugin.fromClass(
   class {
     decorations: DecorationSet
@@ -966,26 +1010,7 @@ const livePreviewPlugin = ViewPlugin.fromClass(
     }
 
     update(update: ViewUpdate) {
-      // Selection is in the list because concealment depends on the
-      // caret: moving it with an arrow key changes what is painted
-      // even though the document did not change.
-      if (
-        update.docChanged ||
-        update.selectionSet ||
-        update.viewportChanged ||
-        // Focus is a decoration input now — see `toDecorations`.
-        update.focusChanged ||
-        update.transactions.some((transaction) =>
-          transaction.effects.some((effect) =>
-            effect.is(setLivePreviewRawMode),
-          ),
-        ) ||
-        // The same `Compartment` reconfigure the block pass watches
-        // for: a checkbox that just became operable is a widget
-        // that has to be rebuilt.
-        update.startState.facet(livePreviewOptions) !==
-          update.state.facet(livePreviewOptions)
-      ) {
+      if (isInlineDecorationStale(update)) {
         this.decorations = toSafeDecorations(update.view)
       }
     }

package/src/sourceRules.test.ts

@@ -615,7 +615,9 @@ test("the barrel is the only place components are re-exported", async () => {
   // question the same way the bars are placed, or the two answers
   // drift by a day and nothing says so.
   // ProgressCard composes Card and ProgressBar for progress-first dashboards.
-  expect(componentNames.length).toBe(67)
+  // Breadcrumbs composes TextLink for the path back up a hierarchy.
+  // ActionMenu composes IconButton and Menu for the overflow control.
+  expect(componentNames.length).toBe(69)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)