@edux-design/tree-select 0.0.1 → 0.1.1

package/README.md

@@ -1,50 +1,189 @@
 # @edux-design/tree-select
 
-Tree-select component for hierarchical navigation and selection. Supports checkbox or chevron controls, drag-and-drop reordering, and add actions at any level.
+TreeSelect renders hierarchical data with expand/collapse controls, optional inline editing, optional add-item actions, and drag-and-drop reordering. The component is controlled: you own the tree data and receive updates via callbacks.
 
 ---
 
 ## Installation
 
 ```bash
-pnpm add @edux-design/tree-select @edux-design/forms @edux-design/icons @edux-design/utils
+pnpm add @edux-design/tree-select @edux-design/forms @edux-design/buttons @edux-design/icons @edux-design/tooltips @dnd-kit/core @dnd-kit/sortable
 # or
-npm install @edux-design/tree-select @edux-design/forms @edux-design/icons @edux-design/utils
+npm install @edux-design/tree-select @edux-design/forms @edux-design/buttons @edux-design/icons @edux-design/tooltips @dnd-kit/core @dnd-kit/sortable
 ```
 
-Peer deps also include `react@^19.1.0`, `react-dom@^19.1.0`.
+Peer deps include `react@^19.1.0` and `react-dom@^19.1.0`.
 
 ---
 
-## Usage
+## Data shape
 
-```jsx
-import { TreeSelect } from "@edux-design/tree-select";
+Each node must have a stable `id`. Children are optional.
 
+```js
 const data = [
   {
     id: "docs",
     label: "Documentation",
-    checked: true,
     children: [
       { id: "intro", label: "Introduction" },
-      { id: "install", label: "Installation", indeterminate: true },
+      { id: "install", label: "Installation" },
     ],
   },
 ];
+```
+
+- `id` is required and must be unique within the tree.
+- `label` is displayed; when missing the `id` is used.
+- `children` is an array of child nodes.
+
+---
+
+## Usage
+
+### Basic
+
+```jsx
+import { TreeSelect } from "@edux-design/tree-select";
 
 export function Example() {
+  return <TreeSelect data={data} />;
+}
+```
+
+### Drag and drop
+
+```jsx
+export function DragExample() {
+  const [tree, setTree] = useState(data);
+
   return (
     <TreeSelect
-      data={data}
-      control="checkbox"
-      defaultExpandedIds={["docs"]}
-      onCheck={(node, nextChecked) => console.log(node, nextChecked)}
+      data={tree}
+      allowDragAndDrop
+      onDataChange={setTree}
     />
   );
 }
 ```
 
+### Multi-select drag
+
+```jsx
+export function MultiDragExample() {
+  const [tree, setTree] = useState(data);
+
+  return (
+    <TreeSelect
+      data={tree}
+      allowDragAndDrop
+      allowMultiDrag
+      onDataChange={setTree}
+    />
+  );
+}
+```
+
+- Hold CMD (Mac) or CTRL (Windows) to select multiple adjacent siblings.
+- Hold SHIFT to select a range of adjacent siblings.
+- Multi-select only works within the same sibling group and must stay contiguous.
+
+### Editable labels and add actions
+
+```jsx
+export function EditableExample() {
+  const [tree, setTree] = useState(data);
+
+  return (
+    <TreeSelect
+      data={tree}
+      isEditable
+      maxDepth={3}
+      addChildTooltip="Add a child item"
+      addSiblingTooltip="Add a sibling item"
+      onDataChange={setTree}
+    />
+  );
+}
+```
+
+### Chevron toggle
+
+```jsx
+export function ChevronExample() {
+  return <TreeSelect data={data} useChevron />;
+}
+```
+
+---
+
+## Props
+
+### `data` (array, required)
+Tree data to render. This component is controlled; updates are emitted through `onDataChange`.
+
+### `onDataChange` (function)
+Called with the updated tree when edits, add actions, or drag-and-drop reordering occur.
+
+### `allowDragAndDrop` (boolean, default `false`)
+Enables drag-and-drop. When `false`, drag handles are hidden and items cannot be reordered.
+
+### `allowMultiDrag` (boolean, default `false`)
+Allows multi-select drag using CMD/CTRL or SHIFT. Selection is restricted to adjacent siblings.
+
+### `isEditable` (boolean, default `false`)
+Enables inline label editing and add-item controls.
+
+### `allowDelete` (boolean, default `false`)
+Shows a delete action for each item and removes the node (plus descendants).
+
+### `useChevron` (boolean, default `false`)
+Uses a chevron control for expand/collapse instead of the checkbox toggle.
+
+### `defaultExpanded` (`"all"` | number | string[] | Set<string | number>)
+Defines the initial expansion state. Use `"all"` to expand every node with children, a number to expand up to that level (1 expands top-level nodes), or an array/set of ids to expand specific items.
+
+### `expanded` (`"all"` | number | string[] | Set<string | number>)
+Controlled expansion state. When provided, the tree expansion is driven by this value.
+
+### `onExpandedChange` (function)
+Called with a `Set` of expanded ids when the user toggles expansion in controlled mode.
+
+### `maxDepth` (number)
+Limits how deep new items can be added. For example, `maxDepth={3}` allows at most 3 levels.
+
+### `addChildTooltip` (string)
+Tooltip copy for the add-child button.
+
+### `addChildTooltipByLevel` (string[])
+Tooltip copy for add-child, keyed by depth. Overrides `addChildTooltip` when provided.
+
+### `addSiblingTooltip` (string)
+Tooltip copy for the add-sibling button.
+
+### `addSiblingTooltipByLevel` (string[])
+Tooltip copy for add-sibling, keyed by depth. Overrides `addSiblingTooltip` when provided.
+
+### `deleteTooltip` (string)
+Tooltip copy for the delete button.
+
+### `deleteTooltipByLevel` (string[])
+Tooltip copy for delete, keyed by depth. Overrides `deleteTooltip` when provided.
+
+---
+
+## Behaviour details
+
+- Nodes with children render an expand/collapse control.
+- Leaf nodes do not render a checkbox/chevron toggle.
+- Expansion only controls visibility of children.
+- When `useChevron` is `false`, the toggle uses the Checkbox plus/indeterminate states.
+- `defaultExpanded` only seeds the initial state; use `expanded` for controlled expansion.
+- When `expanded` is provided, `onExpandedChange` is called with the next set of expanded ids.
+- Deleting a node removes the entire subtree and clears any selected/expanded state for those ids.
+- Drag-and-drop supports reordering within a level and moving items between levels.
+- Drag handle alignment is set so child handles align under the parent toggle.
+
 ---
 
 ## Development

package/dist/index.d.mts

@@ -1,23 +1,23 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
-declare function TreeSelect({ data, control, className, itemClassName, draggable, onReorder, onDataChange, onExpandedChange, expandedIds, defaultExpandedIds, onCheck, onAdd, addLabel, showRootAdd, rootAddLabel, renderLabel, expandOnLabelClick, }: {
+declare function TreeSelect({ data, onDataChange, allowDragAndDrop, allowMultiDrag, isEditable, allowDelete, useChevron, maxDepth, addChildTooltip, addSiblingTooltip, deleteTooltip, addChildTooltipByLevel, addSiblingTooltipByLevel, deleteTooltipByLevel, defaultExpanded, expanded, onExpandedChange, }: {
     data: any;
-    control?: string;
-    className: any;
-    itemClassName: any;
-    draggable?: boolean;
-    onReorder: any;
     onDataChange: any;
+    allowDragAndDrop?: boolean;
+    allowMultiDrag?: boolean;
+    isEditable?: boolean;
+    allowDelete?: boolean;
+    useChevron?: boolean;
+    maxDepth: any;
+    addChildTooltip: any;
+    addSiblingTooltip: any;
+    deleteTooltip: any;
+    addChildTooltipByLevel: any;
+    addSiblingTooltipByLevel: any;
+    deleteTooltipByLevel: any;
+    defaultExpanded: any;
+    expanded: any;
     onExpandedChange: any;
-    expandedIds: any;
-    defaultExpandedIds?: any[];
-    onCheck: any;
-    onAdd: any;
-    addLabel?: string;
-    showRootAdd?: boolean;
-    rootAddLabel?: string;
-    renderLabel: any;
-    expandOnLabelClick?: boolean;
 }): react_jsx_runtime.JSX.Element;
 
 export { TreeSelect };

package/dist/index.d.ts

@@ -1,23 +1,23 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
-declare function TreeSelect({ data, control, className, itemClassName, draggable, onReorder, onDataChange, onExpandedChange, expandedIds, defaultExpandedIds, onCheck, onAdd, addLabel, showRootAdd, rootAddLabel, renderLabel, expandOnLabelClick, }: {
+declare function TreeSelect({ data, onDataChange, allowDragAndDrop, allowMultiDrag, isEditable, allowDelete, useChevron, maxDepth, addChildTooltip, addSiblingTooltip, deleteTooltip, addChildTooltipByLevel, addSiblingTooltipByLevel, deleteTooltipByLevel, defaultExpanded, expanded, onExpandedChange, }: {
     data: any;
-    control?: string;
-    className: any;
-    itemClassName: any;
-    draggable?: boolean;
-    onReorder: any;
     onDataChange: any;
+    allowDragAndDrop?: boolean;
+    allowMultiDrag?: boolean;
+    isEditable?: boolean;
+    allowDelete?: boolean;
+    useChevron?: boolean;
+    maxDepth: any;
+    addChildTooltip: any;
+    addSiblingTooltip: any;
+    deleteTooltip: any;
+    addChildTooltipByLevel: any;
+    addSiblingTooltipByLevel: any;
+    deleteTooltipByLevel: any;
+    defaultExpanded: any;
+    expanded: any;
     onExpandedChange: any;
-    expandedIds: any;
-    defaultExpandedIds?: any[];
-    onCheck: any;
-    onAdd: any;
-    addLabel?: string;
-    showRootAdd?: boolean;
-    rootAddLabel?: string;
-    renderLabel: any;
-    expandOnLabelClick?: boolean;
 }): react_jsx_runtime.JSX.Element;
 
 export { TreeSelect };