@charcuterie/ui 3.23.0 → 3.25.0

package/src/Board/Board.stories.tsx

@@ -477,7 +477,7 @@ export const AllVariants: Story = {
 
       <StoryCell
         align="stretch"
-        label="movable, with the app's own `moveIcon` — ~55px a row cheaper"
+        label="movable, with the app's own `moveIcon` — ~35px a row cheaper"
       >
         <Board
           {...boardProps}
@@ -898,3 +898,54 @@ export const MarkdownTitles: Story = {
     </Frame>
   ),
 }
+
+/**
+ * **The handle wears the gesture that can actually succeed**, and
+ * the two panels below are the same board at two widths.
+ *
+ * Wide, the lanes are side by side: there is somewhere to drop, so
+ * the handle is the app's `moveIcon` — a grip, which is what teaches
+ * a drag. Narrow, there is one lane and a segmented control: nothing
+ * on screen to drop onto, so the handle says **Move**, which is the
+ * gesture that works there. Pressing it opens the same menu at both
+ * widths, and the accessible name is the same sentence at both.
+ *
+ * QueuePilot is why this is not a preference. It shipped `≡` in a
+ * one-lane board and the owner could not move anybody — *"There's
+ * no right-click or anything. How do I move these?"* — and the
+ * first fix took the glyph away at every width, which broke the
+ * half that had been right.
+ */
+export const MoveHandleByWidth: Story = {
+  render: (boardProps) => (
+    <div className="flex flex-col gap-8">
+      <StoryCell
+        align="stretch"
+        label="past --cq-lg — three lanes, so the handle is a grip"
+      >
+        <Frame inlineSize="72rem">
+          <Board
+            {...boardProps}
+            label="Today, wide enough to drag"
+            moveIcon={<MoreIcon />}
+            onMove={() => undefined}
+          />
+        </Frame>
+      </StoryCell>
+
+      <StoryCell
+        align="stretch"
+        label="under --cq-lg — one lane, so the handle says Move"
+      >
+        <Frame inlineSize="34rem">
+          <Board
+            {...boardProps}
+            label="Today, one lane at a time"
+            moveIcon={<MoreIcon />}
+            onMove={() => undefined}
+          />
+        </Frame>
+      </StoryCell>
+    </div>
+  ),
+}

package/src/Board/Board.test.tsx

@@ -20,6 +20,7 @@ const {
   Interactive,
   MarkdownTitles,
   LinkedLaneHeadings,
+  MoveHandleByWidth,
   Responsive,
 } = composeStories(stories)
 
@@ -467,3 +468,84 @@ test("draws a project's colour on the card's own edge", async () => {
     }),
   )
 })
+
+/**
+ * The handle wears the gesture that can succeed, and nothing else.
+ *
+ * This is the bug QueuePilot shipped twice, from both directions. A
+ * `≡` grip in a one-lane board taught a drag with nowhere to land —
+ * *"There's no right-click or anything. How do I move these?"* — and
+ * taking the grip away at every width broke the wide board, where
+ * dragging is exactly what a person reaches for.
+ *
+ * Both affordances are in the DOM at both widths and CSS decides,
+ * so this asserts on what is PAINTED. A container query is the only
+ * honest way to ask: the two boards below sit in a 72rem frame and a
+ * 24rem frame inside one window that never moves.
+ */
+test("a wide board's handle is the app's grip, not the word", async () => {
+  const { canvas } = await mountStory(MoveHandleByWidth)
+
+  const handle = within(
+    canvas.getByRole("region", {
+      name: "Today, wide enough to drag",
+    }),
+  ).getByRole("button", {
+    name: "Move Retire the second scheduler and fold its jobs into the broker, currently in Todo",
+  })
+
+  await expect(
+    within(handle).getByText("Move"),
+  ).not.toBeVisible()
+
+  await expect(handle.querySelector("svg")).toBeVisible()
+
+  // And it is still the SQUARE icon button it was before the word
+  // joined it in the DOM. `sizing` is a prop and cannot be two
+  // values, so the button is `control`-sized underneath and takes
+  // `ICON_CONTROL_SIZE_CLASS`'s width and `px-0` back at this width.
+  // Getting that wrong costs every card in every lane ~20px of
+  // title, silently — this board renders pixel-identically to the
+  // one before the change, and that is the assertion.
+  await expect(handle.offsetWidth).toBe(handle.offsetHeight)
+})
+
+test("a one-lane board's handle says Move, whatever the app passed", async () => {
+  const { canvas } = await mountStory(MoveHandleByWidth)
+
+  const handle = within(
+    canvas.getByRole("region", {
+      name: "Today, one lane at a time",
+    }),
+  ).getByRole("button", {
+    name: "Move Retire the second scheduler and fold its jobs into the broker, currently in Todo",
+  })
+
+  await expect(
+    within(handle).getByText("Move"),
+  ).toBeVisible()
+
+  await expect(
+    handle.querySelector("svg"),
+  ).not.toBeVisible()
+})
+
+/**
+ * The name is the same sentence at both widths, and that is the
+ * point of putting the whole of it in a `VisuallyHidden` while both
+ * visible affordances are `aria-hidden`.
+ *
+ * Left to the visible text, the handle would be called "Move X"
+ * wide and "Move Move X" narrow — one control with two names, one
+ * `getByRole` query that works in one layout and not the other, and
+ * a screen-reader user hearing the word twice.
+ */
+test("the handle has one name at both widths", async () => {
+  const { canvas } = await mountStory(MoveHandleByWidth)
+
+  await expect(
+    canvas.getAllByRole("button", {
+      name: "Move Retire the second scheduler and fold its jobs into the broker, currently in Todo",
+    }),
+  ).toHaveLength(2)
+})

package/src/Board/Board.tsx

@@ -44,12 +44,15 @@ export type BoardProps = {
   label: string
   lanes: readonly BoardLane[]
   /**
-   * What the move handle shows instead of the word "Move". The
-   * library ships no icons and no symbol glyphs in a default —
+   * What the move handle shows **while the lanes are side by side**.
+   * Below `cq-lg` the handle says "Move" whatever this is, because
+   * there is nowhere to drag to — see `BoardCard`.
+   *
+   * The library ships no icons and no symbol glyphs in a default —
    * they render as nothing where the font lacks them, which
    * includes this sandbox's chromium, the kiosk image and the
    * ePaper build — so the default is a word and an app that owns a
-   * glyph set passes one. On a dense board it is worth ~55px a row.
+   * glyph set passes one. On a dense board it is worth ~35px a row.
    */
   moveIcon?: ReactNode
   /**
@@ -216,7 +219,24 @@ export const Board = ({
   return (
     <section
       aria-label={label}
-      className={toClassName("@container", className)}
+      /*
+       * `@container/board`, and the NAME is what a card's move
+       * handle needs.
+       *
+       * An unnamed container query matches the nearest ancestor
+       * container, and between this box and a card there is a
+       * second one — the lane's, one level down, which decides what
+       * shape a card is. So a `cq-lg:` written inside `BoardCard`
+       * asks about the LANE, and the answer is inverted against the
+       * question the handle has to ask: in a three-up board a lane
+       * is ~280px, and in the Narrow View the single lane is the
+       * whole board. Naming this one lets the handle query past the
+       * lane to the box that actually decides how many lanes are on
+       * screen. Naming changes nothing else — a named container
+       * still answers an unnamed query, which is why the segmented
+       * control and the lanes below keep their plain `cq-lg:`.
+       */
+      className={toClassName("@container/board", className)}
     >
       <div className="flex flex-col gap-3">
         {/*

package/src/Board/BoardCard.tsx

@@ -147,13 +147,16 @@ export type BoardCardProps = {
   item: BoardItem
   laneLabel: string
   /**
-   * Shown on the move handle instead of the word "Move". The
-   * library ships no icons, so the default is words — a `⋮` renders
-   * as nothing where the font lacks it, which includes the kiosk
-   * image and the ePaper build. An app that already owns a glyph
-   * set passes one and buys back the ~55px per row that a word
-   * costs, which in a 500px lane is the difference between twenty
-   * characters of title and thirty.
+   * Shown on the move handle **while the lanes are side by side**,
+   * instead of the word "Move". Below the board's `cq-lg` the word
+   * comes back whatever this is — see the handle section below.
+   *
+   * The library ships no icons, so the default is words — a `⋮`
+   * renders as nothing where the font lacks it, which includes the
+   * kiosk image and the ePaper build. An app that already owns a
+   * glyph set passes one and buys back the ~35px per row that a
+   * word costs, which in a 500px lane is several characters of
+   * title.
    */
   moveIcon?: ReactNode
   /** The lanes this card can be sent to — never its own. */
@@ -205,6 +208,38 @@ export type BoardCardProps = {
  * on screen at all. Dragging from it moves the card directly. Both
  * commit through the same callback, so there is no second code path
  * to keep honest and neither is a fallback for the other.
+ *
+ * ### What it WEARS depends on whether a drag can succeed
+ *
+ * The two drivers are not equally available at every width, so the
+ * handle does not claim they are:
+ *
+ * | The board is | The handle shows | Because |
+ * | --- | --- | --- |
+ * | `cq-lg` and wider — lanes side by side | the app's `moveIcon` | the other lanes are on screen, so a drag has somewhere to land, and a grip glyph teaches that gesture |
+ * | narrower — one lane and a segmented control | the word **Move** | there is nothing on screen to drop onto, so the only gesture the glyph teaches is the one that cannot work |
+ *
+ * That table is a bug report. QueuePilot shipped a `≡` handle in a
+ * one-lane board and the owner could not move anybody: *"I can't
+ * seem to drag 'n drop the names from Everyone Else anywhere else.
+ * There's no right-click or anything. How do I move these?"* The
+ * first fix took the glyph away everywhere, which was the wrong
+ * half — *"I think the drag handles were fine, but now you have it
+ * in a 3-column mode, so dragging would work, but it has this
+ * 'move' button instead."*
+ *
+ * Both are in the DOM and CSS picks; neither is rendered from a
+ * measurement. A `ResizeObserver` would get the first paint wrong,
+ * and a kiosk Pi shows that. Both are `aria-hidden`, and the
+ * handle's whole accessible name comes from the `VisuallyHidden`
+ * beside them — so the name is the same sentence at every width,
+ * which is what keeps one `getByRole` query working in both
+ * layouts.
+ *
+ * The query is against the **board's** container, named `board`,
+ * not the lane's. A lane in a three-up board is narrow and the
+ * Narrow View's single lane is wide, so the nearer container
+ * answers this question exactly backwards.
  */
 export const BoardCard = ({
   item,
@@ -346,12 +381,29 @@ export const BoardCard = ({
                     <Button
                       appearance="ghost"
                       intent="neutral"
-                      // `touch-none` so a touch drag is a drag
-                      // rather than a page scroll. Only the handle
-                      // needs it; the rest of the gesture is covered
-                      // by `preventDefault` on the captured
-                      // `pointermove`.
-                      className="touch-none opacity-70 group-hover:opacity-100"
+                      className={toClassName(
+                        // `touch-none` so a touch drag is a drag
+                        // rather than a page scroll. Only the handle
+                        // needs it; the rest of the gesture is
+                        // covered by `preventDefault` on the
+                        // captured `pointermove`.
+                        "touch-none opacity-70 group-hover:opacity-100",
+                        // `sizing` is a prop and cannot be two
+                        // things at once, so the button stays
+                        // `control`-sized — which is what the word
+                        // needs — and takes `icon` sizing back at
+                        // the width where the glyph is what is
+                        // showing. These are the two utilities
+                        // `ICON_CONTROL_SIZE_CLASS.sm` is, minus the
+                        // height `CONTROL_SIZE_CLASS.sm` already
+                        // set. Deterministic rather than a
+                        // specificity coin-flip: Tailwind orders a
+                        // variant after the utility it varies, which
+                        // is the same thing the lane's own
+                        // `cq-lg:p-0` relies on.
+                        moveIcon != null &&
+                          "@min-[48rem]/board:w-(--control-height-sm) @min-[48rem]/board:px-0",
+                      )}
                       onClick={() => {
                         setIsMenuVisible(
                           (isVisible) => !isVisible,
@@ -361,23 +413,53 @@ export const BoardCard = ({
                         onStartDrag?.(pointerEvent)
                       }}
                       size="sm"
-                      sizing={moveIcon ? "icon" : "control"}
+                      sizing="control"
                     >
-                      {moveIcon ?? "Move"}
+                      {moveIcon == null ? null : (
+                        // `hidden` first, so a browser with no
+                        // container-query support — and every test
+                        // renderer that does not lay out — keeps the
+                        // word, which is the affordance that works
+                        // everywhere.
+                        //
+                        // `contents` rather than `inline`: the glyph
+                        // stays a direct flex child of the button,
+                        // so it centres the way it did when it was
+                        // the button's only content.
+                        <span
+                          aria-hidden="true"
+                          className="hidden @min-[48rem]/board:contents"
+                        >
+                          {moveIcon}
+                        </span>
+                      )}
+
+                      <span
+                        aria-hidden="true"
+                        className={toClassName(
+                          moveIcon != null &&
+                            "@min-[48rem]/board:hidden",
+                        )}
+                      >
+                        Move
+                      </span>
 
                       {/*
                        * Thirty controls all named "Move" is thirty
                        * indistinguishable buttons to a screen reader
                        * and to `getByRole("button", { name })`, so
                        * the accessible name says *which* card and
-                       * where it currently is. With an icon this is
-                       * the whole name; with the word it qualifies
-                       * it.
+                       * where it currently is.
+                       *
+                       * The whole name lives here, and both visible
+                       * affordances are `aria-hidden`, because which
+                       * of them is painted is a CSS answer that the
+                       * accessible name must not depend on — a
+                       * handle called "Move X" wide and "Move Move
+                       * X" narrow is one control with two names.
                        */}
                       <VisuallyHidden>
-                        {moveIcon
-                          ? `Move ${item.title}, currently in ${laneLabel}`
-                          : ` ${item.title}, currently in ${laneLabel}`}
+                        {`Move ${item.title}, currently in ${laneLabel}`}
                       </VisuallyHidden>
                     </Button>
                   }

package/src/Board/boardMoveHandleContainer.test.ts

@@ -0,0 +1,54 @@
+import { readFile } from "node:fs/promises"
+import { join } from "node:path"
+
+import { containerQuery } from "@charcuterie/tokens/src/scales.ts"
+import { expect, test } from "vitest"
+
+/**
+ * The move handle swaps its glyph for the word "Move" at the width
+ * where the lanes stop being side by side — and it has to be the
+ * SAME width the lanes themselves use, or there is a band where the
+ * board is one lane and the handle still teaches a drag.
+ *
+ * Two literals cannot be shared: a container query's threshold is
+ * resolved before custom properties exist, so
+ * `@container (min-inline-size: var(--cq-lg))` is invalid CSS and
+ * `48rem` has to be written out. The lanes get theirs from the
+ * generated `cq-lg` variant; the handle writes Tailwind's own
+ * `@min-[…]/board:`, because that is the only form that can name a
+ * container. This test is what keeps the two from drifting.
+ */
+const directory = import.meta.dirname
+
+test("the handle's own breakpoint is the scale's `cq-lg`, spelled out", async () => {
+  const source = await readFile(
+    join(directory, "BoardCard.tsx"),
+    "utf8",
+  )
+
+  const thresholds = [
+    ...source.matchAll(/@min-\[([^\]]+)\]\/board:/g),
+  ].map((match) => match[1])
+
+  // The mutation guard: a refactor that renames the variant would
+  // otherwise turn the assertion below into `[] === []`.
+  expect(thresholds.length).toBeGreaterThan(0)
+
+  expect([...new Set(thresholds)]).toEqual([
+    containerQuery.lg,
+  ])
+})
+
+/**
+ * The other half. A named query with no container of that name
+ * never matches anything — no error, no warning, and the handle
+ * silently keeps whichever affordance the base classes gave it.
+ */
+test("the board declares the `board` container the handle queries", async () => {
+  const source = await readFile(
+    join(directory, "Board.tsx"),
+    "utf8",
+  )
+
+  expect(source).toContain('"@container/board"')
+})

package/src/DeploymentUpdate/useDeploymentUpdate.ts

@@ -0,0 +1,143 @@
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from "react"
+
+/** Matches `@charcuterie/server`'s default build-marker URL. */
+export const DEFAULT_DEPLOYMENT_PATH =
+  "/__charcuterie/deployment"
+
+/** Matches `@charcuterie/server`'s default SSE URL. */
+export const DEFAULT_DEPLOYMENT_EVENTS_PATH =
+  "/__charcuterie/deployment/events"
+
+export type UseDeploymentUpdateOptions = {
+  deploymentPath?: string
+  deploymentEventsPath?: string
+  /** `0` disables polling. SSE is normally enough. */
+  pollIntervalMs?: number
+  /** Disable when an app calls `checkForUpdate` after its own SSE reconnects. */
+  isEventSourceEnabled?: boolean
+}
+
+export type DeploymentUpdate = {
+  isUpdateAvailable: boolean
+  /** Revalidate the marker now. Safe to call after an app SSE reconnects. */
+  checkForUpdate: () => Promise<boolean>
+  /** Reload after the user has saved or finished their current work. */
+  reload: () => void
+}
+
+const getBuildId = (value: unknown): string | undefined => {
+  if (
+    typeof value === "object" &&
+    value !== null &&
+    "buildId" in value &&
+    typeof value.buildId === "string"
+  ) {
+    return value.buildId
+  }
+  return undefined
+}
+
+/**
+ * Detects a replacement static SPA without taking control away from
+ * the app. It never reloads by itself: a tab can contain unsaved
+ * form state, so the app shows its own accessible update action and
+ * calls `reload` only when the user is ready.
+ *
+ * `createStaticHandler` supplies both endpoints by default. Existing
+ * app SSE can keep its one connection: set `isEventSourceEnabled` to
+ * `false`, then call `checkForUpdate` in its post-reconnect callback.
+ */
+export const useDeploymentUpdate = ({
+  deploymentEventsPath = DEFAULT_DEPLOYMENT_EVENTS_PATH,
+  deploymentPath = DEFAULT_DEPLOYMENT_PATH,
+  isEventSourceEnabled = true,
+  pollIntervalMs = 0,
+}: UseDeploymentUpdateOptions = {}): DeploymentUpdate => {
+  const buildIdRef = useRef<string | undefined>(undefined)
+  const [isUpdateAvailable, setIsUpdateAvailable] =
+    useState(false)
+
+  const acceptBuildId = useCallback(
+    (buildId: string): boolean => {
+      if (buildIdRef.current === undefined) {
+        buildIdRef.current = buildId
+        return false
+      }
+      if (buildIdRef.current === buildId) {
+        return false
+      }
+      setIsUpdateAvailable(true)
+      return true
+    },
+    [],
+  )
+
+  const checkForUpdate =
+    useCallback(async (): Promise<boolean> => {
+      const response = await globalThis.fetch(
+        deploymentPath,
+        {
+          cache: "no-store",
+          headers: { Accept: "application/json" },
+        },
+      )
+      if (!response.ok) {
+        return false
+      }
+      const buildId = getBuildId(await response.json())
+      return buildId === undefined
+        ? false
+        : acceptBuildId(buildId)
+    }, [acceptBuildId, deploymentPath])
+
+  useEffect(() => {
+    void checkForUpdate().catch(() => undefined)
+  }, [checkForUpdate])
+
+  useEffect(() => {
+    if (
+      !isEventSourceEnabled ||
+      typeof EventSource === "undefined"
+    ) {
+      return
+    }
+    const source = new EventSource(deploymentEventsPath)
+    const onDeployment = (event: MessageEvent<string>) => {
+      try {
+        const buildId = getBuildId(JSON.parse(event.data))
+        if (buildId !== undefined) {
+          acceptBuildId(buildId)
+        }
+      } catch {
+        // A malformed marker is not a reason to interrupt the tab.
+      }
+    }
+    source.addEventListener("deployment", onDeployment)
+    return () => source.close()
+  }, [
+    acceptBuildId,
+    deploymentEventsPath,
+    isEventSourceEnabled,
+  ])
+
+  useEffect(() => {
+    if (pollIntervalMs <= 0) {
+      return
+    }
+    const interval = globalThis.setInterval(() => {
+      void checkForUpdate().catch(() => undefined)
+    }, pollIntervalMs)
+    return () => globalThis.clearInterval(interval)
+  }, [checkForUpdate, pollIntervalMs])
+
+  return {
+    checkForUpdate,
+    isUpdateAvailable,
+    reload: () => globalThis.location.reload(),
+  }
+}