@recursica/mui-adapter 0.2.0 → 0.4.0

package/src/components/Flex/Flex.tsx

@@ -1,7 +1,79 @@
-import React from "react";
+/**
+ * Flex layout wrapper.
+ *
+ * NOTE: MUI does not have a native `<Flex>` component (it relies on `<Box display="flex">`
+ * or `<Stack>`). To maintain API parity with the mantine-adapter and provide a consistent
+ * developer experience, this component wraps MUI's Box and forces `display="flex"`.
+ *
+ * Like Stack and Group, this is a primitive layout component. It strictly filters out the
+ * `sx` prop using `OmitSx` and `filterSxProp` to enforce the use of standard layout scales.
+ */
+import React, { forwardRef } from "react";
+import { Box as MUIBox, type BoxProps as MUIBoxProps } from "@mui/material";
+import {
+  type RecursicaSpacing,
+  SPACING_MAP,
+  type OmitSx,
+  filterSxProp,
+} from "../../utils/filterStylingProps";
 
-export type FlexProps = React.HTMLAttributes<HTMLDivElement>;
+export interface RecursicaFlexProps {
+  /**
+   * Content to render inside the flex container.
+   */
+  children?: React.ReactNode;
 
-export const Flex: React.FC<FlexProps> = (props) => {
-  return <div {...props}>Flex</div>;
-};
+  /**
+   * The gap between flex items. Accepts standard MUI spacing or Recursica gap tokens
+   * (e.g. "rec-md").
+   */
+  gap?: string | number | RecursicaSpacing;
+
+  /**
+   * The vertical gap between flex items when wrapping. Accepts standard MUI spacing
+   * or Recursica gap tokens.
+   */
+  rowGap?: string | number | RecursicaSpacing;
+
+  /**
+   * The horizontal gap between flex items when wrapping. Accepts standard MUI spacing
+   * or Recursica gap tokens.
+   */
+  columnGap?: string | number | RecursicaSpacing;
+}
+
+export type FlexProps = OmitSx<MUIBoxProps & RecursicaFlexProps>;
+
+export const Flex = forwardRef<HTMLDivElement, FlexProps>(function Flex(
+  { children, gap = "rec-default", rowGap, columnGap, ...rest },
+  ref,
+) {
+  const safeProps = filterSxProp(rest as Record<string, unknown>);
+  const resolvedGap =
+    typeof gap === "string" && gap in SPACING_MAP
+      ? SPACING_MAP[gap as keyof typeof SPACING_MAP]
+      : gap;
+  const resolvedRowGap =
+    typeof rowGap === "string" && rowGap in SPACING_MAP
+      ? SPACING_MAP[rowGap as keyof typeof SPACING_MAP]
+      : rowGap;
+  const resolvedColumnGap =
+    typeof columnGap === "string" && columnGap in SPACING_MAP
+      ? SPACING_MAP[columnGap as keyof typeof SPACING_MAP]
+      : columnGap;
+
+  return (
+    <MUIBox
+      ref={ref}
+      display="flex"
+      {...safeProps}
+      gap={resolvedGap}
+      rowGap={resolvedRowGap}
+      columnGap={resolvedColumnGap}
+    >
+      {children}
+    </MUIBox>
+  );
+});
+
+Flex.displayName = "Flex";

package/src/components/FormControlLayout/FormControlLayout.stories.tsx

@@ -6,6 +6,25 @@ const meta: Meta<typeof FormControlLayout> = {
   title: "UI-Kit/🚧 FormControlLayout",
   component: FormControlLayout,
   tags: ["autodocs"],
+  parameters: {
+    controls: {
+      include: [
+        "layer",
+        "withLayer",
+        "children",
+        "component",
+        "variant",
+        "size",
+        "icon",
+        "disabled",
+        "href",
+        "onClick",
+        "onChange",
+        "value",
+        "checked",
+      ],
+    },
+  },
 };
 
 export default meta;

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

@@ -6,6 +6,25 @@ const meta: Meta<typeof FormControlWrapper> = {
   title: "UI-Kit/🚧 FormControlWrapper",
   component: FormControlWrapper,
   tags: ["autodocs"],
+  parameters: {
+    controls: {
+      include: [
+        "layer",
+        "withLayer",
+        "children",
+        "component",
+        "variant",
+        "size",
+        "icon",
+        "disabled",
+        "href",
+        "onClick",
+        "onChange",
+        "value",
+        "checked",
+      ],
+    },
+  },
 };
 
 export default meta;

package/src/components/Group/Group.stories.tsx

@@ -1,16 +1,144 @@
+import React from "react";
 import type { Meta, StoryObj } from "@storybook/react";
 import { Group } from "./Group";
-import { ComingSoon } from "@recursica/storybook-template";
+import { Button } from "../Button";
+import { Text } from "../Text/Text";
 
-const meta: Meta<typeof Group> = {
-  title: "UI-Kit/🚧 Group",
+type GroupStoryProps = React.ComponentProps<typeof Group>;
+
+const meta: Meta<GroupStoryProps> = {
+  title: "UI-Kit/Group",
   component: Group,
   tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Group is a flex horizontal layout container that maps directly to Mantine's Group component allowing safe layout property passing.",
+      },
+    },
+    controls: {
+      include: [
+        "layer",
+        "withLayer",
+        "gap",
+        "alignItems",
+        "justifyContent",
+        "flexWrap",
+        "defaultChecked",
+        "rowGap",
+        "columnGap",
+        "children",
+        "component",
+        "variant",
+        "size",
+        "icon",
+        "disabled",
+        "href",
+        "onClick",
+        "onChange",
+        "value",
+        "checked",
+      ],
+    },
+  },
+  args: {
+    gap: "rec-default",
+    alignItems: "center",
+    justifyContent: "flex-start",
+    flexWrap: "wrap",
+  },
+  argTypes: {
+    gap: {
+      control: "select",
+      options: [
+        "rec-none",
+        "rec-sm",
+        "rec-default",
+        "rec-md",
+        "rec-lg",
+        "rec-xl",
+        "rec-2xl",
+        "xs",
+        "sm",
+        "md",
+        "lg",
+        "xl",
+      ],
+      description: "Gap between elements",
+    },
+    alignItems: {
+      control: "select",
+      options: ["flex-start", "center", "flex-end", "stretch"],
+      description: "Align-items property",
+    },
+    justifyContent: {
+      control: "select",
+      options: [
+        "flex-start",
+        "center",
+        "flex-end",
+        "space-between",
+        "space-around",
+      ],
+      description: "Justify-content property",
+    },
+    flexWrap: {
+      control: "select",
+      options: ["wrap", "nowrap", "wrap-reverse"],
+      description: "Flex-wrap property",
+    },
+    defaultChecked: {
+      table: { disable: true },
+    },
+    rowGap: {
+      table: { disable: true },
+    },
+    columnGap: {
+      table: { disable: true },
+    },
+  },
 };
 
 export default meta;
-type Story = StoryObj<typeof Group>;
+
+type Story = StoryObj<GroupStoryProps>;
 
 export const Default: Story = {
-  render: () => <ComingSoon componentName="Group" />,
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Group {...args}>
+      <Button variant="solid">Primary</Button>
+      <Button variant="outline">Secondary</Button>
+      <Text>Text element within Group</Text>
+    </Group>
+  ),
+};
+
+export const StaticGapSmall: Story = {
+  args: {
+    gap: "rec-sm",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Group {...args}>
+      <Button variant="solid">Item 1</Button>
+      <Button variant="solid">Item 2</Button>
+      <Button variant="solid">Item 3</Button>
+    </Group>
+  ),
+};
+
+export const StaticGapLarge: Story = {
+  args: {
+    gap: "rec-xl",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Group {...args}>
+      <Button variant="solid">Item 1</Button>
+      <Button variant="solid">Item 2</Button>
+      <Button variant="solid">Item 3</Button>
+    </Group>
+  ),
 };

package/src/components/Group/Group.tsx

@@ -1,7 +1,59 @@
-import React from "react";
+import React, { forwardRef } from "react";
+import {
+  Stack as MUIStack,
+  type StackProps as MUIStackProps,
+} from "@mui/material";
+import {
+  type RecursicaSpacing,
+  SPACING_MAP,
+  type OmitSx,
+  filterSxProp,
+} from "../../utils/filterStylingProps";
 
-export type GroupProps = React.HTMLAttributes<HTMLDivElement>;
+export interface RecursicaGroupProps {
+  children?: React.ReactNode;
+  gap?: MUIStackProps["spacing"] | RecursicaSpacing;
+  rowGap?: MUIStackProps["spacing"] | RecursicaSpacing;
+  columnGap?: MUIStackProps["spacing"] | RecursicaSpacing;
+}
 
-export const Group: React.FC<GroupProps> = (props) => {
-  return <div {...props}>Group</div>;
-};
+export type GroupProps = OmitSx<
+  Omit<MUIStackProps, "spacing" | "direction"> & RecursicaGroupProps
+>;
+
+export const Group = forwardRef<HTMLDivElement, GroupProps>(function Group(
+  { children, gap = "rec-default", rowGap, columnGap, ...rest },
+  ref,
+) {
+  const safeProps = filterSxProp(rest as Record<string, unknown>);
+  const resolvedGap =
+    typeof gap === "string" && gap in SPACING_MAP
+      ? SPACING_MAP[gap as keyof typeof SPACING_MAP]
+      : gap;
+  const resolvedRowGap =
+    typeof rowGap === "string" && rowGap in SPACING_MAP
+      ? SPACING_MAP[rowGap as keyof typeof SPACING_MAP]
+      : rowGap;
+  const resolvedColumnGap =
+    typeof columnGap === "string" && columnGap in SPACING_MAP
+      ? SPACING_MAP[columnGap as keyof typeof SPACING_MAP]
+      : columnGap;
+
+  return (
+    <MUIStack
+      ref={ref}
+      direction="row"
+      flexWrap="wrap"
+      spacing={resolvedGap}
+      sx={{
+        ...(resolvedRowGap ? { rowGap: resolvedRowGap } : {}),
+        ...(resolvedColumnGap ? { columnGap: resolvedColumnGap } : {}),
+      }}
+      {...safeProps}
+    >
+      {children}
+    </MUIStack>
+  );
+});
+
+Group.displayName = "Group";

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

@@ -6,6 +6,25 @@ const meta: Meta<typeof HoverCard> = {
   title: "UI-Kit/🚧 HoverCard",
   component: HoverCard,
   tags: ["autodocs"],
+  parameters: {
+    controls: {
+      include: [
+        "layer",
+        "withLayer",
+        "children",
+        "component",
+        "variant",
+        "size",
+        "icon",
+        "disabled",
+        "href",
+        "onClick",
+        "onChange",
+        "value",
+        "checked",
+      ],
+    },
+  },
 };
 
 export default meta;

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

@@ -6,6 +6,25 @@ const meta: Meta<typeof Label> = {
   title: "UI-Kit/🚧 Label",
   component: Label,
   tags: ["autodocs"],
+  parameters: {
+    controls: {
+      include: [
+        "layer",
+        "withLayer",
+        "children",
+        "component",
+        "variant",
+        "size",
+        "icon",
+        "disabled",
+        "href",
+        "onClick",
+        "onChange",
+        "value",
+        "checked",
+      ],
+    },
+  },
 };
 
 export default meta;

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

@@ -0,0 +1,133 @@
+/* 
+HARDCODED VALUES:
+- display: inline-flex; (Base layout to align icon and text correctly)
+- align-items: center;
+- cursor: pointer;
+- text-decoration: none; (Overridden by our design tokens instead of using Mantine's underline prop)
+- color: inherit; (Reset before applying token)
+*/
+
+.root {
+  /* HARDCODE: base layout to support optional icon gaps */
+  display: inline-flex;
+  align-items: center;
+  cursor: pointer;
+
+  /* HARDCODE: Reset underline and color so we can explicitly use our tokens */
+  text-decoration: none;
+  color: inherit;
+
+  /* Typography Default Tokens */
+  font-family: var(
+    --recursica_ui-kit_components_link_properties_text_font-family
+  );
+  font-size: var(--recursica_ui-kit_components_link_properties_text_font-size);
+  letter-spacing: var(
+    --recursica_ui-kit_components_link_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_link_properties_text_line-height
+  );
+
+  /* Default State Tokens */
+  font-style: var(
+    --recursica_ui-kit_components_link_variants_states_default_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_link_variants_states_default_properties_text_font-weight
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_link_variants_states_default_properties_text_text-decoration
+  );
+  color: var(
+    --recursica_ui-kit_components_link_variants_states_default_properties_colors_text
+  );
+}
+
+.root[data-has-icon] {
+  gap: var(--recursica_ui-kit_components_link_properties_icon-text-gap);
+}
+
+.root:hover {
+  /* Reset Mantine's potential hover override */
+  text-decoration: var(
+    --recursica_ui-kit_components_link_variants_states_hover_properties_text_text-decoration
+  );
+  font-style: var(
+    --recursica_ui-kit_components_link_variants_states_hover_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_link_variants_states_hover_properties_text_font-weight
+  );
+  color: var(
+    --recursica_ui-kit_components_link_variants_states_hover_properties_colors_text
+  );
+}
+
+.root:visited {
+  text-decoration: var(
+    --recursica_ui-kit_components_link_variants_states_visited_properties_text_text-decoration
+  );
+  font-style: var(
+    --recursica_ui-kit_components_link_variants_states_visited_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_link_variants_states_visited_properties_text_font-weight
+  );
+  color: var(
+    --recursica_ui-kit_components_link_variants_states_visited_properties_colors_text
+  );
+}
+
+.root:visited:hover {
+  text-decoration: var(
+    --recursica_ui-kit_components_link_variants_states_visited-hover_properties_text_text-decoration
+  );
+  font-style: var(
+    --recursica_ui-kit_components_link_variants_states_visited-hover_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_link_variants_states_visited-hover_properties_text_font-weight
+  );
+  color: var(
+    --recursica_ui-kit_components_link_variants_states_visited-hover_properties_colors_text
+  );
+}
+
+/* Icon Support */
+.iconWrapper {
+  /* HARDCODE: maintain intrinsic icon bounds */
+  display: flex;
+  align-items: center;
+  justify-content: center;
+
+  width: var(--recursica_ui-kit_components_link_properties_icon-size);
+  height: var(--recursica_ui-kit_components_link_properties_icon-size);
+  color: var(
+    --recursica_ui-kit_components_link_variants_states_default_properties_colors_icon
+  );
+}
+
+.root:hover .iconWrapper {
+  color: var(
+    --recursica_ui-kit_components_link_variants_states_hover_properties_colors_icon
+  );
+}
+
+.root:visited .iconWrapper {
+  color: var(
+    --recursica_ui-kit_components_link_variants_states_visited_properties_colors_icon
+  );
+}
+
+.root:visited:hover .iconWrapper {
+  color: var(
+    --recursica_ui-kit_components_link_variants_states_visited-hover_properties_colors_icon
+  );
+}
+
+/* Label text wrapper */
+.labelText {
+  /* HARDCODE: allows text truncation if bounded */
+  min-width: 0;
+}

package/src/components/Link/Link.stories.tsx

@@ -1,16 +1,64 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable @typescript-eslint/no-unused-vars */
 import type { Meta, StoryObj } from "@storybook/react";
 import { Link } from "./Link";
-import { ComingSoon } from "@recursica/storybook-template";
+import { Text } from "../Text/Text";
 
 const meta: Meta<typeof Link> = {
-  title: "UI-Kit/🚧 Link",
+  title: "UI-Kit/Link",
   component: Link,
   tags: ["autodocs"],
+  parameters: {
+    controls: {
+      include: ["children", "href", "icon", "component", "onClick"],
+    },
+  },
+  args: {
+    children: "Link text",
+    href: "#",
+  },
+  render: ({ withLayer, layer, ...args }: any) => <Link {...args} />,
 };
 
 export default meta;
+
 type Story = StoryObj<typeof Link>;
 
-export const Default: Story = {
-  render: () => <ComingSoon componentName="Link" />,
+export const Default: Story = {};
+
+export const WithIcon: Story = {
+  args: {
+    icon: (
+      <svg
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path>
+        <path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path>
+      </svg>
+    ),
+    children: "Link with Icon",
+  },
+};
+
+export const Polymorphic: Story = {
+  args: {
+    component: "button",
+    onClick: () => alert("Button clicked!"),
+    children: "Rendered as <button>",
+  },
+};
+
+export const InlineText: Story = {
+  render: () => (
+    <Text>
+      Here is some text with an <Link href="#">inline link</Link> inside it.
+    </Text>
+  ),
 };

package/src/components/Link/Link.tsx

@@ -1,7 +1,49 @@
-import React from "react";
+import React, { forwardRef } from "react";
+import { Link as MUILink, type LinkProps as MUILinkProps } from "@mui/material";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Link.module.css";
 
-export type LinkProps = React.HTMLAttributes<HTMLDivElement>;
+export interface RecursicaLinkProps {
+  icon?: React.ReactNode;
+  children?: React.ReactNode;
+  component?: React.ElementType;
+}
 
-export const Link: React.FC<LinkProps> = (props) => {
-  return <div {...props}>Link</div>;
-};
+export type LinkProps = RecursicaOverStyled<
+  Omit<MUILinkProps, "underline"> & RecursicaLinkProps
+>;
+
+export const Link = forwardRef<HTMLAnchorElement, LinkProps>(function Link(
+  { icon, children, overStyled = false, ...rest },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
+  const classNameProp = restRecord.className as string | undefined;
+  const finalClass = classNameProp
+    ? `${styles.root} ${classNameProp}`
+    : styles.root;
+
+  return (
+    <MUILink
+      ref={ref}
+      className={finalClass}
+      underline="none"
+      {...(icon ? { "data-has-icon": "" } : {})}
+      {...sanitizedProps}
+    >
+      {icon && (
+        <span className={styles.iconWrapper} aria-hidden>
+          {icon}
+        </span>
+      )}
+      <span className={styles.labelText}>{children}</span>
+    </MUILink>
+  );
+});
+
+Link.displayName = "Link";

package/src/components/Loader/LOADER_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,25 @@
+# Loader Implementation Notes
+
+## Architecture & Integration
+
+The `Loader` component for the MUI adapter has been completely hand-coded from scratch using pure CSS and basic HTML `<span>` elements. It explicitly **does not** use MUI's native `<CircularProgress>` component.
+
+This was a deliberate architectural decision to ensure 100% feature and visual parity with the `mantine-adapter`.
+
+### Key Decisions:
+
+- **Bypassing Native Components:** MUI's native loaders (like `<CircularProgress>`) are built using complex animated SVGs and only support a circular "oval" shape. Since the Recursica design system mandates `oval`, `bars`, and `dots` variants, relying on MUI's primitives would have forced a fragmented architecture where `oval` used MUI but `bars` and `dots` were hand-coded.
+- **Parity with Mantine:** To guarantee identical animation timing, easing curves, and DOM structures across frameworks, the CSS keyframes and layout strategies used internally by Mantine's `<Loader>` were extracted and directly replicated in this adapter's `Loader.module.css`.
+
+### Token Mapping:
+
+Sizes are bound through `data-size` attributes (`sm`, `md`, `lg` parsing to target `<div data-size="small">`, etc.).
+
+- **Oval Variant:** Uses a CSS spinning `::after` pseudo-element. To avoid CSS border inheritance bugs when computing tokenized border-widths, a custom `--loader-thickness` CSS variable is used to bridge the token into the spinning element.
+- **Bars & Dots Variants:** Render three internal `<span />` elements sequentially, styled via `Loader.module.css` to handle individual keyframe delays for bouncing or fading animations.
+
+### Color Contrast Rules:
+
+Loaders are hardcoded to map to their explicitly defined design tokens (e.g., `--recursica_ui-kit_components_loader_properties_indicator-color`). By default, they do **not** inherit `currentColor`.
+
+When injected into components like the `Button` (where contrast issues may arise against solid backgrounds), it is the responsibility of the parent component (e.g., `Button.module.css`) to use contextual CSS overrides to force `--loader-color: currentColor !important` if necessary.