@recursica/mantine-adapter 0.18.0 → 0.20.0

package/src/components/Popover/Popover.stories.tsx

@@ -0,0 +1,133 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Popover } from "./Popover";
+import { Button } from "../Button";
+import { Text } from "../Text/Text";
+import { Stack } from "../Stack/Stack";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type PopoverStoryArgs = Record<string, any>;
+
+const meta = {
+  title: "UI-Kit/Popover",
+  component: Popover,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The `Popover` component is a composable wrapper around Mantine's Popover. It displays a dropdown panel when the user clicks or interacts with a target element.",
+      },
+    },
+  },
+  argTypes: {
+    withBeak: {
+      control: "boolean",
+      description:
+        "Whether to display a beak (arrow) pointing from the dropdown to the target.",
+    },
+    position: {
+      control: "select",
+      options: [
+        "top",
+        "top-start",
+        "top-end",
+        "bottom",
+        "bottom-start",
+        "bottom-end",
+        "left",
+        "left-start",
+        "left-end",
+        "right",
+        "right-start",
+        "right-end",
+      ],
+      description: "Dropdown position relative to target",
+    },
+    defaultOpened: {
+      control: "boolean",
+      description: "Initial opened state",
+    },
+  },
+} satisfies Meta<typeof Popover>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    withBeak: true,
+    position: "top",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: PopoverStoryArgs) => {
+    return (
+      <Popover width={250} {...args}>
+        <Popover.Target>
+          <Button variant="solid">Toggle Popover</Button>
+        </Popover.Target>
+        <Popover.Dropdown>
+          <Text size="rec-sm">
+            This is the popover content. It can contain any elements you want to
+            display when the user clicks the target.
+          </Text>
+        </Popover.Dropdown>
+      </Popover>
+    );
+  },
+};
+
+export const SolidDefault: Story = {
+  args: {
+    withBeak: true,
+    position: "top",
+    defaultOpened: true,
+  },
+  parameters: {
+    controls: { disable: true },
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: PopoverStoryArgs) => {
+    return (
+      <Stack align="center" justify="center" style={{ padding: "100px" }}>
+        <Popover width={200} {...args}>
+          <Popover.Target>
+            <Button variant="solid">Toggle Popover</Button>
+          </Popover.Target>
+          <Popover.Dropdown>
+            <Text size="rec-sm">
+              This is a static representation of an opened popover with a beak.
+            </Text>
+          </Popover.Dropdown>
+        </Popover>
+      </Stack>
+    );
+  },
+};
+
+export const WithoutBeak: Story = {
+  args: {
+    withBeak: false,
+    position: "bottom",
+    defaultOpened: true,
+  },
+  parameters: {
+    controls: { disable: true },
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: PopoverStoryArgs) => {
+    return (
+      <Stack align="center" justify="center" style={{ padding: "100px" }}>
+        <Popover width={200} {...args}>
+          <Popover.Target>
+            <Button variant="outline">Bottom Popover</Button>
+          </Popover.Target>
+          <Popover.Dropdown>
+            <Text size="rec-sm">
+              This popover is positioned at the bottom and has no beak.
+            </Text>
+          </Popover.Dropdown>
+        </Popover>
+      </Stack>
+    );
+  },
+};

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/Stack/Stack.tsx

@@ -2,8 +2,12 @@ import { forwardRef } from "react";
 import {
   Stack as MantineStack,
   type StackProps as MantineStackProps,
+  createPolymorphicComponent,
 } from "@mantine/core";
-import { type RecursicaSpacing } from "../../utils/filterStylingProps";
+import {
+  type RecursicaSpacing,
+  mapLayoutProps,
+} from "../../utils/filterStylingProps";
 import styles from "./Stack.module.css";
 
 export interface RecursicaStackProps {
@@ -23,7 +27,7 @@ export interface RecursicaStackProps {
  */
 export type StackProps = MantineStackProps & RecursicaStackProps;
 
-export const Stack = forwardRef<HTMLDivElement, StackProps>(function Stack(
+const _Stack = forwardRef<HTMLDivElement, StackProps>(function Stack(
   { children, gap = "rec-default", ...rest },
   ref,
 ) {
@@ -51,12 +55,12 @@ export const Stack = forwardRef<HTMLDivElement, StackProps>(function Stack(
       ref={ref}
       className={finalClass}
       classNames={mergedClassNames}
-      gap={gap}
-      {...rest}
+      {...mapLayoutProps({ gap, ...rest } as Record<string, unknown>)}
     >
       {children}
     </MantineStack>
   );
 });
+_Stack.displayName = "Stack";
 
-Stack.displayName = "Stack";
+export const Stack = createPolymorphicComponent<"div", StackProps>(_Stack);

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.