@recursica/mantine-adapter 0.55.1 → 0.55.2

package/src/components/Stepper/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,28 @@
+# Stepper Implementation Notes
+
+## Completed/current label & description colors never applied (source-of-truth audit, 2026-08-30)
+
+**Bug:** `.step[data-progress="completed"]`, `.step[data-progress="progress"]`, and
+`.step[data-progress="pending"]` selectors in `Stepper.module.css` checked `data-progress` for
+literal string values (`"completed"`/`"progress"`/`"pending"`) that Mantine's `Stepper.Step` never
+sets. Mantine actually stamps two independent boolean-presence attributes on the step root:
+`data-completed` (present, value `"true"`, when the step index is before `active`) and
+`data-progress` (present, value `"true"`, only on the active step); neither attribute exists at
+all on upcoming steps. Since `[data-progress="completed"]` and `[data-progress="pending"]` never
+match anything real, every step's label and description silently fell through to Mantine's own
+unstyled defaults instead of any Recursica token — for description text specifically, that meant
+Mantine's native muted/dimmed gray (`rgb(134, 142, 150)`, not any `--recursica_*` variable)
+appeared on _every_ step regardless of state, including completed/current steps where the design
+tokens (`..._completed-description-color`/`..._current-description-color`) both resolve to the
+same near-black `layer-0_elements_text_color` as the label. This was visually indistinguishable
+for labels (Mantine's own default text color happens to look close to black too) but clearly
+visible for descriptions, and was mistaken for a mui-adapter bug (mui's class-based `.Mui-active`/
+`.Mui-completed` selectors were already correctly reading these tokens, so mui rendered
+completed/current descriptions in the token's actual dark color while mantine — the presumed
+source of truth — rendered them in this incidental gray).
+
+**Fix:** Match the same working pattern already used one selector up for `.stepIcon` (`.stepIcon
+[data-completed]` / `.stepIcon[data-progress]`, which check attribute _presence_, not a value) —
+changed the `.step` label/description rules to `[data-completed]` / `[data-progress]` /
+`:not([data-completed]):not([data-progress])`. No `mui-adapter` change was needed for this: its
+class-based state selectors were already correct against the design tokens.

package/src/components/Stepper/Stepper.module.css

@@ -298,13 +298,13 @@
   height: var(--stepper-svg-size);
 }
 
-.root .step[data-progress="completed"] .stepLabel {
+.root .step[data-completed] .stepLabel {
   color: var(
     --recursica_ui-kit_components_stepper_properties_colors_completed-label-color
   );
 }
 
-.root .step[data-progress="completed"] .stepDescription {
+.root .step[data-completed] .stepDescription {
   color: var(
     --recursica_ui-kit_components_stepper_properties_colors_completed-description-color
   );
@@ -323,26 +323,26 @@
   );
 }
 
-.root .step[data-progress="progress"] .stepLabel {
+.root .step[data-progress] .stepLabel {
   color: var(
     --recursica_ui-kit_components_stepper_properties_colors_current-label-color
   );
 }
 
-.root .step[data-progress="progress"] .stepDescription {
+.root .step[data-progress] .stepDescription {
   color: var(
     --recursica_ui-kit_components_stepper_properties_colors_current-description-color
   );
 }
 
 /* Upcoming State (Pending Labels) */
-.root .step[data-progress="pending"] .stepLabel {
+.root .step:not([data-completed]):not([data-progress]) .stepLabel {
   color: var(
     --recursica_ui-kit_components_stepper_properties_colors_upcoming-label-color
   );
 }
 
-.root .step[data-progress="pending"] .stepDescription {
+.root .step:not([data-completed]):not([data-progress]) .stepDescription {
   color: var(
     --recursica_ui-kit_components_stepper_properties_colors_upcoming-description-color
   );

package/src/components/Tabs/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,27 @@
+# Tabs Implementation Notes
+
+## `inverted` never actually moved the tab list below the content (2026-08-30, source-of-truth audit)
+
+**Reported symptom:** in the `Inverted` story, content should render above the tab list (tabs
+below), with padding between them — the padding looked missing "when content is on top".
+
+**What was actually happening:** `inverted` is a real, native `@mantine/core` `Tabs` prop
+(confirmed by reading `@mantine/core`'s own `Tabs.cjs`/`Tabs.css`) — this adapter doesn't even
+reference it directly, it flows straight through `...rest` to `<MantineTabs>`. But Mantine's own
+`inverted` support only flips the active-indicator line and border-radius direction (top vs
+bottom) via `data-inverted` CSS selectors; it does not reposition `.list` below `.panel`. The
+story always renders `<Tabs.List>` before the `<Tabs.Panel>`s in JSX regardless of `inverted`, so
+"padding missing when content is on top" wasn't reproducible as such: content was never on top to
+begin with, before this fix.
+
+**Fix:** Mantine renders `Tabs.List`/`Tabs.Panel` as flat siblings directly under `.root` despite
+the nested JSX (confirmed via live DOM dump) — so making `.root[data-orientation="horizontal"]`
+a flex column and giving `.list` `order: 1` only when `[data-inverted]` reorders them visually
+with zero DOM changes, no compound-component internals to touch. Scoped to horizontal only —
+vertical's "instead of left" flip isn't exercised by any story. Also introduced a shared
+`--tabs-content-gap` custom property per variant (previously each variant inlined its own long
+token reference directly into `.list`'s `margin-bottom`) so the same gap can be redirected:
+`margin-bottom: 0; margin-top: var(--tabs-content-gap);` when inverted, since the gap now needs
+to land above the now-trailing tab list instead of below it. Verified live against mui-adapter's
+identical fix (see its own `Tabs/IMPLEMENTATION_NOTES.md`) — pixel-equivalent stacking order and
+gap; no regression on Default/Outline/Pills/Vertical stories.

package/src/components/Tabs/Tabs.module.css

@@ -21,6 +21,24 @@
   .panel (content)
 */
 
+/* `inverted` (RecursicaTabsProps): "tabs list at the bottom ... instead of top". Mantine's own
+   Tabs only reuses `data-inverted` to flip indicator-line/border-radius direction (see
+   @mantine/core's Tabs.css) — it does NOT move `.list` below `.panel`, since both are plain
+   block-level children stacking in DOM order. `.list`/`.panel` here are direct siblings under
+   this same `.root` (Mantine renders Tabs.List/Tabs.Panel flat, despite the nested JSX), so a
+   flex column + `order` on `.list` alone reorders them visually with no DOM change. Scoped to
+   horizontal only — vertical's "instead of left" flip isn't exercised by any story yet.
+   See IMPLEMENTATION_NOTES.md. */
+.root[data-orientation="horizontal"] {
+  display: flex;
+  flex-direction: column;
+}
+.root[data-orientation="horizontal"][data-inverted] .list {
+  order: 1;
+  margin-bottom: 0;
+  margin-top: var(--tabs-content-gap);
+}
+
 /* ---------------------------------
    VARIANTS
    Sizing, geometry, colors, and typography are all scoped per style (default/outline/pills) in
@@ -72,13 +90,14 @@
   --tabs-space-between-tabs: var(
     --recursica_ui-kit_components_tabs_variants_styles_default_variants_orientation_horizontal_properties_space-between-tabs
   );
+  --tabs-content-gap: var(
+    --recursica_ui-kit_components_tabs_variants_styles_default_variants_orientation_horizontal_properties_tabs-content-gap
+  );
 }
 .root[data-variant="default"][data-orientation="horizontal"] .list {
   gap: var(--tabs-space-between-tabs);
   width: 100%;
-  margin-bottom: var(
-    --recursica_ui-kit_components_tabs_variants_styles_default_variants_orientation_horizontal_properties_tabs-content-gap
-  );
+  margin-bottom: var(--tabs-content-gap);
 }
 
 .root[data-variant="default"][data-orientation="vertical"] {
@@ -141,13 +160,14 @@
   --tabs-space-between-tabs: var(
     --recursica_ui-kit_components_tabs_variants_styles_outline_variants_orientation_horizontal_properties_space-between-tabs
   );
+  --tabs-content-gap: var(
+    --recursica_ui-kit_components_tabs_variants_styles_outline_variants_orientation_horizontal_properties_tabs-content-gap
+  );
 }
 .root[data-variant="outline"][data-orientation="horizontal"] .list {
   gap: var(--tabs-space-between-tabs);
   width: 100%;
-  margin-bottom: var(
-    --recursica_ui-kit_components_tabs_variants_styles_outline_variants_orientation_horizontal_properties_tabs-content-gap
-  );
+  margin-bottom: var(--tabs-content-gap);
 }
 
 .root[data-variant="outline"][data-orientation="vertical"] {
@@ -204,13 +224,14 @@
   --tabs-space-between-tabs: var(
     --recursica_ui-kit_components_tabs_variants_styles_pills_variants_orientation_horizontal_properties_space-between-tabs
   );
+  --tabs-content-gap: var(
+    --recursica_ui-kit_components_tabs_variants_styles_pills_variants_orientation_horizontal_properties_tabs-content-gap
+  );
 }
 .root[data-variant="pills"][data-orientation="horizontal"] .list {
   gap: var(--tabs-space-between-tabs);
   width: 100%;
-  margin-bottom: var(
-    --recursica_ui-kit_components_tabs_variants_styles_pills_variants_orientation_horizontal_properties_tabs-content-gap
-  );
+  margin-bottom: var(--tabs-content-gap);
 }
 
 .root[data-variant="pills"][data-orientation="vertical"] {

package/src/components/TimePicker/TIMEPICKER_IMPLEMENTATION_NOTES.md

@@ -82,6 +82,37 @@ Added `leftSection` (`RecursicaTimePickerProps`), matching `TextField`/`AutoComp
 
 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).

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

@@ -51,8 +51,10 @@
 .timeWrapper {
   display: flex;
   align-items: center;
-  /* Gap between the leading-icon section (when leftSection is passed) and the field itself — a
-     no-op with no icon, since gap has no effect between fewer than two flex children. */
+  /* 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;
@@ -127,12 +129,24 @@
 }
 
 /* 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. */
+   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);
@@ -141,6 +155,19 @@
   );
 }
 
+/* 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(