@aiao/rxdb-model 0.0.19 → 0.0.26

package/src/entity-table/vtable/table-operations.ts

@@ -0,0 +1,123 @@
+import type * as VTable from '@visactor/vtable';
+import type { ListTableConstructorOptions } from '@visactor/vtable';
+import type { EntityTableRecord } from '../interfaces.js';
+import { isRowDragEnabled } from './table-row-move.js';
+
+declare const ngDevMode: boolean | undefined;
+
+/**
+ * HACK: VTable 不提供禁用特定行拖拽的 API，通过 monkey-patch 内部属性实现
+ *
+ * 只读行、新增行不给手柄；`setRowDragEnabled(table, false)` 之后所有行都不给。
+ *
+ * TODO(vtable-upstream): 跟踪 VTable 上游 API，一旦提供 per-row dragOrder 配置即可移除此 hack
+ * @see https://github.com/AgoraIO/vtable/issues — 搜索 "drag order per row"
+ * @param table 目标表格实例
+ */
+export function patchDragIconForReadonlyRows(table: VTable.ListTable): void {
+  const helper = (table as unknown as Record<string, unknown>)['internalProps'] as
+    { rowSeriesNumberHelper?: { getIcons: (col: number, row: number) => unknown[] } } | undefined;
+  if (!helper?.rowSeriesNumberHelper) {
+    if (typeof ngDevMode === 'undefined' || ngDevMode) {
+      console.warn('[entity-table] VTable internalProps.rowSeriesNumberHelper not found — drag icon patch skipped');
+    }
+    return;
+  }
+  const original = helper.rowSeriesNumberHelper.getIcons.bind(helper.rowSeriesNumberHelper);
+  helper.rowSeriesNumberHelper.getIcons = (col: number, row: number): unknown[] => {
+    if (!isRowDragEnabled(table)) return [];
+    const record = table.getRecordByCell(col, row) as EntityTableRecord | undefined;
+    if (record?._readonly || record?._isAddRow) return [];
+    return original(col, row);
+  };
+}
+
+/**
+ * 列头排序点击时 VTable 交出的状态
+ */
+export interface HeaderSortClick {
+  /** 被点击列的字段 */
+  readonly field: unknown;
+  /** 点击后的排序方向：`asc` → `desc` → `normal` 轮转 */
+  readonly order: unknown;
+}
+
+/**
+ * 同步列头排序图标，不执行客户端排序
+ *
+ * @param table - 目标表格实例
+ * @param click - `sort_click` 事件参数
+ *
+ * @remarks
+ * 业务层在 `sort_click` 里返回 `false` 阻止 VTable 客户端排序、改由查询重排；
+ * 但返回 `false` 也让 VTable 跳过记录排序状态，图标停在 normal，下一次点击又从 asc 起，
+ * 永远到不了 desc / normal。这里补记状态（`executeSort = false`），图标与轮转才正常。
+ *
+ * @example
+ * ```typescript
+ * table.on('sort_click', args => {
+ *   emitSort(args);
+ *   syncHeaderSortIcon(table, args);
+ *   return false;
+ * });
+ * ```
+ */
+export function syncHeaderSortIcon(table: VTable.ListTable, click: HeaderSortClick): void {
+  const { field, order } = click;
+  const sorted = typeof field === 'string' && field !== '' && (order === 'asc' || order === 'desc');
+  table.updateSortState(sorted ? { field, order } : null, false);
+}
+
+/**
+ * 收集拖拽排序后的非只读行 ID 列表
+ *
+ * @param table 目标表格实例
+ * @param idField 记录 ID 字段名
+ * @returns 按当前行顺序排列的非只读行 ID
+ */
+export function collectReorderedIds(table: VTable.ListTable, idField: string): string[] {
+  const rowCount = table.rowCount;
+  const orderedIds: string[] = [];
+  for (let row = 1; row < rowCount; row++) {
+    const record = table.getRecordByCell(0, row) as EntityTableRecord | undefined;
+    if (record && !record._readonly && !record._isAddRow) {
+      const id = record[idField];
+      if (typeof id === 'string') orderedIds.push(id);
+    }
+  }
+  return orderedIds;
+}
+
+/**
+ * 更新表格数据并恢复列宽（按 field 名匹配，容忍列增删）
+ *
+ * @param table 目标表格实例
+ * @param records 更新后的行数据
+ * @param prevColumns 更新前的列定义，用于读取旧列宽
+ * @param newColumns 更新后的列定义
+ */
+export function updateTableRecords(
+  table: VTable.ListTable,
+  records: EntityTableRecord[],
+  prevColumns: ListTableConstructorOptions['columns'],
+  newColumns: ListTableConstructorOptions['columns']
+): void {
+  const prevCols = prevColumns as { field?: string }[];
+  const colCount = table.colCount;
+  const widthByField = new Map<string, number>();
+  for (let col = 1; col < colCount; col++) {
+    const field = prevCols[col - 1]?.field;
+    if (field) widthByField.set(field, table.getColWidth(col));
+  }
+  table.setRecords(records);
+  if (newColumns) table.updateColumns(newColumns as never);
+  const newColDefs = newColumns as { field?: string }[] | undefined;
+  const newColCount = table.colCount;
+  for (let col = 1; col < newColCount; col++) {
+    const field = newColDefs?.[col - 1]?.field;
+    if (field) {
+      const w = widthByField.get(field);
+      if (w !== undefined) table.setColWidth(col, w);
+    }
+  }
+}

package/src/entity-table/vtable/table-row-move.ts

@@ -0,0 +1,122 @@
+/**
+ * @fileoverview 表格单行拖动的读取与动态开关（US-028 阶段 B）
+ *
+ * VTable 只在建表时读 `rowSeriesNumber.dragOrder`，之后改选项不生效；手柄是否出现由
+ * `rowSeriesNumberHelper.getIcons` 决定。所以建表时统一打开 `dragOrder`，再由
+ * {@link setRowDragEnabled} 记下的开关在 `patchDragIconForReadonlyRows` 打的补丁里收掉手柄。
+ */
+import type * as VTable from '@visactor/vtable';
+import type { EntityTableRecord } from '../interfaces.js';
+
+/**
+ * 单行拖放的结果：被拖行与它落点前后的邻居
+ *
+ * @remarks
+ * 形状对齐 `Repository.reorder(id, { prevId, nextId })`；落到首部时 `prevId` 为 `null`，
+ * 落到尾部时 `nextId` 为 `null`。只描述表格里看到的位置，是否允许落库由调用方决定。
+ */
+export interface RowMoveEvent {
+  /** 被拖动行的主键 */
+  readonly id: string;
+  /** 落点之前那一行的主键；落到首部为 `null` */
+  readonly prevId: string | null;
+  /** 落点之后那一行的主键；落到尾部为 `null` */
+  readonly nextId: string | null;
+}
+
+/**
+ * VTable `change_header_position` 事件参数中本模块用到的部分
+ */
+export interface HeaderPositionChange {
+  /** 拖动起点 */
+  readonly source: { readonly col: number; readonly row: number };
+  /** 放下后的位置 */
+  readonly target: { readonly col: number; readonly row: number };
+  /** 拖动的是行还是列 */
+  readonly movingColumnOrRow?: 'row' | 'column';
+}
+
+/** 第 0 行是表头，数据从第 1 行开始 */
+const FIRST_DATA_ROW = 1;
+
+const disabledTables = new WeakSet<VTable.ListTable>();
+
+const idAt = (table: VTable.ListTable, idField: string, row: number): string | null => {
+  if (row < FIRST_DATA_ROW || row >= table.rowCount) return null;
+  const id = (table.getRecordByCell(0, row) as EntityTableRecord | undefined)?.[idField];
+  return typeof id === 'string' ? id : null;
+};
+
+/**
+ * 从一次行拖放读出被拖行与落点邻居
+ *
+ * @param table - 已完成换位的表格实例（VTable 先 `changeRecordOrder` 再派发事件）
+ * @param idField - 记录主键字段名
+ * @param change - `change_header_position` 的事件参数
+ * @returns 拖的是列、原位放下或被拖行主键不是字符串时为 `null`
+ *
+ * @example
+ * ```typescript
+ * table.on('change_header_position', args => {
+ *   const move = readRowMove(table, 'id', args);
+ *   if (move) emitRowMoved(move);
+ * });
+ * ```
+ */
+export function readRowMove(
+  table: VTable.ListTable,
+  idField: string,
+  change: HeaderPositionChange
+): RowMoveEvent | null {
+  if (change.movingColumnOrRow === 'column' || change.source.row === change.target.row) return null;
+  const row = change.target.row;
+  const id = idAt(table, idField, row);
+  if (id === null) return null;
+  return { id, prevId: idAt(table, idField, row - 1), nextId: idAt(table, idField, row + 1) };
+}
+
+/**
+ * 运行时开关表格的行拖动手柄
+ *
+ * @param table - 目标表格实例（建表时需开启 `rowSeriesNumber.dragOrder`）
+ * @param enabled - `false` 时所有行都不显示手柄
+ *
+ * @remarks
+ * 只在状态真的变化时重建单元格；手柄的收起依赖 `patchDragIconForReadonlyRows` 已经打过补丁。
+ */
+export function setRowDragEnabled(table: VTable.ListTable, enabled: boolean): void {
+  if (enabled === isRowDragEnabled(table)) return;
+  if (enabled) disabledTables.delete(table);
+  else disabledTables.add(table);
+  table.renderWithRecreateCells();
+}
+
+/**
+ * 表格当前是否允许行拖动
+ *
+ * @param table - 目标表格实例
+ * @returns 未调用过 {@link setRowDragEnabled} 时为 `true`
+ */
+export function isRowDragEnabled(table: VTable.ListTable): boolean {
+  return !disabledTables.has(table);
+}
+
+/**
+ * 把表格行恢复成最近一次提交的顺序
+ *
+ * @param table - 目标表格实例
+ * @param records - 交给表格的那份记录数组（会被原地改回）
+ * @param committed - 最近一次 `setRecords` 时记下的顺序副本
+ *
+ * @remarks
+ * VTable 拖放换位是对传入数组原地 `splice`，交进去的记录数组此时已是拖后的顺序；
+ * 所以宿主组件每次交数据时要另存一份副本，失败或被拒时用它把数组改回去再重绘。
+ */
+export function restoreTableRecords(
+  table: VTable.ListTable,
+  records: EntityTableRecord[],
+  committed: readonly EntityTableRecord[]
+): void {
+  records.splice(0, records.length, ...committed);
+  table.setRecords(records);
+}

package/src/entity-table/vtable/table-theme.ts

@@ -0,0 +1,181 @@
+import * as VTable from '@visactor/vtable';
+import type { SwitchStyle } from '@visactor/vtable/es/ts-types/column/style.js';
+
+/** 系统字体栈 */
+const SYSTEM_FONT = `-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif`;
+
+/** daisyUI 主题 CSS 变量集合 */
+export interface CSSVariables {
+  /** 根背景色 */
+  rootBg: string;
+  /** base-100 面板背景色 */
+  base100: string;
+  /** base-200 次级背景色 */
+  base200: string;
+  /** base-300 边框/分隔线颜色 */
+  base300: string;
+  /** 基础内容文字色 */
+  baseContent: string;
+  /** 主色调 */
+  primary: string;
+  /** 主色调上的文字颜色 */
+  primaryContent: string;
+  /** 圆角尺寸 */
+  radiusBox: string;
+}
+
+/**
+ * 返回默认颜色集合
+ *
+ * @returns 内置默认主题色，作为无 CSS 变量环境下的兜底
+ */
+export function getDefaultColors(): CSSVariables {
+  return {
+    rootBg: '#fafbfc',
+    base100: '#ffffff',
+    base200: '#eef0f2',
+    base300: '#dcdee0',
+    baseContent: '#1e2328',
+    primary: '#167bff',
+    primaryContent: '#ffffff',
+    radiusBox: '20px'
+  };
+}
+
+/**
+ * 获取文档根元素的计算样式
+ *
+ * @returns 文档根元素计算样式；非浏览器环境（无 document）时返回 undefined
+ */
+export function getDocumentRootStyle(): Pick<CSSStyleDeclaration, 'getPropertyValue'> | undefined {
+  if (typeof document === 'undefined') {
+    return undefined;
+  }
+
+  return getComputedStyle(document.documentElement);
+}
+
+/**
+ * 读取单个 CSS 变量值，为空时回退到默认值
+ *
+ * @param name CSS 变量名
+ * @param fallback 变量缺失或为空时的回退值
+ * @param style 样式来源，默认取文档根元素计算样式
+ * @returns 变量值（已去除首尾空白）；无效或为空时返回 fallback
+ */
+export function getCSSVariableValue(
+  name: string,
+  fallback: string,
+  style: Pick<CSSStyleDeclaration, 'getPropertyValue'> | undefined = getDocumentRootStyle()
+): string {
+  return style?.getPropertyValue(name).trim() || fallback;
+}
+
+/**
+ * 判断当前文档是否处于暗色模式
+ *
+ * @returns data-theme=dark 或系统 prefers-color-scheme: dark 时为 true；非浏览器环境返回 false
+ */
+export function isDocumentDarkMode(): boolean {
+  if (typeof document === 'undefined') {
+    return false;
+  }
+
+  const theme = document.documentElement.getAttribute('data-theme');
+  if (theme === 'dark') return true;
+  if (theme === 'light') return false;
+
+  return (
+    typeof window !== 'undefined' &&
+    typeof window.matchMedia === 'function' &&
+    window.matchMedia('(prefers-color-scheme: dark)').matches
+  );
+}
+
+/**
+ * 从 CSS 自定义属性读取 daisyUI 主题色
+ *
+ * @returns 主题色集合；无 document 时返回默认色
+ */
+export function getCSSVariables(): CSSVariables {
+  const defaults = getDefaultColors();
+  const style = getDocumentRootStyle();
+
+  if (!style) {
+    return defaults;
+  }
+
+  return {
+    rootBg: getCSSVariableValue('--root-bg', defaults.rootBg, style),
+    base100: getCSSVariableValue('--color-base-100', defaults.base100, style),
+    base200: getCSSVariableValue('--color-base-200', defaults.base200, style),
+    base300: getCSSVariableValue('--color-base-300', defaults.base300, style),
+    baseContent: getCSSVariableValue('--color-base-content', defaults.baseContent, style),
+    primary: getCSSVariableValue('--color-primary', defaults.primary, style),
+    primaryContent: getCSSVariableValue('--color-primary-content', defaults.primaryContent, style),
+    radiusBox: getCSSVariableValue('--radius-box', defaults.radiusBox, style)
+  };
+}
+
+/**
+ * 基于 daisyUI CSS 变量构建 VTable 主题
+ *
+ * @param isDark 是否暗色模式
+ * @param cssVars 主题 CSS 变量集合
+ * @returns VTable 主题对象
+ */
+export function createTheme(isDark: boolean, cssVars: CSSVariables): ReturnType<typeof VTable.themes.DEFAULT.extends> {
+  const switchStyle: SwitchStyle = {
+    checkedFill: cssVars.primary,
+    uncheckedFill: isDark ? '#ffffff33' : '#00000033',
+    circleFill: isDark ? '#ffffffDD' : '#ffffffEE',
+    disableCheckedFill: isDark ? '#ffffff33' : '#00000033',
+    disableUncheckedFill: isDark ? '#ffffff11' : '#00000011'
+  };
+
+  return VTable.themes.DEFAULT.extends({
+    underlayBackgroundColor: cssVars.rootBg,
+    defaultStyle: {
+      borderColor: cssVars.base300,
+      color: cssVars.baseContent,
+      bgColor: cssVars.base100,
+      fontSize: 13,
+      fontFamily: SYSTEM_FONT
+    },
+    headerStyle: {
+      borderColor: cssVars.base300,
+      color: cssVars.baseContent,
+      bgColor: cssVars.base200,
+      fontSize: 13,
+      fontWeight: 600,
+      fontFamily: SYSTEM_FONT
+    },
+    bodyStyle: {
+      borderColor: cssVars.base300,
+      color: cssVars.baseContent,
+      bgColor: cssVars.base100,
+      hover: {
+        cellBgColor: cssVars.base200
+      }
+    },
+    frameStyle: {
+      borderColor: cssVars.base300,
+      borderLineWidth: 0.5
+    },
+    scrollStyle: {
+      scrollSliderColor: cssVars.base300,
+      scrollRailColor: cssVars.base200,
+      width: 8,
+      visible: 'scrolling',
+      hoverOn: true
+    },
+    selectionStyle: {
+      cellBorderColor: cssVars.primary,
+      cellBorderLineWidth: 2,
+      cellBgColor: `color-mix(in srgb, ${cssVars.primary} ${isDark ? '10' : '5'}%, transparent)`,
+      inlineRowBgColor: `color-mix(in srgb, ${cssVars.primary} ${isDark ? '5' : '2'}%, transparent)`,
+      inlineColumnBgColor: `color-mix(in srgb, ${cssVars.primary} ${isDark ? '5' : '2'}%, transparent)`
+    },
+    switchStyle
+  });
+}

package/src/entity-table/vtable/table-tooltip.ts

@@ -0,0 +1,70 @@
+import type * as VTable from '@visactor/vtable';
+import { getTableContainer } from './vtable-compat.js';
+
+/**
+ * 计算 tooltip 在页面上的绝对位置
+ *
+ * @param container tooltip 所在容器元素
+ * @param rect 单元格矩形信息（x/left、y/top、height/bottom）
+ * @returns 页面坐标（位于单元格下方）；容器、矩形或位置信息缺失时返回 null
+ */
+export function computeTooltipPosition(
+  container: HTMLElement | null | undefined,
+  rect: Record<string, number> | null | undefined
+): { x: number; y: number } | null {
+  if (!container || !rect || (typeof rect['x'] !== 'number' && typeof rect['left'] !== 'number')) return null;
+  const br = container.getBoundingClientRect();
+  const x = typeof rect['x'] === 'number' ? rect['x'] : (rect['left'] ?? 0);
+  const y = typeof rect['y'] === 'number' ? rect['y'] : (rect['top'] ?? 0);
+  const height =
+    typeof rect['height'] === 'number' ? rect['height']
+    : typeof rect['bottom'] === 'number' ? rect['bottom'] - y
+    : 20;
+  return { x: br.left + x, y: br.top + y + height + 4 };
+}
+
+/** 默认 tooltip 延迟（毫秒） */
+const DEFAULT_TOOLTIP_DELAY = 800;
+
+/** 单元格错误 tooltip 生命周期管理 */
+export class CellTooltipManager {
+  #timer: ReturnType<typeof setTimeout> | null = null;
+  #hoveredCell: { col: number; row: number } | null = null;
+
+  /** 延迟显示错误 tooltip */
+  showError(
+    table: VTable.ListTable,
+    col: number,
+    row: number,
+    content: string,
+    setTooltip: (tip: { x: number; y: number; content: string } | null) => void,
+    delay = DEFAULT_TOOLTIP_DELAY
+  ): void {
+    this.#hoveredCell = { col, row };
+    if (this.#timer !== null) clearTimeout(this.#timer);
+    this.#timer = setTimeout(() => {
+      if (this.#hoveredCell?.col !== col || this.#hoveredCell?.row !== row) return;
+      const containerEl = getTableContainer(table);
+      const rect = table.getCellRect(col, row) as unknown as Record<string, number> | undefined;
+      const pos = computeTooltipPosition(containerEl, rect);
+      setTooltip(pos ? { ...pos, content } : { x: 0, y: 0, content });
+    }, delay);
+  }
+
+  /** 隐藏 tooltip */
+  hide(setTooltip: (tip: null) => void): void {
+    if (this.#timer !== null) {
+      clearTimeout(this.#timer);
+      this.#timer = null;
+    }
+    this.#hoveredCell = null;
+    setTooltip(null);
+  }
+
+  /** 销毁时清理定时器 */
+  cleanup(): void {
+    if (this.#timer !== null) clearTimeout(this.#timer);
+    this.#timer = null;
+    this.#hoveredCell = null;
+  }
+}

package/src/entity-table/vtable/vtable-compat.ts

@@ -0,0 +1,84 @@
+import type * as VTable from '@visactor/vtable';
+
+/**
+ * VTable ListTable 类型补充工具
+ *
+ * VTable 官方类型未导出部分内部方法，此模块提供类型安全的包装器，
+ * 避免散落的 `as unknown as` 类型断言。
+ * 所有包装器在调用前做运行时 `in` 检查，VTable 版本升级移除 API 时安全降级。
+ */
+
+/**
+ * VTable rowSeriesNumber 列占据 col=0，数据列从 col=1 开始。
+ * 将 VTable 列索引映射到 columns 数组索引时需减此偏移。
+ */
+export const ROW_SERIES_COL_OFFSET = 1;
+
+type AnyTable = Record<string, unknown>;
+
+/**
+ * 设置 switch/checkbox/radio 单元格视觉状态
+ *
+ * @param table 目标表格实例
+ * @param col 列索引
+ * @param row 行索引
+ * @param value 目标布尔状态
+ */
+export function setCellSwitchState(table: VTable.ListTable, col: number, row: number, value: boolean): void {
+  const t = table as unknown as AnyTable;
+  if (typeof t['setCellSwitchState'] === 'function') {
+    (t['setCellSwitchState'] as (c: number, r: number, v: boolean) => void)(col, row, value);
+  }
+}
+
+/**
+ * 获取表格 DOM 容器元素
+ *
+ * @param table 目标表格实例
+ * @returns 容器元素；VTable 未提供该方法时返回 undefined
+ */
+export function getTableContainer(table: VTable.ListTable): HTMLElement | undefined {
+  const t = table as unknown as AnyTable;
+  if (typeof t['getContainer'] === 'function') {
+    return (t['getContainer'] as () => HTMLElement)();
+  }
+  return undefined;
+}
+
+/**
+ * 检查表格是否正在编辑中
+ *
+ * @param table 目标表格实例
+ * @returns 存在活动编辑器时为 true
+ */
+export function isTableEditing(table: VTable.ListTable): boolean {
+  const em = (table as unknown as AnyTable)['editorManager'] as AnyTable | undefined;
+  return !!em?.['editingEditor'];
+}
+
+/**
+ * 完成当前单元格编辑
+ *
+ * @param table 目标表格实例
+ */
+export function completeTableEdit(table: VTable.ListTable): void {
+  const em = (table as unknown as AnyTable)['editorManager'] as AnyTable | undefined;
+  if (em?.['editCell'] && typeof em['completeEdit'] === 'function') {
+    (em['completeEdit'] as () => void)();
+  }
+}
+
+/**
+ * 回写单元格值（不触发编辑事件）
+ *
+ * @param table 目标表格实例
+ * @param col 列索引
+ * @param row 行索引
+ * @param value 写入的值
+ */
+export function changeCellValue(table: VTable.ListTable, col: number, row: number, value: unknown): void {
+  const t = table as unknown as AnyTable;
+  if (typeof t['changeCellValue'] === 'function') {
+    (t['changeCellValue'] as (...args: unknown[]) => void)(col, row, value, false, false);
+  }
+}