From 6b5b33540fe80c6ea2842d0d5f969973ee1e8ceb Mon Sep 17 00:00:00 2001
From: t8y2 <1156263951@qq.com>
Date: Mon, 24 Aug 2026 18:22:10 +0000
Subject: [PATCH] feat(grid): show column defaults in new row placeholders

Closes #3096
---
 apps/desktop/src/components/grid/DataGrid.vue | 26 +++++---
 .../lib/dataGrid/canvasDataGridRenderer.ts    |  6 +-
 .../lib/dataGrid/dataGridColumnMetadata.ts    |  2 +-
 .../dataGrid/dataGridDefaultPlaceholder.ts    | 21 ++++++
 .../app-tests/dataGridBooleanColumn.test.ts   | 15 +++--
 .../dataGridDefaultPlaceholder.test.ts        | 64 +++++++++++++++++++
 6 files changed, 117 insertions(+), 17 deletions(-)
 create mode 100644 apps/desktop/src/lib/dataGrid/dataGridDefaultPlaceholder.ts
 create mode 100644 packages/app-tests/dataGridDefaultPlaceholder.test.ts

diff --git a/apps/desktop/src/components/grid/DataGrid.vue b/apps/desktop/src/components/grid/DataGrid.vue
index e0408d99e2..4662a75b1c 100644
--- a/apps/desktop/src/components/grid/DataGrid.vue
+++ b/apps/desktop/src/components/grid/DataGrid.vue
@@ -181,6 +181,7 @@ import {
 import { temporalCellEditorConfig, type TemporalCellEditorConfig } from "@/lib/dataGrid/dataGridTemporalEditor";
 import { BOOLEAN_CELL_EDITOR_VALUES, booleanCellEditorValue, isBooleanCellValue, isBooleanColumnType, isPointInBooleanCheckbox, nextBooleanCellValue, normalizeBooleanCellValue, parseBooleanCellEditorValue } from "@/lib/dataGrid/dataGridBooleanColumn";
 import { resolveDataGridColumnNullability, resolveDataGridColumnsByResultIndex } from "@/lib/dataGrid/dataGridColumnMetadata";
+import { resolveDataGridNewRowCellPlaceholder } from "@/lib/dataGrid/dataGridDefaultPlaceholder";
 import { isCancelSearchShortcut, isCopyCurrentRowShortcut, isDeleteCurrentRowShortcut, isFocusSearchShortcut, isModRShortcut, isSaveShortcut, isToggleTransposeShortcut } from "@/lib/editor/keyboardShortcuts";
 import { dataGridHeaderContentWidth, scrollbarGutterWidth } from "@/lib/dataGrid/dataGridScrollGutter";
 import { canFetchNextDataGridSegment, canGoNextDataGridPage, dataGridTotalRowCountLabelKey, dataGridTruncationHintKey, hasCompleteLocalDataGridResult, resolveDataGridPaginationTotal, type DataGridInexactTotalRowCountMode } from "@/lib/dataGrid/dataGridPagination";
@@ -6580,8 +6581,15 @@ function rowNumberText(item: RowItem | undefined): string {
   return String(item.displayIndex + 1 + rowNumberPageOffset());
 }
 
-function draftCellPlaceholder(item: RowItem | undefined, columnIndex: number): string | null {
-  return item?.isDraft && item.data[columnIndex] === null ? t("grid.quickEntryDraftPlaceholder") : null;
+const quickEntryDraftPlaceholder = computed(() => t("grid.quickEntryDraftPlaceholder"));
+
+function newRowCellPlaceholder(item: RowItem | undefined, columnIndex: number): string | null {
+  return resolveDataGridNewRowCellPlaceholder({
+    row: item,
+    columnIndex,
+    column: tableColumnsByResultIndex.value[columnIndex],
+    draftFallback: quickEntryDraftPlaceholder.value,
+  });
 }
 
 function columnTypeCacheSignature(): string {
@@ -7349,7 +7357,7 @@ function drawCanvasGrid() {
     searchMatchKeys: searchMatchSet.value,
     currentSearchMatch: currentSearchMatch.value,
     formatCell: (value, columnIndex, row) => formatCellCached(visibleLargeValuePreviewValue(row, columnIndex, value), columnIndex, largeValueOriginalBytes(row, columnIndex)),
-    draftCellPlaceholder: t("grid.quickEntryDraftPlaceholder"),
+    newRowCellPlaceholder,
     isRowActive,
     rowCellsUseSelectionVisual,
     cellIsSelected,
@@ -12036,8 +12044,8 @@ function currentGridContextMenuItems(): ContextMenuItem[] {
                         />
                       </template>
                       <template v-else>
-                        <template v-if="draftCellPlaceholder(displayItems[cell.recordIndex], cell.valueIndex)">
-                          <span class="text-muted-foreground/70 italic">{{ draftCellPlaceholder(displayItems[cell.recordIndex], cell.valueIndex) }}</span>
+                        <template v-if="newRowCellPlaceholder(displayItems[cell.recordIndex], cell.valueIndex)">
+                          <span class="text-muted-foreground/70 italic">{{ firstLineCellDisplayValue(newRowCellPlaceholder(displayItems[cell.recordIndex], cell.valueIndex) ?? "", flatteningMultiLineEnabled) }}</span>
                         </template>
                         <template v-else>{{ firstLineCellDisplayValue(cell.display, flatteningMultiLineEnabled) }}</template>
                         <div v-if="cellDetailButtonVisible(cell.recordIndex, cell.valueIndex)" class="absolute right-2 top-1/2 flex -translate-y-1/2 items-center gap-1">
@@ -12979,11 +12987,13 @@ function currentGridContextMenuItems(): ContextMenuItem[] {
                           </div>
                         </template>
                         <template v-else-if="booleanCellsUseCheckbox && isBooleanGridCell(item, col.actualColIdx) && item.data[col.actualColIdx] === null && canEditCellItem(item, col.actualColIdx)">
-                          <span class="italic text-muted-foreground cursor-pointer select-none" @click.stop="cycleBooleanGridCell(item, col.actualColIdx, $event)">{{ firstLineCellDisplayValue(formatCellCached(item.data[col.actualColIdx], col.actualColIdx), flatteningMultiLineEnabled) }}</span>
+                          <span class="italic text-muted-foreground cursor-pointer select-none" @click.stop="cycleBooleanGridCell(item, col.actualColIdx, $event)">{{
+                            firstLineCellDisplayValue(newRowCellPlaceholder(item, col.actualColIdx) ?? formatCellCached(item.data[col.actualColIdx], col.actualColIdx), flatteningMultiLineEnabled)
+                          }}</span>
                         </template>
                         <template v-else>
-                          <template v-if="draftCellPlaceholder(item, col.actualColIdx)">
-                            <span class="text-muted-foreground/70 italic">{{ draftCellPlaceholder(item, col.actualColIdx) }}</span>
+                          <template v-if="newRowCellPlaceholder(item, col.actualColIdx)">
+                            <span class="text-muted-foreground/70 italic">{{ firstLineCellDisplayValue(newRowCellPlaceholder(item, col.actualColIdx) ?? "", flatteningMultiLineEnabled) }}</span>
                           </template>
                           <template v-else>{{ firstLineCellDisplayValue(formatGridItemCell(item, col.actualColIdx), flatteningMultiLineEnabled) }}</template>
                           <div v-if="cellDetailButtonVisible(item.displayIndex, col.actualColIdx)" class="absolute right-2 top-1/2 flex -translate-y-1/2 items-center gap-1">
diff --git a/apps/desktop/src/lib/dataGrid/canvasDataGridRenderer.ts b/apps/desktop/src/lib/dataGrid/canvasDataGridRenderer.ts
index 109947fdd1..ae514ef64f 100644
--- a/apps/desktop/src/lib/dataGrid/canvasDataGridRenderer.ts
+++ b/apps/desktop/src/lib/dataGrid/canvasDataGridRenderer.ts
@@ -80,7 +80,7 @@ export interface DrawCanvasDataGridOptions {
   currentSearchMatch: CanvasSearchMatch | null;
   formatCell: (value: CellValue, columnIndex: number, row: CanvasDataGridRow) => string;
   columnIsBoolean?: (columnIndex: number) => boolean;
-  draftCellPlaceholder?: string;
+  newRowCellPlaceholder?: (row: CanvasDataGridRow, columnIndex: number) => string | null;
   isRowActive: (rowIndex: number) => boolean;
   rowCellsUseSelectionVisual: (rowId: number) => boolean;
   cellIsSelected: (rowIndex: number, visibleColIdx: number) => boolean;
@@ -340,7 +340,7 @@ export function drawCanvasDataGrid(options: DrawCanvasDataGridOptions) {
     searchMatchKeys,
     currentSearchMatch,
     formatCell,
-    draftCellPlaceholder,
+    newRowCellPlaceholder,
     isRowActive,
     rowCellsUseSelectionVisual,
     cellIsSelected,
@@ -577,7 +577,7 @@ export function drawCanvasDataGrid(options: DrawCanvasDataGridOptions) {
           ctx.stroke();
         }
       } else {
-        const rawDisplayText = item.isDraft && value === null ? (draftCellPlaceholder ?? "") : formatCell(value, actualColIdx, item);
+        const rawDisplayText = (value === null ? newRowCellPlaceholder?.(item, actualColIdx) : null) ?? formatCell(value, actualColIdx, item);
         const displayText = isEditingThisCell ? "" : firstLineCellDisplayValue(rawDisplayText, flatteningMultiLineEnabled);
         const text = isEditingThisCell ? displayText : fitCanvasText(ctx, displayText, cellMaxWidth, isBooleanNullCell ? "left" : isRightAlign ? "right" : "left");
         const anchorX = isBooleanNullCell ? alignCanvasPixel(drawX + colWidth / 2, scaleX) : textAnchorX;
diff --git a/apps/desktop/src/lib/dataGrid/dataGridColumnMetadata.ts b/apps/desktop/src/lib/dataGrid/dataGridColumnMetadata.ts
index a16c62050c..ab9d995373 100644
--- a/apps/desktop/src/lib/dataGrid/dataGridColumnMetadata.ts
+++ b/apps/desktop/src/lib/dataGrid/dataGridColumnMetadata.ts
@@ -14,7 +14,7 @@ export function resolveDataGridColumnsByResultIndex(options: { resultColumns: re
     if (!columnsByName.has(key)) columnsByName.set(key, column);
   }
   return options.resultColumns.map((resultColumn, index) => {
-    const columnName = options.sourceColumns?.[index] ?? resultColumn;
+    const columnName = options.sourceColumns ? options.sourceColumns[index] : resultColumn;
     return columnName ? columnsByName.get(columnName.toLowerCase()) : undefined;
   });
 }
diff --git a/apps/desktop/src/lib/dataGrid/dataGridDefaultPlaceholder.ts b/apps/desktop/src/lib/dataGrid/dataGridDefaultPlaceholder.ts
new file mode 100644
index 0000000000..d2a0eeb7c4
--- /dev/null
+++ b/apps/desktop/src/lib/dataGrid/dataGridDefaultPlaceholder.ts
@@ -0,0 +1,21 @@
+import type { CellValue } from "@/lib/dataGrid/cellValue";
+import type { ColumnInfo } from "@/types/database";
+
+export interface DataGridNewRowPlaceholderRow {
+  data: readonly CellValue[];
+  isNew: boolean;
+  isDraft?: boolean;
+}
+
+export function resolveDataGridNewRowCellPlaceholder(options: { row: DataGridNewRowPlaceholderRow | undefined; columnIndex: number; column: Pick<ColumnInfo, "column_default"> | undefined; draftFallback: string }): string | null {
+  const { row, columnIndex, column, draftFallback } = options;
+  if (!row || (!row.isNew && !row.isDraft) || row.data[columnIndex] !== null) return null;
+
+  const rawDefault = column?.column_default;
+  if (rawDefault != null) {
+    const normalizedDefault = rawDefault.trim();
+    if (normalizedDefault && normalizedDefault.toUpperCase() !== "NULL") return rawDefault;
+  }
+
+  return row.isDraft ? draftFallback : null;
+}
diff --git a/packages/app-tests/dataGridBooleanColumn.test.ts b/packages/app-tests/dataGridBooleanColumn.test.ts
index 65c20de948..5d60dd006a 100644
--- a/packages/app-tests/dataGridBooleanColumn.test.ts
+++ b/packages/app-tests/dataGridBooleanColumn.test.ts
@@ -79,18 +79,23 @@ test("parses explicit enum-style boolean selections", () => {
   assert.equal(parseBooleanCellEditorValue("maybe"), undefined);
 });
 
-test("indexes table metadata once and resolves source-column aliases", () => {
+test("indexes table metadata once and honors explicit source-column mappings", () => {
   const enabled = column("Enabled", "boolean");
   const displayName = column("DisplayName", "varchar");
-  const resolved = resolveDataGridColumnsByResultIndex({
+  const explicitlyMapped = resolveDataGridColumnsByResultIndex({
     resultColumns: ["enabled_alias", "DisplayName", "missing"],
     sourceColumns: ["enabled", undefined, undefined],
     tableColumns: [enabled, displayName],
   });
+  const inferred = resolveDataGridColumnsByResultIndex({
+    resultColumns: ["DisplayName"],
+    tableColumns: [enabled, displayName],
+  });
 
-  assert.equal(resolved[0], enabled);
-  assert.equal(resolved[1], displayName);
-  assert.equal(resolved[2], undefined);
+  assert.equal(explicitlyMapped[0], enabled);
+  assert.equal(explicitlyMapped[1], undefined);
+  assert.equal(explicitlyMapped[2], undefined);
+  assert.equal(inferred[0], displayName);
 });
 
 test("shows nullability only for query results with resolved column metadata", () => {
diff --git a/packages/app-tests/dataGridDefaultPlaceholder.test.ts b/packages/app-tests/dataGridDefaultPlaceholder.test.ts
new file mode 100644
index 0000000000..ef5e2d2df4
--- /dev/null
+++ b/packages/app-tests/dataGridDefaultPlaceholder.test.ts
@@ -0,0 +1,64 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { test } from "vitest";
+import { resolveDataGridColumnsByResultIndex } from "../../apps/desktop/src/lib/dataGrid/dataGridColumnMetadata.ts";
+import { resolveDataGridNewRowCellPlaceholder } from "../../apps/desktop/src/lib/dataGrid/dataGridDefaultPlaceholder.ts";
+import type { ColumnInfo } from "../../apps/desktop/src/types/database.ts";
+
+function column(name: string, columnDefault: string | null): ColumnInfo {
+  return {
+    name,
+    data_type: "text",
+    is_nullable: true,
+    column_default: columnDefault,
+    is_primary_key: false,
+    extra: null,
+  };
+}
+
+test("explicitly unmapped result columns do not fall back to matching aliases", () => {
+  const [resolved] = resolveDataGridColumnsByResultIndex({
+    resultColumns: ["created_at"],
+    sourceColumns: [undefined],
+    tableColumns: [column("created_at", "CURRENT_TIMESTAMP")],
+  });
+
+  assert.equal(resolved, undefined);
+});
+
+test("new and draft null cells preserve usable raw column defaults", () => {
+  const rawDefault = "  CURRENT_TIMESTAMP  ";
+  const mappedColumn = column("created_at", rawDefault);
+
+  assert.equal(resolveDataGridNewRowCellPlaceholder({ row: { data: [null], isNew: true }, columnIndex: 0, column: mappedColumn, draftFallback: "New" }), rawDefault);
+  assert.equal(resolveDataGridNewRowCellPlaceholder({ row: { data: [null], isNew: false, isDraft: true }, columnIndex: 0, column: mappedColumn, draftFallback: "New" }), rawDefault);
+});
+
+test("unusable defaults keep the existing new and draft fallbacks", () => {
+  for (const columnDefault of [null, "", "   ", "NULL", " nUlL "]) {
+    const mappedColumn = column("created_at", columnDefault);
+    assert.equal(resolveDataGridNewRowCellPlaceholder({ row: { data: [null], isNew: true }, columnIndex: 0, column: mappedColumn, draftFallback: "New" }), null);
+    assert.equal(resolveDataGridNewRowCellPlaceholder({ row: { data: [null], isNew: false, isDraft: true }, columnIndex: 0, column: mappedColumn, draftFallback: "New" }), "New");
+  }
+});
+
+test("existing nulls, explicit values, and unmapped new columns do not show schema defaults", () => {
+  const mappedColumn = column("created_at", "CURRENT_TIMESTAMP");
+
+  assert.equal(resolveDataGridNewRowCellPlaceholder({ row: { data: [null], isNew: false }, columnIndex: 0, column: mappedColumn, draftFallback: "New" }), null);
+  assert.equal(resolveDataGridNewRowCellPlaceholder({ row: { data: ["manual"], isNew: true }, columnIndex: 0, column: mappedColumn, draftFallback: "New" }), null);
+  assert.equal(resolveDataGridNewRowCellPlaceholder({ row: { data: [null], isNew: true }, columnIndex: 0, column: undefined, draftFallback: "New" }), null);
+  assert.equal(resolveDataGridNewRowCellPlaceholder({ row: { data: [null], isNew: false, isDraft: true }, columnIndex: 0, column: undefined, draftFallback: "New" }), "New");
+});
+
+test("DOM and canvas paths consume the same per-cell placeholder resolver", () => {
+  const dataGridSource = readFileSync(new URL("../../apps/desktop/src/components/grid/DataGrid.vue", import.meta.url), "utf8");
+  const canvasSource = readFileSync(new URL("../../apps/desktop/src/lib/dataGrid/canvasDataGridRenderer.ts", import.meta.url), "utf8");
+
+  assert.match(dataGridSource, /function newRowCellPlaceholder\(item: RowItem \| undefined, columnIndex: number\)/);
+  assert.match(dataGridSource, /newRowCellPlaceholder,\n\s+isRowActive/);
+  assert.match(dataGridSource, /newRowCellPlaceholder\(displayItems\[cell\.recordIndex\], cell\.valueIndex\)/);
+  assert.match(dataGridSource, /newRowCellPlaceholder\(item, col\.actualColIdx\)/);
+  assert.match(canvasSource, /newRowCellPlaceholder\?: \(row: CanvasDataGridRow, columnIndex: number\) => string \| null/);
+  assert.match(canvasSource, /newRowCellPlaceholder\?\.\(item, actualColIdx\)/);
+});