@recursica/adapter-mui-v7 1.0.0

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,28 @@
+import React, { forwardRef } from "react";
+import { type TypographyProps as MuiTypographyProps } from "@mui/material";
+import { Typography } from "../Typography/Typography";
+import { type RecursicaOverStyled } from "../../utils/filterStylingProps";
+import { type RecursicaHeadingProps } from "@recursica/adapter-common";
+
+export type HeadingProps = RecursicaOverStyled<
+  Omit<MuiTypographyProps, "variant" | "classes"> & RecursicaHeadingProps
+>;
+
+export const Heading = forwardRef<HTMLElement, HeadingProps>(function Heading(
+  { order = 1, component, ...rest },
+  ref,
+) {
+  const typographyClass = `recursica_brand_typography_h${order}`;
+  const defaultComponent = `h${order}` as React.ElementType;
+
+  return (
+    <Typography
+      ref={ref}
+      typographyClass={typographyClass}
+      component={component || defaultComponent}
+      {...rest}
+    />
+  );
+});
+
+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-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Heading } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Heading } from "@recursica/adapter-mui-v7";
+
+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-mui-v7` 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/Heading/index.ts

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

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

@@ -0,0 +1,107 @@
+/* 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). See COMPONENT_ISSUES.md for details.
+   - All structural layout (display, position, overflow) is deferred to Mantine's native
+     behavior. We only override visual design tokens (colors, typography, spacing, borders).
+   - margin: 0 !important on .dropdown. Mui's Tooltip hardcodes a per-placement margin
+     (14px, reset to 0 only when arrow is enabled) on top of whatever offset the popper
+     "offset" modifier applies, so with withBeak=false the trigger-to-dropdown gap was
+     offset + 14px instead of just offset. There is no Recursica token for this spacing —
+     the gap is driven purely by the `offset` prop (a plain number, same as Mantine's
+     HoverCard), so we zero out Mui's extra margin to make offset the only source of gap. */
+
+/* ======================================
+   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
+  );
+
+  margin: 0 !important; /* HARDCODE: cancel Mui's built-in per-placement margin, see note above */
+}
+
+/* ======================================
+   ARROW / BEAK
+   ====================================== */
+
+/* Mui's arrow is a rotated square (via ::before, background-color: currentColor)
+   sized in em units off font-size, not a bordered CSS triangle. `color` (not
+   border-color) is what actually fills it, which is why setting border-color here
+   previously had no visible effect and left it defaulting to the inherited text
+   color (solid black). Fill it with the same background-color token the card body
+   uses so it blends into the card exactly like Mantine's beak, and size it off the
+   beak-size token instead of Mui's default 1em/0.71em (font-size-relative) box. */
+.arrow {
+  color: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_colors_background-color
+  );
+  width: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_beak-size
+  );
+  height: calc(
+    var(--recursica_ui-kit_components_hover-card-popover_properties_beak-size) *
+      0.7071
+  ); /* = width / sqrt(2), same ratio Mui's default arrow uses */
+}

package/src/components/HoverCard/HoverCard.stories.tsx

@@ -0,0 +1,172 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { HoverCard } from "./HoverCard";
+import { Button } from "../Button";
+import { Text } from "../Text/Text";
+import { Group } from "../Group/Group";
+import { Stack } from "../Stack/Stack";
+import { Avatar } from "../Avatar";
+
+/**
+ * HoverCard story axes:
+ * - position: dropdown alignment relative to target
+ * - withArrow: arrow indicator on the dropdown
+ * - openDelay / closeDelay: hover timing controls
+ * - content variations: plain text, rich content (avatar + text + actions)
+ * - layer: tested via the global Layer decorator (withLayer/layer args)
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type HoverCardStoryArgs = Record<string, any>;
+
+const meta: Meta = {
+  title: "UI-Kit/HoverCard",
+  component: HoverCard,
+  tags: ["autodocs"],
+  argTypes: {
+    position: {
+      control: "select",
+      options: [
+        "bottom",
+        "bottom-start",
+        "bottom-end",
+        "top",
+        "top-start",
+        "top-end",
+        "left",
+        "left-start",
+        "left-end",
+        "right",
+        "right-start",
+        "right-end",
+      ],
+      description: "The position of the dropdown relative to the target.",
+    },
+    withBeak: {
+      control: "boolean",
+      description:
+        "Whether to display a beak (arrow) pointing to the target. Recursica equivalent of Mantine's withArrow.",
+    },
+    offset: {
+      control: "number",
+      description:
+        "Distance in px between the dropdown and the target element.",
+    },
+    openDelay: {
+      control: "number",
+      description: "Delay in ms before the dropdown opens on hover.",
+    },
+    closeDelay: {
+      control: "number",
+      description: "Delay in ms before the dropdown closes when hover ends.",
+    },
+    disabled: {
+      control: "boolean",
+      description: "If set, the hover card dropdown will not be rendered.",
+    },
+  },
+  parameters: {
+    layout: "centered",
+    docs: {
+      description: {
+        component: `
+The \`HoverCard\` component displays a popover-style dropdown when the user hovers over a target element. It wraps Mantine's composable \`HoverCard\` while enforcing strict Recursica design token styling.
+
+### Composable API
+
+HoverCard uses a dot-notation composition pattern:
+- \`<HoverCard>\` — Root container managing open/close state on hover
+- \`<HoverCard.Target>\` — Wrapper for the trigger element (must be a single element supporting ref)
+- \`<HoverCard.Dropdown>\` — The popup panel displaying content on hover
+
+### Key Behaviors
+- The dropdown opens when the user hovers over the target and closes when they move away
+- \`openDelay\` and \`closeDelay\` control the timing of open/close transitions
+- The dropdown stays open while the user hovers over it, allowing interaction with its content
+        `,
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<HoverCardStoryArgs>;
+
+export const Default: Story = {
+  args: {
+    position: "top",
+    withBeak: true,
+    offset: 5,
+    openDelay: 0,
+    closeDelay: 150,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: HoverCardStoryArgs) => {
+    return (
+      <HoverCard {...args}>
+        <HoverCard.Target>
+          <Button variant="solid">Hover me</Button>
+        </HoverCard.Target>
+
+        <HoverCard.Dropdown>
+          <Text>
+            This is a hover card with informational content that appears when
+            you hover over the target element.
+          </Text>
+        </HoverCard.Dropdown>
+      </HoverCard>
+    );
+  },
+};
+
+export const WithoutBeak: Story = {
+  args: {
+    position: "top",
+    withBeak: false,
+    offset: 5,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: HoverCardStoryArgs) => {
+    return (
+      <HoverCard {...args}>
+        <HoverCard.Target>
+          <Button variant="outline">Without Beak</Button>
+        </HoverCard.Target>
+
+        <HoverCard.Dropdown>
+          <Text>
+            This hover card has the beak disabled, showing a clean dropdown
+            without the pointing indicator.
+          </Text>
+        </HoverCard.Dropdown>
+      </HoverCard>
+    );
+  },
+};
+
+export const RichContent: Story = {
+  args: {
+    position: "top",
+    offset: 5,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: HoverCardStoryArgs) => {
+    return (
+      <HoverCard {...args}>
+        <HoverCard.Target>
+          <Button variant="solid">User Profile</Button>
+        </HoverCard.Target>
+
+        <HoverCard.Dropdown>
+          <Group>
+            <Avatar src={undefined} alt="User avatar" />
+            <Stack>
+              <Text>Jane Doe</Text>
+              <Text>Software Engineer at Recursica</Text>
+            </Stack>
+          </Group>
+        </HoverCard.Dropdown>
+      </HoverCard>
+    );
+  },
+};

package/src/components/HoverCard/HoverCard.test.tsx

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

package/src/components/HoverCard/HoverCard.tsx

@@ -0,0 +1,145 @@
+import React, { isValidElement } from "react";
+import {
+  Tooltip as MuiTooltip,
+  type TooltipProps as MuiTooltipProps,
+} from "@mui/material";
+import {
+  filterStylingProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./HoverCard.module.css";
+
+// ============================================================
+// HOVERCARD ROOT
+// ============================================================
+
+import { type RecursicaHoverCardProps } from "@recursica/adapter-common";
+
+export type HoverCardProps = RecursicaOverStyled<
+  Omit<MuiTooltipProps, "title" | "children"> & RecursicaHoverCardProps
+>;
+
+const HoverCardBase = function HoverCard({
+  overStyled = false,
+  withBeak = true,
+  position = "top",
+  openDelay = 0,
+  closeDelay = 150,
+  disabled = false,
+  offset = 5,
+  children,
+  ...rest
+}: HoverCardProps) {
+  const sanitizedProps = filterStylingProps(
+    rest as Record<string, unknown>,
+    overStyled,
+  );
+
+  // Bind CSS module classes to Mui's internal classNames API. Note MUI's actual prop is
+  // "classes", not "classNames" (that's Mantine's naming) — this used to read the wrong key,
+  // silently no-op-ing any caller-supplied classes.
+  const mergedClassNames = mergeClassNames(
+    {
+      tooltip: styles.dropdown,
+      arrow: styles.arrow,
+    },
+    (sanitizedProps as Record<string, unknown>).classes as
+      | Partial<Record<string, string>>
+      | undefined,
+  );
+
+  // Find Target and Dropdown children
+  let targetNode: React.ReactNode = null;
+  let dropdownNode: React.ReactNode = null;
+
+  React.Children.forEach(children, (child) => {
+    if (isValidElement(child)) {
+      const childElement = child as unknown as {
+        type?: { displayName?: string };
+        props: { children?: React.ReactNode };
+      };
+      if (childElement.type?.displayName === "HoverCardTarget") {
+        targetNode = childElement.props.children;
+      } else if (childElement.type?.displayName === "HoverCardDropdown") {
+        dropdownNode = childElement.props.children;
+      }
+    }
+  });
+
+  if (!targetNode) {
+    // Fallback if structure is wrong
+    targetNode = <div />;
+  }
+  if (!dropdownNode) {
+    dropdownNode = <div />;
+  }
+
+  return (
+    <MuiTooltip
+      {...(sanitizedProps as unknown as Record<string, unknown>)}
+      title={dropdownNode}
+      placement={position as unknown as MuiTooltipProps["placement"]}
+      arrow={withBeak}
+      enterDelay={openDelay}
+      leaveDelay={closeDelay}
+      disableHoverListener={disabled}
+      slotProps={{
+        popper: {
+          modifiers: [
+            {
+              name: "offset",
+              options: {
+                offset: [0, offset],
+              },
+            },
+          ],
+        },
+      }}
+      classes={mergedClassNames as unknown as MuiTooltipProps["classes"]}
+    >
+      {/* Tooltip requires a single valid React element child that accepts a ref */}
+      {isValidElement(targetNode) ? targetNode : <span>{targetNode}</span>}
+    </MuiTooltip>
+  );
+};
+HoverCardBase.displayName = "HoverCard";
+
+// ============================================================
+// HOVERCARD TARGET
+// ============================================================
+
+export type HoverCardTargetProps = { children?: React.ReactNode };
+
+const HoverCardTarget = function HoverCardTarget({
+  children,
+}: HoverCardTargetProps) {
+  return <>{children}</>;
+};
+HoverCardTarget.displayName = "HoverCardTarget";
+
+// ============================================================
+// HOVERCARD DROPDOWN
+// ============================================================
+
+export type HoverCardDropdownProps = { children?: React.ReactNode };
+
+const HoverCardDropdown = function HoverCardDropdown({
+  children,
+}: HoverCardDropdownProps) {
+  return <>{children}</>;
+};
+HoverCardDropdown.displayName = "HoverCardDropdown";
+
+// ============================================================
+// DOT NOTATION EXPORT
+// ============================================================
+
+type HoverCardComponent = typeof HoverCardBase & {
+  Target: typeof HoverCardTarget;
+  Dropdown: typeof HoverCardDropdown;
+};
+
+export const HoverCard = HoverCardBase as HoverCardComponent;
+HoverCard.Target = HoverCardTarget;
+HoverCard.Dropdown = HoverCardDropdown;

package/src/components/HoverCard/USAGE.md

@@ -0,0 +1,45 @@
+# HoverCard - Usage Guide
+
+This document describes how to integrate and use the `HoverCard` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { HoverCard } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { HoverCard } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return (
+    <HoverCard>
+      <HoverCard.Target>
+        <Text>Hover over me</Text>
+      </HoverCard.Target>
+      <HoverCard.Dropdown>
+        <Text size="sm">This is the hover card popup content.</Text>
+      </HoverCard.Dropdown>
+    </HoverCard>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mui-v7` 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/index.ts

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

package/src/components/Label/LABEL_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,27 @@
+# Label Implementation Notes
+
+Decisions and gotchas specific to wrapping `@mui/material`'s `InputLabel` for the UI Kit's Label.
+
+## `labelAlignment` was completely unimplemented
+
+**Found 2026-08-30, source-of-truth audit against mantine.** `ui-kit-label--right-aligned` used
+identical story args on both adapters, but only mantine's rendering was actually right-aligned.
+Root cause: `labelAlignment` isn't part of MUI `InputLabelProps`, and this component never
+destructured or otherwise referenced it — it silently fell into `...rest` and got spread onto
+`<InputLabel>` as an unrecognized prop (no visual effect, MUI drops/ignores it). Fixed by
+destructuring `labelAlignment` (defaulting to `"left"`, matching mantine), exposing it as
+`data-alignment` on the root `<InputLabel>`, and adding
+`.root[data-alignment="right"] .innerLayout { justify-content: flex-end; text-align: right; }`
+in `Label.module.css` — mirroring mantine-adapter's own `[data-alignment]` selector pattern.
+
+## `labelOptionalText` custom string wasn't wrapped in parentheses
+
+**Found 2026-08-30, source-of-truth audit against mantine.** `ui-kit-label--with-optional-text`
+passes a custom string (`"Max 100 characters"`), not the `true` sentinel. This component only
+special-cased `labelOptionalText === true` (mapping it to the literal `"(optional)"` string) and
+rendered any other value verbatim, with no parentheses — e.g. mantine shows `(Max 100
+characters)`, this adapter showed `Max 100 characters`. Mantine's component wraps ANY resolved
+string value in parentheses, not just its own boolean-default case. Fixed to match: resolve
+`true` to `"optional"` same as before, then wrap the result in parentheses whenever it's a
+string (non-string custom nodes, e.g. a caller-supplied element, pass through unwrapped, same as
+mantine).