@recursica/mantine-adapter 0.17.0 → 0.19.0

package/src/components/Popover/Popover.tsx

@@ -0,0 +1,156 @@
+import {
+  Popover as MantinePopover,
+  type PopoverProps as MantinePopoverProps,
+  type PopoverTargetProps as MantinePopoverTargetProps,
+  type PopoverDropdownProps as MantinePopoverDropdownProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Popover.module.css";
+
+// ============================================================
+// POPOVER ROOT
+// ============================================================
+
+/**
+ * Recursica-specific props for Popover.
+ */
+export interface RecursicaPopoverProps {
+  /**
+   * Whether to display a beak (arrow) pointing from the dropdown to the target.
+   * This is the Recursica equivalent of Mantine's `withArrow`.
+   * When both `withBeak` and `withArrow` are provided, `withBeak` takes precedence.
+   */
+  withBeak?: boolean;
+}
+
+/**
+ * Recursica Popover component wrapping Mantine's composable Popover.
+ *
+ * Displays a dropdown panel when the user clicks or interacts with a target element.
+ * Uses the composable dot-notation pattern:
+ * ```tsx
+ * <Popover withBeak>
+ *   <Popover.Target>
+ *     <Button>Click me</Button>
+ *   </Popover.Target>
+ *   <Popover.Dropdown>
+ *     Content displayed in popover
+ *   </Popover.Dropdown>
+ * </Popover>
+ * ```
+ */
+export type PopoverProps = RecursicaOverStyled<
+  MantinePopoverProps & RecursicaPopoverProps
+>;
+
+const PopoverBase = function Popover({
+  overStyled = false,
+  withBeak = true,
+  ...rest
+}: PopoverProps) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+
+  // Bind CSS module classes to Mantine's internal classNames API
+  const mergedClassNames: Partial<Record<string, string>> = {
+    dropdown: styles.dropdown,
+    arrow: styles.arrow,
+  };
+
+  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];
+      }
+    });
+  }
+
+  // arrowSize must be a JS number prop — Mantine uses it for inline width/height
+  // and positioning offset (-arrowSize/2) calculations that cannot be CSS-driven.
+  // Default to 16 to match the Recursica beak-size token (16px).
+  const arrowSize =
+    ((sanitizedProps as Record<string, unknown>).arrowSize as
+      | number
+      | undefined) ?? 16;
+
+  // Resolve withBeak (Recursica) vs withArrow (Mantine).
+  // withBeak takes precedence when both are provided.
+  const withArrow = (sanitizedProps as Record<string, unknown>).withArrow as
+    | boolean
+    | undefined;
+  const resolvedWithArrow = withBeak ?? withArrow;
+
+  return (
+    <MantinePopover
+      position="top" /* Recursica default; Mantine defaults to "bottom" */
+      arrowSize={arrowSize}
+      withArrow={resolvedWithArrow}
+      classNames={mergedClassNames}
+      {...(sanitizedProps as unknown as MantinePopoverProps)}
+    />
+  );
+};
+PopoverBase.displayName = "Popover";
+
+// ============================================================
+// POPOVER TARGET
+// ============================================================
+
+/**
+ * Wrapper for the element that triggers the popover.
+ * Requires a single child element that supports ref forwarding.
+ */
+export type PopoverTargetProps = MantinePopoverTargetProps;
+
+const PopoverTarget = function PopoverTarget(props: PopoverTargetProps) {
+  return <MantinePopover.Target {...props} />;
+};
+PopoverTarget.displayName = "PopoverTarget";
+
+// ============================================================
+// POPOVER DROPDOWN
+// ============================================================
+
+/** The dropdown panel displayed from the popover. */
+export type PopoverDropdownProps =
+  RecursicaOverStyled<MantinePopoverDropdownProps>;
+
+const PopoverDropdown = function PopoverDropdown({
+  overStyled = false,
+  ...rest
+}: PopoverDropdownProps) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const classNameProp = (sanitizedProps as Record<string, unknown>)
+    .className as string | undefined;
+
+  return (
+    <MantinePopover.Dropdown
+      className={classNameProp}
+      {...(sanitizedProps as unknown as MantinePopoverDropdownProps)}
+    />
+  );
+};
+PopoverDropdown.displayName = "PopoverDropdown";
+
+// ============================================================
+// DOT NOTATION EXPORT
+// ============================================================
+
+type PopoverComponent = typeof PopoverBase & {
+  Target: typeof PopoverTarget;
+  Dropdown: typeof PopoverDropdown;
+};
+
+export const Popover = PopoverBase as PopoverComponent;
+Popover.Target = PopoverTarget;
+Popover.Dropdown = PopoverDropdown;

package/src/components/Popover/index.ts

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

package/src/components/Timeline/TIMELINE_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,13 @@
+# Timeline Implementation Notes
+
+## Architecture
+
+The `Timeline` component is a strict structural wrapper around Mantine's `<Timeline>` and `<Timeline.Item>` components.
+
+- `Timeline.tsx` intercepts overarching properties like `lineWidth` and `bulletSize` to strip them out via `overStyled`, strictly adhering to the CSS token mapping in `.item` rules instead.
+- `TimelineItem.tsx` implements a custom `timestamp` React node rendering slot to match the design system, positioning the text directly below the item's `children`.
+- `TimelineItem.tsx` supports a custom `bulletVariant` prop (`"default" | "avatar" | "icon" | "icon-alternative"`) mapped onto `data-variant` to handle CSS variations dynamically.
+
+## Limitations & Missing Tokens
+
+- **Avatar Bullet Size**: There is no specific pixel variable provided for the Avatar bullet size in the UI kit tokens (`avatar-size` evaluates to `"default"`). To maintain exact mathematical centering with Mantine's connector line `calc()` equations, the CSS falls back to inheriting the `default` bullet size (`20px`) for avatar nodes natively. If users supply a custom sized `img` tag, it must adhere to inline structural constraints or flex mappings.

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

@@ -0,0 +1,361 @@
+.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,11 +1,13 @@
 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"],
+  argTypes: {
+    defaultChecked: { table: { disable: true } },
+  },
 };
 
 export default meta;
@@ -13,5 +15,114 @@ 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>
+  ),
 };