@recursica/adapter-mantine-v8 1.3.2 → 1.3.4

package/dist/index.d.ts

@@ -1035,6 +1035,10 @@ export declare const Panel: PanelComponent;
  * </Panel>
  * ```
  *
+ * 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.
+ *
  * Mantine Drawer sub-components available via dot-notation:
  * - `Panel.Header` — Top section with title and close button
  * - `Panel.Title` — Title text within the header
@@ -1240,7 +1244,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">, RecursicaPanelProps_2 {
+export declare interface RecursicaPanelProps extends Omit<DrawerProps, "size" | "styles" | "classNames" | "style" | "position" | "opened" | "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/docs/PHILOSOPHY.md

@@ -4,6 +4,10 @@ Recursica's component architecture isn't just a wrapper; it's a strict enforcing
 
 This document serves as the governing framework for why the `adapter-mantine-v8` components are built the way they are.
 
+## Why an Adapter?
+
+Most companies already have an existing component library or use an existing UI kit, and switching to a different kit means painful refactoring. Rather than replace Mantine, this adapter adapts to its API surface while enforcing the behaviors and styling Recursica defines for a consistent UX. You don't ship two separate UI kits, and you can migrate to Recursica systematically, over time.
+
 ## 1. Strict Separation of Props (The Unified Recursica Prop Layer)
 
 Recursica has a **single universal API surface** internally regardless of whether we use Mantine or another underlying UI library.

package/package.json

@@ -12,7 +12,7 @@
     "type": "git",
     "url": "git+https://github.com/borderux/recursica-adapter-mantine-v8.git"
   },
-  "version": "1.3.2",
+  "version": "1.3.4",
   "publishConfig": {
     "access": "public"
   },
@@ -31,18 +31,14 @@
   "files": [
     "dist",
     "src",
+    "!src/**/*.stories.tsx",
     "CHANGELOG.md",
-    ".storybook/commonArgTypes.ts",
     "llms.txt",
     "USAGE.md",
     "ARCHITECTURE.md",
     "SETUP.md",
     "OVERSTYLING.md",
-    "docs/PHILOSOPHY.md",
-    "recursica_variables_scoped.css",
-    "recursica_brand.json",
-    "recursica_tokens.json",
-    "recursica_ui-kit.json"
+    "docs/PHILOSOPHY.md"
   ],
   "keywords": [
     "react",
@@ -86,7 +82,7 @@
     "@playwright/test": "^1.62.1",
     "@recursica/adapter-tester": "^5.3.1",
     "@recursica/recursica-postcss-vars": "^1.5.0",
-    "@recursica/storybook-template": "^0.7.15",
+    "@recursica/storybook-template": "^0.7.16",
     "@recursica/token-analyzer": "^1.8.0",
     "@storybook/addon-a11y": "^10.3.3",
     "@storybook/addon-docs": "^10.3.3",

package/src/components/Heading/HEADING_IMPLEMENTATION_NOTES.md

@@ -16,3 +16,12 @@ line — headings are the primary intended use case for this property. Not a des
 layout algorithm choice, so it's hardcoded rather than pulled from `recursica_variables_scoped.css`.
 Chromium/Firefox only balance up to ~6 lines, which comfortably covers heading text. No fallback
 needed — browsers that don't support the value just ignore the declaration.
+
+## Heading owns semantic `h1`-`h6` (Matt Massey, 2026-10-08)
+
+**Decision:** `Heading` is the only component that renders semantic `<h1>`-`<h6>` elements. Each
+`order` maps to a heading level that Recursica and Forge define and style
+(`recursica_brand_typography_h{order}`).
+
+**Implementation:** Heading's styles are fixed by the Recursica JSON/CSS. Do not add variants to
+Heading. Any other kind of text belongs in `Text`.

package/src/components/Panel/PANEL_IMPLEMENTATION_NOTES.md

@@ -122,3 +122,11 @@ Project-wide fix; see Chip's `CHIP_IMPLEMENTATION_NOTES.md` for the original dis
 **Decision:** The `border-radius` token is applied only to the corners on the edge that faces the page, not all four.
 
 **Implementation:** A panel with `placement="right"` (the default) rounds its upper-left and lower-left corners only; its right corners are square against the screen edge. A panel with `placement="left"` rounds its upper-right and lower-right corners only. `Panel.tsx` adds `.contentRight` / `.contentLeft` to the `content` class, and those zero the two outer corners. `top` and `bottom` placements are unchanged (all four corners rounded).
+
+---
+
+## 10. Always non-modal (Matt Massey, 2026-10-08)
+
+**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.

package/src/components/Panel/Panel.tsx

@@ -13,7 +13,6 @@ import {
 import {
   filterStylingProps,
   mergeClassNames,
-  withCallerOverride,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./Panel.module.css";
@@ -30,7 +29,18 @@ import { type RecursicaPanelProps as BaseRecursicaPanelProps } from "@recursica/
 export interface RecursicaPanelProps
   extends Omit<
       MantineDrawerProps,
-      "size" | "styles" | "classNames" | "style" | "position" | "opened"
+      | "size"
+      | "styles"
+      | "classNames"
+      | "style"
+      | "position"
+      | "opened"
+      | "withOverlay"
+      | "trapFocus"
+      | "lockScroll"
+      | "returnFocus"
+      | "closeOnEscape"
+      | "closeOnClickOutside"
     >,
     BaseRecursicaPanelProps {}
 
@@ -52,6 +62,10 @@ export type PanelProps = RecursicaOverStyled<RecursicaPanelProps>;
  * </Panel>
  * ```
  *
+ * 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.
+ *
  * Mantine Drawer sub-components available via dot-notation:
  * - `Panel.Header` — Top section with title and close button
  * - `Panel.Title` — Title text within the header
@@ -98,10 +112,13 @@ const PanelBase = function Panel({
       size="var(--recursica_ui-kit_components_panel_properties_max-width)"
       position={placement} /* Recursica default: right; Mantine default: left */
       keepMounted={keepMounted}
-      closeOnClickOutside={withCallerOverride(
-        Boolean(rest.opened),
-        rest.closeOnClickOutside,
-      )}
+      /* Always non-modal: the page behind stays usable, Escape always closes */
+      withOverlay={false}
+      trapFocus={false}
+      lockScroll={false}
+      returnFocus
+      closeOnEscape
+      closeOnClickOutside={false}
       classNames={mergedClassNames}
     />
   );

package/src/components/Text/TEXT_IMPLEMENTATION_NOTES.md

@@ -10,3 +10,13 @@ line. Not a design token — it's a layout algorithm choice, so it's hardcoded r
 from `recursica_variables_scoped.css`. Chromium/Firefox only balance up to ~6 lines; longer
 paragraphs silently fall back to normal wrapping past that point. No fallback needed — browsers
 that don't support the value just ignore the declaration.
+
+## Text must never render `h1`-`h6` (Matt Massey, 2026-10-08)
+
+**Decision:** `Text` must never render an `<h1>`-`<h6>` element. It is not allowed. Semantic
+headings use `Heading`.
+
+**Implementation:** `Text` covers every other kind of text in the system (body, labels, captions,
+etc.). Its variants can extend what the Recursica JSON and CSS define, so a variant need not
+exist in the Recursica tokens. Heading levels are the one thing `Text` can't be: they have a
+fixed definition and styling from Recursica and Forge, owned by `Heading`.

package/src/components/Text/Text.headings.dom.test.tsx

@@ -0,0 +1,51 @@
+import React from "react";
+import { describe, it, expect, vi } from "vitest";
+import { createRoot } from "react-dom/client";
+import { flushSync } from "react-dom";
+import { MantineProvider } from "@mantine/core";
+import { Text } from "./Text";
+
+class Boundary extends React.Component<
+  { children: React.ReactNode },
+  { message: string | null }
+> {
+  state = { message: null as string | null };
+  static getDerivedStateFromError(error: Error) {
+    return { message: error.message };
+  }
+  render() {
+    return this.state.message ?? this.props.children;
+  }
+}
+
+function render(component: string): HTMLElement {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const props = { component } as Record<string, unknown>;
+  flushSync(() =>
+    createRoot(container).render(
+      <MantineProvider>
+        <Boundary>
+          <Text {...(props as object)}>Content</Text>
+        </Boundary>
+      </MantineProvider>,
+    ),
+  );
+  return container;
+}
+
+describe("Text heading elements", () => {
+  it.each(["h1", "h2", "h3", "h4", "h5", "h6"])(
+    "throws when component is %s",
+    (component) => {
+      vi.spyOn(console, "error").mockImplementation(() => {});
+      expect(render(component).textContent).toContain(
+        `Text cannot render <${component}>. Use <Heading> for semantic h1-h6.`,
+      );
+    },
+  );
+
+  it.each(["p", "span", "label"])("renders component=%s", (component) => {
+    expect(render(component).querySelector(component)).not.toBeNull();
+  });
+});

package/src/components/Text/Text.tsx

@@ -18,6 +18,8 @@ export type TextProps = RecursicaOverStyled<
   "color"
 >;
 
+const HEADING_ELEMENTS = ["h1", "h2", "h3", "h4", "h5", "h6"];
+
 const _Text = forwardRef<HTMLDivElement, TextProps>(function Text(
   {
     overStyled = false,
@@ -28,6 +30,13 @@ const _Text = forwardRef<HTMLDivElement, TextProps>(function Text(
   },
   ref,
 ) {
+  const component = (rest as { component?: unknown }).component;
+  if (typeof component === "string" && HEADING_ELEMENTS.includes(component)) {
+    throw new Error(
+      `Text cannot render <${component}>. Use <Heading> for semantic h1-h6.`,
+    );
+  }
+
   const sanitizedProps = filterStylingProps(rest, overStyled);
   const classNameProp = (sanitizedProps as Record<string, unknown>)
     .className as string | undefined;

package/.storybook/commonArgTypes.ts

@@ -1,148 +0,0 @@
-/**
- * commonArgTypes.ts
- *
- * This file centralizes the standard Storybook Controls (ArgTypes) for all UI Kit
- * components that natively wrap or extend the `FormControlWrapper`.
- *
- * PHILOSOPHY:
- * Recursica ensures strict unified design boundaries across all form inputs (TextField,
- * CheckboxGroup, Dropdown, etc.). Because they all share the exact same label structures,
- * layout variants (stacked vs side-by-side), and assistive text bindings natively supplied
- * by the `FormControlWrapper`, their Storybook experiences should be exactly identical.
- *
- * USAGE:
- * Rather than recreating these controls inside every `Component.stories.tsx` file,
- * developers must spread this object directly into the `argTypes` of their story default block:
- *
- * ```tsx
- * import { formControlArgTypes } from "../../.storybook/commonArgTypes";
- *
- * export default {
- *   component: TextField,
- *   argTypes: {
- *     ...formControlArgTypes,
- *     // Component-specific argTypes below...
- *   }
- * }
- * ```
- */
-import type { ArgTypes } from "@storybook/react";
-
-export const formControlArgTypes: Partial<ArgTypes> = {
-  formLayout: {
-    control: "inline-radio",
-    options: ["stacked", "side-by-side"],
-    description:
-      "Determines the structural flow layout of the Label relative to the Input.",
-    table: {
-      category: "Form Layout",
-    },
-  },
-  labelSize: {
-    control: "inline-radio",
-    options: ["default", "small"],
-    description:
-      "Adjusts the typographical boundaries bounding the Label section.",
-    table: {
-      category: "Form Layout",
-    },
-  },
-  labelAlignment: {
-    control: "inline-radio",
-    options: ["left", "right"],
-    description:
-      "Adjusts the explicit text alignment axis exclusively evaluating side-by-side structures.",
-    table: {
-      category: "Form Layout",
-    },
-  },
-  labelOptionalText: {
-    control: "text",
-    description:
-      "Optional secondary stylistic text injected alongside the primary Label node.",
-    table: {
-      category: "Form Layout",
-    },
-  },
-  labelWithEditIcon: {
-    control: "boolean",
-    description:
-      "Dynamically toggles interactivity hooks revealing the Edit context icon.",
-    table: {
-      category: "Form Layout",
-    },
-  },
-  description: {
-    table: {
-      disable: true,
-    },
-  },
-  assistiveText: {
-    control: "text",
-    description:
-      "Helper instructions safely dynamically anchored below the input box natively outperforming description.",
-    table: {
-      category: "Form Layout",
-    },
-  },
-  assistiveWithIcon: {
-    control: "boolean",
-    description:
-      "Toggles native Recursica Info-styling rendering universally alongside the assistive block.",
-    table: {
-      category: "Form Layout",
-    },
-  },
-  error: {
-    control: "text",
-    description:
-      "Dynamically maps error feedback validation strings rendering explicit error states.",
-    table: {
-      category: "Form State",
-    },
-  },
-  required: {
-    control: "boolean",
-    description:
-      "Native DOM compliance flag explicitly marking the field as required natively.",
-    table: {
-      category: "Form State",
-    },
-  },
-  disabled: {
-    control: "boolean",
-    description:
-      "Globally disables interactive components bounding all click and focus logic natively.",
-    table: {
-      category: "Form State",
-    },
-  },
-  withAsterisk: {
-    control: "boolean",
-    description:
-      "Visually forces the mandatory asterisk presence completely independent of logical 'required' attribute properties.",
-    table: {
-      category: "Form State",
-    },
-  },
-  labelActionArea: {
-    table: {
-      disable: true,
-    },
-  },
-  onLabelEditClick: {
-    table: {
-      disable: true,
-    },
-  },
-  controlMaxWidth: {
-    table: {
-      disable: true,
-    },
-  },
-  controlMinWidth: {
-    table: {
-      disable: true,
-    },
-  },
-};