JavaScript Project to Manipulate DOM Elements

DFlex

A Drag-and-Drop library for all JavaScript frameworks implementing an enhanced transformation mechanism to manipulate DOM elements. It is so far the only library on internet that manipulates the DOM instead of reconstructing it.

Features ✅

• Dynamic architecture.
• Traverse DOM without calling browser API.
• Transform elements instead of reordering the DOM tree.
• Animated movement from point-x to point-y.
• Prevent drag and drop layout shift.
• Isolated from data flow.
• Headless as it is just functions that do manipulation.
• Event driven API.
• Targeting each DOM node individually.
• Extensible using JSON tree instead of flat recursion.
• Support three different types of restrictions:
  1 -Restricted area related to the parent container.
  2- Restricted area related to the viewport.
  3- Restricted area related to the position itself.
• Support four types of custom events with custom layout state emitter.
• Auto remove selection when starting dragging.

Implemented Transformation 💡

• The original input order which appears when inspecting elements stays the same. While the visual order happens after transformation and it's supported by the data-index attribute to know the order of elements in the visual list.
  
  

• To enable handling a large set of elements, the transformation is related to the viewport. No matter how many elements are affected, DFlex only transforms elements visible on the screen. Elements outside the viewport are triggered to a new position when they are visible.
  
  

• Support strict transformation between containers.
  
  

Project Content 🚀

@dflex/dom-gen

DFlex DOM relations generator algorithm. It Generates relations between DOM elements based on element depth so all the registered DOM can be called inside registry without the need to call browser API. Read once, implement everywhere.

@dflex/core-instance

Core instance is the mirror of interactive element that includes all the properties and methods to manipulate the node.

@dflex/utils

A collection of shared functions. Mostly classes, and types that are used across the project.

@dflex/store

DFex Store has main registry for all DOM elements that will be manipulated. It is a singleton object that is accessible from anywhere in the application. The initial release was generic but it only has the Core of the library since ^V3.

@dflex/draggable

Light weight draggable element without extra functionalities that is responsible for interacting with the DOM and moving the affected element(s).

@dflex/dnd

The main package that depends on the other packages. It is responsible for the magical logic of the library to introduce the drag and drop interactive functionality.

Documentation 📖

Visit DFlex site for more https://www.dflex.dev/

Local Development 📦

DFlex contains multiple packages that shapes the final product. All Packages are decoupled and work separately. Each package has it own universe including test and playground or at lease this is the initial plan.

DFlex is written entirely in plain JavaScript/TypeScript and doesn't depend on any specific framework. However, it's using the React for playground and Cypress for end to end testing. It's also using Jest for unit testing and PNPM to manage the packages.

Clone the repository

git clone https://github.com/dflex-js/dflex.git
cd dflex
pnpm install

To start development you can use the following command:

pnpm -F @dflex/dnd server

This will run the development playground for the DnD package. Open the browser http://localhost:3001 to see the playground. You can check the code in the packages/dnd/playgrounds to see the available routing.

If you want to change the codebase and live edit the playground you have to compile while running the playground. You can use the following command:

pnpm -F @dflex/dnd compile:w
pnpm -F @dflex/dnd build:w
pnpm -F @dflex/dnd run server

After finish editing you can make sure the changes you make are not going to break the code. You can do that by running the test and have some fun watching Cypress do the job:

pnpm -F @dflex/dnd test

Contribution 🌎

PRs are welcome, If you wish to help, you can learn more about how you can contribute to this project in the Contributing guide.

To submit a PR:

1- Fork DFlex then clone the repository.

2- Create a new branch: git checkout -b my-branch-name.

3- Make your change.

4- Push to your fork and submit a pull request when ready.

Work in progress 🔨

DFlex is a work in progress. The transformation between containers is still in development. Yet, you can use the library in your project if you depend on transformation inside one container.

License 🤝

DFlex is MIT License since version 3.0.0 and above.

Author

Jalal Maskoun (@jalal246)