@recursica/mantine-adapter 0.9.3 → 0.10.0

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "@recursica/mantine-adapter",
-  "description": "Recursica Design Token Adapter - Convert design tokens to code",
-  "version": "0.9.3",
+  "description": "Reusable UI components for Recursica applications based on Mantine 8+",
   "private": false,
-  "homepage": "https://github.com/borderux/recursica#readme",
+  "homepage": "https://github.com/borderux/recursica/tree/main/packages/mantine-adapter",
   "author": "hi@borderux.com",
   "bugs": {
     "url": "https://github.com/borderux/recursica/issues"
@@ -12,44 +11,84 @@
     "type": "git",
     "url": "git+https://github.com/borderux/recursica.git"
   },
+  "version": "0.10.0",
   "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "bin": {
-    "recursica": "dist/main.cjs"
-  },
-  "scripts": {
-    "build": "rollup -c",
-    "dev": "rollup -c -w",
-    "clean": "rm -rf dist"
+  "main": "./dist/mantine-adapter.cjs",
+  "module": "./dist/mantine-adapter.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/mantine-adapter.js",
+      "require": "./dist/mantine-adapter.cjs"
+    },
+    "./style.css": "./dist/mantine-adapter.css"
   },
+  "files": [
+    "dist",
+    "src",
+    "CHANGELOG.md",
+    ".storybook/commonArgTypes.ts"
+  ],
   "keywords": [
-    "design-tokens",
-    "figma",
+    "react",
+    "ui",
+    "components",
+    "typescript",
+    "mantine",
     "recursica",
-    "theme",
-    "adapter"
+    "design system",
+    "design systems"
   ],
-  "files": [
-    "dist/**/*",
-    "README.md"
-  ],
-  "dependencies": {
-    "@recursica/common": "*",
-    "typescript": "^5.0.0"
+  "scripts": {
+    "dev": "npm run storybook",
+    "build": "vite build --mode library",
+    "build-storybook": "storybook build -o storybook-static",
+    "lint": "eslint .",
+    "storybook": "storybook dev -p 6006"
   },
   "devDependencies": {
-    "@recursica/schemas": "*",
-    "@rollup/plugin-commonjs": "^28.0.3",
-    "@rollup/plugin-json": "^6.1.0",
-    "@rollup/plugin-node-resolve": "^16.0.1",
-    "@rollup/plugin-terser": "^0.4.4",
-    "@rollup/plugin-typescript": "^12.1.2",
-    "@types/node": "^20.0.0",
-    "rollup": "^4.42.0"
-  },
-  "engines": {
-    "node": ">=16.0.0"
+    "@chromatic-com/storybook": "^5.1.1",
+    "@eslint/js": "^9.25.0",
+    "@recursica/adapter-common": "*",
+    "@recursica/recursica-postcss-vars": "*",
+    "@recursica/storybook-template": "*",
+    "@repo/typescript-config": "*",
+    "@storybook/addon-a11y": "^10.3.3",
+    "@storybook/addon-docs": "^10.3.3",
+    "@storybook/addon-mcp": "^0.4.2",
+    "@storybook/addon-onboarding": "^10.3.3",
+    "@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",
+    "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"
   },
-  "license": "MIT"
+  "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"
+  }
 }

package/src/OverStyling.stories.tsx

@@ -0,0 +1,174 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import {
+  Container,
+  Paper,
+  Title,
+  Text,
+  List,
+  Divider,
+  Group,
+  Code,
+} from "@mantine/core";
+import { Button } from "./components/Button/Button";
+
+const OverStylingInfo = () => {
+  return (
+    <Container size="md" py="xl">
+      <Paper withBorder p="xl" radius="md">
+        <Title order={1} mb="md">
+          Over Styling (<Code>overStyled</Code>)
+        </Title>
+        <Text mb="md">
+          By default, all Recursica components are strictly sandboxed. This
+          means they are protected against arbitrary styling configurations
+          (like passing generic React <Code>style</Code> objects, custom{" "}
+          <Code>classNames</Code> injections, or using deep Mantine layout hooks
+          like <Code>bg</Code> and <Code>c</Code>). This strict compile-time and
+          run-time enforcement guarantees that your design system tokens remain
+          true across your application.
+        </Text>
+        <Text mb="md">
+          However, there may be edge cases where a developer absolutely must
+          modify a component beyond what the design tokens natively allow. For
+          this, we provide the <strong>escape hatch</strong> property:{" "}
+          <Code>overStyled={`{true}`}</Code>.
+        </Text>
+
+        <Title order={3} mb="sm">
+          The Core Philosophy
+        </Title>
+        <Text mb="sm">
+          **You should not over-style components.** Using{" "}
+          <Code>overStyled</Code> explicitly signifies that you are breaking
+          design system rules.
+        </Text>
+        <List mb="xl" type="ordered">
+          <List.Item>
+            <strong>Technical Debt:</strong> If over-styling is required, it
+            should be treated as a short-term workaround. Ideally, the component
+            will be refactored once the required layouts or variants are
+            officially integrated into the core Recursica component library.
+          </List.Item>
+          <List.Item>
+            <strong>Auditing & Searching:</strong> Because this pattern creates
+            technical debt, we enforce the explicit <Code>overStyled</Code>{" "}
+            boolean. This provides a highly auditable, easily searchable string.
+            Product managers and engineers can quickly grep the codebase for{" "}
+            <Code>overStyled</Code> (or the <Code>RecursicaOverStyled</Code>{" "}
+            typings) to hunt down components that don't match standard patterns.
+          </List.Item>
+          <List.Item>
+            <strong>Highly Custom Components:</strong> If your application
+            genuinely requires massive custom layouts that the UI kit cannot
+            support, <strong>do not hack the Recursica component</strong>.
+            Instead, it is highly encouraged that you import the underlying
+            primitive component directly from <Code>@mantine/core</Code> and
+            construct your independent feature there. While you can utilize raw
+            Recursica CSS variables on these custom components, note that they
+            are not guaranteed to be accurately maintained as Recursica evolves.
+            Keep strict components strict!
+          </List.Item>
+        </List>
+
+        <Divider mb="xl" />
+
+        <Title order={3} mb="sm">
+          Permitted Layout Properties
+        </Title>
+        <Text mb="sm">
+          Unlike deep styling bounds (colors, typography, padding, dimensions),
+          external <strong>layout spacing properties</strong> like Margins (
+          <Code>m</Code>, <Code>mt</Code>, <Code>mb</Code>, <Code>mx</Code>) are
+          safely <strong>permitted by default</strong>. This allows integrators
+          to structurally compose components alongside siblings without
+          breaching internal token boundaries.
+        </Text>
+        <Text mb="xl">
+          When using layout properties, you have the flexibility to use either
+          ecosystem seamlessly:
+        </Text>
+        <List mb="md" type="ordered">
+          <List.Item>
+            <strong>Mantine Core Values:</strong> Passing standard Mantine sizes
+            (like <Code>mt="md"</Code>) passes straight through to Mantine
+            natively, allowing you to interface completely normally with a
+            parent application's existing Mantine Theme setup that might fall
+            outside Recursica's scope.
+          </List.Item>
+          <List.Item>
+            <strong>Recursica Strict Tokens:</strong> Passing our custom
+            prefixed tokens (like <Code>mt="rec-md"</Code>) signals our internal
+            layout interceptor to securely translate the value directly to our
+            native <Code>recursica_brand_dimensions</Code> CSS variables. This
+            ensures strict design token measurements while sharing the exact
+            same prop interface!
+          </List.Item>
+        </List>
+        <Text mb="sm" fw={500}>
+          Available Recursica Layout Tokens:
+        </Text>
+        <List mb="xl" type="unordered">
+          <List.Item>
+            <Code>rec-none</Code> (0px limit)
+          </List.Item>
+          <List.Item>
+            <Code>rec-sm</Code> (0.5x scaling)
+          </List.Item>
+          <List.Item>
+            <Code>rec-default</Code> (1.0x scaling)
+          </List.Item>
+          <List.Item>
+            <Code>rec-md</Code> (1.5x scaling)
+          </List.Item>
+          <List.Item>
+            <Code>rec-lg</Code> (2.0x scaling)
+          </List.Item>
+          <List.Item>
+            <Code>rec-xl</Code> (3.0x scaling)
+          </List.Item>
+          <List.Item>
+            <Code>rec-2xl</Code> (4.0x scaling)
+          </List.Item>
+        </List>
+
+        <Divider mb="xl" />
+
+        <Title order={3} mb="md">
+          Live Example
+        </Title>
+        <Text mb="xl">
+          Below is a side-by-side comparison. The first is a standard Recursica
+          Button protected by the design tokens mapping. The second flagrantly
+          forces <Code>overStyled={`{true}`}</Code>, allowing Mantine's native
+          styling generics to punch right through the sandbox layout.
+        </Text>
+
+        <Group gap="xl">
+          <div>
+            <Text size="sm" c="dimmed" mb="xs">
+              Strict Baseline (Default)
+            </Text>
+            <Button variant="solid">Standard UI Kit Button</Button>
+          </div>
+          <div>
+            <Text size="sm" c="dimmed" mb="xs">
+              overStyled={`{true}`}
+            </Text>
+            <Button overStyled={true} bg="pink" c="black" radius="xl">
+              Unsafe Pink Marketing Button
+            </Button>
+          </div>
+        </Group>
+      </Paper>
+    </Container>
+  );
+};
+
+const meta: Meta<typeof OverStylingInfo> = {
+  title: "Introduction/Over Styling",
+  component: OverStylingInfo,
+};
+
+export default meta;
+
+export const Default: StoryObj<typeof OverStylingInfo> = {};

package/src/Version.stories.tsx

@@ -0,0 +1,56 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import ReactMarkdown from "react-markdown";
+import {
+  Container,
+  Paper,
+  Title,
+  TypographyStylesProvider,
+  Group,
+  Anchor,
+  Divider,
+} from "@mantine/core";
+import pkg from "../package.json";
+import changelog from "../CHANGELOG.md?raw";
+
+const VersionInfo = () => {
+  return (
+    <Container size="md" py="xl">
+      <Paper withBorder p="xl" radius="md">
+        <Title order={1} mb="xs">
+          Mantine Adapter v{pkg.version}
+        </Title>
+        <Group mb="xl" gap="md">
+          <Anchor
+            href="https://github.com/borderux/recursica"
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            GitHub Repository
+          </Anchor>
+          <Anchor
+            href="https://recursica.com"
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            Documentation & Website
+          </Anchor>
+        </Group>
+        <Divider mb="xl" />
+        <TypographyStylesProvider>
+          <ReactMarkdown>{changelog}</ReactMarkdown>
+        </TypographyStylesProvider>
+      </Paper>
+    </Container>
+  );
+};
+
+const meta: Meta<typeof VersionInfo> = {
+  title: "Introduction/Version Info",
+  component: VersionInfo,
+};
+
+export default meta;
+
+type Story = StoryObj<typeof VersionInfo>;
+
+export const Default: Story = {};

package/src/components/Accordion/ACCORDION_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,48 @@
+# Accordion – implementation notes
+
+Decisions and design tweaks strictly tailored for the UI Kit's Accordion wrapped against `@mantine/core`. Use this when managing components possessing deeply nested state logic (e.g., active toggles, nested headers mapping external design properties).
+
+---
+
+## 1. Hybrid Composition API (Smart Rendering Flow)
+
+**Decision:** We fundamentally maintain the exact library composition API structure (`<Accordion>`, `<Accordion.Item>`, `<Accordion.Control>`, `<Accordion.Panel>`) while actively supporting an auto-completing flattened prop schema matching the unified Recursica API (`title`, `leftIcon`, `divider`).
+**Implementation:** Avoid rigid raw parameter dumps. Mantine dynamically injects explicit `id` logic, keyboard ARIA mapping, and focus tracking correctly across `Control` to `Panel` DOM connections natively. By exposing the hierarchical mapping 1:1, Recursica safely adopts these capabilities. However, to strictly support Recursica's unified prop mapping interface:
+
+- **Auto-Construction:** If integrators natively pass `title` and/or `leftIcon` props into `<AccordionItem>`, the component structurally auto-generates the internal `AccordionControl` sub-wrappers mapping the text and SVG natively, whilst treating `children` implicitly as the Panel contents.
+- **Graceful Falldown:** If `title` is heavily omitted, the node immediately falls backward into raw Mantine composability expecting integrators mapped `<Accordion.Control>` entirely manually.
+
+---
+
+## 2. Default Configuration Reset (`unstyled`)
+
+**Decision:** We strip Mantine's inner styles away completely from Accordion mappings by leveraging React's default `variant="unstyled"`.
+**Implementation:** In `Accordion.tsx`, `<MantineAccordion>` binds `variant="unstyled"`. This effectively deletes Mantine's precomputed padding, borders, and shadow mappings allowing our targeted `classNames` inside `Accordion.module.css` to become the exact source of foundational truth without "fighting" `!important` tags or unpredictable flex-layouts inherited globally.
+
+---
+
+## 3. Strict SVG Icons Wrapper (`.iconLeftWrapper`)
+
+**Decision:** Identical logic enforced as seen within Buttons: SVG scales dynamically inside `.mantine-leftSection` based on SVGs internal definition boundaries potentially corrupting header gaps.
+**Implementation:** `AccordionControl` captures `<span className={styles.iconLeftWrapper} aria-hidden>` forcing `object-fit: contain` mapped exactly to the `properties_icon-left-size` Recursica dimension token forcing integrator SVG overrides inline perfectly.
+
+---
+
+## 4. Transparent Global Hover Fixes
+
+**Decision:** We nullify internal Mantine button hover actions and exclusively utilize Recursica's hover structure natively.
+**Implementation:** We construct `.control::after` pseudo-objects dynamically pulling our `hover-color` & `hover-opacity` bindings. Mantine's native action sets `.control:hover { background-color: var(...) }` dynamically causing internal layer overlaps. We enforce `background-color: transparent` strictly overriding it, preserving our pseudo-overlay layer-cascade cleanly.
+
+---
+
+## 5. Active Target Hooks (`[data-active]`)
+
+**Decision:** Collapsed and expanded state tracking requires separate background maps across `AccordionItem`.
+**Implementation:** Rather than syncing React `useState` hooks matching `Accordion.value`, we defer to Mantine's inherent DOM mapping: `.item[data-active]` implicitly triggers exactly when Mantine registers an expansion state swap changing values down dynamically on the element layer, perfectly binding to `--recursica_..._background-expanded`.
+
+---
+
+## 6. Nullifying Isolated State Bounds (`open` boolean)
+
+**Decision:** We do not bind isolated `open={true}` state properties natively on individual `<AccordionItem>` configurations.
+**Implementation:** Recursica natively dictates an item-level `open` tracking mapping. However, internally mapping boolean flags structurally across specific tree nodes heavily corrupts Mantine's DOM layout algorithms mapping parent-driven transition listeners. Mantine forces all expanded-height logic to run symmetrically off the `<Accordion value="...">` string matching array to accurately bind ARIA transitions. We explicitly ignore isolated item `<AccordionItem open={...}>` booleans to shield the rendering sequence cleanly.