@recursica/mui-adapter 0.5.0 → 0.7.0

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

@@ -1,23 +1,91 @@
+/* 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).
 /* EXEMPTIONS:
-   This component is a placeholder stub. Once fully implemented, its specific
-   tokens will be fully wired up to direct styles. */
-
-/* recursica-ignore: --recursica_ui-kit_components_hover-card-popover_properties_beak-size */
-/* recursica-ignore: --recursica_ui-kit_components_hover-card-popover_properties_border-radius */
-/* recursica-ignore: --recursica_ui-kit_components_hover-card-popover_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_hover-card-popover_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_hover-card-popover_properties_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_hover-card-popover_properties_colors_content */
-/* recursica-ignore: --recursica_ui-kit_components_hover-card-popover_properties_content-text_font-family */
-/* recursica-ignore: --recursica_ui-kit_components_hover-card-popover_properties_content-text_font-size */
-/* recursica-ignore: --recursica_ui-kit_components_hover-card-popover_properties_content-text_font-style */
-/* recursica-ignore: --recursica_ui-kit_components_hover-card-popover_properties_content-text_font-weight */
-/* recursica-ignore: --recursica_ui-kit_components_hover-card-popover_properties_content-text_letter-spacing */
-/* recursica-ignore: --recursica_ui-kit_components_hover-card-popover_properties_content-text_line-height */
-/* recursica-ignore: --recursica_ui-kit_components_hover-card-popover_properties_content-text_text-decoration */
-/* recursica-ignore: --recursica_ui-kit_components_hover-card-popover_properties_content-text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_hover-card-popover_properties_elevation */
-/* recursica-ignore: --recursica_ui-kit_components_hover-card-popover_properties_horizontal-padding */
-/* recursica-ignore: --recursica_ui-kit_components_hover-card-popover_properties_max-width */
-/* recursica-ignore: --recursica_ui-kit_components_hover-card-popover_properties_min-width */
-/* recursica-ignore: --recursica_ui-kit_components_hover-card-popover_properties_vertical-padding */
+   - beak-size is ignored here because Mantine's popover arrows compute their sizing and positional offsets
+     dynamically within the React rendering engine (requires inline pixel number rather than standard CSS variables).
+     The beak size is checked in JS against a fixed value of 16px. If this variable changes, the TSX components
+     need to be reviewed/re-compiled. */
+/* recursica-ignore: --recursica_ui-kit_components_hover-card-popover_properties_beak-size = 16px */
+
+/* ======================================
+   DROPDOWN CONTAINER
+   ====================================== */
+
+.dropdown {
+  background-color: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_colors_background
+  );
+  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
+  );
+}

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

@@ -1,35 +1,172 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { HoverCard } from "./HoverCard";
-import { ComingSoon } from "@recursica/storybook-template";
+import { Button } from "../Button";
+import { Text } from "../Text/Text";
+import { Group } from "../Group/Group";
+import { Stack } from "../Stack/Stack";
+import { Avatar } from "../Avatar";
 
-const meta: Meta<typeof HoverCard> = {
-  title: "UI-Kit/🚧 HoverCard",
+/**
+ * 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"],
-  parameters: {
-    controls: {
-      include: [
-        "layer",
-        "withLayer",
-        "children",
-        "component",
-        "variant",
-        "size",
-        "icon",
-        "disabled",
-        "href",
-        "onClick",
-        "onChange",
-        "value",
-        "checked",
+  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<typeof HoverCard>;
+
+type Story = StoryObj<HoverCardStoryArgs>;
 
 export const Default: Story = {
-  render: () => <ComingSoon componentName="HoverCard" />,
+  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={null} alt="User avatar" />
+            <Stack>
+              <Text>Jane Doe</Text>
+              <Text>Software Engineer at Recursica</Text>
+            </Stack>
+          </Group>
+        </HoverCard.Dropdown>
+      </HoverCard>
+    );
+  },
 };

package/src/components/HoverCard/HoverCard.tsx

@@ -1,8 +1,150 @@
-import React from "react";
-import "./HoverCard.module.css";
+import React, { isValidElement } from "react";
+import {
+  Tooltip as MuiTooltip,
+  type TooltipProps as MuiTooltipProps,
+} from "@mui/material";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./HoverCard.module.css";
 
-export type HoverCardProps = React.HTMLAttributes<HTMLDivElement>;
+// ============================================================
+// HOVERCARD ROOT
+// ============================================================
 
-export const HoverCard: React.FC<HoverCardProps> = (props) => {
-  return <div {...props}>HoverCard</div>;
+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
+  const mergedClassNames: Partial<Record<string, string>> = {
+    tooltip: styles.dropdown,
+    arrow: styles.arrow,
+  };
+
+  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];
+      }
+    });
+  }
+
+  // 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 any;
+      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
+      title={dropdownNode}
+      placement={position as any}
+      arrow={withBeak}
+      enterDelay={openDelay}
+      leaveDelay={closeDelay}
+      disableHoverListener={disabled}
+      slotProps={{
+        popper: {
+          modifiers: [
+            {
+              name: "offset",
+              options: {
+                offset: [0, offset],
+              },
+            },
+          ],
+        },
+      }}
+      classes={mergedClassNames as any}
+      {...(sanitizedProps as any)}
+    >
+      {/* 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/Label/Label.module.css

@@ -1,35 +1,140 @@
-/* EXEMPTIONS:
-   This component is a placeholder stub. Once fully implemented, its specific
-   tokens will be fully wired up to direct styles. */
-
-/* recursica-ignore: --recursica_ui-kit_components_label_properties_colors_asterisk */
-/* recursica-ignore: --recursica_ui-kit_components_label_properties_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_label_properties_edit-icon-gap */
-/* recursica-ignore: --recursica_ui-kit_components_label_properties_label-optional-text-gap */
-/* recursica-ignore: --recursica_ui-kit_components_label_properties_label-text_font-family */
-/* recursica-ignore: --recursica_ui-kit_components_label_properties_label-text_font-size */
-/* recursica-ignore: --recursica_ui-kit_components_label_properties_label-text_font-style */
-/* recursica-ignore: --recursica_ui-kit_components_label_properties_label-text_font-weight */
-/* recursica-ignore: --recursica_ui-kit_components_label_properties_label-text_letter-spacing */
-/* recursica-ignore: --recursica_ui-kit_components_label_properties_label-text_line-height */
-/* recursica-ignore: --recursica_ui-kit_components_label_properties_label-text_text-decoration */
-/* recursica-ignore: --recursica_ui-kit_components_label_properties_label-text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_label_properties_optional-text-opacity */
-/* recursica-ignore: --recursica_ui-kit_components_label_properties_optional-text_font-family */
-/* recursica-ignore: --recursica_ui-kit_components_label_properties_optional-text_font-size */
-/* recursica-ignore: --recursica_ui-kit_components_label_properties_optional-text_font-style */
-/* recursica-ignore: --recursica_ui-kit_components_label_properties_optional-text_font-weight */
-/* recursica-ignore: --recursica_ui-kit_components_label_properties_optional-text_letter-spacing */
-/* recursica-ignore: --recursica_ui-kit_components_label_properties_optional-text_line-height */
-/* recursica-ignore: --recursica_ui-kit_components_label_properties_optional-text_text-decoration */
-/* recursica-ignore: --recursica_ui-kit_components_label_properties_optional-text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_label_properties_required-indicator-gap */
-/* recursica-ignore: --recursica_ui-kit_components_label_variants_layouts_side-by-side_properties_gutter */
-/* recursica-ignore: --recursica_ui-kit_components_label_variants_layouts_side-by-side_properties_min-height */
-/* recursica-ignore: --recursica_ui-kit_components_label_variants_layouts_side-by-side_properties_vertical-padding */
-/* recursica-ignore: --recursica_ui-kit_components_label_variants_layouts_side-by-side_variants_sizes_default_properties_width */
-/* recursica-ignore: --recursica_ui-kit_components_label_variants_layouts_side-by-side_variants_sizes_small_properties_width */
-/* recursica-ignore: --recursica_ui-kit_components_label_variants_layouts_stacked_properties_bottom-padding */
-/* recursica-ignore: --recursica_ui-kit_components_label_variants_layouts_stacked_properties_min-height */
-/* recursica-ignore: --recursica_ui-kit_components_label_variants_layouts_stacked_variants_sizes_default_properties_width */
-/* recursica-ignore: --recursica_ui-kit_components_label_variants_layouts_stacked_variants_sizes_small_properties_width */
+.root {
+  /* Prevent default MUI absolute positioning logic */
+  position: relative;
+  transform: none;
+  pointer-events: auto;
+  white-space: normal;
+
+  /* Reset MUI structural overrides */
+  margin: 0;
+  padding: 0;
+  display: flex;
+  width: 100%;
+
+  /* Recursica Font Map */
+  font-family: var(
+    --recursica_ui-kit_components_label_properties_label-text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_label_properties_label-text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_label_properties_label-text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_label_properties_label-text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_label_properties_label-text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_label_properties_label-text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_label_properties_label-text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_label_properties_label-text_text-transform
+  );
+
+  color: var(--recursica_ui-kit_components_label_properties_colors_text);
+}
+
+.innerLayout {
+  display: flex;
+  align-items: center;
+  gap: var(
+    --recursica_ui-kit_components_label_properties_label-optional-text-gap
+  );
+  width: 100%;
+}
+
+.text {
+  /* Natively intercepts MUI asterisk rendering securely wrapping inline with typography */
+  display: inline;
+}
+
+.required {
+  /* Override the `.MuiInputLabel-asterisk` natively */
+  color: var(--recursica_ui-kit_components_label_properties_colors_asterisk);
+  margin-left: var(
+    --recursica_ui-kit_components_label_properties_required-indicator-gap
+  );
+}
+
+.root :global(.MuiFormLabel-asterisk) {
+  display: none !important;
+}
+
+/* MUI propagates .Mui-error to the label automatically on FormControl error. 
+   We explicitly override this bleed to prevent the main label text from turning red, 
+   while allowing the asterisk to take the error color! */
+.root:global(.Mui-error) {
+  color: var(--recursica_ui-kit_components_label_properties_colors_text);
+}
+.root:global(.Mui-error) .required {
+  color: var(
+    --recursica_ui-kit_components_assistive-element_variants_types_error_properties_colors_text-color
+  );
+}
+
+.endNodes {
+  display: flex;
+  align-items: center;
+  gap: var(
+    --recursica_ui-kit_components_label_properties_label-optional-text-gap
+  );
+}
+
+.optionalText {
+  color: inherit;
+  font-family: var(
+    --recursica_ui-kit_components_label_properties_optional-text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_label_properties_optional-text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_label_properties_optional-text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_label_properties_optional-text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_label_properties_optional-text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_label_properties_optional-text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_label_properties_optional-text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_label_properties_optional-text_text-transform
+  );
+}
+
+.actionArea {
+  display: flex;
+  align-items: center;
+}
+
+.editIcon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  background: none;
+  border: none;
+  padding: 0;
+
+  width: 16px;
+  height: 16px;
+  color: inherit;
+}
+
+.editIcon :global(svg) {
+  width: 100%;
+  height: 100%;
+  stroke-width: 2px;
+}