docs: add code snippets for drag'n drop (#17390)

Fixes https://github.com/microsoft/playwright.dev/issues/775

docs/src/api/class-locator.md

@@ -266,6 +266,72 @@ Optional event-specific initialization properties.
 
 ## async method: Locator.dragTo
 * since: v1.18
+
+This method drags the locator to another target locator or target position. It will
+first move to the source element, perform a `mousedown`, then move to the target
+element or position and perform a `mouseup`.
+
+```js
+const source = page.locator('#source');
+const target = page.locator('#target');
+
+await source.dragTo(target);
+// or specify exact positions relative to the top-left corners of the elements:
+await source.dragTo(target, {
+  sourcePosition: { x: 34, y: 7 },
+  targetPosition: { x: 10, y: 20 },
+});
+```
+
+```java
+Locator source = page.locator("#source");
+Locator target = page.locator("#target");
+
+source.dragTo(target);
+// or specify exact positions relative to the top-left corners of the elements:
+source.dragTo(target, new Locator.DragToOptions()
+  .setSourcePosition(34, 7).setTargetPosition(10, 20));
+```
+
+```python async
+source = page.locator("#source")
+target = page.locator("#target")
+
+await source.drag_to(target)
+# or specify exact positions relative to the top-left corners of the elements:
+await source.drag_to(
+  target,
+  source_position={"x": 34, "y": 7},
+  target_position={"x": 10, "y": 20}
+)
+```
+
+```python sync
+source = page.locator("#source")
+target = page.locator("#target")
+
+source.drag_to(target)
+# or specify exact positions relative to the top-left corners of the elements:
+source.drag_to(
+  target,
+  source_position={"x": 34, "y": 7},
+  target_position={"x": 10, "y": 20}
+)
+```
+
+```csharp
+var source = Page.Locator("#source");
+var target = Page.Locator("#target");
+
+await source.DragToAsync(target);
+// or specify exact positions relative to the top-left corners of the elements:
+await source.DragToAsync(target, new()
+{
+    SourcePosition = new() { X = 34, Y = 7 },
+    TargetPosition = new() { X = 10, Y = 20 },
+});
+```
+
 ### param: Locator.dragTo.target
 * since: v1.18
 - `target` <[Locator]>

docs/src/api/class-page.md

@@ -964,6 +964,58 @@ Optional event-specific initialization properties.
 ## async method: Page.dragAndDrop
 * since: v1.13
 
+This method drags the source element to the target element.
+It will first move to the source element, perform a `mousedown`,
+then move to the target element and perform a `mouseup`.
+
+```js
+await page.dragAndDrop('#source', '#target');
+// or specify exact positions relative to the top-left corners of the elements:
+await page.dragAndDrop('#source', '#target', {
+  sourcePosition: { x: 34, y: 7 },
+  targetPosition: { x: 10, y: 20 },
+});
+```
+
+```java
+page.dragAndDrop("#source", '#target');
+// or specify exact positions relative to the top-left corners of the elements:
+page.dragAndDrop("#source", '#target', new Page.DragAndDropOptions()
+  .setSourcePosition(34, 7).setTargetPosition(10, 20));
+```
+
+```python async
+await page.drag_and_drop("#source", "#target")
+# or specify exact positions relative to the top-left corners of the elements:
+await page.drag_and_drop(
+  "#source",
+  "#target",
+  source_position={"x": 34, "y": 7},
+  target_position={"x": 10, "y": 20}
+)
+```
+
+```python sync
+page.drag_and_drop("#source", "#target")
+# or specify exact positions relative to the top-left corners of the elements:
+page.drag_and_drop(
+  "#source",
+  "#target",
+  source_position={"x": 34, "y": 7},
+  target_position={"x": 10, "y": 20}
+)
+```
+
+```csharp
+await Page.DragAndDropAsync("#source", "#target");
+// or specify exact positions relative to the top-left corners of the elements:
+await Page.DragAndDropAsync("#source", "#target", new()
+{
+    SourcePosition = new() { X = 34, Y = 7 },
+    TargetPosition = new() { X = 10, Y = 20 },
+});
+```
+
 ### param: Page.dragAndDrop.source = %%-input-source-%%
 * since: v1.13
 ### param: Page.dragAndDrop.target = %%-input-target-%%

packages/playwright-core/types/types.d.ts

@@ -2146,6 +2146,18 @@ export interface Page {
   }): Promise<void>;
 
   /**
+   * This method drags the source element to the target element. It will first move to the source element, perform a
+   * `mousedown`, then move to the target element and perform a `mouseup`.
+   *
+   * ```js
+   * await page.dragAndDrop('#source', '#target');
+   * // or specify exact positions relative to the top-left corners of the elements:
+   * await page.dragAndDrop('#source', '#target', {
+   *   sourcePosition: { x: 34, y: 7 },
+   *   targetPosition: { x: 10, y: 20 },
+   * });
+   * ```
+   *
    * @param source A selector to search for an element to drag. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
    * @param target A selector to search for an element to drop onto. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
    * @param options
@@ -9413,6 +9425,21 @@ export interface Locator {
   }): Promise<void>;
 
   /**
+   * This method drags the locator to another target locator or target position. It will first move to the source element,
+   * perform a `mousedown`, then move to the target element or position and perform a `mouseup`.
+   *
+   * ```js
+   * const source = page.locator('#source');
+   * const target = page.locator('#target');
+   *
+   * await source.dragTo(target);
+   * // or specify exact positions relative to the top-left corners of the elements:
+   * await source.dragTo(target, {
+   *   sourcePosition: { x: 34, y: 7 },
+   *   targetPosition: { x: 10, y: 20 },
+   * });
+   * ```
+   *
    * @param target Locator of the element to drag to.
    * @param options
    */