@recursica/mui-adapter 0.6.0 → 0.7.0

package/src/components/Button/Button.tsx

@@ -1,6 +1,5 @@
 import React, { forwardRef } from "react";
 import { Loader } from "../Loader/Loader";
-import type { RecursicaLoaderProps } from "../Loader/Loader";
 import {
   Button as MuiButton,
   type ButtonProps as MuiButtonProps,
@@ -11,21 +10,7 @@ import {
 } from "../../utils/filterStylingProps";
 import styles from "./Button.module.css";
 
-export interface RecursicaButtonProps {
-  variant?: "solid" | "outline" | "text";
-  size?: "default" | "small";
-  icon?: React.ReactNode;
-  /**
-   * For polymorphic support (e.g., `component="a"`), native to MUI.
-   */
-  component?: React.ElementType;
-  /** Which Recursica Loader variant to use */
-  loaderVariant?: RecursicaLoaderProps["variant"];
-  /** The size variant for the loader */
-  loaderSize?: RecursicaLoaderProps["size"];
-  /** Whether to use the Recursica loader or fallback to the Mantine loader */
-  useRecursicaLoader?: boolean;
-}
+import { type RecursicaButtonProps } from "@recursica/adapter-common";
 
 export type ButtonProps = RecursicaOverStyled<
   Omit<MuiButtonProps, "variant" | "size" | "color" | "fullWidth"> &
@@ -73,7 +58,6 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
     const restRecord = sanitizedProps as Record<string, unknown>;
 
     // Explicitly delete blocked semantic expansion dimension props that MUI uses natively
-    delete restRecord["fullWidth"];
     delete restRecord["color"]; // Recursica handles colors internally via tokens
 
     const hasStartIcon = !!icon || !!restRecord["startIcon"];
@@ -127,8 +111,13 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
         className={finalClass}
         loading={!!restRecord.loading}
         loadingIndicator={loadingIndicator}
+        fullWidth={!!restRecord.fullWidth}
         startIcon={
-          icon != null ? (
+          restRecord.loading ? (
+            <span className={styles.iconWrapper} aria-hidden>
+              {loadingIndicator}
+            </span>
+          ) : icon != null ? (
             <span className={styles.iconWrapper} aria-hidden>
               {icon}
             </span>

package/src/components/Card/Card.module.css

@@ -65,6 +65,18 @@
   text-decoration: var(
     --recursica_ui-kit_components_card_properties_header-style_textDecoration
   );
+
+  /* Edge-to-edge behavior */
+  margin-left: calc(var(--card-padding) * -1) !important;
+  margin-right: calc(var(--card-padding) * -1) !important;
+}
+
+.header:first-child {
+  margin-top: calc(var(--card-padding) * -1) !important;
+}
+
+.header:last-child {
+  margin-bottom: calc(var(--card-padding) * -1) !important;
 }
 
 .footer {
@@ -75,6 +87,18 @@
   border-top: var(--recursica_ui-kit_components_card_properties_divider-size)
     solid
     var(--recursica_ui-kit_components_card_properties_colors_divider-color);
+
+  /* Edge-to-edge behavior */
+  margin-left: calc(var(--card-padding) * -1) !important;
+  margin-right: calc(var(--card-padding) * -1) !important;
+}
+
+.footer:first-child {
+  margin-top: calc(var(--card-padding) * -1) !important;
+}
+
+.footer:last-child {
+  margin-bottom: calc(var(--card-padding) * -1) !important;
 }
 
 .section {
@@ -82,6 +106,18 @@
   margin-top: var(
     --recursica_ui-kit_components_card_properties_vertical-gutter
   );
+
+  /* Edge-to-edge behavior */
+  margin-left: calc(var(--card-padding) * -1) !important;
+  margin-right: calc(var(--card-padding) * -1) !important;
+}
+
+.section:first-child {
+  margin-top: calc(var(--card-padding) * -1) !important;
+}
+
+.section:last-child {
+  margin-bottom: calc(var(--card-padding) * -1) !important;
 }
 
 .content {

package/src/components/Card/Card.tsx

@@ -6,8 +6,13 @@ import {
 } from "../../utils/filterStylingProps";
 import styles from "./Card.module.css";
 
+import {
+  type RecursicaCardProps,
+  type RecursicaCardSectionProps,
+} from "@recursica/adapter-common";
+
 // ==== CARD CONTAINER ====
-export type CardProps = RecursicaOverStyled<MuiCardProps>;
+export type CardProps = RecursicaOverStyled<MuiCardProps & RecursicaCardProps>;
 
 /**
  * The root Card elevation box. It establishes the global background color, border radius, nested component gap, and outer shadow governed by the current `Layer` context.
@@ -53,9 +58,6 @@ const CardBase = forwardRef<HTMLDivElement, CardProps>(function Card(
 CardBase.displayName = "Card";
 
 // ==== NATIVE MANTINE CARD.SECTION ====
-export type RecursicaCardSectionProps = React.HTMLAttributes<HTMLDivElement> & {
-  children?: React.ReactNode;
-};
 export type CardSectionProps = RecursicaOverStyled<RecursicaCardSectionProps>;
 
 /**

package/src/components/Checkbox/Checkbox.module.css

@@ -11,17 +11,11 @@
 
 /* --- GROUP STYLES --- */
 .groupRoot {
-  padding: var(
-    --recursica_ui-kit_components_checkbox-group_properties_padding,
-    0
-  );
+  padding: var(--recursica_ui-kit_components_checkbox-group_properties_padding);
   margin: 0; /* HARDCODE: structural reset; consider token if layout needs change */
   display: flex;
   flex-direction: column;
-  gap: var(
-    --recursica_ui-kit_components_checkbox-group_properties_item-gap,
-    16px
-  );
+  gap: var(--recursica_ui-kit_components_checkbox-group_properties_item-gap);
 }
 
 /* SideBySide Variant */
@@ -118,7 +112,8 @@
 }
 
 /* Checked/Indeterminate State */
-.input:checked {
+.input:checked,
+.inputChecked {
   background-color: var(
     --recursica_ui-kit_components_checkbox_properties_colors_background-checked
   );
@@ -126,7 +121,8 @@
     --recursica_ui-kit_components_checkbox_properties_colors_border-checked
   );
 }
-.input[data-indeterminate] {
+.input[data-indeterminate],
+.inputIndeterminate {
   background-color: var(
     --recursica_ui-kit_components_checkbox_properties_colors_background-indeterminate
   );
@@ -213,6 +209,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_checkbox-item_properties_disabled-opacity
+  );
+}
+
 /* CheckboxGroup Layouts */
 .groupRoot {
   display: flex;

package/src/components/Checkbox/Checkbox.tsx

@@ -2,15 +2,17 @@ import React, { forwardRef } from "react";
 import {
   Checkbox as MuiCheckbox,
   type CheckboxProps as MuiCheckboxProps,
-  FormControlLabel,
 } from "@mui/material";
 import { type ReadOnlyControlProps } from "@recursica/adapter-common";
-import { CheckboxGroup } from "./CheckboxGroup";
+import { CheckboxGroup, CheckboxGroupContext } from "./CheckboxGroup";
 import {
   filterStylingProps,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
-import { type RequireAccessibleLabel } from "../../utils/RequireAccessibleLabel";
+import {
+  type RequireAccessibleLabel,
+  type RecursicaCheckboxProps,
+} from "@recursica/adapter-common";
 import {
   FormControlLayout,
   type FormControlLayoutProps,
@@ -18,17 +20,18 @@ import {
 
 import styles from "./Checkbox.module.css";
 
-export type RecursicaCheckboxProps = RequireAccessibleLabel<
-  Omit<MuiCheckboxProps, "size" | "color"> & {
-    label?: React.ReactNode;
-  } & ReadOnlyControlProps &
-    Pick<
-      FormControlLayoutProps,
-      "formLayout" | "labelSize" | "controlMaxWidth" | "controlMinWidth"
-    >
->;
+export type CheckboxWrapperProps = Omit<MuiCheckboxProps, "size" | "color"> &
+  RecursicaCheckboxProps &
+  ReadOnlyControlProps &
+  Pick<
+    FormControlLayoutProps,
+    "formLayout" | "labelSize" | "controlMaxWidth" | "controlMinWidth"
+  >;
+
+export type RecursicaCheckboxPropsAlias =
+  RequireAccessibleLabel<CheckboxWrapperProps>;
 
-export type CheckboxProps = RecursicaOverStyled<RecursicaCheckboxProps>;
+export type CheckboxProps = RecursicaOverStyled<RecursicaCheckboxPropsAlias>;
 
 type CheckboxComponent = React.ForwardRefExoticComponent<
   CheckboxProps & React.RefAttributes<HTMLButtonElement>
@@ -48,6 +51,9 @@ export const Checkbox = forwardRef<HTMLButtonElement, CheckboxProps>(
       controlMaxWidth,
       controlMinWidth,
       label,
+      description,
+      error,
+      style,
       ...rest
     } = props;
 
@@ -84,11 +90,21 @@ export const Checkbox = forwardRef<HTMLButtonElement, CheckboxProps>(
       ? `${styles.root} ${classNameProp}`
       : styles.root;
 
+    const groupContext = React.useContext(CheckboxGroupContext);
+    const isGrouped = groupContext !== null;
+    const isGroupReadOnly = isGrouped ? groupContext.readOnly : false;
+    const isChecked = isGrouped
+      ? (groupContext.value || []).includes(restRecord.value)
+      : !!(restRecord.checked ?? restRecord.defaultChecked);
+
     if (readOnly && !!readOnlyComponent) {
-      const isChecked = !!(restRecord.checked ?? restRecord.defaultChecked);
       const ReadOnlyComp = readOnlyComponent;
       const roNode = (
-        <ReadOnlyComp {...props} checked={isChecked} label={label} />
+        <ReadOnlyComp
+          {...props}
+          checked={isChecked}
+          label={label as React.ReactNode}
+        />
       );
 
       if (formLayout) {
@@ -107,25 +123,109 @@ export const Checkbox = forwardRef<HTMLButtonElement, CheckboxProps>(
       return <>{roNode}</>;
     }
 
+    const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+      if (isGrouped) {
+        const newValue = e.target.checked
+          ? [...(groupContext.value || []), restRecord.value]
+          : (groupContext.value || []).filter((v) => v !== restRecord.value);
+        if (groupContext.onChange) {
+          groupContext.onChange(e, newValue);
+        }
+      } else {
+        if (restRecord.onChange) {
+          (restRecord.onChange as any)(e, e.target.checked);
+        }
+      }
+    };
+
+    const CheckIcon = (props: React.ComponentProps<"svg">) => (
+      <svg
+        viewBox="0 0 10 7"
+        fill="none"
+        xmlns="http://www.w3.org/2000/svg"
+        {...props}
+      >
+        <path
+          d="M4 4.586L1.707 2.293A1 1 0 1 0 .293 3.707l3 3a.997.997 0 0 0 1.414 0l5-5A1 1 0 1 0 8.293.293L4 4.586z"
+          fill="currentColor"
+          fillRule="evenodd"
+          clipRule="evenodd"
+        />
+      </svg>
+    );
+
     const checkboxNode = (
       <MuiCheckbox
         ref={ref}
-        className={finalClass}
+        className={!label ? `${finalClass} ${styles.inner}` : styles.inner}
         classes={mergedClassNames}
-        disabled={readOnly || disabled}
+        disabled={readOnly || disabled || isGroupReadOnly}
         {...(sanitizedProps as unknown as MuiCheckboxProps)}
+        checked={isChecked as boolean}
+        onChange={handleChange}
+        sx={label ? { padding: 0 } : undefined}
+        icon={<div className={styles.input} />}
+        checkedIcon={
+          <div className={`${styles.input} ${styles.inputChecked}`}>
+            <CheckIcon className={styles.icon} />
+          </div>
+        }
+        indeterminateIcon={
+          <div className={`${styles.input} ${styles.inputIndeterminate}`}>
+            <svg
+              className={styles.icon}
+              xmlns="http://www.w3.org/2000/svg"
+              fill="none"
+              viewBox="0 0 32 32"
+            >
+              <rect x="6" y="14" width="20" height="4" fill="currentColor" />
+            </svg>
+          </div>
+        }
       />
     );
 
     const finalNode = label ? (
-      <FormControlLabel
-        control={checkboxNode}
-        label={label}
-        className={styles.labelWrapper}
-        classes={{ label: styles.label }}
-      />
+      <div className={finalClass} style={style as React.CSSProperties}>
+        <div className={styles.body}>
+          {checkboxNode}
+          <div className={styles.labelWrapper}>
+            <label
+              className={styles.label}
+              htmlFor={restRecord.id as string}
+              data-disabled={
+                readOnly || disabled || isGroupReadOnly ? true : undefined
+              }
+            >
+              {label as React.ReactNode}
+            </label>
+            {description && (
+              <div
+                className={styles.description}
+                data-disabled={
+                  readOnly || disabled || isGroupReadOnly ? true : undefined
+                }
+              >
+                {description}
+              </div>
+            )}
+            {error && (
+              <div
+                className={styles.error}
+                data-disabled={
+                  readOnly || disabled || isGroupReadOnly ? true : undefined
+                }
+              >
+                {error}
+              </div>
+            )}
+          </div>
+        </div>
+      </div>
     ) : (
-      checkboxNode
+      <div className={finalClass} style={style as React.CSSProperties}>
+        {checkboxNode}
+      </div>
     );
 
     if (formLayout) {

package/src/components/Checkbox/CheckboxGroup.stories.tsx

@@ -0,0 +1,139 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Checkbox } from "./Checkbox";
+import { CheckboxGroup } from "./CheckboxGroup";
+import { useState } from "react";
+import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
+
+const meta: Meta<typeof CheckboxGroup> = {
+  title: "UI-Kit/CheckboxGroup",
+  component: CheckboxGroup,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The \`CheckboxGroup\` component is the mandatory organizational wrapper aggregating multiple \`Checkbox\` primitives into structurally bound unified arrays. It inherently leverages the \`FormControlWrapper\` granting native access to macroscopic layout structuring, assistive descriptions, and strict flex arrays.
+
+We exclusively utilize the \`formLayout\` parameter to control macro-level form flow:
+- **\`formLayout="stacked"\`**: Top-to-bottom layout cascading the Label bounding box down vertically into a standard stacked checkbox column array.
+- **\`formLayout="side-by-side"\`**: Flow architecture pulling the grouping Label dynamically to the left while structurally organizing the internal checkboxes cleanly alongside it horizontally.
+
+\`\`\`tsx
+<Checkbox.Group 
+  label="Execution Targets" 
+  assistiveText="Strictly mapped structural grouping dynamically applied natively."
+  formLayout="stacked" 
+>
+  <Checkbox value="react" label="Browser Execution Context" />
+  <Checkbox value="svelte" label="Edge Nodes" />
+</Checkbox.Group>
+\`\`\`
+`,
+      },
+    },
+  },
+  argTypes: {
+    ...formControlArgTypes,
+    readOnly: {
+      control: "boolean",
+      description:
+        "Toggles structural read-only data presentation bypassing interaction boundaries completely.",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof CheckboxGroup>;
+
+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 (
+      <Checkbox.Group {...args} value={value} onChange={setValue}>
+        <Checkbox value="1" label="Option 1" />
+        <Checkbox value="2" label="Option 2" />
+      </Checkbox.Group>
+    );
+  },
+};
+
+export const SideBySideLayout: Story = {
+  args: {
+    formLayout: "side-by-side",
+    labelOptionalText: "Recommended",
+    labelWithEditIcon: true,
+    label: "Frontend Frameworks",
+    assistiveText:
+      "Select all libraries currently in use for this specific workspace configuration.",
+  },
+  // 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[]>(["react"]);
+    return (
+      <Checkbox.Group {...args} value={value} onChange={setValue}>
+        <Checkbox value="react" label="React (Standard Build)" />
+        <Checkbox
+          value="svelte"
+          label="The Svelte architecture which provides a highly optimized, completely compiler-driven framework avoiding virtual DOM boundaries. This massively extended text explicitly guarantees accurate wrapper constraint checking and multi-line flex alignment."
+        />
+        <Checkbox value="vue" label="Vue Configuration Map" />
+      </Checkbox.Group>
+    );
+  },
+};
+
+export const StackedLayout: Story = {
+  args: {
+    formLayout: "stacked",
+    required: true,
+    label: "Execution Targets",
+    error: "You must select at least one deployment target to compile.",
+  },
+  // 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[]>(["react"]);
+    return (
+      <Checkbox.Group {...args} value={value} onChange={setValue}>
+        <Checkbox value="react" label="Browser Execution Context" />
+        <Checkbox
+          value="svelte"
+          label="Highly distributed Edge computing environments seamlessly bridging local runtime boundaries."
+        />
+        <Checkbox value="vue" label="Serverless Cloud Providers" />
+      </Checkbox.Group>
+    );
+  },
+};
+
+export const ReadOnly: Story = {
+  args: {
+    readOnly: true,
+    formLayout: "stacked",
+    required: true,
+    label: "Static ReadOnly Execution Locks",
+    assistiveText:
+      "This structure explicitly validates native component-level DOM preservation natively mapping lock bounds safely over interaction.",
+  },
+  // 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[]>(["disabledNode"]);
+    return (
+      <Checkbox.Group {...args} value={value} onChange={setValue}>
+        <Checkbox
+          value="disabledNode"
+          label="Structurally Checked Node natively"
+        />
+        <Checkbox
+          value="disabledNodeEmpty"
+          label="Unchecked Configuration Limit"
+        />
+      </Checkbox.Group>
+    );
+  },
+};

package/src/components/Checkbox/CheckboxGroup.tsx

@@ -1,6 +1,5 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import React, { forwardRef } from "react";
-import { FormGroup, type FormGroupProps } from "@mui/material";
 import { type ReadOnlyControlProps } from "@recursica/adapter-common";
 import {
   filterStylingProps,
@@ -10,17 +9,29 @@ import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/For
 import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
 import styles from "./Checkbox.module.css";
 
+import { FormGroup as MuiFormGroup } from "@mui/material";
+
+export const CheckboxGroupContext = React.createContext<{
+  value?: any[];
+  onChange?: (event: React.SyntheticEvent, value: any) => void;
+  name?: string;
+  readOnly?: boolean;
+} | null>(null);
+
+import { type RecursicaCheckboxGroupProps as BaseRecursicaCheckboxGroupProps } from "@recursica/adapter-common";
+
 export interface RecursicaCheckboxGroupProps
-  extends Omit<FormGroupProps, "size" | "onChange">,
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange">,
     Omit<
       RecursicaFormControlWrapperProps,
-      "controlMaxWidth" | "controlMinWidth"
+      | "controlMaxWidth"
+      | "controlMinWidth"
+      | "onChange"
+      | "classes"
+      | "withAsterisk"
     >,
-    ReadOnlyControlProps {
-  value?: any[];
-  defaultValue?: any[];
-  onChange?: (value: any[]) => void;
-}
+    ReadOnlyControlProps,
+    BaseRecursicaCheckboxGroupProps {}
 
 export type CheckboxGroupProps =
   RecursicaOverStyled<RecursicaCheckboxGroupProps>;
@@ -45,7 +56,7 @@ export const CheckboxGroup = forwardRef<HTMLDivElement, CheckboxGroupProps>(
       assistiveWithIcon,
       error,
       required,
-      withAsterisk,
+      // removed withAsterisk
       id,
       className,
       style,
@@ -56,6 +67,7 @@ export const CheckboxGroup = forwardRef<HTMLDivElement, CheckboxGroupProps>(
       value,
       defaultValue,
       onChange,
+      row,
       ...rest
     } = props;
     const sanitizedProps = filterStylingProps(rest, overStyled);
@@ -64,11 +76,10 @@ export const CheckboxGroup = forwardRef<HTMLDivElement, CheckboxGroupProps>(
     // Delete prohibited sizing hooks
     delete restRecord["size"];
 
-    const handleChange = (event: React.SyntheticEvent, childValue: any) => {
-      // In MUI, FormGroup doesn't handle value arrays automatically like Mantine Checkbox.Group does.
-      // A common pattern is that each child Checkbox handles its own onChange,
-      // but to match Mantine API we might need context or cloning.
-      // For now, we pass down props or rely on the user to handle state.
+    const handleChange = (_event: React.SyntheticEvent, childValue: any) => {
+      if (onChange) {
+        onChange(childValue);
+      }
     };
 
     return (
@@ -78,7 +89,7 @@ export const CheckboxGroup = forwardRef<HTMLDivElement, CheckboxGroupProps>(
         controlMaxWidth="var(--recursica_ui-kit_components_checkbox-item_properties_max-width)"
         controlMinWidth={undefined}
         overStyled={overStyled as true}
-        labelElement="div"
+        // strictly override
         formLayout={formLayout}
         labelSize={labelSize}
         labelAlignment={labelAlignment}
@@ -91,7 +102,6 @@ export const CheckboxGroup = forwardRef<HTMLDivElement, CheckboxGroupProps>(
         assistiveWithIcon={assistiveWithIcon}
         error={error}
         required={required}
-        withAsterisk={withAsterisk}
         id={id}
         readOnly={readOnly && !!readOnlyComponent}
         readOnlyComponent={readOnlyComponent}
@@ -100,14 +110,24 @@ export const CheckboxGroup = forwardRef<HTMLDivElement, CheckboxGroupProps>(
         readOnlyValue={value !== undefined ? value : defaultValue}
         readOnlyNativeProps={props}
         activeComponent={
-          <FormGroup
-            ref={ref}
-            {...(sanitizedProps as unknown as FormGroupProps)}
-            className={`${styles.groupRoot} ${(sanitizedProps as any).className || ""}`}
-            data-layout={formLayout}
+          <CheckboxGroupContext.Provider
+            value={{
+              value: value !== undefined ? value : defaultValue,
+              onChange: handleChange,
+              name: restRecord.name as string | undefined,
+              readOnly: readOnly || !!(restRecord as any).disabled,
+            }}
           >
-            {children}
-          </FormGroup>
+            <MuiFormGroup
+              ref={ref}
+              row={row}
+              {...(sanitizedProps as any)}
+              className={`${styles.groupRoot} ${(sanitizedProps as any).className || ""}`.trim()}
+              data-layout={formLayout}
+            >
+              {children}
+            </MuiFormGroup>
+          </CheckboxGroupContext.Provider>
         }
       />
     );