@veltra/compositions 1.0.0

package/src/use-fallback-props/index.ts

@@ -0,0 +1,76 @@
+import type { ComponentSize } from '@veltra/utils/types'
+import { computed, type ComputedRef } from 'vue'
+
+import { useConfig } from '../use-config'
+
+/**
+ * 使用回滚属性，用于控制多级属性的使用优先级，如果多级属性中不存在该值，则使用全局配置中的属性，如再不存在则为undefined
+ * @param propsList 属性列表，最右边的属性优先级最高
+ * @param fallbackProps 要回滚的属性和默认值
+ */
+export function useFallbackProps<
+  F extends Record<string, any>,
+  R extends {
+    [key in keyof F]: ComputedRef<F[key]>
+  }
+>(propsList: Record<string, any>[], fallbackProps: F): R {
+  const { config } = useConfig()
+
+  let result = {} as R
+
+  for (const key in fallbackProps) {
+    if (fallbackProps.hasOwnProperty(key)) {
+      const defaultValue = fallbackProps[key]
+      const ref = computed<any>(() => {
+        for (let i = propsList.length - 1; i > -1; --i) {
+          const props = propsList[i]!
+
+          if (props[key] !== undefined) {
+            return props[key]
+          }
+        }
+
+        return config[key as string] ?? defaultValue
+      })
+
+      result[key as keyof F] = ref as R[keyof F]
+    }
+  }
+
+  return result
+}
+
+type FormFallbackProps = { size: ComponentSize; disabled: boolean; readonly: boolean }
+
+/**
+ * 表单组件的回滚属性
+ * @param propsList props列表
+ * @returns
+ */
+export function useFormFallbackProps(propsList: Record<string, any>[]): {
+  [key in keyof FormFallbackProps]: ComputedRef<FormFallbackProps[key]>
+}
+
+/**
+ * 表单组件的回滚属性
+ * @param propsList props列表
+ * @param fallbackProps 回滚属性，可以只指定部分表单属性
+ * @returns
+ */
+export function useFormFallbackProps<F extends Partial<FormFallbackProps>>(
+  propsList: Record<string, any>[],
+  fallbackProps: F
+): {
+  [key in keyof F]: key extends keyof FormFallbackProps
+    ? ComputedRef<FormFallbackProps[key]>
+    : never
+}
+export function useFormFallbackProps(
+  propsList: Record<string, any>[],
+  fallbackProps?: Record<string, any>
+): any {
+  if (!fallbackProps) {
+    fallbackProps = { size: 'default', disabled: false, readonly: false }
+  }
+  return useFallbackProps(propsList, fallbackProps)
+}

package/src/use-focus/index.ts

@@ -0,0 +1,26 @@
+import { ref, type Ref } from 'vue'
+
+/**
+ * 聚焦
+ * @param cb 回调
+ * @returns
+ */
+export function useFocus(cb?: (focused: boolean) => void): {
+  focus: Ref<boolean>
+  handleBlur: () => void
+  handleFocus: () => void
+} {
+  const focus = ref(false)
+
+  const handleFocus = () => {
+    focus.value = true
+    cb?.(focus.value)
+  }
+
+  const handleBlur = () => {
+    focus.value = false
+    cb?.(focus.value)
+  }
+
+  return { focus, handleBlur, handleFocus }
+}

package/src/use-form-component/index.ts

@@ -0,0 +1,31 @@
+import type { FormContextInjectProps } from '@veltra/utils/types'
+import { type InjectionKey, inject, provide } from 'vue'
+
+type DIContext = {
+  /** 表单属性 */
+  formProps: FormContextInjectProps
+}
+
+const FormComponentDIKey: InjectionKey<DIContext> = Symbol('FormComponentDIKey')
+
+/**
+ * 表单组件本身的组合式方法
+ * @param props 表单属性
+ * @returns
+ */
+export function useFormComponent(props: FormContextInjectProps): void
+/**
+ * 表单内的组件的组合式方法
+ * @returns 提供一个form的上下文
+ */
+export function useFormComponent(): {
+  /** 是否在表单中 */
+  inForm: boolean
+} & Partial<DIContext>
+export function useFormComponent(props?: any): any {
+  if (props) {
+    return provide(FormComponentDIKey, { formProps: props })
+  }
+  const context = inject(FormComponentDIKey, undefined) || {}
+  return { inForm: !!context, ...context }
+}

package/src/use-lock/index.ts

@@ -0,0 +1,50 @@
+import { nextTick } from 'vue'
+
+type Update = (fn: Function) => any
+type Lock = (fn: Function) => Promise<void>
+
+export interface Updater {
+  /**
+   * 更新
+   * @description 在非锁定时执行传入的函数
+   */
+  update: Update
+  /**
+   * 更新并锁定
+   * @description 执行传入的函数，并锁定更新操作，直到函数执行完成
+   */
+  updateAndLock: Lock
+}
+
+/**
+ * 数据更新锁
+ * @description
+ * 更新锁主要用于防止组件数据更新时，循环触发更新。
+ *
+ * @returns 该函数返回两个函数：
+ * 1. update: 更新函数，在非锁定时执行传入的函数
+ * 2. lock: 锁定函数，执行时会锁定更新操作，直到锁定操作结束
+ */
+export function useUpdateLock(): Updater {
+  let lockedCount = 0
+
+  function update(fn: Function) {
+    if (lockedCount > 0) return
+    return fn()
+  }
+
+  async function updateAndLock(fn: Function) {
+    lockedCount++
+
+    try {
+      await fn()
+    } catch (error) {
+      console.error(error)
+    }
+    await nextTick()
+
+    lockedCount--
+  }
+
+  return { updateAndLock, update }
+}

package/src/use-model/index.ts

@@ -0,0 +1,96 @@
+import { type Ref, ref, watch, shallowRef } from 'vue'
+
+interface ModelOptions<Props extends Record<string, unknown>, Name extends keyof Props> {
+  /** 组件定义的属性 */
+  props: Props
+  /** 属性名称 */
+  propName?: Name
+  /** 事件触发函数 */
+  emit: (...args: any[]) => void
+  /** 是否为本地模式, 默认为true, 本地模式允许组件不受控来触发视图更新 */
+  local?: boolean | (() => boolean)
+  /** 默认值 */
+  defaultValue?: Props[Name]
+  /**
+   * 是否浅层响应
+   * @default false
+   */
+  shallow?: boolean
+}
+
+/**
+ * 返回一个基于提供的选项的响应式模型值。
+ * 该方法在将来可能会被替代, 目前使用是为了类型提示可用
+ * 如果 local 选项为true, 模型值将是响应式的，并与属性值同步。
+ * 如果 local 选项为 false，则模型值将是一个代理对象，具有 getter 和 setter。当值发生更改时，它会触发一个更新事件。
+ * @param options - 选项
+ * @returns - 一个模型值
+ */
+
+export function useModel<
+  Props extends Record<string, any>,
+  Name extends keyof Props = 'modelValue'
+>(
+  options: ModelOptions<Props, Name>
+): Ref<Props[Name] | undefined> | { __v_isRef: boolean; value: Props[Name] } {
+  const {
+    props,
+    propName = 'modelValue',
+    emit,
+    local = true,
+    defaultValue,
+    shallow = false
+  } = options
+
+  if (local) {
+    const _default = props[propName] ?? defaultValue
+    const r = shallow ? shallowRef : ref
+
+    // 创建一个响应式对象
+    const _value = r(_default)
+
+    // 监听属性的变更
+    watch(
+      () => props[propName],
+      (v) => {
+        _value.value = v
+      }
+    )
+
+    const getLocal = () => {
+      return typeof local === 'function' ? local() : local
+    }
+
+    const value = {
+      __v_isRef: true,
+      get value() {
+        return _value.value
+      },
+      set value(v) {
+        if (v !== _value.value) {
+          emit(`update:${propName as string}`, v)
+        }
+        if (getLocal()) {
+          _value.value = v
+        }
+      }
+    }
+
+    return value
+  }
+
+  // 创建一个拥有getter和setter的对象
+  const value = {
+    __v_isRef: true,
+
+    get value(): Props[Name] {
+      return (props[propName] ?? defaultValue) as Props[Name]
+    },
+
+    set value(v: Props[Name]) {
+      emit(`update:${propName as string}`, v)
+    }
+  }
+
+  return value
+}

package/src/use-pop/index.ts

@@ -0,0 +1,206 @@
+import {
+  computePosition,
+  flip,
+  shift,
+  arrow,
+  offset,
+  type ComputePositionReturn,
+  type Placement
+} from '@floating-ui/dom'
+import { getScrollParents, setStyles } from '@veltra/utils'
+import { isRef, onBeforeUnmount, watch, type Ref, type ShallowRef } from 'vue'
+
+type TipDirection = 'top' | 'bottom' | 'left' | 'right'
+type TipAlign = 'center' | 'start' | 'end'
+
+interface Options {
+  /** 触发元素 */
+  triggerRef: ShallowRef<HTMLElement | undefined>
+  /** 内容元素 */
+  contentRef: ShallowRef<HTMLElement | undefined>
+  /**
+   * 箭头元素，如果存在，则会在弹框的箭头位置显示箭头
+   */
+  arrowRef?: ShallowRef<HTMLElement | undefined>
+  /** 方向 */
+  direction?: ShallowRef<TipDirection> | TipDirection
+  /** 对齐方式 */
+  alignment?: ShallowRef<TipAlign> | TipAlign
+  /**
+   * 箭头大小
+   * @default 10
+   */
+  arrowSize?: number
+  /**
+   * 触发器元素位置变更时回调，
+   * 一般用于在触发器元素位置变更时更新弹框位置
+   */
+  onTriggerPositionChange?: () => void
+  /** 更新元素前回调 */
+  onBeforeUpdate?: (triggerEl: HTMLElement, contentEl: HTMLElement) => void
+  /** 更新元素后回调 */
+  onAfterUpdate?: (position: ComputePositionReturn) => void
+  /** 弹框弹出时回调 */
+  onPop?: (position: ComputePositionReturn) => void
+}
+
+interface PopResult {
+  /**
+   * 更新弹框位置
+   */
+  update: () => Promise<void>
+  /** 浮框容器id */
+  popperContainerId: string
+}
+
+let popperContainer: HTMLElement | null = null
+
+const popperContainerId = 'pop-container'
+
+/**
+ * 浮框组合式函数
+ * @param options 选项
+ * @returns
+ */
+export function usePop(options: Options): PopResult {
+  if (!popperContainer) {
+    popperContainer = document.createElement('div')
+    popperContainer.id = popperContainerId
+    document.body.appendChild(popperContainer)
+  }
+
+  const {
+    triggerRef,
+    contentRef,
+    arrowRef,
+    arrowSize = 10,
+    onTriggerPositionChange,
+    onAfterUpdate,
+    onBeforeUpdate,
+    direction,
+    alignment,
+    onPop
+  } = options
+
+  /** 箭头位置 */
+  const arrowPlacementDict = { top: 'bottom', right: 'left', bottom: 'top', left: 'right' }
+
+  function getMaybeRefValue<T>(value?: Ref<T> | T) {
+    return isRef(value) ? value.value : value
+  }
+
+  /**
+   * 更新浮框位置
+   * @param callbackOnPop 是否在弹出时回调
+   */
+  async function update(callbackOnPop = false) {
+    const triggerEl = triggerRef.value
+    const contentEl = contentRef.value
+
+    if (!(triggerEl instanceof HTMLElement) || !(contentEl instanceof HTMLElement)) {
+      return
+    }
+
+    onBeforeUpdate?.(triggerEl, contentEl)
+
+    // 计算位置 ↓↓↓
+    const middleware = [offset(arrowRef?.value ? arrowSize : 6), flip(), shift()]
+
+    if (arrowRef?.value) {
+      middleware.push(arrow({ element: arrowRef.value }))
+    }
+
+    const _direction = getMaybeRefValue(direction) ?? 'top'
+    const _alignment = getMaybeRefValue(alignment) ?? 'center'
+
+    const position = await computePosition(triggerEl, contentEl, {
+      middleware,
+
+      placement: `${_direction}${_alignment === 'center' ? '' : `-${_alignment}`}` as Placement
+    })
+
+    const { x, y, middlewareData, placement } = position
+
+    setStyles(contentEl, { left: `${x}px`, top: `${y}px` })
+    callbackOnPop && onPop?.(position)
+    onAfterUpdate?.(position)
+
+    // 设置箭头位置 ↓↓↓
+    if (middlewareData.arrow) {
+      const { x: arrowX, y: arrowY } = middlewareData.arrow
+
+      const arrowPlacement =
+        arrowPlacementDict[placement.split('-')[0]! as keyof typeof arrowPlacementDict]
+      const size = `${arrowSize}px`
+      // 箭头半径
+      const arrowRadius = arrowSize / 2
+
+      setStyles(arrowRef!.value!, {
+        width: size,
+        height: size,
+        left: arrowX && `${arrowX - arrowRadius}px`,
+        top: arrowY && `${arrowY - arrowRadius}px`,
+        [arrowPlacement]: `-${arrowRadius}px`
+      })
+    }
+    // 设置箭头位置 ↑↑↑
+  }
+
+  let scrollParents: HTMLElement[] = []
+
+  /** 为触发器元素的祖先元素添加滚动事件 */
+  function addScrollEvents() {
+    if (!triggerRef.value) return
+    if (onTriggerPositionChange) {
+      scrollParents = getScrollParents(triggerRef.value)
+      scrollParents.forEach((el) => {
+        el.addEventListener('scroll', onTriggerPositionChange)
+      })
+    }
+  }
+
+  /** 移除触发器元素祖先元素的滚动事件 */
+  function removeScrollEvents() {
+    if (onTriggerPositionChange) {
+      scrollParents.forEach((el) => {
+        el.removeEventListener('scroll', onTriggerPositionChange)
+      })
+    }
+
+    scrollParents = []
+  }
+
+  function addResizeEvents() {
+    onTriggerPositionChange && window.addEventListener('resize', onTriggerPositionChange)
+  }
+
+  function removeResizeEvents() {
+    onTriggerPositionChange && window.removeEventListener('resize', onTriggerPositionChange)
+  }
+
+  watch(
+    [contentRef, () => getMaybeRefValue(direction), () => getMaybeRefValue(alignment)],
+    ([content]) => {
+      if (content) {
+        update(true)
+        addScrollEvents()
+        addResizeEvents()
+        return
+      }
+      removeScrollEvents()
+      removeResizeEvents()
+    }
+  )
+
+  onBeforeUnmount(() => {
+    removeScrollEvents()
+    removeResizeEvents()
+  })
+
+  return {
+    /** 更新浮框位置 */
+    update,
+    /** 浮框容器id */
+    popperContainerId
+  }
+}

package/src/use-reactive-size/index.ts

@@ -0,0 +1,53 @@
+import { computed, reactive } from 'vue'
+
+import { useResizeObserver, type RefElement } from '../use-resize-observer'
+
+interface ElementSize {
+  width: number
+  height: number
+}
+
+/**
+ * 响应式尺寸
+ * @param targets 目标元素
+ * @returns 目标元素的宽高
+ */
+export function useReactiveSize(target: RefElement): ElementSize
+export function useReactiveSize(targets: RefElement[]): ElementSize[]
+export function useReactiveSize(targets: RefElement | RefElement[]): ElementSize | ElementSize[] {
+  const sizes = Array.isArray(targets)
+    ? targets.map(() => {
+        return reactive({ width: 0, height: 0 })
+      })
+    : reactive({ width: 0, height: 0 })
+
+  const sizesMap = Array.isArray(targets)
+    ? computed(() => {
+        const entries = targets
+          .map((target, index) => {
+            return [target.value!, (sizes as ElementSize[])[index]!]
+          })
+          .filter(([target]) => target) as [HTMLElement, ElementSize][]
+
+        return new WeakMap(entries)
+      })
+    : computed(() => {
+        return new WeakMap(targets.value ? [[targets.value, sizes as ElementSize]] : [])
+      })
+
+  useResizeObserver({
+    targets,
+    onResize(entries) {
+      entries.forEach((entry) => {
+        const borderBoxSize = entry.borderBoxSize[0]!
+        const size = sizesMap.value.get(entry.target as HTMLElement)
+        if (size && borderBoxSize) {
+          size.width = borderBoxSize.inlineSize
+          size.height = borderBoxSize.blockSize
+        }
+      })
+    }
+  })
+
+  return sizes
+}

package/src/use-resize-observer/index.ts

@@ -0,0 +1,148 @@
+import { type Ref, type ShallowRef, onBeforeUnmount, watch } from 'vue'
+
+export type RefElement =
+  | ShallowRef<HTMLElement | undefined | null>
+  | Ref<HTMLElement | undefined | null>
+
+interface ResizeObserverOptions {
+  /** 目标节点 */
+  targets: RefElement | RefElement[]
+  /** resize事件 */
+  onResize: ResizeObserverCallback
+  /** 指定观察条件 */
+  when?: () => boolean
+}
+
+/** 监听器 */
+export type ResizeObserverReturn = {
+  /** 终止监听 */
+  disconnect: () => void
+}
+
+/**
+ * 取消监听
+ * @param targets 目标节点
+ * @param observer 观察器
+ */
+function unobserve(targets: RefElement | RefElement[], observer?: ResizeObserver) {
+  if (Array.isArray(targets)) {
+    return targets.forEach((target) => unobserve(target, observer))
+  }
+  if (!targets.value || !observer) return
+  observer.unobserve(targets.value)
+  observer.disconnect()
+}
+
+/**
+ * 监听目标尺寸变化
+ * @param options 选项
+ */
+export function useResizeObserver(options: ResizeObserverOptions): ResizeObserverReturn {
+  const { targets, onResize } = options
+
+  let observer: ResizeObserver | undefined
+
+  if (Array.isArray(targets)) {
+    watch(
+      targets,
+      (val, oldVal) => {
+        // 清除旧的观察
+        oldVal.forEach((target) => {
+          target && observer?.unobserve(target)
+        })
+
+        if (!observer && !!val.length) {
+          observer = new ResizeObserver(onResize)
+        }
+
+        val.forEach((target) => {
+          target && observer?.observe(target)
+        })
+      },
+      { immediate: true }
+    )
+  } else {
+    watch(
+      targets,
+      (val, oldVal) => {
+        oldVal && observer?.unobserve(oldVal)
+        if (!observer && val) {
+          observer = new ResizeObserver(onResize)
+        }
+        val && observer?.observe(val)
+      },
+      { immediate: true }
+    )
+  }
+
+  onBeforeUnmount(() => {
+    unobserve(targets, observer)
+    observer = undefined
+  })
+
+  return {
+    disconnect() {
+      unobserve(targets, observer)
+      observer = undefined
+    }
+  }
+}
+
+/**
+ * 监听元素尺寸变化
+ */
+export function useObserverCallback(): {
+  observeEl: <El extends HTMLElement>(
+    el: El,
+    cb: (entry: Omit<ResizeObserverEntry, 'target'> & { target: El }) => void
+  ) => void
+  unobserveEl: (el: HTMLElement) => void
+} {
+  const observerElMap = new Map<HTMLElement, Function>()
+
+  const observer = new ResizeObserver((entries) => {
+    entries.forEach((entry) => {
+      const target = entry.target as HTMLElement
+      if (!target.dataset.ob) {
+        target.dataset.ob = 'true'
+        return
+      }
+      const fn = observerElMap.get(target)
+
+      fn?.(entry)
+    })
+  })
+
+  /**
+   * 监听元素尺寸
+   * @param el 元素
+   * @param cb 回调
+   */
+  function observeEl<El extends HTMLElement>(
+    el: El,
+    cb: (entry: Omit<ResizeObserverEntry, 'target'> & { target: El }) => void
+  ) {
+    observer.observe(el)
+    observerElMap.set(el, cb)
+  }
+
+  /**
+   * 取消监听元素尺寸
+   * @param el 元素
+   */
+  function unobserveEl(el: HTMLElement) {
+    observer.unobserve(el)
+    delete el.dataset.ob
+    observerElMap.delete(el)
+  }
+
+  onBeforeUnmount(() => {
+    observerElMap.forEach((_, el) => {
+      observer.unobserve(el)
+    })
+    observerElMap.clear()
+    observer.disconnect()
+  })
+
+  return { observeEl, unobserveEl }
+}

package/src/use-transition/index.ts

@@ -0,0 +1,22 @@
+import type { Returned, CssTransitionOptions, StyleTransitionOptions } from './type'
+import { useCssTransition } from './use-css-transition'
+import { useStyleTransition } from './use-style-transition'
+
+/**
+ * 使用CSS类过渡
+ * @param type 过渡类型
+ * @param options 过渡选项
+ */
+export function useTransition(type: 'css', options: CssTransitionOptions): Returned
+/**
+ * 使用style样式过渡
+ * @param type 过渡类型
+ * @param options 过渡选项
+ */
+export function useTransition(type: 'style', options: StyleTransitionOptions): Returned
+export function useTransition(type: string, options: any): Returned {
+  if (type === 'css') {
+    return useCssTransition(options)
+  }
+  return useStyleTransition(options)
+}