@recursica/mui-adapter 0.5.0 → 0.7.0

package/src/components/Switch/Switch.tsx

@@ -1,8 +1,202 @@
-import React from "react";
-import "./Switch.module.css";
+import { forwardRef } from "react";
+import {
+  Switch as MuiSwitch,
+  type SwitchProps as MuiSwitchProps,
+} from "@mui/material";
+import { type ReadOnlyControlProps } from "@recursica/adapter-common";
 
-export type SwitchProps = React.HTMLAttributes<HTMLDivElement>;
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import {
+  type RequireAccessibleLabel,
+  type RecursicaSwitchProps,
+} from "@recursica/adapter-common";
+import {
+  FormControlLayout,
+  type FormControlLayoutProps,
+} from "../FormControlLayout/FormControlLayout";
+import styles from "./Switch.module.css";
 
-export const Switch: React.FC<SwitchProps> = (props) => {
-  return <div {...props}>Switch</div>;
-};
+// Removed unused SwitchGroup import
+
+export type SwitchWrapperProps = Omit<
+  MuiSwitchProps,
+  "size" | "color" | "radius" | "variant"
+> &
+  RecursicaSwitchProps &
+  ReadOnlyControlProps &
+  Pick<
+    FormControlLayoutProps,
+    "formLayout" | "labelSize" | "controlMaxWidth" | "controlMinWidth"
+  >;
+
+export type RecursicaSwitchPropsAlias =
+  RequireAccessibleLabel<SwitchWrapperProps>;
+
+export type SwitchProps = RecursicaOverStyled<RecursicaSwitchPropsAlias>;
+
+type SwitchComponent = any;
+
+export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
+  function Switch(props, ref) {
+    const {
+      overStyled = false,
+      readOnly,
+      readOnlyComponent,
+      disabled,
+      // 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);
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    // Actively delete dimension bindings that bypass the abstraction
+    delete restRecord["size"];
+    delete restRecord["color"];
+    delete restRecord["radius"];
+    delete restRecord["variant"];
+
+    const mergedClassNames: Partial<Record<string, string>> = {
+      root: styles.root,
+      body: styles.body,
+      track: styles.track,
+      thumb: styles.thumb,
+      trackLabel: styles.trackLabel,
+      labelWrapper: styles.labelWrapper,
+      label: styles.label,
+    };
+
+    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.root} ${o.root}` : styles.root;
+      mergedClassNames.body = o.body ? `${styles.body} ${o.body}` : styles.body;
+      mergedClassNames.track = o.track
+        ? `${styles.track} ${o.track}`
+        : styles.track;
+      mergedClassNames.thumb = o.thumb
+        ? `${styles.thumb} ${o.thumb}`
+        : styles.thumb;
+      mergedClassNames.trackLabel = o.trackLabel
+        ? `${styles.trackLabel} ${o.trackLabel}`
+        : styles.trackLabel;
+      mergedClassNames.labelWrapper = o.labelWrapper
+        ? `${styles.labelWrapper} ${o.labelWrapper}`
+        : styles.labelWrapper;
+      mergedClassNames.label = o.label
+        ? `${styles.label} ${o.label}`
+        : styles.label;
+    }
+
+    const classNameProp = restRecord.className as string | undefined;
+    const finalClass = classNameProp
+      ? `${styles.root} ${classNameProp}`
+      : styles.root;
+
+    if (readOnly && !!readOnlyComponent) {
+      const isChecked = !!(restRecord.checked ?? restRecord.defaultChecked);
+      const ReadOnlyComp = readOnlyComponent;
+      const roNode = (
+        <ReadOnlyComp
+          {...props}
+          checked={isChecked}
+          label={restRecord.label as React.ReactNode}
+        />
+      );
+
+      if (formLayout) {
+        return (
+          <FormControlLayout
+            formLayout={formLayout}
+            labelSize={labelSize}
+            controlMaxWidth={controlMaxWidth}
+            controlMinWidth={controlMinWidth}
+          >
+            {roNode}
+          </FormControlLayout>
+        );
+      }
+
+      return <>{roNode}</>;
+    }
+
+    // We omit Mui's sizing/coloring so we rely strictly on variables from Switch.module.css
+    const switchNode = (
+      <MuiSwitch
+        ref={ref as any}
+        className={!label ? `${finalClass} ${styles.inner}` : styles.inner}
+        classes={mergedClassNames}
+        disabled={readOnly || disabled}
+        data-disabled={readOnly || disabled || undefined}
+        // thumbIcon={thumbIcon ?? FinalThumbIcon}
+        {...(sanitizedProps as unknown as MuiSwitchProps)}
+      />
+    );
+
+    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
+          formLayout={formLayout}
+          labelSize={labelSize}
+          controlMaxWidth={controlMaxWidth}
+          controlMinWidth={controlMinWidth}
+        >
+          {finalNode}
+        </FormControlLayout>
+      );
+    }
+
+    return finalNode;
+  },
+) as SwitchComponent;
+
+Switch.displayName = "Switch";

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>
+    );
+  },
+};

package/src/components/Switch/SwitchGroup.tsx

@@ -0,0 +1,120 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import React, { forwardRef } from "react";
+import {
+  FormGroup as MuiFormGroup,
+  type FormGroupProps as MuiFormGroupProps,
+} 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";
+import styles from "./Switch.module.css";
+
+import { type RecursicaSwitchGroupProps as BaseRecursicaSwitchGroupProps } from "@recursica/adapter-common";
+
+export interface RecursicaSwitchGroupProps
+  extends Omit<
+      MuiFormGroupProps,
+      | "size"
+      | "labelProps"
+      | "onChange"
+      | "classes"
+      | "ref"
+      | "value"
+      | "defaultValue"
+    >,
+    Omit<
+      RecursicaFormControlWrapperProps,
+      "controlMaxWidth" | "controlMinWidth" | "classes" | "onChange"
+    >,
+    ReadOnlyControlProps,
+    BaseRecursicaSwitchGroupProps {}
+
+export type SwitchGroupProps = RecursicaOverStyled<RecursicaSwitchGroupProps>;
+
+export const SwitchGroup = forwardRef<HTMLDivElement, SwitchGroupProps>(
+  function SwitchGroup(props, ref) {
+    const {
+      overStyled = false,
+      formLayout = "stacked",
+
+      // Label Wrappers
+      labelSize,
+      labelAlignment,
+      labelOptionalText,
+      labelWithEditIcon,
+      onLabelEditClick,
+
+      // Base Mui Extracted Attributes
+      label,
+      description,
+      assistiveText,
+      assistiveWithIcon,
+      error,
+      required,
+      // removed withAsterisk
+      id,
+      className,
+      style,
+      children,
+      readOnly,
+      readOnlyComponent,
+      emptyValueComponent,
+      value,
+      defaultValue,
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      onChange,
+      ...rest
+    } = props;
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    // Delete prohibited sizing hooks from bypassing the variables
+    delete restRecord["size"];
+
+    return (
+      <WithReadOnlyWrapper
+        className={className}
+        style={style as React.CSSProperties}
+        controlMaxWidth="var(--recursica_ui-kit_components_switch-item_properties_label-max-width)"
+        controlMinWidth={undefined}
+        overStyled={overStyled as true}
+        // Strictly override. ARIA grouping prohibits interactive switches nested natively inside <label>.
+        formLayout={formLayout}
+        labelSize={labelSize}
+        labelAlignment={labelAlignment}
+        labelOptionalText={labelOptionalText}
+        labelWithEditIcon={labelWithEditIcon}
+        onLabelEditClick={onLabelEditClick}
+        label={label}
+        description={description}
+        assistiveText={assistiveText}
+        assistiveWithIcon={assistiveWithIcon}
+        error={error}
+        required={required}
+        id={id}
+        readOnly={readOnly && !!readOnlyComponent}
+        readOnlyComponent={readOnlyComponent}
+        emptyValueComponent={emptyValueComponent}
+        readOnlyType="text"
+        readOnlyValue={value !== undefined ? value : defaultValue}
+        readOnlyNativeProps={props}
+        activeComponent={
+          <MuiFormGroup
+            ref={ref}
+            {...(sanitizedProps as unknown as MuiFormGroupProps)}
+            className={`${styles.groupRoot} ${(sanitizedProps as any).className || ""}`.trim()}
+            data-layout={formLayout}
+          >
+            {children}
+          </MuiFormGroup>
+        }
+      />
+    );
+  },
+);
+
+SwitchGroup.displayName = "SwitchGroup";

package/src/components/Table/Table.stories.tsx

@@ -6,28 +6,10 @@ const meta: Meta<typeof Table> = {
   title: "UI-Kit/🚧 Table",
   component: Table,
   tags: ["autodocs"],
-  parameters: {
-    controls: {
-      include: [
-        "layer",
-        "withLayer",
-        "children",
-        "component",
-        "variant",
-        "size",
-        "icon",
-        "disabled",
-        "href",
-        "onClick",
-        "onChange",
-        "value",
-        "checked",
-      ],
-    },
-  },
 };
 
 export default meta;
+
 type Story = StoryObj<typeof Table>;
 
 export const Default: Story = {

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/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,4 @@
+# Tabs Implementation Notes
+
+- **Compositional API Dropped:** Mantine uses `<Tabs.List>`, `<Tabs.Tab>`, and `<Tabs.Panel>` natively with implicit context from `<Tabs>`. MUI relies on `@mui/lab/TabContext` and separates `Tabs` and `TabPanel`.
+- **Monolithic API Adopted:** Following architectural review, we have opted to drop the broken dot-notation wrappers for `mui-adapter`. We now natively export `Tabs` (MUI List), `Tab` (MUI Item), and `TabPanel` (from `@mui/lab`). Developers must use `TabContext` (from `@mui/lab`) to manage state, just like native MUI. Storybook and visual regression tests have been updated to reflect this divergence while retaining core property mapping compatibility.