@recursica/mantine-adapter 0.13.1 → 0.15.0

package/src/components/Panel/Panel.stories.tsx

@@ -1,17 +1,227 @@
+import { useState } from "react";
 import type { Meta, StoryObj } from "@storybook/react";
-import { Panel } from "./Panel";
-import { ComingSoon } from "@recursica/storybook-template";
+import { Panel, type PanelProps } from "./Panel";
+import { Button } from "../Button";
+import { Text } from "../Text/Text";
 
-const meta: Meta<typeof Panel> = {
-  title: "UI-Kit/🚧 Panel",
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type PanelStoryArgs = Record<string, any>;
+
+const meta: Meta = {
+  title: "UI-Kit/Panel",
   component: Panel,
   tags: ["autodocs"],
+  argTypes: {
+    position: {
+      control: "select",
+      options: ["left", "right", "top", "bottom"],
+      description: "Side of the screen the panel slides in from.",
+    },
+    title: {
+      control: "text",
+      description: "Panel title displayed in the header.",
+    },
+    withOverlay: {
+      control: "boolean",
+      description: "Whether to display a background overlay.",
+    },
+    withCloseButton: {
+      control: "boolean",
+      description: "Whether to display the close button in the header.",
+    },
+    wrapHeaderText: {
+      control: "boolean",
+      description:
+        "If true, forces the header text to a single line and truncates with an ellipsis.",
+    },
+    // Hide auto-detected HTML attributes
+    defaultChecked: { table: { disable: true } },
+    defaultValue: { table: { disable: true } },
+    suppressContentEditableWarning: { table: { disable: true } },
+    suppressHydrationWarning: { table: { disable: true } },
+  },
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component: `
+The \`Panel\` component slides in or expands from the edge of the screen to reveal additional content or functionality. Built on Mantine's \`Drawer\`, it enforces Recursica design tokens for styling.
+
+### Anatomy
+1. **Header** — Title and close icon, remains fixed on scroll
+2. **Divider** — Separates header/footer from content
+3. **Body (Slot)** — Scrollable content area for custom content
+4. **Footer** — Fixed action buttons (Recursica-specific)
+
+### Usage
+\`\`\`tsx
+const [opened, { open, close }] = useDisclosure(false);
+
+<Button onClick={open}>Open Panel</Button>
+<Panel opened={opened} onClose={close} title="Settings" position="right">
+  Content goes here
+  <Panel.Footer>
+    <Button variant="outline">Cancel</Button>
+    <Button variant="solid">Save</Button>
+  </Panel.Footer>
+</Panel>
+\`\`\`
+        `,
+      },
+    },
+  },
 };
 
 export default meta;
 
-type Story = StoryObj<typeof Panel>;
+type Story = StoryObj<PanelStoryArgs>;
 
 export const Default: Story = {
-  render: () => <ComingSoon componentName="Panel" />,
+  args: {
+    position: "right",
+    title: "Panel Title",
+    withOverlay: true,
+    withCloseButton: true,
+    wrapHeaderText: false,
+  },
+  render: ({ wrapHeaderText, ...args }: PanelStoryArgs) => {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const [opened, setOpened] = useState(false);
+
+    return (
+      <>
+        <Button variant="solid" onClick={() => setOpened(true)}>
+          Open Panel
+        </Button>
+        <Panel
+          opened={opened}
+          onClose={() => setOpened(false)}
+          title="Panel Title"
+          position="right"
+          wrapHeaderText={wrapHeaderText}
+          {...(args as PanelProps)}
+        >
+          <Text>
+            This is the panel body content area. Panels slide in from the edge
+            of the screen to reveal supplementary information, navigation
+            options, or toolsets.
+          </Text>
+          <Panel.Footer>
+            <Button variant="outline" onClick={() => setOpened(false)}>
+              Cancel
+            </Button>
+            <Button variant="solid">Save</Button>
+          </Panel.Footer>
+        </Panel>
+      </>
+    );
+  },
+};
+
+export const LeftPosition: Story = {
+  args: {
+    position: "left",
+    title: "Navigation",
+    withOverlay: true,
+    withCloseButton: true,
+    wrapHeaderText: false,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: PanelStoryArgs) => {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const [opened, setOpened] = useState(false);
+
+    return (
+      <>
+        <Button variant="outline" onClick={() => setOpened(true)}>
+          Open Left Panel
+        </Button>
+        <Panel
+          {...(args as PanelProps)}
+          opened={opened}
+          onClose={() => setOpened(false)}
+        >
+          <Text>
+            A panel sliding in from the left, commonly used for navigation menus
+            or sidebars.
+          </Text>
+        </Panel>
+      </>
+    );
+  },
+};
+
+export const ScrollableContent: Story = {
+  args: {
+    position: "right",
+    title: "Scrollable Panel",
+    withOverlay: true,
+    withCloseButton: true,
+    wrapHeaderText: false,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: PanelStoryArgs) => {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const [opened, setOpened] = useState(false);
+
+    return (
+      <>
+        <Button variant="solid" onClick={() => setOpened(true)}>
+          Open Scrollable Panel
+        </Button>
+        <Panel
+          {...(args as PanelProps)}
+          opened={opened}
+          onClose={() => setOpened(false)}
+        >
+          {Array.from({ length: 20 }).map((_, i) => (
+            <p key={i} style={{ marginBottom: "1rem" }}>
+              Paragraph {i + 1}: This is sample content to demonstrate the
+              scrollable behavior of the panel when content exceeds the viewport
+              height.
+            </p>
+          ))}
+          <Panel.Footer>
+            <Button variant="outline" onClick={() => setOpened(false)}>
+              Close
+            </Button>
+            <Button variant="solid">Apply</Button>
+          </Panel.Footer>
+        </Panel>
+      </>
+    );
+  },
+};
+
+export const LongTitle: Story = {
+  args: {
+    position: "right",
+    title:
+      "This is a ridiculously long panel title designed to test how the header CSS handles text overflow and whether it truncates correctly or breaks the layout",
+    withOverlay: true,
+    withCloseButton: true,
+    wrapHeaderText: true,
+  },
+  render: ({ ...args }: PanelStoryArgs) => {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const [opened, setOpened] = useState(false);
+
+    return (
+      <>
+        <Button variant="solid" onClick={() => setOpened(true)}>
+          Open Long Title Panel
+        </Button>
+        <Panel
+          {...(args as PanelProps)}
+          opened={opened}
+          onClose={() => setOpened(false)}
+        >
+          <Text>
+            Check the header to see if the long title is handled gracefully
+            without pushing the close button off screen.
+          </Text>
+        </Panel>
+      </>
+    );
+  },
 };

package/src/components/Panel/Panel.tsx

@@ -1,7 +1,156 @@
-import React from "react";
+import { forwardRef } from "react";
+import {
+  Drawer as MantineDrawer,
+  type DrawerProps as MantineDrawerProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Panel.module.css";
 
-export type PanelProps = React.HTMLAttributes<HTMLDivElement>;
+// ============================================================
+// PANEL (Drawer)
+// ============================================================
 
-export const Panel: React.FC<PanelProps> = (props) => {
-  return <div {...props}>Panel</div>;
+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<RecursicaPanelProps>;
+
+/**
+ * Recursica Panel component wrapping Mantine's Drawer.
+ *
+ * Panels slide in or expand from the edge of the screen to reveal
+ * additional content or functionality. They are commonly used to provide
+ * supplementary information, navigation options, or toolsets without
+ * cluttering the main interface.
+ *
+ * ```tsx
+ * <Panel opened={opened} onClose={close} title="Panel Title" position="right">
+ *   <Panel.Body>
+ *     Content goes here
+ *   </Panel.Body>
+ * </Panel>
+ * ```
+ *
+ * Mantine Drawer sub-components available via dot-notation:
+ * - `Panel.Header` — Top section with title and close button
+ * - `Panel.Title` — Title text within the header
+ * - `Panel.CloseButton` — Close button within the header
+ * - `Panel.Body` — Scrollable body content area
+ * - `Panel.Content` — Outer content container
+ * - `Panel.Overlay` — Background overlay
+ * - `Panel.Root` — Root element for advanced composition
+ * - `Panel.Stack` — Stacked drawer context
+ */
+const PanelBase = function Panel({
+  overStyled = false,
+  position = "right",
+  keepMounted = true,
+  wrapHeaderText = false,
+  ...rest
+}: PanelProps) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+
+  // Bind CSS module classes to Mantine's internal classNames API
+  const mergedClassNames: Partial<Record<string, string>> = {
+    content: styles.content,
+    header: styles.header,
+    title: wrapHeaderText ? styles.titleTruncate : styles.title,
+    body: styles.body,
+    inner: styles.inner,
+  };
+
+  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];
+      }
+    });
+  }
+
+  return (
+    <MantineDrawer
+      position={position} /* Recursica default: right; Mantine default: left */
+      keepMounted={keepMounted}
+      closeOnClickOutside={rest.closeOnClickOutside ?? Boolean(rest.opened)}
+      {...(sanitizedProps as unknown as MantineDrawerProps)}
+      classNames={mergedClassNames}
+    />
+  );
+};
+PanelBase.displayName = "Panel";
+
+// ============================================================
+// PANEL FOOTER (custom — Mantine Drawer has no Footer sub-component)
+// ============================================================
+
+export type PanelFooterProps = RecursicaOverStyled<
+  React.HTMLAttributes<HTMLDivElement>
+>;
+
+/**
+ * Panel footer section with action buttons.
+ * Separated from the body by a divider. Remains fixed at the bottom.
+ * This is a Recursica-specific sub-component; Mantine Drawer does not
+ * natively provide a footer.
+ */
+export const PanelFooter = forwardRef<HTMLDivElement, PanelFooterProps>(
+  function PanelFooter({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const classNameProp = (sanitizedProps as Record<string, unknown>)
+      .className as string | undefined;
+
+    const finalClassName = classNameProp
+      ? `${styles.footer} ${classNameProp}`
+      : styles.footer;
+
+    return <div ref={ref} className={finalClassName} {...sanitizedProps} />;
+  },
+);
+PanelFooter.displayName = "PanelFooter";
+
+// ============================================================
+// DOT NOTATION EXPORT
+// ============================================================
+
+type PanelComponent = typeof PanelBase & {
+  Root: typeof MantineDrawer.Root;
+  Overlay: typeof MantineDrawer.Overlay;
+  Content: typeof MantineDrawer.Content;
+  Header: typeof MantineDrawer.Header;
+  Title: typeof MantineDrawer.Title;
+  CloseButton: typeof MantineDrawer.CloseButton;
+  Body: typeof MantineDrawer.Body;
+  Stack: typeof MantineDrawer.Stack;
+  Footer: typeof PanelFooter;
 };
+
+export const Panel = PanelBase as PanelComponent;
+Panel.Root = MantineDrawer.Root;
+Panel.Overlay = MantineDrawer.Overlay;
+Panel.Content = MantineDrawer.Content;
+Panel.Header = MantineDrawer.Header;
+Panel.Title = MantineDrawer.Title;
+Panel.CloseButton = MantineDrawer.CloseButton;
+Panel.Body = MantineDrawer.Body;
+Panel.Stack = MantineDrawer.Stack;
+Panel.Footer = PanelFooter;

package/src/components/TextArea/TextArea.module.css

@@ -100,9 +100,6 @@
   );
 
   outline: none;
-  transition:
-    border-color 0.15s ease,
-    background-color 0.15s ease;
 }
 
 .input::placeholder {

package/src/components/TextField/TextField.module.css

@@ -100,9 +100,6 @@
   );
 
   outline: none;
-  transition:
-    border-color 0.15s ease,
-    background-color 0.15s ease;
 }
 
 .input::placeholder {

package/src/components/Tooltip/TOOLTIP_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,85 @@
+# Tooltip – Implementation Notes
+
+Decisions and design tweaks strictly tailored for the UI Kit's Tooltip wrapped against `@mantine/core`. This is a living document that tracks _why_ specific logic decisions exist.
+
+---
+
+## 1. Single Component API (Not Composable)
+
+**Decision:** Unlike HoverCard (which uses `HoverCard` + `HoverCard.Target` + `HoverCard.Dropdown`), Tooltip is a single wrapper component.
+
+**Implementation:** Mantine's `Tooltip` takes content via a `label` prop and wraps the trigger element as `children`. There are no separate Target/Dropdown sub-components. The Recursica wrapper preserves this exact API.
+
+**Static sub-components:** `Tooltip.Floating` and `Tooltip.Group` are exposed as pass-through references to Mantine's implementations. These do not receive Recursica styling treatment — they are utility wrappers for cursor-following tooltips and shared delay grouping respectively.
+
+---
+
+## 2. Token Namespace: `tooltip`
+
+**Decision:** The CSS module exclusively uses variables from the `--recursica_ui-kit_components_tooltip_*` namespace.
+
+**Implementation:** The Recursica token system defines the `tooltip` namespace covering:
+
+- Geometry: border-radius, border-size, min-width, min-height, max-width, padding
+- Typography: text_font-\* (family, size, style, weight, letter-spacing, line-height, text-decoration, text-transform)
+- Colors (layer-aware): background, border-color, text
+- Elevation: box-shadow
+- Beak: beak-size (16px), beak-inset (8px)
+
+No tokens from other component namespaces are referenced.
+
+---
+
+## 3. Hardcoded Values
+
+### `border-style: solid` (CSS module)
+
+Mantine renders the tooltip using its `Box` component, which does not set `border-style` natively. Without this hardcoded value, the border-width and border-color tokens would have no visible effect. Same pattern as Menu and HoverCard dropdowns.
+
+### `arrowSize` defaulted to `16` (Tooltip.tsx)
+
+Mantine's `arrowSize` prop is a JavaScript number used for inline style calculations: it sets `width`, `height`, and a positioning offset (`-arrowSize/2`) directly on the arrow `<div>` element. These inline styles cannot be overridden via CSS without `!important`, and the positioning offset has no CSS equivalent. The beak size cannot be fully CSS-driven.
+
+The default value `16` matches the Recursica `beak-size` token (`--recursica_ui-kit_components_tooltip_properties_beak-size: 16px`). Developers can override `arrowSize` if needed. This is documented as an open issue in `docs/COMPONENT_ISSUES.md`.
+
+**Note:** Mantine calls this the "arrow"; Recursica calls it the "beak". The Recursica prop `withBeak` (defaulting to `true`) maps to Mantine's `withArrow`. Both are accepted; `withBeak` takes precedence.
+
+### `multiline={true}` (Tooltip.tsx)
+
+Mantine's `multiline` prop controls whether tooltip text wraps (`white-space: nowrap` when false). Recursica always enables multiline because the design system defines a `max-width` token (300px) — text should wrap naturally within that constraint rather than overflowing. The `multiline` prop is not exposed to developers.
+
+### Flexbox centering (CSS module)
+
+`display: flex; align-items: center; justify-content: center;` is applied to the `.tooltip` class. This ensures text is vertically and horizontally centered within the `min-height: 48px` container defined by the design token. Without this, text sits at the top of the tooltip.
+
+---
+
+## 4. Recursica `withBeak` Prop
+
+**Decision:** `withBeak` is the official Recursica prop for controlling beak visibility, defaulting to `true`.
+
+**Implementation:** Both `withBeak` and Mantine's `withArrow` are accepted. Resolution order: `withBeak ?? withArrow`. When both are provided, `withBeak` takes precedence. The default of `true` means tooltips show the beak by default, matching the Recursica design intent.
+
+---
+
+## 5. ClassNames Binding
+
+**Decision:** CSS module classes are bound via the `classNames` prop on Mantine's Tooltip root.
+
+**Implementation:** The stylesNames for Tooltip are `tooltip` (the container) and `arrow` (the beak). Both are mapped to their respective CSS module classes: `{ tooltip: styles.tooltip, arrow: styles.arrow }`. Consumer-provided `classNames` are merged additively when `overStyled` is true.
+
+---
+
+## 6. Tooltip.Floating and Tooltip.Group
+
+**Decision:** These static sub-components are direct pass-throughs to Mantine with no Recursica styling.
+
+**Implementation:** `Tooltip.Floating` follows the cursor and uses a different rendering mechanism than standard Tooltip. `Tooltip.Group` is a utility for shared delay timing. Neither has Recursica design tokens defined, so they remain unstyled pass-throughs. If tokens are added in the future, they can be wrapped independently.
+
+---
+
+## 7. Default Position Override
+
+**Decision:** Recursica defaults `position` to `"top"`. Mantine defaults to `"bottom"`.
+
+**Implementation:** The `position="top"` default is set on the Mantine root element before the prop spread, so developer-provided `position` values still take precedence. This aligns with Recursica's design intent for overlay components to appear above their trigger by default.

package/src/components/Tooltip/Tooltip.module.css

@@ -0,0 +1,81 @@
+/* HARDCODED VALUES:
+   - border-style: solid. Structural rendering rule for the tooltip border (Mantine uses Box
+     which may not set border-style natively). Same pattern as Menu / HoverCard.
+   - arrowSize defaults to 16 in Tooltip.tsx. Mantine uses arrowSize for inline width/height
+     and positioning (-arrowSize/2) calculations that cannot be CSS-driven. The default matches
+     the Recursica beak-size token (16px). See COMPONENT_ISSUES.md for details.
+   - All structural layout (display, position, overflow) is deferred to Mantine's native
+     behavior. We only override visual design tokens (colors, typography, spacing, borders).
+*/
+
+/* ======================================
+   TOOLTIP CONTAINER
+   ====================================== */
+
+.tooltip {
+  background-color: var(
+    --recursica_ui-kit_components_tooltip_properties_colors_background
+  );
+  border-style: solid; /* HARDCODE: Mantine Box does not set border-style natively */
+  border-width: var(
+    --recursica_ui-kit_components_tooltip_properties_border-size
+  );
+  border-color: var(
+    --recursica_ui-kit_components_tooltip_properties_colors_border-color
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_tooltip_properties_border-radius
+  );
+  box-shadow: var(--recursica_ui-kit_components_tooltip_properties_elevation);
+
+  min-width: var(--recursica_ui-kit_components_tooltip_properties_min-width);
+  min-height: var(--recursica_ui-kit_components_tooltip_properties_min-height);
+  max-width: var(--recursica_ui-kit_components_tooltip_properties_max-width);
+
+  padding: var(
+      --recursica_ui-kit_components_tooltip_properties_vertical-padding
+    )
+    var(--recursica_ui-kit_components_tooltip_properties_horizontal-padding);
+
+  /* Vertically center text within min-height container */
+  display: flex;
+  align-items: center;
+
+  /* Typography */
+  font-family: var(
+    --recursica_ui-kit_components_tooltip_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_tooltip_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_tooltip_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_tooltip_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_tooltip_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_tooltip_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_tooltip_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_tooltip_properties_text_text-transform
+  );
+
+  color: var(--recursica_ui-kit_components_tooltip_properties_colors_text);
+}
+
+/* ======================================
+   ARROW / BEAK
+   ====================================== */
+
+.arrow {
+  border-color: var(
+    --recursica_ui-kit_components_tooltip_properties_colors_border-color
+  );
+}