@veltra/mobile 1.0.0 → 1.1.0

package/src/components/drawer/style.ts

@@ -0,0 +1,2 @@
+import '@veltra/styles/transitions/fade.scss'
+import './style.scss'

package/src/components/empty/empty.vue

@@ -0,0 +1,22 @@
+<template>
+  <span :class="cls.b">
+    <span :class="cls.e('icon')" :style="{ fontSize: withUnit(size, 'px') }">
+      <Empty />
+    </span>
+    <div :class="cls.e('text')">{{ text }}</div>
+  </span>
+</template>
+
+<script lang="ts" setup>
+import { Empty } from '@veltra/icons/normal'
+import { withUnit } from '@veltra/utils'
+
+import { bem } from '../../shared/bem'
+import type { EmptyProps } from '../../types/empty'
+
+defineOptions({ name: 'UEmpty' })
+
+const { size = 48, text = '暂无数据' } = defineProps<EmptyProps>()
+
+const cls = bem('empty')
+</script>

package/src/components/empty/index.ts

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

package/src/components/empty/style.scss

@@ -0,0 +1,36 @@
+@use 'pkg:@veltra/styles/mixins' as m with ($namespace: um);
+@use 'pkg:@veltra/styles/functions' as fn;
+@use '../../styles/tokens' as t;
+
+// 方便拼接
+$root-name: empty;
+
+@include m.b($root-name) {
+  color: fn.use-var(text-color, assist);
+  text-align: center;
+  display: inline-flex;
+  flex-direction: column;
+  align-items: center;
+  gap: t.use-var(spacing-md);
+  user-select: none;
+
+  // 图标占位：以 1em 跟随 size 缩放（移动端包内暂无 UIcon，直接承载图标 svg）
+  @include m.e(icon) {
+    display: inline-flex;
+    width: 1em;
+    height: 1em;
+    line-height: 1em;
+    fill: currentColor;
+
+    svg {
+      width: 1em;
+      height: 1em;
+    }
+  }
+
+  // 空态文本：移动端密度用次字号（14px）
+  @include m.e(text) {
+    font-size: t.use-var(font-size-secondary);
+    line-height: 1.5;
+  }
+}

package/src/components/empty/style.ts

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

package/src/components/form/form.vue

@@ -0,0 +1,119 @@
+<template>
+  <form ref="formRef" :class="[cls.b, bem.is('readonly', readonly)]" @submit.prevent>
+    <div v-if="props.title || $slots.header" :class="cls.e('title')">
+      <slot name="header">{{ props.title }}</slot>
+    </div>
+
+    <template
+      v-for="{ node, isFormItem, formItemProps, field, modelValue, renderKey } of getSlotsNodes()"
+      :key="renderKey"
+    >
+      <UFormItem v-if="!isFormItem && field" v-bind="formItemProps">
+        <component
+          :is="node"
+          :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>
+          {{ formatModifiedValue(getBaselineFieldValue(field)) }}
+        </div>
+      </UFormItem>
+
+      <component v-else :is="node" />
+    </template>
+  </form>
+</template>
+
+<script lang="ts" setup>
+import { o } from '@cat-kit/core'
+import { FORM_EMPTY_CONTENT, provideFormContext } from '@veltra/utils'
+import { nextTick, toRef, useTemplateRef } from 'vue'
+
+import { bem } from '../../shared/bem'
+import type { FormEmits, FormProps, _FormExposed } from '../../types/form'
+import { UFormItem } from '../form-item'
+import { isFieldModified } from './is-field-modified'
+import { useFormFields } from './use-form-fields'
+import { useNodeInterceptor } from './use-node-interceptor'
+
+defineOptions({ name: 'UForm' })
+
+const props = withDefaults(defineProps<FormProps>(), { modifiedLabel: '变更前：' })
+
+const emit = defineEmits<FormEmits>()
+
+defineSlots<{
+  /** 分组标题插槽，优先于 title prop */
+  header?: () => any
+  default?: () => any
+}>()
+
+const cls = bem('form')
+const formItemCls = bem('form-item')
+const formRef = useTemplateRef<HTMLFormElement>('formRef')
+
+const {
+  validate: runValidate,
+  clearValidate,
+  reset,
+  registerField,
+  unregisterField,
+  shouldValidate,
+  getBaselineModel
+} = useFormFields({ props })
+
+/** 校验失败后滚动到第一条错误提示，保证小屏上错误可见 */
+async function validate(keys?: string[]) {
+  const valid = await runValidate(keys)
+  if (!valid) {
+    await nextTick()
+
+    formRef.value
+      ?.querySelector(`.${formItemCls.e('error-text')}`)
+      ?.scrollIntoView({ block: 'center' })
+  }
+  return valid
+}
+
+provideFormContext({
+  formProps: props,
+  registerField,
+  unregisterField,
+  validateFields: validate,
+  shouldValidate,
+  handleFieldUpdate(field: string, value: any) {
+    emit('field:update', field, value)
+  }
+})
+
+const { getSlotsNodes } = useNodeInterceptor()
+
+function handleUpdateValue(field: string, value: any) {
+  if (!props.model) return
+  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)
+}
+
+/** 变更前值按纯文本呈现（移动端密度），不克隆只读控件 */
+function formatModifiedValue(value: unknown): string {
+  if (value === null || value === undefined || value === '') return FORM_EMPTY_CONTENT
+  if (Array.isArray(value)) return value.join('、')
+  if (typeof value === 'object') return JSON.stringify(value)
+  return String(value)
+}
+
+defineExpose<_FormExposed>({ el: toRef(() => formRef.value), validate, clearValidate, reset })
+</script>

package/src/components/form/index.ts

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

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

@@ -0,0 +1,58 @@
+@use 'pkg:@veltra/styles/mixins' as m with ($namespace: um);
+@use 'pkg:@veltra/styles/functions' as fn;
+@use '../../styles/tokens' as t;
+
+@include m.b(form) {
+  // 边框卡片式列表外观：行间分隔线由 form-item 的相邻选择器绘制
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+  width: 100%;
+  background-color: fn.use-var(bg-color);
+  border-radius: t.use-var('control-radius-large');
+  overflow: hidden;
+
+  // 分组标题
+  @include m.e(title) {
+    padding: t.use-var('spacing-md') t.use-var('spacing-lg') t.use-var('spacing-sm');
+    color: fn.use-var(text-color, second);
+    font-size: t.use-var('font-size-secondary');
+    line-height: 1.4;
+  }
+
+  // 只读态：label 退为次级文本，值保持正文色（行式呈现）
+  @include m.is(readonly) {
+    @include m.bem(form-item, label) {
+      color: fn.use-var(text-color, second);
+    }
+
+    @include m.bem(form-item, content) {
+      color: fn.use-var(text-color, main);
+    }
+  }
+
+  // 变更前：以信息色文本行呈现（移动端密度）
+  @include m.e(data-before) {
+    display: flex;
+    align-items: baseline;
+    gap: t.use-var('spacing-xs');
+    flex-wrap: wrap;
+    width: fit-content;
+    max-width: 100%;
+    margin-top: t.use-var('spacing-xs');
+    padding: 2px t.use-var('spacing-xs');
+    border-left: 2px solid fn.use-var(color, info);
+    background-color: fn.color-a(color, 8, info);
+    border-radius: 2px;
+    line-height: 1.4;
+    font-size: t.use-var('font-size-secondary');
+    color: fn.use-var(text-color, main);
+    word-break: break-all;
+  }
+
+  @include m.e(changed-tag) {
+    color: fn.use-var(color, info);
+    font-style: normal;
+    flex-shrink: 0;
+  }
+}

package/src/components/form/style.ts

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

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

@@ -0,0 +1,115 @@
+import { copy, o } from '@cat-kit/core'
+import type { FormFieldItem } from '@veltra/utils'
+import { nextTick, shallowRef, watch } from 'vue'
+
+import type { FormProps } from '../../types/form'
+
+interface Options {
+  props: FormProps
+}
+
+/** 按快照逐字段写回 model，支持 undefined 与嵌套对象 */
+function applySnapshot(target: Record<string, any>, source: Record<string, any>) {
+  for (const key of Object.keys(source)) {
+    const sourceValue = source[key]
+    const targetValue = target[key]
+
+    if (
+      sourceValue !== null &&
+      typeof sourceValue === 'object' &&
+      !Array.isArray(sourceValue) &&
+      targetValue !== null &&
+      typeof targetValue === 'object' &&
+      !Array.isArray(targetValue)
+    ) {
+      applySnapshot(targetValue, sourceValue)
+      continue
+    }
+
+    if (Array.isArray(sourceValue)) {
+      o(target).set(key, copy(sourceValue))
+      continue
+    }
+
+    o(target).set(key, sourceValue)
+  }
+}
+
+export function useFormFields(options: Options) {
+  const { props } = options
+  const fields: Record<string, FormFieldItem> = {}
+
+  let willValidate = true
+
+  /** model 初始快照，供 reset 恢复 */
+  const initialSnapshot = shallowRef<Record<string, any> | undefined>()
+
+  function runWithoutChangeValidate(fn: () => void) {
+    willValidate = false
+    fn()
+    nextTick(() => {
+      willValidate = true
+    })
+  }
+
+  function shouldValidate() {
+    return willValidate
+  }
+
+  watch(
+    () => props.model,
+    (model) => {
+      initialSnapshot.value = model ? copy(model) : undefined
+    },
+    { immediate: true, deep: false }
+  )
+
+  function registerField(field: string, item: FormFieldItem) {
+    fields[field] = item
+  }
+
+  function unregisterField(field: string) {
+    delete fields[field]
+  }
+
+  function clearValidate() {
+    Object.values(fields).forEach((item) => item.clearValidate?.())
+  }
+
+  async function validate(keys?: string[]) {
+    let validList: boolean[]
+    if (keys) {
+      validList = await Promise.all(
+        keys.map((key) => fields[key]?.validate() ?? Promise.resolve(true))
+      )
+    } else {
+      validList = await Promise.all(Object.values(fields).map((field) => field.validate()))
+    }
+    return validList.every((valid) => valid)
+  }
+
+  function reset() {
+    if (!props.model || !initialSnapshot.value) return
+
+    runWithoutChangeValidate(() => {
+      applySnapshot(props.model!, initialSnapshot.value!)
+      Object.values(fields).forEach((item) => item.clearValidate?.())
+    })
+  }
+
+  /** 变更前基准数据：优先 initialModel，否则为 model 引用变更时的快照 */
+  function getBaselineModel() {
+    return props.initialModel ?? initialSnapshot.value
+  }
+
+  return {
+    fields,
+    registerField,
+    validate,
+    unregisterField,
+    clearValidate,
+    reset,
+    shouldValidate,
+    getBaselineModel
+  }
+}

package/src/components/form/use-node-interceptor.ts

@@ -0,0 +1,101 @@
+import { extractNormalVNodes } from '@veltra/utils'
+import { useSlots, type VNode } from 'vue'
+
+export type SlotRenderItem = {
+  isFormItem: boolean
+  formItemProps?: Record<string, any>
+  node: VNode
+  field?: string
+  modelValue?: any
+  /** v-for 身份：调用方 :key 优先，否则 type+field+出现次序 */
+  renderKey: string | number | symbol
+}
+
+function getVNodeTypeName(node: VNode): string {
+  const type = node.type as { name?: string; __name?: string } | string
+  if (typeof type === 'string') return type
+  if (typeof type === 'object' && type) return type.name || type.__name || ''
+  return ''
+}
+
+/** 裸控件 → 自动生成的 UFormItem 透传的属性白名单 */
+const FORM_ITEM_KEYS = [
+  'label',
+  'labelPosition',
+  'labelWidth',
+  'rules',
+  'span',
+  'tips',
+  'readonly',
+  'field'
+] as const
+
+/**
+ * 从裸控件 vnode 的 props 中挑出表单项属性。
+ * 模板 kebab 写法（label-position）在 vnode 原始 props 里不转驼峰，
+ * 因此驼峰 / kebab 双向取值，缺失的键不进入结果。
+ */
+function pickFormItemProps(raw: Record<string, any>): Record<string, any> {
+  const result: Record<string, any> = {}
+
+  for (const key of FORM_ITEM_KEYS) {
+    const kebab = key.replace(/[A-Z]/g, (ch) => `-${ch.toLowerCase()}`)
+    const value = raw[key] ?? raw[kebab]
+    if (value !== undefined) result[key] = value
+  }
+
+  return result
+}
+
+/**
+ * 虚拟node拦截：带 field 的裸控件由 UForm 包进 UFormItem，表单项与其余节点原样渲染
+ * @returns
+ */
+export function useNodeInterceptor(): { getSlotsNodes: () => SlotRenderItem[] | null } {
+  const slots = useSlots()
+
+  function getSlotsNodes() {
+    const nodes = slots.default?.()
+    if (!nodes?.length) return null
+
+    const flattedNodes = extractNormalVNodes(nodes)
+
+    const results: SlotRenderItem[] = []
+    const seen = new Map<string, number>()
+
+    let i = 0
+    while (i < flattedNodes.length) {
+      const node = flattedNodes[i]!
+      i++
+
+      const { props, type } = node
+      const field = props?.field as string | undefined
+      const isFormItem = (type as any)?.name === 'UFormItem'
+
+      const formItemProps = pickFormItemProps((props ?? {}) as Record<string, any>)
+
+      let renderKey: string | number | symbol
+      if (node.key != null) {
+        renderKey = node.key
+      } else {
+        const base = `${getVNodeTypeName(node)}:${field ?? ''}`
+        const n = seen.get(base) ?? 0
+        seen.set(base, n + 1)
+        renderKey = n === 0 ? `uform:${base}` : `uform:${base}#${n}`
+      }
+
+      results.push({
+        isFormItem,
+        formItemProps,
+        node,
+        field,
+        modelValue: props?.['model-value'] ?? props?.modelValue,
+        renderKey
+      })
+    }
+
+    return results
+  }
+
+  return { getSlotsNodes }
+}

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

@@ -0,0 +1,171 @@
+<template>
+  <div :class="className">
+    <label
+      v-if="props.label || $slots.label"
+      :class="[cls.e('label'), bem.is('required', !!rules?.required)]"
+      :style="labelStyles"
+    >
+      <slot name="label">{{ label }}</slot>
+    </label>
+
+    <section :class="cls.e('wrapper')">
+      <div :class="cls.e('content')">
+        <ContentSlot>
+          <slot></slot>
+        </ContentSlot>
+      </div>
+
+      <!-- 只有表单控件处于非只读状态时，才显示错误提示（行内下方，不弹桌面 tooltip） -->
+      <transition name="form-item-tips">
+        <span :class="cls.e('error-text')" v-if="!readonly && !formProps?.noTips && !!errorTip">
+          {{ errorTip }}
+        </span>
+      </transition>
+    </section>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { o } from '@cat-kit/core'
+import { useFallbackProps } from '@veltra/compositions'
+import { extractNormalVNodes, injectFormContext, withUnit } from '@veltra/utils'
+import type { ComponentSize } from '@veltra/utils'
+import {
+  type CSSProperties,
+  type SetupContext,
+  type VNode,
+  cloneVNode,
+  computed,
+  onBeforeUnmount,
+  shallowRef,
+  watch
+} from 'vue'
+
+import { bem } from '../../shared/bem'
+import type { FormItemEmits, FormItemProps } from '../../types/form-item'
+import { formItemCls as cls, defineField } from './helper'
+import { validateField } from './validate'
+
+defineOptions({ name: 'UFormItem' })
+
+const props = withDefaults(defineProps<FormItemProps>(), { readonly: undefined })
+
+const emit = defineEmits<FormItemEmits>()
+
+defineSlots<{
+  /** 标签插槽 */
+  label?: () => any
+  default?: () => any
+}>()
+
+/** 表单组件上下文 */
+const { formProps, registerField, unregisterField, shouldValidate, handleFieldUpdate } =
+  injectFormContext()
+
+function wrapControlChange(node: VNode) {
+  if (!node || typeof node.type === 'symbol') return node
+
+  return cloneVNode(node, {
+    onChange: (...args: any[]) => {
+      emit('change', ...args)
+    }
+  })
+}
+
+/**
+ * 承载默认插槽并拦截控件 change。
+ * 必须经填充插槽接收内容（而非直接读 UFormItem 的 $slots）：
+ * 读父级 $slots 时组件自身没有更新路径，父级重渲染后动态 props（disabled、data 等）会冻结在首帧。
+ */
+function ContentSlot(_: unknown, { slots }: SetupContext) {
+  return extractNormalVNodes(slots.default?.() ?? []).map(wrapControlChange)
+}
+
+const { size, readonly } = useFallbackProps([formProps ?? {}, props], {
+  size: 'default' as ComponentSize,
+  readonly: false
+})
+
+const errorTip = shallowRef<string>()
+/** 递增序号，丢弃过期的异步校验结果 */
+let validateSeq = 0
+/** 最近一次 validate 的 Promise，供过期调用等待最新结果 */
+let latestValidatePromise: Promise<boolean> = Promise.resolve(true)
+
+/** 移动端默认列表行式：label 在左、控件占右侧；'top' 时纵向堆叠 */
+const labelPosition = computed(() => props.labelPosition ?? formProps?.labelPosition ?? 'left')
+
+const className = computed(() => {
+  return [
+    cls.b,
+    cls.m(size.value),
+    bem.is('error', !!errorTip.value),
+    bem.is('label-top', labelPosition.value === 'top')
+  ].join(' ')
+})
+
+/** label 宽度：传了 labelWidth（自身或 UForm）用固定宽，否则按内容自适应 */
+const labelStyles = computed<CSSProperties>(() => {
+  if (labelPosition.value !== 'left') return {}
+  const width = props.labelWidth ?? formProps?.labelWidth
+  return width === undefined ? {} : { width: withUnit(width, 'px') }
+})
+
+const fieldItem = defineField({
+  clearValidate() {
+    errorTip.value = ''
+  },
+  async validate() {
+    if (!props.field || !formProps?.model || !props.rules || !shouldValidate?.()) return true
+
+    const seq = ++validateSeq
+
+    latestValidatePromise = validateField(formProps.model!, props.field!, props.rules!).then(
+      (tip) => {
+        if (seq !== validateSeq) return latestValidatePromise
+
+        errorTip.value = tip
+        return !errorTip.value
+      }
+    )
+    return latestValidatePromise
+  }
+})
+
+watch(
+  () => props.field,
+  (field, oldField) => {
+    if (oldField) {
+      unregisterField?.(oldField)
+    }
+    if (field) {
+      registerField?.(field, fieldItem)
+    }
+  },
+  { immediate: true }
+)
+
+let stopWatchFieldValue: (() => void) | undefined
+
+watch(
+  [() => formProps?.model, () => props.field],
+  ([model, field]) => {
+    stopWatchFieldValue?.()
+
+    if (!field || !model) return
+
+    stopWatchFieldValue = watch(
+      () => o(model).get(field),
+      (value) => {
+        handleFieldUpdate?.(field, value)
+        fieldItem.validate()
+      }
+    )
+  },
+  { immediate: true }
+)
+
+onBeforeUnmount(() => {
+  props.field && unregisterField?.(props.field)
+})
+</script>

package/src/components/form-item/helper.ts

@@ -0,0 +1,9 @@
+import { type FormFieldItem } from '@veltra/utils'
+
+import { bem, type MobileBEM } from '../../shared/bem'
+
+export const formItemCls: MobileBEM<'form-item'> = bem('form-item')
+
+export function defineField(field: FormFieldItem) {
+  return field
+}

package/src/components/form-item/index.ts

@@ -0,0 +1 @@
+export { default as UFormItem } from './form-item.vue'