@recursica/mui-adapter 0.5.0 → 0.7.0

package/src/components/Timeline/Timeline.stories.tsx

@@ -1,35 +1,128 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { Timeline } from "./Timeline";
-import { ComingSoon } from "@recursica/storybook-template";
 
 const meta: Meta<typeof Timeline> = {
-  title: "UI-Kit/🚧 Timeline",
+  title: "UI-Kit/Timeline",
   component: Timeline,
   tags: ["autodocs"],
-  parameters: {
-    controls: {
-      include: [
-        "layer",
-        "withLayer",
-        "children",
-        "component",
-        "variant",
-        "size",
-        "icon",
-        "disabled",
-        "href",
-        "onClick",
-        "onChange",
-        "value",
-        "checked",
-      ],
-    },
+  argTypes: {
+    defaultChecked: { table: { disable: true } },
   },
 };
 
 export default meta;
+
 type Story = StoryObj<typeof Timeline>;
 
 export const Default: Story = {
-  render: () => <ComingSoon componentName="Timeline" />,
+  args: {
+    active: 1,
+  },
+  render: (args) => (
+    <Timeline {...args}>
+      <Timeline.Item
+        title="Commit created"
+        timestamp="Yesterday"
+        bulletVariant="default"
+      >
+        You pushed 3 new commits to the repository.
+      </Timeline.Item>
+      <Timeline.Item
+        title="Pull request opened"
+        timestamp="2 days ago"
+        bulletVariant="default"
+      >
+        You opened a pull request for the feature branch.
+      </Timeline.Item>
+      <Timeline.Item
+        title="Code review completed"
+        timestamp="1 week ago"
+        bulletVariant="default"
+      >
+        Your pull request was approved by 2 reviewers.
+      </Timeline.Item>
+      <Timeline.Item
+        title="Branch merged"
+        timestamp="2 weeks ago"
+        bulletVariant="default"
+      >
+        Your feature branch was successfully merged into main.
+      </Timeline.Item>
+    </Timeline>
+  ),
+};
+
+export const BulletVariants: Story = {
+  args: {
+    active: 1,
+  },
+  render: (args) => (
+    <Timeline {...args}>
+      <Timeline.Item
+        title="Default Bullet"
+        timestamp="Standard configuration"
+        bulletVariant="default"
+      >
+        The default un-configured structural dot.
+      </Timeline.Item>
+      <Timeline.Item
+        title="Icon Bullet"
+        timestamp="Standard sized icons"
+        bulletVariant="icon"
+        bullet={
+          <svg
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          >
+            <polyline points="20 6 9 17 4 12"></polyline>
+          </svg>
+        }
+      >
+        A standard structural icon node mapping.
+      </Timeline.Item>
+      <Timeline.Item
+        title="Alternative Icon"
+        timestamp="Larger structural bounds"
+        bulletVariant="icon-alternative"
+        bullet={
+          <svg
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          >
+            <rect x="3" y="3" width="18" height="18" rx="2" ry="2"></rect>
+          </svg>
+        }
+      >
+        A slightly larger alternative bounding box for specialized icons.
+      </Timeline.Item>
+      <Timeline.Item
+        title="Avatar Bullet"
+        timestamp="Profile pictures"
+        bulletVariant="avatar"
+        bullet={
+          <img
+            src="https://avatars.githubusercontent.com/u/10353856?s=460&v=4"
+            alt="avatar"
+            style={{
+              width: "100%",
+              height: "100%",
+              objectFit: "cover",
+              borderRadius: "inherit",
+            }}
+          />
+        }
+      >
+        Avatar mappings inherently drop borders and leverage specific opacity
+        states.
+      </Timeline.Item>
+    </Timeline>
+  ),
 };

package/src/components/Timeline/Timeline.tsx

@@ -1,8 +1,86 @@
 import React from "react";
-import "./Timeline.module.css";
+import MuiTimeline, {
+  type TimelineProps as MuiTimelineProps,
+} from "@mui/lab/Timeline";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Timeline.module.css";
+import { TimelineItem } from "./TimelineItem";
 
-export type TimelineProps = React.HTMLAttributes<HTMLDivElement>;
+import { type RecursicaTimelineProps } from "@recursica/adapter-common";
 
-export const Timeline: React.FC<TimelineProps> = (props) => {
-  return <div {...props}>Timeline</div>;
-};
+/**
+ * Properties for the strictly-tokenized Timeline component.
+ * Native Mui abstract properties like `color`, `radius`, `bulletSize`, and `lineWidth`
+ * have been stripped out to strictly enforce the structural mappings of the Recursica UI Kit.
+ */
+export type TimelineProps = RecursicaOverStyled<
+  Omit<MuiTimelineProps, "color" | "radius" | "bulletSize" | "lineWidth"> &
+    RecursicaTimelineProps
+>;
+
+interface TimelineComponent
+  extends React.ForwardRefExoticComponent<
+    TimelineProps & React.RefAttributes<HTMLDivElement>
+  > {
+  Item: typeof TimelineItem;
+}
+
+/**
+ * The `Timeline` component displays a list of events in chronological order.
+ *
+ * **Recursica Abstract:**
+ * This component acts as a structural wrapper around Mui's `<Timeline>`.
+ * It forces alignment and geometry strictly via the UI Kit's `.itemBullet` and connector definitions.
+ *
+ * @example
+ * ```tsx
+ * <Timeline active={1}>
+ *   <Timeline.Item title="Event 1" timestamp="Yesterday">Description</Timeline.Item>
+ * </Timeline>
+ * ```
+ */
+const TimelineInner = React.forwardRef<HTMLUListElement, TimelineProps>(
+  function Timeline({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+
+    const mergedClassNames: Partial<Record<string, string>> = {
+      root: styles.root,
+    };
+
+    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 (
+      <MuiTimeline
+        ref={ref}
+        classes={mergedClassNames}
+        {...(sanitizedProps as unknown as Omit<
+          MuiTimelineProps,
+          "color" | "radius" | "bulletSize" | "lineWidth"
+        >)}
+      />
+    );
+  },
+);
+
+TimelineInner.displayName = "Timeline";
+
+export const Timeline = TimelineInner as TimelineComponent;
+Timeline.Item = TimelineItem;

package/src/components/Timeline/TimelineItem.tsx

@@ -0,0 +1,90 @@
+import React from "react";
+import MuiTimelineItem, {
+  type TimelineItemProps as MuiTimelineItemProps,
+} from "@mui/lab/TimelineItem";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Timeline.module.css";
+
+import { type RecursicaTimelineItemProps } from "@recursica/adapter-common";
+
+export type TimelineItemProps = RecursicaOverStyled<
+  Omit<MuiTimelineItemProps, "radius" | "color" | "lineVariant"> &
+    RecursicaTimelineItemProps
+>;
+
+/**
+ * The individual item component for the Timeline.
+ *
+ * **Recursica Abstract:**
+ * The `Timeline.Item` has been extended to support a `timestamp` string natively,
+ * rendering it below the body content. It also accepts a `bulletVariant` to morph
+ * the structural dimensions of the node circle automatically.
+ */
+export const TimelineItem = React.forwardRef<HTMLDivElement, TimelineItemProps>(
+  function TimelineItem(
+    {
+      overStyled = false,
+      timestamp,
+      bulletVariant = "default",
+      children,
+      ...rest
+    },
+    ref,
+  ) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+
+    const mergedClassNames: Partial<Record<string, string>> = {
+      item: styles.item,
+      itemBody: styles.itemBody,
+      itemContent: styles.itemContent,
+      itemBullet: styles.itemBullet,
+      itemTitle: styles.itemTitle,
+    };
+
+    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];
+        }
+      });
+    }
+
+    // Embed timestamp inside children if provided, wrapped in a specific class
+    const content = timestamp ? (
+      <>
+        {children && <div className={styles.description}>{children}</div>}
+        <div className={styles.timestamp}>{timestamp}</div>
+      </>
+    ) : (
+      children
+    );
+
+    return (
+      <MuiTimelineItem
+        ref={ref}
+        classes={mergedClassNames}
+        data-variant={bulletVariant}
+        {...(sanitizedProps as unknown as Omit<
+          MuiTimelineItemProps,
+          "radius" | "color" | "lineVariant"
+        >)}
+      >
+        {content}
+      </MuiTimelineItem>
+    );
+  },
+);
+
+TimelineItem.displayName = "TimelineItem";

package/src/components/Title/Title.stories.tsx

@@ -13,24 +13,6 @@ const meta: Meta<typeof Title> = {
           "The semantic `<Title>` abstraction intrinsically links pure `h1-h6` tag generation with exact Recursica design boundaries to preserve SEO and screen reader trees uniformly globally.",
       },
     },
-    controls: {
-      include: [
-        "layer",
-        "withLayer",
-        "order",
-        "children",
-        "component",
-        "variant",
-        "size",
-        "icon",
-        "disabled",
-        "href",
-        "onClick",
-        "onChange",
-        "value",
-        "checked",
-      ],
-    },
   },
   argTypes: {
     order: {

package/src/components/Title/Title.tsx

@@ -1,13 +1,7 @@
 import React, { forwardRef } from "react";
 import { Typography } from "../Typography/Typography";
 import { type RecursicaOverStyled } from "../../utils/filterStylingProps";
-import { type TypographyProps as MuiTypographyProps } from "@mui/material";
-
-export type RecursicaTitleProps = Omit<MuiTypographyProps, "variant"> & {
-  order?: 1 | 2 | 3 | 4 | 5 | 6;
-  children?: React.ReactNode;
-  component?: React.ElementType;
-};
+import { type RecursicaTitleProps } from "@recursica/adapter-common";
 
 export type TitleProps = RecursicaOverStyled<RecursicaTitleProps>;
 

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

@@ -1,32 +1,170 @@
 /* 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_toast_properties_elevation_layer-0 */
+   - 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 */
-/* recursica-ignore: --recursica_ui-kit_components_toast_properties_horizontal-padding */
-/* recursica-ignore: --recursica_ui-kit_components_toast_properties_icon */
-/* recursica-ignore: --recursica_ui-kit_components_toast_properties_max-width */
-/* recursica-ignore: --recursica_ui-kit_components_toast_properties_min-height */
-/* recursica-ignore: --recursica_ui-kit_components_toast_properties_min-width */
-/* recursica-ignore: --recursica_ui-kit_components_toast_properties_spacing */
-/* recursica-ignore: --recursica_ui-kit_components_toast_properties_text_font-family */
-/* recursica-ignore: --recursica_ui-kit_components_toast_properties_text_font-size */
-/* recursica-ignore: --recursica_ui-kit_components_toast_properties_text_font-style */
-/* recursica-ignore: --recursica_ui-kit_components_toast_properties_text_font-weight */
-/* recursica-ignore: --recursica_ui-kit_components_toast_properties_text_letter-spacing */
-/* recursica-ignore: --recursica_ui-kit_components_toast_properties_text_line-height */
-/* recursica-ignore: --recursica_ui-kit_components_toast_properties_text_text-decoration */
-/* recursica-ignore: --recursica_ui-kit_components_toast_properties_text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_toast_properties_vertical-padding */
-/* recursica-ignore: --recursica_ui-kit_components_toast_variants_styles_default_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_toast_variants_styles_default_properties_colors_button */
-/* recursica-ignore: --recursica_ui-kit_components_toast_variants_styles_default_properties_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_toast_variants_styles_error_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_toast_variants_styles_error_properties_colors_button */
-/* recursica-ignore: --recursica_ui-kit_components_toast_variants_styles_error_properties_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_toast_variants_styles_success_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_toast_variants_styles_success_properties_colors_button */
-/* recursica-ignore: --recursica_ui-kit_components_toast_variants_styles_success_properties_colors_text */
+
+/* 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 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 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} />;
+  },
 };