@recursica/mui-adapter 0.4.0 → 0.6.0

package/src/components/Toast/Toast.module.css

@@ -0,0 +1,170 @@
+/* EXEMPTIONS:
+   - elevation levels layer-1, layer-2, and layer-3 are ignored because all toasts explicitly use the standard 
+     layer-0 elevation shadow for styling consistency. */
+/* recursica-ignore: --recursica_ui-kit_components_toast_properties_elevation_layer-1 */
+/* recursica-ignore: --recursica_ui-kit_components_toast_properties_elevation_layer-2 */
+/* recursica-ignore: --recursica_ui-kit_components_toast_properties_elevation_layer-3 */
+
+/* HARDCODED VALUES:
+   - border-style: none. To ensure the notification doesn't render unwanted borders unless specified.
+ */
+
+/* ======================================
+   TOAST / NOTIFICATION ROOT
+   ====================================== */
+
+.root {
+  border-style: none; /* HARDCODE: Reset to ensure clean shadow boundaries */
+  box-shadow: var(
+    --recursica_ui-kit_components_toast_properties_elevation_layer-0
+  );
+  padding: var(--recursica_ui-kit_components_toast_properties_vertical-padding)
+    var(--recursica_ui-kit_components_toast_properties_horizontal-padding);
+  min-width: var(--recursica_ui-kit_components_toast_properties_min-width);
+  max-width: var(--recursica_ui-kit_components_toast_properties_max-width);
+  min-height: var(--recursica_ui-kit_components_toast_properties_min-height);
+
+  /* Default Variant (Base) */
+  background-color: var(
+    --recursica_ui-kit_components_toast_variants_styles_default_properties_colors_background
+  );
+  gap: var(--recursica_ui-kit_components_toast_properties_spacing);
+
+  /* Hide Mantine's native colored vertical line */
+  &::before {
+    display: none;
+    content: none;
+  }
+
+  & .icon {
+    width: var(--recursica_ui-kit_components_toast_properties_icon) !important;
+    height: var(--recursica_ui-kit_components_toast_properties_icon) !important;
+    margin-right: 0 !important; /* Override Mantine's native spacing in favor of flex gap */
+    background-color: transparent !important; /* Remove Mantine's native circle background */
+
+    color: var(
+      --recursica_ui-kit_components_toast_variants_styles_default_properties_colors_text
+    );
+  }
+
+  & .loader {
+    margin-right: 0 !important; /* Override native spacing */
+  }
+  & .title,
+  & .description {
+    color: var(
+      --recursica_ui-kit_components_toast_variants_styles_default_properties_colors_text
+    );
+  }
+  & .closeButton {
+    color: var(
+      --recursica_ui-kit_components_toast_variants_styles_default_properties_colors_button
+    );
+  }
+
+  /* Error Variant styling */
+  &[data-variant="error"] {
+    background-color: var(
+      --recursica_ui-kit_components_toast_variants_styles_error_properties_colors_background
+    );
+
+    & .icon {
+      color: var(
+        --recursica_ui-kit_components_toast_variants_styles_error_properties_colors_text
+      ) !important;
+    }
+    & .title,
+    & .description {
+      color: var(
+        --recursica_ui-kit_components_toast_variants_styles_error_properties_colors_text
+      );
+    }
+    & .closeButton {
+      color: var(
+        --recursica_ui-kit_components_toast_variants_styles_error_properties_colors_button
+      );
+    }
+  }
+
+  /* Success Variant styling */
+  &[data-variant="success"] {
+    background-color: var(
+      --recursica_ui-kit_components_toast_variants_styles_success_properties_colors_background
+    );
+
+    & .icon {
+      color: var(
+        --recursica_ui-kit_components_toast_variants_styles_success_properties_colors_text
+      ) !important;
+    }
+    & .title,
+    & .description {
+      color: var(
+        --recursica_ui-kit_components_toast_variants_styles_success_properties_colors_text
+      );
+    }
+    & .closeButton {
+      color: var(
+        --recursica_ui-kit_components_toast_variants_styles_success_properties_colors_button
+      );
+    }
+  }
+}
+
+/* ======================================
+   TOAST BODY
+   ====================================== */
+
+.body {
+  /* No extra gap here, root handles icon-to-text, body can handle title-to-description if needed */
+}
+
+.title {
+  font-family: var(
+    --recursica_ui-kit_components_toast_properties_text_font-family
+  );
+  font-size: var(--recursica_ui-kit_components_toast_properties_text_font-size);
+  font-style: var(
+    --recursica_ui-kit_components_toast_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_toast_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_toast_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_toast_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_toast_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_toast_properties_text_text-transform
+  );
+}
+
+.description {
+  font-family: var(
+    --recursica_ui-kit_components_toast_properties_text_font-family
+  );
+  font-size: var(--recursica_ui-kit_components_toast_properties_text_font-size);
+  font-style: var(
+    --recursica_ui-kit_components_toast_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_toast_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_toast_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_toast_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_toast_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_toast_properties_text_text-transform
+  );
+}

package/src/components/Toast/Toast.stories.tsx

@@ -1,35 +1,67 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { Toast } from "./Toast";
-import { ComingSoon } from "@recursica/storybook-template";
 
-const meta: Meta<typeof Toast> = {
-  title: "UI-Kit/🚧 Toast",
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ToastStoryArgs = Record<string, any>;
+
+const meta = {
+  title: "UI-Kit/Toast",
   component: Toast,
   tags: ["autodocs"],
   parameters: {
-    controls: {
-      include: [
-        "layer",
-        "withLayer",
-        "children",
-        "component",
-        "variant",
-        "size",
-        "icon",
-        "disabled",
-        "href",
-        "onClick",
-        "onChange",
-        "value",
-        "checked",
-      ],
+    docs: {
+      description: {
+        component:
+          "The `Toast` component is a standalone visual component wrapping Mantine's `Notification`. Note that this component is visually decoupled from `@mantine/notifications` and is meant to be used when you need to render a static or manually-controlled notification panel. If you need dynamic notification popups, you should use `@mantine/notifications` and configure its provider to use our styles.",
+      },
     },
   },
-};
+  argTypes: {
+    title: {
+      control: "text",
+      description: "Title displayed above the message body",
+    },
+    children: {
+      control: "text",
+      description: "Main notification message",
+    },
+    withCloseButton: {
+      control: "boolean",
+      description: "Whether the close button is visible",
+    },
+  },
+} satisfies Meta<typeof Toast>;
 
 export default meta;
-type Story = StoryObj<typeof Toast>;
+type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
-  render: () => <ComingSoon componentName="Toast" />,
+  args: {
+    variant: "default",
+    title: "Update Available",
+    children:
+      "A new version of the application is available to download. Please restart your browser to apply the latest security patches and feature updates. If you ignore this message, the update will automatically install during your next session.",
+    withCloseButton: true,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: ToastStoryArgs) => {
+    return <Toast {...args} />;
+  },
+};
+
+export const WithIcon: Story = {
+  args: {
+    variant: "default",
+    title: "Action Required",
+    children:
+      "You must complete your profile setup before accessing this feature.",
+    icon: "⚠️",
+  },
+  parameters: {
+    controls: { disable: true },
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: ToastStoryArgs) => {
+    return <Toast {...args} />;
+  },
 };

package/src/components/Toast/Toast.tsx

@@ -1,7 +1,93 @@
 import React from "react";
+import {
+  Snackbar as MuiNotification,
+  type SnackbarProps as MuiNotificationProps,
+} from "@mui/material";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Toast.module.css";
 
-export type ToastProps = React.HTMLAttributes<HTMLDivElement>;
+export interface RecursicaToastProps {
+  /**
+   * The visual variant of the toast.
+   * @default "default"
+   */
+  variant?: "default" | "error" | "success";
 
-export const Toast: React.FC<ToastProps> = (props) => {
-  return <div {...props}>Toast</div>;
-};
+  /**
+   * Loading state is natively unsupported by Recursica UI Kit.
+   * If a loading state is required, pass a `<Loader size="sm" />` directly into the `icon` prop.
+   */
+  loading?: false;
+}
+
+/**
+ * Toast component wrapping Mui's Notification.
+ *
+ * Can be used as a standalone visual component to display a notification or message.
+ */
+export type ToastProps = RecursicaOverStyled<
+  Omit<MuiNotificationProps, "color" | "radius" | "variant" | "loading"> &
+    RecursicaToastProps
+>;
+
+export const Toast = React.forwardRef<HTMLDivElement, ToastProps>(
+  function Toast(
+    {
+      overStyled = false,
+      variant = "default",
+      withCloseButton = true,
+      ...rest
+    },
+    ref,
+  ) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+
+    // Bind CSS module classes to Mui's internal classNames API
+    const mergedClassNames: Partial<Record<string, string>> = {
+      root: styles.root,
+      body: styles.body,
+      title: styles.title,
+      description: styles.description,
+      closeButton: styles.closeButton,
+      icon: styles.icon,
+      loader: styles.loader,
+    };
+
+    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];
+        }
+      });
+    }
+
+    return (
+      <MuiNotification
+        ref={ref}
+        withCloseButton={withCloseButton}
+        withBorder={false} // Border is handled via CSS or tokens if needed
+        data-variant={variant}
+        classes={mergedClassNames}
+        loading={false}
+        {...(sanitizedProps as unknown as Omit<
+          MuiNotificationProps,
+          "color" | "radius" | "variant" | "loading"
+        >)}
+      />
+    );
+  },
+);
+
+Toast.displayName = "Toast";

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

@@ -0,0 +1,90 @@
+/* EXEMPTIONS:
+   - 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>
+    );
+  },
 };