@alekstar79/draggable-resizable-container 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aleksey Tarasenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,265 @@
+# Draggable and Resizable Container
+
+[![npm version](https://img.shields.io/npm/v/draggable-resizable-container.svg)](https://www.npmjs.com/package/@alekstar79/draggable-resizable-container)
+[![Coverage](https://img.shields.io/badge/coverage-80%25-brightgreen.svg)](https://github.com/alekstar79/utils/actions)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?style=flat-square)](https://www.typescriptlang.org)
+[![Node](https://img.shields.io/badge/Node-18%2B-green?style=flat-square)](https://nodejs.org)
+[![Browser](https://img.shields.io/badge/Browser-ES2018-green)]()
+[![License MIT](https://img.shields.io/badge/License-MIT-blue)](LICENSE)
+
+A modern, lightweight, and extensible TypeScript library for creating draggable and resizable containers (windows, dialogs) in your web applications. It features a reactive core, a powerful plugin system, and a clean API.
+
+![banner](banner.svg)
+
+## Features
+
+- **Draggable & Resizable**: Smooth, performant dragging and resizing of containers with multiple handle directions.
+- **Reactive Core**: Built with `@alekstar79/reactive-event-system` for efficient state management and event handling.
+- **Extensible Plugin System**: Easily add new features like snapping, docking, or state persistence.
+- **Rich Event System**: Subscribe to a wide range of events (`dragStart`, `drag`, `dragEnd`, `resize`, etc.).
+- **Boundary Constraints**: Confine containers to the viewport or a parent element.
+- **Customizable**: Control movement direction, resize handles, and more.
+- **Touch Device Support**: Works on both desktop and mobile devices.
+- **Template Loading**: A system for loading content from HTML templates.
+- **State Persistence**: Save and restore container states using `localStorage`.
+- **TypeScript First**: Written entirely in TypeScript for strong typing and better developer experience.
+
+## Installation
+
+You can install the library using npm or yarn:
+
+```bash
+npm install @alekstar79/draggable-resizable-container
+```
+
+or
+
+```bash
+yarn add @alekstar79/draggable-resizable-container
+```
+
+You also need to import the base styles for the library to work correctly.
+
+```javascript
+import '@alekstar79/draggable-resizable-container/styles';
+```
+
+## Quick Start
+
+Here's a simple example of how to create a draggable and resizable container.
+
+**HTML:**
+
+```html
+<div id="my-container" style="width: 300px; height: 200px; top: 50px; left: 50px;">
+  <div data-drag-handle>Drag Me</div>
+  <div class="content">
+    <p>This is a draggable and resizable container.</p>
+  </div>
+</div>
+```
+
+**TypeScript:**
+
+```typescript
+import { ContainerManager } from '@alekstar79/draggable-resizable-container';
+import '@alekstar79/draggable-resizable-container/styles';
+
+const containerElement = document.getElementById('my-container');
+
+if (containerElement) {
+  const manager = new ContainerManager(containerElement, {
+    // Optional configuration
+    constrainToViewport: true,
+    resize: {
+      enabled: true,
+      directions: ['n', 's', 'e', 'w', 'ne', 'nw', 'se', 'sw'],
+    },
+  });
+
+  // Listen to events
+  manager.on('dragEnd', (event) => {
+    console.log('Drag ended at:', event.state);
+  });
+}
+```
+
+## `ContainerManager` API
+
+The `ContainerManager` is the core class of the library.
+
+### `new ContainerManager(element, config)`
+
+Creates a new `ContainerManager` instance.
+
+- `element`: The `HTMLElement` to be managed.
+- `config` (optional): A `ContainerConfig` object for customization.
+
+### `ContainerConfig`
+
+| Property              | Type            | Description                                                                    |
+|-----------------------|-----------------|--------------------------------------------------------------------------------|
+| `mode`                | `MovementMode`  | `'smooth'` (default) or `'pinned'`.                                            |
+| `boundaries`          | `Boundaries`    | An object with `minWidth`, `minHeight`, `maxWidth`, `maxHeight`.               |
+| `draggingDirection`   | `DirectionMode` | `'all'` (default), `'horizontal'`, or `'vertical'`.                            |
+| `constrainToViewport` | `boolean`       | If `true`, constrains the container to the viewport. Default is `false`.       |
+| `constrainToParent`   | `boolean`       | If `true`, constrains the container to its parent element. Default is `false`. |
+| `resize`              | `ResizeConfig`  | Configuration for resizing.                                                    |
+
+### Methods
+
+- `getState(): ContainerState`: Returns the current state (`x`, `y`, `width`, `height`) of the container.
+- `setState(state: Partial<ContainerState>)`: Sets the state of the container.
+- `getMode(): MovementMode`: Returns the current movement mode.
+- `setMode(mode: MovementMode)`: Sets the movement mode.
+- `getDirection(): DirectionMode`: Returns the current dragging direction.
+- `setDirection(direction: DirectionMode)`: Sets the dragging direction.
+- `on(event: string, callback: (data: ContainerEvent) => void)`: Subscribes to an event.
+- `off(event: string, callback: (data: ContainerEvent) => void)`: Unsubscribes from an event.
+- `destroy()`: Cleans up the `ContainerManager` instance and removes event listeners.
+
+### Events
+
+You can subscribe to the following events using the `on` method:
+
+- `dragStart`, `drag`, `dragEnd`
+- `resizeStart`, `resize`, `resizeEnd`
+- `modeChange`
+- `stateChange`
+- `viewportResize`
+
+## Plugin System
+
+The library has a powerful plugin system that allows you to extend its functionality.
+
+### Using a Plugin
+
+To use a plugin, simply import it and pass it to the `use` method of your `ContainerManager` instance.
+
+```typescript
+import { ContainerManager } from '@alekstar79/draggable-resizable-container';
+import { SnappingPlugin } from '@alekstar79/draggable-resizable-container/plugins';
+
+const manager = new ContainerManager(containerElement);
+
+manager.use(new SnappingPlugin({
+  snapStep: 20,
+  enabled: true,
+}));
+```
+
+### Included Plugins
+
+#### `SnappingPlugin`
+
+Adds snapping functionality to the container.
+
+**Options:**
+
+- `snapStep`: The size of the grid to snap to (in pixels). Default is `10`.
+- `enabled`: Whether snapping is enabled. Default is `true`.
+
+**Methods added to `ContainerManager`:**
+
+- `setSnapStep(step: number)`
+- `setSnappingEnabled(enabled: boolean)`
+- `getSnappingConfig(): SnappingPluginOptions`
+
+#### `EdgeDockingPlugin`
+
+Allows containers to be "docked" to the edges of the screen.
+
+**Options:**
+
+- `edgeThreshold`: The distance from the edge (in pixels) at which docking is triggered. Default is `30`.
+- `visiblePeek`: The amount of the container (in pixels) that remains visible when docked. Default is `20`.
+
+**Methods added to `ContainerManager`:**
+
+- `isContainerDocked(element: HTMLElement): boolean`
+- `getContainerDockEdge(element: HTMLElement): Edge | null`
+
+#### `StatePersistencePlugin`
+
+Saves the state of containers to `localStorage` and restores it on page load.
+
+**Options:**
+
+- `containerId`: A unique ID for the container, required for persistence.
+- `isDemo`: A flag to indicate if the container is part of the demo (for demo-specific logic).
+
+**Example:**
+
+```typescript
+import { StatePersistencePlugin } from '@alekstar79/draggable-resizable-container/plugins';
+
+manager.use(new StatePersistencePlugin({
+  containerId: 'my-unique-container-id',
+}));
+```
+
+## Utilities
+
+The library also exports several utility classes that you can use.
+
+### `ContainerInitializer`
+
+A simple utility for creating a container element.
+
+```typescript
+import { ContainerInitializer } from '@alekstar79/draggable-resizable-container';
+
+const newContainer = ContainerInitializer.createContainerElement(400, 250, 100, 100);
+document.body.appendChild(newContainer);
+```
+
+### `ContentCreator` and `TemplateLoader`
+
+These utilities help with managing the content of your containers, including loading HTML templates.
+
+```typescript
+import { ContentCreator, getTemplateLoader, initializeTemplateSystem } from '@alekstar79/draggable-resizable-container';
+
+// Initialize the template system once in your app
+await initializeTemplateSystem();
+
+const templateLoader = getTemplateLoader();
+const contentCreator = new ContentCreator(templateLoader);
+
+// Load content from a template
+await contentCreator.createContent({ template: 'my-template-name' }, containerElement);
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Build library
+npm run build:lib
+
+# Build demo
+npm run build
+
+# Type checking
+npm run type-check
+```
+
+## Browser Support
+
+- Chrome 88+
+- Firefox 78+
+- Safari 14+
+- Edge 88+
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a pull request.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

package/dist/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aleksey Tarasenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/README.md

@@ -0,0 +1,265 @@
+# Draggable and Resizable Container
+
+[![npm version](https://img.shields.io/npm/v/draggable-resizable-container.svg)](https://www.npmjs.com/package/@alekstar79/draggable-resizable-container)
+[![Coverage](https://img.shields.io/badge/coverage-80%25-brightgreen.svg)](https://github.com/alekstar79/utils/actions)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?style=flat-square)](https://www.typescriptlang.org)
+[![Node](https://img.shields.io/badge/Node-18%2B-green?style=flat-square)](https://nodejs.org)
+[![Browser](https://img.shields.io/badge/Browser-ES2018-green)]()
+[![License MIT](https://img.shields.io/badge/License-MIT-blue)](LICENSE)
+
+A modern, lightweight, and extensible TypeScript library for creating draggable and resizable containers (windows, dialogs) in your web applications. It features a reactive core, a powerful plugin system, and a clean API.
+
+![banner](banner.svg)
+
+## Features
+
+- **Draggable & Resizable**: Smooth, performant dragging and resizing of containers with multiple handle directions.
+- **Reactive Core**: Built with `@alekstar79/reactive-event-system` for efficient state management and event handling.
+- **Extensible Plugin System**: Easily add new features like snapping, docking, or state persistence.
+- **Rich Event System**: Subscribe to a wide range of events (`dragStart`, `drag`, `dragEnd`, `resize`, etc.).
+- **Boundary Constraints**: Confine containers to the viewport or a parent element.
+- **Customizable**: Control movement direction, resize handles, and more.
+- **Touch Device Support**: Works on both desktop and mobile devices.
+- **Template Loading**: A system for loading content from HTML templates.
+- **State Persistence**: Save and restore container states using `localStorage`.
+- **TypeScript First**: Written entirely in TypeScript for strong typing and better developer experience.
+
+## Installation
+
+You can install the library using npm or yarn:
+
+```bash
+npm install @alekstar79/draggable-resizable-container
+```
+
+or
+
+```bash
+yarn add @alekstar79/draggable-resizable-container
+```
+
+You also need to import the base styles for the library to work correctly.
+
+```javascript
+import '@alekstar79/draggable-resizable-container/styles';
+```
+
+## Quick Start
+
+Here's a simple example of how to create a draggable and resizable container.
+
+**HTML:**
+
+```html
+<div id="my-container" style="width: 300px; height: 200px; top: 50px; left: 50px;">
+  <div data-drag-handle>Drag Me</div>
+  <div class="content">
+    <p>This is a draggable and resizable container.</p>
+  </div>
+</div>
+```
+
+**TypeScript:**
+
+```typescript
+import { ContainerManager } from '@alekstar79/draggable-resizable-container';
+import '@alekstar79/draggable-resizable-container/styles';
+
+const containerElement = document.getElementById('my-container');
+
+if (containerElement) {
+  const manager = new ContainerManager(containerElement, {
+    // Optional configuration
+    constrainToViewport: true,
+    resize: {
+      enabled: true,
+      directions: ['n', 's', 'e', 'w', 'ne', 'nw', 'se', 'sw'],
+    },
+  });
+
+  // Listen to events
+  manager.on('dragEnd', (event) => {
+    console.log('Drag ended at:', event.state);
+  });
+}
+```
+
+## `ContainerManager` API
+
+The `ContainerManager` is the core class of the library.
+
+### `new ContainerManager(element, config)`
+
+Creates a new `ContainerManager` instance.
+
+- `element`: The `HTMLElement` to be managed.
+- `config` (optional): A `ContainerConfig` object for customization.
+
+### `ContainerConfig`
+
+| Property              | Type            | Description                                                                    |
+|-----------------------|-----------------|--------------------------------------------------------------------------------|
+| `mode`                | `MovementMode`  | `'smooth'` (default) or `'pinned'`.                                            |
+| `boundaries`          | `Boundaries`    | An object with `minWidth`, `minHeight`, `maxWidth`, `maxHeight`.               |
+| `draggingDirection`   | `DirectionMode` | `'all'` (default), `'horizontal'`, or `'vertical'`.                            |
+| `constrainToViewport` | `boolean`       | If `true`, constrains the container to the viewport. Default is `false`.       |
+| `constrainToParent`   | `boolean`       | If `true`, constrains the container to its parent element. Default is `false`. |
+| `resize`              | `ResizeConfig`  | Configuration for resizing.                                                    |
+
+### Methods
+
+- `getState(): ContainerState`: Returns the current state (`x`, `y`, `width`, `height`) of the container.
+- `setState(state: Partial<ContainerState>)`: Sets the state of the container.
+- `getMode(): MovementMode`: Returns the current movement mode.
+- `setMode(mode: MovementMode)`: Sets the movement mode.
+- `getDirection(): DirectionMode`: Returns the current dragging direction.
+- `setDirection(direction: DirectionMode)`: Sets the dragging direction.
+- `on(event: string, callback: (data: ContainerEvent) => void)`: Subscribes to an event.
+- `off(event: string, callback: (data: ContainerEvent) => void)`: Unsubscribes from an event.
+- `destroy()`: Cleans up the `ContainerManager` instance and removes event listeners.
+
+### Events
+
+You can subscribe to the following events using the `on` method:
+
+- `dragStart`, `drag`, `dragEnd`
+- `resizeStart`, `resize`, `resizeEnd`
+- `modeChange`
+- `stateChange`
+- `viewportResize`
+
+## Plugin System
+
+The library has a powerful plugin system that allows you to extend its functionality.
+
+### Using a Plugin
+
+To use a plugin, simply import it and pass it to the `use` method of your `ContainerManager` instance.
+
+```typescript
+import { ContainerManager } from '@alekstar79/draggable-resizable-container';
+import { SnappingPlugin } from '@alekstar79/draggable-resizable-container/plugins';
+
+const manager = new ContainerManager(containerElement);
+
+manager.use(new SnappingPlugin({
+  snapStep: 20,
+  enabled: true,
+}));
+```
+
+### Included Plugins
+
+#### `SnappingPlugin`
+
+Adds snapping functionality to the container.
+
+**Options:**
+
+- `snapStep`: The size of the grid to snap to (in pixels). Default is `10`.
+- `enabled`: Whether snapping is enabled. Default is `true`.
+
+**Methods added to `ContainerManager`:**
+
+- `setSnapStep(step: number)`
+- `setSnappingEnabled(enabled: boolean)`
+- `getSnappingConfig(): SnappingPluginOptions`
+
+#### `EdgeDockingPlugin`
+
+Allows containers to be "docked" to the edges of the screen.
+
+**Options:**
+
+- `edgeThreshold`: The distance from the edge (in pixels) at which docking is triggered. Default is `30`.
+- `visiblePeek`: The amount of the container (in pixels) that remains visible when docked. Default is `20`.
+
+**Methods added to `ContainerManager`:**
+
+- `isContainerDocked(element: HTMLElement): boolean`
+- `getContainerDockEdge(element: HTMLElement): Edge | null`
+
+#### `StatePersistencePlugin`
+
+Saves the state of containers to `localStorage` and restores it on page load.
+
+**Options:**
+
+- `containerId`: A unique ID for the container, required for persistence.
+- `isDemo`: A flag to indicate if the container is part of the demo (for demo-specific logic).
+
+**Example:**
+
+```typescript
+import { StatePersistencePlugin } from '@alekstar79/draggable-resizable-container/plugins';
+
+manager.use(new StatePersistencePlugin({
+  containerId: 'my-unique-container-id',
+}));
+```
+
+## Utilities
+
+The library also exports several utility classes that you can use.
+
+### `ContainerInitializer`
+
+A simple utility for creating a container element.
+
+```typescript
+import { ContainerInitializer } from '@alekstar79/draggable-resizable-container';
+
+const newContainer = ContainerInitializer.createContainerElement(400, 250, 100, 100);
+document.body.appendChild(newContainer);
+```
+
+### `ContentCreator` and `TemplateLoader`
+
+These utilities help with managing the content of your containers, including loading HTML templates.
+
+```typescript
+import { ContentCreator, getTemplateLoader, initializeTemplateSystem } from '@alekstar79/draggable-resizable-container';
+
+// Initialize the template system once in your app
+await initializeTemplateSystem();
+
+const templateLoader = getTemplateLoader();
+const contentCreator = new ContentCreator(templateLoader);
+
+// Load content from a template
+await contentCreator.createContent({ template: 'my-template-name' }, containerElement);
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Build library
+npm run build:lib
+
+# Build demo
+npm run build
+
+# Type checking
+npm run type-check
+```
+
+## Browser Support
+
+- Chrome 88+
+- Firefox 78+
+- Safari 14+
+- Edge 88+
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a pull request.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).