Drag and Drop for the N=1 system


Keywords
monorepo, lerna, react, layout, animation, editor, dashboard, diagrams, templates, games, typescript, javascript, react-component, svg
License
MIT
Install
npm install @neq1/dnd@2.0.0-alpha.1

Documentation

Introduction

An imperative layout system for react

N=1 is a framework for building and editing components that compute the layout dynamically using generators. Generators are used to compute and update the layout and since the generators are just javascript they can generate whatever you can imagine and translate into code. Components use the generated layout by name.

  <Layout ...>
    <div data-layout={{name: 'leftPanel'}}
      ...components
    </div>
  </Layout>

The above code will place components in the 'leftPanel' area defined by the generator. It is the responsibility of the generator to respond to layout changes and to exposed settings.

N=1 is general purpose, supports both html and svg*, and allows precise and continuous control for responsive layouts. Major features include layout using generators, drag and drop, layers, and a built-in property-controlled editor with position and size editing. Applications include responsive layouts, animation, diagrams, dashboards, and simple games.

As an example consider the drag and drop implementation. It is high level built with N=1's blocks. Its runtime behavior follows the philosophy of React. A block specifies the position of a component in a layout and it is the block that is dragged. Its location and size are known. There is little need to query or manipulate html.

N=1 can do more than layout. It can be used to maintain relationships between components since a block also has access to all the other blocks in a layout by name. This lets you connect components using rubber-banding or just to maintain relationships. See the Diagram tab at demo for an example.

Like other components, N=1 can be used through-out an app or only for one component. It's only significant dependency is React 16 itself since Neq1 is built on top of React (the Animate component requires react 16.8 since it is built using react hooks).

* For SVG to be more than an icon generator or canvas in React it needs to know position and size along with relationships. N=1 makes this easy. For example, to use svg to generate a line connecting two react components requires access to the layout details of both components. This can be done in React but small changes in layout can easily break the layout. In N=1 you just reference the two components and register for updates.

Examples

See Live examples. Be sure to turn on the info-circle for details.

Documentation

See docs.

Packages

UI Components

Generators and Hooks

Services

Utilities

Internal

Internal - no API

  • @neq1/styles
  • @neq1/editors

Installation

To evaluate in your own project, install @neq1/layout and then one or more of the generators/hooks using yarn.

Contributing

These steps will guide you through contributing to this project:

  • Fork neq1
  • Clone it and install dependencies

git clone https://github.com/YOUR-USERNAME/neq1

After cloning go to your install directory and use yarn to initialize (see Implementation below).

Make and commit your changes. Make sure the commands start, build, and test are working.

Finally send a GitHub Pull Request with a clear list of what you've done (read more about pull requests). Make sure all of your commits are atomic (one feature per commit).

Implementation

N=1 is a monorepo consisting of three workspace folders: generators, hooks, and packages. There is also a workspace tools folder that is not published.

Notes:

  • NPM is not supported since N=1 uses yarn workspaces. You will also need to install typescript, lerna, and bili globally.

  • Yarn must be run at the root to initialize the monorepo and anytime hand changes are made to root package.json or to the individual package.json in each component.

  • Yarn workspaces are used to link packages. This is accomplished by adding a "workspaces" entry in package.json and lerna.json. In addition lerna.json also includes the keys "npmClient": "yarn" and "useWorkspaces": true.

  • Dependencies between packages are manged using the command lerna add <package> --scope=@neq1/<package>. To add new npm packages use yarn add -W from root (the W is for workspaces).

  • Typedoc is used to generate documentation from TSDoc comments. Typedoc is run on each package with an API and the results are linked by the global Typedoc results. To publish on github pages the file .nojekyll must be included in the docs folder because github pages hides filenames starting with a leading underscore.

  • The tools folder includes a demo app that can be run using 'yarn demo' from the root. The demo is built using webpack using N=1 for the framework. Because the tools folder is part of the workspace, N=1's packages can be accessed without installing.

  • Tests are located in the tools folder and can be run using yarn test or yarn testcov from root.

  • Storybook is also included in the tools folder. To run it use yarn storybook from root.

  • To build all the packages run yarn build from root.

  • To commit changes run yarn commit from root.

The organization of this implementation roughly follows this guide.