@recursica/adapter-mantine-v8 1.0.0

package/src/components/Card/Card.stories.tsx

@@ -0,0 +1,131 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Card } from "./Card";
+import { Layer } from "@recursica/adapter-common";
+import { Button } from "../Button/Button";
+import { Group } from "../Group/Group";
+import { Text } from "../Text/Text";
+
+const meta: Meta<typeof Card> = {
+  title: "UI-Kit/Card",
+  component: Card,
+  subcomponents: {
+    "Card.Header": Card.Header,
+    "Card.Content": Card.Content,
+    "Card.Footer": Card.Footer,
+    "Card.Section": Card.Section,
+  } as Record<string, React.ComponentType<unknown>>,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The Card component acts as the foundational padded surface for grouping related information. It relies on standard internal compositional nodes (`Card.Header`, `Card.Content`, `Card.Footer`) mapped directly to the active Recursica design tokens to enforce layout gaps and margins seamlessly. Use the provided dot-notation wrappers rather than building ad-hoc generic sections.",
+      },
+    },
+  },
+  argTypes: {},
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Card>;
+
+export const Default: Story = {
+  args: {},
+  render: ({ ...args }) => {
+    return (
+      <div
+        style={{
+          padding: "48px",
+          backgroundColor: "#e9ecef",
+        }}
+      >
+        <Layer layer={0}>
+          <Card {...args}>
+            <Card.Header>Customer Activity Report</Card.Header>
+            <Card.Content>
+              <Text>
+                Card inner section content body. Notice how this acts as padded
+                content natively based on the overarching properties.
+                Recursica's vertical gutter governs vertical spacing between
+                siblings in the flex container.
+              </Text>
+              <Text>Another section showing the vertical gutter spacing.</Text>
+            </Card.Content>
+            <Card.Footer>
+              <Group justify="space-between" align="center">
+                <Text variant="caption">Generated today</Text>
+                <Button variant="solid">View Details</Button>
+              </Group>
+            </Card.Footer>
+          </Card>
+        </Layer>
+      </div>
+    );
+  },
+};
+
+export const HeaderlessAndFooterless: Story = {
+  args: {},
+  render: ({ ...args }) => {
+    return (
+      <div
+        style={{
+          padding: "48px",
+          backgroundColor: "#e9ecef",
+        }}
+      >
+        <Layer layer={0}>
+          <Card {...args}>
+            <Card.Content>
+              <Text variant="subtitle">Notice</Text>
+              <Text>
+                This is a completely generic card payload dropping the Header
+                and Footer specific elements, simply acting as a padded
+                elevation boundary box directly mirroring native composability!
+              </Text>
+              <Button variant="solid">Acknowledge</Button>
+            </Card.Content>
+          </Card>
+        </Layer>
+      </div>
+    );
+  },
+};
+
+export const LayerDemonstration: Story = {
+  args: {},
+  render: ({ ...args }) => {
+    return (
+      <div
+        style={{
+          display: "flex",
+          gap: "32px",
+          backgroundColor: "#e9ecef",
+          padding: "32px",
+        }}
+      >
+        <Layer layer={1}>
+          <Card {...args}>
+            <Card.Header>Layer 1 Wrapper</Card.Header>
+            <Card.Content>
+              <Text>Content inside layer 1 card.</Text>
+            </Card.Content>
+          </Card>
+        </Layer>
+
+        <Layer layer={2}>
+          <Card {...args}>
+            <Card.Header>Layer 2 Wrapper</Card.Header>
+            <Card.Content>
+              <Text>
+                Content inside layer 2 card exposing a higher elevation drop
+                shadow inherently cascaded.
+              </Text>
+            </Card.Content>
+          </Card>
+        </Layer>
+      </div>
+    );
+  },
+};

package/src/components/Card/Card.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Card component tests. Add tests here if/when needed.

package/src/components/Card/Card.tsx

@@ -0,0 +1,248 @@
+import { forwardRef } from "react";
+import {
+  Card as MantineCard,
+  type CardProps as MantineCardProps,
+  type CardSectionProps as MantineCardSectionProps,
+  createPolymorphicComponent,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  omitUnsupportedProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Card.module.css";
+
+import {
+  type RecursicaCardProps,
+  type RecursicaCardSectionProps,
+} from "@recursica/adapter-common";
+
+// ==== CARD CONTAINER ====
+export type CardProps = RecursicaOverStyled<
+  MantineCardProps & RecursicaCardProps
+> & {
+  flex?: string | number;
+  flexGrow?: string | number;
+  flexShrink?: string | number;
+  flexBasis?: string | number;
+  grow?: string | number;
+  h?: string | number;
+  height?: string | number;
+};
+
+/**
+ * The root Card elevation box. It establishes the global background color, border radius, nested component gap, and outer shadow governed by the current `Layer` context.
+ */
+// Props this component intentionally doesn't support — deleted at runtime so they can't leak
+// through even if a caller forces them via plain JavaScript. `Card.module.css` unconditionally
+// drives these from Recursica UI Kit tokens on `.root`; the native prop is never consulted.
+const UNSUPPORTED_PROPS = [
+  "radius", // Border radius is token-driven (`--recursica_..._borders_border-radius`), not caller-set.
+  "withBorder", // Border is always applied via tokens on `.root`; not an optional caller toggle.
+  "padding", // Padding is token-driven (`--card-padding`), not Mantine's spacing-scale prop.
+] as const satisfies readonly (keyof MantineCardProps)[];
+
+const CardBase = forwardRef<HTMLDivElement, CardProps>(function Card(
+  { overStyled = false, ...rest },
+  ref,
+) {
+  const sanitizedProps = omitUnsupportedProps(
+    filterStylingProps(rest, overStyled),
+    UNSUPPORTED_PROPS,
+  );
+
+  // Expose outer layout/flexbox properties on Card to allow structuring alongside siblings
+  const safeCardLayoutKeys = [
+    "flex",
+    "flexGrow",
+    "flexShrink",
+    "flexBasis",
+    "grow",
+    "h",
+    "height",
+  ] as const;
+  safeCardLayoutKeys.forEach((key) => {
+    if (key in rest && !(key in sanitizedProps)) {
+      (sanitizedProps as Record<string, unknown>)[key] = (
+        rest as Record<string, unknown>
+      )[key];
+    }
+  });
+
+  const mergedClassNames = mergeClassNames(
+    {
+      root: styles.root,
+    },
+    (sanitizedProps as Record<string, unknown>).classNames as
+      | Partial<Record<string, string>>
+      | undefined,
+  );
+
+  const classNameProp = (sanitizedProps as Record<string, unknown>)
+    .className as string | undefined;
+
+  return (
+    <MantineCard
+      ref={ref}
+      {...(sanitizedProps as unknown as MantineCardProps)}
+      className={classNameProp}
+      classNames={mergedClassNames}
+    />
+  );
+});
+CardBase.displayName = "Card";
+
+export type CardSectionProps = RecursicaOverStyled<
+  MantineCardSectionProps & RecursicaCardSectionProps
+>;
+
+/**
+ * A generalized edge-to-edge structural wrapper native to Mantine. Strips typical boundary padding via negative margins to allow content (like maps or header images) to touch the border seamlessly.
+ */
+export const CardSection = forwardRef<HTMLDivElement, CardSectionProps>(
+  function CardSection({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const classNameProp = (sanitizedProps as Record<string, unknown>)
+      .className as string | undefined;
+
+    return (
+      <MantineCard.Section
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineCardSectionProps)}
+        className={
+          classNameProp ? `${styles.section} ${classNameProp}` : styles.section
+        }
+      />
+    );
+  },
+);
+CardSection.displayName = "CardSection";
+
+// ==== EXPLICIT CARD.HEADER ====
+export type CardHeaderProps = RecursicaOverStyled<RecursicaCardSectionProps>;
+
+/**
+ * Replaces standard generic Mantine `<Card.Section>` wrappers by directly injecting the strict Recursica design tokens for header sizing, background drops, and intrinsic padding limits.
+ */
+// Props this component intentionally doesn't support — deleted at runtime so they can't leak
+// through even if a caller forces them via plain JavaScript. `CardHeaderProps` already omits all
+// native Mantine section props from the public type, but that alone doesn't stop a forced-typed
+// caller from smuggling one through `...rest`; `.header` in Card.module.css unconditionally
+// drives background/padding/border from Recursica tokens, so these native toggles are meaningless.
+const HEADER_FOOTER_UNSUPPORTED_PROPS = [
+  "withBorder", // The divider border is always applied via tokens on `.header`/`.footer`.
+  "inheritPadding", // Padding is fixed by the `.header`/`.footer` token-driven padding, not Mantine's default.
+] as const satisfies readonly (keyof MantineCardSectionProps)[];
+
+export const CardHeader = forwardRef<HTMLDivElement, CardHeaderProps>(
+  function CardHeader({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled),
+      HEADER_FOOTER_UNSUPPORTED_PROPS,
+    );
+    const classNameProp = (sanitizedProps as Record<string, unknown>)
+      .className as string | undefined;
+
+    return (
+      <MantineCard.Section
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineCardSectionProps)}
+        className={
+          classNameProp ? `${styles.header} ${classNameProp}` : styles.header
+        }
+      />
+    );
+  },
+);
+CardHeader.displayName = "CardHeader";
+
+// ==== EXPLICIT CARD.FOOTER ====
+export type CardFooterProps = RecursicaOverStyled<RecursicaCardSectionProps>;
+
+/**
+ * Counterpart to `Card.Header`, applying specific footer elevation margins, sizes, and padding natively.
+ */
+export const CardFooter = forwardRef<HTMLDivElement, CardFooterProps>(
+  function CardFooter({ overStyled = false, ...rest }, ref) {
+    // Reuses HEADER_FOOTER_UNSUPPORTED_PROPS (declared above with CardHeader) — same rationale
+    // applies: `.footer` in Card.module.css unconditionally drives padding/border from tokens.
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled),
+      HEADER_FOOTER_UNSUPPORTED_PROPS,
+    );
+    const classNameProp = (sanitizedProps as Record<string, unknown>)
+      .className as string | undefined;
+
+    return (
+      <MantineCard.Section
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineCardSectionProps)}
+        className={
+          classNameProp ? `${styles.footer} ${classNameProp}` : styles.footer
+        }
+      />
+    );
+  },
+);
+CardFooter.displayName = "CardFooter";
+
+// ==== EXPLICIT CARD.CONTENT ====
+export type CardContentProps = RecursicaOverStyled<
+  React.HTMLAttributes<HTMLDivElement>
+>;
+
+/**
+ * Internal container that safely binds typography and structural flex gaps driven by the active UI kit tokens natively, preserving correct padding blocks compared to rigid `Card.Section` edges.
+ */
+export const CardContent = forwardRef<HTMLDivElement, CardContentProps>(
+  function CardContent({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const classNameProp = (sanitizedProps as Record<string, unknown>)
+      .className as string | undefined;
+
+    return (
+      <div
+        ref={ref}
+        {...sanitizedProps}
+        className={
+          classNameProp ? `${styles.content} ${classNameProp}` : styles.content
+        }
+      />
+    );
+  },
+);
+CardContent.displayName = "CardContent";
+
+// ==== DOT NOTATION EXPORT ====
+
+/**
+ * Recursica Card component wrapping Mantine's Card (Paper).
+ *
+ * Supports polymorphism via the `component` prop or `renderRoot` for custom element rendering.
+ * Use dot-notation sub-components for structured card layouts.
+ */
+const PolymorphicCard = createPolymorphicComponent<
+  "div",
+  CardProps,
+  {
+    Section: typeof CardSection;
+    Header: typeof CardHeader;
+    Footer: typeof CardFooter;
+    Content: typeof CardContent;
+  }
+>(CardBase);
+
+// Attach static components for dot-notation access
+const _card = PolymorphicCard as unknown as Record<string, unknown>;
+_card.Section = CardSection;
+_card.Header = CardHeader;
+_card.Footer = CardFooter;
+_card.Content = CardContent;
+
+export const Card = PolymorphicCard as typeof PolymorphicCard & {
+  Section: typeof CardSection;
+  Header: typeof CardHeader;
+  Footer: typeof CardFooter;
+  Content: typeof CardContent;
+};

package/src/components/Card/USAGE.md

@@ -0,0 +1,63 @@
+# Card - Usage Guide
+
+This document describes how to integrate and use the `Card` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Card } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Card } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return (
+    <Card>
+      <Card.Header>
+        <Heading order={3}>Card Title</Heading>
+      </Card.Header>
+      <Card.Content>
+        <Text>
+          This is some card content styled natively via design tokens.
+        </Text>
+      </Card.Content>
+      <Card.Footer>
+        <Button variant="secondary">Cancel</Button>
+        <Button variant="primary">Submit</Button>
+      </Card.Footer>
+    </Card>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mantine-v8` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+## Header & Footer Styling
+
+`Card.Header` and `Card.Footer` automatically receive their background color and padding from the design system; no manual styling is needed.
+
+## Layout Alignment
+
+`Card` accepts a safe subset of flexbox/sizing props (`flex`, `flexGrow`, `flexShrink`, `flexBasis`, `grow`, `h`, `height`) so it can participate cleanly in flex or grid layouts (dashboard panels, grid tracks, sidebar segments, etc.). `Card.Content` grows to fill available vertical space, which keeps `Card.Footer` pinned to the bottom of the card.

package/src/components/Checkbox/CHECKBOX_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,25 @@
+# Checkbox Implementation Notes
+
+## Architectural Philosophy
+
+The `Checkbox` primitive requires aggressive structural modifications to decouple Mantine's built-in arrays (`<Checkbox.Group>`) tying the raw DOM nodes seamlessly back into Recursica's unified form definitions flawlessly.
+
+### Checkbox Alignment Anchoring (gap overflow hack)
+
+By default, placing a Checkbox alongside a deeply wrapping multi-line label causes native geometric drifts natively. Because Mantine aligns the Checkbox graphic to the top of standard `display: flex` boxes, its optical center will appear natively skewed slightly _too high_ against the very first typographic text-line.
+
+We mathematically fix this alignment within `Checkbox.module.css` using explicit design variable arithmetic natively.
+\`\`\`css
+margin-top: calc(
+(
+var(--recursica_ui-kit_components_checkbox-item_properties_text_line-height) \*
+var(--recursica_ui-kit_components_checkbox-item_properties_text_font-size) -
+var(--recursica_ui-kit_components_checkbox_properties_size)
+) / 2
+) !important;
+\`\`\`
+This calculation ensures that the optical center of the `.inner` checkmark vector perfectly snaps onto the relative center of the text's line-height, permanently solving pixel-drifts natively!
+
+### Checkbox.Group Overrides
+
+To decouple `<CheckboxGroup>` away from `<Input.Wrapper>`, we explicitly extract the raw array execution mapped correctly against our identical `RecursicaFormControlWrapperProps` schema structurally!