weifuwu 0.94.1 → 0.95.0

package/dist/level5/client/components/VirtualTable/VirtualTable.ts

@@ -0,0 +1,239 @@
+/** VirtualTable：虚拟表格：10k 行固定表头 + 可见窗口渲染 + 排序（showcase /components/virtualtable） */
+/**
+ * weifuwu/client/components — VirtualTable
+ *
+ * 虚拟表格（数据密集场景）：固定表头 + 虚拟滚动表体，10k+ 行只渲染可见窗口。
+ * 复用 VirtualList 滚动基座（useScrollPosition 像素级 scrollTop + rAF 节流）。
+ * 排序：受控 sortKey/sortOrder + onSort（与 Table 同款模式）。
+ * 行选择：rowSelection（受控 selectedRowKeys + onChange，复选框列）。
+ * 裁剪（CS-05，见 docs/client.md）：列虚拟化（横向）、行编辑、单元格合并、树形表格。
+ */
+
+import type { Component } from '../../../../level6/client/vdom/index.ts'
+import type { UIContext } from '../../../../level6/client/vdom/index.ts'
+import { h, createItem } from '../../../../level6/client/vdom/index.ts'
+import { Icon } from '../Icon/Icon.ts'
+import type { TableColumn } from '../Table/Table.ts'
+
+export interface VirtualTableProps {
+  columns: TableColumn[]
+  data?: any[]
+  /** 视口高度（px），默认 400 */
+  height?: number
+  /** 行高（px），默认 40 */
+  rowHeight?: number
+  /** 可见区外额外渲染行数 */
+  overscan?: number
+  /** 当前排序列 key */
+  sortKey?: string
+  /** 当前排序方向 */
+  sortOrder?: 'asc' | 'desc'
+  /** 排序变化回调 */
+  onSort?: (key: string, order: 'asc' | 'desc')=> void
+  /** 数据为空时显示的文本 */
+  emptyText?: string
+  /** 行点击 */
+  onRowClick?: (row: any, index: number)=> void
+  /** 行选择配置（受控） */
+  rowSelection?: {
+    selectedRowKeys: (string | number)[]
+    onChange?: (selectedRowKeys: (string | number)[], selectedRows: any[]) => void
+    /** 行 key 字段名，默认 'id'；无该字段回退到索引 */
+    rowKey?: string
+  }
+  className?: string
+}
+
+function sortData(data: any[], columns: TableColumn[], sortKey?: string, sortOrder?: string): any[] {
+  if (!sortKey || !sortOrder) return data
+  const col = columns.find(c => c.key === sortKey)
+  if (!col || !col.sortable) return data
+  const sorted = [...data]
+  sorted.sort((a, b)=> {
+    const va = a[sortKey]
+    const vb = b[sortKey]
+    const result = col.sorter ? col.sorter(va, vb) : String(va ?? '').localeCompare(String(vb ?? ''))
+    return sortOrder === 'desc' ? -result : result
+  })
+  return sorted
+}
+
+export const VirtualTable: Component<VirtualTableProps> = (_init, ctx)=> {
+  // 表头三态复选框（值域槽 enum——checked/indeterminate/aria-checked 三面捆绑单源：
+  // off = 全不选 · checked = 全选 · half = 部分选（mixed aria + indeterminate 半边））
+  const headTriCheck = createItem({
+    cls: 'wf-table-checkbox',
+    enum: {
+      key: 'aria-checked',
+      off: { props: { checked: false, indeterminate: false } },
+      values: {
+        checked: { props: { checked: true, indeterminate: false }, aria: true },
+        half: { props: { checked: false, indeterminate: true }, aria: 'mixed' },
+      },
+    },
+  })
+  // ── mount（只一次）──
+  let bodyEl: HTMLElement | null = null
+  const scroll = ctx.ui.useScrollPosition({ getScroller: ()=> bodyEl ?? null })
+  const stableRef = (node: HTMLElement | null)=> {
+    if (node) {
+      bodyEl = node
+      scroll.refresh()
+    } else {
+      bodyEl = null
+    }
+  }
+
+  return (props: VirtualTableProps)=> {
+    const {
+      columns, data = [], height = 400, rowHeight = 40, overscan = 5,
+      sortKey, sortOrder, onSort, emptyText = '暂无数据', onRowClick, rowSelection, className,
+    } = props
+
+    if (bodyEl && bodyEl.scrollTop !== scroll.y) {
+      scroll.refresh()
+    }
+
+    const sortedData = sortData(data, columns, sortKey, sortOrder)
+    const total = sortedData.length
+
+    // 行 key 提取（rowSelection）
+    const rowKeyField = rowSelection?.rowKey ?? 'id'
+    const rowKeyOf = (row: any, i: number)=> row[rowKeyField] != null ? row[rowKeyField] : i
+    const selectedSet = new Set(rowSelection?.selectedRowKeys ?? [])
+    const toggleRow = (row: any, i: number)=> {
+      if (!rowSelection) return
+      const k = rowKeyOf(row, i)
+      const next = selectedSet.has(k)
+        ? (rowSelection.selectedRowKeys.filter(x => x !== k))
+        : [...rowSelection.selectedRowKeys, k]
+      const nextRows = next.map(nk => sortedData.find((r, ri)=> rowKeyOf(r, ri) === nk)).filter(Boolean)
+      rowSelection.onChange?.(next, nextRows)
+    }
+    const toggleAll = ()=> {
+      if (!rowSelection) return
+      const allSelected = total > 0 && sortedData.every((r, ri)=> selectedSet.has(rowKeyOf(r, ri)))
+      if (allSelected) {
+        rowSelection.onChange?.([], [])
+      } else {
+        const allKeys = sortedData.map((r, ri)=> rowKeyOf(r, ri))
+        rowSelection.onChange?.(allKeys, [...sortedData])
+      }
+    }
+
+    // 列宽：width 显式 → px；无 width → flex 均分剩余
+    const colStyle = (col: TableColumn)=> ({
+      width: typeof col.width === 'number' ? `${col.width}px` : col.width,
+      flex: col.width ? undefined : '1',
+    })
+
+    // ── 固定表头 ──
+    const colHeaders = columns.map(col => {
+      const sorted = sortKey === col.key
+      const orderIcon = col.sortable
+        ? h('span', {
+            class: `wf-virtual-table-sort-icon${sorted ? ' wf-virtual-table-sort-icon--active' : ''}`,
+          }, sorted && sortOrder === 'desc' ? h(Icon, { name: 'chevron-down', size: 12 }) : h(Icon, { name: 'chevron-up', size: 12 }))
+        : null
+      return h('div', {
+        class: `wf-virtual-table-th${col.sortable ? ' wf-virtual-table-th--sortable' : ''}${sorted ? ' wf-virtual-table-th--sorted' : ''}`,
+        style: colStyle(col),
+        role: col.sortable ? 'button' : undefined,
+        tabIndex: col.sortable ? 0 : undefined,
+        onClick: col.sortable ? ()=> {
+          if (!onSort) return
+          if (sortKey !== col.key) onSort(col.key, 'asc')
+          else onSort(col.key, sortOrder === 'asc' ? 'desc' : 'asc')
+        } : undefined,
+        onKeyDown: col.sortable ? (e: KeyboardEvent)=> {
+          if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault()
+            if (!onSort) return
+            if (sortKey !== col.key) onSort(col.key, 'asc')
+            else onSort(col.key, sortOrder === 'asc' ? 'desc' : 'asc')
+          }
+        } : undefined,
+      }, [
+        h('span', { class: 'wf-virtual-table-th-label' }, col.label),
+        orderIcon,
+      ].filter(Boolean))
+    })
+
+    // 行选择：表头全选复选框列（三态：全选 / 部分选中 indeterminate / 未选）
+    const headerCells: any[] = []
+    if (rowSelection) {
+      const allSelected = total > 0 && sortedData.every((r, ri)=> selectedSet.has(rowKeyOf(r, ri)))
+      const someSelected = total > 0 && !allSelected && sortedData.some((r, ri)=> selectedSet.has(rowKeyOf(r, ri)))
+      headerCells.push(h('div', {
+        class: 'wf-virtual-table-th wf-virtual-table-th--select',
+        style: { width: '40px' },
+      }, h('input', headTriCheck(allSelected ? 'checked' : (someSelected ? 'half' : null), {
+        type: 'checkbox',
+        'aria-label': allSelected ? '取消全选' : '全选',
+        onChange: toggleAll,
+      }))))
+    }
+    headerCells.push(...colHeaders)
+
+    const thead = h('div', {
+      class: 'wf-virtual-table-thead',
+    }, headerCells)
+
+    // ── 虚拟表体 ──
+    const start = Math.max(0, Math.floor(scroll.y / rowHeight) - overscan)
+    const end = Math.min(total, Math.ceil((scroll.y + height) / rowHeight) + overscan)
+
+    let body: any
+    if (total === 0) {
+      body = h('div', { class: 'wf-virtual-table-empty' }, emptyText)
+    } else {
+      const spacer = h('div', {
+        class: 'wf-virtual-table-spacer',
+        style: { height: `${total * rowHeight}px` },
+      })
+      const visible: any[] = []
+      for (let i = start; i < end; i++) {
+        const row = sortedData[i]
+        const cells: any[] = []
+        if (rowSelection) {
+          const checked = selectedSet.has(rowKeyOf(row, i))
+          cells.push(h('div', {
+            class: 'wf-virtual-table-td wf-virtual-table-td--select',
+            style: { width: '40px' },
+          }, h('input', {
+            type: 'checkbox',
+            class: 'wf-virtual-table-check',
+            checked,
+            'aria-label': `选择第 ${i + 1} 行`,
+            onChange: ()=> toggleRow(row, i),
+            onClick: (e: Event)=> e.stopPropagation(),
+          })))
+        }
+        for (const col of columns) {
+          cells.push(h('div', {
+            class: 'wf-virtual-table-td',
+            style: colStyle(col),
+          }, col.render ? col.render(row[col.key], row, i) : String(row[col.key] ?? '')))
+        }
+        visible.push(h('div', {
+          class: 'wf-virtual-table-row',
+          style: { position: 'absolute', top: `${i * rowHeight}px`, left: 0, right: 0, height: `${rowHeight}px` },
+          key: String(row.id ?? i),
+          onClick: onRowClick ? ()=> onRowClick(row, i) : undefined,
+          tabIndex: onRowClick ? 0 : undefined,
+          onKeyDown: onRowClick ? (e: KeyboardEvent)=> { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); onRowClick(row, i) } } : undefined,
+        }, cells))
+      }
+      body = h('div', {
+        class: 'wf-virtual-table-body',
+        style: { position: 'relative', width: '100%', height: `${height}px`, overflowY: 'auto' },
+        ref: stableRef,
+      }, [spacer, ...visible])
+    }
+
+    return h('div', {
+      class: ['wf-virtual-table', className].filter(Boolean).join(' '),
+      style: { width: '100%', minHeight: `${height}px` },
+    }, [thead, body])
+  }
+}

package/dist/level5/client/components/Watermark/Watermark.css

@@ -0,0 +1,13 @@
+/* weifuwu/client/components — Watermark */
+
+.wf-watermark {
+  position: relative;
+  font-family: var(--wf-font-sans);
+}
+
+.wf-watermark-overlay {
+  position: absolute;
+  inset: 0;
+  background-repeat: repeat;
+  background-size: auto;
+}

package/dist/level5/client/components/Watermark/Watermark.d.ts

@@ -0,0 +1,20 @@
+/** Watermark：水印：canvas 平铺绘制 + overlay（antd Watermark）（showcase /components/watermark） */
+import type { Component, VNodeChild } from '../../../../level6/client/vdom/index.ts';
+export interface WatermarkProps {
+    /** 水印文字 */
+    text?: string;
+    fontSize?: number;
+    /** 文字颜色（默认继承） */
+    color?: string;
+    /** 透明度 0-1，默认 0.15 */
+    opacity?: number;
+    /** 旋转角度（度），默认 -25 */
+    rotate?: number;
+    /** 平铺间距（px），默认 100 */
+    gap?: number;
+    children?: VNodeChild;
+    className?: string;
+}
+/** 水印（对应 antd Watermark）：canvas 绘制平铺文字 + overlay 覆盖内容（pointer-events none）。
+ * 裁剪（CS-05，见 docs/client.md）：图片水印、多行文字、动态旋转。 */
+export declare const Watermark: Component<WatermarkProps>;

package/dist/level5/client/components/Watermark/Watermark.ts

@@ -0,0 +1,79 @@
+/** Watermark：水印：canvas 平铺绘制 + overlay（antd Watermark）（showcase /components/watermark） */
+import type {Component, VNodeChild} from '../../../../level6/client/vdom/index.ts'
+import { createClientBrowser } from '../../../../level6/client/vdom/index.ts'
+import type { UIContext } from '../../../../level6/client/vdom/index.ts'
+import { h } from '../../../../level6/client/vdom/index.ts'
+
+export interface WatermarkProps {
+  /** 水印文字 */
+  text?: string
+  fontSize?: number
+  /** 文字颜色（默认继承） */
+  color?: string
+  /** 透明度 0-1，默认 0.15 */
+  opacity?: number
+  /** 旋转角度（度），默认 -25 */
+  rotate?: number
+  /** 平铺间距（px），默认 100 */
+  gap?: number
+  children?: VNodeChild
+  className?: string
+}
+
+/** 水印（对应 antd Watermark）：canvas 绘制平铺文字 + overlay 覆盖内容（pointer-events none）。
+ * 裁剪（CS-05，见 docs/client.md）：图片水印、多行文字、动态旋转。 */
+export const Watermark: Component<WatermarkProps> = (_init, _ctx)=> {
+  const _browser = _ctx?.browser ?? createClientBrowser()
+  // ── mount（只一次）──
+  let bgImage = ''
+  // 稳定 ref：render 层的 props 经 latest 引用读取（ref 定义在 mount 作用域，
+  // 避免内联 ref 每次渲染换引用触发 ref-diff churn）
+  let latest: { text: string; fontSize: number; color: string; opacity: number; rotate: number; gap: number } = {
+    text: 'weifuwu', fontSize: 14, color: 'currentColor', opacity: 0.15, rotate: -25, gap: 100,
+  }
+  const overlayRef = (el: HTMLElement | null)=> {
+    if (el && !bgImage) {
+      draw(latest.text, latest.fontSize, latest.color, latest.opacity, latest.rotate, latest.gap)
+      if (bgImage) el.style.backgroundImage = `url(${bgImage})`
+    }
+  }
+
+  const draw = (text: string, fontSize: number, color: string, opacity: number, rotate: number, gap: number)=> {
+    const canvas = _browser?.createElement('canvas')
+    if (!canvas) return
+    const ctx2d = canvas.getContext('2d')
+    if (!ctx2d) return
+    const { width } = ctx2d.measureText(text)
+    const tileW = Math.max(width + gap, gap)
+    const tileH = gap
+    canvas.width = tileW
+    canvas.height = tileH
+    ctx2d.globalAlpha = opacity
+    ctx2d.font = `${fontSize}px sans-serif`
+    ctx2d.fillStyle = color
+    ctx2d.translate(tileW / 2, tileH / 2)
+    ctx2d.rotate((rotate * Math.PI) / 180)
+    ctx2d.fillText(text, -width / 2, 0)
+    bgImage = canvas.toDataURL()
+  }
+
+  return (props)=> {
+    const {
+      text = 'weifuwu', fontSize = 14, color = 'currentColor', opacity = 0.15,
+      rotate = -25, gap = 100, children, className,
+    } = props
+
+    latest = { text, fontSize, color, opacity, rotate, gap }
+
+    return h('div', {
+      class: ['wf-watermark', className].filter(Boolean).join(' '),
+    }, [
+      children,
+      h('div', {
+        class: 'wf-watermark-overlay',
+        style: { pointerEvents: 'none', backgroundImage: bgImage ? `url(${bgImage})` : undefined },
+        ref: overlayRef,
+      }),
+    ])
+  }
+}

package/dist/level5/client/components/Wave/Wave.css

@@ -0,0 +1,23 @@
+.wf-wave {
+  position: relative;
+  display: inline-block;
+  overflow: hidden;
+  border-radius: inherit; /* 跟随子元素圆角（Button 波纹圆角一致） */
+  -webkit-tap-highlight-color: transparent;
+}
+
+.wf-wave-ripple {
+  position: absolute;
+  border-radius: 50%;
+  pointer-events: none;
+  background: color-mix(in srgb, currentColor 12%, transparent);
+  transform: scale(0);
+  animation: wf-wave-pop var(--wf-dur-base) var(--wf-ease-out) forwards;
+}
+
+@keyframes wf-wave-pop {
+  to {
+    transform: scale(1);
+    opacity: 0;
+  }
+}

package/dist/level5/client/components/Wave/Wave.d.ts

@@ -0,0 +1,16 @@
+/** Wave：点击水波纹动效——包装任意可点击元素（纯 CSS，reduced-motion 自动降级）（showcase /components/wave） */
+/**
+ * Wave — 点击水波纹动效（antd Wave 等价，纯 CSS 实现零依赖）
+ *
+ * 用法：<Wave><Button>提交</Button></Wave>——包装任意可点击元素
+ * 实现：点击 → 在点击坐标生成波纹元素（absolute 圆形）→ 动画扩散消失
+ * 纪律：动效走 --wf-dur-*；reduced-motion 自动降级（_base.css）
+ */
+import type { Component, VNodeChild } from '../../../../level6/client/vdom/index.ts';
+export interface WaveProps {
+    children?: VNodeChild;
+    className?: string;
+    /** 波纹颜色（默认 currentColor 12% 透明） */
+    color?: string;
+}
+export declare const Wave: Component<WaveProps>;

package/dist/level5/client/components/Wave/Wave.ts

@@ -0,0 +1,51 @@
+/** Wave：点击水波纹动效——包装任意可点击元素（纯 CSS，reduced-motion 自动降级）（showcase /components/wave） */
+/**
+ * Wave — 点击水波纹动效（antd Wave 等价，纯 CSS 实现零依赖）
+ *
+ * 用法：<Wave><Button>提交</Button></Wave>——包装任意可点击元素
+ * 实现：点击 → 在点击坐标生成波纹元素（absolute 圆形）→ 动画扩散消失
+ * 纪律：动效走 --wf-dur-*；reduced-motion 自动降级（_base.css）
+ */
+import type {Component, VNodeChild} from '../../../../level6/client/vdom/index.ts'
+import { h } from '../../../../level6/client/vdom/index.ts'
+import { createClientBrowser } from '../../../../level6/client/vdom/index.ts'
+
+export interface WaveProps {
+  children?: VNodeChild
+  className?: string
+  /** 波纹颜色（默认 currentColor 12% 透明） */
+  color?: string
+}
+
+let waveSeq = 0
+
+export const Wave: Component<WaveProps> = (_init, ctx)=>
+  (props)=> {
+    const { children, className = '', color } = props
+
+    const spawnRipple = (e: MouseEvent)=> {
+      const el = e.currentTarget as HTMLElement
+      const rect = el.getBoundingClientRect()
+      const size = Math.max(rect.width, rect.height) * 2
+      const x = e.clientX - rect.left - size / 2
+      const y = e.clientY - rect.top - size / 2
+      const ripple = (ctx.browser ?? createClientBrowser()).createElement('span') as HTMLSpanElement
+      ripple.className = 'wf-wave-ripple'
+      ripple.dataset.wid = `wave-${++waveSeq}`
+      ripple.style.cssText = `left:${x}px;top:${y}px;width:${size}px;height:${size}px;${color ? `background:${color};` : ''}`
+      el.appendChild(ripple)
+      // 动画结束移除（reduced-motion 下动画 0.01ms——等效瞬时）
+      const done = ()=> ripple.remove()
+      ripple.addEventListener('animationend', done, { once: true })
+      // 兜底（animationend 丢失防泄漏）
+      ctx.browser?.timeout?.(done, 600)
+    }
+
+    return h('span', {
+      class: `wf-wave${className ? ` ${className}` : ''}`,
+      onClick: (e: MouseEvent)=> {
+        // 透传原点击（包装不吞事件）
+        spawnRipple(e)
+      },
+    }, children)
+  }

package/dist/level5/client/components/WordCloud/WordCloud.css

@@ -0,0 +1,68 @@
+/* weifuwu/client/components — WordCloud */
+
+.wf-wordcloud {
+  position: relative;
+  max-width: 100%;
+}
+
+.wf-wordcloud svg {
+  display: block;
+}
+
+.wf-wordcloud text {
+  cursor: default;
+  transition: opacity var(--wf-dur-fast) var(--wf-ease-out);
+}
+
+/* 可交互态（onWordClick 提供时）——hover/键盘焦点高亮 */
+.wf-wordcloud--clickable text {
+  cursor: pointer;
+  /* SVG text 默认 pointer-events: visiblePainted——命中区=字形笔画（字母间隙漏到
+     svg 根——点击不触发实证）——bounding-box = 命中整个文本 bbox（SVG2） */
+  pointer-events: bounding-box;
+}
+
+.wf-wordcloud--clickable text:hover,
+.wf-wordcloud--clickable text:focus-visible {
+  opacity: 0.7;
+}
+
+/* tooltip 内容（Chart 同款命令式弹窗——面板仅 max-width 无背景——
+ * 内容自带反色卡片（深底浅字——popup-manager z-index 定位由内核完成）） */
+.wf-wordcloud-tooltip {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--wf-gap-xs);
+  background: var(--wf-color-text);
+  color: var(--wf-color-bg);
+  padding: var(--wf-space-xs) var(--wf-space-sm);
+  border-radius: var(--wf-radius-sm);
+  font-family: var(--wf-font-sans);
+  font-size: var(--wf-font-size-sm);
+  line-height: var(--wf-line-height);
+  white-space: nowrap;
+  pointer-events: none;
+}
+
+.wf-wordcloud-tooltip-word {
+  font-weight: var(--wf-font-weight-semibold);
+}
+
+.wf-wordcloud-tooltip-weight {
+  color: var(--wf-color-bg-secondary);
+  font-size: var(--wf-font-size-xs);
+}
+
+/* 空态（words 空/全零权重） */
+.wf-wordcloud-empty {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 80px;
+  padding: var(--wf-space-md);
+  border: var(--wf-border-width) dashed var(--wf-color-border);
+  border-radius: var(--wf-radius);
+  color: var(--wf-color-text-tertiary);
+  font-family: var(--wf-font-sans);
+  font-size: var(--wf-font-size-sm);
+}

package/dist/level5/client/components/WordCloud/WordCloud.d.ts

@@ -0,0 +1,80 @@
+/** WordCloud：词云——权重→字号映射 · 圆心同心环发散布局 · SVG textLength 定宽（零依赖自绘——SSR 一致零重叠）（showcase /components/wordcloud） */
+/**
+ * weifuwu/client/components — WordCloud
+ *
+ * 词云——权重→字号映射 · **中心同心环发散布局**（SVG textLength 定宽——
+ * 渲染宽度精确 = 估算宽——同输入同输出——SSR≡SPA 零差异 + 词矩形零重叠）
+ * 零依赖自绘 SVG（Chart 同族）。canvas 测宽/Canvas 绘制判负（服务端无 canvas——
+ * 见 git log plan/2026-09-wordcloud-组件.md 判负记录——中心排列消费证据推翻
+ * 行式装箱——同心环以 SVG 确定性实现：碰撞=矩形相交（纯函数））。
+ *
+ * 布局契约（纯函数——确定性——测试可断言）：
+ * - 权重线性映射 [minFontSize, maxFontSize]（全等权重 → 全 maxFontSize）
+ * - 降序放置——最大词从中心（环 0）开始——**同心环扫描**：环宽 = 当前词高
+ *   （邻环相接不重叠——环形约束）——环内候选点间距 = max(词宽, 环宽)（奇数环
+ *   错相偏 π/n——无隙漏）——首个无碰撞点放置
+ * - viewBox = 全部词包围盒（自适应——零裁剪——height 为显示高）
+ * - 词矩形（含 padding 间距）两两不相交（环碰撞保证 + textLength 强制实际宽）
+ */
+import type { Component } from '../../../../level6/client/vdom/index.ts';
+export interface WordCloudData {
+    /** 词文本 */
+    word: string;
+    /** 权重（≥0——0 不渲染） */
+    weight: number;
+    /** 覆盖色板（不传按 colors 取模） */
+    color?: string;
+}
+export interface WordCloudProps {
+    words: WordCloudData[];
+    /** 显示高度（px——SVG 等比缩放——默认=布局包围盒高） */
+    height?: number;
+    /** 最大字号（px）——默认 32 */
+    maxFontSize?: number;
+    /** 最小字号（px）——默认 12 */
+    minFontSize?: number;
+    /** 词四周间距（px）——默认 4 */
+    padding?: number;
+    /** 色板（默认 token 色阶——逐词取模） */
+    colors?: string[];
+    /** 点击词回调（提供后词可交互：hover 高亮 + 键盘 Enter/Space 可达） */
+    onWordClick?: (word: string, weight: number) => void;
+    className?: string;
+}
+/** 估算词渲染宽（textLength 将强制实际=此值） */
+export declare function estimateWordWidth(word: string, size: number): number;
+export interface PlacedWord {
+    word: string;
+    weight: number;
+    /** 中心 x（text-anchor: middle） */
+    x: number;
+    /** 基线 y */
+    y: number;
+    size: number;
+    /** textLength（= 实际渲染字宽——不含 padding） */
+    textLength: number;
+    /** 词级颜色（WordCloudData.color——透传——未传由色板兜底） */
+    color?: string;
+    /** 布局矩形（含 padding——零重叠断言单位） */
+    rect: {
+        l: number;
+        t: number;
+        r: number;
+        b: number;
+    };
+}
+/** 布局输出（viewBox = 包围盒——由内容决定——零裁剪） */
+export interface WordCloudLayout {
+    placed: PlacedWord[];
+    /** 布局坐标系宽（= 包围盒宽） */
+    width: number;
+    /** 布局坐标系高（= 包围盒高） */
+    height: number;
+}
+/** 中心同心环布局（纯函数——确定性——同输入同输出——零重叠） */
+export declare function layoutWords(words: WordCloudData[], opts: {
+    maxFontSize: number;
+    minFontSize: number;
+    padding: number;
+}): WordCloudLayout;
+export declare const WordCloud: Component<WordCloudProps>;