@recursica/mantine-adapter 0.18.0 → 0.20.0

package/src/OverStyling.tsx

@@ -1,186 +1,231 @@
-import {
-  Container,
-  Paper,
-  Title,
-  Text,
-  List,
-  Divider,
-  Group,
-  Code,
-} from "@mantine/core";
+import { Container, Card, Title, Text, Group, Stack } from "./components";
 import { Button } from "./components/Button/Button";
 
 export const OverStylingInfo = () => {
   return (
-    <Container size="md" py="xl">
-      <Paper withBorder p="xl" radius="md">
-        <Title order={1} mb="md">
-          Over Styling (<Code>overStyled</Code>)
-        </Title>
-        <Text mb="md">
-          By default, all Recursica components are strictly sandboxed. This
-          means they are protected against arbitrary styling configurations
-          (like passing generic React <Code>style</Code> objects, custom{" "}
-          <Code>classNames</Code> injections, or using deep Mantine layout hooks
-          like <Code>bg</Code> and <Code>c</Code>). This strict compile-time and
-          run-time enforcement guarantees that your design system tokens remain
-          true across your application.
-        </Text>
-        <Text mb="md">
-          However, there may be edge cases where a developer absolutely must
-          modify a component beyond what the design tokens natively allow. For
-          this, we provide the <strong>escape hatch</strong> property:{" "}
-          <Code>overStyled={`{true}`}</Code>.
-        </Text>
+    <Container size="md" style={{ padding: "32px 0" }}>
+      <Card>
+        <Card.Content>
+          <Title order={1} mb="rec-md">
+            Over Styling (<code>overStyled</code>)
+          </Title>
+          <Text mb="rec-md">
+            By default, all Recursica components are strictly sandboxed. This
+            means they are protected against arbitrary styling configurations
+            (like passing generic React <code>style</code> objects, custom{" "}
+            <code>classNames</code> injections, or using deep Mantine layout
+            hooks like <code>bg</code> and <code>c</code>). This strict
+            compile-time and run-time enforcement guarantees that your design
+            system tokens remain true across your application.
+          </Text>
+          <Text mb="rec-md">
+            However, there may be edge cases where a developer absolutely must
+            modify a component beyond what the design tokens natively allow. For
+            this, we provide the <strong>escape hatch</strong> property:{" "}
+            <code>overStyled={`{true}`}</code>.
+          </Text>
 
-        <Title order={3} mb="sm">
-          The Core Philosophy
-        </Title>
-        <Text mb="sm">
-          **You should not over-style components.** Using{" "}
-          <Code>overStyled</Code> explicitly signifies that you are breaking
-          design system rules.
-        </Text>
-        <List mb="xl" type="ordered">
-          <List.Item>
-            <strong>Technical Debt:</strong> If over-styling is required, it
-            should be treated as a short-term workaround. Ideally, the component
-            will be refactored once the required layouts or variants are
-            officially integrated into the core Recursica component library.
-          </List.Item>
-          <List.Item>
-            <strong>Auditing & Searching:</strong> Because this pattern creates
-            technical debt, we enforce the explicit <Code>overStyled</Code>{" "}
-            boolean. This provides a highly auditable, easily searchable string.
-            Product managers and engineers can quickly grep the codebase for{" "}
-            <Code>overStyled</Code> (or the <Code>RecursicaOverStyled</Code>{" "}
-            typings) to hunt down components that don't match standard patterns.
-          </List.Item>
-          <List.Item>
-            <strong>Highly Custom Components:</strong> If your application
-            genuinely requires massive custom layouts that the UI kit cannot
-            support, <strong>do not hack the Recursica component</strong>.
-            Instead, it is highly encouraged that you import the underlying
-            primitive component directly from <Code>@mantine/core</Code> and
-            construct your independent feature there. While you can utilize raw
-            Recursica CSS variables on these custom components, note that they
-            are not guaranteed to be accurately maintained as Recursica evolves.
-            Keep strict components strict!
-          </List.Item>
-        </List>
+          <Title order={3} mb="rec-sm">
+            The Core Philosophy
+          </Title>
+          <Text mb="rec-sm">
+            **You should not over-style components.** Using{" "}
+            <code>overStyled</code> explicitly signifies that you are breaking
+            design system rules.
+          </Text>
+          <Stack
+            component="ol"
+            style={{ paddingLeft: "24px" }}
+            mb="rec-xl"
+            gap="rec-sm"
+          >
+            <li>
+              <Text>
+                <strong>Technical Debt:</strong> If over-styling is required, it
+                should be treated as a short-term workaround. Ideally, the
+                component will be refactored once the required layouts or
+                variants are officially integrated into the core Recursica
+                component library.
+              </Text>
+            </li>
+            <li>
+              <Text>
+                <strong>Auditing & Searching:</strong> Because this pattern
+                creates technical debt, we enforce the explicit{" "}
+                <code>overStyled</code> boolean. This provides a highly
+                auditable, easily searchable string. Product managers and
+                engineers can quickly grep the codebase for{" "}
+                <code>overStyled</code> (or the <code>RecursicaOverStyled</code>{" "}
+                typings) to hunt down components that don't match standard
+                patterns.
+              </Text>
+            </li>
+            <li>
+              <Text>
+                <strong>Highly Custom Components:</strong> If your application
+                genuinely requires massive custom layouts that the UI kit cannot
+                support, <strong>do not hack the Recursica component</strong>.
+                Instead, it is highly encouraged that you import the underlying
+                primitive component directly from <code>@mantine/core</code> and
+                construct your independent feature there. While you can utilize
+                raw Recursica CSS variables on these custom components, note
+                that they are not guaranteed to be accurately maintained as
+                Recursica evolves. Keep strict components strict!
+              </Text>
+            </li>
+          </Stack>
 
-        <Divider mb="xl" />
+          <Stack
+            style={{ height: 1, backgroundColor: "#eaeaea" }}
+            mb="rec-xl"
+          />
 
-        <Title order={3} mb="sm">
-          Permitted Layout Properties
-        </Title>
-        <Text mb="sm">
-          Unlike deep styling bounds (colors, typography, padding, dimensions),
-          external <strong>layout spacing properties</strong> like Margins (
-          <Code>m</Code>, <Code>mt</Code>, <Code>mb</Code>, <Code>mx</Code>) are
-          safely <strong>permitted by default</strong>. This allows integrators
-          to structurally compose components alongside siblings without
-          breaching internal token boundaries.
-        </Text>
-        <Text mb="xl">
-          When using layout properties, you have the flexibility to use either
-          ecosystem seamlessly:
-        </Text>
-        <List mb="md" type="ordered">
-          <List.Item>
-            <strong>Mantine Core Values:</strong> Passing standard Mantine sizes
-            (like <Code>mt="md"</Code>) passes straight through to Mantine
-            natively, allowing you to interface completely normally with a
-            parent application's existing Mantine Theme setup that might fall
-            outside Recursica's scope.
-          </List.Item>
-          <List.Item>
-            <strong>Recursica Strict Tokens:</strong> Passing our custom
-            prefixed tokens (like <Code>mt="rec-md"</Code>) signals our internal
-            layout interceptor to securely translate the value directly to our
-            native <Code>recursica_brand_dimensions</Code> CSS variables. This
-            ensures strict design token measurements while sharing the exact
-            same prop interface!
-          </List.Item>
-        </List>
-        <Text mb="sm" fw={500}>
-          Available Recursica Layout Tokens:
-        </Text>
-        <List mb="xl" type="unordered">
-          <List.Item>
-            <Code>rec-none</Code> (0px limit)
-          </List.Item>
-          <List.Item>
-            <Code>rec-sm</Code> (0.5x scaling)
-          </List.Item>
-          <List.Item>
-            <Code>rec-default</Code> (1.0x scaling)
-          </List.Item>
-          <List.Item>
-            <Code>rec-md</Code> (1.5x scaling)
-          </List.Item>
-          <List.Item>
-            <Code>rec-lg</Code> (2.0x scaling)
-          </List.Item>
-          <List.Item>
-            <Code>rec-xl</Code> (3.0x scaling)
-          </List.Item>
-          <List.Item>
-            <Code>rec-2xl</Code> (4.0x scaling)
-          </List.Item>
-        </List>
+          <Title order={3} mb="rec-sm">
+            Permitted Layout Properties
+          </Title>
+          <Text mb="rec-sm">
+            Unlike deep styling bounds (colors, typography, padding,
+            dimensions), external <strong>layout spacing properties</strong>{" "}
+            like Margins (<code>m</code>, <code>mt</code>, <code>mb</code>,{" "}
+            <code>mx</code>) are safely <strong>permitted by default</strong>.
+            This allows integrators to structurally compose components alongside
+            siblings without breaching internal token boundaries.
+          </Text>
+          <Text mb="rec-xl">
+            When using layout properties, you have the flexibility to use either
+            ecosystem seamlessly:
+          </Text>
+          <Stack
+            component="ol"
+            style={{ paddingLeft: "24px" }}
+            mb="rec-md"
+            gap="rec-sm"
+          >
+            <li>
+              <Text>
+                <strong>Mantine Core Values:</strong> Passing standard Mantine
+                sizes (like <code>mt="md"</code>) passes straight through to
+                Mantine natively, allowing you to interface completely normally
+                with a parent application's existing Mantine Theme setup that
+                might fall outside Recursica's scope.
+              </Text>
+            </li>
+            <li>
+              <Text>
+                <strong>Recursica Strict Tokens:</strong> Passing our custom
+                prefixed tokens (like <code>mt="rec-md"</code>) signals our
+                internal layout interceptor to securely translate the value
+                directly to our native <code>recursica_brand_dimensions</code>{" "}
+                CSS variables. This ensures strict design token measurements
+                while sharing the exact same prop interface!
+              </Text>
+            </li>
+          </Stack>
+          <Text mb="rec-sm" overStyled fw={500}>
+            Available Recursica Layout Tokens:
+          </Text>
+          <Stack
+            component="ul"
+            style={{ paddingLeft: "24px" }}
+            mb="rec-xl"
+            gap="rec-none"
+          >
+            <li>
+              <Text>
+                <code>rec-none</code> (0px limit)
+              </Text>
+            </li>
+            <li>
+              <Text>
+                <code>rec-sm</code> (0.5x scaling)
+              </Text>
+            </li>
+            <li>
+              <Text>
+                <code>rec-default</code> (1.0x scaling)
+              </Text>
+            </li>
+            <li>
+              <Text>
+                <code>rec-md</code> (1.5x scaling)
+              </Text>
+            </li>
+            <li>
+              <Text>
+                <code>rec-lg</code> (2.0x scaling)
+              </Text>
+            </li>
+            <li>
+              <Text>
+                <code>rec-xl</code> (3.0x scaling)
+              </Text>
+            </li>
+            <li>
+              <Text>
+                <code>rec-2xl</code> (4.0x scaling)
+              </Text>
+            </li>
+          </Stack>
 
-        <Divider mb="xl" />
+          <Stack
+            style={{ height: 1, backgroundColor: "#eaeaea" }}
+            mb="rec-xl"
+          />
 
-        <Title order={3} mb="sm">
-          Primitive Layout Components Exemption
-        </Title>
-        <Text mb="sm">
-          Unlike complex UI components (Buttons, Tabs, Inputs) which are
-          strictly protected, <strong>Primitive Layout Components</strong> (
-          <Code>Flex</Code>,<Code>Stack</Code>, <Code>Group</Code>,{" "}
-          <Code>Container</Code>) are entirely exempt from the{" "}
-          <Code>RecursicaOverStyled</Code> gatekeeper.
-        </Text>
-        <Text mb="xl">
-          Because the entire functional purpose of these components is
-          structural layout composition, developers are free to pass any
-          standard Mantine width, height, padding, margin, gap, and alignment
-          property directly to them without needing to flag{" "}
-          <Code>overStyled={`{true}`}</Code>. The internal custom token mapper
-          (such as converting <Code>gap="rec-md"</Code>) is still active
-          natively on these wrappers.
-        </Text>
+          <Title order={3} mb="rec-sm">
+            Primitive Layout Components Exemption
+          </Title>
+          <Text mb="rec-sm">
+            Unlike complex UI components (Buttons, Tabs, Inputs) which are
+            strictly protected, <strong>Primitive Layout Components</strong> (
+            <code>Flex</code>, <code>Stack</code>, <code>Group</code>,{" "}
+            <code>Container</code>) are entirely exempt from the{" "}
+            <code>RecursicaOverStyled</code> gatekeeper.
+          </Text>
+          <Text mb="rec-xl">
+            Because the entire functional purpose of these components is
+            structural layout composition, developers are free to pass any
+            standard Mantine width, height, padding, margin, gap, and alignment
+            property directly to them without needing to flag{" "}
+            <code>overStyled={`{true}`}</code>. The internal custom token mapper
+            (such as converting <code>gap="rec-md"</code>) is still active
+            natively on these wrappers.
+          </Text>
 
-        <Divider mb="xl" />
+          <Stack
+            style={{ height: 1, backgroundColor: "#eaeaea" }}
+            mb="rec-xl"
+          />
 
-        <Title order={3} mb="md">
-          Live Example
-        </Title>
-        <Text mb="xl">
-          Below is a side-by-side comparison. The first is a standard Recursica
-          Button protected by the design tokens mapping. The second flagrantly
-          forces <Code>overStyled={`{true}`}</Code>, allowing Mantine's native
-          styling generics to punch right through the sandbox layout.
-        </Text>
+          <Title order={3} mb="rec-md">
+            Live Example
+          </Title>
+          <Text mb="rec-xl">
+            Below is a side-by-side comparison. The first is a standard
+            Recursica Button protected by the design tokens mapping. The second
+            flagrantly forces <code>overStyled={`{true}`}</code>, allowing
+            Mantine's native styling generics to punch right through the sandbox
+            layout.
+          </Text>
 
-        <Group gap="xl">
-          <div>
-            <Text size="sm" c="dimmed" mb="xs">
-              Strict Baseline (Default)
-            </Text>
-            <Button variant="solid">Standard UI Kit Button</Button>
-          </div>
-          <div>
-            <Text size="sm" c="dimmed" mb="xs">
-              overStyled={`{true}`}
-            </Text>
-            <Button overStyled={true} bg="pink" c="black" radius="xl">
-              Unsafe Pink Marketing Button
-            </Button>
-          </div>
-        </Group>
-      </Paper>
+          <Group gap="rec-xl">
+            <Stack gap="rec-sm">
+              <Text overStyled size="sm" c="dimmed">
+                Strict Baseline (Default)
+              </Text>
+              <Button variant="solid">Standard UI Kit Button</Button>
+            </Stack>
+            <Stack gap="rec-sm">
+              <Text overStyled size="sm" c="dimmed">
+                overStyled={`{true}`}
+              </Text>
+              <Button overStyled={true} bg="pink" c="black" radius="xl">
+                Unsafe Pink Marketing Button
+              </Button>
+            </Stack>
+          </Group>
+        </Card.Content>
+      </Card>
     </Container>
   );
 };

package/src/components/Button/Button.module.css

@@ -6,6 +6,7 @@
   overflow: hidden; /* Truncation bounding box */
   position: relative;
   transition: all 0.2s ease;
+  width: fit-content; /* Prevent stretching in flex columns */
 
   /* Shared Defaults */
   font-family: var(
@@ -37,7 +38,6 @@
 /* Internal Mantine reset & layout logic for Truncation */
 .root > * {
   min-width: 0;
-  width: 100%;
   position: relative;
   z-index: 1;
 }
@@ -52,7 +52,6 @@
 .labelText {
   display: block;
   min-width: 0;
-  width: 100%;
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
@@ -76,6 +75,11 @@
       --recursica_ui-kit_components_button_variants_sizes_default_properties_horizontal-padding
     );
 }
+.root[data-size="default"] .labelText {
+  max-width: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_max-label-width
+  );
+}
 .root[data-size="small"] {
   border-radius: var(
     --recursica_ui-kit_components_button_variants_sizes_small_properties_border-radius
@@ -111,6 +115,11 @@
     )
   );
 }
+.root[data-size="small"] .labelText {
+  max-width: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_max-label-width
+  );
+}
 
 /* Icon Resets */
 .iconWrapper {
@@ -167,8 +176,16 @@
 }
 
 /* Disabled */
-.root:disabled {
-  opacity: var(--recursica_brand_states_disabled);
+.root[data-size="default"]:disabled {
+  opacity: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_disabled-opacity
+  );
+  cursor: not-allowed;
+}
+.root[data-size="small"]:disabled {
+  opacity: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_disabled-opacity
+  );
   cursor: not-allowed;
 }
 

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

@@ -112,3 +112,17 @@ export const PolymorphicAsLink: Story = {
     target: "_blank",
   },
 };
+
+export const TruncatedLabel: Story = {
+  args: {
+    children:
+      "This is an exceptionally long button label designed to demonstrate how the component handles text overflow by applying an ellipsis rather than breaking the layout or wrapping to multiple lines.",
+    variant: "solid",
+    size: "default",
+  },
+  render: (args: ButtonStoryProps) => (
+    <div style={{ maxWidth: "250px" }}>
+      <Button {...args} />
+    </div>
+  ),
+};

package/src/components/Flex/Flex.tsx

@@ -4,7 +4,10 @@ import {
   type FlexProps as MantineFlexProps,
   createPolymorphicComponent,
 } from "@mantine/core";
-import { type RecursicaSpacing } from "../../utils/filterStylingProps";
+import {
+  type RecursicaSpacing,
+  mapLayoutProps,
+} from "../../utils/filterStylingProps";
 import styles from "./Flex.module.css";
 
 export interface RecursicaFlexProps {
@@ -27,7 +30,7 @@ export interface RecursicaFlexProps {
 export type FlexProps = MantineFlexProps & RecursicaFlexProps;
 
 const _Flex = forwardRef<HTMLDivElement, FlexProps>(function Flex(
-  { children, gap = "rec-default", ...rest },
+  { children, gap = "rec-default", rowGap, columnGap, ...rest },
   ref,
 ) {
   const mergedClassNames: Partial<Record<string, string>> = {
@@ -54,8 +57,10 @@ const _Flex = forwardRef<HTMLDivElement, FlexProps>(function Flex(
       ref={ref}
       className={finalClass}
       classNames={mergedClassNames}
-      gap={gap}
-      {...rest}
+      {...mapLayoutProps({ gap, rowGap, columnGap, ...rest } as Record<
+        string,
+        unknown
+      >)}
     >
       {children}
     </MantineFlex>

package/src/components/Group/Group.tsx

@@ -3,7 +3,10 @@ import {
   Group as MantineGroup,
   type GroupProps as MantineGroupProps,
 } from "@mantine/core";
-import { type RecursicaSpacing } from "../../utils/filterStylingProps";
+import {
+  type RecursicaSpacing,
+  mapLayoutProps,
+} from "../../utils/filterStylingProps";
 import styles from "./Group.module.css";
 
 export interface RecursicaGroupProps {
@@ -53,8 +56,7 @@ export const Group = forwardRef<HTMLDivElement, GroupProps>(function Group(
       ref={ref}
       className={finalClass}
       classNames={mergedClassNames}
-      gap={gap}
-      {...rest}
+      {...mapLayoutProps({ gap, ...rest } as Record<string, unknown>)}
     >
       {children}
     </MantineGroup>

package/src/components/Modal/MODAL_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,15 @@
+# Modal Implementation Notes
+
+## Architecture
+
+The `Modal` component strictly wraps Mantine's `<Modal>` primitive. We strip Mantine's abstract native styling props (`size`, `radius`, `shadow`) via the `overStyled` interface and strictly inject CSS variable definitions onto the internal node abstractions (`.content`, `.header`, `.body`, `.title`).
+
+## Limitations & Structural Decisions
+
+### 1. Stripped `size` Prop
+
+Mantine natively exposes an abstract `size` prop (`"sm" | "md" | "lg" | "xl"`) that scales the Modal geometry. The Recursica UI Kit explicitly dictates strict geometric bounding boxes: `max-width: 960px` and `min-width: 304px`. To enforce absolute parity with the design system, the `size` prop has been intentionally omitted from the component's interface. The width of the Modal will scale fluidly strictly between these Figma-driven pixel limits.
+
+### 2. Scroll Dividers behavior
+
+Mantine internally handles scroll state natively, dynamically showing/hiding a divider line when content overflows in `.body`. This logic is tightly coupled to React DOM measurements internally. Our component inherits this dynamic behavior rather than statically rendering a permanent divider, matching Mantine's robust overflow UX. However, we aggressively override the generated `border-bottom` via CSS modules to ensure that when it _does_ appear, it correctly utilizes the `--recursica_ui-kit_components_modal_colors_scroll-divider` variable and `--recursica_ui-kit_components_modal_properties_scroll-divider-thickness` token.