@sixthshift/design-system 0.3.0 → 0.5.0

package/src/components/TimePicker/TimeSegments.tsx

@@ -0,0 +1,131 @@
+import type { Temporal } from "../../date-time";
+import { SegmentedField, type SegmentSpec, type SegmentValues } from "../../internal";
+import { parsedToTemporal, temporalTimeToISO, to12Hour, to24Hour } from "./timepicker.hooks";
+import type { ClockFormat, TimeFormat } from "./timepicker.types";
+
+export type TimeSegmentsProps = {
+  /** The time the segments display. `undefined` leaves them empty. */
+  value: Temporal.PlainTime | undefined;
+  /**
+   * Fires with a complete time, or `undefined` the moment the segments stop
+   * describing one. Never fires a partial time.
+   */
+  onChange: (time: Temporal.PlainTime | undefined) => void;
+  /** `"HH:mm:ss"` adds a seconds segment. */
+  format?: TimeFormat | undefined;
+  /** `"12h"` runs the hour 1–12 and adds an AM/PM segment. */
+  clockFormat?: ClockFormat | undefined;
+  isDisabled?: boolean | undefined;
+  isInvalid?: boolean | undefined;
+  label?: string | undefined;
+  onOpenRequest?: (() => void) | undefined;
+  onSubmit?: (() => void) | undefined;
+  id?: string | undefined;
+  className?: string | undefined;
+};
+
+const PERIODS = ["AM", "PM"];
+
+/**
+ * The segments for a clock, which depend on both format props: the hour's range
+ * is the difference between a 12-hour and a 24-hour clock, and AM/PM only exists
+ * in the former.
+ */
+export function timeSpec(format: TimeFormat, clockFormat: ClockFormat, leadingSeparator?: string): SegmentSpec[] {
+  const twelve = clockFormat === "12h";
+  const spec: SegmentSpec[] = [
+    { name: "hour", label: "Hour", placeholder: "hh", digits: 2, min: twelve ? 1 : 0, max: twelve ? 12 : 23, separatorBefore: leadingSeparator },
+    { name: "minute", label: "Minute", placeholder: "mm", digits: 2, min: 0, max: 59, separatorBefore: ":" },
+  ];
+  if (format === "HH:mm:ss") {
+    spec.push({ name: "second", label: "Second", placeholder: "ss", digits: 2, min: 0, max: 59, separatorBefore: ":" });
+  }
+  if (twelve) {
+    // A choice segment rather than a number: `a` and `p` type it, arrows toggle
+    // it, and it announces "AM" instead of an index.
+    spec.push({ kind: "choice", name: "period", label: "AM/PM", placeholder: "--", options: PERIODS, separatorBefore: " " });
+  }
+  return spec;
+}
+
+export function timeCodec(format: TimeFormat, clockFormat: ClockFormat) {
+  const twelve = clockFormat === "12h";
+  const withSeconds = format === "HH:mm:ss";
+
+  const toSegments = (time: Temporal.PlainTime | undefined): SegmentValues => {
+    if (!time) {
+      return {
+        hour: null,
+        minute: null,
+        ...(withSeconds ? { second: null } : {}),
+        ...(twelve ? { period: null } : {}),
+      };
+    }
+    const { hour12, period } = to12Hour(time.hour);
+    return {
+      hour: twelve ? hour12 : time.hour,
+      minute: time.minute,
+      ...(withSeconds ? { second: time.second } : {}),
+      ...(twelve ? { period: period === "PM" ? 1 : 0 } : {}),
+    };
+  };
+
+  const fromSegments = (values: Record<string, number>): Temporal.PlainTime => {
+    const hour = twelve ? to24Hour(values.hour!, values.period === 1 ? "PM" : "AM") : values.hour!;
+    // Seconds are part of the value even when the field does not show them —
+    // `onChange` always emits canonical `HH:MM:SS`.
+    return parsedToTemporal({ hour, minute: values.minute!, second: withSeconds ? values.second! : 0 });
+  };
+
+  /**
+   * A pasted time is read as `H:MM`, `H:MM:SS`, optionally followed by a
+   * meridiem. The hour is interpreted in the field's own clock, so `9:30 PM`
+   * pasted into a 24-hour field still lands on 21:30.
+   */
+  const parsePaste = (text: string): SegmentValues | null => {
+    const match = /^(\d{1,2}):(\d{2})(?::(\d{2}))?\s*(am|pm)?$/i.exec(text.trim());
+    if (!match) return null;
+    const meridiem = match[4]?.toUpperCase();
+    let hour = Number(match[1]);
+    if (meridiem) hour = to24Hour(hour, meridiem === "PM" ? "PM" : "AM");
+    if (hour > 23 || Number(match[2]) > 59) return null;
+    const second = match[3] === undefined ? 0 : Number(match[3]);
+    if (second > 59) return null;
+    return toSegments(parsedToTemporal({ hour, minute: Number(match[2]), second }));
+  };
+
+  return { toSegments, fromSegments, parsePaste };
+}
+
+/**
+ * The typeable half of `TimePicker`: a time as spinbutton segments.
+ *
+ * A thin spec over `SegmentedField`, which owns the keyboard model. What belongs
+ * to clocks specifically lives here: the hour's range and the AM/PM segment,
+ * both decided by `clockFormat`, and the fact that the value always carries
+ * seconds even when the field does not show them.
+ *
+ * `minuteStep` deliberately does not constrain typing. It sets the popover
+ * column's increment, but snapping a typed `:37` onto a 15-minute grid would
+ * fight the keystrokes.
+ *
+ * Internal to `TimePicker`; not exported from `./index.ts`.
+ */
+export function TimeSegments({ value, onChange, format = "HH:mm", clockFormat = "12h", label = "Time", ...rest }: TimeSegmentsProps) {
+  const spec = timeSpec(format, clockFormat);
+  const { toSegments, fromSegments, parsePaste } = timeCodec(format, clockFormat);
+
+  return (
+    <SegmentedField<Temporal.PlainTime>
+      spec={spec}
+      value={value}
+      toSegments={toSegments}
+      fromSegments={fromSegments}
+      keyOf={(time) => temporalTimeToISO(time, "HH:mm:ss")}
+      onChange={onChange}
+      parsePaste={parsePaste}
+      label={label}
+      {...rest}
+    />
+  );
+}

package/src/components/TimePicker/timepicker.hooks.ts

@@ -1,4 +1,4 @@
-import { formatTimePadded, Temporal } from "../../date-time";
+import { Temporal } from "../../date-time";
 import type { ClockFormat, ParsedTime, TimeFormat, TimePeriod } from "./timepicker.types";
 
 // =============================================================================
@@ -41,29 +41,6 @@ export function temporalTimeToISO(time: Temporal.PlainTime, format: TimeFormat =
 // Time Formatting
 // =============================================================================
 
-/**
- * Format Temporal.PlainTime for display
- */
-export function formatTimeDisplay(time: Temporal.PlainTime, clockFormat: ClockFormat = "12h", format: TimeFormat = "HH:mm"): string {
-  if (clockFormat === "12h") {
-    return formatTimePadded(time);
-  }
-  // 24h format
-  if (format === "HH:mm:ss") {
-    return time.toLocaleString("en-US", {
-      hour: "2-digit",
-      minute: "2-digit",
-      second: "2-digit",
-      hour12: false,
-    });
-  }
-  return time.toLocaleString("en-US", {
-    hour: "2-digit",
-    minute: "2-digit",
-    hour12: false,
-  });
-}
-
 // =============================================================================
 // Time Comparison
 // =============================================================================

package/src/components/TimePicker/timepicker.types.ts

@@ -67,9 +67,6 @@ export type TimePickerProps = {
   /** Preset options (shown in sidebar) */
   presets?: TimePresetOption[];
 
-  /** Placeholder text */
-  placeholder?: string;
-
   /** Input name for form submission */
   name?: string;
 

package/src/components/Toast/Toast.tsx

@@ -31,6 +31,33 @@ export type ToastProps = Omit<MessageProps, "size"> & {
 // Toast
 // =============================================================================
 
+/**
+ * A transient notification for the outcome of an action that already
+ * happened — a save, a delete, a failed request — self-positioned bottom
+ * center. Reach for `Toast` over `Message` when the feedback is about an
+ * action and shouldn't stick around in the page's layout; reach for
+ * `Message` when the feedback belongs inline, in the place the caller puts
+ * it (a form's own validation state, an in-card page-load error).
+ *
+ * Toast renders `Message` internally (`<Message intent={intent}>` wrapping
+ * `MessageIcon`/`MessageBody`/`MessageTitle`/`MessageDescription`), so it
+ * inherits Message's live-region role mapping: `intent="danger"` gets
+ * `role="alert"` (assertive), everything else gets `role="status"` (polite).
+ * `action`/`onAction` render a link-style button inside the description; the
+ * dismiss (X) button only renders when `onClose` is provided.
+ *
+ * `standalone` (default `true`) controls positioning: when `true`, Toast
+ * portals itself (`FloatingPortal`, optionally to a custom `root`) and
+ * applies the fixed bottom-center classes itself. Set it to `false` when a
+ * parent already handles portalling and position — this is how
+ * `OverlayContext`'s toast stack renders it. Toast has no built-in
+ * auto-dismiss timer; that's `useToast`'s job, one layer up.
+ *
+ * Exit animation (`usePresence`) keeps Toast mounted through its fade-out,
+ * so `onClose` fires only after the animation completes. Toast has no focus
+ * trap and no Escape handling of its own — it's a passive notification, not
+ * a dialog.
+ */
 export const Toast = React.forwardRef<HTMLDivElement, ToastProps>(
   ({ className, intent = "neutral", title, icon, action, onAction, onClose, root, standalone = true, children, ...props }, ref) => {
     const { ref: presenceRef, state, isMounted, show, hide } = usePresence();
@@ -93,7 +120,7 @@ export const Toast = React.forwardRef<HTMLDivElement, ToastProps>(
             </MessageDescription>
           </MessageBody>
           {onClose && (
-            <Button variant="ghost" size="icon" className="h-6 w-6 shrink-0 opacity-70 hover:opacity-100" onClick={handleClose} aria-label="Dismiss">
+            <Button variant="ghost" iconOnly className="h-6 w-6 shrink-0 opacity-70 hover:opacity-100" onClick={handleClose} aria-label="Dismiss">
               <X className="h-4 w-4" />
             </Button>
           )}

package/src/components/Toggle/Toggle.tsx

@@ -1,40 +1,20 @@
 import { useControllableState } from "@sixthshift/design-system/hooks";
 import { cn } from "@sixthshift/design-system/utils";
-import { cva, type VariantProps } from "class-variance-authority";
+import type { VariantProps } from "class-variance-authority";
 import * as React from "react";
-import { buttonVariants } from "../Button/Button";
+import { type ButtonIntent, type ButtonVariant, buttonRecipe, type buttonVariants } from "../Button/Button";
 
 /**
- * Pressed-state backgrounds matching Button's active: states.
- * When a toggle is "on", its resting background becomes the pressed token.
+ * `variant` and `intent` are no longer CVA variants on `buttonVariants` — they
+ * select a recipe cell in CSS — so they are declared here rather than inherited
+ * through `VariantProps`, which now yields `size` alone.
  */
-const togglePressedVariants = cva("", {
-  variants: {
-    variant: { solid: "", outline: "", ghost: "", link: "" },
-    intent: { neutral: "", danger: "", success: "", warning: "" },
-  },
-  compoundVariants: [
-    // Solid — use the main -pressed background
-    { variant: "solid", intent: "neutral", className: "bg-bg-brand-pressed hover:bg-bg-brand-pressed" },
-    { variant: "solid", intent: "danger", className: "bg-bg-danger-pressed hover:bg-bg-danger-pressed" },
-    { variant: "solid", intent: "success", className: "bg-bg-success-pressed hover:bg-bg-success-pressed" },
-    { variant: "solid", intent: "warning", className: "bg-bg-warning-pressed hover:bg-bg-warning-pressed" },
-    // Outline — use the subtle -pressed background
-    { variant: "outline", intent: "neutral", className: "bg-bg-subtle-pressed text-fg-normal hover:bg-bg-subtle-pressed" },
-    { variant: "outline", intent: "danger", className: "bg-bg-danger-subtle-pressed text-fg-on-danger-subtle-pressed hover:bg-bg-danger-subtle-pressed" },
-    { variant: "outline", intent: "success", className: "bg-bg-success-subtle-pressed text-fg-on-success-subtle-pressed hover:bg-bg-success-subtle-pressed" },
-    { variant: "outline", intent: "warning", className: "bg-bg-warning-subtle-pressed text-fg-on-warning-subtle-pressed hover:bg-bg-warning-subtle-pressed" },
-    // Ghost — same as outline
-    { variant: "ghost", intent: "neutral", className: "bg-bg-subtle-pressed text-fg-normal hover:bg-bg-subtle-pressed" },
-    { variant: "ghost", intent: "danger", className: "bg-bg-danger-subtle-pressed text-fg-on-danger-subtle-pressed hover:bg-bg-danger-subtle-pressed" },
-    { variant: "ghost", intent: "success", className: "bg-bg-success-subtle-pressed text-fg-on-success-subtle-pressed hover:bg-bg-success-subtle-pressed" },
-    { variant: "ghost", intent: "warning", className: "bg-bg-warning-subtle-pressed text-fg-on-warning-subtle-pressed hover:bg-bg-warning-subtle-pressed" },
-  ],
-  defaultVariants: { variant: "solid", intent: "neutral" },
-});
-
 export type ToggleProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onChange" | "value"> &
   VariantProps<typeof buttonVariants> & {
+    variant?: ButtonVariant | undefined;
+    intent?: ButtonIntent | undefined;
+    /** Square the toggle at its current size, for an icon with no label. */
+    iconOnly?: boolean;
     /** Controlled pressed state */
     pressed?: boolean;
     /** Default pressed state for uncontrolled mode */
@@ -43,14 +23,35 @@ export type ToggleProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "o
     onPressedChange?: (pressed: boolean) => void;
   };
 
+/**
+ * A single button that toggles between pressed and unpressed, for a binary
+ * setting styled like an action (e.g. a bold/italic button in a toolbar) —
+ * for a set of mutually exclusive or multi-select options, use `ToggleGroup`
+ * instead.
+ *
+ * Built directly on Button: it calls `buttonRecipe(...)` and takes the same
+ * `variant`/`intent`/`size` axes Button does, plus `iconOnly` for a toolbar
+ * toggle whose whole content is an icon. The
+ * pressed-state colour mapping lives in `src/theme/recipes/toggle.css`,
+ * keyed off the `data-state="on" | "off"` attribute this component renders
+ * alongside `aria-pressed`.
+ *
+ * Controlled via `pressed`/`defaultPressed`/`onPressedChange`
+ * (`useControllableState`).
+ */
 const Toggle = React.forwardRef<HTMLButtonElement, ToggleProps>(
-  ({ className, variant, intent, size, pressed: controlledPressed, defaultPressed = false, onPressedChange, disabled, children, ...props }, ref) => {
+  (
+    { className, variant, intent, size, iconOnly = false, pressed: controlledPressed, defaultPressed = false, onPressedChange, disabled, children, ...props },
+    ref
+  ) => {
     const [pressed, setPressed] = useControllableState({
       value: controlledPressed,
       defaultValue: defaultPressed,
       onChange: onPressedChange,
     });
 
+    const recipe = buttonRecipe({ variant, intent, size, iconOnly });
+
     return (
       <button
         type="button"
@@ -59,7 +60,8 @@ const Toggle = React.forwardRef<HTMLButtonElement, ToggleProps>(
         disabled={disabled}
         ref={ref}
         onClick={() => setPressed(!pressed)}
-        className={cn(buttonVariants({ variant, intent, size }), pressed && togglePressedVariants({ variant, intent }), className)}
+        {...recipe}
+        className={cn(recipe.className, className)}
         {...props}
       >
         {children}
@@ -69,4 +71,4 @@ const Toggle = React.forwardRef<HTMLButtonElement, ToggleProps>(
 );
 Toggle.displayName = "Toggle";
 
-export { Toggle, togglePressedVariants };
+export { Toggle };

package/src/components/Toggle/index.ts

@@ -1 +1 @@
-export { Toggle, type ToggleProps, togglePressedVariants } from "./Toggle";
+export { Toggle, type ToggleProps } from "./Toggle";

package/src/components/ToggleGroup/ToggleGroup.tsx

@@ -3,6 +3,23 @@ import { ToggleGroupMultiple } from "./ToggleGroupMultiple";
 import { ToggleGroupSingle } from "./ToggleGroupSingle";
 import type { ToggleGroupProps } from "./toggleGroup.types";
 
+/**
+ * A group of `Toggle`-styled buttons for choosing one or more options,
+ * switched by `type`: `"single"` renders `role="radiogroup"` with
+ * `role="radio"` items — one tab stop, arrow keys move focus and selection
+ * together (clicking the already-selected item is a no-op, there's no
+ * deselect) — while `"multiple"` renders `role="group"` with `aria-pressed`
+ * items, each independently tabbable and toggled on its own. `value`/
+ * `defaultValue`/`onValueChange` follow `type`: a string for single, a
+ * string array for multiple (`useControllableState`).
+ *
+ * Items are built on the same `buttonRecipe` as `Button`/`Toggle` and take
+ * the same `variant`/`intent`, with two differences: `variant` excludes
+ * `"link"` (no clear pressed state for an underline in a group) and `size`
+ * excludes `"xl"` (too large for grouped toggles) — see
+ * `toggleGroup.types.ts`. `appearance` chooses `"segmented"` (items joined
+ * into one border) or `"separate"` (individually bordered, gapped) rendering.
+ */
 const ToggleGroup = React.forwardRef<HTMLDivElement, ToggleGroupProps>((props, ref) => {
   if (props.type === "multiple") {
     return <ToggleGroupMultiple ref={ref} {...props} />;

package/src/components/ToggleGroup/ToggleGroupItem.tsx

@@ -1,11 +1,10 @@
 import { cn } from "@sixthshift/design-system/utils";
 import * as React from "react";
-import { buttonVariants } from "../Button/Button";
-import { togglePressedVariants } from "../Toggle/Toggle";
+import { buttonRecipe } from "../Button/Button";
 import type { ToggleGroupBaseProps, ToggleGroupOption } from "./toggleGroup.types";
 
 type ItemProps = React.ButtonHTMLAttributes<HTMLButtonElement> &
-  Required<Pick<ToggleGroupBaseProps, "appearance" | "orientation" | "variant" | "intent" | "size">> & {
+  Required<Pick<ToggleGroupBaseProps, "appearance" | "orientation" | "variant" | "intent" | "size" | "iconOnly">> & {
     option: ToggleGroupOption;
     selected: boolean;
     groupDisabled?: boolean | undefined;
@@ -14,24 +13,30 @@ type ItemProps = React.ButtonHTMLAttributes<HTMLButtonElement> &
   };
 
 const ToggleGroupItem = React.forwardRef<HTMLButtonElement, ItemProps>(
-  ({ option, selected, groupDisabled, appearance, orientation, variant, intent, size, index, total, ...props }, ref) => {
+  ({ option, selected, groupDisabled, appearance, orientation, variant, intent, size, iconOnly, index, total, ...props }, ref) => {
     const isDisabled = groupDisabled || option.disabled;
     const isFirst = index === 0;
     const isLast = index === total - 1;
     const isVertical = orientation === "vertical";
     const isSegmented = appearance === "segmented";
 
-    // Both modes share the same base: buttonVariants + togglePressedVariants.
-    // Segmented just overrides border/shadow/rounding so items join cleanly.
+    // Both modes share the same base: buttonVariants + the pressed-state cells
+    // in recipes/toggle.css. Segmented just overrides border/shadow/rounding
+    // so items join cleanly.
+    const recipe = buttonRecipe({ variant, intent, size, iconOnly });
+
     return (
       <button
         ref={ref}
+        {...recipe}
         type="button"
+        // Same attribute Toggle renders for `pressed` — recipes/toggle.css
+        // selects on it, so selected/unselected items pick up the same cells.
+        data-state={selected ? "on" : "off"}
         disabled={isDisabled}
         aria-label={option.ariaLabel}
         className={cn(
-          buttonVariants({ variant, intent, size }),
-          selected && togglePressedVariants({ variant, intent }),
+          recipe.className,
           // Segmented: only override rounding (let buttonVariants handle border/color).
           // Negative margin collapses double borders between outline items.
           isSegmented &&

package/src/components/ToggleGroup/ToggleGroupMultiple.tsx

@@ -15,7 +15,8 @@ const ToggleGroupMultiple = React.forwardRef<HTMLDivElement, ToggleGroupMultiple
       orientation = "horizontal",
       variant = "solid",
       intent = "neutral",
-      size = "default",
+      size = "md",
+      iconOnly = false,
       disabled,
       className,
       ...props
@@ -46,6 +47,7 @@ const ToggleGroupMultiple = React.forwardRef<HTMLDivElement, ToggleGroupMultiple
             variant={variant}
             intent={intent}
             size={size}
+            iconOnly={iconOnly}
             index={index}
             total={options.length}
             aria-pressed={value.includes(option.value)}

package/src/components/ToggleGroup/ToggleGroupSingle.tsx

@@ -17,7 +17,8 @@ const ToggleGroupSingle = React.forwardRef<HTMLDivElement, ToggleGroupSingleProp
       orientation = "horizontal",
       variant = "solid",
       intent = "neutral",
-      size = "default",
+      size = "md",
+      iconOnly = false,
       disabled,
       className,
       ...props
@@ -88,6 +89,7 @@ const ToggleGroupSingle = React.forwardRef<HTMLDivElement, ToggleGroupSingleProp
             variant={variant}
             intent={intent}
             size={size}
+            iconOnly={iconOnly}
             index={index}
             total={options.length}
             role="radio"

package/src/components/ToggleGroup/toggleGroup.types.ts

@@ -1,4 +1,5 @@
 import type * as React from "react";
+import type { ButtonIntentName, ButtonVariantName } from "../Button/Button";
 import type { ToggleProps } from "../Toggle/Toggle";
 
 /** Extract a prop's union type from ToggleProps, stripping null added by CVA */
@@ -22,12 +23,20 @@ export type ToggleGroupBaseProps = Omit<React.HTMLAttributes<HTMLDivElement>, "o
   appearance?: "segmented" | "separate";
   /** Layout orientation */
   orientation?: "vertical" | "horizontal";
-  /** Button variant (link excluded as it has no clear pressed state in groups) */
-  variant?: Exclude<ToggleProp<"variant">, "link">;
+  /**
+   * Button variant (link excluded as it has no clear pressed state in groups).
+   *
+   * Deliberately the closed union, not Button's widened `ButtonVariant`: an
+   * `Exclude` cannot remove `link` from a type that already admits any string,
+   * so narrowing here requires narrowing from the closed names.
+   */
+  variant?: Exclude<ButtonVariantName, "link">;
   /** Color intent */
-  intent?: ToggleProp<"intent">;
+  intent?: ButtonIntentName;
   /** Button size (xl excluded — too large for grouped toggles) */
   size?: Exclude<ToggleProp<"size">, "xl">;
+  /** Square every item at the current size, for icon-only options */
+  iconOnly?: boolean;
   /** Disable all options */
   disabled?: boolean;
 };

package/src/components/Tooltip/Tooltip.tsx

@@ -60,6 +60,12 @@ const TooltipRoot = ({ open: controlledOpen, onOpenChange, placement = "top", de
   return <TooltipContext.Provider value={contextValue}>{children}</TooltipContext.Provider>;
 };
 
+/**
+ * NOTE: Storybook shows the copy in Tooltip.stories.tsx
+ * (`parameters.docs.description.component`), not this comment. react-docgen
+ * cannot extract a description from an `Object.assign` / cast export, so a
+ * second copy here would only drift. Edit the stories file.
+ */
 export const Tooltip = Object.assign(TooltipRoot, {
   Trigger: TooltipTrigger,
   Body: TooltipBody,

package/src/date-time/index.ts

@@ -315,7 +315,6 @@ export {
 //     until: dateRange?.to ? serialize(dateRange.to) : undefined,
 //   };
 //
-// See: packages/web/src/api/activity-log/useActivityLog.ts for reference implementation
 // =============================================================================
 
 // =============================================================================

package/src/internal/PickerField.tsx

@@ -0,0 +1,90 @@
+import { cn } from "@sixthshift/design-system/utils";
+import { X } from "lucide-react";
+import * as React from "react";
+
+export type PickerFieldProps = {
+  /** The segments, or whatever the field holds. */
+  children: React.ReactNode;
+  /** Icon for the button that opens the popover — a calendar or a clock. */
+  icon: React.ReactNode;
+  /** Accessible name for that button, e.g. `"Open calendar for start date"`. */
+  toggleLabel: string;
+  /**
+   * Props for the toggle button — in practice Floating UI's
+   * `getReferenceProps()`, spread last so its handlers win.
+   */
+  toggleProps?: React.ButtonHTMLAttributes<HTMLButtonElement> | undefined;
+  /** Drives `aria-expanded` and whether `aria-controls` is set. */
+  isOpen: boolean;
+  /** Id of the popover this field opens. */
+  contentId: string;
+  isDisabled?: boolean | undefined;
+  isInvalid?: boolean | undefined;
+  /** Omit to render no clear button. */
+  onClear?: ((event: React.MouseEvent) => void) | undefined;
+  /** Accessible name for the clear button, e.g. `"Clear end date"`. */
+  clearLabel?: string | undefined;
+  className?: string | undefined;
+  onFocusCapture?: React.FocusEventHandler<HTMLDivElement> | undefined;
+};
+
+/**
+ * The bordered box every picker trigger is: an icon button that opens the
+ * popover, the field itself, and an optional clear button.
+ *
+ * Extracted because there were six of these — `DatePicker` alone had three, one
+ * per mode plus the two range halves — and they had already started to drift in
+ * padding. The field height, the `focus-within` ring, the invalid border and the
+ * disabled treatment are decided once here, so changing them is one edit rather
+ * than six.
+ *
+ * Width is deliberately not decided here: a time field is narrower than a
+ * date-and-time field, so callers pass their own `min-w-*` through `className`.
+ *
+ * The ref is the box element — what Floating UI anchors to.
+ *
+ * Internal. Not exported from the package.
+ */
+export const PickerField = React.forwardRef<HTMLDivElement, PickerFieldProps>(
+  (
+    { children, icon, toggleLabel, toggleProps, isOpen, contentId, isDisabled = false, isInvalid = false, onClear, clearLabel, className, onFocusCapture },
+    ref
+  ) => (
+    <div
+      ref={ref}
+      onFocusCapture={onFocusCapture}
+      className={cn(
+        "relative flex h-9 items-center gap-1 rounded-md border border-border-normal bg-transparent py-1 pl-1.5 shadow-xs transition-colors focus-within:ring-2 focus-within:ring-focus-ring",
+        onClear ? "pr-9" : "pr-3",
+        isInvalid && "border-border-danger",
+        isDisabled && "cursor-not-allowed opacity-50",
+        className
+      )}
+    >
+      <button
+        type="button"
+        disabled={isDisabled}
+        aria-label={toggleLabel}
+        aria-haspopup="dialog"
+        aria-expanded={isOpen}
+        aria-controls={isOpen ? contentId : undefined}
+        className="rounded-sm p-1 text-fg-subtle transition-colors hover:text-fg-normal focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-focus-ring disabled:cursor-not-allowed"
+        {...toggleProps}
+      >
+        {icon}
+      </button>
+      {children}
+      {onClear && (
+        <button
+          type="button"
+          onClick={onClear}
+          aria-label={clearLabel}
+          className="absolute right-3 rounded-sm p-0.5 text-fg-subtle hover:bg-bg-subtle hover:text-fg-normal focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-focus-ring"
+        >
+          <X className="h-3.5 w-3.5" />
+        </button>
+      )}
+    </div>
+  )
+);
+PickerField.displayName = "PickerField";