@recursica/mui-adapter 0.5.0 → 0.6.0

package/src/components/HoverCard/HoverCard.tsx

@@ -1,8 +1,153 @@
-import React from "react";
-import "./HoverCard.module.css";
+import {
+  Popover as MuiHoverCard,
+  type PopoverProps as MuiHoverCardProps,
+} 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>;
+/**
+ * Recursica-specific props for HoverCard.
+ */
+export interface RecursicaHoverCardProps {
+  /**
+   * Whether to display a beak (arrow) pointing from the dropdown to the target.
+   * This is the Recursica equivalent of Mui's `withArrow`.
+   * When both `withBeak` and `withArrow` are provided, `withBeak` takes precedence.
+   */
+  withBeak?: boolean;
+}
+
+/**
+ * Recursica HoverCard component wrapping Mui'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<
+  MuiHoverCardProps & RecursicaHoverCardProps
+>;
+
+const HoverCardBase = function HoverCard({
+  overStyled = false,
+  withBeak = true,
+  ...rest
+}: HoverCardProps) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+
+  // Bind CSS module classes to Mui's internal classNames API
+  const mergedClassNames: Partial<Record<string, string>> = {
+    dropdown: 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];
+      }
+    });
+  }
+
+  // arrowSize must be a JS number prop — Mui 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).
+  const arrowSize =
+    ((sanitizedProps as Record<string, unknown>).arrowSize as
+      | number
+      | undefined) ?? 16;
+
+  // Resolve withBeak (Recursica) vs withArrow (Mui).
+  // withBeak takes precedence when both are provided.
+  const withArrow = (sanitizedProps as Record<string, unknown>).withArrow as
+    | boolean
+    | undefined;
+  const resolvedWithArrow = withBeak ?? withArrow;
+
+  return (
+    <MuiHoverCard
+      position="top" /* Recursica default; Mui defaults to "bottom" */
+      arrowSize={arrowSize}
+      withArrow={resolvedWithArrow}
+      classes={mergedClassNames}
+      {...(sanitizedProps as unknown as MuiHoverCardProps)}
+    />
+  );
+};
+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 = any;
+
+const HoverCardTarget = function HoverCardTarget(props: HoverCardTargetProps) {
+  return <div {...props} />;
+};
+HoverCardTarget.displayName = "HoverCardTarget";
+
+// ============================================================
+// HOVERCARD DROPDOWN
+// ============================================================
+
+/** The dropdown panel displayed when hovering over the target. */
+export type HoverCardDropdownProps = RecursicaOverStyled<any>;
+
+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 (
+    <div
+      className={classNameProp}
+      {...(sanitizedProps as unknown as MuiHoverCardDropdownProps)}
+    />
+  );
 };
+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,136 @@
-/* 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
+  );
+}
+
+/* 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;
+}

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

@@ -1,35 +1,116 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import React from "react";
 import type { Meta, StoryObj } from "@storybook/react";
 import { Label } from "./Label";
-import { ComingSoon } from "@recursica/storybook-template";
+import { TextField } from "../TextField/TextField";
+import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
 
-const meta: Meta<typeof Label> = {
-  title: "UI-Kit/🚧 Label",
+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 MUI's native `InputLabel`. It serves as the primary compositional primitive for all form fields, preserving MUI's accessibility associations and context while strictly enforcing the Recursica atomic design system.\n\n### Usage with Form Inputs\nWhen working with form structures, render this `Label` component directly above your inputs or supply it to a component's overriding properties. The component automatically maps structural layout dimensions, dynamic alignment (`left` vs `right`), custom indicator gaps, and integrates a customized `optionalText` and `withEditIcon` flow that safely bypasses MUI's native required asterisk mechanisms.",
+      },
+    },
     controls: {
       include: [
-        "layer",
-        "withLayer",
+        "labelSize",
+        "labelAlignment",
+        "required",
+        "labelOptionalText",
+        "labelWithEditIcon",
         "children",
-        "component",
-        "variant",
-        "size",
-        "icon",
-        "disabled",
-        "href",
-        "onClick",
-        "onChange",
-        "value",
-        "checked",
       ],
     },
   },
+  argTypes: {
+    ...formControlArgTypes,
+  },
 };
 
 export default meta;
-type Story = StoryObj<typeof Label>;
+
+type Story = StoryObj<LabelStoryProps>;
+
+// Utility mapping to pipe raw Label args structurally into TextField accurately
+const renderWithTextField = ({ children, ...args }: any) => (
+  <TextField
+    label={children as React.ReactNode}
+    placeholder="Form Control primitive mapped..."
+    {...(args as any)}
+  />
+);
 
 export const Default: Story = {
-  render: () => <ComingSoon componentName="Label" />,
+  args: {
+    children: "Dynamic Label (Controls)",
+    labelSize: "default",
+    labelAlignment: "left",
+    required: false,
+    labelOptionalText: "",
+    labelWithEditIcon: false,
+  },
+  render: renderWithTextField,
+};
+
+export const StackedDefault: Story = {
+  args: {
+    children: "Email Address",
+  },
+  render: renderWithTextField,
+};
+
+export const StackedRequired: Story = {
+  args: {
+    children: "Primary Network Node",
+    required: true,
+  },
+  render: renderWithTextField,
+};
+
+export const StackedWithEditIcon: Story = {
+  args: {
+    children: "Environment Variables",
+    labelWithEditIcon: true,
+  },
+  render: renderWithTextField,
+};
+
+export const SideBySideDefault: Story = {
+  args: {
+    children: "Status",
+    labelSize: "default",
+  },
+  render: renderWithTextField,
+};
+
+export const RequiredSuppressesOptionalText: Story = {
+  args: {
+    children: "Full Name",
+    required: true,
+    labelOptionalText: "This should not render",
+  },
+  render: renderWithTextField,
+};
+
+export const BooleanOptionalText: Story = {
+  args: {
+    children: "Middle Initial",
+    labelOptionalText: true,
+  },
+  render: renderWithTextField,
+};
+
+export const WithEditIcon: Story = {
+  args: {
+    children: "Shipping Address",
+    labelWithEditIcon: true,
+  },
+  render: renderWithTextField,
 };

package/src/components/Label/Label.tsx

@@ -1,8 +1,91 @@
 import React from "react";
-import "./Label.module.css";
+import { InputLabel, type InputLabelProps } from "@mui/material";
+import { filterStylingProps } from "../../utils/filterStylingProps";
+import styles from "./Label.module.css";
 
-export type LabelProps = React.HTMLAttributes<HTMLDivElement>;
+export interface LabelProps extends InputLabelProps {
+  overStyled?: boolean;
+  /** Explicit optional text to render safely mapping alongside the label. Hidden natively if 'required' is flagged true. */
+  labelOptionalText?: React.ReactNode | true;
+  /** Triggers the inline edit action icon native layout hook beside the label element. */
+  labelWithEditIcon?: boolean;
+  /** Fires specifically on icon click natively. */
+  onLabelEditClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
+  /** Replaces the right side optional text block natively with any custom React node (e.g. actions, toggles). */
+  labelActionArea?: React.ReactNode;
+}
 
-export const Label: React.FC<LabelProps> = (props) => {
-  return <div {...props}>Label</div>;
-};
+export const Label = React.forwardRef<HTMLLabelElement, LabelProps>(
+  function Label(props, ref) {
+    const {
+      overStyled = false,
+      required = false,
+      labelOptionalText = "",
+      labelWithEditIcon = false,
+      onLabelEditClick,
+      labelActionArea,
+      children,
+      className,
+      ...rest
+    } = props;
+
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+
+    const PenIcon = () => (
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <path d="M12 20h9"></path>
+        <path d="M16.5 3.5a2.121 2.121 0 0 1 3 3L7 19l-4 1 1-4L16.5 3.5z"></path>
+      </svg>
+    );
+
+    // Bypassing MUI's floating functionality by forcing shrink=true to static inline positioning.
+    return (
+      <InputLabel
+        ref={ref}
+        shrink={true}
+        className={className ? `${styles.root} ${className}` : styles.root}
+        {...(sanitizedProps as InputLabelProps)}
+      >
+        <div className={styles.innerLayout}>
+          <span className={styles.textWrapper}>
+            <span className={styles.text}>{children}</span>
+            {required && <span className={styles.required}> *</span>}
+          </span>
+
+          <div className={styles.endNodes}>
+            {labelActionArea && (
+              <span className={styles.actionArea}>{labelActionArea}</span>
+            )}
+            {!required && labelOptionalText && !labelActionArea && (
+              <span className={styles.optionalText}>
+                {labelOptionalText === true ? "Optional" : labelOptionalText}
+              </span>
+            )}
+            {labelWithEditIcon && (
+              <button
+                type="button"
+                className={styles.editIcon}
+                onClick={onLabelEditClick}
+                aria-label="Edit label"
+              >
+                <PenIcon />
+              </button>
+            )}
+          </div>
+        </div>
+      </InputLabel>
+    );
+  },
+);
+
+Label.displayName = "Label";