@recursica/mui-adapter 0.31.0 → 0.32.0

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.0",
   "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/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

@@ -2,8 +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%); (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 +167,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/Tree/IMPLEMENTATION_NOTES.md

@@ -43,6 +43,9 @@
   - **MUI-only: a leftover default selected background was still showing through.** `@mui/x-tree-view`'s own `TreeItemContent` ships a built-in selected tint (`rgba(25, 118, 210, 0.08)`, and a separate, higher-specificity `rgba(25, 118, 210, 0.2)` for the `[data-selected][data-focused]` combination specifically) that the earlier `.row:hover, .row[data-focused] { background-color: transparent; }` neutralizer never covered. Added `.row[data-selected]` to that neutralizer — but the `[data-selected][data-focused]` compound needed its _own_ explicit rule too: MUI's equivalent compound selector has higher specificity (two attribute selectors plus its own class) than a single-attribute `.row[data-selected]` rule, so it kept winning regardless of source order until matched with an equally-specific `.row[data-selected][data-focused]` rule on our side.
 
 - **Whole-tree `disabled` (Matt Massey, 2026-08-10), added to support a `Disabled` story.** Unlike mantine-adapter (which has zero `disabled` concept anywhere in its `Tree` API — see its own note on this), `@mui/x-tree-view` already had per-item `disabled` plumbing sitting mostly dormant here: `CustomTreeItem` already destructured `disabled` off `UseTreeItemParameters`, and `.row[data-disabled] { opacity: ...; cursor: auto; }` already existed in `Tree.module.css` — just with no way for a caller to actually set it, since `RecursicaTreeNode` has no `disabled` field (and still doesn't; per-node disabling remains unexposed, same reasoning as the existing "Deliberately not implemented" entry above).
+
   - **Implementation**: `isItemDisabled={disabled ? () => true : undefined}` passed to `<RichTreeView>` — marking every item disabled at once, reusing the library's own per-item mechanism rather than inventing a parallel one. `interactions.handleExpansion`/`handleSelection` (used by both the icon container's click handling and our own `Enter`-key override) already check `status.disabled` internally and no-op, so nothing in `CustomTreeItem` needed an extra guard.
   - **Visual**: the pre-existing `.row[data-disabled]` rule now actually activates. Verified a pre-selected node's chip stays visible underneath the dimming (`.row[data-selected] .label` and `.row[data-disabled]` are independent, non-conflicting selectors — one styles `.label`, the other dims the whole `.row` via `opacity`), per Matt's ask to check that combination.
   - **Found while verifying**: disabled rows still showed the hover tint (`.label::after` opacity) on mouse-over — MUI's own disabled checks block the actual select/expand _action_ on click, but `:hover` is pure CSS with nothing stopping it. Added `pointer-events: none` to `.row[data-disabled]`, matching mantine-adapter's `.root[data-disabled]` (tree-wide there; per-row here, since MUI's disabled state is inherently per-item even when every item is disabled at once by the same whole-tree prop).
+
+- **`ExpandToggleButton` could still steal DOM focus despite `tabIndex={-1}` (Matt Massey, 2026-08-24), caught via a live browser console warning, in both adapters.** `tabIndex={-1}`/`aria-hidden` only removes the embedded chevron `Button` from the sequential tab order; it doesn't stop a native `<button>` from receiving DOM focus on a direct mouse click on the chevron, which browsers still do regardless of `tabIndex`. Since the button also has `aria-hidden="true"`, clicking 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 `Button` inside `ExpandToggleButton`: this suppresses the browser's default click-focuses-the-target behavior without affecting expand/collapse (still driven entirely by `TreeItemIconContainer`'s own click handling, untouched by this). Same fix applied to mantine-adapter's embedded chevron `Button`.

package/src/components/Tree/Tree.tsx

@@ -71,7 +71,12 @@ function ChevronGlyph({ rotated }: { rotated?: boolean }) {
  * not by this Button itself, so the row stays the only focusable element and the button never
  * shows its own focus state. Rendered for every row, including leaf items, so row alignment
  * stays consistent; `hidden` (visibility, not display) is used for leaf rows instead of omitting
- * the button, so the layout space is reserved without duplicating Button's own size tokens. */
+ * the button, so the layout space is reserved without duplicating Button's own size tokens.
+ * `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 on the chevron from
+ * focusing this button) — without this, clicking the chevron leaves the (aria-hidden) button
+ * focused, which browsers now flag as an accessibility violation ("focus must not be hidden from
+ * assistive technology"). */
 function ExpandToggleButton({
   rotated,
   hidden,
@@ -88,6 +93,7 @@ function ExpandToggleButton({
       aria-label="Toggle subtree"
       aria-hidden="true"
       tabIndex={-1}
+      onMouseDown={(event) => event.preventDefault()}
       className={
         hidden
           ? `${styles.expandButton} ${styles.expandButtonHidden}`