@recursica/adapter-mantine-v8 1.0.0

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

@@ -0,0 +1,373 @@
+.root {
+  display: flex;
+  flex-direction: column;
+  /* Mantine drives item spacing (.item's margin-top) AND the connector line's bridging offset
+     (.item::before's negative bottom) off the SAME --mantine-spacing-xl variable. Overriding it
+     here (rather than adding a flex gap) keeps both in sync automatically instead of introducing
+     a visible break in the connector line. */
+  --mantine-spacing-xl: var(
+    --recursica_ui-kit_components_timeline_properties_item-gap
+  );
+}
+
+.item {
+  /* Mantine uses these vars to calculate the exact left: position of the connector line */
+  --tl-line-width: var(
+    --recursica_ui-kit_components_timeline_variants_selection-states_inactive_properties_connector-size
+  ) !important;
+
+  &[data-active] {
+    --tl-line-width: var(
+      --recursica_ui-kit_components_timeline_variants_selection-states_active_properties_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;
+  }
+  /* EXEMPTIONS:
+     - The avatar variant's own avatar-size token is ignored — sizing is deliberately pinned to
+       the default bullet-size above (not the avatar's own size) to keep the connector line
+       aligned across bullet variants; the child Avatar component governs its own visual size. */
+  /* recursica-ignore: --recursica_ui-kit_components_timeline-bullet_variants_types_avatar_properties_avatar-size */
+
+  /* Control connector lines via the item ::before pseudo-element */
+  /* Inactive connector */
+  &::before {
+    border-left-width: var(
+      --recursica_ui-kit_components_timeline_variants_selection-states_inactive_properties_connector-size
+    ) !important;
+    border-left-color: var(
+      --recursica_ui-kit_components_timeline_variants_selection-states_inactive_properties_colors_connector-color
+    ) !important;
+  }
+
+  /* Active connector */
+  &[data-active]::before {
+    border-left-width: var(
+      --recursica_ui-kit_components_timeline_variants_selection-states_active_properties_connector-size
+    ) !important;
+    border-left-color: var(
+      --recursica_ui-kit_components_timeline_variants_selection-states_active_properties_colors_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_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;
+  }
+  :global(.mantine-Timeline-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 */
+  :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_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
+      );
+    }
+  }
+  :global(.mantine-Timeline-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 */
+  :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_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
+      );
+    }
+  }
+  :global(.mantine-Timeline-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 */
+  :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_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;
+  }
+  :global(.mantine-Timeline-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 */
+  :global(.mantine-Timeline-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
+  );
+
+  :global(.mantine-Timeline-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
+  );
+
+  :global(.mantine-Timeline-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,73 @@
+import React from "react";
+import {
+  Timeline as MantineTimeline,
+  type TimelineProps as MantineTimelineProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Timeline.module.css";
+import { TimelineItem } from "./TimelineItem";
+
+import { type RecursicaTimelineProps } from "@recursica/adapter-common";
+
+/**
+ * Properties for the strictly-tokenized Timeline component.
+ * Native Mantine 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<MantineTimelineProps, "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 Mantine'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<HTMLDivElement, TimelineProps>(
+  function Timeline({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    const mergedClassNames = mergeClassNames(
+      { root: styles.root },
+      restRecord.classNames as Partial<Record<string, string>> | undefined,
+    );
+
+    return (
+      <MantineTimeline
+        ref={ref}
+        {...(sanitizedProps as unknown as Omit<
+          MantineTimelineProps,
+          "color" | "radius" | "bulletSize" | "lineWidth"
+        >)}
+        classNames={mergedClassNames}
+      />
+    );
+  },
+);
+
+TimelineInner.displayName = "Timeline";
+
+export const Timeline = TimelineInner as TimelineComponent;
+Timeline.Item = TimelineItem;

package/src/components/Timeline/TimelineItem.tsx

@@ -0,0 +1,79 @@
+import React from "react";
+import {
+  TimelineItem as MantineTimelineItem,
+  type TimelineItemProps as MantineTimelineItemProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Timeline.module.css";
+
+import { type RecursicaTimelineItemProps } from "@recursica/adapter-common";
+
+export type TimelineItemProps = RecursicaOverStyled<
+  Omit<MantineTimelineItemProps, "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 restRecord = sanitizedProps as Record<string, unknown>;
+
+    const mergedClassNames = mergeClassNames(
+      {
+        item: styles.item,
+        itemBody: styles.itemBody,
+        itemContent: styles.itemContent,
+        itemBullet: styles.itemBullet,
+        itemTitle: styles.itemTitle,
+      },
+      restRecord.classNames as Partial<Record<string, string>> | undefined,
+    );
+
+    // 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 (
+      <MantineTimelineItem
+        ref={ref}
+        {...(sanitizedProps as unknown as Omit<
+          MantineTimelineItemProps,
+          "radius" | "color" | "lineVariant"
+        >)}
+        classNames={mergedClassNames}
+        data-variant={bulletVariant}
+      >
+        {content}
+      </MantineTimelineItem>
+    );
+  },
+);
+
+TimelineItem.displayName = "TimelineItem";