@recursica/mantine-adapter 0.10.0 → 0.12.0

package/src/components/Menu/Menu.tsx

@@ -1,7 +1,320 @@
-import React from "react";
+import { forwardRef } from "react";
+import {
+  Menu as MantineMenu,
+  type MenuProps as MantineMenuProps,
+  type MenuTargetProps as MantineMenuTargetProps,
+  type MenuDropdownProps as MantineMenuDropdownProps,
+  type MenuItemProps as MantineMenuItemProps,
+  type MenuDividerProps as MantineMenuDividerProps,
+  type MenuLabelProps as MantineMenuLabelProps,
+  type MenuSubProps as MantineMenuSubProps,
+  type MenuSubTargetProps as MantineMenuSubTargetProps,
+  type MenuSubDropdownProps as MantineMenuSubDropdownProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Menu.module.css";
 
-export type MenuProps = React.HTMLAttributes<HTMLDivElement>;
+// ============================================================
+// MENU ROOT
+// ============================================================
 
-export const Menu: React.FC<MenuProps> = (props) => {
-  return <div {...props}>Menu</div>;
+/**
+ * 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>;
+
+const MenuBase = function Menu({ overStyled = false, ...rest }: MenuProps) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+
+  // Bind CSS module classes to Mantine's internal classNames API
+  const mergedClassNames: Partial<Record<string, string>> = {
+    dropdown: styles.dropdown,
+    item: styles.item,
+    itemLabel: styles.itemLabel,
+    itemSection: styles.itemSection,
+    divider: styles.divider,
+    label: styles.label,
+    chevron: styles.chevron,
+  };
+
+  const classNamesProp = (sanitizedProps as Record<string, unknown>).classNames;
+  if (
+    classNamesProp &&
+    typeof classNamesProp === "object" &&
+    !Array.isArray(classNamesProp)
+  ) {
+    const o = classNamesProp as Record<string, string>;
+    Object.keys(o).forEach((key) => {
+      if (mergedClassNames[key]) {
+        mergedClassNames[key] = `${mergedClassNames[key]} ${o[key]}`;
+      } else {
+        mergedClassNames[key] = o[key];
+      }
+    });
+  }
+
+  return (
+    <MantineMenu
+      classNames={mergedClassNames}
+      {...(sanitizedProps as unknown as MantineMenuProps)}
+    />
+  );
 };
+MenuBase.displayName = "Menu";
+
+// ============================================================
+// MENU TARGET
+// ============================================================
+
+/**
+ * Wrapper for the element that triggers the menu.
+ * Requires a single child element that supports ref forwarding.
+ */
+export type MenuTargetProps = MantineMenuTargetProps;
+
+const MenuTarget = function MenuTarget(props: MenuTargetProps) {
+  return <MantineMenu.Target {...props} />;
+};
+MenuTarget.displayName = "MenuTarget";
+
+// ============================================================
+// MENU DROPDOWN
+// ============================================================
+
+/** The dropdown panel containing menu items, dividers, and labels. */
+export type MenuDropdownProps = RecursicaOverStyled<MantineMenuDropdownProps>;
+
+const MenuDropdown = forwardRef<HTMLDivElement, MenuDropdownProps>(
+  function MenuDropdown({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const classNameProp = (sanitizedProps as Record<string, unknown>)
+      .className as string | undefined;
+
+    return (
+      <MantineMenu.Dropdown
+        ref={ref}
+        className={classNameProp}
+        {...(sanitizedProps as unknown as MantineMenuDropdownProps)}
+      />
+    );
+  },
+);
+MenuDropdown.displayName = "MenuDropdown";
+
+// ============================================================
+// MENU ITEM
+// ============================================================
+
+/**
+ * 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">
+>;
+
+const MenuItem = forwardRef<HTMLButtonElement, MenuItemProps>(function MenuItem(
+  { overStyled = false, ...rest },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
+  // Strip Mantine's `color` prop to enforce token-driven styling
+  if (!overStyled) {
+    delete restRecord["color"];
+  }
+
+  const classNameProp = restRecord.className as string | undefined;
+
+  return (
+    <MantineMenu.Item
+      ref={ref}
+      className={classNameProp}
+      {...(sanitizedProps as unknown as MantineMenuItemProps)}
+    />
+  );
+});
+MenuItem.displayName = "MenuItem";
+
+// ============================================================
+// MENU DIVIDER
+// ============================================================
+
+/** A visual separator between groups of menu items. */
+export type MenuDividerProps = RecursicaOverStyled<MantineMenuDividerProps>;
+
+const MenuDivider = forwardRef<HTMLHRElement, MenuDividerProps>(
+  function MenuDivider({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const classNameProp = (sanitizedProps as Record<string, unknown>)
+      .className as string | undefined;
+
+    return (
+      <MantineMenu.Divider
+        ref={ref}
+        className={classNameProp}
+        {...(sanitizedProps as unknown as MantineMenuDividerProps)}
+      />
+    );
+  },
+);
+MenuDivider.displayName = "MenuDivider";
+
+// ============================================================
+// MENU LABEL
+// ============================================================
+
+/** A non-interactive section label used to categorize groups of menu items. */
+export type MenuLabelProps = RecursicaOverStyled<MantineMenuLabelProps>;
+
+const MenuLabel = forwardRef<HTMLDivElement, MenuLabelProps>(function MenuLabel(
+  { overStyled = false, ...rest },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const classNameProp = (sanitizedProps as Record<string, unknown>)
+    .className as string | undefined;
+
+  return (
+    <MantineMenu.Label
+      ref={ref}
+      className={classNameProp}
+      {...(sanitizedProps as unknown as MantineMenuLabelProps)}
+    />
+  );
+});
+MenuLabel.displayName = "MenuLabel";
+
+// ============================================================
+// MENU SUB (SUBMENU CONTAINER)
+// ============================================================
+
+/** Container for a submenu, wrapping Menu.Sub.Target and Menu.Sub.Dropdown. */
+export type MenuSubProps = MantineMenuSubProps;
+
+const MenuSubBase = function MenuSub(props: MenuSubProps) {
+  return <MantineMenu.Sub {...props} />;
+};
+MenuSubBase.displayName = "MenuSub";
+
+// ============================================================
+// MENU SUB TARGET
+// ============================================================
+
+/** Wrapper for the element that triggers the submenu. */
+export type MenuSubTargetProps = MantineMenuSubTargetProps;
+
+const MenuSubTarget = function MenuSubTarget(props: MenuSubTargetProps) {
+  return <MantineMenu.Sub.Target {...props} />;
+};
+MenuSubTarget.displayName = "MenuSubTarget";
+
+// ============================================================
+// MENU SUB ITEM (triggers submenu)
+// ============================================================
+
+/**
+ * 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">
+>;
+
+const MenuSubItem = forwardRef<HTMLButtonElement, MenuSubItemProps>(
+  function MenuSubItem({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    if (!overStyled) {
+      delete restRecord["color"];
+    }
+
+    const classNameProp = restRecord.className as string | undefined;
+
+    return (
+      <MantineMenu.Sub.Item
+        ref={ref}
+        className={classNameProp}
+        {...(sanitizedProps as unknown as MantineMenuItemProps)}
+      />
+    );
+  },
+);
+MenuSubItem.displayName = "MenuSubItem";
+
+// ============================================================
+// MENU SUB DROPDOWN
+// ============================================================
+
+/** The dropdown panel for a submenu. */
+export type MenuSubDropdownProps =
+  RecursicaOverStyled<MantineMenuSubDropdownProps>;
+
+const MenuSubDropdown = forwardRef<HTMLDivElement, MenuSubDropdownProps>(
+  function MenuSubDropdown({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const classNameProp = (sanitizedProps as Record<string, unknown>)
+      .className as string | undefined;
+
+    return (
+      <MantineMenu.Sub.Dropdown
+        ref={ref}
+        className={classNameProp}
+        {...(sanitizedProps as unknown as MantineMenuSubDropdownProps)}
+      />
+    );
+  },
+);
+MenuSubDropdown.displayName = "MenuSubDropdown";
+
+// ============================================================
+// DOT NOTATION EXPORT
+// ============================================================
+
+type MenuSubComponent = typeof MenuSubBase & {
+  Target: typeof MenuSubTarget;
+  Item: typeof MenuSubItem;
+  Dropdown: typeof MenuSubDropdown;
+};
+
+const MenuSub = MenuSubBase as MenuSubComponent;
+MenuSub.Target = MenuSubTarget;
+MenuSub.Item = MenuSubItem;
+MenuSub.Dropdown = MenuSubDropdown;
+
+type MenuComponent = typeof MenuBase & {
+  Target: typeof MenuTarget;
+  Dropdown: typeof MenuDropdown;
+  Item: typeof MenuItem;
+  Divider: typeof MenuDivider;
+  Label: typeof MenuLabel;
+  Sub: MenuSubComponent;
+};
+
+export const Menu = MenuBase as MenuComponent;
+Menu.Target = MenuTarget;
+Menu.Dropdown = MenuDropdown;
+Menu.Item = MenuItem;
+Menu.Divider = MenuDivider;
+Menu.Label = MenuLabel;
+Menu.Sub = MenuSub;

package/src/components/NumberInput/NumberInput.stories.tsx

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

package/src/components/Radio/Radio.stories.tsx

@@ -18,9 +18,6 @@ The \`Radio\` component represents a fundamental standalone boolean selection no
     },
   },
   argTypes: {
-    disabled: {
-      control: "boolean",
-    },
     checked: {
       control: "boolean",
     },
@@ -33,6 +30,8 @@ The \`Radio\` component represents a fundamental standalone boolean selection no
     defaultChecked: {
       control: "boolean",
     },
+    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 CheckedState: Story = {
   args: {
     ...Default.args,
@@ -68,9 +74,17 @@ export const DisabledChecked: Story = {
   },
 };
 
-export const ReadOnlyStandalone: Story = {
-  args: {
-    readOnly: true,
-    readOnlyComponent: <span>Locked Native Value</span>,
-  },
+export const ReadOnly: Story = {
+  args: {},
+  render: () => (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "24px",
+      }}
+    >
+      <Radio label="Account Type" defaultChecked readOnly />
+    </div>
+  ),
 };

package/src/components/Radio/Radio.tsx

@@ -9,6 +9,12 @@ import {
   filterStylingProps,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
+import { type RequireAccessibleLabel } from "../../utils/RequireAccessibleLabel";
+import {
+  FormControlLayout,
+  type FormControlLayoutProps,
+} from "../FormControlLayout/FormControlLayout";
+
 import styles from "./Radio.module.css";
 
 const RadioIcon: React.FC<{
@@ -26,11 +32,17 @@ const RadioIcon: React.FC<{
   </svg>
 );
 
-export type RecursicaRadioProps = Omit<
-  MantineRadioProps,
-  "size" | "color" | "radius" | "iconColor" | "variant"
-> &
-  ReadOnlyControlProps;
+export type RecursicaRadioProps = RequireAccessibleLabel<
+  Omit<
+    MantineRadioProps,
+    "size" | "color" | "radius" | "iconColor" | "variant"
+  > &
+    ReadOnlyControlProps &
+    Pick<
+      FormControlLayoutProps,
+      "formLayout" | "labelSize" | "controlMaxWidth" | "controlMinWidth"
+    >
+>;
 
 export type RadioProps = RecursicaOverStyled<RecursicaRadioProps>;
 
@@ -40,76 +52,123 @@ type RadioComponent = React.ForwardRefExoticComponent<
   Group: typeof RadioGroup;
 };
 
-export const Radio = forwardRef<HTMLInputElement, RadioProps>(function Radio(
-  { overStyled = false, readOnly, readOnlyComponent, disabled, ...rest },
-  ref,
-) {
-  const sanitizedProps = filterStylingProps(rest, overStyled);
-  const restRecord = sanitizedProps as Record<string, unknown>;
-
-  // Actively delete dimension bindings that bypass the abstraction
-  delete restRecord["size"];
-  delete restRecord["color"];
-  delete restRecord["radius"];
-  delete restRecord["variant"];
-  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,
-    inner: styles.inner,
-    radio: styles.radio,
-    icon: styles.icon,
-    labelWrapper: styles.labelWrapper,
-    label: styles.label,
-  };
-
-  const classNamesProp = restRecord.classNames;
-  if (
-    classNamesProp &&
-    typeof classNamesProp === "object" &&
-    !Array.isArray(classNamesProp)
-  ) {
-    const o = classNamesProp as Partial<Record<string, string>>;
-    mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
-    mergedClassNames.body = o.body ? `${styles.body} ${o.body}` : styles.body;
-    mergedClassNames.inner = o.inner
-      ? `${styles.inner} ${o.inner}`
-      : styles.inner;
-    mergedClassNames.radio = o.radio
-      ? `${styles.radio} ${o.radio}`
-      : styles.radio;
-    mergedClassNames.icon = o.icon ? `${styles.icon} ${o.icon}` : styles.icon;
-    mergedClassNames.labelWrapper = o.labelWrapper
-      ? `${styles.labelWrapper} ${o.labelWrapper}`
-      : styles.labelWrapper;
-    mergedClassNames.label = o.label
-      ? `${styles.label} ${o.label}`
-      : styles.label;
-  }
-
-  const classNameProp = restRecord.className as string | undefined;
-  const finalClass = classNameProp
-    ? `${styles.root} ${classNameProp}`
-    : styles.root;
-
-  // We omit Mantine's sizing/coloring so we rely strictly on variables from Radio.module.css
-  return (
-    <MantineRadio
-      ref={ref}
-      icon={RadioIcon}
-      className={finalClass}
-      classNames={mergedClassNames}
-      disabled={readOnly || disabled}
-      {...(sanitizedProps as unknown as MantineRadioProps)}
-    />
-  );
-}) as RadioComponent;
+export const Radio = forwardRef<HTMLInputElement, RadioProps>(
+  function Radio(props, ref) {
+    const {
+      overStyled = false,
+      readOnly,
+      readOnlyComponent,
+      disabled,
+      formLayout,
+      labelSize,
+      controlMaxWidth,
+      controlMinWidth,
+      ...rest
+    } = props;
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    // Actively delete dimension bindings that bypass the abstraction
+    delete restRecord["size"];
+    delete restRecord["color"];
+    delete restRecord["radius"];
+    delete restRecord["variant"];
+    delete restRecord["iconColor"];
+
+    const mergedClassNames: Partial<Record<string, string>> = {
+      root: styles.root,
+      body: styles.body,
+      inner: styles.inner,
+      radio: styles.radio,
+      icon: styles.icon,
+      labelWrapper: styles.labelWrapper,
+      label: styles.label,
+    };
+
+    const classNamesProp = restRecord.classNames;
+    if (
+      classNamesProp &&
+      typeof classNamesProp === "object" &&
+      !Array.isArray(classNamesProp)
+    ) {
+      const o = classNamesProp as Partial<Record<string, string>>;
+      mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
+      mergedClassNames.body = o.body ? `${styles.body} ${o.body}` : styles.body;
+      mergedClassNames.inner = o.inner
+        ? `${styles.inner} ${o.inner}`
+        : styles.inner;
+      mergedClassNames.radio = o.radio
+        ? `${styles.radio} ${o.radio}`
+        : styles.radio;
+      mergedClassNames.icon = o.icon ? `${styles.icon} ${o.icon}` : styles.icon;
+      mergedClassNames.labelWrapper = o.labelWrapper
+        ? `${styles.labelWrapper} ${o.labelWrapper}`
+        : styles.labelWrapper;
+      mergedClassNames.label = o.label
+        ? `${styles.label} ${o.label}`
+        : styles.label;
+    }
+
+    const classNameProp = restRecord.className as string | undefined;
+    const finalClass = classNameProp
+      ? `${styles.root} ${classNameProp}`
+      : styles.root;
+
+    if (readOnly && !!readOnlyComponent) {
+      const isChecked = !!(restRecord.checked ?? restRecord.defaultChecked);
+      const ReadOnlyComp = readOnlyComponent;
+      const roNode = (
+        <ReadOnlyComp
+          {...props}
+          checked={isChecked}
+          label={restRecord.label as React.ReactNode}
+        />
+      );
+
+      if (formLayout) {
+        return (
+          <FormControlLayout
+            formLayout={formLayout}
+            labelSize={labelSize}
+            controlMaxWidth={controlMaxWidth}
+            controlMinWidth={controlMinWidth}
+          >
+            {roNode}
+          </FormControlLayout>
+        );
+      }
+
+      return <>{roNode}</>;
+    }
+
+    // We omit Mantine's sizing/coloring so we rely strictly on variables from Radio.module.css
+    const radioNode = (
+      <MantineRadio
+        ref={ref}
+        icon={RadioIcon}
+        className={finalClass}
+        classNames={mergedClassNames}
+        disabled={readOnly || disabled}
+        {...(sanitizedProps as unknown as MantineRadioProps)}
+      />
+    );
+
+    if (formLayout) {
+      return (
+        <FormControlLayout
+          formLayout={formLayout}
+          labelSize={labelSize}
+          controlMaxWidth={controlMaxWidth}
+          controlMinWidth={controlMinWidth}
+        >
+          {radioNode}
+        </FormControlLayout>
+      );
+    }
+
+    return radioNode;
+  },
+) as RadioComponent;
 
 Radio.displayName = "Radio";
 Radio.Group = RadioGroup;