@recursica/mantine-adapter 0.53.0 → 0.55.0

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

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

package/src/components/Loader/Loader.tsx

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

package/src/components/Modal/Modal.module.css

@@ -72,7 +72,9 @@
     var(
       --recursica_ui-kit_components_modal_properties_header-footer-horizontal-padding
     );
-  background-color: transparent; /* Inherit from content */
+  background-color: var(
+    --recursica_ui-kit_components_modal_properties_colors_header-background-color
+  );
 }
 
 .title {
@@ -201,7 +203,9 @@
     var(
       --recursica_ui-kit_components_modal_properties_header-footer-horizontal-padding
     );
-  background-color: transparent;
+  background-color: var(
+    --recursica_ui-kit_components_modal_properties_colors_footer-background-color
+  );
   display: flex;
   justify-content: flex-end;
   gap: var(--recursica_ui-kit_components_modal_properties_button-gap);

package/src/components/NumberInput/NumberInput.module.css

@@ -35,13 +35,18 @@
 }
 
 /* HARDCODED VALUES:
-   - border-width: 1px. Native geometric boundary for the input box.
    - border-style: solid. Native structural rendering rule.
    - outline: none. Bypassing browser focus rings to rely strictly on Recursica focus states natively.
    - flex/layout: display: flex on the root wrapper safely encapsulating internal section rendering.
    - Controls: Hardcoded to bypass Mantine's default borders and backgrounds on the increment/decrement arrows.
 */
 
+/* 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_number-input_variants_states_disabled_properties_border-size */
+/* recursica-ignore: --recursica_ui-kit_components_number-input_variants_states_error_properties_border-size */
+
 .root {
   display: flex;
   position: relative;
@@ -92,7 +97,9 @@
   border-radius: var(
     --recursica_ui-kit_components_number-input_properties_border-radius
   );
-  border-width: 1px;
+  border-width: var(
+    --recursica_ui-kit_components_number-input_properties_border-size
+  );
   border-style: solid;
 
   /* Strict Typography Unification */

package/src/components/SegmentedControl/SegmentedControl.module.css

@@ -4,6 +4,12 @@
    - Scope prefix .root to enforce Figma tokens over Mantine's inline calculation without using !important
 */
 
+/* EXEMPTIONS:
+   - The generic, non-state-specific segmented-control-item border-radius is ignored: the
+     selected/unselected state-specific border-radius tokens below already cover both states an
+     item can be in. */
+/* recursica-ignore: --recursica_ui-kit_components_segmented-control-item_properties_item_border-radius */
+
 .root {
   background-color: var(
     --recursica_ui-kit_components_segmented-control_properties_colors_background-color

package/src/components/Table/TABLE_IMPLEMENTATION_NOTES.md

@@ -56,6 +56,17 @@ recipe with a plain `Checkbox`; the only MUI product with built-in selection is
 selected-row background/token state; wiring an actual checkbox column is a separate,
 not-yet-scoped ask.
 
+## Currency alignment on header/footer reuses the table-cell token
+
+`--recursica_ui-kit_components_table-cell_properties_currency-style_text-align` (`right`) is the
+only currency-style text-align token the UI Kit exports — there's no
+`table-header_properties_currency-style_*` block at all, and the
+`table-footer_properties_currency-style_*` block skips `text-align` specifically. `Table.module.css`
+reuses the table-cell token for both `thead th[data-currency="true"]` and
+`tfoot td[data-currency="true"]` so header/footer currency cells stay right-aligned in step with
+the body. `Table.Th` gained a `variant` prop (mirroring `Table.Td`) to set `data-currency` since
+header cells had no way to opt into this before.
+
 ## Deliberately not changed
 
 - **No wrapper divs** — Forge wraps the table in two divs to get a scrollable bordered

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

@@ -218,6 +218,15 @@
   );
 }
 
+/* Currency column header alignment override. No dedicated table-header currency-style token
+   exists yet, so this reuses the table-cell currency-style text-align token to match the
+   currency value cells below it. */
+.root thead th[data-currency="true"] {
+  text-align: var(
+    --recursica_ui-kit_components_table-cell_properties_currency-style_text-align
+  );
+}
+
 /* Header sort icon & gap spacing helper */
 .root thead th .sortIcon {
   width: var(--recursica_ui-kit_components_table-header_properties_icon-size);
@@ -407,6 +416,11 @@
   line-height: var(
     --recursica_ui-kit_components_table-footer_properties_currency-style_line-height
   );
+  /* No table-footer currency-style text-align token exists yet; reuse the table-cell one so
+     footer currency cells match the body's right alignment. */
+  text-align: var(
+    --recursica_ui-kit_components_table-cell_properties_currency-style_text-align
+  );
   text-decoration: var(
     --recursica_ui-kit_components_table-footer_properties_currency-style_text-decoration
   );

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

@@ -117,7 +117,7 @@ export const CurrencyColumnWithFooter: Story = {
         <Table.Thead>
           <Table.Tr>
             <Table.Th>Item</Table.Th>
-            <Table.Th>Price</Table.Th>
+            <Table.Th variant="currency">Price</Table.Th>
           </Table.Tr>
         </Table.Thead>
         <Table.Tbody>

package/src/components/Table/Table.tsx

@@ -114,7 +114,14 @@ export type TableThProps = RecursicaOverStyled<
 
 export const TableTh = forwardRef<HTMLTableCellElement, TableThProps>(
   function TableTh(
-    { overStyled = false, sorted = false, disabled = false, children, ...rest },
+    {
+      overStyled = false,
+      sorted = false,
+      disabled = false,
+      variant = "default",
+      children,
+      ...rest
+    },
     ref,
   ) {
     const sanitizedProps = filterStylingProps(rest, overStyled);
@@ -124,6 +131,7 @@ export const TableTh = forwardRef<HTMLTableCellElement, TableThProps>(
         {...(sanitizedProps as unknown as MantineTableThProps)}
         data-sorted={sorted ? "true" : undefined}
         data-disabled={disabled ? "true" : undefined}
+        data-currency={variant === "currency" ? "true" : undefined}
         aria-sort={
           sorted === "asc"
             ? "ascending"

package/src/components/Table/USAGE.md

@@ -43,7 +43,7 @@ export default function Demo() {
 ## 3. Row and Cell States
 
 - **`Table.Tr`**: `selected` applies the selected-row background; `disabled` dims the row and applies the disabled cell colors to every cell in it.
-- **`Table.Th`**: `sorted="asc" | "desc"` applies the sorted header style and renders the matching chevron icon; omit it (or pass `false`) for the unsorted style. `disabled` dims the header cell.
+- **`Table.Th`**: `sorted="asc" | "desc"` applies the sorted header style and renders the matching chevron icon; omit it (or pass `false`) for the unsorted style. `disabled` dims the header cell. `variant="currency"` right-aligns the header to match a currency column's value cells.
 - **`Table.Td`**: `variant="currency"` applies the currency text style (for numeric/monetary columns); `disabled` dims the cell.
 
 ```tsx
@@ -51,7 +51,9 @@ export default function Demo() {
   <Table.Thead>
     <Table.Tr>
       <Table.Th>Name</Table.Th>
-      <Table.Th sorted="asc">Balance</Table.Th>
+      <Table.Th sorted="asc" variant="currency">
+        Balance
+      </Table.Th>
     </Table.Tr>
   </Table.Thead>
   <Table.Tbody>

package/src/components/TextArea/TextArea.module.css

@@ -35,12 +35,17 @@
 }
 
 /* HARDCODED VALUES:
-   - border-width: 1px. Native geometric boundary for the input box.
    - border-style: solid. Native structural rendering rule.
    - outline: none. Bypassing browser focus rings to rely strictly on Recursica focus states natively.
    - flex/layout: display: flex on the root wrapper safely encapsulating internal section rendering.
 */
 
+/* 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_textarea_variants_states_disabled_properties_border-size */
+/* recursica-ignore: --recursica_ui-kit_components_textarea_variants_states_error_properties_border-size */
+
 .root {
   display: flex;
   position: relative;
@@ -78,7 +83,9 @@
   border-radius: var(
     --recursica_ui-kit_components_textarea_properties_border-radius
   );
-  border-width: 1px;
+  border-width: var(
+    --recursica_ui-kit_components_textarea_properties_border-size
+  );
   border-style: solid;
 
   /* Strict Typography Unification */

package/src/components/TextField/TextField.module.css

@@ -35,12 +35,17 @@
 }
 
 /* HARDCODED VALUES:
-   - border-width: 1px. Native geometric boundary for the input box.
    - border-style: solid. Native structural rendering rule.
    - outline: none. Bypassing browser focus rings to rely strictly on Recursica focus states natively.
    - flex/layout: display: flex on the root wrapper safely encapsulating internal section rendering.
 */
 
+/* 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_text-field_variants_states_disabled_properties_border-size */
+/* recursica-ignore: --recursica_ui-kit_components_text-field_variants_states_error_properties_border-size */
+
 .root {
   display: flex;
   position: relative;
@@ -91,7 +96,9 @@
   border-radius: var(
     --recursica_ui-kit_components_text-field_properties_border-radius
   );
-  border-width: 1px;
+  border-width: var(
+    --recursica_ui-kit_components_text-field_properties_border-size
+  );
   border-style: solid;
 
   /* Strict Typography Unification */

package/src/components/TimePicker/TIMEPICKER_IMPLEMENTATION_NOTES.md

@@ -36,7 +36,7 @@ Because the AM/PM behavior is fixed, several of Mantine's `TimePicker` props are
 ## 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).
+- `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
@@ -76,6 +76,12 @@ The MUI adapter's equivalent (`mui-adapter/src/components/TimePicker/TimePicker.
 
 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.
+
 ## 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

@@ -6,6 +6,12 @@
  *   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 {
@@ -45,6 +51,9 @@
 .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. */
+  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
@@ -117,6 +126,29 @@
   );
 }
 
+/* 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. */
+.section {
+  display: flex;
+  align-items: center;
+}
+
+.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
+  );
+}
+
+/* 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
@@ -202,6 +234,12 @@
   ) !important;
 }
 
+.root[data-error="true"] .section :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_time-picker_variants_states_error_properties_colors_icon-color
+  ) !important;
+}
+
 /* Disabled State Mapping (Propagated strictly down from the wrapper DOM context) */
 .root[data-disabled="true"] .timeWrapper {
   border-color: var(
@@ -218,3 +256,9 @@
   ) !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

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

package/src/components/TimePicker/TimePicker.tsx

@@ -255,6 +255,7 @@ export const TimePicker = forwardRef<HTMLDivElement, TimePickerProps>(
                 {
                   wrapper: styles.timeWrapper,
                   input: styles.timeInput,
+                  section: styles.section,
                   fieldsGroup: styles.fieldsGroup,
                   field: styles.timeField,
                 },

package/src/components/Timeline/Timeline.module.css

@@ -43,6 +43,11 @@
       --recursica_ui-kit_components_timeline-bullet_variants_types_default_properties_bullet-size
     ) !important;
   }
+  /* EXEMPTIONS:
+     - The avatar variant's own avatar-size token is ignored — sizing is deliberately pinned to
+       the default bullet-size above (not the avatar's own size) to keep the connector line
+       aligned across bullet variants; the child Avatar component governs its own visual size. */
+  /* recursica-ignore: --recursica_ui-kit_components_timeline-bullet_variants_types_avatar_properties_avatar-size */
 
   /* Control connector lines via the item ::before pseudo-element */
   /* Inactive connector */

package/src/components/Toast/Toast.module.css

@@ -2,6 +2,14 @@
    - border-style: solid. Baseline so the per-variant border-color tokens actually render.
  */
 
+/* EXEMPTIONS:
+   - elevation_layer-1/2/3 are ignored: a toast's elevation doesn't depend on the layer it's
+     summoned from — all four layer variants resolve to the same brand elevation value, so
+     layer-0 (already wired below) is the correct, layer-agnostic choice for all of them. */
+/* recursica-ignore: --recursica_ui-kit_components_toast_properties_elevation_layer-1 */
+/* recursica-ignore: --recursica_ui-kit_components_toast_properties_elevation_layer-2 */
+/* recursica-ignore: --recursica_ui-kit_components_toast_properties_elevation_layer-3 */
+
 /* ======================================
    TOAST / NOTIFICATION ROOT
    ====================================== */

package/src/components/Tooltip/Tooltip.module.css

@@ -3,11 +3,19 @@
      which may not set border-style natively). Same pattern as Menu / HoverCard.
    - arrowSize defaults to 16 in Tooltip.tsx. Mantine uses arrowSize for inline width/height
      and positioning (-arrowSize/2) calculations that cannot be CSS-driven. The default matches
-     the Recursica beak-size token (16px). See COMPONENT_ISSUES.md for details.
+     the Recursica beak-size token (16px).
+   - arrow inset/offset is Mantine's own default (no arrowOffset override) — same "must be a JS
+     prop, not CSS-driven" constraint as arrowSize.
    - All structural layout (display, position, overflow) is deferred to Mantine's native
      behavior. We only override visual design tokens (colors, typography, spacing, borders).
 */
 
+/* EXEMPTIONS:
+   - beak-size/beak-inset are ignored: the arrow's size and position are Mantine's own
+     `arrowSize`/`arrowOffset` JS props, not CSS-driven — see HARDCODED VALUES above. */
+/* recursica-ignore: --recursica_ui-kit_components_tooltip_properties_beak-size */
+/* recursica-ignore: --recursica_ui-kit_components_tooltip_properties_beak-inset */
+
 /* ======================================
    TOOLTIP CONTAINER
    ====================================== */

package/src/components/TransferList/TransferList.module.css

@@ -4,6 +4,12 @@
    - `properties_title-filter-gap` sits between each pane's header row and its search field.
    - `properties_filter-items-gap` sits between each pane's search field and its item list. */
 
+/* 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_transfer-list_variants_states_disabled_properties_border-size */
+/* recursica-ignore: --recursica_ui-kit_components_transfer-list_variants_states_error_properties_border-size */
+
 .layoutOverride {
   --form-control-margin-bottom: var(
     --recursica_ui-kit_components_transfer-list_variants_layouts_stacked_properties_top-bottom-margin
@@ -41,7 +47,9 @@
     var(
       --recursica_ui-kit_components_transfer-list_properties_horizontal-padding
     );
-  border-width: 1px;
+  border-width: var(
+    --recursica_ui-kit_components_transfer-list_properties_border-size
+  );
   border-style: solid;
   border-radius: var(
     --recursica_ui-kit_components_transfer-list_properties_border-radius