niuma-ui 1.0.0 → 1.0.2

package/src/components/form-rules.ts

@@ -0,0 +1,257 @@
+import type { RsTranslateFn } from '../composables/useRsI18n'
+import { createTranslator } from '../composables/useRsI18n'
+import { defaultLocale } from '../locale/types'
+import {
+  getInputRuleMessage,
+  validateInputRule,
+  type RsInputRule,
+} from './input-rules'
+
+/** 校验触发时机（对齐 Ant Design Form） */
+export type RsFormRuleTrigger = 'blur' | 'change' | 'submit'
+
+/**
+ * 单条表单规则（声明式 + 自定义校验）。
+ * 对标 Ant Design / Element Plus Form rules 的常用子集。
+ */
+/** 规则文案：静态字符串，或按当前值动态生成（对齐 Ant Design message 函数能力） */
+export type RsFormRuleMessage =
+  | string
+  | ((ctx: { value: unknown; rule: RsFormRuleItem }) => string)
+
+export interface RsFormRuleItem {
+  required?: boolean
+  /**
+   * 错误文案；未传时使用内置 i18n。
+   * 可传函数按当前值动态生成文案。
+   */
+  message?: RsFormRuleMessage
+  /** 字符串长度下限 / 数值下限 */
+  min?: number
+  /** 字符串长度上限 / 数值上限 */
+  max?: number
+  /** 字符串精确长度 */
+  len?: number
+  pattern?: RegExp
+  /** 内置类型：email/phone 等，或 string/number/array */
+  type?: RsInputRule | 'string' | 'number' | 'array'
+  /**
+   * 自定义校验。返回 true 通过；false / 字符串为失败；支持 Promise。
+   */
+  validator?: (
+    value: unknown,
+  ) => boolean | string | void | Promise<boolean | string | void>
+  trigger?: RsFormRuleTrigger | RsFormRuleTrigger[]
+}
+
+/** 字段名 → 规则（单条或数组） */
+export type RsFormRules = Record<string, RsFormRuleItem | RsFormRuleItem[]>
+
+export interface RsFormRuleValidateResult {
+  valid: boolean
+  message?: string
+}
+
+export function normalizeFormRules(
+  rules?: RsFormRuleItem | RsFormRuleItem[] | null,
+): RsFormRuleItem[] {
+  if (!rules) return []
+  return Array.isArray(rules) ? rules : [rules]
+}
+
+export function matchFormRuleTrigger(
+  rule: RsFormRuleItem,
+  trigger?: RsFormRuleTrigger,
+): boolean {
+  if (!trigger || trigger === 'submit') return true
+  const ruleTrigger = rule.trigger
+  if (!ruleTrigger) return true
+  const list = Array.isArray(ruleTrigger) ? ruleTrigger : [ruleTrigger]
+  return list.includes(trigger)
+}
+
+function isEmptyValue(value: unknown): boolean {
+  if (value == null) return true
+  if (typeof value === 'string') return value.trim() === ''
+  if (Array.isArray(value)) return value.length === 0
+  // 日期区间 { start, end }：两端皆空视为空
+  if (typeof value === 'object') {
+    const record = value as Record<string, unknown>
+    if ('start' in record || 'end' in record) {
+      return isEmptyValue(record.start) && isEmptyValue(record.end)
+    }
+  }
+  return false
+}
+
+function valueLength(value: unknown): number | null {
+  if (typeof value === 'string') return value.trim().length
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (Array.isArray(value)) return value.length
+  return null
+}
+
+function fail(message: string): RsFormRuleValidateResult {
+  return { valid: false, message }
+}
+
+/** 解析规则 message（字符串或函数） */
+export function resolveRuleMessage(
+  rule: RsFormRuleItem,
+  value: unknown,
+  fallback: string,
+): string {
+  const message = rule.message
+  if (typeof message === 'function') return message({ value, rule })
+  if (typeof message === 'string') return message
+  return fallback
+}
+
+function formatInvalid(
+  rule: RsFormRuleItem,
+  value: unknown,
+  tr: RsTranslateFn,
+): string {
+  return resolveRuleMessage(rule, value, tr('input.formatInvalid'))
+}
+
+/** 类型规则：string/number/array 或内置 email/phone 等 */
+function checkTypeRule(
+  value: unknown,
+  rule: RsFormRuleItem,
+  tr: RsTranslateFn,
+): RsFormRuleValidateResult | null {
+  const type = rule.type
+  if (!type) return null
+
+  if (type === 'string' && typeof value !== 'string') {
+    return fail(formatInvalid(rule, value, tr))
+  }
+  if (type === 'number' && typeof value !== 'number') {
+    return fail(formatInvalid(rule, value, tr))
+  }
+  if (type === 'array' && !Array.isArray(value)) {
+    return fail(formatInvalid(rule, value, tr))
+  }
+
+  const isBuiltin =
+    type !== 'string' && type !== 'number' && type !== 'array'
+  if (isBuiltin && typeof value === 'string' && !validateInputRule(value, type)) {
+    return fail(
+      resolveRuleMessage(rule, value, getInputRuleMessage(type, tr)),
+    )
+  }
+
+  return null
+}
+
+function checkPatternRule(
+  value: unknown,
+  rule: RsFormRuleItem,
+  tr: RsTranslateFn,
+): RsFormRuleValidateResult | null {
+  if (!rule.pattern || typeof value !== 'string') return null
+  if (rule.pattern.test(value)) return null
+  return fail(formatInvalid(rule, value, tr))
+}
+
+function checkLengthRule(
+  value: unknown,
+  rule: RsFormRuleItem,
+  tr: RsTranslateFn,
+): RsFormRuleValidateResult | null {
+  const length = valueLength(value)
+  if (length == null) return null
+
+  if (rule.len != null && length !== rule.len) {
+    return fail(formatInvalid(rule, value, tr))
+  }
+  if (rule.min != null && length < rule.min) {
+    return fail(formatInvalid(rule, value, tr))
+  }
+  if (rule.max != null && length > rule.max) {
+    return fail(formatInvalid(rule, value, tr))
+  }
+  return null
+}
+
+async function checkValidatorRule(
+  value: unknown,
+  rule: RsFormRuleItem,
+  tr: RsTranslateFn,
+): Promise<RsFormRuleValidateResult | null> {
+  if (!rule.validator) return null
+
+  const result = await rule.validator(value)
+  if (result === true || result === undefined || result === null) return null
+  if (result === false) return fail(formatInvalid(rule, value, tr))
+  if (typeof result === 'string') return fail(result)
+  return null
+}
+
+/**
+ * 执行单条规则；通过返回 null，失败返回结果。
+ * 空值且非必填时跳过格式类规则。
+ */
+async function evaluateFormRule(
+  value: unknown,
+  rule: RsFormRuleItem,
+  tr: RsTranslateFn,
+): Promise<RsFormRuleValidateResult | null> {
+  if (rule.required && isEmptyValue(value)) {
+    return fail(resolveRuleMessage(rule, value, tr('input.required')))
+  }
+  if (isEmptyValue(value)) return null
+
+  return (
+    checkTypeRule(value, rule, tr) ??
+    checkPatternRule(value, rule, tr) ??
+    checkLengthRule(value, rule, tr) ??
+    (await checkValidatorRule(value, rule, tr))
+  )
+}
+
+/**
+ * 按顺序执行字段规则，首条失败即返回。
+ */
+export async function runFormFieldRules(
+  value: unknown,
+  rules: RsFormRuleItem[],
+  options?: {
+    trigger?: RsFormRuleTrigger
+    t?: RsTranslateFn
+  },
+): Promise<RsFormRuleValidateResult> {
+  const tr = options?.t ?? createTranslator(defaultLocale)
+  const trigger = options?.trigger
+
+  for (const rule of rules) {
+    if (!matchFormRuleTrigger(rule, trigger)) continue
+    const failed = await evaluateFormRule(value, rule, tr)
+    if (failed) return failed
+  }
+
+  return { valid: true }
+}
+
+/** 将 Input 局部 props 转为规则列表，便于与 Form rules 合并 */
+export function buildLocalInputRules(options: {
+  required?: boolean
+  rule?: RsInputRule
+  validator?: (value: string) => boolean | string
+  requiredMessage?: string
+}): RsFormRuleItem[] {
+  const list: RsFormRuleItem[] = []
+  if (options.required) {
+    list.push({ required: true, message: options.requiredMessage })
+  }
+  if (options.rule) {
+    list.push({ type: options.rule })
+  }
+  if (options.validator) {
+    list.push({
+      validator: (value) => options.validator!(String(value ?? '')),
+    })
+  }
+  return list
+}

package/src/components/form-utils.ts

@@ -7,7 +7,25 @@ import {
   type ComputedRef,
   type InjectionKey,
   type Ref,
+  type VNodeChild,
 } from 'vue'
+import type { RsFormRuleItem, RsFormRuleTrigger, RsFormRules } from './form-rules'
+import { normalizeFormRules } from './form-rules'
+
+/** 自定义错误渲染上下文（Form / 字段共用） */
+export interface RsFormErrorRenderContext {
+  name?: string
+  message: string
+  value: unknown
+}
+
+/**
+ * 自定义错误渲染（对齐 Ant Design Form.Item help / Element #error）。
+ * 返回 VNode / 字符串；返回 null/undefined 时回退默认文案。
+ */
+export type RsFormErrorRender = (
+  ctx: RsFormErrorRenderContext,
+) => VNodeChild | null | undefined
 
 export type RsFormLabelPosition = 'top' | 'left'
 export type RsFormLabelAlign = 'start' | 'end'
@@ -15,15 +33,30 @@ export type RsFormSize = 'ssm' | 'sm' | 'md' | 'lg'
 export type RsFormGap = 'sm' | 'md' | 'lg'
 export type RsFormMaxWidth = 'sm' | 'md' | 'lg' | 'full' | 'none'
 
+/** 整表校验结果（含按字段名聚合的错误） */
 export interface RsFormValidationResult {
   valid: boolean
+  /** 字段名 → 首条错误文案；无 name 的字段不计入 */
+  errors: Record<string, string>
+}
+
+export interface RsFormFieldValidationResult {
+  valid: boolean
+  message?: string
+  name?: string
 }
 
 export interface RsFormFieldExpose {
+  /** 字段名，用于匹配 Form.rules */
+  name?: string
   getValue: () => unknown
   setValue: (value: unknown) => void
-  validate?: () => RsFormValidationResult | Promise<RsFormValidationResult>
+  validate?: (
+    trigger?: RsFormRuleTrigger,
+  ) => RsFormFieldValidationResult | Promise<RsFormFieldValidationResult>
   clearValidation?: () => void
+  /** 由 Form 或外部写入错误态 */
+  setError?: (message: string) => void
 }
 
 export interface RsFormContext {
@@ -32,6 +65,11 @@ export interface RsFormContext {
   labelWidth: Readonly<Ref<string>>
   labelAlign: Readonly<Ref<RsFormLabelAlign>>
   size: Readonly<Ref<RsFormSize>>
+  /** 当前 Form 上的 rules（响应式读取） */
+  rules: Readonly<Ref<RsFormRules | undefined>>
+  getFieldRules: (name?: string) => RsFormRuleItem[]
+  /** Form 级自定义错误渲染；字段无 #error 时使用 */
+  renderError?: RsFormErrorRender
   registerField: (id: symbol, field: RsFormFieldExpose) => void
   unregisterField: (id: symbol) => void
 }
@@ -72,6 +110,18 @@ export function useRsFormField(getExpose: () => RsFormFieldExpose | undefined):
   })
 }
 
-export function resolveRsFormSize(size?: RsFormSize, form?: RsFormContext | null): ComputedRef<RsFormSize> {
+export function resolveRsFormSize(
+  size?: RsFormSize,
+  form?: RsFormContext | null,
+): ComputedRef<RsFormSize> {
   return computed(() => size ?? form?.size.value ?? 'md')
 }
+
+/** 供 Form 内部解析某字段 rules */
+export function resolveFieldRules(
+  rules: RsFormRules | undefined,
+  name?: string,
+): RsFormRuleItem[] {
+  if (!name || !rules) return []
+  return normalizeFormRules(rules[name])
+}

package/src/components/menu-utils.ts

@@ -46,3 +46,14 @@ export function findMenuParentKeys(items: RsMenuItems, key: string): string[] {
 
   return []
 }
+
+/** 判断菜单项自身或其任意后代是否匹配 key（用于父级高亮） */
+export function menuItemContainsKey(item: RsMenuItem, key: string): boolean {
+  if (item.key === key) {
+    return true
+  }
+  if (!item.children?.length) {
+    return false
+  }
+  return item.children.some((child) => menuItemContainsKey(child, key))
+}

package/src/components/overlay-utils.ts

@@ -12,6 +12,9 @@ export const RS_Z_PANEL = 'var(--rs-z-panel)'
 /** 模态对话框 */
 export const RS_Z_MODAL = 'var(--rs-z-modal)'
 
+/** 顶栏加载进度条（低于 toast，避免遮挡通知） */
+export const RS_Z_LOADING_BAR = 'var(--rs-z-loading-bar)'
+
 /** 全局 Toast */
 export const RS_Z_TOAST = 'var(--rs-z-toast)'
 

package/src/components/radio-utils.ts

@@ -0,0 +1,12 @@
+import type { InjectionKey, Ref } from 'vue'
+import type { RsComponentSize } from '../theme/types'
+
+/** 单选值类型 */
+export type RsRadioValue = string | number | boolean
+
+/** RadioGroup 向下注入的上下文 */
+export type RsRadioGroupContext = {
+  size: Ref<RsComponentSize>
+}
+
+export const RS_RADIO_GROUP_KEY: InjectionKey<RsRadioGroupContext> = Symbol('rs-radio-group')

package/src/components/reka.ts

@@ -58,6 +58,11 @@ export {
   PopoverPortal,
   PopoverRoot,
   PopoverTrigger,
+  RadioGroupIndicator,
+  RadioGroupItem,
+  RadioGroupRoot,
+  SwitchRoot,
+  SwitchThumb,
   PaginationEllipsis,
   PaginationFirst,
   PaginationLast,

package/src/components/select-utils.ts

@@ -11,6 +11,22 @@ export interface RsSelectOptionGroup {
 
 export type RsSelectOptions = ReadonlyArray<RsSelectOption | RsSelectOptionGroup>
 
+/**
+ * Reka ComboboxItem 禁止 value 为空串（空串表示未选中 / placeholder）。
+ * 选项若传入 value: ''，对内映射为此哨兵，避免崩溃；对外读写仍为 ''。
+ */
+export const RS_SELECT_EMPTY_VALUE = '__rs_select_empty__'
+
+/** 业务 value → ComboboxItem value（仅处理空串） */
+export function toComboboxValue(value: string): string {
+  return value === '' ? RS_SELECT_EMPTY_VALUE : value
+}
+
+/** ComboboxItem value → 业务 value（仅处理空串哨兵） */
+export function fromComboboxValue(value: string): string {
+  return value === RS_SELECT_EMPTY_VALUE ? '' : value
+}
+
 export function isSelectOptionGroup(
   item: RsSelectOption | RsSelectOptionGroup,
 ): item is RsSelectOptionGroup {
@@ -33,6 +49,7 @@ export function buildOptionLabelMap(options: RsSelectOptions): Map<string, strin
   const map = new Map<string, string>()
   for (const opt of flattenSelectOptions(options)) {
     map.set(opt.value, opt.label)
+    if (opt.value === '') map.set(RS_SELECT_EMPTY_VALUE, opt.label)
   }
   return map
 }
@@ -40,7 +57,9 @@ export function buildOptionLabelMap(options: RsSelectOptions): Map<string, strin
 export function buildOptionDisabledMap(options: RsSelectOptions): Map<string, boolean> {
   const map = new Map<string, boolean>()
   for (const opt of flattenSelectOptions(options)) {
-    map.set(opt.value, Boolean(opt.disabled))
+    const disabled = Boolean(opt.disabled)
+    map.set(opt.value, disabled)
+    if (opt.value === '') map.set(RS_SELECT_EMPTY_VALUE, disabled)
   }
   return map
 }
@@ -68,5 +87,5 @@ export function filterSelectOptions(
 }
 
 export function flattenSelectValues(options: RsSelectOptions): string[] {
-  return flattenSelectOptions(options).map((opt) => opt.value)
+  return flattenSelectOptions(options).map((opt) => toComboboxValue(opt.value))
 }

package/src/components/split-pane-utils.ts

@@ -1,15 +1,23 @@
 /** 面板分割方向：horizontal 左右排布（拖动横向）· vertical 上下排布（拖动纵向） */
 export type RsSplitOrientation = 'horizontal' | 'vertical'
 
-/** 单个面板定义；尺寸单位统一为「占比百分比」(0~100) */
+/** 面板尺寸：数字为占比百分比；'auto' 按内容自适应（不占百分比配额） */
+export type RsSplitPaneSize = number | 'auto'
+
+/** 单个面板定义；百分比尺寸单位为 0~100 */
 export interface RsSplitPaneItem {
   /** 唯一标识，用于插槽名与 v-model:sizes 的顺序映射 */
   key: string
-  /** 初始尺寸（百分比）；缺省时在剩余空间内均分 */
-  size?: number
-  /** 最小尺寸（百分比），默认 0 */
+  /**
+   * 初始尺寸
+   * - number：占比百分比
+   * - 'auto'：按内容自适应（flex-basis: auto）
+   * - 缺省：在「非 auto」面板的剩余百分比内均分
+   */
+  size?: RsSplitPaneSize
+  /** 最小尺寸（百分比），默认 0；auto 面板可作为 min-height/min-width % */
   min?: number
-  /** 最大尺寸（百分比），默认 100 */
+  /** 最大尺寸（百分比），默认 100；auto 面板可作为 max-height/max-width % */
   max?: number
   /** 是否可折叠：拖动越过阈值时吸附到 collapsedSize */
   collapsible?: boolean
@@ -36,6 +44,16 @@ export function roundSize(value: number, precision = 4): number {
   return Math.round(value * factor) / factor
 }
 
+/** 是否为内容自适应尺寸 */
+export function isRsSplitPaneAutoSize(size: RsSplitPaneSize | undefined): size is 'auto' {
+  return size === 'auto'
+}
+
+/** 各面板是否声明为 auto（忽略受控 provided 时的瞬时物化） */
+export function resolveSplitAutoFlags(panes: RsSplitPaneItem[]): boolean[] {
+  return panes.map((pane) => isRsSplitPaneAutoSize(pane.size))
+}
+
 /** 将面板定义解析为规范化约束，保证 0 ≤ min ≤ max ≤ 100 且 collapsedSize ≤ min */
 export function resolveSplitConstraints(panes: RsSplitPaneItem[]): RsSplitConstraint[] {
   return panes.map((pane) => {
@@ -65,8 +83,8 @@ function rescaleTo100(sizes: number[]): number[] {
 }
 
 /**
- * 计算初始尺寸数组（总和 100）。
- * 优先使用 provided（受控值），其次面板自身的 size，未指定的项在剩余空间内均分。
+ * 计算初始尺寸数组（非 auto 面板总和 100；auto 位为 0 占位，样式层不使用 flex-grow）。
+ * 优先使用 provided（受控值），其次面板自身的 number size，未指定的非 auto 项在剩余空间内均分。
  */
 export function normalizeSplitSizes(
   panes: RsSplitPaneItem[],
@@ -75,18 +93,53 @@ export function normalizeSplitSizes(
   const count = panes.length
   if (count === 0) return []
 
+  const autoFlags = resolveSplitAutoFlags(panes)
+  // 受控 sizes 一旦提供完整数组，视为已全部物化为百分比（含原 auto）
+  const fullyControlled =
+    Array.isArray(provided) &&
+    provided.length === count &&
+    provided.every((value) => typeof value === 'number' && Number.isFinite(value))
+
+  if (fullyControlled) {
+    return rescaleTo100(provided!.map((value) => Math.max(0, value))).map((value) =>
+      roundSize(value),
+    )
+  }
+
   const seed: (number | null)[] = panes.map((pane, index) => {
-    const candidate = provided?.[index] ?? pane.size
+    if (autoFlags[index]) return 0
+    const candidate = provided?.[index] ?? (typeof pane.size === 'number' ? pane.size : null)
     return typeof candidate === 'number' && Number.isFinite(candidate)
       ? Math.max(0, candidate)
       : null
   })
 
-  const missing = seed.filter((value) => value === null).length
-  const knownSum = seed.reduce<number>((acc, value) => acc + (value ?? 0), 0)
+  const flexibleIndices = panes
+    .map((_, index) => index)
+    .filter((index) => !autoFlags[index])
+
+  if (flexibleIndices.length === 0) {
+    // 全部 auto：占位全 0，由内容撑开
+    return panes.map(() => 0)
+  }
+
+  const missing = flexibleIndices.filter((index) => seed[index] === null).length
+  const knownSum = flexibleIndices.reduce<number>((acc, index) => acc + (seed[index] ?? 0), 0)
   const each = missing > 0 ? Math.max(0, 100 - knownSum) / missing : 0
-  const filled = seed.map((value) => value ?? each)
-  return rescaleTo100(filled).map((value) => roundSize(value))
+
+  const filled = seed.map((value, index) => {
+    if (autoFlags[index]) return 0
+    return value ?? each
+  })
+
+  // 只对非 auto 部分缩放到 100
+  const flexibleValues = flexibleIndices.map((index) => filled[index] ?? 0)
+  const scaledFlexible = rescaleTo100(flexibleValues)
+  const next = filled.slice()
+  flexibleIndices.forEach((paneIndex, i) => {
+    next[paneIndex] = roundSize(scaledFlexible[i] ?? 0)
+  })
+  return next
 }
 
 /** 判断某面板当前是否处于折叠态 */