@recursica/mui-adapter 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @recursica/mui-adapter
 
+## 0.16.0
+
+### Minor Changes
+
+- db7701f: Updated layout of docs and mcp
+
+## 0.15.0
+
+### Minor Changes
+
+- e0f2fc5: Update to latest official version
+
+### Patch Changes
+
+- Updated dependencies [e0f2fc5]
+  - @recursica/official-release@2.6.0
+
 ## 0.14.0
 
 ### Minor Changes

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mui-adapter"
   },
-  "version": "0.14.0",
+  "version": "0.16.0",
   "publishConfig": {
     "access": "public"
   },

package/src/components/Accordion/USAGE.md

@@ -0,0 +1,43 @@
+# Accordion - Usage Guide
+
+This document describes how to integrate and use the `Accordion` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Accordion } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Accordion } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return (
+    <Accordion>
+      <Accordion.Item value="item-1">
+        <Accordion.Control>Section 1</Accordion.Control>
+        <Accordion.Panel>Section 1 content</Accordion.Panel>
+      </Accordion.Item>
+    </Accordion>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mui-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.

package/src/components/AssistiveElement/USAGE.md

@@ -0,0 +1,36 @@
+# AssistiveElement - Usage Guide
+
+This document describes how to integrate and use the `AssistiveElement` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { AssistiveElement } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { AssistiveElement } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return <AssistiveElement state="error" message="This field is required" />;
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mui-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.

package/src/components/Autocomplete/USAGE.md

@@ -0,0 +1,42 @@
+# Autocomplete - Usage Guide
+
+This document describes how to integrate and use the `Autocomplete` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Autocomplete } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Autocomplete } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return (
+    <Autocomplete
+      label="Country"
+      placeholder="Type a country name..."
+      data={["USA", "Canada", "Mexico"]}
+    />
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mui-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.

package/src/components/Avatar/USAGE.md

@@ -0,0 +1,38 @@
+# Avatar - Usage Guide
+
+This document describes how to integrate and use the `Avatar` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Avatar } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Avatar } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return (
+    <Avatar src="https://example.com/avatar.png" alt="User Name" radius="xl" />
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mui-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.

package/src/components/Badge/USAGE.md

@@ -0,0 +1,40 @@
+# Badge - Usage Guide
+
+This document describes how to integrate and use the `Badge` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Badge } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Badge } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return (
+    <Badge variant="filled" size="md">
+      Active
+    </Badge>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mui-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.

package/src/components/Box/USAGE.md

@@ -0,0 +1,48 @@
+# Box - Usage Guide
+
+This document describes how to integrate and use the `Box` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Box } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Box } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return (
+    <Box>
+      <Text>This is a basic layout container.</Text>
+    </Box>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mui-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+## `sx` Prop Exemption
+
+By design, the `Box` component is the most permissive primitive in the UI kit. It explicitly allows the `sx` prop to pass through to the underlying MUI `Box`. It does not use any strict styling gatekeepers (`RecursicaOverStyled`, `filterSxProp`). It is intended to be used as a final escape hatch when the standard layout primitives or design system tokens cannot fulfill a unique layout requirement.

package/src/components/Breadcrumb/USAGE.md

@@ -0,0 +1,42 @@
+# Breadcrumb - Usage Guide
+
+This document describes how to integrate and use the `Breadcrumb` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Breadcrumb } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Breadcrumb } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return (
+    <Breadcrumb>
+      <Link href="/">Home</Link>
+      <Link href="/components">Components</Link>
+      <Text>Button</Text>
+    </Breadcrumb>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mui-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.

package/src/components/Button/USAGE.md

@@ -0,0 +1,58 @@
+# Button - Usage Guide
+
+This document describes how to integrate and use the `Button` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Button } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Button } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return (
+    <Button variant="primary" onClick={() => console.log("Clicked!")}>
+      Click Me
+    </Button>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mui-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+## Loader color contrast
+
+**Decision:** When a Button is in a loading state, the `Recursica Loader` component is injected via the `loadingIndicator` prop. The `Loader` component strictly defines its own colors and styles per variant, meaning it does not automatically inherit the text color (`currentColor`) from the Button.
+
+**Constraint:** This can lead to contrast issues (e.g., a blue dots loader inside a solid blue button). Design has explicitly decided not to address this at the moment. As such, developers using the `loading` prop must be aware that the loader's color is fixed by its internal tokens, not by the button's context.
+
+---
+
+## Loading state enforces disabled state
+
+**Decision:** When `loading={true}` is passed to the Button, the component explicitly forces `disabled={true}` natively on the underlying element.
+
+**Implementation:** This ensures that loading buttons automatically inherit the brand theme disabled opacities (via the `:disabled` CSS pseudo-class) rather than relying solely on MUI's internal loading opacity adjustments.

package/src/components/Card/USAGE.md

@@ -0,0 +1,69 @@
+# Card - Usage Guide
+
+This document describes how to integrate and use the `Card` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Card } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Card } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return (
+    <Card>
+      <Card.Header>
+        <Title order={3}>Card Title</Title>
+      </Card.Header>
+      <Card.Content>
+        <Text>
+          This is some card content styled natively via design tokens.
+        </Text>
+      </Card.Content>
+      <Card.Footer>
+        <Button variant="secondary">Cancel</Button>
+        <Button variant="primary">Submit</Button>
+      </Card.Footer>
+    </Card>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mui-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+## Architecture Overrides
+
+Because MUI natively constructs `Card` bounding boxes using `<Paper>` components (which lack the precise edge-to-edge layouts native to Mantine's sections), we implemented custom margins for edge-to-edge section components:
+
+- `<Card.Header>` explicitly hooks `--recursica_ui-kit_components_card_properties_header-background` and corresponding padding variables, stretching edge-to-edge via negative margin resets.
+- `<Card.Footer>` explicitly hooks `--recursica_ui-kit_components_card_properties_footer-background` and corresponding padding variables.
+
+## Layout Alignment Exceptions
+
+To allow Cards to fit cleanly inside dynamic/flex layouts (like dashboard panels, grid tracks, or sidebar layout segments), the Card wrapper implements a custom gatekeeper bypass for outer styling properties:
+
+- Exposes a safe subset of flexbox/dimensions styling properties (`flex`, `flexGrow`, `flexShrink`, `flexBasis`, `grow`, `h`, `height`) on the root `<Card>` component to allow proper sizing alongside layout siblings.
+- Sets `<Card.Content>` to `flex-grow: 1;` by default via CSS modules. Since the root `<Card>` has `display: flex; flex-direction: column;`, this makes the content area expand to fill all vertical space, pushing `<Card.Footer>` to align at the absolute bottom of the bounding box.

package/src/components/Checkbox/USAGE.md

@@ -0,0 +1,36 @@
+# Checkbox - Usage Guide
+
+This document describes how to integrate and use the `Checkbox` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Checkbox } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Checkbox } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return <Checkbox label="Accept terms and conditions" defaultChecked />;
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mui-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.

package/src/components/Chip/USAGE.md

@@ -0,0 +1,36 @@
+# Chip - Usage Guide
+
+This document describes how to integrate and use the `Chip` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Chip } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Chip } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return <Chip defaultChecked>Clickable Chip</Chip>;
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mui-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.

package/src/components/Container/USAGE.md

@@ -0,0 +1,48 @@
+# Container - Usage Guide
+
+This document describes how to integrate and use the `Container` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Container } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Container } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return (
+    <Container size="lg">
+      <Text>Centered content container constrained by maximum width.</Text>
+    </Container>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mui-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+## `sx` Prop Exemption
+
+By design, the `Container` component explicitly allows the `sx` prop to pass through to the underlying MUI `Container`. Unlike standard UI kit components (which use the `RecursicaOverStyled` gatekeeper) or flex layout primitives (which strip `sx` via `OmitSx` and `filterSxProp`), `Container` acts as a structural boundary where advanced, one-off positioning adjustments may be required by the consuming application.

package/src/components/DatePicker/USAGE.md

@@ -0,0 +1,36 @@
+# DatePicker - Usage Guide
+
+This document describes how to integrate and use the `DatePicker` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { DatePicker } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { DatePicker } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return <DatePicker label="Select Date" placeholder="Pick a date" />;
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mui-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.

package/src/components/Dropdown/USAGE.md

@@ -0,0 +1,41 @@
+# Dropdown - Usage Guide
+
+This document describes how to integrate and use the `Dropdown` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Dropdown } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Dropdown } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return (
+    <Dropdown placeholder="Select an option">
+      <Dropdown.Item value="1">Option 1</Dropdown.Item>
+      <Dropdown.Item value="2">Option 2</Dropdown.Item>
+    </Dropdown>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mui-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.