@recursica/adapter-mantine-v8 1.3.6 → 1.4.0

package/dist/index.d.ts

@@ -911,7 +911,7 @@ export declare type ModalOverlayProps = RecursicaOverStyled<ModalOverlayProps_2>
  * 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 declare type ModalProps = RecursicaOverStyled<Omit<ModalProps_2, "size" | "radius" | "shadow"> & RecursicaModalProps>;
+export declare type ModalProps = RecursicaOverStyled<Omit<ModalProps_2, "size" | "radius" | "shadow" | "title" | "onClose" | "withCloseButton" | "closeButtonProps"> & RecursicaModalProps>;
 
 declare const ModalRoot: default_2.ForwardRefExoticComponent<ModalRootProps & default_2.RefAttributes<HTMLDivElement>>;
 
@@ -1029,12 +1029,16 @@ export declare const Panel: PanelComponent;
  *
  * ```tsx
  * <Panel opened={opened} onClose={close} title="Panel Title" placement="right">
- *   <Panel.Body>
- *     Content goes here
- *   </Panel.Body>
+ *   Content goes here
+ *   <Panel.Footer>...</Panel.Footer>
  * </Panel>
  * ```
  *
+ * The header is required and always rendered: `title` is required, and an icon-only Recursica
+ * Close button (`aria-label` "Close", overridable via `closeButtonAriaLabel`) calls the required
+ * `onClose`. The footer is optional. Passing `header` replaces the whole default header; avoid it,
+ * because then nothing guarantees the title or the Close button.
+ *
  * Always non-modal, with no props to change it: the page behind stays usable
  * (no overlay, focus trap or scroll lock), focus returns to the opener on close,
  * Escape always closes, and outside clicks never do.
@@ -1050,7 +1054,7 @@ export declare const Panel: PanelComponent;
  * - `Panel.Stack` — Stacked drawer context
  */
 declare const PanelBase: {
-    ({ overStyled, placement, keepMounted, wrapHeaderText, ...rest }: PanelProps): JSX.Element;
+    ({ overStyled, placement, keepMounted, wrapHeaderText, title, onClose, closeButtonAriaLabel, header, children, ...rest }: PanelProps): JSX.Element;
     displayName: string;
 };
 
@@ -1244,7 +1248,7 @@ export declare interface RecursicaNumberInputProps extends Omit<NumberInputProps
 /**
  * Recursica Panel root props. Extends Mantine Drawer.
  */
-export declare interface RecursicaPanelProps extends Omit<DrawerProps, "size" | "styles" | "classNames" | "style" | "position" | "opened" | "withOverlay" | "trapFocus" | "lockScroll" | "returnFocus" | "closeOnEscape" | "closeOnClickOutside">, RecursicaPanelProps_2 {
+export declare interface RecursicaPanelProps extends Omit<DrawerProps, "size" | "styles" | "classNames" | "style" | "position" | "opened" | "title" | "withCloseButton" | "closeButtonProps" | "withOverlay" | "trapFocus" | "lockScroll" | "returnFocus" | "closeOnEscape" | "closeOnClickOutside">, RecursicaPanelProps_2 {
 }
 
 export declare interface RecursicaRadioGroupProps extends Omit<RadioGroupProps_2, "size" | "labelProps" | "defaultValue" | "value">, Omit<RecursicaFormControlWrapperProps, "controlMaxWidth" | "controlMinWidth">, ReadOnlyControlProps, RecursicaRadioGroupProps_2 {

package/package.json

@@ -12,7 +12,7 @@
     "type": "git",
     "url": "git+https://github.com/borderux/recursica-adapter-mantine-v8.git"
   },
-  "version": "1.3.6",
+  "version": "1.4.0",
   "publishConfig": {
     "access": "public"
   },
@@ -74,7 +74,7 @@
     "release": "changeset publish"
   },
   "dependencies": {
-    "@recursica/adapter-common": "^1.2.0"
+    "@recursica/adapter-common": "^1.3.0"
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.7",

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

@@ -1,6 +1,7 @@
 import React from "react";
 import type { Meta, StoryObj } from "@storybook/react";
 import { Button } from "./Button";
+import { Loader } from "../Loader/Loader";
 import { Layer } from "@recursica/adapter-common";
 
 type ButtonStoryProps = React.ComponentProps<typeof Button>;
@@ -180,6 +181,17 @@ export const Loading: Story = {
     variant: "solid",
     size: "default",
     loading: true,
+    // Frozen spinner so the visual-regression snapshot is deterministic.
+    loaderProps: {
+      children: (
+        <Loader
+          size="default"
+          overStyled
+          color="var(--button-color)"
+          animate={false}
+        />
+      ),
+    },
   },
   parameters: {
     docs: {

package/src/components/Modal/MODAL_IMPLEMENTATION_NOTES.md

@@ -30,3 +30,7 @@ Despite §1 above, `.content` never actually scaled fluidly: Mantine's own CSS s
 ### 5. Close button restyled to match Button
 
 `.close` reuses Button's text-variant/icon-only/small tokens (radius, padding, background/icon color, hover overlay, focus ring) instead of Mantine's native CloseButton look. Two overrides need `!important`/an explicit reset to win: Mantine's `CloseIcon` sizes itself via an inline `style` (`--cb-icon-size`, default `70%`), which beats any plain class rule — same category as Tree's `--level-offset` override; and Mantine's own subtle-variant `:hover` background (from `CloseButton.css`) is pinned back to the Button background token so only our `::after` overlay renders hover feedback.
+
+### 3. Required header with an always-present Close button (2026-10-16)
+
+`title` and `onClose` are required (contract in `RecursicaModalProps`, `@recursica/adapter-common`), and `withCloseButton` and `closeButtonProps` are removed. `Modal.tsx` always renders `Modal.Header` > `Modal.Title` + `Modal.CloseButton` with `aria-label="Close"` unless `closeButtonAriaLabel` is passed. A `header` prop replaces the whole default header and is discouraged in its JSDoc.

package/src/components/Modal/Modal.tsx

@@ -26,7 +26,17 @@ import { type RecursicaModalProps } from "@recursica/adapter-common";
  * 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"> & RecursicaModalProps
+  Omit<
+    MantineModalProps,
+    | "size"
+    | "radius"
+    | "shadow"
+    | "title"
+    | "onClose"
+    | "withCloseButton"
+    | "closeButtonProps"
+  > &
+    RecursicaModalProps
 >;
 
 /**
@@ -37,6 +47,11 @@ export type ModalProps = RecursicaOverStyled<
  * It automatically enforces Figma UI Kit geometries (`max-width: 960px`, `min-width: 304px`)
  * and handles internal body scrolling explicitly via CSS module overrides.
  *
+ * The header is required and always rendered: `title` is required, and an icon-only Recursica
+ * Close button (`aria-label` "Close", overridable via `closeButtonAriaLabel`) calls the required
+ * `onClose`. The footer is optional. Passing `header` replaces the whole default header; avoid it,
+ * because then nothing guarantees the title or the Close button.
+ *
  * @example
  * ```tsx
  * <Modal opened={opened} onClose={close} title="Hello World">
@@ -49,10 +64,11 @@ const ModalInner = React.forwardRef<HTMLDivElement, ModalProps>(function Modal(
     overStyled = false,
     children,
     title,
-    withCloseButton = true,
+    onClose,
+    closeButtonAriaLabel = "Close",
+    header,
     overlayProps,
     withOverlay = true,
-    closeButtonProps,
     ...rest
   },
   ref,
@@ -90,16 +106,15 @@ const ModalInner = React.forwardRef<HTMLDivElement, ModalProps>(function Modal(
         MantineModalProps,
         "size" | "radius" | "shadow"
       >)}
+      onClose={onClose}
       classNames={mergedClassNames}
     >
       {withOverlay && <MantineModal.Overlay {...overlayProps} />}
       <MantineModal.Content>
-        {(title || withCloseButton) && (
+        {header ?? (
           <MantineModal.Header>
-            {title && <MantineModal.Title>{title}</MantineModal.Title>}
-            {withCloseButton && (
-              <MantineModal.CloseButton {...closeButtonProps} />
-            )}
+            <MantineModal.Title>{title}</MantineModal.Title>
+            <MantineModal.CloseButton aria-label={closeButtonAriaLabel} />
           </MantineModal.Header>
         )}
         <ModalBody>{children}</ModalBody>

package/src/components/Modal/USAGE.md

@@ -43,6 +43,12 @@ All Recursica components in the `@recursica/adapter-mantine-v8` package adhere s
 
 ## 4. Key Integration Features & Constraints
 
+### Header: required title and Close button
+
+`title` and `onClose` are required. The header always renders the title and an icon-only Recursica Close button with `aria-label="Close"`; pass `closeButtonAriaLabel` to translate it. `withCloseButton` has been removed: there is no way to hide the Close button.
+
+The `header` prop replaces the whole default header. Avoid it: a custom header must supply its own title and Close button, and the adapter can no longer guarantee either.
+
 ## Architecture
 
 `Modal` wraps Mantine's `<Modal>` component. Native Mantine styling props (`size`, `radius`, `shadow`) are not used — appearance and sizing are fully controlled by the design system tokens instead.

package/src/components/Panel/PANEL_IMPLEMENTATION_NOTES.md

@@ -129,4 +129,12 @@ Project-wide fix; see Chip's `CHIP_IMPLEMENTATION_NOTES.md` for the original dis
 
 **Decision:** Panel is never modal, and there are no props to change that.
 
-**Implementation:** The house rule is that the page behind a panel stays usable. `Panel.tsx` always passes `withOverlay={false}`, `trapFocus={false}`, `lockScroll={false}`, `returnFocus`, `closeOnEscape` and `closeOnClickOutside={false}` to Mantine's Drawer, after the caller's props, and omits those keys from `RecursicaPanelProps`. Escape is independent of outside clicks and always closes the panel; clicking the page behind never does. Every adapter must match: no overlay, no focus trap, no scroll lock, no `aria-modal`, no `aria-hidden` on the rest of the page.
+**Implementation:** The house rule is that the page behind a panel stays usable. `Panel.tsx` composes `Drawer.Root` without a `Drawer.Overlay` and always passes `trapFocus={false}`, `lockScroll={false}`, `returnFocus`, `closeOnEscape` and `closeOnClickOutside={false}` to Mantine's Drawer, after the caller's props, and omits those keys from `RecursicaPanelProps`. Escape is independent of outside clicks and always closes the panel; clicking the page behind never does. Every adapter must match: no overlay, no focus trap, no scroll lock, no `aria-modal`, no `aria-hidden` on the rest of the page.
+
+---
+
+## 11. Required header with an always-present Close button (Matt Massey, 2026-10-16)
+
+**Decision:** Every Panel has a header with a required `title` and a Close button wired to a required `onClose`. The footer is optional.
+
+**Implementation:** The contract lives in `RecursicaPanelProps` in `@recursica/adapter-common`. `Panel.tsx` composes `Drawer.Root` > `Drawer.Content` > (`Drawer.Header` > `Drawer.Title` + `Drawer.CloseButton`) + `Drawer.Body`, so the header cannot be omitted. The Close button gets `aria-label="Close"` unless `closeButtonAriaLabel` is passed. `title`, `withCloseButton` and `closeButtonProps` are omitted from the Mantine props type. The `.close` class matches Button's text-variant, icon-only, small-size treatment (same as Modal), so the Close button looks like a Recursica icon-only Button. A `header` prop replaces the whole default header; it is discouraged in its JSDoc because nothing then guarantees a title or Close button.

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

@@ -1,3 +1,14 @@
+/* Brand-layer exemptions (recursica-allow-brand) — see recursica-token-analyzer README.md.
+ * Close button is styled to match the Button component's text/icon-only variant, so it reuses
+ * the same global hover/focus state tokens Button.module.css exempts.
+ *   recursica-allow-brand: --recursica_brand_states_focus_blur
+ *   recursica-allow-brand: --recursica_brand_states_focus_border-size
+ *   recursica-allow-brand: --recursica_brand_states_focus_color
+ *   recursica-allow-brand: --recursica_brand_states_focus_margin
+ *   recursica-allow-brand: --recursica_brand_states_hover_color
+ *   recursica-allow-brand: --recursica_brand_states_hover_opacity
+ */
+
 /* HARDCODED VALUES:
    - border-style: solid: Structural rendering rule for the panel border.
    - .contentTop {
@@ -232,3 +243,97 @@
   /* Render over scrolling content */
   z-index: 10;
 }
+
+/* ======================================
+   PANEL CLOSE BUTTON
+   ====================================== */
+
+.close {
+  /* Matches the Button component's text-variant, icon-only, small-size visual treatment
+     (see Button.module.css) so the modal close control looks like a Recursica Button
+     rather than Mantine's native CloseButton. */
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  position: relative;
+  overflow: hidden;
+  transition: all 0.2s ease;
+
+  height: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_height
+  );
+  min-width: var(
+    --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_small_properties_min-width
+  );
+  padding: 0
+    var(
+      --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_small_properties_horizontal-padding
+    );
+  border-radius: var(
+    --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_small_properties_border-radius
+  );
+
+  border-style: solid;
+  border-width: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_border-size
+  );
+  border-color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_border-color
+  );
+  background-color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_background-color
+  );
+  color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_icon-color
+  );
+}
+
+/* Mantine's CloseIcon sets width/height via an inline `style` attribute
+   (`--cb-icon-size`, default 70%), which beats any plain class rule regardless of specificity —
+   same category of override as Tree's `--level-offset` (see Tree/IMPLEMENTATION_NOTES.md).
+   `!important` is required here to land the Button's small icon-size token instead. */
+.close svg {
+  position: relative;
+  z-index: 1;
+  width: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_icon
+  ) !important;
+  height: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_icon
+  ) !important;
+}
+
+.close::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  z-index: 0;
+  pointer-events: none;
+  transition: opacity 150ms ease;
+  opacity: 0;
+  background-color: var(--recursica_brand_states_hover_color);
+}
+.close:hover:not(:disabled)::after {
+  opacity: var(--recursica_brand_states_hover_opacity);
+}
+
+/* Mantine's own subtle-variant hover background (CloseButton.css) would otherwise show through
+   underneath the overlay above — pin it back to the Button's own background token so only the
+   `::after` overlay renders the hover feedback, matching Button's single-overlay treatment. */
+.close:hover {
+  background-color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_background-color
+  );
+}
+
+.close:focus-visible {
+  outline: none;
+  box-shadow:
+    0 0 0 var(--recursica_brand_states_focus_border-size)
+      var(--recursica_brand_states_focus_color),
+    0 0 var(--recursica_brand_states_focus_blur)
+      var(--recursica_brand_states_focus_margin)
+      var(--recursica_brand_states_focus_color);
+}

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

@@ -21,10 +21,6 @@ const meta: Meta = {
       control: "text",
       description: "Panel title displayed in the header.",
     },
-    withCloseButton: {
-      control: "boolean",
-      description: "Whether to display the close button in the header.",
-    },
     wrapHeaderText: {
       control: "boolean",
       description:
@@ -76,7 +72,6 @@ export const Default: Story = {
   args: {
     placement: "right",
     title: "Panel Title",
-    withCloseButton: true,
     wrapHeaderText: false,
   },
   render: ({ wrapHeaderText, ...args }: PanelStoryArgs) => {
@@ -117,7 +112,6 @@ export const LeftPlacement: Story = {
   args: {
     placement: "left",
     title: "Navigation",
-    withCloseButton: true,
     wrapHeaderText: false,
   },
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -149,7 +143,6 @@ export const ScrollableContent: Story = {
   args: {
     placement: "right",
     title: "Scrollable Panel",
-    withCloseButton: true,
     wrapHeaderText: false,
   },
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -191,7 +184,6 @@ export const LongTitle: Story = {
     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",
-    withCloseButton: true,
     wrapHeaderText: true,
   },
   render: ({ ...args }: PanelStoryArgs) => {

package/src/components/Panel/Panel.tsx

@@ -35,6 +35,9 @@ export interface RecursicaPanelProps
       | "style"
       | "position"
       | "opened"
+      | "title"
+      | "withCloseButton"
+      | "closeButtonProps"
       | "withOverlay"
       | "trapFocus"
       | "lockScroll"
@@ -56,12 +59,16 @@ export type PanelProps = RecursicaOverStyled<RecursicaPanelProps>;
  *
  * ```tsx
  * <Panel opened={opened} onClose={close} title="Panel Title" placement="right">
- *   <Panel.Body>
- *     Content goes here
- *   </Panel.Body>
+ *   Content goes here
+ *   <Panel.Footer>...</Panel.Footer>
  * </Panel>
  * ```
  *
+ * The header is required and always rendered: `title` is required, and an icon-only Recursica
+ * Close button (`aria-label` "Close", overridable via `closeButtonAriaLabel`) calls the required
+ * `onClose`. The footer is optional. Passing `header` replaces the whole default header; avoid it,
+ * because then nothing guarantees the title or the Close button.
+ *
  * Always non-modal, with no props to change it: the page behind stays usable
  * (no overlay, focus trap or scroll lock), focus returns to the opener on close,
  * Escape always closes, and outside clicks never do.
@@ -81,6 +88,11 @@ const PanelBase = function Panel({
   placement = "right",
   keepMounted = true,
   wrapHeaderText = true,
+  title,
+  onClose,
+  closeButtonAriaLabel = "Close",
+  header,
+  children,
   ...rest
 }: PanelProps) {
   const sanitizedProps = filterStylingProps(rest, overStyled);
@@ -100,6 +112,7 @@ const PanelBase = function Panel({
       }`,
       header: styles.header,
       title: wrapHeaderText ? styles.titleTruncate : styles.title,
+      close: styles.close,
       body: styles.body,
       inner: styles.inner,
     },
@@ -107,20 +120,30 @@ const PanelBase = function Panel({
   );
 
   return (
-    <MantineDrawer
-      {...(sanitizedProps as unknown as MantineDrawerProps)}
+    <MantineDrawer.Root
+      {...(sanitizedProps as unknown as MantineDrawerRootProps)}
+      onClose={onClose}
       size="var(--recursica_ui-kit_components_panel_properties_max-width)"
       position={placement} /* Recursica default: right; Mantine default: left */
       keepMounted={keepMounted}
-      /* Always non-modal: the page behind stays usable, Escape always closes */
-      withOverlay={false}
+      /* Always non-modal and overlay-less: the page behind stays usable, Escape always closes */
       trapFocus={false}
       lockScroll={false}
       returnFocus
       closeOnEscape
       closeOnClickOutside={false}
       classNames={mergedClassNames}
-    />
+    >
+      <MantineDrawer.Content>
+        {header ?? (
+          <MantineDrawer.Header>
+            <MantineDrawer.Title>{title}</MantineDrawer.Title>
+            <MantineDrawer.CloseButton aria-label={closeButtonAriaLabel} />
+          </MantineDrawer.Header>
+        )}
+        <MantineDrawer.Body>{children}</MantineDrawer.Body>
+      </MantineDrawer.Content>
+    </MantineDrawer.Root>
   );
 };
 PanelBase.displayName = "Panel";

package/src/components/Panel/USAGE.md

@@ -15,12 +15,13 @@ import { Panel } from "@recursica/adapter-mantine-v8";
 ## 2. Basic Example
 
 ```tsx
-import React from "react";
+import React, { useState } from "react";
 import { Panel } from "@recursica/adapter-mantine-v8";
 
 export default function Demo() {
+  const [opened, setOpened] = useState(false);
   return (
-    <Panel>
+    <Panel opened={opened} onClose={() => setOpened(false)} title="Settings">
       <Text>This is a clean, structured visual container.</Text>
     </Panel>
   );
@@ -47,6 +48,12 @@ All Recursica components in the `@recursica/adapter-mantine-v8` package adhere s
 
 Use the `placement` prop (not `position`) to choose which edge the panel slides in from: `"left"`, `"right"`, `"top"`, or `"bottom"`. It defaults to `"right"`.
 
+### Header: required title and Close button
+
+`title` and `onClose` are required. The header always renders the title and an icon-only Recursica Close button with `aria-label="Close"`; pass `closeButtonAriaLabel` to translate it. There is no prop to hide the Close button.
+
+The `header` prop replaces the whole default header. Avoid it: a custom header must supply its own title and Close button, and the adapter can no longer guarantee either.
+
 ### Panel.Footer
 
 A `Panel.Footer` sub-component is available for footer content and action buttons.