@recursica/adapter-mantine-v8 1.0.0

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={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.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,133 @@
+import {
+  HoverCard as MantineHoverCard,
+  type HoverCardProps as MantineHoverCardProps,
+  type HoverCardTargetProps as MantineHoverCardTargetProps,
+  type HoverCardDropdownProps as MantineHoverCardDropdownProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./HoverCard.module.css";
+
+// ============================================================
+// HOVERCARD ROOT
+// ============================================================
+
+/**
+ * Recursica-specific props for HoverCard.
+ */
+import { type RecursicaHoverCardProps } from "@recursica/adapter-common";
+
+/**
+ * Recursica HoverCard component wrapping Mantine's composable HoverCard.
+ *
+ * Displays a dropdown panel when the user hovers over a target element.
+ * Uses the composable dot-notation pattern:
+ * ```tsx
+ * <HoverCard withBeak>
+ *   <HoverCard.Target>
+ *     <Button>Hover me</Button>
+ *   </HoverCard.Target>
+ *   <HoverCard.Dropdown>
+ *     Content displayed on hover
+ *   </HoverCard.Dropdown>
+ * </HoverCard>
+ * ```
+ */
+export type HoverCardProps = RecursicaOverStyled<
+  MantineHoverCardProps & RecursicaHoverCardProps
+>;
+
+const HoverCardBase = function HoverCard({
+  overStyled = false,
+  withBeak = true,
+  position = "top", // Recursica default; Mantine defaults to "bottom". Consumers can still override.
+  // arrowSize must be a JS number prop — Mantine uses it for inline width/height
+  // and positioning offset (-arrowSize/2) calculations that cannot be CSS-driven.
+  // Default to 16 to match the Recursica beak-size token (16px). Consumers can still override.
+  arrowSize = 16,
+  withArrow,
+  ...rest
+}: HoverCardProps) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
+  // Bind CSS module classes to Mantine's internal classNames API
+  const mergedClassNames = mergeClassNames(
+    {
+      dropdown: styles.dropdown,
+      arrow: styles.arrow,
+    },
+    restRecord.classNames as Partial<Record<string, string>> | undefined,
+  );
+
+  // Resolve withBeak (Recursica) vs withArrow (Mantine).
+  // withBeak takes precedence when both are provided.
+  const resolvedWithArrow = withBeak ?? withArrow;
+
+  return (
+    <MantineHoverCard
+      {...(sanitizedProps as unknown as MantineHoverCardProps)}
+      position={position}
+      arrowSize={arrowSize}
+      withArrow={resolvedWithArrow}
+      classNames={mergedClassNames}
+    />
+  );
+};
+HoverCardBase.displayName = "HoverCard";
+
+// ============================================================
+// HOVERCARD TARGET
+// ============================================================
+
+/**
+ * Wrapper for the element that triggers the hover card.
+ * Requires a single child element that supports ref forwarding.
+ */
+export type HoverCardTargetProps = MantineHoverCardTargetProps;
+
+const HoverCardTarget = function HoverCardTarget(props: HoverCardTargetProps) {
+  return <MantineHoverCard.Target {...props} />;
+};
+HoverCardTarget.displayName = "HoverCardTarget";
+
+// ============================================================
+// HOVERCARD DROPDOWN
+// ============================================================
+
+/** The dropdown panel displayed when hovering over the target. */
+export type HoverCardDropdownProps =
+  RecursicaOverStyled<MantineHoverCardDropdownProps>;
+
+const HoverCardDropdown = function HoverCardDropdown({
+  overStyled = false,
+  ...rest
+}: HoverCardDropdownProps) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const classNameProp = (sanitizedProps as Record<string, unknown>)
+    .className as string | undefined;
+
+  return (
+    <MantineHoverCard.Dropdown
+      {...(sanitizedProps as unknown as MantineHoverCardDropdownProps)}
+      className={classNameProp}
+    />
+  );
+};
+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,52 @@
+# HoverCard - Usage Guide
+
+This document describes how to integrate and use the `HoverCard` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { HoverCard } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { HoverCard } from "@recursica/adapter-mantine-v8";
+
+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-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. Notes
+
+- Mantine calls the pointer indicator the "arrow"; Recursica calls it the "beak". Use the `withBeak` prop (default `true`) to show or hide it; `withArrow` is also accepted for compatibility, with `withBeak` taking precedence.
+- The default `position` is `"top"` (Mantine's default is `"bottom"`); pass your own `position` prop to override it.

package/src/components/Label/LABEL_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,48 @@
+# Label Implementation Notes
+
+## Architecture Overview
+
+The `Label` component is fundamentally built as a strict, localized wrapper around Mantine's native `Input.Label`. The core goal is to preserve context, ref-forwarding, and native accessibility links, while completely overriding visual behaviors via Recursica design variables in scoped CSS.
+
+## Key Design Decisions
+
+### **Layout Architecture**
+
+- Because Recursica dictates complex alignments between primary label text, asterisks, edit icons, and optional strings, Mantine's rigid form label flow could not be used out-of-the-box.
+- Implemented `display: flex; flex-wrap: wrap;` directly on `.root`.
+- Injected strict integer-based flex `order` properties (e.g. `order: 1` for text, `order: 2` for `required`, `order: 5` for `optionalText`) to physically decouple DOM rendering from markup flow.
+- Because `optionalText` often acts as secondary contextual detail, it forces `flex-basis: 100%`, securely wrapping to a secondary line underneath the primary label properties and transforming the horizontal gap spacing seamlessly into a `margin-top` vector.
+
+### **Optional Text & Required Mutually Exclusive Parsing**
+
+- By design standards, a component cannot logically be both "Required" and mapped as "Optional".
+- To bulletproof implementations natively, the adapter forcibly suppresses rendering of the `resolvedOptionalText` strings if the parent wrapper invokes `required={true}`.
+- `optionalText` can operate as dynamic data or specifically as a boolean `true`, which forces the adapter to natively render the formal `(Optional)` string map.
+
+### **The "Edit Icon" Replacer Logic**
+
+- Passing `withEditIcon={true}` evaluates it as fundamentally mutually exclusive to the standard required indicator asterisk.
+- `required={required && !withEditIcon}` is passed to the underlying Mantine structure so the native `*` is entirely suppressed.
+- Added localized styling via `data-replaces-asterisk={required ? "true" : undefined}` onto the `.editIconWrapper` element. If an editable instance is simultaneously designated as required, the edit icon functionally assumes the indicator role natively, overriding its default icon metrics explicitly to match `--recursica_ui-kit_components_label_properties_colors_asterisk`.
+
+### **Bypassing `Input.Wrapper` Integrations**
+
+- By decoupling from Mantine's standard `Input.Wrapper`, the `Label` component is exclusively mapped manually through `FormControlWrapper`. This grants us exact visual sync regarding where the label renders based on `formLayout="stacked"` or `formLayout="side-by-side"`, without fighting internal Mantine positional hooks that assume vertical stacking by default.
+
+### **Label Size Container Constraints**
+
+- The `labelSize` parameter (mapping values like `"small"`) internally **does not scale typographic font metrics**. Instead, it dynamically defines the explicit horizontal bounding width limit of the block container itself.
+- **Architectural Rule:** `labelSize` modifications are strictly designed to execute exclusively when `formLayout="side-by-side"` is active. It acts as an optical grid threshold ensuring left-aligned string wrappers constrain correctly uniformly down a column without bleeding into the physical input arrays alongside them.
+
+## Outstanding Technical Debt / Issues
+
+### **Description Property Omission**
+
+- **Issue:** Currently, the adapter `Label` does not natively parse or support a structured `description` node directly attached beneath it.
+- **Context:** Standard forms often attach subtext beneath inputs, but mapping a description purely within the `<Label>` (distinct from an overall form-control description) is omitted structurally until subsequent UI Kit requirements mandate dedicated `description` styles locally on the label component itself.
+
+### **Global Interactive Hover Mappings**
+
+- **Issue:** Currently, the `editIconWrapper` lacks a dedicated hover background layer.
+- **Context:** While the global theme abstracts interactive hover environments deeply using layered variable syntax (e.g., `--recursica_brand_layer_1_elements_interactive_hover-color`), Recursica's token generation framework natively fails to expose a universally generic placeholder token (e.g., `--recursica_elements_interactive_hover-color`) which downstream wrappers can map their `<Layer>` injections directly into safely.
+- **Resolution Path:** We are explicitly ignoring the `.editIconWrapper:hover` background color assignment until the raw Figma token exports directly scaffold a generic token placeholder that we can interface cleanly with across arbitrary `<Layer>` contexts, avoiding manually mapping statically hardcoded depths (`layer-0`, `layer-1`).

package/src/components/Label/Label.module.css

@@ -0,0 +1,141 @@
+/* HARDCODED VALUES:
+   - display: flex helps us leverage flex 'order' to perfectly position Mantine's injected asterisk.
+   - align-items: baseline ensures text logic lines up nicely if font sizes differ slightly.
+   - margin/padding resets.
+ */
+
+.root {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+  box-sizing: border-box;
+  margin: 0;
+  color: var(--recursica_ui-kit_components_label_properties_colors_text-color);
+}
+
+.root[data-alignment="left"] {
+  justify-content: flex-start;
+  text-align: left;
+}
+
+.root[data-alignment="right"] {
+  justify-content: flex-end;
+  text-align: right;
+}
+
+.labelText {
+  order: 1;
+  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-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
+  );
+  font-style: var(
+    --recursica_ui-kit_components_label_properties_label-text_font-style
+  );
+  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
+  );
+}
+
+.required {
+  order: 2;
+  margin-left: var(
+    --recursica_ui-kit_components_label_properties_required-indicator-gap
+  );
+  color: var(
+    --recursica_ui-kit_components_label_properties_colors_asterisk-color
+  );
+
+  /* Inherit identical typography bounds to prevent flex row line-height stretching */
+  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
+  );
+  line-height: var(
+    --recursica_ui-kit_components_label_properties_label-text_line-height
+  );
+}
+
+.optionalText {
+  order: 5;
+  flex-basis: 100%;
+  margin-top: var(
+    --recursica_ui-kit_components_label_properties_label-optional-text-gap
+  );
+  margin-left: 0;
+  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-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
+  );
+  font-style: var(
+    --recursica_ui-kit_components_label_properties_optional-text_font-style
+  );
+  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
+  );
+  color: inherit;
+  opacity: var(
+    --recursica_ui-kit_components_label_properties_optional-text-opacity
+  );
+}
+
+.actionAreaWrapper {
+  order: 4;
+  margin-left: var(
+    --recursica_ui-kit_components_label_properties_edit-icon-gap
+  );
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.editIconWrapper {
+  order: 4;
+  margin-left: var(
+    --recursica_ui-kit_components_label_properties_edit-icon-gap
+  );
+  background: none;
+  border: none;
+  padding: 0;
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: inherit;
+}
+
+.editIconWrapper[data-replaces-asterisk="true"] {
+  color: var(
+    --recursica_ui-kit_components_label_properties_colors_asterisk-color
+  );
+}

package/src/components/Label/Label.stories.tsx

@@ -0,0 +1,131 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Label } from "./Label";
+import { Button } from "../Button/Button";
+
+type LabelStoryProps = React.ComponentProps<typeof Label>;
+
+const meta: Meta<LabelStoryProps> = {
+  title: "UI-Kit/Label",
+  component: Label,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The `Label` component is a strict Recursica-styled wrapper around Mantine's native `Input.Label`. It serves as the primary compositional primitive for all form fields, preserving Mantine's accessibility associations and context while strictly enforcing the Recursica atomic design system.\n\n### Usage with Form Inputs\nThis component only renders the label itself — layout concerns like `stacked` vs `side-by-side` positioning relative to an input live on `FormControlLayout`/`FormControlWrapper`, not here. Render this `Label` in isolation to verify its own states, or see `UI-Kit/FormControlLayout` for how it composes into a full form field.",
+      },
+    },
+  },
+  argTypes: {
+    labelSize: {
+      control: "inline-radio",
+      options: ["default", "small"],
+      description:
+        "Sizing metrics for the Label. Only visually distinguishable once composed inside a `side-by-side` FormControlLayout, which is where the resulting width constraint applies.",
+    },
+    labelAlignment: {
+      control: "inline-radio",
+      options: ["left", "right"],
+      description: "Text alignment of the label content.",
+    },
+    required: {
+      control: "boolean",
+      description:
+        "Renders the required asterisk (suppressed automatically when `labelWithEditIcon` is set, and mutually exclusive with `labelOptionalText`).",
+    },
+    labelOptionalText: {
+      control: "text",
+      description:
+        "Secondary text rendered beneath the label. Pass `true` for the default '(Optional)' string, or a custom node/string. Suppressed when `required` is true.",
+    },
+    labelWithEditIcon: {
+      control: "boolean",
+      description:
+        "Replaces the default edit icon slot with an interactive edit affordance; replaces the required asterisk visually when both are set.",
+    },
+    labelActionArea: {
+      table: { disable: true },
+    },
+    onLabelEditClick: {
+      table: { disable: true },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<LabelStoryProps>;
+
+export const Default: Story = {
+  args: {
+    children: "Label",
+    labelSize: "default",
+    labelAlignment: "left",
+    required: false,
+    labelOptionalText: "",
+    labelWithEditIcon: false,
+  },
+};
+
+export const Required: Story = {
+  args: {
+    children: "Required Field",
+    required: true,
+  },
+};
+
+export const RequiredSuppressesOptionalText: Story = {
+  args: {
+    children: "Full Name",
+    required: true,
+    labelOptionalText: "This should not render",
+  },
+};
+
+export const WithOptionalText: Story = {
+  args: {
+    children: "Bio",
+    labelOptionalText: "Max 100 characters",
+  },
+};
+
+export const BooleanOptionalText: Story = {
+  args: {
+    children: "Middle Initial",
+    labelOptionalText: true,
+  },
+};
+
+export const WithEditIcon: Story = {
+  args: {
+    children: "Shipping Address",
+    labelWithEditIcon: true,
+  },
+};
+
+export const RequiredWithEditIcon: Story = {
+  args: {
+    children: "Primary Network Node",
+    required: true,
+    labelWithEditIcon: true,
+  },
+};
+
+export const RightAligned: Story = {
+  args: {
+    children: "Status",
+    labelAlignment: "right",
+  },
+};
+
+export const WithActionArea: Story = {
+  args: {
+    children: "Configuration",
+    labelActionArea: (
+      <Button variant="text" size="small">
+        Edit
+      </Button>
+    ),
+  },
+};

package/src/components/Label/Label.test.tsx

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