niuma-ui 1.0.0

package/src/__tests__/tree-utils.spec.ts

@@ -0,0 +1,234 @@
+import { describe, expect, it } from 'vitest'
+import {
+  buildTreeNodeIndex,
+  collectHalfCheckedKeys,
+  filterTreeNodes,
+  flattenVisibleTreeNodes,
+  isTreeAncestorKey,
+  resolveAccordionExpandedKeys,
+  resolveTreeIndent,
+  resolveTreeRowHeight,
+  resolveTreeCheckState,
+  resolveTreeFieldNames,
+  resolveTreeFocusKey,
+  resolveTreeVirtualEnabled,
+  shouldShowTreeCheckbox,
+  sliceVirtualTreeNodes,
+  splitTreeLabelHighlight,
+  toggleTreeCheck,
+  type RsTreeNode,
+} from '../components/tree-utils'
+import { RS_COMPONENT_SIZES } from '../theme/types'
+
+const nodes = [
+  {
+    key: 'root',
+    label: '根',
+    children: [
+      { key: 'child-a', label: '子节点 A' },
+      { key: 'child-b', label: '子节点 B' },
+    ],
+  },
+]
+
+describe('tree-utils', () => {
+  it('filters nodes by keyword and keeps ancestors', () => {
+    const filtered = filterTreeNodes(nodes, 'b')
+    expect(filtered).toHaveLength(1)
+    expect(filtered[0]?.children).toHaveLength(1)
+    expect(filtered[0]?.children?.[0]?.key).toBe('child-b')
+  })
+
+  it('filters with custom filterNode', () => {
+    const apiNodes = [{ id: '1', name: 'Alpha' }, { id: '2', name: 'Beta' }]
+    const filtered = filterTreeNodes(apiNodes, 'bet', {
+      fieldNames: { key: 'id', label: 'name' },
+      filterNode: (node, keyword) => String(node.name).toLowerCase().includes(keyword.toLowerCase()),
+    })
+    expect(filtered).toHaveLength(1)
+    expect(filtered[0]?.id).toBe('2')
+  })
+
+  it('flattens visible nodes based on expanded keys', () => {
+    const expanded = new Set(['root'])
+    const flat = flattenVisibleTreeNodes(nodes, expanded)
+    expect(flat.map((item) => item.key)).toEqual(['root', 'child-a', 'child-b'])
+  })
+
+  it('tracks ancestor levelLines for continuous showLine guides', () => {
+    const tree: RsTreeNode[] = [
+      {
+        key: 'a',
+        label: 'A',
+        children: [
+          { key: 'a1', label: 'A1' },
+          {
+            key: 'a2',
+            label: 'A2',
+            children: [{ key: 'a2x', label: 'A2X' }],
+          },
+        ],
+      },
+      { key: 'b', label: 'B' },
+    ]
+    const flat = flattenVisibleTreeNodes(tree, new Set(['a', 'a2']))
+    const a2x = flat.find((item) => item.key === 'a2x')
+    // a 不是末项 → 子树行需保留 depth0 贯穿线；a2 是 a 下末项 → depth1 应断开
+    expect(a2x?.levelLines).toEqual([true, false])
+    expect(a2x?.isLast).toBe(true)
+    const a1 = flat.find((item) => item.key === 'a1')
+    expect(a1?.levelLines).toEqual([true])
+    expect(a1?.isLast).toBe(false)
+  })
+
+  it('toggles parent-child checks', () => {
+    const index = buildTreeNodeIndex(nodes)
+    const next = toggleTreeCheck('root', new Set(), index, false)
+    expect(next).toEqual(expect.arrayContaining(['root', 'child-a', 'child-b']))
+    expect(resolveTreeCheckState('root', new Set(next), index, false)).toBe('checked')
+  })
+
+  it('collects half checked keys', () => {
+    const index = buildTreeNodeIndex(nodes)
+    const half = collectHalfCheckedKeys(index, new Set(['child-a']), false)
+    expect(half).toEqual(['root'])
+  })
+
+  it('resolves accordion expanded keys', () => {
+    const index = buildTreeNodeIndex(nodes)
+    const next = resolveAccordionExpandedKeys('child-b', ['root', 'child-a'], index, ['root'])
+    expect(next).toEqual(expect.arrayContaining(['root', 'child-b']))
+    expect(next).not.toContain('child-a')
+  })
+
+  it('supports strict checking', () => {
+    const index = buildTreeNodeIndex(nodes)
+    const next = toggleTreeCheck('child-a', new Set(), index, true)
+    expect(next).toEqual(['child-a'])
+    expect(resolveTreeCheckState('root', new Set(next), index, true)).toBe('unchecked')
+  })
+
+  it('enables virtual scroll by threshold', () => {
+    expect(resolveTreeVirtualEnabled({ flatCount: 50 })).toBe(false)
+    expect(resolveTreeVirtualEnabled({ flatCount: 150 })).toBe(true)
+    expect(resolveTreeVirtualEnabled({ virtual: true, flatCount: 10 })).toBe(true)
+  })
+
+  it('slices virtual tree nodes', () => {
+    const flat = Array.from({ length: 200 }, (_, index) => ({
+      key: String(index),
+      node: { key: String(index), label: `N${index}` },
+      depth: 0,
+      hasChildren: false,
+      isLast: index === 199,
+      parentKey: null,
+      levelLines: [] as boolean[],
+    }))
+    const slice = sliceVirtualTreeNodes(flat, 320, 200, 32, 2)
+    expect(slice.nodes.length).toBeLessThan(flat.length)
+    expect(slice.paddingTop).toBeGreaterThan(0)
+  })
+
+  it('clamps virtual slice when scrollTop exceeds filtered content', () => {
+    const flat = Array.from({ length: 5 }, (_, index) => ({
+      key: String(index),
+      node: { key: String(index), label: `N${index}` },
+      depth: 0,
+      hasChildren: false,
+      isLast: index === 4,
+      parentKey: null,
+      levelLines: [] as boolean[],
+    }))
+    const slice = sliceVirtualTreeNodes(flat, 50_000, 200, 32, 2)
+    expect(slice.nodes.length).toBeGreaterThan(0)
+    expect(slice.nodes.length).toBeLessThanOrEqual(flat.length)
+    expect(slice.paddingTop).toBeLessThan(flat.length * 32)
+  })
+
+  it('reports the slice start index so rows can be positioned in O(1)', () => {
+    const flat = Array.from({ length: 500 }, (_, index) => ({
+      key: String(index),
+      node: { key: String(index), label: `N${index}` },
+      depth: 0,
+      hasChildren: false,
+      isLast: index === 499,
+      parentKey: null,
+      levelLines: [] as boolean[],
+    }))
+    const slice = sliceVirtualTreeNodes(flat, 3200, 200, 32, 2)
+    expect(slice.startIndex).toBe(98)
+    expect(slice.nodes[0]?.key).toBe(String(slice.startIndex))
+    expect(slice.paddingTop).toBe(slice.startIndex * 32)
+  })
+
+  it('flattens a huge sibling group without blowing the call stack', () => {
+    // 旧实现用 push(...子结果)，单层可见节点过多时实参超限会抛 RangeError
+    const wide: RsTreeNode = {
+      key: 'wide',
+      label: '宽节点',
+      children: Array.from({ length: 200_000 }, (_, index) => ({
+        key: `w-${index}`,
+        label: `W${index}`,
+      })),
+    }
+    const flat = flattenVisibleTreeNodes([wide], new Set(['wide']))
+    expect(flat).toHaveLength(200_001)
+    expect(flat[200_000]?.key).toBe('w-199999')
+  })
+
+  it('detects ancestry by walking up parents', () => {
+    const index = buildTreeNodeIndex(nodes)
+    expect(isTreeAncestorKey('root', 'child-a', index)).toBe(true)
+    expect(isTreeAncestorKey('child-a', 'root', index)).toBe(false)
+    expect(isTreeAncestorKey('child-a', 'child-b', index)).toBe(false)
+    expect(isTreeAncestorKey('root', 'root', index)).toBe(false)
+  })
+
+  it('short-circuits check state when nothing is checked', () => {
+    const index = buildTreeNodeIndex(nodes)
+    expect(resolveTreeCheckState('root', new Set(), index, false)).toBe('unchecked')
+    expect(collectHalfCheckedKeys(index, new Set(), false)).toEqual([])
+  })
+
+  it('highlights label segments', () => {
+    const parts = splitTreeLabelHighlight('RsTree 组件', 'tree')
+    expect(parts.find((part) => part.highlight)?.text).toBe('Tree')
+  })
+
+  it('resolves a finite row height and indent for every size', () => {
+    // 漏掉任一档会返回 undefined，进而让虚拟滚动的 padding 变成 NaN
+    for (const size of RS_COMPONENT_SIZES) {
+      expect(Number.isFinite(resolveTreeRowHeight(size))).toBe(true)
+      expect(Number.isFinite(resolveTreeIndent(size))).toBe(true)
+    }
+    expect(resolveTreeRowHeight('ssm')).toBeLessThan(resolveTreeRowHeight('sm'))
+    expect(resolveTreeIndent('ssm')).toBeLessThan(resolveTreeIndent('sm'))
+    expect(resolveTreeRowHeight('md', 21)).toBe(21)
+  })
+
+  it('maps field names', () => {
+    const fields = resolveTreeFieldNames({ key: 'id', label: 'title', children: 'items' })
+    expect(fields.key).toBe('id')
+    expect(fields.children).toBe('items')
+  })
+
+  it('moves focus within flat nodes', () => {
+    const flat = flattenVisibleTreeNodes(nodes, new Set(['root']))
+    const index = buildTreeNodeIndex(nodes)
+    expect(resolveTreeFocusKey(flat, 'child-a', 'next', index)).toBe('child-b')
+    expect(resolveTreeFocusKey(flat, 'child-b', 'parent', index)).toBe('root')
+  })
+
+  it('supports onlyCheckLeaf mode', () => {
+    const index = buildTreeNodeIndex(nodes)
+    const root = nodes[0]!
+    expect(shouldShowTreeCheckbox(root)).toBe(true)
+    expect(shouldShowTreeCheckbox(root, undefined, { onlyCheckLeaf: true })).toBe(false)
+    const next = toggleTreeCheck('child-a', new Set(), index, false, true)
+    expect(next).toEqual(['child-a'])
+    expect(resolveTreeCheckState('root', new Set(next), index, false, true)).toBe('indeterminate')
+    const both = toggleTreeCheck('child-b', new Set(next), index, false, true)
+    expect(resolveTreeCheckState('root', new Set(both), index, false, true)).toBe('checked')
+    expect(collectHalfCheckedKeys(index, new Set(next), false, true)).toEqual(['root'])
+  })
+})

package/src/__tests__/useTableCellTooltip.spec.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it, vi, afterEach, beforeEach } from 'vitest'
+import { flushPromises, mount } from '@vue/test-utils'
+import { defineComponent, ref } from 'vue'
+import { useTableCellTooltip } from '../composables/useTableCellTooltip'
+
+const Host = defineComponent({
+  props: {
+    delay: { type: Number, default: 0 },
+  },
+  setup(props) {
+    const tipRef = ref<HTMLElement | null>(null)
+    const { state, onPointerOver, onPointerOut, hide } = useTableCellTooltip({
+      enabled: () => true,
+      delay: () => props.delay,
+      tipRef,
+    })
+    return { state, onPointerOver, onPointerOut, hide, tipRef }
+  },
+  template: `
+    <div @pointerover="onPointerOver" @pointerout="onPointerOut">
+      <span
+        class="rs-table__cell-tip rs-table__ellipsis-text"
+        data-rs-table-tip-mode="overflow"
+        data-rs-table-tip-text="完整文本"
+      >截断</span>
+      <div
+        v-if="state.visible"
+        ref="tipRef"
+        class="rs-table__shared-tip"
+        :style="state.style"
+      >{{ state.text }}</div>
+    </div>
+  `,
+})
+
+describe('useTableCellTooltip', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('shows tooltip only when ellipsis content overflows', async () => {
+    const wrapper = mount(Host, { attachTo: document.body })
+    const cell = wrapper.find('.rs-table__cell-tip').element as HTMLElement
+    Object.defineProperty(cell, 'scrollWidth', { value: 200, configurable: true })
+    Object.defineProperty(cell, 'clientWidth', { value: 80, configurable: true })
+
+    await wrapper.find('.rs-table__cell-tip').trigger('pointerover', { pointerType: 'mouse' })
+    await vi.runAllTimersAsync()
+    await flushPromises()
+
+    expect(wrapper.find('.rs-table__shared-tip').text()).toBe('完整文本')
+    wrapper.unmount()
+  })
+
+  it('hides tooltip when content does not overflow', async () => {
+    const wrapper = mount(Host, { attachTo: document.body })
+    await wrapper.find('.rs-table__cell-tip').trigger('pointerover', { pointerType: 'mouse' })
+    await vi.runAllTimersAsync()
+    await flushPromises()
+    expect(wrapper.find('.rs-table__shared-tip').exists()).toBe(false)
+    wrapper.unmount()
+  })
+
+  it('shows header tooltip via shared layer', async () => {
+    const HeaderHost = defineComponent({
+      setup() {
+        const tipRef = ref<HTMLElement | null>(null)
+        const { state, onPointerOver, onPointerOut } = useTableCellTooltip({
+          enabled: () => false,
+          headerEnabled: () => true,
+          delay: () => 0,
+          tipRef,
+        })
+        return { state, onPointerOver, onPointerOut, tipRef }
+      },
+      template: `
+        <div @pointerover="onPointerOver" @pointerout="onPointerOut">
+          <span class="rs-table__th-label" data-rs-table-header-tip="字段: id&#10;类型: int">id</span>
+          <div
+            v-if="state.visible"
+            ref="tipRef"
+            class="rs-table__shared-tip"
+            :class="{ 'rs-table__shared-tip--header': state.kind === 'header' }"
+            :style="state.style"
+          >{{ state.text }}</div>
+        </div>
+      `,
+    })
+    const wrapper = mount(HeaderHost, { attachTo: document.body })
+    await wrapper.find('.rs-table__th-label').trigger('pointerover', { pointerType: 'mouse' })
+    await vi.runAllTimersAsync()
+    await flushPromises()
+    expect(wrapper.find('.rs-table__shared-tip--header').exists()).toBe(true)
+    expect(wrapper.find('.rs-table__shared-tip').text()).toContain('字段: id')
+    wrapper.unmount()
+  })
+})

package/src/components/RsAvatar.vue

@@ -0,0 +1,115 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { AvatarFallback, AvatarImage, AvatarRoot } from './reka'
+import { getAvatarInitials, type RsAvatarShape, type RsAvatarSize, type RsAvatarTone } from './avatar-utils'
+import RsIcon from './RsIcon.vue'
+
+const props = withDefaults(
+  defineProps<{
+    src?: string
+    alt?: string
+    name?: string
+    fallback?: string
+    icon?: string
+    size?: RsAvatarSize
+    shape?: RsAvatarShape
+    tone?: RsAvatarTone
+    label?: string
+  }>(),
+  {
+    size: 'md',
+    shape: 'circle',
+    tone: 'primary',
+    icon: 'user',
+  },
+)
+
+const fallbackText = computed(() => {
+  if (props.fallback?.trim()) return props.fallback.trim()
+  if (props.name?.trim()) return getAvatarInitials(props.name)
+  return ''
+})
+
+const showIconFallback = computed(() => !fallbackText.value)
+const imageAlt = computed(() => props.alt ?? props.name ?? '')
+const ariaLabel = computed(() => props.label ?? props.alt ?? props.name ?? undefined)
+</script>
+
+<template>
+  <AvatarRoot
+    class="rs-avatar"
+    :class="[`rs-avatar--${size}`, `rs-avatar--${shape}`]"
+    :aria-label="ariaLabel"
+    :role="ariaLabel ? 'img' : undefined"
+  >
+    <AvatarImage v-if="src" :src="src" :alt="imageAlt" class="rs-avatar__image" />
+    <AvatarFallback class="rs-avatar__fallback" :class="`rs-avatar__fallback--${tone}`">
+      <slot name="fallback">
+        <RsIcon v-if="showIconFallback" :name="icon" :size="size === 'sm' ? 14 : size === 'lg' ? 20 : 16" />
+        <span v-else>{{ fallbackText }}</span>
+      </slot>
+    </AvatarFallback>
+  </AvatarRoot>
+</template>
+
+<style>
+.rs-avatar {
+  display: inline-flex;
+  overflow: hidden;
+  flex-shrink: 0;
+  border: 1px solid var(--rs-border);
+  background: var(--rs-surface);
+}
+.rs-avatar--circle {
+  border-radius: var(--rs-radius-full);
+}
+.rs-avatar--square {
+  border-radius: var(--rs-radius-sm);
+}
+.rs-avatar--sm {
+  width: 1.75rem;
+  height: 1.75rem;
+}
+.rs-avatar--md {
+  width: 2.25rem;
+  height: 2.25rem;
+}
+.rs-avatar--lg {
+  width: 3rem;
+  height: 3rem;
+}
+.rs-avatar__image {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+.rs-avatar__fallback {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  font-size: var(--rs-font-size-xs);
+  font-weight: 600;
+}
+.rs-avatar__fallback--default {
+  background: var(--rs-surface-hover);
+  color: var(--rs-muted);
+}
+.rs-avatar__fallback--primary {
+  background: var(--rs-primary-container);
+  color: var(--rs-on-primary-container);
+}
+.rs-avatar__fallback--success {
+  background: var(--rs-success-container);
+  color: var(--rs-on-success-container);
+}
+.rs-avatar__fallback--warning {
+  background: var(--rs-warning-container);
+  color: var(--rs-on-warning-container);
+}
+.rs-avatar__fallback--danger {
+  background: var(--rs-danger-container);
+  color: var(--rs-on-danger-container);
+}
+</style>

package/src/components/RsBadge.vue

@@ -0,0 +1,59 @@
+<script setup lang="ts">
+withDefaults(
+  defineProps<{
+    variant?: 'default' | 'primary' | 'success' | 'warning' | 'danger' | 'info'
+  }>(),
+  {
+    variant: 'default',
+  },
+)
+</script>
+
+<template>
+  <span class="rs-badge" :class="`rs-badge--${variant}`">
+    <slot />
+  </span>
+</template>
+
+<style scoped>
+.rs-badge {
+  display: inline-flex;
+  align-items: center;
+  padding: 0.125rem 0.625rem;
+  border-radius: var(--rs-radius-full);
+  font-size: var(--rs-font-size-xs);
+  font-weight: 500;
+  line-height: var(--rs-line-height-tight);
+  letter-spacing: 0.02em;
+}
+.rs-badge--default {
+  background: var(--rs-surface-hover);
+  color: var(--rs-text);
+  border: 1px solid var(--rs-border);
+}
+.rs-badge--primary {
+  background: var(--rs-primary-container);
+  color: var(--rs-on-primary-container);
+  border: 1px solid color-mix(in srgb, var(--rs-primary) 40%, transparent);
+}
+.rs-badge--success {
+  background: var(--rs-success-container);
+  color: var(--rs-on-success-container);
+  border: 1px solid color-mix(in srgb, var(--rs-success) 40%, transparent);
+}
+.rs-badge--warning {
+  background: var(--rs-warning-container);
+  color: var(--rs-on-warning-container);
+  border: 1px solid color-mix(in srgb, var(--rs-warning) 40%, transparent);
+}
+.rs-badge--danger {
+  background: var(--rs-danger-container);
+  color: var(--rs-on-danger-container);
+  border: 1px solid color-mix(in srgb, var(--rs-danger) 40%, transparent);
+}
+.rs-badge--info {
+  background: var(--rs-info-container);
+  color: var(--rs-on-info-container);
+  border: 1px solid color-mix(in srgb, var(--rs-info) 40%, transparent);
+}
+</style>

package/src/components/RsBreadcrumb.vue

@@ -0,0 +1,65 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useRsI18n } from '../composables/useRsI18n'
+import { buildBreadcrumbRenderItems } from './breadcrumb-utils'
+import RsBreadcrumbItems from './RsBreadcrumbItems.vue'
+
+const { t } = useRsI18n()
+
+export interface RsBreadcrumbItem {
+  label: string
+  to?: string
+  href?: string
+}
+
+const props = defineProps<{
+  items: RsBreadcrumbItem[]
+}>()
+
+const renderItems = computed(() => buildBreadcrumbRenderItems(props.items))
+</script>
+
+<template>
+  <nav class="rs-breadcrumb" :aria-label="t('breadcrumb.label')">
+    <RsBreadcrumbItems :items="renderItems" :separator-label="t('breadcrumb.separator')" />
+  </nav>
+</template>
+
+<style>
+.rs-breadcrumb__list {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.25rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+.rs-breadcrumb__item {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+}
+.rs-breadcrumb__link {
+  font-size: var(--rs-font-size-sm);
+  color: var(--rs-muted);
+  text-decoration: none;
+  padding: 0.125rem 0.25rem;
+  border-radius: var(--rs-radius-xs);
+  transition:
+    color var(--rs-transition-fast),
+    background var(--rs-transition-fast);
+}
+.rs-breadcrumb__link:hover:not(.rs-breadcrumb__link--current) {
+  color: var(--rs-primary);
+  background: var(--rs-surface-hover);
+}
+.rs-breadcrumb__link--current {
+  color: var(--rs-text);
+  font-weight: 500;
+  pointer-events: none;
+}
+.rs-breadcrumb__sep {
+  color: var(--rs-muted);
+}
+</style>

package/src/components/RsBreadcrumbItems.vue

@@ -0,0 +1,36 @@
+<script setup lang="ts">
+import type { RsBreadcrumbRenderItem } from './breadcrumb-utils'
+import RsIcon from './RsIcon.vue'
+
+defineProps<{
+  items: RsBreadcrumbRenderItem[]
+  separatorLabel: string
+}>()
+</script>
+
+<template>
+  <ol class="rs-breadcrumb__list">
+    <li
+      v-for="(item, index) in items"
+      :key="item.key"
+      class="rs-breadcrumb__item"
+    >
+      <component
+        :is="item.isLink ? 'a' : 'span'"
+        :href="item.href"
+        class="rs-breadcrumb__link"
+        :class="{ 'rs-breadcrumb__link--current': item.isCurrent }"
+        :aria-current="item.isCurrent ? 'page' : undefined"
+      >
+        {{ item.label }}
+      </component>
+      <RsIcon
+        v-if="index < items.length - 1"
+        name="chevron-right"
+        :size="14"
+        class="rs-breadcrumb__sep"
+        :label="separatorLabel"
+      />
+    </li>
+  </ol>
+</template>