An open API service indexing awesome lists of open source software.

https://github.com/yookoala/dragdrop-components

Web Components for Simple Drag and Drop Operations
https://github.com/yookoala/dragdrop-components

drag-and-drop drag-drop webcomponent

Last synced: 2 months ago
JSON representation

Web Components for Simple Drag and Drop Operations

Awesome Lists containing this project

README

        

# Drag Drop Components

Web components to simplify drag-drop interface coding. Suitable for all UI that user drag and drop
items from one container to another. Such as:

1. Kanban-like UI: Drag and drop an item from one board to another.
2. Board game: drag and drop pieces from one tile to another.

Live Examples: [https://yookoala.github.io/dragdrop-components/examples/][examples-url]

[![CI test][ci-badge]][ci-url] [![NPM][npm-badge]][npm-url] [![Downloads][npm-download-badge]][npm-url]

[examples-url]: https://yookoala.github.io/dragdrop-components/examples/
[ci-url]: https://github.com/yookoala/dragdrop-components/actions?query=branch%3Amain+workflow%3APlaywright
[ci-badge]: https://github.com/yookoala/dragdrop-components/actions/workflows/playwright.yml/badge.svg?branch=main
[npm-url]: https://www.npmjs.com/package/dragdrop-components
[npm-badge]: https://img.shields.io/npm/v/dragdrop-components
[npm-download-badge]: https://img.shields.io/npm/dm/dragdrop-components

---
**Table of Contents**
- [How to Use](#how-to-use)
- [HTML](#html)
- [Simple Example](#simple-example)
- [NodeJS](#nodejs)
- [API](#api)
- [Events](#events)
- [dragdrop-child](#dragdrop-child)
- [dragdrop-container](#dragdrop-container)
- [Contribution](#contribution)
- [Building the Library](#building-the-library)
- [Development Mode](#development-mode)
- [Playwright Test](#playwright-test)
- [Report Issue and Contribution](#report-issue-and-contribution)
- [License](#license)

---

## How to Use

### HTML

Just include the script from jsdelivr.net:

```html

```

They you can use these 2 custom elements in your HTML:

* ``
A div-like block element to be dragged arround and drop into containers.

* ``
A div-like block element to receive ``.

No framework. Couldn't have been easier.

#### Simple Example

There is very little pre-defined CSS style to stand in the way. A simple
Kanban applicaiton can be structured like this:

```html

main {
display: flex;
}
dragdrop-container {
border: 1px solid #ddd;
min-height: 3em; /** prevent empty container from disappearing */
}
dragdrop-child {
border: 1px solid #ddd;
min-height: 3em; /** prevent empty child from disappearing */
}


Todo




My Task






Doing





Done



document.getElementById("todo").addEventListener(
"dnd:dropped",
function (event) {
const child = event.detail.child;
const taskId = child.dataset.taskId;
console.log('TODO: ', taskId);
},
);

document.getElementById("doing").addEventListener(
"dnd:dropped",
function (event) {
const child = event.detail.child;
const taskId = child.dataset.taskId;
console.log('DOING: ', taskId);
},
);

document.getElementById("done").addEventListener(
"dnd:dropped",
function (event) {
const child = event.detail.child;
const taskId = child.dataset.taskId;
console.log('DONE: ', taskId);
},
);

```

More examples can be found in [examples](examples).

### NodeJS

Install to your environment by:
```shell
npm install dragdrop-components
```

Use it on browser script:
```js
// For the side-effects.
import 'dragdrop-components';

// Then use like simple HTML element, for example.
const container1 = document.createElement('dragdrop-container');
const container2 = document.createElement('dragdrop-container');
const child = document.createElement('dragdrop-child');
container1.appendChild(child);
document.documentElement.appendChild(container1);
document.documentElement.appendChild(container2);
```

## API

### Events

This library will fire a few custom events. The same event(s) will fire both
with ordinary mouse drag-drop or touch drag-drop.

#### dragdrop-child

* `dnd:dragstart`
* Fires when a it is started being dragged (both using mouse or touch).
* Attributes
- target (HTMLElement): the dragdrop-child element.
* `dnd:dragend`
* Fires when a it is released from drag (both using mouse or touch).
* Attributes
- target (HTMLElement): the dragdrop-child element.

#### dragdrop-container

* `dnd:dragenter`
* Fires when the dragdrop-child is dragging into the container.
* Attributes
- target (HTMLElement): the dragdrop-container element.
- detail (Object)
with attribute:
- child (HTMLElement): the dragdrop-child element being dragged.

* `dnd:dragleave`
* Fires when the dragdrop-child is dragging away from the container.
* Attributes
- target (HTMLElement): the dragdrop-container element.
- detail (Object)
with attribute:
- child (HTMLElement): the dragdrop-child element being dragged.

* `dnd:bounced`
* Fires when a previously dragged-away dragdrop-child is rejected from the
destination container or otherwise being bounced back.
* Attributes
- target (HTMLElement): the dragdrop-container element.
- detail (Object)
with attribute:
- child (HTMLElement): the dragdrop-child element being dragged.

* `dnd:dropped`
* Fires when a dragdrop-child is dropped on this container.
* Attributes
- target (HTMLElement): the dragdrop-container element.
- detail (Object)
with attribute:
- child (HTMLElement): the dragdrop-child element being dragged.

## Contribution

You are very welcome to modify and backport changes here.

The best way is to work or extend on the [examples](examples) along with proper
[test cases](tests). All example depends on, and should always depend on, the
built copy "dist/dragdrop-component.js" in this repository.

### Building the Library

This command will build the "dist/dragdrop-component.js" file for distribution.

```
npm install
npm run build
```

### Development Mode

To modify the library, you may run these to start the development mode.
The source files will be monitored and built into the "dist" folder.

```
npm install
npm run dev
```

### Playwright Test

This library uses Playwright test for the dragdrop effect verifications. To
prevent regression, please verify that your changes can pass Playwright tests.

Playwright also provides very good support to VSCode's debugger. If you do not
have a preferred editor, you're recommended to use [VSCode](https://playwright.dev/docs/getting-started-vscode)
along with the [Playwright Test](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright)
plugin.

### Report Issue and Contribution

The library is hosted [here](https://github.com/yookoala/dragdrop-components). Please
use our [issue tracker](https://github.com/yookoala/dragdrop-components/issues) to
report issue, discuss or request new features. You're more than welcome to submit
[Pull Request](https://github.com/yookoala/dragdrop-components/pulls) for bug fixes
and new features.

## License

This software is licensed to the MIT License. A copy of the license can be found [here](LICENSE).