@recursica/mui-adapter 0.4.0 → 0.6.0

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

@@ -0,0 +1,136 @@
+.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,7 +1,91 @@
 import React from "react";
+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";

package/src/components/Link/Link.module.css

@@ -131,3 +131,11 @@ HARDCODED VALUES:
   /* HARDCODE: allows text truncation if bounded */
   min-width: 0;
 }
+
+/* EXEMPTIONS:
+   text_text-transform across multiple link states (default, hover, visited, visited-hover) is ignored
+   because links naturally inherit casing directly from text children rather than requiring custom CSS transforms. */
+/* recursica-ignore: --recursica_ui-kit_components_link_variants_states_default_properties_text_text-transform */
+/* recursica-ignore: --recursica_ui-kit_components_link_variants_states_hover_properties_text_text-transform */
+/* recursica-ignore: --recursica_ui-kit_components_link_variants_states_visited_properties_text_text-transform */
+/* recursica-ignore: --recursica_ui-kit_components_link_variants_states_visited-hover_properties_text_text-transform */

package/src/components/Menu/Menu.module.css

@@ -0,0 +1,287 @@
+/* EXEMPTIONS:
+   - colors_selected-item_supporting-text-color is ignored because selected menu items do not render 
+     supporting secondary text, making selected state overrides for supporting text colors obsolete. */
+/* recursica-ignore: --recursica_ui-kit_components_menu-item_properties_colors_selected-item_supporting-text-color */
+
+/* HARDCODED VALUES:
+   - border-style: solid. Structural rendering rule for the dropdown border (Mantine uses Paper which may not set border natively).
+   - opacity: 0.5 on disabled items. Recursica has no dedicated disabled-opacity token for menu items.
+   - NOTE: overflow is intentionally NOT set on .dropdown. Mantine renders sub-menu dropdowns
+     inside the parent dropdown DOM tree using Floating UI absolute positioning. Setting
+     overflow: hidden clips sub-menus; overflow-y: auto causes unwanted scrollbars.
+   - All structural layout (flex, cursor, pointer-events on disabled) is deferred to Mantine's
+     native behavior. We only override visual design tokens (colors, typography, spacing, borders).
+*/
+
+/* ======================================
+   DROPDOWN CONTAINER
+   ====================================== */
+
+.dropdown {
+  background-color: var(
+    --recursica_ui-kit_components_menu_properties_colors_background
+  );
+  border-style: solid; /* HARDCODE: Mantine Paper does not set border-style natively */
+  border-width: var(--recursica_ui-kit_components_menu_properties_border-size);
+  border-color: var(
+    --recursica_ui-kit_components_menu_properties_colors_border-color
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_menu_properties_border-radius
+  );
+  box-shadow: var(--recursica_ui-kit_components_menu_properties_elevation);
+
+  min-width: var(--recursica_ui-kit_components_menu_properties_min-width);
+  max-height: var(--recursica_ui-kit_components_menu_properties_max-height);
+  max-width: var(--recursica_ui-kit_components_menu_properties_max-width);
+
+  /* HARDCODE: Figma UI Kit does not export padding tokens for the Menu container itself. 
+     If added in the future, it would be mapped here. */
+  padding: 8px;
+}
+
+/* ======================================
+   MENU ITEM
+   ====================================== */
+
+.item {
+  position: relative;
+
+  /* Geometry */
+  padding: var(
+      --recursica_ui-kit_components_menu-item_properties_vertical-padding
+    )
+    var(--recursica_ui-kit_components_menu-item_properties_horizontal-padding);
+  border-radius: var(
+    --recursica_ui-kit_components_menu-item_properties_border-radius
+  );
+
+  /* Typography */
+  font-family: var(
+    --recursica_ui-kit_components_menu-item_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_menu-item_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_menu-item_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_menu-item_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_menu-item_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_menu-item_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_menu-item_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_menu-item_properties_text_text-transform
+  );
+
+  /* Default State: Unselected */
+  background-color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_background
+  );
+  color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_text
+  );
+  opacity: 1;
+}
+
+/* Override Mantine's native hover background to use our overlay technique */
+.item:hover {
+  background-color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_background
+  );
+}
+
+/* Hover overlay using ::after pseudo-element (same technique as Accordion) */
+.item::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  z-index: 0;
+  pointer-events: none;
+  background-color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_hover-color
+  );
+  opacity: 0;
+  transition: opacity 150ms ease;
+}
+
+.item:hover:not([data-disabled])::after {
+  opacity: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_hover-opacity
+  );
+}
+
+/* Selected item state */
+.item[data-selected] {
+  background-color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_selected-item_background
+  );
+  color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_selected-item_text
+  );
+  opacity: 1;
+}
+
+.item[data-selected]::after {
+  background-color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_selected-item_hover-color
+  );
+}
+
+/* Hovered item state (keyboard navigation) */
+.item[data-hovered] {
+  background-color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_background
+  );
+}
+.item[data-hovered]::after {
+  opacity: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_hover-opacity
+  );
+}
+
+.item[data-hovered][data-selected]::after {
+  opacity: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_selected-item_hover-opacity
+  );
+}
+
+/* Disabled item */
+.item[data-disabled] {
+  opacity: var(
+    --recursica_ui-kit_components_menu-item_properties_disabled-opacity
+  );
+}
+
+/* ======================================
+   ITEM LABEL
+   ====================================== */
+
+.itemLabel {
+  position: relative;
+  z-index: 1;
+  color: inherit;
+}
+
+/* ======================================
+   ITEM SECTION (LEFT / RIGHT ICONS)
+   ====================================== */
+
+.itemSection {
+  position: relative;
+  z-index: 1;
+}
+
+.itemSection[data-position="left"] {
+  width: var(
+    --recursica_ui-kit_components_menu-item_properties_icon-leading-size
+  );
+  height: var(
+    --recursica_ui-kit_components_menu-item_properties_icon-leading-size
+  );
+  margin-right: var(
+    --recursica_ui-kit_components_menu-item_properties_icon-text-gap
+  );
+  color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_leading-icon-color
+  );
+}
+
+.itemSection[data-position="right"] {
+  width: var(
+    --recursica_ui-kit_components_menu-item_properties_icon-trailing-size
+  );
+  height: var(
+    --recursica_ui-kit_components_menu-item_properties_icon-trailing-size
+  );
+  margin-left: var(--recursica_ui-kit_components_menu-item_properties_text-gap);
+  color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_trailing-icon-color
+  );
+}
+
+.item[data-selected] .itemSection[data-position="left"] {
+  color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_selected-item_leading-icon-color
+  );
+}
+
+.item[data-selected] .itemSection[data-position="right"] {
+  color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_selected-item_trailing-icon-color
+  );
+}
+
+/* ======================================
+   DIVIDER
+   ====================================== */
+
+.divider {
+  height: var(--recursica_ui-kit_components_menu_properties_divider-height);
+  background-color: var(
+    --recursica_ui-kit_components_menu_properties_colors_divider-color
+  );
+  opacity: var(--recursica_ui-kit_components_menu_properties_divider-opacity);
+  margin: 8px 0;
+}
+
+/* ======================================
+   SECTION LABEL
+   ====================================== */
+
+.label {
+  padding: var(
+      --recursica_ui-kit_components_menu-item_properties_vertical-padding
+    )
+    var(--recursica_ui-kit_components_menu-item_properties_horizontal-padding);
+
+  /* Supporting Text Typography */
+  font-family: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_text-transform
+  );
+
+  color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_supporting-text-color
+  );
+  opacity: 0.7;
+}
+
+/* ======================================
+   SUB-MENU CHEVRON
+   ====================================== */
+
+.chevron {
+  position: relative;
+  z-index: 1;
+  color: inherit;
+}