@recursica/adapter-mantine-v8 1.3.2 → 1.3.3

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/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.3",
   "publishConfig": {
     "access": "public"
   },

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

@@ -21,10 +21,6 @@ const meta: Meta = {
       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.",
@@ -80,7 +76,6 @@ export const Default: Story = {
   args: {
     placement: "right",
     title: "Panel Title",
-    withOverlay: true,
     withCloseButton: true,
     wrapHeaderText: false,
   },
@@ -122,7 +117,6 @@ export const LeftPlacement: Story = {
   args: {
     placement: "left",
     title: "Navigation",
-    withOverlay: true,
     withCloseButton: true,
     wrapHeaderText: false,
   },
@@ -155,7 +149,6 @@ export const ScrollableContent: Story = {
   args: {
     placement: "right",
     title: "Scrollable Panel",
-    withOverlay: true,
     withCloseButton: true,
     wrapHeaderText: false,
   },
@@ -198,7 +191,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",
-    withOverlay: true,
     withCloseButton: true,
     wrapHeaderText: true,
   },

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

@@ -121,3 +121,28 @@ export const Emphasis: Story = {
     </div>
   ),
 };
+
+export const AsElement: Story = {
+  args: {},
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "`component` renders Text as an inline `span`, a `label` or a `div`. `h1` to `h6` throw; use `<Heading>`.",
+      },
+    },
+  },
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "16px" }}>
+      <Text>Default is a block paragraph.</Text>
+      <div>
+        Inline text:{" "}
+        <Text component="span" emphasis="low">
+          a span inside a line
+        </Text>
+        .
+      </div>
+      <Text component="label">A label</Text>
+    </div>
+  ),
+};

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;