@veltra/desktop 1.7.9 → 1.7.11

package/src/components/drawer/drawer.vue

@@ -1,6 +1,6 @@
 <template>
   <Teleport to="body">
-    <transition name="fade" mode="out-in" @enter="onEnter">
+    <transition name="fade" mode="out-in" @enter="onEnter" @after-leave="emit('closed')">
       <div v-if="overlayVisible" :class="overlayCls.b" :style="{ zIndex: zIndex() }" @click="close">
         <transition :name="transitionName" appear @after-leave="onAfterDrawerLeave">
           <div
@@ -10,6 +10,9 @@
             :style="drawerStyle"
             @click.stop
           >
+            <div v-if="title" :class="cls.e('header')">
+              <span :class="cls.e('title')">{{ title }}</span>
+            </div>
             <span :class="cls.e('close')" @click="close" v-if="showClose">
               <u-icon><Close /></u-icon>
             </span>
@@ -31,7 +34,7 @@ import { UIcon } from '../icon'
 
 defineOptions({ name: 'UDrawer', inheritAttrs: false })
 
-const props = withDefaults(defineProps<DrawerProps>(), { direction: 'right', closable: true })
+const props = withDefaults(defineProps<DrawerProps>(), { direction: 'right' })
 
 const emit = defineEmits<DrawerEmits>()
 

package/src/components/drawer/style.scss

@@ -40,6 +40,21 @@ $direction-map: (
     justify-content: center;
   }
 
+  // 标题栏：传入 title 时渲染在内容区上方，其余行为与把标题写进默认插槽一致
+  @include m.e(header) {
+    height: $close-size;
+    flex-shrink: 0;
+    padding: 0 fn.use-var(gap, default);
+    font-size: fn.use-var(font-size-title, default);
+    border-bottom: fn.use-var(border);
+    @include m.flex();
+  }
+
+  @include m.e(title) {
+    font-weight: 600;
+    line-height: 1em;
+  }
+
   @include m.is(right, left) {
     top: $edge-offset;
     bottom: $edge-offset;

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

@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'vitest'
+import { createApp, h, nextTick, reactive, ref } from 'vue'
+
+import { UInput } from '../../input'
+import { USelect } from '../../select'
+import { UForm } from '../index'
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+const behaviorOptions = [
+  { label: '事件', value: 'event' },
+  { label: '接口', value: 'api' }
+]
+
+async function openSelect(host: HTMLElement) {
+  const input = host.querySelector('input')!
+  input.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true }))
+  await nextTick()
+  await nextTick()
+}
+
+async function clickSelectOption(label: string) {
+  const option = [...document.body.querySelectorAll<HTMLElement>('.u-select__option')].find(
+    (el) => el.textContent === label
+  )
+  expect(option, `选项「${label}」应存在`).toBeTruthy()
+  option!.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+  await nextTick()
+  await sleep(50)
+}
+
+describe('UForm field events', () => {
+  it('field:update and field:change are separate', async () => {
+    const host = document.createElement('div')
+    document.body.appendChild(host)
+
+    const model = reactive({ behavior: 'event' })
+    const updates: { field: string; value: unknown }[] = []
+    const changes: { field: string; args: unknown[] }[] = []
+
+    const app = createApp({
+      render() {
+        return h(
+          UForm,
+          {
+            model,
+            'onField:update': (field: string, value: unknown) => {
+              updates.push({ field, value })
+            },
+            'onField:change': (field: string, ...args: unknown[]) => {
+              changes.push({ field, args })
+            }
+          },
+          {
+            default: () =>
+              h(USelect, { field: 'behavior', label: '行为', options: behaviorOptions })
+          }
+        )
+      }
+    })
+
+    app.mount(host)
+    updates.length = 0
+    changes.length = 0
+
+    model.behavior = 'api'
+    await nextTick()
+
+    expect(updates.some((item) => item.field === 'behavior' && item.value === 'api')).toBe(true)
+    expect(changes).toHaveLength(0)
+
+    await openSelect(host)
+    await clickSelectOption('事件')
+
+    expect(changes).toHaveLength(1)
+    expect(changes[0]).toEqual({ field: 'behavior', args: [{ label: '事件', value: 'event' }] })
+
+    app.unmount()
+    host.remove()
+  })
+
+  it('父级重渲染时动态 props 同步到插槽控件', async () => {
+    const host = document.createElement('div')
+    document.body.appendChild(host)
+
+    const model = reactive({ username: '' })
+    const disabled = ref(false)
+    const placeholder = ref('第一次')
+
+    const app = createApp({
+      render() {
+        return h(
+          UForm,
+          { model },
+          {
+            default: () =>
+              h(UInput, {
+                field: 'username',
+                label: '账号',
+                disabled: disabled.value,
+                placeholder: placeholder.value
+              })
+          }
+        )
+      }
+    })
+
+    app.mount(host)
+
+    const input = () => host.querySelector('input')!
+    expect(input().disabled).toBe(false)
+    expect(input().placeholder).toBe('第一次')
+
+    disabled.value = true
+    placeholder.value = '第二次'
+    await nextTick()
+
+    expect(input().disabled).toBe(true)
+    expect(input().placeholder).toBe('第二次')
+
+    app.unmount()
+    host.remove()
+  })
+})

package/src/components/form/__test__/is-field-modified.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest'
+
+import { isFieldModified } from '../is-field-modified'
+
+describe('isFieldModified', () => {
+  it('primitive 严格相等视为未变更', () => {
+    expect(isFieldModified('a', 'a')).toBe(false)
+    expect(isFieldModified(1, 1)).toBe(false)
+    expect(isFieldModified(true, true)).toBe(false)
+  })
+
+  it('primitive 不等视为已变更', () => {
+    expect(isFieldModified('a', 'b')).toBe(true)
+    expect(isFieldModified(1, 2)).toBe(true)
+    expect(isFieldModified(true, false)).toBe(true)
+  })
+
+  it('nullish 空值等价视为未变更', () => {
+    expect(isFieldModified(null, undefined)).toBe(false)
+    expect(isFieldModified(undefined, '')).toBe(false)
+    expect(isFieldModified('', null)).toBe(false)
+    expect(isFieldModified(null, null)).toBe(false)
+  })
+
+  it('数组与对象按 JSON 深比较', () => {
+    expect(isFieldModified([1, 2], [1, 2])).toBe(false)
+    expect(isFieldModified([1, 2], [1, 3])).toBe(true)
+    expect(isFieldModified({ a: 1 }, { a: 1 })).toBe(false)
+    expect(isFieldModified({ a: 1 }, { a: 2 })).toBe(true)
+  })
+
+  it('undefined 与有值视为已变更', () => {
+    expect(isFieldModified(undefined, 'x')).toBe(true)
+    expect(isFieldModified('x', undefined)).toBe(true)
+    expect(isFieldModified(null, 'x')).toBe(true)
+  })
+})

package/src/components/form/form.vue

@@ -17,6 +17,10 @@
           :model-value="modelValue ?? o(model ?? {}).get(field)"
           @update:model-value="handleUpdateValue(field, $event)"
         />
+        <div v-if="shouldShowModified(field)" :class="cls.e('data-before')">
+          <span :class="cls.e('changed-tag')">{{ modifiedLabel }}</span>
+          <component :is="node" readonly :model-value="getBaselineFieldValue(field)" />
+        </div>
       </u-form-item>
 
       <component v-else :is="node" />
@@ -33,12 +37,13 @@ import { nextTick, toRef, useTemplateRef } from 'vue'
 import type { BreakCols, FormProps, _FormExposed, FormEmits } from '../../types'
 import { UFormItem } from '../form-item'
 import { UGrid } from '../grid'
+import { isFieldModified } from './is-field-modified'
 import { useFormFields } from './use-form-fields'
 import { useNodeInterceptor } from './use-node-interceptor'
 
 defineOptions({ name: 'UForm' })
 
-const props = defineProps<FormProps>()
+const props = withDefaults(defineProps<FormProps>(), { modifiedLabel: '变更前：' })
 
 const emit = defineEmits<FormEmits>()
 
@@ -56,7 +61,8 @@ const {
   reset,
   registerField,
   unregisterField,
-  shouldValidate
+  shouldValidate,
+  getBaselineModel
 } = useFormFields({ props })
 
 async function validate(keys?: string[]) {
@@ -71,8 +77,12 @@ async function validate(keys?: string[]) {
   return valid
 }
 
-function handleFieldChange(field: string, value: any) {
-  emit('field:change', field, value)
+function handleFieldUpdate(field: string, value: any) {
+  emit('field:update', field, value)
+}
+
+function handleFieldChange(field: string, ...args: any[]) {
+  emit('field:change', field, ...args)
 }
 
 provideFormContext({
@@ -81,6 +91,7 @@ provideFormContext({
   unregisterField,
   validateFields: validate,
   shouldValidate,
+  handleFieldUpdate,
   handleFieldChange
 })
 
@@ -91,5 +102,18 @@ function handleUpdateValue(field: string, value: any) {
   o(props.model).set(field, value)
 }
 
+function getBaselineFieldValue(field: string) {
+  return o(getBaselineModel() ?? {}).get(field)
+}
+
+function shouldShowModified(field: string) {
+  if (!props.showModified) return false
+  const baseline = getBaselineModel()
+  if (!baseline || !props.model) return false
+  const current = o(props.model).get(field)
+  const initial = o(baseline).get(field)
+  return isFieldModified(current, initial)
+}
+
 defineExpose<_FormExposed>({ el: toRef(() => gridRef.value?.el), validate, clearValidate, reset })
 </script>

package/src/components/form/is-field-modified.ts

@@ -0,0 +1,16 @@
+/** 判断字段当前值相对基准值是否已变更 */
+export function isFieldModified(current: unknown, initial: unknown): boolean {
+  if (current === initial) return false
+
+  const currentNullish = current === null || current === undefined || current === ''
+  const initialNullish = initial === null || initial === undefined || initial === ''
+  if (currentNullish && initialNullish) return false
+
+  const currentIsObject = current !== null && typeof current === 'object'
+  const initialIsObject = initial !== null && typeof initial === 'object'
+  if (currentIsObject || initialIsObject) {
+    return JSON.stringify(current) !== JSON.stringify(initial)
+  }
+
+  return true
+}

package/src/components/form/style.scss

@@ -16,12 +16,63 @@
   }
 
   @include m.e(data-before) {
-    width: 100%;
-    line-height: 1.3;
+    display: flex;
+    align-items: center;
+    gap: 4px;
+    flex-wrap: wrap;
+    margin-top: 4px;
+    padding: 2px 8px;
+    border-left: 2px solid fn.use-var(color, info);
+    background-color: fn.color-a(color, 8, info);
+    border-radius: 2px;
+    width: fit-content;
+    max-width: 100%;
+    line-height: 1.4;
+    font-size: fn.use-var(font-size, assist, default);
+
+    // 文本类控件保持全宽，便于展示较长内容
+    &:has(#{fn.bem(input)}),
+    &:has(#{fn.bem(textarea)}),
+    &:has(#{fn.bem(select)}),
+    &:has(#{fn.bem(multi-select)}),
+    &:has(#{fn.bem(multi-tree-select)}),
+    &:has(#{fn.bem(auto-complete)}),
+    &:has(#{fn.bem(cascade)}),
+    &:has(#{fn.bem(date-picker)}),
+    &:has(#{fn.bem(date-range-picker)}),
+    &:has(#{fn.bem(number-input)}),
+    &:has(#{fn.bem(tree-select)}) {
+      width: 100%;
+    }
+
+    // 让内部只读控件更像辅助说明，减少「第二个输入框」感
+    @include m.bem(form-item, content) {
+      background: transparent;
+      padding: 0;
+    }
+
+    #{fn.bem(input)},
+    #{fn.bem(textarea)},
+    #{fn.bem(select)},
+    #{fn.bem(multi-select)},
+    #{fn.bem(multi-tree-select)},
+    #{fn.bem(auto-complete)},
+    #{fn.bem(cascade)},
+    #{fn.bem(date-picker)},
+    #{fn.bem(date-range-picker)} {
+      border: none;
+      box-shadow: none;
+      background: transparent;
+      min-height: auto;
+      height: auto;
+      padding: 0;
+    }
   }
 
   @include m.e(changed-tag) {
     color: fn.use-var(color, info);
     font-size: fn.use-var(font-size, assist, default);
+    font-style: normal;
+    flex-shrink: 0;
   }
 }

package/src/components/form/use-form-fields.ts

@@ -1,6 +1,6 @@
 import { copy, o } from '@cat-kit/core'
 import type { FormFieldItem } from '@veltra/utils'
-import { nextTick, watch } from 'vue'
+import { nextTick, shallowRef, watch } from 'vue'
 
 import type { FormProps } from '../../types/form'
 
@@ -42,7 +42,7 @@ export function useFormFields(options: Options) {
   let willValidate = true
 
   /** model 初始快照，供 reset 恢复 */
-  let initialSnapshot: Record<string, any> | undefined
+  const initialSnapshot = shallowRef<Record<string, any> | undefined>()
 
   function runWithoutChangeValidate(fn: () => void) {
     willValidate = false
@@ -59,7 +59,7 @@ export function useFormFields(options: Options) {
   watch(
     () => props.model,
     (model) => {
-      initialSnapshot = model ? copy(model) : undefined
+      initialSnapshot.value = model ? copy(model) : undefined
     },
     { immediate: true, deep: false }
   )
@@ -89,13 +89,27 @@ export function useFormFields(options: Options) {
   }
 
   function reset() {
-    if (!props.model || !initialSnapshot) return
+    if (!props.model || !initialSnapshot.value) return
 
     runWithoutChangeValidate(() => {
-      applySnapshot(props.model!, initialSnapshot!)
+      applySnapshot(props.model!, initialSnapshot.value!)
       Object.values(fields).forEach((item) => item.clearValidate?.())
     })
   }
 
-  return { fields, registerField, validate, unregisterField, clearValidate, reset, shouldValidate }
+  /** 变更前基准数据：优先 initialModel，否则为 model 引用变更时的快照 */
+  function getBaselineModel() {
+    return props.initialModel ?? initialSnapshot.value
+  }
+
+  return {
+    fields,
+    registerField,
+    validate,
+    unregisterField,
+    clearValidate,
+    reset,
+    shouldValidate,
+    getBaselineModel
+  }
 }

package/src/components/form-item/__test__/form-item.test.ts

@@ -0,0 +1,129 @@
+import { describe, expect, it } from 'vitest'
+import { createApp, h, nextTick, reactive, ref } from 'vue'
+
+import { UForm } from '../../form'
+import { UInput } from '../../input'
+import { USelect } from '../../select'
+import { UFormItem } from '../index'
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+const behaviorOptions = [
+  { label: '事件', value: 'event' },
+  { label: '接口', value: 'api' }
+]
+
+async function openSelect(host: HTMLElement) {
+  const input = host.querySelector('input')!
+  input.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true }))
+  await nextTick()
+  await nextTick()
+}
+
+async function clickSelectOption(label: string) {
+  const option = [...document.body.querySelectorAll<HTMLElement>('.u-select__option')].find(
+    (el) => el.textContent === label
+  )
+  expect(option, `选项「${label}」应存在`).toBeTruthy()
+  option!.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+  await nextTick()
+  await sleep(50)
+}
+
+describe('UFormItem change', () => {
+  it('forwards Select change with option object', async () => {
+    const host = document.createElement('div')
+    document.body.appendChild(host)
+
+    const model = reactive({ behavior: 'event' })
+    const itemChanges: unknown[][] = []
+    const formChanges: { field: string; args: unknown[] }[] = []
+
+    const app = createApp({
+      render() {
+        return h(
+          UForm,
+          {
+            model,
+            'onField:change': (field: string, ...args: unknown[]) => {
+              formChanges.push({ field, args })
+            }
+          },
+          {
+            default: () =>
+              h(
+                UFormItem,
+                {
+                  field: 'behavior',
+                  label: '行为',
+                  onChange: (...args: unknown[]) => itemChanges.push(args)
+                },
+                {
+                  default: () =>
+                    h(USelect, {
+                      modelValue: model.behavior,
+                      'onUpdate:modelValue': (value: string) => {
+                        model.behavior = value
+                      },
+                      options: behaviorOptions
+                    })
+                }
+              )
+          }
+        )
+      }
+    })
+
+    app.mount(host)
+
+    await openSelect(host)
+    await clickSelectOption('接口')
+
+    expect(itemChanges).toHaveLength(1)
+    expect(itemChanges[0]![0]).toEqual({ label: '接口', value: 'api' })
+
+    expect(formChanges).toHaveLength(1)
+    expect(formChanges[0]).toEqual({ field: 'behavior', args: [{ label: '接口', value: 'api' }] })
+
+    app.unmount()
+    host.remove()
+  })
+
+  it('显式 UFormItem 内控件的动态 props 随父级更新', async () => {
+    const host = document.createElement('div')
+    document.body.appendChild(host)
+
+    const model = reactive({ name: '' })
+    const disabled = ref(false)
+
+    const app = createApp({
+      render() {
+        return h(
+          UForm,
+          { model },
+          {
+            default: () =>
+              h(
+                UFormItem,
+                { field: 'name', label: '姓名' },
+                { default: () => h(UInput, { modelValue: model.name, disabled: disabled.value }) }
+              )
+          }
+        )
+      }
+    })
+
+    app.mount(host)
+
+    const input = () => host.querySelector('input')!
+    expect(input().disabled).toBe(false)
+
+    disabled.value = true
+    await nextTick()
+
+    expect(input().disabled).toBe(true)
+
+    app.unmount()
+    host.remove()
+  })
+})

package/src/components/form-item/form-item.vue

@@ -17,7 +17,9 @@
 
     <section :class="cls.e('wrapper')">
       <div :class="cls.e('content')">
-        <slot></slot>
+        <ContentSlot>
+          <slot></slot>
+        </ContentSlot>
       </div>
 
       <!-- 只有表单控件处于非只读状态时，才显示错误提示 -->
@@ -35,11 +37,20 @@
 <script lang="tsx" setup>
 import { o } from '@cat-kit/core'
 import { useConfig, useFallbackProps } from '@veltra/compositions'
-import { bem, withUnit } from '@veltra/utils'
+import { bem, extractNormalVNodes, withUnit } from '@veltra/utils'
 import { injectFormContext } from '@veltra/utils'
-import { type CSSProperties, computed, onBeforeUnmount, shallowRef, watch } from 'vue'
-
-import type { FormItemProps, ComponentSize } from '../../types'
+import {
+  type CSSProperties,
+  type SetupContext,
+  type VNode,
+  cloneVNode,
+  computed,
+  onBeforeUnmount,
+  shallowRef,
+  watch
+} from 'vue'
+
+import type { FormItemEmits, FormItemProps, ComponentSize } from '../../types'
 import { UGridItem } from '../grid'
 import { UTip } from '../tip'
 import { formItemCls as cls, defineField } from './helper'
@@ -49,6 +60,8 @@ defineOptions({ name: 'UFormItem' })
 
 const props = withDefaults(defineProps<FormItemProps>(), { readonly: undefined })
 
+const emit = defineEmits<FormItemEmits>()
+
 defineSlots<{
   /** 标签插槽 */
   label?: () => any
@@ -56,8 +69,34 @@ defineSlots<{
 }>()
 
 /** 表单组件上下文 */
-const { formProps, registerField, unregisterField, shouldValidate, handleFieldChange } =
-  injectFormContext()
+const {
+  formProps,
+  registerField,
+  unregisterField,
+  shouldValidate,
+  handleFieldUpdate,
+  handleFieldChange
+} = injectFormContext()
+
+function wrapControlChange(node: VNode) {
+  if (!node || typeof node.type === 'symbol') return node
+
+  return cloneVNode(node, {
+    onChange: (...args: any[]) => {
+      emit('change', ...args)
+      if (props.field) handleFieldChange?.(props.field, ...args)
+    }
+  })
+}
+
+/**
+ * 承载默认插槽并拦截控件 change。
+ * 必须经填充插槽接收内容（而非直接读 UFormItem 的 $slots）：
+ * 读父级 $slots 时组件自身没有更新路径，父级重渲染后动态 props（disabled、data 等）会冻结在首帧。
+ */
+function ContentSlot(_: unknown, { slots }: SetupContext) {
+  return extractNormalVNodes(slots.default?.() ?? []).map(wrapControlChange)
+}
 
 const { config } = useConfig()
 
@@ -137,7 +176,7 @@ watch(
     stopWatchFieldValue = watch(
       () => o(model).get(field),
       (value) => {
-        handleFieldChange?.(field, value)
+        handleFieldUpdate?.(field, value)
         fieldItem.validate()
       }
     )

package/src/types/action.ts

@@ -4,7 +4,12 @@ import type { ButtonProps } from './button'
 
 /** 操作组件属性 */
 export interface ActionProps extends ButtonProps {
-  /** 是否需要确认 */
+  /**
+   * 是否需要确认：true 时点击只弹确认气泡（UPopConfirm），点气泡里的「确认」才触发 `run`
+   * @default false
+   * @description 不要在本项的 `run` 回调里再调 `messageConfirm`：`run` 触发时气泡已经确认过一次，
+   * 会变成两次确认。需要弹窗级确认时去掉 `needConfirm`，只在 `run` 里用 `messageConfirm`
+   */
   needConfirm?: boolean
 
   /**

package/src/types/batch-edit.ts

@@ -115,6 +115,8 @@ export interface BatchEditProps extends TableProps {
 
 /** 批量编辑组件定义的事件 */
 export interface BatchEditEmits extends TableEmits {
+  /** 表单控件 change，透传自 UForm */
+  (e: 'field:change', field: string, ...args: any[]): void
   /** 更新数据 */
   (e: 'update:data', value: Record<string, any>[]): void
   /** 点击底部「新增一行」 */

package/src/types/button.ts

@@ -4,7 +4,11 @@ import type { Component, ShallowRef } from 'vue'
 /** 按钮类型 */
 export type ButtonType = ColorType
 
-/** 按钮属性类型 */
+/**
+ * 按钮属性类型
+ * @description 组件不注入默认 `aria-label`：可访问名来自默认插槽文本，
+ * 或你自己传入的 `aria-label`（透传到根元素）；只有图标的按钮必须自行传 `aria-label`
+ */
 export interface ButtonProps extends ComponentProps {
   /** 按钮类型 */
   type?: ButtonType