@recursica/mui-adapter 0.31.0 → 0.32.1

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mui-adapter"
   },
-  "version": "0.31.0",
+  "version": "0.32.1",
   "publishConfig": {
     "access": "public"
   },
@@ -102,7 +102,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@recursica/adapter-common": "^0.22.0",
+    "@recursica/adapter-common": "^0.23.0",
     "@recursica/official-release": "^2.8.0",
     "dayjs": "^1.11.21"
   },

package/src/components/Accordion/Accordion.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_disabled
+ *   recursica-allow-brand: --recursica_brand_states_hover_color
+ *   recursica-allow-brand: --recursica_brand_states_hover_opacity
+ */
+
 /* ==== ACCORDION CONTAINER ==== */
 .root {
   box-sizing: border-box;

package/src/components/Autocomplete/Autocomplete.module.css

@@ -1,3 +1,13 @@
+/* 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
+ *   recursica-allow-brand: --recursica_brand_states_hover_color
+ *   recursica-allow-brand: --recursica_brand_states_hover_opacity
+ */
+
 /* LAYOUT SPACING OVERRIDES:
    - Sets the --form-control-margin-bottom spacing hook to map component-specific layout tokens.
    - Also sets the --autocomplete-control-{max,min}-width hooks consumed inline in Autocomplete.tsx,

package/src/components/Button/Button.module.css

@@ -1,3 +1,13 @@
+/* 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
+ *   recursica-allow-brand: --recursica_brand_states_hover_color
+ *   recursica-allow-brand: --recursica_brand_states_hover_opacity
+ */
+
 /* Baseline and Reset */
 .root {
   box-sizing: border-box;

package/src/components/Card/Card.stories.tsx

@@ -37,8 +37,7 @@ export const Default: Story = {
       <div
         style={{
           padding: "48px",
-          backgroundColor:
-            "var(--recursica_brand_palettes_neutral_050_color_tone)",
+          backgroundColor: "#e9ecef",
         }}
       >
         <Layer layer={0}>
@@ -73,8 +72,7 @@ export const HeaderlessAndFooterless: Story = {
       <div
         style={{
           padding: "48px",
-          backgroundColor:
-            "var(--recursica_brand_palettes_neutral_050_color_tone)",
+          backgroundColor: "#e9ecef",
         }}
       >
         <Layer layer={0}>

package/src/components/Chip/Chip.module.css

@@ -1,3 +1,12 @@
+/* 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
+ */
+
 /* HARDCODED VALUES
    border-style: solid;  (Baseline reset)
    box-sizing: border-box; (Baseline reset)

package/src/components/DatePicker/DatePicker.module.css

@@ -1,3 +1,16 @@
+/* Brand-layer exemptions (recursica-allow-brand) — see recursica-token-analyzer README.md.
+ * No ui-kit_components_date-picker radius token exists for the calendar day cells; reuses the brand default border-radius.
+ *   recursica-allow-brand: --recursica_brand_dimensions_border-radii_default
+ * 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:
    - border-style: solid. Native structural rendering rule.
    - outline: none. Bypassing browser focus rings to rely strictly on Recursica focus states natively.

package/src/components/Dropdown/Dropdown.module.css

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

package/src/components/FileInput/FILEINPUT_IMPLEMENTATION_NOTES.md

@@ -136,7 +136,10 @@ roving group, _then_ the trailing clear button as its own stop.
 wraps onto multiple lines below the dropzone — `FileInput` is a fixed single-line, `min-height`d
 control, so wrapping would grow it vertically. Enough chips to overflow the control's own width
 scroll horizontally within it instead (mouse wheel/trackpad or a native scrollbar), same tradeoff
-already made for `.value`'s ellipsis truncation.
+already made for `.value`'s ellipsis truncation. The native scrollbar itself is hidden
+(`scrollbar-width: none`, `-ms-overflow-style: none`, `::-webkit-scrollbar { display: none }`) —
+the control's `min-height` isn't tall enough to host a visible horizontal scrollbar without
+clipping the chips, and scrolling (wheel/trackpad/drag) still works with it hidden.
 
 ## Read-only vs disabled
 

package/src/components/FileInput/FileInput.module.css

@@ -1,3 +1,13 @@
+/* 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
+ *   recursica-allow-brand: --recursica_brand_states_hover_color
+ *   recursica-allow-brand: --recursica_brand_states_hover_opacity
+ */
+
 /* LAYOUT SPACING OVERRIDES:
    - Sets the --form-control-margin-bottom spacing hook to map component-specific layout tokens.
    - Also sets the --file-input-control-{max,min}-width hooks consumed inline in FileInput.tsx,
@@ -178,6 +188,13 @@
   overflow-x: auto;
   overflow-y: hidden;
   gap: var(--recursica_ui-kit_components_file-input_properties_icon-text-gap);
+  /* HARDCODE: scrollbar stays functional (still scrolls via wheel/trackpad/drag) but hidden —
+     the control isn't tall enough to host a visible scrollbar without clipping the chips. */
+  scrollbar-width: none; /* Firefox */
+  -ms-overflow-style: none; /* legacy Edge */
+}
+.chipRow::-webkit-scrollbar {
+  display: none; /* Chrome, Safari */
 }
 
 .chipWrapper {

package/src/components/FileUpload/FileUpload.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:
    - .root: display: flex; flex-direction: column; width: 100% — structural layout, not a design
      token concern (matches how other block-level components like Layer are laid out).

package/src/components/Link/Link.module.css

@@ -1,3 +1,8 @@
+/* Brand-layer exemptions (recursica-allow-brand) — see recursica-token-analyzer README.md.
+ * Only source for link hover-underline; no per-component token exists (see IMPLEMENTATION_NOTES.md).
+ *   recursica-allow-brand: --recursica_brand_states_link_decoration
+ */
+
 /*
 HARDCODED VALUES:
 - display: inline-flex; (Base layout to align icon and text correctly)

package/src/components/Menu/Menu.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-style: solid. Structural rendering rule for the dropdown border (Mantine uses Paper which may not set border natively).
    - NOTE: overflow is intentionally NOT set on .dropdown. Mantine renders sub-menu dropdowns

package/src/components/NumberInput/NumberInput.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 --number-input-control-{max,min}-width hooks consumed inline in NumberInput.tsx,

package/src/components/Pagination/Pagination.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_disabled
+ *   recursica-allow-brand: --recursica_brand_states_hover_color
+ *   recursica-allow-brand: --recursica_brand_states_hover_opacity
+ */
+
 .root {
   display: flex;
   align-items: center;

package/src/components/Slider/IMPLEMENTATION_NOTES.md

@@ -34,6 +34,22 @@ This document contains specific design decisions, architectural constraints, and
 
 **Fix:** `.currentValue` now runs `resolvedValue` through `tooltipLabel` when it's a function, reusing the same formatter passed to `valueLabelFormat`. Added `minLabel`/`maxLabel` (new `adapter-common` props) to override the `.minMaxGuide` text at either end of the track, and `trailingIcon` (new `adapter-common` prop) to render a second icon opposite the existing `icon`, reusing the same `.iconWrapper` styling.
 
-## 6. No Dual-Thumb / Range Support
+## 6. Dual-Thumb / Range Support
 
-**Decision:** Requested (MUI's `Slider` already accepts `number[]` for `value`/`onChange` and renders multiple thumbs natively), declined — no current use case needs it. `Slider` stays single-thumb only; `value`/`onChange` remain typed as `number` and arrays continue to be collapsed to `value[0]`.
+**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:**
+
+- MUI's `Slider` already accepts `number[]` for `value`/`onChange` and renders two thumbs natively, so unlike `mantine-adapter` (which must swap to a separate `RangeSlider` component) this stays the same `<MuiSlider>` — arrays are no longer collapsed to `value[0]`.
+- 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 (`valueLabelFormat` already handled this per-thumb natively, unchanged).
+- 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 §7 below.
+
+## 7. 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).
+
+## 8. Mark Vertically Off-Center
+
+**Decision:** MUI's own mark is `top: 50%; transform: translate(-1px, -50%)` — the `-1px` assumes MUI's built-in 2px dot, the `-50%` is real vertical centering. `.sliderMark` overrode `transform` to `translateX(-50%)` (horizontal-only, meant to mirror the mantine-adapter) without noticing it dropped MUI's vertical `-50%`, leaving the dot hanging below the track's midpoint instead of centered.
+**Implementation:** Changed `.sliderMark`'s transform to `translate(-50%, -50%)` — keeps MUI's vertical centering and swaps the horizontal term to properly center our (non-2px) `step-indicator-width` instead of MUI's hardcoded 1px.

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

@@ -1,9 +1,20 @@
+/* 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:
  * - 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%); (Step marks/mark labels positioning alignment offset, matching
- *   Mantine's own offset mechanism)
+ * - transform: translate(-50%, -50%); on .sliderMark (preserves MUI's own vertical mark
+ *   centering while re-deriving the horizontal offset for our step-indicator-width token — see
+ *   .sliderMark below)
+ * - transform: translateX(-50%); on .sliderMarkLabel (horizontal-only; matches Mantine's offset
+ *   mechanism)
  * - outline: none; border-style: solid; (Standard focus reset and border outlines)
  * - Focus ring on thumb/input: the token schema no longer provides per-component focus
  *   colors for these (only `active` covers track/step-indicator-color). We apply the generic
@@ -164,7 +175,13 @@
   background-color: var(
     --recursica_ui-kit_components_slider_properties_colors_step-indicator-color
   );
-  transform: translateX(-50%);
+  /* MUI's own mark is `top: 50%; transform: translate(-1px, -50%)` — the -1px assumes its
+     built-in 2px-wide dot and the -50% is real vertical centering, not decoration. Overriding
+     width/height above without preserving that vertical -50% would leave the dot vertically
+     un-centered (it would hang below the track's midpoint); translateX(-50%) alone stomped it.
+     translate(-50%, -50%) keeps the vertical centering and swaps the horizontal offset to match
+     our (non-2px) step-indicator-width. */
+  transform: translate(-50%, -50%);
   border: none;
 }
 

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

@@ -190,6 +190,71 @@ export const WithIconsAndLabels: Story = {
   },
 };
 
+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

@@ -20,7 +20,13 @@ import { type RecursicaSliderProps as BaseRecursicaSliderProps } from "@recursic
 export interface RecursicaSliderProps
   extends Omit<
       MuiSliderProps,
-      "size" | "color" | "classes" | "onChange" | "onChangeCommitted"
+      | "size"
+      | "color"
+      | "classes"
+      | "onChange"
+      | "onChangeCommitted"
+      | "value"
+      | "defaultValue"
     >,
     Omit<
       RecursicaFormControlWrapperProps,
@@ -38,15 +44,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 Mui's Slider.
  *
+ * MUI's own `Slider` already renders two thumbs natively when given a tuple `value`, so range
+ * mode here is a typing/handler concern rather than a different underlying component (contrast
+ * with the mantine-adapter, which swaps in Mantine's separate `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`),
  * optional leading/trailing icons, and an explicit read-only layout.
@@ -96,35 +110,45 @@ 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>(() => {
-      if (value !== undefined) return Array.isArray(value) ? value[0] : value;
-      if (defaultValue !== undefined)
-        return Array.isArray(defaultValue) ? defaultValue[0] : defaultValue;
+    // 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 — MUI's own Slider already renders two thumbs for a tuple value.
+    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
-        ? Array.isArray(value)
-          ? value[0]
-          : 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 = (_e: Event, val: number | number[]) => {
-      const singleVal = Array.isArray(val) ? val[0] : val;
+      const normalized: SliderValue = Array.isArray(val)
+        ? [val[0], val[1]]
+        : val;
       if (value === undefined) {
-        setInternalValue(singleVal);
+        setInternalValue(normalized);
       }
-      onChange?.(singleVal);
+      onChange?.(normalized);
     };
 
     const handleInputChange = (e: React.ChangeEvent<HTMLInputElement>) => {
@@ -140,7 +164,38 @@ export const Slider = forwardRef<HTMLDivElement, SliderProps>(
     };
 
     const handleInputBlur = () => {
-      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(null as unknown as Event, [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(null as unknown as Event, [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
@@ -232,8 +287,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;
 
@@ -272,6 +331,22 @@ export const Slider = forwardRef<HTMLDivElement, SliderProps>(
             data-error={error ? "true" : undefined}
             data-suppress-focus-ring={suppressFocusRing ? "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 ?? undefined}
+                disabled={disabled}
+                data-error={error ? "true" : undefined}
+                aria-label="Minimum value"
+              />
+            )}
+
             {leadingIcon}
 
             {showMinMaxLabels && (
@@ -319,22 +394,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 ?? undefined}
-                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 ?? undefined}
+                  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 ?? undefined}
+                  disabled={disabled}
+                  data-error={error ? "true" : undefined}
+                />
+              ))}
           </div>
         }
       />

package/src/components/Slider/USAGE.md

@@ -39,4 +39,18 @@ All Recursica components in the `@recursica/mui-adapter` package adhere strictly
 
 ## 4. Key Integration Features & Constraints
 
-The `label` prop is passed through to the surrounding form label rather than MUI'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 MUI'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`. 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)