@recursica/mantine-adapter 0.18.0 → 0.19.0

package/src/components/Toast/TOAST_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,39 @@
+# Toast – Implementation Notes
+
+Decisions and design tweaks tailored for the UI Kit's Toast wrapped against `@mantine/core`'s `Notification` component.
+
+---
+
+## 1. Standalone Visual Wrapper
+
+**Decision:** We wrap `@mantine/core`'s standalone `Notification` component instead of wrapping the `@mantine/notifications` provider.
+
+**Implementation:** The UI Kit provides variables for the `Toast` component itself (e.g., `--recursica_ui-kit_components_toast_*`). We use these variables to style the standard Mantine `Notification` element. This allows developers to use `<Toast>` manually if they want a static or inline message.
+
+If dynamic popups are required, developers can configure `@mantine/notifications` to utilize this component or use its classes.
+
+---
+
+## 2. Variant Mapping via `data-variant`
+
+**Decision:** `variant` props (`"default" | "error" | "success"`) are mapped directly to `data-variant` on the Mantine root `Box`.
+
+**Implementation:** Mantine's `Notification` doesn't inherently support our custom variants out of the box in the way we want them styled. By passing `data-variant` directly to the `Box`, we can explicitly target the root element in our `Toast.module.css` (e.g., `.root[data-variant="success"]`) and pipe in the corresponding UI Kit layer colors.
+
+---
+
+## 3. Minimal CSS Override Philosophy
+
+**Decision:** The CSS module only overrides visual design tokens (colors, typography, padding, borders, shadows).
+
+**Implementation:** We defer layout structure, icon rendering, loader transitions, and close button mechanics to Mantine. The `border-style: none;` is hardcoded to reset any underlying styles from Mantine's defaults, ensuring a clean mapping of elevation and shadows.
+
+---
+
+## 4. Unsupported `loading` State
+
+**Decision:** The native `loading` state is explicitly stripped and bypassed from the `<Toast />` component wrapper.
+
+**Implementation:** Mantine's `Notification` inherently supports a `loading={true}` state that natively spins up a loader instead of an icon. However, Recursica's UI Kit strictly does not define structural tokens for loader states inside toasts.
+Instead of attempting to tightly couple the internal `Loader` abstraction or mapping variables incorrectly, the `loading` property is explicitly omitted and `false`-enforced from the public API.
+If consumers explicitly require a loading toast, they must manually inject a `<Loader />` component into the `icon` slot.

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

@@ -0,0 +1,109 @@
+/* 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);
+
+  & .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
+    );
+  }
+}
+
+/* ======================================
+   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,17 +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: {
+    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 {
+  Notification as MantineNotification,
+  type NotificationProps as MantineNotificationProps,
+} from "@mantine/core";
+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";
 
-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 Mantine's Notification.
+ *
+ * Can be used as a standalone visual component to display a notification or message.
+ */
+export type ToastProps = RecursicaOverStyled<
+  Omit<MantineNotificationProps, "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 Mantine'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 (
+      <MantineNotification
+        ref={ref}
+        withCloseButton={withCloseButton}
+        withBorder={false} // Border is handled via CSS or tokens if needed
+        data-variant={variant}
+        classNames={mergedClassNames}
+        loading={false}
+        {...(sanitizedProps as unknown as Omit<
+          MantineNotificationProps,
+          "color" | "radius" | "variant" | "loading"
+        >)}
+      />
+    );
+  },
+);
+
+Toast.displayName = "Toast";

package/src/components/Toast/index.ts

@@ -0,0 +1 @@
+export * from "./Toast";

package/src/components/index.ts

@@ -24,6 +24,7 @@ export * from "./Modal/Modal";
 export * from "./NumberInput/NumberInput";
 export * from "./Pagination/Pagination";
 export * from "./Panel/Panel";
+export * from "./Popover";
 export * from "./Radio/Radio";
 export * from "./Radio/RadioGroup";
 export * from "./ReadOnlyField";
@@ -41,6 +42,6 @@ export * from "./TextField/TextField";
 export * from "./TimePicker/TimePicker";
 export * from "./Timeline/Timeline";
 export * from "./Title/Title";
-export * from "./Toast/Toast";
+export * from "./Toast";
 export * from "./Tooltip/Tooltip";
 export * from "./TransferList/TransferList";