@recursica/adapter-mui-v7 1.0.0

package/src/components/Tabs/Tabs.stories.tsx

@@ -0,0 +1,174 @@
+import React, { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Tabs, Tab, TabPanel } from "./Tabs";
+import { TabContext } from "@mui/lab";
+import { Flex } from "../Flex/Flex";
+
+const meta: Meta<typeof Tabs> = {
+  title: "UI-Kit/Tabs",
+  component: Tabs,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+  argTypes: {
+    variant: {
+      control: "radio",
+      options: ["default", "outline", "pills"],
+    },
+    orientation: {
+      control: "radio",
+      options: ["horizontal", "vertical"],
+    },
+    // @ts-expect-error Custom prop not in native TabsProps
+    disabled: {
+      control: "boolean",
+    },
+    defaultChecked: {
+      table: {
+        disable: true,
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Tabs>;
+
+const InteractiveTabs = (
+  args: React.ComponentProps<typeof Tabs> & {
+    disabled?: boolean;
+    inverted?: boolean;
+  },
+) => {
+  const [value, setValue] = useState("gallery");
+
+  const handleChange = (_event: React.SyntheticEvent, newValue: string) => {
+    setValue(newValue);
+  };
+
+  return (
+    <Flex
+      direction={args.orientation === "vertical" ? "row" : "column"}
+      style={{ width: 600, height: 300 }}
+    >
+      <TabContext value={value}>
+        <Tabs value={value} onChange={handleChange} {...args}>
+          <Tab
+            value="gallery"
+            label="Gallery"
+            disabled={args.disabled}
+            icon={
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                width={16}
+                height={16}
+              >
+                <rect x="3" y="3" width="18" height="18" rx="2" ry="2"></rect>
+                <circle cx="8.5" cy="8.5" r="1.5"></circle>
+                <polyline points="21 15 16 10 5 21"></polyline>
+              </svg>
+            }
+            iconPosition="start"
+          />
+          <Tab
+            value="messages"
+            label="Messages"
+            disabled={args.disabled}
+            icon={
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                width={16}
+                height={16}
+              >
+                <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"></path>
+              </svg>
+            }
+            iconPosition="start"
+          />
+          <Tab
+            value="settings"
+            label="Settings"
+            disabled={args.disabled}
+            icon={
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                width={16}
+                height={16}
+              >
+                <circle cx="12" cy="12" r="3"></circle>
+                <path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 0 1 0 2.83 2 2 0 0 1-2.83 0l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-2 2 2 2 0 0 1-2-2v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 0 1-2.83 0 2 2 0 0 1 0-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1-2-2 2 2 0 0 1 2-2h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 0 1 0-2.83 2 2 0 0 1 2.83 0l.06.06a1.65 1.65 0 0 0 1.82.33H9a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 2-2 2 2 0 0 1 2 2v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 0 1 2.83 0 2 2 0 0 1 0 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 2 2 2 2 0 0 1-2 2h-.09a1.65 1.65 0 0 0-1.51 1z"></path>
+              </svg>
+            }
+            iconPosition="start"
+          />
+        </Tabs>
+
+        <TabPanel value="gallery">Gallery tab content</TabPanel>
+
+        <TabPanel value="messages">Messages tab content</TabPanel>
+
+        <TabPanel value="settings">Settings tab content</TabPanel>
+      </TabContext>
+    </Flex>
+  );
+};
+
+export const Default: Story = {
+  render: (args) => <InteractiveTabs {...args} />,
+  args: {
+    variant: "default",
+    orientation: "horizontal",
+  },
+};
+
+export const Outline: Story = {
+  render: (args) => <InteractiveTabs {...args} />,
+  args: {
+    variant: "outline",
+    orientation: "horizontal",
+  },
+};
+
+export const Pills: Story = {
+  render: (args) => <InteractiveTabs {...args} />,
+  args: {
+    variant: "pills",
+    orientation: "horizontal",
+  },
+};
+
+export const Vertical: Story = {
+  render: (args) => <InteractiveTabs {...args} />,
+  args: {
+    variant: "default",
+    orientation: "vertical",
+  },
+};
+
+export const Inverted: Story = {
+  render: (args) => <InteractiveTabs {...args} />,
+  args: {
+    variant: "default",
+    orientation: "horizontal",
+    inverted: true,
+  },
+};

package/src/components/Tabs/Tabs.test.tsx

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

package/src/components/Tabs/Tabs.tsx

@@ -0,0 +1,103 @@
+import { forwardRef } from "react";
+import {
+  Tabs as MuiTabs,
+  type TabsProps as MuiTabsProps,
+  Tab as MuiTab,
+  type TabProps as MuiTabProps,
+} from "@mui/material";
+import {
+  filterStylingProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Tabs.module.css";
+
+import { type RecursicaTabsProps } from "@recursica/adapter-common";
+
+export interface RecursicaTabsPropsExtended
+  extends Omit<MuiTabsProps, "variant">,
+    RecursicaTabsProps {}
+
+export type TabsProps = RecursicaOverStyled<RecursicaTabsPropsExtended>;
+
+export const Tabs = forwardRef<HTMLDivElement, TabsProps>(
+  function Tabs(props, ref) {
+    const {
+      variant = "default",
+      orientation = "horizontal",
+      inverted = false,
+      overStyled = false,
+      className,
+      ...rest
+    } = props;
+
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+
+    const mergedClassNames = mergeClassNames(
+      {
+        flexContainer: styles.list,
+        indicator: styles.indicator,
+      },
+      (sanitizedProps as Record<string, unknown>).classes as
+        | Partial<Record<string, string>>
+        | undefined,
+    );
+
+    return (
+      <MuiTabs
+        ref={ref}
+        {...(sanitizedProps as MuiTabsProps)}
+        orientation={orientation}
+        className={`${styles.root} ${className || ""}`}
+        data-variant={variant}
+        data-orientation={orientation}
+        data-inverted={inverted || undefined}
+        classes={mergedClassNames}
+      />
+    );
+  },
+);
+
+Tabs.displayName = "Tabs";
+
+export type TabProps = RecursicaOverStyled<MuiTabProps>;
+
+export const Tab = forwardRef<HTMLDivElement, TabProps>(
+  function Tab(props, ref) {
+    const { overStyled = false, className, ...rest } = props;
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+
+    return (
+      <MuiTab
+        ref={ref}
+        disableRipple
+        className={`${styles.tab} ${className || ""}`}
+        {...(sanitizedProps as MuiTabProps)}
+      />
+    );
+  },
+);
+
+Tab.displayName = "Tab";
+
+import { TabPanel as MuiTabPanel } from "@mui/lab";
+import type { TabPanelProps as MuiTabPanelProps } from "@mui/lab";
+
+export type TabPanelProps = RecursicaOverStyled<MuiTabPanelProps>;
+
+export const TabPanel = forwardRef<HTMLDivElement, TabPanelProps>(
+  function TabPanel(props, ref) {
+    const { overStyled = false, className, ...rest } = props;
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+
+    return (
+      <MuiTabPanel
+        ref={ref}
+        className={`${styles.panel} ${className || ""}`}
+        {...(sanitizedProps as MuiTabPanelProps)}
+      />
+    );
+  },
+);
+
+TabPanel.displayName = "TabPanel";

package/src/components/Tabs/USAGE.md

@@ -0,0 +1,61 @@
+# Tabs - Usage Guide
+
+This document describes how to integrate and use the `Tabs` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Tabs, Tab, TabPanel } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+Unlike the mantine-adapter, `Tabs` has no `.List`/`.Panel` compound API — it mirrors native
+MUI's own `@mui/lab` split, where `Tabs`/`Tab` and `TabPanel` are separate elements coordinated
+by `TabContext`. Because `TabPanel` renders as a sibling of `Tabs` (not nested inside it), wrap
+both in a column-direction container yourself so the panel renders below the tab list instead of
+beside it.
+
+> [!WARNING] > `Tabs` wraps `@mui/material`'s `Tabs`, which does **not** read `TabContext` for its own
+> selected state — only `TabPanel` (from `@mui/lab`) does that. You must pass `value` to `Tabs`
+> explicitly, in addition to wrapping everything in `TabContext`. Omitting it silently leaves
+> every tab unselected (no active styling, no indicator).
+
+```tsx
+import React, { useState } from "react";
+import { TabContext } from "@mui/lab";
+import { Tabs, Tab, TabPanel, Flex } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  const [value, setValue] = useState("home");
+
+  return (
+    <Flex direction="column">
+      <TabContext value={value}>
+        <Tabs value={value} onChange={(_e, v) => setValue(v)}>
+          <Tab value="home" label="Home" />
+          <Tab value="profile" label="Profile" />
+        </Tabs>
+        <TabPanel value="home">Home content</TabPanel>
+        <TabPanel value="profile">Profile content</TabPanel>
+      </TabContext>
+    </Flex>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mui-v7` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.

package/src/components/Tabs/index.ts

@@ -0,0 +1 @@
+export * from "./Tabs";

package/src/components/Text/TEXT_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,10 @@
+# Text – Implementation Notes
+
+## `StaticVariations` story gap didn't match mantine (2026-08-30, source-of-truth audit)
+
+**Found:** `ui-kit-text--static-variations` used `gap: "24px"` in its own inline story wrapper,
+while mantine's equivalent story used `gap: "16px"` — same component, same six variants, but
+visibly more vertical space between each item in mui's render. Not a component bug: `Text.tsx`
+itself has no opinion on inter-item spacing; the gap is entirely owned by each story's own
+`<div style={{ display: "flex", flexDirection: "column", gap }}>` wrapper. Fixed by changing the
+story's `gap` to `"16px"` to match mantine's.

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

@@ -0,0 +1,75 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Text } from "./Text";
+
+const meta: Meta<typeof Text> = {
+  title: "UI-Kit/Text",
+  component: Text,
+  tags: ["autodocs"],
+  parameters: {
+    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 `<Heading>` instead.",
+      },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: "select",
+      options: [
+        "body",
+        "body-small",
+        "caption",
+        "overline",
+        "subtitle",
+        "subtitle-small",
+      ],
+      description:
+        "Controls the standard logical boundary definitions natively extracted from Figma.",
+    },
+    c: {
+      control: "text",
+      description:
+        "Standard Mantine color string mapped via internal boundaries. Example: `dimmed`",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Text>;
+
+export const Default: Story = {
+  args: {
+    variant: "body",
+    children:
+      "This is standard body typography controlled by the central UI-kit boundaries exclusively.",
+  },
+  render: ({ ...args }) => <Text {...args} />,
+};
+
+export const StaticVariations: Story = {
+  args: {},
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "16px" }}>
+      <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>
+    </div>
+  ),
+};

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

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

package/src/components/Text/Text.tsx

@@ -0,0 +1,19 @@
+import { forwardRef } from "react";
+import { type TypographyProps as MuiTypographyProps } from "@mui/material";
+import { Typography } from "../Typography/Typography";
+import { type RecursicaOverStyled } from "../../utils/filterStylingProps";
+import { type RecursicaTextProps } from "@recursica/adapter-common";
+
+export type TextProps = RecursicaOverStyled<
+  Omit<MuiTypographyProps, "variant" | "classes"> & RecursicaTextProps
+>;
+
+export const Text = forwardRef<HTMLElement, TextProps>(function Text(
+  { variant = "body", ...rest },
+  ref,
+) {
+  const typographyClass = `recursica_brand_typography_${variant}`;
+  return <Typography ref={ref} typographyClass={typographyClass} {...rest} />;
+});
+
+Text.displayName = "Text";

package/src/components/Text/USAGE.md

@@ -0,0 +1,40 @@
+# Text - Usage Guide
+
+This document describes how to integrate and use the `Text` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Text } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Text } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return (
+    <Text size="md" color="dimmed">
+      This is some styled body text.
+    </Text>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mui-v7` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.

package/src/components/Text/index.ts

@@ -0,0 +1 @@
+export * from "./Text";

package/src/components/TextArea/TEXTAREA_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,42 @@
+# TextArea – implementation notes
+
+Decisions and design tweaks specific to the UI Kit's TextArea wrapped against `@mui/material`.
+
+---
+
+## 1. Neutralizing `min-height` on TextareaAutosize's hidden measurement clone (source-of-truth audit, 2026-08-30)
+
+**Symptom:** `ui-kit-textarea--autosize` (MUI) rendered much taller than Mantine's equivalent —
+~208px vs. Mantine's ~93px for the same `minRows={2}`/`maxRows={6}` content.
+
+**Root cause:** MUI's `TextField` always renders `multiline` fields through
+`@mui/material/TextareaAutosize`, which mounts **two** `<textarea>` elements: the real, visible
+one, and a second `aria-hidden="true"` clone (`visibility: hidden; position: absolute; height: 0`)
+used purely to measure natural `scrollHeight` for the auto-grow calculation
+(`TextareaAutosize.js` → `calculateTextareaStyles`). Both clones receive the exact same
+`className`, including this component's own CSS-module `.input` class.
+
+`.input`'s `min-height: calc(rows * line-height + 2*padding + 2px)` rule — meant only as a
+cosmetic floor for the _visible_ textarea — was therefore also forcing the hidden clone's
+`scrollHeight` up to that same floor, regardless of its actual (near-zero) content. Since
+TextareaAutosize's algorithm computes `singleRowHeight` from that clone and then multiplies it by
+`minRows`, the corrupted single-row measurement (~93px instead of the true ~17px line height)
+cascaded into a final `minRows * singleRowHeight` output roughly double what it should have been
+— confirmed via `getComputedStyle` on both clones: the hidden one's `scrollHeight` matched the
+CSS floor almost exactly instead of the actual near-empty content height.
+
+**Implementation:** Added `.input[aria-hidden="true"] { min-height: 0; }`. This selector only
+ever matches TextareaAutosize's own hidden measurement clone (the real textarea has no
+`aria-hidden` attribute), so it restores accurate content-based measurement there without
+touching the visible textarea at all — which still gets the `min-height` floor applied directly,
+producing the same ~93px baseline Mantine renders for short/empty content.
+
+## 2. Fixed (non-autosize) height still pinned via `!important` on `.input`
+
+Unchanged from the existing implementation: `.root:not([data-autosize]) .input { height: ... !important }`
+still overrides TextareaAutosize's own inline `height` for every story that doesn't set
+`autosize`, since MUI always routes `multiline` through TextareaAutosize regardless of Recursica's
+`autosize` prop — there is no way to opt a MUI `TextField` out of it once `multiline` is set. This
+rule is unaffected by the `[aria-hidden="true"]` fix above, since it targets the visible node via
+`.root:not([data-autosize]) .input` and the `[aria-hidden="true"]` rule only lowers specificity
+competition for `min-height`, not `height`.