@recursica/mantine-adapter 0.51.0 → 0.52.0

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mantine-adapter"
   },
-  "version": "0.51.0",
+  "version": "0.52.0",
   "type": "module",
   "main": "./dist/mantine-adapter.cjs",
   "module": "./dist/mantine-adapter.js",
@@ -95,7 +95,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@recursica/adapter-common": "^0.25.1",
+    "@recursica/adapter-common": "^0.26.0",
     "@recursica/official-release": "^2.8.0"
   },
   "peerDependencies": {

package/src/Introduction.stories.tsx

@@ -6,7 +6,7 @@ import {
   Container,
   Stack,
   Group,
-  Title,
+  Heading,
   Text,
   Link,
   Button,
@@ -21,9 +21,9 @@ function IntroductionContent() {
       <Group gap="rec-md" mb="rec-xl" align="flex-start" wrap="nowrap">
         <MantineLogo width={80} height={80} />
         <Stack gap={0}>
-          <Title order={1} m={0}>
+          <Heading order={1} m={0}>
             Recursica Design System (Mantine Adapter)
-          </Title>
+          </Heading>
           <Link href="https://mantine.dev" target="_blank" rel="noreferrer">
             mantine.dev
           </Link>
@@ -36,9 +36,9 @@ function IntroductionContent() {
       </Text>
 
       <Stack mb="rec-xl">
-        <Title order={2} mb="rec-md">
+        <Heading order={2} mb="rec-md">
           Looking for another UI Kit?
-        </Title>
+        </Heading>
         <Text mb="rec-md">
           Are you using a different UI Kit (like Material UI)? Recursica
           provides multiple adapters for different frameworks.
@@ -56,9 +56,9 @@ function IntroductionContent() {
       </Stack>
 
       <Stack mb="rec-xl">
-        <Title order={2} mb="rec-md">
+        <Heading order={2} mb="rec-md">
           Installation
-        </Title>
+        </Heading>
         <Text mb="rec-md">
           To install the Mantine adapter in your project, run:
         </Text>
@@ -78,9 +78,9 @@ function IntroductionContent() {
       </Stack>
 
       <Stack mb="rec-xl">
-        <Title order={2} mb="rec-md">
+        <Heading order={2} mb="rec-md">
           Tokens
-        </Title>
+        </Heading>
         <Text mb="rec-md">
           Raw design tokens (colors, sizes, font weights, opacities, etc.) that
           feed the theme and components. These are the primitive values defined
@@ -89,9 +89,9 @@ function IntroductionContent() {
       </Stack>
 
       <Stack mb="rec-xl">
-        <Title order={2} mb="rec-md">
+        <Heading order={2} mb="rec-md">
           Theme
-        </Title>
+        </Heading>
         <Text mb="rec-md">
           Brand and theme layer built on top of tokens. Typography types,
           dimensions, and layout grids are defined here. Theme uses the tokens
@@ -101,9 +101,9 @@ function IntroductionContent() {
       </Stack>
 
       <Stack mb="rec-xl">
-        <Title order={2} mb="rec-md">
+        <Heading order={2} mb="rec-md">
           Configuring Recursica
-        </Title>
+        </Heading>
         <Text mb="rec-md">
           To modify the Recursica configuration (tokens, brand, theme), go to{" "}
           <Link href={FORGE_URL} target="_blank" rel="noopener noreferrer">
@@ -114,9 +114,9 @@ function IntroductionContent() {
       </Stack>
 
       <Stack mb="rec-xl">
-        <Title order={2} mb="rec-md">
+        <Heading order={2} mb="rec-md">
           Documentation
-        </Title>
+        </Heading>
         <Text mb="rec-md">
           For full documentation, guides, and API reference, visit{" "}
           <Link href={DOCS_URL} target="_blank" rel="noopener noreferrer">

package/src/OverStyling.tsx

@@ -3,7 +3,7 @@ import { TypographyStylesProvider } from "@mantine/core";
 import {
   Container,
   Card,
-  Title,
+  Heading,
   Text as RawText,
   Group,
   Stack,
@@ -36,9 +36,9 @@ export const OverStylingInfo = () => {
             my="rec-xl"
           />
 
-          <Title order={3} mb="rec-md">
+          <Heading order={3} mb="rec-md">
             Try It Yourself
-          </Title>
+          </Heading>
 
           <Group mb="rec-xl">
             <Switch

package/src/components/Card/USAGE.md

@@ -22,7 +22,7 @@ export default function Demo() {
   return (
     <Card>
       <Card.Header>
-        <Title order={3}>Card Title</Title>
+        <Heading order={3}>Card Title</Heading>
       </Card.Header>
       <Card.Content>
         <Text>

package/src/components/{Title/TITLE_IMPLEMENTATION_NOTES.md → Heading/HEADING_IMPLEMENTATION_NOTES.md}

@@ -1,8 +1,14 @@
-# Title – Implementation Notes
+# Heading – Implementation Notes
+
+## Renamed from `Title` (Matt Massey, 2026-08-28)
+
+**Decision:** Renamed the component from `Title` to `Heading` — designers refer to semantic tags
+(`h1`-`h6`, `span`, `p`), and "Title" wasn't part of that vocabulary. `Heading` + `Text` are now
+Recursica's common typography component names across all adapters. No behavior change.
 
 ## `.root` `text-wrap: balance` (Matt Massey, 2026-08-28)
 
-**Decision:** Added `text-wrap: balance` via a new `Title.module.css` `.root` class, merged onto
+**Decision:** Added `text-wrap: balance` via a new `Heading.module.css` `.root` class, merged onto
 the typography class for every `order` (h1–h6), alongside the caller's own `className`.
 
 **Implementation:** UX asked for more evenly balanced multi-line wrapping instead of a ragged last

package/src/components/{Title/Title.module.css → Heading/Heading.module.css}

@@ -1,7 +1,7 @@
 /*
  * HARDCODED VALUES
  * - `.root` `text-wrap: balance` — not a design token; a layout algorithm choice requested by
- *   UX (Matt Massey, 2026-08-28) to even out wrapped line lengths. See TEXT_IMPLEMENTATION_NOTES.md.
+ *   UX (Matt Massey, 2026-08-28) to even out wrapped line lengths. See HEADING_IMPLEMENTATION_NOTES.md.
  */
 
 .root {

package/src/components/{Title/Title.stories.tsx → Heading/Heading.stories.tsx}

@@ -1,15 +1,15 @@
 import type { Meta, StoryObj } from "@storybook/react";
-import { Title } from "./Title";
+import { Heading } from "./Heading";
 
-const meta: Meta<typeof Title> = {
-  title: "UI-Kit/Title",
-  component: Title,
+const meta: Meta<typeof Heading> = {
+  title: "UI-Kit/Heading",
+  component: Heading,
   tags: ["autodocs"],
   parameters: {
     docs: {
       description: {
         component:
-          "The semantic `<Title>` abstraction intrinsically links pure `h1-h6` tag generation with exact Recursica design boundaries to preserve SEO and screen reader trees uniformly globally.",
+          "The semantic `<Heading>` abstraction intrinsically links pure `h1-h6` tag generation with exact Recursica design boundaries to preserve SEO and screen reader trees uniformly globally.",
       },
     },
   },
@@ -25,26 +25,26 @@ const meta: Meta<typeof Title> = {
 
 export default meta;
 
-type Story = StoryObj<typeof Title>;
+type Story = StoryObj<typeof Heading>;
 
 export const Default: Story = {
   args: {
     order: 1,
     children: "Semantic H1 Document Boundary",
   },
-  render: ({ ...args }) => <Title {...args} />,
+  render: ({ ...args }) => <Heading {...args} />,
 };
 
 export const StaticVariations: Story = {
   args: {},
   render: () => (
     <div style={{ display: "flex", flexDirection: "column", gap: "24px" }}>
-      <Title order={1}>H1 Title</Title>
-      <Title order={2}>H2 Title</Title>
-      <Title order={3}>H3 Title</Title>
-      <Title order={4}>H4 Title</Title>
-      <Title order={5}>H5 Title</Title>
-      <Title order={6}>H6 Title</Title>
+      <Heading order={1}>H1 Heading</Heading>
+      <Heading order={2}>H2 Heading</Heading>
+      <Heading order={3}>H3 Heading</Heading>
+      <Heading order={4}>H4 Heading</Heading>
+      <Heading order={5}>H5 Heading</Heading>
+      <Heading order={6}>H6 Heading</Heading>
     </div>
   ),
 };

package/src/components/Heading/Heading.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Heading component tests. Add tests here if/when needed.

package/src/components/Heading/Heading.tsx

@@ -0,0 +1,52 @@
+import { forwardRef } from "react";
+import {
+  Title as MantineTitle,
+  type TitleProps as MantineTitleProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  omitUnsupportedProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+
+import { type RecursicaHeadingProps } from "@recursica/adapter-common";
+import styles from "./Heading.module.css";
+
+export type HeadingProps = RecursicaOverStyled<
+  Omit<MantineTitleProps, "size"> & RecursicaHeadingProps
+>;
+
+/**
+ * Enforces highly accessible structural markup utilizing semantic `<h1>` through `<h6>` tags securely bound directly to Recursica typographic scales.
+ */
+export const Heading = forwardRef<HTMLHeadingElement, HeadingProps>(
+  function Heading({ overStyled = false, order = 1, ...rest }, ref) {
+    // Props this component intentionally doesn't support — deleted at runtime so they can't leak
+    // through even if a caller forces them via plain JavaScript, bypassing the `Omit<>` above.
+    const UNSUPPORTED_PROPS = [
+      "size", // Recursica controls Heading sizing via the `order` prop + typography tokens, not Mantine's native `size`.
+    ] as const satisfies readonly (keyof MantineTitleProps)[];
+
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled),
+      UNSUPPORTED_PROPS,
+    );
+    const classNameProp = (sanitizedProps as Record<string, unknown>)
+      .className as string | undefined;
+
+    const typographyClass = `recursica_brand_typography_h${order}`;
+    const mergedClassName = [typographyClass, styles.root, classNameProp]
+      .filter(Boolean)
+      .join(" ");
+
+    return (
+      <MantineTitle
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineTitleProps)}
+        order={order}
+        className={mergedClassName}
+      />
+    );
+  },
+);
+Heading.displayName = "Heading";

package/src/components/{Title → Heading}/USAGE.md

@@ -1,13 +1,13 @@
-# Title - Usage Guide
+# Heading - Usage Guide
 
-This document describes how to integrate and use the `Title` component in your projects using `@recursica/mantine-adapter`.
+This document describes how to integrate and use the `Heading` component in your projects using `@recursica/mantine-adapter`.
 
 ---
 
 ## 1. Import Reference
 
 ```tsx
-import { Title } from "@recursica/mantine-adapter";
+import { Heading } from "@recursica/mantine-adapter";
 ```
 
 ---
@@ -16,10 +16,10 @@ import { Title } from "@recursica/mantine-adapter";
 
 ```tsx
 import React from "react";
-import { Title } from "@recursica/mantine-adapter";
+import { Heading } from "@recursica/mantine-adapter";
 
 export default function Demo() {
-  return <Title order={1}>This is a Heading 1</Title>;
+  return <Heading order={1}>This is a Heading 1</Heading>;
 }
 ```
 

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

@@ -9,7 +9,7 @@ const meta: Meta<typeof Text> = {
     docs: {
       description: {
         component:
-          "The standard `<Text>` component controls common body sizing scales and implicit paragraphs governed by the active theme layer. For semantic headings (`h1` through `h6`), use `<Title>` instead.",
+          "The standard `<Text>` component controls common body sizing scales and implicit paragraphs governed by the active theme layer. For semantic headings (`h1` through `h6`), use `<Heading>` instead.",
       },
     },
   },

package/src/components/Text/Text.tsx

@@ -41,7 +41,7 @@ _Text.displayName = "Text";
 
 /**
  * A generalized typographical wrapper limiting text properties to bounded Recursica UI-kit tokens inherently.
- * Do not use for semantic headings; use the explicit `<Title>` component for `<h1>` - `<h6>`.
+ * Do not use for semantic headings; use the explicit `<Heading>` component for `<h1>` - `<h6>`.
  *
  * Supports polymorphism via the `component` prop or `renderRoot` for custom element rendering.
  * @example

package/src/components/index.ts

@@ -18,6 +18,7 @@ export * from "./Flex/Flex";
 export * from "./FormControlLayout/FormControlLayout";
 export * from "./Grid/Grid";
 export * from "./Group/Group";
+export * from "./Heading/Heading";
 export * from "./HoverCard/HoverCard";
 export * from "./Link/Link";
 export * from "./Loader/Loader";
@@ -45,7 +46,6 @@ export * from "./TextField/TextField";
 export * from "./TimePicker/TimePicker";
 export * from "./Timeline/Timeline";
 export * from "./Timeline/TimelineItem";
-export * from "./Title/Title";
 export * from "./Toast";
 export * from "./Tooltip/Tooltip";
 export * from "./TransferList/TransferList";

package/src/index.ts

@@ -72,6 +72,9 @@ export const FileUpload = wrapComponent(
 export const FormControlLayout = wrapComponent(
   rawComponents.FormControlLayout,
 ) as typeof rawComponents.FormControlLayout;
+export const Heading = wrapComponent(
+  rawComponents.Heading,
+) as typeof rawComponents.Heading;
 export const HoverCard = wrapComponent(
   rawComponents.HoverCard,
 ) as typeof rawComponents.HoverCard;
@@ -147,9 +150,6 @@ export const Timeline = wrapComponent(
 export const TimelineItem = wrapComponent(
   rawComponents.TimelineItem,
 ) as typeof rawComponents.TimelineItem;
-export const Title = wrapComponent(
-  rawComponents.Title,
-) as typeof rawComponents.Title;
 export const Toast = wrapComponent(
   rawComponents.Toast,
 ) as typeof rawComponents.Toast;

package/src/components/Title/Title.test.tsx

@@ -1 +0,0 @@
-// Placeholder for future Title component tests. Add tests here if/when needed.

package/src/components/Title/Title.tsx

@@ -1,53 +0,0 @@
-import { forwardRef } from "react";
-import {
-  Title as MantineTitle,
-  type TitleProps as MantineTitleProps,
-} from "@mantine/core";
-import {
-  filterStylingProps,
-  omitUnsupportedProps,
-  type RecursicaOverStyled,
-} from "../../utils/filterStylingProps";
-
-import { type RecursicaTitleProps } from "@recursica/adapter-common";
-import styles from "./Title.module.css";
-
-export type TitleProps = RecursicaOverStyled<
-  Omit<MantineTitleProps, "size"> & RecursicaTitleProps
->;
-
-/**
- * Enforces highly accessible structural markup utilizing semantic `<h1>` through `<h6>` tags securely bound directly to Recursica typographic scales.
- */
-export const Title = forwardRef<HTMLHeadingElement, TitleProps>(function Title(
-  { overStyled = false, order = 1, ...rest },
-  ref,
-) {
-  // Props this component intentionally doesn't support — deleted at runtime so they can't leak
-  // through even if a caller forces them via plain JavaScript, bypassing the `Omit<>` above.
-  const UNSUPPORTED_PROPS = [
-    "size", // Recursica controls Title sizing via the `order` prop + typography tokens, not Mantine's native `size`.
-  ] as const satisfies readonly (keyof MantineTitleProps)[];
-
-  const sanitizedProps = omitUnsupportedProps(
-    filterStylingProps(rest, overStyled),
-    UNSUPPORTED_PROPS,
-  );
-  const classNameProp = (sanitizedProps as Record<string, unknown>)
-    .className as string | undefined;
-
-  const typographyClass = `recursica_brand_typography_h${order}`;
-  const mergedClassName = [typographyClass, styles.root, classNameProp]
-    .filter(Boolean)
-    .join(" ");
-
-  return (
-    <MantineTitle
-      ref={ref}
-      {...(sanitizedProps as unknown as MantineTitleProps)}
-      order={order}
-      className={mergedClassName}
-    />
-  );
-});
-Title.displayName = "Title";