@recursica/mui-adapter 0.6.0 → 0.7.0

package/src/components/Stepper/Stepper.stories.tsx

@@ -1,6 +1,6 @@
 import React, { useState } from "react";
 import type { Meta, StoryObj } from "@storybook/react";
-import { Stepper } from "./Stepper";
+import { Stepper, Step, StepLabel } from "./Stepper";
 import { Button } from "../Button/Button";
 import { Group } from "../Group/Group";
 import { Flex } from "../Flex/Flex";
@@ -11,19 +11,6 @@ const meta: Meta<typeof Stepper> = {
   tags: ["autodocs"],
   parameters: {
     layout: "centered",
-    docs: {
-      description: {
-        component: `
-The \`Stepper\` component provides a visual progression interface strictly mapped to Recursica's UI-Kit.
-This component wraps Mantine's \`Stepper\` and natively enforces Figma tokens for sizes, colors, gaps, and states (\`completed\`, \`current\`, \`upcoming\`).
-
-### Layout & Orientation
-Orientation dictates how the steps flow:
-- **horizontal**: Steps render side-by-side. 
-- **vertical**: Steps stack vertically, mapping seamlessly to the vertical gap tokens.
-        `,
-      },
-    },
   },
   argTypes: {
     size: {
@@ -34,9 +21,6 @@ Orientation dictates how the steps flow:
       control: "radio",
       options: ["horizontal", "vertical"],
     },
-    defaultChecked: {
-      table: { disable: true },
-    },
   },
 };
 
@@ -50,23 +34,39 @@ const InteractiveStepper = (args: React.ComponentProps<typeof Stepper>) => {
   const prevStep = () =>
     setActive((current) => (current > 0 ? current - 1 : current));
 
+  const steps = [
+    {
+      label: "First step",
+      description: "Create an account and set up your billing profile",
+    },
+    {
+      label: "Second step",
+      description:
+        "Verify email and ensure all notification preferences are correct",
+    },
+    { label: "Final step", description: "Get full access" },
+  ];
+
   return (
     <Flex direction="column" w={600}>
-      <Stepper {...args} active={active} onStepClick={setActive}>
-        <Stepper.Step
-          label="First step"
-          description="Create an account and set up your billing profile"
-        />
-        <Stepper.Step
-          label="Second step"
-          description="Verify email and ensure all notification preferences are correct"
-        />
-        <Stepper.Step label="Final step" description="Get full access" />
-        <Stepper.Completed>
-          Completed, click back button to get to previous step
-        </Stepper.Completed>
+      <Stepper {...args} activeStep={active}>
+        {steps.map((step, index) => (
+          <Step key={index} completed={active > index}>
+            <StepLabel description={step.description}>{step.label}</StepLabel>
+          </Step>
+        ))}
       </Stepper>
 
+      {active === steps.length ? (
+        <div style={{ marginTop: 24, textAlign: "center" }}>
+          Completed, click back button to get to previous step
+        </div>
+      ) : (
+        <div style={{ marginTop: 24, textAlign: "center" }}>
+          Step {active + 1} content
+        </div>
+      )}
+
       <Group mt={24} justify="center" gap={8}>
         <Button variant="outline" onClick={prevStep} disabled={active === 0}>
           Previous step
@@ -110,23 +110,36 @@ const StressTestStepper = (args: React.ComponentProps<typeof Stepper>) => {
   const prevStep = () =>
     setActive((current) => (current > 0 ? current - 1 : current));
 
+  const steps = [
+    {
+      label:
+        "This is an extremely long step title designed to test how the layout handles multiline text wrapping and constraints",
+      description: "Create an account and set up your billing profile",
+    },
+    {
+      label: "Second step",
+      description:
+        "Verify email and ensure all notification preferences are correct",
+    },
+    { label: "Final step", description: undefined },
+  ];
+
   return (
     <Flex direction="column" w={600}>
-      <Stepper {...args} active={active} onStepClick={setActive}>
-        <Stepper.Step
-          label="This is an extremely long step title designed to test how the layout handles multiline text wrapping and constraints"
-          description="Create an account and set up your billing profile"
-        />
-        <Stepper.Step
-          label="Second step"
-          description="Verify email and ensure all notification preferences are correct"
-        />
-        <Stepper.Step label="Final step" />
-        <Stepper.Completed>
-          Completed, click back button to get to previous step
-        </Stepper.Completed>
+      <Stepper {...args} activeStep={active}>
+        {steps.map((step, index) => (
+          <Step key={index} completed={active > index}>
+            <StepLabel description={step.description}>{step.label}</StepLabel>
+          </Step>
+        ))}
       </Stepper>
 
+      {active === steps.length && (
+        <div style={{ marginTop: 24, textAlign: "center" }}>
+          Completed, click back button to get to previous step
+        </div>
+      )}
+
       <Group mt={24} justify="center" gap={8}>
         <Button variant="outline" onClick={prevStep} disabled={active === 0}>
           Previous step

package/src/components/Stepper/Stepper.tsx

@@ -1,4 +1,4 @@
-import React, { forwardRef, isValidElement } from "react";
+import React, { forwardRef } from "react";
 import {
   Stepper as MuiStepper,
   Step as MuiStep,
@@ -6,6 +6,10 @@ import {
   StepButton as MuiStepButton,
   StepConnector as MuiStepConnector,
   type StepperProps as MuiStepperProps,
+  type StepProps as MuiStepProps,
+  type StepLabelProps as MuiStepLabelProps,
+  type StepButtonProps as MuiStepButtonProps,
+  type StepConnectorProps as MuiStepConnectorProps,
 } from "@mui/material";
 import {
   filterStylingProps,
@@ -13,23 +17,11 @@ import {
 } from "../../utils/filterStylingProps";
 import styles from "./Stepper.module.css";
 
-export interface RecursicaStepperProps
-  extends Omit<
-    MuiStepperProps,
-    "size" | "color" | "radius" | "iconSize" | "contentPadding" | "activeStep"
-  > {
-  size?: "small" | "large";
-  active?: number;
-  onStepClick?: (stepIndex: number) => void;
-  orientation?: "horizontal" | "vertical";
-}
+import { type RecursicaStepperProps } from "@recursica/adapter-common";
 
 export type StepperProps = RecursicaOverStyled<RecursicaStepperProps>;
 
-export const StepperStep: React.FC<any> = () => null;
-export const StepperCompleted: React.FC<any> = () => null;
-
-const _Stepper = forwardRef<HTMLDivElement, StepperProps>(
+export const Stepper = forwardRef<HTMLDivElement, StepperProps>(
   function Stepper(props, ref) {
     const {
       overStyled = false,
@@ -37,27 +29,11 @@ const _Stepper = forwardRef<HTMLDivElement, StepperProps>(
       orientation = "horizontal",
       className,
       style,
-      active = 0,
-      onStepClick,
-      children,
       ...rest
     } = props;
 
     const sanitizedProps = filterStylingProps(rest, overStyled);
 
-    const steps = React.Children.toArray(children).filter(
-      (child: any) =>
-        isValidElement(child) &&
-        (child.type === StepperStep ||
-          (child.type as any).displayName === "StepperStep"),
-    );
-    const completed = React.Children.toArray(children).find(
-      (child: any) =>
-        isValidElement(child) &&
-        (child.type === StepperCompleted ||
-          (child.type as any).displayName === "StepperCompleted"),
-    );
-
     return (
       <div
         className={`${styles.root} ${orientation === "horizontal" ? styles.horizontal : styles.vertical} ${size === "large" ? styles.large : styles.small} ${className || ""}`}
@@ -68,7 +44,6 @@ const _Stepper = forwardRef<HTMLDivElement, StepperProps>(
         <MuiStepper
           ref={ref as any}
           orientation={orientation}
-          activeStep={active}
           connector={
             <MuiStepConnector
               classes={{
@@ -83,65 +58,92 @@ const _Stepper = forwardRef<HTMLDivElement, StepperProps>(
             root: styles.steps,
           }}
           {...(sanitizedProps as MuiStepperProps)}
-        >
-          {steps.map((step: any, index: number) => {
-            const stepProps = step.props;
-            const label = stepProps.label;
-            const description = stepProps.description;
-
-            return (
-              <MuiStep
-                key={index}
-                classes={{ root: styles.step }}
-                completed={active > index}
-              >
-                <MuiStepButton onClick={() => onStepClick?.(index)}>
-                  <MuiStepLabel
-                    optional={
-                      description ? (
-                        <div className={styles.stepDescription}>
-                          {description}
-                        </div>
-                      ) : null
-                    }
-                    classes={{
-                      label: styles.stepLabel,
-                      iconContainer: styles.stepIcon,
-                    }}
-                  >
-                    {label}
-                  </MuiStepLabel>
-                </MuiStepButton>
-              </MuiStep>
-            );
-          })}
-        </MuiStepper>
-        {active >= steps.length && completed && (
-          <div className={styles.content}>
-            {(completed as React.ReactElement).props.children}
-          </div>
-        )}
-        {active < steps.length &&
-          steps[active] &&
-          (steps[active] as React.ReactElement).props.children && (
-            <div className={styles.content}>
-              {(steps[active] as React.ReactElement).props.children}
-            </div>
-          )}
+        />
       </div>
     );
   },
 );
 
-StepperStep.displayName = "StepperStep";
-StepperCompleted.displayName = "StepperCompleted";
+Stepper.displayName = "Stepper";
+
+export type StepProps = RecursicaOverStyled<MuiStepProps>;
+
+export const Step = forwardRef<HTMLDivElement, StepProps>(
+  function Step(props, ref) {
+    const { overStyled = false, className, ...rest } = props;
+    return (
+      <MuiStep
+        ref={ref}
+        classes={{ root: styles.step }}
+        className={className || ""}
+        {...(filterStylingProps(rest, overStyled) as MuiStepProps)}
+      />
+    );
+  },
+);
+
+Step.displayName = "Step";
+
+export type StepButtonProps = RecursicaOverStyled<MuiStepButtonProps>;
+
+export const StepButton = forwardRef<HTMLButtonElement, StepButtonProps>(
+  function StepButton(props, ref) {
+    const { overStyled = false, className, ...rest } = props;
+    return (
+      <MuiStepButton
+        ref={ref}
+        className={className || ""}
+        {...(filterStylingProps(rest, overStyled) as MuiStepButtonProps)}
+      />
+    );
+  },
+);
+
+StepButton.displayName = "StepButton";
+
+export type StepLabelProps = RecursicaOverStyled<
+  MuiStepLabelProps & { description?: React.ReactNode }
+>;
 
-export const Stepper: typeof _Stepper & {
-  Step: typeof StepperStep;
-  Completed: typeof StepperCompleted;
-} = Object.assign(_Stepper, {
-  Step: StepperStep,
-  Completed: StepperCompleted,
-});
+export const StepLabel = forwardRef<HTMLDivElement, StepLabelProps>(
+  function StepLabel(props, ref) {
+    const { overStyled = false, className, description, ...rest } = props;
+    return (
+      <MuiStepLabel
+        ref={ref}
+        className={className || ""}
+        classes={{
+          label: styles.stepLabel,
+          iconContainer: styles.stepIcon,
+        }}
+        optional={
+          description ? (
+            <div className={styles.stepDescription}>{description}</div>
+          ) : (
+            rest.optional
+          )
+        }
+        {...(filterStylingProps(rest, overStyled) as MuiStepLabelProps)}
+      />
+    );
+  },
+);
+
+StepLabel.displayName = "StepLabel";
+
+export type StepConnectorProps = RecursicaOverStyled<MuiStepConnectorProps>;
+
+export const StepConnector = forwardRef<HTMLDivElement, StepConnectorProps>(
+  function StepConnector(props, ref) {
+    const { overStyled = false, className, ...rest } = props;
+    return (
+      <MuiStepConnector
+        ref={ref}
+        className={className || ""}
+        {...(filterStylingProps(rest, overStyled) as MuiStepConnectorProps)}
+      />
+    );
+  },
+);
 
-_Stepper.displayName = "Stepper";
+StepConnector.displayName = "StepConnector";

package/src/components/Switch/Switch.module.css

@@ -150,6 +150,27 @@
   );
 }
 
+.description {
+  margin-top: 5px; /* HARDCODE: mantine default */
+  color: #868e96; /* HARDCODE: mantine default dimmed */
+  font-size: 12px; /* HARDCODE: mantine default xs */
+  line-height: 1.2;
+}
+
+.error {
+  margin-top: 5px; /* HARDCODE: mantine default */
+  color: #fa5252; /* HARDCODE: mantine default error */
+  font-size: 12px; /* HARDCODE: mantine default xs */
+  line-height: 1.2;
+}
+
+.description[data-disabled="true"],
+.error[data-disabled="true"] {
+  opacity: var(
+    --recursica_ui-kit_components_switch-item_properties_disabled-opacity
+  );
+}
+
 .thumbIconWrapper {
   display: flex;
   align-items: center;

package/src/components/Switch/Switch.tsx

@@ -9,25 +9,33 @@ 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,
 } from "../FormControlLayout/FormControlLayout";
 import styles from "./Switch.module.css";
 
-import { SwitchGroup } from "./SwitchGroup";
+// Removed unused SwitchGroup import
+
+export type SwitchWrapperProps = Omit<
+  MuiSwitchProps,
+  "size" | "color" | "radius" | "variant"
+> &
+  RecursicaSwitchProps &
+  ReadOnlyControlProps &
+  Pick<
+    FormControlLayoutProps,
+    "formLayout" | "labelSize" | "controlMaxWidth" | "controlMinWidth"
+  >;
 
-export type RecursicaSwitchProps = RequireAccessibleLabel<
-  Omit<MuiSwitchProps, "size" | "color" | "radius" | "variant"> &
-    ReadOnlyControlProps &
-    Pick<
-      FormControlLayoutProps,
-      "formLayout" | "labelSize" | "controlMaxWidth" | "controlMinWidth"
-    >
->;
+export type RecursicaSwitchPropsAlias =
+  RequireAccessibleLabel<SwitchWrapperProps>;
 
-export type SwitchProps = RecursicaOverStyled<RecursicaSwitchProps>;
+export type SwitchProps = RecursicaOverStyled<RecursicaSwitchPropsAlias>;
 
 type SwitchComponent = any;
 
@@ -38,11 +46,15 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
       readOnly,
       readOnlyComponent,
       disabled,
-      thumbIcon,
+      // Removed thumbIcon from destructured props since it's not supported
       formLayout,
       labelSize,
       controlMaxWidth,
       controlMinWidth,
+      label,
+      description,
+      error,
+      style,
       ...rest
     } = props;
     const sanitizedProps = filterStylingProps(rest, overStyled);
@@ -125,8 +137,8 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
     // We omit Mui's sizing/coloring so we rely strictly on variables from Switch.module.css
     const switchNode = (
       <MuiSwitch
-        ref={ref}
-        className={finalClass}
+        ref={ref as any}
+        className={!label ? `${finalClass} ${styles.inner}` : styles.inner}
         classes={mergedClassNames}
         disabled={readOnly || disabled}
         data-disabled={readOnly || disabled || undefined}
@@ -135,6 +147,41 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
       />
     );
 
+    const finalNode = label ? (
+      <div className={finalClass} style={style as React.CSSProperties}>
+        <div className={styles.body}>
+          {switchNode}
+          <div className={styles.labelWrapper}>
+            <label
+              className={styles.label}
+              htmlFor={restRecord.id as string}
+              data-disabled={readOnly || disabled ? true : undefined}
+            >
+              {label as React.ReactNode}
+            </label>
+            {description && (
+              <div
+                className={styles.description}
+                data-disabled={readOnly || disabled ? true : undefined}
+              >
+                {description}
+              </div>
+            )}
+            {error && (
+              <div
+                className={styles.error}
+                data-disabled={readOnly || disabled ? true : undefined}
+              >
+                {error}
+              </div>
+            )}
+          </div>
+        </div>
+      </div>
+    ) : (
+      switchNode
+    );
+
     if (formLayout) {
       return (
         <FormControlLayout
@@ -143,12 +190,12 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
           controlMaxWidth={controlMaxWidth}
           controlMinWidth={controlMinWidth}
         >
-          {switchNode}
+          {finalNode}
         </FormControlLayout>
       );
     }
 
-    return switchNode;
+    return finalNode;
   },
 ) as SwitchComponent;
 

package/src/components/Switch/SwitchGroup.stories.tsx

@@ -0,0 +1,132 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Switch } from "./Switch";
+import { SwitchGroup } from "./SwitchGroup";
+import { useState } from "react";
+import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
+
+const meta: Meta<typeof SwitchGroup> = {
+  title: "UI-Kit/SwitchGroup",
+  component: SwitchGroup,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The \`SwitchGroup\` component is the mandatory organizational wrapper for orchestrating \`Switch\` primitives into macro form layouts. It inherently leverages the \`FormControlWrapper\`, granting native access to structural alignments, assistive descriptions, and strict flex arrays.
+
+### Supported Layout Vectors
+- **\`formLayout="stacked"\`**: Top-to-bottom layout cascading the Label bounding box down vertically into a standard stacked switch array.
+- **\`formLayout="side-by-side"\`**: Flow architecture pulling the grouping Label dynamically to the left while structurally organizing the internal switches cleanly alongside it horizontally.
+
+> [!IMPORTANT]  
+> If you require a solitary \`Switch\` field to natively accept an overarching form label, assistive text, or align with other side-by-side components in a form column, you must wrap it inside a \`Switch.Group\` to trigger the \`FormControlWrapper\` mapping.
+`,
+      },
+    },
+  },
+  argTypes: {
+    ...formControlArgTypes,
+    readOnly: {
+      control: "boolean",
+      description:
+        "Passes read-only lock natively down mapping inner switches into explicitly disabled states.",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof SwitchGroup>;
+
+export const Default: Story = {
+  args: {
+    formLayout: "stacked",
+    label: "Standard Group",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: function StoryRender({ withLayer, layer, ...args }: any) {
+    const [value, setValue] = useState<string[]>([]);
+    return (
+      <SwitchGroup {...args} value={value} onChange={setValue}>
+        <Switch value="1" label="Option 1" />
+        <Switch value="2" label="Option 2" />
+      </SwitchGroup>
+    );
+  },
+};
+
+export const StackedLayout: Story = {
+  args: {
+    formLayout: "stacked",
+    label: "Notification Settings",
+    description: "Manage your preferences.",
+    assistiveText: "We recommend turning these on.",
+    error: "",
+    required: true,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: function StoryRender({ withLayer, layer, ...args }: any) {
+    const [value, setValue] = useState<string[]>(["email"]);
+    return (
+      <SwitchGroup {...args} value={value} onChange={setValue}>
+        <Switch value="email" label="Email Alerts" />
+        <Switch value="push" label="Push Notifications" />
+        <Switch value="sms" label="SMS Messages" />
+      </SwitchGroup>
+    );
+  },
+};
+
+export const SideBySideLayout: Story = {
+  args: {
+    ...StackedLayout.args,
+    formLayout: "side-by-side",
+    labelSize: "default",
+    labelAlignment: "left",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: function StoryRender({ withLayer, layer, ...args }: any) {
+    const [value, setValue] = useState<string[]>([]);
+    return (
+      <SwitchGroup {...args} value={value} onChange={setValue}>
+        <Switch value="weekly" label="Weekly Digest" />
+        <Switch value="marketing" label="Marketing Emails" />
+      </SwitchGroup>
+    );
+  },
+};
+
+export const SolitaryFormControl: Story = {
+  args: {
+    formLayout: "side-by-side",
+    label: "Enable Backups",
+    description: "Automatically back up your data nightly.",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: function StoryRender({ withLayer, layer, ...args }: any) {
+    const [value, setValue] = useState<string[]>(["auto"]);
+    return (
+      <SwitchGroup {...args} value={value} onChange={setValue}>
+        <Switch value="auto" label="Auto-backup" />
+      </SwitchGroup>
+    );
+  },
+};
+
+export const ReadOnly: Story = {
+  args: {
+    ...StackedLayout.args,
+    readOnly: true,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: function StoryRender({ withLayer, layer, ...args }: any) {
+    const [value, setValue] = useState<string[]>(["email", "sms"]);
+    return (
+      <SwitchGroup {...args} value={value} onChange={setValue}>
+        <Switch value="email" label="Email Alerts" />
+        <Switch value="push" label="Push Notifications" />
+        <Switch value="sms" label="SMS Messages" />
+      </SwitchGroup>
+    );
+  },
+};