@recursica/adapter-mui-v7 1.0.0

package/src/components/Slider/Slider.tsx

@@ -0,0 +1,435 @@
+import React, { forwardRef, useState, useEffect, useRef } from "react";
+import {
+  Slider as MuiSlider,
+  type SliderProps as MuiSliderProps,
+} from "@mui/material";
+import { type ReadOnlyControlProps } from "@recursica/adapter-common";
+import {
+  filterStylingProps,
+  omitUnsupportedProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
+import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
+
+import styles from "./Slider.module.css";
+
+import { type RecursicaSliderProps as BaseRecursicaSliderProps } from "@recursica/adapter-common";
+
+export interface RecursicaSliderProps
+  extends Omit<
+      MuiSliderProps,
+      | "size"
+      | "color"
+      | "classes"
+      | "onChange"
+      | "onChangeCommitted"
+      | "value"
+      | "defaultValue"
+    >,
+    Omit<
+      RecursicaFormControlWrapperProps,
+      | "controlMaxWidth"
+      | "controlMinWidth"
+      | "error"
+      | "required"
+      | "withAsterisk"
+      | keyof MuiSliderProps
+    >,
+    ReadOnlyControlProps,
+    BaseRecursicaSliderProps {}
+
+export type SliderProps = RecursicaOverStyled<RecursicaSliderProps>;
+
+/**
+ * Custom Read-Only visual representation of the Slider value.
+ * 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 | [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.
+ */
+export const Slider = forwardRef<HTMLDivElement, SliderProps>(
+  function Slider(props, ref) {
+    const {
+      overStyled = false,
+      formLayout = "stacked",
+
+      // Label & Wrapper Maps
+      labelSize,
+      labelAlignment,
+      labelOptionalText,
+      labelWithEditIcon,
+      labelActionArea,
+      onLabelEditClick,
+
+      label,
+      tooltipLabel,
+      assistiveText,
+      assistiveWithIcon,
+      error,
+      required,
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      withAsterisk,
+      id,
+      className,
+      style,
+      disabled,
+      readOnly,
+      readOnlyComponent,
+      emptyValueComponent,
+      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. 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: 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(s) whenever the slider value changes
+    useEffect(() => {
+      setInputValue(
+        Array.isArray(resolvedValue)
+          ? [resolvedValue[0].toString(), resolvedValue[1].toString()]
+          : resolvedValue.toString(),
+      );
+    }, [resolvedValue]);
+
+    const handleValueChange = (_e: Event, val: number | number[]) => {
+      const normalized: SliderValue = Array.isArray(val)
+        ? [val[0], val[1]]
+        : val;
+      if (value === undefined) {
+        setInternalValue(normalized);
+      }
+      onChange?.(normalized);
+    };
+
+    const handleInputChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+      const valStr = e.target.value;
+      setInputValue(valStr);
+
+      const parsed = parseFloat(valStr);
+      if (!isNaN(parsed)) {
+        // Clamp input value to bounds
+        const clamped = Math.max(min, Math.min(max, parsed));
+        handleValueChange(null as unknown as Event, clamped);
+      }
+    };
+
+    const handleInputBlur = () => {
+      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
+    // through even if a caller forces them via plain JavaScript, bypassing the Omit<> above.
+    const UNSUPPORTED_PROPS = [
+      "size", // Recursica controls sizing via design tokens, not MUI's native small/medium size
+      "color", // Colors are token-driven; MUI's native palette isn't exposed
+    ] as const satisfies readonly (keyof MuiSliderProps)[];
+
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled),
+      UNSUPPORTED_PROPS,
+    );
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    // MUI always programmatically re-focuses its hidden native input on pointer interaction,
+    // which browsers' `:focus-visible` heuristic treats as keyboard-visible — unlike Mantine's
+    // plain div thumb, where a real click correctly resolves to a non-visible focus. Track
+    // pointer-vs-keyboard ourselves so the focus ring only paints for genuine keyboard focus,
+    // matching Mantine (a later keypress while still focused reveals the ring, same as native).
+    const pointerDownRef = useRef(false);
+    const [suppressFocusRing, setSuppressFocusRing] = useState(false);
+    const externalOnMouseDown = (sanitizedProps as MuiSliderProps).onMouseDown;
+    const externalOnFocus = (sanitizedProps as MuiSliderProps).onFocus;
+    const externalOnBlur = (sanitizedProps as MuiSliderProps).onBlur;
+    const externalOnKeyDown = (sanitizedProps as MuiSliderProps).onKeyDown;
+
+    const handleThumbMouseDown = (e: React.MouseEvent<HTMLSpanElement>) => {
+      pointerDownRef.current = true;
+      externalOnMouseDown?.(e);
+    };
+    const handleThumbFocus = (e: React.FocusEvent<HTMLSpanElement>) => {
+      setSuppressFocusRing(pointerDownRef.current);
+      pointerDownRef.current = false;
+      externalOnFocus?.(e);
+    };
+    const handleThumbBlur = (e: React.FocusEvent<HTMLSpanElement>) => {
+      setSuppressFocusRing(false);
+      externalOnBlur?.(e);
+    };
+    const handleThumbKeyDown = (e: React.KeyboardEvent<HTMLSpanElement>) => {
+      setSuppressFocusRing(false);
+      externalOnKeyDown?.(e);
+    };
+
+    // Securely map core native blocks down ensuring nested CSS modules map precisely. Note MUI's
+    // actual prop is "classes", not "classNames" (that's Mantine's naming) — this used to read
+    // the wrong key, silently no-op-ing any caller-supplied classes. The caller-facing slot names
+    // below (root/track/bar/thumb/mark/markLabel) mirror the mantine-adapter's own Slider
+    // classNames slots, translated to MUI's real classes slot names (root/rail/track/thumb/...).
+    const callerClasses = restRecord.classes as
+      | Partial<Record<string, string>>
+      | undefined;
+    const mergedClassNames = mergeClassNames(
+      {
+        root: styles.sliderRoot,
+        rail: styles.sliderTrack,
+        track: styles.sliderBar,
+        thumb: styles.sliderThumb,
+        mark: styles.sliderMark,
+        markLabel: styles.sliderMarkLabel,
+        valueLabel: styles.sliderTooltip,
+      },
+      callerClasses && {
+        root: callerClasses.root,
+        rail: callerClasses.track,
+        track: callerClasses.bar,
+        thumb: callerClasses.thumb,
+        mark: callerClasses.mark,
+        markLabel: callerClasses.markLabel,
+      },
+    );
+
+    const wrapperClass = className
+      ? `${styles.layoutOverride} ${className}`
+      : styles.layoutOverride;
+
+    const leadingIcon = icon ? (
+      <span className={styles.iconWrapper} aria-hidden>
+        {icon}
+      </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}
+        className={wrapperClass}
+        style={style as React.CSSProperties}
+        controlMaxWidth={undefined}
+        controlMinWidth={undefined}
+        overStyled={overStyled as true}
+        formLayout={formLayout}
+        labelSize={labelSize}
+        labelAlignment={labelAlignment}
+        labelOptionalText={labelOptionalText}
+        labelWithEditIcon={labelWithEditIcon}
+        labelActionArea={labelActionArea}
+        onLabelEditClick={onLabelEditClick}
+        label={label}
+        assistiveText={assistiveText}
+        assistiveWithIcon={assistiveWithIcon}
+        error={!!error}
+        required={required}
+        id={id}
+        readOnly={readOnly}
+        readOnlyComponent={readOnlyComponent || SliderReadOnlyValue}
+        emptyValueComponent={emptyValueComponent}
+        readOnlyType="text"
+        readOnlyValue={resolvedValue}
+        readOnlyNativeProps={{ value: resolvedValue }}
+        activeComponent={
+          <div
+            className={styles.sliderContainer}
+            data-form-layout={formLayout}
+            data-disabled={disabled ? "true" : undefined}
+            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 && (
+              <span className={styles.minMaxGuide}>{minLabel ?? min}</span>
+            )}
+
+            <div className={styles.sliderTrackWrapper}>
+              <MuiSlider
+                {...(sanitizedProps as unknown as MuiSliderProps)}
+                classes={mergedClassNames}
+                disabled={disabled}
+                value={resolvedValue}
+                onChange={handleValueChange}
+                onMouseDown={handleThumbMouseDown}
+                onFocus={handleThumbFocus}
+                onBlur={handleThumbBlur}
+                onKeyDown={handleThumbKeyDown}
+                onChangeCommitted={
+                  onChangeEnd as unknown as (
+                    event: Event | React.SyntheticEvent,
+                    value: number | number[],
+                  ) => void
+                }
+                min={min}
+                max={max}
+                step={step}
+                valueLabelDisplay={tooltipLabel === null ? "off" : "auto"}
+                valueLabelFormat={
+                  typeof tooltipLabel === "function"
+                    ? (tooltipLabel as unknown as (
+                        value: number,
+                        index: number,
+                      ) => React.ReactNode)
+                    : undefined
+                }
+              />
+            </div>
+
+            <div className={styles.rightGuideContainer}>
+              {!showInput && (
+                <span className={styles.currentValue}>{displayValue}</span>
+              )}
+              {showMinMaxLabels && (
+                <span className={styles.minMaxGuide}>{maxLabel ?? max}</span>
+              )}
+            </div>
+
+            {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>
+        }
+      />
+    );
+  },
+);
+
+Slider.displayName = "Slider";

package/src/components/Slider/USAGE.md

@@ -0,0 +1,56 @@
+# Slider - Usage Guide
+
+This document describes how to integrate and use the `Slider` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Slider } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Slider } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return <Slider defaultValue={50} min={0} max={100} label="Volume" />;
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mui-v7` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 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, 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/Slider/index.ts

@@ -0,0 +1 @@
+export * from "./Slider";

package/src/components/Stack/Stack.stories.tsx

@@ -0,0 +1,108 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Stack } from "./Stack";
+import { Button } from "../Button";
+import { Text } from "../Text/Text";
+
+type StackStoryProps = React.ComponentProps<typeof Stack>;
+
+const meta: Meta<StackStoryProps> = {
+  title: "UI-Kit/Stack",
+  component: Stack,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Stack is a flex vertical layout container that maps directly to Mantine's Stack component allowing safe layout property passing.",
+      },
+    },
+  },
+  args: {
+    spacing: "rec-default",
+    alignItems: "stretch",
+    justifyContent: "flex-start",
+  },
+  argTypes: {
+    spacing: {
+      control: "select",
+      options: [
+        "rec-none",
+        "rec-sm",
+        "rec-default",
+        "rec-md",
+        "rec-lg",
+        "rec-xl",
+        "rec-2xl",
+        "xs",
+        "sm",
+        "md",
+        "lg",
+        "xl",
+      ],
+      description: "Space between elements",
+    },
+    alignItems: {
+      control: "select",
+      options: ["flex-start", "center", "flex-end", "stretch"],
+      description: "Align-items property",
+    },
+    justifyContent: {
+      control: "select",
+      options: [
+        "flex-start",
+        "center",
+        "flex-end",
+        "space-between",
+        "space-around",
+      ],
+      description: "Justify-content property",
+    },
+    defaultChecked: {
+      table: { disable: true },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<StackStoryProps>;
+
+export const Default: Story = {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Stack {...args}>
+      <Button variant="solid">Primary Block</Button>
+      <Button variant="outline">Secondary Block</Button>
+      <Text>Text element within Stack</Text>
+    </Stack>
+  ),
+};
+
+export const StaticGapSmall: Story = {
+  args: {
+    spacing: "rec-sm",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Stack {...args}>
+      <Button variant="solid">Item 1</Button>
+      <Button variant="solid">Item 2</Button>
+      <Button variant="solid">Item 3</Button>
+    </Stack>
+  ),
+};
+
+export const StaticGapLarge: Story = {
+  args: {
+    spacing: "rec-xl",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Stack {...args}>
+      <Button variant="solid">Item 1</Button>
+      <Button variant="solid">Item 2</Button>
+      <Button variant="solid">Item 3</Button>
+    </Stack>
+  ),
+};

package/src/components/Stack/Stack.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Stack component tests. Add tests here if/when needed.

package/src/components/Stack/Stack.tsx

@@ -0,0 +1,43 @@
+/**
+ * Stack layout wrapper.
+ *
+ * MUI has a native `Stack`, so this simply passes through its own props (`direction`,
+ * `spacing`, `alignItems`, `justifyContent`, etc.) with no Recursica renaming — only
+ * `spacing` gains `rec-*` token support via `WithRecursicaSpacing`.
+ */
+import { forwardRef } from "react";
+import {
+  Stack as MUIStack,
+  type StackProps as MUIStackProps,
+} from "@mui/material";
+import {
+  SPACING_MAP,
+  type OmitSx,
+  filterSxProp,
+  type WithRecursicaSpacing,
+} from "../../utils/filterStylingProps";
+
+export type StackProps = WithRecursicaSpacing<OmitSx<MUIStackProps>>;
+
+export const Stack = forwardRef<HTMLDivElement, StackProps>(function Stack(
+  { children, spacing = "rec-default", ...rest },
+  ref,
+) {
+  const safeProps = filterSxProp(rest as Record<string, unknown>);
+  const resolvedSpacing =
+    typeof spacing === "string" && spacing in SPACING_MAP
+      ? SPACING_MAP[spacing as keyof typeof SPACING_MAP]
+      : spacing;
+
+  return (
+    <MUIStack
+      ref={ref}
+      {...(safeProps as unknown as MUIStackProps)}
+      spacing={resolvedSpacing}
+    >
+      {children}
+    </MUIStack>
+  );
+});
+
+Stack.displayName = "Stack";

package/src/components/Stack/USAGE.md

@@ -0,0 +1,41 @@
+# Stack - Usage Guide
+
+This document describes how to integrate and use the `Stack` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Stack } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Stack } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return (
+    <Stack spacing="md" alignItems="stretch">
+      <Text>Item 1</Text>
+      <Text>Item 2</Text>
+    </Stack>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mui-v7` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.

package/src/components/Stack/index.ts

@@ -0,0 +1 @@
+export * from "./Stack";