fix(grid): explain the import wizard's disabled Next and silent downgrade (#2640, #2639) (#2646)

#2640: the mapping step renders an inline hint listing every unmapped required field as `label (name)`, so a disabled Next button explains itself; the hint updates live and clears once the columns are supplied.

#2639: the scalar-only legacy per-row fallback is no longer silent — a new optional `ImportResult.degraded` flag drives a "compatibility fallback" notice on the completion screen. The pre-existing guard that refuses the fallback when relation columns are mapped (preventing raw natural keys in FK columns) is retained.

Component tests cover both paths.

Closes #2640
Closes #2639

Author: os-zhuang

.changeset/import-required-hint-and-downgrade-notice.md

@@ -0,0 +1,8 @@
+---
+"@object-ui/plugin-grid": patch
+---
+
+Import wizard: stop leaving the user at two silent dead-ends (surfaced during framework batch-write testing).
+
+- #2640 — the mapping step now renders an inline hint listing every required field that has no column mapped (as `label (name)`), so a disabled **Next** button always explains itself. The hint updates live with the mapping and clears once the columns are supplied; the disable logic itself is unchanged.
+- #2639 — when the server `/import` route is unavailable and the wizard downgrades to the legacy per-row `create` loop, the completion screen now shows a "compatibility fallback" notice (values written as-is, without server-side coercion) via a new optional `ImportResult.degraded` flag — the downgrade is no longer silent. The pre-existing guard that refuses the fallback when relation columns are mapped (which would otherwise write raw natural keys into FK columns) is retained.

packages/plugin-grid/src/ImportWizard.tsx

@@ -166,6 +166,12 @@ const IMPORT_DEFAULT_TRANSLATIONS: Record<string, string> = {
   'grid.import.required': 'Required',
   'grid.import.invalidType': 'Invalid {{type}}',
   'grid.import.legacyReferenceBlocked': 'Import blocked: {{fields}} are relation fields that need the server import route to resolve names into record IDs, and this connection doesn’t support it. Importing them as plain text would corrupt the data. Upgrade the backend/client, or unmap these columns and import them separately.',
+  // Shown in the mapping step when a required field has no column mapped — the
+  // reason the Next button is disabled. Field names are listed as `label (name)`.
+  'grid.import.missingRequiredHint': 'Can’t continue — required field(s) not mapped: {{fields}}. Add a matching column to your file, or go back and upload one that includes it.',
+  // Shown on the completion screen when the import ran via the legacy per-row
+  // fallback (server `/import` route unavailable) — no server-side coercion.
+  'grid.import.legacyFallbackNotice': 'Imported via a compatibility fallback: this connection doesn’t support the server import route, so values were saved as text without server-side type coercion. Upgrade the backend/client for full import support (type coercion and relation lookups).',
 };
 
 /** Apply `{{var}}` interpolation to a translation template. */
@@ -303,6 +309,11 @@ export interface ImportResult {
   resultsTruncated?: boolean;
   /** True when the user cancelled an in-flight async import job. */
   cancelled?: boolean;
+  /** True when the import ran via the legacy per-row `create` fallback because
+   *  the server `/import` route was unavailable — values are written as-is,
+   *  with no server-side type coercion or reference resolution. Surfaced on the
+   *  completion screen so a silent downgrade never passes for a full import. */
+  degraded?: boolean;
 }
 
 type WizardStep = 'upload' | 'mapping' | 'preview';
@@ -960,7 +971,10 @@ const StepMapping: React.FC<{
   activeMapping: SavedMapping | null;
   onSelectSavedMapping: (name: string) => void;
   onClearSavedMapping: () => void;
-}> = ({ headers, fields, mapping, onMappingChange, inferredTypes, suggestions, templates, selectedTemplateId, onSelectTemplate, onSaveTemplate, onDeleteTemplate, savedMappings, activeMapping, onSelectSavedMapping, onClearSavedMapping }) => {
+  /** Required fields with no column mapped — surfaced as an inline hint so the
+   *  disabled Next button always explains itself. */
+  missingRequired: ImportWizardProps['fields'];
+}> = ({ headers, fields, mapping, onMappingChange, inferredTypes, suggestions, templates, selectedTemplateId, onSelectTemplate, onSaveTemplate, onDeleteTemplate, savedMappings, activeMapping, onSelectSavedMapping, onClearSavedMapping, missingRequired }) => {
   const { t } = useImportTranslation();
   const usedFields = useMemo(() => new Set(Object.values(mapping)), [mapping]);
   const suggestionByCol = useMemo(() => {
@@ -1070,6 +1084,21 @@ const StepMapping: React.FC<{
         </TableBody>
       </Table>
       </div>
+      {missingRequired.length > 0 && (
+        <div
+          className="mt-3 flex items-start gap-2 rounded-md border border-amber-400/40 bg-amber-50 p-3 text-xs text-amber-900 dark:bg-amber-950/30 dark:text-amber-200"
+          data-testid="import-missing-required"
+        >
+          <AlertCircle className="mt-0.5 h-4 w-4 shrink-0" />
+          <span>
+            {t('grid.import.missingRequiredHint', {
+              fields: missingRequired
+                .map((f) => (f.label && f.label !== f.name ? `${f.label} (${f.name})` : f.name))
+                .join(', '),
+            })}
+          </span>
+        </div>
+      )}
       </>
       )}
     </div>
@@ -1756,7 +1785,10 @@ export const ImportWizard: React.FC<ImportWizardProps> = ({
       }
       setProgress(Math.round(((i + 1) / rows.length) * 100));
     }
-    const importResult: ImportResult = { totalRows: rows.length, importedRows, skippedRows, errors };
+    // `degraded`: this per-row path ran because the server `/import` route was
+    // unavailable — flag it so the completion screen tells the user the import
+    // was downgraded (no server-side coercion) instead of reporting a clean win.
+    const importResult: ImportResult = { totalRows: rows.length, importedRows, skippedRows, errors, degraded: true };
     setResult(importResult); setImporting(false); onComplete?.(importResult);
   }, [rows, mapping, fields, dataSource, objectName, onComplete, onErrorMode, corrections, t]);
 
@@ -2092,6 +2124,7 @@ export const ImportWizard: React.FC<ImportWizardProps> = ({
                 activeMapping={activeMapping}
                 onSelectSavedMapping={handleSelectSavedMapping}
                 onClearSavedMapping={handleClearSavedMapping}
+                missingRequired={missingRequired}
               />
             )}
             {step === 'preview' && (
@@ -2234,6 +2267,15 @@ export const ImportWizard: React.FC<ImportWizardProps> = ({
               )}
               {result.skippedRows > 0 && <Badge variant="destructive">{t('grid.import.skippedCount', { count: result.skippedRows })}</Badge>}
             </div>
+            {result.degraded && !result.cancelled && (
+              <div
+                className="flex w-full items-start gap-2 rounded-md border border-amber-400/40 bg-amber-50 p-3 text-xs text-amber-900 dark:bg-amber-950/30 dark:text-amber-200"
+                data-testid="import-degraded-notice"
+              >
+                <AlertCircle className="mt-0.5 h-4 w-4 shrink-0" />
+                <span>{t('grid.import.legacyFallbackNotice')}</span>
+              </div>
+            )}
             {renderResultExtra && (
               <div className="w-full" data-testid="import-result-extra">{renderResultExtra(result)}</div>
             )}

packages/plugin-grid/src/__tests__/importLegacyReferenceGuard.test.tsx

@@ -77,3 +77,21 @@ describe('ImportWizard legacy fallback: relation columns', () => {
     expect(onComplete.mock.calls[0][0].importedRows).toBe(1);
   });
 });
+
+describe('ImportWizard legacy fallback: downgrade is not silent (issue #2639)', () => {
+  it('flags the result degraded and shows a downgrade notice on the scalar path', async () => {
+    const create = vi.fn().mockResolvedValue({ id: '1' });
+    const onComplete = vi.fn();
+    // Scalar-only columns → the fallback runs (no importRecords) and succeeds,
+    // but the user must be told the server import route was unavailable.
+    await runWizardImport('Name\nAcme', { create }, onComplete);
+
+    await waitFor(() => expect(onComplete).toHaveBeenCalled());
+    expect(create).toHaveBeenCalledTimes(1);
+    // The result carries the downgrade flag...
+    expect(onComplete.mock.calls[0][0].degraded).toBe(true);
+    // ...and the completion screen surfaces it rather than reporting a clean win.
+    expect(screen.getByTestId('import-degraded-notice')).toBeInTheDocument();
+    expect(screen.getByText(/compatibility fallback/i)).toBeInTheDocument();
+  });
+});

packages/plugin-grid/src/__tests__/importMissingRequiredHint.test.tsx

@@ -0,0 +1,66 @@
+/**
+ * Missing-required-field hint — mapping step (issue #2640).
+ *
+ * When a required object field has no column mapped, the Next button is
+ * disabled. Without a hint the user faces a greyed-out button with no reason
+ * and no way to know which field is missing. The mapping step must list every
+ * unmapped required field (as `label (name)`) and clear the hint the moment the
+ * column is supplied — the disable logic itself stays put.
+ */
+import { describe, it, expect } from 'vitest';
+import { render, screen, fireEvent, waitFor, act } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import React from 'react';
+
+import { ImportWizard } from '../ImportWizard';
+
+// `status` is required but its label ("Lifecycle") differs from its api-name,
+// so the hint must show both — that's exactly the value a user needs to fix it.
+const FIELDS = [
+  { name: 'name', label: 'Name', type: 'text' },
+  { name: 'status', label: 'Lifecycle', type: 'text', required: true },
+];
+
+/** Paste TSV into the upload step via the wizard's window-level handler. */
+function pasteRows(text: string) {
+  const evt = new Event('paste', { bubbles: true, cancelable: true }) as Event & {
+    clipboardData: { getData: (type: string) => string };
+  };
+  evt.clipboardData = { getData: (type: string) => (type === 'text/plain' ? text : '') };
+  act(() => { window.dispatchEvent(evt); });
+}
+
+function renderWizard() {
+  render(
+    <ImportWizard objectName="account" fields={FIELDS} open onOpenChange={() => {}} />,
+  );
+}
+
+describe('ImportWizard mapping step: missing required-field hint', () => {
+  it('names each unmapped required field as `label (name)` and disables Next', async () => {
+    renderWizard();
+    // File omits the required `status` column — only `name` auto-maps.
+    pasteRows('Name\nAcme');
+
+    const hint = await screen.findByTestId('import-missing-required');
+    expect(hint).toHaveTextContent('Lifecycle (status)');
+    expect(screen.getByTestId('import-next-btn')).toBeDisabled();
+  });
+
+  it('clears the hint and enables Next once the required column is supplied', async () => {
+    renderWizard();
+    pasteRows('Name\nAcme');
+    await screen.findByTestId('import-missing-required');
+    expect(screen.getByTestId('import-next-btn')).toBeDisabled();
+
+    // Go back and re-upload a file that now carries the required column; the
+    // hint must react live to the new mapping, not require a remount.
+    fireEvent.click(screen.getByRole('button', { name: 'Back' }));
+    pasteRows('Name\tstatus\nAcme\tactive');
+
+    await waitFor(() => {
+      expect(screen.queryByTestId('import-missing-required')).not.toBeInTheDocument();
+    });
+    expect(screen.getByTestId('import-next-btn')).toBeEnabled();
+  });
+});