@veltra/sheet 2.3.4 → 2.4.0

package/src/report/__test__/drill.test.ts

@@ -0,0 +1,194 @@
+import { Sheet, cellKey } from '@veltra/sheet-core'
+import { describe, expect, it } from 'vitest'
+
+import { REPORT_META_NAMESPACE } from '../binding'
+import {
+  buildDrillHitMap,
+  createDrillStack,
+  currentDrillLayer,
+  popDrillLayer,
+  pushDrillLayer,
+  resolveDrillParams
+} from '../drill'
+import { createReportTemplate, type ReportTemplate } from '../template'
+import type { ReportBinding, ReportDrillConfig } from '../types'
+
+// ---- 内联 fixtures ----
+
+/** 最小 Report Template：下钻栈只关心引用与参数，不消费快照内容 */
+function makeTemplate(rows: number): ReportTemplate {
+  return {
+    version: 1,
+    cells: [],
+    styles: [],
+    merges: [],
+    frozen: { rows: 0, cols: 0 },
+    rows,
+    cols: 0
+  }
+}
+
+const TPL_A = makeTemplate(10)
+const TPL_B = makeTemplate(20)
+const TPL_C = makeTemplate(30)
+
+const DRILL: ReportDrillConfig = {
+  target: 'tpl-detail',
+  mapping: { region: 'p_region', amount: 'p_amount' },
+  openMode: 'switch'
+}
+
+describe('resolveDrillParams', () => {
+  it('按映射从记录取值为详情报参数', () => {
+    const values = resolveDrillParams(DRILL, { region: '华东', amount: 100 })
+    expect(values).toEqual({ p_region: '华东', p_amount: 100 })
+  })
+
+  it('记录缺字段时跳过对应参数，null 值保留', () => {
+    const values = resolveDrillParams(DRILL, { region: '华东', amount: null })
+    expect(values).toEqual({ p_region: '华东', p_amount: null })
+    expect(
+      'p_missing' in resolveDrillParams({ ...DRILL, mapping: { missing: 'p_missing' } }, {})
+    ).toBe(false)
+  })
+
+  it('空映射返回空参数', () => {
+    expect(resolveDrillParams({ ...DRILL, mapping: {} }, { region: '华东' })).toEqual({})
+  })
+})
+
+describe('下钻栈', () => {
+  it('根层即当前层', () => {
+    const stack = createDrillStack({ template: TPL_A, params: { p: 'a0' } })
+    expect(stack).toHaveLength(1)
+    expect(currentDrillLayer(stack)).toEqual({ template: TPL_A, params: { p: 'a0' } })
+  })
+
+  it('push 后当前层为新层，前层参数定格为离开时的值', () => {
+    const stack = createDrillStack({ template: TPL_A, params: { p: 'a0' } })
+    const next = pushDrillLayer(stack, { template: TPL_B, params: { p: 'b1' } }, { p: 'a1' })
+    expect(next).toHaveLength(2)
+    expect(currentDrillLayer(next)).toEqual({ template: TPL_B, params: { p: 'b1' } })
+    expect(next[0]).toEqual({ template: TPL_A, params: { p: 'a1' } })
+    // 不可变更新：原栈不受影响
+    expect(stack).toHaveLength(1)
+  })
+
+  it('push 缺省 currentParams 时保留前层原参数', () => {
+    const stack = createDrillStack({ template: TPL_A, params: { p: 'a0' } })
+    const next = pushDrillLayer(stack, { template: TPL_B, params: {} })
+    expect(next[0]).toEqual({ template: TPL_A, params: { p: 'a0' } })
+  })
+
+  it('pop 逐级回退并保留各层当时参数', () => {
+    let stack = createDrillStack({ template: TPL_A, params: { p: 'a0' } })
+    stack = pushDrillLayer(stack, { template: TPL_B, params: { p: 'b1' } }, { p: 'a1' })
+    stack = pushDrillLayer(stack, { template: TPL_C, params: { p: 'c1' } }, { p: 'b2' })
+
+    stack = popDrillLayer(stack)
+    expect(currentDrillLayer(stack)).toEqual({ template: TPL_B, params: { p: 'b2' } })
+    stack = popDrillLayer(stack)
+    expect(currentDrillLayer(stack)).toEqual({ template: TPL_A, params: { p: 'a1' } })
+  })
+
+  it('仅剩根层时 pop 原样返回', () => {
+    const stack = createDrillStack({ template: TPL_A, params: {} })
+    expect(popDrillLayer(stack)).toBe(stack)
+  })
+
+  it('指向自身照常压栈，靠 pop 逐级退出', () => {
+    let stack = createDrillStack({ template: TPL_A, params: { p: 'a0' } })
+    stack = pushDrillLayer(stack, { template: TPL_A, params: { p: 'a1' } })
+    stack = pushDrillLayer(stack, { template: TPL_A, params: { p: 'a2' } })
+    expect(stack).toHaveLength(3)
+
+    stack = popDrillLayer(stack)
+    expect(currentDrillLayer(stack)).toEqual({ template: TPL_A, params: { p: 'a1' } })
+    stack = popDrillLayer(stack)
+    expect(currentDrillLayer(stack)).toEqual({ template: TPL_A, params: { p: 'a0' } })
+  })
+
+  it('成环照常压栈，回退沿压栈路径逐级退出', () => {
+    let stack = createDrillStack({ template: TPL_A, params: { p: 'root' } })
+    stack = pushDrillLayer(stack, { template: TPL_B, params: { p: 'b1' } })
+    stack = pushDrillLayer(stack, { template: TPL_A, params: { p: 'a-from-b' } })
+    stack = pushDrillLayer(stack, { template: TPL_B, params: { p: 'b2' } })
+    expect(stack.map((layer) => layer.template)).toEqual([TPL_A, TPL_B, TPL_A, TPL_B])
+
+    stack = popDrillLayer(stack)
+    expect(currentDrillLayer(stack)).toEqual({ template: TPL_A, params: { p: 'a-from-b' } })
+    stack = popDrillLayer(stack)
+    expect(currentDrillLayer(stack)).toEqual({ template: TPL_B, params: { p: 'b1' } })
+    stack = popDrillLayer(stack)
+    expect(currentDrillLayer(stack)).toEqual({ template: TPL_A, params: { p: 'root' } })
+  })
+})
+
+describe('buildDrillHitMap 与上下文解析', () => {
+  it('分组格与汇总聚合格均生成正确命中上下文（含汇总格自身聚合值）', () => {
+    const sheet = new Sheet()
+    sheet.setCellMeta({ row: 0, col: 0 }, REPORT_META_NAMESPACE, {
+      dataset: 'ds',
+      field: 'region',
+      aggregate: 'group',
+      expand: 'down',
+      drill: { target: 't2', mapping: { region: 'p_region' }, openMode: 'switch' }
+    })
+    sheet.setCellMeta({ row: 0, col: 1 }, REPORT_META_NAMESPACE, {
+      dataset: 'ds',
+      field: 'amount',
+      aggregate: 'sum',
+      expand: 'none',
+      rowParent: { row: 0, col: 0 },
+      drill: {
+        target: 't2',
+        mapping: { region: 'p_region', amount: 'p_amount' },
+        openMode: 'dialog'
+      }
+    })
+
+    const template = sheet.snapshot()
+    const data = {
+      ds: [
+        { region: '华东', amount: 100 },
+        { region: '华东', amount: 200 },
+        { region: '华南', amount: 50 }
+      ]
+    }
+
+    const hitMap = buildDrillHitMap(template, data)
+    // 华东分组格 (0,0)
+    const hitGroup0 = hitMap.get(cellKey({ row: 0, col: 0 }))
+    expect(hitGroup0?.record).toEqual({ region: '华东' })
+
+    // 华东汇总格 (0,1) 拥有祖先分组 region 与自身的求和计算值 300
+    const hitSum0 = hitMap.get(cellKey({ row: 0, col: 1 }))
+    expect(hitSum0?.record).toEqual({ region: '华东', amount: 300 })
+    expect(resolveDrillParams(hitSum0!.config, hitSum0!.record)).toEqual({
+      p_region: '华东',
+      p_amount: 300
+    })
+
+    // 华南汇总格 (1,1)
+    const hitSum1 = hitMap.get(cellKey({ row: 1, col: 1 }))
+    expect(hitSum1?.record).toEqual({ region: '华南', amount: 50 })
+    expect(resolveDrillParams(hitSum1!.config, hitSum1!.record)).toEqual({
+      p_region: '华南',
+      p_amount: 50
+    })
+  })
+})
+
+describe('旧绑定兼容', () => {
+  it('无 drill 字段的旧绑定序列化往返后不出现 drill 键', () => {
+    const binding: ReportBinding = {
+      dataset: 'orders',
+      field: 'region',
+      expand: 'down',
+      aggregate: 'list'
+    }
+    const restored = JSON.parse(JSON.stringify(binding)) as ReportBinding
+    expect('drill' in restored).toBe(false)
+    expect(restored.drill).toBeUndefined()
+  })
+})

package/src/report/__test__/print.test.ts

@@ -0,0 +1,170 @@
+import { Sheet } from '@veltra/sheet-core'
+import { describe, expect, it } from 'vitest'
+
+import { buildFilledReportPrintHtml } from '../print'
+
+/** 基础填充表：表头 + 两列数据 */
+function createFilledSheet(name = '销售报表'): Sheet {
+  const sheet = new Sheet(name)
+  sheet.setCells([
+    { addr: { row: 0, col: 0 }, data: { v: '客户' } },
+    { addr: { row: 0, col: 1 }, data: { v: '金额' } },
+    { addr: { row: 1, col: 0 }, data: { v: '甲公司' } },
+    { addr: { row: 1, col: 1 }, data: { v: 100 } }
+  ])
+  return sheet
+}
+
+describe('buildFilledReportPrintHtml', () => {
+  it('输出完整打印文档：值为文本、默认 A4 纵向、缺省标题取 sheet 名', () => {
+    const html = buildFilledReportPrintHtml(createFilledSheet())
+
+    expect(html).toContain('<!doctype html>')
+    expect(html).toContain('<title>销售报表</title>')
+    expect(html).toContain('@page { size: A4 portrait;')
+    expect(html).toContain('<td>客户</td>')
+    expect(html).toContain('<td>100</td>')
+    // 默认列宽 80 / 行高 28（对齐 grid 默认）
+    expect(html).toContain('<col style="width:80px">')
+    expect(html).toContain('<tr style="height:28px">')
+    // 背景色打印保色
+    expect(html).toContain('print-color-adjust: exact')
+  })
+
+  it('选项：title 覆盖、landscape 方向；空名 sheet 回落「报表」', () => {
+    const html = buildFilledReportPrintHtml(createFilledSheet(), {
+      title: '月度报表',
+      orientation: 'landscape'
+    })
+    expect(html).toContain('<title>月度报表</title>')
+    expect(html).toContain('@page { size: A4 landscape;')
+
+    const fallback = buildFilledReportPrintHtml(new Sheet(''))
+    expect(fallback).toContain('<title>报表</title>')
+  })
+
+  it('合并格映射 rowspan/colspan，被覆盖格不输出', () => {
+    const sheet = createFilledSheet()
+    sheet.mergeCells({ start: { row: 0, col: 0 }, end: { row: 1, col: 1 } })
+
+    const html = buildFilledReportPrintHtml(sheet)
+    expect(html).toContain('<td colspan="2" rowspan="2">客户</td>')
+    // 2×2 合并后只剩 1 个 td（锚点），覆盖格跳过
+    const tdCount = (html.match(/<td/g) ?? []).length
+    expect(tdCount).toBe(1)
+  })
+
+  it('有效样式序列化为内联 CSS（fill/border/font/align/wrap）', () => {
+    const sheet = createFilledSheet()
+    sheet.setCellStyle(
+      { start: { row: 0, col: 0 }, end: { row: 0, col: 0 } },
+      {
+        fill: { color: '#ff0000' },
+        border: { top: { style: 'thin', width: 1, color: '#000000' } },
+        font: {
+          bold: true,
+          italic: true,
+          underline: true,
+          strikethrough: true,
+          size: 14,
+          color: '#111111'
+        },
+        align: { horizontal: 'center', vertical: 'middle', wrap: true }
+      }
+    )
+    sheet.setCellStyle(
+      { start: { row: 1, col: 1 }, end: { row: 1, col: 1 } },
+      { align: { horizontal: 'right' } }
+    )
+
+    const html = buildFilledReportPrintHtml(sheet)
+    expect(html).toContain('background-color:#ff0000')
+    expect(html).toContain('border-top:1px solid #000000')
+    expect(html).toContain('font-weight:bold')
+    expect(html).toContain('font-style:italic')
+    expect(html).toContain('text-decoration:underline line-through')
+    expect(html).toContain('font-size:14pt')
+    expect(html).toContain('color:#111111')
+    expect(html).toContain('text-align:center')
+    expect(html).toContain('vertical-align:middle')
+    expect(html).toContain('white-space:normal;word-break:break-all')
+    expect(html).toContain('text-align:right')
+  })
+
+  it('虚线/点线边框线型映射 CSS dashed/dotted', () => {
+    const sheet = createFilledSheet()
+    sheet.setCellStyle(
+      { start: { row: 0, col: 0 }, end: { row: 0, col: 0 } },
+      {
+        border: {
+          left: { style: 'dashed', width: 1, color: '#000000' },
+          right: { style: 'dotted', width: 2, color: '#00ff00' }
+        }
+      }
+    )
+    const html = buildFilledReportPrintHtml(sheet)
+    expect(html).toContain('border-left:1px dashed #000000')
+    expect(html).toContain('border-right:2px dotted #00ff00')
+  })
+
+  it('自定义列宽 / 行高写入 colgroup 与 tr', () => {
+    const sheet = createFilledSheet()
+    sheet.setColWidth(1, 160)
+    sheet.setRowHeight(1, 40)
+
+    const html = buildFilledReportPrintHtml(sheet)
+    expect(html).toContain('<col style="width:160px">')
+    expect(html).toContain('<tr style="height:40px">')
+  })
+
+  it('文本与标题 HTML 转义', () => {
+    const sheet = new Sheet('报表<Q>')
+    sheet.setCells([{ addr: { row: 0, col: 0 }, data: { v: '<b>"x"</b> & y' } }])
+
+    const html = buildFilledReportPrintHtml(sheet)
+    expect(html).toContain('<title>报表&lt;Q&gt;</title>')
+    expect(html).toContain('<td>&lt;b&gt;"x"&lt;/b&gt; &amp; y</td>')
+    expect(html).not.toContain('<td><b>')
+  })
+
+  it('浮动图：data URL 内嵌，锚点格左上 + 格内偏移定位，显式宽高直出', () => {
+    const sheet = createFilledSheet()
+    sheet.setColWidth(0, 100)
+    sheet.insertImage({
+      data: new Uint8Array([1, 2, 3]),
+      type: 'png',
+      anchor: { from: { row: 1, col: 1, offsetX: 10, offsetY: 5 } },
+      width: 48,
+      height: 24,
+      altText: '图章'
+    })
+
+    const html = buildFilledReportPrintHtml(sheet)
+    // left = col0 宽 100 + 默认列宽 80（col1 前）→ 取 col1 左缘 100... colWidths=[100,80]，col1 左缘=100，+offsetX=110
+    // top = row0 高 28，+offsetY=5 → 33
+    expect(html).toContain(`<img src="data:image/png;base64,AQID"`)
+    expect(html).toContain('left:110px;top:33px;width:48px;height:24px;')
+    expect(html).toContain('alt="图章"')
+  })
+
+  it('浮动图：宽高缺失且有 to 时按 from→to 跨度兜底', () => {
+    const sheet = createFilledSheet()
+    sheet.insertImage({
+      data: new Uint8Array([0]),
+      type: 'jpeg',
+      anchor: { from: { row: 0, col: 0 }, to: { row: 1, col: 1 } }
+    })
+
+    const html = buildFilledReportPrintHtml(sheet)
+    // 跨度：col0+col1 = 80+80 = 160；row0+row1 = 28+28 = 56
+    expect(html).toContain('left:0px;top:0px;width:160px;height:56px;')
+    expect(html).toContain('data:image/jpeg;base64,')
+  })
+
+  it('空 sheet 输出合法空表文档', () => {
+    const html = buildFilledReportPrintHtml(new Sheet('空白'))
+    expect(html).toContain('<title>空白</title>')
+    expect(html).toContain('<table>')
+    expect(html).not.toContain('<tr')
+  })
+})

package/src/report/drill.ts

@@ -0,0 +1,112 @@
+import type { SheetSnapshot } from '@veltra/sheet-core'
+import { cellKey } from '@veltra/sheet-core'
+
+import { AggregateIndex, resolvePlacementContext } from './render/aggregate'
+import { computeExpansionLayout } from './render/coordinate'
+import { buildTemplateIndex } from './render/template-index'
+import type { ReportTemplate } from './template'
+import type { DatasetRecords, ParamValues, ReportDrillConfig } from './types'
+
+/**
+ * 宿主模板解析契约：按下钻 target 引用取回目标模板（允许同步/异步）。
+ * 失败抛错——查看器提示可读错误并停留当前报；设计器配置对话框据此解析目标模板查询参数。
+ */
+export type ResolveReportTemplate = (ref: string) => ReportTemplate | Promise<ReportTemplate>
+
+/**
+ * 按下钻映射从该格对应记录取值，生成详情报 Filter Bar 参数值。
+ * 记录缺字段（值为 `undefined`）时跳过对应参数，由详情报回退默认值；空映射返回空参数。
+ */
+export function resolveDrillParams(
+  config: ReportDrillConfig,
+  record: Record<string, unknown>
+): ParamValues {
+  const values: ParamValues = {}
+  for (const [field, paramId] of Object.entries(config.mapping)) {
+    const value = record[field]
+    if (value === undefined) continue
+    values[paramId] = value
+  }
+  return values
+}
+
+/** 下钻栈层：一张报表模板 + 当时 Filter Bar 参数值（回退时据此恢复并重新取数） */
+export interface DrillStackLayer {
+  template: ReportTemplate
+  params: ParamValues
+}
+
+/**
+ * 下钻栈：自根（初始报表）到顶的层序列，至少一层。
+ * 只经下方纯函数做不可变更新（返回新栈），便于组件层直接挂响应式。
+ */
+export type DrillStack = DrillStackLayer[]
+
+/** 以初始报表为根层创建下钻栈 */
+export function createDrillStack(root: DrillStackLayer): DrillStack {
+  return [{ template: root.template, params: { ...root.params } }]
+}
+
+/**
+ * 压入详情报新层并使其成为当前层；`currentParams` 把当前层参数定格为离开时的值
+ * （缺省保留原值）。指向自身或成环不做检测，照常压栈，靠 pop 逐级退出。
+ */
+export function pushDrillLayer(
+  stack: DrillStack,
+  next: DrillStackLayer,
+  currentParams?: ParamValues
+): DrillStack {
+  const top = stack[stack.length - 1]!
+  const layers = currentParams
+    ? [...stack.slice(0, -1), { template: top.template, params: { ...currentParams } }]
+    : [...stack]
+  layers.push({ template: next.template, params: { ...next.params } })
+  return layers
+}
+
+/** 弹出当前层返回上一层；仅剩根层时原样返回（查看器始终保留一张报表） */
+export function popDrillLayer(stack: DrillStack): DrillStack {
+  if (stack.length <= 1) return stack
+  return stack.slice(0, -1)
+}
+
+/** 当前层（栈顶） */
+export function currentDrillLayer(stack: DrillStack): DrillStackLayer {
+  return stack[stack.length - 1]!
+}
+
+/** 下钻命中：物理格对应的下钻配置与该格记录 */
+export interface DrillHit {
+  config: ReportDrillConfig
+  record: Record<string, unknown>
+}
+
+/**
+ * 构建填充报表的物理格 → 下钻命中索引（每次成功取数后重建）。
+ * 仅含配了下钻的绑定格落点（含分组/汇总格与展开后的实例格，合并跨度内每格都命中）；
+ * 记录由 `resolvePlacementContext` 解析：list 明细取源数据行，分组/汇总取分组上下文。
+ */
+export function buildDrillHitMap(
+  template: SheetSnapshot,
+  data: DatasetRecords
+): Map<number, DrillHit> {
+  const hits = new Map<number, DrillHit>()
+  const index = buildTemplateIndex(template)
+  const layout = computeExpansionLayout(index, data)
+  const aggregateIndex = new AggregateIndex(data)
+
+  for (const placement of layout.placements) {
+    const config = placement.binding?.drill
+    if (!config) continue
+    const record = resolvePlacementContext(placement, index, data, aggregateIndex)
+    if (!record) continue
+
+    const hit: DrillHit = { config, record }
+    for (let row = placement.physical.start.row; row <= placement.physical.end.row; row++) {
+      for (let col = placement.physical.start.col; col <= placement.physical.end.col; col++) {
+        hits.set(cellKey({ row, col }), hit)
+      }
+    }
+  }
+  return hits
+}

package/src/report/index.ts

@@ -1,5 +1,6 @@
 // 报表纯 TS 内核（ADR-0003 决策 1）：渲染引擎 / 绑定 / 条件规则 / 查询参数 / 数据连接器 /
-// Report Template（自包含模板与取数）/ Filter Bar 值规范化。
+// Report Template（自包含模板与取数）/ Filter Bar 值规范化 / 下钻配置与下钻栈 /
+// Filled Report XLSX 导出与打印 HTML。
 // 框架无关、无 DOM 依赖；组件壳（UReportDesigner / UReportViewer）落 components/report/。
 
 export * from './types'
@@ -10,4 +11,6 @@ export * from './render'
 export * from './connector'
 export * from './template'
 export * from './filter-bar'
+export * from './drill'
 export * from './export-xlsx'
+export * from './print'