@dojo-ng/data-grid-drag 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,66 @@
-# Temporary Holding Version
+# @dojo-ng/data-grid-drag
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Drag rows out of a `<dj-data-grid>` with native HTML5 drag and drop, for example onto a `<dj-tree>` folder list.
+
+Part of [Dojo NG](../../README.md), a framework-agnostic web component library. BSD-3-Clause.
+
+## Install
+
+```bash
+npm install @dojo-ng/data-grid-drag
+```
+
+## Usage
+
+The grid writes the dragged rows' ids under its own MIME type; the tree accepts only that type, and `dj-drop` names the folder.
+
+```html
+<dj-tree id="folders"></dj-tree>
+<dj-data-grid id="mail" height="320px" activation="click" selection-mode="multiple"></dj-data-grid>
+<script type="module">
+  import "@dojo-ng/tree";
+  import "@dojo-ng/data-grid";
+  import { selectColumnPlugin } from "@dojo-ng/data-grid-select";
+  import { rowDragPlugin } from "@dojo-ng/data-grid-drag";
+  const TYPE = "application/x-demo-messages";
+
+  const tree = document.getElementById("folders");
+  tree.nodes = [{ id: "inbox", label: "Inbox" }, { id: "archive", label: "Archive" }];
+  tree.canDrop = (id, types) => types.includes(TYPE);
+  tree.addEventListener("dj-drop", (e) => {
+    const ids = JSON.parse(e.detail.dataTransfer.getData(TYPE));
+    move(ids, e.detail.id);
+  });
+
+  const grid = document.getElementById("mail");
+  grid.columns = [{ id: "from", header: "From" }, { id: "subject", header: "Subject" }];
+  grid.getRowId = (m) => String(m.id);
+  grid.data = [
+    { id: 1, from: "Ada", subject: "Analytical engine" },
+    { id: 2, from: "Grace", subject: "Compiler notes" },
+  ];
+  grid.plugins = [
+    selectColumnPlugin({ label: (m) => `Select ${m.subject}` }),
+    rowDragPlugin({
+      type: TYPE,
+      data: (rows) => JSON.stringify(rows.map((m) => m.id)),
+      label: (rows) => (rows.length === 1 ? rows[0].subject : `${rows.length} messages`),
+    }),
+  ];
+</script>
+```
+
+## How it works
+
+- Every row becomes `draggable`. Dragging a selected row drags every selected row; dragging an unselected row drags it alone and leaves the selection as it was.
+- The payload is yours: `data(rows)` is written to the drag under the MIME type you name in `type`. A drop target checks for that type, which is the only part of a payload the browser shows before the drop.
+- The drag image is a small chip. `label(rows)` sets its text (default "1 row" / "N rows").
+- Clicking, double clicking, and the checkbox column work as before: a drag only starts once the pointer moves, and a drag that starts on a control inside a cell is canceled.
+
+## Events
+
+- `dj-row-dragstart` (cancelable, detail `{ rows }`) and `dj-row-dragend` (detail `{ rows, dropEffect }`). Dragged rows carry the `row--dragging` part until the drag ends.
+
+## Accessibility
+
+- Dragging has no keyboard form. Offer the same action another way, such as a Move command with a picker (WCAG 2.5.7).

package/dist/drag-plugin.d.ts

@@ -0,0 +1,48 @@
+import { type DataGridPlugin, type Row } from "@dojo-ng/data-grid";
+export interface RowDragOptions {
+    /** The MIME type the payload is written under, e.g. `"application/x-myapp-items"`. A drop
+     *  target checks for it in `dataTransfer.types`, the only part of a payload a browser shows
+     *  before the drop. */
+    type: string;
+    /** Build the payload from the dragged rows' data. Written under `type`. */
+    data: (rows: Row[]) => string;
+    /** Text for the drag image, and the `text/plain` fallback. Defaults to "1 row" / "N rows". */
+    label?: (rows: Row[]) => string;
+}
+/** Detail of `dj-row-dragstart`. Cancel the event to refuse the drag. */
+export interface RowDragStartDetail {
+    rows: Row[];
+}
+/** Detail of `dj-row-dragend`. `dropEffect` is `"none"` when the drag was dropped nowhere or
+ *  canceled with Escape. */
+export interface RowDragEndDetail {
+    rows: Row[];
+    dropEffect: string;
+}
+/**
+ * `rowDragPlugin(options)` — makes `<dj-data-grid>` rows drag sources for native HTML5 drag and
+ * drop.
+ *
+ * Every row is `draggable`. Dragging a selected row drags every selected row; dragging an
+ * unselected row drags that row alone and leaves the selection as it was. The payload is yours:
+ * `data(rows)` is written under `type`, so a drop target (such as `dj-tree` with `canDrop`) can
+ * accept exactly the drags it understands. The drag image is a small chip naming what moves.
+ *
+ * A drag only starts after the pointer moves, so clicking, double clicking, and the checkbox
+ * column behave as without the plugin. A drag that starts on a control inside a cell (a checkbox,
+ * button, or link) is canceled and stays a click on that control.
+ *
+ * Events, from the grid: `dj-row-dragstart` (cancelable; detail `{ rows }`), then
+ * `dj-row-dragend` (detail `{ rows, dropEffect }`). Dragged rows carry the `row--dragging` part
+ * until the drag ends.
+ *
+ * Dragging has no keyboard form. Offer the same action another way (WCAG 2.5.7), such as a
+ * command that opens a picker.
+ */
+export declare function rowDragPlugin(options: RowDragOptions): DataGridPlugin;
+declare global {
+    interface GlobalEventHandlersEventMap {
+        "dj-row-dragstart": CustomEvent<RowDragStartDetail>;
+        "dj-row-dragend": CustomEvent<RowDragEndDetail>;
+    }
+}

package/dist/drag-plugin.js

@@ -0,0 +1,128 @@
+import { defineDataGridPlugin } from "@dojo-ng/data-grid";
+/** Starting a drag on one of these keeps it a click on the control instead. */
+const INTERACTIVE = "input, button, a[href], select, textarea, [contenteditable]:not([contenteditable=false])";
+const defaultLabel = (rows) => (rows.length === 1 ? "1 row" : `${rows.length} rows`);
+/**
+ * `rowDragPlugin(options)` — makes `<dj-data-grid>` rows drag sources for native HTML5 drag and
+ * drop.
+ *
+ * Every row is `draggable`. Dragging a selected row drags every selected row; dragging an
+ * unselected row drags that row alone and leaves the selection as it was. The payload is yours:
+ * `data(rows)` is written under `type`, so a drop target (such as `dj-tree` with `canDrop`) can
+ * accept exactly the drags it understands. The drag image is a small chip naming what moves.
+ *
+ * A drag only starts after the pointer moves, so clicking, double clicking, and the checkbox
+ * column behave as without the plugin. A drag that starts on a control inside a cell (a checkbox,
+ * button, or link) is canceled and stays a click on that control.
+ *
+ * Events, from the grid: `dj-row-dragstart` (cancelable; detail `{ rows }`), then
+ * `dj-row-dragend` (detail `{ rows, dropEffect }`). Dragged rows carry the `row--dragging` part
+ * until the drag ends.
+ *
+ * Dragging has no keyboard form. Offer the same action another way (WCAG 2.5.7), such as a
+ * command that opens a picker.
+ */
+export function rowDragPlugin(options) {
+    const label = options.label ?? defaultLabel;
+    /** Row ids being dragged, for the `row--dragging` part. */
+    let dragging = new Set();
+    let draggedData = [];
+    return defineDataGridPlugin({
+        name: "drag",
+        rowAttributes(row) {
+            const attrs = { draggable: "true" };
+            if (dragging.has(row.id))
+                attrs.part = "row--dragging";
+            return attrs;
+        },
+        setup(ctx) {
+            const host = ctx.host;
+            const root = host.renderRoot;
+            /** The table row a drag started on, from its composed path; null when it started on a
+             *  control or outside a body row. */
+            const rowOf = (e) => {
+                for (const n of e.composedPath()) {
+                    if (n === host)
+                        break;
+                    const el = n;
+                    if (!el.matches)
+                        continue;
+                    if (el.matches(INTERACTIVE))
+                        return null;
+                    if (el.classList.contains("vrow")) {
+                        const index = Number((el.id || "").replace(/^r-/, ""));
+                        return Number.isInteger(index) ? (ctx.table.getRowModel().rows[index] ?? null) : null;
+                    }
+                }
+                return null;
+            };
+            const onStart = (e) => {
+                const de = e;
+                const row = rowOf(de);
+                if (!row) {
+                    de.preventDefault();
+                    return;
+                }
+                const rows = row.getIsSelected() ? ctx.table.getSelectedRowModel().flatRows : [row];
+                const data = rows.map((r) => r.original);
+                const start = new CustomEvent("dj-row-dragstart", {
+                    bubbles: true, composed: true, cancelable: true, detail: { rows: data },
+                });
+                if (!host.dispatchEvent(start)) {
+                    de.preventDefault();
+                    return;
+                }
+                const dt = de.dataTransfer;
+                const text = label(data);
+                if (dt) {
+                    dt.setData(options.type, options.data(data));
+                    dt.setData("text/plain", text);
+                    dt.effectAllowed = "move";
+                    setDragImage(dt, text);
+                }
+                dragging = new Set(rows.map((r) => r.id));
+                draggedData = data;
+                ctx.refresh();
+            };
+            const onEnd = (e) => {
+                if (!dragging.size)
+                    return;
+                const dropEffect = e.dataTransfer?.dropEffect ?? "none";
+                const rows = draggedData;
+                dragging = new Set();
+                draggedData = [];
+                ctx.refresh();
+                host.dispatchEvent(new CustomEvent("dj-row-dragend", {
+                    bubbles: true, composed: true, detail: { rows, dropEffect },
+                }));
+            };
+            root.addEventListener("dragstart", onStart);
+            root.addEventListener("dragend", onEnd);
+            return () => {
+                root.removeEventListener("dragstart", onStart);
+                root.removeEventListener("dragend", onEnd);
+                dragging = new Set();
+                draggedData = [];
+            };
+        },
+    });
+}
+/** A chip naming what moves, used as the drag image. The browser snapshots it during
+ *  `dragstart`, so it can be removed on the next tick. */
+function setDragImage(dt, text) {
+    if (typeof dt.setDragImage !== "function" || typeof document === "undefined")
+        return;
+    const chip = document.createElement("div");
+    chip.textContent = text;
+    chip.setAttribute("aria-hidden", "true");
+    chip.style.cssText = [
+        "position:fixed", "top:-1000px", "left:-1000px", "max-width:20rem",
+        "overflow:hidden", "text-overflow:ellipsis", "white-space:nowrap",
+        "padding:0.25rem 0.6rem", "border-radius:999px",
+        "font:500 0.8125rem/1.4 var(--dj-font-sans, system-ui, sans-serif)",
+        "background:var(--dj-color-primary-600, #2563eb)", "color:var(--dj-color-text-on-primary, #fff)",
+    ].join(";");
+    document.body.appendChild(chip);
+    dt.setDragImage(chip, 12, 12);
+    setTimeout(() => chip.remove(), 0);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./drag-plugin.js";
+export { rowDragPlugin as default } from "./drag-plugin.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./drag-plugin.js";
+export { rowDragPlugin as default } from "./drag-plugin.js";

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "@dojo-ng/data-grid-drag",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "license": "BSD-3-Clause",
+  "description": "Row drag source plugin for @dojo-ng/data-grid (native HTML5 drag, drags the selection)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@dojo-ng/data-grid": "^0.2.0",
+    "@tanstack/table-core": "^8.0.0"
+  }
+}