@charcuterie/ui 3.26.0 → 3.28.0

package/src/Board/BoardLaneList.tsx

@@ -89,6 +89,7 @@ export type BoardLaneListProps = {
   headingLevel: 2 | 3 | 4 | 5
   isVisibleWhenNarrow: boolean
   lane: BoardLane
+  laneLayout: "columns" | "rows"
   moveIcon?: ReactNode
   moveTargets: readonly { key: string; label: string }[]
   onMoveToLane?: (
@@ -144,6 +145,7 @@ export const BoardLaneList = ({
   headingLevel,
   isVisibleWhenNarrow,
   lane,
+  laneLayout,
   moveIcon,
   moveTargets,
   onMoveToLane,
@@ -189,7 +191,11 @@ export const BoardLaneList = ({
         // queries the **board**, not the list below — an element
         // carrying `container-type` still resolves its own container
         // queries against its nearest ancestor container.
-        isVisibleWhenNarrow ? "flex" : "hidden cq-lg:flex",
+        laneLayout === "rows"
+          ? "flex"
+          : isVisibleWhenNarrow
+            ? "flex"
+            : "hidden cq-lg:flex",
       )}
     >
       {/*
@@ -201,8 +207,20 @@ export const BoardLaneList = ({
        * treatment becomes expressible.
        */}
       <div className="@container">
-        <div className="flex flex-col gap-2 rounded-lg border border-border-subtle bg-surface-raised px-3 py-2 cq-lg:border-0 cq-lg:bg-transparent cq-lg:p-0">
-          <header className="flex items-center gap-2">
+        <div
+          className={toClassName(
+            "gap-2 rounded-lg border border-border-subtle px-3 py-2",
+            laneLayout === "rows"
+              ? "grid bg-surface-raised cq-lg:grid-cols-[12rem_minmax(0,1fr)] cq-lg:items-start cq-lg:gap-x-3"
+              : "flex flex-col bg-surface-raised cq-lg:border-0 cq-lg:bg-transparent cq-lg:p-0",
+          )}
+        >
+          <header
+            className={toClassName(
+              "flex items-center gap-2",
+              laneLayout === "rows" && "flex-wrap",
+            )}
+          >
             <Heading
               className="font-semibold text-content-primary text-sm"
               id={headingId}
@@ -245,7 +263,12 @@ export const BoardLaneList = ({
           </header>
 
           <ul
-            className="relative flex flex-col"
+            className={toClassName(
+              "relative",
+              laneLayout === "rows"
+                ? "grid grid-cols-[repeat(auto-fit,minmax(min(100%,14rem),1fr))] gap-2"
+                : "flex flex-col",
+            )}
             ref={registerListElement}
           >
             {lane.items.length === 0 ? (
@@ -266,6 +289,7 @@ export const BoardLaneList = ({
             ) : (
               lane.items.map((item, index) => (
                 <BoardCard
+                  isInGrid={laneLayout === "rows"}
                   item={item}
                   key={item.key}
                   laneLabel={lane.label}
@@ -304,7 +328,13 @@ export const BoardLaneList = ({
           </ul>
 
           {hiddenCount > 0 ? (
-            <p className="text-content-muted text-xs">
+            <p
+              className={toClassName(
+                "text-content-muted text-xs",
+                laneLayout === "rows" &&
+                  "cq-lg:col-start-2",
+              )}
+            >
               {lane.onShowMore ? (
                 <Button
                   appearance="ghost"

package/src/MarkdownEditor/MarkdownEditor.mdx

@@ -114,7 +114,7 @@ A consumer that must swap the whole document — Docket opening a different task
 with a `key`. That is one line, and it is honest about the fact that the old undo history
 belonged to the old document.
 
-## Paste an image at the cursor
+## Put an image at the cursor — paste, drop, or press **Image**
 
 ```tsx
 <MarkdownEditor
@@ -137,8 +137,35 @@ during an upload and the insertion point has to move with what they type. It car
 counter so two files of the same name do not resolve into each other's slot, and a failed
 upload leaves a document the user can read and fix rather than a dangling widget.
 
-Omit `onUploadImage` and image paste is simply not offered. A `<textarea>` ignores a pasted
-image on its own, which is the correct fallback rather than a broken one.
+Omit `onUploadImage` and none of the three is offered — no toolbar button, and a paste left
+to the browser. A `<textarea>` ignores a pasted image on its own, which is the correct
+fallback rather than a broken one.
+
+### The **Image** button, and why it is in the toolbar
+
+Paste and drop are both mouse-and-keyboard gestures. On a tablet there is nothing to paste
+from and nothing to drag, so wiring `onUploadImage` also puts an **Image** action in the
+toolbar: it opens the platform file picker, which on a phone is where the camera is offered.
+
+It is a toolbar action rather than a `FileDropZone` under the box **because of the caret**.
+Pressing anything outside the editor moves focus out of it, so a control beside the editor
+can only append to the end of the document — and an image in prose belongs at the point it
+is explained, not stapled to the bottom. The `<textarea>` keeps its `selectionStart` while
+blurred, so the insertion lands where the user last was.
+
+**It is the fourth action, and the position is load-bearing.** `Toolbar` overflows from the
+**end** of the list, so the order in that list is the priority order. Placed last — beside
+Link, where it reads most naturally — Image was the first thing to collapse, hidden behind
+"More actions" at 900px. A control nobody can find does not fix "adding an image is buried";
+it moves the problem. Fourth is visible wherever four actions fit, and it reads as a group:
+emphasis, structure, insert.
+
+⚠️ **It still collapses on a genuinely narrow editor, and that is not a bug to route around.**
+Measured on the `Interactive` story: at 900px the bar carries eight actions and Image is one
+of them; at 460px it carries three, and everything after Heading is in the overflow. A
+comment box in a rail is that width. Keep a `FileDropZone` beside such an editor as well —
+appending to the end of the document is the right trade when the alternative is a control
+nobody can reach.
 
 ## Composition, and the one component that did not fit
 
@@ -152,7 +179,8 @@ component.
 `<label>` around a file input covering its whole area — correct for "drop a disc image here",
 and wrong for a text surface, where the drop has to land *at a character offset* and the area
 has to keep taking clicks as caret placement. So the editor handles its own drop, and
-`FileDropZone` stays the right answer for the attachment list beside it.
+`FileDropZone` stays the right answer for the attachment list beside it — and for a
+narrow editor whose toolbar has collapsed the Image action away.
 
 <Canvas of={MarkdownEditorStories.Responsive} />
 

package/src/MarkdownEditor/MarkdownEditor.test.tsx

@@ -625,3 +625,111 @@ test("the hint stays described when the container is narrow", async () => {
 
   await expectNoAxeViolations(canvasElement)
 })
+
+/**
+ * THE IMAGE BUTTON, and the reason it is in the toolbar rather
+ * than beside the editor.
+ *
+ * The editor already took a paste and a drop. Neither exists on a
+ * tablet, so the only way in there was a `FileDropZone` under the
+ * box — which appends to the END of the document, because pressing
+ * it moves focus out of the editor. An image in prose belongs at
+ * the point it is explained, so the control has to be one the
+ * editor owns.
+ *
+ * ⚠️ It is the FOURTH action, before the lists, because `Toolbar`
+ * overflows from the end and last put it behind "More actions" at
+ * 900px. It still collapses on a narrow enough surface, so a test
+ * cannot assume the button is on the bar.
+ */
+const openImageButton = async (
+  canvas: Canvas,
+  body: Canvas,
+) => {
+  const onTheBar = canvas.queryByRole("button", {
+    name: "Image",
+  })
+
+  if (onTheBar) {
+    return onTheBar
+  }
+
+  await userEvent.click(
+    canvas.getByRole("button", { name: "More actions" }),
+  )
+
+  // The menu is PORTALLED, so it is on `body` and not inside the
+  // story's canvas.
+  return body.getByRole("menuitem", { name: "Image" })
+}
+
+test("the toolbar offers Image when uploads are wired", async () => {
+  const { body, canvas } = await mountStory(Interactive)
+
+  await expect(
+    await openImageButton(canvas, body),
+  ).not.toBeNull()
+})
+
+/** A button that opens a file picker and then has nowhere to send
+ * the file is worse than no button. */
+test("the toolbar hides Image when nothing can take the file", async () => {
+  const { body, canvas } = await mountStory(NoUpload)
+
+  const overflow = canvas.queryByRole("button", {
+    name: "More actions",
+  })
+
+  if (overflow) {
+    await userEvent.click(overflow)
+  }
+
+  await expect(
+    body.queryByRole("button", { name: "Image" }),
+  ).toBeNull()
+
+  await expect(
+    body.queryByRole("menuitem", { name: "Image" }),
+  ).toBeNull()
+})
+
+test("a picked file uploads and lands at the caret", async () => {
+  const { body, canvas } = await mountStory(Interactive)
+
+  const editor = getEditor(canvas, "Task description")
+
+  await userEvent.click(editor)
+
+  editor.setSelectionRange(0, 0)
+
+  await userEvent.click(await openImageButton(canvas, body))
+
+  const picker = canvas
+    .getByRole("toolbar")
+    .parentElement?.querySelector(
+      'input[type="file"]',
+    ) as HTMLInputElement
+
+  await expect(picker).not.toBeNull()
+
+  // The picker itself is the browser's; what this drives is the
+  // `change` it fires on the way back.
+  await userEvent.upload(
+    picker,
+    new File(["binary"], "jig.png", { type: "image/png" }),
+  )
+
+  await waitFor(() => {
+    expect(editor.value).toContain(
+      "![jig.png](https://example.invalid/blobs/jig.png)",
+    )
+  })
+
+  // At the caret — offset 0 — not appended to the end.
+  await expect(editor.value.startsWith("![jig.png](")).toBe(
+    true,
+  )
+
+  // And it is still markdown, with no tag anywhere.
+  await expect(editor.value).not.toContain("<img")
+})

package/src/MarkdownEditor/MarkdownEditor.tsx

@@ -63,6 +63,7 @@ export type MarkdownEditorIcons = Partial<
     | "bulletedList"
     | "code"
     | "heading"
+    | "image"
     | "italic"
     | "link"
     | "numberedList"
@@ -286,6 +287,12 @@ export const MarkdownEditor = ({
 
   const layerRef = useRef<HTMLDivElement>(null)
 
+  /** The toolbar's Image button presses this. It is a real
+   * `<input type="file">` because nothing else opens a file
+   * picker, and it is the only way in on a touch device — there
+   * is nothing to paste from and nothing to drag. */
+  const imageInputRef = useRef<HTMLInputElement>(null)
+
   const uploadCount = useRef(0)
 
   const [value, setValue] = useState(defaultValue)
@@ -674,6 +681,54 @@ export const MarkdownEditor = ({
                 )
               },
             },
+            /*
+              IMAGE, and only when the consumer can actually take
+              one. A button that opens a file picker and then has
+              nowhere to send the file is worse than no button.
+
+              Spread rather than a `filter(Boolean)` so the array
+              stays a `ToolbarItem[]` without a cast.
+
+              ⚠️ FOURTH, and the position is load-bearing rather
+              than aesthetic. `Toolbar` overflows from the END of
+              this list, so the order IS the priority order. Put
+              last, beside Link where it reads most naturally, and
+              Image was the first thing to collapse into "More
+              actions" — at 900px it was already hidden, and in a
+              comment box in a rail it never appeared at all. That
+              is the complaint this button exists to answer:
+              *"adding an image is way at the bottom"*. Hiding it
+              behind an overflow trigger moves the problem rather
+              than fixing it.
+
+              Fourth is visible wherever four actions fit — at
+              900px the bar carries eight. It still collapses on a
+              genuinely narrow editor (at 460px the bar carries
+              three), which is why a comment box in a rail keeps a
+              `FileDropZone` beside it. It also reads: emphasis,
+              then structure, then insert.
+
+              The caret is why this belongs in the toolbar at all
+              rather than beside the editor. A `FileDropZone` under
+              the box appends to the end of the document, because
+              pressing it moves focus out; the textarea keeps its
+              `selectionStart` while blurred, so the insertion
+              lands where the user last was — which is the whole
+              point of an image in prose.
+            */
+            ...(onUploadImage
+              ? [
+                  {
+                    icon: icons?.image,
+                    isDisabled: isDisabled || isReadOnly,
+                    key: "image",
+                    label: "Image",
+                    onSelect: () => {
+                      imageInputRef.current?.click()
+                    },
+                  },
+                ]
+              : []),
             {
               icon: icons?.bulletedList,
               isDisabled: isDisabled || isReadOnly,
@@ -755,6 +810,40 @@ export const MarkdownEditor = ({
           overflow="menu"
           overflowIcon={icons?.overflow}
         />
+
+        {/*
+          The Image button's actual control.
+
+          `hidden`, not `sr-only`: `display: none` takes it out of
+          the accessibility tree, which is what is wanted here —
+          the toolbar button is the named control, and a second
+          unlabelled file input announced beside it would be one
+          control too many. `.click()` on a hidden input opens the
+          picker in every browser the fleet runs.
+
+          `multiple`, because a drop already takes several and the
+          two ways in should not disagree. The value is cleared
+          after each pick so choosing the SAME file twice fires
+          `change` the second time.
+        */}
+        {onUploadImage ? (
+          <input
+            accept="image/*"
+            aria-hidden="true"
+            className="hidden"
+            multiple
+            onChange={(changeEvent) => {
+              uploadImages(
+                Array.from(changeEvent.target.files ?? []),
+              )
+
+              changeEvent.target.value = ""
+            }}
+            ref={imageInputRef}
+            tabIndex={-1}
+            type="file"
+          />
+        ) : null}
       </div>
 
       <div className="grid">

package/src/Stepper/Stepper.stories.tsx

@@ -170,6 +170,33 @@ export const Responsive: Story = {
   ),
 }
 
+/** Short labels can opt out of the collapse when the sequence is a
+ * compact status ladder inside a card. */
+export const CompactCard: Story = {
+  args: {
+    appearance: "compact",
+    isResponsive: false,
+    orientation: "horizontal",
+    steps: [
+      { key: "ordered", label: "Ordered", status: "done" },
+      { key: "shipped", label: "Shipped", status: "done" },
+      { key: "out", label: "Out today", status: "current" },
+      {
+        key: "delivered",
+        label: "Delivered",
+        status: "upcoming",
+      },
+    ],
+  },
+  render: (stepperProps) => (
+    <div className="w-[22rem] max-w-full">
+      <Card>
+        <Stepper {...stepperProps} />
+      </Card>
+    </div>
+  ),
+}
+
 /**
  * The whole keyboard path, which is the point of the headings: a
  * stepper is a document outline, not a widget. There is nothing to

package/src/Stepper/Stepper.test.tsx

@@ -6,8 +6,13 @@ import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
 import { mountStory } from "../mountStory.testHelpers.ts"
 import * as stories from "./Stepper.stories.tsx"
 
-const { AllStates, Default, Interactive, Responsive } =
-  composeStories(stories)
+const {
+  AllStates,
+  CompactCard,
+  Default,
+  Interactive,
+  Responsive,
+} = composeStories(stories)
 
 test("the sequence is an ordered list with a name", async () => {
   const { canvas } = await mountStory(Default)
@@ -127,3 +132,13 @@ test("no axe violations, in either orientation", async () => {
 
   await expectNoAxeViolations(horizontal.canvasElement)
 })
+
+test("a compact card can keep the horizontal ladder below cq-md", async () => {
+  const { canvas } = await mountStory(CompactCard)
+
+  await expect(
+    getComputedStyle(
+      canvas.getByRole("list", { name: "Ingest sequence" }),
+    ).flexDirection,
+  ).toBe("row")
+})

package/src/Stepper/Stepper.tsx

@@ -43,6 +43,8 @@ export type Step = {
 export type StepperOrientation = "horizontal" | "vertical"
 
 export type StepperProps = {
+  /** `compact` is the dot-and-line ladder for short status labels in cards. */
+  readonly appearance?: "default" | "compact"
   readonly className?: string
   /**
    * What level the step labels are. The caller's, because only the
@@ -55,6 +57,13 @@ export type StepperProps = {
   /** The list's accessible name. Required — an unnamed sequence of
    * numbers is a sequence of numbers. */
   readonly label: string
+  /**
+   * Whether a requested horizontal sequence collapses below `cq-md`.
+   * Keep this on for prose-sized steps. Turn it off only when the
+   * caller supplies short labels that are designed to remain a compact
+   * ladder inside a card.
+   */
+  readonly isResponsive?: boolean
   /**
    * `horizontal` is a REQUEST, not a promise: it collapses to
    * vertical below `cq-md`, because four steps side by side in a
@@ -99,14 +108,17 @@ export type StepperProps = {
  * `:not(:last-child)` selector nobody remembers to write.
  */
 export const Stepper = ({
+  appearance = "default",
   className,
   headingLevel = 3,
+  isResponsive = true,
   label,
   orientation = "vertical",
   steps,
 }: StepperProps) => {
   const Heading = `h${headingLevel}` as "h3"
   const isHorizontal = orientation === "horizontal"
+  const isCompact = appearance === "compact"
 
   return (
     // The container is a WRAPPER, never the `<ol>` itself.
@@ -131,7 +143,10 @@ export const Stepper = ({
           // `Board` follows and for the same reason: the owner
           // browses zoomed in, so a window's width is not the
           // number of pixels anything actually has.
-          isHorizontal && "cq-md:flex-row cq-md:gap-0",
+          isHorizontal &&
+            (isResponsive
+              ? "cq-md:flex-row cq-md:gap-0"
+              : "flex-row gap-0"),
         )}
       >
         {steps.map((step, index) => {
@@ -163,7 +178,10 @@ export const Stepper = ({
               className={toClassName(
                 "relative grid grid-cols-[auto_minmax(0,1fr)] grid-rows-[auto_minmax(0,1fr)] gap-x-3",
                 isHorizontal &&
-                  "cq-md:flex cq-md:min-w-0 cq-md:flex-1 cq-md:flex-col cq-md:gap-y-2",
+                  (isResponsive
+                    ? "cq-md:flex cq-md:min-w-0 cq-md:flex-1 cq-md:flex-col cq-md:gap-y-2"
+                    : "flex min-w-0 flex-1 flex-col gap-y-2"),
+                isCompact && "gap-y-1",
                 // Blocked and upcoming recede; the step you can act
                 // on is the one that keeps full contrast. Opacity
                 // rather than a muted token so the step's own
@@ -177,12 +195,23 @@ export const Stepper = ({
             >
               <span
                 className={toClassName(
-                  "col-start-1 row-start-1 grid size-7 place-items-center rounded-full border text-sm tabular-nums",
+                  isCompact
+                    ? "col-start-1 row-start-1 grid size-3 place-items-center rounded-full border text-xs tabular-nums"
+                    : "col-start-1 row-start-1 grid size-7 place-items-center rounded-full border text-sm tabular-nums",
                   STATUS_MARKER_CLASS[status],
-                  isHorizontal && "cq-md:col-start-1",
+                  isHorizontal &&
+                    (isResponsive
+                      ? "cq-md:col-start-1"
+                      : "col-start-1"),
                 )}
               >
-                {step.marker ?? index + 1}
+                {isCompact ? (
+                  <VisuallyHidden>
+                    {step.marker ?? index + 1}
+                  </VisuallyHidden>
+                ) : (
+                  (step.marker ?? index + 1)
+                )}
               </span>
 
               {/* Absent on the last step, so nothing draws a line
@@ -199,7 +228,13 @@ export const Stepper = ({
                       ? "bg-intent-success-solid"
                       : "bg-border-subtle",
                     isHorizontal &&
-                      "cq-md:absolute cq-md:top-3.5 cq-md:start-7 cq-md:my-0 cq-md:h-0.5 cq-md:w-[calc(100%-1.75rem)]",
+                      (isCompact
+                        ? isResponsive
+                          ? "cq-md:absolute cq-md:top-1.5 cq-md:start-3 cq-md:my-0 cq-md:h-0.5 cq-md:w-[calc(100%-0.75rem)]"
+                          : "absolute top-1.5 start-3 my-0 h-0.5 w-[calc(100%-0.75rem)]"
+                        : isResponsive
+                          ? "cq-md:absolute cq-md:top-3.5 cq-md:start-7 cq-md:my-0 cq-md:h-0.5 cq-md:w-[calc(100%-1.75rem)]"
+                          : "absolute top-3.5 start-7 my-0 h-0.5 w-[calc(100%-1.75rem)]"),
                   )}
                 />
               )}
@@ -207,10 +242,18 @@ export const Stepper = ({
               <div
                 className={toClassName(
                   "col-start-2 row-span-2 row-start-1 min-w-0",
-                  isHorizontal && "cq-md:col-start-1",
+                  isHorizontal &&
+                    (isResponsive
+                      ? "cq-md:col-start-1"
+                      : "col-start-1"),
                 )}
               >
-                <Heading className="m-0 flex flex-wrap items-center gap-2 text-md font-medium text-content-primary">
+                <Heading
+                  className={toClassName(
+                    "m-0 flex flex-wrap items-center gap-2 font-medium text-content-primary",
+                    isCompact ? "text-xs" : "text-md",
+                  )}
+                >
                   {step.label}
 
                   {/* The status as a WORD. Four marker colours is

package/src/icons.storyHelpers.tsx

@@ -295,6 +295,16 @@ export const LinkIcon = (): ReactNode => (
   </svg>
 )
 
+export const ImageIcon = (): ReactNode => (
+  <svg {...iconProps} aria-hidden="true">
+    <rect height="16" rx="2" width="18" x="3" y="4" />
+
+    <path d="M3 15l5-5 4 4 3-3 6 6" />
+
+    <circle cx="8.5" cy="9" r="1.2" />
+  </svg>
+)
+
 /**
  * The whole `MarkdownEditorIcons` bag, ready to spread into either
  * editor's `icons` prop.
@@ -304,6 +314,7 @@ export const MARKDOWN_ICONS = {
   bulletedList: <BulletedListIcon />,
   code: <CodeIcon />,
   heading: <HeadingIcon />,
+  image: <ImageIcon />,
   italic: <ItalicIcon />,
   link: <LinkIcon />,
   numberedList: <NumberedListIcon />,

package/src/markdownEditorCodeMirror/MarkdownEditorCodeMirror.mdx

@@ -148,7 +148,9 @@ from either edge, or flip the Markdown source toggle, which is exactly what it i
 
 ## Pasting
 
-- **An image** (or a drop) runs `onUploadImage` and inserts `![alt](url)` at the caret, then
+- **An image** — pasted, dropped, or picked with the toolbar's **Image** action, which
+  appears only when `onUploadImage` is wired and is the only way in on a tablet — 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

package/src/markdownEditorCodeMirror/MarkdownEditorCodeMirror.stories.tsx

@@ -242,3 +242,34 @@ export const IconsVersusWords: Story = {
     </StoryGrid>
   ),
 }
+
+/**
+ * With an upload wired, so the **Image** toolbar action appears.
+ *
+ * The editor already took a paste and a drop; neither exists on a
+ * tablet, and a `FileDropZone` beside the box appends to the end of
+ * the document because pressing it moves focus out. The toolbar
+ * button keeps the insertion at the caret, which is the whole point
+ * of an image in prose.
+ *
+ * The upload here is a fake that resolves after a beat, so the
+ * placeholder is visible while it runs. A real consumer returns a
+ * URL from its own blob storage.
+ */
+export const Uploading: Story = {
+  args: {
+    defaultValue:
+      "Press Image, or paste one, and it lands where the caret is.\n",
+    label: "Task description",
+    onUploadImage: async (file: File) => {
+      await new Promise((resolve) => {
+        setTimeout(resolve, 600)
+      })
+
+      return {
+        alt: file.name,
+        url: `https://example.invalid/blobs/${encodeURIComponent(file.name)}`,
+      }
+    },
+  },
+}