@recursica/mantine-adapter 0.36.0 → 0.38.0

package/src/components/ReadOnlyField/USAGE.md

@@ -39,14 +39,6 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-## 1. Stripping Mantine Assumptions
+### Editable Mode
 
-Unlike standard input variables, standard HTML output `<p>` tags inherently carry margin and spacing assumptions from core browser stylesheets. To correctly map `ReadOnlyTextField` elements gracefully inside the generic `FormControlWrapper` bounded context, we hardcode resets:
-
-- `margin: 0` explicitly strips block flow gap so `FormControlWrapper` handles vertical rhythm.
-- `min-height`: Native `Input` boxes typically have baseline padding borders. We map directly to `var(--recursica_ui-kit_components_read-only-field_properties_min-height)` to ensure a side-by-side editable `TextField` and `ReadOnlyField` perfectly share roughly identical visual heights.
-
-## 2. Unidirectional Editable Mode
-
-The main wrapper intercepts `readOnly` boolean blocks, maintaining its own `isReadOnly` state. Natively, if a user clicks an exposed 'Edit' action (like our legacy SVG or custom `labelActionArea`), the context permanently switches to active.
-There is intentionally no built-in reverse toggle inside typical field bindings (like input "Blur") to revert state. Parents must pass external controls to `readOnly` forcing the internal hooks to reset via standard `useEffect` propagation.
+If an edit action (e.g. via `labelActionArea`) is used to let a user switch a field from read-only to editable, that switch is one-directional in the UI — there is no built-in control (such as blurring the input) that switches it back to read-only. To revert to read-only, the parent must pass an updated `readOnly` value.

package/src/components/SegmentedControl/USAGE.md

@@ -39,18 +39,4 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-## 1. Stripping Mantine's Native Variants and Sizes
-
-The Figma design tokens for the SegmentedControl component do not define nested layers of variants (such as `solid`, `outline`) or specific sizing steps (`xs`, `sm`, etc.). They are defined globally. Therefore, we explicitly `Omit` the standard `variant`, `size`, `radius`, and `color` props from the generic Mantine `SegmentedControlProps` interface.
-
-## 2. Hardcoded Overrides for Figma Strictness
-
-Mantine injects inline hover styles on `.label` (specifically, adding a subtle gray background when hovering). Since Recursica defines explicit transparent or specifically-driven hover states, we use `!important` tags within `SegmentedControl.module.css` for background and typography overriding.
-
-## 3. Divider Separators
-
-Mantine uses an `::before` pseudo-element on the `.control` block to draw standard visual separators between adjacent elements. Instead of stripping this functionality out, we hook directly into the pseudo-element and override its `background-color` with `--recursica_ui-kit_components_segmented-control_properties_colors_divider-color`.
-
-## 4. Indicator Mapping
-
-The moving active background element (`.indicator`) is decoupled from the actual text label. It is styled natively with its own background color, border size, and elevation shadow variables to match the exact visual parity of a "floating active chip" as defined in the Recursica properties map.
+The `variant`, `size`, `radius`, and `color` props are not available on this component, since appearance is fully controlled by the design system tokens. The active segment is shown as a floating indicator that moves behind the selected label, with a divider rendered between adjacent segments.

package/src/components/Slider/USAGE.md

@@ -39,48 +39,4 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-## 1. Bidirectional State Synchronization
-
-**Decision:** Maintain a highly responsive, bidirectional connection between the sliding track value and the adjacent numeric text input.
-**Implementation:**
-
-- The slider track requires a clean `number` state, whereas the text box requires a `string` state (`inputValue`) to allow typing intermediate characters like decimals (`2.`), negative signs (`-`), or empty text without breaking standard React input binding.
-- A `useEffect` hook continuously feeds the outer numeric state changes back into the text input value as a string representation.
-- Input changes instantly parsed as float clamp bounds securely. On blur (`onBlur`), the input state is automatically sanitized and reset to the clean, clamped string representation of the final track value.
-
-## 2. Outer Form Control Wrapper Integration
-
-**Decision:** Bypass Mantine's native `Input.Wrapper` and `label` properties.
-**Implementation:**
-
-- Universal form wrappers like `<FormControlWrapper>` and `<WithReadOnlyWrapper>` handle the outer layout architecture, including labels, assistive text, error states, and optional edit-triggering fields.
-- Therefore, we map the outer form label directly to the `label` property of the `Slider` (delegated to the wrapper), and rename Mantine's internal dragging tooltip label property to `tooltipLabel`.
-
-## 3. Custom Min-Max Labels and Step Indicators
-
-**Decision:** Enforce rigid typography tokens on lower bounds and custom mark indicators.
-**Implementation:**
-
-- Mantine's native mark and step structures are fully styles-mapped back to our scoped variables in `Slider.module.css`.
-- Min and Max numeric guides are rendered directly to the left and right of the slider track, centered vertically and spaced automatically using standard input gaps, while dynamically fetching custom typography tokens for min-max labels to avoid hardcoded formatting constraints.
-
-## 4. Visual Overrides for Stacked and Side-by-Side Spacing
-
-**Decision:** Enforce layout margins dynamically based on container orientation parameters.
-**Implementation:**
-
-- Using custom layouts (e.g. `stacked` and `side-by-side`), we override the margins by assigning the component-specific Figma spacing variables to the unified `--form-control-margin-bottom` property.
-
-## 5. Right-Aligned Floating Current Value
-
-**Decision:** Position the current active value of the slider directly above the max guide (or right-side element) on the right side of the track.
-**Implementation:**
-
-- Wrap the max guide element in a relative layout container (`.rightGuideContainer`) to provide a positioning anchor.
-- Place the active value element (`.currentValue`) inside `.rightGuideContainer` and position it absolutely (`bottom: calc(100% + var(--recursica_ui-kit_globals_form_properties_label-field-gap-vertical, 8px))`, `right: 0`).
-- This absolute positioning strategy guarantees that the active value floats cleanly above the track's right side, while aligning it vertically on the Y-axis to sit in perfect baseline alignment with the component's left-aligned form label.
-- Set typography using the Figma-aligned component-specific read-only value variables (`--recursica_ui-kit_components_slider_properties_read-only-value_...`).
-- Allow the text color of both the floating current value (`.currentValue`) and the component's read-only value (`.readOnlyValue`) to naturally inherit from their parent states/form globals, automatically supporting default (`--form-field-text-valued`), disabled (`--form-field-disabled-text`), and error colors without explicit color overrides, matching the min/max guides.
-- If `showInput` is enabled, the floating `.currentValue` is hidden since the active value is already displayed and editable within the adjacent numeric text input, avoiding visual redundancy.
-- In `side-by-side` form layouts, the `.currentValue` is positioned inline (static positioning) to the right of the max label rather than floating above it, centered vertically with the max label and aligned right to the container. This uses CSS flexbox ordering (`order: 2` for `.currentValue` and `order: 1` for `.minMaxGuide`) to visually swap their positions while preserving clean, semantic DOM ordering.
-- To ensure perfect, pixel-perfect vertical track alignment between sliders that show numeric text inputs (`showInput={true}`) and sliders that display the active inline value (`showInput={false}`), the `.currentValue` element is globally given a width equal to the input width (`var(--recursica_ui-kit_components_slider_properties_input-width)`) and right-aligned (`text-align: right`). In `side-by-side` layouts, `.rightGuideContainer`'s flex gap is also matched to the horizontal input-to-track gap (`var(--recursica_ui-kit_components_slider_properties_input-gap)`), making the horizontal space occupied by the rightmost elements exactly identical in both component modes.
+The `label` prop is passed through to the surrounding form label rather than Mantine's dragging tooltip; use `tooltipLabel` to set the label shown while dragging. When `showInput` is enabled, a numeric text input is rendered alongside the track and stays in sync with the slider's value. Set `showMinMaxLabels` to `false` to hide the min/max guides shown at either end of the track. Otherwise, the current value is displayed near the track instead.

package/src/components/Stack/USAGE.md

@@ -45,4 +45,4 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 ## 4. Key Integration Features & Constraints
 
 The `Stack` component is a generic flex layout wrapper mapped directly to Mantine's `Stack`.
-It currently does not require any custom logical layouts or CSS workarounds since it serves only to organize layout structure, and doesn't enforce any strict design-system token styling itself. All gap, align, and justify properties pass safely through via the `filterStylingProps` layout-property allowance.
+`gap`, `align`, and `justify` all pass through as normal.

package/src/components/Switch/USAGE.md

@@ -39,27 +39,4 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-## 1. Stripping Mantine's Size Engine
-
-Mantine uses properties like `size`, `color`, and `radius` to dynamically map CSS layout values across its `.track` and `.thumb` nodes. We proactively strip and delete these properties using `filterStylingProps` to entirely neutralize this native behavior.
-
-## 2. Hardcoded Values & Transitions
-
-Mantine injects dynamic width/height attributes into its switch through inline CSS variables (e.g. `--switch-height`). To strictly enforce the UI Kit tokens without breaking Mantine's internal math, our `Switch.module.css` structurally remaps Mantine's internal variables explicitly:
-
-```css
---switch-width: var(--switch-track-width);
---switch-height: calc(
-  var(--switch-thumb-height) + (var(--switch-track-padding) * 2)
-);
-```
-
-We also hardcode `border: none` since the UI kit designs rely purely on box-shadow elevations and background color tracking. Mantine’s default border logic is entirely disabled.
-
-## 3. ReadOnly Behavior
-
-Similar to `Checkbox`, the `Switch` component handles `readOnly` presentation by dropping the entire underlying node tree and falling back structurally onto `<FormControlWrapper>` when `readOnly: true`. This strictly preserves exact baseline alignment across all primitives without trying to hack disabled CSS to look like read-only text.
-
-## 4. Hover State Reset
-
-Mantine forcefully triggers track hover color states globally. Since Recursica currently does not map specific hover states to switch backgrounds across themes (falling back to standard unselected tokens or simply providing a cursor), we structurally wipe out Mantine's `.track:hover` class block inside `Switch.module.css`.
+The `size`, `color`, and `radius` props are not available on this component, since appearance is fully controlled by the design system tokens. When `readOnly` is set, the switch renders as a read-only label instead of an interactive control. There is currently no distinct hover color for the track; it falls back to the standard unselected background.

package/src/components/TextArea/USAGE.md

@@ -43,6 +43,6 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 The `TextArea` component is mapped explicitly to Mantine's `<Textarea>` following the same strict encapsulation rules as `TextField`.
 
-1. **Naked Primitive Mapping:** Mantine's `Textarea` natively executes macro-label generation. To decouple it, we explicitly disable internal labels (`label={undefined}`) and inject it purely inside our generic `FormControlWrapper`.
-2. **Text Field Token Re-Use:** Because text areas fundamentally share the same box-geometry, text, and state definitions as single-line inputs, it strictly implements the `--recursica_ui-kit_components_text-field_...` variables natively.
+1. **Label Rendering:** The label is rendered via the surrounding form label, not Mantine's built-in label.
+2. **Visual Styling:** `TextArea` shares the same visual styling (geometry, typography, and state colors) as `TextField`.
 3. **Autosize Handling:** The component supports Mantine's raw `autosize`, `minRows`, and `maxRows` parameters out of the box dynamically via property passthrough.

package/src/components/TextField/USAGE.md

@@ -41,20 +41,4 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-## Architectural philosophy
-
-The `TextField` primitive intentionally ignores Mantine's built-in `<TextInput>` structure in favor of directly binding against `<Input>`.
-
-### 1. Bypassing `Input.Wrapper`
-
-Because `<TextInput>` inherently renders Mantine's `Input.Wrapper` underneath the hood, utilizing it natively double-wraps our layouts causing massive DOM bloat and margin collapsing errors. By leveraging the completely naked `<Input>` primitive natively natively alongside `FormControlWrapper`, we retain full logical control of where the `label` maps, avoiding dual label conflicts or mis-aligned asterisks securely.
-
-### 2. State Hooks (`wrapperProps`)
-
-Because we target `<Input>`, all dynamic UI modifiers (`disabled`, `error`, etc) must strictly be applied to the `.root` CSS module to correctly style the internal `<input>` boxes AND the nested `.[data-position]` icon sections simultaneously.
-
-To accomplish this safely without spilling random pseudo-variables onto the input parameters, we exclusively use Mantine's `<Input wrapperProps={{...}}>` block natively locking `.root[data-error]` to correctly map Recursica UI variable hooks without breaking the DOM hierarchy natively.
-
-### 3. Component Definition Intersections
-
-To strictly acquire native HTML typings, `TextField.tsx` explicitly extracts `React.ComponentPropsWithoutRef<"input">`. However, to prevent Typescript strict union collisions with overlapping Mantine definitions over functional `style` components and custom mappings natively, we meticulously omit (`Pick<InputWrapperProps, ...>`) explicit base elements to guarantee that strictly Recursica styles traverse the array flawlessly.
+The label, assistive text, and error state are rendered via the surrounding form label rather than Mantine's built-in label, so there is a single, consistently positioned label and asterisk for the field.

package/src/components/TimePicker/TIMEPICKER_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,72 @@
+# 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` are exempted (`recursica-ignore`) — the time field has no icon slot and no native `::placeholder` pseudo-element to target (each `SpinInput`'s `"--"` placeholder is styled internally by Mantine).
+- 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 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

@@ -1,44 +1,228 @@
-/*
- * EXEMPTIONS:
- * - TimePicker is a "Coming Soon" stub component.
- * - It renders a placeholder and has no active implementation or CSS stylesheet yet.
- * - The following tokens generated by Figma are ignored until the component is fully built.
- */
-
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_border-radius */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_horizontal-padding */
+/* EXEMPTIONS:
+   - state-specific border-size variables are ignored because a uniform border-size is applied
+     globally to prevent unexpected layout shift or flickering during disabled/error transitions.
+   - icon-size/icon-color/icon-text-gap have no equivalent here: the time field has no icon slot,
+     unlike TextField/DatePicker.
+   - placeholder-opacity has no direct equivalent: each SpinInput's native "--" placeholder is styled
+     by Mantine's own SpinInput internals, not a ::placeholder pseudo-element we can target directly. */
+/* 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 */
 /* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_icon-size */
 /* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_icon-text-gap */
 /* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_placeholder-opacity */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_text_font-family */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_text_font-size */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_text_font-style */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_text_font-weight */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_text_letter-spacing */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_text_line-height */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_text_text-decoration */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_vertical-padding */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_width */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_layouts_side-by-side_properties_top-bottom-margin */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_layouts_stacked_properties_top-bottom-margin */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_default_properties_border-size */
-/* 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 */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_focus_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_default_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_default_properties_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_default_properties_colors_icon */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_default_properties_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_disabled_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_disabled_properties_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_disabled_properties_colors_icon */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_disabled_properties_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_error_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_error_properties_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_error_properties_colors_icon */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_error_properties_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_focus_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_focus_properties_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_focus_properties_colors_icon */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_focus_properties_colors_text */
+/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_colors_icon-color */
+/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_disabled_properties_colors_icon-color */
+/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_error_properties_colors_icon-color */
+
+/* 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;
+  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
+  );
+}
+
+.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;
+}
+
+/* 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;
+}