@recursica/mui-adapter 0.6.0 → 0.7.0

package/src/components/Dropdown/Dropdown.tsx

@@ -13,6 +13,8 @@ import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/For
 import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
 import styles from "./Dropdown.module.css";
 
+import { type RecursicaDropdownProps as BaseRecursicaDropdownProps } from "@recursica/adapter-common";
+
 export interface RecursicaDropdownProps
   extends Omit<
       MuiSelectProps,
@@ -29,14 +31,8 @@ export interface RecursicaDropdownProps
       | "labelWithEditIcon"
       | "onLabelEditClick"
     >,
-    ReadOnlyControlProps {
-  /** Internal hook for Selects to override raw layout width properties when necessary */
-  containerWidth?: React.CSSProperties["width"];
-  data?: (string | { value: string; label: ReactNode; disabled?: boolean })[];
-  searchable?: boolean;
-  clearable?: boolean;
-  withAsterisk?: boolean;
-}
+    ReadOnlyControlProps,
+    BaseRecursicaDropdownProps {}
 
 export type DropdownProps = RecursicaOverStyled<RecursicaDropdownProps>;
 
@@ -59,6 +55,7 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
       assistiveWithIcon,
       error,
       required,
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       withAsterisk,
       id,
       className,
@@ -70,7 +67,9 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
       value,
       defaultValue,
       data,
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       searchable, // Not natively supported by basic MUI Select, stubbed
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       clearable, // Not natively supported by basic MUI Select, stubbed
       ...rest
     } = props;
@@ -135,7 +134,6 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
         assistiveWithIcon={assistiveWithIcon}
         error={!!error}
         required={required}
-        withAsterisk={withAsterisk}
         id={id}
         readOnly={readOnly}
         readOnlyComponent={readOnlyComponent}

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

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

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

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

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

@@ -1,35 +1,128 @@
+import React from "react";
 import type { Meta, StoryObj } from "@storybook/react";
 import { Flex } from "./Flex";
-import { ComingSoon } from "@recursica/storybook-template";
+import { Button } from "../Button";
+import { Text } from "../Text/Text";
 
-const meta: Meta<typeof Flex> = {
-  title: "UI-Kit/🚧 Flex",
+type FlexStoryProps = React.ComponentProps<typeof Flex>;
+
+const meta: Meta<FlexStoryProps> = {
+  title: "UI-Kit/Flex",
   component: Flex,
   tags: ["autodocs"],
   parameters: {
-    controls: {
-      include: [
-        "layer",
-        "withLayer",
-        "children",
-        "component",
-        "variant",
-        "size",
-        "icon",
-        "disabled",
-        "href",
-        "onClick",
-        "onChange",
-        "value",
-        "checked",
+    docs: {
+      description: {
+        component:
+          "Flex is a bare-metal flex container that maps directly to Mantine's Flex component, providing unopinionated control over direction, alignment, and wrapping.",
+      },
+    },
+  },
+  args: {
+    gap: "rec-default",
+    align: "center",
+    justify: "flex-start",
+    direction: "row",
+    wrap: "wrap",
+  },
+  argTypes: {
+    gap: {
+      control: "select",
+      options: [
+        "rec-none",
+        "rec-sm",
+        "rec-default",
+        "rec-md",
+        "rec-lg",
+        "rec-xl",
+        "rec-2xl",
+        "xs",
+        "sm",
+        "md",
+        "lg",
+        "xl",
+      ],
+      description: "Gap between elements",
+    },
+    direction: {
+      control: "select",
+      options: ["row", "column", "row-reverse", "column-reverse"],
+      description: "Flex-direction property",
+    },
+    align: {
+      control: "select",
+      options: ["flex-start", "center", "flex-end", "stretch"],
+      description: "Align-items property",
+    },
+    justify: {
+      control: "select",
+      options: [
+        "flex-start",
+        "center",
+        "flex-end",
+        "space-between",
+        "space-around",
       ],
+      description: "Justify-content property",
+    },
+    wrap: {
+      control: "select",
+      options: ["wrap", "nowrap", "wrap-reverse"],
+      description: "Flex-wrap property",
+    },
+    defaultChecked: {
+      table: { disable: true },
+    },
+    rowGap: {
+      table: { disable: true },
+    },
+    columnGap: {
+      table: { disable: true },
     },
   },
 };
 
 export default meta;
-type Story = StoryObj<typeof Flex>;
+
+type Story = StoryObj<FlexStoryProps>;
 
 export const Default: Story = {
-  render: () => <ComingSoon componentName="Flex" />,
+  // 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>
+      <Text>Text inside Flex</Text>
+    </Flex>
+  ),
+};
+
+export const StaticGapSmallColumn: Story = {
+  args: {
+    gap: "rec-sm",
+    direction: "column",
+  },
+  // 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>
+      <Button variant="solid">Item 3</Button>
+    </Flex>
+  ),
+};
+
+export const StaticGapLargeRow: Story = {
+  args: {
+    gap: "rec-xl",
+    direction: "row",
+  },
+  // 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>
+      <Button variant="solid">Item 3</Button>
+    </Flex>
+  ),
 };

package/src/components/Flex/Flex.tsx

@@ -11,41 +11,27 @@
 import React, { forwardRef } from "react";
 import { Box as MUIBox, type BoxProps as MUIBoxProps } from "@mui/material";
 import {
-  type RecursicaSpacing,
   SPACING_MAP,
   type OmitSx,
   filterSxProp,
 } from "../../utils/filterStylingProps";
 
-export interface RecursicaFlexProps {
-  /**
-   * Content to render inside the flex container.
-   */
-  children?: React.ReactNode;
-
-  /**
-   * The gap between flex items. Accepts standard MUI spacing or Recursica gap tokens
-   * (e.g. "rec-md").
-   */
-  gap?: string | number | RecursicaSpacing;
-
-  /**
-   * The vertical gap between flex items when wrapping. Accepts standard MUI spacing
-   * or Recursica gap tokens.
-   */
-  rowGap?: string | number | RecursicaSpacing;
-
-  /**
-   * The horizontal gap between flex items when wrapping. Accepts standard MUI spacing
-   * or Recursica gap tokens.
-   */
-  columnGap?: string | number | RecursicaSpacing;
-}
+import { type RecursicaFlexProps } from "@recursica/adapter-common";
 
 export type FlexProps = OmitSx<MUIBoxProps & RecursicaFlexProps>;
 
 export const Flex = forwardRef<HTMLDivElement, FlexProps>(function Flex(
-  { children, gap = "rec-default", rowGap, columnGap, ...rest },
+  {
+    children,
+    gap = "rec-default",
+    rowGap,
+    columnGap,
+    direction,
+    align,
+    justify,
+    wrap,
+    ...rest
+  },
   ref,
 ) {
   const safeProps = filterSxProp(rest as Record<string, unknown>);
@@ -70,6 +56,10 @@ export const Flex = forwardRef<HTMLDivElement, FlexProps>(function Flex(
       gap={resolvedGap}
       rowGap={resolvedRowGap}
       columnGap={resolvedColumnGap}
+      flexDirection={direction}
+      alignItems={align}
+      justifyContent={justify}
+      flexWrap={wrap}
     >
       {children}
     </MUIBox>

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

@@ -1,5 +1,3 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import React from "react";
 import type { Meta, StoryObj } from "@storybook/react";
 import { FormControlLayout } from "./FormControlLayout";
 import { Switch } from "../Switch/Switch";
@@ -15,9 +13,6 @@ const meta: Meta<typeof FormControlLayout> = {
           "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.",
       },
     },
-    controls: {
-      include: ["formLayout", "labelSize"],
-    },
   },
   tags: ["autodocs"],
   argTypes: {
@@ -59,7 +54,6 @@ export const Default: Story = {
     ),
     children: <Switch label="Input area content" />,
   },
-  render: ({ ...args }: any) => <FormControlLayout {...args} />,
 };
 
 /**
@@ -72,7 +66,6 @@ export const StackedLayout: Story = {
     labelSize: "default",
     children: <Switch label="Flush stacked switch" />,
   },
-  render: ({ ...args }: any) => <FormControlLayout {...args} />,
 };
 
 /**
@@ -86,5 +79,4 @@ export const SideBySideLayout: Story = {
     labelSize: "default",
     children: <Switch label="Offset switch aligning with grid" />,
   },
-  render: ({ ...args }: any) => <FormControlLayout {...args} />,
 };

package/src/components/FormControlLayout/FormControlLayout.tsx

@@ -2,15 +2,12 @@ import React from "react";
 import { filterStylingProps } from "../../utils/filterStylingProps";
 import styles from "./FormControlLayout.module.css";
 
+import { type RecursicaFormControlLayoutProps } from "@recursica/adapter-common";
+
 export interface FormControlLayoutProps
-  extends React.HTMLAttributes<HTMLDivElement> {
+  extends React.HTMLAttributes<HTMLDivElement>,
+    RecursicaFormControlLayoutProps {
   overStyled?: boolean;
-  formLayout?: "stacked" | "side-by-side";
-  labelSize?: "small" | "default" | "md";
-  controlMaxWidth?: string;
-  controlMinWidth?: string;
-  leftSection?: React.ReactNode;
-  children: React.ReactNode;
 }
 
 export const FormControlLayout = React.forwardRef<
@@ -21,9 +18,12 @@ export const FormControlLayout = React.forwardRef<
     overStyled = false,
     formLayout = "stacked",
     labelSize = "default",
+    controlMaxWidth,
+    controlMinWidth,
     leftSection,
     className,
     children,
+    style,
     ...rest
   } = props;
 
@@ -34,6 +34,17 @@ export const FormControlLayout = React.forwardRef<
       ref={ref}
       className={className ? `${styles.root} ${className}` : styles.root}
       data-form-layout={formLayout}
+      style={
+        {
+          ...style,
+          ...(controlMaxWidth
+            ? { "--form-control-max-width": controlMaxWidth }
+            : {}),
+          ...(controlMinWidth
+            ? { "--form-control-min-width": controlMinWidth }
+            : {}),
+        } as React.CSSProperties
+      }
       {...sanitizedProps}
     >
       {/* 

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

@@ -74,21 +74,12 @@
   color: var(--form-field-text-valued);
 }
 
-.inputContainer {
+.inputSection {
   display: flex;
   flex-direction: column;
   flex: 1;
   min-width: 0;
-
-  /* Constrain the input natively to custom properties */
-  max-width: var(--form-control-max-width);
-  min-width: var(--form-control-min-width);
-
-  /* Hook to allow child components to add margin below themselves dynamically 
-     via CSS variables (e.g. padding beneath TextField before AssistiveText renders) */
-  margin-bottom: var(--form-control-margin-bottom);
 }
-
 .assistive {
   margin-top: var(
     --recursica_ui-kit_globals_form_properties_label-field-gap-vertical

package/src/components/FormControlWrapper/FormControlWrapper.stories.tsx

@@ -1,5 +1,3 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import React from "react";
 import type { Meta, StoryObj } from "@storybook/react";
 import {
   FormControlWrapper,
@@ -18,23 +16,9 @@ const meta: Meta<WrapperStoryProps> = {
     docs: {
       description: {
         component:
-          "The `FormControlWrapper` is the ultimate structural replacement for built-in wrapper layouts. By centralizing label tracking, error rendering, ARIA generation, and grid layouts natively inside this single component, we achieve pixel-perfect layout compliance while retaining MUI's internal `useFormControl` Context natively.\n\n### Usage with Naked Primitives\nThis component wraps 'naked' elements directly. The demonstration stories below utilize `<TextField>` as a native display vehicle, since `<TextField>` natively pipes all its properties structurally back into this wrapper.",
+          "The `FormControlWrapper` is the ultimate structural replacement for Mantine's built-in `Input.Wrapper`. By abandoning Mantine's opinionated wrappers entirely, we centralize all label tracking, error rendering, ARIA generation, and grid layouts natively inside this single component.\n\n### Usage with Naked Primitives\nThis component wraps 'naked' elements like `<Input>` directly. The demonstration stories below utilize `<TextField>` as a native display vehicle, since `<TextField>` natively pipes all its properties structurally back into this wrapper.",
       },
     },
-    controls: {
-      include: [
-        "error",
-        "assistiveText",
-        "assistiveWithIcon",
-        "required",
-        "formLayout",
-        "labelSize",
-        "labelAlignment",
-        "labelOptionalText",
-        "labelWithEditIcon",
-        "labelActionArea",
-      ],
-    },
   },
   argTypes: {
     ...formControlArgTypes,
@@ -61,10 +45,15 @@ export default meta;
 
 type Story = StoryObj<WrapperStoryProps>;
 
-const renderWithTextField = ({ ...args }: any) => (
-  // We explicitly cast args to 'any' here because MUI wrapper defines Wrapper anatomy,
+const renderWithTextField = (args: WrapperStoryProps) => (
+  // We explicitly cast args to 'any' here because Mantine enforces strict anatomy types for
+  // 'classNames', 'styles', and 'attributes'. WrapperStoryProps defines these for the Wrapper anatomy,
   // but TextField expects them for the full TextInput anatomy, causing a TS intersection mismatch.
-  <TextField placeholder="Form Control primitive mapped..." {...args} />
+  <TextField
+    placeholder="Form Control primitive mapped..."
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    {...(args as any)}
+  />
 );
 
 export const Default: Story = {
@@ -119,7 +108,8 @@ export const NativeChildrenDirectly: Story = {
     formLayout: "side-by-side",
     assistiveText: "This wraps a raw HTML input tag mapping correctly.",
   },
-  render: ({ ...args }: any) => (
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
     <div
       style={{
         display: "flex",
@@ -127,6 +117,7 @@ export const NativeChildrenDirectly: Story = {
         alignItems: "center",
       }}
     >
+      {/* We can cleanly wrap even un-styled HTML primitives! */}
       <FormControlWrapper {...args}>
         <input
           type="checkbox"

package/src/components/FormControlWrapper/FormControlWrapper.tsx

@@ -6,29 +6,14 @@ import { AssistiveElement } from "../AssistiveElement/AssistiveElement";
 import { FormControlLayout } from "../FormControlLayout/FormControlLayout";
 import styles from "./FormControlWrapper.module.css";
 
+import { type RecursicaFormControlWrapperProps as BaseRecursicaFormControlWrapperProps } from "@recursica/adapter-common";
+
 export interface RecursicaFormControlWrapperProps
-  extends Omit<FormControlProps, "margin" | "variant" | "size" | "color"> {
+  extends Omit<FormControlProps, "margin" | "variant" | "size" | "color">,
+    BaseRecursicaFormControlWrapperProps {
   overStyled?: boolean;
   label?: React.ReactNode;
-  /** Primary assistive description bound natively to the component footer. Maps to MUI's 'helperText' dynamically. */
-  assistiveText?: React.ReactNode;
-  /** Secondary parameter fallback identical to assistiveText to match MUI / Mantine native APIs safely. */
-  description?: React.ReactNode;
-  /** Fallback mapping for MUI's native helperText */
-  helperText?: React.ReactNode;
-  assistiveWithIcon?: boolean;
-
-  formLayout?: "stacked" | "side-by-side";
-  labelSize?: "small" | "default" | "md";
-  labelAlignment?: "left" | "right"; // Currently functionally maps to left automatically natively
-  labelOptionalText?: React.ReactNode | true;
-  labelWithEditIcon?: boolean;
-  onLabelEditClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
-  labelActionArea?: React.ReactNode;
-
-  /** Allows layout mapping to limit the input's bounding box without impacting the label */
-  controlMaxWidth?: string;
-  controlMinWidth?: string;
+  focused?: boolean;
 }
 
 export type FormControlWrapperProps = RecursicaFormControlWrapperProps;
@@ -95,11 +80,16 @@ export const FormControlWrapper = React.forwardRef<
       focused={focused}
       className={className ? `${styles.root} ${className}` : styles.root}
       style={style}
+      data-error={error ? "true" : undefined}
+      data-disabled={disabled ? "true" : undefined}
+      data-focused={focused ? "true" : undefined}
       {...(sanitizedProps as FormControlProps)}
     >
       <FormControlLayout
         formLayout={formLayout}
         labelSize={labelSize}
+        controlMaxWidth={controlMaxWidth}
+        controlMinWidth={controlMinWidth}
         leftSection={
           label && (
             <Label
@@ -116,15 +106,7 @@ export const FormControlWrapper = React.forwardRef<
           )
         }
       >
-        <div
-          className={styles.inputContainer}
-          style={
-            {
-              "--form-control-max-width": controlMaxWidth,
-              "--form-control-min-width": controlMinWidth,
-            } as React.CSSProperties
-          }
-        >
+        <div className={styles.inputSection}>
           {/* Natively wrap children into flex box */}
           {mappedChildren}
 
@@ -134,7 +116,6 @@ export const FormControlWrapper = React.forwardRef<
               id={descriptionId}
               assistiveVariant={error ? "error" : "help"}
               assistiveWithIcon={assistiveWithIcon}
-              className={styles.assistive}
             >
               {error && typeof error === "string" ? error : finalAssistiveText}
             </AssistiveElement>

package/src/components/Group/Group.stories.tsx

@@ -17,36 +17,12 @@ const meta: Meta<GroupStoryProps> = {
           "Group is a flex horizontal layout container that maps directly to Mantine's Group component allowing safe layout property passing.",
       },
     },
-    controls: {
-      include: [
-        "layer",
-        "withLayer",
-        "gap",
-        "alignItems",
-        "justifyContent",
-        "flexWrap",
-        "defaultChecked",
-        "rowGap",
-        "columnGap",
-        "children",
-        "component",
-        "variant",
-        "size",
-        "icon",
-        "disabled",
-        "href",
-        "onClick",
-        "onChange",
-        "value",
-        "checked",
-      ],
-    },
   },
   args: {
     gap: "rec-default",
-    alignItems: "center",
-    justifyContent: "flex-start",
-    flexWrap: "wrap",
+    align: "center",
+    justify: "flex-start",
+    wrap: "wrap",
   },
   argTypes: {
     gap: {
@@ -67,12 +43,12 @@ const meta: Meta<GroupStoryProps> = {
       ],
       description: "Gap between elements",
     },
-    alignItems: {
+    align: {
       control: "select",
       options: ["flex-start", "center", "flex-end", "stretch"],
       description: "Align-items property",
     },
-    justifyContent: {
+    justify: {
       control: "select",
       options: [
         "flex-start",
@@ -83,7 +59,7 @@ const meta: Meta<GroupStoryProps> = {
       ],
       description: "Justify-content property",
     },
-    flexWrap: {
+    wrap: {
       control: "select",
       options: ["wrap", "nowrap", "wrap-reverse"],
       description: "Flex-wrap property",