npm package: @combeenation/2d-planning-utils
Description: Combeenation 2D planning utils
Author: Combeenation
Latest version: 0.2.1

# 2D planning utils

This repository contains utils for implementing 2d planning editors in an Combeenation Configurator.

[API Documentation](https://2d-planning-utils.docs.combeenation.com)

## Dependency Documentations and Examples

Here are some useful links to the documentation of the used external packages:

- [InfiniteViewer | Documentation](https://daybrush.com/infinite-viewer/release/latest/doc/InfiniteViewer.html)
- [Moveable | Documentation](https://daybrush.com/moveable/release/latest/doc/Moveable.html)
- [Selecto | Documentation](https://daybrush.com/selecto/release/latest/doc/Selecto.html)
- [SVG.js | Documentation](https://svgjs.dev/docs/3.2)

Daybrush (the package owner of infinite viewer, moveable and selecto) has a very useful storybook which shows a lot of examples: [Storybook Daybrush](https://daybrush.com/moveable/storybook2)

## Functionalities

### Dataview Drag and Drop Handler

This handler can be used to attach to a `Dataview` component of the configurator.
It allows you to drag and drop from a `Dataview` into a drop container and provides events to write custom behaviors.

#### Usage

1. Create the `CbnDataviewDragManager` specifying the type of the custom drag data, the `dataview` to drag items from, a selector for the target container (where items will be dropped into), and optionally the class of disabled dataview items.

2. `onDragStart` and `onDrag` need to be overwritten to set the drag data and handle the drop logic, respectively. Drag image creation, drag image positioning and drop zone detection are done by the handler.
Optionally, `onDragEnd` can be overwritten for any post drag logic.

See docs for more infos: [CbnDataviewDragManager](https://2d-planning-utils.docs.combeenation.com/classes/CbnDataviewDragManager.html)

### Infinite 2D Viewer Integration

Provides a full infinite 2d viewer which can be used to control complex planning modes. In addition to the default features, it offers custom methods such as automatic viewport centering.

#### Usage

1. Create the `CbnInfiniteViewer` specifying the container element, and optionally [CbnInfiniteViewerOptions](https://2d-planning-utils.docs.combeenation.com/interfaces/Types.CbnInfiniteViewerOptions.html) for customization. See [InfiniteViewerOption](https://daybrush.com/infinite-viewer/release/latest/doc/InfiniteViewer.html#.InfiniteViewerOptions) for detailed information.

See docs for more infos: [CbnInfiniteViewer](https://2d-planning-utils.docs.combeenation.com/classes/CbnInfiniteViewer.html)

### Elements `Moveable` and `Selecto` manager

Can be used to make html elements moveable and draggable (and much more) inside the infinite viewer.
It provides a lot of functionality out-of-the-box and has been adapted with several Combeenation-specific methods.
All necessary events are exposed and can be fully customized.

#### Usage

1. Create the `CbnMoveableSelectoManager` specifying the `CbnInfiniteViewer` to use, selectors for the moveable items and the container, and optionally [MoveableOptions](https://daybrush.com/moveable/release/latest/doc/Moveable.html#.MoveableOptions).

2. Overwrite the events you need. Using `onSelect` for selection handling and `onDrag` for position handling is advised.

See docs for more infos: [CbnMoveableSelectoManager](https://2d-planning-utils.docs.combeenation.com/classes/CbnMoveableSelectoManager.html)

### Various util methods and standardized functions

Provides methods that are frequently used across various projects.
These methods cover a wide spectrum, from simple unit conversions to complex mathematical calculations, useful SVG manipulations, and much more.

See docs for more infos:

- [CbnMathUtils](https://2d-planning-utils.docs.combeenation.com/modules/CbnMathUtils.html)
- [CbnMiscUtils](https://2d-planning-utils.docs.combeenation.com/modules/CbnMiscUtils.html)
- [CbnSvgUtils](https://2d-planning-utils.docs.combeenation.com/modules/CbnSvgUtils.html)

### Provided Types

You can view the exported and provided types in the documentation: [Documentation - Types](https://2d-planning-utils.docs.combeenation.com/modules/Types.html)

[Infinite Viewer](https://daybrush.com/infinite-viewer/release/latest/doc/InfiniteViewer.html#.AnimationOptions),
[Moveable](https://daybrush.com/moveable/release/latest/doc/Moveable.html#.AbleRequesters) and [Selecto](https://daybrush.com/selecto/release/latest/doc/Selecto.html#.BoundContainer) types are re-exported.