@recursica/mantine-adapter 0.32.0 → 0.33.0

package/src/components/TextArea/USAGE.md

@@ -0,0 +1,48 @@
+# TextArea - Usage Guide
+
+This document describes how to integrate and use the `TextArea` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { TextArea } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { TextArea } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return (
+    <TextArea label="Comments" placeholder="Leave your comments here..." />
+  );
+}
+```
+
+---
+
+## 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
+
+The `TextArea` component is mapped explicitly to Mantine's `<Textarea>` following the same strict encapsulation rules as `TextField`.
+
+1. **Naked Primitive Mapping:** Mantine's `Textarea` natively executes macro-label generation. To decouple it, we explicitly disable internal labels (`label={undefined}`) and inject it purely inside our generic `FormControlWrapper`.
+2. **Text Field Token Re-Use:** Because text areas fundamentally share the same box-geometry, text, and state definitions as single-line inputs, it strictly implements the `--recursica_ui-kit_components_text-field_...` variables natively.
+3. **Autosize Handling:** The component supports Mantine's raw `autosize`, `minRows`, and `maxRows` parameters out of the box dynamically via property passthrough.

package/src/components/TextField/USAGE.md

@@ -0,0 +1,60 @@
+# TextField - Usage Guide
+
+This document describes how to integrate and use the `TextField` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { TextField } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { TextField } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return (
+    <TextField label="Username" placeholder="Enter your username" required />
+  );
+}
+```
+
+---
+
+## 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
+
+## Architectural philosophy
+
+The `TextField` primitive intentionally ignores Mantine's built-in `<TextInput>` structure in favor of directly binding against `<Input>`.
+
+### 1. Bypassing `Input.Wrapper`
+
+Because `<TextInput>` inherently renders Mantine's `Input.Wrapper` underneath the hood, utilizing it natively double-wraps our layouts causing massive DOM bloat and margin collapsing errors. By leveraging the completely naked `<Input>` primitive natively natively alongside `FormControlWrapper`, we retain full logical control of where the `label` maps, avoiding dual label conflicts or mis-aligned asterisks securely.
+
+### 2. State Hooks (`wrapperProps`)
+
+Because we target `<Input>`, all dynamic UI modifiers (`disabled`, `error`, etc) must strictly be applied to the `.root` CSS module to correctly style the internal `<input>` boxes AND the nested `.[data-position]` icon sections simultaneously.
+
+To accomplish this safely without spilling random pseudo-variables onto the input parameters, we exclusively use Mantine's `<Input wrapperProps={{...}}>` block natively locking `.root[data-error]` to correctly map Recursica UI variable hooks without breaking the DOM hierarchy natively.
+
+### 3. Component Definition Intersections
+
+To strictly acquire native HTML typings, `TextField.tsx` explicitly extracts `React.ComponentPropsWithoutRef<"input">`. However, to prevent Typescript strict union collisions with overlapping Mantine definitions over functional `style` components and custom mappings natively, we meticulously omit (`Pick<InputWrapperProps, ...>`) explicit base elements to guarantee that strictly Recursica styles traverse the array flawlessly.

package/src/components/TimePicker/USAGE.md

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

package/src/components/Timeline/USAGE.md

@@ -0,0 +1,57 @@
+# Timeline - Usage Guide
+
+This document describes how to integrate and use the `Timeline` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Timeline } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Timeline } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return (
+    <Timeline active={1}>
+      <Timeline.Item title="Step 1">Created branch</Timeline.Item>
+      <Timeline.Item title="Step 2">Pushed changes</Timeline.Item>
+    </Timeline>
+  );
+}
+```
+
+---
+
+## 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 `Timeline` component is a strict structural wrapper around Mantine's `<Timeline>` and `<Timeline.Item>` components.
+
+- `Timeline.tsx` intercepts overarching properties like `lineWidth` and `bulletSize` to strip them out via `overStyled`, strictly adhering to the CSS token mapping in `.item` rules instead.
+- `TimelineItem.tsx` implements a custom `timestamp` React node rendering slot to match the design system, positioning the text directly below the item's `children`.
+- `TimelineItem.tsx` supports a custom `bulletVariant` prop (`"default" | "avatar" | "icon" | "icon-alternative"`) mapped onto `data-variant` to handle CSS variations dynamically.
+
+## Limitations & Missing Tokens
+
+- **Avatar Bullet Size**: There is no specific pixel variable provided for the Avatar bullet size in the UI kit tokens (`avatar-size` evaluates to `"default"`). To maintain exact mathematical centering with Mantine's connector line `calc()` equations, the CSS falls back to inheriting the `default` bullet size (`20px`) for avatar nodes natively. If users supply a custom sized `img` tag, it must adhere to inline structural constraints or flex mappings.

package/src/components/Title/USAGE.md

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

package/src/components/Toast/USAGE.md

@@ -0,0 +1,80 @@
+# Toast - Usage Guide
+
+This document describes how to integrate and use the `Toast` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Toast } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Toast } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return (
+    <Toast
+      title="Success"
+      message="Your action completed successfully"
+      state="success"
+    />
+  );
+}
+```
+
+---
+
+## 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. Standalone Visual Wrapper
+
+**Decision:** We wrap `@mantine/core`'s standalone `Notification` component instead of wrapping the `@mantine/notifications` provider.
+
+**Implementation:** The UI Kit provides variables for the `Toast` component itself (e.g., `--recursica_ui-kit_components_toast_*`). We use these variables to style the standard Mantine `Notification` element. This allows developers to use `<Toast>` manually if they want a static or inline message.
+
+If dynamic popups are required, developers can configure `@mantine/notifications` to utilize this component or use its classes.
+
+---
+
+## 2. Variant Mapping via `data-variant`
+
+**Decision:** `variant` props (`"default" | "error" | "success"`) are mapped directly to `data-variant` on the Mantine root `Box`.
+
+**Implementation:** Mantine's `Notification` doesn't inherently support our custom variants out of the box in the way we want them styled. By passing `data-variant` directly to the `Box`, we can explicitly target the root element in our `Toast.module.css` (e.g., `.root[data-variant="success"]`) and pipe in the corresponding UI Kit layer colors.
+
+---
+
+## 3. Minimal CSS Override Philosophy
+
+**Decision:** The CSS module only overrides visual design tokens (colors, typography, padding, borders, shadows).
+
+**Implementation:** We defer layout structure, icon rendering, loader transitions, and close button mechanics to Mantine. The `border-style: none;` is hardcoded to reset any underlying styles from Mantine's defaults, ensuring a clean mapping of elevation and shadows.
+
+---
+
+## 4. Unsupported `loading` State
+
+**Decision:** The native `loading` state is explicitly stripped and bypassed from the `<Toast />` component wrapper.
+
+**Implementation:** Mantine's `Notification` inherently supports a `loading={true}` state that natively spins up a loader instead of an icon. However, Recursica's UI Kit strictly does not define structural tokens for loader states inside toasts.
+Instead of attempting to tightly couple the internal `Loader` abstraction or mapping variables incorrectly, the `loading` property is explicitly omitted and `false`-enforced from the public API.
+If consumers explicitly require a loading toast, they must manually inject a `<Loader />` component into the `icon` slot.

package/src/components/Tooltip/USAGE.md

@@ -0,0 +1,124 @@
+# Tooltip - Usage Guide
+
+This document describes how to integrate and use the `Tooltip` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Tooltip } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Tooltip } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return (
+    <Tooltip label="This is a helpful tooltip">
+      <Button variant="primary">Hover Me</Button>
+    </Tooltip>
+  );
+}
+```
+
+---
+
+## 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. Single Component API (Not Composable)
+
+**Decision:** Unlike HoverCard (which uses `HoverCard` + `HoverCard.Target` + `HoverCard.Dropdown`), Tooltip is a single wrapper component.
+
+**Implementation:** Mantine's `Tooltip` takes content via a `label` prop and wraps the trigger element as `children`. There are no separate Target/Dropdown sub-components. The Recursica wrapper preserves this exact API.
+
+**Static sub-components:** `Tooltip.Floating` and `Tooltip.Group` are exposed as pass-through references to Mantine's implementations. These do not receive Recursica styling treatment — they are utility wrappers for cursor-following tooltips and shared delay grouping respectively.
+
+---
+
+## 2. Token Namespace: `tooltip`
+
+**Decision:** The CSS module exclusively uses variables from the `--recursica_ui-kit_components_tooltip_*` namespace.
+
+**Implementation:** The Recursica token system defines the `tooltip` namespace covering:
+
+- Geometry: border-radius, border-size, min-width, min-height, max-width, padding
+- Typography: text_font-\* (family, size, style, weight, letter-spacing, line-height, text-decoration, text-transform)
+- Colors (layer-aware): background, border-color, text
+- Elevation: box-shadow
+- Beak: beak-size (16px), beak-inset (8px)
+
+No tokens from other component namespaces are referenced.
+
+---
+
+## 3. Hardcoded Values
+
+### `border-style: solid` (CSS module)
+
+Mantine renders the tooltip using its `Box` component, which does not set `border-style` natively. Without this hardcoded value, the border-width and border-color tokens would have no visible effect. Same pattern as Menu and HoverCard dropdowns.
+
+### `arrowSize` defaulted to `16` (Tooltip.tsx)
+
+Mantine's `arrowSize` prop is a JavaScript number used for inline style calculations: it sets `width`, `height`, and a positioning offset (`-arrowSize/2`) directly on the arrow `<div>` element. These inline styles cannot be overridden via CSS without `!important`, and the positioning offset has no CSS equivalent. The beak size cannot be fully CSS-driven.
+
+The default value `16` matches the Recursica `beak-size` token (`--recursica_ui-kit_components_tooltip_properties_beak-size: 16px`). Developers can override `arrowSize` if needed. This is documented as an open issue in `docs/COMPONENT_ISSUES.md`.
+
+**Note:** Mantine calls this the "arrow"; Recursica calls it the "beak". The Recursica prop `withBeak` (defaulting to `true`) maps to Mantine's `withArrow`. Both are accepted; `withBeak` takes precedence.
+
+### `multiline={true}` (Tooltip.tsx)
+
+Mantine's `multiline` prop controls whether tooltip text wraps (`white-space: nowrap` when false). Recursica always enables multiline because the design system defines a `max-width` token (300px) — text should wrap naturally within that constraint rather than overflowing. The `multiline` prop is not exposed to developers.
+
+### Flexbox centering (CSS module)
+
+`display: flex; align-items: center; justify-content: center;` is applied to the `.tooltip` class. This ensures text is vertically and horizontally centered within the `min-height: 48px` container defined by the design token. Without this, text sits at the top of the tooltip.
+
+---
+
+## 4. Recursica `withBeak` Prop
+
+**Decision:** `withBeak` is the official Recursica prop for controlling beak visibility, defaulting to `true`.
+
+**Implementation:** Both `withBeak` and Mantine's `withArrow` are accepted. Resolution order: `withBeak ?? withArrow`. When both are provided, `withBeak` takes precedence. The default of `true` means tooltips show the beak by default, matching the Recursica design intent.
+
+---
+
+## 5. ClassNames Binding
+
+**Decision:** CSS module classes are bound via the `classNames` prop on Mantine's Tooltip root.
+
+**Implementation:** The stylesNames for Tooltip are `tooltip` (the container) and `arrow` (the beak). Both are mapped to their respective CSS module classes: `{ tooltip: styles.tooltip, arrow: styles.arrow }`. Consumer-provided `classNames` are merged additively when `overStyled` is true.
+
+---
+
+## 6. Tooltip.Floating and Tooltip.Group
+
+**Decision:** These static sub-components are direct pass-throughs to Mantine with no Recursica styling.
+
+**Implementation:** `Tooltip.Floating` follows the cursor and uses a different rendering mechanism than standard Tooltip. `Tooltip.Group` is a utility for shared delay timing. Neither has Recursica design tokens defined, so they remain unstyled pass-throughs. If tokens are added in the future, they can be wrapped independently.
+
+---
+
+## 7. Default Position Override
+
+**Decision:** Recursica defaults `position` to `"top"`. Mantine defaults to `"bottom"`.
+
+**Implementation:** The `position="top"` default is set on the Mantine root element before the prop spread, so developer-provided `position` values still take precedence. This aligns with Recursica's design intent for overlay components to appear above their trigger by default.

package/src/components/TransferList/USAGE.md

@@ -0,0 +1,46 @@
+# TransferList - Usage Guide
+
+This document describes how to integrate and use the `TransferList` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { TransferList } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { TransferList } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return (
+    <TransferList
+      data={[
+        [
+          { value: "1", label: "Item 1" },
+          { value: "2", label: "Item 2" },
+        ],
+        [{ value: "3", label: "Item 3" }],
+      ]}
+    />
+  );
+}
+```
+
+---
+
+## 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.

package/src/components/Tree/USAGE.md

@@ -0,0 +1,46 @@
+# Tree - Usage Guide
+
+This document describes how to integrate and use the `Tree` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Tree } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Tree } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return (
+    <Tree
+      data={[
+        {
+          value: "1",
+          label: "Root",
+          children: [{ value: "2", label: "Child" }],
+        },
+      ]}
+    />
+  );
+}
+```
+
+---
+
+## 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.