@recursica/mui-adapter 0.35.0 → 0.37.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @recursica/mui-adapter
 
+## 0.37.0
+
+### Minor Changes
+
+- 786d870: Version bumped
+
+## 0.36.0
+
+### Minor Changes
+
+- f618b38: Renamed the `Title` component to `Heading` (and `RecursicaTitleProps` to `RecursicaHeadingProps`) to match designers' semantic vocabulary. `Text` is unchanged. Breaking: update imports from `Title`/`TitleProps` to `Heading`/`HeadingProps`.
+
+### Patch Changes
+
+- Updated dependencies [f618b38]
+  - @recursica/adapter-common@0.26.0
+
 ## 0.35.0
 
 ### Minor Changes

package/SETUP.md

@@ -24,16 +24,14 @@ npm install @mui/material@>=7.0.0 @emotion/react@>=11.14.0 @emotion/styled@>=11.
 
 Before consuming Recursica components, integrate the CSS and design tokens into your application:
 
-1. **Theme Files Setup**: When you install `@recursica/mui-adapter`, a postinstall script automatically creates default theme files (including `recursica_variables_scoped.css` and JSON config files) in your project root. If they are missing, simply run `npm install` to create them. To customize or update these variables, you should use [Forge Recursica](https://forge.recursica.com) to export the updated theme files into your project.
-   > [!IMPORTANT] > **AI Agent Directive**: The theme files (`recursica_variables_scoped.css` and associated JSON files) are created at the project root automatically via `npm install`. If they are not present, instruct the user to run `npm install`. Do NOT attempt to generate, mock, or write a placeholder CSS/JSON file yourself. When updates to these files are needed, instruct the user to export them from [Forge Recursica](https://forge.recursica.com) and replace the existing ones.
-2. **Integrate CSS**: Import `recursica_variables_scoped.css` and the MUI adapter CSS `style.css` into your application entrypoint (e.g., `main.tsx` or `App.tsx`).
+1. **Integrate CSS**: Import `recursica_variables_scoped.css` and the MUI adapter CSS `style.css` into your application entrypoint (e.g., `main.tsx` or `App.tsx`).
 
    ```tsx
    import "./path/to/recursica_variables_scoped.css"; // Recursica theme variables
    import "@recursica/mui-adapter/style.css"; // MUI adapter styles
    ```
 
-3. **Configure MUI's CSS Injection & Theme Provider**: Because the Recursica UI components use native CSS modules, they must be given a higher priority than MUI's default engine styles. You **must** wrap your application root in `<StyledEngineProvider injectFirst>` and `<RecursicaThemeProvider theme="light">` to correctly cascade design token properties. By default `RecursicaThemeProvider` also wraps its children in a `<Layer layer={0}>` (via the `initLayer0` prop, which defaults to `true`), so the base page surface/border/elevation variables resolve automatically with no extra setup:
+2. **Configure MUI's CSS Injection & Theme Provider**: Because the Recursica UI components use native CSS modules, they must be given a higher priority than MUI's default engine styles. You **must** wrap your application root in `<StyledEngineProvider injectFirst>` and `<RecursicaThemeProvider theme="light">` to correctly cascade design token properties. By default `RecursicaThemeProvider` also wraps its children in a `<Layer layer={0}>` (via the `initLayer0` prop, which defaults to `true`), so the base page surface/border/elevation variables resolve automatically with no extra setup:
 
    ```tsx
    import { StyledEngineProvider } from "@mui/material/styles";
@@ -50,13 +48,13 @@ Before consuming Recursica components, integrate the CSS and design tokens into
    }
    ```
 
-4. **Integrate Google Fonts**: Integrating custom fonts depends on how you load fonts in your project and which fonts are specified in your `recursica_variables_scoped.css` (since it is project-dependent). We suggest loading them via Google Fonts, as shown in this example:
+3. **Integrate Google Fonts**: Integrating custom fonts depends on how you load fonts in your project and which fonts are specified in your `recursica_variables_scoped.css` (since it is project-dependent). We suggest loading them via Google Fonts, as shown in this example:
 
    ```css
    @import url("https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap");
    ```
 
-5. **Configure PostCSS Plugin (Optional but Recommended)**: It is highly recommended (but optional) to install the `@recursica/recursica-postcss-vars` plugin to verify that Recursica CSS variables are properly connected in case they change.
+4. **Configure PostCSS Plugin (Optional but Recommended)**: It is highly recommended (but optional) to install the `@recursica/recursica-postcss-vars` plugin to verify that Recursica CSS variables are properly connected in case they change.
 
    Install the plugin as a dev dependency:
 
@@ -76,3 +74,19 @@ Before consuming Recursica components, integrate the CSS and design tokens into
      },
    };
    ```
+
+5. **Configure ESLint Plugin (Optional but Recommended)**: It is highly recommended (but optional) to install `eslint-plugin-recursica`, which flags use of the `overStyled` escape-hatch prop so it stays easy to audit.
+
+   Install the plugin as a dev dependency:
+
+   ```bash
+   npm install eslint-plugin-recursica --save-dev
+   ```
+
+   Then, add it to your `eslint.config.js`:
+
+   ```javascript
+   import recursica from "eslint-plugin-recursica";
+
+   export default [recursica.configs.recommended];
+   ```

package/dist/index.d.ts

@@ -690,6 +690,29 @@ declare interface GroupOwnProps {
 
 declare type GroupProps = WithRecursicaSpacing<OmitSx<Omit<StackProps, "spacing" | "direction"> & GroupOwnProps>>;
 
+export declare const Heading: typeof rawComponents.Heading;
+
+declare const Heading_2: default_2.ForwardRefExoticComponent<(Omit<Omit<WithRecursicaSpacing<Omit<TypographyProps, "classes" | "variant"> & RecursicaHeadingProps>, BlockedStylingKeys> & ForbiddenStyles & {
+    overStyled?: false | undefined;
+}, "ref"> | Omit<Omit<Omit<TypographyProps, "classes" | "variant"> & RecursicaHeadingProps, "m" | "my" | "mx" | "mt" | "mb" | "ml" | "mr" | "gap" | "rowGap" | "columnGap" | "gutter" | "spacing"> & {
+    m?: string | number | RecursicaSpacing;
+    mx?: string | number | RecursicaSpacing;
+    my?: string | number | RecursicaSpacing;
+    mt?: string | number | RecursicaSpacing;
+    mb?: string | number | RecursicaSpacing;
+    ml?: string | number | RecursicaSpacing;
+    mr?: string | number | RecursicaSpacing;
+    gap?: string | number | RecursicaSpacing;
+    rowGap?: string | number | RecursicaSpacing;
+    columnGap?: string | number | RecursicaSpacing;
+    gutter?: string | number | RecursicaSpacing;
+    spacing?: string | number | RecursicaSpacing;
+} & {
+    overStyled: true;
+}, "ref">) & default_2.RefAttributes<HTMLElement>>;
+
+declare type HeadingProps = RecursicaOverStyled<Omit<TypographyProps, "variant" | "classes"> & RecursicaHeadingProps>;
+
 export declare const HoverCard: typeof rawComponents.HoverCard;
 
 declare const HoverCard_2: HoverCardComponent;
@@ -1329,6 +1352,8 @@ declare namespace rawComponents {
         Grid_2 as Grid,
         GroupProps,
         Group_2 as Group,
+        HeadingProps,
+        Heading_2 as Heading,
         HoverCardProps,
         HoverCardTargetProps,
         HoverCardDropdownProps,
@@ -1440,8 +1465,6 @@ declare namespace rawComponents {
         Timeline_2 as Timeline,
         TimelineItemProps_2 as TimelineItemProps,
         TimelineItem_2 as TimelineItem,
-        TitleProps,
-        Title_2 as Title,
         RecursicaToastProps,
         ToastProps,
         Toast_2 as Toast,
@@ -1487,7 +1510,7 @@ export declare type ReadOnlyFieldType = "text" | "number" | "date" | "boolean" |
 /**
  * Official list of all components in Recursica.
  */
-export declare const RECURSICA_COMPONENTS: readonly ["Accordion", "AssistiveElement", "Autocomplete", "Avatar", "Badge", "Box", "Breadcrumb", "Button", "Card", "Checkbox", "CheckboxGroup", "Chip", "Container", "DatePicker", "Dropdown", "EmptyValueRenderer", "FileInput", "FileUpload", "Flex", "FormControlLayout", "FormControlWrapper", "Grid", "Group", "HoverCard", "Label", "Layer", "Link", "Loader", "Menu", "Modal", "NumberInput", "Pagination", "Panel", "Popover", "Radio", "ReadOnlyField", "SegmentedControl", "Slider", "Stack", "Stepper", "Switch", "Table", "Tabs", "Text", "TextArea", "TextField", "TimePicker", "Timeline", "Title", "Toast", "Tooltip", "TransferList", "Tree", "Typography"];
+export declare const RECURSICA_COMPONENTS: readonly ["Accordion", "AssistiveElement", "Autocomplete", "Avatar", "Badge", "Box", "Breadcrumb", "Button", "Card", "Checkbox", "CheckboxGroup", "Chip", "Container", "DatePicker", "Dropdown", "EmptyValueRenderer", "FileInput", "FileUpload", "Flex", "FormControlLayout", "FormControlWrapper", "Grid", "Group", "Heading", "HoverCard", "Label", "Layer", "Link", "Loader", "Menu", "Modal", "NumberInput", "Pagination", "Panel", "Popover", "Radio", "ReadOnlyField", "SegmentedControl", "Slider", "Stack", "Stepper", "Switch", "Table", "Tabs", "Text", "TextArea", "TextField", "TimePicker", "Timeline", "Toast", "Tooltip", "TransferList", "Tree", "Typography"];
 
 /**
  * Props for the Recursica Accordion Control component.
@@ -2044,6 +2067,18 @@ declare interface RecursicaFormControlWrapperProps_2 extends RecursicaLabelProps
     controlMinWidth?: string | undefined;
 }
 
+/**
+ * Props for the Recursica Heading component.
+ */
+export declare interface RecursicaHeadingProps extends default_2.HTMLAttributes<HTMLHeadingElement> {
+    /** Heading ordering hierarchies (1 represents H1, 6 represents H6) */
+    order?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Heading contents */
+    children?: default_2.ReactNode;
+    /** Polymorphic component override */
+    component?: default_2.ElementType;
+}
+
 /**
  * Props for the Recursica HoverCard component.
  */
@@ -2558,18 +2593,6 @@ declare interface RecursicaTimePickerProps_2 {
     maxTime?: string;
 }
 
-/**
- * Props for the Recursica Title component.
- */
-export declare interface RecursicaTitleProps extends default_2.HTMLAttributes<HTMLHeadingElement> {
-    /** Heading ordering hierarchies (1 represents H1, 6 represents H6) */
-    order?: 1 | 2 | 3 | 4 | 5 | 6;
-    /** Title contents */
-    children?: default_2.ReactNode;
-    /** Polymorphic component override */
-    component?: default_2.ElementType;
-}
-
 export declare interface RecursicaToastProps extends RecursicaToastProps_2 {
     withCloseButton?: boolean;
     title?: default_2.ReactNode;
@@ -3344,29 +3367,6 @@ declare const TimePicker_2: default_2.ForwardRefExoticComponent<TimePickerProps_
 
 declare type TimePickerProps_2 = RecursicaOverStyled<RecursicaTimePickerProps>;
 
-export declare const Title: typeof rawComponents.Title;
-
-declare const Title_2: default_2.ForwardRefExoticComponent<(Omit<Omit<WithRecursicaSpacing<Omit<TypographyProps, "classes" | "variant"> & RecursicaTitleProps>, BlockedStylingKeys> & ForbiddenStyles & {
-    overStyled?: false | undefined;
-}, "ref"> | Omit<Omit<Omit<TypographyProps, "classes" | "variant"> & RecursicaTitleProps, "m" | "my" | "mx" | "mt" | "mb" | "ml" | "mr" | "gap" | "rowGap" | "columnGap" | "gutter" | "spacing"> & {
-    m?: string | number | RecursicaSpacing;
-    mx?: string | number | RecursicaSpacing;
-    my?: string | number | RecursicaSpacing;
-    mt?: string | number | RecursicaSpacing;
-    mb?: string | number | RecursicaSpacing;
-    ml?: string | number | RecursicaSpacing;
-    mr?: string | number | RecursicaSpacing;
-    gap?: string | number | RecursicaSpacing;
-    rowGap?: string | number | RecursicaSpacing;
-    columnGap?: string | number | RecursicaSpacing;
-    gutter?: string | number | RecursicaSpacing;
-    spacing?: string | number | RecursicaSpacing;
-} & {
-    overStyled: true;
-}, "ref">) & default_2.RefAttributes<HTMLElement>>;
-
-declare type TitleProps = RecursicaOverStyled<Omit<TypographyProps, "variant" | "classes"> & RecursicaTitleProps>;
-
 export declare const Toast: typeof rawComponents.Toast;
 
 declare const Toast_2: default_2.ForwardRefExoticComponent<(Omit<Omit<WithRecursicaSpacing<Omit<AlertProps, "color" | "variant" | "onClose" | "radius"> & RecursicaToastProps>, BlockedStylingKeys> & ForbiddenStyles & {