@veltra/mobile 1.0.0 → 1.1.0

package/src/shared/use-scroll-lock.ts

@@ -0,0 +1,111 @@
+import { getCurrentScope, onScopeDispose } from 'vue'
+
+/**
+ * body / 任意容器滚动锁定（Dialog / Drawer / BottomSheet 等弹层共用）
+ *
+ * - body 用 `position: fixed` 定住页面（iOS Safari 下仅 `overflow: hidden`
+ *   阻不住橡皮筋滚动），其余容器（设备外壳视口等）用 `overflow: hidden`
+ *   并记录 `scrollTop`，解锁时还原滚动位置
+ * - 计数嵌套：多个弹层叠加（或对不同元素）各自 `lock()`/`unlock()`，
+ *   同一元素只有最外层解锁（计数归零）才还原样式与滚动位置
+ */
+
+/** body 锁定期间改写的内联样式属性，解锁时逐项还原为锁定前的值 */
+const BODY_PROPS = ['position', 'top', 'left', 'width', 'overflow'] as const
+
+interface ElementLock {
+  count: number
+  restore: () => void
+}
+
+/** 逐元素持有状态；不同元素互不影响（body 与自定义容器可同时被锁） */
+const locks = new WeakMap<HTMLElement, ElementLock>()
+
+function lockElement(el: HTMLElement): void {
+  const held = locks.get(el)
+  if (held) {
+    held.count++
+    return
+  }
+
+  if (el === document.body) {
+    const prev = BODY_PROPS.map((prop) => [prop, el.style.getPropertyValue(prop)] as const)
+    const scrollY = window.scrollY
+
+    el.style.position = 'fixed'
+    el.style.top = `-${scrollY}px`
+    el.style.left = '0'
+    el.style.width = '100%'
+    el.style.overflow = 'hidden'
+
+    locks.set(el, {
+      count: 1,
+      restore: () => {
+        for (const [prop, value] of prev) el.style.setProperty(prop, value)
+        window.scrollTo(0, scrollY)
+      }
+    })
+    return
+  }
+
+  const prevOverflow = el.style.overflow
+  const scrollTop = el.scrollTop
+  el.style.overflow = 'hidden'
+
+  locks.set(el, {
+    count: 1,
+    restore: () => {
+      el.style.overflow = prevOverflow
+      el.scrollTop = scrollTop
+    }
+  })
+}
+
+function unlockElement(el: HTMLElement): void {
+  const held = locks.get(el)
+  if (!held) return
+
+  held.count--
+  if (held.count === 0) {
+    locks.delete(el)
+    held.restore()
+  }
+}
+
+export interface ScrollLock {
+  /** 锁定目标元素滚动；可嵌套调用 */
+  lock: () => void
+  /** 解锁一层；未持有时为空操作 */
+  unlock: () => void
+}
+
+/**
+ * 按需解析锁定目标：元素可能在锁定的瞬间才注册/切换（设备外壳重挂载）。
+ * 内部工厂，供弹层宿主（overlay-container）按各自目标派生锁，不进公开导出。
+ */
+export function createScrollLock(resolve: () => HTMLElement): ScrollLock {
+  let target: HTMLElement | undefined
+
+  const lock = () => {
+    // 锁定期间目标变化（罕见）时先还原旧目标，避免永久锁死
+    if (target) unlockElement(target)
+    target = resolve()
+    lockElement(target)
+  }
+
+  const unlock = () => {
+    if (!target) return
+    unlockElement(target)
+    target = undefined
+  }
+
+  // 持锁期间组件被整体卸载（如外层 v-if 直接拔掉弹层）时兜底解锁
+  if (getCurrentScope()) onScopeDispose(unlock)
+
+  return { lock, unlock }
+}
+
+/** 锁定 body 滚动（公开 API），关闭后恢复原滚动位置 */
+export function useScrollLock(): ScrollLock {
+  return createScrollLock(() => document.body)
+}

package/src/shared/use-touch-gesture.ts

@@ -0,0 +1,150 @@
+/**
+ * 单指触摸手势基建（Drawer 四向边缘拖拽关闭、DatePicker 横滑翻月共用）
+ *
+ * - 只消费 `touch*` 事件，不依赖 pointer / hover
+ * - 判定逻辑不调用 `preventDefault`，监听是否 passive 均可工作；
+ *   需要阻断滚动链时由组件在模板上加 `.prevent` 修饰符
+ *
+ * 用法：返回的四个处理函数逐个绑到模板（或 `v-on` 整体展开），
+ * 位移跟随写在 `onMove`，释放判定用 `shouldCloseByDrag` / `horizontalSwipeDirection`
+ */
+
+export interface TouchGestureState {
+  /** 相对起点的横向位移（px，向右为正） */
+  dx: number
+  /** 相对起点的纵向位移（px，向下为正） */
+  dy: number
+  /** 起触至今的时长（ms） */
+  duration: number
+  /** 横向速度（px/ms，向右为正，按最近一段位移计算） */
+  vx: number
+  /** 纵向速度（px/ms，向下为正，按最近一段位移计算） */
+  vy: number
+}
+
+export interface UseTouchGestureOptions {
+  /** 触摸开始（位移为 0 的首帧） */
+  onStart?: (state: TouchGestureState) => void
+  /** 触摸移动（每帧更新，供拖拽跟随） */
+  onMove?: (state: TouchGestureState) => void
+  /** 松手，在这里做释放判定 */
+  onEnd?: (state: TouchGestureState) => void
+  /** 手势被打断（来电、系统手势、落到多指等）：拖拽中的组件应回弹而非关闭 */
+  onCancel?: (state: TouchGestureState) => void
+}
+
+/** 绑定到模板 `touch*` 事件的处理函数集，可直接 `v-on` 展开 */
+export interface TouchGestureHandlers {
+  touchstart: (event: TouchEvent) => void
+  touchmove: (event: TouchEvent) => void
+  touchend: (event: TouchEvent) => void
+  touchcancel: () => void
+}
+
+export function useTouchGesture(options: UseTouchGestureOptions = {}): TouchGestureHandlers {
+  let startX = 0
+  let startY = 0
+  let startT = 0
+  let lastX = 0
+  let lastY = 0
+  let lastT = 0
+  let lastVX = 0
+  let lastVY = 0
+  let tracking = false
+
+  function stateAt(x: number, y: number, t: number): TouchGestureState {
+    const dt = t - lastT
+    // 速度按最近一段位移计算，长距离慢拖后再甩动时不被整体平均稀释
+    if (dt > 0) {
+      lastVX = (x - lastX) / dt
+      lastVY = (y - lastY) / dt
+    }
+
+    return { dx: x - startX, dy: y - startY, duration: t - startT, vx: lastVX, vy: lastVY }
+  }
+
+  function cancelTracking() {
+    if (!tracking) return
+    tracking = false
+    options.onCancel?.(stateAt(lastX, lastY, lastT))
+  }
+
+  return {
+    touchstart(e) {
+      // 只跟踪单指；第二指落下视为手势被打断
+      if (tracking || e.touches.length !== 1) {
+        cancelTracking()
+        return
+      }
+
+      const touch = e.touches[0]!
+      tracking = true
+      startX = lastX = touch.clientX
+      startY = lastY = touch.clientY
+      lastT = startT = e.timeStamp
+      lastVX = lastVY = 0
+      options.onStart?.({ dx: 0, dy: 0, duration: 0, vx: 0, vy: 0 })
+    },
+
+    touchmove(e) {
+      if (!tracking) return
+      if (e.touches.length !== 1) {
+        cancelTracking()
+        return
+      }
+
+      const touch = e.touches[0]!
+      options.onMove?.(stateAt(touch.clientX, touch.clientY, e.timeStamp))
+      lastX = touch.clientX
+      lastY = touch.clientY
+      lastT = e.timeStamp
+    },
+
+    touchend(e) {
+      if (!tracking) return
+      tracking = false
+      const touch = e.changedTouches[0]
+      options.onEnd?.(stateAt(touch?.clientX ?? lastX, touch?.clientY ?? lastY, e.timeStamp))
+    },
+
+    touchcancel: cancelTracking
+  }
+}
+
+export interface DragDismissOptions {
+  /** 拖拽轴：Drawer 的 bottom / top 形态用 y，left / right 形态用 x */
+  axis: 'x' | 'y'
+  /**
+   * 关闭方向：1 沿正方向（右 / 下）拖动关闭，-1 沿负方向（左 / 上）。
+   * Drawer 对应关系：bottom 向下拉 1、top 向上推 -1、left 向左拖 -1、right 向右拖 1
+   */
+  sign: 1 | -1
+  /** 判定为关闭的最小位移（px），默认 100 */
+  distance?: number
+  /** 判定为关闭的最小甩动速度（px/ms），默认 0.3 */
+  velocity?: number
+}
+
+/**
+ * 拖拽释放判定：沿关闭方向的位移或甩动速度任一达标即应关闭；
+ * 反方向（离开关闭方向）拖动永远不关闭
+ */
+export function shouldCloseByDrag(state: TouchGestureState, options: DragDismissOptions): boolean {
+  const { axis, sign, distance = 100, velocity = 0.3 } = options
+  const delta = sign * (axis === 'x' ? state.dx : state.dy)
+
+  if (delta <= 0) return false
+
+  const speed = sign * (axis === 'x' ? state.vx : state.vy)
+  return delta >= distance || speed >= velocity
+}
+
+/** 横向滑动方向判定：位移达阈值且横向分量大于纵向时返回方向，否则 null（点按或纵向滚动） */
+export function horizontalSwipeDirection(
+  state: TouchGestureState,
+  distance = 50
+): 'left' | 'right' | null {
+  const { dx, dy } = state
+  if (Math.abs(dx) < distance || Math.abs(dx) <= Math.abs(dy)) return null
+  return dx > 0 ? 'right' : 'left'
+}

package/src/styles/_tokens.scss

@@ -0,0 +1,129 @@
+/**
+ * 移动端密度 token 层（`--um-*` 前缀，纯 SCSS，不经运行时注入）
+ *
+ * - 值表是编译期回退值的单一来源：组件样式一律经 `use-var()` 取密度值，
+ *   产出 `var(--um-<name>, 回退值)`，宿主可在任意层级用 `--um-*` 覆盖
+ * - 配色、圆角、阴影等观感 token 仍走 `@veltra/styles` 的 `--u-*` 预设体系
+ * - 本模块只提供值与函数，不产出任何 CSS；组件 SCSS 以
+ *   `@use '../../styles/tokens' as t;` 引用（下划线 partial，禁止单独编译）
+ */
+@use 'sass:map';
+
+$namespace: 'um' !default;
+
+// 密度值表：键为去掉 `--um-` 前缀的 token 名
+$values: (
+  // 字号：正文主字号 16px（正文与输入类字号不小于 16px），辅助信息 14 / 12px
+  'font-size-main': 16px,
+  'font-size-secondary': 14px,
+  'font-size-auxiliary': 12px,
+  // 面板标题档：底部弹层头部主标题、滚轮等大号主内容
+  'font-size-title': 18px,
+  // 列表行式表单的行高（约 48px）
+  'form-row-height': 48px,
+  // 表单 / 按钮等控件高度档（small / default / large）
+  'control-height-small': 32px,
+  'control-height-default': 40px,
+  'control-height-large': 48px,
+  // 输入类控件圆角档（small / default / large）
+  'control-radius-small': 4px,
+  'control-radius-default': 6px,
+  'control-radius-large': 8px,
+  // 弹层与浮层容器圆角（dialog / drawer / bottom-sheet / message 等面板级圆角）
+  'panel-radius': 12px,
+  // 输入类正文行高
+  'text-line-height': 1.5,
+  // 头像等组件尺寸档：整体上移的移动端密度，最小档 ≥32px
+  'avatar-size-small': 32px,
+  'avatar-size-default': 40px,
+  'avatar-size-large': 48px,
+  // 展示组件密度基准：加载指示器边长（ring / dual-ring 直径，dot / bars 推导基准）、
+  // 环形进度兜底直径（progress 的 size 未传时生效）
+  'loading-indicator': 36px,
+  'progress-circle': 100px,
+  // 开关轨道高度档（宽度为高度两倍，手柄随轨道推导）
+  'switch-track-small': 24px,
+  'switch-track-default': 28px,
+  'switch-track-large': 32px,
+  // 上传组件瓦片尺寸档（375 视口默认档约三列 + 间距）
+  'uploader-size-small': 64px,
+  'uploader-size-default': 80px,
+  'uploader-size-large': 96px,
+  // 间距刻度（4px 基）
+  'spacing-xs': 4px,
+  'spacing-sm': 8px,
+  'spacing-md': 12px,
+  'spacing-lg': 16px,
+  'spacing-xl': 24px,
+  // 触控热区下限
+  'touch-target': 44px
+);
+
+// 引用移动端密度 token：`var(--um-<name>, 编译期回退值)`
+@function use-var($name) {
+  @if not map.has-key($values, $name) {
+    @error '未知的移动端 token：--#{$namespace}-#{$name}';
+  }
+
+  @return var(--#{$namespace}-#{$name}, #{map.get($values, $name)});
+}
+
+// 按组件尺寸取控件高度：small / default / large → --um-control-height-*
+@function control-height($size) {
+  @return use-var(map.get(
+    (
+      small: 'control-height-small',
+      default: 'control-height-default',
+      large: 'control-height-large'
+    ),
+    $size
+  ));
+}
+
+// 按组件尺寸取输入类控件圆角：small / default / large → --um-control-radius-*
+@function control-radius($size) {
+  @return use-var(map.get(
+    (
+      small: 'control-radius-small',
+      default: 'control-radius-default',
+      large: 'control-radius-large'
+    ),
+    $size
+  ));
+}
+
+// 按组件尺寸取间距：small / default / large → --um-spacing-sm / md / lg
+@function spacing($size) {
+  @return use-var(map.get(
+    (
+      small: 'spacing-sm',
+      default: 'spacing-md',
+      large: 'spacing-lg'
+    ),
+    $size
+  ));
+}
+
+// 按组件尺寸取开关轨道高度：small / default / large → --um-switch-track-*
+@function switch-track($size) {
+  @return use-var(map.get(
+    (
+      small: 'switch-track-small',
+      default: 'switch-track-default',
+      large: 'switch-track-large'
+    ),
+    $size
+  ));
+}
+
+// 按组件尺寸取上传瓦片尺寸：small / default / large → --um-uploader-size-*
+@function uploader-size($size) {
+  @return use-var(map.get(
+    (
+      small: 'uploader-size-small',
+      default: 'uploader-size-default',
+      large: 'uploader-size-large'
+    ),
+    $size
+  ));
+}

package/src/types/avatar.ts

@@ -0,0 +1,31 @@
+import type { ComponentProps, DeconstructValue } from '@veltra/utils'
+
+/** 头像形状：circle 圆形 / round 圆角方形 */
+export type AvatarShape = 'circle' | 'round'
+
+/** 头像组件属性 */
+export interface AvatarProps extends ComponentProps {
+  /**
+   * 尺寸档位（继承自 ComponentProps）：small / default / large，
+   * 宽高取移动端密度 token `--um-avatar-size-*`（32 / 40 / 48px），默认 default
+   */
+  size?: ComponentProps['size']
+
+  /** 图片地址；未传或加载失败时回退展示默认插槽内容 */
+  src?: string
+  /** 图片描述，作为 img 的 alt */
+  alt?: string
+  /** 形状，默认 circle */
+  shape?: AvatarShape
+}
+
+/** 头像组件定义的事件 */
+export interface AvatarEmits {
+  (e: 'error', ev: Event): void
+}
+
+/** 头像组件暴露的属性和方法(组件内部使用) */
+export interface _AvatarExposed {}
+
+/** 头像组件暴露的属性和方法(组件外部使用, 引用的值会被自动解构) */
+export type AvatarExposed = DeconstructValue<_AvatarExposed>

package/src/types/badge.ts

@@ -0,0 +1,28 @@
+import type { ColorType, ComponentProps, DeconstructValue } from '@veltra/utils'
+
+/** 徽章组件属性 */
+export interface BadgeProps extends ComponentProps {
+  /** 显示值 */
+  value?: number | string
+  /** 类别 */
+  type?: ColorType
+  /** 自定义背景色 */
+  color?: string
+  /** 是否隐藏 Badge */
+  hidden?: boolean
+  /** 最大值 {{max}}+ */
+  max?: number
+  /** 是否显示小圆点 */
+  dot?: boolean
+}
+
+/** 徽章组件定义的事件 */
+export interface BadgeEmits {
+  (e: 'update:modelValue', value: string): void
+}
+
+/** 徽章组件暴露的属性和方法(组件内部使用) */
+export interface _BadgeExposed {}
+
+/** 徽章组件暴露的属性和方法(组件外部使用, 引用的值会被自动解构) */
+export type BadgeExposed = DeconstructValue<_BadgeExposed>

package/src/types/button.ts

@@ -0,0 +1,48 @@
+import type { ColorType, ComponentProps, DeconstructValue } from '@veltra/utils'
+import type { Component, ShallowRef } from 'vue'
+
+/** 按钮类型 */
+export type ButtonType = ColorType
+
+/**
+ * 按钮属性类型
+ * @description 组件不注入默认 `aria-label`：可访问名来自默认插槽文本，
+ * 或你自己传入的 `aria-label`（透传到根元素）；只有图标的按钮必须自行传 `aria-label`
+ */
+export interface ButtonProps extends ComponentProps {
+  /** 按钮类型 */
+  type?: ButtonType
+  /** 是否以文本形式展示 */
+  text?: boolean
+  /** 朴素模式 */
+  plain?: boolean
+  /** 加载中 */
+  loading?: boolean
+  /** 加载图标 */
+  loadingIcon?: Component
+  /** 圆形 */
+  circle?: boolean
+  /** 禁用 */
+  disabled?: boolean
+  /** 图标 */
+  icon?: Component
+  /** 图标大小, 单位px */
+  iconSize?: number
+  /** 图标位置 */
+  iconPosition?: 'left' | 'right'
+  /** 事件是否传播（冒泡或者捕获） */
+  propagate?: boolean
+}
+
+export interface ButtonEmits {
+  /** 点击事件 */
+  (name: 'click', e: MouseEvent): void
+}
+
+/** 在组件内部引用 */
+export interface _ButtonExposed {
+  el: ShallowRef<HTMLButtonElement | undefined>
+}
+
+/** 按钮暴露的属性和方法 */
+export type ButtonExposed = DeconstructValue<_ButtonExposed>

package/src/types/card.ts

@@ -0,0 +1,16 @@
+import type { ComponentProps, DeconstructValue } from '@veltra/utils'
+
+/** 卡片组件属性 */
+export interface CardProps extends ComponentProps {
+  /** 宽度 */
+  width?: string | number
+
+  /** 融合样式，卡片不再有阴影 */
+  integrate?: boolean
+}
+
+export interface CardEmits {}
+
+export interface _CardExposed {}
+
+export type CardExposed = DeconstructValue<_CardExposed>

package/src/types/cascade.ts

@@ -0,0 +1,87 @@
+import type { TreeNode } from '@cat-kit/core'
+import type { DeconstructValue, FormComponentProps } from '@veltra/utils'
+import type { CSSProperties } from 'vue'
+
+export interface CascadeNode<
+  Data extends Record<string, any> = Record<string, any>
+> extends TreeNode<Data, CascadeNode<Data>> {
+  visible: boolean
+  value: string
+  label: string
+}
+
+/** 级联选择器组件属性（移动端形态：面包屑 Tab + 底部面板） */
+export interface CascadeProps extends FormComponentProps {
+  /**
+   * 分隔符
+   * @default '/'
+   */
+  separator?: string
+  /** 数据值 */
+  modelValue?: string[] | string
+  /** 级联数据项的标签字段 */
+  labelKey?: string
+  /**
+   * 兜底展示文案
+   * @description 单选 modelValue 未命中数据时展示 text（如回显路径已不在选项中），命中时展示节点 label 路径
+   */
+  text?: string
+  /** 级联数据项的值字段 */
+  valueKey?: string
+  /** 占位符 */
+  placeholder?: string
+  /** 是否可清除 */
+  clearable?: boolean
+  /** 子级字段 */
+  childrenKey?: string
+  /** 严格模式：仅叶子节点提交，非叶子点击只展开下级 */
+  strict?: boolean
+  /**
+   * 是否展示/提交完整路径
+   * @default true
+   * false 时显示、modelValue、update:label 均只体现选中叶子节点
+   */
+  showFullPath?: boolean
+  /**
+   * 数据项
+   */
+  data?: Record<string, any>[]
+  /**
+   * 多选
+   */
+  multiple?: boolean
+  /**
+   * 搜索
+   */
+  filterable?: boolean
+  /** 触发器上最多展示的标签数，超出折叠为 +N */
+  visibilityLimit?: number
+  /** 底部面板内容容器样式 */
+  contentStyle?: CSSProperties | string
+  /** 底部面板内容容器类名 */
+  contentClass?: unknown
+}
+
+/** 级联选择器组件定义的事件 */
+export interface CascadeEmits {
+  /** 触发更新 label 事件 */
+  (e: 'update:label', label?: string | string[]): void
+  (e: 'update:modelValue', value?: string | string[]): void
+  (
+    e: 'change',
+    items: (Record<string, any> & { fullLabel?: string })[],
+    fullLabels?: string[]
+  ): void
+  (
+    e: 'change',
+    item: (Record<string, any> & { fullLabel?: string }) | undefined,
+    fullLabel?: string
+  ): void
+  (e: 'clear'): void
+}
+
+/** 级联选择器组件暴露的属性和方法(组件内部使用) */
+export interface _CascadeExposed {}
+
+/** 级联选择器组件暴露的属性和方法(组件外部使用, 引用的值会被自动解构) */
+export type CascadeExposed = DeconstructValue<_CascadeExposed>

package/src/types/check-tag.ts

@@ -0,0 +1,24 @@
+import type { DeconstructValue } from '@veltra/utils'
+
+/** check-tag组件属性 */
+export interface CheckTagProps {
+  modelValue?: boolean
+
+  checked?: boolean
+
+  /** 是否禁用；禁用后点击不切换选中态、不触发任何事件 */
+  disabled?: boolean
+}
+
+/** check-tag组件定义的事件 */
+export interface CheckTagEmits {
+  (e: 'update:modelValue', value: boolean): void
+
+  (e: 'change', value: boolean): void
+}
+
+/** check-tag组件暴露的属性和方法(组件内部使用) */
+export interface _CheckTagExposed {}
+
+/** check-tag组件暴露的属性和方法(组件外部使用, 引用的值会被自动解构) */
+export type CheckTagExposed = DeconstructValue<_CheckTagExposed>

package/src/types/checkbox-group.ts

@@ -0,0 +1,20 @@
+import type { FormComponentProps } from '@veltra/utils'
+
+/** 复选框组组件属性（移动端列表行式：选项纵向排列占满整行，v-model 为选中值数组） */
+export interface CheckboxGroupProps extends FormComponentProps {
+  /** 值 */
+  modelValue?: Array<any>
+  /** 复选框项 */
+  items: Array<Record<string, any>>
+  /** 标签文本的key */
+  labelKey?: string
+  /** 值的key */
+  valueKey?: string
+  /** 选项行间细分隔线。默认 false */
+  divider?: boolean
+}
+
+/** 复选框组组件定义的事件 */
+export interface CheckboxGroupEmits {
+  (e: 'update:modelValue', value: Array<any>): void
+}

package/src/types/checkbox.ts

@@ -0,0 +1,15 @@
+import type { FormComponentProps } from '@veltra/utils'
+
+/** 复选框组件属性（与 @veltra/desktop UCheckbox 同名；呈移动端列表行式选项形态） */
+export interface CheckboxProps extends FormComponentProps {
+  /** 部分选中 */
+  indeterminate?: boolean
+  /** 是否选中  */
+  modelValue?: boolean
+}
+
+/** 复选框组件定义的事件 */
+export interface CheckboxEmits {
+  (name: 'update:modelValue', checked: boolean): void
+  (name: 'change', checked: boolean, e: MouseEvent): void
+}