@recursica/adapter-mantine-v8 1.0.0

package/src/components/TimePicker/TIMEPICKER_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,119 @@
+# TimePicker Implementation Notes
+
+## Architecture Overview
+
+`TimePicker` is a composite of two independently-styled controls sitting side by side in a flex row:
+
+1. **The time field** — Mantine's own `TimePicker` component (not `TimeInput` — a separate, more advanced component in the same package with real segmented hour/minute/second masking), always rendered with `format="12h"`.
+2. **The AM/PM selector** — `BareDropdown`, a headless variant of this adapter's own `Dropdown` component (see below), not a native `<select>`.
+
+This shape is deliberate and **not configurable** — there is no prop to get a plain 24-hour input or to hide the AM/PM control. Every consumer gets the same 12-hour + Dropdown-styled-AM/PM composite.
+
+## Why not just Mantine's `TimePicker` alone
+
+Mantine's `TimePicker` with `format="12h"` already renders hour/minute masking **and** an AM/PM control together — but that control is a native HTML `<select>` (`AmPmInput`, rendered via `format === "12h" && <AmPmInput />` in Mantine's own source, unconditionally bundled with 12h format — there's no prop to get one without the other). A native `<select>`'s styling is limited, especially its open option list (browser/OS-rendered), so it doesn't visually match Recursica's `Dropdown` component. (Matt Massey, 2026-08-07, after reviewing the initial native-select version in Storybook.)
+
+Resolution: keep Mantine's `TimePicker` for what it does well (real, accessible 1-12 hour + minute + second masking with proper keyboard navigation — not something worth rebuilding from scratch), **CSS-hide its bundled native AM/PM `<select>`** (`.timeWrapper :global([data-am-pm]) { display: none; }`), and drive AM/PM entirely through our own `BareDropdown` next to it.
+
+## `BareDropdown`
+
+A new, **internal-only** component in `../Dropdown/BareDropdown.tsx` — not exported from this folder's `index.ts` (there isn't one; the barrel export is at the package level and only references `Dropdown`, not `BareDropdown`). It's the same `MantineSelect` primitive `Dropdown` wraps, styled via the **same** `Dropdown.module.css` classes (`wrapper`/`input`/`section`/`dropdown`/`option`), but with no `FormControlWrapper`/`WithReadOnlyWrapper` and no label/assistiveText/error/required props.
+
+**Why not the public `Dropdown` component directly**: `Dropdown` wraps its own `FormControlWrapper`/`FormControlLayout` internally (it's meant to be used standalone). Nesting the full `Dropdown` inside `TimePicker` — which is already `FormControlWrapper`-wrapped — would double up `FormControl`/`FormControlLayout` structure. `BareDropdown` is the headless escape hatch for exactly this situation: reuse `Dropdown`'s visual styling without its structural wrapping. (Matt Massey, 2026-08-07.)
+
+## Internal state, unlike every other component here
+
+Every other input in this adapter is a thin pass-through — the wrapped library component owns all interaction state. `TimePicker` is the exception: the time field and the AM/PM `BareDropdown` both mutate the _same_ conceptual value, so something has to reconcile them. `TimePicker.tsx` keeps a `useState<string | undefined>` for the full 24-hour `"HH:mm[:ss]"` value, seeded from `value`/`defaultValue`, synced when `value` changes (controlled usage), and updated by both controls (the field's own `onChange`, and the `BareDropdown`'s `onChange` — which just adds or subtracts 12 from the current hour). The public `value`/`onChange` API is unaffected — still the same plain string convention as always.
+
+## Hidden/omitted native props
+
+Because the AM/PM behavior is fixed, several of Mantine's `TimePicker` props are **omitted from the public API** rather than exposed and silently ignored — a consumer shouldn't be able to pass a prop that looks like it should do something (change format, relabel the native AM/PM control) when it can't:
+
+- `format`, `min`, `max` — hardcoded/remapped internally (`format` always `"12h"`; `min`/`max` come from `minTime`/`maxTime` instead, matching the shared `RecursicaTimePickerProps` contract).
+- `amPmInputLabel`, `amPmLabels`, `amPmSelectProps`, `amPmRef` — all control the native AM/PM `<select>`, which is now CSS-hidden and non-interactive. Exposing these would be misleading.
+- `withDropdown`, `presets`, `maxDropdownContentHeight`, `scrollAreaProps`, `reverseTimeControlsList`, `popoverProps` — the optional time-presets popover feature isn't wired up; kept out of the public API to keep it minimal.
+
+## Design tokens
+
+- No dedicated `min-height` token exists for `time-picker` (unlike `text-field`/`date-picker`) — `.fieldsGroup`'s explicit `height` is derived from `text_line-height` instead, which also fixes a real bug: Mantine's own field CSS sets `height: 100%` on every field to fill `.fieldsGroup`, and a percentage height only resolves against a _concrete_ parent height. Before this, `.fieldsGroup` was auto-height (padding only), so `100%` resolved to `0` — this is why the AM/PM control was invisible in early builds (verified via real headless-browser inspection, not just markup checks — a raw server-render test had missed this entirely since it doesn't compute layout).
+- `icon-size`/`icon-color`/`icon-text-gap`/`placeholder-opacity` (plus the disabled/error `icon-color` variants) are wired via `leftSection` — see "Leading icon" below. Not exempted: despite an earlier note here claiming otherwise, `SpinInput` (`@mantine/dates`) renders a real `<input placeholder="--">` per hour/minute/second segment, so `::placeholder` targets it like any other input.
+- 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.
+
+## Read-Only Implementation
+
+`readOnlyType="text"`, matching `DatePicker`'s convention.
+
+## Visual review fixes (Matt Massey, 2026-08-07)
+
+Follow-up fixes after the first Storybook review of the `BareDropdown`-based rebuild:
+
+- **Outer box was ~62px tall instead of matching `TextField`'s 48px**: Mantine's `TimePicker` renders its `classNames.input` slot as a real, separately-styled box (its own border, background, and `min-height: var(--input-height)` = 36px by default) nested _inside_ `classNames.wrapper` — not a plain content container. Left alone, that gave every field a second, competing Mantine-default border/background stacked underneath our own `.timeWrapper` chrome. Fixed by resetting `.timeInput` (mapped to `classNames.input`) to a bare, unstyled flex shell (`border: none; background-color: transparent; padding: 0; height: auto; min-height: 0;`) — every visual property now lives on `.timeWrapper` alone. Confirmed by reading Mantine's `Input.mjs`/`use-input-props.mjs` source directly, not just trial-and-error CSS.
+- **No dedicated `min-height` token for `time-picker`** (unlike `text-field`): `.timeWrapper` now sets `min-height: var(--recursica_ui-kit_globals_form_field_size_single-line-input-height)` — the same global `text-field`'s own `min-height` token itself resolves to (confirmed via `recursica_variables_scoped.css`), so both land on exactly 48px without binding to another component's own namespace.
+- **No dedicated gap token between the time field and the AM/PM dropdown**: checked `ui-kit.globals.form.properties` — the closest candidates (`label-field-gap-horizontal`, `vertical-item-gap`) are for label-to-field and vertical stacking, not a horizontal gap between two sibling controls. `.root`'s flex `gap` continues to reuse `time-picker`'s own `horizontal-padding` token as a stand-in until a real token exists.
+- **AM/PM `BareDropdown` was as wide as the time field**: two stacked causes, both now fixed:
+  1. A plain `style={{ width: "fit-content" }}` prop doesn't reach the bordered box at all — Mantine's `useInputProps` routes a top-level `style` prop to the _label_ `InputWrapper`, not the input box. Fixed by using the styles-api `styles={{ wrapper: { width: "fit-content" } }}` prop instead, which targets that box directly.
+  2. Even with that fixed, the box stayed wide: `Dropdown.module.css`'s `.input` sets `width: 100%`, and a native `<input>`'s own intrinsic/`auto` width is a fixed browser default (~20 characters), not based on its actual "AM"/"PM" value text, so resetting to `auto` alone didn't shrink it either. Fixed with an explicit small width (`.amPmSelect :global(.mantine-Select-input) { width: 2.5rem; }`, targeting Mantine's stable global class since this module can't reference `Dropdown.module.css`'s own hashed class name) — the wrapper's rendered width just follows this input, since `Dropdown.module.css`'s right-section icon is positioned absolutely and doesn't add to flex flow.
+
+## Visual review round 2 (Matt Massey, 2026-08-08)
+
+- **AM/PM box was too tight — 2.5rem left no room for the "AM"/"PM" text or breathing room around the chevron**: `2.5rem` (40px) is a `box-sizing: border-box` width, so it has to fit Dropdown's own left padding (16px) _and_ its right padding reserved for the chevron section (48px, `horizontal-padding + icon-size + icon-text-gap`) inside it — that's 64px of padding alone, more than the 40px box, leaving a _negative_ content area (hence the invisible value and the chevron crowding the border). Widened to `6rem` (96px), leaving a real ~32px for the text.
+
+## Visual review round 3 (Matt Massey, 2026-08-08) — AM/PM value now defaults and persists
+
+Previously flagged as a known limitation, now fixed: Mantine's own `TimePicker` only reports a valid `onChange` value once its internal `amPm` state is non-`null` (see `getTimeString` in `@mantine/dates`) — that state is normally set by interacting with the native AM/PM `<select>`, which this component CSS-hides entirely. In practice, typing hour/minute digits alone never fired a valid `onChange`, so the AM/PM `BareDropdown` stayed blank forever and selecting a value there did nothing (its own `handleMeridiemChange` logic bailed out early, since `hour` was always `undefined`).
+
+**Fix**: `convertTimeTo12HourFormat` in `@mantine/dates` derives `amPm` from whatever `hours` value it's given — `null` only when `hours` itself is `null`. And `onAmPmChange` (Mantine's internal handler for the — hidden — native select) calls `setAmPm(value)` _unconditionally_, before any validity check. So simulating one real interaction with that native `<select>` — defaulting it to "AM" — permanently seeds Mantine's internal `amPm` state, after which typing hour/minute correctly resolves and reports a real value, and our own `BareDropdown` (which drives the same native select the same way) correctly displays and changes it.
+
+Implementation: a `useEffect` on mount, gated to only run when there's no real initial `value`/`defaultValue` already (Mantine already derives the correct AM/PM from a real value on its own — this only fixes the genuinely-empty-start case). It sets the native select's `.value` via `Object.getOwnPropertyDescriptor(HTMLSelectElement.prototype, "value").set` (required to make a React-controlled element pick up a value set outside of React) and dispatches a `change` event — access to the native element comes via `amPmRef`, a prop omitted from this component's own public API but still usable internally when calling Mantine's `<TimePicker>` directly.
+
+## Visual review round 6 (Matt Massey, 2026-08-17) — AM/PM dropdown blank until an hour is typed
+
+Round 3 fixed Mantine's internal `amPm` state never becoming valid (the deadlock preventing `onChange` from ever firing). It did not fix a separate problem: the visible `BareDropdown`'s own `value` prop was computed as `hour === undefined ? null : isPM ? "PM" : "AM"` — explicitly `null` whenever no hour had been typed yet, so the control displayed empty on mount even though round 3's mount effect had already seeded Mantine's hidden native `<select>` to "AM". Those are two different pieces of state: the hidden native select (round 3's fix target) and `internalValue`/`hour` (what `BareDropdown` actually renders), and writing to one never touched the other.
+
+The MUI adapter's equivalent (`mui-adapter/src/components/TimePicker/TimePicker.tsx`) never had this problem — its `isPM` is a plain boolean (`internalValue ? internalValue.hour() >= 12 : false`) with no `null`/"unset" branch, so its dropdown always renders a concrete "AM"/"PM".
+
+**Fix**: dropped the `null` branch — `BareDropdown`'s `value` is now just `isPM ? "PM" : "AM"`, matching MUI. `isPM` already evaluates `false` when `hour` is `undefined`, so this alone makes the dropdown default to "AM" with no other changes.
+
+Note: selecting AM/PM before any hour is typed is still a no-op in both adapters (`handleMeridiemChange` bails out when `hour`/`internalValue` is undefined) — that's pre-existing, shared behavior in both adapters, not something this fix touches.
+
+## Leading icon (Matt Massey, 2026-08-30)
+
+Added `leftSection` (`RecursicaTimePickerProps`), matching `TextField`/`AutoComplete`'s naming and convention: purely decorative, consumer-supplied, no default. Unlike `DatePicker`'s fixed `CalendarIcon`, there's no single icon that makes sense for every `TimePicker` use, so this is opt-in only.
+
+Mantine's `TimePicker` already accepts `leftSection` (inherited from `@mantine/core`'s `__InputProps` via `InputBase`, which it renders through internally with `component: "div"` — confirmed by reading `TimePicker.mjs`/`Input.mjs` directly) — it was already passing through unstyled before this change (not blocked by `filterStylingProps`), just never mapped to a `classNames.section`/CSS, so an icon would render with no size or color. Added `section: styles.section` to the `classNames` map and the token-driven `.section`/`.section svg` rules (icon-size, icon-color, disabled/error icon-color) to actually style it.
+
+## Leading icon overlapped the field text (bug fix, Matt Massey, 2026-08-30)
+
+Follow-up to the section above, found during a mantine-vs-mui source-of-truth comparison: `.section`
+(the leading icon) is absolutely positioned — Mantine's own default for `Input.Section`, same as
+`Dropdown`/`AutoComplete`'s equivalent — so it never occupies real flex-flow space. `.timeWrapper`'s
+own `gap` (added in the round above, intended to space the icon from the field) has **no effect** on
+it for exactly that reason: `gap` only spaces in-flow flex siblings, and an absolutely-positioned
+child isn't one. Nothing else reserved room for the icon either, so `.fieldsGroup`'s hour/minute/
+second inputs rendered right where `.timeWrapper`'s own base `padding-left` put them — directly
+underneath the icon (visually, the icon and the leading "-- : --" overlapped).
+
+Separately, `.section[data-position="left"]` had no explicit `left`/`padding-left` of its own,
+so it fell back to Mantine's un-tokenized default: centered in a fixed-width box flush against the
+border, not inset by `horizontal-padding` the way `Dropdown`/`AutoComplete`'s own left sections are.
+
+**Fix** (mirrors `Dropdown.module.css`'s established pattern exactly):
+
+- `.section[data-position="left"] { position: absolute; left: 0; padding-left: horizontal-padding; }`
+  — explicit instead of relying on Mantine's un-tokenized default.
+- `.timeWrapper[data-with-left-section] .fieldsGroup { padding-left: calc(icon-size + icon-text-gap); }`
+  — reserves the room the (now out-of-flow) icon needs, on top of `.timeWrapper`'s own existing
+  base `padding-left` (which already covers the initial `horizontal-padding` inset).
+
+**Why mui-adapter, once it fixes its own "icon too far right" bug for the same story, should match
+this corrected rendering and not the previous (overlapping) one**: the previous rendering was a
+straightforward layout bug, not an intentional design — an icon and adjacent text overlapping is
+never a valid state for any other component in either adapter (`Dropdown`, `AutoComplete`,
+`TextField`, `DatePicker` all reserve real space for a leading icon before rendering the field's
+own text/placeholder). This fix brings `TimePicker` in line with that same, already-established
+convention.
+
+## Visual review round 5 (Matt Massey, 2026-08-08)
+
+- **AM/PM error-state border wasn't changing**: `BareDropdown` set `data-error`/`data-disabled` via Mantine's `wrapperProps` — which targets the _outer_ `Input.Wrapper` (the label/description/error stacking element), a different, ancestor element from the "wrapper" styles-api slot that actually carries `styles.root`'s border. `Dropdown.module.css`'s `.root[data-error]`/`[data-disabled]` rules never matched as a result. This is the exact same "two different things both called 'wrapper'" trap as the earlier `style` vs `styles.wrapper` bug. Fixed by using `attributes={{ wrapper: {...} }}` instead — the styles-api hook that actually targets the same slot as `classNames.wrapper`. **This is a shared, pre-existing bug** — the real `Dropdown.tsx` had the identical mistake, so its error/disabled states never applied a border color either; fixed there too (low-risk, purely-additive, same reasoning as the `data-selected` fix above).
+- **Static/Editable ReadOnly showed the raw 24-hour value with no AM/PM** (e.g. "14:30" instead of "2:30 PM"): `readOnlyValue` was passed the raw internal string as-is. Added `formatReadOnlyTime`, converting to a 12-hour + AM/PM display string before handing it to `WithReadOnlyWrapper`.

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

@@ -0,0 +1,291 @@
+/* Brand-layer exemptions (recursica-allow-brand) — see recursica-token-analyzer README.md.
+ * Global hover/focus/disabled state tokens (recursica_variables_scoped.css header, 'Hover & Focus states' / 'Disabled state' — implicit rule for every interactive element; components must not define their own per-component treatment).
+ *   recursica-allow-brand: --recursica_brand_states_focus_blur
+ *   recursica-allow-brand: --recursica_brand_states_focus_border-size
+ *   recursica-allow-brand: --recursica_brand_states_focus_color
+ *   recursica-allow-brand: --recursica_brand_states_focus_margin
+ */
+
+/* EXEMPTIONS:
+   - border-size is constant across disabled/error states — only border-color changes; the
+     disabled/error border-size tokens are never applied by design. */
+/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_disabled_properties_border-size */
+/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_error_properties_border-size */
+
+/* LAYOUT SPACING OVERRIDES:
+   - Sets the --form-control-margin-bottom spacing hook to map component-specific layout tokens. */
+.layoutOverride {
+  --form-control-margin-bottom: var(
+    --recursica_ui-kit_components_time-picker_variants_layouts_stacked_properties_top-bottom-margin
+  );
+}
+
+.layoutOverride[data-form-layout="side-by-side"] {
+  --form-control-margin-bottom: var(
+    --recursica_ui-kit_components_time-picker_variants_layouts_side-by-side_properties_top-bottom-margin
+  );
+}
+
+/* HARDCODED VALUES:
+   - border-style: solid. Native structural rendering rule.
+   - display: flex on .root — the time field and the AM/PM BareDropdown are two visually separate
+     controls sitting side by side, not merged into one shared box. See
+     TIMEPICKER_IMPLEMENTATION_NOTES.md for why this composite exists.
+*/
+
+.root {
+  display: flex;
+  align-items: flex-start;
+  gap: var(
+    --recursica_ui-kit_components_time-picker_properties_horizontal-padding
+  );
+  width: fit-content;
+}
+
+/* Mantine's own native AM/PM <select> is unconditionally bundled with format="12h" (no prop to
+   omit it) — hide it; our own BareDropdown next to the field is the only AM/PM control. */
+.timeWrapper :global([data-am-pm]) {
+  display: none;
+}
+
+.timeWrapper {
+  display: flex;
+  align-items: center;
+  /* This `gap` is a no-op: the leading-icon `.section` is absolutely positioned (Mantine's own
+     default for Input.Section, same as Dropdown/AutoComplete), so it never participates in flex
+     gap spacing as a normal flow sibling — see `.fieldsGroup` below for the fix that actually
+     reserves room for it. Left in place only because it's harmless with a single in-flow child. */
+  gap: var(--recursica_ui-kit_components_time-picker_properties_icon-text-gap);
+  position: relative;
+  box-sizing: border-box;
+  /* min-width, not width: the `width` token was authored for a single plain input (confirmed against
+     text-field's identical token shape); this is now only the time-entry half of the composite. */
+  min-width: var(--recursica_ui-kit_components_time-picker_properties_width);
+  width: fit-content;
+  /* time-picker has no dedicated min-height token (unlike text-field/date-picker); this global is
+     the one text-field's own min-height token resolves to, so both controls land on the same 48px
+     height without binding to another component's own namespace. See
+     TIMEPICKER_IMPLEMENTATION_NOTES.md. */
+  min-height: var(
+    --recursica_ui-kit_globals_form_field_size_single-line-input-height
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_time-picker_properties_border-radius
+  );
+  border-width: var(
+    --recursica_ui-kit_components_time-picker_properties_border-size
+  );
+  border-style: solid;
+  border-color: var(
+    --recursica_ui-kit_components_time-picker_properties_colors_border-color
+  );
+  background-color: var(
+    --recursica_ui-kit_components_time-picker_properties_colors_background-color
+  );
+  color: var(
+    --recursica_ui-kit_components_time-picker_properties_colors_text-color
+  );
+  padding-top: var(
+    --recursica_ui-kit_components_time-picker_properties_vertical-padding
+  );
+  padding-bottom: var(
+    --recursica_ui-kit_components_time-picker_properties_vertical-padding
+  );
+  padding-left: var(
+    --recursica_ui-kit_components_time-picker_properties_horizontal-padding
+  );
+  padding-right: var(
+    --recursica_ui-kit_components_time-picker_properties_horizontal-padding
+  );
+}
+
+/* Mantine's TimePicker renders its own "input" slot as a real, separately-styled box (border,
+   background, height/min-height, padding-inline) nested *inside* .timeWrapper — not just a plain
+   content container. Left alone, that gave every field its own competing Mantine-default border/
+   background/36px-min-height stacked underneath our own .timeWrapper chrome, which is what made
+   the outer box look far taller than intended. Reset it to a plain, unstyled flex shell; every
+   visual property (border, background, padding, height) is owned by .timeWrapper alone. */
+.timeInput {
+  height: auto;
+  min-height: 0;
+  border: none;
+  background-color: transparent;
+  padding: 0;
+  display: block;
+}
+
+/* Padding lives on .timeWrapper, not .fieldsGroup: Mantine's own field styles set `height: 100%` on
+   every field (hour/minute/second SpinInputs) to fill their direct parent (.fieldsGroup). A
+   percentage height only resolves against a parent with a *concrete* height — giving .fieldsGroup
+   an explicit height (derived from time-picker's own text_line-height token, since there's no
+   dedicated min-height token for this component, unlike text-field/date-picker) avoids that
+   collapsing to zero, and doubles as the "min-height" this component doesn't have a token for. */
+.fieldsGroup {
+  display: flex;
+  align-items: center;
+  height: var(
+    --recursica_ui-kit_components_time-picker_properties_text_line-height
+  );
+}
+
+/* Leading icon (leftSection). Only one icon-color token exists for time-picker (unlike
+   text-field's separate leading/trailing) — this field has no right-side icon slot.
+   Positioned explicitly (left:0 + padding-left) rather than left on Mantine's own absolute-
+   positioning default alone (bug fix, see `.fieldsGroup` below): Mantine centers it in a
+   fixed-width box flush against the border with no Recursica padding token applied at all,
+   same technique Dropdown/AutoComplete's own `.section[data-position="left"]` already use. */
+.section {
+  display: flex;
+  align-items: center;
+}
+
+.section[data-position="left"] {
+  position: absolute;
+  left: 0;
+  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
+  );
+}
+
+/* Reserves room for the (absolutely positioned, see `.section` above) leading icon in the actual
+   text flow — without this, `.fieldsGroup`'s hour/minute/second inputs start right where
+   `.timeWrapper`'s own base `padding-left` (horizontal-padding) puts them, which is directly
+   underneath the icon (bug: the icon and the field's leading ":" visibly overlapped). Only the
+   icon-size/icon-text-gap on top of that base padding is needed here, since `.timeWrapper`'s own
+   padding-left already reserves the horizontal-padding portion. */
+.timeWrapper[data-with-left-section] .fieldsGroup {
+  padding-left: calc(
+    var(--recursica_ui-kit_components_time-picker_properties_icon-size) +
+      var(--recursica_ui-kit_components_time-picker_properties_icon-text-gap)
+  );
+}
+
+/* SpinInput renders a real <input placeholder="--">, one per hour/minute/second segment. */
+.timeField::placeholder {
+  opacity: var(
+    --recursica_ui-kit_components_time-picker_properties_placeholder-opacity
+  );
+  color: inherit;
+}
+
+.timeField {
+  font-family: var(
+    --recursica_ui-kit_components_time-picker_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_time-picker_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_time-picker_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_time-picker_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_time-picker_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_time-picker_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_time-picker_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_time-picker_properties_text_text-transform
+  );
+  color: inherit;
+  outline: none;
+}
+
+/* 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 {
+  flex: 0 0 auto;
+  width: auto;
+  min-width: 5.5rem;
+}
+
+/* Dropdown.module.css's own .input sets width: 100% (correct for a standalone Dropdown filling
+   its own column) — resetting that to `auto` still isn't enough here: a native <input>'s intrinsic
+   ("auto"/"fit-content") width is a fixed UA default (~20 characters wide), not based on its actual
+   value text, so it doesn't naturally shrink to "AM"/"PM" either way. Give it an explicit small
+   width sized for a couple of characters instead — the wrapper (.amPmSelect, whose own rendered
+   width just follows this input, since Dropdown.module.css's .section icon is positioned
+   absolutely and doesn't add to flex flow) ends up hugging the content as a result. Target
+   Mantine's own stable global class (not the Dropdown.module.css hash, which this module can't
+   reference directly). See TIMEPICKER_IMPLEMENTATION_NOTES.md.
+   Width math (box-sizing: border-box, so padding eats into this number): Dropdown's own
+   horizontal-padding (16px) on the left + the chevron's reserved right-section padding
+   (horizontal-padding + icon-size + icon-text-gap = 16+24+8 = 48px) on the right leaves very
+   little room for the "AM"/"PM" text itself — 2.5rem (40px) put the padding in a negative content
+   box, which is why the value was invisible and the chevron looked jammed against the border. 6rem
+   leaves a real ~32px content area. */
+.amPmSelect :global(.mantine-Select-input) {
+  width: 6rem;
+}
+
+/* -------------------------------------
+   STATE CASCADE ARCHITECTURE
+-------------------------------------- */
+
+/* Focus State Mapping — applied to the time field only (the BareDropdown has its own via Dropdown's
+   own CSS module). */
+.timeField:focus-within,
+.timeWrapper:focus-within {
+  box-shadow:
+    0 0 0 var(--recursica_brand_states_focus_border-size)
+      var(--recursica_brand_states_focus_color),
+    0 0 var(--recursica_brand_states_focus_blur)
+      var(--recursica_brand_states_focus_margin)
+      var(--recursica_brand_states_focus_color);
+}
+
+/* Error State Mapping (Propagated strictly down from the wrapper DOM context) */
+.root[data-error="true"] .timeWrapper {
+  border-color: var(
+    --recursica_ui-kit_components_time-picker_variants_states_error_properties_colors_border-color
+  ) !important;
+  background-color: var(
+    --recursica_ui-kit_components_time-picker_variants_states_error_properties_colors_background-color
+  ) !important;
+  color: var(
+    --recursica_ui-kit_components_time-picker_variants_states_error_properties_colors_text-color
+  ) !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 (Propagated strictly down from the wrapper DOM context) */
+.root[data-disabled="true"] .timeWrapper {
+  border-color: var(
+    --recursica_ui-kit_components_time-picker_variants_states_disabled_properties_colors_border-color
+  ) !important;
+  background-color: var(
+    --recursica_ui-kit_components_time-picker_variants_states_disabled_properties_colors_background-color
+  ) !important;
+  color: var(
+    --recursica_ui-kit_components_time-picker_variants_states_disabled_properties_colors_text-color
+  ) !important;
+  opacity: var(
+    --recursica_ui-kit_components_time-picker_variants_states_disabled_properties_opacity
+  ) !important;
+  cursor: not-allowed;
+}
+
+.root[data-disabled="true"] .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

@@ -0,0 +1,141 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { TimePicker } from "./TimePicker";
+import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
+
+const meta: Meta<typeof TimePicker> = {
+  title: "UI-Kit/TimePicker",
+  component: TimePicker,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The \`TimePicker\` primitive provides a segmented hour/minute (optionally seconds) time entry input, paired with a dedicated AM/PM \`Dropdown\`-style selector, integrated directly into the \`FormControlWrapper\` architecture. This 12-hour + AM/PM composite is the only way this component operates — a Recursica-specific design, not a user-configurable option.
+
+### Examples
+Always structure horizontal architectures via the generic \`formLayout\` parameter.
+\`\`\`tsx
+<TimePicker
+  label="Start Time"
+  assistiveText="Select the deployment kick-off time."
+  formLayout="stacked"
+/>
+\`\`\`
+`,
+      },
+    },
+  },
+  argTypes: {
+    ...formControlArgTypes,
+    disabled: {
+      control: "boolean",
+      description:
+        "Maps the formal disabled variable states structurally to the input core.",
+    },
+    error: {
+      control: "text",
+      description:
+        "Applies the strict error string boundary rendering invalid structures seamlessly.",
+    },
+    required: {
+      control: "boolean",
+    },
+    label: {
+      control: "text",
+    },
+    assistiveText: {
+      control: "text",
+    },
+    readOnly: {
+      control: "boolean",
+      description:
+        "Toggles structural read-only data presentation explicitly blocking standard component bindings.",
+    },
+    withSeconds: {
+      control: "boolean",
+      description: "Shows and allows editing the seconds segment.",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof TimePicker>;
+
+export const Default: Story = {
+  args: {
+    disabled: false,
+    label: "Meeting Time",
+    assistiveText: "Choose the start time in your local timezone.",
+  },
+};
+
+export const FormsSideBySide: Story = {
+  args: {
+    label: "Incident Start Time",
+    assistiveText: "When did the incident originally occur?",
+    formLayout: "side-by-side",
+  },
+};
+
+export const WithSeconds: Story = {
+  args: {
+    label: "Precise Execution Time",
+    assistiveText: "Includes a seconds segment for exact scheduling.",
+    withSeconds: true,
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    label: "Disabled Time Slot",
+    disabled: true,
+  },
+};
+
+export const ErrorState: Story = {
+  args: {
+    label: "Deployment Window",
+    error: "The chosen time falls outside the allowed deployment window.",
+    required: true,
+  },
+};
+
+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",
+    value: "14:30",
+    readOnly: true,
+  },
+};
+
+export const EditableReadOnly: Story = {
+  args: {
+    label: "Editable ReadOnly Review",
+    defaultValue: "09:00",
+    readOnly: true,
+    labelWithEditIcon: true,
+  },
+};

package/src/components/TimePicker/TimePicker.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future TimePicker component tests. Add tests here if/when needed.