@recursica/mui-adapter 0.1.0

package/src/OverStyling.stories.tsx

@@ -0,0 +1,235 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import {
+  Container,
+  Paper,
+  Typography as Text,
+  Divider,
+  Stack,
+  Box,
+} from "@mui/material";
+import { Button } from "./components/Button/Button";
+
+const OverStylingInfo = () => {
+  return (
+    <Container maxWidth="md" sx={{ py: 4 }}>
+      <Paper variant="outlined" sx={{ p: 4, borderRadius: 2 }}>
+        <Text variant="h4" mb={2}>
+          Over Styling (<code>overStyled</code>)
+        </Text>
+        <Text mb={2}>
+          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>className</code> injections, or using deep MUI layout props like{" "}
+          <code>sx</code>). This strict compile-time and run-time enforcement
+          guarantees that your design system tokens remain true across your
+          application.
+        </Text>
+        <Text mb={2}>
+          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>
+
+        <Text variant="h6" mb={1} mt={4}>
+          The Core Philosophy
+        </Text>
+        <Text mb={1}>
+          **You should not over-style components.** Using{" "}
+          <code>overStyled</code> explicitly signifies that you are breaking
+          design system rules.
+        </Text>
+        <Box component="ol" sx={{ pl: 4, mb: 4 }}>
+          <li>
+            <Text>
+              <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.
+            </Text>
+          </li>
+          <li>
+            <Text>
+              <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.
+            </Text>
+          </li>
+          <li>
+            <Text>
+              <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>@mui/material</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!
+            </Text>
+          </li>
+        </Box>
+
+        <Divider sx={{ mb: 4 }} />
+
+        <Text variant="h6" mb={1}>
+          Permitted Layout Properties
+        </Text>
+        <Text mb={1}>
+          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={3}>
+          When using layout properties, you have the flexibility to use either
+          ecosystem seamlessly:
+        </Text>
+        <Box component="ol" sx={{ pl: 4, mb: 2 }}>
+          <li>
+            <Text>
+              <strong>MUI Core Values:</strong> Passing standard MUI sizes (like{" "}
+              <code>mt={"{2}"}</code>) passes straight through to MUI natively,
+              allowing you to interface completely normally with a parent
+              application's existing MUI Theme setup that might fall outside
+              Recursica's scope.
+            </Text>
+          </li>
+          <li>
+            <Text>
+              <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!
+            </Text>
+          </li>
+        </Box>
+        <Text mb={1} sx={{ fontWeight: 500 }}>
+          Available Recursica Layout Tokens:
+        </Text>
+        <Box component="ul" sx={{ pl: 4, mb: 4 }}>
+          <li>
+            <Text>
+              <code>rec-none</code> (0px limit)
+            </Text>
+          </li>
+          <li>
+            <Text>
+              <code>rec-sm</code> (0.5x scaling)
+            </Text>
+          </li>
+          <li>
+            <Text>
+              <code>rec-default</code> (1.0x scaling)
+            </Text>
+          </li>
+          <li>
+            <Text>
+              <code>rec-md</code> (1.5x scaling)
+            </Text>
+          </li>
+          <li>
+            <Text>
+              <code>rec-lg</code> (2.0x scaling)
+            </Text>
+          </li>
+          <li>
+            <Text>
+              <code>rec-xl</code> (3.0x scaling)
+            </Text>
+          </li>
+          <li>
+            <Text>
+              <code>rec-2xl</code> (4.0x scaling)
+            </Text>
+          </li>
+        </Box>
+
+        <Divider sx={{ mb: 4 }} />
+
+        <Text variant="h6" mb={1}>
+          Primitive Layout Components Exemption
+        </Text>
+        <Text mb={1}>
+          Unlike complex UI components (Buttons, Tabs, Inputs) which are
+          strictly protected, <strong>Primitive Layout Components</strong> (
+          <code>Flex</code>,<code>Stack</code>, <code>Group</code>,{" "}
+          <code>Container</code>) are entirely exempt from the{" "}
+          <code>RecursicaOverStyled</code> gatekeeper.
+        </Text>
+        <Text mb={4}>
+          Because the entire functional purpose of these components is
+          structural layout composition, developers are free to pass any
+          standard MUI width, height, padding, margin, gap, and alignment
+          property directly to them without needing to flag{" "}
+          <code>overStyled={`{true}`}</code>. The internal custom token mapper
+          (such as converting <code>gap="rec-md"</code>) is still active
+          natively on these wrappers.
+        </Text>
+
+        <Divider sx={{ mb: 4 }} />
+
+        <Text variant="h6" mb={2}>
+          Live Example
+        </Text>
+        <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={4}>
+          <Box>
+            <Text
+              variant="caption"
+              sx={{ color: "text.secondary", mb: 1, display: "block" }}
+            >
+              Strict Baseline (Default)
+            </Text>
+            {/* Note: In mui-adapter, Button is currently a stub so we just pass standard React props */}
+            <Button>Standard UI Kit Button</Button>
+          </Box>
+          <Box>
+            <Text
+              variant="caption"
+              sx={{ color: "text.secondary", mb: 1, display: "block" }}
+            >
+              overStyled={`{true}`}
+            </Text>
+            {/* Note: Button props are just standard HTML div props for the stub */}
+            <Button
+              style={{
+                backgroundColor: "pink",
+                color: "black",
+                borderRadius: "24px",
+                padding: "8px 16px",
+              }}
+            >
+              Unsafe Pink Marketing Button
+            </Button>
+          </Box>
+        </Stack>
+      </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.stories.tsx

@@ -0,0 +1,16 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Accordion } from "./Accordion";
+import { ComingSoon } from "@recursica/storybook-template";
+
+const meta: Meta<typeof Accordion> = {
+  title: "UI-Kit/🚧 Accordion",
+  component: Accordion,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Accordion>;
+
+export const Default: Story = {
+  render: () => <ComingSoon componentName="Accordion" />,
+};

package/src/components/Accordion/Accordion.tsx

@@ -0,0 +1,7 @@
+import React from "react";
+
+export type AccordionProps = React.HTMLAttributes<HTMLDivElement>;
+
+export const Accordion: React.FC<AccordionProps> = (props) => {
+  return <div {...props}>Accordion</div>;
+};

package/src/components/Accordion/index.ts

@@ -0,0 +1 @@
+export * from "./Accordion";

package/src/components/AssistiveElement/AssistiveElement.stories.tsx

@@ -0,0 +1,16 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { AssistiveElement } from "./AssistiveElement";
+import { ComingSoon } from "@recursica/storybook-template";
+
+const meta: Meta<typeof AssistiveElement> = {
+  title: "UI-Kit/🚧 AssistiveElement",
+  component: AssistiveElement,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof AssistiveElement>;
+
+export const Default: Story = {
+  render: () => <ComingSoon componentName="AssistiveElement" />,
+};

package/src/components/AssistiveElement/AssistiveElement.tsx

@@ -0,0 +1,7 @@
+import React from "react";
+
+export type AssistiveElementProps = React.HTMLAttributes<HTMLDivElement>;
+
+export const AssistiveElement: React.FC<AssistiveElementProps> = (props) => {
+  return <div {...props}>AssistiveElement</div>;
+};

package/src/components/AssistiveElement/index.ts

@@ -0,0 +1 @@
+export * from "./AssistiveElement";

package/src/components/Avatar/Avatar.stories.tsx

@@ -0,0 +1,16 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Avatar } from "./Avatar";
+import { ComingSoon } from "@recursica/storybook-template";
+
+const meta: Meta<typeof Avatar> = {
+  title: "UI-Kit/🚧 Avatar",
+  component: Avatar,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Avatar>;
+
+export const Default: Story = {
+  render: () => <ComingSoon componentName="Avatar" />,
+};

package/src/components/Avatar/Avatar.tsx

@@ -0,0 +1,7 @@
+import React from "react";
+
+export type AvatarProps = React.HTMLAttributes<HTMLDivElement>;
+
+export const Avatar: React.FC<AvatarProps> = (props) => {
+  return <div {...props}>Avatar</div>;
+};

package/src/components/Avatar/index.ts

@@ -0,0 +1 @@
+export * from "./Avatar";

package/src/components/Badge/Badge.stories.tsx

@@ -0,0 +1,16 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Badge } from "./Badge";
+import { ComingSoon } from "@recursica/storybook-template";
+
+const meta: Meta<typeof Badge> = {
+  title: "UI-Kit/🚧 Badge",
+  component: Badge,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Badge>;
+
+export const Default: Story = {
+  render: () => <ComingSoon componentName="Badge" />,
+};

package/src/components/Badge/Badge.tsx

@@ -0,0 +1,7 @@
+import React from "react";
+
+export type BadgeProps = React.HTMLAttributes<HTMLDivElement>;
+
+export const Badge: React.FC<BadgeProps> = (props) => {
+  return <div {...props}>Badge</div>;
+};

package/src/components/Badge/index.ts

@@ -0,0 +1 @@
+export * from "./Badge";

package/src/components/Box/Box.stories.tsx

@@ -0,0 +1,59 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Box } from "./Box";
+
+const meta: Meta<typeof Box> = {
+  title: "UI-Kit/Box",
+  component: Box,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The `Box` component is the foundational layout primitive. It accepts all standard MUI layout properties (like `m`, `mt`, `p`, `px`, etc.), but natively intercepts **Recursica Spacing Tokens** (e.g., `rec-none`, `rec-sm`, `rec-default`, `rec-md`, `rec-lg`, `rec-xl`, `rec-2xl`). This allows developers to use Recursica's strict design tokens seamlessly alongside standard MUI spacing.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Box>;
+
+export const Default: Story = {
+  args: {
+    children: "This is a standard Box",
+    m: "20px",
+  },
+  render: (args) => (
+    <Box
+      {...args}
+      style={{ border: "1px solid gray", padding: "10px" }}
+      overStyled={true}
+    />
+  ),
+};
+
+export const WithRecursicaTokens: Story = {
+  args: {
+    children: "This Box uses Recursica layout tokens",
+    m: "rec-xl",
+    p: "rec-md",
+  },
+  render: (args) => (
+    <div style={{ border: "1px dashed #ccc", display: "inline-block" }}>
+      <Box
+        {...args}
+        style={{ backgroundColor: "rgba(0,0,0,0.1)" }}
+        overStyled={true}
+      />
+    </div>
+  ),
+};
+
+export const Polymorphic: Story = {
+  args: {
+    component: "section",
+    children: "This Box is rendered as a <section> element",
+    m: "rec-default",
+    p: "rec-lg",
+  },
+};

package/src/components/Box/Box.tsx

@@ -0,0 +1,27 @@
+import React, { forwardRef } from "react";
+import { Box as MUIBox, type BoxProps as MUIBoxProps } from "@mui/material";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+
+export type BoxProps<C extends React.ElementType = "div"> = RecursicaOverStyled<
+  MUIBoxProps<C, { component?: C }>
+>;
+
+export const Box = forwardRef(function Box<C extends React.ElementType = "div">(
+  props: BoxProps<C>,
+  ref: React.Ref<Element>,
+) {
+  const { overStyled = false, ...rest } = props;
+
+  const sanitizedProps = filterStylingProps(
+    rest as Record<string, unknown>,
+    overStyled,
+  );
+
+  return <MUIBox ref={ref} {...sanitizedProps} />;
+}) as <C extends React.ElementType = "div">(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  props: BoxProps<C> & { ref?: React.ForwardedRef<any> },
+) => React.ReactElement | null;

package/src/components/Box/index.ts

@@ -0,0 +1 @@
+export * from "./Box";

package/src/components/Breadcrumb/Breadcrumb.stories.tsx

@@ -0,0 +1,16 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Breadcrumb } from "./Breadcrumb";
+import { ComingSoon } from "@recursica/storybook-template";
+
+const meta: Meta<typeof Breadcrumb> = {
+  title: "UI-Kit/🚧 Breadcrumb",
+  component: Breadcrumb,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Breadcrumb>;
+
+export const Default: Story = {
+  render: () => <ComingSoon componentName="Breadcrumb" />,
+};

package/src/components/Breadcrumb/Breadcrumb.tsx

@@ -0,0 +1,7 @@
+import React from "react";
+
+export type BreadcrumbProps = React.HTMLAttributes<HTMLDivElement>;
+
+export const Breadcrumb: React.FC<BreadcrumbProps> = (props) => {
+  return <div {...props}>Breadcrumb</div>;
+};

package/src/components/Breadcrumb/index.ts

@@ -0,0 +1 @@
+export * from "./Breadcrumb";

package/src/components/Button/Button.stories.tsx

@@ -0,0 +1,16 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Button } from "./Button";
+import { ComingSoon } from "@recursica/storybook-template";
+
+const meta: Meta<typeof Button> = {
+  title: "UI-Kit/🚧 Button",
+  component: Button,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Button>;
+
+export const Default: Story = {
+  render: () => <ComingSoon componentName="Button" />,
+};

package/src/components/Button/Button.tsx

@@ -0,0 +1,7 @@
+import React from "react";
+
+export type ButtonProps = React.HTMLAttributes<HTMLDivElement>;
+
+export const Button: React.FC<ButtonProps> = (props) => {
+  return <div {...props}>Button</div>;
+};

package/src/components/Button/index.ts

@@ -0,0 +1 @@
+export * from "./Button";

package/src/components/Card/Card.stories.tsx

@@ -0,0 +1,16 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Card } from "./Card";
+import { ComingSoon } from "@recursica/storybook-template";
+
+const meta: Meta<typeof Card> = {
+  title: "UI-Kit/🚧 Card",
+  component: Card,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Card>;
+
+export const Default: Story = {
+  render: () => <ComingSoon componentName="Card" />,
+};

package/src/components/Card/Card.tsx

@@ -0,0 +1,7 @@
+import React from "react";
+
+export type CardProps = React.HTMLAttributes<HTMLDivElement>;
+
+export const Card: React.FC<CardProps> = (props) => {
+  return <div {...props}>Card</div>;
+};

package/src/components/Card/index.ts

@@ -0,0 +1 @@
+export * from "./Card";

package/src/components/Checkbox/Checkbox.stories.tsx

@@ -0,0 +1,16 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Checkbox } from "./Checkbox";
+import { ComingSoon } from "@recursica/storybook-template";
+
+const meta: Meta<typeof Checkbox> = {
+  title: "UI-Kit/🚧 Checkbox",
+  component: Checkbox,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Checkbox>;
+
+export const Default: Story = {
+  render: () => <ComingSoon componentName="Checkbox" />,
+};

package/src/components/Checkbox/Checkbox.tsx

@@ -0,0 +1,7 @@
+import React from "react";
+
+export type CheckboxProps = React.HTMLAttributes<HTMLDivElement>;
+
+export const Checkbox: React.FC<CheckboxProps> = (props) => {
+  return <div {...props}>Checkbox</div>;
+};

package/src/components/Checkbox/index.ts

@@ -0,0 +1 @@
+export * from "./Checkbox";

package/src/components/Chip/Chip.stories.tsx

@@ -0,0 +1,16 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Chip } from "./Chip";
+import { ComingSoon } from "@recursica/storybook-template";
+
+const meta: Meta<typeof Chip> = {
+  title: "UI-Kit/🚧 Chip",
+  component: Chip,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Chip>;
+
+export const Default: Story = {
+  render: () => <ComingSoon componentName="Chip" />,
+};

package/src/components/Chip/Chip.tsx

@@ -0,0 +1,7 @@
+import React from "react";
+
+export type ChipProps = React.HTMLAttributes<HTMLDivElement>;
+
+export const Chip: React.FC<ChipProps> = (props) => {
+  return <div {...props}>Chip</div>;
+};

package/src/components/Chip/index.ts

@@ -0,0 +1 @@
+export * from "./Chip";

package/src/components/Container/Container.stories.tsx

@@ -0,0 +1,16 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Container } from "./Container";
+import { ComingSoon } from "@recursica/storybook-template";
+
+const meta: Meta<typeof Container> = {
+  title: "UI-Kit/🚧 Container",
+  component: Container,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Container>;
+
+export const Default: Story = {
+  render: () => <ComingSoon componentName="Container" />,
+};