@recursica/mui-adapter 0.5.0 → 0.6.0

package/src/components/FormControlWrapper/FormControlWrapper.stories.tsx

@@ -1,35 +1,138 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import React from "react";
 import type { Meta, StoryObj } from "@storybook/react";
-import { FormControlWrapper } from "./FormControlWrapper";
-import { ComingSoon } from "@recursica/storybook-template";
+import {
+  FormControlWrapper,
+  type FormControlWrapperProps,
+} from "./FormControlWrapper";
+import { TextField } from "../TextField/TextField";
+import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
 
-const meta: Meta<typeof FormControlWrapper> = {
-  title: "UI-Kit/🚧 FormControlWrapper",
+type WrapperStoryProps = FormControlWrapperProps;
+
+const meta: Meta<WrapperStoryProps> = {
+  title: "UI-Kit/FormControlWrapper",
   component: FormControlWrapper,
   tags: ["autodocs"],
   parameters: {
+    docs: {
+      description: {
+        component:
+          "The `FormControlWrapper` is the ultimate structural replacement for built-in wrapper layouts. By centralizing label tracking, error rendering, ARIA generation, and grid layouts natively inside this single component, we achieve pixel-perfect layout compliance while retaining MUI's internal `useFormControl` Context natively.\n\n### Usage with Naked Primitives\nThis component wraps 'naked' elements directly. The demonstration stories below utilize `<TextField>` as a native display vehicle, since `<TextField>` natively pipes all its properties structurally back into this wrapper.",
+      },
+    },
     controls: {
       include: [
-        "layer",
-        "withLayer",
-        "children",
-        "component",
-        "variant",
-        "size",
-        "icon",
-        "disabled",
-        "href",
-        "onClick",
-        "onChange",
-        "value",
-        "checked",
+        "error",
+        "assistiveText",
+        "assistiveWithIcon",
+        "required",
+        "formLayout",
+        "labelSize",
+        "labelAlignment",
+        "labelOptionalText",
+        "labelWithEditIcon",
+        "labelActionArea",
       ],
     },
   },
+  argTypes: {
+    ...formControlArgTypes,
+    error: {
+      control: "text",
+      description:
+        "Error string driving native assistive component and validation markers.",
+    },
+    assistiveText: {
+      control: "text",
+      description:
+        "Helper instructions safely dynamically anchored below the input box.",
+    },
+    assistiveWithIcon: {
+      control: "boolean",
+    },
+    required: {
+      control: "boolean",
+    },
+  },
 };
 
 export default meta;
-type Story = StoryObj<typeof FormControlWrapper>;
+
+type Story = StoryObj<WrapperStoryProps>;
+
+const renderWithTextField = ({ ...args }: any) => (
+  // We explicitly cast args to 'any' here because MUI wrapper defines Wrapper anatomy,
+  // but TextField expects them for the full TextInput anatomy, causing a TS intersection mismatch.
+  <TextField placeholder="Form Control primitive mapped..." {...args} />
+);
 
 export const Default: Story = {
-  render: () => <ComingSoon componentName="FormControlWrapper" />,
+  args: {
+    label: "Account Username",
+    formLayout: "stacked",
+    assistiveText: "Validation occurs immediately natively.",
+  },
+  render: renderWithTextField,
+};
+
+export const VisualErrorState: Story = {
+  args: {
+    label: "Encryption Protocol",
+    formLayout: "stacked",
+    error: "Strict validation limits reached. Handshake rejected securely.",
+  },
+  render: renderWithTextField,
+};
+
+export const RequiredArchitecture: Story = {
+  args: {
+    label: "Root Password",
+    formLayout: "side-by-side",
+    required: true,
+    assistiveText: "Bypass string structure required to initiate protocol.",
+  },
+  render: renderWithTextField,
+};
+
+export const WithoutAssistiveIcons: Story = {
+  args: {
+    label: "Server Domain",
+    assistiveText:
+      "A standard text boundary without default native icon parameters bounding.",
+    assistiveWithIcon: false,
+  },
+  render: renderWithTextField,
+};
+
+export const NativeChildrenDirectly: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Bypassing the TextField map to show exactly how native `<input>` hooks execute inside the raw wrapper natively perfectly.",
+      },
+    },
+  },
+  args: {
+    label: "Raw HTML Checkbox",
+    formLayout: "side-by-side",
+    assistiveText: "This wraps a raw HTML input tag mapping correctly.",
+  },
+  render: ({ ...args }: any) => (
+    <div
+      style={{
+        display: "flex",
+        gap: "10px",
+        alignItems: "center",
+      }}
+    >
+      <FormControlWrapper {...args}>
+        <input
+          type="checkbox"
+          style={{ margin: 0, width: "16px", height: "16px" }}
+        />
+      </FormControlWrapper>
+    </div>
+  ),
 };

package/src/components/FormControlWrapper/FormControlWrapper.tsx

@@ -1,9 +1,148 @@
 import React from "react";
+import { FormControl, type FormControlProps } from "@mui/material";
+import { filterStylingProps } from "../../utils/filterStylingProps";
+import { Label } from "../Label/Label";
+import { AssistiveElement } from "../AssistiveElement/AssistiveElement";
+import { FormControlLayout } from "../FormControlLayout/FormControlLayout";
+import styles from "./FormControlWrapper.module.css";
 
-export type FormControlWrapperProps = React.HTMLAttributes<HTMLDivElement>;
+export interface RecursicaFormControlWrapperProps
+  extends Omit<FormControlProps, "margin" | "variant" | "size" | "color"> {
+  overStyled?: boolean;
+  label?: React.ReactNode;
+  /** Primary assistive description bound natively to the component footer. Maps to MUI's 'helperText' dynamically. */
+  assistiveText?: React.ReactNode;
+  /** Secondary parameter fallback identical to assistiveText to match MUI / Mantine native APIs safely. */
+  description?: React.ReactNode;
+  /** Fallback mapping for MUI's native helperText */
+  helperText?: React.ReactNode;
+  assistiveWithIcon?: boolean;
 
-export const FormControlWrapper: React.FC<FormControlWrapperProps> = (
-  props,
-) => {
-  return <div {...props}>FormControlWrapper</div>;
-};
+  formLayout?: "stacked" | "side-by-side";
+  labelSize?: "small" | "default" | "md";
+  labelAlignment?: "left" | "right"; // Currently functionally maps to left automatically natively
+  labelOptionalText?: React.ReactNode | true;
+  labelWithEditIcon?: boolean;
+  onLabelEditClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
+  labelActionArea?: React.ReactNode;
+
+  /** Allows layout mapping to limit the input's bounding box without impacting the label */
+  controlMaxWidth?: string;
+  controlMinWidth?: string;
+}
+
+export type FormControlWrapperProps = RecursicaFormControlWrapperProps;
+
+export const FormControlWrapper = React.forwardRef<
+  HTMLDivElement,
+  FormControlWrapperProps
+>(function FormControlWrapper(props, ref) {
+  const {
+    overStyled = false,
+    label,
+    assistiveText,
+    description,
+    helperText,
+    assistiveWithIcon = true,
+    error,
+    required,
+    disabled,
+    focused,
+    id,
+
+    formLayout = "stacked",
+    labelSize = "default",
+    labelOptionalText,
+    labelWithEditIcon,
+    onLabelEditClick,
+    labelActionArea,
+
+    controlMaxWidth,
+    controlMinWidth,
+
+    className,
+    style,
+    children,
+    ...rest
+  } = props;
+
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+
+  // Map descriptions fallback exactly like Mantine
+  const finalAssistiveText = assistiveText || description || helperText;
+
+  // ARIA Bindings
+  const labelId = id ? `${id}-label` : undefined;
+  const descriptionId = id ? `${id}-description` : undefined;
+
+  // Wrap children safely cloning aria hooks down natively
+  const mappedChildren = React.Children.map(children, (child) => {
+    if (React.isValidElement(child)) {
+      return React.cloneElement(child, {
+        "aria-labelledby": labelId,
+        "aria-describedby": finalAssistiveText ? descriptionId : undefined,
+      } as React.HTMLAttributes<HTMLElement>);
+    }
+    return child;
+  });
+
+  return (
+    <FormControl
+      ref={ref}
+      error={!!error}
+      required={required}
+      disabled={disabled}
+      focused={focused}
+      className={className ? `${styles.root} ${className}` : styles.root}
+      style={style}
+      {...(sanitizedProps as FormControlProps)}
+    >
+      <FormControlLayout
+        formLayout={formLayout}
+        labelSize={labelSize}
+        leftSection={
+          label && (
+            <Label
+              id={labelId}
+              htmlFor={id}
+              required={required}
+              labelOptionalText={labelOptionalText}
+              labelWithEditIcon={labelWithEditIcon}
+              onLabelEditClick={onLabelEditClick}
+              labelActionArea={labelActionArea}
+            >
+              {label}
+            </Label>
+          )
+        }
+      >
+        <div
+          className={styles.inputContainer}
+          style={
+            {
+              "--form-control-max-width": controlMaxWidth,
+              "--form-control-min-width": controlMinWidth,
+            } as React.CSSProperties
+          }
+        >
+          {/* Natively wrap children into flex box */}
+          {mappedChildren}
+
+          {/* Append native assistive block dynamically below the input */}
+          {(finalAssistiveText || error) && (
+            <AssistiveElement
+              id={descriptionId}
+              assistiveVariant={error ? "error" : "help"}
+              assistiveWithIcon={assistiveWithIcon}
+              className={styles.assistive}
+            >
+              {error && typeof error === "string" ? error : finalAssistiveText}
+            </AssistiveElement>
+          )}
+        </div>
+      </FormControlLayout>
+    </FormControl>
+  );
+});
+
+FormControlWrapper.displayName = "FormControlWrapper";

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>
+    );
+  },
 };