@recursica/mantine-adapter 0.10.0 → 0.12.0

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

@@ -1,4 +1,3 @@
-import React from "react";
 import type { Meta, StoryObj } from "@storybook/react";
 import {
   FormControlWrapper,
@@ -47,7 +46,14 @@ export default meta;
 type Story = StoryObj<WrapperStoryProps>;
 
 const renderWithTextField = (args: WrapperStoryProps) => (
-  <TextField placeholder="Form Control primitive mapped..." {...args} />
+  // 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..."
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    {...(args as any)}
+  />
 );
 
 export const Default: Story = {
@@ -89,14 +95,21 @@ export const WithoutAssistiveIcons: Story = {
 };
 
 export const NativeChildrenDirectly: Story = {
-  description:
-    "Bypassing the TextField map to show exactly how native `<input>` hooks execute inside the raw wrapper natively perfectly.",
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Bypassing the TextField map to show exactly how native `<input>` hooks execute inside the raw wrapper natively perfectly.",
+      },
+    },
+  },
   args: {
     label: "Raw HTML Checkbox",
     formLayout: "side-by-side",
     assistiveText: "This wraps a raw HTML input tag mapping correctly.",
   },
-  render: (args) => (
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
     <div
       style={{
         display: "flex",

package/src/components/FormControlWrapper/FormControlWrapper.tsx

@@ -1,14 +1,17 @@
 import React, { forwardRef, useId } from "react";
-import { type InputWrapperProps, Box } from "@mantine/core";
+import { type InputWrapperProps } from "@mantine/core";
 import {
   filterStylingProps,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import { Label, type RecursicaLabelProps } from "../Label/Label";
+import { FormControlLayout } from "../FormControlLayout/FormControlLayout";
 import { AssistiveElement } from "../AssistiveElement/AssistiveElement";
 import styles from "./FormControlWrapper.module.css";
 
 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. */
@@ -93,51 +96,35 @@ export const FormControlWrapper = forwardRef<
       )
     : children;
 
+  const labelNode = label ? (
+    <Label
+      id={id} // Directly binds ARIA references down
+      labelAlignment={labelAlignment}
+      labelOptionalText={labelOptionalText}
+      labelWithEditIcon={labelWithEditIcon}
+      labelActionArea={labelActionArea}
+      onLabelEditClick={onLabelEditClick}
+      required={withAsterisk ?? required}
+      // Manually propagate relevant structural logic if underlying groups dictate Label to act as generic wrapper
+      {...(labelElement === "div" ? { as: "div" } : {})}
+    >
+      {label}
+    </Label>
+  ) : undefined;
+
   return (
-    <Box
+    <FormControlLayout
       ref={ref}
       className={finalClass}
-      data-form-layout={formLayout || "stacked"}
-      data-form-alignment={labelAlignment || "left"}
-      style={
-        {
-          ...((restRecord.style as React.CSSProperties) || {}),
-          ...(controlMaxWidth
-            ? { "--form-control-max-width": controlMaxWidth }
-            : {}),
-          ...(controlMinWidth
-            ? { "--form-control-min-width": controlMinWidth }
-            : {}),
-        } as React.CSSProperties
-      }
+      formLayout={formLayout}
+      labelSize={labelSize}
+      controlMaxWidth={controlMaxWidth}
+      controlMinWidth={controlMinWidth}
+      leftSection={labelNode}
       {...restRecord}
     >
-      {/* 
-        Section 1: The Native Custom Label
-        Bypasses Mantine's built-in Input.Wrapper Label entirely in favor of explicit Recursica formatting.
-      */}
-      {label && (
-        <div className={styles.labelSection}>
-          <Label
-            id={id} // Directly binds ARIA references down
-            formLayout={formLayout}
-            labelSize={labelSize}
-            labelAlignment={labelAlignment}
-            labelOptionalText={labelOptionalText}
-            labelWithEditIcon={labelWithEditIcon}
-            labelActionArea={labelActionArea}
-            onLabelEditClick={onLabelEditClick}
-            required={withAsterisk ?? required}
-            // Manually propagate relevant structural logic if underlying groups dictate Label to act as generic wrapper
-            {...(labelElement === "div" ? { as: "div" } : {})}
-          >
-            {label}
-          </Label>
-        </div>
-      )}
-
       {/*
-        Section 2: The Core Input Wrapper & Controls
+        The Core Input Wrapper & Controls
         Nakedly inject the actual field elements alongside natively bridged Assistive components mapped dynamically.
       */}
       <div className={styles.inputSection}>
@@ -163,7 +150,7 @@ export const FormControlWrapper = forwardRef<
           </AssistiveElement>
         )}
       </div>
-    </Box>
+    </FormControlLayout>
   );
 });
 

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

@@ -81,7 +81,8 @@ export default meta;
 type Story = StoryObj<GroupStoryProps>;
 
 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) => (
     <Group {...args}>
       <Button variant="solid">Primary</Button>
       <Button variant="outline">Secondary</Button>
@@ -94,7 +95,8 @@ export const StaticGapSmall: Story = {
   args: {
     gap: "rec-sm",
   },
-  render: (args) => (
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
     <Group {...args}>
       <Button variant="solid">Item 1</Button>
       <Button variant="solid">Item 2</Button>
@@ -107,7 +109,8 @@ export const StaticGapLarge: Story = {
   args: {
     gap: "rec-xl",
   },
-  render: (args) => (
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
     <Group {...args}>
       <Button variant="solid">Item 1</Button>
       <Button variant="solid">Item 2</Button>

package/src/components/Label/Label.module.css

@@ -23,43 +23,6 @@
   text-align: right;
 }
 
-.root[data-layout="stacked"] {
-  padding-bottom: var(
-    --recursica_ui-kit_components_label_variants_layouts_stacked_properties_bottom-padding
-  );
-  min-height: var(
-    --recursica_ui-kit_components_label_variants_layouts_stacked_properties_min-height
-  );
-}
-
-.root[data-layout="side-by-side"] {
-  padding-top: var(
-    --recursica_ui-kit_components_label_variants_layouts_side-by-side_properties_vertical-padding
-  );
-  padding-bottom: var(
-    --recursica_ui-kit_components_label_variants_layouts_side-by-side_properties_vertical-padding
-  );
-  min-height: var(
-    --recursica_ui-kit_components_label_variants_layouts_side-by-side_properties_min-height
-  );
-  /* In side-by-side, the label 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
-  );
-}
-
-.root[data-layout="side-by-side"][data-size="default"] {
-  width: var(
-    --recursica_ui-kit_components_label_variants_layouts_side-by-side_variants_sizes_default_properties_width
-  );
-}
-
-.root[data-layout="side-by-side"][data-size="small"] {
-  width: var(
-    --recursica_ui-kit_components_label_variants_layouts_side-by-side_variants_sizes_small_properties_width
-  );
-}
-
 .labelText {
   order: 1;
   font-family: var(

package/src/components/Label/Label.stories.tsx

@@ -40,7 +40,7 @@ const renderWithTextField = ({ children, ...args }: LabelStoryProps) => (
 export const Default: Story = {
   args: {
     children: "Dynamic Label (Controls)",
-    formLayout: "stacked",
+
     labelSize: "default",
     labelAlignment: "left",
     required: false,
@@ -53,7 +53,6 @@ export const Default: Story = {
 export const StackedDefault: Story = {
   args: {
     children: "Email Address",
-    formLayout: "stacked",
   },
   render: renderWithTextField,
 };
@@ -61,7 +60,7 @@ export const StackedDefault: Story = {
 export const StackedRequired: Story = {
   args: {
     children: "Primary Network Node",
-    formLayout: "stacked",
+
     required: true,
   },
   render: renderWithTextField,
@@ -70,7 +69,7 @@ export const StackedRequired: Story = {
 export const StackedWithEditIcon: Story = {
   args: {
     children: "Environment Variables",
-    formLayout: "stacked",
+
     labelWithEditIcon: true,
   },
   render: renderWithTextField,
@@ -79,7 +78,7 @@ export const StackedWithEditIcon: Story = {
 export const SideBySideDefault: Story = {
   args: {
     children: "Status",
-    formLayout: "side-by-side",
+
     labelSize: "default",
   },
   render: renderWithTextField,
@@ -88,7 +87,7 @@ export const SideBySideDefault: Story = {
 export const RequiredSuppressesOptionalText: Story = {
   args: {
     children: "Full Name",
-    formLayout: "stacked",
+
     required: true,
     labelOptionalText: "This should not render",
   },
@@ -98,7 +97,7 @@ export const RequiredSuppressesOptionalText: Story = {
 export const BooleanOptionalText: Story = {
   args: {
     children: "Middle Initial",
-    formLayout: "side-by-side",
+
     labelOptionalText: true,
   },
   render: renderWithTextField,
@@ -107,7 +106,7 @@ export const BooleanOptionalText: Story = {
 export const WithEditIcon: Story = {
   args: {
     children: "Shipping Address",
-    formLayout: "side-by-side",
+
     labelWithEditIcon: true,
   },
   render: renderWithTextField,
@@ -116,7 +115,7 @@ export const WithEditIcon: Story = {
 export const LayerOneSideBySide: Story = {
   args: {
     children: "Configuration",
-    formLayout: "side-by-side",
+
     labelWithEditIcon: true,
   },
   render: renderWithTextField,

package/src/components/Label/Label.tsx

@@ -7,10 +7,8 @@ import {
 import styles from "./Label.module.css";
 
 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. */
@@ -29,7 +27,6 @@ export type LabelProps = RecursicaOverStyled<
 
 export const Label = forwardRef<HTMLLabelElement, LabelProps>(function Label(
   {
-    formLayout = "stacked",
     labelSize = "default",
     labelAlignment,
     required = false,
@@ -43,8 +40,7 @@ export const Label = forwardRef<HTMLLabelElement, LabelProps>(function Label(
   },
   ref,
 ) {
-  const resolvedAlignment =
-    labelAlignment || (formLayout === "side-by-side" ? "right" : "left");
+  const resolvedAlignment = labelAlignment || "left";
 
   let resolvedOptionalText: React.ReactNode | undefined;
   if (!required) {
@@ -85,7 +81,6 @@ export const Label = forwardRef<HTMLLabelElement, LabelProps>(function Label(
       ref={ref}
       className={finalClass}
       classNames={mergedClassNames}
-      data-layout={formLayout}
       data-size={labelSize}
       data-alignment={resolvedAlignment}
       required={required && !labelWithEditIcon}

package/src/components/Loader/Loader.stories.tsx

@@ -54,7 +54,8 @@ export const Default: Story = {
     size: "default",
     layer: 0,
   },
-  render: ({ layer, ...args }) => (
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
     <Layer layer={layer ?? 0} style={{ padding: "24px" }}>
       <Loader {...args} />
     </Layer>
@@ -66,7 +67,8 @@ export const StaticOvalDefault: Story = {
     variant: "oval",
     size: "default",
   },
-  render: (args) => <Loader {...args} />,
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => <Loader {...args} />,
 };
 
 export const StaticBarsLarge: Story = {
@@ -74,7 +76,8 @@ export const StaticBarsLarge: Story = {
     variant: "bars",
     size: "large",
   },
-  render: (args) => <Loader {...args} />,
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => <Loader {...args} />,
 };
 
 export const StaticDotsSmall: Story = {
@@ -82,7 +85,8 @@ export const StaticDotsSmall: Story = {
     variant: "dots",
     size: "sm",
   },
-  render: (args) => <Loader {...args} />,
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => <Loader {...args} />,
 };
 
 export const LayerTwoOval: Story = {
@@ -90,7 +94,8 @@ export const LayerTwoOval: Story = {
     variant: "oval",
     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={2} style={{ padding: "24px" }}>
       <Loader {...args} />
     </Layer>

package/src/components/Menu/MENU_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,78 @@
+# Menu – Implementation Notes
+
+Decisions and design tweaks strictly tailored for the UI Kit's Menu wrapped against `@mantine/core`. This is a living document that tracks _why_ specific logic decisions exist.
+
+---
+
+## 1. Composable API Preservation (1:1 Mapping)
+
+**Decision:** We maintain the exact library composition API structure (`<Menu>`, `<Menu.Target>`, `<Menu.Dropdown>`, `<Menu.Item>`, `<Menu.Divider>`, `<Menu.Label>`, `<Menu.Sub>`, `<Menu.Sub.Target>`, `<Menu.Sub.Item>`, `<Menu.Sub.Dropdown>`) as a 1:1 React component mapping.
+
+**Implementation:** Mantine's Menu internally manages WAI-ARIA role assignments (`role="menu"`, `role="menuitem"`, `aria-haspopup`, `aria-expanded`, `aria-controls`), keyboard navigation (arrow keys, Enter, Escape), and focus trapping natively across its composable hierarchy. By preserving the exact sub-component tree, Recursica safely adopts all of these accessibility behaviors without reimplementation.
+
+---
+
+## 2. Hover State Overlay Technique
+
+**Decision:** We nullify Mantine's native hover background on `Menu.Item` and exclusively utilize Recursica's hover structure via a `::after` pseudo-element overlay.
+
+**Implementation:** The `.item::after` pseudo-object dynamically pulls `hover-color` & `hover-opacity` bindings from the Recursica token system. Mantine natively changes `background-color` on item hover which would override our token-driven colors. We enforce `background-color` to remain the unselected-item background on hover, then layer our pseudo-overlay on top. This is the same technique used in the Accordion component.
+
+---
+
+## 3. Selected vs Unselected Item States
+
+**Decision:** Menu items map to Recursica's `selected-item` and `unselected-item` color token groups.
+
+**Implementation:** The CSS module defaults all items to `unselected-item_*` tokens (background, text, opacity). Items with `[data-selected]` switch to `selected-item_*` tokens. This mapping is natively driven by Mantine's internal state tracking without React state hooks.
+
+---
+
+## 4. `color` Prop Stripping
+
+**Decision:** Mantine's `color` prop on `Menu.Item` (used for semantics like "danger/red") is explicitly stripped in strict mode.
+
+**Implementation:** The `color` prop is deleted from the sanitized props when `overStyled` is `false`. This enforces strict design token adherence — all item colors come from the CSS module referencing Recursica variables. Developers requiring custom color semantics must either:
+
+1. Use `overStyled={true}` as an explicit escape hatch
+2. Contribute a proper Recursica variant to the token system
+
+**Rationale:** The Recursica token set does not currently include danger-specific or semantic-color variants for menu items. Allowing arbitrary `color` values would break design system consistency.
+
+---
+
+## 5. Menu.Target Pass-Through
+
+**Decision:** `Menu.Target` is a transparent pass-through with no styling applied.
+
+**Implementation:** The target wrapper exists solely to manage Mantine's ref forwarding and event binding for the trigger element. No `filterStylingProps` or CSS module classes are applied — the trigger's appearance is entirely controlled by whatever component the integrator places inside it (e.g., `<Button>`).
+
+---
+
+## 6. Sub-Menu Support
+
+**Decision:** We wrap the full Mantine sub-menu hierarchy (`Menu.Sub`, `Menu.Sub.Target`, `Menu.Sub.Item`, `Menu.Sub.Dropdown`).
+
+**Implementation:** Sub-menu components inherit the same CSS module classes as their top-level counterparts since the Recursica token set does not distinguish sub-menu-specific styling. `Menu.Sub.Item` also strips the `color` prop in strict mode, consistent with `Menu.Item`. The sub-menu dropdown portal inherits the same `classNames` from the root Menu's `classNames` mapping.
+
+---
+
+## 7. Dropdown Container Padding
+
+**Decision:** The dropdown container uses `divider-item-gap` as its internal padding.
+
+**Implementation:** This ensures consistent spacing between the dropdown border and its content items. The gap token (`4px` by default) creates a subtle inset that visually separates items from the container edge, matching the Figma design specifications.
+
+---
+
+## 8. Minimal CSS Override Philosophy
+
+**Decision:** The CSS module only overrides visual design tokens (colors, typography, spacing, borders, shadows). All structural layout properties (flex, cursor, pointer-events, box-sizing, etc.) are deferred to Mantine's native behavior.
+
+**Implementation:** Unlike form-field components (e.g., Dropdown/TextField) which require deep structural overrides to strip Mantine's macro wrappers, the Menu is an overlay component where Mantine's native layout is already correct. We avoid setting:
+
+- `overflow` on the dropdown (Mantine renders sub-menu dropdowns inside the parent DOM tree using Floating UI absolute positioning — setting overflow clips them)
+- `display`, `align-items`, `width`, `cursor` on items (Mantine's button-based items already handle this)
+- `pointer-events` on disabled items (Mantine handles disabled natively)
+
+**Rationale:** Early iterations included aggressive structural resets (like `overflow: hidden`, `box-sizing: border-box`, `margin: 0`) cargo-culted from the Dropdown component. These caused sub-menus to render clipped inside the parent dropdown with scrollbars. The lesson: default to Mantine's native behavior and only override what the Recursica token system explicitly needs to control.