@recursica/adapter-mantine-v8 1.0.0

package/src/components/Panel/USAGE.md

@@ -0,0 +1,56 @@
+# Panel - Usage Guide
+
+This document describes how to integrate and use the `Panel` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Panel } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Panel } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return (
+    <Panel>
+      <Text>This is a clean, structured visual container.</Text>
+    </Panel>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mantine-v8` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+### Placement
+
+Use the `placement` prop (not `position`) to choose which edge the panel slides in from: `"left"`, `"right"`, `"top"`, or `"bottom"`. It defaults to `"right"`.
+
+### Panel.Footer
+
+A `Panel.Footer` sub-component is available for footer content and action buttons.
+
+### Content Overflow
+
+When content exceeds the panel's available height, the body scrolls internally while the header and footer stay fixed in place.

package/src/components/Popover/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,77 @@
+# Popover – Implementation Notes
+
+Decisions and design tweaks strictly tailored for the UI Kit's Popover wrapped against `@mantine/core`. This is a living document that tracks _why_ specific logic decisions exist.
+
+---
+
+## 1. Composable API Preservation (1:1 Mapping)
+
+**Decision:** We maintain the exact library composition API structure (`<Popover>`, `<Popover.Target>`, `<Popover.Dropdown>`) as a 1:1 React component mapping.
+
+**Implementation:** Mantine's Popover internally manages click detection, open/close state, Floating UI positioning, and portal rendering. By preserving the exact sub-component tree, Recursica safely inherits all of these behaviors without reimplementation.
+
+---
+
+## 2. Popover.Target Pass-Through
+
+**Decision:** `Popover.Target` is a transparent pass-through with no styling applied.
+
+**Implementation:** The target wrapper exists solely to manage Mantine's ref forwarding and event binding for the trigger element. No `filterStylingProps` or CSS module classes are applied — the trigger's appearance is entirely controlled by whatever component the integrator places inside it (e.g., `<Button>`). This is identical to the `Menu.Target` and `HoverCard.Target` pattern.
+
+---
+
+## 3. Token Namespace: `hover-card-popover`
+
+**Decision:** The CSS module exclusively uses variables from the `--recursica_ui-kit_components_hover-card-popover_*` namespace.
+
+**Implementation:** The Recursica token system defines a single shared namespace (`hover-card-popover`) for this component and HoverCard. It covers geometry (border-radius, border-size, padding, min/max-width), typography (content-text\_\*), elevation, and layer-aware colors (background, border-color, content).
+
+---
+
+## 4. Hardcoded Values
+
+**Decision:** Two hardcoded values exist in the component.
+
+### `border-style: solid` (CSS module)
+
+Mantine renders the dropdown using its `Paper` component, which does not set `border-style` natively. Without this hardcoded value, the border-width and border-color tokens would have no visible effect. This is the same pattern used in the Menu component's dropdown.
+
+### `arrowSize` defaulted to `16` (Popover.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. This means the beak size cannot be fully CSS-driven — it is one of the rare cases where a design token value must be mirrored as a JS prop.
+
+The default value `16` matches the Recursica `beak-size` token (`--recursica_ui-kit_components_hover-card-popover_properties_beak-size: 16px`). Developers can override `arrowSize` if needed, but should be aware this is a design system concern. If the token value changes, the default in `Popover.tsx` must also be updated.
+
+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 `withBeak` and `withArrow` are accepted; `withBeak` takes precedence.
+
+---
+
+## 5. Minimal CSS Override Philosophy
+
+**Decision:** The CSS module only overrides visual design tokens (colors, typography, spacing, borders, shadows). All structural layout properties are deferred to Mantine's native behavior.
+
+**Implementation:** Popover is an overlay component where Mantine's native Floating UI positioning and Paper layout are already correct. We avoid setting:
+
+- `overflow` on the dropdown (Mantine handles scroll behavior natively)
+- `display`, `position`, `z-index` (Floating UI controls these)
+- `pointer-events` (Mantine manages hover detection across target and dropdown)
+
+**Rationale:** Default to Mantine's native behavior and only override what the Recursica token system explicitly needs to control.
+
+---
+
+## 6. ClassNames Merging on Root
+
+**Decision:** The root `Popover` component binds CSS module classes via `classNames` on the Mantine root.
+
+**Implementation:** The root component receives `classNames={{ dropdown: styles.dropdown, arrow: styles.arrow }}` and merges any consumer-provided `classNames` when `overStyled` is true. This ensures our token-driven styles are applied to the dropdown panel without wrapper divs, and the consumer's classes are additive.
+
+---
+
+## 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/Popover/Popover.module.css

@@ -0,0 +1,86 @@
+/* HARDCODED VALUES:
+   - border-style: solid. Structural rendering rule for the dropdown border (Mantine uses Paper
+     which may not set border-style natively). Same pattern as Menu and HoverCard.
+   - arrowSize defaults to 16 in Popover.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).
+*/
+
+/* ======================================
+   DROPDOWN CONTAINER
+   ====================================== */
+
+.dropdown {
+  background-color: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_colors_background-color
+  );
+  border-style: solid; /* HARDCODE: Mantine Paper does not set border-style natively */
+  border-width: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_border-size
+  );
+  border-color: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_colors_border-color
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_border-radius
+  );
+  box-shadow: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_elevation
+  );
+
+  min-width: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_min-width
+  );
+  max-width: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_max-width
+  );
+
+  padding: var(
+      --recursica_ui-kit_components_hover-card-popover_properties_vertical-padding
+    )
+    var(
+      --recursica_ui-kit_components_hover-card-popover_properties_horizontal-padding
+    );
+
+  /* Typography */
+  font-family: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_content-text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_content-text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_content-text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_content-text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_content-text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_content-text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_content-text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_content-text_text-transform
+  );
+
+  color: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_colors_content
+  );
+}
+
+/* ======================================
+   ARROW / BEAK
+   ====================================== */
+
+.arrow {
+  border-color: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_colors_border-color
+  );
+}

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.test.tsx

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

package/src/components/Popover/Popover.tsx

@@ -0,0 +1,142 @@
+import {
+  Popover as MantinePopover,
+  type PopoverProps as MantinePopoverProps,
+  type PopoverTargetProps as MantinePopoverTargetProps,
+  type PopoverDropdownProps as MantinePopoverDropdownProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  mergeClassNames,
+  withCallerOverride,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Popover.module.css";
+
+// ============================================================
+// POPOVER ROOT
+// ============================================================
+
+/**
+ * Recursica-specific props for Popover.
+ */
+import { type RecursicaPopoverProps } from "@recursica/adapter-common";
+
+/**
+ * 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 = Omit<
+  RecursicaOverStyled<
+    Omit<MantinePopoverProps, "position"> & RecursicaPopoverProps
+  >,
+  "position"
+> & {
+  position?: MantinePopoverProps["position"];
+};
+
+const PopoverBase = function Popover({
+  overStyled = false,
+  withBeak = true,
+  position = "top", // Recursica default; Mantine defaults to "bottom"
+  ...rest
+}: PopoverProps) {
+  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(
+    { dropdown: styles.dropdown, arrow: styles.arrow },
+    restRecord.classNames as Partial<Record<string, string>> | undefined,
+  );
+
+  // 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 = withCallerOverride<number>(
+    16,
+    restRecord.arrowSize as number | undefined,
+  );
+
+  // Resolve withBeak (Recursica) vs withArrow (Mantine).
+  // withBeak takes precedence when both are provided.
+  const resolvedWithArrow = withCallerOverride<boolean | undefined>(
+    withBeak,
+    restRecord.withArrow as boolean | undefined,
+  );
+
+  return (
+    <MantinePopover
+      {...(sanitizedProps as unknown as MantinePopoverProps)}
+      position={position}
+      arrowSize={arrowSize}
+      withArrow={resolvedWithArrow}
+      classNames={mergedClassNames}
+    />
+  );
+};
+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
+      {...(sanitizedProps as unknown as MantinePopoverDropdownProps)}
+      className={classNameProp}
+    />
+  );
+};
+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/USAGE.md

@@ -0,0 +1,61 @@
+# Popover - Usage Guide
+
+This document describes how to integrate and use the `Popover` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Popover } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Popover } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return (
+    <Popover position="bottom" withArrow>
+      <Popover.Target>
+        <Button>Open Popover</Button>
+      </Popover.Target>
+      <Popover.Dropdown>
+        <Text size="sm">This is the popover content.</Text>
+      </Popover.Dropdown>
+    </Popover>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mantine-v8` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+### Composition
+
+`Popover`, `Popover.Target`, and `Popover.Dropdown` are used together the same way as in Mantine: `Popover.Target` wraps the trigger element and applies no styling of its own, while `Popover.Dropdown` renders the styled panel content.
+
+### Beak (Arrow)
+
+The Recursica prop `withBeak` (defaulting to `true`) controls whether the pointer beak is shown, and maps to Mantine's `withArrow`. Both `withBeak` and `withArrow` are accepted; `withBeak` takes precedence. An `arrowSize` prop is also available (default `16`) to size the beak.
+
+### Default Position
+
+Recursica defaults `position` to `"top"` rather than Mantine's `"bottom"`. Pass your own `position` value to override it.

package/src/components/Popover/index.ts

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