@clevertask/react-sortable-tree 0.0.5 → 0.0.7

package/README.md

@@ -1,6 +1,10 @@
 # @clevertask/react-sortable-tree
 
-A customizable React component for rendering and managing tree structures with drag-and-drop functionality. This is built on top of the [sortable tree Component from the dnd-kit library](https://github.com/clauderic/dnd-kit/blob/master/stories/3%20-%20Examples/Tree/SortableTree.tsx).
+A customizable React component for rendering and managing tree structures with drag-and-drop functionality. Built on top of the [dnd-kit sortable tree example](https://github.com/clauderic/dnd-kit/blob/master/stories/3%20-%20Examples/Tree/SortableTree.tsx).
+
+This library is currently focused on **custom item rendering** and **type-safe tree structures**. A more detailed API and feature set will be released in a future major version with support for virtualization and multi-selection.
+
+---
 
 ## Table of Contents
 
@@ -8,54 +12,193 @@ A customizable React component for rendering and managing tree structures with d
 - [Usage](#usage)
 - [Props](#props)
 - [Types](#types)
-  - [TreeItem](#treeitem)
-  - [TreeItems](#treeitems)
 - [Helper Functions](#helper-functions)
-  - [getItemById](#getItemById)
-  - [removeItemById](#removeitembyid)
-  - [setTreeItemProperties](#settreeitemproperties)
 - [Roadmap](#roadmap)
-- [Release Process](#release-process)
 - [License](#license)
 
+---
+
 ## Installation
 
 ```bash
 npm install @clevertask/react-sortable-tree
 ```
 
+---
+
 ## Usage
 
+### 1. Define your custom tree item type if needed
+
+```ts
+type CustomTreeItem = TreeItem<{
+  metadata?: Record<string, any>;
+  icon?: string;
+}>;
+```
+
+Otherwise, the component will use the default [tree item type](#types).
+
+---
+
+### 2. Create your custom item component
+
+This is the basic structure you can start with:
+
 ```tsx
-import '@clevertask/react-sortable-tree/dist/style.css';
-import React, { useState } from 'react';
-import { SortableTree, TreeItems } from '@clevertask/react-sortable-tree';
+import {
+  RenderItemProps,
+  TreeItemStructure,
+  createSortableTreeGlobalStyles,
+  RenderItemProps,
+} from '@clevertask/react-sortable-tree';
+
+export const TreeItem = ({ treeItem, collapsed, onCollapse, ...rest }: RenderItemProps) => {
+  <TreeItemStructure {...rest}>
+    <button {...dragListeners}>Drag me</button>
+    {onCollapse && <button onClick={onCollapse}>{collapsed ? 'Expand' : 'Collapse'}</button>}
+
+    <h5>{treeItem.label}</h5>
+
+    <button onClick={() => openItemInfoModal(treeItem.id)}>Show treeItem info</button>
+  </TreeItemStructure>;
+};
+```
+
+This is a real-world example using Radix:
 
-function App() {
-  const [items, setItems] = useState<TreeItems>([
-    { id: '1', label: 'Item 1', children: [] },
-    { id: '2', label: 'Item 2', children: [{ id: '3', label: 'Item 2.1', children: [] }] },
-  ]);
+```tsx
+import {
+  RenderItemProps,
+  TreeItemStructure,
+  createSortableTreeGlobalStyles,
+  TreeItem as TTreeItem,
+} from '@clevertask/react-sortable-tree';
+import {
+  DragHandleDots2Icon,
+  ChevronRightIcon,
+  ChevronDownIcon,
+  TrashIcon,
+  PlusIcon,
+} from '@radix-ui/react-icons';
+import { Flex, Button, Text, Box } from '@radix-ui/themes';
+import { CustomTreeItem } from '.';
+
+export const TreeItem = ({
+  treeItem,
+  dragListeners,
+  onCollapse,
+  collapsed,
+  onClickAddNestedItemButton,
+  onClickItemRemoveButton,
+  onItemClick,
+  ...rest
+}: RenderItemProps<CustomTreeItem> & {
+  onClickAddNestedItemButton: (id: string) => void;
+  onClickItemRemoveButton: (id: string) => void;
+  onItemClick: (id: string) => void;
+}) => {
+  const useSortableTreeGlobalStyles = createSortableTreeGlobalStyles({
+    indicatorColor: 'var(--orange-7)',
+    indicatorBorderColor: 'var(--orange-7)',
+  });
+
+  useSortableTreeGlobalStyles();
 
   return (
-    <SortableTree
-      items={items}
-      setItems={setItems}
-      isCollapsible
-      isRemovable
-      allowNestedItemAddition
-      // ... other props
-    />
+    <TreeItemStructure
+      {...rest}
+      asDropZone={Box}
+      asDraggableItem={Box}
+      draggableItemStyle={{
+        display: 'flex',
+        justifyContent: 'space-between',
+        padding: '1rem',
+        border: '1px solid var(--gray-3)',
+        background: 'var(--color-background)',
+      }}
+    >
+      <Flex align="center" gap="5" direction="row">
+        <Button color="gray" variant="ghost" {...dragListeners}>
+          <DragHandleDots2Icon />
+        </Button>
+
+        {onCollapse && (
+          <Button color="gray" variant="ghost" onClick={onCollapse}>
+            {collapsed ?
+              <ChevronRightIcon />
+            : <ChevronDownIcon />}
+          </Button>
+        )}
+
+        <Text style={{ cursor: 'pointer' }} onClick={() => onItemClick(treeItem.id)}>
+          {treeItem.label} {treeItem.metadata.foo}
+        </Text>
+      </Flex>
+
+      <Flex align="center" gap="3" direction="row">
+        <Button variant="ghost" color="red" onClick={() => onClickItemRemoveButton(treeItem.id)}>
+          <TrashIcon />
+        </Button>
+        <Button
+          variant="ghost"
+          color="gray"
+          onClick={() => onClickAddNestedItemButton(treeItem.id)}
+        >
+          <PlusIcon />
+        </Button>
+      </Flex>
+    </TreeItemStructure>
   );
-}
+};
+```
+
+The `<TreeItemStructure/>` appends the dataSlots (for CSS styles), dropzone, and drag item container listeners and refs so you don't have to do it from scratch, but it's possible making your custom tree items without that component.
+
+---
+
+### 3. Use the `SortableTree` with your custom item
+
+```tsx
+import React, { useState } from 'react';
+import { TreeItems, SortableTree } from '@clevertask/react-sortable-tree';
+type CustomTreeItem = TreeItem<{ metadata?: Record<string, string> }>;
+
+const [items, setItems] = useState<TreeItems<CustomTreeItem>>([
+  { id: '1', label: 'Item 1', children: [] },
+  {
+    id: '2',
+    label: 'Item 2',
+    children: [{ id: '3', label: 'Item 2.1', children: [] }],
+    metadata: { foo: 'foo' },
+  },
+]);
+
+<SortableTree<CustomTreeItem>
+  isCollapsible
+  showDropIndicator
+  items={items}
+  setItems={setItems}
+  renderItem={(props: RenderItemProps<CustomTreeItem>) => (
+    <TreeItem
+      {...props}
+      onClickAddNestedItemButton={onClickAddNestedItemButton}
+      onClickItemRemoveButton={onClickItemRemoveButton}
+      onItemClick={onItemClick}
+    />
+  )}
+/>;
 ```
 
+---
+
 ## Props
 
 | Prop                      | Type                                                            | Default     | Description                                                                                                          |
 | ------------------------- | --------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------- |
-| `items`                   | `TreeItems`                                                     | Required    | The array of tree items to be rendered.                                                                              |
-| `setItems`                | `React.Dispatch<React.SetStateAction<TreeItems>>`               | Required    | Callback function called when the tree items array changes.                                                          |
+| `items`                   | `TreeItems<T>`                                                  | Required    | The array of tree items to be rendered.                                                                              |
+| `setItems`                | `(items: TreeItems<T>) => void`                                 | Required    | Callback function called when the tree items array changes.                                                          |
+| `renderItem`              | `(props: RenderItemProps<T>) => React.ReactNode`                | Required    | Function to render each tree item.                                                                                   |
 | `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 |
@@ -67,106 +210,122 @@ function App() {
 | `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 = {
+```ts
+type TreeItem<ExtraProps = unknown> = {
   id: UniqueIdentifier;
   label: string;
-  children: TreeItem[];
+  children: TreeItem<ExtraProps>[];
   collapsed?: boolean;
   canFetchChildren?: boolean;
   disableDragging?: boolean;
-  [key: string]: any;
-};
+} & ExtraProps;
 ```
 
 ### TreeItems
 
-```typescript
-type TreeItems = TreeItem[];
+```ts
+type TreeItems<T = TreeItem> = T[];
 ```
 
-## Helper Functions
-
-### getItemById
-
-```typescript
-function getItemById(items: TreeItems, id: UniqueIdentifier): TreeItem | undefined;
+### TreeStructureProps
+
+```ts
+export interface TreeItemStructureProps {
+  dropZoneRef: (element: HTMLElement | null) => void;
+  draggableItemRef: React.Ref<any>;
+  dropZoneStyle?: React.CSSProperties;
+  draggableItemStyle?: React.CSSProperties;
+  classNames?: {
+    dropZone?: string;
+    draggableItem?: string;
+  };
+  asDropZone?: React.ElementType;
+  asDraggableItem?: React.ElementType;
+  draggableItemProps?: Record<string, any>;
+  children?: React.ReactNode;
+  dataSlots: {
+    dropZone: Record<string, string | boolean | undefined>;
+    draggableItem: Record<string, string>;
+  };
+}
 ```
 
-Retrieves a tree item by its unique identifier.
+### RenderItemProps
+
+```ts
+export interface RenderItemProps<T extends TTreeItem = TTreeItem>
+  extends Pick<
+      TreeItemStructureProps,
+      'classNames' | 'dropZoneStyle' | 'dropZoneRef' | 'draggableItemRef'
+    >,
+    Pick<
+      Props,
+      | 'onCollapse'
+      | 'childCount'
+      | 'clone'
+      | 'ghost'
+      | 'indicator'
+      | 'disableSelection'
+      | 'disableInteraction'
+      | 'collapsed'
+    > {
+  dragListeners?: any;
+  treeItem: T;
+  dataSlots: {
+    dropZone: Record<string, string | boolean | undefined>;
+    draggableItem: Record<string, string>;
+  };
+}
+```
 
-Usage example:
+---
 
-```typescript
-const item = getItemById(items, '1');
-```
+## Helper Functions
 
-### removeItemById
+### getItemById
 
-```typescript
-function removeItemById(items: TreeItems, id: UniqueIdentifier): TreeItems;
+```ts
+function getItemById<T extends TreeItem>(items: TreeItems<T>, id: UniqueIdentifier): T | undefined;
 ```
 
-This function removes an item from the tree structure by its ID. It returns a new `TreeItems` array with the item removed. It also handles removing the item from nested children.
-
-Usage example:
+### removeItemById
 
-```typescript
-const updatedItems = removeItemById(items, '123');
-setItems(updatedItems);
+```ts
+function removeItemById<T extends TreeItem>(
+  items: TreeItems<T>,
+  id: UniqueIdentifier,
+): TreeItems<T>;
 ```
 
 ### setTreeItemProperties
 
-```typescript
-function setTreeItemProperties(
-  items: TreeItems,
+```ts
+function setTreeItemProperties<T extends TreeItem>(
+  items: TreeItems<T>,
   id: UniqueIdentifier,
-  setter: (value: TreeItem) => Partial<TreeItem>,
-): TreeItems;
+  setter: (value: T) => Partial<T>,
+): TreeItems<T>;
 ```
 
-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 `TreeItems` array with the updated item.
-
-Usage example:
-
-```typescript
-setItems((items) => {
-  return setTreeItemProperties(items, '123', (item) => ({
-    label: 'New Label',
-    collapsed: !item.collapsed,
-  }));
-});
-```
+---
 
 ## 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.
+- ✅ Custom item rendering (done!)
+- 🔜 Virtualization for large trees
+- 🔜 Multi-selection support
+- 🔜 Drag multiple items
+- 🔜 Keyboard navigation
+- 🔜 API usage example
+- 🔜 E2E tests
 
-The GitHub Action will automatically build, test, and publish the new version to npm.
+---
 
 ## License
 

package/dist/SortableTree/SortableTree.d.ts

@@ -1,4 +1,2 @@
-import { SortableTreeProps } from './types';
-declare function PrivateSortableTree({ items, 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 {};
+import { SortableTreeProps, TreeItem } from './types';
+export declare const SortableTree: <T extends TreeItem = TreeItem>(props: SortableTreeProps<T>) => import("react/jsx-runtime").JSX.Element;

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

@@ -1,5 +1,15 @@
 import { default as React, HTMLAttributes } from 'react';
-export interface Props extends Omit<HTMLAttributes<HTMLLIElement>, 'id'> {
+import { TreeItemStructureProps } from '../TreeItemStructure';
+import { TreeItem as TTreeItem } from '../../types';
+export interface RenderItemProps<T extends TTreeItem = TTreeItem> extends Pick<TreeItemStructureProps, 'classNames' | 'dropZoneStyle' | 'dropZoneRef' | 'draggableItemRef'>, Pick<Props, 'onCollapse' | 'childCount' | 'clone' | 'ghost' | 'indicator' | 'disableSelection' | 'disableInteraction' | 'collapsed'> {
+    dragListeners?: any;
+    treeItem: T;
+    dataSlots: {
+        dropZone: Record<string, string | boolean | undefined>;
+        draggableItem: Record<string, string>;
+    };
+}
+export interface Props<T extends TTreeItem = TTreeItem> extends Omit<HTMLAttributes<HTMLLIElement>, 'id'> {
     childCount?: number;
     clone?: boolean;
     collapsed?: boolean;
@@ -11,12 +21,13 @@ export interface Props extends Omit<HTMLAttributes<HTMLLIElement>, 'id'> {
     handleProps?: any;
     indicator?: boolean;
     indentationWidth: number;
-    value: string;
+    value: T;
     onCollapse?(): void;
     onRemove?(): void;
     onAdd?(): void;
     onLabelClick?(): void;
-    wrapperRef?(node: HTMLLIElement): void;
+    wrapperRef: RenderItemProps<T>['dropZoneRef'];
+    renderItem?: (props: RenderItemProps<T>) => React.ReactNode;
 }
-export declare const _TreeItem: React.ForwardRefExoticComponent<Props & React.RefAttributes<HTMLDivElement>>;
-export declare const TreeItem: React.MemoExoticComponent<React.ForwardRefExoticComponent<Props & React.RefAttributes<HTMLDivElement>>>;
+export declare const _TreeItem: React.ForwardRefExoticComponent<Props<import('../..').BaseTreeItem<unknown>> & React.RefAttributes<HTMLDivElement>>;
+export declare const TreeItem: React.NamedExoticComponent<Props<import('../..').BaseTreeItem<unknown>> & React.RefAttributes<HTMLDivElement>>;

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

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

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

@@ -0,0 +1,19 @@
+export interface TreeItemStructureProps {
+    dropZoneRef: (element: HTMLElement | null) => void;
+    draggableItemRef: React.Ref<any>;
+    dropZoneStyle?: React.CSSProperties;
+    draggableItemStyle?: React.CSSProperties;
+    classNames?: {
+        dropZone?: string;
+        draggableItem?: string;
+    };
+    asDropZone?: React.ElementType;
+    asDraggableItem?: React.ElementType;
+    draggableItemProps?: Record<string, any>;
+    children?: React.ReactNode;
+    dataSlots: {
+        dropZone: Record<string, string | boolean | undefined>;
+        draggableItem: Record<string, string>;
+    };
+}
+export declare const TreeItemStructure: ({ dropZoneRef, draggableItemRef, dropZoneStyle, draggableItemStyle, classNames, asDropZone: DropZoneComponent, asDraggableItem: DraggableComponent, draggableItemProps, children, dataSlots, }: TreeItemStructureProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -1 +1,4 @@
 export { TreeItem, SortableTreeItem } from './TreeItem';
+export type { RenderItemProps } from './TreeItem';
+export { TreeItemStructure } from './TreeItemStructure';
+export type { TreeItemStructureProps } from './TreeItemStructure';

package/dist/SortableTree/createSortableTreeGlobalStyles.d.ts

@@ -0,0 +1,8 @@
+type SortableTreeStyleOptions = {
+    indicatorColor?: string;
+    indicatorBorderColor?: string;
+    indicatorDotColor?: string;
+    dragBoxShadow?: string;
+};
+export declare const createSortableTreeGlobalStyles: (options?: SortableTreeStyleOptions) => () => void;
+export {};

package/dist/SortableTree/index.d.ts

@@ -1,3 +1,6 @@
 export * from './types';
 export { SortableTree } from './SortableTree';
+export { TreeItemStructure } from './components';
+export type { TreeItemStructureProps, RenderItemProps } from './components';
 export { setTreeItemProperties, removeItemById, getItemById } from './utilities';
+export { createSortableTreeGlobalStyles } from './createSortableTreeGlobalStyles';

package/dist/SortableTree/types.d.ts

@@ -1,9 +1,11 @@
 import { MutableRefObject } from 'react';
 import { UniqueIdentifier } from '@dnd-kit/core';
+import { Props } from './components/TreeItem/TreeItem';
+export type TreeItem<ExtraProps = unknown> = BaseTreeItem & ExtraProps;
 /**
  * Represents an item in the tree structure.
  */
-export type TreeItem = {
+export type BaseTreeItem<ExtraProps = unknown> = {
     /**
      * Unique identifier for the item. Can be a string or number.
      */
@@ -15,7 +17,7 @@ export type TreeItem = {
     /**
      * An array of child TreeItems. If empty, the item is a leaf node.
      */
-    children: TreeItem[];
+    children: TreeItem<ExtraProps>[];
     /**
      * Determines whether the item's children are initially collapsed.
      * @default false
@@ -34,12 +36,8 @@ export type TreeItem = {
      * @default false
      */
     disableDragging?: boolean;
-    /**
-     * Any additional custom properties can be added here.
-     */
-    [key: string]: any;
 };
-export type TreeItems = TreeItem[];
+export type TreeItems<ExtraProps = unknown> = TreeItem<ExtraProps>[];
 export interface FlattenedItem extends TreeItem {
     parentId: UniqueIdentifier | null;
     depth: number;
@@ -52,7 +50,7 @@ export type SensorContext = MutableRefObject<{
 /**
  * Props for the SortableTree component.
  */
-export interface SortableTreeProps {
+export interface SortableTreeProps<T extends TreeItem = TreeItem> {
     /**
      * A control that lets you add the indentation width for children elements
      */
@@ -60,12 +58,12 @@ export interface SortableTreeProps {
     /**
      * The array of tree items to be rendered.
      */
-    items: TreeItems;
+    items: TreeItems<T>;
     /**
      * Callback function called when the tree structure changes.
      * @param items - The updated array of tree items.
      */
-    setItems: React.Dispatch<React.SetStateAction<TreeItems>>;
+    setItems: React.Dispatch<React.SetStateAction<TreeItems<T>>>;
     /**
      * Determines if tree items can be collapsed/expanded.
      * @default false
@@ -113,6 +111,13 @@ export interface SortableTreeProps {
      * @param id - The id of the clicked item.
      */
     onItemClick?: (id: UniqueIdentifier) => void;
+    /**
+     * You can place a react component next to the item's label. This is temporal while we
+     * figure out a way of rendering a whole custom item
+     * @param item
+     * @returns
+     */
+    renderItem?: Props<T>['renderItem'];
 }
 /**
  * Represents the result of a drag operation in the tree.

package/dist/SortableTree/utilities.d.ts

@@ -9,16 +9,16 @@ export declare function getProjection(items: FlattenedItem[], activeId: UniqueId
 };
 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 findItem(items: TreeItem[], itemId: UniqueIdentifier): import('./types').BaseTreeItem<unknown> | undefined;
 export declare function findItemDeep(items: TreeItems, itemId: UniqueIdentifier): TreeItem | undefined;
-export declare function removeItemById(items: TreeItems, id: UniqueIdentifier): TreeItems;
-export declare function setTreeItemProperties(items: TreeItems, id: UniqueIdentifier, setter: (value: TreeItem) => Partial<TreeItem>): TreeItems;
+export declare function removeItemById<T extends TreeItem>(items: TreeItems<T>, id: UniqueIdentifier): TreeItems<T>;
+export declare function setTreeItemProperties<T extends TreeItem>(items: TreeItems<T>, id: UniqueIdentifier, setter: (value: T) => Partial<T>): TreeItems<T>;
 /**
  * Retrieves a tree item by its unique identifier.
  * @param structure The current tree items array
  * @param id The unique identifier of the item to retrieve.
  * @returns The tree item if found, undefined otherwise.
  */
-export declare function getItemById(items: TreeItems, id: UniqueIdentifier): TreeItem | undefined;
+export declare function getItemById<T extends TreeItem>(items: TreeItems<T>, id: UniqueIdentifier): TreeItem<T> | undefined;
 export declare function getChildCount(treeStructure: TreeItems, id: UniqueIdentifier): number;
 export declare function removeChildrenOf(items: FlattenedItem[], ids: UniqueIdentifier[]): FlattenedItem[];