@recursica/mantine-adapter 0.47.0 → 0.48.1

package/src/components/Slider/Slider.tsx

@@ -1,7 +1,9 @@
 import React, { forwardRef, useState, useEffect } from "react";
 import {
   Slider as MantineSlider,
+  RangeSlider as MantineRangeSlider,
   type SliderProps as MantineSliderProps,
+  type RangeSliderProps as MantineRangeSliderProps,
   type InputWrapperProps,
 } from "@mantine/core";
 import { type ReadOnlyControlProps } from "@recursica/adapter-common";
@@ -28,6 +30,10 @@ export interface RecursicaSliderProps
       | "classNames"
       | "styles"
       | "label"
+      | "value"
+      | "defaultValue"
+      | "onChange"
+      | "onChangeEnd"
     >,
     Omit<
       RecursicaFormControlWrapperProps,
@@ -41,14 +47,19 @@ export type SliderProps = RecursicaOverStyled<RecursicaSliderProps>;
 
 /**
  * Custom Read-Only visual representation of the Slider value.
- * Utilizes component-specific read-only typography variables.
+ * Utilizes component-specific read-only typography variables. Renders a "lower – upper" pair
+ * when the value is a range tuple.
  */
-const SliderReadOnlyValue: React.FC<{ value: number }> = ({ value }) => {
-  return <div className={styles.readOnlyValue}>{value}</div>;
+const SliderReadOnlyValue: React.FC<{ value: number | [number, number] }> = ({
+  value,
+}) => {
+  const display = Array.isArray(value) ? `${value[0]} – ${value[1]}` : value;
+  return <div className={styles.readOnlyValue}>{display}</div>;
 };
 
 /**
- * Recursica Slider component wrapping Mantine's Slider.
+ * Recursica Slider component wrapping Mantine's Slider (or, when `value`/`defaultValue` is a
+ * `[number, number]` tuple, Mantine's two-thumb RangeSlider).
  *
  * Implements a bidirectional text input field next to the slider track, responsive layouts,
  * custom typography-bound min/max labels (optionally overridden via `minLabel`/`maxLabel`),
@@ -98,24 +109,38 @@ export const Slider = forwardRef<HTMLDivElement, SliderProps>(
       ...rest
     } = props;
 
-    // Bidirectional state linking the slider track value to the input field string representation
-    const [internalValue, setInternalValue] = useState<number>(() => {
+    // Bidirectional state linking the slider track value to the input field string
+    // representation. A `[number, number]` value/defaultValue switches the component into
+    // two-thumb range mode, backed by Mantine's RangeSlider instead of Slider.
+    type SliderValue = number | [number, number];
+
+    const [internalValue, setInternalValue] = useState<SliderValue>(() => {
       if (value !== undefined) return value;
       if (defaultValue !== undefined) return defaultValue;
       return min;
     });
 
-    const resolvedValue = value !== undefined ? value : internalValue;
-    const [inputValue, setInputValue] = useState<string>(
-      resolvedValue.toString(),
+    const resolvedValue: SliderValue =
+      value !== undefined ? value : internalValue;
+    const isRange = Array.isArray(resolvedValue);
+
+    const [inputValue, setInputValue] = useState<string | [string, string]>(
+      () =>
+        Array.isArray(resolvedValue)
+          ? [resolvedValue[0].toString(), resolvedValue[1].toString()]
+          : resolvedValue.toString(),
     );
 
-    // Synchronize text input whenever the slider value changes
+    // Synchronize text input(s) whenever the slider value changes
     useEffect(() => {
-      setInputValue(resolvedValue.toString());
+      setInputValue(
+        Array.isArray(resolvedValue)
+          ? [resolvedValue[0].toString(), resolvedValue[1].toString()]
+          : resolvedValue.toString(),
+      );
     }, [resolvedValue]);
 
-    const handleValueChange = (val: number) => {
+    const handleValueChange = (val: SliderValue) => {
       if (value === undefined) {
         setInternalValue(val);
       }
@@ -136,7 +161,38 @@ export const Slider = forwardRef<HTMLDivElement, SliderProps>(
 
     const handleInputBlur = () => {
       // Clean up text field on blur to reflect the final clamped resolved value
-      setInputValue(resolvedValue.toString());
+      setInputValue((resolvedValue as number).toString());
+    };
+
+    // Range-mode input handlers: each bound clamps against the other thumb rather than the
+    // shared min/max, so the lower thumb can never cross the upper one and vice versa.
+    const handleLowerInputChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+      const current = resolvedValue as [number, number];
+      const valStr = e.target.value;
+      setInputValue([valStr, current[1].toString()]);
+
+      const parsed = parseFloat(valStr);
+      if (!isNaN(parsed)) {
+        const clamped = Math.max(min, Math.min(current[1], parsed));
+        handleValueChange([clamped, current[1]]);
+      }
+    };
+
+    const handleUpperInputChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+      const current = resolvedValue as [number, number];
+      const valStr = e.target.value;
+      setInputValue([current[0].toString(), valStr]);
+
+      const parsed = parseFloat(valStr);
+      if (!isNaN(parsed)) {
+        const clamped = Math.max(current[0], Math.min(max, parsed));
+        handleValueChange([current[0], clamped]);
+      }
+    };
+
+    const handleRangeInputBlur = () => {
+      const current = resolvedValue as [number, number];
+      setInputValue([current[0].toString(), current[1].toString()]);
     };
 
     // Props this component intentionally doesn't support — deleted at runtime so they can't leak
@@ -164,6 +220,7 @@ export const Slider = forwardRef<HTMLDivElement, SliderProps>(
         track: styles.sliderTrack,
         bar: styles.sliderBar,
         thumb: styles.sliderThumb,
+        markWrapper: styles.sliderMarkWrapper,
         mark: styles.sliderMark,
         markLabel: styles.sliderMarkLabel,
       },
@@ -188,8 +245,12 @@ export const Slider = forwardRef<HTMLDivElement, SliderProps>(
 
     // Duplicates the raw numeric value next to the track by default; when `tooltipLabel` is a
     // formatter, reuse it here too so both displays agree instead of one showing raw numbers.
-    const displayValue =
-      typeof tooltipLabel === "function"
+    // Range mode formats each thumb independently and joins them with an en dash.
+    const displayValue = Array.isArray(resolvedValue)
+      ? typeof tooltipLabel === "function"
+        ? `${tooltipLabel(resolvedValue[0])} – ${tooltipLabel(resolvedValue[1])}`
+        : `${resolvedValue[0]} – ${resolvedValue[1]}`
+      : typeof tooltipLabel === "function"
         ? tooltipLabel(resolvedValue)
         : resolvedValue;
 
@@ -228,6 +289,22 @@ export const Slider = forwardRef<HTMLDivElement, SliderProps>(
             data-disabled={disabled ? "true" : undefined}
             data-error={error ? "true" : undefined}
           >
+            {isRange && showInput && (
+              <input
+                type="number"
+                className={styles.inputField}
+                value={(inputValue as [string, string])[0]}
+                onChange={handleLowerInputChange}
+                onBlur={handleRangeInputBlur}
+                min={min}
+                max={(resolvedValue as [number, number])[1]}
+                step={step}
+                disabled={disabled}
+                data-error={error ? "true" : undefined}
+                aria-label="Minimum value"
+              />
+            )}
+
             {leadingIcon}
 
             {showMinMaxLabels && (
@@ -235,18 +312,33 @@ export const Slider = forwardRef<HTMLDivElement, SliderProps>(
             )}
 
             <div className={styles.sliderTrackWrapper}>
-              <MantineSlider
-                {...(sanitizedProps as unknown as MantineSliderProps)}
-                classNames={mergedClassNames}
-                disabled={disabled}
-                value={resolvedValue}
-                onChange={handleValueChange}
-                onChangeEnd={onChangeEnd}
-                min={min}
-                max={max}
-                step={step}
-                label={tooltipLabel}
-              />
+              {isRange ? (
+                <MantineRangeSlider
+                  {...(sanitizedProps as unknown as MantineRangeSliderProps)}
+                  classNames={mergedClassNames}
+                  disabled={disabled}
+                  value={resolvedValue as [number, number]}
+                  onChange={handleValueChange}
+                  onChangeEnd={onChangeEnd}
+                  min={min}
+                  max={max}
+                  step={step}
+                  label={tooltipLabel}
+                />
+              ) : (
+                <MantineSlider
+                  {...(sanitizedProps as unknown as MantineSliderProps)}
+                  classNames={mergedClassNames}
+                  disabled={disabled}
+                  value={resolvedValue as number}
+                  onChange={handleValueChange}
+                  onChangeEnd={onChangeEnd}
+                  min={min}
+                  max={max}
+                  step={step}
+                  label={tooltipLabel}
+                />
+              )}
             </div>
 
             <div className={styles.rightGuideContainer}>
@@ -258,22 +350,37 @@ export const Slider = forwardRef<HTMLDivElement, SliderProps>(
               )}
             </div>
 
-            {showInput && (
-              <input
-                type="number"
-                className={styles.inputField}
-                value={inputValue}
-                onChange={handleInputChange}
-                onBlur={handleInputBlur}
-                min={min}
-                max={max}
-                step={step}
-                disabled={disabled}
-                data-error={error ? "true" : undefined}
-              />
-            )}
-
             {trailingIconEl}
+
+            {showInput &&
+              (isRange ? (
+                <input
+                  type="number"
+                  className={styles.inputField}
+                  value={(inputValue as [string, string])[1]}
+                  onChange={handleUpperInputChange}
+                  onBlur={handleRangeInputBlur}
+                  min={(resolvedValue as [number, number])[0]}
+                  max={max}
+                  step={step}
+                  disabled={disabled}
+                  data-error={error ? "true" : undefined}
+                  aria-label="Maximum value"
+                />
+              ) : (
+                <input
+                  type="number"
+                  className={styles.inputField}
+                  value={inputValue as string}
+                  onChange={handleInputChange}
+                  onBlur={handleInputBlur}
+                  min={min}
+                  max={max}
+                  step={step}
+                  disabled={disabled}
+                  data-error={error ? "true" : undefined}
+                />
+              ))}
           </div>
         }
       />

package/src/components/Slider/USAGE.md

@@ -39,4 +39,18 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-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 — pass `tooltipLabel` as a formatter function (`(value) => ReactNode`) and that same formatter is reused for this display, instead of always showing the raw number. `minLabel`/`maxLabel` override the text shown at either end of the track (defaults to the numeric `min`/`max`). `icon` renders a leading icon next to the track; `trailingIcon` renders one on the opposite side.
+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 — pass `tooltipLabel` as a formatter function (`(value) => ReactNode`) and that same formatter is reused for this display, instead of always showing the raw number. `minLabel`/`maxLabel` override the text shown at either end of the track (defaults to the numeric `min`/`max`). `icon` renders a leading icon next to the track; `trailingIcon` renders one on the opposite side, rendered right after the max label and before the numeric input.
+
+### Range Mode
+
+Pass a `[number, number]` tuple as `value`/`defaultValue` to render a two-thumb range slider — `onChange`/`onChangeEnd` are then called with a `[number, number]` tuple instead of a `number`. This is a real component swap under the hood (Mantine's `RangeSlider`, not `Slider`), so `value` and `defaultValue` must agree on shape for a given instance. With `showInput` enabled, a second numeric input for the upper bound appears after the trailing icon, with the lower-bound input before the leading icon:
+
+```tsx
+<Slider
+  label="Price Range"
+  defaultValue={[20, 80]}
+  min={0}
+  max={100}
+  onChange={(value) => console.log(value)} // [number, number]
+/>
+```

package/src/components/Switch/Switch.module.css

@@ -1,3 +1,11 @@
+/* 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
+ */
+
 /* HARDCODED VALUES
  *
  * 1. track border: none; (we do not use border for the switch track)

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

@@ -1,3 +1,9 @@
+/* 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_hover_color
+ *   recursica-allow-brand: --recursica_brand_states_hover_opacity
+ */
+
 /* HARDCODED VALUES:
  * - border-collapse: separate; border-spacing: 0; (To support custom border-radius on table elements)
  * - overflow: hidden; (To prevent content from bleeding outside the rounded table border)

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

@@ -1,3 +1,10 @@
+/* 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_hover_color
+ *   recursica-allow-brand: --recursica_brand_states_hover_opacity
+ *   recursica-allow-brand: --recursica_brand_states_disabled
+ */
+
 /*
   Recursica Tabs CSS module natively binding to Figma variables.
 */

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

@@ -1,3 +1,11 @@
+/* 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
+ */
+
 /* LAYOUT SPACING OVERRIDES:
    - Sets the --form-control-margin-bottom spacing hook to map component-specific layout tokens.
    - Also sets the --textarea-control-{max,min}-width hooks consumed inline in TextArea.tsx, since

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

@@ -1,3 +1,11 @@
+/* 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
+ */
+
 /* LAYOUT SPACING OVERRIDES:
    - Sets the --form-control-margin-bottom spacing hook to map component-specific layout tokens.
    - Also sets the --text-field-control-{max,min}-width hooks consumed inline in TextField.tsx,

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

@@ -1,3 +1,11 @@
+/* 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
+ */
+
 /* LAYOUT SPACING OVERRIDES:
    - Sets the --form-control-margin-bottom spacing hook to map component-specific layout tokens. */
 .layoutOverride {

package/src/components/Tree/IMPLEMENTATION_NOTES.md

@@ -40,6 +40,9 @@
   - No MUI-style leftover "default selected background" issue existed here — Mantine's own `Tree` has no default row styling of its own once a custom `renderNode` is supplied (see the very first entry in this file), so there was nothing to neutralize on this side.
 
 - **Whole-tree `disabled` (Matt Massey, 2026-08-10), added to support a `Disabled` story.** Mantine's `Tree`/`useTree`/`TreeNode` have no `disabled` concept anywhere in their API, unlike `@mui/x-tree-view` (which already had per-item `disabled` plumbing sitting mostly unused — see mui-adapter's own note on this). Per-node disabling still isn't exposed (no token, no `disabled` field on `RecursicaTreeNode` — same reasoning as the existing "Deliberately not implemented" entry above), only a single whole-tree toggle.
+
   - **Mouse**: `selectOnClick={!disabled}` reuses Mantine's own flag for row clicks. The chevron `Button`'s `onClick` bypasses that flag entirely (calls `tree.toggleExpanded` directly), so it needs its own explicit `if (disabled) return;` guard. `.root[data-disabled] { pointer-events: none; }` is a second, CSS-only backstop covering both at once — belt-and-suspenders, not strictly required given the two guards above, but consistent with how little the library gives us to rely on here.
   - **Keyboard**: our own `Enter`/`Space` → `select` listener (added in the entry above) just checks `disabled` at the top now. `ArrowLeft`/`ArrowRight` expand/collapse is baked into Mantine's own `TreeNode.handleKeyDown`, on the `<li>` itself, with no prop to disable it — the only reachable way to block it is a _second_, capture-phase `keydown` listener on the tree root that unconditionally calls `stopPropagation()` when disabled. Since capture fires before the event ever reaches its target (the focused `<li>`), this keeps Mantine's internal handler — and our own bubble-phase listener on the same root — from ever running, without needing to fork `TreeNode`.
   - **Visual**: `opacity: var(--recursica_brand_states_disabled)` on `.root` — the generic disabled token, same convention used everywhere else in the design system for components without a dedicated disabled token (no `tree`-specific one exists). A selected node's chip stays visible underneath, just dimmed along with everything else, per Matt's ask to verify that combination looks right.
+
+- **Chevron `Button` could still steal DOM focus despite `tabIndex={-1}` (Matt Massey, 2026-08-24), caught via a live browser console warning.** The embedded chevron `Button`'s `tabIndex={-1}`/`aria-hidden` combination (added when the chevron became a real `Button` — see above) only removes it from the sequential tab order; it doesn't stop a native `<button>` from receiving DOM focus on a direct mouse click, which browsers still do regardless of `tabIndex`. Since the button also has `aria-hidden="true"`, a click on it left an aria-hidden element holding focus — flagged by Chrome as "Blocked aria-hidden on an element because its descendant retained focus." Fixed with `onMouseDown={(event) => event.preventDefault()}` on the same `Button`: this suppresses the browser's default click-focuses-the-target behavior without affecting the `onClick` handler (`click` still fires normally on mouseup). Same fix applied to mui-adapter's `ExpandToggleButton`.

package/src/components/Tree/Tree.module.css

@@ -1,3 +1,14 @@
+/* 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_disabled
+ *   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
+ *   recursica-allow-brand: --recursica_brand_states_hover_color
+ *   recursica-allow-brand: --recursica_brand_states_hover_opacity
+ */
+
 /* HARDCODED VALUES:
  * - list-style/margin/padding resets on .root/.subtree: layout resets, no corresponding
  *   design tokens (structural, not visual design values).

package/src/components/Tree/Tree.tsx

@@ -65,12 +65,16 @@ function createRenderTreeNode(disabled: boolean) {
             row. Stops propagation so the click never also reaches `.row`'s own handler and
             selects the node. Never independently focusable/tab-stoppable (tabIndex={-1},
             aria-hidden), so the row stays the only focusable element and this button never
-            shows its own focus state. Always rendered, even for leaf nodes, so every row
-            reserves the same layout space; CSS hides it (visibility, not display) when there
-            are no children to toggle. Guards `disabled` itself (not just via the CSS
-            `pointer-events: none` on `.root`) since this handler bypasses Mantine's own
-            `expandOnClick`/`selectOnClick` flags entirely by calling `tree.toggleExpanded`
-            directly. */}
+            shows its own focus state. `onMouseDown` prevents the browser's default
+            click-focuses-the-button behavior (tabIndex={-1} only removes it from the tab
+            order, it doesn't stop a direct mouse click from focusing it) — without this, a
+            click here leaves the (aria-hidden) button focused, which browsers now flag as an
+            accessibility violation ("focus must not be hidden from assistive technology").
+            Always rendered, even for leaf nodes, so every row reserves the same layout space;
+            CSS hides it (visibility, not display) when there are no children to toggle. Guards
+            `disabled` itself (not just via the CSS `pointer-events: none` on `.root`) since this
+            handler bypasses Mantine's own `expandOnClick`/`selectOnClick` flags entirely by
+            calling `tree.toggleExpanded` directly. */}
         <Button
           overStyled
           variant="text"
@@ -80,6 +84,7 @@ function createRenderTreeNode(disabled: boolean) {
           aria-hidden="true"
           tabIndex={-1}
           className={styles.expandButton}
+          onMouseDown={(event) => event.preventDefault()}
           onClick={(event) => {
             event.stopPropagation();
             if (disabled) return;