@recursica/mui-adapter 0.5.0 → 0.7.0

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mui-adapter"
   },
-  "version": "0.5.0",
+  "version": "0.7.0",
   "publishConfig": {
     "access": "public"
   },
@@ -33,7 +33,11 @@
     "dist",
     "src",
     "CHANGELOG.md",
-    ".storybook/commonArgTypes.ts"
+    ".storybook/commonArgTypes.ts",
+    "llms.txt",
+    "USAGE.md",
+    "ARCHITECTURE.md",
+    "SETUP.md"
   ],
   "keywords": [
     "react",
@@ -51,13 +55,14 @@
     "build": "vite build --mode library",
     "build-storybook": "storybook build -o storybook-static",
     "lint": "eslint .",
-    "storybook": "storybook dev -p 6006",
+    "storybook": "storybook dev -p 6012",
     "analyze-tokens": "analyze-tokens --css recursica_variables_scoped.css --dir src/components --output token-analysis.json",
     "prebuild": "npm run analyze-tokens"
   },
   "devDependencies": {
     "@chromatic-com/storybook": "^5.1.1",
     "@eslint/js": "^9.25.0",
+    "@mui/lab": "^7.0.1-beta.25",
     "@recursica/adapter-common": "*",
     "@recursica/recursica-postcss-vars": "*",
     "@recursica/storybook-template": "*",
@@ -96,8 +101,14 @@
   "peerDependencies": {
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.0",
+    "@mui/lab": "^7.0.1-beta.25",
     "@mui/material": "^7.3.0",
     "react": ">=16.8.0",
     "react-dom": ">=16.8.0"
+  },
+  "peerDependenciesMeta": {
+    "@mui/lab": {
+      "optional": true
+    }
   }
 }

package/src/components/Accordion/Accordion.module.css

@@ -1,56 +1,294 @@
-/* EXEMPTIONS:
-   This component is a placeholder stub. Once fully implemented, its specific
-   tokens will be fully wired up to direct styles. */
-
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_border-radius */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_colors_background-collapsed */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_colors_background-expanded */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_colors_content-background */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_colors_content-border-color */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_colors_content-text */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_colors_icon */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_colors_item-border-color */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_content-border-radius */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_content-border-size */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_content-bottom-padding */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_content-horizontal-padding */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_content-margin */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_content-text_font-family */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_content-text_font-size */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_content-text_font-style */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_content-text_font-weight */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_content-text_letter-spacing */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_content-text_line-height */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_content-text_text-decoration */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_content-text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_content-top-padding */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_elevation-content */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_elevation-item */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_header-horizontal-padding */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_header-text_font-family */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_header-text_font-size */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_header-text_font-style */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_header-text_font-weight */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_header-text_letter-spacing */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_header-text_line-height */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_header-text_text-decoration */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_header-text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_header-vertical-padding */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_hover-color */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_hover-opacity */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_icon-gap */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_icon-left-size */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_icon-right-size */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-item_properties_item-border-size */
-/* recursica-ignore: --recursica_ui-kit_components_accordion_properties_border-radius */
-/* recursica-ignore: --recursica_ui-kit_components_accordion_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_accordion_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_accordion_properties_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_accordion_properties_colors_divider */
-/* recursica-ignore: --recursica_ui-kit_components_accordion_properties_divider-size */
-/* recursica-ignore: --recursica_ui-kit_components_accordion_properties_elevation */
-/* recursica-ignore: --recursica_ui-kit_components_accordion_properties_item-gap */
-/* recursica-ignore: --recursica_ui-kit_components_accordion_properties_max-width */
-/* recursica-ignore: --recursica_ui-kit_components_accordion_properties_min-width */
-/* recursica-ignore: --recursica_ui-kit_components_accordion_properties_padding */
+/* ==== ACCORDION CONTAINER ==== */
+.root {
+  box-sizing: border-box;
+  margin: 0;
+  display: flex;
+  flex-direction: column;
+
+  border-style: solid;
+  border-width: var(
+    --recursica_ui-kit_components_accordion_properties_border-size
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_accordion_properties_border-radius
+  );
+  border-color: var(
+    --recursica_ui-kit_components_accordion_properties_colors_border-color
+  );
+  background-color: var(
+    --recursica_ui-kit_components_accordion_properties_colors_background
+  );
+  box-shadow: var(--recursica_ui-kit_components_accordion_properties_elevation);
+
+  max-width: var(--recursica_ui-kit_components_accordion_properties_max-width);
+  min-width: var(--recursica_ui-kit_components_accordion_properties_min-width);
+  padding: var(--recursica_ui-kit_components_accordion_properties_padding);
+
+  /* Ensure gaps between items */
+  gap: var(--recursica_ui-kit_components_accordion_properties_item-gap);
+}
+
+/* ==== ACCORDION ITEM ==== */
+.item {
+  box-sizing: border-box;
+  margin: 0;
+  position: relative;
+  transition: all 0.2s ease;
+
+  /* Overriding Mantine Default Borders natively */
+  border-bottom: none;
+
+  border-style: solid;
+  border-color: var(
+    --recursica_ui-kit_components_accordion-item_properties_colors_item-border-color
+  );
+  border-width: var(
+    --recursica_ui-kit_components_accordion-item_properties_item-border-size
+  );
+  border-bottom-color: var(
+    --recursica_ui-kit_components_accordion_properties_colors_divider
+  );
+  border-bottom-width: var(
+    --recursica_ui-kit_components_accordion_properties_divider-size
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_accordion-item_properties_border-radius
+  );
+  box-shadow: var(
+    --recursica_ui-kit_components_accordion-item_properties_elevation-item
+  );
+
+  background-color: var(
+    --recursica_ui-kit_components_accordion-item_properties_colors_background-collapsed
+  );
+}
+.item:global(.Mui-expanded) {
+  background-color: var(
+    --recursica_ui-kit_components_accordion-item_properties_colors_background-expanded
+  );
+}
+.noDivider {
+  border-bottom: none !important;
+  border-bottom-width: 0 !important;
+}
+
+/* ==== ACCORDION CONTROL (HEADER) ==== */
+.control {
+  box-sizing: border-box;
+  width: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+
+  /* Re-apply gap defined by UI Kit for icons vs text */
+  gap: var(--recursica_ui-kit_components_accordion-item_properties_icon-gap);
+
+  /* Strip Mantine's baked padding directly */
+  padding: var(
+      --recursica_ui-kit_components_accordion-item_properties_header-vertical-padding
+    )
+    var(
+      --recursica_ui-kit_components_accordion-item_properties_header-horizontal-padding
+    );
+  background-color: transparent;
+
+  transition: background-color 0.15s ease;
+  position: relative;
+  z-index: 1;
+  color: var(
+    --recursica_ui-kit_components_accordion-item_properties_colors_text
+  );
+
+  /* Header Typography */
+  font-family: var(
+    --recursica_ui-kit_components_accordion-item_properties_header-text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_accordion-item_properties_header-text_font-size
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_accordion-item_properties_header-text_font-weight
+  );
+  font-style: var(
+    --recursica_ui-kit_components_accordion-item_properties_header-text_font-style
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_accordion-item_properties_header-text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_accordion-item_properties_header-text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_accordion-item_properties_header-text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_accordion-item_properties_header-text_text-transform
+  );
+}
+
+/* Ensure inner native wrap aligns and has zero margins */
+.control :global(.MuiAccordionSummary-content) {
+  margin: 0 !important;
+  display: flex;
+  align-items: center;
+  gap: inherit;
+  flex: 1;
+}
+
+.control :global(.MuiAccordionSummary-content.Mui-expanded) {
+  margin: 0 !important;
+}
+
+/* Mantine natively places hover states on the control node. 
+   We explicitly override it with our layer hover tokens via an overlay ::after structure
+   so we can cleanly utilize the hover-opacity token! */
+.control:hover {
+  background-color: transparent;
+}
+.control::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  z-index: -1;
+  pointer-events: none;
+  background-color: var(
+    --recursica_ui-kit_components_accordion-item_properties_hover-color
+  );
+  opacity: 0;
+  transition: opacity 150ms ease;
+}
+.control:hover:not(:disabled)::after {
+  opacity: var(
+    --recursica_ui-kit_components_accordion-item_properties_hover-opacity
+  );
+}
+
+/* Label logic inside the Control wrapper */
+.label {
+  flex: 1;
+  text-align: left;
+  color: inherit;
+  padding: 0; /* Clear Mantine inner padding */
+}
+
+/* ==== CHEVRON / RIGHT ICON ==== */
+.chevron {
+  flex-shrink: 0;
+  width: var(
+    --recursica_ui-kit_components_accordion-item_properties_icon-right-size
+  );
+  height: var(
+    --recursica_ui-kit_components_accordion-item_properties_icon-right-size
+  );
+  color: var(
+    --recursica_ui-kit_components_accordion-item_properties_colors_icon
+  );
+  margin: 0;
+  transition: transform 200ms ease;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+.chevron > * {
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+}
+.item:global(.Mui-expanded) .chevron {
+  transform: rotate(180deg);
+}
+
+/* ==== LEFT ICON / CUSTOM ICONS ==== */
+.iconLeftWrapper {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: var(
+    --recursica_ui-kit_components_accordion-item_properties_icon-left-size
+  );
+  height: var(
+    --recursica_ui-kit_components_accordion-item_properties_icon-left-size
+  );
+  color: var(
+    --recursica_ui-kit_components_accordion-item_properties_colors_icon
+  );
+}
+.iconLeftWrapper > * {
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+}
+
+/* ==== ACCORDION PANEL (CONTENT) ==== */
+.panel {
+  box-sizing: border-box;
+  margin: var(
+    --recursica_ui-kit_components_accordion-item_properties_content-margin
+  );
+  padding: 0; /* Overriding dynamic layout structure */
+  background-color: var(
+    --recursica_ui-kit_components_accordion-item_properties_colors_content-background
+  );
+  border-style: solid;
+  border-color: var(
+    --recursica_ui-kit_components_accordion-item_properties_colors_content-border-color
+  );
+  border-width: var(
+    --recursica_ui-kit_components_accordion-item_properties_content-border-size
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_accordion-item_properties_content-border-radius
+  );
+  box-shadow: var(
+    --recursica_ui-kit_components_accordion-item_properties_elevation-content
+  );
+}
+
+.content {
+  box-sizing: border-box;
+  /* Strip Mantine padding and apply logic directly mapped */
+  padding: 0
+    var(
+      --recursica_ui-kit_components_accordion-item_properties_content-horizontal-padding
+    )
+    var(
+      --recursica_ui-kit_components_accordion-item_properties_content-bottom-padding
+    );
+
+  /* Apply offset gap explicitly calculated below header */
+  padding-top: var(
+    --recursica_ui-kit_components_accordion-item_properties_content-top-padding
+  );
+
+  color: var(
+    --recursica_ui-kit_components_accordion-item_properties_colors_content-text
+  );
+
+  /* Content Typography */
+  font-family: var(
+    --recursica_ui-kit_components_accordion-item_properties_content-text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_accordion-item_properties_content-text_font-size
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_accordion-item_properties_content-text_font-weight
+  );
+  font-style: var(
+    --recursica_ui-kit_components_accordion-item_properties_content-text_font-style
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_accordion-item_properties_content-text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_accordion-item_properties_content-text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_accordion-item_properties_content-text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_accordion-item_properties_content-text_text-transform
+  );
+}

package/src/components/Accordion/Accordion.stories.tsx

@@ -1,35 +1,145 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { Accordion } from "./Accordion";
-import { ComingSoon } from "@recursica/storybook-template";
+import { Layer } from "@recursica/adapter-common";
+
+const SVGIcon = () => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width="24"
+    height="24"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+  >
+    <path d="M12 2v20M17 5H9.5a3.5 3.5 0 0 0 0 7h5a3.5 3.5 0 0 1 0 7H6" />
+  </svg>
+);
+
+const ChevronIcon = () => (
+  <svg
+    width="24"
+    height="24"
+    viewBox="0 0 24 24"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+  >
+    <path
+      d="M20.0306 9.53062L12.5306 17.0306C12.461 17.1003 12.3783 17.1557 12.2872 17.1934C12.1962 17.2312 12.0986 17.2506 12 17.2506C11.9014 17.2506 11.8038 17.2312 11.7128 17.1934C11.6218 17.1557 11.539 17.1003 11.4694 17.0306L3.96938 9.53062C3.82865 9.38988 3.74959 9.19901 3.74959 8.99999C3.74959 8.80097 3.82865 8.61009 3.96938 8.46936C4.11011 8.32863 4.30098 8.24957 4.50001 8.24957C4.69903 8.24957 4.8899 8.32863 5.03063 8.46936L12 15.4397L18.9694 8.46936C19.0391 8.39968 19.1218 8.34441 19.2128 8.30669C19.3039 8.26898 19.4015 8.24957 19.5 8.24957C19.5986 8.24957 19.6961 8.26898 19.7872 8.30669C19.8782 8.34441 19.9609 8.39968 20.0306 8.46936C20.1003 8.53905 20.1556 8.62177 20.1933 8.71282C20.231 8.80386 20.2504 8.90144 20.2504 8.99999C20.2504 9.09854 20.231 9.19612 20.1933 9.28716C20.1556 9.37821 20.1003 9.46093 20.0306 9.53062Z"
+      fill="currentColor"
+    />
+  </svg>
+);
 
 const meta: Meta<typeof Accordion> = {
-  title: "UI-Kit/🚧 Accordion",
+  title: "UI-Kit/Accordion",
   component: Accordion,
   tags: ["autodocs"],
   parameters: {
-    controls: {
-      include: [
-        "layer",
-        "withLayer",
-        "children",
-        "component",
-        "variant",
-        "size",
-        "icon",
-        "disabled",
-        "href",
-        "onClick",
-        "onChange",
-        "value",
-        "checked",
-      ],
+    docs: {
+      description: {
+        component: `
+The \`Accordion\` component intelligently wraps \`@mantine/core\`'s underlying Accordion layers while applying strict native design system mapping via \`recursica_variables_scoped.css\`.
+
+### Hybrid Composition API (Smart-Rendering)
+To maximize flexibility while strictly aligning with the explicit Recursica design logic, the \`AccordionItem\` operates utilizing a **Hybrid Smart-Rendering Flow**:
+
+1. **Auto-Construction (Explicit Mapping)**:
+If you supply the explicitly outlined Recursica properties (\`title\`, \`leftIcon\`) directly onto \`<Accordion.Item>\`, the component auto-generates the necessary \`<Accordion.Control>\` DOM layer inherently bridging the icons and titles visually while leaving the raw \`children\` wrapped neatly as the \`<Accordion.Panel>\`.
+
+2. **Graceful Falldown (Raw Composability)**:
+If you deliberately omit the \`title\` property, the entire mapping system gracefully falls backward yielding exactly to the raw \`@mantine/core\` composition model. Under this context, you must inject your localized \`<Accordion.Control>\` and \`<Accordion.Panel>\` configurations completely manually.
+
+### Architecture Warning (\`open\`)
+To structurally protect the parent wrapper's core transitions tracking architecture (\`<Accordion value="...">\`), this configuration explicitly rejects mapping isolated \`open={true}\` object states natively on specific configurations. Use Mantine's inherent sibling arrays matching the corresponding active value map!
+        `,
+      },
     },
   },
 };
 
 export default meta;
-type Story = StoryObj<typeof Accordion>;
 
-export const Default: Story = {
-  render: () => <ComingSoon componentName="Accordion" />,
+export const Default: StoryObj<typeof Accordion> = {
+  render: () => {
+    return (
+      <Layer layer={0} style={{ padding: "24px" }}>
+        <Accordion defaultValue="item-1" chevron={<ChevronIcon />}>
+          <Accordion.Item value="item-1">
+            <Accordion.Control>Billing and Membership</Accordion.Control>
+            <Accordion.Panel>
+              You can manage your billing directly from the dashboard tab. All
+              payments are processed automatically.
+            </Accordion.Panel>
+          </Accordion.Item>
+
+          <Accordion.Item value="item-2">
+            <Accordion.Control>Refund Policy</Accordion.Control>
+            <Accordion.Panel>
+              We offer a 30-day money-back guarantee for all new subscriptions.
+            </Accordion.Panel>
+          </Accordion.Item>
+
+          <Accordion.Item value="item-3">
+            <Accordion.Control>Technical Support</Accordion.Control>
+            <Accordion.Panel>
+              Our support team is available 24/7 via live chat or email.
+            </Accordion.Panel>
+          </Accordion.Item>
+        </Accordion>
+      </Layer>
+    );
+  },
+};
+
+export const WithIcons: StoryObj<typeof Accordion> = {
+  render: () => {
+    return (
+      <Layer layer={0} style={{ padding: "24px" }}>
+        <Accordion defaultValue="security" chevron={<ChevronIcon />}>
+          <Accordion.Item value="security">
+            <Accordion.Control leftIcon={<SVGIcon />}>
+              Security Settings
+            </Accordion.Control>
+            <Accordion.Panel>
+              Enable two-factor authentication (2FA) and monitor active sessions
+              below.
+            </Accordion.Panel>
+          </Accordion.Item>
+
+          <Accordion.Item value="privacy">
+            <Accordion.Control leftIcon={<SVGIcon />}>
+              Privacy Configuration
+            </Accordion.Control>
+            <Accordion.Panel>
+              Choose what data is shared with our analytics partners.
+            </Accordion.Panel>
+          </Accordion.Item>
+        </Accordion>
+      </Layer>
+    );
+  },
+};
+
+export const LayerOne: StoryObj<typeof Accordion> = {
+  render: () => {
+    return (
+      <Layer layer={1} style={{ padding: "24px" }}>
+        <Accordion defaultValue="demo" chevron={<ChevronIcon />}>
+          <Accordion.Item value="demo">
+            <Accordion.Control leftIcon={<SVGIcon />}>
+              Layer 1 Render Engine
+            </Accordion.Control>
+            <Accordion.Panel>
+              This Accordion dynamically updates its colors, borders, and
+              typography variables because it is wrapped securely by the
+              simulated `data-recursica-layer="1"`.
+            </Accordion.Panel>
+          </Accordion.Item>
+        </Accordion>
+      </Layer>
+    );
+  },
 };