@recursica/adapter-mantine-v8 1.0.0

package/src/components/Slider/USAGE.md

@@ -0,0 +1,56 @@
+# Slider - Usage Guide
+
+This document describes how to integrate and use the `Slider` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Slider } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Slider } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return <Slider defaultValue={50} min={0} max={100} label="Volume" />;
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mantine-v8` 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 `label` prop is passed through to the surrounding form label rather than Mantine's dragging tooltip; use `tooltipLabel` to set the label shown while dragging. When `showInput` is enabled, a numeric text input is rendered alongside the track and stays in sync with the slider's value. Set `showMinMaxLabels` to `false` to hide the min/max guides shown at either end of the track. Otherwise, the current value is displayed near the track instead — pass `tooltipLabel` as a formatter function (`(value) => ReactNode`) and that same formatter is reused for this display, instead of always showing the raw number. `minLabel`/`maxLabel` override the text shown at either end of the track (defaults to the numeric `min`/`max`). `icon` renders a leading icon next to the track; `trailingIcon` renders one on the opposite side, rendered right after the max label and before the numeric input.
+
+### Range Mode
+
+Pass a `[number, number]` tuple as `value`/`defaultValue` to render a two-thumb range slider — `onChange`/`onChangeEnd` are then called with a `[number, number]` tuple instead of a `number`. This is a real component swap under the hood (Mantine's `RangeSlider`, not `Slider`), so `value` and `defaultValue` must agree on shape for a given instance. With `showInput` enabled, a second numeric input for the upper bound appears after the trailing icon, with the lower-bound input before the leading icon:
+
+```tsx
+<Slider
+  label="Price Range"
+  defaultValue={[20, 80]}
+  min={0}
+  max={100}
+  onChange={(value) => console.log(value)} // [number, number]
+/>
+```

package/src/components/Stack/STACK_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,4 @@
+# Stack Implementation Notes
+
+The `Stack` component is a generic flex layout wrapper mapped directly to Mantine's `Stack`.
+It currently does not require any custom logical layouts or CSS workarounds since it serves only to organize layout structure, and doesn't enforce any strict design-system token styling itself. All gap, align, and justify properties pass safely through via the `filterStylingProps` layout-property allowance.

package/src/components/Stack/Stack.module.css

@@ -0,0 +1,7 @@
+/* HARDCODED VALUES:
+ * None. This is a generic flex layout wrapper.
+ */
+
+.root {
+  /* Mantine handles flex, gap, align, justify. No intrinsic design-system styles required for pure layout wrappers. */
+}

package/src/components/Stack/Stack.stories.tsx

@@ -0,0 +1,108 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Stack } from "./Stack";
+import { Button } from "../Button";
+import { Text } from "../Text/Text";
+
+type StackStoryProps = React.ComponentProps<typeof Stack>;
+
+const meta: Meta<StackStoryProps> = {
+  title: "UI-Kit/Stack",
+  component: Stack,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Stack is a flex vertical layout container that maps directly to Mantine's Stack component allowing safe layout property passing.",
+      },
+    },
+  },
+  args: {
+    gap: "rec-default",
+    align: "stretch",
+    justify: "flex-start",
+  },
+  argTypes: {
+    gap: {
+      control: "select",
+      options: [
+        "rec-none",
+        "rec-sm",
+        "rec-default",
+        "rec-md",
+        "rec-lg",
+        "rec-xl",
+        "rec-2xl",
+        "xs",
+        "sm",
+        "md",
+        "lg",
+        "xl",
+      ],
+      description: "Gap between elements",
+    },
+    align: {
+      control: "select",
+      options: ["flex-start", "center", "flex-end", "stretch"],
+      description: "Align-items property",
+    },
+    justify: {
+      control: "select",
+      options: [
+        "flex-start",
+        "center",
+        "flex-end",
+        "space-between",
+        "space-around",
+      ],
+      description: "Justify-content property",
+    },
+    defaultChecked: {
+      table: { disable: true },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<StackStoryProps>;
+
+export const Default: Story = {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Stack {...args}>
+      <Button variant="solid">Primary Block</Button>
+      <Button variant="outline">Secondary Block</Button>
+      <Text>Text element within Stack</Text>
+    </Stack>
+  ),
+};
+
+export const StaticGapSmall: Story = {
+  args: {
+    gap: "rec-sm",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Stack {...args}>
+      <Button variant="solid">Item 1</Button>
+      <Button variant="solid">Item 2</Button>
+      <Button variant="solid">Item 3</Button>
+    </Stack>
+  ),
+};
+
+export const StaticGapLarge: Story = {
+  args: {
+    gap: "rec-xl",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Stack {...args}>
+      <Button variant="solid">Item 1</Button>
+      <Button variant="solid">Item 2</Button>
+      <Button variant="solid">Item 3</Button>
+    </Stack>
+  ),
+};

package/src/components/Stack/Stack.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Stack component tests. Add tests here if/when needed.

package/src/components/Stack/Stack.tsx

@@ -0,0 +1,62 @@
+import { forwardRef } from "react";
+import {
+  Stack as MantineStack,
+  type StackProps as MantineStackProps,
+  createPolymorphicComponent,
+} from "@mantine/core";
+import {
+  mapLayoutProps,
+  type WithRecursicaSpacing,
+} from "../../utils/filterStylingProps";
+import styles from "./Stack.module.css";
+
+/**
+ * Stack flex layout wrapper.
+ *
+ * Note: Unlike complex UI components, primitive layout components (Flex, Stack, Group, Container)
+ * DO NOT use the `RecursicaOverStyled` gatekeeper. Developers must be able to freely pass
+ * width, height, padding, margins, and flexbox alignment props to construct structural layouts.
+ *
+ * No formal Recursica prop contract here: this simply passes through Mantine's own
+ * `StackProps` (gap/align/justify are all native to Mantine), layered only with rec-
+ * spacing token support via `WithRecursicaSpacing`.
+ */
+export type StackProps = WithRecursicaSpacing<MantineStackProps>;
+
+const _Stack = forwardRef<HTMLDivElement, StackProps>(function Stack(
+  { children, gap = "rec-default", ...rest },
+  ref,
+) {
+  const mergedClassNames: Partial<Record<string, string>> = {
+    root: styles.root,
+  };
+
+  const classNamesProp = rest.classNames;
+  if (
+    classNamesProp &&
+    typeof classNamesProp === "object" &&
+    !Array.isArray(classNamesProp)
+  ) {
+    const o = classNamesProp as Partial<Record<string, string>>;
+    mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
+  }
+
+  const classNameProp = rest.className as string | undefined;
+  const finalClass = classNameProp
+    ? `${styles.root} ${classNameProp}`
+    : styles.root;
+
+  return (
+    <MantineStack
+      ref={ref}
+      className={finalClass}
+      classNames={mergedClassNames}
+      {...mapLayoutProps({ gap, ...rest } as Record<string, unknown>)}
+    >
+      {children}
+    </MantineStack>
+  );
+});
+_Stack.displayName = "Stack";
+
+export const Stack = createPolymorphicComponent<"div", StackProps>(_Stack);

package/src/components/Stack/USAGE.md

@@ -0,0 +1,48 @@
+# Stack - Usage Guide
+
+This document describes how to integrate and use the `Stack` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Stack } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Stack } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return (
+    <Stack gap="md" align="stretch">
+      <Text>Item 1</Text>
+      <Text>Item 2</Text>
+    </Stack>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mantine-v8` 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 `Stack` component is a generic flex layout wrapper mapped directly to Mantine's `Stack`.
+`gap`, `align`, and `justify` all pass through as normal.

package/src/components/Stepper/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,28 @@
+# Stepper Implementation Notes
+
+## Completed/current label & description colors never applied (source-of-truth audit, 2026-08-30)
+
+**Bug:** `.step[data-progress="completed"]`, `.step[data-progress="progress"]`, and
+`.step[data-progress="pending"]` selectors in `Stepper.module.css` checked `data-progress` for
+literal string values (`"completed"`/`"progress"`/`"pending"`) that Mantine's `Stepper.Step` never
+sets. Mantine actually stamps two independent boolean-presence attributes on the step root:
+`data-completed` (present, value `"true"`, when the step index is before `active`) and
+`data-progress` (present, value `"true"`, only on the active step); neither attribute exists at
+all on upcoming steps. Since `[data-progress="completed"]` and `[data-progress="pending"]` never
+match anything real, every step's label and description silently fell through to Mantine's own
+unstyled defaults instead of any Recursica token — for description text specifically, that meant
+Mantine's native muted/dimmed gray (`rgb(134, 142, 150)`, not any `--recursica_*` variable)
+appeared on _every_ step regardless of state, including completed/current steps where the design
+tokens (`..._completed-description-color`/`..._current-description-color`) both resolve to the
+same near-black `layer-0_elements_text_color` as the label. This was visually indistinguishable
+for labels (Mantine's own default text color happens to look close to black too) but clearly
+visible for descriptions, and was mistaken for a mui-adapter bug (mui's class-based `.Mui-active`/
+`.Mui-completed` selectors were already correctly reading these tokens, so mui rendered
+completed/current descriptions in the token's actual dark color while mantine — the presumed
+source of truth — rendered them in this incidental gray).
+
+**Fix:** Match the same working pattern already used one selector up for `.stepIcon` (`.stepIcon
+[data-completed]` / `.stepIcon[data-progress]`, which check attribute _presence_, not a value) —
+changed the `.step` label/description rules to `[data-completed]` / `[data-progress]` /
+`:not([data-completed]):not([data-progress])`. No `mui-adapter` change was needed for this: its
+class-based state selectors were already correct against the design tokens.