@charcuterie/ui 4.3.0 → 4.5.0

package/src/TimecodeInput/TimecodeInput.test.tsx

@@ -7,7 +7,8 @@ import { mountStory } from "../mountStory.testHelpers.ts"
 import { expectAgentDrivable } from "../testing/index.ts"
 import * as stories from "./TimecodeInput.stories.tsx"
 
-const { AllStates, Interactive } = composeStories(stories)
+const { AllStates, Interactive, Responsive } =
+  composeStories(stories)
 
 const mountInteractive = async () => {
   const mounted = await mountStory(Interactive)
@@ -40,9 +41,7 @@ test("a typed position is echoed in full, and does NOT commit until Enter", asyn
   // and the field says so in a live region before anything is
   // stored.
   await waitFor(() => {
-    expect(
-      canvas.getByText("00:01:30.000"),
-    ).toBeInTheDocument()
+    expect(canvas.getByText("00:01:30")).toBeInTheDocument()
   })
 
   await expect(
@@ -53,13 +52,13 @@ test("a typed position is echoed in full, and does NOT commit until Enter", asyn
 
   await waitFor(() => {
     expect(
-      canvas.getByText("Chosen: 00:01:30.000"),
+      canvas.getByText("Chosen: 00:01:30"),
     ).toBeInTheDocument()
   })
 
   // Committed in the one canonical spelling, so a re-read of the
   // field parses to the number that produced it.
-  await expect(single).toHaveValue("00:01:30.000")
+  await expect(single).toHaveValue("00:01:30")
 })
 
 test("an overflowed field is refused by name, and the typed text survives", async () => {
@@ -101,7 +100,7 @@ test("Escape puts the last committed value back", async () => {
 
   await userEvent.type(single, "90{Enter}")
 
-  await expect(single).toHaveValue("00:01:30.000")
+  await expect(single).toHaveValue("00:01:30")
 
   await userEvent.clear(single)
 
@@ -109,7 +108,7 @@ test("Escape puts the last committed value back", async () => {
 
   await userEvent.keyboard("{Escape}")
 
-  await expect(single).toHaveValue("00:01:30.000")
+  await expect(single).toHaveValue("00:01:30")
 })
 
 test("the arrows step by stepMs, and Shift multiplies that by ten", async () => {
@@ -123,24 +122,24 @@ test("the arrows step by stepMs, and Shift multiplies that by ten", async () =>
   // than a draft the echo is reporting on.
   await waitFor(() => {
     expect(
-      canvas.getByText("Chosen: 00:00:01.000"),
+      canvas.getByText("Chosen: 00:00:01"),
     ).toBeInTheDocument()
   })
 
   await userEvent.keyboard("{Shift>}{ArrowUp}{/Shift}")
 
-  await expect(single).toHaveValue("00:00:11.000")
+  await expect(single).toHaveValue("00:00:11")
 
   await userEvent.keyboard("{ArrowDown}")
 
-  await expect(single).toHaveValue("00:00:10.000")
+  await expect(single).toHaveValue("00:00:10")
 
   // The floor is the start of the media, not a negative position.
   await userEvent.keyboard(
     "{Shift>}{ArrowDown}{ArrowDown}{/Shift}",
   )
 
-  await expect(single).toHaveValue("00:00:00.000")
+  await expect(single).toHaveValue("00:00:00")
 })
 
 test("a position past the end of the media says so, then commits clamped", async () => {
@@ -152,13 +151,13 @@ test("a position past the end of the media says so, then commits clamped", async
 
   await waitFor(() => {
     expect(
-      canvas.getByText(/commits as 00:45:12\.000/),
+      canvas.getByText(/commits as 00:45:12/),
     ).toBeInTheDocument()
   })
 
   await userEvent.keyboard("{Enter}")
 
-  await expect(single).toHaveValue("00:45:12.000")
+  await expect(single).toHaveValue("00:45:12")
 })
 
 test("an inverted section swaps, rather than throwing away the boundary just typed", async () => {
@@ -167,14 +166,12 @@ test("an inverted section swaps, rather than throwing away the boundary just typ
 
   await userEvent.click(end)
 
-  // The seeded start is 00:05:00.000, so this end sits before it.
+  // The seeded start is 00:05:00, so this end sits before it.
   await userEvent.type(end, "1:00{Enter}")
 
   await waitFor(() => {
     expect(
-      canvas.getByText(
-        "Chosen: 00:01:00.000 to 00:05:00.000",
-      ),
+      canvas.getByText("Chosen: 00:01:00 to 00:05:00"),
     ).toBeInTheDocument()
   })
 
@@ -200,7 +197,7 @@ test("a zero-length section is refused by name, because it plays nothing", async
   // The start is untouched and the end is still open — nothing was
   // committed, and the text is still what was typed.
   await expect(
-    canvas.getByText("Chosen: 00:05:00.000 to the end"),
+    canvas.getByText("Chosen: 00:05:00 to the end"),
   ).toBeInTheDocument()
 
   await expect(end).toHaveValue("5:00")
@@ -217,9 +214,7 @@ test("both ends are independently optional, and clearing one leaves the other al
 
   await waitFor(() => {
     expect(
-      canvas.getByText(
-        "Chosen: 00:05:00.000 to 00:10:00.000",
-      ),
+      canvas.getByText("Chosen: 00:05:00 to 00:10:00"),
     ).toBeInTheDocument()
   })
 
@@ -231,9 +226,7 @@ test("both ends are independently optional, and clearing one leaves the other al
 
   await waitFor(() => {
     expect(
-      canvas.getByText(
-        "Chosen: the beginning to 00:10:00.000",
-      ),
+      canvas.getByText("Chosen: the beginning to 00:10:00"),
     ).toBeInTheDocument()
   })
 })
@@ -260,20 +253,250 @@ test("the four states of a section all render as values, not as half-finished in
   ).toHaveLength(2)
 
   await expect(
-    canvas.getByText("Chosen: 00:05:00.000 to the end"),
+    canvas.getByText("Chosen: 00:05:00 to the end"),
   ).toBeInTheDocument()
 
   await expect(
-    canvas.getByText(
-      "Chosen: the beginning to 00:05:00.000",
-    ),
+    canvas.getByText("Chosen: the beginning to 00:05:00"),
   ).toBeInTheDocument()
 
   await expect(
-    canvas.getByText(
-      "Chosen: 00:05:00.000 to 00:15:00.000",
-    ),
+    canvas.getByText("Chosen: 00:05:00 to 00:15:00"),
+  ).toBeInTheDocument()
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("the echo is a reading of the focused field, so it leaves with the focus", async () => {
+  const { canvas, single } = await mountInteractive()
+
+  await userEvent.click(single)
+
+  await userEvent.type(single, "90")
+
+  await waitFor(() => {
+    expect(canvas.getByText("00:01:30")).toBeInTheDocument()
+  })
+
+  // Tab commits and takes the focus away. What is left underneath an
+  // idle field would be an unlabelled timecode, which reads as a
+  // stray value rather than as a report on the field above it.
+  await userEvent.tab()
+
+  await waitFor(() => {
+    expect(
+      canvas.queryByText("00:01:30"),
+    ).not.toBeInTheDocument()
+  })
+
+  // The value itself is untouched by any of that: the line is a
+  // reading, not the state.
+  await expect(single).toHaveValue("00:01:30")
+
+  await expect(
+    canvas.getByText("Chosen: 00:01:30"),
+  ).toBeInTheDocument()
+})
+
+test("an unparsed text keeps its refusal after the focus leaves, because the control is still invalid", async () => {
+  const { canvas, canvasElement, single } =
+    await mountInteractive()
+
+  await userEvent.click(single)
+
+  await userEvent.type(single, "1:90")
+
+  await userEvent.tab()
+
+  // `aria-invalid` survives the blur, so the sentence that says why
+  // has to survive it too. An invalid control with no message is
+  // worse than the stray line the test above removes.
+  await expect(single).toHaveAttribute(
+    "aria-invalid",
+    "true",
+  )
+
+  await expect(
+    canvas.getByText(/A minute has 60 seconds/),
   ).toBeInTheDocument()
 
+  await expect(single).toHaveValue("1:90")
+
   await expectNoAxeViolations(canvasElement)
 })
+
+test("a zero-length refusal is written at the commit, so it survives the blur that wrote it", async () => {
+  const { canvas, canvasElement, end } =
+    await mountInteractive()
+
+  await userEvent.click(end)
+
+  // The seeded start is 00:05:00, so this end has no length. Blur is
+  // the commit here, which is the case that would have hidden the
+  // complaint the instant it was made.
+  await userEvent.type(end, "5:00")
+
+  await userEvent.tab()
+
+  await waitFor(() => {
+    expect(
+      canvas.getByText(/A section needs a length/),
+    ).toBeInTheDocument()
+  })
+
+  await expect(end).toHaveAttribute("aria-invalid", "true")
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * The container query, asserted rather than assumed — and the
+ * accessible name held identical across the two layouts it draws.
+ *
+ * The window never moves in this test. Each panel of the board is a
+ * fixed inline size around `--cq-sm`, which is the only honest way
+ * to exercise a query about the component's own box.
+ */
+test("the Narrow View stacks the two fields, and neither layout changes a control's name", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Responsive)
+
+  const narrowStart = expectAgentDrivable(canvas, {
+    name: "Section 15rem start",
+    role: "textbox",
+  })
+
+  const wideStart = expectAgentDrivable(canvas, {
+    name: "Section 34rem start",
+    role: "textbox",
+  })
+
+  expectAgentDrivable(canvas, {
+    name: "Section 15rem end",
+    role: "textbox",
+  })
+
+  expectAgentDrivable(canvas, {
+    name: "Section 34rem end",
+    role: "textbox",
+  })
+
+  const narrowRow = narrowStart.parentElement
+    ?.parentElement as HTMLElement
+
+  const wideRow = wideStart.parentElement
+    ?.parentElement as HTMLElement
+
+  await expect(
+    globalThis.getComputedStyle(narrowRow).flexDirection,
+  ).toBe("column")
+
+  await expect(
+    globalThis.getComputedStyle(wideRow).flexDirection,
+  ).toBe("row")
+
+  const [
+    narrowStartCaption,
+    narrowJoiner,
+    narrowEndCaption,
+  ] = Array.from(
+    narrowRow.querySelectorAll<HTMLElement>(
+      ":scope > * > span, :scope > span",
+    ),
+  )
+
+  const [wideStartCaption, wideJoiner, wideEndCaption] =
+    Array.from(
+      wideRow.querySelectorAll<HTMLElement>(
+        ":scope > * > span, :scope > span",
+      ),
+    )
+
+  // Narrow: two captions, no joining word.
+  await expect(narrowStartCaption).toHaveTextContent(
+    "Start",
+  )
+
+  await expect(narrowEndCaption).toHaveTextContent("End")
+
+  await expect(
+    globalThis.getComputedStyle(
+      narrowStartCaption as HTMLElement,
+    ).display,
+  ).not.toBe("none")
+
+  await expect(
+    globalThis.getComputedStyle(narrowJoiner as HTMLElement)
+      .display,
+  ).toBe("none")
+
+  // Wide: the joining word, no captions.
+  await expect(wideJoiner).toHaveTextContent("to")
+
+  await expect(
+    globalThis.getComputedStyle(wideJoiner as HTMLElement)
+      .display,
+  ).not.toBe("none")
+
+  await expect(
+    globalThis.getComputedStyle(
+      wideStartCaption as HTMLElement,
+    ).display,
+  ).toBe("none")
+
+  await expect(
+    globalThis.getComputedStyle(
+      wideEndCaption as HTMLElement,
+    ).display,
+  ).toBe("none")
+
+  // Every one of them is for the eye. A real `<label>` would name the
+  // start control a second time and fight the `id` a `Field` clones
+  // onto it, so nothing here is named "Start" or "End".
+  for (const caption of [
+    narrowStartCaption,
+    narrowJoiner,
+    narrowEndCaption,
+    wideStartCaption,
+    wideJoiner,
+    wideEndCaption,
+  ]) {
+    await expect(caption).toHaveAttribute(
+      "aria-hidden",
+      "true",
+    )
+  }
+
+  await expect(
+    canvas.queryAllByRole("textbox", {
+      name: /^(Start|End)$/,
+    }),
+  ).toHaveLength(0)
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("milliseconds are optional to read as well as to type", async () => {
+  const { canvas, single } = await mountInteractive()
+
+  await userEvent.click(single)
+
+  // No fraction typed, so no fraction written back. You write 3, not
+  // 3.000.
+  await userEvent.type(single, "10:00{Enter}")
+
+  await expect(single).toHaveValue("00:10:00")
+
+  await waitFor(() => {
+    expect(
+      canvas.getByText("Chosen: 00:10:00"),
+    ).toBeInTheDocument()
+  })
+
+  await userEvent.clear(single)
+
+  // A real fraction still prints in full, padded on the right.
+  await userEvent.type(single, "10:00.25{Enter}")
+
+  await expect(single).toHaveValue("00:10:00.250")
+})

package/src/TimecodeInput/TimecodeInput.tsx

@@ -64,6 +64,21 @@ const INPUT_CLASS =
 
 type Endpoint = "end" | "start"
 
+/**
+ * How this field prints, everywhere it prints — the text it writes
+ * back on commit, and the echo that reports what a draft resolves
+ * to. The two have to agree, so they read the same constant.
+ *
+ * `"auto"` rather than the exported default of three digits: a
+ * person who types `1:01:00` and tabs away did not ask for
+ * `01:01:00.000`, any more than typing `3` asks for `3.000`. A real
+ * fraction still prints in full, and the grammar reads both back to
+ * the same number.
+ */
+const DISPLAY_FORMAT = {
+  millisecondDigits: "auto",
+} as const
+
 const toSeededRange = (
   valueMs: number | TimecodeRange | undefined,
 ): TimecodeRange =>
@@ -117,6 +132,23 @@ const toSeededRange = (
  * discard the boundary just typed. A **zero-length** section is
  * refused by name: it plays nothing, so swapping would hide a typo
  * behind a window that silently does not exist.
+ *
+ * ### The Narrow View stacks the two fields
+ *
+ * Below `--cq-sm` a section is two fields one above the other, under
+ * the captions "Start" and "End"; above it, the row with `to`
+ * between them. It is a **container** query, so a 390px modal on a
+ * 2560px monitor gets the stacked form that a window breakpoint
+ * would have denied it. The captions are `aria-hidden`, so the
+ * accessible name of each control is the same in both layouts.
+ *
+ * ### Milliseconds are optional to read as well as to type
+ *
+ * The grammar has always accepted `1:01:00`. The field now writes it
+ * back as `01:01:00` rather than as `01:01:00.000`, through
+ * `formatTimecode`'s `millisecondDigits: "auto"`, because a fraction
+ * nobody typed is not information. `1:01:00.5` still commits as
+ * `01:01:00.500`.
  */
 export const TimecodeInput = ({
   className,
@@ -149,16 +181,29 @@ export const TimecodeInput = ({
   const toDisplayText = (milliseconds: null | number) =>
     milliseconds === null
       ? ""
-      : formatTimecode(milliseconds)
+      : formatTimecode(milliseconds, DISPLAY_FORMAT)
 
   const [texts, setTexts] = useState({
     end: toDisplayText(seededRange.end),
     start: toDisplayText(seededRange.start),
   })
 
+  /**
+   * Which endpoint the keyboard steps and the echo belong to. It
+   * SURVIVES blur, deliberately: a refusal has to keep naming the
+   * field it is about after the focus has gone somewhere else.
+   */
   const [activeEndpoint, setActiveEndpoint] =
     useState<Endpoint>("start")
 
+  /**
+   * Whether a field of this control holds the focus. Separate from
+   * `activeEndpoint` because the two answer different questions —
+   * *which* endpoint, and *whether anybody is typing* — and only the
+   * second one may hide the echo.
+   */
+  const [isFocused, setIsFocused] = useState(false)
+
   /**
    * A refusal the grammar cannot see, because it is about the
    * **pair** rather than about either text: a zero-length section.
@@ -355,14 +400,55 @@ export const TimecodeInput = ({
       : parsed.kind === "empty" || clampedPreview === null
         ? ""
         : clampedPreview === parsed.milliseconds
-          ? formatTimecode(parsed.milliseconds)
-          : `${formatTimecode(parsed.milliseconds)} is outside the media, so it commits as ${formatTimecode(clampedPreview)}.`
+          ? formatTimecode(
+              parsed.milliseconds,
+              DISPLAY_FORMAT,
+            )
+          : `${formatTimecode(parsed.milliseconds, DISPLAY_FORMAT)} is outside the media, so it commits as ${formatTimecode(clampedPreview, DISPLAY_FORMAT)}.`
 
-  const echoText = rangeRefusal ?? parsedEcho
+  /**
+   * A restatement is a reading of the field above it, so it leaves
+   * with the focus. Left up, an unlabelled `00:05:00` under an idle
+   * control reads as a stray value rather than as a report on one.
+   *
+   * A REFUSAL stays, and both kinds do. `rangeRefusal` is set on
+   * commit — which is exactly blur — so a rule that hid it on blur
+   * would mean it was never readable at all. And an unparsed text
+   * keeps `aria-invalid` on the control, so the sentence saying why
+   * has to stay with it: an invalid field with no message is worse
+   * than the stray line this removes.
+   *
+   * Emptying a live region announces nothing, so the blur costs a
+   * screen reader no chatter.
+   */
+  const echoText =
+    rangeRefusal ??
+    (isFocused || parsed.kind === "unparsed"
+      ? parsedEcho
+      : "")
 
   const isInvalid =
     rangeRefusal !== null || parsed.kind === "unparsed"
 
+  /**
+   * The Narrow View's caption over one field.
+   *
+   * Presentational, and `aria-hidden` for the same reason the word
+   * `to` is: each input already carries
+   * `aria-label="<label> <endpoint>"`, and a real `<label>` here
+   * would name the start control a second time and fight the `id` a
+   * `Field` above clones onto it. The eye gets a caption; the
+   * accessible name is the same in both layouts.
+   */
+  const renderCaption = (text: string) => (
+    <span
+      aria-hidden="true"
+      className="text-content-secondary text-sm cq-sm:hidden"
+    >
+      {text}
+    </span>
+  )
+
   const renderInput = (endpoint: Endpoint) => {
     const ownProps = {
       "aria-describedby": echoId,
@@ -398,6 +484,8 @@ export const TimecodeInput = ({
       // rather than by a keyboard the field cannot choose.
       inputMode: "numeric" as const,
       onBlur: () => {
+        setIsFocused(false)
+
         commitText(endpoint)
       },
       onChange: (changeEvent: {
@@ -417,6 +505,8 @@ export const TimecodeInput = ({
         }))
       },
       onFocus: () => {
+        setIsFocused(true)
+
         setActiveEndpoint(endpoint)
       },
       onKeyDown: (
@@ -444,28 +534,49 @@ export const TimecodeInput = ({
   }
 
   return (
+    // `@container` here, not on a wrapper: the box a caller sized is
+    // the box that either has room for two timecodes side by side or
+    // does not. A viewport breakpoint reads that backwards — a 390px
+    // modal on a 2560px monitor is a Wide View by the window and a
+    // Narrow View by every measurement that matters. The cost is the
+    // `contain: inline-size` that rides along with it, so this field
+    // takes its width from its parent rather than from its content:
+    // give it a definite inline size, as every container-query
+    // component in this library needs.
     <div
       className={toClassName(
-        "flex flex-col gap-1",
+        "@container flex flex-col gap-1",
         className,
       )}
     >
-      <div className="flex items-center gap-2">
-        {renderInput("start")}
-
-        {isRange ? (
-          <>
-            <span
-              aria-hidden="true"
-              className="shrink-0 text-content-secondary text-sm"
-            >
-              to
-            </span>
+      {isRange ? (
+        // Below `--cq-sm` the two fields STACK, each under a caption
+        // of its own, because `hh:mm:ss.mmm` twice and the word
+        // between them fills a phone-width modal edge to edge with
+        // no slack left. Above it, the row is unchanged.
+        <div className="flex flex-col gap-2 cq-sm:flex-row cq-sm:items-center cq-sm:gap-2">
+          <div className="flex min-w-0 flex-col gap-1 cq-sm:flex-1">
+            {renderCaption("Start")}
+
+            {renderInput("start")}
+          </div>
+
+          <span
+            aria-hidden="true"
+            className="hidden shrink-0 text-content-secondary text-sm cq-sm:inline"
+          >
+            to
+          </span>
+
+          <div className="flex min-w-0 flex-col gap-1 cq-sm:flex-1">
+            {renderCaption("End")}
 
             {renderInput("end")}
-          </>
-        ) : null}
-      </div>
+          </div>
+        </div>
+      ) : (
+        renderInput("start")
+      )}
 
       {/*
         The anti-silent-guess mechanism, and the reason this field is

package/src/TimecodeInput/timecode.test.ts

@@ -210,6 +210,49 @@ test("millisecondDigits truncates rather than rounding, because a position is no
   ).toBe("00:00:01")
 })
 
+test('millisecondDigits "auto" prints the fraction only when there is one', () => {
+  // The complaint this answers: typing `1:01:00` and tabbing away
+  // rewrote the field to `01:01:00.000`. You write 3, not 3.000.
+  expect(
+    formatTimecode(3_660_000, {
+      millisecondDigits: "auto",
+    }),
+  ).toBe("01:01:00")
+
+  // A real fraction still prints in full, at the same three digits.
+  expect(
+    formatTimecode(3_660_500, {
+      millisecondDigits: "auto",
+    }),
+  ).toBe("01:01:00.500")
+
+  expect(
+    formatTimecode(1, { millisecondDigits: "auto" }),
+  ).toBe("00:00:00.001")
+
+  expect(
+    formatTimecode(0, { millisecondDigits: "auto" }),
+  ).toBe("00:00:00")
+
+  // Both spellings read back to the number that produced them, so
+  // the shorter one costs the round trip nothing.
+  expect(parsedMilliseconds("01:01:00")).toBe(3_660_000)
+  expect(parsedMilliseconds("01:01:00.500")).toBe(3_660_500)
+
+  // It composes with the other option rather than replacing it.
+  expect(
+    formatTimecode(90_000, {
+      isHoursShown: false,
+      millisecondDigits: "auto",
+    }),
+  ).toBe("01:30")
+})
+
+test("the DEFAULT is still three digits, because a published export is read by callers this change never saw", () => {
+  expect(formatTimecode(3_660_000)).toBe("01:01:00.000")
+  expect(formatTimecode(90_000)).toBe("00:01:30.000")
+})
+
 test("formatTimecode refuses to print a position that does not exist", () => {
   expect(formatTimecode(-5_000)).toBe("00:00:00.000")
   expect(formatTimecode(Number.NaN)).toBe("00:00:00.000")