frappe-ui 1.0.0-beta.2 → 1.0.0-beta.21

package/src/components/Tree/Tree.md

@@ -1,8 +1,150 @@
 # Tree
 
-Displays hierarchical data in a collapsible tree structure. Makes it easy to navigate nested items and manage complex relationships.
+Displays hierarchical data as a collapsible tree. Renders a forest of roots with
+keyboard navigation and optional drag-and-drop reparenting/reordering. Connector
+guides visually link parents to their children.
+
+## Default
+
+The simplest tree — pass `nodes` and tell it which field is the key. Nodes are
+expanded by default; here **Documents** carries `expanded: false` to start
+collapsed.
 
-## Default 
 <ComponentPreview name="Tree-Example" />
 
+## Expand / collapse all
+
+Bind `v-model:expanded` to a boolean for a master switch — toggling it opens or
+closes every node. It's two-way, so it also reflects whether all nodes are
+currently open as the user toggles rows individually.
+
+<ComponentPreview name="Tree-ExpandAll" />
+
+## Indentation guides
+
+`guides` controls how nesting is drawn: `connectors` (elbow lines), `lines`
+(plain vertical rules), or `none`. The indentation itself stays either way —
+`guides` only changes the lines.
+
+<ComponentPreview name="Tree-Guides" />
+
+## Drag and drop
+
+Set `draggable` to let nodes be dragged onto one another to reparent, or between
+siblings to reorder. A `move` predicate gates where drops are allowed (here,
+only into folders), and `@drag-end` hands you the committed move to persist.
+This example is fully working — drag a file into a folder and it stays there.
+Flip **Disable interaction** to see the `disabled` state freeze drag and
+expand/collapse.
+
+<ComponentPreview name="Tree-DragDrop" />
+
+## List view with avatars and row actions
+
+Use the `#item-prefix`, `#item-label`, and `#item-suffix` slots to turn the tree
+into a rich list — an avatar on the left, a two-line label, and a row action (an
+add button) on the right. `guides="none"` drops the connector lines for a plain
+list look.
+
+<ComponentPreview name="Tree-ListView" />
+
+## Usage
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { Tree } from 'frappe-ui'
+
+const nodes = ref([
+  {
+    name: 'src',
+    label: 'src',
+    children: [
+      { name: 'index.ts', label: 'index.ts' },
+      { name: 'app.vue', label: 'app.vue' },
+    ],
+  },
+])
+</script>
+
+<template>
+  <Tree :nodes="nodes" node-key="name" />
+</template>
+```
+
+## Node shape
+
+Each node is a plain object with a `label` (display text) and optional
+`children`. Its unique id lives under the field named by `nodeKey` (e.g.
+`name`). A node is a leaf when `children` is missing or empty. Extra fields are
+passed through to the slots, so you can render avatars, roles, badges, etc.
+
+To display a field other than `label`, use the `#item-label` slot rather than
+remapping.
+
+## Expansion
+
+Each node owns its own state via an `expanded` field — the source of truth the
+tree reads and writes as rows toggle, so expansion travels with your data. Nodes
+are **expanded by default**; set `expanded: false` to start one collapsed.
+
+`v-model:expanded` is a separate, optional boolean **switch** for the whole
+tree: toggle it to open or close everything at once (see
+[Expand / collapse all](#expand-collapse-all)). It's two-way, reflecting whether
+all nodes are currently open.
+
+Clicking a row, or pressing `Enter`/`Space` on it, toggles that node.
+
+## Keyboard
+
+Following the WAI-ARIA Tree View pattern: `↑`/`↓` move between visible rows, `→`
+expands or steps into children, `←` collapses or steps to the parent,
+`Home`/`End` jump to the first/last row, `Enter`/`Space` toggle expansion, and
+typing letters jumps to the next matching label.
+
+## Drag and drop
+
+Set `draggable` to enable dragging. The tree resolves the drop position from the
+cursor (`before` / `inside` / `after`) and shows a live indicator.
+
+- `move(ctx)` — an optional predicate called as you hover. Return `false` to
+  reject a target (it shows the no-drop cursor and hides the indicator).
+  Built-in guards already reject drop-on-self and drop-into-own-descendant, so
+  `move` only carries your domain rules. `ctx` is `{ node, target, position }`.
+- `@drag-start(node)` — fires when a drag is picked up.
+- `@drag-end(info)` — fires when the drag ends. `info` is a `DropInfo` on a
+  committed move, or `null` if the drag was cancelled. Apply it to your data and
+  update `nodes`.
+
+```vue
+<Tree
+  :nodes="nodes"
+  node-key="name"
+  draggable
+  :move="({ node, target, position }) => Array.isArray(target.children)"
+  @drag-end="onDragEnd"
+/>
+```
+
+`DropInfo` is `{ node, from, to, position, oldIndex, newIndex }` — `from`/`to`
+are the old/new parent keys (`null` at root level) and `newIndex` is the node's
+final index within its new parent, already accounting for its removal.
+
+## Customizing rows
+
+Use the `#item` slot to fully replace a row (you receive `toggle` plus state),
+or the lighter `#item-label`, `#item-prefix`, and `#item-suffix` slots to keep
+the default layout. Style via the `data-slot`, `data-state`, `data-drop` and
+`data-level` attributes rather than class props.
+
+Row height and indentation are CSS variables — override them in CSS rather than
+through props:
+
+```css
+.my-tree {
+  --tree-row-height: 40px;
+  --tree-indent: 24px;
+}
+```
+
 <!-- @include: ./Tree.api.md -->

package/src/components/Tree/Tree.vue

@@ -1,122 +1,301 @@
 <template>
-  <!-- Current Tree Node -->
-  <slot
-    name="node"
-    v-bind="{ node, hasChildren, isCollapsed, toggleCollapsed }"
+  <ul
+    ref="treeRef"
+    v-bind="$attrs"
+    role="tree"
+    class="frappe-tree select-none"
+    :data-guides="guides"
+    @keydown="onKeydown"
+    @focusin="onFocusin"
   >
+    <TreeItem
+      v-for="(node, index) in roots"
+      :key="keyOf(node)"
+      :node="node"
+      :parent="null"
+      :level="1"
+      :index="index"
+      :set-size="roots.length"
+    >
+      <template v-if="$slots.item" #item="p"
+        ><slot name="item" v-bind="p"
+      /></template>
+      <template v-if="$slots['item-label']" #item-label="p"
+        ><slot name="item-label" v-bind="p"
+      /></template>
+      <template v-if="$slots['item-prefix']" #item-prefix="p"
+        ><slot name="item-prefix" v-bind="p"
+      /></template>
+      <template v-if="$slots['item-suffix']" #item-suffix="p"
+        ><slot name="item-suffix" v-bind="p"
+      /></template>
+    </TreeItem>
+
+    <li v-if="!roots.length" role="none" data-slot="empty">
+      <slot name="empty" />
+    </li>
+  </ul>
+
+  <!-- Floating drag indicator -->
+  <Teleport to="body">
     <div
-      class="flex items-center cursor-pointer gap-1"
-      :style="{ height: options.rowHeight }"
-      @click="toggleCollapsed"
+      v-if="dragLabel"
+      class="frappe-tree-drag-label pointer-events-none fixed z-[1000] rounded-md bg-surface-gray-7 px-2 py-1 text-xs text-ink-white shadow-lg"
+      :style="{
+        top: `${dragDrop.state.y + 18}px`,
+        left: `${dragDrop.state.x + 12}px`,
+      }"
     >
-      <div ref="iconRef">
-        <!-- slot to only override the Icon -->
-        <slot name="icon" v-bind="{ hasChildren, isCollapsed }">
-          <span
-            v-if="hasChildren && !isCollapsed"
-            class="lucide-chevron-down size-3.5"
-            aria-hidden="true"
-          />
-          <span
-            v-else-if="hasChildren"
-            class="lucide-chevron-right size-3.5"
-            aria-hidden="true"
-          />
-        </slot>
-      </div>
-
-      <!-- slot to only override the label -->
-      <slot name="label" v-bind="{ node, hasChildren, isCollapsed }">
-        <div class="text-base truncate" :class="hasChildren ? '' : 'pl-3.5'">
-          {{ node.label }}
-        </div>
-      </slot>
+      {{ dragLabel }}
     </div>
-  </slot>
+  </Teleport>
 
-  <!-- Recursively render the children -->
-  <div v-if="hasChildren && !isCollapsed" class="flex">
-    <div
-      :style="{ paddingLeft: linePadding }"
-      class="border-r"
-      v-if="options.showIndentationGuides"
-    ></div>
-    <ul class="w-full" :style="{ paddingLeft: options.indentWidth }">
-      <li v-for="child in node.children" :key="child[nodeKey] as string">
-        <Tree :node="child" :nodeKey="nodeKey" :options="options">
-          <!-- Pass the parent slots to the children of current node -->
-          <template #node="{ node, hasChildren, isCollapsed, toggleCollapsed }">
-            <slot
-              name="node"
-              v-bind="{ node, hasChildren, isCollapsed, toggleCollapsed }"
-            />
-          </template>
-
-          <template #icon="{ hasChildren, isCollapsed }">
-            <slot name="icon" v-bind="{ hasChildren, isCollapsed }" />
-          </template>
-
-          <template #label="{ node, hasChildren, isCollapsed }">
-            <slot name="label" v-bind="{ node, hasChildren, isCollapsed }" />
-          </template>
-        </Tree>
-      </li>
-    </ul>
-  </div>
+  <!-- Polite live region for drag/drop announcements -->
+  <div class="sr-only" role="status" aria-live="polite">{{ liveMessage }}</div>
 </template>
 
 <script setup lang="ts">
-import { ref, computed, onMounted } from 'vue'
-import type { TreeNode, TreeProps } from './types'
+import { computed, nextTick, provide, ref, toRef, watch } from 'vue'
+import TreeItem from './TreeItem.vue'
+import { useTreeDragDrop } from './useTreeDragDrop'
+import { useTreeKeyboard, type FlatNode } from './useTreeKeyboard'
+import {
+  TreeContextKey,
+  type DropInfo,
+  type TreeKey,
+  type TreeNode,
+  type TreeNodeSlotProps,
+  type TreeProps,
+} from './types'
+
+defineOptions({ inheritAttrs: false })
 
 const props = withDefaults(defineProps<TreeProps>(), {
-  options: () => ({
-    rowHeight: '25px',
-    indentWidth: '20px',
-    showIndentationGuides: true,
-    defaultCollapsed: true,
-  }),
+  nodeKey: 'key',
+  draggable: false,
+  guides: 'connectors',
+  disabled: false,
 })
 
-const slots = defineSlots<{
-  /** Slot to fully override how a tree node renders */
-  node: {
-    node: TreeNode
-    hasChildren: boolean
-    isCollapsed: boolean
-    toggleCollapsed: (event: MouseEvent) => void
-  }
+const emit = defineEmits<{
+  'drag-start': [node: TreeNode]
+  'drag-end': [info: DropInfo | null]
+}>()
 
-  /** Slot to override only the node expand/collapse icon */
-  icon: {
-    hasChildren: boolean
-    isCollapsed: boolean
-  }
+defineSlots<{
+  item: (props: TreeNodeSlotProps) => unknown
+  'item-prefix': (props: Omit<TreeNodeSlotProps, 'toggle'>) => unknown
+  'item-label': (props: Omit<TreeNodeSlotProps, 'toggle'>) => unknown
+  'item-suffix': (props: Omit<TreeNodeSlotProps, 'toggle'>) => unknown
+  empty: () => unknown
+}>()
+
+/**
+ * Expand/collapse-all switch. Toggling it writes that value into every node's
+ * `expanded` field. Two-way: it also reflects whether all collapsible nodes are
+ * currently open, so a bound button stays in sync. Per-node state lives on the
+ * nodes themselves (`node.expanded`).
+ */
+const expanded = defineModel<boolean>('expanded', { default: false })
 
-  /** Slot to override only the node label/content */
-  label: {
-    node: TreeNode
-    hasChildren: boolean
-    isCollapsed: boolean
+const treeRef = ref<HTMLElement | null>(null)
+const focusedKey = ref<TreeKey | null>(null)
+const liveMessage = ref('')
+const itemEls = new Map<TreeKey, HTMLElement>()
+
+// --- node field accessors -------------------------------------------------
+const roots = computed(() => props.nodes ?? [])
+const keyOf = (node: TreeNode) => node[props.nodeKey] as TreeKey
+const labelOf = (node: TreeNode) => node.label ?? ''
+const childrenOf = (node: TreeNode) => node.children ?? []
+const hasChildren = (node: TreeNode) => childrenOf(node).length > 0
+// Siblings of a node: a parent's children, or the roots for top-level nodes.
+const siblingsOf = (parent: TreeNode | null) =>
+  parent ? childrenOf(parent) : roots.value
+
+// --- expansion ------------------------------------------------------------
+// Per-node state lives on the node itself. Expanded by default — a node is only
+// closed when it explicitly carries `expanded: false`.
+const isExpanded = (node: TreeNode) => node.expanded !== false
+
+function setExpanded(node: TreeNode, value: boolean) {
+  if (props.disabled || !hasChildren(node)) return
+  node.expanded = value
+  syncModel()
+}
+
+const toggle = (node: TreeNode) => setExpanded(node, !isExpanded(node))
+const expand = (node: TreeNode) => setExpanded(node, true)
+const collapse = (node: TreeNode) => setExpanded(node, false)
+
+function eachCollapsible(nodes: TreeNode[], fn: (node: TreeNode) => void) {
+  for (const node of nodes) {
+    if (hasChildren(node)) {
+      fn(node)
+      eachCollapsible(childrenOf(node), fn)
+    }
   }
-}>()
+}
 
-const isCollapsed = ref(props.options.defaultCollapsed ?? true)
+// Write `value` into every collapsible node's `expanded` field.
+function setAll(value: boolean) {
+  eachCollapsible(roots.value, (node) => (node.expanded = value))
+}
 
-const linePadding = ref('')
+// True when every collapsible node is open (drives the two-way switch).
+function allExpanded() {
+  let total = 0
+  let open = 0
+  eachCollapsible(roots.value, (node) => {
+    total++
+    if (isExpanded(node)) open++
+  })
+  return total > 0 ? open === total : expanded.value
+}
 
-const hasChildren = computed(() => props.node.children?.length > 0)
+// Reflect the per-node state back onto the switch without re-triggering setAll.
+let syncing = false
+function syncModel() {
+  const all = allExpanded()
+  if (expanded.value === all) return
+  syncing = true
+  expanded.value = all
+  syncing = false
+}
 
-const iconRef = ref<HTMLElement | null>(null)
+// --- focus -----------------------------------------------------------------
+function focus(key: TreeKey) {
+  focusedKey.value = key
+  nextTick(() => itemEls.get(key)?.focus())
+}
 
-const toggleCollapsed = (event: MouseEvent) => {
-  event.stopPropagation()
-  if (hasChildren.value) isCollapsed.value = !isCollapsed.value
+function onFocusin() {
+  if (focusedKey.value == null && roots.value.length)
+    focusedKey.value = keyOf(roots.value[0])
 }
 
-onMounted(() => {
-  if (iconRef.value?.clientWidth)
-    // Set the padding for the LHS line to align with the center of icon
-    linePadding.value = iconRef.value.clientWidth / 2 + 'px'
+const registerItem = (key: TreeKey, el: HTMLElement) => itemEls.set(key, el)
+const unregisterItem = (key: TreeKey) => itemEls.delete(key)
+
+// --- flattened visible list (for keyboard nav) ----------------------------
+const flat = computed(() => {
+  const out: FlatNode[] = []
+  const walk = (
+    nodes: TreeNode[],
+    parentKey: TreeKey | null,
+    level: number,
+  ) => {
+    for (const node of nodes) {
+      const expandedNow = isExpanded(node)
+      out.push({
+        key: keyOf(node),
+        node,
+        parentKey,
+        level,
+        hasChildren: hasChildren(node),
+        expanded: expandedNow,
+      })
+      if (expandedNow && hasChildren(node))
+        walk(childrenOf(node), keyOf(node), level + 1)
+    }
+  }
+  walk(roots.value, null, 1)
+  return out
+})
+
+// --- drag & drop ----------------------------------------------------------
+const dragDrop = useTreeDragDrop({
+  keyOf,
+  childrenOf,
+  siblingsOf,
+  labelOf,
+  disabled: toRef(props, 'disabled'),
+  move: (ctx) => props.move?.(ctx) ?? true,
+  emitDragStart: (node) => emit('drag-start', node),
+  emitDragEnd: (info) => emit('drag-end', info),
+  announce: (message) => (liveMessage.value = message),
+})
+
+const dragLabel = computed(() => {
+  const { state } = dragDrop
+  const position = dragDrop.dropPosition.value
+  if (!state.source || !state.target || !position) return null
+  const target = labelOf(state.target)
+  return position === 'inside'
+    ? `Move under ${target}`
+    : `Move ${position} ${target}`
+})
+
+// --- keyboard -------------------------------------------------------------
+const { onKeydown } = useTreeKeyboard({
+  flat,
+  focusedKey,
+  labelOf,
+  focus,
+  expand,
+  collapse,
+  toggle,
+})
+
+// --- lifecycle ------------------------------------------------------------
+// The switch applies to every node when toggled. Skip the initial `false` so a
+// tree's per-node `expanded` data is respected on first render.
+watch(
+  expanded,
+  (value, old) => {
+    if (syncing) return
+    if (old === undefined && value === false) return
+    setAll(value)
+  },
+  { immediate: true, flush: 'sync' },
+)
+
+// Keep the switch reflecting the real per-node state, including initial data
+// and async-loaded nodes.
+watch(roots, syncModel, { immediate: true })
+
+// Keep focus valid if the focused node disappears from the tree.
+watch(flat, (rows) => {
+  if (focusedKey.value != null && !rows.some((r) => r.key === focusedKey.value))
+    focusedKey.value = rows[0]?.key ?? null
+})
+
+// --- provide context ------------------------------------------------------
+provide(TreeContextKey, {
+  nodeKey: toRef(props, 'nodeKey'),
+  guides: toRef(props, 'guides'),
+  draggable: toRef(props, 'draggable'),
+  disabled: toRef(props, 'disabled'),
+  focusedKey,
+  keyOf,
+  labelOf,
+  childrenOf,
+  hasChildren,
+  isExpanded,
+  toggle,
+  focus,
+  registerItem,
+  unregisterItem,
+  dragSourceKey: dragDrop.dragSourceKey,
+  dropTargetKey: dragDrop.dropTargetKey,
+  dropPosition: dragDrop.dropPosition,
+  onDragStart: dragDrop.onDragStart,
+  onDragOver: dragDrop.onDragOver,
+  onDragLeave: dragDrop.onDragLeave,
+  onDrop: dragDrop.onDrop,
+  onDragEnd: dragDrop.onDragEnd,
 })
 </script>
+
+<style>
+.frappe-tree {
+  --_tree-row-height: var(--tree-row-height, 32px);
+  --_tree-indent: var(--tree-indent, 24px);
+  padding: 0;
+}
+.frappe-tree,
+.frappe-tree ul {
+  list-style: none;
+  margin: 0;
+}
+</style>