@recursica/adapter-mantine-v8 1.0.0

package/src/components/ReadOnlyField/WithReadOnlyWrapper.tsx

@@ -0,0 +1,93 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import React, { forwardRef } from "react";
+import { type ReadOnlyFieldType } from "@recursica/adapter-common";
+import {
+  FormControlWrapper,
+  type FormControlWrapperProps,
+} from "../FormControlWrapper/FormControlWrapper";
+import { ReadOnlyField } from "./ReadOnlyField";
+
+export interface WithReadOnlyWrapperProps
+  extends Omit<FormControlWrapperProps, "children" | "overStyled"> {
+  /** Injects whether the field defaults to reading mode natively */
+  readOnly?: boolean;
+  /** Explicit React component directly overtaking the baseline text renderer when read-only mode is active */
+  readOnlyComponent?: React.ElementType<any>;
+  /** Custom renderer explicitly responsible for formatting missing/empty value mappings (overriding default 'N/A') */
+  emptyValueComponent?: React.ElementType<{ value?: any }>;
+  /** The full native props dictionary securely forwarded into the custom readOnlyComponent if active */
+  readOnlyNativeProps?: any;
+  /** Instructs the underlying generic ReadOnlyField which raw visual structure to bridge automatically */
+  readOnlyType?: ReadOnlyFieldType;
+  /** The isolated raw data value intercepted explicitly into the ReadOnly formatters */
+  readOnlyValue?: any;
+  /** Safely enables deep Mantine overrides transparently bypassing block filters */
+  overStyled?: boolean;
+  /** The nested active node dynamically exposed exclusively when read-only bounds are disabled */
+  activeComponent: React.ReactNode;
+}
+
+/**
+ * Universal execution barrier trapping readOnly states globally.
+ * Natively delegates active logic down avoiding duplicative internal component bindings dynamically.
+ */
+export const WithReadOnlyWrapper = forwardRef<
+  HTMLDivElement,
+  WithReadOnlyWrapperProps
+>(function WithReadOnlyWrapper(
+  {
+    readOnly,
+    readOnlyComponent,
+    readOnlyType = "text",
+    readOnlyValue,
+    readOnlyNativeProps,
+    emptyValueComponent,
+    activeComponent,
+    overStyled,
+    onLabelEditClick,
+    ...wrapperProps
+  },
+  ref,
+) {
+  if (readOnly) {
+    if (readOnlyComponent) {
+      const ReadOnlyComponent = readOnlyComponent;
+      return (
+        <FormControlWrapper
+          ref={ref}
+          {...wrapperProps}
+          onLabelEditClick={onLabelEditClick}
+          overStyled={overStyled as true}
+        >
+          <ReadOnlyComponent {...readOnlyNativeProps} />
+        </FormControlWrapper>
+      );
+    }
+
+    return (
+      <ReadOnlyField
+        ref={ref}
+        {...wrapperProps}
+        type={readOnlyType}
+        value={readOnlyValue}
+        emptyValueComponent={emptyValueComponent}
+        onLabelEditClick={onLabelEditClick}
+        overStyled={overStyled as true}
+      />
+    );
+  }
+
+  // Active Standard Execution natively forwarding bound children implicitly
+  return (
+    <FormControlWrapper
+      ref={ref}
+      {...wrapperProps}
+      onLabelEditClick={onLabelEditClick}
+      overStyled={overStyled as true}
+    >
+      {activeComponent}
+    </FormControlWrapper>
+  );
+});
+
+WithReadOnlyWrapper.displayName = "WithReadOnlyWrapper";

package/src/components/ReadOnlyField/index.ts

@@ -0,0 +1,5 @@
+export * from "./ReadOnlyField";
+export * from "./WithReadOnlyWrapper";
+export * from "./ReadOnlyTextField";
+export * from "./ReadOnlySwitchField";
+export * from "./ReadOnlyBooleanField";

package/src/components/RecursicaThemeProvider/USAGE.md

@@ -0,0 +1,60 @@
+# RecursicaThemeProvider - Usage Guide
+
+This document describes how to integrate and use `RecursicaThemeProvider` in your projects using `@recursica/adapter-mantine-v8`.
+
+> [!NOTE] > `RecursicaThemeProvider` is defined once in `@recursica/adapter-common` and re-exported here so it shares the exact same behavior across every Recursica adapter.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { RecursicaThemeProvider } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import { MantineProvider } from "@mantine/core";
+import { RecursicaThemeProvider } from "@recursica/adapter-mantine-v8";
+
+function App() {
+  return (
+    <MantineProvider>
+      <RecursicaThemeProvider theme="light">
+        {/* Your App Components */}
+      </RecursicaThemeProvider>
+    </MantineProvider>
+  );
+}
+```
+
+By default, `RecursicaThemeProvider` also wraps `children` in a base [`Layer`](../Layer/USAGE.md) (`layer={0}`), so surface/border/elevation variables resolve immediately — no separate `Layer` needed for the page background.
+
+If you want to place the base layer yourself (e.g. to use `contentsOnly`, or to control exactly where layer 0 starts in the tree), opt out with `initLayer0={false}`:
+
+```tsx
+import { RecursicaThemeProvider, Layer } from "@recursica/adapter-mantine-v8";
+
+<RecursicaThemeProvider theme="light" initLayer0={false}>
+  <Layer layer={0}>{/* Your App Components */}</Layer>
+</RecursicaThemeProvider>;
+```
+
+---
+
+## 3. Design System Integration
+
+> [!IMPORTANT]
+>
+> - **Required for setup**: `RecursicaThemeProvider` must wrap your entire application, once, near the root. See [SETUP.md](../../../SETUP.md) for the full setup sequence.
+> - **`initLayer0` (default `true`)**: Automatically wraps `children` in a layer-0 [`Layer`](../Layer/USAGE.md). `RecursicaThemeProvider` itself only sets `data-recursica-theme` (`"light"` or `"dark"`, defaults to `"light"`) on `document.documentElement` — without a `Layer` in the tree (either the automatic one or one you add yourself with `initLayer0={false}`), none of Recursica's surface CSS variables resolve.
+> - **Runtime theme switching**: Changing the `theme` prop re-runs the effect and updates `data-recursica-theme` immediately, so you can drive light/dark switching from application state.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+`RecursicaThemeProvider` also wires up the `overStyled` development-mode visual auditing helper (see [OVERSTYLING.md](../../../OVERSTYLING.md)) — `recursica.toggleOverStyled()` in the browser console only works once this provider has mounted.

package/src/components/SegmentedControl/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,25 @@
+# SegmentedControl Implementation Notes
+
+## 1. Stripping Mantine's Native Variants and Sizes
+
+The Figma design tokens for the SegmentedControl component do not define nested layers of variants (such as `solid`, `outline`) or specific sizing steps (`xs`, `sm`, etc.). They are defined globally. Therefore, we explicitly `Omit` the standard `variant`, `size`, `radius`, and `color` props from the generic Mantine `SegmentedControlProps` interface.
+
+## 2. Hardcoded Overrides for Figma Strictness
+
+Mantine injects inline hover styles on `.label` (specifically, adding a subtle gray background when hovering). Since Recursica defines explicit transparent or specifically-driven hover states, we use `!important` tags within `SegmentedControl.module.css` for background and typography overriding.
+
+## 3. Divider Separators
+
+Mantine uses an `::before` pseudo-element on the `.control` block to draw standard visual separators between adjacent elements. Instead of stripping this functionality out, we hook directly into the pseudo-element and override its `background-color` with `--recursica_ui-kit_components_segmented-control_properties_colors_divider-color`.
+
+## 4. Indicator Mapping
+
+The moving active background element (`.indicator`) is decoupled from the actual text label. It is styled natively with its own background color, border size, and elevation shadow variables to match the exact visual parity of a "floating active chip" as defined in the Recursica properties map.
+
+## 5. Per-item `icon`
+
+`RecursicaSegmentedControlProps.data` objects accept an optional `icon`. Mantine's own `data` item has no such slot, so this component `Omit`s Mantine's native `data` type and composes `icon`+`label` into a single `label` ReactNode before handing it to Mantine — Mantine's own `innerLabel` wrapper then lays it out using the icon-size/gap tokens already present in `SegmentedControl.module.css`.
+
+## 6. Whole-control `disabled`
+
+`RecursicaSegmentedControlProps.disabled` was previously typed `never` and stripped at runtime. It's now a real `boolean?`, passed straight through to Mantine's own native `disabled` — Mantine's `SegmentedControl` already disables every item when set. Per-item disabling via `data[].disabled` continues to work independently of it.

package/src/components/SegmentedControl/SegmentedControl.module.css

@@ -0,0 +1,185 @@
+/* HARDCODED VALUES:
+   - border-style: solid; on container and indicator
+   - background-color: transparent; on label hover (overriding Mantine)
+   - Scope prefix .root to enforce Figma tokens over Mantine's inline calculation without using !important
+*/
+
+/* EXEMPTIONS:
+   - The generic, non-state-specific segmented-control-item border-radius is ignored: the
+     selected/unselected state-specific border-radius tokens below already cover both states an
+     item can be in. */
+/* recursica-ignore: --recursica_ui-kit_components_segmented-control-item_properties_item_border-radius */
+
+.root {
+  background-color: var(
+    --recursica_ui-kit_components_segmented-control_properties_colors_background-color
+  );
+  border: var(
+      --recursica_ui-kit_components_segmented-control_properties_border-size
+    )
+    solid
+    var(
+      --recursica_ui-kit_components_segmented-control_properties_colors_border-color
+    );
+  border-radius: var(
+    --recursica_ui-kit_components_segmented-control_properties_border-radius
+  );
+  padding: var(
+      --recursica_ui-kit_components_segmented-control_properties_padding-vertical
+    )
+    var(
+      --recursica_ui-kit_components_segmented-control_properties_padding-horizontal
+    );
+  box-shadow: var(
+    --recursica_ui-kit_components_segmented-control_properties_elevation
+  );
+  gap: var(--recursica_ui-kit_components_segmented-control_properties_item-gap);
+}
+
+.root .label {
+  padding-left: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_item_padding-horizontal
+  );
+  padding-right: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_item_padding-horizontal
+  );
+  height: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_item_height
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_segmented-control-item_variants_selection-states_unselected_properties_border-radius
+  );
+
+  border: var(
+      --recursica_ui-kit_components_segmented-control-item_variants_selection-states_unselected_properties_border-size
+    )
+    solid
+    var(
+      --recursica_ui-kit_components_segmented-control-item_variants_selection-states_unselected_properties_colors_border-color
+    );
+  background-color: var(
+    --recursica_ui-kit_components_segmented-control-item_variants_selection-states_unselected_properties_colors_background-color
+  );
+  box-shadow: var(
+    --recursica_ui-kit_components_segmented-control-item_variants_selection-states_unselected_properties_elevation
+  );
+
+  font-family: var(
+    --recursica_ui-kit_components_segmented-control-item_variants_selection-states_unselected_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_segmented-control-item_variants_selection-states_unselected_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_segmented-control-item_variants_selection-states_unselected_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_segmented-control-item_variants_selection-states_unselected_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_segmented-control-item_variants_selection-states_unselected_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_segmented-control-item_variants_selection-states_unselected_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_segmented-control-item_variants_selection-states_unselected_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_segmented-control-item_variants_selection-states_unselected_properties_text_text-transform
+  );
+
+  color: var(
+    --recursica_ui-kit_components_segmented-control-item_variants_selection-states_unselected_properties_colors_text-color
+  );
+
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+/* Mantine natively wraps label contents in an innerLabel span */
+.root .label :global(.mantine-SegmentedControl-innerLabel) {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_item_icon-text-gap
+  );
+}
+
+.root .label svg {
+  width: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_item_icon-size
+  );
+  height: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_item_icon-size
+  );
+  flex-shrink: 0;
+}
+
+/* Mantine adds a background on hover, we must strictly strip it */
+.root .label:hover {
+  background-color: transparent;
+}
+
+/* Mantine adds separators via ::before on the .control */
+.root .control::before {
+  background-color: var(
+    --recursica_ui-kit_components_segmented-control_properties_colors_divider-color
+  );
+  width: var(
+    --recursica_ui-kit_components_segmented-control_properties_divider-size
+  );
+}
+
+/* Indicator (the moving selected block) */
+.root .indicator {
+  background-color: var(
+    --recursica_ui-kit_components_segmented-control-item_variants_selection-states_selected_properties_colors_background-color
+  );
+  border: var(
+      --recursica_ui-kit_components_segmented-control-item_variants_selection-states_selected_properties_border-size
+    )
+    solid
+    var(
+      --recursica_ui-kit_components_segmented-control-item_variants_selection-states_selected_properties_colors_border-color
+    );
+  box-shadow: var(
+    --recursica_ui-kit_components_segmented-control-item_variants_selection-states_selected_properties_elevation
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_segmented-control-item_variants_selection-states_selected_properties_border-radius
+  );
+}
+
+/* Selected label text color override */
+.root .control[data-active] .label {
+  color: var(
+    --recursica_ui-kit_components_segmented-control-item_variants_selection-states_selected_properties_colors_text-color
+  );
+  font-family: var(
+    --recursica_ui-kit_components_segmented-control-item_variants_selection-states_selected_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_segmented-control-item_variants_selection-states_selected_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_segmented-control-item_variants_selection-states_selected_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_segmented-control-item_variants_selection-states_selected_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_segmented-control-item_variants_selection-states_selected_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_segmented-control-item_variants_selection-states_selected_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_segmented-control-item_variants_selection-states_selected_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_segmented-control-item_variants_selection-states_selected_properties_text_text-transform
+  );
+}

package/src/components/SegmentedControl/SegmentedControl.stories.tsx

@@ -0,0 +1,106 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { SegmentedControl } from "./SegmentedControl";
+
+const meta: Meta<typeof SegmentedControl> = {
+  title: "UI-Kit/SegmentedControl",
+  component: SegmentedControl,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "SegmentedControl provides a linear set of two or more segments, each of which functions as a mutually exclusive button.",
+      },
+    },
+  },
+  argTypes: {
+    orientation: {
+      control: "radio",
+      options: ["horizontal", "vertical"],
+    },
+    fullWidth: {
+      control: "boolean",
+    },
+    disabled: {
+      control: "boolean",
+    },
+    data: { table: { disable: true } },
+    defaultChecked: { table: { disable: true } },
+  },
+} satisfies Meta<typeof SegmentedControl>;
+
+export default meta;
+type Story = StoryObj<typeof SegmentedControl>;
+
+export const Default: Story = {
+  args: {
+    data: ["React", "Angular", "Vue", "Svelte"],
+    orientation: "horizontal",
+    fullWidth: false,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: any) => {
+    return <SegmentedControl {...args} />;
+  },
+};
+
+export const FullWidth: Story = {
+  args: {
+    data: ["Daily", "Weekly", "Monthly"],
+    fullWidth: true,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: any) => {
+    return <SegmentedControl {...args} />;
+  },
+};
+
+export const Vertical: Story = {
+  args: {
+    data: ["Option 1", "Option 2", "Option 3"],
+    orientation: "vertical",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: any) => {
+    return <SegmentedControl {...args} />;
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    data: ["Preview", "Code", "Edit"],
+    disabled: true,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: any) => {
+    return <SegmentedControl {...args} />;
+  },
+};
+
+const CheckIcon = () => (
+  <svg
+    viewBox="0 0 24 24"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+  >
+    <polyline points="20 6 9 17 4 12" />
+  </svg>
+);
+
+export const WithIcons: Story = {
+  args: {
+    data: [
+      { value: "daily", label: "Daily", icon: <CheckIcon /> },
+      { value: "weekly", label: "Weekly", icon: <CheckIcon /> },
+      { value: "monthly", label: "Monthly", icon: <CheckIcon /> },
+    ],
+  },
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: any) => {
+    return <SegmentedControl {...args} />;
+  },
+};

package/src/components/SegmentedControl/SegmentedControl.test.tsx

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

package/src/components/SegmentedControl/SegmentedControl.tsx

@@ -0,0 +1,110 @@
+import { forwardRef } from "react";
+import {
+  SegmentedControl as MantineSegmentedControl,
+  type SegmentedControlProps as MantineSegmentedControlProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./SegmentedControl.module.css";
+
+import { type RecursicaSegmentedControlProps } from "@recursica/adapter-common";
+
+export type SegmentedControlProps = RecursicaOverStyled<
+  Omit<
+    MantineSegmentedControlProps,
+    | "variant"
+    | "size"
+    | "radius"
+    | "color"
+    | "classNames"
+    | "className"
+    | "data"
+  > & {
+    className?: string;
+    classNames?: Partial<Record<string, string>>;
+  } & RecursicaSegmentedControlProps
+>;
+
+function useSegmentedControlClassNames(restRecord: Record<string, unknown>): {
+  className: string;
+  classNames: Partial<Record<string, string>>;
+} {
+  const mergedClassNames = mergeClassNames(
+    {
+      root: styles.root,
+      control: styles.control,
+      label: styles.label,
+      indicator: styles.indicator,
+    },
+    restRecord.classNames as Partial<Record<string, string>> | undefined,
+  );
+
+  const classNameProp = restRecord.className as string | undefined;
+  const finalClass = classNameProp
+    ? `${styles.root} ${classNameProp}`
+    : styles.root;
+
+  return { className: finalClass, classNames: mergedClassNames };
+}
+
+const _SegmentedControl = forwardRef<HTMLDivElement, SegmentedControlProps>(
+  function SegmentedControl(
+    {
+      overStyled = false,
+      orientation = "horizontal",
+      fullWidth,
+      data = [],
+      ...rest
+    },
+    ref,
+  ) {
+    const sanitizedProps = filterStylingProps(rest, overStyled) as Partial<
+      typeof rest
+    >;
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    const stylingParams = useSegmentedControlClassNames(restRecord);
+
+    // Mantine's own data item has no icon slot; compose one into `label` (already a ReactNode)
+    // so Mantine's native innerLabel wrapper lays it out using the icon-size/gap tokens already
+    // wired in SegmentedControl.module.css.
+    const mappedData = data.map((item) =>
+      typeof item === "string" || !item.icon
+        ? item
+        : {
+            ...item,
+            label: (
+              <>
+                {item.icon}
+                {item.label}
+              </>
+            ),
+          },
+    );
+
+    return (
+      <MantineSegmentedControl
+        ref={ref}
+        {...(sanitizedProps as Omit<
+          MantineSegmentedControlProps,
+          "variant" | "size"
+        >)}
+        className={stylingParams.className}
+        classNames={stylingParams.classNames}
+        orientation={orientation}
+        fullWidth={fullWidth}
+        data-orientation={orientation}
+        data={mappedData}
+      />
+    );
+  },
+);
+_SegmentedControl.displayName = "SegmentedControl";
+
+/**
+ * Recursica SegmentedControl component wrapping Mantine's SegmentedControl.
+ */
+export const SegmentedControl = _SegmentedControl;

package/src/components/SegmentedControl/USAGE.md

@@ -0,0 +1,55 @@
+# SegmentedControl - Usage Guide
+
+This document describes how to integrate and use the `SegmentedControl` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { SegmentedControl } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { SegmentedControl } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return <SegmentedControl data={["Preview", "Code", "Edit"]} />;
+}
+```
+
+Each `data` item may also be an object with an optional `icon`, rendered ahead of the label:
+
+```tsx
+<SegmentedControl
+  data={[
+    { value: "daily", label: "Daily", icon: <CheckIcon /> },
+    { value: "weekly", label: "Weekly" },
+  ]}
+/>
+```
+
+---
+
+## 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 `variant`, `size`, `radius`, and `color` props are not available on this component, since appearance is fully controlled by the design system tokens. The active segment is shown as a floating indicator that moves behind the selected label, with a divider rendered between adjacent segments.
+
+A top-level `disabled` disables every item at once; an individual item can still be disabled on its own via `data[].disabled`.