@recursica/mui-adapter 0.14.0 → 0.16.0

package/src/components/FileInput/USAGE.md

@@ -0,0 +1,36 @@
+# FileInput - Usage Guide
+
+This document describes how to integrate and use the `FileInput` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { FileInput } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { FileInput } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return <FileInput label="Upload Resume" placeholder="Choose a file..." />;
+}
+```
+
+---
+
+## 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/FileUpload/USAGE.md

@@ -0,0 +1,41 @@
+# FileUpload - Usage Guide
+
+This document describes how to integrate and use the `FileUpload` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { FileUpload } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { FileUpload } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return (
+    <FileUpload
+      label="Drop files here"
+      onDrop={(files) => console.log(files)}
+    />
+  );
+}
+```
+
+---
+
+## 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/Flex/USAGE.md

@@ -0,0 +1,41 @@
+# Flex - Usage Guide
+
+This document describes how to integrate and use the `Flex` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Flex } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Flex } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return (
+    <Flex gap="md" justify="space-between" align="center">
+      <Text>Item 1</Text>
+      <Text>Item 2</Text>
+    </Flex>
+  );
+}
+```
+
+---
+
+## 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/FormControlLayout/USAGE.md

@@ -0,0 +1,40 @@
+# FormControlLayout - Usage Guide
+
+This document describes how to integrate and use the `FormControlLayout` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { FormControlLayout } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { FormControlLayout } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return (
+    <FormControlLayout label="Input Field" required>
+      <input type="text" />
+    </FormControlLayout>
+  );
+}
+```
+
+---
+
+## 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/FormControlWrapper/USAGE.md

@@ -0,0 +1,40 @@
+# FormControlWrapper - Usage Guide
+
+This document describes how to integrate and use the `FormControlWrapper` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { FormControlWrapper } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { FormControlWrapper } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return (
+    <FormControlWrapper label="Email Address" required error="Invalid email">
+      <input type="email" />
+    </FormControlWrapper>
+  );
+}
+```
+
+---
+
+## 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/Group/USAGE.md

@@ -0,0 +1,41 @@
+# Group - Usage Guide
+
+This document describes how to integrate and use the `Group` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Group } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Group } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return (
+    <Group gap="md" align="center">
+      <Button variant="secondary">Cancel</Button>
+      <Button variant="primary">Submit</Button>
+    </Group>
+  );
+}
+```
+
+---
+
+## 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/HoverCard/USAGE.md

@@ -0,0 +1,45 @@
+# HoverCard - Usage Guide
+
+This document describes how to integrate and use the `HoverCard` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { HoverCard } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { HoverCard } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return (
+    <HoverCard>
+      <HoverCard.Target>
+        <Text>Hover over me</Text>
+      </HoverCard.Target>
+      <HoverCard.Dropdown>
+        <Text size="sm">This is the hover card popup content.</Text>
+      </HoverCard.Dropdown>
+    </HoverCard>
+  );
+}
+```
+
+---
+
+## 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/Label/USAGE.md

@@ -0,0 +1,36 @@
+# Label - Usage Guide
+
+This document describes how to integrate and use the `Label` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Label } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Label } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return <Label required>Field Label</Label>;
+}
+```
+
+---
+
+## 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/Link/USAGE.md

@@ -0,0 +1,40 @@
+# Link - Usage Guide
+
+This document describes how to integrate and use the `Link` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Link } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Link } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return (
+    <Link href="/dashboard" variant="inline">
+      Go to Dashboard
+    </Link>
+  );
+}
+```
+
+---
+
+## 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/Loader/USAGE.md

@@ -0,0 +1,64 @@
+# Loader - Usage Guide
+
+This document describes how to integrate and use the `Loader` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Loader } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Loader } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return <Loader size="md" />;
+}
+```
+
+---
+
+## 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 & Integration
+
+The `Loader` component for the MUI adapter has been completely hand-coded from scratch using pure CSS and basic HTML `<span>` elements. It explicitly **does not** use MUI's native `<CircularProgress>` component.
+
+This was a deliberate architectural decision to ensure 100% feature and visual parity with the `mantine-adapter`.
+
+### Key Decisions:
+
+- **Bypassing Native Components:** MUI's native loaders (like `<CircularProgress>`) are built using complex animated SVGs and only support a circular "oval" shape. Since the Recursica design system mandates `oval`, `bars`, and `dots` variants, relying on MUI's primitives would have forced a fragmented architecture where `oval` used MUI but `bars` and `dots` were hand-coded.
+- **Parity with Mantine:** To guarantee identical animation timing, easing curves, and DOM structures across frameworks, the CSS keyframes and layout strategies used internally by Mantine's `<Loader>` were extracted and directly replicated in this adapter's `Loader.module.css`.
+
+### Token Mapping:
+
+Sizes are bound through `data-size` attributes (`sm`, `md`, `lg` parsing to target `<div data-size="small">`, etc.).
+
+- **Oval Variant:** Uses a CSS spinning `::after` pseudo-element. To avoid CSS border inheritance bugs when computing tokenized border-widths, a custom `--loader-thickness` CSS variable is used to bridge the token into the spinning element.
+- **Bars & Dots Variants:** Render three internal `<span />` elements sequentially, styled via `Loader.module.css` to handle individual keyframe delays for bouncing or fading animations.
+
+### Color Contrast Rules:
+
+Loaders are hardcoded to map to their explicitly defined design tokens (e.g., `--recursica_ui-kit_components_loader_properties_indicator-color`). By default, they do **not** inherit `currentColor`.
+
+When injected into components like the `Button` (where contrast issues may arise against solid backgrounds), it is the responsibility of the parent component (e.g., `Button.module.css`) to use contextual CSS overrides to force `--loader-color: currentColor !important` if necessary.

package/src/components/Menu/USAGE.md

@@ -0,0 +1,54 @@
+# Menu - Usage Guide
+
+This document describes how to integrate and use the `Menu` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Menu } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Menu } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return (
+    <Menu>
+      <Menu.Target>
+        <Button>Toggle Menu</Button>
+      </Menu.Target>
+      <Menu.Dropdown>
+        <Menu.Item>Profile</Menu.Item>
+        <Menu.Item>Settings</Menu.Item>
+        <Menu.Item color="red">Logout</Menu.Item>
+      </Menu.Dropdown>
+    </Menu>
+  );
+}
+```
+
+---
+
+## 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
+
+- **Compositional API Dropped:** Mantine uses `<Menu.Target>`, `<Menu.Dropdown>`, `<Menu.Item>`, etc., and manages state natively via React context within `<Menu>`. MUI's API is fully monolithic.
+- **Monolithic API Adopted:** Following architectural review, we have abandoned the fabricated context wrappers for `mui-adapter`. We now natively export `Menu`, `MenuItem`, and `MenuDivider` wrapping their `@mui/material` counterparts. Developers are expected to manage `anchorEl` state themselves, just like native MUI. Storybook tests have been updated to simulate this open state so visual regressions still cover the dropdown menu visually.

package/src/components/Modal/USAGE.md

@@ -0,0 +1,40 @@
+# Modal - Usage Guide
+
+This document describes how to integrate and use the `Modal` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Modal } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Modal } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return (
+    <Modal opened={isOpen} onClose={close} title="Modal Title">
+      <Text>This is a styled Modal wrapping the native primitive.</Text>
+    </Modal>
+  );
+}
+```
+
+---
+
+## 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/NumberInput/USAGE.md

@@ -0,0 +1,36 @@
+# NumberInput - Usage Guide
+
+This document describes how to integrate and use the `NumberInput` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { NumberInput } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { NumberInput } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return <NumberInput label="Quantity" min={1} max={10} defaultValue={1} />;
+}
+```
+
+---
+
+## 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/Pagination/USAGE.md

@@ -0,0 +1,42 @@
+# Pagination - Usage Guide
+
+This document describes how to integrate and use the `Pagination` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Pagination } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Pagination } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return <Pagination total={10} value={activePage} onChange={setPage} />;
+}
+```
+
+---
+
+## 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
+
+- **Compositional API Dropped:** Mantine's original `Pagination` component relies heavily on dot-notation sub-components (`Pagination.Root`, `Pagination.Items`, `Pagination.Control`, etc.). MUI's `<Pagination>` is fundamentally monolithic. Following architectural review, we have decided to drop the dot-notation wrappers for `mui-adapter` and rely strictly on MUI's monolithic API. Storybook and visual regression tests have been updated to reflect this divergence while retaining core property mapping compatibility.