@recursica/mui-adapter 0.4.0 → 0.6.0

package/src/components/Timeline/Timeline.module.css

@@ -0,0 +1,367 @@
+/* EXEMPTIONS:
+   - timeline-bullet_variants_types_avatar_properties_avatar-size is ignored because under the avatar timeline variant,
+     the bullet container size uses fallback bullet-size configurations to maintain vertical alignment with the 
+     inactive/active connector line, while the nested Avatar subcomponent handles its own sizing natively. */
+/* recursica-ignore: --recursica_ui-kit_components_timeline-bullet_variants_types_avatar_properties_avatar-size */
+
+.root {
+  display: flex;
+  flex-direction: column;
+}
+
+.item {
+  /* Mantine uses these vars to calculate the exact left: position of the connector line */
+  --tl-line-width: var(
+    --recursica_ui-kit_components_timeline_properties_inactive-connector-size
+  ) !important;
+
+  &[data-active] {
+    --tl-line-width: var(
+      --recursica_ui-kit_components_timeline_properties_active-connector-size
+    ) !important;
+  }
+
+  &[data-variant="default"] {
+    --tl-bullet-size: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_default_properties_bullet-size
+    ) !important;
+  }
+  &[data-variant="icon"] {
+    --tl-bullet-size: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon_properties_bullet-size
+    ) !important;
+  }
+  &[data-variant="icon-alternative"] {
+    --tl-bullet-size: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon-alternative_properties_bullet-size
+    ) !important;
+  }
+  &[data-variant="avatar"] {
+    /* Avatar sizing fallback to default to maintain connector alignment */
+    --tl-bullet-size: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_default_properties_bullet-size
+    ) !important;
+  }
+
+  /* Control connector lines via the item ::before pseudo-element */
+  /* Inactive connector */
+  &::before {
+    border-left-width: var(
+      --recursica_ui-kit_components_timeline_properties_inactive-connector-size
+    ) !important;
+    border-left-color: var(
+      --recursica_ui-kit_components_timeline_properties_colors_inactive-connector-color
+    ) !important;
+  }
+
+  /* Active connector */
+  &[data-active]::before {
+    border-left-width: var(
+      --recursica_ui-kit_components_timeline_properties_active-connector-size
+    ) !important;
+    border-left-color: var(
+      --recursica_ui-kit_components_timeline_properties_colors_active-connector-color
+    ) !important;
+  }
+}
+
+.itemBody {
+  /* Space between the bullet and the content */
+  padding-left: var(
+    --recursica_ui-kit_components_timeline_properties_bullet-content-gap
+  ) !important;
+}
+
+.itemBullet {
+  /* Default Variant */
+  :global(.mantine-Timeline-item)[data-variant="default"] & {
+    width: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_default_properties_bullet-size
+    ) !important;
+    height: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_default_properties_bullet-size
+    ) !important;
+    border-radius: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_default_properties_border-radius
+    ) !important;
+    border-width: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_default_properties_border-size
+    ) !important;
+
+    background-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_default_properties_colors_inactive-background
+    ) !important;
+    border-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_default_properties_colors_inactive-border-color
+    ) !important;
+  }
+  :global(.mantine-Timeline-item)[data-variant="default"][data-active] & {
+    background-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_default_properties_colors_active-background
+    ) !important;
+    border-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_default_properties_colors_active-border-color
+    ) !important;
+  }
+
+  /* Icon Variant */
+  :global(.mantine-Timeline-item)[data-variant="icon"] & {
+    width: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon_properties_bullet-size
+    ) !important;
+    height: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon_properties_bullet-size
+    ) !important;
+    border-radius: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon_properties_border-radius
+    ) !important;
+    border-width: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon_properties_border-size
+    ) !important;
+
+    background-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon_properties_colors_inactive-background
+    ) !important;
+    border-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon_properties_colors_inactive-border-color
+    ) !important;
+    color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon_properties_colors_inactive-icon-color
+    ) !important;
+
+    /* Propagate icon size */
+    font-size: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon_properties_icon-size
+    );
+    & svg {
+      width: var(
+        --recursica_ui-kit_components_timeline-bullet_variants_types_icon_properties_icon-size
+      );
+      height: var(
+        --recursica_ui-kit_components_timeline-bullet_variants_types_icon_properties_icon-size
+      );
+    }
+  }
+  :global(.mantine-Timeline-item)[data-variant="icon"][data-active] & {
+    background-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon_properties_colors_active-background
+    ) !important;
+    border-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon_properties_colors_active-border-color
+    ) !important;
+    color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon_properties_colors_active-icon-color
+    ) !important;
+  }
+
+  /* Icon Alternative Variant */
+  :global(.mantine-Timeline-item)[data-variant="icon-alternative"] & {
+    width: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon-alternative_properties_bullet-size
+    ) !important;
+    height: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon-alternative_properties_bullet-size
+    ) !important;
+    border-radius: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon-alternative_properties_border-radius
+    ) !important;
+    border-width: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon-alternative_properties_border-size
+    ) !important;
+
+    background-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon-alternative_properties_colors_inactive-background
+    ) !important;
+    border-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon-alternative_properties_colors_inactive-border-color
+    ) !important;
+    color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon-alternative_properties_colors_inactive-icon-color
+    ) !important;
+
+    font-size: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon-alternative_properties_icon-size
+    );
+    & svg {
+      width: var(
+        --recursica_ui-kit_components_timeline-bullet_variants_types_icon-alternative_properties_icon-size
+      );
+      height: var(
+        --recursica_ui-kit_components_timeline-bullet_variants_types_icon-alternative_properties_icon-size
+      );
+    }
+  }
+  :global(.mantine-Timeline-item)[data-variant="icon-alternative"][data-active]
+    & {
+    background-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon-alternative_properties_colors_active-background
+    ) !important;
+    border-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon-alternative_properties_colors_active-border-color
+    ) !important;
+    color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon-alternative_properties_colors_active-icon-color
+    ) !important;
+  }
+
+  /* Avatar Variant */
+  :global(.mantine-Timeline-item)[data-variant="avatar"] & {
+    /* Avatar sizing is often governed by the avatar itself, but we'll apply the radius and opacity */
+    border-radius: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_avatar_properties_border-radius
+    ) !important;
+    border-width: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_avatar_properties_border-size
+    ) !important;
+    opacity: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_avatar_properties_inactive-avatar-opacity
+    ) !important;
+
+    background-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_avatar_properties_colors_inactive-background
+    ) !important;
+    border-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_avatar_properties_colors_inactive-border-color
+    ) !important;
+  }
+  :global(.mantine-Timeline-item)[data-variant="avatar"][data-active] & {
+    opacity: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_avatar_properties_active-avatar-opacity
+    ) !important;
+    background-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_avatar_properties_colors_active-background
+    ) !important;
+    border-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_avatar_properties_colors_active-border-color
+    ) !important;
+  }
+}
+
+.itemTitle {
+  font-family: var(
+    --recursica_ui-kit_components_timeline_properties_title-text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_timeline_properties_title-text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_timeline_properties_title-text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_timeline_properties_title-text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_timeline_properties_title-text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_timeline_properties_title-text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_timeline_properties_title-text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_timeline_properties_title-text_text-transform
+  );
+
+  /* Title Description Gap */
+  margin-bottom: var(
+    --recursica_ui-kit_components_timeline_properties_title-description-gap
+  ) !important;
+
+  /* Inactive Title Color */
+  color: var(
+    --recursica_ui-kit_components_timeline_properties_colors_inactive-title-color
+  ) !important;
+
+  /* Active Title Color */
+  :global(.mantine-Timeline-item)[data-active] & {
+    color: var(
+      --recursica_ui-kit_components_timeline_properties_colors_active-title-color
+    ) !important;
+  }
+}
+
+.itemContent {
+  display: flex;
+  flex-direction: column;
+  gap: var(
+    --recursica_ui-kit_components_timeline_properties_description-timestamp-gap
+  );
+  max-width: var(
+    --recursica_ui-kit_components_timeline_properties_max-text-width
+  );
+}
+
+.description {
+  font-family: var(
+    --recursica_ui-kit_components_timeline_properties_description-text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_timeline_properties_description-text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_timeline_properties_description-text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_timeline_properties_description-text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_timeline_properties_description-text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_timeline_properties_description-text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_timeline_properties_description-text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_timeline_properties_description-text_text-transform
+  );
+
+  color: var(
+    --recursica_ui-kit_components_timeline_properties_colors_inactive-description-color
+  );
+
+  :global(.mantine-Timeline-item)[data-active] & {
+    color: var(
+      --recursica_ui-kit_components_timeline_properties_colors_active-description-color
+    );
+  }
+}
+
+.timestamp {
+  font-family: var(
+    --recursica_ui-kit_components_timeline_properties_timestamp-text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_timeline_properties_timestamp-text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_timeline_properties_timestamp-text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_timeline_properties_timestamp-text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_timeline_properties_timestamp-text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_timeline_properties_timestamp-text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_timeline_properties_timestamp-text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_timeline_properties_timestamp-text_text-transform
+  );
+
+  color: var(
+    --recursica_ui-kit_components_timeline_properties_colors_inactive-timestamp-color
+  );
+
+  :global(.mantine-Timeline-item)[data-active] & {
+    color: var(
+      --recursica_ui-kit_components_timeline_properties_colors_active-timestamp-color
+    );
+  }
+}

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,7 +1,83 @@
 import React from "react";
+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>;
+/**
+ * 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">
+>;
 
-export const Timeline: React.FC<TimelineProps> = (props) => {
-  return <div {...props}>Timeline</div>;
-};
+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,101 @@
+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";
+
+export interface RecursicaTimelineItemProps {
+  /**
+   * Timestamp text displayed below the description.
+   */
+  timestamp?: React.ReactNode;
+  /**
+   * The structural styling variant of the bullet container.
+   * Maps to the UI Kit structural tokens.
+   * @default "default"
+   */
+  bulletVariant?: "default" | "avatar" | "icon" | "icon-alternative";
+}
+
+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";