@recursica/adapter-mantine-v8 1.0.0

package/dist/test.html

@@ -0,0 +1 @@
+<h1>Hello Public</h1>

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 Mantine Adapter: Core Philosophy
+
+Recursica's component architecture isn't just a wrapper; it's a strict enforcing layer over Mantine'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-mantine-v8` 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 Mantine or another underlying UI library.
+
+- We decouple our visual properties natively. Instead of mapping perfectly to Mantine's variants `(solid, outline)`, 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` out of Mantine Badge when Recursica enforces a universal single size).
+
+## 2. Component Wrappers (Leaving Mantine Alone)
+
+We actively avoid mutating or patching Mantine source code or deeply hooking into the Mantine Theme object to apply our token system.
+
+- We rely on standard DOM `module.css` bridging with strictly targeted `className`/`classNames` overrides.
+- This creates total decoupled isolation: updating Mantine natively will not fracture our styles, and we avoid dealing with deep Emotion/styled-component theme clashing logic.
+
+## 3. The `overStyled` Property
+
+Mantine encourages deep styling access by injecting properties like `p` (padding), `bg` (background), `c` (color), or `styles`/`classNames` directly into component tags.
+
+- By default, **Recursica components block all arbitrary styling vectors**. `className` maps, system styles, and inline logic are proactively stripped before they hit Mantine 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`, `mb`, etc.) to pass through so developers can still 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 Mantine 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 `@mantine/core` 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,74 @@
+# @recursica/adapter-mantine-v8
+
+> Reusable UI components for Recursica applications based on Mantine 8+.
+
+This adapter converts Recursica design tokens into Mantine-specific themes and components.
+
+## Usage Guidelines
+
+- Relies on `@mantine/core`, `@mantine/dates`, and `@mantine/hooks` 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)
+- [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)

package/package.json

@@ -0,0 +1,131 @@
+{
+  "name": "@recursica/adapter-mantine-v8",
+  "description": "Reusable UI components for Recursica applications based on Mantine 8+",
+  "private": false,
+  "homepage": "https://github.com/borderux/recursica-adapter-mantine-v8",
+  "author": "hi@borderux.com",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/borderux/recursica-adapter-mantine-v8/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/borderux/recursica-adapter-mantine-v8.git"
+  },
+  "version": "1.0.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/adapter-mantine-v8.cjs",
+  "module": "./dist/adapter-mantine-v8.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/adapter-mantine-v8.js",
+      "require": "./dist/adapter-mantine-v8.cjs"
+    },
+    "./style.css": "./dist/adapter-mantine-v8.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",
+    "mantine",
+    "recursica",
+    "design system",
+    "design systems"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "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",
+    "test": "vitest run --project unit",
+    "test:dom": "vitest run --project dom",
+    "adapter-tester": "adapter-tester --serve",
+    "adapter-tester:automated": "adapter-tester",
+    "adapter-tester:update-golden": "adapter-tester --update-golden",
+    "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,md,css,scss}\"",
+    "prepare": "node .husky/install.mjs",
+    "precommit": "npm run check-types && npm run lint && npm run format",
+    "version": "changeset version",
+    "release": "changeset publish"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.7",
+    "@eslint/js": "^9.25.0",
+    "@playwright/test": "^1.62.1",
+    "@recursica/adapter-tester": "^5.0.2",
+    "@recursica/recursica-postcss-vars": "^1.5.0",
+    "@recursica/storybook-template": "^0.7.11",
+    "@recursica/token-analyzer": "^1.5.0",
+    "@storybook/addon-a11y": "^10.3.3",
+    "@types/node": "^24.0.0",
+    "@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",
+    "husky": "^9.1.7",
+    "lint-staged": "^15.5.2",
+    "playwright": "^1.53.0",
+    "prettier": "3.5.3",
+    "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",
+    "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"
+  },
+  "peerDependencies": {
+    "@mantine/core": "^8.0.0",
+    "@mantine/dates": "^8.0.0",
+    "@mantine/hooks": "^8.0.0",
+    "react": ">=16.8.0",
+    "react-dom": ">=16.8.0"
+  }
+}