@recursica/mui-adapter 0.37.0 → 0.38.0

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mui-adapter"
   },
-  "version": "0.37.0",
+  "version": "0.38.0",
   "publishConfig": {
     "access": "public"
   },
@@ -66,6 +66,8 @@
     "prebuild": "npm run analyze-tokens",
     "adapter-tester": "adapter-tester --serve",
     "adapter-tester:automated": "adapter-tester",
+    "adapter-tester:update-golden": "adapter-tester --update-golden",
+    "adapter-tester:source-of-truth": "adapter-tester --divergence-only",
     "test": "vitest run --project unit",
     "test:dom": "vitest run --project dom"
   },
@@ -111,7 +113,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@recursica/adapter-common": "^0.26.0",
+    "@recursica/adapter-common": "^0.27.0",
     "dayjs": "^1.11.21"
   },
   "peerDependencies": {

package/src/components/Label/Label.stories.tsx

@@ -1,9 +1,7 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
 import React from "react";
 import type { Meta, StoryObj } from "@storybook/react";
 import { Label } from "./Label";
-import { TextField } from "../TextField/TextField";
-import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
+import { Button } from "../Button/Button";
 
 type LabelStoryProps = React.ComponentProps<typeof Label>;
 
@@ -15,12 +13,43 @@ const meta: Meta<LabelStoryProps> = {
     docs: {
       description: {
         component:
-          "The `Label` component is a strict Recursica-styled wrapper around Mantine's native `Input.Label`. It serves as the primary compositional primitive for all form fields, preserving Mantine's accessibility associations and context while strictly enforcing the Recursica atomic design system.\n\n### Usage with Form Inputs\nWhen working with form structures, render this `Label` component directly above your inputs or supply it to a component's overriding properties. The component automatically maps structural layout dimensions, dynamic alignment (`left` vs `right`), custom indicator gaps, and integrates a customized `optionalText` and `withEditIcon` flow that safely bypasses Mantine's native required asterisk mechanisms.",
+          "The `Label` component is a strict Recursica-styled wrapper around Mantine's native `Input.Label`. It serves as the primary compositional primitive for all form fields, preserving Mantine's accessibility associations and context while strictly enforcing the Recursica atomic design system.\n\n### Usage with Form Inputs\nThis component only renders the label itself — layout concerns like `stacked` vs `side-by-side` positioning relative to an input live on `FormControlLayout`/`FormControlWrapper`, not here. Render this `Label` in isolation to verify its own states, or see `UI-Kit/FormControlLayout` for how it composes into a full form field.",
       },
     },
   },
   argTypes: {
-    ...formControlArgTypes,
+    labelSize: {
+      control: "inline-radio",
+      options: ["default", "small", "md"],
+      description:
+        "Sizing metrics for the Label. Only visually distinguishable once composed inside a `side-by-side` FormControlLayout, which is where the resulting width constraint applies.",
+    },
+    labelAlignment: {
+      control: "inline-radio",
+      options: ["left", "right"],
+      description: "Text alignment of the label content.",
+    },
+    required: {
+      control: "boolean",
+      description:
+        "Renders the required asterisk (suppressed automatically when `labelWithEditIcon` is set, and mutually exclusive with `labelOptionalText`).",
+    },
+    labelOptionalText: {
+      control: "text",
+      description:
+        "Secondary text rendered beneath the label. Pass `true` for the default '(Optional)' string, or a custom node/string. Suppressed when `required` is true.",
+    },
+    labelWithEditIcon: {
+      control: "boolean",
+      description:
+        "Replaces the default edit icon slot with an interactive edit affordance; replaces the required asterisk visually when both are set.",
+    },
+    labelActionArea: {
+      table: { disable: true },
+    },
+    onLabelEditClick: {
+      table: { disable: true },
+    },
   },
 };
 
@@ -28,95 +57,75 @@ export default meta;
 
 type Story = StoryObj<LabelStoryProps>;
 
-// Utility mapping to pipe raw Label args structurally into TextField accurately
-const renderWithTextField = ({ children, ...args }: LabelStoryProps) => (
-  <TextField
-    label={children as React.ReactNode}
-    placeholder="Form Control primitive mapped..."
-    {...(args as any)}
-  />
-);
-
 export const Default: Story = {
   args: {
-    children: "Dynamic Label (Controls)",
-
+    children: "Label",
     labelSize: "default",
     labelAlignment: "left",
     required: false,
     labelOptionalText: "",
     labelWithEditIcon: false,
   },
-  render: renderWithTextField,
 };
 
-export const StackedDefault: Story = {
+export const Required: Story = {
   args: {
-    children: "Email Address",
+    children: "Required Field",
+    required: true,
   },
-  render: renderWithTextField,
 };
 
-export const StackedRequired: Story = {
+export const RequiredSuppressesOptionalText: Story = {
   args: {
-    children: "Primary Network Node",
-
+    children: "Full Name",
     required: true,
+    labelOptionalText: "This should not render",
   },
-  render: renderWithTextField,
 };
 
-export const StackedWithEditIcon: Story = {
+export const WithOptionalText: Story = {
   args: {
-    children: "Environment Variables",
-
-    labelWithEditIcon: true,
+    children: "Bio",
+    labelOptionalText: "Max 100 characters",
   },
-  render: renderWithTextField,
 };
 
-export const SideBySideDefault: Story = {
+export const BooleanOptionalText: Story = {
   args: {
-    children: "Status",
-
-    labelSize: "default",
+    children: "Middle Initial",
+    labelOptionalText: true,
   },
-  render: renderWithTextField,
 };
 
-export const RequiredSuppressesOptionalText: Story = {
+export const WithEditIcon: Story = {
   args: {
-    children: "Full Name",
-
-    required: true,
-    labelOptionalText: "This should not render",
+    children: "Shipping Address",
+    labelWithEditIcon: true,
   },
-  render: renderWithTextField,
 };
 
-export const BooleanOptionalText: Story = {
+export const RequiredWithEditIcon: Story = {
   args: {
-    children: "Middle Initial",
-
-    labelOptionalText: true,
+    children: "Primary Network Node",
+    required: true,
+    labelWithEditIcon: true,
   },
-  render: renderWithTextField,
 };
 
-export const WithEditIcon: Story = {
+export const RightAligned: Story = {
   args: {
-    children: "Shipping Address",
-
-    labelWithEditIcon: true,
+    children: "Status",
+    labelAlignment: "right",
   },
-  render: renderWithTextField,
 };
 
-export const LayerOneSideBySide: Story = {
+export const WithActionArea: Story = {
   args: {
     children: "Configuration",
-
-    labelWithEditIcon: true,
+    labelActionArea: (
+      <Button variant="text" size="small">
+        Edit
+      </Button>
+    ),
   },
-  render: renderWithTextField,
 };

package/src/components/Loader/Loader.animate.dom.test.tsx

@@ -0,0 +1,72 @@
+import React from "react";
+import { describe, it, expect } from "vitest";
+import { createRoot, type Root } from "react-dom/client";
+import { flushSync } from "react-dom";
+import { Loader } from "./Loader";
+
+function mount(node: React.ReactElement): {
+  container: HTMLElement;
+  root: Root;
+} {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  flushSync(() => root.render(node));
+  return { container, root };
+}
+
+function unmount({ container, root }: { container: HTMLElement; root: Root }) {
+  root.unmount();
+  container.remove();
+}
+
+/**
+ * `animate={false}` must deterministically freeze every variant — including
+ * the bars'/dots' individually-animated child spans, which the freeze rule
+ * can only reach via a descendant selector, not the `data-variant`-scoped
+ * rules the size/thickness CSS uses.
+ */
+describe("Loader animate prop", () => {
+  it.each(["oval", "bars", "dots"] as const)(
+    "freezes every animated element for variant=%s when animate is false, and animates by default",
+    (variant) => {
+      const animated = mount(<Loader variant={variant} />);
+      const frozen = mount(<Loader variant={variant} animate={false} />);
+
+      try {
+        const animatedRoot =
+          animated.container.querySelector("[data-variant]")!;
+        const frozenRoot = frozen.container.querySelector("[data-variant]")!;
+
+        const animatedTargets = [
+          animatedRoot,
+          ...Array.from(animatedRoot.querySelectorAll("*")),
+        ];
+        const frozenTargets = [
+          frozenRoot,
+          ...Array.from(frozenRoot.querySelectorAll("*")),
+        ];
+
+        // At least one element (or the root's own ::after, for oval) actually
+        // animates by default — otherwise this test would trivially pass.
+        const hasAnimation = (el: Element, pseudo?: string) =>
+          getComputedStyle(el, pseudo).animationName !== "none";
+        const animatedHasMotion =
+          animatedTargets.some((el) => hasAnimation(el)) ||
+          hasAnimation(animatedRoot, "::after");
+        expect(animatedHasMotion).toBe(true);
+
+        // Frozen: nothing animates, root included, pseudo-element included.
+        for (const el of frozenTargets) {
+          expect(getComputedStyle(el).animationName).toBe("none");
+        }
+        expect(getComputedStyle(frozenRoot, "::after").animationName).toBe(
+          "none",
+        );
+      } finally {
+        unmount(animated);
+        unmount(frozen);
+      }
+    },
+  );
+});

package/src/components/Loader/Loader.module.css

@@ -9,6 +9,16 @@
   box-sizing: border-box;
 }
 
+/* `animate={false}` — freezes every variant's animation (the oval's own
+ * spinning ::after, and the bars'/dots' individually-animated child spans)
+ * so the loader renders deterministically, e.g. for a visual-regression
+ * snapshot that would otherwise diff differently every run. */
+.root[data-animate="false"],
+.root[data-animate="false"] *,
+.root[data-animate="false"]::after {
+  animation: none !important;
+}
+
 /* data-size mapping */
 
 /* SMALL */

package/src/components/Loader/Loader.stories.tsx

@@ -41,6 +41,11 @@ const meta: Meta<LoaderStoryArgs> = {
       description:
         "Applies a wrapping context to observe rendering logic externally",
     },
+    animate: {
+      control: "boolean",
+      description:
+        "Freezes the CSS animation when false — deterministic, for visual regression",
+    },
   },
 };
 
@@ -48,6 +53,11 @@ export default meta;
 
 type Story = StoryObj<LoaderStoryArgs>;
 
+/**
+ * Animated — excluded from visual regression (`adapter-tester.config.json`),
+ * since a moving animation diffs differently every run. See the `Static*`
+ * stories below for the deterministic, visual-regression-covered equivalents.
+ */
 export const Default: Story = {
   args: {
     variant: "oval",
@@ -62,33 +72,43 @@ export const Default: Story = {
   ),
 };
 
+/** `animate: false` freezes the spin — deterministic for visual regression. */
 export const StaticOvalDefault: Story = {
   args: {
     variant: "oval",
     size: "default",
+    animate: false,
   },
   // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
   render: ({ withLayer, layer, ...args }: any) => <Loader {...args} />,
 };
 
+/** `animate: false` freezes the bars — deterministic for visual regression. */
 export const StaticBarsLarge: Story = {
   args: {
     variant: "bars",
     size: "large",
+    animate: false,
   },
   // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
   render: ({ withLayer, layer, ...args }: any) => <Loader {...args} />,
 };
 
+/** `animate: false` freezes the dots — deterministic for visual regression. */
 export const StaticDotsSmall: Story = {
   args: {
     variant: "dots",
     size: "sm",
+    animate: false,
   },
   // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
   render: ({ withLayer, layer, ...args }: any) => <Loader {...args} />,
 };
 
+/**
+ * Animated — excluded from visual regression, same as `Default`; this one
+ * additionally demonstrates rendering inside a `layer={2}` context.
+ */
 export const LayerTwoOval: Story = {
   args: {
     variant: "oval",

package/src/components/Loader/Loader.tsx

@@ -12,7 +12,13 @@ export type LoaderProps = RecursicaOverStyled<
 >;
 
 export const Loader = forwardRef<HTMLSpanElement, LoaderProps>(function Loader(
-  { variant = "oval", size = "default", overStyled = false, ...rest },
+  {
+    variant = "oval",
+    size = "default",
+    animate = true,
+    overStyled = false,
+    ...rest
+  },
   ref,
 ) {
   const mapSize = {
@@ -54,6 +60,7 @@ export const Loader = forwardRef<HTMLSpanElement, LoaderProps>(function Loader(
       ref={ref}
       data-variant={variant}
       data-size={resolvedSize}
+      data-animate={animate}
       {...sanitizedProps}
       className={finalClass}
     >

package/src/components/Table/TABLE_IMPLEMENTATION_NOTES.md

@@ -55,6 +55,17 @@ than Mantine's. `Table.module.css` resets `.row:global(.Mui-selected)` to
 `background-color: transparent` so only the Recursica token color shows — same
 override-the-library's-own-styling rule the canonical guide documents for hover.
 
+## Currency alignment on header/footer reuses the table-cell token
+
+`--recursica_ui-kit_components_table-cell_properties_currency-style_text-align` (`right`) is the
+only currency-style text-align token the UI Kit exports — there's no
+`table-header_properties_currency-style_*` block at all, and the
+`table-footer_properties_currency-style_*` block skips `text-align` specifically.
+`Table.module.css` reuses the table-cell token for both `thead .cell[data-currency="true"]` and
+`tfoot .cell[data-currency="true"]` so header/footer currency cells stay right-aligned in step
+with the body. `Table.Cell` already threads `variant`/`data-currency` through regardless of
+context, so no `Table.tsx` change was needed here (unlike `mantine-adapter`'s `Table.Th`).
+
 ## Selectable rows (checkboxes)
 
 See `mantine-adapter`'s `TABLE_IMPLEMENTATION_NOTES.md` — confirmed 2026-08-22 that neither

package/src/components/Table/Table.module.css

@@ -225,6 +225,15 @@
   );
 }
 
+/* Currency column header alignment override. No dedicated table-header currency-style token
+   exists yet, so this reuses the table-cell currency-style text-align token to match the
+   currency value cells below it. */
+.root thead .cell[data-currency="true"] {
+  text-align: var(
+    --recursica_ui-kit_components_table-cell_properties_currency-style_text-align
+  );
+}
+
 /* Sort label — MUI's TableSortLabel renders its own arrow icon; re-color it to inherit the
    cell's own text color (instead of MUI's default sort-label color) and size/space it with the
    same tokens Mantine's own inline chevron uses. */
@@ -425,6 +434,11 @@
   line-height: var(
     --recursica_ui-kit_components_table-footer_properties_currency-style_line-height
   );
+  /* No table-footer currency-style text-align token exists yet; reuse the table-cell one so
+     footer currency cells match the body's right alignment. */
+  text-align: var(
+    --recursica_ui-kit_components_table-cell_properties_currency-style_text-align
+  );
   text-decoration: var(
     --recursica_ui-kit_components_table-footer_properties_currency-style_text-decoration
   );

package/src/components/Table/Table.stories.tsx

@@ -128,7 +128,7 @@ export const CurrencyColumnWithFooter: Story = {
           <Table.Head>
             <Table.Row>
               <Table.Cell>Item</Table.Cell>
-              <Table.Cell>Price</Table.Cell>
+              <Table.Cell variant="currency">Price</Table.Cell>
             </Table.Row>
           </Table.Head>
           <Table.Body>

package/src/components/Table/USAGE.md

@@ -45,14 +45,14 @@ export default function Demo() {
 ## 3. Row and Cell States
 
 - **`Table.Row`**: `selected` applies the selected-row background (and MUI's own `selected`/`aria-selected`); `disabled` dims the row and applies the disabled cell colors to every cell in it.
-- **`Table.Cell`**: `sorted="asc" | "desc"` applies the sorted header style (pair with `Table.SortLabel` for the actual sort icon — see below); `variant="currency"` applies the currency text style; `disabled` dims the cell.
+- **`Table.Cell`**: `sorted="asc" | "desc"` applies the sorted header style (pair with `Table.SortLabel` for the actual sort icon — see below); `variant="currency"` applies the currency text style, right-aligning it in any context (header, body, or footer); `disabled` dims the cell.
 - **`Table.SortLabel`** (wraps MUI's `TableSortLabel`): renders the actual sort arrow. Compose it inside a `Table.Cell` the same way MUI's own docs do.
 
 ```tsx
 <Table.Head>
   <Table.Row>
     <Table.Cell>Name</Table.Cell>
-    <Table.Cell sorted="asc">
+    <Table.Cell sorted="asc" variant="currency">
       <Table.SortLabel active direction="asc">
         Balance
       </Table.SortLabel>

package/src/components/TimePicker/TIMEPICKER_IMPLEMENTATION_NOTES.md

@@ -32,7 +32,8 @@ Lowercase `hh` renders 12-hour digits (1–12) with no `a` (meridiem) token, so
 ## Design tokens
 
 - No dedicated `min-height` token exists for `time-picker` (unlike `text-field`/`date-picker`) — the field's height is derived from its own padding + line-height instead of a fixed token.
-- `icon-size`/`icon-color`/`icon-text-gap`/`placeholder-opacity` are exempted (`recursica-ignore`) — the time field has no icon slot and MUI X's field renders empty sections via its own internal placeholder styling, not a native `::placeholder` pseudo-element.
+- `icon-size`/`icon-color`/`icon-text-gap` (plus the disabled/error `icon-color` variants) are wired via `leftSection` — see "Leading icon" below.
+- `placeholder-opacity` remains exempted (`recursica-ignore`) — MUI X's field renders its empty-state "hh"/"mm" placeholder via its own internal `isFieldValueEmpty` styled-component variant (an inline opacity applied through emotion), not a native `::placeholder` pseudo-element this CSS module can target. Unlike mantine-adapter's `SpinInput` (a real `<input placeholder="--">`), there's no stable selector here to hook a token to without depending on MUI X's internal class names.
 - The AM/PM `BareDropdown` draws its own border/background/padding from `Dropdown`'s own tokens via `Dropdown.module.css` — it does not reuse any `time-picker` tokens.
 
 ## Known limitation — the popup clock/list view is unstyled
@@ -43,6 +44,12 @@ This pass covers the closed-state field and the AM/PM `BareDropdown` only. The o
 
 `readOnlyType="text"`, matching `DatePicker`'s convention.
 
+## Leading icon (Matt Massey, 2026-08-30)
+
+Added `leftSection` (`RecursicaTimePickerProps`), matching `TextField`'s naming/convention: purely decorative, consumer-supplied, no default (unlike `DatePicker`'s fixed `CalendarIcon` — there's no single icon that fits every `TimePicker` use).
+
+MUI X's `TimePicker` has no `leftSection` concept — wired via `slotProps.textField.slotProps.input.startAdornment` (the `textField`/`input` slots are exposed at the top level of `TimePicker`'s own `slotProps`, sibling to `field`, via `PickerFieldUISlotPropsFromContext` — confirmed by reading `useDesktopPicker.types.d.ts`/`PickerFieldUI.d.ts` directly, not just the top-level `TimePickerProps` surface). `startAdornment` renders as a plain sibling of `.MuiPickersInputBase-sectionsContainer` inside `PickersInputBase` (confirmed via `PickersInputBase.js`), so it's wrapped in the same `<div className={styles.section} data-position="left">` shape `TextField.tsx` already uses, rather than depending on MUI's own adornment styling. Also added `data-with-left-section` on `.root` so `.MuiPickersInputBase-sectionsContainer`'s own hardcoded `padding-left` (previously always the field's full `horizontal-padding`, structured for the no-icon case) collapses to just `icon-text-gap` once the icon itself is doing the border-inset job instead.
+
 ## Visual review fix (Matt Massey, 2026-08-07)
 
 **`BareDropdown`'s border color didn't match Mantine's version, despite both reading the same `Dropdown` tokens**: a real bug in `BareDropdown.tsx` — `className={styles.root}` was set explicitly on `<MuiSelect>`, then `{...sanitizedProps}` was spread _after_ it. Any caller passing its own `className` (like `TimePicker.tsx`'s `styles.amPmSelect`) silently overwrote `styles.root` entirely via that later spread, so `Dropdown.module.css`'s border-color/background/`width: 100%` never actually applied — MUI's own default border rendered instead. Fixed by extracting `className` explicitly and merging it (`` `${styles.root} ${className}` ``) before it reaches `<MuiSelect>`, the same pattern mantine-adapter's `BareDropdown` already used. This also explains why the AM/PM box's width had looked accidentally "correct" before: the competing `width: 100%` rule from `.root` was never actually being applied either.

package/src/components/TimePicker/TimePicker.module.css

@@ -128,6 +128,37 @@
   color: inherit;
 }
 
+/* Leading icon (leftSection), rendered via slotProps.textField.slotProps.input.startAdornment —
+   a sibling of .MuiPickersInputBase-sectionsContainer inside .field, same shape as TextField's own
+   startAdornment wrapping. Only one icon-color token exists for time-picker (unlike text-field's
+   separate leading/trailing) — this field has no right-side icon slot. */
+.section {
+  display: flex;
+  align-items: center;
+  padding-left: var(
+    --recursica_ui-kit_components_time-picker_properties_horizontal-padding
+  );
+}
+
+.section :global(svg) {
+  width: var(--recursica_ui-kit_components_time-picker_properties_icon-size);
+  height: var(--recursica_ui-kit_components_time-picker_properties_icon-size);
+  color: var(
+    --recursica_ui-kit_components_time-picker_properties_colors_icon-color
+  );
+}
+
+/* With a leftSection present, the icon (not .field's own border) now owns the inset from the left
+   edge — sectionsContainer's own padding-left collapses to just the icon-text-gap between icon and
+   digits. */
+.root[data-with-left-section="true"]
+  .field
+  :global(.MuiPickersInputBase-sectionsContainer) {
+  padding-left: var(
+    --recursica_ui-kit_components_time-picker_properties_icon-text-gap
+  ) !important;
+}
+
 /* The AM/PM BareDropdown reuses Dropdown.module.css's own border/background/padding entirely —
    this only controls its size/alignment within the flex row. */
 .amPmSelect {
@@ -191,6 +222,12 @@
   ) !important;
 }
 
+.root[data-error="true"] .section :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_time-picker_variants_states_error_properties_colors_icon-color
+  ) !important;
+}
+
 /* Disabled State Mapping */
 .field:has(:global(.Mui-disabled)) {
   border-color: var(
@@ -207,3 +244,9 @@
   ) !important;
   cursor: not-allowed;
 }
+
+.field:has(:global(.Mui-disabled)) .section :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_time-picker_variants_states_disabled_properties_colors_icon-color
+  ) !important;
+}

package/src/components/TimePicker/TimePicker.stories.tsx

@@ -115,6 +115,28 @@ export const ErrorState: Story = {
   },
 };
 
+export const WithLeadingIcon: Story = {
+  args: {
+    label: "Meeting Time",
+    assistiveText: "Choose the start time in your local timezone.",
+    leftSection: (
+      <svg
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <circle cx="12" cy="12" r="10"></circle>
+        <polyline points="12 6 12 12 16 14"></polyline>
+      </svg>
+    ),
+  },
+};
+
 export const StaticReadOnly: Story = {
   args: {
     label: "Static ReadOnly Review",

package/src/components/TimePicker/TimePicker.tsx

@@ -124,6 +124,7 @@ export const TimePicker = forwardRef<HTMLDivElement, TimePickerProps>(
       withSeconds,
       minTime,
       maxTime,
+      leftSection,
       ...rest
     } = props;
 
@@ -148,6 +149,12 @@ export const TimePicker = forwardRef<HTMLDivElement, TimePickerProps>(
       ? `${styles.layoutOverride} ${className}`
       : styles.layoutOverride;
 
+    const startAdornment = leftSection ? (
+      <div className={styles.section} data-position="left">
+        {leftSection}
+      </div>
+    ) : undefined;
+
     const emitChange = (next: Dayjs | null) => {
       setInternalValue(next);
       onChange?.(
@@ -206,7 +213,11 @@ export const TimePicker = forwardRef<HTMLDivElement, TimePickerProps>(
              format="hh:mm" is always on (12-hour digits, no native meridiem section) — this is the
              only way this component operates, not a user choice. The AM/PM BareDropdown next to it
              is the only AM/PM control; see TIMEPICKER_IMPLEMENTATION_NOTES.md. */
-          <div className={styles.root} data-error={error ? "true" : undefined}>
+          <div
+            className={styles.root}
+            data-error={error ? "true" : undefined}
+            data-with-left-section={leftSection ? "true" : undefined}
+          >
             <LocalizationProvider dateAdapter={AdapterDayjs}>
               <MuiTimePicker
                 {...(sanitizedProps as unknown as Partial<MuiTimePickerProps>)}
@@ -221,16 +232,23 @@ export const TimePicker = forwardRef<HTMLDivElement, TimePickerProps>(
                 }
                 minTime={toDayjs(minTime)}
                 maxTime={toDayjs(maxTime)}
-                // No icon/open-picker button: time-picker's own token schema has no icon slot (see
-                // EXEMPTIONS above), and the popup clock/list view this button opens isn't styled
-                // to Recursica tokens anyway (see TIMEPICKER_IMPLEMENTATION_NOTES.md) — showing an
-                // affordance to open an unstyled popup would be worse than not showing one. Typing
-                // directly into the field's masked hour/minute segments is the only interaction.
+                // No open-picker button: the popup clock/list view it opens isn't styled to
+                // Recursica tokens (see TIMEPICKER_IMPLEMENTATION_NOTES.md) — showing an affordance
+                // to open an unstyled popup would be worse than not showing one. Typing directly
+                // into the field's masked hour/minute segments is the only interaction. leftSection
+                // (below) is purely decorative, unrelated to this button.
                 slots={{ openPickerButton: () => null }}
                 slotProps={{
                   field: {
                     className: styles.field,
                   },
+                  textField: {
+                    slotProps: {
+                      input: {
+                        startAdornment,
+                      },
+                    },
+                  },
                 }}
               />
             </LocalizationProvider>