@recursica/adapter-mui-v7 1.0.0

package/src/components/Timeline/USAGE.md

@@ -0,0 +1,41 @@
+# Timeline - Usage Guide
+
+This document describes how to integrate and use the `Timeline` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Timeline } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Timeline } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return (
+    <Timeline active={1}>
+      <Timeline.Item title="Step 1">Created branch</Timeline.Item>
+      <Timeline.Item title="Step 2">Pushed changes</Timeline.Item>
+    </Timeline>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mui-v7` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.

package/src/components/Timeline/index.ts

@@ -0,0 +1,2 @@
+export * from "./Timeline";
+export * from "./TimelineItem";

package/src/components/Toast/TOAST_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,37 @@
+# Toast – Implementation Notes
+
+Decisions and design tweaks tailored for the UI Kit's Toast wrapped against `@mui/material`'s `Alert` component.
+
+---
+
+## 1. No default icon (source-of-truth audit, 2026-08-30)
+
+**Decision:** `icon` defaults to suppressed (no icon) when the caller doesn't supply one, matching mantine-adapter's `Notification`-based Toast, which never renders an icon unless explicitly given one (see its own `TOAST_IMPLEMENTATION_NOTES.md` §3).
+
+**Implementation:** MUI's `Alert` falls back to its own built-in severity icon (a checkmark, since MUI's default `severity` is `"success"`) whenever its `icon` prop is left `undefined` — `icon={false}` is the only way to render no icon at all. `Toast` now passes `icon={icon ?? false}` instead of `icon={icon}` so an unset `icon` prop renders nothing, not MUI's own default. Found via the `adapter-tester:source-of-truth` divergence check: mui's `Default` story rendered a leading checkmark icon mantine's golden never had.
+
+---
+
+## 2. Doubled vertical padding (source-of-truth audit, 2026-08-30)
+
+**Symptom:** `ui-kit-toast--default` (and `with-icon`) rendered visibly taller than mantine's —
+confirmed via computed styles: mui's `.MuiAlert-root` measured 93.7px tall vs mantine's
+`.mantine-Notification-root` at 76.8px, for identical content and an identical
+`--recursica_ui-kit_components_toast_properties_vertical-padding`/`horizontal-padding` on
+`.root` in both (`8px 16px` either way — the CSS files are otherwise byte-identical).
+
+**Root cause:** MUI's `Alert` renders internal wrapper `<div>`s for its icon/message/action
+slots (`.MuiAlert-message`, `.MuiAlert-icon`, `.MuiAlert-action`), and each of those ships its
+own non-zero default padding (`8px 0`, `7px 0`, and `4px 0 0 16px` respectively, straight from
+MUI's own `Alert.js` source) that stacks on top of `.root`'s own padding token — doubling the
+effective vertical padding. Mantine's `Notification` has no equivalent built-in padding on its
+`body`/`icon`/`close` slots, so `.root`'s token is already the sole source of padding there;
+that's "the correct var mantine uses" — mui just wasn't the only thing applying it.
+
+**Fix:** Added `padding: 0 !important;` to `.body` (→ `.MuiAlert-message`), `.icon` (→
+`.MuiAlert-icon`), and `.closeButton` (→ `.MuiAlert-action`) in `Toast.module.css`, so
+`.root`'s own `vertical-padding`/`horizontal-padding` tokens are the only padding applied,
+matching mantine exactly. `!important` follows the same pattern already used on `.icon`'s other
+overrides in this file (MUI's own emotion-generated class can win the cascade depending on
+`<style>` injection order otherwise). Verified via computed styles after the fix: mui's root
+measured 77.7px vs mantine's 76.8px — the ~1px residual is font-metric noise, not padding.

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

@@ -0,0 +1,193 @@
+/* HARDCODED VALUES:
+   - border-style: solid. Baseline so the per-variant border-color tokens actually render.
+ */
+
+/* ======================================
+   TOAST / NOTIFICATION ROOT
+   ====================================== */
+
+.root {
+  border-radius: var(
+    --recursica_ui-kit_components_toast_properties_border-radius
+  );
+  border-width: var(--recursica_ui-kit_components_toast_properties_border-size);
+  border-style: solid; /* HARDCODE: baseline so border-color tokens render */
+  border-color: var(
+    --recursica_ui-kit_components_toast_variants_styles_default_properties_colors_border-color
+  );
+  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-color
+  );
+  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 */
+    /* MUI's `.MuiAlert-icon` ships its own default `padding: 7px 0`, stacking on top of
+       `--recursica_ui-kit_components_toast_properties_vertical-padding` already applied to
+       `.root` below — zero it for the same reason as `.body`'s padding override. */
+    padding: 0 !important;
+
+    color: var(
+      --recursica_ui-kit_components_toast_variants_styles_default_properties_colors_text-color
+    );
+  }
+
+  & .loader {
+    margin-right: 0 !important; /* Override native spacing */
+  }
+  & .title,
+  & .description {
+    color: var(
+      --recursica_ui-kit_components_toast_variants_styles_default_properties_colors_text-color
+    );
+  }
+  & .closeButton {
+    color: var(
+      --recursica_ui-kit_components_toast_variants_styles_default_properties_colors_button
+    );
+    /* MUI's `.MuiAlert-action` ships its own default `padding: 4px 0 0 16px`, adding vertical
+       space beyond `.root`'s own vertical-padding token (mantine's close button has no built-in
+       padding to conflict with it) — zero it so `.root`'s padding is the single source of
+       truth, same as `.body` below. `margin-left: auto` (MUI's own default, untouched) still
+       keeps it pinned to the row's end. */
+    padding: 0 !important;
+  }
+
+  /* Error Variant styling */
+  &[data-variant="error"] {
+    background-color: var(
+      --recursica_ui-kit_components_toast_variants_styles_error_properties_colors_background-color
+    );
+    border-color: var(
+      --recursica_ui-kit_components_toast_variants_styles_error_properties_colors_border-color
+    );
+
+    & .icon {
+      color: var(
+        --recursica_ui-kit_components_toast_variants_styles_error_properties_colors_text-color
+      ) !important;
+    }
+    & .title,
+    & .description {
+      color: var(
+        --recursica_ui-kit_components_toast_variants_styles_error_properties_colors_text-color
+      );
+    }
+    & .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-color
+    );
+    border-color: var(
+      --recursica_ui-kit_components_toast_variants_styles_success_properties_colors_border-color
+    );
+
+    & .icon {
+      color: var(
+        --recursica_ui-kit_components_toast_variants_styles_success_properties_colors_text-color
+      ) !important;
+    }
+    & .title,
+    & .description {
+      color: var(
+        --recursica_ui-kit_components_toast_variants_styles_success_properties_colors_text-color
+      );
+    }
+    & .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 */
+  /* MUI's `.MuiAlert-message` ships its own default `padding: 8px 0`, doubling up on top of
+     `--recursica_ui-kit_components_toast_properties_vertical-padding` already applied to
+     `.root` above (mantine's Notification body has no built-in padding to conflict with the
+     same token — confirmed via computed styles: mui's root measured 93.7px tall vs mantine's
+     76.8px for identical content). Zero it so `.root`'s own padding is the single source of
+     truth, matching mantine exactly. */
+  padding: 0 !important;
+}
+
+.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

@@ -0,0 +1,67 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Toast } from "./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 Mui's `Alert`. Note that this component is visually decoupled from `@mui/material/Snackbar` and is meant to be used when you need to render a static or manually-controlled notification panel.",
+      },
+    },
+  },
+  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 meta>;
+
+export const Default: Story = {
+  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.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Toast component tests. Add tests here if/when needed.

package/src/components/Toast/Toast.tsx

@@ -0,0 +1,121 @@
+import React from "react";
+import {
+  Alert as MuiAlert,
+  AlertTitle as MuiAlertTitle,
+  IconButton as MuiIconButton,
+  type AlertProps as MuiAlertProps,
+} from "@mui/material";
+import {
+  filterStylingProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Toast.module.css";
+
+import { type RecursicaToastProps as BaseRecursicaToastProps } from "@recursica/adapter-common";
+
+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);
+
+    // Note MUI's actual prop is "classes", not "classNames" (that's Mantine's naming) — this
+    // used to read the wrong key, silently no-op-ing any caller-supplied classes.
+    const mergedClassNames = mergeClassNames(
+      {
+        root: styles.root,
+        message: styles.body,
+        icon: styles.icon,
+        action: styles.closeButton,
+      },
+      (sanitizedProps as Record<string, unknown>).classes as
+        | Partial<Record<string, string>>
+        | undefined,
+    );
+
+    const handleClose = () => {
+      if (onClose) onClose();
+    };
+
+    return (
+      <MuiAlert
+        ref={ref}
+        {...(sanitizedProps as unknown as Omit<
+          MuiAlertProps,
+          "color" | "radius" | "variant" | "onClose"
+        >)}
+        // MUI's Alert falls back to its own built-in severity icon (default severity is
+        // "success", hence a checkmark) when `icon` is left `undefined` — `icon={false}`
+        // is required to render no icon at all, which is Recursica's own default.
+        icon={icon ?? false}
+        data-variant={variant}
+        className={`${className || ""}`}
+        classes={mergedClassNames}
+        action={
+          withCloseButton ? (
+            <MuiIconButton
+              size="small"
+              aria-label="close"
+              color="inherit"
+              onClick={handleClose}
+            >
+              <CloseIcon />
+            </MuiIconButton>
+          ) : undefined
+        }
+      >
+        {title && (
+          <MuiAlertTitle className={styles.title}>{title}</MuiAlertTitle>
+        )}
+        <div className={styles.description}>{children}</div>
+      </MuiAlert>
+    );
+  },
+);
+
+Toast.displayName = "Toast";

package/src/components/Toast/USAGE.md

@@ -0,0 +1,42 @@
+# Toast - Usage Guide
+
+This document describes how to integrate and use the `Toast` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Toast } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Toast } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return (
+    <Toast
+      title="Success"
+      message="Your action completed successfully"
+      state="success"
+    />
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mui-v7` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.

package/src/components/Toast/index.ts

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

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

@@ -0,0 +1,83 @@
+/* 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-color
+  );
+  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-color
+  );
+}
+
+/* ======================================
+   ARROW / BEAK
+   ====================================== */
+
+.arrow {
+  border-color: var(
+    --recursica_ui-kit_components_tooltip_properties_colors_border-color
+  );
+}