@charcuterie/ui 4.2.1 → 4.4.0

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

package/src/TimecodeInput/timecode.ts

@@ -90,8 +90,17 @@ export type FormatTimecodeOptions = {
    * unchanged because the largest field present is unbounded.
    */
   isHoursShown?: boolean
-  /** `0` through `3`. `0` drops the fraction and its separator. */
-  millisecondDigits?: number
+  /**
+   * `0` through `3`. `0` drops the fraction and its separator.
+   *
+   * `"auto"` prints the fraction only when there is one to print: a
+   * whole number of seconds comes back as `01:01:00`, and half a
+   * second more comes back as `01:01:00.500`. It is how a decimal
+   * number is written everywhere else — you write `3`, not `3.000` —
+   * and the grammar reads both spellings back to the number that
+   * produced them, because its fraction is optional.
+   */
+  millisecondDigits?: "auto" | number
 }
 
 const padTwo = (value: number) =>
@@ -105,12 +114,16 @@ const padTwo = (value: number) =>
  * because it has not reached second 2 yet. Rounding would print a
  * seek point the media has not played.
  *
- * The default is the canonical `hh:mm:ss.mmm`, and that is what the
- * field writes back on commit. One spelling means a re-read of the
- * field parses to the number that produced it, and a screenshot of
- * the same value is the same picture — neither of which is true of
- * the fleet's five printers, three of which hide the hour and two of
- * which do not pad the minute.
+ * The default is the canonical `hh:mm:ss.mmm`. `TimecodeInput` asks
+ * for `millisecondDigits: "auto"` instead, so a whole second is
+ * written back as `01:01:00` rather than as `01:01:00.000` — a
+ * person who typed no fraction did not ask for one, and both
+ * spellings re-read to the number that produced them.
+ *
+ * Either way it is ONE spelling per value, which is what the fleet's
+ * five printers never were: three of them hide the hour and two do
+ * not pad the minute, so the same position is a different picture in
+ * each app.
  */
 export const formatTimecode = (
   milliseconds: number,
@@ -123,10 +136,15 @@ export const formatTimecode = (
     ? Math.max(0, Math.floor(milliseconds))
     : 0
 
-  const digits = Math.min(
-    3,
-    Math.max(0, Math.floor(millisecondDigits)),
-  )
+  const digits =
+    millisecondDigits === "auto"
+      ? total % MILLISECONDS_PER_SECOND === 0
+        ? 0
+        : 3
+      : Math.min(
+          3,
+          Math.max(0, Math.floor(millisecondDigits)),
+        )
 
   const hours = isHoursShown
     ? Math.floor(total / MILLISECONDS_PER_HOUR)

package/src/sourceRules.test.ts

@@ -251,6 +251,13 @@ test("a container-query component is never storied in a shrink-to-fit cell", ()
     // measured in Docket, before any of the steps contained
     // anything.
     "Stepper",
+    // `TimecodeInput` queries its own box to decide whether a section
+    // is `[start] to [end]` in a row or two captioned fields stacked.
+    // The width that decides it is a modal's, not a window's: the
+    // report came from a 390px dialog, and the same dialog on a
+    // 2560px monitor is the Wide View by every media query and the
+    // Narrow View by the only measurement that matters.
+    "TimecodeInput",
   ])
 
   // `StoryCell`s are never nested, so the lazy match really does