@recursica/adapter-mantine-v8 1.0.0

package/src/GlobalExemptions.modules.css

@@ -0,0 +1,7 @@
+/**
+ * GLOBAL EXEMPTIONS
+ *
+ * This file hosts global, brand, and layout variables that are defined in
+ * recursica_variables_scoped.css but are not used by any specific component.
+ * Isolating them here keeps individual component stylesheets clean and focused.
+ */

package/src/Introduction.stories.tsx

@@ -0,0 +1,154 @@
+import type { Meta } from "@storybook/react-vite";
+import { AdaptersContent, MantineLogo } from "@recursica/storybook-template";
+import { VersionInfo } from "./Version";
+import { OverStylingInfo } from "./OverStyling";
+import {
+  Container,
+  Stack,
+  Group,
+  Heading,
+  Text,
+  Link,
+  Button,
+} from "./components";
+
+const DOCS_URL = "https://recursica.com";
+const FORGE_URL = "https://forge.recursica.com";
+
+function IntroductionContent() {
+  return (
+    <Container size="md" style={{ padding: "32px 0", maxWidth: 640 }}>
+      <Group gap="rec-md" mb="rec-xl" align="flex-start" wrap="nowrap">
+        <MantineLogo width={80} height={80} />
+        <Stack gap={0}>
+          <Heading order={1} m={0}>
+            Recursica Design System (Mantine Adapter)
+          </Heading>
+          <Link href="https://mantine.dev" target="_blank" rel="noreferrer">
+            mantine.dev
+          </Link>
+        </Stack>
+      </Group>
+      <Text mb="rec-xl">
+        This Storybook showcases the Recursica design system implemented for the{" "}
+        <strong>Mantine UI Kit</strong>. It provides reusable components that
+        map our design tokens to Mantine's robust component layer.
+      </Text>
+
+      <Stack mb="rec-xl">
+        <Heading order={2} mb="rec-md">
+          Looking for another UI Kit?
+        </Heading>
+        <Text mb="rec-md">
+          Are you using a different UI Kit (like Material UI)? Recursica
+          provides multiple adapters for different frameworks.
+        </Text>
+        <Group mt="rec-md">
+          <Button
+            component="a"
+            href="./?path=/story/introduction--adapters"
+            target="_parent"
+            variant="solid"
+          >
+            View Supported Adapters
+          </Button>
+        </Group>
+      </Stack>
+
+      <Stack mb="rec-xl">
+        <Heading order={2} mb="rec-md">
+          Installation
+        </Heading>
+        <Text mb="rec-md">
+          To install the Mantine adapter in your project, run:
+        </Text>
+        <Stack
+          style={{
+            padding: 12,
+            backgroundColor: "#f5f5f5",
+            borderRadius: 6,
+            fontSize: 13,
+            marginTop: 8,
+          }}
+        >
+          <code>
+            npm install @recursica/adapter-mantine-v8 @mantine/core @mantine/hooks
+          </code>
+        </Stack>
+      </Stack>
+
+      <Stack mb="rec-xl">
+        <Heading order={2} mb="rec-md">
+          Tokens
+        </Heading>
+        <Text mb="rec-md">
+          Raw design tokens (colors, sizes, font weights, opacities, etc.) that
+          feed the theme and components. These are the primitive values defined
+          in your token set and exposed as CSS custom properties.
+        </Text>
+      </Stack>
+
+      <Stack mb="rec-xl">
+        <Heading order={2} mb="rec-md">
+          Theme
+        </Heading>
+        <Text mb="rec-md">
+          Brand and theme layer built on top of tokens. Typography types,
+          dimensions, and layout grids are defined here. Theme uses the tokens
+          and exposes both CSS variables and helper classes (e.g. typography
+          classes) for consistent styling across the product.
+        </Text>
+      </Stack>
+
+      <Stack mb="rec-xl">
+        <Heading order={2} mb="rec-md">
+          Configuring Recursica
+        </Heading>
+        <Text mb="rec-md">
+          To modify the Recursica configuration (tokens, brand, theme), go to{" "}
+          <Link href={FORGE_URL} target="_blank" rel="noopener noreferrer">
+            {FORGE_URL}
+          </Link>
+          . Changes there drive the tokens and theme you see in this Storybook.
+        </Text>
+      </Stack>
+
+      <Stack mb="rec-xl">
+        <Heading order={2} mb="rec-md">
+          Documentation
+        </Heading>
+        <Text mb="rec-md">
+          For full documentation, guides, and API reference, visit{" "}
+          <Link href={DOCS_URL} target="_blank" rel="noopener noreferrer">
+            {DOCS_URL}
+          </Link>
+          .
+        </Text>
+      </Stack>
+    </Container>
+  );
+}
+
+const meta = {
+  title: "Introduction",
+} satisfies Meta;
+
+export default meta;
+
+export const Welcome = {
+  render: () => <IntroductionContent />,
+};
+
+export const Adapters = {
+  render: () => <AdaptersContent />,
+};
+
+export const OverStyling = {
+  name: "Over Styling",
+  render: () => <OverStylingInfo />,
+};
+
+export const VersionInfoStory = {
+  name: "Version Info",
+  render: () => <VersionInfo />,
+};

package/src/OverStyling.tsx

@@ -0,0 +1,79 @@
+import ReactMarkdown from "react-markdown";
+import { TypographyStylesProvider } from "@mantine/core";
+import {
+  Container,
+  Card,
+  Heading,
+  Text as RawText,
+  Group,
+  Stack,
+  Switch as RawSwitch,
+} from "./components";
+import { Button as RawButton } from "./components/Button/Button";
+import {
+  useGlobalOverStyled,
+  toggleGlobalOverStyled,
+  wrapComponent,
+} from "@recursica/adapter-common";
+import overStylingDoc from "../OVERSTYLING.md?raw";
+
+const Button = wrapComponent(RawButton);
+const Text = wrapComponent(RawText);
+const Switch = wrapComponent(RawSwitch);
+
+export const OverStylingInfo = () => {
+  const isHighlightActive = useGlobalOverStyled();
+  return (
+    <Container size="md" style={{ padding: "32px 0" }}>
+      <Card>
+        <Card.Content>
+          <TypographyStylesProvider>
+            <ReactMarkdown>{overStylingDoc}</ReactMarkdown>
+          </TypographyStylesProvider>
+
+          <Stack
+            style={{ height: 1, backgroundColor: "#eaeaea" }}
+            my="rec-xl"
+          />
+
+          <Heading order={3} mb="rec-md">
+            Try It Yourself
+          </Heading>
+
+          <Group mb="rec-xl">
+            <Switch
+              label="Highlight Over-Styled Components"
+              checked={isHighlightActive}
+              onChange={() => toggleGlobalOverStyled()}
+            />
+          </Group>
+
+          <Text mb="rec-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="rec-xl">
+            <Stack gap="rec-sm">
+              <Text overStyled size="sm" c="dimmed">
+                Strict Baseline (Default)
+              </Text>
+              <Button variant="solid">Standard UI Kit Button</Button>
+            </Stack>
+            <Stack gap="rec-sm">
+              <Text overStyled size="sm" c="dimmed">
+                overStyled
+              </Text>
+              <Button overStyled={true} bg="pink" c="black" radius="xl">
+                Unsafe Pink Marketing Button
+              </Button>
+            </Stack>
+          </Group>
+        </Card.Content>
+      </Card>
+    </Container>
+  );
+};

package/src/Version.tsx

@@ -0,0 +1,44 @@
+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";
+
+export 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>
+  );
+};

package/src/components/Accordion/ACCORDION_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,72 @@
+# 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 Mantine's own `variant="unstyled"`. That Mantine sentinel is an internal implementation detail, not something a Recursica consumer should ever set directly — `RecursicaAccordionProps.variant` is `"default" | (string & {})`: `"default"` is the only value with dedicated Recursica styling, mapped internally via `mapVariant` in `Accordion.tsx`; any other string is a caller-supplied custom variant and passes straight through to Mantine unmapped.
+**Implementation:** `AccordionBase` defaults `variant` to Recursica's `"default"`, looks it up in `mapVariant` (`{ default: "unstyled" }`), and passes the resolved value (or the original string, if it wasn't a recognized key) to `<MantineAccordion variant={...}>`. The `"default"` → `"unstyled"` mapping 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.
+
+---
+
+## 7. Native `icon` slot is omitted on `AccordionControl`
+
+**Decision:** Mantine's `AccordionControl` has its own native `icon` prop — a distinct,
+documented slot ("icon displayed next to the label") — which the adapter reuses internally
+to render Recursica's `leftIcon`. Left unguarded, a caller could pass native `icon` directly
+and silently override the `leftIcon`-derived element (spread order would let it win).
+**Implementation:** `AccordionControlWrapperProps` omits `icon` from Mantine's native
+`AccordionControlProps` before merging in `RecursicaAccordionControlProps`, so the only way
+to set that slot is through `leftIcon`. Mantine's separate, per-control `chevron` override
+is _not_ omitted — nothing here computes it, so it still passes through safely if a caller
+wants to override the cascaded container-level chevron for a single item.
+
+---
+
+## `.label` descender clipping (Matt Massey, 2026-08-28)
+
+`.label` used plain `overflow: hidden` to make `text-overflow: ellipsis` work, which also clips
+descenders (e.g. the "g" in a long title) whenever `text_line-height` is tighter than the font's
+natural ascent+descent. Switched to `overflow: clip; overflow-clip-margin: 0.35em;` — same
+truncation, but ink can bleed slightly past the line box before it's actually clipped. Project-wide
+fix; see Chip's `CHIP_IMPLEMENTATION_NOTES.md` for the original discovery.