@recursica/adapter-mui-v7 1.0.0

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

@@ -0,0 +1,363 @@
+.root {
+  display: flex;
+  flex-direction: column;
+  gap: var(--recursica_ui-kit_components_timeline_properties_item-gap);
+  margin: 0 !important;
+  padding: 0 !important;
+}
+
+.item {
+  /* Mui gives every item a 70px min-height by default; content should drive height instead */
+  min-height: 0 !important;
+}
+
+/* Mui reserves a flex:1 spacer (via ::before) for the opposite-content column even when none is
+   rendered. Recursica's Timeline never uses TimelineOppositeContent, so neutralize it to keep the
+   bullet/connector column flush against the left edge. */
+:global(.MuiTimelineItem-root)::before {
+  content: none !important;
+  flex: 0 !important;
+  padding: 0 !important;
+}
+
+.itemBody {
+  padding: 0 0 0
+    var(--recursica_ui-kit_components_timeline_properties_bullet-content-gap) !important;
+}
+
+.itemConnector {
+  width: var(
+    --recursica_ui-kit_components_timeline_variants_selection-states_inactive_properties_connector-size
+  ) !important;
+  background-color: var(
+    --recursica_ui-kit_components_timeline_variants_selection-states_inactive_properties_colors_connector-color
+  ) !important;
+  /* `.root`'s flex `gap` (item-gap) puts real space between adjacent `<li>`s, but
+     this connector is `flex: 1` (MUI default) filling only its own `<li>`'s
+     content height — it always ended flush with its own item's bottom edge,
+     short of the next item's bullet by exactly `item-gap`. A negative
+     margin-bottom the same size as the gap grows the connector's own flex
+     size by that amount (flexbox distributes remaining main-size accounting
+     for margins, so a negative margin here hands the connector extra grow
+     space) while the *container's* own layout size is pulled back in by the
+     same amount — net effect: the rendered line visually extends the full
+     `item-gap` past its own item, reaching the next bullet. */
+  margin-bottom: calc(
+    -1 * var(--recursica_ui-kit_components_timeline_properties_item-gap)
+  ) !important;
+}
+.item[data-active] .itemConnector {
+  width: var(
+    --recursica_ui-kit_components_timeline_variants_selection-states_active_properties_connector-size
+  ) !important;
+  background-color: var(
+    --recursica_ui-kit_components_timeline_variants_selection-states_active_properties_colors_connector-color
+  ) !important;
+}
+
+.itemBullet {
+  display: flex !important;
+  align-items: center;
+  justify-content: center;
+  align-self: center !important;
+  margin: 0 !important;
+  padding: 0 !important;
+  box-shadow: none !important;
+
+  /* Default Variant */
+  .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_variants_selection-states_inactive_properties_colors_background-color
+    ) !important;
+    border-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_default_variants_selection-states_inactive_properties_colors_border-color
+    ) !important;
+  }
+  .item[data-variant="default"][data-active] & {
+    background-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_default_variants_selection-states_active_properties_colors_background-color
+    ) !important;
+    border-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_default_variants_selection-states_active_properties_colors_border-color
+    ) !important;
+  }
+
+  /* Icon Variant */
+  .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_variants_selection-states_inactive_properties_colors_background-color
+    ) !important;
+    border-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon_variants_selection-states_inactive_properties_colors_border-color
+    ) !important;
+    color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon_variants_selection-states_inactive_properties_colors_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
+      );
+    }
+  }
+  .item[data-variant="icon"][data-active] & {
+    background-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon_variants_selection-states_active_properties_colors_background-color
+    ) !important;
+    border-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon_variants_selection-states_active_properties_colors_border-color
+    ) !important;
+    color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon_variants_selection-states_active_properties_colors_icon-color
+    ) !important;
+  }
+
+  /* Icon Alternative Variant */
+  .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_variants_selection-states_inactive_properties_colors_background-color
+    ) !important;
+    border-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon-alternative_variants_selection-states_inactive_properties_colors_border-color
+    ) !important;
+    color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon-alternative_variants_selection-states_inactive_properties_colors_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
+      );
+    }
+  }
+  .item[data-variant="icon-alternative"][data-active] & {
+    background-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon-alternative_variants_selection-states_active_properties_colors_background-color
+    ) !important;
+    border-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon-alternative_variants_selection-states_active_properties_colors_border-color
+    ) !important;
+    color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_icon-alternative_variants_selection-states_active_properties_colors_icon-color
+    ) !important;
+  }
+
+  /* Avatar Variant */
+  .item[data-variant="avatar"] & {
+    /* Avatar sizing is often governed by the avatar itself, but we'll apply the radius and opacity */
+    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_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_variants_selection-states_inactive_properties_avatar-opacity
+    ) !important;
+
+    background-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_avatar_variants_selection-states_inactive_properties_colors_background-color
+    ) !important;
+    border-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_avatar_variants_selection-states_inactive_properties_colors_border-color
+    ) !important;
+  }
+  .item[data-variant="avatar"][data-active] & {
+    opacity: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_avatar_variants_selection-states_active_properties_avatar-opacity
+    ) !important;
+    background-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_avatar_variants_selection-states_active_properties_colors_background-color
+    ) !important;
+    border-color: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_avatar_variants_selection-states_active_properties_colors_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_variants_selection-states_inactive_properties_colors_title-color
+  ) !important;
+
+  /* Active Title Color */
+  .item[data-active] & {
+    color: var(
+      --recursica_ui-kit_components_timeline_variants_selection-states_active_properties_colors_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_variants_selection-states_inactive_properties_colors_description-color
+  );
+
+  .item[data-active] & {
+    color: var(
+      --recursica_ui-kit_components_timeline_variants_selection-states_active_properties_colors_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_variants_selection-states_inactive_properties_colors_timestamp-color
+  );
+
+  .item[data-active] & {
+    color: var(
+      --recursica_ui-kit_components_timeline_variants_selection-states_active_properties_colors_timestamp-color
+    );
+  }
+}

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

@@ -0,0 +1,128 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Timeline } from "./Timeline";
+
+const meta: Meta<typeof Timeline> = {
+  title: "UI-Kit/Timeline",
+  component: Timeline,
+  tags: ["autodocs"],
+  argTypes: {
+    defaultChecked: { table: { disable: true } },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Timeline>;
+
+export const Default: Story = {
+  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.test.tsx

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

package/src/components/Timeline/Timeline.tsx

@@ -0,0 +1,90 @@
+import React from "react";
+import MuiTimeline, {
+  type TimelineProps as MuiTimelineProps,
+} from "@mui/lab/Timeline";
+import {
+  filterStylingProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Timeline.module.css";
+import { TimelineItem, type TimelineItemProps } from "./TimelineItem";
+
+import { type RecursicaTimelineProps } from "@recursica/adapter-common";
+
+/**
+ * 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<HTMLUListElement>
+  > {
+  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>`, composing
+ * `TimelineSeparator`/`TimelineDot`/`TimelineConnector`/`TimelineContent` per item
+ * (via `Timeline.Item`) so the bullet marker and connecting line render the same way
+ * they do in the Mantine adapter.
+ *
+ * @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, active = -1, children, ...rest },
+    ref,
+  ) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+
+    const mergedClassNames = mergeClassNames(
+      { root: styles.root },
+      (sanitizedProps as Record<string, unknown>).classes as
+        | Partial<Record<string, string>>
+        | undefined,
+    );
+
+    const items = React.Children.toArray(children);
+    const decoratedItems = items.map((item, index) =>
+      React.isValidElement(item)
+        ? React.cloneElement(item as React.ReactElement<TimelineItemProps>, {
+            __active: active >= index,
+            __isLast: index === items.length - 1,
+          })
+        : item,
+    );
+
+    return (
+      <MuiTimeline
+        ref={ref}
+        {...(sanitizedProps as unknown as Omit<
+          MuiTimelineProps,
+          "color" | "radius" | "bulletSize" | "lineWidth"
+        >)}
+        classes={mergedClassNames}
+      >
+        {decoratedItems}
+      </MuiTimeline>
+    );
+  },
+);
+
+TimelineInner.displayName = "Timeline";
+
+export const Timeline = TimelineInner as TimelineComponent;
+Timeline.Item = TimelineItem;

package/src/components/Timeline/TimelineItem.tsx

@@ -0,0 +1,95 @@
+import React from "react";
+import MuiTimelineItem, {
+  type TimelineItemProps as MuiTimelineItemProps,
+} from "@mui/lab/TimelineItem";
+import TimelineSeparator from "@mui/lab/TimelineSeparator";
+import TimelineDot from "@mui/lab/TimelineDot";
+import TimelineConnector from "@mui/lab/TimelineConnector";
+import TimelineContent from "@mui/lab/TimelineContent";
+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" | "title"> &
+    RecursicaTimelineItemProps & {
+      /** Heading rendered above the item's description/timestamp */
+      title?: React.ReactNode;
+      /** @internal injected by `Timeline` to mark items up to `active` */
+      __active?: boolean;
+      /** @internal injected by `Timeline`; suppresses the trailing connector on the last item */
+      __isLast?: boolean;
+    }
+>;
+
+/**
+ * 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.
+ *
+ * Internally it composes Mui's `TimelineSeparator`/`TimelineDot`/`TimelineConnector`/
+ * `TimelineContent` primitives (Mui has no single "item" abstraction like Mantine's
+ * `Timeline.Item` that renders a bullet + connector on its own).
+ */
+export const TimelineItem = React.forwardRef<HTMLLIElement, TimelineItemProps>(
+  function TimelineItem(
+    {
+      overStyled = false,
+      timestamp,
+      bulletVariant = "default",
+      bullet,
+      title,
+      children,
+      __active = false,
+      __isLast = false,
+      ...rest
+    },
+    ref,
+  ) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const { className: userClassName, ...restSanitizedProps } =
+      sanitizedProps as Record<string, unknown> & { className?: string };
+
+    const content = timestamp ? (
+      <>
+        {children && <div className={styles.description}>{children}</div>}
+        <div className={styles.timestamp}>{timestamp}</div>
+      </>
+    ) : (
+      children
+    );
+
+    return (
+      <MuiTimelineItem
+        ref={ref}
+        {...(restSanitizedProps as unknown as Omit<
+          MuiTimelineItemProps,
+          "radius" | "color" | "lineVariant" | "title"
+        >)}
+        data-variant={bulletVariant}
+        data-active={__active || undefined}
+        className={
+          userClassName ? `${styles.item} ${userClassName}` : styles.item
+        }
+      >
+        <TimelineSeparator>
+          <TimelineDot className={styles.itemBullet}>{bullet}</TimelineDot>
+          {!__isLast && <TimelineConnector className={styles.itemConnector} />}
+        </TimelineSeparator>
+        <TimelineContent className={styles.itemBody}>
+          {title && <div className={styles.itemTitle}>{title}</div>}
+          <div className={styles.itemContent}>{content}</div>
+        </TimelineContent>
+      </MuiTimelineItem>
+    );
+  },
+);
+
+TimelineItem.displayName = "TimelineItem";