niuma-ui 1.0.0 → 1.0.2

package/src/components/date-picker-utils.ts

@@ -25,6 +25,80 @@ export interface RsDateRangeValue {
   end?: string
 }
 
+/** v-model 取值格式：string 为默认字符串；timestamp 为毫秒时间戳 */
+export type RsDatePickerValueFormat = 'string' | 'timestamp'
+
+/** 时间戳范围（毫秒），用于 valueFormat=timestamp 的 range 模式 */
+export type RsDatePickerTimestampRange = [number, number]
+
+/** 组件对外 v-model 联合类型 */
+export type RsDatePickerModelValue =
+  | string
+  | number
+  | null
+  | RsDateRangeValue
+  | RsDatePickerTimestampRange
+
+/** 快捷项可返回字符串、时间戳或范围 */
+export type RsDatePickerShortcutValue =
+  | string
+  | number
+  | RsDateRangeValue
+  | RsDatePickerTimestampRange
+
+/** 日期/时间范围面板快捷项 */
+export interface RsDatePickerShortcut {
+  label: string
+  value: () => RsDatePickerShortcutValue
+}
+
+/** 将毫秒时间戳格式化为组件内部日期时间字符串 */
+export function formatTimestampValue(ms: number, withTime = true): string {
+  const parsed = dayjs(ms)
+  return withTime ? parsed.format(RS_DATETIME_FORMAT) : parsed.format(RS_DATE_FORMAT)
+}
+
+/** 将组件内部日期/日期时间字符串解析为毫秒时间戳 */
+export function parseTimestampValue(value?: string): number | null {
+  if (!value) return null
+  const parsed = parseRsDateTimeDayjs(value) ?? parseRsDayjs(value)
+  return parsed ? parsed.valueOf() : null
+}
+
+/** 判断是否为时间戳范围元组 */
+export function isTimestampRange(value: unknown): value is RsDatePickerTimestampRange {
+  return (
+    Array.isArray(value)
+    && value.length === 2
+    && typeof value[0] === 'number'
+    && typeof value[1] === 'number'
+  )
+}
+
+/** 将快捷项返回值规范为内部 string / RsDateRangeValue */
+export function normalizeShortcutValue(
+  next: RsDatePickerShortcutValue,
+  options?: { withTime?: boolean },
+): string | RsDateRangeValue | null {
+  const withTime = options?.withTime ?? true
+  if (typeof next === 'number') {
+    return formatTimestampValue(next, withTime)
+  }
+  if (isTimestampRange(next)) {
+    return {
+      start: formatTimestampValue(next[0], withTime),
+      end: formatTimestampValue(next[1], withTime),
+    }
+  }
+  if (typeof next === 'string') {
+    return next || null
+  }
+  if (next && typeof next === 'object') {
+    return { ...next }
+  }
+  return null
+}
+
 export interface RsCalendarCell extends RsParsedDate {
   inCurrentMonth: boolean
 }
@@ -78,10 +152,16 @@ export function formatDateTimeParts(
   withSeconds = true,
 ): string | null {
   const dateText = formatDateParts(date)
-  const timeFormat = withSeconds ? RS_TIME_SECONDS_FORMAT : RS_TIME_MINUTE_FORMAT
-  const parsed = dayjs(`${dateText} ${time}`, `${RS_DATE_FORMAT} ${timeFormat}`, true)
-  if (!parsed.isValid()) return null
-  return parsed.format(RS_DATETIME_FORMAT)
+  const formats = withSeconds
+    ? [`${RS_DATE_FORMAT} ${RS_TIME_SECONDS_FORMAT}`, `${RS_DATE_FORMAT} ${RS_TIME_MINUTE_FORMAT}`]
+    : [`${RS_DATE_FORMAT} ${RS_TIME_MINUTE_FORMAT}`]
+  for (const format of formats) {
+    const parsed = dayjs(`${dateText} ${time}`, format, true)
+    if (parsed.isValid()) {
+      return parsed.format(withSeconds ? RS_DATETIME_FORMAT : `${RS_DATE_FORMAT} ${RS_TIME_MINUTE_FORMAT}`)
+    }
+  }
+  return null
 }
 
 export function extractTimeFromDateTime(value?: string, withSeconds = true): string {

package/src/components/descriptions-utils.ts

@@ -0,0 +1,24 @@
+import type { InjectionKey } from 'vue'
+import type { RsComponentSize } from '../theme/types'
+
+/** Descriptions 尺寸与全局控件尺寸对齐：ssm / sm / md / lg */
+export type RsDescriptionsSize = RsComponentSize
+
+export type RsDescriptionsLabelPlacement = 'left' | 'top'
+
+export type RsDescriptionsItem = {
+  label: string
+  value?: string | number | null
+  span?: number
+  key?: string | number
+}
+
+export type RsDescriptionsContext = {
+  labelPlacement: RsDescriptionsLabelPlacement
+  bordered: boolean
+  size: RsDescriptionsSize
+  columns: number
+}
+
+export const RS_DESCRIPTIONS_KEY: InjectionKey<RsDescriptionsContext> =
+  Symbol('rs-descriptions')

package/src/components/dialog-utils.ts

@@ -0,0 +1,147 @@
+import type { Component } from 'vue'
+import type { RsLocale } from '../locale/types'
+import type { RsThemeMode } from '../theme/types'
+import type { RsFeedbackTone } from './overlay-utils'
+
+/** 宽度预设（与历史 sm/md/lg 一致） */
+export type RsDialogWidthPreset = 'sm' | 'md' | 'lg'
+
+/**
+ * 对话框宽度：预设或自定义（number 按 px；string 原样写入 CSS，如 `40rem` / `60%`）。
+ * 仅传入预设时行为与旧版完全一致。
+ */
+export type RsDialogWidth = RsDialogWidthPreset | number | string
+
+export type RsDialogLayout = 'window' | 'confirm'
+
+/** 关闭来源，供 beforeClose / afterClose 区分 */
+export type RsDialogCloseReason =
+  | 'close'
+  | 'overlay'
+  | 'escape'
+  | 'cancel'
+  | 'confirm'
+  | 'programmatic'
+
+/**
+ * 关闭前钩子：返回 false 阻止关闭；支持异步。
+ * 未提供或返回 void/true 时允许关闭。
+ */
+export type RsDialogBeforeClose = (
+  reason: RsDialogCloseReason,
+) => boolean | void | Promise<boolean | void>
+
+export function isRsDialogWidthPreset(width: RsDialogWidth): width is RsDialogWidthPreset {
+  return width === 'sm' || width === 'md' || width === 'lg'
+}
+
+/** 将自定义宽度规范为 CSS 长度 */
+export function resolveRsDialogCssWidth(width: RsDialogWidth): string | undefined {
+  if (isRsDialogWidthPreset(width)) return undefined
+  if (typeof width === 'number') {
+    if (!Number.isFinite(width) || width <= 0) return undefined
+    return `${width}px`
+  }
+  const trimmed = String(width).trim()
+  return trimmed || undefined
+}
+
+export async function runRsDialogBeforeClose(
+  beforeClose: RsDialogBeforeClose | undefined,
+  reason: RsDialogCloseReason,
+): Promise<boolean> {
+  if (!beforeClose) return true
+  const result = await beforeClose(reason)
+  return result !== false
+}
+
+/** 确认框关闭来源，供 beforeClose 区分 */
+export type RsConfirmCloseReason = 'confirm' | 'cancel' | 'escape' | 'programmatic'
+
+/**
+ * 确认框关闭前钩子：返回 false 阻止关闭；支持异步。
+ * 未提供或返回 void/true 时允许关闭。
+ */
+export type RsConfirmBeforeClose = (
+  reason: RsConfirmCloseReason,
+) => boolean | void | Promise<boolean | void>
+
+export interface RsConfirmOptions {
+  title?: string
+  /** 次要说明（标题与正文之间，对应业务侧常见 subtitle） */
+  subtitle?: string
+  description?: string
+  tone?: RsFeedbackTone
+  /** 自定义图标组件；不传则使用默认 "!" */
+  icon?: Component
+  /** 宽度：预设 sm/md/lg，或 number(px) / CSS 长度；默认保持 28rem */
+  width?: RsDialogWidth
+  confirmText?: string
+  cancelText?: string
+  confirmVariant?: 'primary' | 'danger'
+  /** 是否显示取消按钮；false 时为单按钮提示（info/success/error） */
+  showCancel?: boolean
+  /** 受控加载态；若同时提供 onConfirm，命令式 API 会在执行期间自动置 true */
+  confirmLoading?: boolean
+  /**
+   * 确认回调。返回 Promise 时对话框保持打开并进入 loading，
+   * resolve 后关闭并 resolve(true)；reject 则取消 loading 并保持打开。
+   */
+  onConfirm?: () => void | Promise<void>
+  /** 取消/关闭时回调（不区分来源） */
+  onCancel?: () => void
+  /** 关闭前钩子；返回 false 可阻止关闭 */
+  beforeClose?: RsConfirmBeforeClose
+  /**
+   * 正文与按钮之间的额外内容（渲染函数）。
+   * 声明式请用 RsConfirmDialog 的 #extra 插槽。
+   */
+  extra?: () => unknown
+  showOverlay?: boolean
+  /**
+   * 遮罩不透明度 0–1；覆盖 CSS 变量 --rs-dialog-overlay-bg。
+   * 未传时使用主题默认（最浅）。
+   */
+  overlayOpacity?: number
+  /**
+   * 遮罩模糊半径；number 按 px。覆盖 --rs-dialog-overlay-blur。
+   * 未传时使用主题默认（0）。
+   */
+  overlayBlur?: number | string
+  /** false 表示禁用 Teleport，就地渲染 */
+  teleportTo?: string | HTMLElement | false
+  /** 命令式挂载时覆盖主题；默认读 document data-rs-theme */
+  theme?: RsThemeMode
+  /** 命令式挂载时覆盖语言；默认读 document data-rs-locale */
+  locale?: RsLocale
+}
+
+/** 运行确认框 beforeClose；未提供或非 false 视为允许关闭 */
+export async function runRsConfirmBeforeClose(
+  beforeClose: RsConfirmBeforeClose | undefined,
+  reason: RsConfirmCloseReason,
+): Promise<boolean> {
+  if (!beforeClose) return true
+  const result = await beforeClose(reason)
+  return result !== false
+}
+
+/**
+ * 将 overlayOpacity / overlayBlur 转为遮罩 CSS 变量（可挂到 overlay 节点 style）。
+ */
+export function resolveDialogOverlayStyle(options?: {
+  overlayOpacity?: number
+  overlayBlur?: number | string
+}): Record<string, string> | undefined {
+  if (!options) return undefined
+  const style: Record<string, string> = {}
+  if (options.overlayOpacity != null && Number.isFinite(options.overlayOpacity)) {
+    const opacity = Math.min(1, Math.max(0, options.overlayOpacity))
+    style['--rs-dialog-overlay-bg'] = `rgb(0 0 0 / ${opacity})`
+  }
+  if (options.overlayBlur != null && options.overlayBlur !== '') {
+    style['--rs-dialog-overlay-blur'] =
+      typeof options.overlayBlur === 'number' ? `${options.overlayBlur}px` : String(options.overlayBlur)
+  }
+  return Object.keys(style).length ? style : undefined
+}

package/src/components/dialog-window.ts

@@ -1,7 +1,9 @@
 import { computed, onBeforeUnmount, ref, watch, type Ref } from 'vue'
+import type { RsDialogWidthPreset } from './dialog-utils'
 import { dialogViewportSize, readDialogViewportInsets } from './dialog-viewport'
 
-export type RsDialogWidth = 'sm' | 'md' | 'lg'
+/** @deprecated 使用 RsDialogWidthPreset；保留别名避免外部类型断裂 */
+export type RsDialogWidth = RsDialogWidthPreset
 export type RsDialogResizeHandle = 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw'
 
 export interface RsDialogBounds {
@@ -11,7 +13,7 @@ export interface RsDialogBounds {
   height: number
 }
 
-const widthMap: Record<RsDialogWidth, number> = {
+const widthMap: Record<RsDialogWidthPreset, number> = {
   sm: 384,
   md: 448,
   lg: 512,
@@ -24,7 +26,9 @@ const minHeight = 240
 
 export function useRsDialogWindow(options: {
   open: Ref<boolean>
-  widthPreset: Ref<RsDialogWidth>
+  widthPreset: Ref<RsDialogWidthPreset>
+  /** 自定义初始宽度（px）；有值时优先于预设/比例 */
+  initialWidth?: Ref<number | undefined>
   draggable: Ref<boolean>
   resizable: Ref<boolean>
   compact?: Ref<boolean>
@@ -39,6 +43,9 @@ export function useRsDialogWindow(options: {
 
   let boundsTransitionTimer: ReturnType<typeof setTimeout> | null = null
   let cachedInsets = readDialogViewportInsets()
+  /** 交互中的目标面板；有值时 pointermove 只改 DOM，pointerup 再写回 bounds */
+  let panelEl: HTMLElement | null = null
+  let liveBounds: RsDialogBounds | null = null
 
   let dragState: { startX: number; startY: number; origin: RsDialogBounds } | null = null
   let resizeState: {
@@ -48,10 +55,41 @@ export function useRsDialogWindow(options: {
     origin: RsDialogBounds
   } | null = null
 
+  function writePanelBox(next: RsDialogBounds): void {
+    if (!panelEl) return
+    panelEl.style.left = `${next.x}px`
+    panelEl.style.top = `${next.y}px`
+    panelEl.style.width = `${next.width}px`
+    panelEl.style.height = `${next.height}px`
+    panelEl.style.transform = 'none'
+  }
+
+  /** 绑定可定位的对话框根节点（DialogContent 的 DOM） */
+  function setPanelEl(el: HTMLElement | null): void {
+    panelEl = el
+  }
+
+  /** 优先用已绑定节点；否则从事件目标向上找面板（Reka DialogContent ref 不一定有 $el） */
+  function ensurePanelEl(from?: EventTarget | null): HTMLElement | null {
+    if (panelEl?.isConnected) return panelEl
+    const node = from instanceof Element ? from : null
+    const found = node?.closest('.rs-dialog__content')
+    if (found instanceof HTMLElement) {
+      panelEl = found
+      return found
+    }
+    return null
+  }
+
   function defaultWindowSize(): Pick<RsDialogBounds, 'width' | 'height'> {
     const { width: maxW, height: maxH } = dialogViewportSize()
+    const customW = options.initialWidth?.value
+    const width =
+      customW != null && Number.isFinite(customW) && customW > 0
+        ? Math.min(maxW, Math.max(minWidth, Math.round(customW)))
+        : Math.min(maxW, Math.max(minWidth, Math.round(maxW * defaultWidthRatio)))
     return {
-      width: Math.min(maxW, Math.max(minWidth, Math.round(maxW * defaultWidthRatio))),
+      width,
       height: Math.min(maxH, Math.max(minHeight, Math.round(maxH * defaultHeightRatio))),
     }
   }
@@ -97,7 +135,12 @@ export function useRsDialogWindow(options: {
     options.open,
     (value) => {
       if (value) resetOnOpen()
-      else stopInteractions()
+      else {
+        stopInteractions()
+        // 关闭时清全屏态，避免 KeepAlive 缓存残留 --fullscreen 类导致 Presence 补丁异常
+        isFullscreen.value = false
+        restoreBounds.value = null
+      }
     },
     // 弹出等场景：组件挂载时 open 已为 true，需立即居中，不能只等 false→true
     { immediate: true },
@@ -115,7 +158,11 @@ export function useRsDialogWindow(options: {
       }
     }
     if (options.compact?.value) {
-      const width = widthMap[options.widthPreset.value]
+      const customW = options.initialWidth?.value
+      const width =
+        customW != null && Number.isFinite(customW) && customW > 0
+          ? customW
+          : widthMap[options.widthPreset.value]
       return {
         left: '50%',
         top: `calc(${insets.top}px + (100vh - ${insets.top + insets.bottom}px) / 2)`,
@@ -169,7 +216,14 @@ export function useRsDialogWindow(options: {
     if (dragState) {
       const dx = event.clientX - dragState.startX
       const dy = event.clientY - dragState.startY
-      bounds.value = clampBounds({ ...dragState.origin, x: dragState.origin.x + dx, y: dragState.origin.y + dy })
+      const next = clampBounds({
+        ...dragState.origin,
+        x: dragState.origin.x + dx,
+        y: dragState.origin.y + dy,
+      })
+      // 拖拽中只改 DOM，避免触发 Vue 对对话框子树（如虚拟滚动树）的高频 patch
+      liveBounds = next
+      writePanelBox(next)
       return
     }
 
@@ -187,10 +241,16 @@ export function useRsDialogWindow(options: {
       next.height = resizeState.origin.height - dy
       next.y = resizeState.origin.y + dy
     }
-    bounds.value = clampBounds(next)
+    const clamped = clampBounds(next)
+    liveBounds = clamped
+    writePanelBox(clamped)
   }
 
   function stopInteractions(): void {
+    if (liveBounds) {
+      bounds.value = liveBounds
+      liveBounds = null
+    }
     dragState = null
     resizeState = null
     window.removeEventListener('pointermove', onPointerMove)
@@ -203,6 +263,7 @@ export function useRsDialogWindow(options: {
     boundsTransitionEnabled.value = false
     clearBoundsTransitionTimer()
     refreshCachedInsets()
+    liveBounds = { ...bounds.value }
     window.addEventListener('pointermove', onPointerMove)
     window.addEventListener('pointerup', stopInteractions)
     document.body.style.userSelect = 'none'
@@ -214,8 +275,10 @@ export function useRsDialogWindow(options: {
     const target = event.target as HTMLElement
     if (target.closest('button,a,input,textarea,select')) return
     event.preventDefault()
+    ensurePanelEl(event.target)
     dragState = { startX: event.clientX, startY: event.clientY, origin: { ...bounds.value } }
-    startInteraction('grabbing')
+    // move：四向十字箭头，表示可自由拖移窗口
+    startInteraction('move')
   }
 
   const resizeCursor: Record<RsDialogResizeHandle, string> = {
@@ -232,6 +295,7 @@ export function useRsDialogWindow(options: {
   function onResizePointerDown(handle: RsDialogResizeHandle, event: PointerEvent): void {
     if (!options.resizable.value || isFullscreen.value) return
     event.preventDefault()
+    ensurePanelEl(event.target)
     resizeState = { handle, startX: event.clientX, startY: event.clientY, origin: { ...bounds.value } }
     startInteraction(resizeCursor[handle])
   }
@@ -246,6 +310,7 @@ export function useRsDialogWindow(options: {
     boundsTransitionEnabled,
     dialogStyle,
     resizeHandles,
+    setPanelEl,
     toggleFullscreen,
     onHeaderPointerDown,
     onResizePointerDown,

package/src/components/drawer-utils.ts

@@ -0,0 +1,73 @@
+import {
+  resolveDialogOverlayStyle,
+  runRsDialogBeforeClose,
+  type RsDialogBeforeClose,
+  type RsDialogCloseReason,
+} from './dialog-utils'
+
+/** 抽屉滑出方向 */
+export type RsDrawerSide = 'left' | 'right' | 'top' | 'bottom'
+
+/** 抽屉尺寸预设（左右为宽度，上下为高度） */
+export type RsDrawerSize = 'sm' | 'md' | 'lg' | 'full'
+
+/**
+ * 自定义面板尺寸：number 按 px；string 原样写入 CSS（如 `24rem` / `40%`）。
+ * 与 size 同时传入时，自定义尺寸优先。
+ */
+export type RsDrawerDimension = number | string
+
+/** 关闭来源，与 Dialog 共用语义，便于业务统一 beforeClose */
+export type RsDrawerCloseReason = RsDialogCloseReason
+
+/** 关闭前钩子：返回 false 阻止关闭；支持异步 */
+export type RsDrawerBeforeClose = RsDialogBeforeClose
+
+const SIZE_INLINE: Record<Exclude<RsDrawerSize, 'full'>, string> = {
+  sm: '20rem',
+  md: '28rem',
+  lg: '36rem',
+}
+
+/** 将 size 预设解析为 CSS 长度（full 由样式类处理） */
+export function resolveRsDrawerSizeCss(size: RsDrawerSize): string | undefined {
+  if (size === 'full') return undefined
+  return SIZE_INLINE[size]
+}
+
+/** 将自定义 width/height 规范为 CSS 长度 */
+export function resolveRsDrawerDimensionCss(value: RsDrawerDimension | undefined): string | undefined {
+  if (value == null) return undefined
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value) || value <= 0) return undefined
+    return `${value}px`
+  }
+  const trimmed = String(value).trim()
+  return trimmed || undefined
+}
+
+export function runRsDrawerBeforeClose(
+  beforeClose: RsDrawerBeforeClose | undefined,
+  reason: RsDrawerCloseReason,
+): Promise<boolean> {
+  return runRsDialogBeforeClose(beforeClose, reason)
+}
+
+/**
+ * 遮罩样式：复用 Dialog 的 opacity/blur 解析，写入抽屉专用 CSS 变量。
+ */
+export function resolveDrawerOverlayStyle(options?: {
+  overlayOpacity?: number
+  overlayBlur?: number | string
+}): Record<string, string> | undefined {
+  const dialogStyle = resolveDialogOverlayStyle(options)
+  if (!dialogStyle) return undefined
+  const style: Record<string, string> = {}
+  if (dialogStyle['--rs-dialog-overlay-bg']) {
+    style['--rs-drawer-overlay-bg'] = dialogStyle['--rs-dialog-overlay-bg']
+  }
+  if (dialogStyle['--rs-dialog-overlay-blur']) {
+    style['--rs-drawer-overlay-blur'] = dialogStyle['--rs-dialog-overlay-blur']
+  }
+  return Object.keys(style).length ? style : undefined
+}