@recursica/mantine-adapter 0.6.0 → 0.7.0

package/src/components/Button/Button.tsx

@@ -0,0 +1,122 @@
+import React, { forwardRef } from "react";
+import {
+  Button as MantineButton,
+  type ButtonProps as MantineButtonProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Button.module.css";
+
+export interface RecursicaButtonProps {
+  variant?: "solid" | "outline" | "text";
+  size?: "default" | "small";
+  icon?: React.ReactNode;
+}
+
+export type ButtonProps = RecursicaOverStyled<
+  Omit<MantineButtonProps, "variant" | "size" | "leftSection" | "fullWidth"> &
+    RecursicaButtonProps
+>;
+
+function hasVisibleChildren(children: React.ReactNode): boolean {
+  if (children == null || children === "") return false;
+  if (typeof children === "string") return children.trim() !== "";
+  return true;
+}
+
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+  function Button(
+    {
+      variant = "solid",
+      size = "default",
+      icon,
+      children,
+      overStyled = false,
+      ...rest
+    },
+    ref,
+  ) {
+    const mapVariant = {
+      solid: "filled",
+      outline: "outline",
+      text: "subtle",
+    } as const;
+
+    const mapSize = {
+      default: "md",
+      small: "sm",
+    } as const;
+
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    // Explicitly delete blocked semantic expansion dimension props
+    delete restRecord["fullWidth"];
+
+    const hasLeftSection = !!icon || !!restRecord["leftSection"];
+    const hasRightSection = !!restRecord["rightSection"];
+    const isIconOnly =
+      (hasLeftSection || hasRightSection) && !hasVisibleChildren(children);
+
+    if (
+      typeof process !== "undefined" &&
+      process.env.NODE_ENV !== "production" &&
+      isIconOnly &&
+      !restRecord["aria-label"]
+    ) {
+      console.warn(
+        '[Recursica Button] Icon-only buttons must provide an accessible name. Pass aria-label (e.g. aria-label="Submit").',
+      );
+    }
+
+    const mergedClassNames: Partial<Record<string, string>> = {
+      root: styles.root,
+      section: styles.section,
+      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.section = o.section ?? styles.section;
+      mergedClassNames.label = o.label ?? styles.label;
+    }
+
+    const classNameProp = restRecord.className as string | undefined;
+    const finalClass = classNameProp
+      ? `${styles.root} ${classNameProp}`
+      : styles.root;
+
+    return (
+      <MantineButton
+        ref={ref}
+        className={finalClass}
+        classNames={mergedClassNames}
+        variant={mapVariant[variant]}
+        size={mapSize[size]}
+        leftSection={
+          icon != null ? (
+            <span className={styles.iconWrapper} aria-hidden>
+              {icon}
+            </span>
+          ) : undefined
+        }
+        data-variant={variant}
+        data-size={size}
+        {...(isIconOnly ? { "data-icon-only": "" } : {})}
+        {...sanitizedProps}
+      >
+        <span className={styles.labelText}>{children}</span>
+      </MantineButton>
+    );
+  },
+);
+
+Button.displayName = "Button";

package/src/components/Button/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,45 @@
+# Button – implementation notes
+
+Decisions and design tweaks for the Recursica Button that go beyond the Component Development Guide. Use this when maintaining the Button or when adding similar behavior to other components.
+
+---
+
+## Icon size: Recursica defines it
+
+**Decision:** Icon size is **not** left to the developer. Recursica defines it via the design tokens; the Button enforces it so callers cannot pass an arbitrarily sized icon.
+
+**Implementation:**
+
+- When `icon` is provided, the Button wraps it in a single element with class `iconWrapper` before passing it to Mantine’s `leftSection`.
+- In `Button.module.css`, `.iconWrapper` has explicit `width` and `height` from the Recursica tokens mapping natively based on `data-size`.
+- The rule `.iconWrapper > *` sets `width: 100%`, `height: 100%`, and `object-fit: contain` so whatever the caller passes scales cleanly with the token constraints.
+
+---
+
+## Icon-only buttons: accessibility and width
+
+**Decision:** When the button has an icon and no visible label (icon-only), callers must provide an accessible name, and the button must not show extra space to the right of the icon.
+
+**Accessibility:** We document that icon-only buttons must pass `aria-label` (e.g. `aria-label="Submit"`). In development we log a console warning if `icon` is set, `children` is empty, and `aria-label` is missing.
+
+**Width:** Mantine’s layout natively applies structural section gaps. We detect icon-only and set a `data-icon-only` hook so that `Button.module.css` zeros out the sections spacing allowing the button to precisely hit `min-width` perfectly centered.
+
+---
+
+## Label truncation at max-width
+
+**Decision:** When the button hits its Recursica max-width (500px), the label truncates with an ellipsis instead of wrapping.
+
+**Implementation:**
+Mantine's `.mantine-Button-label` flex centering breaks primitive truncation logic. To combat this:
+
+- **`.root`** has `overflow: hidden`.
+- **`.root > *`** forces `min-width: 0`.
+- The structural children wrap into `<span className={styles.labelText}>`.
+- **`.labelText`** binds `overflow: hidden; text-overflow: ellipsis; white-space: nowrap;` creating flawless string cutoffs strictly at exact UI constraints.
+
+---
+
+## Disabled state: brand theme opacity (implicit)
+
+**Decision:** The UI kit enforces global brand theme disabled opacities. The `.root:disabled` logic implicitly overrides visibility locally via `var(--recursica_brand_states_disabled)`.

package/src/components/Button/index.ts

@@ -0,0 +1 @@
+export * from "./Button";

package/src/components/Card/CARD_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,10 @@
+# Card Implementation Notes
+
+## Architecture Overrides
+
+Because Mantine natively constructs `Card` bounding boxes with generic inner `<Card.Section>` elements that depend on explicit user styling (and lack implicit native designations for "Header" vs "Footer"), we implemented an explicit component wrapper departure:
+
+- `<Card.Header>` explicitly hooks `--recursica_ui-kit_components_card_properties_header-background` and corresponding padding variables.
+- `<Card.Footer>` explicitly hooks `--recursica_ui-kit_components_card_properties_footer-background` and corresponding padding variables.
+
+Mantine's generic `<Card.Section>` calculates negative margins implicitly. Because of this, it is crucial that our local CSS module declares `--card-padding: var(--recursica_ui-kit_components_card_properties_padding)` directly on `.root` so that all generic or explicit section wrappers natively stretch across the bounding box properly.

package/src/components/Card/Card.module.css

@@ -0,0 +1,60 @@
+.root {
+  /* HARDCODE: Map Recursica explicitly into Mantine's variable format so internal components know the margins */
+  --card-padding: var(--recursica_ui-kit_components_card_properties_padding);
+
+  background-color: var(
+    --recursica_ui-kit_components_card_properties_colors_background
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_card_properties_borders_border-radius
+  );
+  border: var(--recursica_ui-kit_components_card_properties_borders_border-size)
+    solid var(--recursica_ui-kit_components_card_properties_colors_border-color);
+  box-shadow: var(
+    --recursica_ui-kit_components_card_properties_elevations_elevation
+  );
+
+  padding: var(--card-padding);
+  min-width: var(--recursica_ui-kit_components_card_properties_min-width);
+  max-width: var(--recursica_ui-kit_components_card_properties_max-width);
+  color: var(--recursica_ui-kit_components_card_properties_colors_content);
+
+  display: flex;
+  flex-direction: column;
+  gap: var(--recursica_ui-kit_components_card_properties_section-gap);
+}
+
+.header {
+  background-color: var(
+    --recursica_ui-kit_components_card_properties_colors_header-background
+  );
+  padding: var(--recursica_ui-kit_components_card_properties_header-padding);
+  color: var(--recursica_ui-kit_components_card_properties_colors_title);
+  border-bottom: var(--recursica_ui-kit_components_card_properties_divider-size)
+    solid
+    var(--recursica_ui-kit_components_card_properties_colors_divider-color);
+}
+
+.footer {
+  background-color: var(
+    --recursica_ui-kit_components_card_properties_colors_footer-background
+  );
+  padding: var(--recursica_ui-kit_components_card_properties_footer-padding);
+  border-top: var(--recursica_ui-kit_components_card_properties_divider-size)
+    solid
+    var(--recursica_ui-kit_components_card_properties_colors_divider-color);
+}
+
+.section {
+  /* Just maps standard section spacing overrides if passed explicitly */
+  margin-top: var(
+    --recursica_ui-kit_components_card_properties_vertical-gutter
+  );
+}
+
+.content {
+  display: flex;
+  flex-direction: column;
+  gap: var(--recursica_ui-kit_components_card_properties_vertical-gutter);
+  padding: 0;
+}

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

@@ -0,0 +1,141 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Card } from "./Card";
+import { Layer } from "@recursica/adapter-common";
+import { Button } from "../Button/Button";
+
+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 (
+      <Layer
+        layer={0}
+        style={{
+          padding: "48px",
+          backgroundColor: "var(--recursica_brand_palettes_neutral_050)",
+        }}
+      >
+        <Card {...args}>
+          <Card.Header>
+            <span style={{ fontWeight: 500, fontSize: "1.125rem" }}>
+              Customer Activity Report
+            </span>
+          </Card.Header>
+          <Card.Content>
+            <p>
+              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.
+            </p>
+            <p>Another section showing the vertical gutter spacing.</p>
+          </Card.Content>
+          <Card.Footer>
+            <div
+              style={{
+                display: "flex",
+                justifyContent: "space-between",
+                alignItems: "center",
+                marginTop: "16px",
+                marginBottom: "8px",
+              }}
+            >
+              <span style={{ color: "#868e96", fontSize: "0.75rem" }}>
+                Generated today
+              </span>
+              <Button variant="solid">View Details</Button>
+            </div>
+          </Card.Footer>
+        </Card>
+      </Layer>
+    );
+  },
+};
+
+export const HeaderlessAndFooterless: Story = {
+  args: {},
+  render: ({ ...args }) => {
+    return (
+      <Layer
+        layer={0}
+        style={{
+          padding: "48px",
+          backgroundColor: "var(--recursica_brand_palettes_neutral_050)",
+        }}
+      >
+        <Card {...args}>
+          <Card.Content>
+            <span style={{ fontWeight: 500, fontSize: "1.125rem" }}>
+              Notice
+            </span>
+            <p>
+              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!
+            </p>
+            <Button variant="solid" mt="rec-md">
+              Acknowledge
+            </Button>
+          </Card.Content>
+        </Card>
+      </Layer>
+    );
+  },
+};
+
+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>
+            <p>Content inside layer 1 card.</p>
+          </Card>
+        </Layer>
+
+        <Layer layer={2}>
+          <Card {...args}>
+            <Card.Header>Layer 2 Wrapper</Card.Header>
+            <p>
+              Content inside layer 2 card exposing a higher elevation drop
+              shadow inherently cascaded.
+            </p>
+          </Card>
+        </Layer>
+      </div>
+    );
+  },
+};

package/src/components/Card/Card.tsx

@@ -0,0 +1,176 @@
+import { forwardRef } from "react";
+import {
+  Card as MantineCard,
+  type CardProps as MantineCardProps,
+  type CardSectionProps as MantineCardSectionProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Card.module.css";
+
+// ==== CARD CONTAINER ====
+export type CardProps = RecursicaOverStyled<MantineCardProps>;
+
+/**
+ * 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.
+ */
+const CardBase = forwardRef<HTMLDivElement, CardProps>(function Card(
+  { overStyled = false, ...rest },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+
+  const mergedClassNames: Partial<Record<string, string>> = {
+    root: styles.root,
+  };
+
+  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];
+      }
+    });
+  }
+
+  const classNameProp = (sanitizedProps as Record<string, unknown>)
+    .className as string | undefined;
+
+  return (
+    <MantineCard
+      ref={ref}
+      className={classNameProp}
+      classNames={mergedClassNames}
+      {...(sanitizedProps as unknown as MantineCardProps)}
+    />
+  );
+});
+CardBase.displayName = "Card";
+
+// ==== NATIVE MANTINE CARD.SECTION ====
+export type RecursicaCardSectionProps = MantineCardSectionProps & {
+  children?: React.ReactNode;
+};
+export type CardSectionProps = RecursicaOverStyled<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}
+        className={
+          classNameProp ? `${styles.section} ${classNameProp}` : styles.section
+        }
+        {...(sanitizedProps as unknown as MantineCardSectionProps)}
+      />
+    );
+  },
+);
+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.
+ */
+export const CardHeader = forwardRef<HTMLDivElement, CardHeaderProps>(
+  function CardHeader({ 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}
+        className={
+          classNameProp ? `${styles.header} ${classNameProp}` : styles.header
+        }
+        {...(sanitizedProps as unknown as MantineCardSectionProps)}
+      />
+    );
+  },
+);
+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) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const classNameProp = (sanitizedProps as Record<string, unknown>)
+      .className as string | undefined;
+
+    return (
+      <MantineCard.Section
+        ref={ref}
+        className={
+          classNameProp ? `${styles.footer} ${classNameProp}` : styles.footer
+        }
+        {...(sanitizedProps as unknown as MantineCardSectionProps)}
+      />
+    );
+  },
+);
+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}
+        className={
+          classNameProp ? `${styles.content} ${classNameProp}` : styles.content
+        }
+        {...sanitizedProps}
+      />
+    );
+  },
+);
+CardContent.displayName = "CardContent";
+
+// ==== DOT NOTATION EXPORT ====
+type CardComponent = typeof CardBase & {
+  Section: typeof CardSection;
+  Header: typeof CardHeader;
+  Footer: typeof CardFooter;
+  Content: typeof CardContent;
+};
+
+export const Card = CardBase as CardComponent;
+Card.Section = CardSection;
+Card.Header = CardHeader;
+Card.Footer = CardFooter;
+Card.Content = CardContent;

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!