@recursica/adapter-mui-v7 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,184 @@
+import type { Meta } from "@storybook/react-vite";
+import { AdaptersContent, MuiLogo } from "@recursica/storybook-template";
+import { VersionInfo } from "./Version";
+import { OverStylingInfo } from "./OverStyling";
+
+const DOCS_URL = "https://recursica.com";
+const FORGE_URL = "https://forge.recursica.com";
+
+import { Box } from "@mui/material";
+import { Container, Group, Heading, Text, Link } from "./components";
+
+function IntroductionContent() {
+  return (
+    <Container size="md" style={{ padding: "32px 0", maxWidth: 640 }}>
+      <Group gap="rec-md" mb={2}>
+        <MuiLogo width={40} height={40} />
+        <Box>
+          <Heading order={1} m={0}>
+            Recursica Design System (MUI Adapter)
+          </Heading>
+          <Link href="https://mui.com" target="_blank" rel="noreferrer">
+            mui.com
+          </Link>
+        </Box>
+      </Group>
+      <Text mb={4}>
+        This Storybook showcases the Recursica design system implemented for the{" "}
+        <strong>Material UI (MUI) Kit</strong>. It provides reusable components
+        that map our design tokens to MUI's robust component layer.
+      </Text>
+
+      <Box component="section" sx={{ mb: 4 }}>
+        <Heading order={2} mb={1}>
+          Looking for another UI Kit?
+        </Heading>
+        <Text>
+          Are you using a different UI Kit (like Mantine)? Recursica provides
+          multiple adapters for different frameworks.
+        </Text>
+        <Box sx={{ mt: 2 }}>
+          <a
+            href="./?path=/story/introduction--adapters"
+            target="_parent"
+            className="adapter-btn"
+            style={{
+              display: "inline-flex",
+              alignItems: "center",
+              justifyContent: "center",
+              backgroundColor:
+                "var(--recursica_ui-kit_components_button_variants_styles_solid_properties_colors_background)",
+              color:
+                "var(--recursica_ui-kit_components_button_variants_styles_solid_properties_colors_text)",
+              textDecoration: "none",
+              borderRadius:
+                "var(--recursica_ui-kit_components_button_variants_sizes_default_properties_border-radius)",
+              height:
+                "var(--recursica_ui-kit_components_button_variants_sizes_default_properties_height)",
+              padding:
+                "0 var(--recursica_ui-kit_components_button_variants_sizes_default_properties_horizontal-padding)",
+              fontFamily:
+                "var(--recursica_ui-kit_components_button_variants_sizes_default_properties_text_font-family)",
+              fontSize:
+                "var(--recursica_ui-kit_components_button_variants_sizes_default_properties_text_font-size)",
+              fontWeight:
+                "var(--recursica_ui-kit_components_button_variants_sizes_default_properties_text_font-weight)",
+              boxShadow:
+                "var(--recursica_ui-kit_components_button_variants_styles_solid_properties_elevation)",
+              border:
+                "var(--recursica_ui-kit_components_button_variants_styles_solid_properties_border-size) solid var(--recursica_ui-kit_components_button_variants_styles_solid_properties_colors_border-color)",
+              transition: "opacity 0.2s ease",
+            }}
+            onMouseOver={(e) => {
+              e.currentTarget.style.opacity = "0.85";
+              e.currentTarget.style.color =
+                "var(--recursica_ui-kit_components_button_variants_styles_solid_properties_colors_text-hover)";
+            }}
+            onMouseOut={(e) => {
+              e.currentTarget.style.opacity = "1";
+              e.currentTarget.style.color =
+                "var(--recursica_ui-kit_components_button_variants_styles_solid_properties_colors_text)";
+            }}
+          >
+            View Supported Adapters
+          </a>
+        </Box>
+      </Box>
+
+      <Box component="section" sx={{ mb: 4 }}>
+        <Heading order={2} mb={1}>
+          Installation
+        </Heading>
+        <Text>To install the MUI adapter in your project, run:</Text>
+        <Box
+          component="pre"
+          sx={{
+            p: 1.5,
+            bgcolor: "grey.100",
+            borderRadius: 1,
+            fontSize: 13,
+            mt: 1,
+          }}
+        >
+          <code>
+            npm install @recursica/adapter-mui-v7 @mui/material @emotion/react
+            @emotion/styled
+          </code>
+        </Box>
+      </Box>
+
+      <Box component="section" sx={{ mb: 4 }}>
+        <Heading order={2} mb={1}>
+          Tokens
+        </Heading>
+        <Text>
+          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>
+      </Box>
+
+      <Box component="section" sx={{ mb: 4 }}>
+        <Heading order={2} mb={1}>
+          Theme
+        </Heading>
+        <Text>
+          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>
+      </Box>
+
+      <Box component="section" sx={{ mb: 4 }}>
+        <Heading order={2} mb={1}>
+          Configuring Recursica
+        </Heading>
+        <Text>
+          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>
+      </Box>
+
+      <Box component="section" sx={{ mb: 4 }}>
+        <Heading order={2} mb={1}>
+          Documentation
+        </Heading>
+        <Text>
+          For full documentation, guides, and API reference, visit{" "}
+          <Link href={DOCS_URL} target="_blank" rel="noopener noreferrer">
+            {DOCS_URL}
+          </Link>
+          .
+        </Text>
+      </Box>
+    </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,87 @@
+import ReactMarkdown from "react-markdown";
+import { Box, Paper, Divider } from "@mui/material";
+import {
+  Container,
+  Stack,
+  Text as RawText,
+  Heading,
+  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" }}>
+      <Paper variant="outlined" sx={{ p: 4, borderRadius: 2 }}>
+        <Box className="markdown-body">
+          <ReactMarkdown>{overStylingDoc}</ReactMarkdown>
+        </Box>
+
+        <Divider sx={{ my: 4 }} />
+
+        <Heading order={6} mb={2}>
+          Try It Yourself
+        </Heading>
+
+        <Stack direction="row" alignItems="center" spacing="rec-sm" mb="rec-md">
+          <Switch
+            label="Highlight Over-Styled Components"
+            checked={isHighlightActive}
+            onChange={() => toggleGlobalOverStyled()}
+          />
+        </Stack>
+
+        <Text mb={4}>
+          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 MUI's native
+          styling generics to punch right through the sandbox layout.
+        </Text>
+
+        <Stack direction="row" spacing="rec-default">
+          <Box>
+            <Text
+              variant="caption"
+              overStyled
+              sx={{ color: "text.secondary", mb: 1, display: "block" }}
+            >
+              Strict Baseline (Default)
+            </Text>
+            <Button>Standard UI Kit Button</Button>
+          </Box>
+          <Box>
+            <Text
+              variant="caption"
+              overStyled
+              sx={{ color: "text.secondary", mb: 1, display: "block" }}
+            >
+              overStyled={`{true}`}
+            </Text>
+            <Button
+              overStyled={true}
+              style={{
+                backgroundColor: "pink",
+                color: "black",
+                borderRadius: "24px",
+                padding: "8px 16px",
+              }}
+            >
+              Unsafe Pink Marketing Button
+            </Button>
+          </Box>
+        </Stack>
+      </Paper>
+    </Container>
+  );
+};

package/src/Version.tsx

@@ -0,0 +1,37 @@
+import ReactMarkdown from "react-markdown";
+import { Paper, Divider, Box } from "@mui/material";
+import { Container, Heading, Group, Link } from "./components";
+import pkg from "../package.json";
+import changelog from "../CHANGELOG.md?raw";
+
+export const VersionInfo = () => {
+  return (
+    <Container size="md" style={{ padding: "32px 0" }}>
+      <Paper variant="outlined" sx={{ p: 4, borderRadius: 2 }}>
+        <Heading order={1} mb={1}>
+          MUI Adapter v{pkg.version}
+        </Heading>
+        <Group mb={4} gap="rec-md">
+          <Link
+            href="https://github.com/borderux/recursica"
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            GitHub Repository
+          </Link>
+          <Link
+            href="https://recursica.com"
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            Documentation & Website
+          </Link>
+        </Group>
+        <Divider sx={{ mb: 4 }} />
+        <Box className="markdown-body">
+          <ReactMarkdown>{changelog}</ReactMarkdown>
+        </Box>
+      </Paper>
+    </Container>
+  );
+};

package/src/components/Accordion/ACCORDION_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,107 @@
+# Accordion – implementation notes
+
+Decisions and design tweaks specific to the UI Kit's Accordion wrapped against `@mui/material`.
+
+---
+
+## 1. Context-based container (no native MUI equivalent)
+
+**Decision:** MUI has no group-level `Accordion` — its own `Accordion` component _is_ the
+item, controlled individually via `expanded`/`onChange`. Recursica's container/group model
+(single `value`, `multiple`, cascading `chevron`) is reimplemented with a React context
+(`AccordionContext`) that each `AccordionItem`/`AccordionControl` reads from.
+**Implementation:** `AccordionBase` owns the controlled/uncontrolled `value` state and hands
+`{ value, onChange, chevron }` down via context; `AccordionItem` derives its own `expanded`
+from that context instead of taking it as a prop.
+
+---
+
+## 2. Prop-contract Omits protect the context wiring
+
+**Decision:** Because `AccordionItem`/`AccordionControl` are thin wrappers around real MUI
+components (`MuiAccordion`/`MuiAccordionSummary`), their native `expanded`/`onChange`/
+`expandIcon` props would otherwise collide with the values these wrappers compute from
+context.
+**Implementation:** `AccordionItemWrapperProps` omits `expanded`/`onChange`/`defaultExpanded`
+from `MuiAccordionProps`; `AccordionControlWrapperProps` omits `expandIcon` from
+`MuiAccordionSummaryProps`. Neither is exposed on `RecursicaAccordionItemProps`/
+`RecursicaAccordionControlProps`, so passing them is a compile error, not a silent override.
+
+---
+
+## 3. `disabled` is a formally supported, shared prop
+
+**Decision:** `RecursicaAccordionItemProps.disabled` is shared as-is with MUI's native
+`Accordion.disabled` — same name, same shape, no reshaping needed. MUI already blocks
+click/keyboard interaction on the control internally once `disabled` is set (its `AccordionSummary`
+renders as a real disabled `<button>`); the visual dim is Recursica's own, not MUI's default.
+**Implementation:** `AccordionItem` destructures `disabled` explicitly (rather than letting it
+ride through in `...rest`) so it can also drive `data-disabled` on the item root for the dim.
+MUI's own default disabled treatment — a separate hardcoded background/opacity on both the
+item root and the control (`.Mui-disabled`) — is neutralized in `Accordion.module.css` so the
+token-driven `.item[data-disabled]` dim is the single source of truth.
+
+---
+
+## 4. Chevron via `expandIcon` wrapper
+
+**Decision:** MUI's expand indicator is set through `AccordionSummary.expandIcon`, not a
+child. Recursica's container-level `chevron` (or the default arrow) is threaded through
+context and rendered into that slot.
+**Implementation:** `AccordionControl` resolves `ctx?.chevron ?? <ChevronIcon />` and passes
+it as `expandIcon={<span className={styles.chevron}>{resolvedChevron}</span>}`.
+
+---
+
+## 5. Transparent background for `Layer` overrides
+
+**Decision:** Same reasoning as the Mantine adapter's hover-fix note — MUI's `Paper`-derived
+`Accordion` root ships its own background; Recursica needs it transparent so ambient `Layer`
+tokens can apply.
+**Implementation:** `AccordionItem` merges `backgroundColor: "transparent"` into `style`
+ahead of any caller-supplied `style`, and forces `disableGutters`/`elevation={0}`/`square` to
+strip MUI's own spacing/elevation/border-radius defaults.
+
+---
+
+## 6. Chevron double-rotation (source-of-truth audit, 2026-08-30)
+
+**Decision:** Don't rotate `.chevron` ourselves on expand — let MUI's own wrapper handle it.
+
+**Implementation:** `expandIcon`'s `<span className={styles.chevron}>` gets placed _inside_
+MUI's own `.MuiAccordionSummary-expandIconWrapper`, which already rotates 180deg on
+`.Mui-expanded` (MUI's own stable, documented behavior). `Accordion.module.css` also had
+`.item:global(.Mui-expanded) .chevron { transform: rotate(180deg); }`, rotating the same span
+a _second_ time — the two 180deg rotations canceled out, so the chevron visually never
+appeared to move even though the accordion state was correct. Found via the
+`adapter-tester:source-of-truth` divergence check comparing against mantine's golden. Removed
+the redundant `transform` from that rule; kept the icon-color swap it also carries.
+
+---
+
+## 7. Long title wrapped instead of truncating (source-of-truth audit, 2026-08-30)
+
+**Symptom:** `ui-kit-accordion--long-title-truncation`'s header label wrapped onto multiple
+lines (pushing the chevron down) instead of truncating to a single line with an ellipsis, like
+mantine's does.
+
+**Root cause:** Two missing pieces, both present in mantine's identically-purposed `.label`
+rule but absent from mui's:
+
+1. `.label` itself had no `white-space: nowrap`/`text-overflow: ellipsis`/`overflow` at all —
+   it was never told to truncate in the first place.
+2. Even after adding those, truncation still didn't take effect: `.control
+:global(.MuiAccordionSummary-content)` — the MUI-native flex wrapper sitting between
+   `.control`'s flex row and `.label` — had `flex: 1` but no `min-width: 0`. A flex item's
+   automatic minimum width defaults to its content's min-content size; once `.label`'s text is
+   `white-space: nowrap`, that min-content size becomes the entire unwrapped title width, which
+   propagated up through this intermediate flex item and prevented it (and `.label` inside it)
+   from ever shrinking below the full title width, so `text-overflow: ellipsis` had no room to
+   apply.
+
+**Fix:** Added `min-width: 0`, `overflow: clip` (+ `overflow-clip-margin: 0.35em`, not plain
+`hidden`, to avoid clipping descenders — see Chip/FileInput's implementation notes for the
+original discovery), `white-space: nowrap`, and `text-overflow: ellipsis` to `.label` (matching
+mantine's rule exactly), plus `min-width: 0` on the intermediate `.MuiAccordionSummary-content`
+wrapper so the shrink constraint actually reaches `.label`. Verified live against mantine's
+`LongTitleTruncation` story — both truncate to a single line with a trailing ellipsis.