@clevertask/react-sortable-tree 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 CleverTask
+
+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,183 @@
+# @clevertask/react-sortable-tree
+
+A customizable React component for rendering and managing tree structures with drag-and-drop functionality.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+- [Props](#props)
+- [Types](#types)
+  - [TreeItem](#treeitem)
+  - [TreeItems](#treeitems)
+  - [OptimizedTreeStructure](#optimizedtreestructure)
+- [Helper Functions](#helper-functions)
+  - [createOptimizedTreeStructure](#createoptimizedtreestructure)
+  - [removeItemById](#removeitembyid)
+  - [setTreeItemProperties](#settreeitemproperties)
+- [Roadmap](#roadmap)
+- [Release Process](#release-process)
+- [License](#license)
+
+## Installation
+
+```bash
+npm install @clevertask/react-sortable-tree
+```
+
+## Usage
+
+```tsx
+import '@clevertask/react-sortable-tree/dist/style.css';
+import { SortableTree, createOptimizedTreeStructure } from '@clevertask/react-sortable-tree';
+
+function App() {
+  const [treeStructure, setTreeStructure] = useState(createOptimizedTreeStructure([
+    { id: '1', label: 'Item 1', children: [] },
+    { id: '2', label: 'Item 2', children: [
+      { id: '3', label: 'Item 2.1', children: [] }
+    ] },
+  ]));
+
+  return (
+    <SortableTree
+      items={treeStructure.items}
+      onItemsChange={setTreeStructure}
+      isCollapsible
+      isRemovable
+      allowNestedItemAddition
+      // ... other props
+    />
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `TreeItems` | Required | The array of tree items to be rendered. |
+| `onItemsChange` | `React.Dispatch<React.SetStateAction<OptimizedTreeStructure>>` | Required | Callback function called when the tree structure changes. |
+| `indentationWidth` | `number` | `undefined` | The indentation width for children elements. |
+| `isCollapsible` | `boolean` | `false` | Determines if tree items can be collapsed/expanded. |
+| `onLazyLoadChildren` | `(id: UniqueIdentifier, isExpanding: boolean) => Promise<void>` | `undefined` | Callback for lazy loading child items when a parent is expanded. Useful for getting child items from an API endpoint |
+| `showDropIndicator` | `boolean` | `false` | Determines if a drop indicator should be shown when dragging items. |
+| `isRemovable` | `boolean` | `false` | Determines if items can be removed from the tree. |
+| `onRemoveItem` | `(id: UniqueIdentifier) => void` | `undefined` | Callback function called when an item is removed from the tree. |
+| `allowNestedItemAddition` | `boolean` | `false` | Determines if new items can be added as children to existing items. |
+| `onAddItem` | `(parentId: UniqueIdentifier \| null) => void` | `undefined` | Callback function called when a new item is added to the tree. |
+| `onDragEnd` | `(result: DropResult) => void` | `undefined` | Callback function called when a drag operation ends. |
+| `onItemClick` | `(id: UniqueIdentifier) => void` | `undefined` | Callback function called when an item in the tree is clicked. |
+
+## Types
+
+### TreeItem
+
+```typescript
+type TreeItem = {
+  id: UniqueIdentifier;
+  label: string;
+  children: TreeItem[];
+  collapsed?: boolean;
+  canFetchChildren?: boolean;
+  disableDragging?: boolean;
+  [key: string]: any;
+};
+```
+
+### TreeItems
+
+```typescript
+type TreeItems = TreeItem[];
+```
+
+### OptimizedTreeStructure
+
+```typescript
+interface OptimizedTreeStructure {
+  items: TreeItems;
+  itemMap: Map<UniqueIdentifier, TreeItem>;
+}
+```
+
+The `OptimizedTreeStructure` is used internally to improve performance for large trees. Use the `createOptimizedTreeStructure` function to create this structure from a `TreeItems` array.
+
+## Helper Functions
+
+### createOptimizedTreeStructure
+
+```typescript
+function createOptimizedTreeStructure(items: TreeItems): OptimizedTreeStructure
+```
+
+### removeItemById
+
+```typescript
+function removeItemById(structure: OptimizedTreeStructure, id: UniqueIdentifier): OptimizedTreeStructure
+```
+
+This function removes an item from the tree structure by its ID. It returns a new `OptimizedTreeStructure` with the item removed from both the `items` array and the `itemMap`. It also handles removing the item from nested children.
+
+Usage example:
+
+```typescript
+const updatedStructure = removeItemById(currentStructure, '123');
+setTreeStructure(updatedStructure);
+```
+
+### setTreeItemProperties
+
+```typescript
+function setTreeItemProperties(
+  structure: OptimizedTreeStructure,
+  id: UniqueIdentifier,
+  setter: (value: TreeItem) => Partial<TreeItem>
+): OptimizedTreeStructure
+```
+
+This function updates the properties of a specific tree item. It takes a setter function that receives the current item and returns an object with the properties to be updated. It returns a new `OptimizedTreeStructure` with the updated item in both the `items` array and the `itemMap`.
+
+Usage example:
+
+```typescript
+setTreeStructure((treeStructure) => {
+  return setTreeItemProperties(
+    treeStructure,
+    '123',
+    (item) => ({ label: 'New Label', collapsed: !item.collapsed })
+  );
+});
+```
+
+These helper functions are designed to work with the `OptimizedTreeStructure` to ensure efficient updates to the tree. They maintain both the tree hierarchy in the `items` array and the fast lookup `O(1)` capability of the `itemMap`.
+
+Use this function to create an `OptimizedTreeStructure` from a `TreeItems` array. This is useful when initializing your state.
+
+## Roadmap
+
+We're constantly working to improve @clevertask/react-sortable-tree. Here are some features we're planning to implement:
+
+- **Virtualization**: Improve performance for large trees by only rendering visible nodes.
+- **Custom item rendering**: Allow users to provide custom components for rendering tree items.
+- **Selection and Multi-selection**: Add support for selecting one or multiple items in the tree.
+- **Drag multiple items**: Enable dragging and dropping multiple selected items at once.
+- **API Example**: Provide a comprehensive example illustrating real-world usage with a backend API.
+- **E2E tests**: It will ensure this component's working as expected.
+
+We're excited about these upcoming features and welcome any feedback or contributions from the community. If you have any suggestions or would like to contribute to any of these features, please open an issue or submit a pull request on our GitHub repository.
+
+## Release Process
+
+This package is automatically published to npm when a new release is created on GitHub. To create a new release:
+
+1. Update the version in `package.json` according to semantic versioning rules.
+2. Commit the version change: `git commit -am "Bump version to x.x.x"`
+3. Create a new tag: `git tag vx.x.x`
+4. Push the changes and the tag: `git push && git push --tags`
+5. Go to the GitHub repository and create a new release, selecting the tag you just created.
+
+The GitHub Action will automatically build, test, and publish the new version to npm.
+
+## License
+
+MIT

package/dist/SortableTree/SortableTree.d.ts

@@ -0,0 +1,4 @@
+import { SortableTreeProps } from './types';
+declare function PrivateSortableTree({ items, onItemsChange: setItems, isCollapsible, onLazyLoadChildren, showDropIndicator, indentationWidth, isRemovable, onRemoveItem, allowNestedItemAddition, onAddItem, onDragEnd, onItemClick, }: SortableTreeProps): import("react/jsx-runtime").JSX.Element;
+export declare const SortableTree: import('react').MemoExoticComponent<typeof PrivateSortableTree>;
+export {};

package/dist/SortableTree/components/Action/Action.d.ts

@@ -0,0 +1,9 @@
+import { default as React, CSSProperties } from 'react';
+export interface Props extends React.HTMLAttributes<HTMLButtonElement> {
+    active?: {
+        fill: string;
+        background: string;
+    };
+    cursor?: CSSProperties['cursor'];
+}
+export declare const Action: React.ForwardRefExoticComponent<Props & React.RefAttributes<HTMLButtonElement>>;

package/dist/SortableTree/components/Action/index.d.ts

@@ -0,0 +1,2 @@
+export { Action } from './Action';
+export type { Props as ActionProps } from './Action';

package/dist/SortableTree/components/Add/Add.d.ts

@@ -0,0 +1,2 @@
+import { ActionProps } from '../Action';
+export declare function Add(props: ActionProps): import("react/jsx-runtime").JSX.Element;

package/dist/SortableTree/components/Add/index.d.ts

@@ -0,0 +1 @@
+export { Add } from './Add';

package/dist/SortableTree/components/Handle/Handle.d.ts

@@ -0,0 +1,2 @@
+import { ActionProps } from '../Action';
+export declare const Handle: import('react').ForwardRefExoticComponent<ActionProps & import('react').RefAttributes<HTMLButtonElement>>;

package/dist/SortableTree/components/Handle/index.d.ts

@@ -0,0 +1 @@
+export { Handle } from './Handle';

package/dist/SortableTree/components/Remove/Remove.d.ts

@@ -0,0 +1,2 @@
+import { ActionProps } from '../Action';
+export declare function Remove(props: ActionProps): import("react/jsx-runtime").JSX.Element;

package/dist/SortableTree/components/Remove/index.d.ts

@@ -0,0 +1 @@
+export { Remove } from './Remove';

package/dist/SortableTree/components/TreeItem/SortableTreeItem.d.ts

@@ -0,0 +1,8 @@
+import { UniqueIdentifier } from '@dnd-kit/core';
+import { Props as TreeItemProps } from './TreeItem';
+interface Props extends TreeItemProps {
+    id: UniqueIdentifier;
+}
+declare function PrivateSortableTreeItem({ id, depth, ...props }: Props): import("react/jsx-runtime").JSX.Element;
+export declare const SortableTreeItem: import('react').MemoExoticComponent<typeof PrivateSortableTreeItem>;
+export {};

package/dist/SortableTree/components/TreeItem/TreeItem.d.ts

@@ -0,0 +1,22 @@
+import { default as React, HTMLAttributes } from 'react';
+export interface Props extends Omit<HTMLAttributes<HTMLLIElement>, "id"> {
+    childCount?: number;
+    clone?: boolean;
+    collapsed?: boolean;
+    depth: number;
+    disableInteraction?: boolean;
+    disableSelection?: boolean;
+    disableDragging?: boolean;
+    ghost?: boolean;
+    handleProps?: any;
+    indicator?: boolean;
+    indentationWidth: number;
+    value: string;
+    onCollapse?(): void;
+    onRemove?(): void;
+    onAdd?(): void;
+    onLabelClick?(): void;
+    wrapperRef?(node: HTMLLIElement): void;
+}
+export declare const _TreeItem: React.ForwardRefExoticComponent<Props & React.RefAttributes<HTMLDivElement>>;
+export declare const TreeItem: React.MemoExoticComponent<React.ForwardRefExoticComponent<Props & React.RefAttributes<HTMLDivElement>>>;

package/dist/SortableTree/components/TreeItem/index.d.ts

@@ -0,0 +1,2 @@
+export { TreeItem } from './TreeItem';
+export { SortableTreeItem } from './SortableTreeItem';

package/dist/SortableTree/components/index.d.ts

@@ -0,0 +1 @@
+export { TreeItem, SortableTreeItem } from './TreeItem';

package/dist/SortableTree/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export { SortableTree } from './SortableTree';
+export { setTreeItemProperties, removeItemById, createOptimizedTreeStructure } from './utilities';

package/dist/SortableTree/keyboardCoordinates.d.ts

@@ -0,0 +1,3 @@
+import { KeyboardCoordinateGetter } from '@dnd-kit/core';
+import { SensorContext } from './types';
+export declare const sortableTreeKeyboardCoordinates: (context: SensorContext, indicator: boolean, indentationWidth: number) => KeyboardCoordinateGetter;

package/dist/SortableTree/types.d.ts

@@ -0,0 +1,138 @@
+import { MutableRefObject } from 'react';
+import { UniqueIdentifier } from '@dnd-kit/core';
+export interface OptimizedTreeStructure {
+    items: TreeItems;
+    itemMap: Map<UniqueIdentifier, TreeItem>;
+}
+/**
+ * Represents an item in the tree structure.
+ */
+export type TreeItem = {
+    /**
+     * Unique identifier for the item. Can be a string or number.
+     */
+    id: UniqueIdentifier;
+    /**
+     * The text label displayed for the item in the tree.
+     */
+    label: string;
+    /**
+     * An array of child TreeItems. If empty, the item is a leaf node.
+     */
+    children: TreeItem[];
+    /**
+     * Determines whether the item's children are initially collapsed.
+     * @default false
+     */
+    collapsed?: boolean;
+    /**
+     * Indicates whether this item can lazy-load its children.
+     * When true, children will be fetched on expansion if the children array is empty.
+     * This is useful for optimizing initial render performance with large trees.
+     * @default false
+     */
+    canFetchChildren?: boolean;
+    /**
+     * When true, prevents this item from being dragged.
+     * Useful for creating fixed or header items in the tree.
+     * @default false
+     */
+    disableDragging?: boolean;
+    /**
+     * Any additional custom properties can be added here.
+     */
+    [key: string]: any;
+};
+export type TreeItems = TreeItem[];
+export interface FlattenedItem extends TreeItem {
+    parentId: UniqueIdentifier | null;
+    depth: number;
+    index: number;
+}
+export type SensorContext = MutableRefObject<{
+    items: FlattenedItem[];
+    offset: number;
+}>;
+/**
+ * Props for the SortableTree component.
+ */
+export interface SortableTreeProps {
+    /**
+     * A control that lets you add the indentation width for children elements
+     */
+    indentationWidth?: number;
+    /**
+     * The array of tree items to be rendered.
+     */
+    items: TreeItems;
+    /**
+     * Callback function called when the tree structure changes.
+     * @param items - The updated array of tree items.
+     */
+    onItemsChange: React.Dispatch<React.SetStateAction<OptimizedTreeStructure>>;
+    /**
+     * Determines if tree items can be collapsed/expanded.
+     * @default false
+     */
+    isCollapsible?: boolean;
+    /**
+     * Callback function for lazy loading child items when a parent is expanded.
+     * It only works if the item has the `canFetchChildren` property
+     * @param id - The id of the parent item being expanded.
+     * @param isExpanding - True if the item is being expanded, false if collapsing.
+     */
+    onLazyLoadChildren?: (id: UniqueIdentifier, isExpanding: boolean) => Promise<void>;
+    /**
+     * Determines if a drop indicator should be shown when dragging items.
+     * @default false
+     */
+    showDropIndicator?: boolean;
+    /**
+     * Determines if items can be removed from the tree.
+     * @default false
+     */
+    isRemovable?: boolean;
+    /**
+     * Callback function called when an item is removed from the tree.
+     * @param id - The id of the item being removed.
+     */
+    onRemoveItem?: (id: UniqueIdentifier) => void;
+    /**
+     * Determines if new items can be added as children to existing items.
+     * @default false
+     */
+    allowNestedItemAddition?: boolean;
+    /**
+     * Callback function called when a new item is added to the tree.
+     * @param parentId - The id of the parent item, or null if adding a root item.
+     */
+    onAddItem?: (parentId: UniqueIdentifier | null) => void;
+    /**
+     * Callback function called when a drag operation ends.
+     * @param result - An object containing information about the drag operation.
+     */
+    onDragEnd?: (result: DropResult) => void;
+    /**
+     * Callback function called when an item in the tree is clicked.
+     * @param id - The id of the clicked item.
+     */
+    onItemClick?: (id: UniqueIdentifier) => void;
+}
+/**
+ * Represents the result of a drag operation in the tree.
+ */
+export type DropResult = {
+    /**
+     * The item that was dragged.
+     */
+    movedItem: TreeItem;
+    /**
+     * The new parent of the dragged item, or null if it's now a root item.
+     */
+    parent: UniqueIdentifier | null;
+    /**
+     * The new index of the dragged item within its parent's children array.
+     */
+    index: number;
+} | null;
+export type { UniqueIdentifier } from '@dnd-kit/core';

package/dist/SortableTree/utilities.d.ts

@@ -0,0 +1,18 @@
+import { UniqueIdentifier } from '@dnd-kit/core';
+import { FlattenedItem, OptimizedTreeStructure, TreeItem, TreeItems } from './types';
+export declare const iOS: boolean;
+export declare function getProjection(items: FlattenedItem[], activeId: UniqueIdentifier, overId: UniqueIdentifier, dragOffset: number, indentationWidth: number): {
+    depth: number;
+    maxDepth: number;
+    minDepth: number;
+    parentId: UniqueIdentifier | null;
+};
+export declare function flattenTree(items: TreeItems): FlattenedItem[];
+export declare function buildTree(flattenedItems: FlattenedItem[]): TreeItems;
+export declare function findItem(items: TreeItem[], itemId: UniqueIdentifier): TreeItem | undefined;
+export declare function findItemDeep(items: TreeItems, itemId: UniqueIdentifier): TreeItem | undefined;
+export declare function removeItemById(structure: OptimizedTreeStructure, id: UniqueIdentifier): OptimizedTreeStructure;
+export declare function setTreeItemProperties(structure: OptimizedTreeStructure, id: UniqueIdentifier, setter: (value: TreeItem) => Partial<TreeItem>): OptimizedTreeStructure;
+export declare function createOptimizedTreeStructure(items: TreeItems): OptimizedTreeStructure;
+export declare function getChildCount(items: TreeItems, id: UniqueIdentifier): number;
+export declare function removeChildrenOf(items: FlattenedItem[], ids: UniqueIdentifier[]): FlattenedItem[];

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './SortableTree';

package/dist/main.d.ts

@@ -0,0 +1 @@
+export {};