feat: forward additional mapping method parameters

docs/docs/configuration/additional-mapping-parameters.mdx

@@ -14,7 +14,7 @@ An additional mapping parameter has lower priority than a `MapProperty` mapping,
 but higher than a by-name matched regular member mapping.
 
 <Tabs>
-  <TabItem default label="Declaration" value="declaration">
+  <TabItem value="declaration" label="Declaration" default>
     ```csharp
     [Mapper]
     public partial class CarMapper
@@ -39,7 +39,7 @@ but higher than a by-name matched regular member mapping.
     ```
 
   </TabItem>
-  <TabItem default label="Generated code" value="generated">
+  <TabItem value="generated" label="Generated code">
     ```csharp
     [Mapper]
     public partial class CarMapper
@@ -55,7 +55,141 @@ but higher than a by-name matched regular member mapping.
         target.Name = name;
         // highlight-end
         return target;
-      } 
+      }
+    }
+    ```
+  </TabItem>
+</Tabs>
+
+## Forwarding parameters to nested mappings
+
+Additional parameters can be forwarded to user-defined nested mapping methods.
+When Mapperly resolves a nested type mapping (e.g., `A.Nested → B.Nested`),
+it will prefer a user-defined mapping method whose additional parameters can be satisfied
+from the parent mapping's additional parameters, matched by name.
+
+Mapperly will **not** auto-generate mapping methods with additional parameters.
+Only explicitly declared user-defined methods are considered.
+
+<Tabs>
+  <TabItem value="nested-declaration" label="Declaration" default>
+    ```csharp
+    [Mapper]
+    public partial class OrderMapper
+    {
+      public partial OrderDto Map(Order source, int currentUserId);
+      // highlight-start
+      // Mapperly will call MapItem with the currentUserId parameter forwarded
+      private partial OrderItemDto MapItem(OrderItem source, int currentUserId);
+      // highlight-end
+    }
+    ```
+  </TabItem>
+  <TabItem value="nested-generated" label="Generated code">
+    ```csharp
+    [Mapper]
+    public partial class OrderMapper
+    {
+      public partial OrderDto Map(Order source, int currentUserId)
+      {
+        var target = new OrderDto();
+        // highlight-start
+        target.Item = MapItem(source.Item, currentUserId);
+        // highlight-end
+        return target;
+      }
+    }
+    ```
+  </TabItem>
+</Tabs>
+
+## Forwarding parameters to Use methods
+
+Additional parameters can be passed to methods referenced by `MapValue(Use = ...)`.
+The method's parameters are matched by name from the mapping's additional parameters.
+
+<Tabs>
+  <TabItem value="use-declaration" label="Declaration" default>
+    ```csharp
+    [Mapper]
+    public partial class OrderMapper
+    {
+      // highlight-start
+      [MapValue(nameof(OrderDto.Total), Use = nameof(ComputeTotal))]
+      // highlight-end
+      public partial OrderDto Map(Order source, decimal taxRate);
+
+      // highlight-start
+      private decimal ComputeTotal(decimal taxRate) => 100m * (1 + taxRate);
+      // highlight-end
+    }
+    ```
+
+  </TabItem>
+  <TabItem value="use-generated" label="Generated code">
+    ```csharp
+    [Mapper]
+    public partial class OrderMapper
+    {
+      public partial OrderDto Map(Order source, decimal taxRate)
+      {
+        var target = new OrderDto();
+        // highlight-start
+        target.Total = ComputeTotal(taxRate);
+        // highlight-end
+        return target;
+      }
+    }
+    ```
+  </TabItem>
+</Tabs>
+
+Additional parameters can also be forwarded to methods referenced by `MapProperty(Use = ...)`.
+The first parameter of the `Use` method receives the source member value;
+the remaining parameters are matched by name from the mapping's additional parameters.
+This works with both mapper-internal methods and [external mapper](./external-mappings.mdx) methods.
+See also [user-implemented property mappings](./mapper.mdx#user-implemented-property-mappings).
+
+## Additional parameters in queryable projections
+
+Additional parameters work in queryable projections.
+The parameters become captured variables in the generated projection lambda.
+User-implemented methods with additional parameters are inlined following the same rules
+as regular [user-implemented mapping methods in projections](./queryable-projections.mdx#user-implemented-mapping-methods).
+
+<Tabs>
+  <TabItem value="projection-declaration" label="Declaration" default>
+    ```csharp
+    [Mapper]
+    public static partial class OrderMapper
+    {
+      public static partial IQueryable<OrderDto> ProjectToDto(
+        this IQueryable<Order> q,
+        // highlight-next-line
+        int currentUserId
+      );
+    }
+    ```
+  </TabItem>
+  <TabItem value="projection-generated" label="Generated code">
+    ```csharp
+    [Mapper]
+    public static partial class OrderMapper
+    {
+      public static partial IQueryable<OrderDto> ProjectToDto(
+        this IQueryable<Order> q,
+        // highlight-next-line
+        int currentUserId
+      )
+      {
+        return q.Select(x => new OrderDto()
+        {
+          // ...
+          // highlight-start
+          CurrentUserId = currentUserId,  // captured from outer scope
+          // highlight-end
+        });
+      }
     }
     ```
   </TabItem>
@@ -64,10 +198,10 @@ but higher than a by-name matched regular member mapping.
 :::info
 Mappings with additional parameters do have some limitations:
 
-- The additional parameters are not passed to nested mappings.
+- Additional parameters are forwarded to user-defined nested mapping methods only (not auto-generated ones).
 - A mapping with additional mapping parameters cannot be the default mapping
   (it is not used by Mapperly when encountering a nested mapping for the given types),
-  see also [default mapping methods](./user-implemented-methods.mdx##default-mapping-methods).
+  see also [default mapping methods](./user-implemented-methods.mdx#default-mapping-methods).
 - Generic and runtime target type mappings do not support additional type parameters.
 - Derived type mappings do not support additional type parameters.
   :::

docs/docs/configuration/analyzer-diagnostics/RMG097.mdx

@@ -0,0 +1,46 @@
+---
+sidebar_label: RMG097
+description: 'Mapperly analyzer diagnostic RMG097 — MapValue Use method parameters cannot be satisfied'
+---
+
+# RMG097 — MapValue Use method parameters cannot be satisfied
+
+A method referenced by `MapValue(Use = ...)` has parameters that cannot be matched
+from the mapping method's [additional parameters](../additional-mapping-parameters.mdx).
+
+To fix this, ensure the mapping method declares additional parameters with names matching
+the parameters of the `Use` method.
+
+## Example
+
+`GetValue` requires an `int ctx` parameter,
+but the `Map` method does not declare a matching additional parameter.
+
+```csharp
+[Mapper]
+public partial class MyMapper
+{
+    // highlight-start
+    // Error: GetValue requires 'ctx' but Map has no additional parameters
+    [MapValue(nameof(B.Value), Use = nameof(GetValue))]
+    // highlight-end
+    public partial B Map(A source);
+
+    private int GetValue(int ctx) => ctx * 2;
+}
+```
+
+Add the missing parameter to the mapping method:
+
+```csharp
+[Mapper]
+public partial class MyMapper
+{
+    [MapValue(nameof(B.Value), Use = nameof(GetValue))]
+    // highlight-start
+    public partial B Map(A source, int ctx);
+    // highlight-end
+
+    private int GetValue(int ctx) => ctx * 2;
+}
+```

docs/docs/configuration/analyzer-diagnostics/RMG098.mdx

@@ -0,0 +1,49 @@
+---
+sidebar_label: RMG098
+description: 'Mapperly analyzer diagnostic RMG098 — Named mapping additional parameters cannot be satisfied'
+---
+
+# RMG098 — Named mapping additional parameters cannot be satisfied
+
+A named mapping referenced by `MapProperty(Use = ...)` or `MapPropertyFromSource(Use = ...)`
+has [additional parameters](../additional-mapping-parameters.mdx) that cannot be matched
+from the caller's additional parameters.
+
+To fix this, ensure the calling mapping method declares additional parameters with names matching
+the parameters of the referenced named mapping.
+
+## Example
+
+`Transform` requires an `int multiplier` parameter,
+but the `Map` method does not declare a matching additional parameter.
+
+```csharp
+[Mapper]
+public partial class MyMapper
+{
+    // highlight-start
+    // Error: Transform requires 'multiplier' but Map has no additional parameters
+    [MapProperty(nameof(A.Value), nameof(B.Result), Use = nameof(Transform))]
+    // highlight-end
+    public partial B Map(A source);
+
+    [UserMapping(Default = false)]
+    private partial int Transform(int value, int multiplier);
+}
+```
+
+Add the missing parameter to the calling mapping method:
+
+```csharp
+[Mapper]
+public partial class MyMapper
+{
+    [MapProperty(nameof(A.Value), nameof(B.Result), Use = nameof(Transform))]
+    // highlight-start
+    public partial B Map(A source, int multiplier);
+    // highlight-end
+
+    [UserMapping(Default = false)]
+    private partial int Transform(int value, int multiplier);
+}
+```

docs/docs/configuration/analyzer-diagnostics/RMG099.mdx

@@ -0,0 +1,36 @@
+---
+sidebar_label: RMG099
+description: 'Mapperly analyzer diagnostic RMG099 — Duplicate additional parameter names differing only in casing'
+---
+
+# RMG099 — Duplicate additional parameter names differing only in casing
+
+A mapping method has multiple [additional parameters](../additional-mapping-parameters.mdx)
+whose names differ only in casing (e.g., `userId` and `UserId`).
+Mapperly matches additional parameters case-insensitively,
+so only the first parameter is used and the others are ignored.
+
+## Example
+
+```csharp
+[Mapper]
+public partial class MyMapper
+{
+    // highlight-start
+    // Error: UserId and userId differ only in casing
+    public partial B Map(A source, int UserId, int userId);
+    // highlight-end
+}
+```
+
+Rename the parameters to have distinct names or delete duplicate ones:
+
+```csharp
+[Mapper]
+public partial class MyMapper
+{
+    // highlight-start
+    public partial B Map(A source, int userId);
+    // highlight-end
+}
+```

docs/docs/configuration/constant-generated-values.mdx

@@ -54,6 +54,29 @@ Make sure the return type exactly matches the target type.
 
 This also works for constructor parameters.
 
+### Using additional mapping parameters
+
+When the mapping method has [additional parameters](./additional-mapping-parameters.mdx),
+they can be passed to `MapValue(Use = ...)` methods.
+The method's parameters are matched by name from the mapping's additional parameters:
+
+<Tabs>
+    <TabItem value="declaration" label="Declaration" default>
+        ```csharp
+        [MapValue(nameof(CarDto.FormattedDate), Use = nameof(FormatDate))]
+        public partial CarDto Map(Car car, string dateFormat);
+
+        string FormatDate(string dateFormat) => DateTime.Now.ToString(dateFormat);
+        ```
+    </TabItem>
+    <TabItem value="generated" label="Generated code" default>
+        ```csharp
+        target.FormattedDate = FormatDate(dateFormat);
+        ```
+    </TabItem>
+
+</Tabs>
+
 ### Named mapping
 
 The name of the value generator can be overridden by the `NamedMapping` attribute:

docs/docs/configuration/mapper.mdx

@@ -444,6 +444,35 @@ public partial class CarMapper
 }
 ```
 
+#### Use methods with additional parameters
+
+When the mapping method has [additional parameters](./additional-mapping-parameters.mdx),
+they can be forwarded to `Use` methods.
+For `MapProperty(Use = ...)`, the first parameter of the `Use` method receives the source member value,
+and the remaining parameters are matched by name from the mapping's additional parameters:
+
+```csharp
+[Mapper]
+public partial class CarMapper
+{
+    // highlight-start
+    [MapProperty(nameof(Car.Price), nameof(CarDto.DisplayPrice), Use = nameof(FormatPrice))]
+    // highlight-end
+    public partial CarDto MapCar(Car source, string currency);
+
+    // highlight-start
+    [UserMapping(Default = false)]
+    private string FormatPrice(decimal price, string currency)
+        => $"{currency} {price:F2}";
+    // highlight-end
+
+    // generates
+    target.DisplayPrice = FormatPrice(source.Price, currency);
+}
+```
+
+See also [additional mapping parameters](./additional-mapping-parameters.mdx) for more details on parameter forwarding.
+
 #### Custom mapping names
 
 By default, Mapperly uses the method name as the identifier for each mapping.