Vue Draggable Sortable Tree Component

Common errors

• Uncaught ReferenceError: require is not defined

  cause Attempting to use CommonJS `require()` syntax in a modern Vue 3 project (e.g., with Vite or a browser-based bundler that expects ES Modules).
  fix Change `const { Draggable } = require('he-tree-vue')` to `import { Draggable } from 'he-tree-vue'` and ensure your project's build configuration (e.g., `vite.config.ts`) is set up for ES Modules.

• npm ERR! ERESOLVE unable to resolve dependency tree \n npm ERR! Found: vue@^2.x.x \n npm ERR! Could not resolve dependency: \n npm ERR! peer vue@"^3.0.0" from he-tree-vue@3.x.x

  cause `he-tree-vue` is a Vue 3 component, but your project is either using Vue 2 or has a conflicting Vue 2 dependency in its tree.
  fix Ensure your project explicitly installs Vue 3 (`npm install vue@^3.0.0`) and that no other dependencies are forcing Vue 2. If migrating, fully upgrade your project to Vue 3. Use `npm install --legacy-peer-deps` as a temporary workaround if direct resolution is difficult, but prioritize fixing the dependency tree.

• Property 'text' does not exist on type 'TreeDataItem' or 'Property 'children' does not exist on type 'TreeDataItem'

  cause Your tree data items do not conform to the expected type `TreeDataItem` or your custom interface for `he-tree-vue`.
  fix Define a TypeScript interface for your tree nodes that extends `TreeDataItem` and explicitly includes properties like `text` and `children`, as shown in the quickstart. Ensure all your data objects adhere to this interface.

Warnings

• breaking This library is designed for Vue 3. Migrating an existing Vue 2 application or components to use `he-tree-vue` will require a full Vue 3 migration, which involves significant breaking changes to global APIs, template directives, component options, and reactivity system. It is not a drop-in replacement for Vue 2 tree components.
  Fix: Consult the official Vue 3 Migration Guide (v3.vuejs.org/guide/migration/introduction.html) and update your entire Vue application and its dependencies to Vue 3 before integrating `he-tree-vue`.
• gotcha The `updateBehavior` prop controls how `v-model` data changes are emitted. By default ('modify'), it directly modifies the bound data. If set to 'new', it emits a completely new data object. This is crucial for state management patterns (e.g., Vuex/Pinia) where immutability might be preferred or required.
  Fix: Always check the `updateBehavior` prop and set it to `'new'` if your state management system (e.g., Pinia, Vuex) requires immutable data updates or if you prefer a new data object on changes to simplify change detection. Otherwise, be aware that the original `v-model` array/object will be mutated directly.
• gotcha The component relies on JavaScript to set the `padding-left` for indentation of `tree-node-back` elements. Overriding this with custom CSS `padding-left` will break the tree's visual structure and indentation logic.
  Fix: Avoid applying custom `padding-left` directly to `.tree-node-back` or similar internal elements. Adjust indentation using the `indent` prop provided by the component or other CSS properties like `margin-left` on parent elements if necessary, ensuring not to interfere with the component's internal indentation styling.

Install

• npm install he-tree-vue npm
• yarn add he-tree-vue yarn
• pnpm add he-tree-vue pnpm

Imports

• Draggable
  wrong:

  const Draggable = require('he-tree-vue').Draggable

  correct:

  import { Draggable } from 'he-tree-vue'

  Draggable is the main component for a draggable and sortable tree. CommonJS `require` is not supported in modern Vue 3/Vite projects; use ES Module `import`.
• BaseTree

  import { BaseTree } from 'he-tree-vue'

  BaseTree is the foundational tree component that Draggable extends. Useful for basic, non-draggable trees.
• TreeDataItem

  import type { TreeDataItem } from 'he-tree-vue'

  Import types for enhanced type safety when defining your tree data structure. The library provides comprehensive TypeScript definitions.
• CSS Styles

  import 'he-tree-vue/style/default.css'

  Essential default styles for the tree component, including placeholders and basic layout. Omission will result in an unstyled component.

Quickstart

Demonstrates a basic draggable and sortable tree component using `he-tree-vue` with Vue 3's `<script setup>`, TypeScript, and custom styling. It shows data binding, event handling for drag-and-drop, and dynamic node addition.

<template>
  <div id="app">
    <h1>My Draggable Tree</h1>
    <Draggable
      v-model="treeData"
      :indent="20"
      :eachNodeAttributes="(node) => ({ 'data-id': node.id })"
      @change="onTreeChange"
      @node-drop="onNodeDrop"
      class="my-custom-tree"
    >
      <template #default="{ node, index, path, tree }">
        <div class="tree-node-back">
          {{ node.text }}
          <button @click="addNode(node)">Add Child</button>
        </div>
      </template>
    </Draggable>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { Draggable, type TreeDataItem } from 'he-tree-vue';
import 'he-tree-vue/style/default.css';

interface MyTreeDataItem extends TreeDataItem {
  id: number;
  text: string;
  children?: MyTreeDataItem[];
}

let nextId = 4;

const treeData = ref<MyTreeDataItem[]>([
  { id: 1, text: 'Node 1', children: [
    { id: 2, text: 'Node 1.1' },
    { id: 3, text: 'Node 1.2' }
  ]}
]);

const onTreeChange = (data: MyTreeDataItem[]) => {
  console.log('Tree data changed:', data);
};

const onNodeDrop = (dragInfo: any) => {
  console.log('Node dropped:', dragInfo);
  // You might want to persist the updated treeData to a backend here
};

const addNode = (parentNode: MyTreeDataItem) => {
  if (!parentNode.children) {
    parentNode.children = [];
  }
  const newNode: MyTreeDataItem = { id: nextId++, text: `New Child of ${parentNode.text}` };
  parentNode.children.push(newNode);
  console.log('Added new node:', newNode);
};
</script>

<style>
.my-custom-tree {
  border: 1px solid #eee;
  padding: 10px;
  min-height: 100px;
}
.tree-node-back {
  padding: 5px;
  border: 1px solid #ccc;
  margin: 2px 0;
  background-color: #f9f9f9;
  display: flex;
  justify-content: space-between;
  align-items: center;
}
.he-tree-drag-placeholder {
  background-color: #e0f2f7 !important; /* Light blue placeholder */
  border: 1px dashed #90caf9 !important;
}
</style>