@recursica/mantine-adapter 0.22.0 → 0.24.0

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

@@ -1,12 +1,60 @@
 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"],
-  argTypes: {},
+  parameters: {
+    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;
@@ -14,5 +62,112 @@ 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,7 +1,278 @@
-import React from "react";
+import React, { forwardRef, useState, useEffect } from "react";
+import {
+  Slider as MantineSlider,
+  type SliderProps as MantineSliderProps,
+  type InputWrapperProps,
+} from "@mantine/core";
+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<
+      MantineSliderProps,
+      | "size"
+      | "variant"
+      | "radius"
+      | "wrapperProps"
+      | "classNames"
+      | "styles"
+      | "label"
+    >,
+    Omit<
+      RecursicaFormControlWrapperProps,
+      "controlMaxWidth" | "controlMinWidth"
+    >,
+    Pick<InputWrapperProps, "error" | "required" | "withAsterisk">,
+    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 Mantine'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,
+      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 value;
+      if (defaultValue !== undefined) return defaultValue;
+      return min;
+    });
+
+    const resolvedValue = value !== undefined ? value : internalValue;
+    const [inputValue, setInputValue] = useState<string>(
+      resolvedValue.toString(),
+    );
+
+    // Synchronize text input whenever the slider value changes
+    useEffect(() => {
+      setInputValue(resolvedValue.toString());
+    }, [resolvedValue]);
+
+    const handleValueChange = (val: number) => {
+      if (value === undefined) {
+        setInternalValue(val);
+      }
+      onChange?.(val);
+    };
+
+    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(clamped);
+      }
+    };
+
+    const handleInputBlur = () => {
+      // Clean up text field on blur to reflect the final clamped resolved value
+      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["variant"];
+    delete restRecord["radius"];
+    delete restRecord["wrapperProps"];
+
+    // Securely map core native blocks down ensuring nested CSS modules map precisely
+    const mergedClassNames: Partial<Record<string, string>> = {
+      root: styles.sliderRoot,
+      track: styles.sliderTrack,
+      bar: styles.sliderBar,
+      thumb: styles.sliderThumb,
+      mark: styles.sliderMark,
+      markLabel: styles.sliderMarkLabel,
+    };
+
+    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.track = o.track
+        ? `${styles.sliderTrack} ${o.track}`
+        : styles.sliderTrack;
+      mergedClassNames.bar = 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}
+        required={required}
+        withAsterisk={withAsterisk}
+        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}>
+              <MantineSlider
+                classNames={mergedClassNames}
+                disabled={disabled}
+                value={resolvedValue}
+                onChange={handleValueChange}
+                onChangeEnd={onChangeEnd}
+                min={min}
+                max={max}
+                step={step}
+                label={tooltipLabel}
+                {...(sanitizedProps as unknown as MantineSliderProps)}
+              />
+            </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}
+                disabled={disabled}
+                data-error={error ? "true" : undefined}
+              />
+            )}
+          </div>
+        }
+      />
+    );
+  },
+);
+
+Slider.displayName = "Slider";

package/src/components/Stack/Stack.tsx

@@ -4,19 +4,10 @@ import {
   type StackProps as MantineStackProps,
   createPolymorphicComponent,
 } from "@mantine/core";
-import {
-  type RecursicaSpacing,
-  mapLayoutProps,
-} from "../../utils/filterStylingProps";
+import { mapLayoutProps } from "../../utils/filterStylingProps";
 import styles from "./Stack.module.css";
 
-export interface RecursicaStackProps {
-  /**
-   * Children components inside the stack
-   */
-  children?: React.ReactNode;
-  gap?: MantineStackProps["gap"] | RecursicaSpacing;
-}
+import { type RecursicaStackProps } from "@recursica/adapter-common";
 
 /**
  * Stack flex layout wrapper.

package/src/components/Stepper/Stepper.tsx

@@ -9,13 +9,7 @@ import {
 } from "../../utils/filterStylingProps";
 import styles from "./Stepper.module.css";
 
-export interface RecursicaStepperProps
-  extends Omit<
-    MantineStepperProps,
-    "size" | "color" | "radius" | "iconSize" | "contentPadding"
-  > {
-  size?: "small" | "large";
-}
+import { type RecursicaStepperProps } from "@recursica/adapter-common";
 
 export type StepperProps = RecursicaOverStyled<RecursicaStepperProps>;
 

package/src/components/Switch/Switch.tsx

@@ -11,7 +11,10 @@ import {
   filterStylingProps,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
-import { type RequireAccessibleLabel } from "../../utils/RequireAccessibleLabel";
+import {
+  type RequireAccessibleLabel,
+  type RecursicaSwitchProps,
+} from "@recursica/adapter-common";
 import {
   FormControlLayout,
   type FormControlLayoutProps,
@@ -20,16 +23,21 @@ import styles from "./Switch.module.css";
 
 import { SwitchGroup } from "./SwitchGroup";
 
-export type RecursicaSwitchProps = RequireAccessibleLabel<
-  Omit<MantineSwitchProps, "size" | "color" | "radius" | "variant"> &
-    ReadOnlyControlProps &
-    Pick<
-      FormControlLayoutProps,
-      "formLayout" | "labelSize" | "controlMaxWidth" | "controlMinWidth"
-    >
->;
-
-export type SwitchProps = RecursicaOverStyled<RecursicaSwitchProps>;
+export type SwitchWrapperProps = Omit<
+  MantineSwitchProps,
+  "size" | "color" | "radius" | "variant"
+> &
+  RecursicaSwitchProps &
+  ReadOnlyControlProps &
+  Pick<
+    FormControlLayoutProps,
+    "formLayout" | "labelSize" | "controlMaxWidth" | "controlMinWidth"
+  >;
+
+export type RecursicaSwitchPropsAlias =
+  RequireAccessibleLabel<SwitchWrapperProps>;
+
+export type SwitchProps = RecursicaOverStyled<RecursicaSwitchPropsAlias>;
 
 type SwitchComponent = React.ForwardRefExoticComponent<
   SwitchProps & React.RefAttributes<HTMLInputElement>

package/src/components/Switch/SwitchGroup.tsx

@@ -13,13 +13,16 @@ import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/For
 import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
 import styles from "./Switch.module.css";
 
+import { type RecursicaSwitchGroupProps as BaseRecursicaSwitchGroupProps } from "@recursica/adapter-common";
+
 export interface RecursicaSwitchGroupProps
   extends Omit<MantineSwitchGroupProps, "size" | "labelProps">,
     Omit<
       RecursicaFormControlWrapperProps,
       "controlMaxWidth" | "controlMinWidth"
     >,
-    ReadOnlyControlProps {}
+    ReadOnlyControlProps,
+    BaseRecursicaSwitchGroupProps {}
 
 export type SwitchGroupProps = RecursicaOverStyled<RecursicaSwitchGroupProps>;
 

package/src/components/Table/Table.tsx

@@ -1,6 +1,8 @@
 import React from "react";
+import { type RecursicaTableProps } from "@recursica/adapter-common";
 
-export type TableProps = React.HTMLAttributes<HTMLDivElement>;
+export type TableProps = React.HTMLAttributes<HTMLDivElement> &
+  RecursicaTableProps;
 
 export const Table: React.FC<TableProps> = (props) => {
   return <div {...props}>Table</div>;

package/src/components/Tabs/Tabs.tsx

@@ -12,13 +12,7 @@ import {
 } from "../../utils/filterStylingProps";
 import styles from "./Tabs.module.css";
 
-export interface RecursicaTabsProps
-  extends Omit<
-    MantineTabsProps,
-    "variant" | "classNames" | "color" | "radius"
-  > {
-  variant?: "default" | "outline" | "pills";
-}
+import { type RecursicaTabsProps } from "@recursica/adapter-common";
 
 export type TabsProps = RecursicaOverStyled<RecursicaTabsProps>;
 

package/src/components/Text/Text.tsx

@@ -1,4 +1,4 @@
-import { forwardRef, type ReactNode } from "react";
+import { forwardRef } from "react";
 import {
   Text as MantineText,
   type TextProps as MantineTextProps,
@@ -9,21 +9,7 @@ import {
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 
-export type TextVariant =
-  | "body"
-  | "body-small"
-  | "caption"
-  | "overline"
-  | "subtitle"
-  | "subtitle-small";
-
-export type RecursicaTextProps = Omit<MantineTextProps, "variant"> & {
-  /**
-   * The explicit typography hierarchy dictated by Recursica's global design tokens.
-   */
-  variant?: TextVariant;
-  children?: ReactNode;
-};
+import { type RecursicaTextProps } from "@recursica/adapter-common";
 
 export type TextProps = RecursicaOverStyled<RecursicaTextProps>;
 

package/src/components/TextArea/TextArea.tsx

@@ -12,6 +12,8 @@ import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/For
 import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
 import styles from "./TextArea.module.css";
 
+import { type RecursicaTextAreaProps as BaseRecursicaTextAreaProps } from "@recursica/adapter-common";
+
 export interface RecursicaTextAreaProps
   extends Omit<
       MantineTextareaProps,
@@ -28,14 +30,8 @@ export interface RecursicaTextAreaProps
       | "labelWithEditIcon"
       | "onLabelEditClick"
     >,
-    ReadOnlyControlProps {
-  /** Maximum rows for autosize textarea to grow */
-  maxRows?: number;
-  /** Minimum rows of autosize textarea */
-  minRows?: number;
-  /** If set, enables textarea height growing with its content */
-  autosize?: boolean;
-}
+    ReadOnlyControlProps,
+    BaseRecursicaTextAreaProps {}
 
 export type TextAreaProps = RecursicaOverStyled<RecursicaTextAreaProps>;
 

package/src/components/TextField/TextField.tsx

@@ -9,6 +9,8 @@ import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/For
 import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
 import styles from "./TextField.module.css";
 
+import { type RecursicaTextFieldProps as BaseRecursicaTextFieldProps } from "@recursica/adapter-common";
+
 export interface RecursicaTextFieldProps
   extends Omit<InputProps, "size" | "variant" | "radius" | "wrapperProps">,
     Pick<
@@ -23,7 +25,8 @@ export interface RecursicaTextFieldProps
       RecursicaFormControlWrapperProps,
       "controlMaxWidth" | "controlMinWidth"
     >,
-    ReadOnlyControlProps {}
+    ReadOnlyControlProps,
+    BaseRecursicaTextFieldProps {}
 
 export type TextFieldProps = RecursicaOverStyled<RecursicaTextFieldProps>;
 

package/src/components/TimePicker/TimePicker.tsx

@@ -1,6 +1,8 @@
 import React from "react";
+import { type RecursicaTimePickerProps } from "@recursica/adapter-common";
 
-export type TimePickerProps = React.HTMLAttributes<HTMLDivElement>;
+export type TimePickerProps = React.HTMLAttributes<HTMLDivElement> &
+  RecursicaTimePickerProps;
 
 export const TimePicker: React.FC<TimePickerProps> = (props) => {
   return <div {...props}>TimePicker</div>;

package/src/components/Timeline/Timeline.tsx

@@ -10,13 +10,16 @@ import {
 import styles from "./Timeline.module.css";
 import { TimelineItem } from "./TimelineItem";
 
+import { type RecursicaTimelineProps } from "@recursica/adapter-common";
+
 /**
  * Properties for the strictly-tokenized Timeline component.
  * Native Mantine abstract properties like `color`, `radius`, `bulletSize`, and `lineWidth`
  * have been stripped out to strictly enforce the structural mappings of the Recursica UI Kit.
  */
 export type TimelineProps = RecursicaOverStyled<
-  Omit<MantineTimelineProps, "color" | "radius" | "bulletSize" | "lineWidth">
+  Omit<MantineTimelineProps, "color" | "radius" | "bulletSize" | "lineWidth"> &
+    RecursicaTimelineProps
 >;
 
 interface TimelineComponent