@recursica/adapter-mui-v7 1.3.1 → 1.3.3

package/dist/index.d.ts

@@ -985,18 +985,23 @@ export declare const Panel: PanelComponent;
  * </Panel>
  * ```
  *
+ * Always non-modal, with no props to change it: the page behind stays usable
+ * (no overlay, focus trap, scroll lock, `aria-modal` or `aria-hidden` on the
+ * rest of the page), focus returns to the opener on close, Escape always
+ * closes, and outside clicks never do. Implemented with MUI's `persistent`
+ * Drawer variant (no Modal) plus an Escape listener and focus restoration.
+ *
  * Mui 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
  */
 declare const PanelBase: {
-    ({ overStyled, placement, keepMounted, wrapHeaderText, opened, title, withOverlay, withCloseButton, onClose, children, ...rest }: PanelProps): JSX.Element;
+    ({ overStyled, placement, keepMounted, wrapHeaderText, opened, title, withCloseButton, onClose, children, ...rest }: PanelProps): JSX.Element;
     displayName: string;
 };
 
@@ -1208,11 +1213,9 @@ export declare interface RecursicaNumberInputProps extends Omit<InputBaseProps,
 /**
  * Recursica Panel root props. Extends Mui Drawer.
  */
-export declare interface RecursicaPanelProps extends Omit<DrawerProps, "classes" | "position" | "style" | "anchor" | "open" | "title">, RecursicaPanelProps_2 {
+export declare interface RecursicaPanelProps extends Omit<DrawerProps, "classes" | "position" | "style" | "anchor" | "open" | "title" | "variant" | "hideBackdrop" | "ModalProps" | "BackdropComponent" | "BackdropProps" | "disableEscapeKeyDown" | "disableScrollLock" | "disableEnforceFocus" | "disableAutoFocus" | "disableRestoreFocus">, RecursicaPanelProps_2 {
     /** Panel header title label. */
     title?: ReactNode;
-    /** Whether to display a background overlay. Default true. */
-    withOverlay?: boolean;
     /** Whether to display the close button in the header. Default true. */
     withCloseButton?: boolean;
 }

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-mui-v7` 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 MUI, 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 MUI or another underlying UI library.

package/package.json

@@ -12,7 +12,7 @@
     "type": "git",
     "url": "git+https://github.com/borderux/recursica-adapter-mui-v7.git"
   },
-  "version": "1.3.1",
+  "version": "1.3.3",
   "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",
@@ -85,7 +81,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

@@ -0,0 +1,10 @@
+# Heading – Implementation Notes
+
+## 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`, which throws if asked to render `h1`-`h6`.

package/src/components/Panel/PANEL_IMPLEMENTATION_NOTES.md

@@ -131,3 +131,11 @@ clips descenders (e.g. the "g" in a long title) whenever `text_line-height` is t
 font's natural ascent+descent. Switched to `overflow: clip; overflow-clip-margin: 0.35em;` — same
 truncation, but ink can bleed slightly past the line box before it's actually clipped.
 Project-wide fix; see Chip's `CHIP_IMPLEMENTATION_NOTES.md` for the original discovery.
+
+---
+
+## 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 renders MUI's Drawer with `variant="persistent"` (after the caller's props), which has no Modal: no backdrop, no focus trap, no scroll lock, no `aria-modal`, and no `aria-hidden` on the rest of the page. Because there is no Modal, `Panel.tsx` supplies the rest itself: a document `keydown` listener (while open) calls `onClose` on Escape, and focus returns to the opener (the element focused at open) on close. Escape is independent of outside clicks and always closes the panel; clicking the page behind never does. `withOverlay` and MUI's `variant`, `hideBackdrop`, `ModalProps`, `BackdropProps`/`BackdropComponent` and `disable*` (escape, scroll lock, enforce focus, auto focus, restore focus) props are omitted from `RecursicaPanelProps`. Every adapter must match.

package/src/components/Panel/Panel.tsx

@@ -1,4 +1,4 @@
-import { forwardRef, type ReactNode } from "react";
+import { forwardRef, useEffect, useRef, type ReactNode } from "react";
 import {
   Drawer as MuiDrawer,
   type DrawerProps as MuiDrawerProps,
@@ -23,13 +23,26 @@ import { type RecursicaPanelProps as BaseRecursicaPanelProps } from "@recursica/
 export interface RecursicaPanelProps
   extends Omit<
       MuiDrawerProps,
-      "classes" | "position" | "style" | "anchor" | "open" | "title"
+      | "classes"
+      | "position"
+      | "style"
+      | "anchor"
+      | "open"
+      | "title"
+      | "variant"
+      | "hideBackdrop"
+      | "ModalProps"
+      | "BackdropComponent"
+      | "BackdropProps"
+      | "disableEscapeKeyDown"
+      | "disableScrollLock"
+      | "disableEnforceFocus"
+      | "disableAutoFocus"
+      | "disableRestoreFocus"
     >,
     BaseRecursicaPanelProps {
   /** Panel header title label. */
   title?: ReactNode;
-  /** Whether to display a background overlay. Default true. */
-  withOverlay?: boolean;
   /** Whether to display the close button in the header. Default true. */
   withCloseButton?: boolean;
 }
@@ -68,13 +81,18 @@ const CloseIcon = () => (
  * </Panel>
  * ```
  *
+ * Always non-modal, with no props to change it: the page behind stays usable
+ * (no overlay, focus trap, scroll lock, `aria-modal` or `aria-hidden` on the
+ * rest of the page), focus returns to the opener on close, Escape always
+ * closes, and outside clicks never do. Implemented with MUI's `persistent`
+ * Drawer variant (no Modal) plus an Escape listener and focus restoration.
+ *
  * Mui 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
  */
@@ -85,13 +103,37 @@ const PanelBase = function Panel({
   wrapHeaderText = true,
   opened,
   title,
-  withOverlay = true,
   withCloseButton = true,
   onClose,
   children,
   ...rest
 }: PanelProps) {
   const sanitizedProps = filterStylingProps(rest, overStyled);
+  const isOpen = Boolean(opened);
+  const openerRef = useRef<HTMLElement | null>(null);
+  const onCloseRef = useRef(onClose);
+  onCloseRef.current = onClose;
+
+  // Non-modal: there is no Modal to handle Escape or focus restoration, so do both here.
+  useEffect(() => {
+    if (!isOpen) return;
+    openerRef.current = document.activeElement as HTMLElement | null;
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        onCloseRef.current?.(
+          e as unknown as React.SyntheticEvent,
+          "escapeKeyDown",
+        );
+      }
+    };
+    document.addEventListener("keydown", onKeyDown);
+    return () => {
+      document.removeEventListener("keydown", onKeyDown);
+      const opener = openerRef.current;
+      if (opener && opener.isConnected) opener.focus();
+      openerRef.current = null;
+    };
+  }, [isOpen]);
 
   // MUI Drawer's `classes` prop only recognizes its own slot names (`root`, `paper`,
   // `docked`, ...) — unlike Mantine's `classNames`, it has no `content`/`header`/`title`/`body`
@@ -113,10 +155,10 @@ const PanelBase = function Panel({
     <MuiDrawer
       anchor={placement} /* Recursica default: right; Mui default: left */
       keepMounted={keepMounted}
-      open={Boolean(opened)}
-      onClose={onClose}
-      hideBackdrop={!withOverlay}
+      open={isOpen}
       {...(sanitizedProps as unknown as MuiDrawerProps)}
+      /* Always non-modal: persistent variant has no backdrop, focus trap, scroll lock or aria-modal */
+      variant="persistent"
       classes={mergedClassNames as unknown as MuiDrawerProps["classes"]}
     >
       <div

package/src/components/Slider/Slider.module.css

@@ -74,6 +74,8 @@
 
 .sliderRoot {
   width: 100%;
+  /* MUI defaults the root to 4px, so the thumb overflows and the block collapses; match the thumb height. */
+  height: var(--recursica_ui-kit_components_slider_properties_thumb-size);
   box-sizing: border-box;
   color: inherit;
   font-family: inherit;
@@ -84,6 +86,7 @@
 
 .sliderTrack {
   height: var(--recursica_ui-kit_components_slider_properties_track-height);
+  opacity: 1; /* MUI fades the rail to 0.38 by default, which washes out the token color */
   border-radius: var(
     --recursica_ui-kit_components_slider_properties_track-border-radius
   );
@@ -249,6 +252,14 @@
   display: flex !important;
   align-items: center !important;
   justify-content: center !important;
+
+  /* The transform override above defeats MUI's scale(0) hiding, so hide until MUI marks it open. */
+  opacity: 0;
+  pointer-events: none;
+}
+
+.sliderTooltip:global(.MuiSlider-valueLabelOpen) {
+  opacity: 1;
 }
 
 .sliderTooltip * {

package/src/components/Text/TEXT_IMPLEMENTATION_NOTES.md

@@ -18,3 +18,15 @@ accepts any string since `@recursica/adapter-common` 1.2.0). In development, `Te
 if absent it logs one `console.error` per name and sets `data-typography-missing`, which
 `Typography.module.css` hides with `visibility: hidden`. The attribute is never set when
 `NODE_ENV === "production"`.
+
+## 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`. `Text.tsx` throws
+`Text cannot render <hN>. Use <Heading> for semantic h1-h6.` when `component` (or
+`variantMapping.inherit`, which MUI uses to pick the element) is `h1`-`h6`.

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

@@ -0,0 +1,54 @@
+import React from "react";
+import { describe, it, expect, vi } from "vitest";
+import { createRoot } from "react-dom/client";
+import { flushSync } from "react-dom";
+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(props: Record<string, unknown>): HTMLElement {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  flushSync(() =>
+    createRoot(container).render(
+      <Boundary>
+        <Text {...(props as object)}>Content</Text>
+      </Boundary>,
+    ),
+  );
+  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("throws when variantMapping maps to a heading", () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    expect(render({ variantMapping: { inherit: "h2" } }).textContent).toContain(
+      "Text cannot render <h2>.",
+    );
+  });
+
+  it.each(["p", "span", "label"])("renders component=%s", (component) => {
+    expect(render({ component }).querySelector(component)).not.toBeNull();
+  });
+});

package/src/components/Text/Text.tsx

@@ -11,10 +11,26 @@ export type TextProps = RecursicaOverStyled<
   "color"
 >;
 
+const HEADING_ELEMENTS = ["h1", "h2", "h3", "h4", "h5", "h6"];
+
 export const Text = forwardRef<HTMLElement, TextProps>(function Text(
   { variant = "body", emphasis = "high", color = "default", ...rest },
   ref,
 ) {
+  // Text never renders semantic h1-h6; those belong to Heading. MUI picks the element from
+  // `component`, or (for variant "inherit") from `variantMapping.inherit`, so check both.
+  const { component, variantMapping } = rest as {
+    component?: unknown;
+    variantMapping?: Record<string, unknown>;
+  };
+  for (const element of [component, variantMapping?.inherit]) {
+    if (typeof element === "string" && HEADING_ELEMENTS.includes(element)) {
+      throw new Error(
+        `Text cannot render <${element}>. Use <Heading> for semantic h1-h6.`,
+      );
+    }
+  }
+
   // Dev only: an unknown variant hides the text (and logs) instead of silently rendering with the
   // UI kit's default styling.
   const typographyMissing =

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,
-    },
-  },
-};