@recursica/mantine-adapter 0.32.0 → 0.34.0

package/src/components/Label/USAGE.md

@@ -0,0 +1,87 @@
+# Label - Usage Guide
+
+This document describes how to integrate and use the `Label` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Label } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Label } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return <Label required>Field Label</Label>;
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mantine-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 Overview
+
+The `Label` component is fundamentally built as a strict, localized wrapper around Mantine's native `Input.Label`. The core goal is to preserve context, ref-forwarding, and native accessibility links, while completely overriding visual behaviors via Recursica design variables in scoped CSS.
+
+## Key Design Decisions
+
+### **Layout Architecture**
+
+- Because Recursica dictates complex alignments between primary label text, asterisks, edit icons, and optional strings, Mantine's rigid form label flow could not be used out-of-the-box.
+- Implemented `display: flex; flex-wrap: wrap;` directly on `.root`.
+- Injected strict integer-based flex `order` properties (e.g. `order: 1` for text, `order: 2` for `required`, `order: 5` for `optionalText`) to physically decouple DOM rendering from markup flow.
+- Because `optionalText` often acts as secondary contextual detail, it forces `flex-basis: 100%`, securely wrapping to a secondary line underneath the primary label properties and transforming the horizontal gap spacing seamlessly into a `margin-top` vector.
+
+### **Optional Text & Required Mutually Exclusive Parsing**
+
+- By design standards, a component cannot logically be both "Required" and mapped as "Optional".
+- To bulletproof implementations natively, the adapter forcibly suppresses rendering of the `resolvedOptionalText` strings if the parent wrapper invokes `required={true}`.
+- `optionalText` can operate as dynamic data or specifically as a boolean `true`, which forces the adapter to natively render the formal `(Optional)` string map.
+
+### **The "Edit Icon" Replacer Logic**
+
+- Passing `withEditIcon={true}` evaluates it as fundamentally mutually exclusive to the standard required indicator asterisk.
+- `required={required && !withEditIcon}` is passed to the underlying Mantine structure so the native `*` is entirely suppressed.
+- Added localized styling via `data-replaces-asterisk={required ? "true" : undefined}` onto the `.editIconWrapper` element. If an editable instance is simultaneously designated as required, the edit icon functionally assumes the indicator role natively, overriding its default icon metrics explicitly to match `--recursica_ui-kit_components_label_properties_colors_asterisk`.
+
+### **Bypassing `Input.Wrapper` Integrations**
+
+- By decoupling from Mantine's standard `Input.Wrapper`, the `Label` component is exclusively mapped manually through `FormControlWrapper`. This grants us exact visual sync regarding where the label renders based on `formLayout="stacked"` or `formLayout="side-by-side"`, without fighting internal Mantine positional hooks that assume vertical stacking by default.
+
+### **Label Size Container Constraints**
+
+- The `labelSize` parameter (mapping values like `"small"`) internally **does not scale typographic font metrics**. Instead, it dynamically defines the explicit horizontal bounding width limit of the block container itself.
+- **Architectural Rule:** `labelSize` modifications are strictly designed to execute exclusively when `formLayout="side-by-side"` is active. It acts as an optical grid threshold ensuring left-aligned string wrappers constrain correctly uniformly down a column without bleeding into the physical input arrays alongside them.
+
+## Outstanding Technical Debt / Issues
+
+### **Description Property Omission**
+
+- **Issue:** Currently, the adapter `Label` does not natively parse or support a structured `description` node directly attached beneath it.
+- **Context:** Standard forms often attach subtext beneath inputs, but mapping a description purely within the `<Label>` (distinct from an overall form-control description) is omitted structurally until subsequent UI Kit requirements mandate dedicated `description` styles locally on the label component itself.
+
+### **Global Interactive Hover Mappings**
+
+- **Issue:** Currently, the `editIconWrapper` lacks a dedicated hover background layer.
+- **Context:** While the global theme abstracts interactive hover environments deeply using layered variable syntax (e.g., `--recursica_brand_layer_1_elements_interactive_hover-color`), Recursica's token generation framework natively fails to expose a universally generic placeholder token (e.g., `--recursica_elements_interactive_hover-color`) which downstream wrappers can map their `<Layer>` injections directly into safely.
+- **Resolution Path:** We are explicitly ignoring the `.editIconWrapper:hover` background color assignment until the raw Figma token exports directly scaffold a generic token placeholder that we can interface cleanly with across arbitrary `<Layer>` contexts, avoiding manually mapping statically hardcoded depths (`layer-0`, `layer-1`).

package/src/components/Link/USAGE.md

@@ -0,0 +1,69 @@
+# Link - Usage Guide
+
+This document describes how to integrate and use the `Link` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Link } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Link } from "@recursica/mantine-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/mantine-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
+
+## Missing States in Design Tokens
+
+Currently, the design tokens (`recursica_variables_scoped.css`) only provide states for:
+
+- `default`
+- `hover`
+- `visited`
+- `visited-hover`
+
+There are no tokens for the `active` or `focus` states. If these are needed, they must be added to the Figma variables and exported via the token pipeline. The component relies on the browser's default focus outline for accessibility unless overriden by a global reset.
+
+## Overriding Mantine's underline Prop
+
+Mantine's `Anchor` component uses `underline="hover"` by default. Because our design system specifies exact `text-decoration` styles via CSS tokens, we explicitly pass `underline="never"` to the underlying Mantine component. This prevents Mantine from injecting its own text-decoration inline or via generic classnames, ensuring our scoped CSS remains the single source of truth.
+
+## Base Layout
+
+Mantine's `Anchor` renders an inline element by default and does not natively support `leftSection` like the `Button` component. To support an optional `icon` alongside the text, we enforce a baseline layout of `display: inline-flex` and `align-items: center` in `Link.module.css`.
+
+When an icon is present, the component conditionally passes a `data-has-icon` attribute to the root element. The CSS module uses this attribute to apply the `icon-text-gap` token via the CSS `gap` property.
+
+## Inner Wrappers
+
+The icon and children are wrapped in internal `<span>` tags (`.iconWrapper` and `.labelText` respectively). This follows the component development guide for structural robustness, allowing us to enforce specific sizing on the icon and intrinsic text truncation behavior if the link is placed in a bounded container.

package/src/components/Loader/USAGE.md

@@ -0,0 +1,63 @@
+# Loader - Usage Guide
+
+This document describes how to integrate and use the `Loader` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Loader } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Loader } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return <Loader size="md" />;
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mantine-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 acts as a strictly tokenized wrapper bridging the Recursica UI-Kit `loader` variables to the generic Mantine `@mantine/core` `Loader` primitive.
+
+### Key Decisions:
+
+- **Variant Mapping:** Recursica's `variant` directly proxies to Mantine's `type` prop for `"oval" | "bars" | "dots"`.
+- **Property Overrides Disabled:** Natively overriding specific structural variants directly on the JSX interface like `thickness` and `borderRadius` has been intentionally omitted. Component rendering relies entirely on variables exposed by the underlying UI Kit mappings tied to the size prop.
+
+### Token Mapping:
+
+Sizes are bound through `data-size` attributes (`sm`, `md`, `lg` parsing to target `<div data-size="small">`, etc.).
+
+Mantine natively sets sizing dynamically at the component root and parses thickness/variants differently natively (e.g., `oval` styles its geometry strictly via CSS `border`, while `bars` and `dots` utilize specific DOM inner spans `span.dot` / `span.bar`).
+
+#### Specific CSS Targeting Hacks Used
+
+- `border-width` and `border-radius` structurally style the `thickness` and `border-radius` configuration of the `oval` variant on the `::after` pseudo-element by resolving `--recursica_ui-kit_components_loader_variants_sizes_..._properties_thickness` and `_border-radius`.
+
+### Unsupported Properties
+
+- **xs and xl Sizing:** These sizes are explicitly unsupported in the Recursica standard logic (as surfaced in `filterStylingProps` and UI Kit mappings). Attempting to use them will safely default back or fallthrough statically unless defined later. See `COMPONENT_ISSUES.md`.

package/src/components/Menu/USAGE.md

@@ -0,0 +1,124 @@
+# Menu - Usage Guide
+
+This document describes how to integrate and use the `Menu` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Menu } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Menu } from "@recursica/mantine-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/mantine-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
+
+## 1. Composable API Preservation (1:1 Mapping)
+
+**Decision:** We maintain the exact library composition API structure (`<Menu>`, `<Menu.Target>`, `<Menu.Dropdown>`, `<Menu.Item>`, `<Menu.Divider>`, `<Menu.Label>`, `<Menu.Sub>`, `<Menu.Sub.Target>`, `<Menu.Sub.Item>`, `<Menu.Sub.Dropdown>`) as a 1:1 React component mapping.
+
+**Implementation:** Mantine's Menu internally manages WAI-ARIA role assignments (`role="menu"`, `role="menuitem"`, `aria-haspopup`, `aria-expanded`, `aria-controls`), keyboard navigation (arrow keys, Enter, Escape), and focus trapping natively across its composable hierarchy. By preserving the exact sub-component tree, Recursica safely adopts all of these accessibility behaviors without reimplementation.
+
+---
+
+## 2. Hover State Overlay Technique
+
+**Decision:** We nullify Mantine's native hover background on `Menu.Item` and exclusively utilize Recursica's hover structure via a `::after` pseudo-element overlay.
+
+**Implementation:** The `.item::after` pseudo-object dynamically pulls `hover-color` & `hover-opacity` bindings from the Recursica token system. Mantine natively changes `background-color` on item hover which would override our token-driven colors. We enforce `background-color` to remain the unselected-item background on hover, then layer our pseudo-overlay on top. This is the same technique used in the Accordion component.
+
+---
+
+## 3. Selected vs Unselected Item States
+
+**Decision:** Menu items map to Recursica's `selected-item` and `unselected-item` color token groups.
+
+**Implementation:** The CSS module defaults all items to `unselected-item_*` tokens (background, text, opacity). Items with `[data-selected]` switch to `selected-item_*` tokens. This mapping is natively driven by Mantine's internal state tracking without React state hooks.
+
+---
+
+## 4. `color` Prop Stripping
+
+**Decision:** Mantine's `color` prop on `Menu.Item` (used for semantics like "danger/red") is explicitly stripped in strict mode.
+
+**Implementation:** The `color` prop is deleted from the sanitized props when `overStyled` is `false`. This enforces strict design token adherence — all item colors come from the CSS module referencing Recursica variables. Developers requiring custom color semantics must either:
+
+1. Use `overStyled={true}` as an explicit escape hatch
+2. Contribute a proper Recursica variant to the token system
+
+**Rationale:** The Recursica token set does not currently include danger-specific or semantic-color variants for menu items. Allowing arbitrary `color` values would break design system consistency.
+
+---
+
+## 5. Menu.Target Pass-Through
+
+**Decision:** `Menu.Target` is a transparent pass-through with no styling applied.
+
+**Implementation:** The target wrapper exists solely to manage Mantine's ref forwarding and event binding for the trigger element. No `filterStylingProps` or CSS module classes are applied — the trigger's appearance is entirely controlled by whatever component the integrator places inside it (e.g., `<Button>`).
+
+---
+
+## 6. Sub-Menu Support
+
+**Decision:** We wrap the full Mantine sub-menu hierarchy (`Menu.Sub`, `Menu.Sub.Target`, `Menu.Sub.Item`, `Menu.Sub.Dropdown`).
+
+**Implementation:** Sub-menu components inherit the same CSS module classes as their top-level counterparts since the Recursica token set does not distinguish sub-menu-specific styling. `Menu.Sub.Item` also strips the `color` prop in strict mode, consistent with `Menu.Item`. The sub-menu dropdown portal inherits the same `classNames` from the root Menu's `classNames` mapping.
+
+---
+
+## 7. Dropdown Container Padding
+
+**Decision:** The dropdown container uses `divider-item-gap` as its internal padding.
+
+**Implementation:** This ensures consistent spacing between the dropdown border and its content items. The gap token (`4px` by default) creates a subtle inset that visually separates items from the container edge, matching the Figma design specifications.
+
+---
+
+## 8. Minimal CSS Override Philosophy
+
+**Decision:** The CSS module only overrides visual design tokens (colors, typography, spacing, borders, shadows). All structural layout properties (flex, cursor, pointer-events, box-sizing, etc.) are deferred to Mantine's native behavior.
+
+**Implementation:** Unlike form-field components (e.g., Dropdown/TextField) which require deep structural overrides to strip Mantine's macro wrappers, the Menu is an overlay component where Mantine's native layout is already correct. We avoid setting:
+
+- `overflow` on the dropdown (Mantine renders sub-menu dropdowns inside the parent DOM tree using Floating UI absolute positioning — setting overflow clips them)
+- `display`, `align-items`, `width`, `cursor` on items (Mantine's button-based items already handle this)
+- `pointer-events` on disabled items (Mantine handles disabled natively)
+
+**Rationale:** Early iterations included aggressive structural resets (like `overflow: hidden`, `box-sizing: border-box`, `margin: 0`) cargo-culted from the Dropdown component. These caused sub-menus to render clipped inside the parent dropdown with scrollbars. The lesson: default to Mantine's native behavior and only override what the Recursica token system explicitly needs to control.

package/src/components/Modal/Modal.tsx

@@ -2,6 +2,12 @@ import React from "react";
 import {
   Modal as MantineModal,
   type ModalProps as MantineModalProps,
+  type ModalRootProps as MantineModalRootProps,
+  type ModalOverlayProps as MantineModalOverlayProps,
+  type ModalContentProps as MantineModalContentProps,
+  type ModalHeaderProps as MantineModalHeaderProps,
+  type ModalTitleProps as MantineModalTitleProps,
+  type ModalCloseButtonProps as MantineModalCloseButtonProps,
 } from "@mantine/core";
 import {
   filterStylingProps,
@@ -114,18 +120,22 @@ ModalInner.displayName = "Modal";
  * > primary action button MUST be the right-most element, with the secondary
  * > (outline variant) action placed immediately to the left of it.
  */
-const ModalFooter = React.forwardRef<
-  HTMLDivElement,
+export type ModalFooterProps = RecursicaOverStyled<
   React.ComponentPropsWithoutRef<"div">
->(function ModalFooter({ className, ...rest }, ref) {
-  return (
-    <div
-      ref={ref}
-      className={`${styles.footer} ${className || ""}`}
-      {...rest}
-    />
-  );
-});
+>;
+
+const ModalFooter = React.forwardRef<HTMLDivElement, ModalFooterProps>(
+  function ModalFooter({ overStyled = false, className, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    return (
+      <div
+        ref={ref}
+        className={`${styles.footer} ${className || ""}`}
+        {...sanitizedProps}
+      />
+    );
+  },
+);
 ModalFooter.displayName = "Modal.Footer";
 
 const ModalBody = React.forwardRef<
@@ -197,16 +207,112 @@ const ModalBody = React.forwardRef<
 });
 ModalBody.displayName = "Modal.Body";
 
+// ============================================================
+// MODAL SUB-COMPONENTS (wrapped so overStyled/filterStylingProps applies)
+// ============================================================
+
+export type ModalRootProps = RecursicaOverStyled<MantineModalRootProps>;
+
+const ModalRoot = React.forwardRef<HTMLDivElement, ModalRootProps>(
+  function ModalRoot({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    return (
+      <MantineModal.Root
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineModalRootProps)}
+      />
+    );
+  },
+);
+ModalRoot.displayName = "Modal.Root";
+
+export type ModalOverlayProps = RecursicaOverStyled<MantineModalOverlayProps>;
+
+const ModalOverlay = React.forwardRef<HTMLDivElement, ModalOverlayProps>(
+  function ModalOverlay({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    return (
+      <MantineModal.Overlay
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineModalOverlayProps)}
+      />
+    );
+  },
+);
+ModalOverlay.displayName = "Modal.Overlay";
+
+export type ModalContentProps = RecursicaOverStyled<MantineModalContentProps>;
+
+const ModalContent = React.forwardRef<HTMLDivElement, ModalContentProps>(
+  function ModalContent({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    return (
+      <MantineModal.Content
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineModalContentProps)}
+      />
+    );
+  },
+);
+ModalContent.displayName = "Modal.Content";
+
+export type ModalHeaderProps = RecursicaOverStyled<MantineModalHeaderProps>;
+
+const ModalHeader = React.forwardRef<HTMLElement, ModalHeaderProps>(
+  function ModalHeader({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    return (
+      <MantineModal.Header
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineModalHeaderProps)}
+      />
+    );
+  },
+);
+ModalHeader.displayName = "Modal.Header";
+
+export type ModalTitleProps = RecursicaOverStyled<MantineModalTitleProps>;
+
+const ModalTitle = React.forwardRef<HTMLHeadingElement, ModalTitleProps>(
+  function ModalTitle({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    return (
+      <MantineModal.Title
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineModalTitleProps)}
+      />
+    );
+  },
+);
+ModalTitle.displayName = "Modal.Title";
+
+export type ModalCloseButtonProps =
+  RecursicaOverStyled<MantineModalCloseButtonProps>;
+
+const ModalCloseButton = React.forwardRef<
+  HTMLButtonElement,
+  ModalCloseButtonProps
+>(function ModalCloseButton({ overStyled = false, ...rest }, ref) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  return (
+    <MantineModal.CloseButton
+      ref={ref}
+      {...(sanitizedProps as unknown as MantineModalCloseButtonProps)}
+    />
+  );
+});
+ModalCloseButton.displayName = "Modal.CloseButton";
+
 interface ModalComponent
   extends React.ForwardRefExoticComponent<
     ModalProps & React.RefAttributes<HTMLDivElement>
   > {
-  Root: typeof MantineModal.Root;
-  Overlay: typeof MantineModal.Overlay;
-  Content: typeof MantineModal.Content;
-  Header: typeof MantineModal.Header;
-  Title: typeof MantineModal.Title;
-  CloseButton: typeof MantineModal.CloseButton;
+  Root: typeof ModalRoot;
+  Overlay: typeof ModalOverlay;
+  Content: typeof ModalContent;
+  Header: typeof ModalHeader;
+  Title: typeof ModalTitle;
+  CloseButton: typeof ModalCloseButton;
   Body: typeof ModalBody;
   Footer: typeof ModalFooter;
 }
@@ -214,11 +320,11 @@ interface ModalComponent
 export const Modal = ModalInner as ModalComponent & {
   Footer: typeof ModalFooter;
 };
-Modal.Root = MantineModal.Root;
-Modal.Overlay = MantineModal.Overlay;
-Modal.Content = MantineModal.Content;
-Modal.Header = MantineModal.Header;
-Modal.Title = MantineModal.Title;
-Modal.CloseButton = MantineModal.CloseButton;
+Modal.Root = ModalRoot;
+Modal.Overlay = ModalOverlay;
+Modal.Content = ModalContent;
+Modal.Header = ModalHeader;
+Modal.Title = ModalTitle;
+Modal.CloseButton = ModalCloseButton;
 Modal.Body = ModalBody;
 Modal.Footer = ModalFooter;

package/src/components/Modal/USAGE.md

@@ -0,0 +1,58 @@
+# Modal - Usage Guide
+
+This document describes how to integrate and use the `Modal` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Modal } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Modal } from "@recursica/mantine-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/mantine-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
+
+The `Modal` component strictly wraps Mantine's `<Modal>` primitive. We strip Mantine's abstract native styling props (`size`, `radius`, `shadow`) via the `overStyled` interface and strictly inject CSS variable definitions onto the internal node abstractions (`.content`, `.header`, `.body`, `.title`).
+
+## Limitations & Structural Decisions
+
+### 1. Stripped `size` Prop
+
+Mantine natively exposes an abstract `size` prop (`"sm" | "md" | "lg" | "xl"`) that scales the Modal geometry. The Recursica UI Kit explicitly dictates strict geometric bounding boxes: `max-width: 960px` and `min-width: 304px`. To enforce absolute parity with the design system, the `size` prop has been intentionally omitted from the component's interface. The width of the Modal will scale fluidly strictly between these Figma-driven pixel limits.
+
+### 2. Scroll Dividers behavior
+
+Mantine internally handles scroll state natively, dynamically showing/hiding a divider line when content overflows in `.body`. This logic is tightly coupled to React DOM measurements internally. Our component inherits this dynamic behavior rather than statically rendering a permanent divider, matching Mantine's robust overflow UX. However, we aggressively override the generated `border-bottom` via CSS modules to ensure that when it _does_ appear, it correctly utilizes the `--recursica_ui-kit_components_modal_colors_scroll-divider` variable and `--recursica_ui-kit_components_modal_properties_scroll-divider-thickness` token.

package/src/components/NumberInput/USAGE.md

@@ -0,0 +1,55 @@
+# NumberInput - Usage Guide
+
+This document describes how to integrate and use the `NumberInput` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { NumberInput } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { NumberInput } from "@recursica/mantine-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/mantine-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
+
+## 1. Native Macro Wrapper Bypass
+
+**Decision:** The `<NumberInput>` component explicitly bypasses Mantine's native `Input.Wrapper` DOM injections.
+**Implementation:** We pass `label={undefined}`, `description={undefined}`, and `error={undefined}` directly into the primitive `<MantineNumberInput>`. All visual form control geometry is delegated exclusively to our unified `<FormControlWrapper>`, ensuring 100% token adherence for label spacing and assistive text styling without duplicate DOM rendering.
+
+## 2. Right Section & Controls Override
+
+**Decision:** Passing a `rightSection` element will natively remove the increment/decrement arrow controls.
+**Implementation:** Mantine inherently renders its stepper controls inside the `rightSection` DOM slot. Providing a custom right-aligned icon or text element intentionally overwrites this slot. If a layout strictly requires both a custom right-aligned element and the stepper controls simultaneously, the integrator must manually rebuild the arrows using Mantine's `handlersRef` within a custom right-section wrapper.
+
+## 3. Controls Styling
+
+**Decision:** The increment/decrement control arrows rely partially on native Mantine CSS inheritance.
+**Implementation:** The current Recursica design system tokens do not provide explicit UI styling parameters (`background`, `border`, `hover` states) for the inner number-input arrows. We have explicitly removed Mantine's default borders to cleanly nest them inside the unified input box, and mapped the icon colors to the generic `trailing-icon` token variable, but further visual configurations currently fall back to Mantine defaults.