@recursica/adapter-mantine-v8 1.3.1 → 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.1",
+  "version": "1.3.3",
   "publishConfig": {
     "access": "public"
   },
@@ -78,7 +78,7 @@
     "release": "changeset publish"
   },
   "dependencies": {
-    "@recursica/adapter-common": "^1.1.1"
+    "@recursica/adapter-common": "^1.2.0"
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.7",

package/src/components/Card/Card.stories.tsx

@@ -2,6 +2,7 @@ import type { Meta, StoryObj } from "@storybook/react";
 import { Card } from "./Card";
 import { Button } from "../Button/Button";
 import { Group } from "../Group/Group";
+import { Heading } from "../Heading/Heading";
 import { Text } from "../Text/Text";
 
 const meta: Meta<typeof Card> = {
@@ -61,7 +62,7 @@ export const HeaderlessAndFooterless: Story = {
     return (
       <Card {...args}>
         <Card.Content>
-          <Text variant="subtitle">Notice</Text>
+          <Heading order={6}>Notice</Heading>
           <Text>
             This is a completely generic card payload dropping the Header and
             Footer specific elements, simply acting as a padded elevation

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.module.css

@@ -50,3 +50,9 @@
 .root[data-emphasis="low"] {
   opacity: var(--recursica_brand_text-emphasis_low);
 }
+
+/* Dev only (the attribute is never set in production): hides text whose typography variant has no
+   exported style, so a typo is obvious instead of rendering with the UI kit's defaults. */
+.root[data-typography-missing] {
+  visibility: hidden;
+}

package/src/components/Text/Text.stories.tsx

@@ -1,5 +1,15 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { Text } from "./Text";
+import brand from "../../../recursica_brand.json";
+
+const BUILT_IN_VARIANTS = ["body", "caption", "overline"];
+
+// Custom styles defined under `brand.typography` (beyond h1-h6 and the built-ins above); each has
+// an exported `recursica_brand_typography_<name>` class, so `Text` renders it by name.
+// Sorted so the render order is stable across exports (the visual diff depends on it).
+const customVariants = Object.keys(brand.brand.typography)
+  .filter((name) => !/^h[1-6]$/.test(name) && !BUILT_IN_VARIANTS.includes(name))
+  .sort();
 
 const meta: Meta<typeof Text> = {
   title: "UI-Kit/Text",
@@ -16,14 +26,7 @@ const meta: Meta<typeof Text> = {
   argTypes: {
     variant: {
       control: "select",
-      options: [
-        "body",
-        "body-small",
-        "caption",
-        "overline",
-        "subtitle",
-        "subtitle-small",
-      ],
+      options: [...BUILT_IN_VARIANTS, ...customVariants],
       description:
         "Controls the standard logical boundary definitions natively extracted from Figma.",
     },
@@ -62,21 +65,17 @@ export const StaticVariations: Story = {
       <Text variant="body">
         Body (Base paragraph and generic information flow)
       </Text>
-      <Text variant="body-small">
-        Body Small (Compacted list items and helper blocks)
-      </Text>
       <Text variant="caption">
         Caption (Data table descriptions or micro-labels)
       </Text>
       <Text variant="overline">
         Overline (Card contextual pre-headers and categorical tags)
       </Text>
-      <Text variant="subtitle">
-        Subtitle (Minor sub-headers avoiding heavy display weights)
-      </Text>
-      <Text variant="subtitle-small">
-        Subtitle Small (Section anchors deep in hierarchy)
-      </Text>
+      {customVariants.map((name) => (
+        <Text key={name} variant={name}>
+          {name} (Custom style from brand.typography)
+        </Text>
+      ))}
     </div>
   ),
 };
@@ -122,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

@@ -10,6 +10,7 @@ import {
 } from "../../utils/filterStylingProps";
 
 import { type RecursicaTextProps } from "@recursica/adapter-common";
+import { isTypographyStyleDefined } from "../../utils/typographyClass";
 import styles from "./Text.module.css";
 
 export type TextProps = RecursicaOverStyled<
@@ -17,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,
@@ -27,10 +30,24 @@ 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;
 
+  // Dev only: an unknown variant hides the text (and logs) instead of silently rendering with the
+  // UI kit's default styling.
+  const typographyMissing =
+    process.env.NODE_ENV !== "production" &&
+    typeof document !== "undefined" &&
+    !isTypographyStyleDefined(variant);
+
   const typographyClass = `recursica_brand_typography_${variant}`;
   const mergedClassName = [typographyClass, styles.root, classNameProp]
     .filter(Boolean)
@@ -45,6 +62,7 @@ const _Text = forwardRef<HTMLDivElement, TextProps>(function Text(
       {...(sanitizedProps as unknown as MantineTextProps)}
       data-color={color}
       data-emphasis={emphasis}
+      data-typography-missing={typographyMissing || undefined}
       className={mergedClassName}
     />
   );

package/src/components/TimePicker/TimePicker.module.css

@@ -58,10 +58,7 @@
   gap: var(--recursica_ui-kit_components_time-picker_properties_icon-text-gap);
   position: relative;
   box-sizing: border-box;
-  /* min-width, not width: the `width` token was authored for a single plain input (confirmed against
-     text-field's identical token shape); this is now only the time-entry half of the composite. */
-  min-width: var(--recursica_ui-kit_components_time-picker_properties_width);
-  width: fit-content;
+  width: var(--recursica_ui-kit_components_time-picker_properties_width);
   /* time-picker has no dedicated min-height token (unlike text-field/date-picker); this global is
      the one text-field's own min-height token resolves to, so both controls land on the same 48px
      height without binding to another component's own namespace. See
@@ -209,27 +206,14 @@
    this only controls its size/alignment within the flex row. */
 .amPmSelect {
   flex: 0 0 auto;
-  width: auto;
-  min-width: 5.5rem;
+  width: var(--recursica_ui-kit_components_time-picker_properties_width);
 }
 
-/* Dropdown.module.css's own .input sets width: 100% (correct for a standalone Dropdown filling
-   its own column) — resetting that to `auto` still isn't enough here: a native <input>'s intrinsic
-   ("auto"/"fit-content") width is a fixed UA default (~20 characters wide), not based on its actual
-   value text, so it doesn't naturally shrink to "AM"/"PM" either way. Give it an explicit small
-   width sized for a couple of characters instead — the wrapper (.amPmSelect, whose own rendered
-   width just follows this input, since Dropdown.module.css's .section icon is positioned
-   absolutely and doesn't add to flex flow) ends up hugging the content as a result. Target
-   Mantine's own stable global class (not the Dropdown.module.css hash, which this module can't
-   reference directly). See TIMEPICKER_IMPLEMENTATION_NOTES.md.
-   Width math (box-sizing: border-box, so padding eats into this number): Dropdown's own
-   horizontal-padding (16px) on the left + the chevron's reserved right-section padding
-   (horizontal-padding + icon-size + icon-text-gap = 16+24+8 = 48px) on the right leaves very
-   little room for the "AM"/"PM" text itself — 2.5rem (40px) put the padding in a negative content
-   box, which is why the value was invisible and the chevron looked jammed against the border. 6rem
-   leaves a real ~32px content area. */
+/* Fill .amPmSelect, which carries the time-picker width token (Dropdown's own .input is
+   otherwise a native input with a fixed UA-default intrinsic width). Target Mantine's stable
+   global class; this module can't reference Dropdown.module.css's hashed class. */
 .amPmSelect :global(.mantine-Select-input) {
-  width: 6rem;
+  width: 100%;
 }
 
 /* -------------------------------------

package/src/utils/typographyClass.ts

@@ -0,0 +1,38 @@
+const found = new Set<string>();
+const reported = new Set<string>();
+
+function ruleListDefines(rules: CSSRuleList, selector: string): boolean {
+  return Array.from(rules).some((rule) => {
+    if (rule instanceof CSSStyleRule) {
+      return rule.selectorText.split(",").some((s) => s.trim() === selector);
+    }
+    const nested = (rule as CSSGroupingRule).cssRules;
+    return nested ? ruleListDefines(nested, selector) : false;
+  });
+}
+
+/**
+ * Dev-only: whether a `.recursica_brand_typography_<name>` rule exists in any readable stylesheet.
+ * Logs a console error once per missing name. Cross-origin stylesheets can't be read and are
+ * skipped, so they never count as defining the class.
+ */
+export function isTypographyStyleDefined(name: string): boolean {
+  const selector = `.recursica_brand_typography_${name}`;
+  if (found.has(selector)) return true;
+  const defined = Array.from(document.styleSheets).some((sheet) => {
+    try {
+      return ruleListDefines(sheet.cssRules, selector);
+    } catch {
+      return false;
+    }
+  });
+  if (defined) {
+    found.add(selector);
+  } else if (!reported.has(selector)) {
+    reported.add(selector);
+    console.error(
+      `Text: no "${selector}" rule found. "${name}" is not defined under brand.typography in the exported Recursica CSS, so the text is hidden.`,
+    );
+  }
+  return defined;
+}