@recursica/mantine-adapter 0.10.0 → 0.12.0

package/dist/src/components/Checkbox/Checkbox.d.ts

@@ -2,7 +2,9 @@ import { CheckboxProps as MantineCheckboxProps } from '@mantine/core';
 import { ReadOnlyControlProps } from '@recursica/adapter-common';
 import { CheckboxGroup } from './CheckboxGroup';
 import { RecursicaOverStyled } from '../../utils/filterStylingProps';
-export type RecursicaCheckboxProps = Omit<MantineCheckboxProps, "size" | "color" | "radius" | "iconColor" | "variant"> & ReadOnlyControlProps;
+import { RequireAccessibleLabel } from '../../utils/RequireAccessibleLabel';
+import { FormControlLayoutProps } from '../FormControlLayout/FormControlLayout';
+export type RecursicaCheckboxProps = RequireAccessibleLabel<Omit<MantineCheckboxProps, "size" | "color" | "radius" | "iconColor" | "variant"> & ReadOnlyControlProps & Pick<FormControlLayoutProps, "formLayout" | "labelSize" | "controlMaxWidth" | "controlMinWidth">>;
 export type CheckboxProps = RecursicaOverStyled<RecursicaCheckboxProps>;
 type CheckboxComponent = React.ForwardRefExoticComponent<CheckboxProps & React.RefAttributes<HTMLInputElement>> & {
     Group: typeof CheckboxGroup;

package/dist/src/components/FormControlLayout/FormControlLayout.d.ts

@@ -0,0 +1,21 @@
+import { default as React } from 'react';
+export interface FormControlLayoutProps extends React.HTMLAttributes<HTMLDivElement> {
+    formLayout?: "stacked" | "side-by-side";
+    labelSize?: "default" | "small" | "md";
+    controlMaxWidth?: string;
+    controlMinWidth?: string;
+    leftSection?: React.ReactNode;
+    children?: React.ReactNode;
+}
+/**
+ * A layout component used to correctly position form inputs alongside their labels.
+ *
+ * **When to use this:**
+ * Typically, you should use `FormControlWrapper` instead, which uses this component
+ * under the hood to handle layout automatically.
+ *
+ * However, this component is useful when you need to align standalone inputs
+ * (like a `Switch` or `Checkbox` without a label) so they perfectly match the spacing
+ * and alignment of your other form fields in a `side-by-side` layout.
+ */
+export declare const FormControlLayout: React.ForwardRefExoticComponent<FormControlLayoutProps & React.RefAttributes<HTMLDivElement>>;

package/dist/src/components/FormControlWrapper/FormControlWrapper.d.ts

@@ -3,6 +3,8 @@ import { InputWrapperProps } from '@mantine/core';
 import { RecursicaOverStyled } from '../../utils/filterStylingProps';
 import { RecursicaLabelProps } from '../Label/Label';
 export interface RecursicaFormControlWrapperProps extends RecursicaLabelProps {
+    /** Overall structural flow mapping the Form Control natively cascading down to Label and Input logic. */
+    formLayout?: "stacked" | "side-by-side";
     /** Securely replaces standard Mantine descriptions safely providing standard Assistive properties. */
     assistiveText?: React.ReactNode;
     /** Explicit toggle to suppress the Info icon rendering natively alongside the assistiveText. Defaults to true. */

package/dist/src/components/Label/Label.d.ts

@@ -2,10 +2,8 @@ import { default as React } from 'react';
 import { InputLabelProps } from '@mantine/core';
 import { RecursicaOverStyled } from '../../utils/filterStylingProps';
 export interface RecursicaLabelProps {
-    /** Overall structural flow mapping the Form Control natively cascading down to Label and Input logic. */
-    formLayout?: "stacked" | "side-by-side";
     /** Specifies the sizing metrics natively mapping the Label boundaries. */
-    labelSize?: "default" | "small";
+    labelSize?: "default" | "small" | "md";
     /** Overall alignment directive for the label strings natively forcing Left/Right justification. */
     labelAlignment?: "left" | "right";
     /** Injects an indicator text block alongside the label. Can be boolean (`true` maps to '(Optional)') or custom React nodes. */

package/dist/src/components/Menu/Menu.d.ts

@@ -1,3 +1,85 @@
-import { default as React } from 'react';
-export type MenuProps = React.HTMLAttributes<HTMLDivElement>;
-export declare const Menu: React.FC<MenuProps>;
+import { MenuProps as MantineMenuProps, MenuTargetProps as MantineMenuTargetProps, MenuDropdownProps as MantineMenuDropdownProps, MenuItemProps as MantineMenuItemProps, MenuDividerProps as MantineMenuDividerProps, MenuLabelProps as MantineMenuLabelProps, MenuSubProps as MantineMenuSubProps, MenuSubTargetProps as MantineMenuSubTargetProps, MenuSubDropdownProps as MantineMenuSubDropdownProps } from '@mantine/core';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+/**
+ * Recursica Menu component wrapping Mantine's composable Menu.
+ *
+ * Usage follows the composable dot-notation pattern:
+ * ```tsx
+ * <Menu>
+ *   <Menu.Target><Button>Open</Button></Menu.Target>
+ *   <Menu.Dropdown>
+ *     <Menu.Label>Section</Menu.Label>
+ *     <Menu.Item>Action</Menu.Item>
+ *     <Menu.Divider />
+ *     <Menu.Item>Another action</Menu.Item>
+ *   </Menu.Dropdown>
+ * </Menu>
+ * ```
+ */
+export type MenuProps = RecursicaOverStyled<MantineMenuProps>;
+declare const MenuBase: {
+    ({ overStyled, ...rest }: MenuProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+/**
+ * Wrapper for the element that triggers the menu.
+ * Requires a single child element that supports ref forwarding.
+ */
+export type MenuTargetProps = MantineMenuTargetProps;
+declare const MenuTarget: {
+    (props: MenuTargetProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+/** The dropdown panel containing menu items, dividers, and labels. */
+export type MenuDropdownProps = RecursicaOverStyled<MantineMenuDropdownProps>;
+declare const MenuDropdown: import('react').ForwardRefExoticComponent<MenuDropdownProps & import('react').RefAttributes<HTMLDivElement>>;
+/**
+ * An individual actionable item within the menu dropdown.
+ *
+ * **Note:** Mantine's `color` prop is stripped in strict mode to enforce
+ * design token adherence. Use `overStyled={true}` if you need to bypass.
+ */
+export type MenuItemProps = RecursicaOverStyled<Omit<MantineMenuItemProps, "color">>;
+declare const MenuItem: import('react').ForwardRefExoticComponent<MenuItemProps & import('react').RefAttributes<HTMLButtonElement>>;
+/** A visual separator between groups of menu items. */
+export type MenuDividerProps = RecursicaOverStyled<MantineMenuDividerProps>;
+declare const MenuDivider: import('react').ForwardRefExoticComponent<MenuDividerProps & import('react').RefAttributes<HTMLHRElement>>;
+/** A non-interactive section label used to categorize groups of menu items. */
+export type MenuLabelProps = RecursicaOverStyled<MantineMenuLabelProps>;
+declare const MenuLabel: import('react').ForwardRefExoticComponent<MenuLabelProps & import('react').RefAttributes<HTMLDivElement>>;
+/** Container for a submenu, wrapping Menu.Sub.Target and Menu.Sub.Dropdown. */
+export type MenuSubProps = MantineMenuSubProps;
+declare const MenuSubBase: {
+    (props: MenuSubProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+/** Wrapper for the element that triggers the submenu. */
+export type MenuSubTargetProps = MantineMenuSubTargetProps;
+declare const MenuSubTarget: {
+    (props: MenuSubTargetProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+/**
+ * A menu item that acts as a submenu trigger.
+ * Renders within Menu.Sub.Target and displays a chevron indicator.
+ */
+export type MenuSubItemProps = RecursicaOverStyled<Omit<MantineMenuItemProps, "color">>;
+declare const MenuSubItem: import('react').ForwardRefExoticComponent<MenuSubItemProps & import('react').RefAttributes<HTMLButtonElement>>;
+/** The dropdown panel for a submenu. */
+export type MenuSubDropdownProps = RecursicaOverStyled<MantineMenuSubDropdownProps>;
+declare const MenuSubDropdown: import('react').ForwardRefExoticComponent<MenuSubDropdownProps & import('react').RefAttributes<HTMLDivElement>>;
+type MenuSubComponent = typeof MenuSubBase & {
+    Target: typeof MenuSubTarget;
+    Item: typeof MenuSubItem;
+    Dropdown: typeof MenuSubDropdown;
+};
+type MenuComponent = typeof MenuBase & {
+    Target: typeof MenuTarget;
+    Dropdown: typeof MenuDropdown;
+    Item: typeof MenuItem;
+    Divider: typeof MenuDivider;
+    Label: typeof MenuLabel;
+    Sub: MenuSubComponent;
+};
+export declare const Menu: MenuComponent;
+export {};

package/dist/src/components/Radio/Radio.d.ts

@@ -2,7 +2,9 @@ import { RadioProps as MantineRadioProps } from '@mantine/core';
 import { ReadOnlyControlProps } from '@recursica/adapter-common';
 import { RadioGroup } from './RadioGroup';
 import { RecursicaOverStyled } from '../../utils/filterStylingProps';
-export type RecursicaRadioProps = Omit<MantineRadioProps, "size" | "color" | "radius" | "iconColor" | "variant"> & ReadOnlyControlProps;
+import { RequireAccessibleLabel } from '../../utils/RequireAccessibleLabel';
+import { FormControlLayoutProps } from '../FormControlLayout/FormControlLayout';
+export type RecursicaRadioProps = RequireAccessibleLabel<Omit<MantineRadioProps, "size" | "color" | "radius" | "iconColor" | "variant"> & ReadOnlyControlProps & Pick<FormControlLayoutProps, "formLayout" | "labelSize" | "controlMaxWidth" | "controlMinWidth">>;
 export type RadioProps = RecursicaOverStyled<RecursicaRadioProps>;
 type RadioComponent = React.ForwardRefExoticComponent<RadioProps & React.RefAttributes<HTMLInputElement>> & {
     Group: typeof RadioGroup;

package/dist/src/components/ReadOnlyField/ReadOnlyBooleanField.d.ts

@@ -0,0 +1,5 @@
+import { default as React } from 'react';
+export declare const ReadOnlyBooleanField: React.FC<{
+    checked: boolean;
+    label?: React.ReactNode;
+}>;

package/dist/src/components/ReadOnlyField/ReadOnlyField.d.ts

@@ -1,16 +1,16 @@
 import { default as React } from 'react';
-import { ReadOnlyFieldType } from '@recursica/adapter-common';
+import { ReadOnlyFieldType, ReadOnlyControlProps } from '@recursica/adapter-common';
 import { RecursicaOverStyled } from '../../utils/filterStylingProps';
 import { FormControlWrapperProps } from '../FormControlWrapper/FormControlWrapper';
-export interface RecursicaReadOnlyFieldProps extends Omit<FormControlWrapperProps, "children" | "overStyled"> {
+export interface RecursicaReadOnlyFieldProps extends Omit<FormControlWrapperProps, "children" | "overStyled" | "controlMaxWidth" | "controlMinWidth">, Pick<ReadOnlyControlProps, "emptyValueComponent"> {
     /** The specific value to be rendered in read-only mode explicitly matching the original field input */
     value?: any;
     /** The data type formatting rules bounding how the string is presented to the user */
     type?: ReadOnlyFieldType;
-    /** Custom renderer explicitly responsible for formatting missing/empty value mappings (overriding default 'N/A') */
-    emptyValueComponent?: React.ElementType<{
-        value?: any;
-    }>;
+    /** Pass the native maximum width design variable dynamically bounding the specific wrapper width exclusively. */
+    controlMaxWidth?: string | undefined;
+    /** Pass the native minimum width design variable dynamically bounding the specific wrapper width exclusively. */
+    controlMinWidth?: string | undefined;
 }
 export type ReadOnlyFieldProps = RecursicaOverStyled<RecursicaReadOnlyFieldProps>;
 /**

package/dist/src/components/ReadOnlyField/ReadOnlySwitchField.d.ts

@@ -0,0 +1,5 @@
+import { default as React } from 'react';
+export declare const ReadOnlySwitchField: React.FC<{
+    checked: boolean;
+    label?: React.ReactNode;
+}>;

package/dist/src/components/ReadOnlyField/WithReadOnlyWrapper.d.ts

@@ -5,7 +5,13 @@ export interface WithReadOnlyWrapperProps extends Omit<FormControlWrapperProps,
     /** Injects whether the field defaults to reading mode natively */
     readOnly?: boolean;
     /** Explicit React component directly overtaking the baseline text renderer when read-only mode is active */
-    readOnlyComponent?: React.ReactNode;
+    readOnlyComponent?: React.ElementType<any>;
+    /** Custom renderer explicitly responsible for formatting missing/empty value mappings (overriding default 'N/A') */
+    emptyValueComponent?: React.ElementType<{
+        value?: any;
+    }>;
+    /** The full native props dictionary securely forwarded into the custom readOnlyComponent if active */
+    readOnlyNativeProps?: any;
     /** Instructs the underlying generic ReadOnlyField which raw visual structure to bridge automatically */
     readOnlyType?: ReadOnlyFieldType;
     /** The isolated raw data value intercepted explicitly into the ReadOnly formatters */

package/dist/src/components/ReadOnlyField/index.d.ts

@@ -1,3 +1,5 @@
 export * from './ReadOnlyField';
 export * from './WithReadOnlyWrapper';
 export * from './ReadOnlyTextField';
+export * from './ReadOnlySwitchField';
+export * from './ReadOnlyBooleanField';

package/dist/src/components/Switch/Switch.d.ts

@@ -1,8 +1,10 @@
 import { SwitchProps as MantineSwitchProps } from '@mantine/core';
 import { ReadOnlyControlProps } from '@recursica/adapter-common';
 import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+import { RequireAccessibleLabel } from '../../utils/RequireAccessibleLabel';
+import { FormControlLayoutProps } from '../FormControlLayout/FormControlLayout';
 import { SwitchGroup } from './SwitchGroup';
-export type RecursicaSwitchProps = Omit<MantineSwitchProps, "size" | "color" | "radius" | "variant"> & ReadOnlyControlProps;
+export type RecursicaSwitchProps = RequireAccessibleLabel<Omit<MantineSwitchProps, "size" | "color" | "radius" | "variant"> & ReadOnlyControlProps & Pick<FormControlLayoutProps, "formLayout" | "labelSize" | "controlMaxWidth" | "controlMinWidth">>;
 export type SwitchProps = RecursicaOverStyled<RecursicaSwitchProps>;
 type SwitchComponent = React.ForwardRefExoticComponent<SwitchProps & React.RefAttributes<HTMLInputElement>> & {
     Group: typeof SwitchGroup;

package/dist/src/components/index.d.ts

@@ -13,6 +13,7 @@ export * from './Dropdown/Dropdown';
 export * from './FileInput/FileInput';
 export * from './FileUpload/FileUpload';
 export * from './Flex/Flex';
+export * from './FormControlLayout/FormControlLayout';
 export * from './Group/Group';
 export * from './HoverCard/HoverCard';
 export * from './Link/Link';

package/dist/src/utils/RequireAccessibleLabel.d.ts

@@ -0,0 +1,18 @@
+import { ReactNode } from 'react';
+/**
+ * Enforces accessibility by strictly requiring at least one form of labeling:
+ * either a visual \`label\`, an \`aria-label\`, or an \`aria-labelledby\`.
+ */
+export type RequireAccessibleLabel<T> = T & ({
+    label: ReactNode;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+} | {
+    label?: ReactNode;
+    "aria-label": string;
+    "aria-labelledby"?: string;
+} | {
+    label?: ReactNode;
+    "aria-label"?: string;
+    "aria-labelledby": string;
+});

package/package.json

@@ -11,7 +11,7 @@
     "type": "git",
     "url": "git+https://github.com/borderux/recursica.git"
   },
-  "version": "0.10.0",
+  "version": "0.12.0",
   "type": "module",
   "main": "./dist/mantine-adapter.cjs",
   "module": "./dist/mantine-adapter.js",

package/src/components/AssistiveElement/AssistiveElement.stories.tsx

@@ -1,7 +1,6 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { AssistiveElement } from "./AssistiveElement";
 import { Layer } from "@recursica/adapter-common";
-import React from "react";
 
 const meta: Meta<typeof AssistiveElement> = {
   title: "UI-Kit/AssistiveElement",
@@ -37,7 +36,8 @@ export const DefaultHelp: Story = {
     assistiveVariant: "help",
     assistiveWithIcon: true,
   },
-  render: (args) => (
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
     <Layer layer={0} style={{ padding: "48px" }}>
       <AssistiveElement {...args} />
     </Layer>
@@ -51,7 +51,8 @@ export const ErrorState: Story = {
     assistiveVariant: "error",
     assistiveWithIcon: true,
   },
-  render: (args) => (
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
     <Layer layer={0} style={{ padding: "48px" }}>
       <AssistiveElement {...args} />
     </Layer>
@@ -65,7 +66,8 @@ export const NoIconHelp: Story = {
     assistiveVariant: "help",
     assistiveWithIcon: false,
   },
-  render: (args) => (
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
     <Layer layer={0} style={{ padding: "48px" }}>
       <AssistiveElement {...args} />
     </Layer>

package/src/components/Avatar/Avatar.stories.tsx

@@ -42,7 +42,8 @@ export const Default: Story = {
     size: "default",
     variant: "solid",
   },
-  render: (args) => {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => {
     return <Avatar {...args} />;
   },
 };
@@ -53,7 +54,8 @@ export const TextSolidDefault: Story = {
     variant: "solid",
     size: "default",
   },
-  render: (args) => <Avatar {...args} />,
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => <Avatar {...args} />,
 };
 
 export const ImageLarge: Story = {
@@ -61,7 +63,8 @@ export const ImageLarge: Story = {
     src: "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=250&q=80",
     size: "large",
   },
-  render: (args) => <Avatar {...args} />,
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => <Avatar {...args} />,
 };
 
 export const IconSmallGhost: Story = {
@@ -85,7 +88,8 @@ export const IconSmallGhost: Story = {
       </svg>
     ),
   },
-  render: (args) => <Avatar {...args} />,
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => <Avatar {...args} />,
 };
 
 export const LayerOneOutline: Story = {
@@ -94,7 +98,8 @@ export const LayerOneOutline: Story = {
     variant: "outline",
     size: "default",
   },
-  render: (args) => (
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
     <Layer layer={1} style={{ padding: "24px", display: "inline-block" }}>
       <Avatar {...args} />
     </Layer>

package/src/components/Badge/Badge.stories.tsx

@@ -27,7 +27,8 @@ export const Default: Story = {
     children: "Badge Label",
     variant: "primary-color",
   },
-  render: (args) => {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => {
     return <Badge {...args} />;
   },
 };

package/src/components/Button/Button.stories.tsx

@@ -20,9 +20,6 @@ const meta: Meta<ButtonStoryProps> = {
       options: ["default", "small"],
       description: "The size of the button",
     },
-    disabled: {
-      control: "boolean",
-    },
   },
 };
 
@@ -37,7 +34,8 @@ export const Default: Story = {
     size: "default",
     disabled: false,
   },
-  render: (args) => {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => {
     return <Button {...args} />;
   },
 };

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

@@ -161,7 +161,7 @@
     --recursica_ui-kit_components_checkbox_properties_colors_icon-color
   ) !important;
 }
-.input:disabled + .iconWrapper .icon {
+.input:disabled + .icon {
   color: var(
     --recursica_ui-kit_components_checkbox_properties_colors_disabled-icon
   ) !important;

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

@@ -24,14 +24,13 @@ To render a solitary component natively:
     },
   },
   argTypes: {
-    disabled: {
-      control: "boolean",
-    },
     readOnly: {
       control: "boolean",
       description:
         "Toggles structural read-only data presentation bypassing interaction boundaries completely.",
     },
+    controlMaxWidth: { table: { disable: true } },
+    controlMinWidth: { table: { disable: true } },
   },
 };
 
@@ -46,6 +45,13 @@ export const Default: Story = {
   },
 };
 
+export const SideBySideLayout: Story = {
+  args: {
+    label: "Opt-in form alignment",
+    formLayout: "side-by-side",
+  },
+};
+
 export const LongLabelWrap: Story = {
   args: {
     label:
@@ -71,3 +77,18 @@ export const StaticVariations: Story = {
     </div>
   ),
 };
+
+export const ReadOnly: Story = {
+  args: {},
+  render: () => (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "24px",
+      }}
+    >
+      <Checkbox label="Accept Terms & Conditions" defaultChecked readOnly />
+    </div>
+  ),
+};

package/src/components/Checkbox/Checkbox.tsx

@@ -9,13 +9,25 @@ import {
   filterStylingProps,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
+import { type RequireAccessibleLabel } from "../../utils/RequireAccessibleLabel";
+import {
+  FormControlLayout,
+  type FormControlLayoutProps,
+} from "../FormControlLayout/FormControlLayout";
+
 import styles from "./Checkbox.module.css";
 
-export type RecursicaCheckboxProps = Omit<
-  MantineCheckboxProps,
-  "size" | "color" | "radius" | "iconColor" | "variant"
-> &
-  ReadOnlyControlProps;
+export type RecursicaCheckboxProps = RequireAccessibleLabel<
+  Omit<
+    MantineCheckboxProps,
+    "size" | "color" | "radius" | "iconColor" | "variant"
+  > &
+    ReadOnlyControlProps &
+    Pick<
+      FormControlLayoutProps,
+      "formLayout" | "labelSize" | "controlMaxWidth" | "controlMinWidth"
+    >
+>;
 
 export type CheckboxProps = RecursicaOverStyled<RecursicaCheckboxProps>;
 
@@ -26,10 +38,18 @@ type CheckboxComponent = React.ForwardRefExoticComponent<
 };
 
 export const Checkbox = forwardRef<HTMLInputElement, CheckboxProps>(
-  function Checkbox(
-    { overStyled = false, readOnly, readOnlyComponent, disabled, ...rest },
-    ref,
-  ) {
+  function Checkbox(props, ref) {
+    const {
+      overStyled = false,
+      readOnly,
+      readOnlyComponent,
+      disabled,
+      formLayout,
+      labelSize,
+      controlMaxWidth,
+      controlMinWidth,
+      ...rest
+    } = props;
     // Checkbox doesn't use Label onLabelEditClick natively since it isn't mapped inside FormControlWrapper intrinsically.
     const sanitizedProps = filterStylingProps(rest, overStyled);
     const restRecord = sanitizedProps as Record<string, unknown>;
@@ -41,11 +61,6 @@ export const Checkbox = forwardRef<HTMLInputElement, CheckboxProps>(
     delete restRecord["variant"];
     delete restRecord["iconColor"];
 
-    if (readOnly && readOnlyComponent) {
-      // Safely fallback explicitly returning mapped elements natively without macro wrappers
-      return <>{readOnlyComponent}</>;
-    }
-
     const mergedClassNames: Partial<Record<string, string>> = {
       root: styles.root,
       body: styles.body,
@@ -85,8 +100,35 @@ export const Checkbox = forwardRef<HTMLInputElement, CheckboxProps>(
       ? `${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 Mantine's sizing/coloring so we rely strictly on variables from Checkbox.module.css
-    return (
+    const checkboxNode = (
       <MantineCheckbox
         ref={ref}
         className={finalClass}
@@ -95,6 +137,21 @@ export const Checkbox = forwardRef<HTMLInputElement, CheckboxProps>(
         {...(sanitizedProps as unknown as MantineCheckboxProps)}
       />
     );
+
+    if (formLayout) {
+      return (
+        <FormControlLayout
+          formLayout={formLayout}
+          labelSize={labelSize}
+          controlMaxWidth={controlMaxWidth}
+          controlMinWidth={controlMinWidth}
+        >
+          {checkboxNode}
+        </FormControlLayout>
+      );
+    }
+
+    return checkboxNode;
   },
 ) as CheckboxComponent;