@veltra/desktop 1.8.0 → 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'