@recursica/adapter-mantine-v8 1.0.0

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

@@ -0,0 +1,120 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Group } from "./Group";
+import { Button } from "../Button";
+import { Text } from "../Text/Text";
+
+type GroupStoryProps = React.ComponentProps<typeof Group>;
+
+const meta: Meta<GroupStoryProps> = {
+  title: "UI-Kit/Group",
+  component: Group,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Group is a flex horizontal layout container that maps directly to Mantine's Group component allowing safe layout property passing.",
+      },
+    },
+  },
+  args: {
+    gap: "rec-default",
+    align: "center",
+    justify: "flex-start",
+    wrap: "wrap",
+  },
+  argTypes: {
+    gap: {
+      control: "select",
+      options: [
+        "rec-none",
+        "rec-sm",
+        "rec-default",
+        "rec-md",
+        "rec-lg",
+        "rec-xl",
+        "rec-2xl",
+        "xs",
+        "sm",
+        "md",
+        "lg",
+        "xl",
+      ],
+      description: "Gap between elements",
+    },
+    align: {
+      control: "select",
+      options: ["flex-start", "center", "flex-end", "stretch"],
+      description: "Align-items property",
+    },
+    justify: {
+      control: "select",
+      options: [
+        "flex-start",
+        "center",
+        "flex-end",
+        "space-between",
+        "space-around",
+      ],
+      description: "Justify-content property",
+    },
+    wrap: {
+      control: "select",
+      options: ["wrap", "nowrap", "wrap-reverse"],
+      description: "Flex-wrap property",
+    },
+    defaultChecked: {
+      table: { disable: true },
+    },
+    rowGap: {
+      table: { disable: true },
+    },
+    columnGap: {
+      table: { disable: true },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<GroupStoryProps>;
+
+export const Default: Story = {
+  // 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>
+      <Text>Text element within Group</Text>
+    </Group>
+  ),
+};
+
+export const StaticGapSmall: Story = {
+  args: {
+    gap: "rec-sm",
+  },
+  // 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>
+      <Button variant="solid">Item 3</Button>
+    </Group>
+  ),
+};
+
+export const StaticGapLarge: Story = {
+  args: {
+    gap: "rec-xl",
+  },
+  // 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>
+      <Button variant="solid">Item 3</Button>
+    </Group>
+  ),
+};

package/src/components/Group/Group.test.tsx

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

package/src/components/Group/Group.tsx

@@ -0,0 +1,60 @@
+import { forwardRef } from "react";
+import {
+  Group as MantineGroup,
+  type GroupProps as MantineGroupProps,
+} from "@mantine/core";
+import {
+  mapLayoutProps,
+  type WithRecursicaSpacing,
+} from "../../utils/filterStylingProps";
+import styles from "./Group.module.css";
+
+/**
+ * Group flex layout wrapper.
+ *
+ * Note: Unlike complex UI components, primitive layout components (Flex, Stack, Group, Container)
+ * DO NOT use the `RecursicaOverStyled` gatekeeper. Developers must be able to freely pass
+ * width, height, padding, margins, and flexbox alignment props to construct structural layouts.
+ *
+ * No formal Recursica prop contract here: this simply passes through Mantine's own
+ * `GroupProps` (gap/rowGap/columnGap/justify/align/wrap are all native to Mantine),
+ * layered only with rec- spacing token support via `WithRecursicaSpacing`.
+ */
+export type GroupProps = WithRecursicaSpacing<MantineGroupProps>;
+
+export const Group = forwardRef<HTMLDivElement, GroupProps>(function Group(
+  { children, gap = "rec-default", ...rest },
+  ref,
+) {
+  const mergedClassNames: Partial<Record<string, string>> = {
+    root: styles.root,
+  };
+
+  const classNamesProp = rest.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;
+  }
+
+  const classNameProp = rest.className as string | undefined;
+  const finalClass = classNameProp
+    ? `${styles.root} ${classNameProp}`
+    : styles.root;
+
+  return (
+    <MantineGroup
+      ref={ref}
+      className={finalClass}
+      classNames={mergedClassNames}
+      {...mapLayoutProps({ gap, ...rest } as Record<string, unknown>)}
+    >
+      {children}
+    </MantineGroup>
+  );
+});
+
+Group.displayName = "Group";

package/src/components/Group/USAGE.md

@@ -0,0 +1,48 @@
+# Group - Usage Guide
+
+This document describes how to integrate and use the `Group` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Group } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Group } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return (
+    <Group gap="md" align="center">
+      <Button variant="secondary">Cancel</Button>
+      <Button variant="primary">Submit</Button>
+    </Group>
+  );
+}
+```
+
+---
+
+## 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
+
+The `Group` component is a generic flex layout wrapper mapped directly to Mantine's `Group`.
+`gap`, `align`, `wrap`, and `justify` all pass through as normal.

package/src/components/Heading/HEADING_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,18 @@
+# Heading – Implementation Notes
+
+## Renamed from `Title` (Matt Massey, 2026-08-28)
+
+**Decision:** Renamed the component from `Title` to `Heading` — designers refer to semantic tags
+(`h1`-`h6`, `span`, `p`), and "Title" wasn't part of that vocabulary. `Heading` + `Text` are now
+Recursica's common typography component names across all adapters. No behavior change.
+
+## `.root` `text-wrap: balance` (Matt Massey, 2026-08-28)
+
+**Decision:** Added `text-wrap: balance` via a new `Heading.module.css` `.root` class, merged onto
+the typography class for every `order` (h1–h6), alongside the caller's own `className`.
+
+**Implementation:** UX asked for more evenly balanced multi-line wrapping instead of a ragged last
+line — headings are the primary intended use case for this property. Not a design token — it's a
+layout algorithm choice, so it's hardcoded rather than pulled from `recursica_variables_scoped.css`.
+Chromium/Firefox only balance up to ~6 lines, which comfortably covers heading text. No fallback
+needed — browsers that don't support the value just ignore the declaration.

package/src/components/Heading/Heading.module.css

@@ -0,0 +1,13 @@
+/*
+ * HARDCODED VALUES
+ * - `.root` `text-wrap: balance` — not a design token; a layout algorithm choice requested by
+ *   UX (Matt Massey, 2026-08-28) to even out wrapped line lengths. See HEADING_IMPLEMENTATION_NOTES.md.
+ */
+
+.root {
+  /* HARDCODE: balances wrapped line lengths instead of leaving a ragged short last line. Most
+     effective on short text; browsers cap balancing at ~6 lines, so long paragraphs silently
+     fall back to normal wrapping past that point — no fallback needed, unsupported browsers
+     just ignore the declaration. */
+  text-wrap: balance;
+}

package/src/components/Heading/Heading.stories.tsx

@@ -0,0 +1,50 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Heading } from "./Heading";
+
+const meta: Meta<typeof Heading> = {
+  title: "UI-Kit/Heading",
+  component: Heading,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The semantic `<Heading>` abstraction intrinsically links pure `h1-h6` tag generation with exact Recursica design boundaries to preserve SEO and screen reader trees uniformly globally.",
+      },
+    },
+  },
+  argTypes: {
+    order: {
+      control: "select",
+      options: [1, 2, 3, 4, 5, 6],
+      description:
+        "Controls the `h` tag and the resultant typographical weighting natively mapped to Recursica.",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Heading>;
+
+export const Default: Story = {
+  args: {
+    order: 1,
+    children: "Semantic H1 Document Boundary",
+  },
+  render: ({ ...args }) => <Heading {...args} />,
+};
+
+export const StaticVariations: Story = {
+  args: {},
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "24px" }}>
+      <Heading order={1}>H1 Heading</Heading>
+      <Heading order={2}>H2 Heading</Heading>
+      <Heading order={3}>H3 Heading</Heading>
+      <Heading order={4}>H4 Heading</Heading>
+      <Heading order={5}>H5 Heading</Heading>
+      <Heading order={6}>H6 Heading</Heading>
+    </div>
+  ),
+};

package/src/components/Heading/Heading.test.tsx

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

package/src/components/Heading/Heading.tsx

@@ -0,0 +1,52 @@
+import { forwardRef } from "react";
+import {
+  Title as MantineTitle,
+  type TitleProps as MantineTitleProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  omitUnsupportedProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+
+import { type RecursicaHeadingProps } from "@recursica/adapter-common";
+import styles from "./Heading.module.css";
+
+export type HeadingProps = RecursicaOverStyled<
+  Omit<MantineTitleProps, "size"> & RecursicaHeadingProps
+>;
+
+/**
+ * Enforces highly accessible structural markup utilizing semantic `<h1>` through `<h6>` tags securely bound directly to Recursica typographic scales.
+ */
+export const Heading = forwardRef<HTMLHeadingElement, HeadingProps>(
+  function Heading({ overStyled = false, order = 1, ...rest }, ref) {
+    // 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, bypassing the `Omit<>` above.
+    const UNSUPPORTED_PROPS = [
+      "size", // Recursica controls Heading sizing via the `order` prop + typography tokens, not Mantine's native `size`.
+    ] as const satisfies readonly (keyof MantineTitleProps)[];
+
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled),
+      UNSUPPORTED_PROPS,
+    );
+    const classNameProp = (sanitizedProps as Record<string, unknown>)
+      .className as string | undefined;
+
+    const typographyClass = `recursica_brand_typography_h${order}`;
+    const mergedClassName = [typographyClass, styles.root, classNameProp]
+      .filter(Boolean)
+      .join(" ");
+
+    return (
+      <MantineTitle
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineTitleProps)}
+        order={order}
+        className={mergedClassName}
+      />
+    );
+  },
+);
+Heading.displayName = "Heading";

package/src/components/Heading/USAGE.md

@@ -0,0 +1,36 @@
+# Heading - Usage Guide
+
+This document describes how to integrate and use the `Heading` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Heading } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Heading } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return <Heading order={1}>This is a Heading 1</Heading>;
+}
+```
+
+---
+
+## 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.

package/src/components/HoverCard/HOVERCARD_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,77 @@
+# HoverCard – Implementation Notes
+
+Decisions and design tweaks strictly tailored for the UI Kit's HoverCard 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 (`<HoverCard>`, `<HoverCard.Target>`, `<HoverCard.Dropdown>`) as a 1:1 React component mapping.
+
+**Implementation:** Mantine's HoverCard internally manages hover detection, open/close delays, Floating UI positioning, and portal rendering. By preserving the exact sub-component tree, Recursica safely inherits all of these behaviors without reimplementation.
+
+---
+
+## 2. HoverCard.Target Pass-Through
+
+**Decision:** `HoverCard.Target` is a transparent pass-through with no styling applied.
+
+**Implementation:** The target wrapper exists solely to manage Mantine's ref forwarding and hover 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>`). This is identical to the `Menu.Target` pattern.
+
+---
+
+## 3. Token Namespace: `hover-card-popover`
+
+**Decision:** The CSS module exclusively uses variables from the `--recursica_ui-kit_components_hover-card-popover_*` namespace.
+
+**Implementation:** The Recursica token system defines a single shared namespace (`hover-card-popover`) for this component covering geometry (border-radius, border-size, padding, min/max-width), typography (content-text\_\*), elevation, and layer-aware colors (background, border-color, content). No tokens from other component namespaces are referenced.
+
+---
+
+## 4. Hardcoded Values
+
+**Decision:** Two hardcoded values exist in the component.
+
+### `border-style: solid` (CSS module)
+
+Mantine renders the dropdown using its `Paper` component, which does not set `border-style` natively. Without this hardcoded value, the border-width and border-color tokens would have no visible effect. This is the same pattern used in the Menu component's dropdown.
+
+### `arrowSize` defaulted to `16` (HoverCard.tsx)
+
+Mantine's `arrowSize` prop is a JavaScript number used for inline style calculations: it sets `width`, `height`, and a positioning offset (`-arrowSize/2`) directly on the arrow `<div>` element. These inline styles **cannot** be overridden via CSS without `!important`, and the positioning offset has no CSS equivalent. This means the beak size cannot be fully CSS-driven — it is one of the rare cases where a design token value must be mirrored as a JS prop.
+
+The default value `16` matches the Recursica `beak-size` token (`--recursica_ui-kit_components_hover-card-popover_properties_beak-size: 16px`). Developers can override `arrowSize` if needed, but should be aware this is a design system concern. If the token value changes, the default in `HoverCard.tsx` must also be updated.
+
+This is documented as an open issue in `docs/COMPONENT_ISSUES.md`.
+
+**Note:** Mantine calls this the "arrow"; Recursica calls it the "beak". The Recursica prop `withBeak` (defaulting to `true`) maps to Mantine's `withArrow`. Both `withBeak` and `withArrow` are accepted; `withBeak` takes precedence.
+
+---
+
+## 5. Minimal CSS Override Philosophy
+
+**Decision:** The CSS module only overrides visual design tokens (colors, typography, spacing, borders, shadows). All structural layout properties are deferred to Mantine's native behavior.
+
+**Implementation:** HoverCard is an overlay component where Mantine's native Floating UI positioning and Paper layout are already correct. We avoid setting:
+
+- `overflow` on the dropdown (Mantine handles scroll behavior natively)
+- `display`, `position`, `z-index` (Floating UI controls these)
+- `pointer-events` (Mantine manages hover detection across target and dropdown)
+
+**Rationale:** The Menu implementation demonstrated that aggressive structural resets (overflow, box-sizing) on overlay components cause layout breakage. Default to Mantine's native behavior and only override what the Recursica token system explicitly needs to control.
+
+---
+
+## 6. ClassNames Merging on Root
+
+**Decision:** The root `HoverCard` component binds CSS module classes via `classNames` on the Mantine root, identical to the Menu pattern.
+
+**Implementation:** The root component receives `classNames={{ dropdown: styles.dropdown }}` and merges any consumer-provided `classNames` when `overStyled` is true. This ensures our token-driven styles are applied to the dropdown panel without wrapper divs, and the consumer's classes are additive.
+
+---
+
+## 7. Default Position Override
+
+**Decision:** Recursica defaults `position` to `"top"`. Mantine defaults to `"bottom"`.
+
+**Implementation:** The `position="top"` default is set on the Mantine root element before the prop spread, so developer-provided `position` values still take precedence. This aligns with Recursica's design intent for overlay components to appear above their trigger by default.

package/src/components/HoverCard/HoverCard.module.css

@@ -0,0 +1,90 @@
+/* HARDCODED VALUES:
+   - border-style: solid. Structural rendering rule for the dropdown border (Mantine uses Paper
+     which may not set border-style natively). Same pattern as Menu.
+   - arrowSize defaults to 16 in HoverCard.tsx. Mantine uses arrowSize for inline width/height
+     and positioning (-arrowSize/2) calculations that cannot be CSS-driven. The default matches
+     the Recursica beak-size token (16px).
+   - All structural layout (display, position, overflow) is deferred to Mantine's native
+     behavior. We only override visual design tokens (colors, typography, spacing, borders). */
+
+/* EXEMPTIONS:
+   - beak-size is ignored: the arrow's size is Mantine's own `arrowSize` JS prop, not CSS-driven —
+     see HARDCODED VALUES above. */
+/* recursica-ignore: --recursica_ui-kit_components_hover-card-popover_properties_beak-size */
+
+/* ======================================
+   DROPDOWN CONTAINER
+   ====================================== */
+
+.dropdown {
+  background-color: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_colors_background-color
+  );
+  border-style: solid; /* HARDCODE: Mantine Paper does not set border-style natively */
+  border-width: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_border-size
+  );
+  border-color: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_colors_border-color
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_border-radius
+  );
+  box-shadow: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_elevation
+  );
+
+  min-width: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_min-width
+  );
+  max-width: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_max-width
+  );
+
+  padding: var(
+      --recursica_ui-kit_components_hover-card-popover_properties_vertical-padding
+    )
+    var(
+      --recursica_ui-kit_components_hover-card-popover_properties_horizontal-padding
+    );
+
+  /* Typography */
+  font-family: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_content-text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_content-text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_content-text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_content-text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_content-text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_content-text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_content-text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_content-text_text-transform
+  );
+
+  color: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_colors_content
+  );
+}
+
+/* ======================================
+   ARROW / BEAK
+   ====================================== */
+
+.arrow {
+  border-color: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_colors_border-color
+  );
+}