@recursica/adapter-mantine-v8 1.0.0

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

@@ -0,0 +1,282 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Slider } from "./Slider";
+import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
+
+const meta: Meta<typeof Slider> = {
+  title: "UI-Kit/Slider",
+  component: Slider,
+  tags: ["autodocs"],
+  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;
+
+type Story = StoryObj<typeof Slider>;
+
+export const Default: Story = {
+  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: true,
+  },
+};
+
+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 WithIconsAndLabels: Story = {
+  args: {
+    label: "Volume",
+    assistiveText:
+      "Icons flank the track; min/max labels replace the raw bounds.",
+    defaultValue: 60,
+    minLabel: "Quiet",
+    maxLabel: "Loud",
+    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 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
+      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.test.tsx

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

package/src/components/Slider/Slider.tsx

@@ -0,0 +1,391 @@
+import React, { forwardRef, useState, useEffect } from "react";
+import {
+  Slider as MantineSlider,
+  RangeSlider as MantineRangeSlider,
+  type SliderProps as MantineSliderProps,
+  type RangeSliderProps as MantineRangeSliderProps,
+  type InputWrapperProps,
+} from "@mantine/core";
+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<
+      MantineSliderProps,
+      | "size"
+      | "variant"
+      | "radius"
+      | "wrapperProps"
+      | "classNames"
+      | "styles"
+      | "label"
+      | "value"
+      | "defaultValue"
+      | "onChange"
+      | "onChangeEnd"
+    >,
+    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. 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 Mantine's Slider (or, when `value`/`defaultValue` is a
+ * `[number, number]` tuple, Mantine's two-thumb 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,
+      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, backed by Mantine's RangeSlider instead of Slider.
+    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 = (val: SliderValue) => {
+      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 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([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([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 Slider.module.css variables, not Mantine's native size scale.
+      "variant", // Slider has a single Recursica-defined visual treatment; Mantine's variant isn't exposed.
+      "radius", // Corner radius is fixed by Recursica tokens in Slider.module.css, not caller-configurable.
+      // Not currently a real key of Mantine's SliderProps (that's an Input.Wrapper-only prop) — kept
+      // as a defensive no-op delete since it predates this consolidation and the public prop type
+      // already `Omit`s it; Recursica's own FormControlLayout/WithReadOnlyWrapper own wrapper markup.
+      "wrapperProps",
+    ] as const satisfies readonly (keyof MantineSliderProps | "wrapperProps")[];
+
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled) as Record<string, unknown>,
+      UNSUPPORTED_PROPS,
+    ) as Partial<typeof rest>;
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    // Securely map core native blocks down ensuring nested CSS modules map precisely
+    const mergedClassNames = mergeClassNames(
+      {
+        root: styles.sliderRoot,
+        track: styles.sliderTrack,
+        bar: styles.sliderBar,
+        thumb: styles.sliderThumb,
+        markWrapper: styles.sliderMarkWrapper,
+        mark: styles.sliderMark,
+        markLabel: styles.sliderMarkLabel,
+      },
+      restRecord.classNames as Partial<Record<string, string>> | undefined,
+    );
+
+    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}
+        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}
+          >
+            {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}
+                disabled={disabled}
+                data-error={error ? "true" : undefined}
+                aria-label="Minimum value"
+              />
+            )}
+
+            {leadingIcon}
+
+            {showMinMaxLabels && (
+              <span className={styles.minMaxGuide}>{minLabel ?? min}</span>
+            )}
+
+            <div className={styles.sliderTrackWrapper}>
+              {isRange ? (
+                <MantineRangeSlider
+                  {...(sanitizedProps as unknown as MantineRangeSliderProps)}
+                  classNames={mergedClassNames}
+                  disabled={disabled}
+                  value={resolvedValue as [number, number]}
+                  onChange={handleValueChange}
+                  onChangeEnd={onChangeEnd}
+                  min={min}
+                  max={max}
+                  step={step}
+                  label={tooltipLabel}
+                />
+              ) : (
+                <MantineSlider
+                  {...(sanitizedProps as unknown as MantineSliderProps)}
+                  classNames={mergedClassNames}
+                  disabled={disabled}
+                  value={resolvedValue as number}
+                  onChange={handleValueChange}
+                  onChangeEnd={onChangeEnd}
+                  min={min}
+                  max={max}
+                  step={step}
+                  label={tooltipLabel}
+                />
+              )}
+            </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}
+                  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}
+                  disabled={disabled}
+                  data-error={error ? "true" : undefined}
+                />
+              ))}
+          </div>
+        }
+      />
+    );
+  },
+);
+
+Slider.displayName = "Slider";