@veltra/desktop 1.7.19 → 1.8.1

package/src/components/kanban/__test__/kanban.test.ts

@@ -0,0 +1,212 @@
+import { describe, expect, it } from 'vitest'
+import { createApp, h, nextTick, ref } from 'vue'
+
+import type { KanbanColumnItem } from '../../types'
+import UKanban from '../kanban.vue'
+
+const defaultColumns: KanbanColumnItem[] = [
+  {
+    key: 'todo',
+    title: '待办',
+    items: [
+      { id: 1, title: '任务 1' },
+      { id: 2, title: '任务 2' }
+    ]
+  },
+  { key: 'done', title: '已完成', items: [{ id: 3, title: '任务 3' }] },
+  { key: 'archive', title: '归档', items: [] }
+]
+
+function mountKanban(
+  props: Record<string, unknown> = {},
+  columns: KanbanColumnItem[] = defaultColumns,
+  slots: Record<string, any> = {}
+) {
+  const host = document.createElement('div')
+  document.body.appendChild(host)
+
+  const model = ref(columns)
+  const changes: KanbanColumnItem[][] = []
+
+  const app = createApp({
+    render() {
+      return h(
+        UKanban,
+        {
+          columns: model.value,
+          ...props,
+          'onUpdate:columns': (value: KanbanColumnItem[]) => {
+            model.value = value
+          },
+          onChange: (value: KanbanColumnItem[]) => {
+            changes.push(value)
+          }
+        },
+        slots
+      )
+    }
+  })
+
+  app.mount(host)
+
+  return {
+    host,
+    model,
+    changes,
+    unmount() {
+      app.unmount()
+      host.remove()
+    }
+  }
+}
+
+function queryRoot(host: HTMLElement) {
+  return host.querySelector<HTMLElement>('.u-kanban')!
+}
+
+function queryColumns(host: HTMLElement) {
+  return [...host.querySelectorAll<HTMLElement>('.u-kanban__column')]
+}
+
+function queryCards(host: HTMLElement) {
+  return [...host.querySelectorAll<HTMLElement>('.u-kanban__card')]
+}
+
+describe('UKanban', () => {
+  it('基础渲染：列、列头标题、计数徽标与卡片', async () => {
+    const { host, unmount } = mountKanban()
+    await nextTick()
+
+    try {
+      const root = queryRoot(host)
+      expect(root).toBeTruthy()
+
+      const columns = queryColumns(host)
+      expect(columns.length).toBe(3)
+
+      const titles = [...host.querySelectorAll('.u-kanban__column-title')].map(
+        (el) => el.textContent
+      )
+      expect(titles).toEqual(['待办', '已完成', '归档'])
+
+      const counts = [...host.querySelectorAll('.u-kanban__column-count')].map(
+        (el) => el.textContent
+      )
+      expect(counts).toEqual(['2', '1', '0'])
+
+      const cards = queryCards(host)
+      expect(cards.length).toBe(3)
+      expect(cards[0]!.textContent).toContain('任务 1')
+      expect(cards[0]!.querySelector('.u-kanban__card-handle')).toBeTruthy()
+    } finally {
+      unmount()
+    }
+  })
+
+  it('空列渲染占位文案，自定义 placeholder 生效', async () => {
+    const { host, unmount } = mountKanban({ placeholder: '拖卡片到这里' })
+    await nextTick()
+
+    try {
+      const empties = [...host.querySelectorAll('.u-kanban__empty')]
+      expect(empties.length).toBe(1)
+      expect(empties[0]!.textContent).toBe('拖卡片到这里')
+      // 空列的卡片容器仍存在，作为拖放目标
+      expect(queryColumns(host)[2]!.querySelector('.u-kanban__cards')).toBeTruthy()
+    } finally {
+      unmount()
+    }
+  })
+
+  it('countable 为 false 时不显示计数徽标', async () => {
+    const { host, unmount } = mountKanban({ countable: false })
+    await nextTick()
+
+    try {
+      expect(host.querySelector('.u-kanban__column-count')).toBeNull()
+    } finally {
+      unmount()
+    }
+  })
+
+  it('支持自定义 cardKey 与 titleKey', async () => {
+    const columns: KanbanColumnItem[] = [
+      {
+        key: 'list',
+        name: '自定义列',
+        items: [
+          { no: 'a', name: '卡片 A' },
+          { no: 'b', name: '卡片 B' }
+        ]
+      }
+    ]
+    const { host, unmount } = mountKanban({ cardKey: 'no', titleKey: 'name' }, columns)
+    await nextTick()
+
+    try {
+      expect(host.querySelector('.u-kanban__column-title')!.textContent).toBe('自定义列')
+
+      const cards = queryCards(host)
+      expect(cards.length).toBe(2)
+      expect(cards[0]!.textContent).toContain('卡片 A')
+      expect(cards[1]!.textContent).toContain('卡片 B')
+    } finally {
+      unmount()
+    }
+  })
+
+  it('header / card / empty 插槽自定义内容', async () => {
+    const { host, unmount } = mountKanban({}, defaultColumns, {
+      header: ({ column, count }: { column: KanbanColumnItem; count: number }) =>
+        h('span', { class: 'custom-header' }, `${column.title}(${count})`),
+      card: ({ card }: { card: Record<string, any> }) =>
+        h('span', { class: 'custom-card' }, `#${card.id} ${card.title}`),
+      empty: ({ column }: { column: KanbanColumnItem }) =>
+        h('span', { class: 'custom-empty' }, `${column.title}空`)
+    })
+    await nextTick()
+
+    try {
+      const headers = [...host.querySelectorAll('.custom-header')].map((el) => el.textContent)
+      expect(headers).toEqual(['待办(2)', '已完成(1)', '归档(0)'])
+
+      const cards = [...host.querySelectorAll('.custom-card')].map((el) => el.textContent)
+      expect(cards).toEqual(['#1 任务 1', '#2 任务 2', '#3 任务 3'])
+
+      expect(host.querySelector('.custom-empty')!.textContent).toBe('归档空')
+    } finally {
+      unmount()
+    }
+  })
+
+  it('disabled 时根节点带 is-disabled 类名', async () => {
+    const { host, unmount } = mountKanban({ disabled: true })
+    await nextTick()
+
+    try {
+      expect(queryRoot(host).classList.contains('is-disabled')).toBe(true)
+    } finally {
+      unmount()
+    }
+  })
+
+  it('外部替换 columns 数据视图响应更新', async () => {
+    const { host, model, unmount } = mountKanban()
+    await nextTick()
+
+    try {
+      expect(queryCards(host).length).toBe(3)
+
+      model.value = [{ key: 'only', title: '唯一列', items: [{ id: 9, title: '新卡片' }] }]
+      await nextTick()
+
+      expect(queryColumns(host).length).toBe(1)
+      expect(queryCards(host).length).toBe(1)
+      expect(queryCards(host)[0]!.textContent).toContain('新卡片')
+      // 原空列占位消失
+      expect(host.querySelector('.u-kanban__empty')).toBeNull()
+    } finally {
+      unmount()
+    }
+  })
+})

package/src/components/kanban/di.ts

@@ -0,0 +1,19 @@
+import type { BEM } from '@veltra/utils'
+import type { InjectionKey } from 'vue'
+
+import type { KanbanProps } from '../../types'
+
+/** 看板上下文：主组件向列子组件注入 */
+export interface KanbanContext {
+  /** 看板组件属性 */
+  kanbanProps: KanbanProps
+  /** BEM */
+  cls: BEM<'kanban'>
+  /** 某列卡片重排写回（getter 数据源 onReorder 链路），items 为该列最新完整卡片数组 */
+  reorderColumn: (columnKey: string, items: Record<string, any>[]) => void
+  /** 拖拽操作结束通知（一次操作只通知一次，主组件据此 emit change） */
+  notifyChange: () => void
+}
+
+/** 看板依赖注入key */
+export const KanbanDIKey: InjectionKey<KanbanContext> = Symbol('KanbanDIKey')

package/src/components/kanban/index.ts

@@ -0,0 +1 @@
+export { default as UKanban } from './kanban.vue'

package/src/components/kanban/kanban-column.vue

@@ -0,0 +1,77 @@
+<template>
+  <div :class="cls.e('column')">
+    <div :class="cls.e('column-header')">
+      <slot name="header" :column="column" :count="values.length">
+        <span :class="cls.e('column-title')">{{ title }}</span>
+        <span v-if="countable" :class="cls.e('column-count')">{{ values.length }}</span>
+      </slot>
+    </div>
+
+    <div ref="parentRef" :class="cls.e('cards')">
+      <div v-for="(card, index) of values" :key="card[cardKey]" :class="cls.e('card')">
+        <span :class="cls.e('card-handle')">≡</span>
+        <div :class="cls.e('card-body')">
+          <slot name="card" :card="card" :column="column" :index="index">
+            {{ card[titleKey] ?? card[cardKey] }}
+          </slot>
+        </div>
+      </div>
+
+      <div v-if="!values.length" :class="cls.e('empty')">
+        <slot name="empty" :column="column">{{ placeholder }}</slot>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { animations, useDnD, type VueParentConfig } from '@veltra/compositions'
+import { computed, inject, watch } from 'vue'
+
+import type { KanbanColumnItem, KanbanSlots } from '../../types'
+import { KanbanDIKey } from './di'
+
+defineOptions({ name: 'UKanbanColumn' })
+
+defineSlots<KanbanSlots>()
+
+const props = defineProps<{ column: KanbanColumnItem }>()
+
+const ctx = inject(KanbanDIKey)!
+
+const cls = ctx.cls
+
+const titleKey = computed(() => ctx.kanbanProps.titleKey ?? 'title')
+const cardKey = computed(() => ctx.kanbanProps.cardKey ?? 'id')
+const countable = computed(() => ctx.kanbanProps.countable !== false)
+const placeholder = computed(() => ctx.kanbanProps.placeholder ?? '暂无内容')
+
+const title = computed(() => props.column[titleKey.value])
+
+function makeConfig(): VueParentConfig<Record<string, any>> {
+  return {
+    group: 'u-kanban',
+    dragHandle: `.${cls.e('card-handle')}`,
+    draggable: (el) => el.classList.contains(cls.e('card')),
+    draggingClass: 'is-dragging',
+    dropZoneClass: 'is-dropzone',
+    disabled: ctx.kanbanProps.disabled,
+    // 排序/转移数据已由 onReorder 写回，这里只负责对外发 change 通知
+    onSort: () => ctx.notifyChange(),
+    onTransfer: () => ctx.notifyChange(),
+    plugins: [animations()]
+  }
+}
+
+const { parentRef, values, updateConfig } = useDnD<Record<string, any>>({
+  values: () => props.column.items,
+  onReorder: (items) => ctx.reorderColumn(props.column.key, items),
+  ...makeConfig()
+})
+
+// updateConfig 是整体替换配置，须传完整配置而非仅 disabled
+watch(
+  () => ctx.kanbanProps.disabled,
+  () => updateConfig(makeConfig())
+)
+</script>

package/src/components/kanban/kanban.vue

@@ -0,0 +1,81 @@
+<template>
+  <div v-bind="$attrs" :class="[cls.b, bem.is('disabled', disabled)]">
+    <KanbanColumn v-for="column of localColumns" :key="column.key" :column="column">
+      <template #header="{ column: col, count }">
+        <slot name="header" :column="col" :count="count" />
+      </template>
+      <template #card="{ card, column: col, index }">
+        <slot name="card" :card="card" :column="col" :index="index" />
+      </template>
+      <template #empty="{ column: col }">
+        <slot name="empty" :column="col" />
+      </template>
+    </KanbanColumn>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { bem } from '@veltra/utils'
+import { provide, ref, watch } from 'vue'
+
+import type { KanbanColumnItem, KanbanEmits, KanbanProps, KanbanSlots } from '../../types'
+import { KanbanDIKey, type KanbanContext } from './di'
+import KanbanColumn from './kanban-column.vue'
+
+defineOptions({ name: 'UKanban', inheritAttrs: false })
+
+const props = withDefaults(defineProps<KanbanProps>(), {
+  cardKey: 'id',
+  titleKey: 'title',
+  disabled: false,
+  countable: true,
+  placeholder: '暂无内容'
+})
+
+const emit = defineEmits<KanbanEmits>()
+defineSlots<KanbanSlots>()
+
+const cls = bem('kanban')
+
+// 拖拽写回的本地数据源：props 拷贝一份避免原地改父级数据，
+// 拖拽结果经 update:columns 交给父级决定是否受控回写
+const localColumns = ref<KanbanColumnItem[]>([])
+
+watch(
+  () => props.columns,
+  (columns) => {
+    localColumns.value = (columns ?? []).map((column) => ({ ...column, items: [...column.items] }))
+  },
+  { immediate: true }
+)
+
+function snapshot(): KanbanColumnItem[] {
+  return localColumns.value.map((column) => ({ ...column, items: [...column.items] }))
+}
+
+function reorderColumn(columnKey: string, items: Record<string, any>[]) {
+  localColumns.value = localColumns.value.map((column) =>
+    column.key === columnKey ? { ...column, items } : column
+  )
+  emit('update:columns', snapshot())
+}
+
+// 一次拖拽可能同步触发多个回调（跨列转移在源列与目标列各触发一次 onTransfer），
+// microtask 内合并保证一次操作只 emit 一次 change
+let changePending = false
+function notifyChange() {
+  if (changePending) return
+  changePending = true
+  queueMicrotask(() => {
+    changePending = false
+    emit('change', snapshot())
+  })
+}
+
+provide(KanbanDIKey, {
+  kanbanProps: props,
+  cls,
+  reorderColumn,
+  notifyChange
+} satisfies KanbanContext)
+</script>

package/src/components/kanban/style.scss

@@ -0,0 +1,124 @@
+@use 'pkg:@veltra/styles/mixins' as m;
+@use 'pkg:@veltra/styles/functions' as fn;
+@use 'pkg:@veltra/styles/vars';
+
+@include m.b(kanban) {
+  @include m.flex($align: flex-start, $wrap: nowrap);
+  gap: fn.use-var(gap, default);
+  padding: fn.use-var(gap, default);
+  overflow-x: auto;
+  box-sizing: border-box;
+
+  @include m.e(column) {
+    flex: 0 0 auto;
+    width: 280px;
+    max-width: 100%;
+    display: flex;
+    flex-direction: column;
+    gap: fn.use-var(gap, small);
+    padding: fn.use-var(gap, small);
+    background-color: fn.use-var(bg-color, bottom);
+    border-radius: fn.use-var(radius, default);
+    box-sizing: border-box;
+  }
+
+  @include m.e(column-header) {
+    @include m.flex;
+    gap: fn.use-var(gap, small);
+    padding: 0 2px;
+  }
+
+  @include m.e(column-title) {
+    @include m.ellipsis;
+    flex: 1 1 0%;
+    min-width: 0;
+    font-size: fn.use-var(font-size-main, default);
+    font-weight: 600;
+    color: fn.use-var(text-color, title);
+  }
+
+  @include m.e(column-count) {
+    flex: none;
+    min-width: 18px;
+    padding: 0 6px;
+    border-radius: fn.use-var(radius, large);
+    background-color: fn.color-a(color, 11, primary);
+    color: fn.use-var(color, primary);
+    font-size: fn.use-var(font-size-main, small);
+    line-height: 18px;
+    text-align: center;
+  }
+
+  @include m.e(cards) {
+    display: flex;
+    flex-direction: column;
+    gap: fn.use-var(gap, small);
+    // 空列也保持可拖入的目标高度
+    min-height: 64px;
+    padding: 2px;
+
+    &.is-dropzone {
+      background-color: fn.color-a(color, 4, primary);
+      border-radius: fn.use-var(radius, default);
+    }
+  }
+
+  @include m.e(card) {
+    @include m.flex($align: flex-start);
+    gap: fn.use-var(gap, small);
+    padding: fn.use-var(gap, small);
+    background-color: fn.use-var(bg-color, top);
+    border-radius: fn.use-var(radius, default);
+    box-shadow: fn.use-var(shadow, sm);
+    font-size: fn.use-var(font-size-main, default);
+    color: fn.use-var(text-color, main);
+    transition:
+      box-shadow fn.use-var(transition, fast) fn.use-var(transition, ease),
+      opacity fn.use-var(transition, fast) fn.use-var(transition, ease);
+
+    &:hover {
+      box-shadow: fn.use-var(shadow);
+    }
+
+    &.is-dragging {
+      opacity: 0.6;
+    }
+  }
+
+  @include m.e(card-handle) {
+    flex: none;
+    line-height: 1;
+    color: fn.use-var(text-color, assist);
+    cursor: grab;
+    user-select: none;
+
+    &:active {
+      cursor: grabbing;
+    }
+  }
+
+  @include m.e(card-body) {
+    flex: 1 1 0%;
+    min-width: 0;
+    word-break: break-word;
+  }
+
+  @include m.e(empty) {
+    border: 1px dashed fn.use-var(border-color);
+    border-radius: fn.use-var(radius, default);
+    padding: fn.use-var(gap, default) fn.use-var(gap, small);
+    font-size: fn.use-var(font-size-main, default);
+    color: fn.use-var(text-color, assist);
+    text-align: center;
+  }
+
+  @include m.is(disabled) {
+    @include m.bem(kanban, card-handle) {
+      cursor: not-allowed;
+
+      &:active {
+        cursor: not-allowed;
+      }
+    }
+  }
+}

package/src/components/kanban/style.ts

@@ -0,0 +1 @@
+import './style.scss'

package/src/components/multi-select/multi-select.vue

@@ -80,11 +80,14 @@
         虚拟化启用时内容容器 height 由 useVirtualizer 命令式写入；
         模板不再绑定 totalSize，避免尺寸变化引起重渲染。
       -->
+      <div v-if="loading" :class="cls.e('loading')">
+        <ULoading type="dual-ring" />
+      </div>
       <u-scroll
         tag="ul"
         :class="[cls.e('options')]"
         ref="scrollRef"
-        v-if="options.length"
+        v-else-if="options.length"
         :content-class="[cls.e('options-wrap'), bem.is('virtual', virtualEnabled)]"
       >
         <template v-if="virtualEnabled">
@@ -166,6 +169,7 @@ import { UCheckbox } from '../checkbox'
 import { UDropdown } from '../dropdown'
 import { UEmpty } from '../empty'
 import { UIcon } from '../icon'
+import { ULoading } from '../loading'
 import { UScroll } from '../scroll'
 import { useOptions } from '../select/use-options'
 import { UTag } from '../tag'
@@ -204,7 +208,12 @@ const scrollRef = shallowRef<ScrollExposed>()
 
 const hovered = shallowRef(false)
 
-const { options: rawOptions, queryString, allOptions: rawAllOptions } = useOptions({ props })
+const {
+  options: rawOptions,
+  queryString,
+  loading,
+  allOptions: rawAllOptions
+} = useOptions({ props })
 
 const createdOptions = shallowRef<Record<string, any>[]>([])
 

package/src/components/multi-select/style.scss

@@ -170,4 +170,10 @@ $root-name: multi-select;
     text-align: center;
     padding: fn.use-var(gap, default) 0;
   }
+
+  @include m.e(loading) {
+    // 与选项内容区同高，加载期间保持面板形态，避免塌缩成贴着输入框的小条
+    @include m.flex($justify: center, $align: center);
+    min-height: 240px;
+  }
 }

package/src/components/multi-tree-select/multi-tree-select.vue

@@ -71,15 +71,19 @@
           {{ allExpanded ? '收起全部' : '展开全部' }}
         </u-button>
       </div>
+      <div v-if="remoteLoading" :class="cls.e('loading')">
+        <ULoading type="dual-ring" />
+      </div>
       <!-- 菜单列表 -->
       <u-tree
+        v-else
         v-bind="treeProps"
         v-model:checked="model"
         @update:checked="handleCheck"
         ref="treeRef"
         :class="cls.e('content-tree')"
         checkable
-        :data="data"
+        :data="treeData"
         :slots="slots"
         scroll-to-view
       ></u-tree>
@@ -100,7 +104,7 @@
 </template>
 
 <script lang="ts" setup>
-import { dfs, o } from '@cat-kit/core'
+import { debounce, dfs, o } from '@cat-kit/core'
 import { useFormFallbackProps } from '@veltra/compositions'
 import { ArrowDown, Close } from '@veltra/icons/normal'
 import { bem, fieldKey, FORM_EMPTY_CONTENT } from '@veltra/utils'
@@ -113,6 +117,7 @@ import { UButton } from '../button'
 import { UCheckbox } from '../checkbox'
 import { UDropdown } from '../dropdown'
 import { UIcon } from '../icon'
+import { ULoading } from '../loading'
 import { UTag } from '../tag'
 import { UTree } from '../tree'
 import type { TreeSlotsScope } from '../tree/di'
@@ -148,6 +153,7 @@ const treeProps = computed(() => {
     'label',
     'readonly',
     'modelValue',
+    'data',
     'contentClass',
     'contentStyle',
     'minWidth',
@@ -159,11 +165,56 @@ const emit = defineEmits<MultiTreeSelectEmits>()
 
 const slots = defineSlots<{ default?: (props: TreeSlotsScope) => any }>()
 
-/**过滤 */
+/** 是否可搜索：显式声明或数据源为远程函数 */
+const filterable = computed(() => props.filterable || typeof props.data === 'function')
+
+/** 过滤 */
 const qs = shallowRef('')
-watch(qs, (qs) => {
-  treeRef.value?.filter(qs)
-})
+
+const treeRef = shallowRef<TreeExposed>()
+
+/** 远程搜索返回的树数据 */
+const remoteData = shallowRef<Record<string, any>[]>()
+
+/** 面板渲染的树数据：data 为函数时来自远程搜索，否则为静态数据 */
+const treeData = computed(() => (typeof props.data === 'function' ? remoteData.value : props.data))
+
+const remoteLoading = shallowRef(false)
+/** 远程请求序号；响应返回时序号不一致说明已有更新的请求，结果作废 */
+let remoteSeq = 0
+
+const debouncedRemoteSearch = debounce(
+  async (
+    query: string,
+    dataFn: (qs: string) => Promise<Record<string, any>[]> | Record<string, any>[]
+  ) => {
+    const seq = ++remoteSeq
+    remoteLoading.value = true
+    try {
+      const data = await dataFn(query)
+      // 响应到达时查询词可能已变化或已有更新的请求，过期结果直接丢弃
+      if (seq !== remoteSeq || query !== qs.value) return
+      remoteData.value = data ?? []
+      // 搜索结果展示完整命中路径，与本地过滤自动展开祖先的行为对齐
+      if (query) nextTick(() => treeRef.value?.expandAll())
+    } finally {
+      if (seq === remoteSeq) remoteLoading.value = false
+    }
+  },
+  200
+)
+
+watch(
+  [qs, () => props.data],
+  ([query, data]) => {
+    if (typeof data === 'function') {
+      debouncedRemoteSearch(query, data)
+      return
+    }
+    treeRef.value?.filter(query)
+  },
+  { immediate: true }
+)
 
 const model = defineModel<(string | number)[]>({ default: () => [] })
 
@@ -179,8 +230,6 @@ const showClear = computed(() => {
   return props.clearable && model.value?.length && hovered.value && !disabled.value
 })
 
-const treeRef = shallowRef<TreeExposed>()
-
 const dropdownRef = shallowRef<DropdownExposed>()
 
 let changedByEvent = false
@@ -237,7 +286,7 @@ const handleClear = () => {
 const keyDicts = shallowRef(new Map<string | number, Record<string, any>>())
 
 watch(
-  () => props.data,
+  treeData,
   (data) => {
     if (!data?.length) {
       keyDicts.value = new Map()