@recursica/mantine-adapter 0.14.0 → 0.16.0

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

@@ -11,9 +11,15 @@ export type ButtonProps = RecursicaOverStyled<Omit<MantineButtonProps, "variant"
  * Recursica Button component wrapping Mantine's Button.
  *
  * Supports polymorphism via the `component` prop or `renderRoot` for custom element rendering.
+ * This is particularly useful when you need a button that behaves as a hyperlink (rendering an `<a>` tag)
+ * or integrates with a routing library (e.g., `react-router-dom` or Next.js), while preserving full visual styling.
+ *
  * @example
  * ```tsx
- * <Button component="a" href="/dashboard">Navigate</Button>
+ * // Renders as an <a> tag natively
+ * <Button component="a" href="/dashboard" target="_blank">Navigate</Button>
+ *
+ * // Renders using a custom router link
  * <Button renderRoot={(props) => <Link to="/home" {...props} />}>Home</Button>
  * ```
  */

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

@@ -1,3 +1,33 @@
 import { default as React } from 'react';
-export type LinkProps = React.HTMLAttributes<HTMLDivElement>;
-export declare const Link: React.FC<LinkProps>;
+import { AnchorProps as MantineAnchorProps } from '@mantine/core';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+export interface RecursicaLinkProps {
+    /**
+     * Optional leading icon to display next to the link text.
+     */
+    icon?: React.ReactNode;
+    /**
+     * The text or elements to display inside the link.
+     */
+    children?: React.ReactNode;
+}
+export type LinkProps = RecursicaOverStyled<Omit<MantineAnchorProps, "underline"> & RecursicaLinkProps>;
+/**
+ * Recursica Link component wrapping Mantine's Anchor.
+ *
+ * Supports polymorphism via the `component` prop or `renderRoot` for custom element rendering (e.g. react-router Link).
+ * @example
+ * ```tsx
+ * <Link component="a" href="https://example.com">External Link</Link>
+ * <Link renderRoot={(props) => <RouterLink to="/home" {...props} />}>Home</Link>
+ * ```
+ */
+export declare const Link: (<C = "a">(props: import('@mantine/core').PolymorphicComponentProps<C, LinkProps>) => React.ReactElement) & Omit<React.FunctionComponent<((LinkProps & {
+    component?: any;
+}) & Omit<Omit<any, "ref">, "className" | "classNames" | "style" | "styles" | "vars" | "p" | "px" | "py" | "pt" | "pb" | "pl" | "pr" | "bg" | "c" | "opacity" | "ff" | "fz" | "fw" | "lts" | "ta" | "lh" | "fs" | "tt" | "td" | "bd" | "w" | "miw" | "maw" | "h" | "mih" | "mah" | "m" | "my" | "mx" | "mt" | "mb" | "ml" | "mr" | "top" | "left" | "bottom" | "right" | "color" | "children" | "__vars" | "__size" | "hiddenFrom" | "visibleFrom" | "lightHidden" | "darkHidden" | "mod" | "ms" | "me" | "ps" | "pe" | "bdrs" | "bgsz" | "bgp" | "bgr" | "bga" | "pos" | "inset" | "display" | "flex" | "unstyled" | "variant" | "attributes" | "overStyled" | "icon" | "inherit" | "inline" | "size" | "gradient" | "component" | "__staticSelector" | "lineClamp" | "truncate"> & {
+    ref?: any;
+    renderRoot?: (props: any) => any;
+}) | (LinkProps & {
+    component: React.ElementType;
+    renderRoot?: (props: Record<string, any>) => any;
+})>, never> & Record<string, never>;

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

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

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

@@ -1,3 +1,51 @@
 import { default as React } from 'react';
-export type PaginationProps = React.HTMLAttributes<HTMLDivElement>;
-export declare const Pagination: React.FC<PaginationProps>;
+import { Pagination as MantinePagination, PaginationProps as MantinePaginationProps, PaginationRootProps as MantinePaginationRootProps } from '@mantine/core';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+import { PaginationIcon } from './Pagination.icons';
+export type PaginationProps = RecursicaOverStyled<MantinePaginationProps> & {
+    /** If set to true, displays text labels alongside the icons for next/previous/first/last edges. */
+    withLabels?: boolean;
+};
+export type PaginationRootProps = RecursicaOverStyled<MantinePaginationRootProps>;
+export type PaginationEdgeProps<T extends React.ElementType> = React.ComponentProps<T> & {
+    /** If set to true, displays text labels alongside the icon. */
+    withLabel?: boolean;
+    icon?: any;
+};
+declare const _PaginationRoot: React.ForwardRefExoticComponent<PaginationRootProps & React.RefAttributes<HTMLDivElement>>;
+declare const _PaginationNext: React.ForwardRefExoticComponent<{
+    /** If set to true, displays text labels alongside the icon. */
+    withLabel?: boolean;
+    icon?: any;
+} & React.RefAttributes<HTMLButtonElement>>;
+declare const _PaginationPrevious: React.ForwardRefExoticComponent<{
+    /** If set to true, displays text labels alongside the icon. */
+    withLabel?: boolean;
+    icon?: any;
+} & React.RefAttributes<HTMLButtonElement>>;
+declare const _PaginationFirst: React.ForwardRefExoticComponent<{
+    /** If set to true, displays text labels alongside the icon. */
+    withLabel?: boolean;
+    icon?: any;
+} & React.RefAttributes<HTMLButtonElement>>;
+declare const _PaginationLast: React.ForwardRefExoticComponent<{
+    /** If set to true, displays text labels alongside the icon. */
+    withLabel?: boolean;
+    icon?: any;
+} & React.RefAttributes<HTMLButtonElement>>;
+declare const _Pagination: React.ForwardRefExoticComponent<PaginationProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * Recursica Pagination component wrapping Mantine's Pagination.
+ */
+export declare const Pagination: typeof _Pagination & {
+    Root: typeof _PaginationRoot;
+    Items: typeof MantinePagination.Items;
+    Control: typeof MantinePagination.Control;
+    Dots: typeof MantinePagination.Dots;
+    Next: typeof _PaginationNext;
+    Previous: typeof _PaginationPrevious;
+    First: typeof _PaginationFirst;
+    Last: typeof _PaginationLast;
+    Icon: typeof PaginationIcon;
+};
+export {};

package/dist/src/components/Pagination/Pagination.icons.d.ts

@@ -0,0 +1,8 @@
+export type PaginationIconType = "next" | "prev" | "first" | "last";
+export declare const PaginationIcon: ({ type, className, ...props }: React.ComponentProps<"svg"> & {
+    type: PaginationIconType;
+}) => import("react/jsx-runtime").JSX.Element;
+export declare const NextWithLabel: (props: any) => import("react/jsx-runtime").JSX.Element;
+export declare const PrevWithLabel: (props: any) => import("react/jsx-runtime").JSX.Element;
+export declare const FirstWithLabel: (props: any) => import("react/jsx-runtime").JSX.Element;
+export declare const LastWithLabel: (props: any) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1 @@
+export { Pagination, type PaginationProps, type PaginationRootProps, } from './Pagination';

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

@@ -1,9 +1,17 @@
 import { Drawer as MantineDrawer, DrawerProps as MantineDrawerProps } from '@mantine/core';
 import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+export interface RecursicaPanelProps extends MantineDrawerProps {
+    /**
+     * If true, forces the header text to a single line and truncates with an ellipsis.
+     * Note: While the prop is named `wrapHeaderText` for backward compatibility,
+     * setting it to `true` actually PREVENTS wrapping (it forces truncation).
+     */
+    wrapHeaderText?: boolean;
+}
 /**
  * Recursica Panel root props. Extends Mantine Drawer.
  */
-export type PanelProps = RecursicaOverStyled<MantineDrawerProps>;
+export type PanelProps = RecursicaOverStyled<RecursicaPanelProps>;
 /**
  * Recursica Panel component wrapping Mantine's Drawer.
  *
@@ -31,7 +39,7 @@ export type PanelProps = RecursicaOverStyled<MantineDrawerProps>;
  * - `Panel.Stack` — Stacked drawer context
  */
 declare const PanelBase: {
-    ({ overStyled, position, keepMounted, ...rest }: PanelProps): import("react/jsx-runtime").JSX.Element;
+    ({ overStyled, position, keepMounted, wrapHeaderText, ...rest }: PanelProps): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };
 export type PanelFooterProps = RecursicaOverStyled<React.HTMLAttributes<HTMLDivElement>>;

package/package.json

@@ -11,7 +11,7 @@
     "type": "git",
     "url": "git+https://github.com/borderux/recursica.git"
   },
-  "version": "0.14.0",
+  "version": "0.16.0",
   "type": "module",
   "main": "./dist/mantine-adapter.cjs",
   "module": "./dist/mantine-adapter.js",

package/src/components/Button/Button.stories.tsx

@@ -101,3 +101,14 @@ export const DisabledSolid: Story = {
     disabled: true,
   },
 };
+
+export const PolymorphicAsLink: Story = {
+  args: {
+    children: "Button as Link",
+    variant: "solid",
+    size: "default",
+    component: "a",
+    href: "https://example.com",
+    target: "_blank",
+  },
+};

package/src/components/Button/Button.tsx

@@ -123,9 +123,15 @@ _Button.displayName = "Button";
  * Recursica Button component wrapping Mantine's Button.
  *
  * Supports polymorphism via the `component` prop or `renderRoot` for custom element rendering.
+ * This is particularly useful when you need a button that behaves as a hyperlink (rendering an `<a>` tag)
+ * or integrates with a routing library (e.g., `react-router-dom` or Next.js), while preserving full visual styling.
+ *
  * @example
  * ```tsx
- * <Button component="a" href="/dashboard">Navigate</Button>
+ * // Renders as an <a> tag natively
+ * <Button component="a" href="/dashboard" target="_blank">Navigate</Button>
+ *
+ * // Renders using a custom router link
  * <Button renderRoot={(props) => <Link to="/home" {...props} />}>Home</Button>
  * ```
  */

package/src/components/Card/Card.module.css

@@ -33,6 +33,7 @@
   border-bottom: var(--recursica_ui-kit_components_card_properties_divider-size)
     solid
     var(--recursica_ui-kit_components_card_properties_colors_divider-color);
+  composes: recursica_brand_typography_h3 from global;
 }
 
 .footer {

package/src/components/Card/Card.stories.tsx

@@ -2,6 +2,8 @@ import type { Meta, StoryObj } from "@storybook/react";
 import { Card } from "./Card";
 import { Layer } from "@recursica/adapter-common";
 import { Button } from "../Button/Button";
+import { Group } from "../Group/Group";
+import { Text } from "../Text/Text";
 
 const meta: Meta<typeof Card> = {
   title: "UI-Kit/Card",
@@ -32,46 +34,33 @@ export const Default: Story = {
   args: {},
   render: ({ ...args }) => {
     return (
-      <Layer
-        layer={0}
+      <div
         style={{
           padding: "48px",
           backgroundColor: "var(--recursica_brand_palettes_neutral_050)",
         }}
       >
-        <Card {...args}>
-          <Card.Header>
-            <span style={{ fontWeight: 500, fontSize: "1.125rem" }}>
-              Customer Activity Report
-            </span>
-          </Card.Header>
-          <Card.Content>
-            <p>
-              Card inner section content body. Notice how this acts as padded
-              content natively based on the overarching properties. Recursica's
-              vertical gutter governs vertical spacing between siblings in the
-              flex container.
-            </p>
-            <p>Another section showing the vertical gutter spacing.</p>
-          </Card.Content>
-          <Card.Footer>
-            <div
-              style={{
-                display: "flex",
-                justifyContent: "space-between",
-                alignItems: "center",
-                marginTop: "16px",
-                marginBottom: "8px",
-              }}
-            >
-              <span style={{ color: "#868e96", fontSize: "0.75rem" }}>
-                Generated today
-              </span>
-              <Button variant="solid">View Details</Button>
-            </div>
-          </Card.Footer>
-        </Card>
-      </Layer>
+        <Layer layer={0}>
+          <Card {...args}>
+            <Card.Header>Customer Activity Report</Card.Header>
+            <Card.Content>
+              <Text>
+                Card inner section content body. Notice how this acts as padded
+                content natively based on the overarching properties.
+                Recursica's vertical gutter governs vertical spacing between
+                siblings in the flex container.
+              </Text>
+              <Text>Another section showing the vertical gutter spacing.</Text>
+            </Card.Content>
+            <Card.Footer>
+              <Group justify="space-between" align="center">
+                <Text variant="caption">Generated today</Text>
+                <Button variant="solid">View Details</Button>
+              </Group>
+            </Card.Footer>
+          </Card>
+        </Layer>
+      </div>
     );
   },
 };
@@ -80,29 +69,26 @@ export const HeaderlessAndFooterless: Story = {
   args: {},
   render: ({ ...args }) => {
     return (
-      <Layer
-        layer={0}
+      <div
         style={{
           padding: "48px",
           backgroundColor: "var(--recursica_brand_palettes_neutral_050)",
         }}
       >
-        <Card {...args}>
-          <Card.Content>
-            <span style={{ fontWeight: 500, fontSize: "1.125rem" }}>
-              Notice
-            </span>
-            <p>
-              This is a completely generic card payload dropping the Header and
-              Footer specific elements, simply acting as a padded elevation
-              boundary box directly mirroring native composability!
-            </p>
-            <Button variant="solid" mt="rec-md">
-              Acknowledge
-            </Button>
-          </Card.Content>
-        </Card>
-      </Layer>
+        <Layer layer={0}>
+          <Card {...args}>
+            <Card.Content>
+              <Text variant="subtitle">Notice</Text>
+              <Text>
+                This is a completely generic card payload dropping the Header
+                and Footer specific elements, simply acting as a padded
+                elevation boundary box directly mirroring native composability!
+              </Text>
+              <Button variant="solid">Acknowledge</Button>
+            </Card.Content>
+          </Card>
+        </Layer>
+      </div>
     );
   },
 };
@@ -122,17 +108,21 @@ export const LayerDemonstration: Story = {
         <Layer layer={1}>
           <Card {...args}>
             <Card.Header>Layer 1 Wrapper</Card.Header>
-            <p>Content inside layer 1 card.</p>
+            <Card.Content>
+              <Text>Content inside layer 1 card.</Text>
+            </Card.Content>
           </Card>
         </Layer>
 
         <Layer layer={2}>
           <Card {...args}>
             <Card.Header>Layer 2 Wrapper</Card.Header>
-            <p>
-              Content inside layer 2 card exposing a higher elevation drop
-              shadow inherently cascaded.
-            </p>
+            <Card.Content>
+              <Text>
+                Content inside layer 2 card exposing a higher elevation drop
+                shadow inherently cascaded.
+              </Text>
+            </Card.Content>
           </Card>
         </Layer>
       </div>

package/src/components/Link/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,26 @@
+# Link Component Implementation Notes
+
+## Missing States in Design Tokens
+
+Currently, the design tokens (`recursica_variables_scoped.css`) only provide states for:
+
+- `default`
+- `hover`
+- `visited`
+- `visited-hover`
+
+There are no tokens for the `active` or `focus` states. If these are needed, they must be added to the Figma variables and exported via the token pipeline. The component relies on the browser's default focus outline for accessibility unless overriden by a global reset.
+
+## Overriding Mantine's underline Prop
+
+Mantine's `Anchor` component uses `underline="hover"` by default. Because our design system specifies exact `text-decoration` styles via CSS tokens, we explicitly pass `underline="never"` to the underlying Mantine component. This prevents Mantine from injecting its own text-decoration inline or via generic classnames, ensuring our scoped CSS remains the single source of truth.
+
+## Base Layout
+
+Mantine's `Anchor` renders an inline element by default and does not natively support `leftSection` like the `Button` component. To support an optional `icon` alongside the text, we enforce a baseline layout of `display: inline-flex` and `align-items: center` in `Link.module.css`.
+
+When an icon is present, the component conditionally passes a `data-has-icon` attribute to the root element. The CSS module uses this attribute to apply the `icon-text-gap` token via the CSS `gap` property.
+
+## Inner Wrappers
+
+The icon and children are wrapped in internal `<span>` tags (`.iconWrapper` and `.labelText` respectively). This follows the component development guide for structural robustness, allowing us to enforce specific sizing on the icon and intrinsic text truncation behavior if the link is placed in a bounded container.

package/src/components/Link/Link.module.css

@@ -0,0 +1,133 @@
+/* 
+HARDCODED VALUES:
+- display: inline-flex; (Base layout to align icon and text correctly)
+- align-items: center;
+- cursor: pointer;
+- text-decoration: none; (Overridden by our design tokens instead of using Mantine's underline prop)
+- color: inherit; (Reset before applying token)
+*/
+
+.root {
+  /* HARDCODE: base layout to support optional icon gaps */
+  display: inline-flex;
+  align-items: center;
+  cursor: pointer;
+
+  /* HARDCODE: Reset underline and color so we can explicitly use our tokens */
+  text-decoration: none;
+  color: inherit;
+
+  /* Typography Default Tokens */
+  font-family: var(
+    --recursica_ui-kit_components_link_properties_text_font-family
+  );
+  font-size: var(--recursica_ui-kit_components_link_properties_text_font-size);
+  letter-spacing: var(
+    --recursica_ui-kit_components_link_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_link_properties_text_line-height
+  );
+
+  /* Default State Tokens */
+  font-style: var(
+    --recursica_ui-kit_components_link_variants_states_default_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_link_variants_states_default_properties_text_font-weight
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_link_variants_states_default_properties_text_text-decoration
+  );
+  color: var(
+    --recursica_ui-kit_components_link_variants_states_default_properties_colors_text
+  );
+}
+
+.root[data-has-icon] {
+  gap: var(--recursica_ui-kit_components_link_properties_icon-text-gap);
+}
+
+.root:hover {
+  /* Reset Mantine's potential hover override */
+  text-decoration: var(
+    --recursica_ui-kit_components_link_variants_states_hover_properties_text_text-decoration
+  );
+  font-style: var(
+    --recursica_ui-kit_components_link_variants_states_hover_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_link_variants_states_hover_properties_text_font-weight
+  );
+  color: var(
+    --recursica_ui-kit_components_link_variants_states_hover_properties_colors_text
+  );
+}
+
+.root:visited {
+  text-decoration: var(
+    --recursica_ui-kit_components_link_variants_states_visited_properties_text_text-decoration
+  );
+  font-style: var(
+    --recursica_ui-kit_components_link_variants_states_visited_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_link_variants_states_visited_properties_text_font-weight
+  );
+  color: var(
+    --recursica_ui-kit_components_link_variants_states_visited_properties_colors_text
+  );
+}
+
+.root:visited:hover {
+  text-decoration: var(
+    --recursica_ui-kit_components_link_variants_states_visited-hover_properties_text_text-decoration
+  );
+  font-style: var(
+    --recursica_ui-kit_components_link_variants_states_visited-hover_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_link_variants_states_visited-hover_properties_text_font-weight
+  );
+  color: var(
+    --recursica_ui-kit_components_link_variants_states_visited-hover_properties_colors_text
+  );
+}
+
+/* Icon Support */
+.iconWrapper {
+  /* HARDCODE: maintain intrinsic icon bounds */
+  display: flex;
+  align-items: center;
+  justify-content: center;
+
+  width: var(--recursica_ui-kit_components_link_properties_icon-size);
+  height: var(--recursica_ui-kit_components_link_properties_icon-size);
+  color: var(
+    --recursica_ui-kit_components_link_variants_states_default_properties_colors_icon
+  );
+}
+
+.root:hover .iconWrapper {
+  color: var(
+    --recursica_ui-kit_components_link_variants_states_hover_properties_colors_icon
+  );
+}
+
+.root:visited .iconWrapper {
+  color: var(
+    --recursica_ui-kit_components_link_variants_states_visited_properties_colors_icon
+  );
+}
+
+.root:visited:hover .iconWrapper {
+  color: var(
+    --recursica_ui-kit_components_link_variants_states_visited-hover_properties_colors_icon
+  );
+}
+
+/* Label text wrapper */
+.labelText {
+  /* HARDCODE: allows text truncation if bounded */
+  min-width: 0;
+}

package/src/components/Link/Link.stories.tsx

@@ -1,17 +1,59 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable @typescript-eslint/no-unused-vars */
 import type { Meta, StoryObj } from "@storybook/react";
 import { Link } from "./Link";
-import { ComingSoon } from "@recursica/storybook-template";
+import { Text } from "@mantine/core";
 
 const meta: Meta<typeof Link> = {
-  title: "UI-Kit/🚧 Link",
+  title: "UI-Kit/Link",
   component: Link,
   tags: ["autodocs"],
+  args: {
+    children: "Link text",
+    href: "#",
+  },
+  render: ({ withLayer, layer, ...args }: any) => <Link {...args} />,
 };
 
 export default meta;
 
 type Story = StoryObj<typeof Link>;
 
-export const Default: Story = {
-  render: () => <ComingSoon componentName="Link" />,
+export const Default: Story = {};
+
+export const WithIcon: Story = {
+  args: {
+    icon: (
+      <svg
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path>
+        <path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path>
+      </svg>
+    ),
+    children: "Link with Icon",
+  },
+};
+
+export const Polymorphic: Story = {
+  args: {
+    component: "button",
+    onClick: () => alert("Button clicked!"),
+    children: "Rendered as <button>",
+  },
+};
+
+export const InlineText: Story = {
+  render: () => (
+    <Text>
+      Here is some text with an <Link href="#">inline link</Link> inside it.
+    </Text>
+  ),
 };