@multiplatform.one/forms 7.4.1 → 7.6.0

package/src/fields/DatePicker/parts.tsx

@@ -1,4 +1,5 @@
-import { Calendar, ChevronLeft, ChevronRight, X } from "@tamagui/lucide-icons-2";
+import { ChevronLeft, ChevronRight } from "@tamagui/lucide-icons-2";
+import { CalendarBlankIcon, ClockIcon, XIcon } from "@phosphor-icons/react";
 import {
   ensureFocusVisibleRing,
   formatAbsoluteDate,
@@ -173,9 +174,9 @@ export function isSameDay(a: Date | null | undefined, b: Date | null | undefined
  * square (binary-pointy, same contract as Switch/Radio). Inline style so a
  * consumer `circular` variant cannot expand past the nested-control box.
  */
-export function dayCellRadius(knobProps: {
-  pointy?: boolean;
-}): { style: { borderRadius: number } } {
+export function dayCellRadius(knobProps: { pointy?: boolean }): {
+  style: { borderRadius: number };
+} {
   return { style: { borderRadius: knobProps.pointy ? 0 : 9999 } };
 }
 
@@ -348,13 +349,19 @@ export function CalendarDayCell({
       aria-disabled={disabled || undefined}
       aria-pressed={selected || undefined}
       aria-current={today ? "date" : undefined}
-      cursor={disabled ? "default" : "pointer"}
+      cursor={disabled ? "not-allowed" : "pointer"}
       alignItems="center"
       justifyContent="center"
       onPress={() => {
         if (!disabled) onPress();
       }}
-      opacity={dimmed ? 0.45 : 1}
+      // Adjacent-month spill uses this file's 0.45 day-cell dim.
+      // Unavailable (min/max or multi-select cap) uses the 0.5 disabled
+      // idiom from the Today control and the trigger Box. Unavailable
+      // wins when both apply so an out-of-range adjacent day does not
+      // look like a pickable spill-over day. Bento paints this state
+      // identical to a choosable cell; we do not adopt that.
+      opacity={disabled ? 0.5 : dimmed ? 0.45 : 1}
       pointerEvents={disabled ? "none" : "auto"}
       backgroundColor={selected ? (selectedBackground ?? "$background") : "transparent"}
       theme={selected ? ("accent" as any) : undefined}
@@ -371,7 +378,7 @@ export function CalendarDayCell({
         ? {
             tabIndex: resolvedTabIndex,
             onKeyDown: ((e: { key?: string; preventDefault?: () => void }) => {
-              calendarKeyHandler(onPress)(e);
+              if (!disabled) calendarKeyHandler(onPress)(e);
               onKeyDown?.(e);
             }) as unknown as () => void,
           }
@@ -399,6 +406,7 @@ export function CalendarDays({
   skipEmptyWeeks,
   rangeStripe,
   onToday,
+  selectionCapped,
 }: {
   calendarData: CalendarData;
   minDate?: Date;
@@ -409,6 +417,8 @@ export function CalendarDays({
   skipEmptyWeeks?: boolean;
   rangeStripe?: (day: Date) => ReactNode;
   onToday?: () => void;
+  /** Multiple-mode is at `limit`; unselected cells look unavailable. */
+  selectionCapped?: boolean;
 }) {
   const { knobProps } = useCalendarKnobs();
   const { animation, animationKey } = useDateAnimation(
@@ -491,7 +501,7 @@ export function CalendarDays({
                 const isToday = isSameDay(calendarData.today, day);
                 const isOutOfRange =
                   (minDate != null && day < minDate) || (maxDate != null && day > maxDate);
-                const isDisabled = isOutOfRange;
+                const isDisabled = isOutOfRange || (!!selectionCapped && !isSelected(day));
                 const cell = (
                   <CalendarDayCell
                     day={day}
@@ -696,7 +706,9 @@ export function MonthGrid({ currentYear, selectedMonth, onSelectMonth }: MonthGr
               {...(isWeb
                 ? {
                     tabIndex: 0,
-                    onKeyDown: calendarKeyHandler(() => onSelectMonth(index)) as unknown as () => void,
+                    onKeyDown: calendarKeyHandler(() =>
+                      onSelectMonth(index),
+                    ) as unknown as () => void,
                   }
                 : { accessible: true })}
             >
@@ -762,13 +774,7 @@ export function YearGrid({
       </View>
 
       <AnimatePresence key={animationKey}>
-        <View
-          {...animation}
-          transition="quick"
-          flexDirection="row"
-          flexWrap="wrap"
-          width={px * 7}
-        >
+        <View {...animation} transition="quick" flexDirection="row" flexWrap="wrap" width={px * 7}>
           {years.map((year) => {
             const isSelected = year === selectedYear;
             return (
@@ -797,7 +803,9 @@ export function YearGrid({
                 {...(isWeb
                   ? {
                       tabIndex: 0,
-                      onKeyDown: calendarKeyHandler(() => onSelectYear(year)) as unknown as () => void,
+                      onKeyDown: calendarKeyHandler(() =>
+                        onSelectYear(year),
+                      ) as unknown as () => void,
                     }
                   : { accessible: true })}
               >
@@ -830,6 +838,8 @@ interface DatePickerInputTriggerProps {
   onButtonPress: () => void;
   error?: boolean;
   id?: string;
+  /** Empty-state glyph. Datetime uses calendar; TimePicker uses clock. */
+  glyph?: "calendar" | "clock";
   "aria-label"?: string;
   "aria-labelledby"?: string;
   "aria-describedby"?: string;
@@ -837,6 +847,32 @@ interface DatePickerInputTriggerProps {
   "aria-invalid"?: boolean;
 }
 
+export function DatePickerClearButton({
+  onReset,
+  disabled,
+  label,
+}: {
+  onReset: () => void;
+  disabled?: boolean;
+  label?: string;
+}) {
+  return (
+    <InputParts.Button
+      data-testid="date-picker-clear"
+      aria-label={label ?? t("Clear date")}
+      disabled={disabled}
+      onPress={(e) => {
+        e.stopPropagation();
+        onReset();
+      }}
+    >
+      <InputParts.Icon>
+        <XIcon />
+      </InputParts.Icon>
+    </InputParts.Button>
+  );
+}
+
 export function DatePickerInputTrigger({
   value,
   onButtonPress,
@@ -846,6 +882,7 @@ export function DatePickerInputTrigger({
   error,
   id,
   open,
+  glyph = "calendar",
   "aria-label": ariaLabel,
   "aria-labelledby": ariaLabelledBy,
   "aria-describedby": ariaDescribedBy,
@@ -866,6 +903,8 @@ export function DatePickerInputTrigger({
     }
   };
 
+  const Glyph = glyph === "clock" ? ClockIcon : CalendarBlankIcon;
+
   return (
     // LC-40: the disabled Box below is pointerEvents-none, so the cursor
     // affordance must ride this wrapper — the fragment's not-allowed never
@@ -901,6 +940,11 @@ export function DatePickerInputTrigger({
             }
           : undefined)}
       >
+        <InputParts.Section data-testid="date-picker-glyph">
+          <InputParts.Icon adornment="leading" color={formCommonColors.muted}>
+            <Glyph />
+          </InputParts.Icon>
+        </InputParts.Section>
         <InputParts.Section>
           <InputParts.Area
             readOnly
@@ -910,34 +954,21 @@ export function DatePickerInputTrigger({
             placeholder={placeholder}
             disabled={disabled}
             color={formCommonColors.text}
+            placeholderTextColor={formCommonColors.muted}
           />
         </InputParts.Section>
-        <InputParts.Section>
-          {value ? (
-            <InputParts.Button
-              aria-label={t("Clear date")}
-              onPress={(e) => {
-                e.stopPropagation();
-                onReset();
-              }}
-            >
-              <InputParts.Icon>
-                <X />
-              </InputParts.Icon>
-            </InputParts.Button>
-          ) : (
-            <InputParts.Icon adornment="trailing">
-              <Calendar />
-            </InputParts.Icon>
-          )}
-        </InputParts.Section>
+        {value && isWeb ? (
+          <InputParts.Section>
+            <DatePickerClearButton onReset={onReset} disabled={disabled} />
+          </InputParts.Section>
+        ) : null}
       </InputParts.Box>
     </View>
   );
 }
 
 // ---------------------------------------------------------------------------
-// DatePickerPopoverShell — Popover + Adapt/Sheet wrapper
+// DatePickerPopoverShell — FloatingPanel (sheet below OVERLAY_BREAKPOINT)
 // ---------------------------------------------------------------------------
 
 interface DatePickerPopoverShellProps {
@@ -950,6 +981,9 @@ interface DatePickerPopoverShellProps {
   popoverRef?: RefObject<any>;
   /** Native trigger announcement (name / current value / hint) — see FloatingPanel. */
   triggerA11y?: { label?: string; value?: string; hint?: string };
+  /** When set, native hosts render Clear outside the pointerEvents-none trigger. */
+  clearValue?: string;
+  onClear?: () => void;
 }
 
 export function DatePickerPopoverShell({
@@ -960,17 +994,22 @@ export function DatePickerPopoverShell({
   children,
   disabled,
   triggerA11y,
+  clearValue,
+  onClear,
 }: DatePickerPopoverShellProps) {
+  const nativeClear =
+    !isWeb && clearValue && onClear ? (
+      <DatePickerClearButton onReset={onClear} disabled={disabled} />
+    ) : undefined;
   return (
     <FloatingPanel
       open={open}
       onOpenChange={onOpenChange}
       trigger={trigger}
-      triggerEnd={triggerEnd}
+      triggerEnd={triggerEnd ?? nativeClear}
       disabled={disabled}
-      scrollable
       sizing="grow"
-      fitContent
+      widthMode="at-least-trigger"
       triggerA11y={triggerA11y}
     >
       {children}

package/src/fields/Duration/Duration.spec.tsx

@@ -1,7 +1,31 @@
-import { describe, expect, it } from "vitest";
+import { act, fireEvent } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { sizeRecipeForToken } from "@multiplatform.one/theme";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
 import { Form } from "../../Form";
-import { Duration, normalizeSeconds, parseDurationText, secondsToParts } from "./index";
+import { TableCellContext } from "../../shared/tableCellContext";
+import { getFieldHeight } from "../../shared/utils";
+import {
+  Duration,
+  durationSegmentWidth,
+  normalizeSeconds,
+  parseDurationText,
+  secondsToParts,
+} from "./index";
+
+function segmentValue(el: Element | null): string {
+  return el?.getAttribute("value") ?? (el as HTMLInputElement | null)?.value ?? "";
+}
+
+function segmentWidthPx(el: Element | null): number {
+  const input = el as HTMLElement | null;
+  if (!input) return 0;
+  const attr = input.getAttribute("width");
+  if (attr && /^\d+(\.\d+)?$/.test(attr)) return Number(attr);
+  const style = input.style.width;
+  if (style.endsWith("px")) return Number.parseFloat(style);
+  return Number.parseFloat(getComputedStyle(input).width) || 0;
+}
 
 describe("Duration", () => {
   describe("math", () => {
@@ -50,9 +74,14 @@ describe("Duration", () => {
       expect(result.findTextElement("In seconds")).toBeDefined();
     });
 
-    it("renders skeleton placeholder", () => {
+    it("renders skeleton at the control recipe height (LC-20)", () => {
       const result = renderWithProviders(<Duration label="Loading" name="l" skeleton />);
       expect(result.container.querySelector("input")).toBeNull();
+      const skeleton = result.container.querySelector("[data-duration-skeleton]") as HTMLElement;
+      expect(skeleton).toBeTruthy();
+      const expected = getFieldHeight("$4");
+      const height = skeletonWidthOrHeight(skeleton, "height");
+      expect(height).toBe(expected);
     });
 
     it("renders disabled state", () => {
@@ -62,12 +91,13 @@ describe("Duration", () => {
       expect(input?.getAttribute("tabindex")).toBe("-1");
     });
 
-    it("renders readOnly with formatted value", () => {
+    it("renders readOnly with formatted value and hides presets", () => {
       const result = renderWithProviders(
         <Duration label="ReadOnly" name="r" readOnly value={3661} />,
       );
       const input = result.container.querySelector("input");
       expect(input?.getAttribute("aria-readonly")).toBe("true");
+      expect(result.container.querySelector("[data-duration-presets]")).toBeNull();
     });
 
     it("supplies a default clock affordance", () => {
@@ -85,13 +115,13 @@ describe("Duration", () => {
     it("normalises a negative value in the hours segment", () => {
       const result = renderWithProviders(<Duration label="Neg" name="n" value={-100} />);
       const hours = result.container.querySelector('input[aria-label="Hours"]');
-      expect(hours?.getAttribute("value") ?? (hours as HTMLInputElement | null)?.value).toBe("0");
+      expect(segmentValue(hours)).toBe("0");
     });
 
     it("shows hours above 23 when hideDays", () => {
       const result = renderWithProviders(<Duration label="Long" name="l" value={100000} />);
       const hours = result.container.querySelector('input[aria-label="Hours"]');
-      expect(hours?.getAttribute("value") ?? (hours as HTMLInputElement | null)?.value).toBe("27");
+      expect(segmentValue(hours)).toBe("27");
     });
 
     it("shows a days segment when hideDays is false", () => {
@@ -102,6 +132,97 @@ describe("Duration", () => {
     });
   });
 
+  describe("design law", () => {
+    it("sizes segments from the size recipe (LC-75)", () => {
+      const small = renderWithProviders(<Duration label="S" size="$2" value={0} />);
+      const large = renderWithProviders(<Duration label="L" size="$6" value={0} />);
+      const sMin = small.container.querySelector('input[aria-label="Min"]');
+      const lMin = large.container.querySelector('input[aria-label="Min"]');
+      expect(segmentWidthPx(sMin)).toBe(durationSegmentWidth("$2", 2));
+      expect(segmentWidthPx(lMin)).toBe(durationSegmentWidth("$6", 2));
+      expect(segmentWidthPx(sMin)).toBeLessThan(segmentWidthPx(lMin));
+      const sHours = small.container.querySelector('input[aria-label="Hours"]');
+      expect(segmentWidthPx(sHours)).toBe(durationSegmentWidth("$2", 3));
+    });
+
+    it("clock glyph follows the icon recipe, not a hardcoded 16 (LC-75)", () => {
+      const small = renderWithProviders(<Duration label="S" size="$2" value={3600} />);
+      const large = renderWithProviders(<Duration label="L" size="$6" value={3600} />);
+      const sSvg = small.container.querySelector("svg");
+      const lSvg = large.container.querySelector("svg");
+      const sSize = Number(sSvg?.getAttribute("width") ?? sSvg?.getAttribute("height"));
+      const lSize = Number(lSvg?.getAttribute("width") ?? lSvg?.getAttribute("height"));
+      expect(sSize).toBe(sizeRecipeForToken("$2").iconSize);
+      expect(lSize).toBe(sizeRecipeForToken("$6").iconSize);
+      expect(sSize).not.toBe(lSize);
+    });
+
+    it("rings the outer box, never the inner segments (LC-71)", () => {
+      const result = renderWithProviders(<Duration label="Ring" value={3600} />);
+      const box = result.container.querySelector("[data-ring-target='box']") as HTMLElement;
+      const hours = result.container.querySelector('input[aria-label="Hours"]') as HTMLInputElement;
+      expect(box).toBeTruthy();
+      expect(box.className).toMatch(/mp-composite-ring/);
+      expect(box.contains(hours)).toBe(true);
+      expect(hours.className).toMatch(/mp-input-area/);
+    });
+
+    it("fires onChange with seconds (LC-14) from a preset", () => {
+      const onChange = vi.fn();
+      const result = renderWithProviders(<Duration label="P" value={0} onChange={onChange} />);
+      const chip = result.container.querySelector(
+        "[data-duration-preset], [data-duration-presets] button, [data-duration-presets] [role='button']",
+      );
+      expect(chip).toBeTruthy();
+      fireEvent.click(chip as HTMLElement);
+      expect(onChange).toHaveBeenCalled();
+      expect(typeof onChange.mock.calls[0]?.[0]).toBe("number");
+    });
+
+    it("arrow-up on hours commits via onChange", () => {
+      const onChange = vi.fn();
+      const result = renderWithProviders(<Duration label="A" value={3600} onChange={onChange} />);
+      const hours = result.container.querySelector('input[aria-label="Hours"]') as HTMLInputElement;
+      fireEvent.keyDown(hours, { key: "ArrowUp" });
+      expect(onChange).toHaveBeenCalledWith(7200);
+    });
+
+    it("normalises overflow minutes on blur", () => {
+      const onChange = vi.fn();
+      const result = renderWithProviders(<Duration label="O" value={0} onChange={onChange} />);
+      const minutes = result.container.querySelector('input[aria-label="Min"]') as HTMLInputElement;
+      act(() => {
+        fireEvent.change(minutes, { target: { value: "90" } });
+        fireEvent.blur(minutes);
+      });
+      expect(onChange).toHaveBeenCalledWith(5400);
+    });
+
+    it("pastes Frappe-style text into the whole value", () => {
+      const onChange = vi.fn();
+      const result = renderWithProviders(<Duration label="Paste" value={0} onChange={onChange} />);
+      const hours = result.container.querySelector('input[aria-label="Hours"]') as HTMLInputElement;
+      fireEvent.paste(hours, {
+        clipboardData: { getData: () => "1h 30m" },
+      } as unknown as ClipboardEvent);
+      expect(onChange).toHaveBeenCalledWith(5400);
+    });
+
+    it("hides presets in a table cell", () => {
+      const result = renderWithProviders(
+        <TableCellContext.Provider value={{ inTableCell: true, isHeader: false, editable: true }}>
+          <Duration label="Cell" value={3600} />
+        </TableCellContext.Provider>,
+      );
+      expect(result.container.querySelector("[data-duration-presets]")).toBeNull();
+    });
+
+    it("hides presets when the list is empty", () => {
+      const result = renderWithProviders(<Duration label="None" value={0} presets={[]} />);
+      expect(result.container.querySelector("[data-duration-presets]")).toBeNull();
+    });
+  });
+
   describe("with form context", () => {
     it("renders inside form", () => {
       const result = renderWithProviders(
@@ -113,3 +234,11 @@ describe("Duration", () => {
     });
   });
 });
+
+function skeletonWidthOrHeight(el: HTMLElement, axis: "height" | "width"): number {
+  const attr = el.getAttribute(axis);
+  if (attr && /^\d+(\.\d+)?$/.test(attr)) return Number(attr);
+  const style = axis === "height" ? el.style.height : el.style.width;
+  if (style.endsWith("px")) return Number.parseFloat(style);
+  return Number.parseFloat(getComputedStyle(el)[axis]) || 0;
+}

package/src/fields/Duration/Duration.stories.tsx

@@ -24,10 +24,14 @@ const meta: Meta<typeof Duration> = {
     error: { control: "text" },
     required: { control: "boolean" },
     disabled: { control: "boolean" },
-    size: { control: "select", options: ["$2", "$3", "$4"] },
+    size: { control: "select", options: ["$2", "$3", "$4", "$6"] },
     value: { control: "number", description: "Duration in seconds" },
     showSeconds: { control: "boolean", description: "Show seconds segment" },
     hideDays: { control: "boolean", description: "Fold days into hours" },
+    readOnly: { control: "boolean" },
+    compact: { control: "boolean" },
+    clockIcon: { control: false, description: "Leading clock; pass null to hide" },
+    skeleton: { control: "boolean" },
     placeholder: { control: "text" },
   },
 };
@@ -166,3 +170,28 @@ export const Interactive: Story = {
 export const SkeletonState: Story = {
   args: { label: "Estimated Time", skeleton: true },
 };
+
+export const ReadOnly: Story = {
+  args: {
+    label: "Logged time",
+    helperText: "Read-only fact",
+    value: 5400,
+    readOnly: true,
+  },
+};
+
+export const HideClock: Story = {
+  args: {
+    label: "Duration",
+    value: 3600,
+    clockIcon: null,
+  },
+};
+
+export const Compact: Story = {
+  args: {
+    label: "Compact",
+    value: 1800,
+    compact: true,
+  },
+};

package/src/fields/Duration/durationMath.spec.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import { sizeRecipeForToken } from "@multiplatform.one/theme";
+import {
+  durationSegmentWidth,
+  normalizeSeconds,
+  parseDurationText,
+  partsToSeconds,
+  secondsToParts,
+} from "./durationMath";
+
+describe("durationMath", () => {
+  it("clamps negative and non-finite values to zero", () => {
+    expect(normalizeSeconds(-100)).toBe(0);
+    expect(normalizeSeconds(Number.NaN)).toBe(0);
+    expect(normalizeSeconds(Number.POSITIVE_INFINITY)).toBe(0);
+    expect(normalizeSeconds(1.9)).toBe(1);
+  });
+
+  it("folds days into hours when hideDays", () => {
+    const parts = secondsToParts(100000, true);
+    expect(parts.days).toBe(0);
+    expect(parts.hours).toBe(27);
+    expect(parts.minutes).toBe(46);
+    expect(parts.seconds).toBe(40);
+  });
+
+  it("keeps days first-class when hideDays is false", () => {
+    const parts = secondsToParts(100000, false);
+    expect(parts.days).toBe(1);
+    expect(parts.hours).toBe(3);
+    expect(parts.minutes).toBe(46);
+    expect(parts.seconds).toBe(40);
+  });
+
+  it("round-trips parts through seconds", () => {
+    const seconds = partsToSeconds({ days: 1, hours: 2, minutes: 3, seconds: 4 }, false);
+    expect(seconds).toBe(93784);
+    expect(secondsToParts(seconds, false)).toEqual({
+      days: 1,
+      hours: 2,
+      minutes: 3,
+      seconds: 4,
+    });
+  });
+
+  it("drops days when converting parts with hideDays", () => {
+    expect(partsToSeconds({ days: 2, hours: 1, minutes: 0, seconds: 0 }, true)).toBe(3600);
+  });
+
+  it("parses Frappe-style duration text, clock, and raw seconds", () => {
+    expect(parseDurationText("1d 2h 3m 4s")).toBe(93784);
+    expect(parseDurationText("01h 30m")).toBe(5400);
+    expect(parseDurationText("1:30")).toBe(5400);
+    expect(parseDurationText("1:30:05")).toBe(5405);
+    expect(parseDurationText("-100")).toBe(0);
+    expect(parseDurationText("  ")).toBeNull();
+    expect(parseDurationText("nope")).toBeNull();
+  });
+
+  it("sizes segment width from the size recipe, not a fixed 48/64", () => {
+    const md = sizeRecipeForToken("$4");
+    expect(durationSegmentWidth("$4", 2)).toBe(md.paddingHorizontal + md.fontSize * 2);
+    expect(durationSegmentWidth("$4", 3)).toBe(md.paddingHorizontal + md.fontSize * 3);
+    expect(durationSegmentWidth("$2", 2)).not.toBe(durationSegmentWidth("$6", 2));
+    expect(durationSegmentWidth("$2", 2)).toBeLessThan(durationSegmentWidth("$4", 2));
+  });
+});

package/src/fields/Duration/durationMath.ts

@@ -0,0 +1,78 @@
+import { sizeRecipeForToken } from "@multiplatform.one/theme";
+
+export interface DurationParts {
+  days: number;
+  hours: number;
+  minutes: number;
+  seconds: number;
+}
+
+const UNIT_SECONDS = { d: 86400, h: 3600, m: 60, s: 1 } as const;
+
+export function normalizeSeconds(value: unknown): number {
+  const n = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(n) || n < 0) return 0;
+  return Math.floor(n);
+}
+
+export function secondsToParts(total: number, hideDays: boolean): DurationParts {
+  const s = normalizeSeconds(total);
+  if (hideDays) {
+    return {
+      days: 0,
+      hours: Math.floor(s / 3600),
+      minutes: Math.floor((s % 3600) / 60),
+      seconds: s % 60,
+    };
+  }
+  return {
+    days: Math.floor(s / 86400),
+    hours: Math.floor((s % 86400) / 3600),
+    minutes: Math.floor((s % 3600) / 60),
+    seconds: s % 60,
+  };
+}
+
+export function partsToSeconds(parts: DurationParts, hideDays: boolean): number {
+  const days = hideDays ? 0 : Math.max(0, Math.floor(Number(parts.days)) || 0);
+  const hours = Math.max(0, Math.floor(Number(parts.hours)) || 0);
+  const minutes = Math.max(0, Math.floor(Number(parts.minutes)) || 0);
+  const seconds = Math.max(0, Math.floor(Number(parts.seconds)) || 0);
+  return days * 86400 + hours * 3600 + minutes * 60 + seconds;
+}
+
+/** Frappe-style "1d 2h 3m 4s", clock "1:30" / "1:30:00", or raw seconds. */
+export function parseDurationText(text: string): number | null {
+  const trimmed = text.trim().toLowerCase();
+  if (!trimmed) return null;
+  if (/^-?\d+$/.test(trimmed)) return normalizeSeconds(Number(trimmed));
+  const clock = trimmed.match(/^(\d+):(\d{1,2})(?::(\d{1,2}))?$/);
+  if (clock) {
+    return partsToSeconds(
+      {
+        days: 0,
+        hours: Number(clock[1]),
+        minutes: Number(clock[2]),
+        seconds: Number(clock[3] || 0),
+      },
+      true,
+    );
+  }
+  const pieces = [...trimmed.matchAll(/(\d+)\s*(d|h|m|s)\b/g)];
+  if (pieces.length === 0) return null;
+  let total = 0;
+  for (const piece of pieces) {
+    const unit = piece[2] as keyof typeof UNIT_SECONDS;
+    total += Number(piece[1]) * UNIT_SECONDS[unit];
+  }
+  return total;
+}
+
+/**
+ * Segment box width from the size recipe (LC-75 / LC-79).
+ * Narrow units (min/sec) use 2 digits; wide units (hours/days) use 3.
+ */
+export function durationSegmentWidth(sizeToken: string, digits: number): number {
+  const recipe = sizeRecipeForToken(sizeToken);
+  return recipe.paddingHorizontal + recipe.fontSize * digits;
+}