feat(Tree): add disabled for TreeItem (#2529)

kricsleo · web-flow · commit 7ef555b07676 · 2026-06-10T17:29:56.000+08:00
diff --git a/docs/content/meta/TreeItem.md b/docs/content/meta/TreeItem.md
@@ -15,6 +15,12 @@
     'type': 'boolean',
     'required': false
   },
+  {
+    'name': 'disabled',
+    'description': '<p>When <code>true</code>, prevents the user from interacting with the item.</p>\n',
+    'type': 'boolean',
+    'required': false
+  },
   {
     'name': 'level',
     'description': '<p>Level of depth</p>\n',
@@ -58,6 +64,11 @@
     'description': '',
     'type': 'boolean | undefined'
   },
+  {
+    'name': 'isDisabled',
+    'description': '',
+    'type': 'boolean'
+  },
   {
     'name': 'handleToggle',
     'description': '',
diff --git a/packages/core/src/Tree/Tree.test.ts b/packages/core/src/Tree/Tree.test.ts
@@ -2,8 +2,9 @@ import type { DOMWrapper, VueWrapper } from '@vue/test-utils'
 import { mount } from '@vue/test-utils'
 import { beforeEach, describe, expect, it } from 'vitest'
 import { axe } from 'vitest-axe'
-import { nextTick } from 'vue'
+import { defineComponent, h, nextTick } from 'vue'
 import { useKbd } from '@/shared'
+import { TreeItem, TreeRoot } from '.'
 import Tree from './story/_Tree.vue'
 
 const kbd = useKbd()
@@ -333,3 +334,75 @@ describe('given a Tree with bubbleSelect and propagateSelect', () => {
     expect(items.map(i => i.attributes('aria-selected'))).toStrictEqual(['false', 'false', 'false', 'false'])
   })
 })
+
+describe('given a Tree with disabled items', () => {
+  const treeItems = [
+    { title: 'apple' },
+    { title: 'banana' },
+    { title: 'cherry' },
+    { title: 'fruits', children: [{ title: 'grape' }, { title: 'kiwi' }] },
+  ]
+
+  function mountTree(disabledKeys: string[] = ['banana'], rootDisabled = false) {
+    const wrapper = mount(defineComponent({
+      setup() {
+        return () => h(TreeRoot as any, {
+          items: treeItems,
+          getKey: (item: any) => item.title,
+          selectionBehavior: 'toggle',
+          disabled: rootDisabled,
+          expanded: ['fruits'],
+        }, {
+          default: ({ flattenItems }: any) => flattenItems.map((item: any) =>
+            h(TreeItem as any, {
+              key: item._id,
+              ...item.bind,
+              disabled: disabledKeys.includes(item._id),
+            }, { default: () => item.value.title }),
+          ),
+        })
+      },
+    }), { attachTo: document.body })
+    return { wrapper, items: () => wrapper.findAll('[role=treeitem]') }
+  }
+
+  beforeEach(() => {
+    document.body.innerHTML = ''
+  })
+
+  it('should set aria-disabled and data-disabled attributes', () => {
+    const { items } = mountTree()
+    expect(items()[1].attributes('aria-disabled')).toBe('true')
+    expect(items()[1].attributes('data-disabled')).toBe('')
+    expect(items()[0].attributes('aria-disabled')).toBeUndefined()
+    expect(items()[0].attributes('data-disabled')).toBeUndefined()
+  })
+
+  it('should not select a disabled item on click or keydown', async () => {
+    const { items } = mountTree()
+    await items()[1].trigger('click')
+    expect(items()[1].attributes('aria-selected')).toBe('false')
+    await items()[1].trigger('keydown', { key: kbd.ENTER })
+    expect(items()[1].attributes('aria-selected')).toBe('false')
+  })
+
+  it('should not toggle a disabled item', async () => {
+    const { items } = mountTree(['fruits'])
+    expect(items().length).toBe(6)
+
+    await items()[3].trigger('click')
+    expect(items().length).toBe(6)
+
+    await items()[3].trigger('keydown', { key: kbd.ARROW_LEFT })
+    expect(items().length).toBe(6)
+  })
+
+  it('should disable all items when root is disabled', async () => {
+    const { items } = mountTree([], true)
+    for (const item of items()) {
+      expect(item.attributes('aria-disabled')).toBe('true')
+    }
+    await items()[0].trigger('click')
+    expect(items()[0].attributes('aria-selected')).toBe('false')
+  })
+})
diff --git a/packages/core/src/Tree/TreeItem.vue b/packages/core/src/Tree/TreeItem.vue
@@ -4,6 +4,8 @@ export interface TreeItemProps<T> extends PrimitiveProps {
   value: T
   /** Level of depth */
   level: number
+  /** When `true`, prevents the user from interacting with the item. */
+  disabled?: boolean
 }
 
 export type SelectEvent<T> = CustomEvent<{ originalEvent: PointerEvent | KeyboardEvent, value?: T, isExpanded: boolean, isSelected: boolean }>
@@ -45,6 +47,7 @@ defineSlots<{
     isExpanded: boolean
     isSelected: boolean
     isIndeterminate: boolean | undefined
+    isDisabled: boolean
     handleToggle: () => void
     handleSelect: () => void
   }) => any
@@ -81,7 +84,11 @@ const isIndeterminate = computed(() => {
   }
 })
 
+const isDisabled = computed(() => rootContext.disabled.value || props.disabled)
+
 function handleKeydownRight(ev: KeyboardEvent) {
+  if (isDisabled.value)
+    return
   if (!hasChildren.value)
     return
 
@@ -103,6 +110,8 @@ function handleKeydownRight(ev: KeyboardEvent) {
 }
 
 function handleKeydownLeft(ev: KeyboardEvent) {
+  if (isDisabled.value)
+    return
   if (isExpanded.value) {
     //  close expanded
     handleToggleCustomEvent(ev)
@@ -121,13 +130,17 @@ function handleKeydownLeft(ev: KeyboardEvent) {
 }
 
 async function handleSelect(ev: SelectEvent<T>) {
+  if (isDisabled.value)
+    return
   emits('select', ev)
   if (ev?.defaultPrevented)
     return
 
   rootContext.onSelect(props.value)
 }
 async function handleToggle(ev: ToggleEvent<T>) {
+  if (isDisabled.value)
+    return
   emits('toggle', ev)
   if (ev?.defaultPrevented)
     return
@@ -155,6 +168,7 @@ defineExpose({
   isExpanded,
   isSelected,
   isIndeterminate,
+  isDisabled,
   handleToggle: () => rootContext.onToggle(props.value),
   handleSelect: () => rootContext.onSelect(props.value),
 })
@@ -165,6 +179,7 @@ defineExpose({
     as-child
     :value="value"
     allow-shift-key
+    :focusable="!isDisabled"
   >
     <Primitive
       v-bind="$attrs"
@@ -174,9 +189,11 @@ defineExpose({
       :aria-selected="isSelected"
       :aria-expanded="hasChildren ? isExpanded : undefined"
       :aria-level="level"
+      :aria-disabled="isDisabled ? true : undefined"
       :data-indent="level"
       :data-selected="isSelected ? '' : undefined"
       :data-expanded="isExpanded ? '' : undefined"
+      :data-disabled="isDisabled ? '' : undefined"
       @keydown.enter.space.self.prevent="handleSelectCustomEvent"
       @keydown.right.prevent="(ev: KeyboardEvent) => rootContext.dir.value === 'ltr' ? handleKeydownRight(ev) : handleKeydownLeft(ev)"
       @keydown.left.prevent="(ev: KeyboardEvent) => rootContext.dir.value === 'ltr' ? handleKeydownLeft(ev) : handleKeydownRight(ev)"
@@ -189,6 +206,7 @@ defineExpose({
         :is-expanded="isExpanded"
         :is-selected="isSelected"
         :is-indeterminate="isIndeterminate"
+        :is-disabled="isDisabled"
         :handle-select="() => rootContext.onSelect(value)"
         :handle-toggle="() => rootContext.onToggle(value)"
       />
diff --git a/packages/core/src/Tree/TreeVirtualizer.vue b/packages/core/src/Tree/TreeVirtualizer.vue
@@ -133,7 +133,9 @@ rootContext.virtualKeydownHook.on((event) => {
     const index = intent === 'first' ? 0 : rootContext.expandedItems.value.length - 1
     virtualizer.value.scrollToIndex(index)
     requestAnimationFrame(() => {
-      const items = getItems()
+      const items = getItems().filter(i => i.ref.dataset.disabled !== '')
+      if (!items.length)
+        return
       const item = intent === 'first' ? items[0] : items.at(-1)!
       item.ref.focus()
     })
