Merge pull request #7 from crabnebula-dev/feat/docs-covector

feat: add documentation and covector setup

.changes/config.json

@@ -0,0 +1,38 @@
+{
+  "gitSiteUrl": "https://github.com/crabnebula-dev/drag-rs/",
+  "pkgManagers": {
+    "javascript": {
+      "version": true,
+      "getPublishedVersion": {
+        "use": "fetch:check",
+        "options": {
+          "url": "https://registry.npmjs.com/${ pkg.pkg }/${ pkg.pkgFile.version }"
+        }
+      },
+      "publish": [
+        "npm publish --access public"
+      ]
+    },
+    "rust": {
+      "version": true,
+      "getPublishedVersion": "cargo search ${ pkg.pkg } --limit 1 | sed -nE 's/^[^\"]*\"//; s/\".*//1p' -",
+      "publish": [
+        "cargo publish"
+      ]
+    }
+  },
+  "packages": {
+    "@crabnebula/plugin-drag": {
+      "path": "./packages/tauri-plugin-api",
+      "manager": "javascript"
+    },
+    "drag": {
+      "path": "./crates/drag",
+      "manager": "rust"
+    },
+    "tauri-plugin-drag": {
+      "path": "./crates/tauri-plugin",
+      "manager": "rust"
+    }
+  }
+}

.changes/initial-release.md

@@ -0,0 +1,7 @@
+---
+"@crabnebula/plugin-drag": minor
+"drag": minor
+"tauri-plugin-drag": minor
+---
+
+Initial release.

.changes/readme.md

@@ -0,0 +1,31 @@
+# Changes
+
+##### via https://github.com/jbolda/covector
+
+As you create PRs and make changes that require a version bump, please add a new markdown file in this folder. You do not note the version _number_, but rather the type of bump that you expect: major, minor, or patch. The filename is not important, as long as it is a `.md`, but we recommend that it represents the overall change for organizational purposes.
+
+When you select the version bump required, you do _not_ need to consider dependencies. Only note the package with the actual change, and any packages that depend on that package will be bumped automatically in the process.
+
+Use the following format:
+
+```md
+---
+"package-a": patch
+"package-b": minor
+---
+
+Change summary goes here
+
+```
+
+Summaries do not have a specific character limit, but are text only. These summaries are used within the (future implementation of) changelogs. They will give context to the change and also point back to the original PR if more details and context are needed.
+
+Changes will be designated as a `major`, `minor` or `patch` as further described in [semver](https://semver.org/).
+
+Given a version number MAJOR.MINOR.PATCH, increment the:
+
+- MAJOR version when you make incompatible API changes,
+- MINOR version when you add functionality in a backwards compatible manner, and
+- PATCH version when you make backwards compatible bug fixes.
+
+Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format, but will be discussed prior to usage (as extra steps will be necessary in consideration of merging and publishing).

.github/workflows/covector-status.yml

@@ -0,0 +1,16 @@
+name: covector status
+on: [pull_request]
+
+jobs:
+  covector:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # required for use of git history
+      - name: covector status
+        uses: jbolda/covector/packages/[email protected]
+        id: covector
+        with:
+          command: 'status'

.github/workflows/covector-version-or-publish.yml

@@ -0,0 +1,50 @@
+name: version or publish
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  version-or-publish:
+    runs-on: ubuntu-latest
+    timeout-minutes: 65
+    outputs:
+      change: ${{ steps.covector.outputs.change }}
+      commandRan: ${{ steps.covector.outputs.commandRan }}
+      successfulPublish: ${{ steps.covector.outputs.successfulPublish }}
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # required for use of git history
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 14
+          registry-url: 'https://registry.npmjs.org'
+      - name: cargo login
+        run: cargo login ${{ secrets.crate_token }}
+      - name: git config
+        run: |
+          git config --global user.name "${{ github.event.pusher.name }}"
+          git config --global user.email "${{ github.event.pusher.email }}"
+      - name: covector version or publish (publish when no change files present)
+        uses: jbolda/covector/packages/[email protected]
+        id: covector
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          CARGO_AUDIT_OPTIONS: ${{ secrets.CARGO_AUDIT_OPTIONS }}
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          command: 'version-or-publish'
+          createRelease: true
+      - name: Create Pull Request With Versions Bumped
+        id: cpr
+        uses: peter-evans/create-pull-request@v3
+        if: steps.covector.outputs.commandRan == 'version'
+        with:
+          title: "Publish New Versions"
+          commit-message: "publish new versions"
+          labels: "version updates"
+          branch: "release"
+          body: ${{ steps.covector.outputs.change }}

Cargo.toml

@@ -1,7 +1,6 @@
 [workspace]
 resolver = "2"
 members = ["crates/*", "examples/*"]
-exclude = ["examples/wry"]
 
 [workspace.package]
 edition = "2021"

README.md

@@ -1,30 +1,134 @@
 # drag-rs
 
-Start a drag operation out of a window.
+Start a drag operation out of a window on macOS, Windows and Linux (via GTK).
 
-Tested for [tao](https://github.com/tauri-apps/tao), [winit](https://github.com/rust-windowing/winit) and [tauri](https://github.com/tauri-apps/tauri) windows.
+Tested for [tao](https://github.com/tauri-apps/tao) (latest), [winit](https://github.com/rust-windowing/winit) (latest), [wry](https://github.com/tauri-apps/wry) (v0.24) and [tauri](https://github.com/tauri-apps/tauri) (v1) windows.
+Due to the GTK-based implementation, winit currently cannot leverage this crate on Linux yet.
 
 This project also includes a Tauri plugin for simplified usage on Tauri apps.
 
-## Examples
+## Setup
 
-Running the examples:
+There's two ways to consume this crate API: from Rust code via the `drag` crate or from Tauri's frontend via `tauri-plugin-drag`.
+
+### Rust
+
+- Add the `drag` dependency:
+
+`$ cargo add drag`
+
+- Define the drag item and preview icon:
+
+  ```rust
+  let item = drag::DragItem::Files(vec![std::fs::canonicalize("./examples/icon.png").unwrap()]);
+  let preview_icon = drag::Image::Raw(include_bytes!("../../icon.png").to_vec());
+  ```
+
+- Use the `drag::start_drag` function. It takes a `&T: raw_window_handle::HasRawWindowHandle` type on macOS and Windows, and a `&gtk::ApplicationWindow` on Linux:
+
+  - tao:
+  ```rust
+  let event_loop = tao::event_loop::EventLoop::new();
+  let window = tao::window::WindowBuilder::new().build(&event_loop).unwrap();
+
+  drag::start_drag(
+    #[cfg(target_os = "linux")]
+    {
+      use tao::platform::unix::WindowExtUnix;
+      window.gtk_window()
+    },
+    #[cfg(not(target_os = "linux"))]
+    &window,
+    item,
+    preview_icon,
+  );
+  ```
+
+  - wry:
+  ```rust
+  let event_loop = wry::application::event_loop::EventLoop::new();
+  let window = wry::application::window::WindowBuilder::new().build(&event_loop).unwrap();
+  let webview = wry::webview::WebViewBuilder::new(window).unwrap().build().unwrap();
+
+  drag::start_drag(
+    #[cfg(target_os = "linux")]
+    {
+      use wry::application::platform::unix::WindowExtUnix;
+      webview.window().gtk_window()
+    },
+    #[cfg(not(target_os = "linux"))]
+    &webview.window(),
+    item,
+    preview_icon,
+  );
+  ```
+
+  - winit: 
+  ```rust
+  let event_loop = winit::event_loop::EventLoop::new().unwrap();
+  let window = winit::window::WindowBuilder::new().build(&event_loop).unwrap();
+  let _ = drag::start_drag(&window, item, preview_icon);
+  ```
+
+  - tauri:
+  ```rust
+  tauri::Builder::default()
+    .setup(|app| {
+      let window = app.get_window("main").unwrap();
 
-- Tauri:
+      drag::start_drag(
+        #[cfg(target_os = "linux")]
+        &window.gtk_window()?,
+        #[cfg(not(target_os = "linux"))]
+        &window,
+        item,
+        preview_icon
+      );
+
+      Ok(())
+    })
+  ```
+
+### Tauri Plugin
+
+- Add the `tauri-plugin-drag` dependency:
+
+`$ cargo add tauri-plugin-drag`
+
+- Install the `@crabnebula/plugin-drag` NPM package containing the API bindings:
 
 ```sh
-cargo run --bin tauri-app
+pnpm add @crabnebula/plugin-drag
+# or
+npm add @crabnebula/plugin-drag
+# or
+yarn add @crabnebula/plugin-drag
 ```
 
-- Winit:
+- Register the core plugin with Tauri:
 
-```sh
-cargo run --bin winit-app
+`src-tauri/src/main.rs`
+
+```rust
+fn main() {
+    tauri::Builder::default()
+        .plugin(tauri_plugin_drag::init())
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
 ```
 
-- Wry:
+- Afterwards all the plugin's APIs are available through the JavaScript guest bindings:
+
+```javascript
+import { startDrag } from "@crabnebula/plugin-drag";
+startDrag({ item: ['/path/to/drag/file'], icon: '/path/to/icon/image' })
+```
+
+## Examples
+
+Running the examples:
 
 ```sh
-cd examples/wry
-cargo run
-```
+cargo run --bin [tauri-app|winit-app|tao-app|wry-app]
+```

SECURITY.md

@@ -0,0 +1,30 @@
+# Security Policy
+
+**Do not report security vulnerabilities through public GitHub issues.**
+
+**Please use the [Private Vulnerability Disclosure](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability#privately-reporting-a-security-vulnerability) feature of GitHub.**
+
+Alternatively, you can also send them by email to [email protected].
+You can encrypt your mail using GnuPG if you want. 
+
+See the [security.txt](https://crabnebula.dev/.well-known/security.txt) from CrabNebula
+
+```
+Contact: mailto:[email protected]
+Expires: 2025-01-30T06:30:00.000Z
+Encryption: https://crabnebula.dev/.well-known/pgp.txt
+Preferred-Languages: en,de,fr
+Canonical: https://crabnebula.dev/.well-known/security.txt
+```
+
+Include as much of the following information:
+
+- Type of issue (e.g. buffer overflow, privilege escalation, etc.)
+- The location of the affected source code (tag/branch/commit or direct URL)
+- Any special configuration required to reproduce the issue
+- The distribution affected or used for reproduction.
+- Step-by-step instructions to reproduce the issue
+- Impact of the issue, including how an attacker might exploit the issue
+- Preferred Languages
+
+We prefer to receive reports in English. If necessary, we also understand French and German.

crates/drag/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "drag"
-version = "0.0.0"
+version = "0.1.0"
 description = "Start a drag operation out of a window"
 edition = { workspace = true }
 
@@ -9,6 +9,12 @@ raw-window-handle = "0.5"
 thiserror = "1"
 serde = { version = "1", optional = true }
 
+[dev-dependencies]
+tao = "0.16"
+winit = "0.29"
+wry = "0.24"
+tauri = "1"
+
 [target."cfg(target_os = \"macos\")".dependencies]
 cocoa = "0.25"
 objc = "0.2"