@recursica/mantine-adapter 0.46.0 → 0.48.0

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mantine-adapter"
   },
-  "version": "0.46.0",
+  "version": "0.48.0",
   "type": "module",
   "main": "./dist/mantine-adapter.cjs",
   "module": "./dist/mantine-adapter.js",
@@ -94,7 +94,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@recursica/adapter-common": "^0.21.0",
+    "@recursica/adapter-common": "^0.23.0",
     "@recursica/official-release": "^2.8.0"
   },
   "peerDependencies": {

package/src/components/Slider/IMPLEMENTATION_NOTES.md

@@ -57,3 +57,36 @@ This document contains specific design decisions, architectural constraints, and
 - The thumb's focus box-shadow layers the ring on top of its existing `thumb-elevation` shadow rather than replacing it.
 - `.sliderMark[data-filled]` has no default-state "-active" step-indicator token anymore (only `disabled`/`error` define one); it reuses `colors_track-active` so filled marks stay visually tied to the filled portion of the track. Worth a design review if a distinct filled-mark color is expected.
 - `markLabel` was already mapped in the `classNames` prop but had no matching `.sliderMarkLabel` rule in this file, so Mantine silently fell back to its own default theme grey instead of any recursica token. Added a `.sliderMarkLabel` rule reusing the min-max-label typography tokens with `color: inherit`, matching the mui-adapter's equivalent.
+
+## 7. Formatted Current Value, Label Overrides, Trailing Icon
+
+**Decision:** The floating `.currentValue` display (see §5) always rendered the raw numeric value, even when `tooltipLabel` was a formatter function — a caller mapping values onto custom text (e.g. 0-4 → XS/S/M/L/XL) got the formatted tooltip while dragging but the raw number next to the track otherwise.
+**Implementation:**
+
+- `.currentValue` now runs `resolvedValue` through `tooltipLabel` when it's a function, so both displays agree. No change when `tooltipLabel` is absent or a static node — still the raw number.
+- `minLabel`/`maxLabel` (new `adapter-common` props) override the `.minMaxGuide` text at either end of the track, falling back to the numeric `min`/`max`.
+- `trailingIcon` (new `adapter-common` prop) renders a second icon on the opposite side of the track from the existing `icon`, reusing the same `.iconWrapper` styling (disabled/error/focus states already target `.iconWrapper` generically, so no new CSS was needed).
+
+## 8. Dual-Thumb / Range Support
+
+**Decision:** Previously requested and declined (see git history for this section) as no use case needed it; reopened with a full spec and implemented. `value`/`defaultValue`/`onChange`/`onChangeEnd` are now typed `number | [number, number]` in `@recursica/adapter-common`'s `RecursicaSliderProps`.
+**Implementation:**
+
+- `isRange = Array.isArray(resolvedValue)` picks which underlying Mantine component to render: single-thumb `Slider` (unchanged) or two-thumb `RangeSlider` — Mantine ships these as two separate components (unlike raw MUI, which renders two thumbs off a single `Slider` given a tuple `value`), so this is a real component swap, not just a type/prop change. Both share the same `SliderStylesNames` shape, so `mergedClassNames` (root/track/bar/thumb/mark/markLabel) applies unchanged to either.
+- Internal state (`internalValue`, `resolvedValue`, `inputValue`) generalized from `number` to `number | [number, number]`; range-mode input handlers (`handleLowerInputChange`/`handleUpperInputChange`) clamp each thumb against the other's current value (not the shared `min`/`max`) so the two inputs can't cross.
+- `SliderReadOnlyValue` and the floating `.currentValue` display both render `"lower – upper"` for a range value, running each side through `tooltipLabel` independently when it's a formatter.
+- DOM order in range mode (input → leading icon → min label → track → max label → trailing icon → input) mirrors Forge's own Material/Carbon range layouts — see §9 below.
+- Not carried over: Mantine `RangeSlider`'s own `minRange`/`maxRange`/`pushOnOverlap`/`thumbFromLabel`/`thumbToLabel` pass through via the existing unsanitized `...rest` spread if a caller sets them directly; no adapter-level default is applied (e.g. Mantine's own `minRange` default of `10` is left as-is).
+
+## 9. Trailing Icon Order Relative to the Input Field
+
+**Decision:** `trailingIcon` previously rendered after the numeric input (`... max label, input, trailing icon`), reversed from Forge's Material/Carbon kits, which always render the trailing icon directly after the max label and before the input.
+**Implementation:** Moved `{trailingIconEl}` before the `showInput` input block in the single-value layout; the range layout was built with this order from the start (input → icon → min label → track → max label → trailing icon → input).
+
+## 10. Marks Rendering Off Mantine Defaults Instead of Recursica Tokens
+
+**Decision:** §3 claimed marks were "fully styles-mapped back to our scoped variables" — not quite true. Mantine's `markWrapper` style slot (the zero-height, top-anchored positioning wrapper around each mark dot + label) was never mapped in `mergedClassNames`, and `markLabel`'s vertical position was never overridden, so both stayed on raw Mantine defaults.
+**Implementation:**
+
+- `markWrapper` is anchored to Mantine's own `top: 0` (the track's top edge), with the mark dot inside it unpositioned. Mantine's own dot has no size override so it happens to fill the track height exactly by default; our `step-indicator-width` token is independent of track height, so the dot rendered small and flush to the top instead of centered. Added `markWrapper: styles.sliderMarkWrapper` to `mergedClassNames`, with `.sliderMarkWrapper { top: 50%; }`, and changed `.sliderMark`'s transform from `translateX(-50%)` to `translate(-50%, -50%)` to center the dot on that midpoint.
+- `.sliderMarkLabel` never overrode `transform`, so its vertical offset stayed Mantine's own `calc(var(--mantine-spacing-xs) / 2)` — an unbound theme default, not a recursica token. Replaced the vertical term with `--recursica_ui-kit_globals_form_properties_label-field-gap-vertical` (the same token the mui-adapter's markLabel already uses), keeping the horizontal term (`-50% + var(--slider-size) / 2`, Mantine's own mark-offset compensation) unchanged.

package/src/components/Slider/Slider.module.css

@@ -2,7 +2,11 @@
  * HARDCODED VALUES:
  * - display: flex; align-items: center; width: 100%; (Standard CSS flexbox layouts for bidirectional components)
  * - flex-grow: 1; flex-shrink: 0; (Layout control structures)
- * - transform: translateX(-50%); (Mantine's standard step marks positioning alignment offset)
+ * - transform: translate(-50%, -50%); (custom step-mark centering offset — see .sliderMarkWrapper
+ *   / .sliderMark below; not inherited from Mantine, which centers marks via its own
+ *   --slider-size variable that our step-indicator-width token doesn't participate in)
+ * - top: 50%; on .sliderMarkWrapper (re-anchors Mantine's zero-height mark wrapper to the
+ *   track's vertical midpoint instead of its top edge)
  * - outline: none; border-style: solid; (Standard focus reset and border outlines)
  * - Focus ring on thumb/icon/input: the token schema no longer provides per-component focus
  *   colors for these (only `active` covers track/step-indicator-color). We apply the generic
@@ -109,6 +113,18 @@
       var(--recursica_brand_states_focus_color);
 }
 
+/*
+ * Mantine positions the mark dot inside a zero-height `markWrapper` anchored to the track's
+ * top edge, relying on the dot's height matching Mantine's own `--slider-size` to land centered.
+ * Our step-indicator-width token is independent of that, so without an explicit vertical
+ * transform the dot sits flush to the track's top instead of centered. `sliderMarkWrapper`
+ * moves the anchor to the track's vertical midpoint; `translate(-50%, -50%)` below centers the
+ * dot on that midpoint (in addition to the pre-existing horizontal centering).
+ */
+.sliderMarkWrapper {
+  top: 50%;
+}
+
 .sliderMark {
   box-sizing: border-box;
   width: var(
@@ -123,7 +139,7 @@
   background-color: var(
     --recursica_ui-kit_components_slider_properties_colors_step-indicator-color
   );
-  transform: translateX(-50%);
+  transform: translate(-50%, -50%);
   border: none;
 }
 
@@ -139,8 +155,18 @@
  * Mantine's default markLabel has no dedicated recursica token; it renders with Mantine's own
  * theme grey instead of inheriting the container text color. Reusing the min-max-label
  * typography tokens and inheriting color keeps this visually consistent with the min/max guides.
+ *
+ * The vertical gap between mark and label is also Mantine's own default (half of
+ * --mantine-spacing-xs, unbound to any recursica token) unless overridden here. The transform's
+ * horizontal term (`-50% + var(--slider-size) / 2`) is Mantine's own mark-offset compensation
+ * and is left untouched; only the vertical term is replaced with the same label-field gap token
+ * the mui-adapter's markLabel already uses, for cross-adapter consistency.
  */
 .sliderMarkLabel {
+  transform: translate(
+    calc(-50% + var(--slider-size) / 2),
+    var(--recursica_ui-kit_globals_form_properties_label-field-gap-vertical)
+  );
   color: inherit;
 
   font-family: var(

package/src/components/Slider/Slider.stories.tsx

@@ -146,6 +146,115 @@ export const WithMarks: Story = {
   },
 };
 
+export const WithIconsAndLabels: Story = {
+  args: {
+    label: "Volume",
+    assistiveText:
+      "Icons flank the track; min/max labels replace the raw bounds.",
+    defaultValue: 60,
+    minLabel: "Quiet",
+    maxLabel: "Loud",
+    tooltipLabel: (value: number) => `${value}%`,
+    icon: (
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="16"
+        height="16"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <polygon points="11 5 6 9 2 9 2 15 6 15 11 19 11 5"></polygon>
+      </svg>
+    ),
+    trailingIcon: (
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="16"
+        height="16"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <polygon points="11 5 6 9 2 9 2 15 6 15 11 19 11 5"></polygon>
+        <path d="M15.54 8.46a5 5 0 0 1 0 7.07"></path>
+        <path d="M19.07 4.93a10 10 0 0 1 0 14.14"></path>
+      </svg>
+    ),
+  },
+};
+
+export const RangeMode: Story = {
+  args: {
+    label: "Price Range",
+    assistiveText: "Pass a [number, number] tuple to render two thumbs.",
+    defaultValue: [20, 80],
+    min: 0,
+    max: 100,
+    showMinMaxLabels: true,
+  },
+};
+
+export const RangeModeWithInputs: Story = {
+  args: {
+    ...RangeMode.args,
+    showInput: true,
+  },
+};
+
+export const RangeModeWithIconsAndInputs: Story = {
+  args: {
+    label: "Price Range",
+    assistiveText:
+      "Full range usage: leading/trailing icons, min/max label overrides, and both bound inputs.",
+    defaultValue: [20, 80],
+    min: 0,
+    max: 100,
+    showInput: true,
+    minLabel: "$0",
+    maxLabel: "$100",
+    tooltipLabel: (value: number) => `$${value}`,
+    icon: (
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="16"
+        height="16"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <polygon points="11 5 6 9 2 9 2 15 6 15 11 19 11 5"></polygon>
+      </svg>
+    ),
+    trailingIcon: (
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="16"
+        height="16"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <polygon points="11 5 6 9 2 9 2 15 6 15 11 19 11 5"></polygon>
+        <path d="M15.54 8.46a5 5 0 0 1 0 7.07"></path>
+        <path d="M19.07 4.93a10 10 0 0 1 0 14.14"></path>
+      </svg>
+    ),
+  },
+};
+
 export const FormLayouts: Story = {
   render: () => (
     <div

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,17 +47,23 @@ 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, an optional leading icon, and an explicit read-only layout.
+ * custom typography-bound min/max labels (optionally overridden via `minLabel`/`maxLabel`),
+ * optional leading/trailing icons, and an explicit read-only layout.
  */
 export const Slider = forwardRef<HTMLDivElement, SliderProps>(
   function Slider(props, ref) {
@@ -84,34 +96,51 @@ export const Slider = forwardRef<HTMLDivElement, SliderProps>(
       value,
       defaultValue,
       icon,
+      trailingIcon,
       showInput = false,
       showMinMaxLabels = true,
       min = 0,
       max = 100,
+      minLabel,
+      maxLabel,
       step = 1,
       onChange,
       onChangeEnd,
       ...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);
       }
@@ -132,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
@@ -160,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,
       },
@@ -176,6 +237,23 @@ export const Slider = forwardRef<HTMLDivElement, SliderProps>(
       </span>
     ) : null;
 
+    const trailingIconEl = trailingIcon ? (
+      <span className={styles.iconWrapper} aria-hidden>
+        {trailingIcon}
+      </span>
+    ) : null;
+
+    // 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.
+    // 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;
+
     return (
       <WithReadOnlyWrapper
         ref={ref}
@@ -211,50 +289,98 @@ 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 && (
-              <span className={styles.minMaxGuide}>{min}</span>
+              <span className={styles.minMaxGuide}>{minLabel ?? min}</span>
             )}
 
             <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}>
               {!showInput && (
-                <span className={styles.currentValue}>{resolvedValue}</span>
+                <span className={styles.currentValue}>{displayValue}</span>
               )}
               {showMinMaxLabels && (
-                <span className={styles.minMaxGuide}>{max}</span>
+                <span className={styles.minMaxGuide}>{maxLabel ?? max}</span>
               )}
             </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.
+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/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.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;