niuma-ui 1.0.2 → 1.1.0

package/src/components/use-rs-select.ts

@@ -0,0 +1,436 @@
+import { computed, nextTick, watch, type ModelRef } from 'vue'
+import type { RsTranslateFn } from '../composables/useRsI18n'
+import { useFilter } from './reka'
+import {
+  buildOptionDisabledMap,
+  buildOptionLabelMap,
+  comboboxBindingToTokens,
+  filterSelectOptions,
+  findSelectOption,
+  flattenSelectOptions,
+  flattenSelectValues,
+  fromComboboxValue,
+  isSelectLabeledValue,
+  normalizeSelectOptions,
+  optionDisplayLabel,
+  packSelectModel,
+  restoreSelectValue,
+  restoreSelectValues,
+  selectModelEntries,
+  sortSelectOptions,
+  splitByTokenSeparators,
+  toComboboxValue,
+  toSelectedTokens,
+  type RsSelectFieldNames,
+  type RsSelectFilterOption,
+  type RsSelectFilterSort,
+  type RsSelectModelValue,
+  type RsSelectOption,
+  type RsSelectOptionFilterProp,
+  type RsSelectOptionsInput,
+  type RsSelectValue,
+} from './select-utils'
+
+/** RsSelect 行为层入参（不含尺寸 / 表单外观） */
+export interface RsSelectEngineProps {
+  options: RsSelectOptionsInput
+  fieldNames?: RsSelectFieldNames
+  optionLabelProp?: string
+  optionFilterProp?: RsSelectOptionFilterProp
+  filterOption?: RsSelectFilterOption | boolean
+  filterSort?: RsSelectFilterSort
+  searchable?: boolean
+  creatable?: boolean
+  multiple?: boolean
+  remote?: boolean
+  virtual?: boolean
+  virtualThreshold?: number
+  maxTagCount?: number
+  maxTagPlaceholder?: string | ((omitted: number) => string)
+  maxTagTooltip?: boolean
+  maxTagTextLength?: number
+  multipleLimit?: number
+  labelInValue?: boolean
+  tokenSeparators?: string[]
+  autoClearSearchValue?: boolean
+  searchPlaceholder?: string
+  emptyText?: string
+  loadingText?: string
+  placeholder?: string
+}
+
+export type RsSelectEngineEmit = {
+  (e: 'search', query: string): void
+  (e: 'select', value: RsSelectValue, option?: RsSelectOption): void
+  (e: 'deselect', value: RsSelectValue, option?: RsSelectOption): void
+  (e: 'clear'): void
+}
+
+/**
+ * Select 过滤、选中、多选 tag、creatable / 分隔符提交。
+ * 组件模板只消费返回值；表单校验仍留在 SFC。
+ */
+export function useRsSelect(
+  props: RsSelectEngineProps,
+  model: ModelRef<RsSelectModelValue>,
+  open: ModelRef<boolean>,
+  searchQuery: ModelRef<string>,
+  emit: RsSelectEngineEmit,
+  t: RsTranslateFn,
+) {
+  const { contains } = useFilter({ sensitivity: 'base' })
+
+  const normalizedOptions = computed(() =>
+    normalizeSelectOptions(props.options, props.fieldNames),
+  )
+
+  const resolvedPlaceholder = computed(() => props.placeholder ?? t('select.placeholder'))
+  const resolvedSearchPlaceholder = computed(
+    () => props.searchPlaceholder ?? t('select.searchPlaceholder'),
+  )
+  const resolvedEmptyText = computed(() => props.emptyText ?? t('select.empty'))
+  const resolvedLoadingText = computed(() => props.loadingText ?? t('select.loading'))
+  const isSearchable = computed(() => Boolean(props.searchable || props.creatable))
+
+  const labelMap = computed(() => buildOptionLabelMap(normalizedOptions.value))
+  const disabledMap = computed(() => buildOptionDisabledMap(normalizedOptions.value))
+  const flatOptions = computed(() => flattenSelectOptions(normalizedOptions.value))
+  const flatCount = computed(() => flatOptions.value.length)
+  const useVirtual = computed(
+    () => Boolean(props.virtual) || flatCount.value > (props.virtualThreshold ?? 50),
+  )
+
+  const useManualFilter = computed(
+    () =>
+      Boolean(props.remote) ||
+      useVirtual.value ||
+      typeof props.filterOption === 'function' ||
+      props.filterOption === false ||
+      Boolean(props.optionFilterProp && props.optionFilterProp !== 'label') ||
+      Boolean(props.filterSort) ||
+      Boolean(props.fieldNames),
+  )
+
+  const displayOptions = computed(() => {
+    let next = normalizedOptions.value
+    if (!props.remote && props.filterOption !== false) {
+      if (useManualFilter.value || props.filterOption) {
+        next = filterSelectOptions(
+          normalizedOptions.value,
+          searchQuery.value,
+          contains,
+          props.filterOption,
+          props.optionFilterProp,
+        )
+      }
+    }
+    return sortSelectOptions(next, props.filterSort)
+  })
+
+  const createValue = computed(() => searchQuery.value.trim())
+
+  const canCreate = computed(() => {
+    if (!props.creatable) return false
+    const q = createValue.value
+    if (!q) return false
+    const lower = q.toLowerCase()
+    return !flatOptions.value.some(
+      (opt) =>
+        String(opt.value).toLowerCase() === lower || String(opt.label).toLowerCase() === lower,
+    )
+  })
+
+  const createOptionLabel = computed(() =>
+    t('select.createOption', '使用 “{query}”').replace('{query}', createValue.value),
+  )
+
+  const virtualValues = computed(() => {
+    const values = flattenSelectValues(displayOptions.value)
+    if (!canCreate.value) return values
+    return [createValue.value, ...values.filter((item) => String(item) !== createValue.value)]
+  })
+
+  const selectedValues = computed(() => toSelectedTokens(model.value, Boolean(props.multiple)))
+  const hasValue = computed(() => selectedValues.value.length > 0)
+
+  const visibleTagTokens = computed(() => {
+    const all = selectedValues.value
+    if (!props.multiple || props.maxTagCount == null || all.length <= props.maxTagCount) {
+      return all
+    }
+    return all.slice(0, Math.max(0, props.maxTagCount))
+  })
+
+  const omittedTagCount = computed(() =>
+    Math.max(0, selectedValues.value.length - visibleTagTokens.value.length),
+  )
+
+  const omittedTagLabel = computed(() => {
+    const count = omittedTagCount.value
+    if (typeof props.maxTagPlaceholder === 'function') return props.maxTagPlaceholder(count)
+    if (props.maxTagPlaceholder) return props.maxTagPlaceholder
+    return t('select.maxTagPlaceholder', { count })
+  })
+
+  function optionFromToken(token: string): RsSelectOption | undefined {
+    return findSelectOption(normalizedOptions.value, String(token))
+  }
+
+  function tokenLabel(token: string): string {
+    if (props.labelInValue) {
+      for (const entry of selectModelEntries(model.value)) {
+        if (
+          isSelectLabeledValue(entry) &&
+          toComboboxValue(entry.value) === token &&
+          entry.label
+        ) {
+          return entry.label
+        }
+      }
+    }
+    const option = optionFromToken(token)
+    if (option) return optionDisplayLabel(option, props.optionLabelProp)
+    return labelMap.value.get(token) ?? fromComboboxValue(token)
+  }
+
+  const omittedTagTitle = computed(() => {
+    if (!props.maxTagTooltip) return omittedTagLabel.value
+    const omitted = selectedValues.value.slice(visibleTagTokens.value.length)
+    if (!omitted.length) return omittedTagLabel.value
+    return omitted.map((token) => tokenLabel(token)).join('、')
+  })
+
+  function truncateTagLabel(label: string): string {
+    const max = props.maxTagTextLength
+    if (!max || max < 1 || label.length <= max) return label
+    return `${label.slice(0, max)}…`
+  }
+
+  const atMultipleLimit = computed(
+    () =>
+      Boolean(props.multiple) &&
+      props.multipleLimit != null &&
+      props.multipleLimit > 0 &&
+      selectedValues.value.length >= props.multipleLimit,
+  )
+
+  function isOptionLimited(option: RsSelectOption): boolean {
+    if (!atMultipleLimit.value) return false
+    return !selectedValues.value.includes(toComboboxValue(option.value))
+  }
+
+  function isTokenDisabled(token: string): boolean {
+    if (disabledMap.value.get(String(token))) return true
+    const option = optionFromToken(token)
+    return option ? isOptionLimited(option) : false
+  }
+
+  const singleDisplayLabel = computed(() => {
+    if (props.multiple || !hasValue.value) return ''
+    return tokenLabel(selectedValues.value[0]!)
+  })
+
+  function writeTokens(tokens: string[]): void {
+    const values = restoreSelectValues(tokens, normalizedOptions.value)
+    model.value = packSelectModel(
+      values,
+      normalizedOptions.value,
+      Boolean(props.multiple),
+      Boolean(props.labelInValue),
+    )
+  }
+
+  function emitSelectionDiff(prev: string[], next: string[]): void {
+    const prevSet = new Set(prev)
+    const nextSet = new Set(next)
+    for (const token of next) {
+      if (prevSet.has(token)) continue
+      const value = restoreSelectValue(token, normalizedOptions.value)
+      emit('select', value, findSelectOption(normalizedOptions.value, token))
+    }
+    for (const token of prev) {
+      if (nextSet.has(token)) continue
+      const value = restoreSelectValue(token, normalizedOptions.value)
+      emit('deselect', value, findSelectOption(normalizedOptions.value, token))
+    }
+  }
+
+  const comboboxModel = computed<string | string[] | undefined>({
+    get() {
+      if (props.multiple) return selectedValues.value.map((token) => token)
+      return hasValue.value ? selectedValues.value[0] : undefined
+    },
+    set(value) {
+      const prev = selectedValues.value
+      const tokens = comboboxBindingToTokens(value, Boolean(props.multiple))
+      emitSelectionDiff(prev, tokens)
+      writeTokens(tokens)
+      if (props.autoClearSearchValue) searchQuery.value = ''
+    },
+  })
+
+  function currentValues(): RsSelectValue[] {
+    return restoreSelectValues(selectedValues.value, normalizedOptions.value)
+  }
+
+  function commitCreatedValue(value: string): void {
+    const next = value.trim()
+    if (!next) return
+    const values = currentValues()
+    if (values.some((item) => String(item) === next)) return
+    if (props.multiple) {
+      if (atMultipleLimit.value) return
+      const prev = selectedValues.value
+      const packed = packSelectModel(
+        [...values, next],
+        normalizedOptions.value,
+        true,
+        Boolean(props.labelInValue),
+      )
+      model.value = packed
+      emitSelectionDiff(prev, toSelectedTokens(packed, true))
+    } else {
+      const prev = selectedValues.value
+      model.value = packSelectModel(
+        [next],
+        normalizedOptions.value,
+        false,
+        Boolean(props.labelInValue),
+      )
+      emitSelectionDiff(prev, toSelectedTokens(model.value, false))
+      open.value = false
+    }
+    if (props.autoClearSearchValue) searchQuery.value = ''
+  }
+
+  function consumeTokenSeparators(raw: string): void {
+    if (!props.multiple && !props.creatable) return
+    const parts = splitByTokenSeparators(raw, props.tokenSeparators ?? [])
+    if (!parts) return
+    const rest = parts.pop() ?? ''
+    for (const part of parts) {
+      const token = part.trim()
+      if (!token) continue
+      const matched = flatOptions.value.find(
+        (opt) => String(opt.value) === token || String(opt.label) === token,
+      )
+      if (matched) {
+        const prev = selectedValues.value
+        const key = toComboboxValue(matched.value)
+        if (prev.includes(key)) continue
+        if (props.multiple && atMultipleLimit.value) continue
+        const nextTokens = props.multiple ? [...prev, key] : [key]
+        emitSelectionDiff(prev, nextTokens)
+        writeTokens(nextTokens)
+        if (!props.multiple) open.value = false
+      } else if (props.creatable) {
+        commitCreatedValue(token)
+      }
+    }
+    if (rest !== raw) searchQuery.value = rest
+  }
+
+  watch(searchQuery, (query) => {
+    if (props.remote) emit('search', query)
+    if (props.tokenSeparators?.length) consumeTokenSeparators(query)
+  })
+
+  watch(open, async (isOpen) => {
+    if (isOpen) {
+      const pending = searchQuery.value
+      await nextTick()
+      await nextTick()
+      // ComboboxInput 挂载时会 resetSearchTerm；受控 searchValue 需要写回
+      if (pending) searchQuery.value = pending
+      return
+    }
+    if (props.autoClearSearchValue) searchQuery.value = ''
+  })
+
+  function onSearchKeydown(event: KeyboardEvent): void {
+    if (event.key !== 'Enter' || event.isComposing) return
+    if (!canCreate.value) return
+    event.preventDefault()
+    event.stopPropagation()
+    commitCreatedValue(createValue.value)
+  }
+
+  function onClear(event: MouseEvent): void {
+    event.preventDefault()
+    event.stopPropagation()
+    emitSelectionDiff(selectedValues.value, [])
+    emit('clear')
+    model.value = props.multiple ? [] : ''
+  }
+
+  function removeTag(value: string, event: MouseEvent): void {
+    event.preventDefault()
+    event.stopPropagation()
+    if (!props.multiple) return
+    const prev = selectedValues.value
+    const tokens = prev.filter((item) => item !== value)
+    emitSelectionDiff(prev, tokens)
+    writeTokens(tokens)
+  }
+
+  function setValue(value: unknown): void {
+    if (props.multiple) {
+      const list = Array.isArray(value) ? value : value !== '' && value != null ? [value] : []
+      writeTokens(toSelectedTokens(list, true))
+      return
+    }
+    writeTokens(toSelectedTokens(value, false))
+  }
+
+  function restoreTokenValue(token: string): RsSelectValue {
+    return restoreSelectValue(token, normalizedOptions.value)
+  }
+
+  function optionOrCreate(token: string): RsSelectOption {
+    return (
+      optionFromToken(token) ?? {
+        label: fromComboboxValue(token),
+        value: restoreTokenValue(token),
+      }
+    )
+  }
+
+  return {
+    normalizedOptions,
+    resolvedPlaceholder,
+    resolvedSearchPlaceholder,
+    resolvedEmptyText,
+    resolvedLoadingText,
+    isSearchable,
+    labelMap,
+    useVirtual,
+    useManualFilter,
+    displayOptions,
+    createValue,
+    canCreate,
+    createOptionLabel,
+    virtualValues,
+    selectedValues,
+    hasValue,
+    visibleTagTokens,
+    omittedTagCount,
+    omittedTagLabel,
+    omittedTagTitle,
+    singleDisplayLabel,
+    comboboxModel,
+    tokenLabel,
+    truncateTagLabel,
+    optionFromToken,
+    optionOrCreate,
+    isOptionLimited,
+    isTokenDisabled,
+    restoreTokenValue,
+    onSearchKeydown,
+    onClear,
+    removeTag,
+    setValue,
+    resetSearch: () => {
+      searchQuery.value = ''
+    },
+  }
+}

package/src/composables/useRsConfig.ts

@@ -1,4 +1,9 @@
 import { inject, provide, ref, type InjectionKey, type Ref } from 'vue'
+import {
+  interpolateRsMessage,
+  resolveRsTranslateArgs,
+  type RsTranslateFn,
+} from '../locale/interpolate'
 import { localeMap } from '../locale/messages'
 import { defaultLocale, type RsLocale } from '../locale/types'
 import type { RsComponentSize, RsRadius, RsThemeMode } from '../theme/types'
@@ -17,7 +22,7 @@ export interface RsConfigContext {
   setLocale: (locale: RsLocale) => void
   setControlSize: (size: RsComponentSize) => void
   setControlRadius: (radius: RsRadius | undefined) => void
-  t: (key: string, fallback?: string) => string
+  t: RsTranslateFn
 }
 
 export const rsConfigKey: InjectionKey<RsConfigContext> = Symbol('rs-config')
@@ -65,8 +70,10 @@ export function createRsConfigState(
     controlRadius.value = radius
   }
 
-  function t(key: string, fallback?: string) {
-    return localeMap[locale.value][key] ?? fallback ?? key
+  const t: RsTranslateFn = (key, fallbackOrVars, vars) => {
+    const parsed = resolveRsTranslateArgs(fallbackOrVars, vars)
+    const raw = localeMap[locale.value][key] ?? parsed.fallback ?? key
+    return interpolateRsMessage(raw, parsed.vars)
   }
 
   if (typeof document !== 'undefined') {

package/src/composables/useRsI18n.ts

@@ -1,22 +1,33 @@
 import { computed, inject } from 'vue'
+import { interpolateRsMessage, resolveRsTranslateArgs, type RsI18nVars, type RsTranslateFn } from '../locale/interpolate'
 import { localeMap } from '../locale/messages'
 import { defaultLocale, type RsLocale } from '../locale/types'
 import { rsConfigKey } from './useRsConfig'
 
-export type RsTranslateFn = (key: string, fallback?: string) => string
+export type { RsI18nVars, RsTranslateFn }
+
+function translate(
+  locale: RsLocale,
+  key: string,
+  fallbackOrVars?: string | RsI18nVars,
+  vars?: RsI18nVars,
+): string {
+  const parsed = resolveRsTranslateArgs(fallbackOrVars, vars)
+  const raw = localeMap[locale][key] ?? parsed.fallback ?? key
+  return interpolateRsMessage(raw, parsed.vars)
+}
 
 /** 组件内安全取文案：Provider 内跟随 locale，否则回退 defaultLocale */
 export function useRsI18n() {
   const ctx = inject(rsConfigKey, null)
   const locale = computed<RsLocale>(() => ctx?.locale.value ?? defaultLocale)
 
-  function t(key: string, fallback?: string): string {
-    return localeMap[locale.value][key] ?? fallback ?? key
-  }
+  const t: RsTranslateFn = (key, fallbackOrVars, vars) =>
+    translate(locale.value, key, fallbackOrVars, vars)
 
   return { t, locale }
 }
 
 export function createTranslator(locale: RsLocale): RsTranslateFn {
-  return (key, fallback) => localeMap[locale][key] ?? fallback ?? key
+  return (key, fallbackOrVars, vars) => translate(locale, key, fallbackOrVars, vars)
 }

package/src/index.ts

@@ -11,6 +11,7 @@ export {
 } from './components/button-utils'
 export { default as RsCheckbox } from './components/RsCheckbox.vue'
 export { default as RsSwitch } from './components/RsSwitch.vue'
+export type { RsSwitchValue } from './components/RsSwitch.vue'
 export { default as RsRadio } from './components/RsRadio.vue'
 export { default as RsRadioItem } from './components/RsRadioItem.vue'
 export type { RsRadioValue } from './components/radio-utils'
@@ -89,6 +90,7 @@ export {
   isRsDialogWidthPreset,
   resolveDialogOverlayStyle,
   resolveRsDialogCssWidth,
+  resolveRsDialogWidthPx,
   runRsConfirmBeforeClose,
   runRsDialogBeforeClose,
 } from './components/dialog-utils'
@@ -107,6 +109,8 @@ export {
   runRsDrawerBeforeClose,
 } from './components/drawer-utils'
 export { default as RsForm } from './components/RsForm.vue'
+export { default as RsFormItem } from './components/RsFormItem.vue'
+export { default as RsFormList } from './components/RsFormList.vue'
 export { default as RsToaster } from './components/RsToaster.vue'
 export { default as RsDatePicker } from './components/RsDatePicker.vue'
 export { default as RsDateTimePicker } from './components/RsDateTimePicker.vue'
@@ -205,11 +209,33 @@ export type { RsContextMenuItem } from './components/context-menu-utils'
 export type { RsDropdownItem, RsDropdownItemGroup, RsDropdownItems } from './components/dropdown-utils'
 export type { RsMenuItem, RsMenuItemGroup, RsMenuItems } from './components/menu-utils'
 export type { RsScrollbarOrientation, RsScrollbarType } from './components/scrollbar-utils'
-export type { RsSelectOption, RsSelectOptionGroup, RsSelectOptions } from './components/select-utils'
+export type {
+  RsSelectFieldNames,
+  RsSelectFilterOption,
+  RsSelectFilterSort,
+  RsSelectGetPopupContainer,
+  RsSelectLabeledValue,
+  RsSelectModelValue,
+  RsSelectOption,
+  RsSelectOptionFilterProp,
+  RsSelectOptionGroup,
+  RsSelectOptionInput,
+  RsSelectOptions,
+  RsSelectOptionsInput,
+  RsSelectPlacement,
+  RsSelectStatus,
+  RsSelectValue,
+} from './components/select-utils'
 export {
   RS_SELECT_EMPTY_VALUE,
   fromComboboxValue,
+  isSelectLabeledValue,
+  normalizeSelectOptions,
+  optionDisplayLabel,
+  packSelectModel,
+  restoreSelectValue,
   toComboboxValue,
+  unwrapSelectEntry,
 } from './components/select-utils'
 export type { RsFeedbackTone, RsToastPosition, RsToastType } from './components/overlay-utils'
 export { RS_TOAST_DEFAULT_GAP, RS_TOAST_DEFAULT_POSITION, rsToastPositions, rsFeedbackIconClass } from './components/overlay-utils'
@@ -218,27 +244,51 @@ export type {
   RsFormErrorRender,
   RsFormErrorRenderContext,
   RsFormFieldExpose,
+  RsFormItemContext,
+  RsFormListContext,
+  RsFormListField,
+  RsFormListOperations,
   RsFormFieldValidationResult,
   RsFormGap,
   RsFormLabelAlign,
   RsFormLabelPosition,
   RsFormMaxWidth,
   RsFormSize,
+  RsFormValidateStatus,
   RsFormValidationResult,
 } from './components/form-utils'
 export {
   cloneFormFieldValue,
+  isRsFormItemBoundControl,
+  provideRsFormItemContext,
+  provideRsFormListContext,
   RS_FORM_INJECTION_KEY,
+  RS_FORM_ITEM_INJECTION_KEY,
+  RS_FORM_LIST_INJECTION_KEY,
   resolveFieldRules,
   useRsFormContext,
   useRsFormField,
+  useRsFormItemContext,
+  useRsFormListContext,
 } from './components/form-utils'
+export type { RsFormNamePath } from './components/form-path'
+export {
+  concatNamePath,
+  getByNamePath,
+  hasByNamePath,
+  isIndexSegment,
+  namePathKey,
+  normalizeNamePath,
+  setByNamePath,
+} from './components/form-path'
 export type {
   RsFormRuleItem,
   RsFormRuleMessage,
   RsFormRules,
   RsFormRuleTrigger,
   RsFormRuleValidateResult,
+  RsFormValidateMessages,
+  RsFormValidatorContext,
 } from './components/form-rules'
 export {
   buildLocalInputRules,
@@ -596,7 +646,9 @@ export type {
   RsDatePickerModelValue,
   RsDatePickerShortcut,
   RsDatePickerTimestampRange,
+  RsDatePickerValueConvertOptions,
   RsDatePickerValueFormat,
+  RsDatePickerValueFormatPreset,
   RsDateRangeValue,
   RsParsedDate,
   RsParsedDateTime,
@@ -609,11 +661,15 @@ export {
   formatDateTimeDisplay,
   formatDateTimeValue,
   formatDateValue,
+  fromInternalPickerValue,
   isDateRangeEmpty,
   isDateRangeOrdered,
   isDateTimeRangeOrdered,
   parseDateTimeValue,
   parseDateValue,
+  RS_DATE_PICKER_VALUE_FORMAT_PRESETS,
+  toInternalPickerValue,
+  toRangeEndpointString,
 } from './components/date-picker-utils'
 export {
   RS_DATE_FORMAT,
@@ -723,3 +779,15 @@ export { useResolvedRsComponentSize, resolveRsComponentSize } from './components
 export { useResolvedRsRadius, rsRadiusCss } from './components/resolve-radius'
 export { themePresets } from './theme/presets'
 export { applyTheme } from './theme/apply'
+export {
+  parseCssLengthToPx,
+  readCodeFontFamily,
+  readCodeFontSizePx,
+  readCssLengthPx,
+  readCssVar,
+  readRootFontSizePx,
+  readTerminalFontFamily,
+  readTerminalFontSizePx,
+  readTerminalFontWeight,
+  readTerminalFontWeightBold,
+} from './theme/css-token'

package/src/locale/interpolate.ts

@@ -0,0 +1,32 @@
+export type RsI18nVars = Record<string, string | number>
+
+export type RsTranslateFn = (
+  key: string,
+  fallbackOrVars?: string | RsI18nVars,
+  vars?: RsI18nVars,
+) => string
+
+/**
+ * 将文案中的 `{name}` 替换为 vars。
+ * 对标 Ant Design / vue-i18n 的命名插值。
+ */
+export function interpolateRsMessage(template: string, vars?: RsI18nVars): string {
+  if (!vars) return template
+  return template.replace(/\{(\w+)\}/g, (matched, key: string) => {
+    const value = vars[key]
+    return value == null ? matched : String(value)
+  })
+}
+
+/**
+ * 解析 t() 的第 2、3 参：既兼容 `t(key, fallback)`，也支持 `t(key, vars)`。
+ */
+export function resolveRsTranslateArgs(
+  fallbackOrVars?: string | RsI18nVars,
+  vars?: RsI18nVars,
+): { fallback?: string; vars?: RsI18nVars } {
+  if (fallbackOrVars && typeof fallbackOrVars === 'object') {
+    return { vars: fallbackOrVars }
+  }
+  return { fallback: fallbackOrVars, vars }
+}