@recursica/mui-adapter 0.5.0 → 0.7.0

package/src/components/Toast/Toast.tsx

@@ -1,8 +1,127 @@
 import React from "react";
-import "./Toast.module.css";
+import {
+  Alert as MuiAlert,
+  AlertTitle as MuiAlertTitle,
+  IconButton as MuiIconButton,
+  type AlertProps as MuiAlertProps,
+} from "@mui/material";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Toast.module.css";
 
-export type ToastProps = React.HTMLAttributes<HTMLDivElement>;
+import { type RecursicaToastProps as BaseRecursicaToastProps } from "@recursica/adapter-common";
 
-export const Toast: React.FC<ToastProps> = (props) => {
-  return <div {...props}>Toast</div>;
-};
+export interface RecursicaToastProps extends BaseRecursicaToastProps {
+  withCloseButton?: boolean;
+  title?: React.ReactNode;
+  icon?: React.ReactNode;
+  onClose?: () => void;
+}
+
+/**
+ * Toast component wrapping Mui's Alert.
+ *
+ * Can be used as a standalone visual component to display a notification or message.
+ */
+export type ToastProps = RecursicaOverStyled<
+  Omit<MuiAlertProps, "color" | "radius" | "variant" | "onClose"> &
+    RecursicaToastProps
+>;
+
+const CloseIcon = () => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width="20"
+    height="20"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+  >
+    <path d="M18 6L6 18M6 6l12 12" />
+  </svg>
+);
+
+export const Toast = React.forwardRef<HTMLDivElement, ToastProps>(
+  function Toast(
+    {
+      overStyled = false,
+      variant = "default",
+      withCloseButton = true,
+      title,
+      icon,
+      children,
+      onClose,
+      className,
+      ...rest
+    },
+    ref,
+  ) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+
+    const mergedClassNames: Partial<Record<string, string>> = {
+      root: styles.root,
+      message: styles.body,
+      icon: styles.icon,
+      action: styles.closeButton,
+    };
+
+    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];
+        }
+      });
+    }
+
+    const handleClose = () => {
+      if (onClose) onClose();
+    };
+
+    return (
+      <MuiAlert
+        ref={ref}
+        icon={icon}
+        data-variant={variant}
+        className={`${className || ""}`}
+        classes={mergedClassNames}
+        action={
+          withCloseButton ? (
+            <MuiIconButton
+              size="small"
+              aria-label="close"
+              color="inherit"
+              onClick={handleClose}
+            >
+              <CloseIcon />
+            </MuiIconButton>
+          ) : undefined
+        }
+        {...(sanitizedProps as unknown as Omit<
+          MuiAlertProps,
+          "color" | "radius" | "variant" | "onClose"
+        >)}
+      >
+        {title && (
+          <MuiAlertTitle className={styles.title}>{title}</MuiAlertTitle>
+        )}
+        <div className={styles.description}>{children}</div>
+      </MuiAlert>
+    );
+  },
+);
+
+Toast.displayName = "Toast";

package/src/components/Tooltip/Tooltip.module.css

@@ -1,25 +1,90 @@
 /* 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_tooltip_properties_beak-inset */
-/* recursica-ignore: --recursica_ui-kit_components_tooltip_properties_beak-size */
-/* recursica-ignore: --recursica_ui-kit_components_tooltip_properties_border-radius */
-/* recursica-ignore: --recursica_ui-kit_components_tooltip_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_tooltip_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_tooltip_properties_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_tooltip_properties_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_tooltip_properties_elevation */
-/* recursica-ignore: --recursica_ui-kit_components_tooltip_properties_horizontal-padding */
-/* recursica-ignore: --recursica_ui-kit_components_tooltip_properties_max-width */
-/* recursica-ignore: --recursica_ui-kit_components_tooltip_properties_min-height */
-/* recursica-ignore: --recursica_ui-kit_components_tooltip_properties_min-width */
-/* recursica-ignore: --recursica_ui-kit_components_tooltip_properties_text_font-family */
-/* recursica-ignore: --recursica_ui-kit_components_tooltip_properties_text_font-size */
-/* recursica-ignore: --recursica_ui-kit_components_tooltip_properties_text_font-style */
-/* recursica-ignore: --recursica_ui-kit_components_tooltip_properties_text_font-weight */
-/* recursica-ignore: --recursica_ui-kit_components_tooltip_properties_text_letter-spacing */
-/* recursica-ignore: --recursica_ui-kit_components_tooltip_properties_text_line-height */
-/* recursica-ignore: --recursica_ui-kit_components_tooltip_properties_text_text-decoration */
-/* recursica-ignore: --recursica_ui-kit_components_tooltip_properties_text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_tooltip_properties_vertical-padding */
+   - beak-inset is ignored because Tooltip positioning calculations are handled dynamically by Mantine/Floating UI at the React runtime.
+   - beak-size is ignored because Mantine's tooltip 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_tooltip_properties_beak-inset = 8px */
+/* recursica-ignore: --recursica_ui-kit_components_tooltip_properties_beak-size = 16px */
+
+/* HARDCODED VALUES:
+   - border-style: solid. Structural rendering rule for the tooltip border (Mantine uses Box
+     which may not set border-style natively). Same pattern as Menu / HoverCard.
+   - arrowSize defaults to 16 in Tooltip.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).
+*/
+
+/* ======================================
+   TOOLTIP CONTAINER
+   ====================================== */
+
+.tooltip {
+  background-color: var(
+    --recursica_ui-kit_components_tooltip_properties_colors_background
+  );
+  border-style: solid; /* HARDCODE: Mantine Box does not set border-style natively */
+  border-width: var(
+    --recursica_ui-kit_components_tooltip_properties_border-size
+  );
+  border-color: var(
+    --recursica_ui-kit_components_tooltip_properties_colors_border-color
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_tooltip_properties_border-radius
+  );
+  box-shadow: var(--recursica_ui-kit_components_tooltip_properties_elevation);
+
+  min-width: var(--recursica_ui-kit_components_tooltip_properties_min-width);
+  min-height: var(--recursica_ui-kit_components_tooltip_properties_min-height);
+  max-width: var(--recursica_ui-kit_components_tooltip_properties_max-width);
+
+  padding: var(
+      --recursica_ui-kit_components_tooltip_properties_vertical-padding
+    )
+    var(--recursica_ui-kit_components_tooltip_properties_horizontal-padding);
+
+  /* Vertically center text within min-height container */
+  display: flex;
+  align-items: center;
+
+  /* Typography */
+  font-family: var(
+    --recursica_ui-kit_components_tooltip_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_tooltip_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_tooltip_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_tooltip_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_tooltip_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_tooltip_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_tooltip_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_tooltip_properties_text_text-transform
+  );
+
+  color: var(--recursica_ui-kit_components_tooltip_properties_colors_text);
+}
+
+/* ======================================
+   ARROW / BEAK
+   ====================================== */
+
+.arrow {
+  border-color: var(
+    --recursica_ui-kit_components_tooltip_properties_colors_border-color
+  );
+}

package/src/components/Tooltip/Tooltip.stories.tsx

@@ -1,35 +1,165 @@
 import type { Meta, StoryObj } from "@storybook/react";
-import { Tooltip } from "./Tooltip";
-import { ComingSoon } from "@recursica/storybook-template";
+import { Tooltip, type TooltipProps } from "./Tooltip";
+import { Button } from "../Button";
 
-const meta: Meta<typeof Tooltip> = {
-  title: "UI-Kit/🚧 Tooltip",
+/**
+ * Tooltip story axes:
+ * - position: tooltip alignment relative to target
+ * - withBeak: beak (arrow) indicator on the tooltip
+ * - openDelay / closeDelay: hover timing controls
+ * - multiline: text wrapping behavior
+ * - disabled: suppress the tooltip entirely
+ * - layer: tested via the global Layer decorator (withLayer/layer args)
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type TooltipStoryArgs = Record<string, any>;
+
+const meta: Meta = {
+  title: "UI-Kit/Tooltip",
   component: Tooltip,
   tags: ["autodocs"],
-  parameters: {
-    controls: {
-      include: [
-        "layer",
-        "withLayer",
-        "children",
-        "component",
-        "variant",
-        "size",
-        "icon",
-        "disabled",
-        "href",
-        "onClick",
-        "onChange",
-        "value",
-        "checked",
+  argTypes: {
+    label: {
+      control: "text",
+      description: "Content displayed inside the tooltip.",
+    },
+    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 tooltip 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 tooltip and the target element.",
+    },
+    openDelay: {
+      control: "number",
+      description: "Delay in ms before the tooltip opens on hover.",
+    },
+    closeDelay: {
+      control: "number",
+      description: "Delay in ms before the tooltip closes when hover ends.",
+    },
+    disabled: {
+      control: "boolean",
+      description: "If set, the tooltip will not be rendered.",
+    },
+    opened: {
+      control: "boolean",
+      description:
+        "Force the tooltip to stay open. Useful for inspecting styling.",
+    },
+    // Hide auto-detected HTML attributes that leak from ElementProps<'div'>
+    defaultChecked: { table: { disable: true } },
+    defaultValue: { table: { disable: true } },
+    suppressContentEditableWarning: { table: { disable: true } },
+    suppressHydrationWarning: { table: { disable: true } },
+  },
+  parameters: {
+    layout: "centered",
+    docs: {
+      description: {
+        component: `
+The \`Tooltip\` component displays a floating label when the user hovers over or focuses a target element. It wraps Mantine's \`Tooltip\` while enforcing strict Recursica design token styling.
+
+### API
+
+Unlike \`HoverCard\`, Tooltip is a single component — content is passed via the \`label\` prop:
+\`\`\`tsx
+<Tooltip label="Helpful text" withBeak>
+  <Button>Hover me</Button>
+</Tooltip>
+\`\`\`
+
+### Static Sub-Components
+- \`Tooltip.Floating\` — A tooltip that follows the cursor position
+- \`Tooltip.Group\` — Groups multiple tooltips to share hover delay
+
+### Key Behaviors
+- The beak (arrow) is shown by default (\`withBeak={true}\`)
+- Supports \`openDelay\` and \`closeDelay\` for timing control
+- Set \`multiline\` to allow text wrapping within max-width
+        `,
+      },
     },
   },
 };
 
 export default meta;
-type Story = StoryObj<typeof Tooltip>;
+
+type Story = StoryObj<TooltipStoryArgs>;
 
 export const Default: Story = {
-  render: () => <ComingSoon componentName="Tooltip" />,
+  args: {
+    label: "This is a helpful tooltip",
+    position: "top",
+    withBeak: true,
+    offset: 5,
+    openDelay: 0,
+    closeDelay: 0,
+    disabled: false,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: TooltipStoryArgs) => {
+    return (
+      <Tooltip {...(args as TooltipProps)}>
+        <Button variant="solid">Hover me</Button>
+      </Tooltip>
+    );
+  },
+};
+
+export const WithoutBeak: Story = {
+  args: {
+    label: "Tooltip without a beak indicator",
+    position: "top",
+    withBeak: false,
+    offset: 5,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: TooltipStoryArgs) => {
+    return (
+      <Tooltip {...(args as TooltipProps)}>
+        <Button variant="outline">Without Beak</Button>
+      </Tooltip>
+    );
+  },
+};
+
+export const LongContent: Story = {
+  args: {
+    label:
+      "This is a longer tooltip message that demonstrates how text wraps within the maximum width defined by the design system.",
+    position: "top",
+    withBeak: true,
+    opened: true,
+    offset: 5,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: TooltipStoryArgs) => {
+    return (
+      <Tooltip {...(args as TooltipProps)}>
+        <Button variant="solid">Long Content</Button>
+      </Tooltip>
+    );
+  },
 };

package/src/components/Tooltip/Tooltip.tsx

@@ -1,8 +1,91 @@
-import React from "react";
-import "./Tooltip.module.css";
+import {
+  Tooltip as MuiTooltip,
+  type TooltipProps as MuiTooltipProps,
+} from "@mui/material";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Tooltip.module.css";
 
-export type TooltipProps = React.HTMLAttributes<HTMLDivElement>;
+// ============================================================
+// TOOLTIP
+// ============================================================
 
-export const Tooltip: React.FC<TooltipProps> = (props) => {
-  return <div {...props}>Tooltip</div>;
+/**
+ * Recursica-specific props for Tooltip.
+ */
+import { type RecursicaTooltipProps } from "@recursica/adapter-common";
+
+/**
+ * Recursica Tooltip component wrapping Mui's Tooltip.
+ *
+ * Displays a floating label when the user hovers over or focuses a target element.
+ * Unlike HoverCard, Tooltip is a single component (not composable) — content is
+ * passed via the `label` prop, and the trigger is passed as `children`.
+ *
+ * ```tsx
+ * <Tooltip label="Helpful information" withBeak>
+ *   <Button>Hover me</Button>
+ * </Tooltip>
+ * ```
+ *
+ * Static sub-components available via dot-notation:
+ * - `// Tooltip.Floating` — Tooltip that follows the cursor
+ * - `// Tooltip.Group` — Shared hover delay group for multiple tooltips
+ */
+export type TooltipProps = RecursicaOverStyled<
+  MuiTooltipProps & RecursicaTooltipProps
+>;
+
+const TooltipBase = function Tooltip({
+  overStyled = false,
+  withBeak = true,
+  label,
+  opened,
+  ...rest
+}: TooltipProps & { label?: React.ReactNode; opened?: boolean }) {
+  const { title, ...restProps } = rest;
+  const sanitizedProps = filterStylingProps(restProps, overStyled);
+
+  // Bind CSS module classes to Mui's internal classNames API
+  const mergedClassNames: Partial<Record<string, string>> = {
+    tooltip: styles.tooltip,
+    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];
+      }
+    });
+  }
+
+  const withArrow = (sanitizedProps as Record<string, unknown>).withArrow as
+    | boolean
+    | undefined;
+  const resolvedWithArrow = withBeak ?? withArrow;
+
+  return (
+    <MuiTooltip
+      title={label || title || ""}
+      open={opened}
+      placement="top" /* Recursica default; Mui defaults to "bottom" */
+      arrow={resolvedWithArrow}
+      classes={mergedClassNames}
+      {...(sanitizedProps as unknown as Omit<MuiTooltipProps, "title">)}
+    />
+  );
 };
+TooltipBase.displayName = "Tooltip";
+
+export const Tooltip = TooltipBase;

package/src/components/TransferList/TransferList.stories.tsx

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

package/src/components/TransferList/TransferList.tsx

@@ -1,7 +1,9 @@
 import React from "react";
 import "./TransferList.module.css";
+import { type RecursicaTransferListProps } from "@recursica/adapter-common";
 
-export type TransferListProps = React.HTMLAttributes<HTMLDivElement>;
+export type TransferListProps = React.HTMLAttributes<HTMLDivElement> &
+  RecursicaTransferListProps;
 
 export const TransferList: React.FC<TransferListProps> = (props) => {
   return <div {...props}>TransferList</div>;

package/src/utils/RequireAccessibleLabel.ts

@@ -1,12 +1 @@
-import { ReactNode } from "react";
-
-/**
- * Enforces accessibility by strictly requiring at least one form of labeling:
- * either a visual \`label\`, an \`aria-label\`, or an \`aria-labelledby\`.
- */
-export type RequireAccessibleLabel<T> = T &
-  (
-    | { label: ReactNode; "aria-label"?: string; "aria-labelledby"?: string }
-    | { label?: ReactNode; "aria-label": string; "aria-labelledby"?: string }
-    | { label?: ReactNode; "aria-label"?: string; "aria-labelledby": string }
-  );
+export { type RequireAccessibleLabel } from "@recursica/adapter-common";

package/src/utils/filterStylingProps.ts

@@ -51,19 +51,13 @@ export const BLOCKED_STYLING_KEYS = [
   "position",
   "zIndex",
 ] as const;
-
-export type BlockedStylingKeys = (typeof BLOCKED_STYLING_KEYS)[number];
-
-export type RecursicaSpacing =
-  | "rec-none"
-  | "rec-sm"
-  | "rec-default"
-  | "rec-md"
-  | "rec-lg"
-  | "rec-xl"
-  | "rec-2xl";
-
-export type RecursicaSize = "small" | "default" | "large";
+export {
+  type RecursicaSpacing,
+  type RecursicaSize,
+  type RecursicaOverStyled,
+  type BlockedStylingKeys,
+  type ForbiddenStyles,
+} from "@recursica/adapter-common";
 
 const LAYOUT_PROPS = new Set([
   "m",
@@ -99,8 +93,6 @@ export const SPACING_MAP: Record<string, string> = {
   "rec-2xl": "var(--recursica_brand_dimensions_general_2xl)",
 };
 
-export type ForbiddenStyles = { [K in BlockedStylingKeys]?: never };
-
 export type OmitSx<T> = Omit<T, "sx">;
 
 export function filterSxProp<T extends Record<string, unknown>>(
@@ -113,11 +105,6 @@ export function filterSxProp<T extends Record<string, unknown>>(
   return sanitized as Omit<T, "sx">;
 }
 
-export type RecursicaOverStyled<T> =
-  | (Omit<T, BlockedStylingKeys> &
-      ForbiddenStyles & { overStyled?: false | undefined })
-  | (T & { overStyled: true });
-
 export function filterStylingProps<T extends Record<string, unknown>>(
   props: T,
   overStyled?: boolean,