@recursica/mantine-adapter 0.17.0 → 0.19.0

package/dist/src/OverStyling.d.ts

@@ -0,0 +1 @@
+export declare const OverStylingInfo: () => import("react/jsx-runtime").JSX.Element;

package/dist/src/Version.d.ts

@@ -0,0 +1 @@
+export declare const VersionInfo: () => import("react/jsx-runtime").JSX.Element;

package/dist/src/components/Modal/Modal.d.ts

@@ -1,3 +1,40 @@
 import { default as React } from 'react';
-export type ModalProps = React.HTMLAttributes<HTMLDivElement>;
-export declare const Modal: React.FC<ModalProps>;
+import { Modal as MantineModal, ModalProps as MantineModalProps } from '@mantine/core';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+/**
+ * Properties for the strictly-tokenized Modal component.
+ * Native Mantine abstract properties like `size`, `radius`, and `shadow` have been stripped out
+ * because they directly conflict with the non-negotiable pixel boundaries defined in the Recursica UI Kit.
+ */
+export type ModalProps = RecursicaOverStyled<Omit<MantineModalProps, "size" | "radius" | "shadow">>;
+/**
+ * The `Modal.Footer` provides a perfectly padded container for modal actions.
+ *
+ * **Recursica Abstract:**
+ * By default, this container aligns its children to the right (`justify-content: flex-end`)
+ * and applies the standard Figma button-gap spacing.
+ *
+ * > [!IMPORTANT]
+ * > **Button Hierarchy:** Recursica design language explicitly requires that the
+ * > primary action button MUST be the right-most element, with the secondary
+ * > (outline variant) action placed immediately to the left of it.
+ */
+declare const ModalFooter: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare const ModalBody: React.ForwardRefExoticComponent<Omit<import('@mantine/core').ModalBodyProps & React.RefAttributes<HTMLDivElement> & {
+    component?: any;
+    renderRoot?: (props: Record<string, any>) => React.ReactNode;
+}, "ref"> & React.RefAttributes<HTMLDivElement>>;
+interface ModalComponent extends React.ForwardRefExoticComponent<ModalProps & React.RefAttributes<HTMLDivElement>> {
+    Root: typeof MantineModal.Root;
+    Overlay: typeof MantineModal.Overlay;
+    Content: typeof MantineModal.Content;
+    Header: typeof MantineModal.Header;
+    Title: typeof MantineModal.Title;
+    CloseButton: typeof MantineModal.CloseButton;
+    Body: typeof ModalBody;
+    Footer: typeof ModalFooter;
+}
+export declare const Modal: ModalComponent & {
+    Footer: typeof ModalFooter;
+};
+export {};

package/dist/src/components/Modal/index.d.ts

@@ -0,0 +1 @@
+export * from './Modal';

package/dist/src/components/Popover/Popover.d.ts

@@ -0,0 +1,55 @@
+import { PopoverProps as MantinePopoverProps, PopoverTargetProps as MantinePopoverTargetProps, PopoverDropdownProps as MantinePopoverDropdownProps } from '@mantine/core';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+/**
+ * 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>;
+declare const PopoverBase: {
+    ({ overStyled, withBeak, ...rest }: PopoverProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+/**
+ * Wrapper for the element that triggers the popover.
+ * Requires a single child element that supports ref forwarding.
+ */
+export type PopoverTargetProps = MantinePopoverTargetProps;
+declare const PopoverTarget: {
+    (props: PopoverTargetProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+/** The dropdown panel displayed from the popover. */
+export type PopoverDropdownProps = RecursicaOverStyled<MantinePopoverDropdownProps>;
+declare const PopoverDropdown: {
+    ({ overStyled, ...rest }: PopoverDropdownProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+type PopoverComponent = typeof PopoverBase & {
+    Target: typeof PopoverTarget;
+    Dropdown: typeof PopoverDropdown;
+};
+export declare const Popover: PopoverComponent;
+export {};

package/dist/src/components/Popover/index.d.ts

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

package/dist/src/components/Timeline/Timeline.d.ts

@@ -1,3 +1,15 @@
 import { default as React } from 'react';
-export type TimelineProps = React.HTMLAttributes<HTMLDivElement>;
-export declare const Timeline: React.FC<TimelineProps>;
+import { TimelineProps as MantineTimelineProps } from '@mantine/core';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+import { TimelineItem } from './TimelineItem';
+/**
+ * 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">>;
+interface TimelineComponent extends React.ForwardRefExoticComponent<TimelineProps & React.RefAttributes<HTMLDivElement>> {
+    Item: typeof TimelineItem;
+}
+export declare const Timeline: TimelineComponent;
+export {};

package/dist/src/components/Timeline/TimelineItem.d.ts

@@ -0,0 +1,25 @@
+import { default as React } from 'react';
+import { TimelineItemProps as MantineTimelineItemProps } from '@mantine/core';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+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<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 declare const TimelineItem: React.ForwardRefExoticComponent<TimelineItemProps & React.RefAttributes<HTMLDivElement>>;

package/dist/src/components/Toast/Toast.d.ts

@@ -1,3 +1,22 @@
 import { default as React } from 'react';
-export type ToastProps = React.HTMLAttributes<HTMLDivElement>;
-export declare const Toast: React.FC<ToastProps>;
+import { NotificationProps as MantineNotificationProps } from '@mantine/core';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+export interface RecursicaToastProps {
+    /**
+     * The visual variant of the toast.
+     * @default "default"
+     */
+    variant?: "default";
+    /**
+     * Loading state is natively unsupported by Recursica UI Kit.
+     * If a loading state is required, pass a `<Loader size="sm" />` directly into the `icon` prop.
+     */
+    loading?: false;
+}
+/**
+ * Toast component wrapping Mantine's Notification.
+ *
+ * Can be used as a standalone visual component to display a notification or message.
+ */
+export type ToastProps = RecursicaOverStyled<Omit<MantineNotificationProps, "color" | "radius" | "variant" | "loading"> & RecursicaToastProps>;
+export declare const Toast: React.ForwardRefExoticComponent<ToastProps & React.RefAttributes<HTMLDivElement>>;

package/dist/src/components/Toast/index.d.ts

@@ -0,0 +1 @@
+export * from './Toast';

package/dist/src/components/index.d.ts

@@ -24,6 +24,7 @@ export * from './Modal/Modal';
 export * from './NumberInput/NumberInput';
 export * from './Pagination/Pagination';
 export * from './Panel/Panel';
+export * from './Popover';
 export * from './Radio/Radio';
 export * from './Radio/RadioGroup';
 export * from './ReadOnlyField';
@@ -41,6 +42,6 @@ export * from './TextField/TextField';
 export * from './TimePicker/TimePicker';
 export * from './Timeline/Timeline';
 export * from './Title/Title';
-export * from './Toast/Toast';
+export * from './Toast';
 export * from './Tooltip/Tooltip';
 export * from './TransferList/TransferList';

package/package.json

@@ -4,14 +4,16 @@
   "private": false,
   "homepage": "https://github.com/borderux/recursica/tree/main/packages/mantine-adapter",
   "author": "hi@borderux.com",
+  "license": "MIT",
   "bugs": {
     "url": "https://github.com/borderux/recursica/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/borderux/recursica.git"
+    "url": "git+https://github.com/borderux/recursica.git",
+    "directory": "packages/mantine-adapter"
   },
-  "version": "0.17.0",
+  "version": "0.19.0",
   "type": "module",
   "main": "./dist/mantine-adapter.cjs",
   "module": "./dist/mantine-adapter.js",
@@ -57,7 +59,6 @@
     "@storybook/addon-a11y": "^10.3.3",
     "@storybook/addon-docs": "^10.3.3",
     "@storybook/addon-mcp": "^0.4.2",
-    "@storybook/addon-onboarding": "^10.3.3",
     "@storybook/addon-vitest": "^10.3.3",
     "@storybook/react-vite": "^10.3.3",
     "@types/react": "^19.1.2",

package/src/Introduction.stories.tsx

@@ -0,0 +1,180 @@
+import type { Meta } from "@storybook/react-vite";
+import { AdaptersContent, MantineLogo } from "@recursica/storybook-template";
+import { Button } from "./components/Button/Button";
+import { VersionInfo } from "./Version";
+import { OverStylingInfo } from "./OverStyling";
+
+const DOCS_URL = "https://recursica.com";
+const FORGE_URL = "https://forge.recursica.com";
+
+const sectionStyle: React.CSSProperties = {
+  marginBottom: 32,
+};
+
+const headingStyle: React.CSSProperties = {
+  fontSize: 14,
+  fontWeight: 600,
+  color: "#333",
+  marginBottom: 8,
+  marginTop: 0,
+};
+
+const bodyStyle: React.CSSProperties = {
+  fontSize: 14,
+  lineHeight: 1.6,
+  color: "#444",
+  margin: 0,
+};
+
+const linkStyle: React.CSSProperties = {
+  color: "#0066cc",
+  textDecoration: "none",
+};
+
+function IntroductionContent() {
+  return (
+    <div style={{ padding: 24, maxWidth: 640 }}>
+      <div
+        style={{
+          display: "flex",
+          alignItems: "center",
+          gap: "16px",
+          marginBottom: "16px",
+        }}
+      >
+        <MantineLogo width={40} height={40} />
+        <div>
+          <h1 style={{ fontSize: 24, fontWeight: 700, margin: 0 }}>
+            Recursica Design System (Mantine Adapter)
+          </h1>
+          <a
+            href="https://mantine.dev"
+            target="_blank"
+            rel="noreferrer"
+            style={linkStyle}
+          >
+            mantine.dev
+          </a>
+        </div>
+      </div>
+      <p style={{ ...bodyStyle, marginBottom: 24 }}>
+        This Storybook showcases the Recursica design system implemented for the{" "}
+        <strong>Mantine UI Kit</strong>. It provides reusable components that
+        map our design tokens to Mantine's robust component layer.
+      </p>
+
+      <section style={sectionStyle}>
+        <h2 style={headingStyle}>Looking for another UI Kit?</h2>
+        <p style={bodyStyle}>
+          Are you using a different UI Kit (like Material UI)? Recursica
+          provides multiple adapters for different frameworks.
+        </p>
+        <div style={{ marginTop: "16px" }}>
+          <Button
+            component="a"
+            href="./?path=/story/introduction--adapters"
+            target="_parent"
+            variant="solid"
+          >
+            View Supported Adapters
+          </Button>
+        </div>
+      </section>
+
+      <section style={sectionStyle}>
+        <h2 style={headingStyle}>Installation</h2>
+        <p style={bodyStyle}>
+          To install the Mantine adapter in your project, run:
+        </p>
+        <pre
+          style={{
+            padding: 12,
+            backgroundColor: "#f5f5f5",
+            borderRadius: 6,
+            fontSize: 13,
+            marginTop: 8,
+          }}
+        >
+          <code>
+            npm install @recursica/mantine-adapter @mantine/core @mantine/hooks
+          </code>
+        </pre>
+      </section>
+
+      <section style={sectionStyle}>
+        <h2 style={headingStyle}>Tokens</h2>
+        <p style={bodyStyle}>
+          Raw design tokens (colors, sizes, font weights, opacities, etc.) that
+          feed the theme and components. These are the primitive values defined
+          in your token set and exposed as CSS custom properties.
+        </p>
+      </section>
+
+      <section style={sectionStyle}>
+        <h2 style={headingStyle}>Theme</h2>
+        <p style={bodyStyle}>
+          Brand and theme layer built on top of tokens. Typography types,
+          dimensions, and layout grids are defined here. Theme uses the tokens
+          and exposes both CSS variables and helper classes (e.g. typography
+          classes) for consistent styling across the product.
+        </p>
+      </section>
+
+      <section style={sectionStyle}>
+        <h2 style={headingStyle}>Configuring Recursica</h2>
+        <p style={bodyStyle}>
+          To modify the Recursica configuration (tokens, brand, theme), go to{" "}
+          <a
+            href={FORGE_URL}
+            target="_blank"
+            rel="noopener noreferrer"
+            style={linkStyle}
+          >
+            {FORGE_URL}
+          </a>
+          . Changes there drive the tokens and theme you see in this Storybook.
+        </p>
+      </section>
+
+      <section style={sectionStyle}>
+        <h2 style={headingStyle}>Documentation</h2>
+        <p style={bodyStyle}>
+          For full documentation, guides, and API reference, visit{" "}
+          <a
+            href={DOCS_URL}
+            target="_blank"
+            rel="noopener noreferrer"
+            style={linkStyle}
+          >
+            {DOCS_URL}
+          </a>
+          .
+        </p>
+      </section>
+    </div>
+  );
+}
+
+const meta = {
+  title: "Introduction",
+} satisfies Meta;
+
+export default meta;
+
+export const Welcome = {
+  render: () => <IntroductionContent />,
+};
+
+export const Adapters = {
+  render: () => <AdaptersContent />,
+};
+
+export const OverStyling = {
+  name: "Over Styling",
+  render: () => <OverStylingInfo />,
+};
+
+export const VersionInfoStory = {
+  name: "Version Info",
+  render: () => <VersionInfo />,
+};

package/src/{OverStyling.stories.tsx → OverStyling.tsx}

@@ -1,4 +1,3 @@
-import type { Meta, StoryObj } from "@storybook/react";
 import {
   Container,
   Paper,
@@ -11,7 +10,7 @@ import {
 } from "@mantine/core";
 import { Button } from "./components/Button/Button";
 
-const OverStylingInfo = () => {
+export const OverStylingInfo = () => {
   return (
     <Container size="md" py="xl">
       <Paper withBorder p="xl" radius="md">
@@ -185,12 +184,3 @@ const OverStylingInfo = () => {
     </Container>
   );
 };
-
-const meta: Meta<typeof OverStylingInfo> = {
-  title: "Introduction/Over Styling",
-  component: OverStylingInfo,
-};
-
-export default meta;
-
-export const Default: StoryObj<typeof OverStylingInfo> = {};

package/src/{Version.stories.tsx → Version.tsx}

@@ -1,4 +1,3 @@
-import type { Meta, StoryObj } from "@storybook/react";
 import ReactMarkdown from "react-markdown";
 import {
   Container,
@@ -12,7 +11,7 @@ import {
 import pkg from "../package.json";
 import changelog from "../CHANGELOG.md?raw";
 
-const VersionInfo = () => {
+export const VersionInfo = () => {
   return (
     <Container size="md" py="xl">
       <Paper withBorder p="xl" radius="md">
@@ -43,14 +42,3 @@ const VersionInfo = () => {
     </Container>
   );
 };
-
-const meta: Meta<typeof VersionInfo> = {
-  title: "Introduction/Version Info",
-  component: VersionInfo,
-};
-
-export default meta;
-
-type Story = StoryObj<typeof VersionInfo>;
-
-export const Default: Story = {};

package/src/components/Modal/MODAL_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,15 @@
+# Modal Implementation Notes
+
+## Architecture
+
+The `Modal` component strictly wraps Mantine's `<Modal>` primitive. We strip Mantine's abstract native styling props (`size`, `radius`, `shadow`) via the `overStyled` interface and strictly inject CSS variable definitions onto the internal node abstractions (`.content`, `.header`, `.body`, `.title`).
+
+## Limitations & Structural Decisions
+
+### 1. Stripped `size` Prop
+
+Mantine natively exposes an abstract `size` prop (`"sm" | "md" | "lg" | "xl"`) that scales the Modal geometry. The Recursica UI Kit explicitly dictates strict geometric bounding boxes: `max-width: 960px` and `min-width: 304px`. To enforce absolute parity with the design system, the `size` prop has been intentionally omitted from the component's interface. The width of the Modal will scale fluidly strictly between these Figma-driven pixel limits.
+
+### 2. Scroll Dividers behavior
+
+Mantine internally handles scroll state natively, dynamically showing/hiding a divider line when content overflows in `.body`. This logic is tightly coupled to React DOM measurements internally. Our component inherits this dynamic behavior rather than statically rendering a permanent divider, matching Mantine's robust overflow UX. However, we aggressively override the generated `border-bottom` via CSS modules to ensure that when it _does_ appear, it correctly utilizes the `--recursica_ui-kit_components_modal_colors_scroll-divider` variable and `--recursica_ui-kit_components_modal_properties_scroll-divider-thickness` token.

package/src/components/Modal/Modal.module.css

@@ -0,0 +1,127 @@
+.root {
+}
+
+.inner {
+  /* Mantine applies padding to inner to keep modal away from edges. We rely on content constraints. */
+}
+
+.content {
+  /* Geometric Bounds */
+  min-width: var(
+    --recursica_ui-kit_components_modal_properties_min-width
+  ) !important;
+  max-width: var(
+    --recursica_ui-kit_components_modal_properties_max-width
+  ) !important;
+  min-height: var(
+    --recursica_ui-kit_components_modal_properties_min-height
+  ) !important;
+
+  /* Restrict max-height to either the UI Kit max or the viewport bounds to force internal scrolling */
+  max-height: min(
+    var(--recursica_ui-kit_components_modal_properties_max-height),
+    calc(100vh - 4rem)
+  ) !important;
+  overflow: hidden !important;
+
+  /* Box model */
+  border-radius: var(
+    --recursica_ui-kit_components_modal_properties_border-radius
+  ) !important;
+  border-width: var(
+    --recursica_ui-kit_components_modal_properties_border-size
+  ) !important;
+  border-color: var(
+    --recursica_ui-kit_components_modal_colors_border-color
+  ) !important;
+  border-style: solid !important;
+
+  /* Appearance */
+  background-color: var(
+    --recursica_ui-kit_components_modal_colors_background
+  ) !important;
+  box-shadow: var(
+    --recursica_ui-kit_components_modal_properties_elevation
+  ) !important;
+
+  /* Internal Flex container to trap header and let body scroll */
+  display: flex !important;
+  flex-direction: column !important;
+}
+
+.header {
+  padding: var(--recursica_ui-kit_components_modal_properties_vertical-padding)
+    var(--recursica_ui-kit_components_modal_properties_horizontal-padding) !important;
+  background-color: transparent !important; /* Inherit from content */
+}
+
+.title {
+  /* Typography Class Injection */
+  composes: recursica_brand_typography_h2 from global;
+  color: var(--recursica_ui-kit_components_modal_colors_title) !important;
+}
+
+.bodyWrapper {
+  /* This is the container that overrides Mantine's native Body. It strips padding and acts as a flex column. */
+  padding: 0 !important;
+  display: flex;
+  flex-direction: column;
+  flex: 1 1 auto;
+  overflow: hidden !important;
+  min-height: 0 !important; /* Critical for flex child scrolling constraint */
+}
+
+.scrollArea {
+  padding: var(--recursica_ui-kit_components_modal_properties_vertical-padding)
+    var(--recursica_ui-kit_components_modal_properties_horizontal-padding) !important;
+
+  /* Internal scrolling */
+  flex: 1 1 auto;
+  overflow-y: auto !important;
+  min-height: 0 !important; /* Critical for flex child scrolling constraint */
+
+  /* Typography */
+  composes: recursica_brand_typography_body from global;
+  color: var(--recursica_ui-kit_components_modal_colors_content) !important;
+
+  /* Ensure button gap token is easily usable if developers use standard spacing */
+  --modal-button-gap: var(
+    --recursica_ui-kit_components_modal_properties_button-gap
+  );
+
+  /* Smooth divider transitions */
+  transition: border-color 0.15s ease;
+  border-top: var(
+      --recursica_ui-kit_components_modal_properties_scroll-divider-thickness
+    )
+    solid transparent !important;
+  border-bottom: var(
+      --recursica_ui-kit_components_modal_properties_scroll-divider-thickness
+    )
+    solid transparent !important;
+}
+
+.scrollArea[data-scrolled-top] {
+  border-top-color: var(
+    --recursica_ui-kit_components_modal_colors_scroll-divider
+  ) !important;
+}
+
+.scrollArea[data-scrolled-bottom] {
+  border-bottom-color: var(
+    --recursica_ui-kit_components_modal_colors_scroll-divider
+  ) !important;
+}
+
+.footer {
+  padding: var(--recursica_ui-kit_components_modal_properties_vertical-padding)
+    var(--recursica_ui-kit_components_modal_properties_horizontal-padding) !important;
+  background-color: transparent !important;
+  display: flex;
+  justify-content: flex-end;
+  gap: var(--recursica_ui-kit_components_modal_properties_button-gap);
+}
+
+.close {
+  /* Inherits standard icon button tokens natively, but we can override if required */
+}