@recursica/mantine-adapter 0.10.0 → 0.12.0

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

@@ -46,7 +46,24 @@ export default meta;
 
 type Story = StoryObj<typeof CheckboxGroup>;
 
-export const GroupSideBySide: Story = {
+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",
@@ -55,7 +72,8 @@ export const GroupSideBySide: Story = {
     assistiveText:
       "Select all libraries currently in use for this specific workspace configuration.",
   },
-  render: function GroupSideBySideRender(args) {
+  // 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}>
@@ -70,14 +88,15 @@ export const GroupSideBySide: Story = {
   },
 };
 
-export const GroupStacked: Story = {
+export const StackedLayout: Story = {
   args: {
     formLayout: "stacked",
     required: true,
     label: "Execution Targets",
     error: "You must select at least one deployment target to compile.",
   },
-  render: function GroupStackedRender(args) {
+  // 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}>
@@ -92,7 +111,7 @@ export const GroupStacked: Story = {
   },
 };
 
-export const StaticReadOnlyGroup: Story = {
+export const ReadOnly: Story = {
   args: {
     readOnly: true,
     formLayout: "stacked",
@@ -101,7 +120,8 @@ export const StaticReadOnlyGroup: Story = {
     assistiveText:
       "This structure explicitly validates native component-level DOM preservation natively mapping lock bounds safely over interaction.",
   },
-  render: function StaticReadOnlyGroupRender(args) {
+  // 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}>
@@ -117,22 +137,3 @@ export const StaticReadOnlyGroup: Story = {
     );
   },
 };
-
-export const EditableReadOnlyGroup: Story = {
-  args: {
-    readOnly: true,
-    formLayout: "side-by-side",
-    labelWithEditIcon: true,
-    label: "Interactively Editable ReadOnly Group",
-    assistiveText: "Users explicitly unlock DOM structures dynamically.",
-  },
-  render: function EditableReadOnlyGroupRender(args) {
-    const [value, setValue] = useState<string[]>(["activeState"]);
-    return (
-      <Checkbox.Group {...args} value={value} onChange={setValue}>
-        <Checkbox value="activeState" label="Locked active state" />
-        <Checkbox value="unlockedNode" label="Locked inactive map" />
-      </Checkbox.Group>
-    );
-  },
-};

package/src/components/Checkbox/CheckboxGroup.tsx

@@ -9,10 +9,8 @@ import {
   filterStylingProps,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
-import {
-  FormControlWrapper,
-  type RecursicaFormControlWrapperProps,
-} from "../FormControlWrapper/FormControlWrapper";
+import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
+import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
 import styles from "./Checkbox.module.css";
 
 export interface RecursicaCheckboxGroupProps
@@ -27,8 +25,8 @@ export type CheckboxGroupProps =
   RecursicaOverStyled<RecursicaCheckboxGroupProps>;
 
 export const CheckboxGroup = forwardRef<HTMLDivElement, CheckboxGroupProps>(
-  function CheckboxGroup(
-    {
+  function CheckboxGroup(props, ref) {
+    const {
       overStyled = false,
       formLayout = "stacked",
 
@@ -53,47 +51,19 @@ export const CheckboxGroup = forwardRef<HTMLDivElement, CheckboxGroupProps>(
       children,
       readOnly,
       readOnlyComponent,
+      emptyValueComponent,
+      value,
+      defaultValue,
       ...rest
-    },
-    ref,
-  ) {
+    } = props;
     const sanitizedProps = filterStylingProps(rest, overStyled);
     const restRecord = sanitizedProps as Record<string, unknown>;
 
     // Delete prohibited sizing hooks from bypassing the variables
     delete restRecord["size"];
 
-    if (readOnly && readOnlyComponent) {
-      return (
-        <FormControlWrapper
-          className={className}
-          style={style as React.CSSProperties}
-          controlMaxWidth="var(--recursica_ui-kit_components_checkbox-item_properties_max-width)"
-          controlMinWidth={undefined}
-          overStyled={overStyled as true}
-          labelElement="div"
-          formLayout={formLayout}
-          labelSize={labelSize}
-          labelAlignment={labelAlignment}
-          labelOptionalText={labelOptionalText}
-          labelWithEditIcon={labelWithEditIcon}
-          onLabelEditClick={onLabelEditClick}
-          label={label}
-          description={description}
-          assistiveText={assistiveText}
-          assistiveWithIcon={assistiveWithIcon}
-          error={error}
-          required={required}
-          withAsterisk={withAsterisk}
-          id={id}
-        >
-          {readOnlyComponent}
-        </FormControlWrapper>
-      );
-    }
-
     return (
-      <FormControlWrapper
+      <WithReadOnlyWrapper
         className={className}
         style={style as React.CSSProperties}
         controlMaxWidth="var(--recursica_ui-kit_components_checkbox-item_properties_max-width)"
@@ -114,25 +84,35 @@ export const CheckboxGroup = forwardRef<HTMLDivElement, CheckboxGroupProps>(
         required={required}
         withAsterisk={withAsterisk}
         id={id}
-      >
-        <MantineCheckbox.Group
-          ref={ref}
-          /* Natively bind local disabled lock dynamically */
-          {...(sanitizedProps as unknown as MantineCheckboxGroupProps)}
-        >
-          <div className={styles.groupRoot} data-layout={formLayout}>
-            {/* If the exact group is read-only natively, we inject disabled hooks dynamically over children? Mantine handles native context directly! */}
-            {React.Children.map(children, (child) => {
-              if (React.isValidElement(child)) {
-                return React.cloneElement(child as React.ReactElement<any>, {
-                  disabled: readOnly || (child.props as any).disabled,
-                });
-              }
-              return child;
-            })}
-          </div>
-        </MantineCheckbox.Group>
-      </FormControlWrapper>
+        readOnly={readOnly && !!readOnlyComponent}
+        readOnlyComponent={readOnlyComponent}
+        emptyValueComponent={emptyValueComponent}
+        readOnlyType="text"
+        readOnlyValue={value !== undefined ? value : defaultValue}
+        readOnlyNativeProps={props}
+        activeComponent={
+          <MantineCheckbox.Group
+            ref={ref}
+            /* Natively bind local disabled lock dynamically */
+            {...(sanitizedProps as unknown as MantineCheckboxGroupProps)}
+            disabled={readOnly || (restRecord as any).disabled}
+            value={value}
+            defaultValue={defaultValue}
+          >
+            <div className={styles.groupRoot} data-layout={formLayout}>
+              {/* If the exact group is read-only natively, we inject disabled hooks dynamically over children? Mantine handles native context directly! */}
+              {React.Children.map(children, (child) => {
+                if (React.isValidElement(child)) {
+                  return React.cloneElement(child as React.ReactElement<any>, {
+                    disabled: readOnly || (child.props as any).disabled,
+                  });
+                }
+                return child;
+              })}
+            </div>
+          </MantineCheckbox.Group>
+        }
+      />
     );
   },
 );

package/src/components/Container/Container.stories.tsx

@@ -55,7 +55,8 @@ export default meta;
 type Story = StoryObj<ContainerStoryProps>;
 
 export const Default: Story = {
-  render: (args) => (
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
     <div style={{ backgroundColor: "#f0f0f0", padding: "16px" }}>
       <Container
         {...args}
@@ -78,7 +79,8 @@ export const SmallContainer: Story = {
   args: {
     size: "sm",
   },
-  render: (args) => (
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
     <div style={{ backgroundColor: "#f0f0f0", padding: "16px" }}>
       <Container
         {...args}
@@ -98,7 +100,8 @@ export const FluidContainer: Story = {
   args: {
     fluid: true,
   },
-  render: (args) => (
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
     <div style={{ backgroundColor: "#f0f0f0", padding: "16px" }}>
       <Container
         {...args}

package/src/components/DatePicker/DatePicker.stories.tsx

@@ -6,11 +6,7 @@ const meta: Meta<typeof DatePicker> = {
   title: "UI-Kit/🚧 DatePicker",
   component: DatePicker,
   tags: ["autodocs"],
-  argTypes: {
-    disabled: {
-      control: "boolean",
-    },
-  },
+  argTypes: {},
 };
 
 export default meta;

package/src/components/Dropdown/Dropdown.stories.tsx

@@ -30,9 +30,6 @@ const meta: Meta<DropdownStoryProps> = {
   },
   argTypes: {
     ...formControlArgTypes,
-    disabled: {
-      control: "boolean",
-    },
     readOnly: {
       control: "boolean",
     },

package/src/components/Dropdown/Dropdown.tsx

@@ -36,8 +36,8 @@ export interface RecursicaDropdownProps
 export type DropdownProps = RecursicaOverStyled<RecursicaDropdownProps>;
 
 export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
-  function Dropdown(
-    {
+  function Dropdown(props, ref) {
+    const {
       overStyled = false,
       formLayout = "stacked",
       containerWidth,
@@ -61,13 +61,12 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
       disabled,
       readOnly,
       readOnlyComponent,
+      emptyValueComponent,
       value,
       defaultValue,
       data,
       ...rest
-    },
-    ref,
-  ) {
+    } = props;
     const sanitizedProps = filterStylingProps(rest, overStyled);
     const restRecord = sanitizedProps as Record<string, unknown>;
 
@@ -136,6 +135,7 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
         id={id}
         readOnly={readOnly}
         readOnlyComponent={readOnlyComponent}
+        emptyValueComponent={emptyValueComponent}
         readOnlyType="text"
         readOnlyValue={
           value !== undefined
@@ -144,6 +144,7 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
               ? String(defaultValue)
               : undefined
         }
+        readOnlyNativeProps={props}
         activeComponent={
           /* Naked Select execution safely decoupled from Mantine's macro Input.Wrapper DOM hooks */
           <MantineSelect

package/src/components/FileInput/FileInput.stories.tsx

@@ -6,11 +6,7 @@ const meta: Meta<typeof FileInput> = {
   title: "UI-Kit/🚧 FileInput",
   component: FileInput,
   tags: ["autodocs"],
-  argTypes: {
-    disabled: {
-      control: "boolean",
-    },
-  },
+  argTypes: {},
 };
 
 export default meta;

package/src/components/FileUpload/FileUpload.stories.tsx

@@ -6,11 +6,7 @@ const meta: Meta<typeof FileUpload> = {
   title: "UI-Kit/🚧 FileUpload",
   component: FileUpload,
   tags: ["autodocs"],
-  argTypes: {
-    disabled: {
-      control: "boolean",
-    },
-  },
+  argTypes: {},
 };
 
 export default meta;

package/src/components/Flex/Flex.stories.tsx

@@ -87,7 +87,8 @@ export default meta;
 type Story = StoryObj<FlexStoryProps>;
 
 export const Default: Story = {
-  render: (args) => (
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
     <Flex {...args}>
       <Button variant="solid">Block A</Button>
       <Button variant="outline">Block B</Button>
@@ -101,7 +102,8 @@ export const StaticGapSmallColumn: Story = {
     gap: "rec-sm",
     direction: "column",
   },
-  render: (args) => (
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
     <Flex {...args}>
       <Button variant="solid">Item 1</Button>
       <Button variant="solid">Item 2</Button>
@@ -115,7 +117,8 @@ export const StaticGapLargeRow: Story = {
     gap: "rec-xl",
     direction: "row",
   },
-  render: (args) => (
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
     <Flex {...args}>
       <Button variant="solid">Item 1</Button>
       <Button variant="solid">Item 2</Button>

package/src/components/FormControlLayout/FormControlLayout.module.css

@@ -0,0 +1,80 @@
+/* FormControlLayout.module.css */
+
+.root {
+  display: flex;
+  margin: 0; /* Hardcoded structural reset */
+  padding: 0; /* Hardcoded structural reset */
+  max-width: var(--form-control-max-width, 100%);
+  min-width: var(--form-control-min-width, auto);
+}
+
+/* Base Structural Stacked Layout */
+.root[data-form-layout="stacked"] {
+  flex-direction: column;
+}
+
+/* Base Structural Grid Layout */
+.root[data-form-layout="side-by-side"] {
+  flex-direction: row;
+  align-items: flex-start;
+  flex-wrap: wrap; /* Allows collapse if screen is too thin, though standard flex width should hold */
+}
+
+.leftSection {
+  /* Width dimensions are strictly governed natively inside this layout column */
+  flex-shrink: 0;
+  display: flex;
+  flex-direction: column;
+}
+
+/* Stacked Layout constraints */
+.root[data-form-layout="stacked"] .leftSection {
+  padding-bottom: var(
+    --recursica_ui-kit_components_label_variants_layouts_stacked_properties_bottom-padding,
+    8px
+  );
+  min-height: var(
+    --recursica_ui-kit_components_label_variants_layouts_stacked_properties_min-height,
+    auto
+  );
+}
+
+/* SideBySide Layout constraints */
+.root[data-form-layout="side-by-side"] .leftSection {
+  padding-top: var(
+    --recursica_ui-kit_components_label_variants_layouts_side-by-side_properties_vertical-padding,
+    0
+  );
+  padding-bottom: var(
+    --recursica_ui-kit_components_label_variants_layouts_side-by-side_properties_vertical-padding,
+    0
+  );
+  min-height: var(
+    --recursica_ui-kit_components_label_variants_layouts_side-by-side_properties_min-height,
+    auto
+  );
+  /* In side-by-side, the label column exists to the left of its input, so we use the gutter gap here. */
+  margin-right: var(
+    --recursica_ui-kit_components_label_variants_layouts_side-by-side_properties_gutter,
+    16px
+  );
+}
+
+.root[data-form-layout="side-by-side"] .leftSection[data-size="default"] {
+  width: var(
+    --recursica_ui-kit_components_label_variants_layouts_side-by-side_variants_sizes_default_properties_width
+  );
+}
+
+.root[data-form-layout="side-by-side"] .leftSection[data-size="small"] {
+  width: var(
+    --recursica_ui-kit_components_label_variants_layouts_side-by-side_variants_sizes_small_properties_width
+  );
+}
+
+.rightSection {
+  display: flex; /* Groups internal field alongside subsequent errors/descriptions */
+  flex-direction: column;
+  flex: 1; /* Consumes the remaining x-axis in grid columns natively */
+  min-width: 0; /* Break boundary preventing internal flex explosion */
+}

package/src/components/FormControlLayout/FormControlLayout.stories.tsx

@@ -0,0 +1,82 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { FormControlLayout } from "./FormControlLayout";
+import { Switch } from "../Switch/Switch";
+
+const meta: Meta<typeof FormControlLayout> = {
+  title: "UI-Kit/FormControlLayout",
+  component: FormControlLayout,
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "A layout component used to correctly position form inputs alongside their labels.\n\n**When to use this:**\nTypically, you should use `FormControlWrapper` instead, which uses this component under the hood to handle layout automatically.\n\nHowever, 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.",
+      },
+    },
+  },
+  tags: ["autodocs"],
+  argTypes: {
+    formLayout: {
+      control: "radio",
+      options: ["stacked", "side-by-side"],
+    },
+    labelSize: {
+      control: "radio",
+      options: ["default", "small", "md"],
+      description: "Dictates the physical width of the left column.",
+    },
+    children: {
+      table: { disable: true },
+    },
+    leftSection: {
+      table: { disable: true },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof FormControlLayout>;
+
+/**
+ * The Default layout demonstrates wrapping a standalone primitive without a Label.
+ * In a stacked layout, an omitted leftSection naturally results in no structural padding.
+ */
+export const Default: Story = {
+  args: {
+    formLayout: "stacked",
+    labelSize: "default",
+    leftSection: (
+      <div
+        style={{ padding: 8, border: "1px dashed #ccc", background: "#fafafa" }}
+      >
+        Left Section Boundary
+      </div>
+    ),
+    children: <Switch label="Input area content" />,
+  },
+};
+
+/**
+ * Demonstrates the stacked layout without a left section.
+ * The input should natively pull flush to the top left since there is no left column.
+ */
+export const StackedLayout: Story = {
+  args: {
+    formLayout: "stacked",
+    labelSize: "default",
+    children: <Switch label="Flush stacked switch" />,
+  },
+};
+
+/**
+ * Demonstrates how a naked boolean primitive perfectly aligns in a side-by-side layout
+ * by utilizing the layout wrapper. The left column maintains its precise design system width
+ * even when `leftSection` is undefined, forcing the component into the correct form column!
+ */
+export const SideBySideLayout: Story = {
+  args: {
+    formLayout: "side-by-side",
+    labelSize: "default",
+    children: <Switch label="Offset switch aligning with grid" />,
+  },
+};

package/src/components/FormControlLayout/FormControlLayout.tsx

@@ -0,0 +1,78 @@
+import React, { forwardRef } from "react";
+import styles from "./FormControlLayout.module.css";
+
+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 const FormControlLayout = forwardRef<
+  HTMLDivElement,
+  FormControlLayoutProps
+>(function FormControlLayout(
+  {
+    formLayout = "stacked",
+    labelSize = "default",
+    controlMaxWidth,
+    controlMinWidth,
+    leftSection,
+    children,
+    className,
+    style,
+    ...rest
+  },
+  ref,
+) {
+  const rootClass = className ? `${styles.root} ${className}` : styles.root;
+
+  // We explicitly render leftSection even if null in side-by-side to preserve the empty grid column bounding constraints.
+  // In stacked layouts, if there is no label, we omit the wrapper to avoid unnecessary padding.
+  const hasLeftContent = leftSection !== undefined && leftSection !== null;
+  const shouldRenderLeft = hasLeftContent || formLayout === "side-by-side";
+
+  return (
+    <div
+      ref={ref}
+      className={rootClass}
+      data-form-layout={formLayout}
+      style={
+        {
+          ...style,
+          ...(controlMaxWidth
+            ? { "--form-control-max-width": controlMaxWidth }
+            : {}),
+          ...(controlMinWidth
+            ? { "--form-control-min-width": controlMinWidth }
+            : {}),
+        } as React.CSSProperties
+      }
+      {...rest}
+    >
+      {shouldRenderLeft && (
+        <div className={styles.leftSection} data-size={labelSize}>
+          {leftSection}
+        </div>
+      )}
+
+      <div className={styles.rightSection}>{children}</div>
+    </div>
+  );
+});
+
+FormControlLayout.displayName = "FormControlLayout";

package/src/components/FormControlWrapper/FormControlWrapper.module.css

@@ -1,46 +1,8 @@
 /* FormControlWrapper.module.css */
 
-.root {
-  display: flex;
-  margin: 0; /* Hardcoded structural reset */
-  padding: 0; /* Hardcoded structural reset */
-  max-width: var(--form-control-max-width, 100%);
-  min-width: var(--form-control-min-width, auto);
-}
-
-/* Base Structural Stacked Layout */
-.root[data-form-layout="stacked"] {
-  flex-direction: column;
-}
-
-/* Base Structural Grid Layout */
-.root[data-form-layout="side-by-side"] {
-  flex-direction: row;
-  align-items: flex-start;
-  flex-wrap: wrap; /* Allows collapse if screen is too thin, though standard flex width should hold */
-}
-
-/* Left structural justification defaults (push input mapping) */
-.root[data-form-alignment="left"] {
-  /* Inherited naturally via row/column flows */
-}
-
-/* Right structural justification defaults */
-.root[data-form-alignment="right"] {
-  /* To justify entire form control components to the right */
-  justify-content: flex-end;
-}
-
-.labelSection {
-  /* Width dimensions are strictly governed natively inside Label.module.css's sizing variant mapping */
-  flex-shrink: 0;
-  display: flex;
-  flex-direction: column;
-}
-
 .inputSection {
-  display: flex; /* Groups internal field alongside subsequent errors/descriptions */
+  display: flex;
   flex-direction: column;
-  flex: 1; /* Consumes the remaining x-axis in grid columns natively */
-  min-width: 0; /* Break boundary preventing internal flex explosion */
+  flex: 1;
+  min-width: 0;
 }