@recursica/adapter-mantine-v8 1.0.0

package/src/components/Panel/Panel.module.css

@@ -0,0 +1,209 @@
+/* HARDCODED VALUES:
+   - border-style: solid: Structural rendering rule for the panel border.
+   - .inner { left: 0 }: Prevents the fixed Drawer portal from being pushed off-screen in centered flex environments (like Storybook Canvas).
+   - flexbox layout on .content & .body: Required to create a vertical flex context that pushes the footer to the bottom.
+   - position: sticky & negative margins on .footer: A CSS technique used to break the footer out of the .body padding constraints so it stretches edge-to-edge, while remaining fixed at the bottom of the scroll container.
+   - z-index: 10 on .footer: Ensures the footer covers the body content as it scrolls underneath.
+ */
+
+/* ======================================
+   PANEL CONTENT (outer drawer container)
+   ====================================== */
+
+.content {
+  background-color: var(
+    --recursica_ui-kit_components_panel_properties_colors_background-color
+  );
+  border-style: solid;
+  border-width: var(--recursica_ui-kit_components_panel_properties_border-size);
+  border-color: var(
+    --recursica_ui-kit_components_panel_properties_colors_border-color
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_panel_properties_border-radius
+  );
+  box-shadow: var(--recursica_ui-kit_components_panel_properties_elevation);
+  min-width: var(--recursica_ui-kit_components_panel_properties_min-width);
+  max-width: var(--recursica_ui-kit_components_panel_properties_max-width);
+
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+}
+
+.inner {
+  /* Forces the Drawer Inner container to the left edge, preventing it from inheriting
+     a centered static position in flex environments like Storybook's Canvas wrapper */
+  left: 0;
+}
+
+/* ======================================
+   PANEL HEADER
+   ====================================== */
+
+.header {
+  background-color: var(
+    --recursica_ui-kit_components_panel_properties_colors_header-background-color
+  );
+  padding: var(
+      --recursica_ui-kit_components_panel_properties_header-footer-vertical-padding
+    )
+    var(
+      --recursica_ui-kit_components_panel_properties_header-footer-horizontal-padding
+    );
+  border-bottom: var(
+      --recursica_ui-kit_components_panel_properties_divider-size
+    )
+    solid
+    var(--recursica_ui-kit_components_panel_properties_colors_divider-color);
+  gap: var(--recursica_ui-kit_components_panel_properties_header-close-gap);
+}
+
+/* ======================================
+   PANEL TITLE
+   ====================================== */
+
+.title {
+  color: var(--recursica_ui-kit_components_panel_properties_colors_title);
+
+  /* Direct Figma Typography Mapping */
+  font-family: var(
+    --recursica_ui-kit_components_panel_properties_header-style_fontFamily
+  );
+  font-size: var(
+    --recursica_ui-kit_components_panel_properties_header-style_fontSize
+  );
+  font-style: var(
+    --recursica_ui-kit_components_panel_properties_header-style_fontStyle
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_panel_properties_header-style_fontWeight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_panel_properties_header-style_letterSpacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_panel_properties_header-style_lineHeight
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_panel_properties_header-style_textCase
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_panel_properties_header-style_textDecoration
+  );
+}
+
+.titleTruncate {
+  composes: title;
+  white-space: nowrap;
+  overflow: clip; /* HARDCODE: `hidden` clips descenders (e.g. "g") when text_line-height is
+    tighter than the font's natural ascent+descent; overflow-clip-margin gives ink a small bleed
+    allowance while still clipping genuinely overflowing text (see Chip's IMPLEMENTATION_NOTES.md). */
+  overflow-clip-margin: 0.35em;
+  text-overflow: ellipsis;
+  display: block;
+  flex: 1;
+  min-width: 0;
+}
+
+/* ======================================
+   PANEL BODY
+   ====================================== */
+
+.body {
+  padding: var(
+      --recursica_ui-kit_components_panel_properties_content-vertical-padding
+    )
+    var(
+      --recursica_ui-kit_components_panel_properties_content-horizontal-padding
+    );
+  color: var(--recursica_ui-kit_components_panel_properties_colors_content);
+
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  overflow-y: auto;
+
+  /* Direct Figma Typography Mapping */
+  font-family: var(
+    --recursica_ui-kit_components_panel_properties_content-style_fontFamily
+  );
+  font-size: var(
+    --recursica_ui-kit_components_panel_properties_content-style_fontSize
+  );
+  font-style: var(
+    --recursica_ui-kit_components_panel_properties_content-style_fontStyle
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_panel_properties_content-style_fontWeight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_panel_properties_content-style_letterSpacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_panel_properties_content-style_lineHeight
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_panel_properties_content-style_textCase
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_panel_properties_content-style_textDecoration
+  );
+}
+
+/* ======================================
+   PANEL FOOTER
+   ====================================== */
+
+.footer {
+  background-color: var(
+    --recursica_ui-kit_components_panel_properties_colors_footer-background-color
+  );
+  padding: var(
+      --recursica_ui-kit_components_panel_properties_header-footer-vertical-padding
+    )
+    var(
+      --recursica_ui-kit_components_panel_properties_header-footer-horizontal-padding
+    );
+  border-top: var(--recursica_ui-kit_components_panel_properties_divider-size)
+    solid
+    var(--recursica_ui-kit_components_panel_properties_colors_divider-color);
+
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: var(--recursica_ui-kit_components_panel_properties_footer-button-gap);
+
+  /* Ensure footer sticks to the bottom of the scroll container */
+  margin-top: auto;
+  position: sticky;
+
+  /* Break out of .body padding constraints to stretch edge-to-edge */
+  bottom: calc(
+    var(
+        --recursica_ui-kit_components_panel_properties_content-vertical-padding
+      ) *
+      -1
+  );
+  margin-left: calc(
+    var(
+        --recursica_ui-kit_components_panel_properties_content-horizontal-padding
+      ) *
+      -1
+  );
+  margin-right: calc(
+    var(
+        --recursica_ui-kit_components_panel_properties_content-horizontal-padding
+      ) *
+      -1
+  );
+  margin-bottom: calc(
+    var(
+        --recursica_ui-kit_components_panel_properties_content-vertical-padding
+      ) *
+      -1
+  );
+
+  /* Render over scrolling content */
+  z-index: 10;
+}

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

@@ -0,0 +1,227 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Panel, type PanelProps } from "./Panel";
+import { Button } from "../Button";
+import { Text } from "../Text/Text";
+
+// 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: {
+    placement: {
+      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" placement="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<PanelStoryArgs>;
+
+export const Default: Story = {
+  args: {
+    placement: "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
+          {...(args as PanelProps)}
+          opened={opened}
+          onClose={() => setOpened(false)}
+          title="Panel Title"
+          placement="right"
+          wrapHeaderText={wrapHeaderText}
+        >
+          <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 LeftPlacement: Story = {
+  args: {
+    placement: "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: {
+    placement: "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: {
+    placement: "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.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Panel component tests. Add tests here if/when needed.

package/src/components/Panel/Panel.tsx

@@ -0,0 +1,269 @@
+import { forwardRef } from "react";
+import {
+  Drawer as MantineDrawer,
+  type DrawerProps as MantineDrawerProps,
+  type DrawerRootProps as MantineDrawerRootProps,
+  type DrawerOverlayProps as MantineDrawerOverlayProps,
+  type DrawerContentProps as MantineDrawerContentProps,
+  type DrawerHeaderProps as MantineDrawerHeaderProps,
+  type DrawerTitleProps as MantineDrawerTitleProps,
+  type DrawerCloseButtonProps as MantineDrawerCloseButtonProps,
+  type DrawerBodyProps as MantineDrawerBodyProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  mergeClassNames,
+  withCallerOverride,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Panel.module.css";
+
+// ============================================================
+// PANEL (Drawer)
+// ============================================================
+
+import { type RecursicaPanelProps as BaseRecursicaPanelProps } from "@recursica/adapter-common";
+
+/**
+ * Recursica Panel root props. Extends Mantine Drawer.
+ */
+export interface RecursicaPanelProps
+  extends Omit<
+      MantineDrawerProps,
+      "size" | "styles" | "classNames" | "style" | "position" | "opened"
+    >,
+    BaseRecursicaPanelProps {}
+
+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" placement="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,
+  placement = "right",
+  keepMounted = true,
+  wrapHeaderText = true,
+  ...rest
+}: PanelProps) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
+  // Bind CSS module classes to Mantine's internal classNames API
+  const mergedClassNames = mergeClassNames(
+    {
+      content: styles.content,
+      header: styles.header,
+      title: wrapHeaderText ? styles.titleTruncate : styles.title,
+      body: styles.body,
+      inner: styles.inner,
+    },
+    restRecord.classNames as Partial<Record<string, string>> | undefined,
+  );
+
+  return (
+    <MantineDrawer
+      {...(sanitizedProps as unknown as MantineDrawerProps)}
+      position={placement} /* Recursica default: right; Mantine default: left */
+      keepMounted={keepMounted}
+      closeOnClickOutside={withCallerOverride(
+        Boolean(rest.opened),
+        rest.closeOnClickOutside,
+      )}
+      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} {...sanitizedProps} className={finalClassName} />;
+  },
+);
+PanelFooter.displayName = "PanelFooter";
+
+// ============================================================
+// PANEL SUB-COMPONENTS (wrapped so overStyled/filterStylingProps applies)
+// ============================================================
+
+export type PanelRootProps = RecursicaOverStyled<MantineDrawerRootProps>;
+
+export const PanelRoot = forwardRef<HTMLDivElement, PanelRootProps>(
+  function PanelRoot({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    return (
+      <MantineDrawer.Root
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineDrawerRootProps)}
+      />
+    );
+  },
+);
+PanelRoot.displayName = "PanelRoot";
+
+export type PanelOverlayProps = RecursicaOverStyled<MantineDrawerOverlayProps>;
+
+export const PanelOverlay = forwardRef<HTMLDivElement, PanelOverlayProps>(
+  function PanelOverlay({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    return (
+      <MantineDrawer.Overlay
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineDrawerOverlayProps)}
+      />
+    );
+  },
+);
+PanelOverlay.displayName = "PanelOverlay";
+
+export type PanelContentProps = RecursicaOverStyled<MantineDrawerContentProps>;
+
+export const PanelContent = forwardRef<HTMLDivElement, PanelContentProps>(
+  function PanelContent({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    return (
+      <MantineDrawer.Content
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineDrawerContentProps)}
+      />
+    );
+  },
+);
+PanelContent.displayName = "PanelContent";
+
+export type PanelHeaderProps = RecursicaOverStyled<MantineDrawerHeaderProps>;
+
+export const PanelHeader = forwardRef<HTMLElement, PanelHeaderProps>(
+  function PanelHeader({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    return (
+      <MantineDrawer.Header
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineDrawerHeaderProps)}
+      />
+    );
+  },
+);
+PanelHeader.displayName = "PanelHeader";
+
+export type PanelTitleProps = RecursicaOverStyled<MantineDrawerTitleProps>;
+
+export const PanelTitle = forwardRef<HTMLHeadingElement, PanelTitleProps>(
+  function PanelTitle({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    return (
+      <MantineDrawer.Title
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineDrawerTitleProps)}
+      />
+    );
+  },
+);
+PanelTitle.displayName = "PanelTitle";
+
+export type PanelCloseButtonProps =
+  RecursicaOverStyled<MantineDrawerCloseButtonProps>;
+
+export const PanelCloseButton = forwardRef<
+  HTMLButtonElement,
+  PanelCloseButtonProps
+>(function PanelCloseButton({ overStyled = false, ...rest }, ref) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  return (
+    <MantineDrawer.CloseButton
+      ref={ref}
+      {...(sanitizedProps as unknown as MantineDrawerCloseButtonProps)}
+    />
+  );
+});
+PanelCloseButton.displayName = "PanelCloseButton";
+
+export type PanelBodyProps = RecursicaOverStyled<MantineDrawerBodyProps>;
+
+export const PanelBody = forwardRef<HTMLDivElement, PanelBodyProps>(
+  function PanelBody({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    return (
+      <MantineDrawer.Body
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineDrawerBodyProps)}
+      />
+    );
+  },
+);
+PanelBody.displayName = "PanelBody";
+
+// ============================================================
+// DOT NOTATION EXPORT
+// ============================================================
+
+type PanelComponent = typeof PanelBase & {
+  Root: typeof PanelRoot;
+  Overlay: typeof PanelOverlay;
+  Content: typeof PanelContent;
+  Header: typeof PanelHeader;
+  Title: typeof PanelTitle;
+  CloseButton: typeof PanelCloseButton;
+  Body: typeof PanelBody;
+  Stack: typeof MantineDrawer.Stack;
+  Footer: typeof PanelFooter;
+};
+
+export const Panel = PanelBase as PanelComponent;
+Panel.Root = PanelRoot;
+Panel.Overlay = PanelOverlay;
+Panel.Content = PanelContent;
+Panel.Header = PanelHeader;
+Panel.Title = PanelTitle;
+Panel.CloseButton = PanelCloseButton;
+Panel.Body = PanelBody;
+// Panel.Stack (DrawerStack) only accepts `children` — no styling props to
+// strip, so re-exporting Mantine's implementation directly is not a gap.
+Panel.Stack = MantineDrawer.Stack;
+Panel.Footer = PanelFooter;