@veltra/sheet 2.1.1 → 2.2.0

package/src/report/binding.ts

@@ -0,0 +1,243 @@
+import type { CellAddress } from '@veltra/sheet-core'
+import { formatAddress, parseAddress } from '@veltra/sheet-core'
+
+import type {
+  DatasetCatalogItem,
+  ReportAggregate,
+  ReportBinding,
+  ReportExpand,
+  ReportPreset
+} from './types'
+
+/** 字段 label 解析用的 catalog（由宿主注入） */
+let bindingCatalog: DatasetCatalogItem[] = []
+
+export function setBindingCatalog(catalog: DatasetCatalogItem[]): void {
+  bindingCatalog = catalog
+}
+
+export const REPORT_META_NAMESPACE = 'report'
+
+const AGGREGATE_PLACEHOLDER_TAG: Record<ReportAggregate, string> = {
+  list: '明细',
+  group: '分组',
+  sum: '求和',
+  avg: '平均',
+  count: '计数',
+  max: '最大',
+  min: '最小'
+}
+
+/** 预设 → 绑定字段补丁（父格除 grandTotal 外均保留推断值） */
+export function presetBindingPatch(
+  preset: ReportPreset,
+  options?: { transpose?: boolean }
+): Partial<ReportBinding> {
+  const expand: ReportExpand = options?.transpose ? 'right' : 'down'
+  switch (preset) {
+    case 'groupHeader':
+      return { preset, expand, aggregate: 'group' }
+    case 'detail':
+      return { preset, expand, aggregate: 'list' }
+    case 'subtotal':
+      return { preset, expand: 'none', aggregate: 'sum' }
+    case 'grandTotal':
+      return {
+        preset,
+        expand: 'none',
+        aggregate: 'sum',
+        rowParent: undefined,
+        colParent: undefined
+      }
+    case 'cross':
+      return { preset, expand: 'none', aggregate: 'sum' }
+  }
+}
+
+/** 将预设写入绑定（grandTotal 清空双父格；其余保留既有父格） */
+export function applyReportPreset(
+  binding: ReportBinding,
+  preset: ReportPreset,
+  options?: { transpose?: boolean }
+): ReportBinding {
+  const patch = presetBindingPatch(preset, options)
+  const next: ReportBinding = { ...binding, ...patch }
+  if (preset === 'grandTotal') {
+    delete next.rowParent
+    delete next.colParent
+  }
+  return next
+}
+
+export function isVerticalExpandBinding(binding: ReportBinding): boolean {
+  return (
+    binding.expand === 'down' && (binding.aggregate === 'group' || binding.aggregate === 'list')
+  )
+}
+
+export function isHorizontalExpandBinding(binding: ReportBinding): boolean {
+  return binding.expand === 'right' && binding.aggregate === 'group'
+}
+
+/** 指定模板行是否含纵向扩展绑定（展开带行） */
+export function isExpansionBandRow(
+  row: number,
+  getBindingAt: (addr: CellAddress) => ReportBinding | undefined,
+  scanCols = 64
+): boolean {
+  for (let col = 0; col < scanCols; col++) {
+    const binding = getBindingAt({ row, col })
+    if (binding && isVerticalExpandBinding(binding)) return true
+  }
+  return false
+}
+
+/** 落格时推断预设：默认明细；数值字段且位于展开带正下方相邻行 → 小计 */
+export function inferDropPreset(
+  addr: CellAddress,
+  fieldType: DatasetCatalogItem['fields'][number]['type'],
+  getBindingAt: (addr: CellAddress) => ReportBinding | undefined
+): ReportPreset {
+  if (fieldType === 'number' && addr.row > 0 && isExpansionBandRow(addr.row - 1, getBindingAt)) {
+    return 'subtotal'
+  }
+  return 'detail'
+}
+
+/** 同数据集纵向扩展绑定格（行方向父格下拉候选） */
+export function listRowParentCandidates(
+  binding: ReportBinding,
+  entries: ReadonlyArray<{ addr: CellAddress; binding: ReportBinding }>
+): CellAddress[] {
+  const candidates: CellAddress[] = []
+  for (const entry of entries) {
+    if (entry.binding.dataset !== binding.dataset) continue
+    if (!isVerticalExpandBinding(entry.binding)) continue
+    candidates.push(entry.addr)
+  }
+  return candidates
+}
+
+/** 同数据集横向扩展绑定格（列方向父格下拉候选） */
+export function listColParentCandidates(
+  binding: ReportBinding,
+  entries: ReadonlyArray<{ addr: CellAddress; binding: ReportBinding }>
+): CellAddress[] {
+  const candidates: CellAddress[] = []
+  for (const entry of entries) {
+    if (entry.binding.dataset !== binding.dataset) continue
+    if (!isHorizontalExpandBinding(entry.binding)) continue
+    candidates.push(entry.addr)
+  }
+  return candidates
+}
+
+/** 同列向上找最近的纵向扩展绑定，作为 rowParent 候选 */
+export function inferRowParentCandidate(
+  addr: CellAddress,
+  getBindingAt: (addr: CellAddress) => ReportBinding | undefined
+): CellAddress | null {
+  for (let row = addr.row - 1; row >= 0; row--) {
+    const binding = getBindingAt({ row, col: addr.col })
+    if (binding && isVerticalExpandBinding(binding)) {
+      return { row, col: addr.col }
+    }
+  }
+  return null
+}
+
+/** 同行向左找最近的横向扩展绑定，作为 colParent 候选 */
+export function inferColParentCandidate(
+  addr: CellAddress,
+  getBindingAt: (addr: CellAddress) => ReportBinding | undefined
+): CellAddress | null {
+  for (let col = addr.col - 1; col >= 0; col--) {
+    const binding = getBindingAt({ row: addr.row, col })
+    if (binding && isHorizontalExpandBinding(binding)) {
+      return { row: addr.row, col }
+    }
+  }
+  return null
+}
+
+/** 从绑定字段推断预设；不匹配任何预设时返回 null（自定义） */
+export function inferReportPreset(binding: ReportBinding): ReportPreset | null {
+  if (binding.preset) return binding.preset
+
+  if (
+    binding.expand === 'none' &&
+    binding.aggregate === 'sum' &&
+    binding.rowParent &&
+    binding.colParent
+  ) {
+    return 'cross'
+  }
+  if (
+    binding.expand === 'none' &&
+    binding.aggregate === 'sum' &&
+    !binding.rowParent &&
+    !binding.colParent
+  ) {
+    return 'grandTotal'
+  }
+  if (
+    binding.expand === 'none' &&
+    binding.aggregate === 'sum' &&
+    binding.rowParent &&
+    !binding.colParent
+  ) {
+    return 'subtotal'
+  }
+  if (binding.aggregate === 'group' && (binding.expand === 'down' || binding.expand === 'right')) {
+    return 'groupHeader'
+  }
+  if (binding.aggregate === 'list' && (binding.expand === 'down' || binding.expand === 'right')) {
+    return 'detail'
+  }
+  return null
+}
+
+/** 默认明细 + 纵向扩展 */
+export function createReportBinding(dataset: DatasetCatalogItem, fieldName: string): ReportBinding {
+  return {
+    dataset: dataset.id,
+    field: fieldName,
+    aggregate: 'list',
+    expand: 'down',
+    preset: 'detail',
+    sort: 'none',
+    conditionalRules: []
+  }
+}
+
+/** 设计地址 → A1 标签（支持多字母列） */
+export function formatCellAddress(addr: CellAddress): string {
+  return formatAddress(addr)
+}
+
+/** A1 标签 → 设计地址；非法输入返回 null */
+export function parseCellAddress(label: string): CellAddress | null {
+  return parseAddress(label)
+}
+
+/** 解析字段中文标签（找不到时回退字段名）；可传入报表配置中的 label */
+function resolveFieldLabel(
+  datasetId: string,
+  fieldName: string,
+  resolveLabel?: (datasetId: string, fieldName: string) => string
+): string {
+  const override = resolveLabel?.(datasetId, fieldName)
+  if (override) return override
+  const dataset = bindingCatalog.find((d) => d.id === datasetId)
+  const field = dataset?.fields.find((f) => f.name === fieldName)
+  return field?.label ?? fieldName
+}
+
+/** Binding Placeholder 中文可读文案（如「分组 · 客户」） */
+export function formatBindingPlaceholder(
+  binding: ReportBinding,
+  resolveLabel?: (datasetId: string, fieldName: string) => string
+): string {
+  const tag = AGGREGATE_PLACEHOLDER_TAG[binding.aggregate]
+  return `${tag} · ${resolveFieldLabel(binding.dataset, binding.field, resolveLabel)}`
+}

package/src/report/connector.ts

@@ -0,0 +1,205 @@
+import type { DatasetField, ParamValues } from './types'
+
+/** 数据连接类型（ADR-0003 决策 3：收敛为 MySQL / PostgreSQL） */
+export type ConnectionType = 'mysql' | 'postgresql'
+
+/** 各连接类型的默认端口 */
+export const DEFAULT_CONNECTION_PORTS: Record<ConnectionType, number> = {
+  mysql: 3306,
+  postgresql: 5432
+}
+
+/**
+ * 切换连接类型时解析端口：若当前端口仍是上一类型的默认值（或 0），则切到新类型默认端口；
+ * 用户已自定义的端口保持不变。
+ */
+export function resolvePortOnTypeChange(
+  prevType: ConnectionType,
+  nextType: ConnectionType,
+  currentPort: number
+): number {
+  if (prevType === nextType) return currentPort
+  if (currentPort === DEFAULT_CONNECTION_PORTS[prevType] || currentPort === 0) {
+    return DEFAULT_CONNECTION_PORTS[nextType]
+  }
+  return currentPort
+}
+
+/**
+ * 数据连接（纯序列化对象，仅驻留内存）。
+ * 凭据持久化与安全存储由下游负责（ADR-0003 决策 4）。
+ */
+export interface DataConnection {
+  id: string
+  label: string
+  type: ConnectionType
+  host: string
+  port: number
+  database: string
+  username: string
+  password: string
+}
+
+/** 业务错误（`200 + { ok: false, error }`）或客户端传输层错误 */
+export interface ConnectorError {
+  code: string
+  message: string
+}
+
+/** 统一结果：成功携带 data；失败携带 error（连接器不抛异常，调用方只处理一条错误路径） */
+export type Result<T> = { ok: true; data: T } | { ok: false; error: ConnectorError }
+
+/** query 成功结果：字段 schema + 行记录（契约 `{ fields, rows }` 归一化后） */
+export interface QueryResult {
+  fields: DatasetField[]
+  rows: Record<string, unknown>[]
+}
+
+/**
+ * 数据连接器（词汇表：Data Connector）：test / describe / query 三方法镜像 HTTP 契约三端点。
+ * 真实数据库访问由下游后端以任意语言实现（BYO）。
+ */
+export interface DataConnector {
+  test(connection: DataConnection): Promise<Result<void>>
+  describe(connection: DataConnection, sql: string): Promise<Result<DatasetField[]>>
+  query(connection: DataConnection, sql: string, values: ParamValues): Promise<Result<QueryResult>>
+}
+
+export interface CreateHttpConnectorOptions {
+  /** 契约端点前缀，如 `https://api.example.com/report`；三端点 = `{endpoint}/test|describe|query`（无版本段） */
+  endpoint: string
+}
+
+// ---- HTTP 契约响应形状（ADR-0003 决策 3）----
+// 传输层错误用 HTTP 状态码；业务错误一律 `200 + { ok: false, error }`。
+
+/** 契约字段 schema：`{ name, type? }`（type 缺省视为 string） */
+interface ContractField {
+  name: string
+  type?: DatasetField['type']
+}
+
+interface ContractErrorBody {
+  ok: false
+  error: ConnectorError
+}
+
+type TestResponseBody = { ok: true } | ContractErrorBody
+
+type DescribeResponseBody = { ok: true; fields: ContractField[] } | ContractErrorBody
+
+type QueryResponseBody =
+  | { ok: true; fields: ContractField[]; rows: Record<string, unknown>[] }
+  | ContractErrorBody
+
+/** 客户端错误：网络不可达 / 非 2xx / 响应不可解析（业务错误由服务端 200 透传） */
+function badResponse(message: string): Result<never> {
+  return { ok: false, error: { code: 'BAD_RESPONSE', message } }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function toConnectorError(value: unknown): ConnectorError {
+  if (isRecord(value)) {
+    const { code, message } = value
+    if (typeof code === 'string' && typeof message === 'string') {
+      return { code, message }
+    }
+  }
+  return { code: 'SERVER_ERROR', message: '服务端返回未知错误' }
+}
+
+/** 契约字段 → 内核 DatasetField（label 缺省回退 name，type 缺省 string） */
+function normalizeField(field: ContractField): DatasetField {
+  return { name: field.name, label: field.name, type: field.type ?? 'string' }
+}
+
+/** 校验并归一化契约 fields；形状不合法返回 null */
+function normalizeFields(fields: unknown): DatasetField[] | null {
+  if (!Array.isArray(fields)) return null
+  const normalized: DatasetField[] = []
+  for (const field of fields) {
+    if (!isRecord(field) || typeof field.name !== 'string') return null
+    normalized.push(normalizeField(field as unknown as ContractField))
+  }
+  return normalized
+}
+
+/**
+ * 创建 HTTP 数据连接器：三方法对应 `POST {endpoint}/test|describe|query`。
+ * - 请求体 JSON 序列化，`Content-Type: application/json`；
+ * - 网络异常与非 2xx（传输层错误）折叠为 `{ ok: false, error }`，不抛异常；
+ * - 业务错误（连接失败 / SQL 报错）由服务端以 `200 + { ok: false, error: { code, message } }` 返回并原样透传；
+ * - `describe` / `query` 的 fields 归一化为内核 `DatasetField`（label 回退 name，type 缺省 string）。
+ */
+export function createHttpConnector({ endpoint }: CreateHttpConnectorOptions): DataConnector {
+  async function postJson<TBody>(path: string, body: unknown): Promise<Result<TBody>> {
+    let response: Response
+    try {
+      response = await fetch(`${endpoint}${path}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body)
+      })
+    } catch (error) {
+      return {
+        ok: false,
+        error: {
+          code: 'NETWORK_ERROR',
+          message: error instanceof Error ? error.message : String(error)
+        }
+      }
+    }
+
+    if (!response.ok) {
+      return {
+        ok: false,
+        error: { code: `HTTP_${response.status}`, message: `请求失败（HTTP ${response.status}）` }
+      }
+    }
+
+    let payload: unknown
+    try {
+      payload = await response.json()
+    } catch {
+      return badResponse('响应不是合法 JSON')
+    }
+
+    if (!isRecord(payload)) return badResponse('响应不是 JSON 对象')
+    return { ok: true, data: payload as TBody }
+  }
+
+  return {
+    async test(connection) {
+      const result = await postJson<TestResponseBody>('/test', { connection })
+      if (!result.ok) return result
+      if (result.data.ok === true) return { ok: true, data: undefined }
+      return { ok: false, error: toConnectorError(result.data.error) }
+    },
+
+    async describe(connection, sql) {
+      const result = await postJson<DescribeResponseBody>('/describe', { connection, sql })
+      if (!result.ok) return result
+      if (result.data.ok !== true) {
+        return { ok: false, error: toConnectorError(result.data.error) }
+      }
+      const fields = normalizeFields(result.data.fields)
+      if (!fields) return badResponse('describe 响应缺少合法的 fields 数组')
+      return { ok: true, data: fields }
+    },
+
+    async query(connection, sql, values) {
+      const result = await postJson<QueryResponseBody>('/query', { connection, sql, values })
+      if (!result.ok) return result
+      if (result.data.ok !== true) {
+        return { ok: false, error: toConnectorError(result.data.error) }
+      }
+      const fields = normalizeFields(result.data.fields)
+      if (!fields) return badResponse('query 响应缺少合法的 fields 数组')
+      if (!Array.isArray(result.data.rows)) return badResponse('query 响应缺少 rows 数组')
+      return { ok: true, data: { fields, rows: result.data.rows } }
+    }
+  }
+}

package/src/report/export-xlsx.ts

@@ -0,0 +1,118 @@
+import type { Sheet } from '@veltra/sheet-core'
+import { rangeToHucre, styleToHucre } from '@veltra/sheet-core/core/io/export'
+import type { Cell, CellValue, ColumnDef, RowDef, WriteSheet } from 'hucre'
+import { writeXlsx } from 'hucre/xlsx'
+
+/** 列宽条目：模型列索引 → 像素宽（sheet-core 列宽未进 SheetSnapshot，导出时由调用方显式传入） */
+export type ReportColWidthEntry = readonly [number, number]
+
+/** 像素 → Excel points */
+function pxToPt(px: number): number {
+  return px * 0.75
+}
+
+/** VTable 像素列宽 → Excel 字符宽度（近似换算） */
+export function pxToExcelColWidth(px: number): number {
+  return Math.max(1, Math.round((px - 5) / 7))
+}
+
+/** 从列宽条目构建 hucre ColumnDef */
+export function buildColumnDefs(colWidths: ReadonlyArray<ReportColWidthEntry>): ColumnDef[] {
+  if (colWidths.length === 0) return []
+  const maxCol = Math.max(...colWidths.map(([col]) => col))
+  const columns: ColumnDef[] = Array.from({ length: maxCol + 1 }, () => ({}))
+  for (const [col, width] of colWidths) {
+    columns[col] = { width: pxToExcelColWidth(width) }
+  }
+  return columns
+}
+
+/**
+ * 将已填充的 Sheet（Filled Report）导出为保真 XLSX（合并 / 样式 / 行高 / 列宽）。
+ * 条件样式颜色已在 renderReport 展开阶段打平进 StylePool（ADR-0001 决策 2）。
+ *
+ * 与 `exportWorkbookXlsx`（sheet-core）的差异：列宽未进 SheetSnapshot，
+ * 只能经 VTable 运行时读取，故这里接收显式列宽并写入 columns 定义。
+ */
+export async function exportFilledReportXlsx(
+  sheet: Sheet,
+  colWidths: ReadonlyArray<ReportColWidthEntry>
+): Promise<Uint8Array> {
+  let maxRow = -1
+  let maxCol = -1
+  for (const [addr] of sheet.store.entries()) {
+    if (addr.row > maxRow) maxRow = addr.row
+    if (addr.col > maxCol) maxCol = addr.col
+  }
+  for (const [row] of sheet.getRowHeights()) {
+    if (row > maxRow) maxRow = row
+  }
+  for (const [col] of colWidths) {
+    if (col > maxCol) maxCol = col
+  }
+
+  const rows =
+    maxRow < 0
+      ? []
+      : Array.from({ length: maxRow + 1 }, () =>
+          Array.from({ length: maxCol + 1 }, () => null as CellValue)
+        )
+  const cells = new Map<string, Partial<Cell>>()
+
+  for (const [addr, data] of sheet.store.entries()) {
+    const row = rows[addr.row]!
+    const key = `${addr.row},${addr.col}`
+    const cell: Partial<Cell> = {}
+    if (data.s != null) {
+      const style = sheet.stylePool.get(data.s)
+      if (style) cell.style = styleToHucre(style)
+    }
+    if (data.f != null && data.f !== '') {
+      cell.formula = data.f
+      if (data.v != null) cell.formulaResult = data.v as CellValue
+      row[addr.col] = (data.v as CellValue) ?? null
+      cells.set(key, cell)
+      continue
+    }
+    if (data.t === 'e') {
+      cell.value = data.v as string
+      cell.type = 'error'
+      row[addr.col] = null
+      cells.set(key, cell)
+      continue
+    }
+    if (data.t === 'd') {
+      cell.value = data.v as number
+      cell.type = 'number'
+      cell.style = { ...cell.style, numFmt: 'yyyy-mm-dd' }
+      row[addr.col] = null
+      cells.set(key, cell)
+      continue
+    }
+    row[addr.col] = (data.v as CellValue) ?? null
+    if (Object.keys(cell).length > 0) cells.set(key, cell)
+  }
+
+  const writeSheet: WriteSheet = {
+    name: sheet.name || '报表',
+    rows,
+    ...(cells.size > 0 ? { cells } : {}),
+    ...(sheet.merges.size > 0
+      ? { merges: sheet.merges.getMerges().map((range) => rangeToHucre(range)) }
+      : {}),
+    ...(colWidths.length > 0 ? { columns: buildColumnDefs(colWidths) } : {})
+  }
+
+  const frozen = sheet.frozen
+  if (frozen.rows > 0 || frozen.cols > 0) {
+    writeSheet.freezePane = { rows: frozen.rows, columns: frozen.cols }
+  }
+
+  const rowDefs = new Map<number, RowDef>()
+  for (const [row, height] of sheet.getRowHeights()) {
+    rowDefs.set(row, { height: pxToPt(height) })
+  }
+  if (rowDefs.size > 0) writeSheet.rowDefs = rowDefs
+
+  return writeXlsx({ sheets: [writeSheet], activeSheet: 0 })
+}

package/src/report/filter-bar.ts

@@ -0,0 +1,36 @@
+import type { ParamValues } from './types'
+
+// Filter Bar 控件值规范化（自 playground filter-bar-helpers 平移，行为不变）
+
+function toParamString(value: unknown): string {
+  if (value == null || value === '') return ''
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+    return String(value)
+  }
+  return ''
+}
+
+/** 将运行时 date-range 参数值规范为 [from, to] 字符串元组 */
+export function parseDateRangeValue(raw: unknown): [string, string] {
+  if (Array.isArray(raw)) {
+    return [toParamString(raw[0]), toParamString(raw[1])]
+  }
+  if (raw && typeof raw === 'object') {
+    const obj = raw as Record<string, unknown>
+    return [toParamString(obj.from ?? obj.start), toParamString(obj.to ?? obj.end)]
+  }
+  return ['', '']
+}
+
+/** 将运行时 number 参数值规范为 UNumberInput 可接受的 number | undefined */
+export function resolveNumberParamValue(raw: unknown): number | undefined {
+  if (raw === '' || raw == null) return undefined
+  if (typeof raw === 'number' && Number.isFinite(raw)) return raw
+  const parsed = Number(raw)
+  return Number.isFinite(parsed) ? parsed : undefined
+}
+
+/** 合并单参数变更，保持其余参数值不变 */
+export function patchParamValues(values: ParamValues, id: string, value: unknown): ParamValues {
+  return { ...values, [id]: value }
+}

package/src/report/index.ts

@@ -0,0 +1,13 @@
+// 报表纯 TS 内核（ADR-0003 决策 1）：渲染引擎 / 绑定 / 条件规则 / 查询参数 / 数据连接器 /
+// Report Template（自包含模板与取数）/ Filter Bar 值规范化。
+// 框架无关、无 DOM 依赖；组件壳（UReportDesigner / UReportViewer）落 components/report/。
+
+export * from './types'
+export * from './binding'
+export * from './rules'
+export * from './params'
+export * from './render'
+export * from './connector'
+export * from './template'
+export * from './filter-bar'
+export * from './export-xlsx'