@charcuterie/ui 3.33.0 → 3.34.0

package/src/TimecodeInput/TimecodeInput.mdx

@@ -0,0 +1,155 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as TimecodeInputStories from "./TimecodeInput.stories";
+
+<Meta of={TimecodeInputStories} />
+
+# TimecodeInput
+
+A text field for a position in a piece of media — `hh:mm:ss.mmm` — with an `isRange` mode
+for a section of a file. The consumer that shaped it is **QueuePilot**, which plays only a
+chosen part of a video
+([decision](../../../../docs/decisions/2026-09-01-a-timecode-is-milliseconds-and-a-section-is-a-mode.md)).
+
+<Canvas of={TimecodeInputStories.Default} />
+
+## Props
+
+<Controls />
+
+## The value is milliseconds, and the props say so
+
+`onChange` reports an integer count of milliseconds from the start of the file. Not a
+`Date`, not a clock time, not a string. A media position is a **duration**, the only
+arithmetic anybody does with it is subtraction, and a number is the type that supports it.
+
+Every prop carrying one keeps the `Ms` suffix — `durationMs`, `maxValueMs`, `minValueMs`,
+`stepMs`, `valueMs` — because a duration's unit is genuinely ambiguous and this fleet has
+both seconds and milliseconds in use. A `*At` timestamp is the opposite case and takes no
+suffix.
+
+```tsx
+<TimecodeInput
+  durationMs={file.durationMs}      // the default maximum
+  label="Start at"
+  onChange={(value) => { setStartMs(value) }}   // number | null
+  valueMs={startMs}                 // seeds; Charcuterie owns it from then on
+/>
+```
+
+## Why this is not `<input type="time">`
+
+Two reasons, and neither is taste.
+
+A `time` input's value is a wall-clock `HH:MM` string capped at 24 hours, its smallest step
+is a second unless `step` is fractional, and it has no way to say "1.5 hours into a file" as
+a duration rather than as half past one. A clip boundary is milliseconds; the platform
+control cannot carry them.
+
+And it is painted by the operating system, out of `::-webkit-datetime-edit-*`
+pseudo-elements no token reaches inside — the same mechanism that deprecated the native
+`Select` and that kept `Slider` off `<input type="range">`.
+
+## Typing is the whole interface, so nothing guesses in silence
+
+| Typed | Resolves to |
+| --- | --- |
+| `90` | `00:01:30.000` — a bare number is **seconds** |
+| `1:30` | `00:01:30.000` |
+| `90:00` | `01:30:00.000` — the largest field present is unbounded |
+| `1:02:03` | `01:02:03.000` |
+| `1:02:03.500`, `1:02:03,500` | `01:02:03.500` |
+| `+90` | `00:01:30.000` — a leading `+` is tolerated |
+
+Three mechanisms keep a grammar that permissive from being dangerous:
+
+1. **The grammar is ordered and total.** Each rule is anchored on the *whole* input, the
+   first match wins, and no match is a stated failure. `1:` is not one minute.
+2. **An overflow is a failure with a name, not a carry.** `1:90` comes back as *A minute
+   has 60 seconds, so "90" is not a seconds field. Type 02:30 to carry it, or 90 to mean 90
+   seconds.* Both legal spellings are offered and neither is taken. Carrying it silently
+   moves the position by a whole minute, which is the `1:60` trap mux-magic wrote down in
+   2023.
+3. **Nothing commits without an echo.** The resolved position is rendered in full underneath
+   the field, in a `role="status"` live region wired into the input's `aria-describedby`.
+   Commit is Enter or blur; a keystroke never commits.
+
+**The largest field present is unbounded; every smaller one is 0–59.** That one sentence is
+every bound in the grammar. It is also why a bare number is seconds: seconds is the smallest
+unit the field prints, so the reading that needs no explanation is the one where the typist
+appended nothing.
+
+Refused by name: a negative, a seconds or minutes field of 60 or more with a larger field
+beside it, more than three colon-separated parts, a fraction longer than three digits, and
+anything the accepting rules do not match. A refused value leaves the text **exactly as
+typed**, marks the field invalid and says why.
+
+<Canvas of={TimecodeInputStories.AllVariants} />
+
+## A section is `isRange`, and both of its ends are optional
+
+`{ end, start }` has four real states, not three plus an error:
+
+| `start` | `end` | Means |
+| --- | --- | --- |
+| `null` | `null` | no window at all |
+| set | `null` | from here to the end of the media |
+| `null` | set | from the beginning, stopping here |
+| set | set | the window between them |
+
+So there is no `isEndOpen` prop — `null` already says it — and clearing one end never
+touches the other. An open start is the **absence of a choice**, not zero, which is why a
+half-open section is clamped but never compared.
+
+Picking an end before the start **swaps**, following `DatePicker`: throwing the pair away
+would discard the boundary just typed. An end **equal** to the start is **refused** by name,
+which is where this parts company with a date range: a zero-length section plays nothing, so
+swapping it would hide a typo behind a window that silently does not exist.
+
+There is no `error` prop. `Field` and `FieldGroup` own the semantic error; this component
+owns only the echo.
+
+<Canvas of={TimecodeInputStories.AllStates} />
+
+## Keyboard
+
+| Key | Does |
+| --- | --- |
+| Enter | commits the typed text |
+| Tab / blur | commits the typed text |
+| Escape | puts the last committed value back |
+| ArrowUp / ArrowDown | steps by `stepMs` (default 1000) and **commits** |
+| Shift + ArrowUp / ArrowDown | steps by ten times `stepMs` |
+
+A step commits, and that is not an exception to "a keystroke never commits" — it is the
+other side of it. Typing is a draft the echo reports on; a step is a whole gesture on a
+value that already exists, the same act as clicking a day in `DatePicker`'s calendar. A
+stepper that needed Enter afterwards is a stepper nobody presses twice.
+
+The control keeps the plain `textbox` role. It is **not** a `role="spinbutton"`: that role
+promises an `aria-valuenow`, and this field has no value at all while it is empty or while
+its text is refused — which are exactly the states the echo exists for. A spinbutton with no
+value is a widget that under-reports itself to a screen reader in its two most important
+states.
+
+<Canvas of={TimecodeInputStories.Responsive} />
+
+## The formatter is exported, because the fleet writes it repeatedly
+
+`formatTimecode`, `parseTimecodeInput` and `clampTimecode` come out of the barrel. The
+printing half is written five times across the fleet — queuepilot's `clock` and `toClock`,
+castkit's `formatTime`, and mux-magic's two modal formatters — each with its own answer to
+whether the hour is shown and whether the minute is padded. A read-only surface should call
+the exported one rather than spell a sixth.
+
+```ts
+formatTimecode(3_723_500)                            // "01:02:03.500"
+formatTimecode(90_000, { isHoursShown: false })      // "01:30.000"
+formatTimecode(1_999, { millisecondDigits: 0 })      // "00:00:01" — truncates
+```
+
+The default is the canonical `hh:mm:ss.mmm`, and it 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.
+
+<Canvas of={TimecodeInputStories.Interactive} />

package/src/TimecodeInput/TimecodeInput.stories.tsx

@@ -0,0 +1,304 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import type { ReactNode } from "react"
+import { useState } from "react"
+
+import { controlSizeArgType } from "../argTypes.storyHelpers.ts"
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import { Field } from "../Field/Field.tsx"
+import { TimecodeInput } from "./TimecodeInput.tsx"
+import type { TimecodeRange } from "./timecode.ts"
+import { formatTimecode } from "./timecode.ts"
+
+/**
+ * A made-up 45 minute 12 second file, so every demo reads the same
+ * numbers and a screenshot of one is the same picture next week.
+ */
+const DURATION_MS = 2_712_000
+
+const describeValue = (
+  value: null | number | TimecodeRange,
+) => {
+  if (value === null) {
+    return "—"
+  }
+
+  if (typeof value === "number") {
+    return formatTimecode(value)
+  }
+
+  // A section with neither end set is the same absence `onChange`
+  // reports as `null`, so the demo reads it the same way.
+  if (value.end === null && value.start === null) {
+    return "—"
+  }
+
+  return `${value.start === null ? "the beginning" : formatTimecode(value.start)} to ${value.end === null ? "the end" : formatTimecode(value.end)}`
+}
+
+const meta = {
+  title: "Components/Controls/TimecodeInput",
+  component: TimecodeInput,
+  args: {
+    durationMs: DURATION_MS,
+    isDisabled: false,
+    isRange: false,
+    label: "Start at",
+    size: "md",
+    stepMs: 1_000,
+  },
+  argTypes: {
+    size: controlSizeArgType,
+  },
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof TimecodeInput>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+const TimecodeHarness = ({
+  ...inputProps
+}: {
+  durationMs?: number
+  isDisabled?: boolean
+  isRange?: boolean
+  label: string
+  maxValueMs?: number
+  minValueMs?: number
+  stepMs?: number
+  valueMs?: number | TimecodeRange
+}): ReactNode => {
+  const [chosen, setChosen] = useState<
+    null | number | TimecodeRange
+  >(inputProps.valueMs ?? null)
+
+  return (
+    <div className="flex flex-col gap-1">
+      <TimecodeInput
+        {...inputProps}
+        durationMs={inputProps.durationMs ?? DURATION_MS}
+        onChange={setChosen}
+      />
+
+      <p className="text-content-muted text-xs">
+        Chosen: {describeValue(chosen)}
+      </p>
+    </div>
+  )
+}
+
+/**
+ * The field, empty. Type a position and the line underneath resolves
+ * it before anything commits — `90` is ninety seconds, `1:30` is the
+ * same position spelled the other way, `1:02:03.500` is the full
+ * form. Enter or blur commits; Escape puts the last value back.
+ */
+export const Default: Story = {
+  args: { label: "Start at" },
+  render: () => <TimecodeHarness label="Start at" />,
+}
+
+/**
+ * Single and section, a bounded window, a coarse step, and the field
+ * inside a `Field`.
+ *
+ * `isRange` is a **mode**, not a sibling component — the same call
+ * `DatePicker` made, and for the same reason: a section has no ARIA
+ * role of its own to be named after.
+ */
+export const AllVariants: Story = {
+  args: { label: "Start at" },
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell align="stretch" label="single (default)">
+        <TimecodeHarness label="Start at" />
+      </StoryCell>
+
+      <StoryCell align="stretch" label="isRange">
+        <TimecodeHarness isRange label="Play section" />
+      </StoryCell>
+
+      <StoryCell
+        align="stretch"
+        label="minValueMs / maxValueMs"
+      >
+        <TimecodeHarness
+          label="Skip the recap until"
+          maxValueMs={180_000}
+          minValueMs={30_000}
+        />
+      </StoryCell>
+
+      <StoryCell align="stretch" label="stepMs={60000}">
+        <TimecodeHarness
+          label="Chapter mark"
+          stepMs={60_000}
+          valueMs={600_000}
+        />
+      </StoryCell>
+
+      <StoryCell align="stretch" label="inside a Field">
+        <Field
+          description="Anything typeable: 90, 1:30, 1:02:03.500."
+          label="Resume from"
+        >
+          <TimecodeInput
+            durationMs={DURATION_MS}
+            label="Resume from"
+          />
+        </Field>
+      </StoryCell>
+
+      <StoryCell align="stretch" label='size="lg"'>
+        <TimecodeInput
+          durationMs={DURATION_MS}
+          label="Large"
+          size="lg"
+          valueMs={62_500}
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * Empty, filled, disabled — and the four states a section really
+ * has. Both ends are independently optional, so "from here to the
+ * end" and "from the beginning, stopping here" are values rather
+ * than half-finished input.
+ */
+export const AllStates: Story = {
+  args: { label: "Start at" },
+  render: () => (
+    <StorySection title="States">
+      <StoryGrid columns={2}>
+        <StoryCell align="stretch" label="empty">
+          <TimecodeHarness label="Empty" />
+        </StoryCell>
+
+        <StoryCell align="stretch" label="filled">
+          <TimecodeHarness
+            label="Filled"
+            valueMs={62_500}
+          />
+        </StoryCell>
+
+        <StoryCell align="stretch" label="isDisabled">
+          <TimecodeHarness
+            isDisabled
+            label="Locked"
+            valueMs={62_500}
+          />
+        </StoryCell>
+
+        <StoryCell
+          align="stretch"
+          label="section: no window"
+        >
+          <TimecodeHarness
+            isRange
+            label="No window"
+            valueMs={{ end: null, start: null }}
+          />
+        </StoryCell>
+
+        <StoryCell
+          align="stretch"
+          label="section: open end"
+        >
+          <TimecodeHarness
+            isRange
+            label="From here on"
+            valueMs={{ end: null, start: 300_000 }}
+          />
+        </StoryCell>
+
+        <StoryCell
+          align="stretch"
+          label="section: open start"
+        >
+          <TimecodeHarness
+            isRange
+            label="Up to here"
+            valueMs={{ end: 300_000, start: null }}
+          />
+        </StoryCell>
+
+        <StoryCell align="stretch" label="section: both">
+          <TimecodeHarness
+            isRange
+            label="Between"
+            valueMs={{ end: 900_000, start: 300_000 }}
+          />
+        </StoryCell>
+
+        <StoryCell
+          align="stretch"
+          label="error (type “1:90”)"
+        >
+          <Field
+            error="Pick a position the field can read."
+            label="Refused"
+          >
+            <TimecodeInput
+              durationMs={DURATION_MS}
+              label="Refused"
+            />
+          </Field>
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * The field at three container widths. Two inputs and a word between
+ * them is the layout that runs out of room first, so the section
+ * mode is the one worth looking at narrow.
+ */
+export const Responsive: Story = {
+  args: { label: "Start at" },
+  render: () => (
+    <ContainerBoard>
+      {(width) => (
+        <TimecodeInput
+          durationMs={DURATION_MS}
+          isRange
+          label={`Section ${width}`}
+        />
+      )}
+    </ContainerBoard>
+  ),
+}
+
+/**
+ * The complete keyboard path.
+ *
+ * Tab to the field and type — the line underneath resolves what you
+ * typed, and nothing has committed. Enter or Tab commits. Escape
+ * puts the last committed value back. ArrowUp and ArrowDown step by
+ * `stepMs`, and Shift multiplies that by ten.
+ *
+ * In the section below, type an end that sits before the start and
+ * the pair **swaps**; type an end equal to the start and it is
+ * **refused**, because a section with no length plays nothing.
+ */
+export const Interactive: Story = {
+  args: { label: "Start at" },
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <TimecodeHarness label="Start at" />
+
+      <TimecodeHarness
+        isRange
+        label="Play section"
+        valueMs={{ end: null, start: 300_000 }}
+      />
+    </div>
+  ),
+}