feat(diagram): show table and column comments on cards

This commit is contained in:
zipg authored and GitHub committed 2026-09-20 19:12:51 +08:00
1 parent a35ceb754e
commit 6aab94b3a8
12 files changed
+273 -55

No files matched your search

@@ -0,0 +1,69 @@
import { describe, expect, it } from "vitest";
import { CARD_BOTTOM_PADDING, CARD_HEADER_HEIGHT, COLUMN_ROW_HEIGHT, COMMENT_LINE_HEIGHT, diagramTableCardHeight, diagramVisibleColumns, tableCardHeight } from "@/lib/diagram/diagram-constants";
import type { DiagramTable } from "@/lib/diagram/erDiagram";
function table(overrides: Partial<DiagramTable> = {}): DiagramTable {
return {
name: "copy_src",
columns: [
{ name: "id", data_type: "bigint", is_nullable: false, column_default: null, is_primary_key: true, extra: null },
{ name: "name", data_type: "varchar(64)", is_nullable: true, column_default: null, is_primary_key: false, extra: null },
],
foreignKeys: [],
...overrides,
};
}
describe("diagramTableCardHeight", () => {
it("matches the plain card height when nothing has a comment", () => {
expect(diagramTableCardHeight(table())).toBe(tableCardHeight(2));
expect(diagramTableCardHeight(table())).toBe(CARD_HEADER_HEIGHT + 2 * COLUMN_ROW_HEIGHT + CARD_BOTTOM_PADDING);
});
it("adds one line for the table comment", () => {
expect(diagramTableCardHeight(table({ comment: "订单主表" }))).toBe(tableCardHeight(2) + COMMENT_LINE_HEIGHT);
});
it("adds one line per commented column", () => {
const commented = table({
columns: [
{ name: "id", data_type: "bigint", is_nullable: false, column_default: null, is_primary_key: true, extra: null, comment: "主键ID" },
{ name: "name", data_type: "varchar(64)", is_nullable: true, column_default: null, is_primary_key: false, extra: null, comment: "下单人" },
],
});
expect(diagramTableCardHeight(commented)).toBe(tableCardHeight(2) + 2 * COMMENT_LINE_HEIGHT);
const withTableComment = table({ ...commented, comment: "测试用表" });
expect(diagramTableCardHeight(withTableComment)).toBe(tableCardHeight(2) + 3 * COMMENT_LINE_HEIGHT);
});
it("ignores blank and missing comments", () => {
const blank = table({
comment: " ",
columns: [
{ name: "id", data_type: "bigint", is_nullable: false, column_default: null, is_primary_key: true, extra: null, comment: "" },
{ name: "name", data_type: "varchar(64)", is_nullable: true, column_default: null, is_primary_key: false, extra: null, comment: "\n" },
],
});
expect(diagramTableCardHeight(blank)).toBe(tableCardHeight(2));
expect(diagramTableCardHeight(table({ comment: null }))).toBe(tableCardHeight(2));
});
it("does not count columns marked for DROP COLUMN", () => {
const dropped = table({
columns: [
{ name: "id", data_type: "bigint", is_nullable: false, column_default: null, is_primary_key: true, extra: null, comment: "主键ID" },
{ name: "note", data_type: "text", is_nullable: true, column_default: null, is_primary_key: false, extra: null, comment: "备注" },
],
droppedColumnNames: ["note"],
});
expect(diagramVisibleColumns(dropped).map((column) => column.name)).toEqual(["id"]);
expect(diagramTableCardHeight(dropped)).toBe(tableCardHeight(2) + COMMENT_LINE_HEIGHT);
});
it("honours caller-supplied card metrics", () => {
const commented = table({ comment: "备注" });
expect(diagramTableCardHeight(commented, { cardHeaderHeight: 44, columnRowHeight: 24, cardBottomPadding: 12, commentLineHeight: 10 })).toBe(tableCardHeight(2) + 10);
expect(tableCardHeight(3, { columnRowHeight: 10 })).toBe(CARD_HEADER_HEIGHT + 30 + CARD_BOTTOM_PADDING);
});
});
@@ -39,8 +39,47 @@ export const LAYER_CONTENT_PADDING = 20;
export const EMPTY_LAYER_WIDTH = 240;
export const EMPTY_LAYER_HEIGHT = LAYER_HEADER_HEIGHT + LAYER_CONTENT_PADDING;
export function tableCardHeight(columnCount: number): number {
return CARD_HEADER_HEIGHT + columnCount * COLUMN_ROW_HEIGHT + CARD_BOTTOM_PADDING;
/** Extra card height for one rendered comment line (table comment / column comment). */
export const COMMENT_LINE_HEIGHT = 16;
/** Card metrics that callers (e.g. the SVG exporter) may override. */
export interface DiagramCardMetrics {
cardHeaderHeight?: number;
columnRowHeight?: number;
cardBottomPadding?: number;
commentLineHeight?: number;
}
export function tableCardHeight(columnCount: number, metrics: DiagramCardMetrics = {}): number {
return (metrics.cardHeaderHeight ?? CARD_HEADER_HEIGHT) + columnCount * (metrics.columnRowHeight ?? COLUMN_ROW_HEIGHT) + (metrics.cardBottomPadding ?? CARD_BOTTOM_PADDING);
}
/** Minimal shape needed to size a card that renders table/column comments. */
export interface DiagramCommentedTable {
comment?: string | null;
columns: readonly { name: string; comment?: string | null }[];
/** Columns marked for DROP COLUMN stay in `columns` but are not rendered. */
droppedColumnNames?: readonly string[];
}
function hasText(value: string | null | undefined): boolean {
return typeof value === "string" && value.trim().length > 0;
}
/** Columns actually rendered on the canvas, in card order. */
export function diagramVisibleColumns<T extends { name: string }>(table: { columns: readonly T[]; droppedColumnNames?: readonly string[] }): T[] {
const dropped = table.droppedColumnNames ?? [];
return table.columns.filter((column) => !dropped.some((name) => name === column.name));
}
/**
* Card height including the table comment line and the per-column comment lines,
* so the canvas bounds, layer boxes, edge routing and auto layout all agree with
* what `TableNode` renders.
*/
export function diagramTableCardHeight(table: DiagramCommentedTable, metrics: DiagramCardMetrics = {}): number {
const commentLines = (hasText(table.comment) ? 1 : 0) + diagramVisibleColumns(table).filter((column) => hasText(column.comment)).length;
return tableCardHeight(table.columns.length, metrics) + commentLines * (metrics.commentLineHeight ?? COMMENT_LINE_HEIGHT);
}
/** LTR wrap column count from available canvas width (at least 1). */
+8 -7
View File
@@ -1,6 +1,6 @@
import ELK from "elkjs/lib/elk.bundled.js";
import type { LayoutOptions, DiagramNode, DiagramEdge, DiagramLayer } from "@/types/diagram";
import { CARD_WIDTH, COLUMN_ROW_HEIGHT, CARD_HEADER_HEIGHT, CARD_BOTTOM_PADDING, LAYER_PADDING, LAYER_HEADER_HEIGHT } from "./diagram-constants";
import { CARD_WIDTH, LAYER_PADDING, LAYER_HEADER_HEIGHT, diagramTableCardHeight, tableCardHeight, type DiagramCommentedTable } from "./diagram-constants";
import { handlesFromWaypoints, type Point } from "./edge-obstacle-router";
const elk = new ELK();
@@ -45,8 +45,9 @@ export interface LayerLayoutInfo {
height: number;
}
function calculateTableHeight(tableColumns: unknown[]): number {
return CARD_HEADER_HEIGHT + tableColumns.length * COLUMN_ROW_HEIGHT + CARD_BOTTOM_PADDING;
function calculateTableHeight(table?: DiagramCommentedTable): number {
if (!table) return tableCardHeight(0);
return diagramTableCardHeight(table);
}
export async function computeLayout(nodes: DiagramNode[], edges: DiagramEdge[], options: LayoutOptions = {}): Promise<{ nodes: DiagramNode[]; edges: DiagramEdge[] }> {
@@ -121,7 +122,7 @@ export async function computeLayoutWithLayers(nodes: DiagramNode[], edges: Diagr
const pos = positionMap.get(tableName) || node?.position;
if (!pos) continue;
hasAny = true;
const height = calculateTableHeight(node?.data?.table?.columns || []);
const height = calculateTableHeight(node?.data?.table);
minX = Math.min(minX, pos.x);
minY = Math.min(minY, pos.y);
maxX = Math.max(maxX, pos.x + CARD_WIDTH);
@@ -173,7 +174,7 @@ function buildElkGraph(nodes: DiagramNode[], edges: DiagramEdge[]): ElkGraph {
const elkNodes: ElkNode[] = nodes.map((node) => ({
id: node.id,
width: CARD_WIDTH,
height: calculateTableHeight(node.data?.table?.columns || []),
height: calculateTableHeight(node.data?.table),
}));
const elkEdges: ElkEdge[] = edges.map((edge) => ({
@@ -200,7 +201,7 @@ function buildHierarchicalElkGraph(nodes: DiagramNode[], edges: DiagramEdge[], a
const elkTableNodes = layerTables.map((tableNode) => ({
id: tableNode.id,
width: CARD_WIDTH,
height: calculateTableHeight(tableNode.data?.table?.columns || []),
height: calculateTableHeight(tableNode.data?.table),
}));
layerTables.forEach((n) => tableIdSet.add(n.id));
@@ -221,7 +222,7 @@ function buildHierarchicalElkGraph(nodes: DiagramNode[], edges: DiagramEdge[], a
const unassignedElkNodes = unassignedNodes.map((node) => ({
id: node.id,
width: CARD_WIDTH,
height: calculateTableHeight(node.data?.table?.columns || []),
height: calculateTableHeight(node.data?.table),
}));
return {
@@ -17,6 +17,8 @@ export function editableStructureIndexes(table: DiagramTable): EditableStructure
export interface DiagramTable {
name: string;
schema?: string;
/** Table description (`TABLE_COMMENT` and friends); rendered under the card title. */
comment?: string | null;
columns: ColumnInfo[];
foreignKeys: ForeignKeyInfo[];
/** Unique/PK indexes used for FK cardinality; drafts also sync via buildCreateTableSql */
@@ -2,7 +2,7 @@ import type { DiagramLayer } from "@/types/diagram";
import type { DiagramPosition, DiagramTable } from "@/lib/diagram/erDiagram";
import { layoutDiagramTables } from "@/lib/diagram/erDiagram";
import { sizeLayerToFit } from "@/lib/diagram/size-layer";
import { CARD_WIDTH, EMPTY_LAYER_HEIGHT, EMPTY_LAYER_WIDTH, GAP_X, GAP_Y, LAYER_CONTENT_PADDING, LAYER_HEADER_HEIGHT, MARGIN, columnsPerRowForWidth, tableCardHeight } from "@/lib/diagram/diagram-constants";
import { CARD_WIDTH, EMPTY_LAYER_HEIGHT, EMPTY_LAYER_WIDTH, GAP_X, GAP_Y, LAYER_CONTENT_PADDING, LAYER_HEADER_HEIGHT, MARGIN, columnsPerRowForWidth, diagramTableCardHeight } from "@/lib/diagram/diagram-constants";
export interface LtrAutoLayoutInput {
tables: DiagramTable[];
@@ -30,7 +30,8 @@ type LayerBox = {
function tableHeightsMap(tables: DiagramTable[]): Record<string, number> {
const heights: Record<string, number> = {};
for (const table of tables) {
heights[table.name] = tableCardHeight(table.columns?.length ?? 0);
// Comment lines are part of the rendered card, so layers and row wrapping include them.
heights[table.name] = diagramTableCardHeight(table);
}
return heights;
}
+37 -23
View File
@@ -2,7 +2,7 @@ import type { EngineeringDiagram, EngineeringEntityNode } from "@/lib/diagram/en
import { isDroppedColumn, type DiagramPosition, type DiagramRelationship, type DiagramTable } from "@/lib/diagram/erDiagram";
import { pickHandles } from "@/lib/diagram/vue-flow-adapter";
import { pointAlongPolyline, pointsToSvgPath, type Point } from "@/lib/diagram/edge-obstacle-router";
import { CARD_BOTTOM_PADDING, CARD_HEADER_HEIGHT, CARD_WIDTH, COLUMN_ROW_HEIGHT, MARGIN } from "@/lib/diagram/diagram-constants";
import { CARD_WIDTH, COMMENT_LINE_HEIGHT, MARGIN, diagramTableCardHeight, tableCardHeight, type DiagramCardMetrics } from "@/lib/diagram/diagram-constants";
const SOURCE_CARDINALITY_T = 0.18;
const TARGET_CARDINALITY_T = 0.82;
@@ -39,6 +39,11 @@ function tableExportKey(table: DiagramSvgTable): string {
return table.diagramKey || table.name;
}
/** Comments are optional metadata; blank/whitespace-only values render nothing. */
function commentText(value: string | null | undefined): string {
return typeof value === "string" ? value.trim() : "";
}
/** Columns the card actually renders: pending-drop columns are hidden on the canvas too. */
function tableExportColumns(table: DiagramTable): DiagramTable["columns"] {
return table.columns.filter((column) => !isDroppedColumn(table, column.name));
@@ -56,15 +61,11 @@ export interface TableDiagramSvgOptions {
cardHeaderHeight: number;
columnRowHeight: number;
cardBottomPadding?: number;
/** Extra height for a rendered table/column comment line. */
commentLineHeight?: number;
layers?: DiagramSvgLayer[];
}
type CardHeightMetrics = {
cardHeaderHeight: number;
columnRowHeight: number;
cardBottomPadding?: number;
};
function escapeXml(value: string | number): string {
return String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
}
@@ -101,11 +102,6 @@ function svgText(
return `<text ${attrs.join(" ")}>${escapeXml(label)}</text>`;
}
/** Shared table card height for SVG canvas / paths / cards. */
function svgCardHeight(columnCount: number, metrics: CardHeightMetrics): number {
return metrics.cardHeaderHeight + columnCount * metrics.columnRowHeight + (metrics.cardBottomPadding ?? CARD_BOTTOM_PADDING);
}
function isForeignKeyColumn(table: DiagramTable, columnName: string): boolean {
return table.foreignKeys.some((fk) => fk.column === columnName);
}
@@ -137,6 +133,7 @@ type RelationshipGeometryInput = {
cardHeaderHeight?: number;
columnRowHeight?: number;
cardBottomPadding?: number;
commentLineHeight?: number;
};
/**
@@ -144,16 +141,17 @@ type RelationshipGeometryInput = {
*/
export function buildTableRelationshipPolylines(input: RelationshipGeometryInput): Record<string, Point[]> {
const cardWidth = input.cardWidth ?? CARD_WIDTH;
const metrics: CardHeightMetrics = {
cardHeaderHeight: input.cardHeaderHeight ?? CARD_HEADER_HEIGHT,
columnRowHeight: input.columnRowHeight ?? COLUMN_ROW_HEIGHT,
cardBottomPadding: input.cardBottomPadding ?? CARD_BOTTOM_PADDING,
const metrics: DiagramCardMetrics = {
cardHeaderHeight: input.cardHeaderHeight,
columnRowHeight: input.columnRowHeight,
cardBottomPadding: input.cardBottomPadding,
commentLineHeight: input.commentLineHeight,
};
// Relationships address tables by their diagram id, cards by their table; index both so the
// routed edges match the drawn card heights in multi-schema mode too.
const heightByName = new Map<string, number>();
for (const table of input.tables) {
const height = svgCardHeight(tableExportColumns(table).length, metrics);
const height = diagramTableCardHeight(table, metrics);
heightByName.set(tableExportKey(table), height);
heightByName.set(table.name, height);
}
@@ -168,8 +166,8 @@ export function buildTableRelationshipPolylines(input: RelationshipGeometryInput
const sourcePos = input.positions[rel.sourceTable];
const targetPos = input.positions[rel.targetTable];
if (!sourcePos || !targetPos) continue;
const sh = heightByName.get(rel.sourceTable) ?? svgCardHeight(0, metrics);
const th = heightByName.get(rel.targetTable) ?? svgCardHeight(0, metrics);
const sh = heightByName.get(rel.sourceTable) ?? tableCardHeight(0, metrics);
const th = heightByName.get(rel.targetTable) ?? tableCardHeight(0, metrics);
polylines[rel.id] = orthogonalPointsBetweenTables(sourcePos, targetPos, sh, th, cardWidth);
}
return polylines;
@@ -196,6 +194,7 @@ export function computeTableDiagramCanvas(
cardHeaderHeight: number;
columnRowHeight: number;
cardBottomPadding?: number;
commentLineHeight?: number;
layers?: DiagramSvgLayer[];
relationshipPolylines?: Record<string, Point[]>;
padding?: number;
@@ -221,7 +220,7 @@ export function computeTableDiagramCanvas(
for (const table of tables) {
const pos = positions[tableExportKey(table)] ?? positions[table.name] ?? { x: 0, y: 0 };
const height = svgCardHeight(tableExportColumns(table).length, options);
const height = diagramTableCardHeight(table, options);
expand(pos.x, pos.y, pos.x + options.cardWidth, pos.y + height);
}
@@ -304,7 +303,7 @@ export function buildTableDiagramSvg(options: TableDiagramSvgOptions): string {
for (const table of options.tables) {
const position = options.positions[tableExportKey(table)] ?? options.positions[table.name] ?? { x: 0, y: 0 };
const columns = tableExportColumns(table);
const height = svgCardHeight(columns.length, options);
const height = diagramTableCardHeight(table, options);
const showSchema = Boolean(table.schema) && tableExportKey(table) !== table.name;
const nameY = options.cardHeaderHeight / 2 + (showSchema ? 6 : 0);
parts.push(`<g transform="translate(${svgNumber(position.x)} ${svgNumber(position.y)})">`);
@@ -323,8 +322,17 @@ export function buildTableDiagramSvg(options: TableDiagramSvgOptions): string {
}),
);
columns.forEach((column, index) => {
const rowTop = options.cardHeaderHeight + index * options.columnRowHeight;
const commentLineHeight = options.commentLineHeight ?? COMMENT_LINE_HEIGHT;
let rowTop = options.cardHeaderHeight;
const tableComment = commentText(table.comment);
if (tableComment) {
parts.push(`<rect x="0" y="${svgNumber(rowTop)}" width="${options.cardWidth}" height="${svgNumber(commentLineHeight)}" fill="#fafafa"/>`);
parts.push(`<path d="M 0 ${svgNumber(rowTop)} H ${options.cardWidth}" stroke="#e4e4e7"/>`);
parts.push(svgText(tableComment, 36, rowTop + commentLineHeight / 2, { size: 9, fill: "#71717a" }));
rowTop += commentLineHeight;
}
columns.forEach((column) => {
const rowCenter = rowTop + options.columnRowHeight / 2;
parts.push(`<path d="M 0 ${svgNumber(rowTop)} H ${options.cardWidth}" stroke="#f0f0f1"/>`);
if (column.is_primary_key) {
@@ -340,6 +348,12 @@ export function buildTableDiagramSvg(options: TableDiagramSvgOptions): string {
anchor: "end",
}),
);
rowTop += options.columnRowHeight;
const columnComment = commentText(column.comment);
if (columnComment) {
parts.push(svgText(columnComment, 38, rowTop + commentLineHeight / 2, { size: 9, fill: "#71717a" }));
rowTop += commentLineHeight;
}
});
parts.push("</g>");
}