feat(tree-view): renaming nodes

Author: segunadebayo

.changeset/tree-view-rename-feature.md

@@ -0,0 +1,198 @@
+---
+"@zag-js/tree-view": minor
+---
+
+Add support for renaming tree node labels with validation and control features.
+
+This feature enables users to edit tree node labels inline, unlocking use cases like file explorers, folder management
+systems, content hierarchies, and any tree-based interface where users need to rename items.
+
+## Key Features
+
+### Basic Renaming
+
+- Press `F2` on any node to enter rename mode
+- Input is automatically focused and synced with current label
+- Press `Enter` to submit or `Escape` to cancel
+- Blur event automatically submits changes
+- IME composition events are properly handled for international input
+
+### Validation & Control
+
+- **`canRename`** - Control which nodes are renameable based on node type or custom logic
+- **`onRenameStart`** - Called when rename mode starts (useful for analytics, showing hints)
+- **`onBeforeRename`** - Validate rename before accepting (e.g., prevent duplicates, empty names)
+- **Empty name prevention** - Automatically stays in rename mode if submitted name is empty/whitespace
+- **Label trimming** - Labels are automatically trimmed before being passed to callbacks
+- **`onRenameComplete`** - Handle the rename and update your collection
+
+### Styling & Visual State
+
+- **`data-renaming`** attribute - Added to both item and branch elements when in rename mode for easy styling
+- **`nodeState.renaming`** - Boolean property to check if a node is currently being renamed
+
+## API
+
+```tsx
+const [collection, setCollection] = useState(initialCollection)
+
+useMachine(tree.machine, {
+  collection,
+
+  // Control which nodes can be renamed
+  canRename: (node, indexPath) => {
+    // Only allow renaming leaf nodes (files), not branches (folders)
+    return !node.children
+  },
+
+  // Called when rename mode starts
+  onRenameStart: (details) => {
+    // details contains: { value, node, indexPath }
+    console.log("Started renaming:", details.node.name)
+    // Track analytics, show hints, etc.
+  },
+
+  // Validate before accepting rename
+  onBeforeRename: (details) => {
+    // Note: details.label is already trimmed by the machine
+
+    // Prevent empty names
+    if (!details.label) return false
+
+    // Prevent duplicate names at the same level
+    const parentPath = details.indexPath.slice(0, -1)
+    const parent = parentPath.length > 0 ? collection.at(parentPath) : collection.rootNode
+    const siblings = parent?.children || []
+
+    const hasDuplicate = siblings.some((sibling) => sibling.name === details.label && sibling.id !== details.value)
+
+    return !hasDuplicate
+  },
+
+  // Handle successful rename
+  onRenameComplete: (details) => {
+    // details contains: { value, label (trimmed), indexPath }
+    const node = collection.at(details.indexPath)
+    const updatedCollection = collection.replace(details.indexPath, {
+      ...node,
+      name: details.label,
+    })
+    setCollection(updatedCollection)
+  },
+})
+```
+
+## Component Integration
+
+```tsx
+const TreeNode = ({ node, indexPath, api }) => {
+  const nodeState = api.getNodeState({ node, indexPath })
+
+  return (
+    <div {...api.getItemProps({ node, indexPath })}>
+      <FileIcon />
+
+      {/* Show text when not renaming */}
+      <span {...api.getItemTextProps({ node, indexPath })} style={{ display: nodeState.renaming ? "none" : "inline" }}>
+        {node.name}
+      </span>
+
+      {/* Show input when renaming */}
+      <input {...api.getNodeRenameInputProps({ node, indexPath })} />
+    </div>
+  )
+}
+```
+
+## Programmatic API
+
+```tsx
+// Start renaming a node
+api.startRenaming(nodeValue)
+
+// Submit rename with new label
+api.submitRenaming(nodeValue, newLabel)
+
+// Cancel renaming
+api.cancelRenaming()
+```
+
+## Node State & Styling
+
+The `nodeState` now includes a `renaming` property to track rename mode:
+
+```tsx
+const nodeState = api.getNodeState({ node, indexPath })
+// nodeState.renaming -> boolean
+```
+
+Both `getItemProps` and `getBranchControlProps` now include a `data-renaming` attribute for styling:
+
+```css
+/* Style items being renamed */
+[data-part="item"][data-renaming] {
+  outline: 2px solid blue;
+}
+
+/* Style branch controls being renamed */
+[data-part="branch-control"][data-renaming] {
+  background: rgba(0, 0, 255, 0.1);
+}
+```
+
+## Use Cases Unlocked
+
+1. **File Explorers** - Allow users to rename files and folders with validation
+2. **Content Management** - Edit page titles, categories, or navigation items in-place
+3. **Folder Organization** - Rename folders with duplicate prevention
+4. **Project Management** - Edit task names, project hierarchies
+5. **Knowledge Bases** - Rename articles, sections, or categories inline
+
+## Example: File Explorer with Smart Validation
+
+```tsx
+useMachine(tree.machine, {
+  collection,
+
+  canRename: (node, indexPath) => {
+    // Prevent renaming system files
+    if (node.system) return false
+    // Prevent renaming locked files
+    if (node.locked) return false
+    // Only allow renaming files, not folders
+    return !node.children
+  },
+
+  onBeforeRename: (details) => {
+    // Note: details.label is already trimmed
+
+    // Check file extension rules
+    if (!details.label.includes(".")) {
+      console.error("File must have an extension")
+      return false
+    }
+
+    // Validate file name characters
+    if (/[<>:"/\\|?*]/.test(details.label)) {
+      console.error("Invalid characters in filename")
+      return false
+    }
+
+    return true
+  },
+
+  onRenameComplete: (details) => {
+    // Update collection and sync to backend
+    const node = collection.at(details.indexPath)
+    const updatedCollection = collection.replace(details.indexPath, {
+      ...node,
+      name: details.label,
+      lastModified: new Date(),
+    })
+    setCollection(updatedCollection)
+
+    // Sync to server
+    api.renameFile(details.value, details.label)
+  },
+})
+```

examples/next-ts/pages/compositions

@@ -14,6 +14,8 @@ export type {
   LoadChildrenCompleteDetails,
   LoadChildrenDetails,
   LoadChildrenErrorDetails,
+  RenameCompleteDetails,
+  RenameStartDetails,
   TreeViewMachine as Machine,
   NodeProps,
   NodeState,

packages/machines/tree-view/src/index.ts

@@ -13,6 +13,7 @@ export const anatomy = createAnatomy("tree-view").parts(
   "itemText",
   "label",
   "nodeCheckbox",
+  "nodeRenameInput",
   "root",
   "tree",
 )

packages/machines/tree-view/src/tree-view.anatomy.ts

@@ -31,6 +31,7 @@ export function connect<T extends PropTypes, V extends TreeNode = TreeNode>(
   const isTypingAhead = computed("isTypingAhead")
   const focusedValue = context.get("focusedValue")
   const loadingStatus = context.get("loadingStatus")
+  const renamingValue = context.get("renamingValue")
 
   function getNodeState(props: NodeProps): NodeState {
     const { node, indexPath } = props
@@ -49,6 +50,7 @@ export function connect<T extends PropTypes, V extends TreeNode = TreeNode>(
       loading: loadingStatus[value] === "loading",
       depth: indexPath.length,
       isBranch: collection.isBranchNode(node),
+      renaming: renamingValue === value,
       get checked() {
         return getCheckedState(collection, node, checkedValue)
       },
@@ -110,6 +112,15 @@ export function connect<T extends PropTypes, V extends TreeNode = TreeNode>(
       const _selectedValue = uniq(value)
       send({ type: "SELECTED.SET", value: _selectedValue })
     },
+    startRenaming(value) {
+      send({ type: "NODE.RENAME", value })
+    },
+    submitRenaming(value, label) {
+      send({ type: "RENAME.SUBMIT", value, label })
+    },
+    cancelRenaming() {
+      send({ type: "RENAME.CANCEL" })
+    },
 
     getRootProps() {
       return normalize.element({
@@ -217,6 +228,24 @@ export function connect<T extends PropTypes, V extends TreeNode = TreeNode>(
               event.preventDefault()
               send({ type: "SELECTED.ALL", moveFocus: true })
             },
+            F2(event) {
+              if (node.dataset.disabled) return
+
+              // Check canRename callback if provided
+              const canRenameFn = prop("canRename")
+              if (canRenameFn) {
+                const indexPath = collection.getIndexPath(nodeId)
+                if (indexPath) {
+                  const node = collection.at(indexPath)
+                  if (node && !canRenameFn(node, indexPath)) {
+                    return
+                  }
+                }
+              }
+
+              event.preventDefault()
+              send({ type: "NODE.RENAME", value: nodeId })
+            },
           }
 
           const key = getEventKey(event, { dir: prop("dir") })
@@ -254,6 +283,7 @@ export function connect<T extends PropTypes, V extends TreeNode = TreeNode>(
         "data-selected": dataAttr(nodeState.selected),
         "aria-disabled": ariaAttr(nodeState.disabled),
         "data-disabled": dataAttr(nodeState.disabled),
+        "data-renaming": dataAttr(nodeState.renaming),
         "aria-level": nodeState.depth,
         "data-depth": nodeState.depth,
         style: {
@@ -372,6 +402,7 @@ export function connect<T extends PropTypes, V extends TreeNode = TreeNode>(
         "data-disabled": dataAttr(nodeState.disabled),
         "data-selected": dataAttr(nodeState.selected),
         "data-focus": dataAttr(nodeState.focused),
+        "data-renaming": dataAttr(nodeState.renaming),
         "data-value": nodeState.value,
         "data-depth": nodeState.depth,
         "data-loading": dataAttr(nodeState.loading),
@@ -449,5 +480,34 @@ export function connect<T extends PropTypes, V extends TreeNode = TreeNode>(
         },
       })
     },
+
+    getNodeRenameInputProps(props) {
+      const nodeState = getNodeState(props)
+      return normalize.input({
+        ...parts.nodeRenameInput.attrs,
+        id: dom.getRenameInputId(scope, nodeState.value),
+        type: "text",
+        "aria-label": "Rename tree item",
+        hidden: !nodeState.renaming,
+        onKeyDown(event) {
+          // CRITICAL: Ignore keyboard events during IME composition
+          if (isComposingEvent(event)) return
+
+          if (event.key === "Escape") {
+            send({ type: "RENAME.CANCEL" })
+            event.preventDefault()
+          }
+          if (event.key === "Enter") {
+            send({ type: "RENAME.SUBMIT", label: event.currentTarget.value })
+            event.preventDefault()
+          }
+          // Stop propagation to prevent tree navigation during renaming
+          event.stopPropagation()
+        },
+        onBlur(event) {
+          send({ type: "RENAME.SUBMIT", label: event.currentTarget.value })
+        },
+      })
+    },
   }
 }

packages/machines/tree-view/src/tree-view.connect.ts

@@ -10,3 +10,9 @@ export const focusNode = (ctx: Scope, value: string | null | undefined) => {
   if (value == null) return
   ctx.getById(getNodeId(ctx, value))?.focus()
 }
+
+export const getRenameInputId = (ctx: Scope, value: string) => `tree:${ctx.id}:rename-input:${value}`
+
+export const getRenameInputEl = (ctx: Scope, value: string) => {
+  return ctx.getById<HTMLInputElement>(getRenameInputId(ctx, value))
+}