@recursica/adapter-mui-v7 1.0.0

package/dist/vite.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"></stop><stop offset="8.333%" stop-color="#FFDD35"></stop><stop offset="100%" stop-color="#FFA800"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>

package/docs/PHILOSOPHY.md

@@ -0,0 +1,39 @@
+# Recursica MUI Adapter: Core Philosophy
+
+Recursica's component architecture isn't just a wrapper; it's a strict enforcing layer over MUI's massive API surface. Our primary goal is to ensure consistency, eliminate "design system rot," and provide clear boundaries for application developers using the UI Kit.
+
+This document serves as the governing framework for why the `adapter-mui-v7` components are built the way they are.
+
+## 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.
+
+- We decouple our visual properties natively. Instead of mapping perfectly to MUI's native variants `(contained, outlined, text)`, we intentionally use Recursica's semantic and behavioral structures (e.g., `<Badge variant="alert" />`).
+- We intentionally omit and strip complex underlying parameters if they collide with or circumvent our UI tokens (like stripping `--size` or raw MUI size properties when Recursica enforces a universal scale).
+
+## 2. Component Wrappers (Leaving MUI Alone)
+
+We actively avoid mutating or patching MUI source code or deeply hooking into the MUI `createTheme` Theme object to apply our token system.
+
+- We rely on standard DOM `module.css` bridging with strictly targeted `className`/`classes` overrides whenever possible, instead of heavy Emotion/CSS-in-JS logic.
+- This creates total decoupled isolation: updating MUI natively will not fracture our styles, and we avoid dealing with deep CSS-in-JS theme clashing logic.
+
+## 3. The `overStyled` Property
+
+MUI encourages deep styling access by injecting the `sx` prop, system props like `bgcolor`, `color`, `typography`, or nested `classes` directly into component tags.
+
+- By default, **Recursica components block all arbitrary styling vectors**. `sx` maps, `classes` overrides, system styles, and inline logic are proactively stripped before they hit MUI using central utility functions.
+- **Why?** To prevent the design system from deteriorating over time as developers write one-off hotfixes into their TSX rendering blocks.
+- **The Caveat:** We allow _external DOM layout positioning props_ (e.g., margin `m`, `mt`, `p`, `px`, etc.) to pass through and natively intercept Recursica Spacing Tokens (`rec-sm`, `rec-default`) so developers can structure components organically within their parent layouts.
+
+### Escape Hatches
+
+If a developer _strictly must_ heavily alter a component, they are required to explicitly declare `<Component overStyled={true} />`. This immediately raises a visible red flag during code reviews.
+
+## 4. Expectations for External Developers (Modifying Recursica)
+
+If a developer finds that a component does not fit their needs and styling must be modified, their path of execution should follow these principles sequentially:
+
+1. **Leverage Native MUI First:** If a Recursica component lacks the functionality or styling variant needed for a highly custom edge case (e.g., a massive marketing hero button), do not try to forcibly hack the Recursica component. Instead, import the raw underlying `Button` component directly from `@mui/material` and style it manually. Use Recursica for standard systematic needs, and native libraries for isolated custom one-offs.
+2. **Accept `overStyled` as Technical Debt:** If you must override the Recursica component immediately but intend to roll it back, use `overStyled={true}`. The expectation is that `overStyled` uses will eventually be replaced once the actual Recursica Figma variants are natively updated to accommodate your usecase, at which point `overStyled={true}` can be safely removed.
+3. **Contribute to the Kit:** Avoid building private custom wrappers around Recursica components. If the system is missing a variant, that is a shared project deficit—raise a concern and have the variant integrated directly into the universal token libraries!

package/llms.txt

@@ -0,0 +1,76 @@
+# @recursica/adapter-mui-v7
+
+> Reusable UI components for Recursica applications based on Material UI (MUI) v7.
+
+This adapter converts Recursica design tokens into MUI-specific themes and components.
+
+## Usage Guidelines
+
+- Relies on `@mui/material`, `@emotion/react`, and `@emotion/styled` peer dependencies.
+- When building UI in consumer applications, prioritize using components exported by this package to adhere to the Recursica design system.
+
+## Reference Documentation
+
+- [USAGE](USAGE.md): Detailed usage instructions, import rules, and layout/token conventions.
+- [OVERSTYLING](OVERSTYLING.md): The `overStyled` escape hatch — when it's appropriate, what's permitted by default, and how to visually audit its usage.
+- [SETUP](SETUP.md): Installation and integration steps.
+- [ARCHITECTURE](ARCHITECTURE.md): Package architecture and dependencies.
+- [README](README.md)
+
+## Components
+
+Each component has its own `USAGE.md` documenting its props, adapter-specific behaviors, layout constraints, and accessibility requirements.
+
+- [Accordion](src/components/Accordion/USAGE.md)
+- [AssistiveElement](src/components/AssistiveElement/USAGE.md)
+- [Autocomplete](src/components/Autocomplete/USAGE.md)
+- [Avatar](src/components/Avatar/USAGE.md)
+- [Badge](src/components/Badge/USAGE.md)
+- [Box](src/components/Box/USAGE.md)
+- [Breadcrumb](src/components/Breadcrumb/USAGE.md)
+- [Button](src/components/Button/USAGE.md)
+- [Card](src/components/Card/USAGE.md)
+- [Checkbox](src/components/Checkbox/USAGE.md)
+- [Chip](src/components/Chip/USAGE.md)
+- [Container](src/components/Container/USAGE.md)
+- [DatePicker](src/components/DatePicker/USAGE.md)
+- [Dropdown](src/components/Dropdown/USAGE.md)
+- [FileInput](src/components/FileInput/USAGE.md)
+- [FileUpload](src/components/FileUpload/USAGE.md)
+- [Flex](src/components/Flex/USAGE.md)
+- [FormControlLayout](src/components/FormControlLayout/USAGE.md)
+- [FormControlWrapper](src/components/FormControlWrapper/USAGE.md)
+- [Grid](src/components/Grid/USAGE.md)
+- [Group](src/components/Group/USAGE.md)
+- [HoverCard](src/components/HoverCard/USAGE.md)
+- [Label](src/components/Label/USAGE.md)
+- [Layer](src/components/Layer/USAGE.md)
+- [Link](src/components/Link/USAGE.md)
+- [Loader](src/components/Loader/USAGE.md)
+- [Menu](src/components/Menu/USAGE.md)
+- [Modal](src/components/Modal/USAGE.md)
+- [NumberInput](src/components/NumberInput/USAGE.md)
+- [Pagination](src/components/Pagination/USAGE.md)
+- [Panel](src/components/Panel/USAGE.md)
+- [Popover](src/components/Popover/USAGE.md)
+- [Radio](src/components/Radio/USAGE.md)
+- [ReadOnlyField](src/components/ReadOnlyField/USAGE.md)
+- [RecursicaThemeProvider](src/components/RecursicaThemeProvider/USAGE.md)
+- [SegmentedControl](src/components/SegmentedControl/USAGE.md)
+- [Slider](src/components/Slider/USAGE.md)
+- [Stack](src/components/Stack/USAGE.md)
+- [Stepper](src/components/Stepper/USAGE.md)
+- [Switch](src/components/Switch/USAGE.md)
+- [Table](src/components/Table/USAGE.md)
+- [Tabs](src/components/Tabs/USAGE.md)
+- [Text](src/components/Text/USAGE.md)
+- [TextArea](src/components/TextArea/USAGE.md)
+- [TextField](src/components/TextField/USAGE.md)
+- [TimePicker](src/components/TimePicker/USAGE.md)
+- [Timeline](src/components/Timeline/USAGE.md)
+- [Title](src/components/Title/USAGE.md)
+- [Toast](src/components/Toast/USAGE.md)
+- [Tooltip](src/components/Tooltip/USAGE.md)
+- [TransferList](src/components/TransferList/USAGE.md)
+- [Tree](src/components/Tree/USAGE.md)
+- [Typography](src/components/Typography/USAGE.md)

package/package.json

@@ -0,0 +1,151 @@
+{
+  "name": "@recursica/adapter-mui-v7",
+  "description": "Reusable UI components for Recursica applications based on Material UI (MUI) v7",
+  "private": false,
+  "homepage": "https://github.com/borderux/recursica-adapter-mui-v7",
+  "author": "hi@borderux.com",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/borderux/recursica-adapter-mui-v7/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/borderux/recursica-adapter-mui-v7.git"
+  },
+  "version": "1.0.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/adapter-mui-v7.cjs",
+  "module": "./dist/adapter-mui-v7.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/adapter-mui-v7.js",
+      "require": "./dist/adapter-mui-v7.cjs"
+    },
+    "./style.css": "./dist/adapter-mui-v7.css"
+  },
+  "files": [
+    "dist",
+    "src",
+    "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"
+  ],
+  "keywords": [
+    "react",
+    "ui",
+    "components",
+    "typescript",
+    "mui",
+    "material-ui",
+    "recursica",
+    "design system",
+    "design systems"
+  ],
+  "scripts": {
+    "dev": "npm run storybook",
+    "build": "vite build --mode library",
+    "build-storybook": "storybook build -o storybook-static",
+    "lint": "eslint .",
+    "check-types": "tsc --noEmit",
+    "storybook": "storybook dev",
+    "analyze-tokens": "analyze-tokens --css ./recursica_variables_scoped.css --dir src/components --output token-analysis.json",
+    "prebuild": "npm run analyze-tokens",
+    "adapter-tester": "adapter-tester --serve",
+    "adapter-tester:automated": "adapter-tester",
+    "adapter-tester:update-golden": "adapter-tester --update-golden",
+    "adapter-tester:source-of-truth": "adapter-tester --divergence-only",
+    "test": "vitest run --project unit",
+    "test:dom": "vitest run --project dom",
+    "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,md,css,scss}\"",
+    "validate-adapter-status": "node scripts/validate-adapter-status.mjs",
+    "prepare": "node .husky/install.mjs",
+    "precommit": "npm run check-types && npm run lint && npm run format && npm run validate-adapter-status",
+    "version": "changeset version",
+    "release": "changeset publish"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.7",
+    "@eslint/js": "^9.25.0",
+    "@mui/lab": "^7.0.1-beta.25",
+    "@mui/x-date-pickers": "^9.11.0",
+    "@mui/x-tree-view": "^9.11.0",
+    "@playwright/test": "^1.62.1",
+    "@recursica/adapter-tester": "^5.1.1",
+    "@recursica/recursica-postcss-vars": "^1.5.0",
+    "@recursica/storybook-template": "^0.7.11",
+    "@recursica/token-analyzer": "^1.7.3",
+    "@types/node": "^24.0.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^15.5.2",
+    "prettier": "3.5.3",
+    "@storybook/addon-a11y": "^10.3.3",
+    "@storybook/addon-docs": "^10.3.3",
+    "@storybook/addon-mcp": "^0.4.2",
+    "@storybook/addon-vitest": "^10.3.3",
+    "@storybook/react-vite": "^10.3.3",
+    "@types/react": "^19.1.2",
+    "@types/react-dom": "^19.1.2",
+    "@vitejs/plugin-react": "^4.4.1",
+    "@vitest/browser": "^3.2.4",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^9.25.0",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-refresh": "^0.4.19",
+    "eslint-plugin-storybook": "^10.3.3",
+    "globals": "^16.0.0",
+    "playwright": "^1.53.0",
+    "react-markdown": "^10.1.0",
+    "sass": "^1.89.2",
+    "sirv": "^3.0.2",
+    "storybook": "^10.3.3",
+    "storybook-dark-mode": "^5.0.0",
+    "strip-literal": "^3.0.0",
+    "ts-morph": "^28.0.0",
+    "typescript": "~5.8.3",
+    "typescript-eslint": "^8.30.1",
+    "vite": "^6.3.5",
+    "vite-plugin-dts": "^4.5.4",
+    "vite-plugin-svgr": "^4.3.0",
+    "vitest": "^3.2.4"
+  },
+  "dependencies": {
+    "@recursica/adapter-common": "^0.29.0",
+    "@recursica/official-release": "^2.8.0",
+    "dayjs": "^1.11.21"
+  },
+  "peerDependencies": {
+    "@emotion/react": "^11.14.0",
+    "@emotion/styled": "^11.14.0",
+    "@mui/lab": "^7.0.1-beta.25",
+    "@mui/material": "^7.3.0",
+    "@mui/x-date-pickers": "^9.11.0",
+    "@mui/x-tree-view": "^9.11.0",
+    "react": ">=16.8.0",
+    "react-dom": ">=16.8.0"
+  },
+  "peerDependenciesMeta": {
+    "@mui/lab": {
+      "optional": true
+    },
+    "@mui/x-date-pickers": {
+      "optional": true
+    },
+    "@mui/x-tree-view": {
+      "optional": true
+    }
+  }
+}