@recursica/mantine-adapter 0.5.0 → 0.7.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!

package/src/components/Checkbox/Checkbox.module.css

@@ -0,0 +1,204 @@
+/**
+ * Checkbox.module.css
+ * 
+ * HARDCODED VALUES:
+ * - margin / padding: 0 — Structural resets; consider token if spacing needed.
+ * - cursor: pointer / not-allowed — Baseline interactive indications.
+ * - appearance / box-sizing / border-style — necessary normalization for inputs.
+ * - transition: all 0.2s ease — Animation curve; consider a transition token.
+ * - min-width: 0 — Forces text wrap boundary in flex children.
+ */
+
+/* --- GROUP STYLES --- */
+.groupRoot {
+  padding: var(
+    --recursica_ui-kit_components_checkbox-group_properties_padding,
+    0
+  );
+  margin: 0; /* HARDCODE: structural reset; consider token if layout needs change */
+  display: flex !important;
+  flex-direction: column;
+  gap: var(
+    --recursica_ui-kit_components_checkbox-group_properties_item-gap,
+    16px
+  );
+}
+
+/* SideBySide Variant */
+.groupRoot[data-layout="side-by-side"] {
+  flex-direction: column;
+  flex-wrap: wrap;
+  padding-top: var(
+    --recursica_ui-kit_components_checkbox-group_variants_layouts_side-by-side_properties_vertical-padding
+  );
+  padding-bottom: var(
+    --recursica_ui-kit_components_checkbox-group_variants_layouts_side-by-side_properties_vertical-padding
+  );
+  margin-top: var(
+    --recursica_ui-kit_components_checkbox-group_variants_layouts_side-by-side_properties_top-bottom-margin
+  );
+  margin-bottom: var(
+    --recursica_ui-kit_components_checkbox-group_variants_layouts_side-by-side_properties_top-bottom-margin
+  );
+}
+
+/* Stacked Variant */
+.groupRoot[data-layout="stacked"] {
+  flex-direction: column;
+  margin-top: var(
+    --recursica_ui-kit_components_checkbox-group_variants_layouts_stacked_properties_top-bottom-margin
+  );
+  margin-bottom: var(
+    --recursica_ui-kit_components_checkbox-group_variants_layouts_stacked_properties_top-bottom-margin
+  );
+}
+
+/* --- PRIMITIVE CHECKBOX STYLES --- */
+
+.root {
+  max-width: var(
+    --recursica_ui-kit_components_checkbox-item_properties_max-width
+  );
+}
+
+.body {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--recursica_ui-kit_components_checkbox-item_properties_label-gap);
+}
+
+.inner {
+  display: flex !important;
+  align-items: center !important;
+  justify-content: center !important;
+  margin: 0 !important; /* HARDCODE: structural reset */
+  width: var(--recursica_ui-kit_components_checkbox_properties_size) !important;
+  height: var(
+    --recursica_ui-kit_components_checkbox_properties_size
+  ) !important;
+  /* Mathematically syncs the physical input checkbox bounding block visually with the center of the text's first line natively. */
+  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;
+}
+
+/* Base explicit reset masking underlying framework defaults */
+.input {
+  cursor: pointer; /* HARDCODE: core interaction behavior */
+  appearance: none; /* HARDCODE: reset native widget */
+  box-sizing: border-box !important; /* HARDCODE: ensures size includes borders */
+  width: var(--recursica_ui-kit_components_checkbox_properties_size) !important;
+  height: var(
+    --recursica_ui-kit_components_checkbox_properties_size
+  ) !important;
+  border-radius: var(
+    --recursica_ui-kit_components_checkbox_properties_border-radius
+  ) !important;
+  border-width: var(
+    --recursica_ui-kit_components_checkbox_properties_border-size
+  ) !important;
+  border-style: solid; /* HARDCODE: normalize primitive border-style */
+
+  /* Standard unchecked state */
+  background-color: var(
+    --recursica_ui-kit_components_checkbox_properties_colors_background-unchecked
+  ) !important;
+  border-color: var(
+    --recursica_ui-kit_components_checkbox_properties_colors_border-unchecked
+  ) !important;
+  transition: all 0.2s ease; /* HARDCODE: consider global transition token */
+}
+
+/* Checked/Indeterminate State */
+.input:checked {
+  background-color: var(
+    --recursica_ui-kit_components_checkbox_properties_colors_background-checked
+  ) !important;
+  border-color: var(
+    --recursica_ui-kit_components_checkbox_properties_colors_border-checked
+  ) !important;
+}
+.input[data-indeterminate] {
+  background-color: var(
+    --recursica_ui-kit_components_checkbox_properties_colors_background-indeterminate
+  ) !important;
+  border-color: var(
+    --recursica_ui-kit_components_checkbox_properties_colors_border-indeterminate
+  ) !important;
+}
+
+/* Disabled State */
+.input:disabled {
+  cursor: not-allowed; /* HARDCODE: disabled state default */
+  opacity: var(
+    --recursica_ui-kit_components_checkbox_properties_disabled-opacity
+  ) !important;
+  background-color: var(
+    --recursica_ui-kit_components_checkbox_properties_colors_disabled-background
+  ) !important;
+  border-color: var(
+    --recursica_ui-kit_components_checkbox_properties_colors_disabled-border
+  ) !important;
+}
+
+.icon {
+  width: var(
+    --recursica_ui-kit_components_checkbox_properties_icon-size
+  ) !important;
+  height: var(
+    --recursica_ui-kit_components_checkbox_properties_icon-size
+  ) !important;
+  color: var(
+    --recursica_ui-kit_components_checkbox_properties_colors_icon-color
+  ) !important;
+}
+.input:disabled + .iconWrapper .icon {
+  color: var(
+    --recursica_ui-kit_components_checkbox_properties_colors_disabled-icon
+  ) !important;
+}
+
+.labelWrapper {
+  padding: 0 !important; /* HARDCODE: structural layout reset */
+  margin: 0 !important; /* HARDCODE: structural layout reset */
+  flex: 1;
+  min-width: 0; /* HARDCODE: forces text wrap boundary in flex child */
+}
+
+.label {
+  cursor: pointer; /* HARDCODE: interactive affordance */
+  padding: 0 !important; /* HARDCODE: reset layout */
+  margin: 0 !important; /* HARDCODE: reset layout */
+  word-wrap: break-word;
+  white-space: normal;
+  color: var(
+    --recursica_ui-kit_components_checkbox-item_properties_text_color
+  ) !important;
+  font-family: var(
+    --recursica_ui-kit_components_checkbox-item_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_checkbox-item_properties_text_font-size
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_checkbox-item_properties_text_font-weight
+  );
+  line-height: var(
+    --recursica_ui-kit_components_checkbox-item_properties_text_line-height
+  );
+}
+.root[data-disabled] .label {
+  cursor: not-allowed; /* HARDCODE: disabled interaction */
+  opacity: var(
+    --recursica_ui-kit_components_checkbox_properties_disabled-opacity
+  );
+}

package/src/components/Checkbox/Checkbox.stories.tsx

@@ -0,0 +1,73 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Checkbox } from "./Checkbox";
+
+const meta: Meta<typeof Checkbox> = {
+  title: "UI-Kit/Checkbox",
+  component: Checkbox,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The \`Checkbox\` component is a precisely engineered, atomic form primitive representing boolean states natively aligned to the Recursica design system. It overrides Mantine's standard properties explicitly enforcing our variables natively across all structural boundaries.
+
+> [!IMPORTANT]  
+> The atomic \`Checkbox\` is intended primarily as an internal primitive. **When wrapping multiple Checkbox elements together or rendering form controls, always utilize the \`<Checkbox.Group>\` component.** \`Checkbox.Group\` inherits the global \`FormControlWrapper\`, granting instantaneous access to macroscopic layout structuring, assistive descriptions, validation errors, and strict flex arrays.
+
+### Usage
+To render a solitary component natively:
+\`\`\`tsx
+<Checkbox label="Acknowledge Terms" defaultChecked />
+\`\`\`
+`,
+      },
+    },
+  },
+  argTypes: {
+    disabled: {
+      control: "boolean",
+    },
+    readOnly: {
+      control: "boolean",
+      description:
+        "Toggles structural read-only data presentation bypassing interaction boundaries completely.",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Checkbox>;
+
+export const Default: Story = {
+  args: {
+    disabled: false,
+    label: "Standard Unchecked Property",
+  },
+};
+
+export const LongLabelWrap: Story = {
+  args: {
+    label:
+      "A meticulously long Checkbox label property demonstrating the absolute maximum 400px wrapper constraints actively snapping the text engine down onto a secondary wrapping line automatically without blowing out the visual boundaries.",
+  },
+};
+
+export const StaticVariations: Story = {
+  args: {},
+  render: () => (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "24px",
+      }}
+    >
+      <Checkbox label="Default Unchecked State" />
+      <Checkbox label="Acknowledge Configuration" defaultChecked />
+      <Checkbox label="Indeterminate Master" indeterminate />
+      <Checkbox label="Disabled Variant" disabled />
+      <Checkbox label="Disabled Checked Variant" checked disabled />
+    </div>
+  ),
+};