@recursica/mui-adapter 0.5.0 → 0.7.0

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

@@ -1,35 +1,173 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { Slider } from "./Slider";
-import { ComingSoon } from "@recursica/storybook-template";
+import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
 
 const meta: Meta<typeof Slider> = {
-  title: "UI-Kit/🚧 Slider",
+  title: "UI-Kit/Slider",
   component: Slider,
   tags: ["autodocs"],
   parameters: {
-    controls: {
-      include: [
-        "layer",
-        "withLayer",
-        "children",
-        "component",
-        "variant",
-        "size",
-        "icon",
-        "disabled",
-        "href",
-        "onClick",
-        "onChange",
-        "value",
-        "checked",
-      ],
+    docs: {
+      description: {
+        component: `
+The \`Slider\` component wraps Mantine's Slider to support a premium design system, a bidirectional input state, 
+custom min/max labels, step indicators, and strict states like error, disabled, and read-only.
+
+### Architecture
+The component uses Recursica's unified \`FormControlWrapper\` and \`<WithReadOnlyWrapper>\` to render consistent form layouts (stacked, side-by-side) and read-only representations.
+All visual properties map perfectly to token values inside \`Slider.module.css\`.
+`,
+      },
+    },
+  },
+  argTypes: {
+    ...formControlArgTypes,
+    disabled: {
+      control: "boolean",
+      description: "Disables both the slider track and the text input field.",
+    },
+    error: {
+      control: "text",
+      description:
+        "Places the slider in an error state with custom border/icon highlights.",
+    },
+    required: {
+      control: "boolean",
+    },
+    label: {
+      control: "text",
+      description: "Outer form control label.",
+    },
+    assistiveText: {
+      control: "text",
+      description: "Assistive text rendered below or beside the component.",
+    },
+    readOnly: {
+      control: "boolean",
+      description: "Puts the component in static read-only mode.",
+    },
+    showInput: {
+      control: "boolean",
+      description: "Controls whether the numeric input box is visible.",
+    },
+    showMinMaxLabels: {
+      control: "boolean",
+      description: "Toggles rendering of min/max labels below the track.",
     },
   },
 };
 
 export default meta;
+
 type Story = StoryObj<typeof Slider>;
 
 export const Default: Story = {
-  render: () => <ComingSoon componentName="Slider" />,
+  args: {
+    label: "Auditory Threshold",
+    assistiveText: "Specify the maximum decibel frequency boundary.",
+    defaultValue: 60,
+    min: 10,
+    max: 100,
+    step: 1,
+    showMinMaxLabels: true,
+  },
+};
+
+export const WithInputField: Story = {
+  args: {
+    ...Default.args,
+    showInput: true,
+  },
+};
+
+export const SideBySideLayout: Story = {
+  args: {
+    ...Default.args,
+    formLayout: "side-by-side",
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    label: "Decommissioned Server Node",
+    assistiveText: "Modifications to this environment are frozen.",
+    defaultValue: 35,
+    disabled: false,
+  },
+};
+
+export const ErrorState: Story = {
+  args: {
+    label: "Core Temperature Alert",
+    assistiveText:
+      "Severe core degradation across the hypervisor socket cluster.",
+    defaultValue: 85,
+    error: "Thermal overload threshold exceeded.",
+    required: true,
+  },
+};
+
+export const StaticReadOnly: Story = {
+  args: {
+    label: "System Calibration Metrics",
+    assistiveText:
+      "Frozen baseline calibrations derived during initial staging.",
+    value: 65,
+    readOnly: true,
+  },
+};
+
+export const EditableReadOnly: Story = {
+  args: {
+    label: "Adaptive Node Output",
+    assistiveText:
+      "Click edit to unlock bidirectional input parameter boundaries.",
+    defaultValue: 15,
+    readOnly: true,
+    labelWithEditIcon: true,
+  },
+};
+
+export const WithMarks: Story = {
+  args: {
+    label: "Interactive Marks Map",
+    defaultValue: 50,
+    min: 0,
+    max: 100,
+    step: 10,
+    marks: [
+      { value: 0, label: "0%" },
+      { value: 25, label: "25%" },
+      { value: 50, label: "50%" },
+      { value: 75, label: "75%" },
+      { value: 100, label: "100%" },
+    ],
+    showMinMaxLabels: false,
+  },
+};
+
+export const FormLayouts: Story = {
+  render: () => (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "2.5rem",
+        maxWidth: 600,
+      }}
+    >
+      <Slider
+        label="Stacked Layout"
+        assistiveText="This is the standard top-to-bottom stacked form layout."
+        defaultValue={40}
+        formLayout="stacked"
+      />
+      <Slider
+        label="Side-by-Side Layout"
+        assistiveText="This is the side-by-side layout aligning label beside control."
+        defaultValue={60}
+        formLayout="side-by-side"
+      />
+    </div>
+  ),
 };

package/src/components/Slider/Slider.tsx

@@ -1,8 +1,286 @@
-import React from "react";
-import "./Slider.module.css";
+import React, { forwardRef, useState, useEffect } from "react";
+import {
+  Slider as MuiSlider,
+  type SliderProps as MuiSliderProps,
+} from "@mui/material";
+import { type ReadOnlyControlProps } from "@recursica/adapter-common";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
+import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
 
-export type SliderProps = React.HTMLAttributes<HTMLDivElement>;
+import styles from "./Slider.module.css";
 
-export const Slider: React.FC<SliderProps> = (props) => {
-  return <div {...props}>Slider</div>;
+import { type RecursicaSliderProps as BaseRecursicaSliderProps } from "@recursica/adapter-common";
+
+export interface RecursicaSliderProps
+  extends Omit<
+      MuiSliderProps,
+      "size" | "color" | "classes" | "onChange" | "onChangeCommitted"
+    >,
+    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.
+ */
+const SliderReadOnlyValue: React.FC<{ value: number }> = ({ value }) => {
+  return <div className={styles.readOnlyValue}>{value}</div>;
 };
+
+/**
+ * Recursica Slider component wrapping Mui's Slider.
+ *
+ * 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.
+ */
+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,
+      showInput = false,
+      showMinMaxLabels = true,
+      min = 0,
+      max = 100,
+      step = 1,
+      onChange,
+      onChangeEnd,
+      ...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;
+      return min;
+    });
+
+    const resolvedValue =
+      value !== undefined
+        ? Array.isArray(value)
+          ? value[0]
+          : value
+        : internalValue;
+    const [inputValue, setInputValue] = useState<string>(
+      resolvedValue.toString(),
+    );
+
+    // Synchronize text input whenever the slider value changes
+    useEffect(() => {
+      setInputValue(resolvedValue.toString());
+    }, [resolvedValue]);
+
+    const handleValueChange = (_e: Event, val: number | number[]) => {
+      const singleVal = Array.isArray(val) ? val[0] : val;
+      if (value === undefined) {
+        setInternalValue(singleVal);
+      }
+      onChange?.(singleVal);
+    };
+
+    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 any, clamped);
+      }
+    };
+
+    const handleInputBlur = () => {
+      setInputValue(resolvedValue.toString());
+    };
+
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    // Delete prohibited sizing hooks from bypassing variables natively
+    delete restRecord["size"];
+    delete restRecord["color"];
+    delete restRecord["wrapperProps"];
+
+    // Securely map core native blocks down ensuring nested CSS modules map precisely
+    const mergedClassNames: Partial<Record<string, string>> = {
+      root: styles.sliderRoot,
+      rail: styles.sliderTrack,
+      track: styles.sliderBar,
+      thumb: styles.sliderThumb,
+      mark: styles.sliderMark,
+      markLabel: styles.sliderMarkLabel,
+      valueLabel: styles.sliderTooltip,
+    };
+
+    const classNamesProp = restRecord.classNames;
+    if (
+      classNamesProp &&
+      typeof classNamesProp === "object" &&
+      !Array.isArray(classNamesProp)
+    ) {
+      const o = classNamesProp as Partial<Record<string, string>>;
+      mergedClassNames.root = o.root
+        ? `${styles.sliderRoot} ${o.root}`
+        : styles.sliderRoot;
+      mergedClassNames.rail = o.track
+        ? `${styles.sliderTrack} ${o.track}`
+        : styles.sliderTrack;
+      mergedClassNames.track = o.bar
+        ? `${styles.sliderBar} ${o.bar}`
+        : styles.sliderBar;
+      mergedClassNames.thumb = o.thumb
+        ? `${styles.sliderThumb} ${o.thumb}`
+        : styles.sliderThumb;
+      mergedClassNames.mark = o.mark
+        ? `${styles.sliderMark} ${o.mark}`
+        : styles.sliderMark;
+      mergedClassNames.markLabel = o.markLabel
+        ? `${styles.sliderMarkLabel} ${o.markLabel}`
+        : styles.sliderMarkLabel;
+    }
+
+    const wrapperClass = className
+      ? `${styles.layoutOverride} ${className}`
+      : styles.layoutOverride;
+
+    const leadingIcon = icon ? (
+      <span className={styles.iconWrapper} aria-hidden>
+        {icon}
+      </span>
+    ) : null;
+
+    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 as any}
+        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}
+          >
+            {leadingIcon}
+
+            {showMinMaxLabels && (
+              <span className={styles.minMaxGuide}>{min}</span>
+            )}
+
+            <div className={styles.sliderTrackWrapper}>
+              <MuiSlider
+                classes={mergedClassNames}
+                disabled={disabled}
+                value={resolvedValue}
+                onChange={handleValueChange}
+                onChangeCommitted={onChangeEnd as any}
+                min={min}
+                max={max}
+                step={step}
+                valueLabelDisplay={tooltipLabel === null ? "off" : "auto"}
+                valueLabelFormat={
+                  typeof tooltipLabel === "function"
+                    ? (tooltipLabel as any)
+                    : undefined
+                }
+                {...(sanitizedProps as unknown as MuiSliderProps)}
+              />
+            </div>
+
+            <div className={styles.rightGuideContainer}>
+              {!showInput && (
+                <span className={styles.currentValue}>{resolvedValue}</span>
+              )}
+              {showMinMaxLabels && (
+                <span className={styles.minMaxGuide}>{max}</span>
+              )}
+            </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}
+              />
+            )}
+          </div>
+        }
+      />
+    );
+  },
+);
+
+Slider.displayName = "Slider";

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

@@ -17,32 +17,11 @@ const meta: Meta<StackStoryProps> = {
           "Stack is a flex vertical layout container that maps directly to Mantine's Stack component allowing safe layout property passing.",
       },
     },
-    controls: {
-      include: [
-        "layer",
-        "withLayer",
-        "gap",
-        "alignItems",
-        "justifyContent",
-        "defaultChecked",
-        "children",
-        "component",
-        "variant",
-        "size",
-        "icon",
-        "disabled",
-        "href",
-        "onClick",
-        "onChange",
-        "value",
-        "checked",
-      ],
-    },
   },
   args: {
     gap: "rec-default",
-    alignItems: "stretch",
-    justifyContent: "flex-start",
+    align: "stretch",
+    justify: "flex-start",
   },
   argTypes: {
     gap: {
@@ -63,12 +42,12 @@ const meta: Meta<StackStoryProps> = {
       ],
       description: "Gap between elements",
     },
-    alignItems: {
+    align: {
       control: "select",
       options: ["flex-start", "center", "flex-end", "stretch"],
       description: "Align-items property",
     },
-    justifyContent: {
+    justify: {
       control: "select",
       options: [
         "flex-start",

package/src/components/Stack/Stack.tsx

@@ -4,16 +4,12 @@ import {
   type StackProps as MUIStackProps,
 } from "@mui/material";
 import {
-  type RecursicaSpacing,
   SPACING_MAP,
   type OmitSx,
   filterSxProp,
 } from "../../utils/filterStylingProps";
 
-export interface RecursicaStackProps {
-  children?: React.ReactNode;
-  gap?: MUIStackProps["spacing"] | RecursicaSpacing;
-}
+import { type RecursicaStackProps } from "@recursica/adapter-common";
 
 export type StackProps = OmitSx<
   Omit<MUIStackProps, "spacing"> & RecursicaStackProps

package/src/components/Stepper/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,4 @@
+# Stepper Implementation Notes
+
+- **Compositional API Dropped:** Mantine manages stepper state and content via `<Stepper.Step>` and `<Stepper.Completed>`. MUI delegates content rendering to the developer and focuses purely on the stepper visual layout using `<Step>`, `<StepLabel>`, etc.
+- **Monolithic API Adopted:** Following architectural review, we have abandoned the fabricated context wrappers for `mui-adapter`. We now natively export `Stepper`, `Step`, `StepLabel`, `StepButton`, and `StepConnector` wrapping their `@mui/material` counterparts. Developers are expected to manage the active step logic and content rendering outside the `Stepper` component, consistent with MUI patterns. Storybook tests have been updated to reflect this divergence while retaining core visual compatibility.