@open-mercato/ui 0.6.6-develop.6229.1.ebe6706732 → 0.6.6-develop.6245.1.2be3b151f8

package/src/backend/DataTable.tsx

@@ -34,7 +34,7 @@ import { resolveInjectedIcon } from './injection/resolveInjectedIcon'
 import { serializeExport, defaultExportFilename, type PreparedExport } from '@open-mercato/shared/lib/crud/exporters'
 import { apiCall, withScopedApiRequestHeaders } from './utils/apiCall'
 import { buildOptimisticLockHeader } from './utils/optimisticLock'
-import { surfaceRecordConflict } from './conflicts'
+import { useGuardedMutation } from './injection/useGuardedMutation'
 import { raiseCrudError } from './utils/serverErrors'
 import { PerspectiveSidebar } from './PerspectiveSidebar'
 import { Popover, PopoverTrigger, PopoverContent } from '../primitives/popover'
@@ -1716,6 +1716,27 @@ export function DataTable<T>({
   }
 
   const perspectiveQueryKey: [string, string | null] = ['table-perspectives', perspectiveTableId]
+
+  type PerspectiveMutationContext = {
+    formId: string
+    resourceKind: 'perspective'
+    retryLastMutation: () => Promise<boolean>
+  }
+  const perspectiveMutationContextId = `data-table-perspectives:${perspectiveTableId ?? 'unknown'}`
+  const { runMutation: runPerspectiveMutation, retryLastMutation: retryPerspectiveMutation } =
+    useGuardedMutation<PerspectiveMutationContext>({
+      contextId: perspectiveMutationContextId,
+      blockedMessage: t('ui.forms.flash.saveBlocked', 'Save blocked by validation'),
+    })
+  const perspectiveMutationContext = React.useMemo<PerspectiveMutationContext>(
+    () => ({
+      formId: perspectiveMutationContextId,
+      resourceKind: 'perspective',
+      retryLastMutation: retryPerspectiveMutation,
+    }),
+    [perspectiveMutationContextId, retryPerspectiveMutation],
+  )
+
   const savePerspectiveMutation = useMutation<PerspectiveSaveResponse, Error, SavePerspectivePayload>({
     mutationFn: async (input) => {
       if (!perspectiveTableId) throw new Error('Missing table id')
@@ -1734,26 +1755,32 @@ export function DataTable<T>({
       const existing = input.perspectiveId
         ? perspectiveData?.perspectives.find((p) => p.id === input.perspectiveId) ?? null
         : null
-      const call = await withScopedApiRequestHeaders(
-        buildOptimisticLockHeader(existing?.updatedAt ?? null),
-        () => apiCall<PerspectiveSaveResponse>(
-          `/api/perspectives/${encodeURIComponent(perspectiveTableId)}`,
-          {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify(payload),
-          },
-        ),
-      )
-      if (call.status === 404) {
-        throw new Error(t('ui.dataTable.perspectives.error.apiUnavailable', 'Perspectives API is not available. Run `yarn generate` to regenerate module routes and restart the dev server.'))
-      }
-      if (!call.ok) {
-        await raiseCrudError(call.response, t('ui.dataTable.perspectives.error.save', 'Failed to save perspective'))
-      }
-      const result = call.result
-      if (!result) throw new Error(t('ui.dataTable.perspectives.error.save', 'Failed to save perspective'))
-      return result
+      return runPerspectiveMutation({
+        operation: async () => {
+          const call = await withScopedApiRequestHeaders(
+            buildOptimisticLockHeader(existing?.updatedAt ?? null),
+            () => apiCall<PerspectiveSaveResponse>(
+              `/api/perspectives/${encodeURIComponent(perspectiveTableId)}`,
+              {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(payload),
+              },
+            ),
+          )
+          if (call.status === 404) {
+            throw new Error(t('ui.dataTable.perspectives.error.apiUnavailable', 'Perspectives API is not available. Run `yarn generate` to regenerate module routes and restart the dev server.'))
+          }
+          if (!call.ok) {
+            await raiseCrudError(call.response, t('ui.dataTable.perspectives.error.save', 'Failed to save perspective'))
+          }
+          const result = call.result
+          if (!result) throw new Error(t('ui.dataTable.perspectives.error.save', 'Failed to save perspective'))
+          return result
+        },
+        context: perspectiveMutationContext,
+        mutationPayload: payload,
+      })
     },
     onSuccess: (data) => {
       if (perspectiveTableId) {
@@ -1763,11 +1790,12 @@ export function DataTable<T>({
         applyPerspectiveSettings(data.perspective.settings, data.perspective.id)
       }
     },
-    onError: (error) => {
+    onError: () => {
+      // Conflict surfacing is handled inside `runPerspectiveMutation`
+      // (surfaceRecordConflict); only the cache refresh remains here.
       if (perspectiveTableId) {
         void queryClient.invalidateQueries({ queryKey: perspectiveQueryKey })
       }
-      surfaceRecordConflict(error, t)
     },
   })
 
@@ -1791,14 +1819,20 @@ export function DataTable<T>({
   const deletePerspectiveMutation = useMutation<void, Error, { perspectiveId: string }>({
     mutationFn: async ({ perspectiveId }) => {
       if (!perspectiveTableId) throw new Error('Missing table id')
-      const call = await apiCall(
-        `/api/perspectives/${encodeURIComponent(perspectiveTableId)}/${encodeURIComponent(perspectiveId)}`,
-        { method: 'DELETE' },
-      )
-      if (call.status === 404) throw new Error(t('ui.dataTable.perspectives.error.apiUnavailable', 'Perspectives API is not available. Run `yarn generate` and restart the dev server.'))
-      if (!call.ok) {
-        await raiseCrudError(call.response, t('ui.dataTable.perspectives.error.delete', 'Failed to delete perspective'))
-      }
+      await runPerspectiveMutation({
+        operation: async () => {
+          const call = await apiCall(
+            `/api/perspectives/${encodeURIComponent(perspectiveTableId)}/${encodeURIComponent(perspectiveId)}`,
+            { method: 'DELETE' },
+          )
+          if (call.status === 404) throw new Error(t('ui.dataTable.perspectives.error.apiUnavailable', 'Perspectives API is not available. Run `yarn generate` and restart the dev server.'))
+          if (!call.ok) {
+            await raiseCrudError(call.response, t('ui.dataTable.perspectives.error.delete', 'Failed to delete perspective'))
+          }
+        },
+        context: perspectiveMutationContext,
+        mutationPayload: { perspectiveId },
+      })
     },
     onMutate: ({ perspectiveId }) => {
       setDeletingIds((prev) => prev.includes(perspectiveId) ? prev : [...prev, perspectiveId])
@@ -1827,14 +1861,20 @@ export function DataTable<T>({
   const clearRoleMutation = useMutation<void, Error, { roleId: string }>({
     mutationFn: async ({ roleId }) => {
       if (!perspectiveTableId) throw new Error('Missing table id')
-      const call = await apiCall(
-        `/api/perspectives/${encodeURIComponent(perspectiveTableId)}/roles/${encodeURIComponent(roleId)}`,
-        { method: 'DELETE' },
-      )
-      if (call.status === 404) throw new Error(t('ui.dataTable.perspectives.error.apiUnavailable', 'Perspectives API is not available. Run `yarn generate` and restart the dev server.'))
-      if (!call.ok) {
-        await raiseCrudError(call.response, t('ui.dataTable.perspectives.error.clearRoles', 'Failed to clear role perspectives'))
-      }
+      await runPerspectiveMutation({
+        operation: async () => {
+          const call = await apiCall(
+            `/api/perspectives/${encodeURIComponent(perspectiveTableId)}/roles/${encodeURIComponent(roleId)}`,
+            { method: 'DELETE' },
+          )
+          if (call.status === 404) throw new Error(t('ui.dataTable.perspectives.error.apiUnavailable', 'Perspectives API is not available. Run `yarn generate` and restart the dev server.'))
+          if (!call.ok) {
+            await raiseCrudError(call.response, t('ui.dataTable.perspectives.error.clearRoles', 'Failed to clear role perspectives'))
+          }
+        },
+        context: perspectiveMutationContext,
+        mutationPayload: { roleId },
+      })
     },
     onMutate: ({ roleId }) => {
       setRoleClearingIds((prev) => prev.includes(roleId) ? prev : [...prev, roleId])

package/src/backend/__tests__/DataTable.perspectiveGuardedMutation.test.tsx

@@ -0,0 +1,263 @@
+/** @jest-environment jsdom */
+import * as React from 'react'
+import { DataTable } from '../DataTable'
+import type { ColumnDef } from '@tanstack/react-table'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { I18nProvider } from '@open-mercato/shared/lib/i18n/context'
+import { render, fireEvent, waitFor, screen } from '@testing-library/react'
+import { OPTIMISTIC_LOCK_HEADER_NAME } from '@open-mercato/shared/lib/crud/optimistic-lock-headers'
+import type { PerspectivesIndexResponse } from '@open-mercato/shared/modules/perspectives/types'
+
+jest.mock('next/navigation', () => ({
+  useRouter: () => ({ push: jest.fn(), replace: jest.fn(), prefetch: jest.fn() }),
+}))
+
+jest.mock('../injection/useInjectionDataWidgets', () => ({
+  useInjectionDataWidgets: () => ({ widgets: [], isLoading: false }),
+}))
+
+// The guarded-mutation hook is the contract under test: every perspective write
+// must be routed through `runMutation` so global mutation injections, record
+// locks, and conflict handling participate consistently.
+const mockRunMutation = jest.fn(
+  async ({ operation }: { operation: () => Promise<unknown> }) => operation(),
+)
+const mockRetryLastMutation = jest.fn(async () => false)
+jest.mock('../injection/useGuardedMutation', () => ({
+  useGuardedMutation: () => ({
+    runMutation: mockRunMutation,
+    retryLastMutation: mockRetryLastMutation,
+  }),
+}))
+
+// Capture the optimistic-lock headers attached to writes while keeping the call
+// flow real: `apiCall` is recorded, `withScopedApiRequestHeaders` records the
+// header bag and still runs the wrapped operation.
+const mockScopedHeaderCalls: Array<Record<string, string>> = []
+const mockApiCall = jest.fn(async (input: unknown, init?: { method?: string }) => {
+  const url = String(input)
+  const method = (init?.method ?? 'GET').toUpperCase()
+  const ok = (result: unknown) => ({
+    ok: true,
+    status: 200,
+    result,
+    response: { ok: true, status: 200 } as Response,
+    cacheStatus: null as const,
+  })
+  if (url.includes('/api/perspectives/') && method === 'POST') {
+    return ok({
+      perspective: {
+        id: 'persp-1',
+        name: 'My view',
+        tableId: 'test-table',
+        settings: {},
+        isDefault: false,
+        createdAt: 'now',
+        updatedAt: '2026-06-19T00:00:00.000Z',
+      },
+      rolePerspectives: [],
+      clearedRoleIds: [],
+    })
+  }
+  return ok(undefined)
+})
+jest.mock('../utils/apiCall', () => ({
+  apiCall: (...args: unknown[]) => mockApiCall(...(args as [unknown, { method?: string }?])),
+  withScopedApiRequestHeaders: async (
+    headers: Record<string, string>,
+    run: () => Promise<unknown>,
+  ) => {
+    mockScopedHeaderCalls.push(headers)
+    return run()
+  },
+}))
+
+type SidebarProps = {
+  onSave: (input: {
+    name: string
+    isDefault: boolean
+    applyToRoles: string[]
+    setRoleDefault: boolean
+    perspectiveId?: string | null
+    settings?: unknown
+  }) => void | Promise<void>
+  onDeletePerspective: (perspectiveId: string) => void | Promise<void>
+  onClearRole: (roleId: string) => void | Promise<void>
+}
+
+// Replace the heavy drawer UI with a stub exposing the three write handlers as
+// buttons, so the test drives the mutations without rendering the full sidebar.
+jest.mock('../PerspectiveSidebar', () => ({
+  PerspectiveSidebar: (props: SidebarProps) => (
+    <div>
+      <button
+        type="button"
+        data-testid="save-perspective"
+        onClick={() => {
+          void props.onSave({
+            name: 'My view',
+            isDefault: false,
+            applyToRoles: [],
+            setRoleDefault: false,
+            perspectiveId: 'persp-1',
+            settings: {
+              columnOrder: [],
+              columnVisibility: {},
+              filters: {},
+              sorting: [],
+              pageSize: 20,
+              searchValue: '',
+            },
+          })
+        }}
+      >
+        save
+      </button>
+      <button
+        type="button"
+        data-testid="delete-perspective"
+        onClick={() => {
+          void props.onDeletePerspective('persp-1')
+        }}
+      >
+        delete
+      </button>
+      <button
+        type="button"
+        data-testid="clear-role"
+        onClick={() => {
+          void props.onClearRole('role-1')
+        }}
+      >
+        clear
+      </button>
+    </div>
+  ),
+}))
+
+type Row = { id: string; name: string }
+
+const INDEX_RESPONSE: PerspectivesIndexResponse = {
+  tableId: 'test-table',
+  perspectives: [
+    {
+      id: 'persp-1',
+      name: 'My view',
+      tableId: 'test-table',
+      settings: {},
+      isDefault: false,
+      createdAt: 'now',
+      updatedAt: '2026-06-19T00:00:00.000Z',
+    },
+  ],
+  defaultPerspectiveId: null,
+  rolePerspectives: [],
+  roles: [{ id: 'role-1', name: 'Role 1', hasPerspective: false, hasDefault: false }],
+  canApplyToRoles: true,
+}
+
+function renderTable() {
+  const columns: ColumnDef<Row>[] = [{ accessorKey: 'name', header: 'Name' }]
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { staleTime: Infinity, gcTime: Infinity, retry: false },
+      mutations: { retry: false },
+    },
+  })
+  // Seed both perspective queries so the component renders the (mocked) sidebar
+  // without issuing any network fetch for them.
+  queryClient.setQueryData(['feature-check', 'perspectives'], { use: true, roleDefaults: true })
+  queryClient.setQueryData(['table-perspectives', 'test-table'], INDEX_RESPONSE)
+  const utils = render(
+    <QueryClientProvider client={queryClient}>
+      <I18nProvider locale="en" dict={{}}>
+        <DataTable
+          columns={columns}
+          data={[]}
+          perspective={{ tableId: 'test-table' }}
+        />
+      </I18nProvider>
+    </QueryClientProvider>,
+  )
+  return { ...utils, queryClient }
+}
+
+describe('DataTable perspective writes go through useGuardedMutation', () => {
+  beforeEach(() => {
+    mockRunMutation.mockClear()
+    mockRetryLastMutation.mockClear()
+    mockApiCall.mockClear()
+    mockScopedHeaderCalls.length = 0
+  })
+
+  it('routes perspective save through runMutation and keeps the optimistic-lock header', async () => {
+    const { queryClient } = renderTable()
+    try {
+      fireEvent.click(screen.getByTestId('save-perspective'))
+      await waitFor(() => expect(mockRunMutation).toHaveBeenCalledTimes(1))
+
+      const call = mockRunMutation.mock.calls[0][0] as {
+        operation: () => Promise<unknown>
+        context: Record<string, unknown>
+        mutationPayload?: Record<string, unknown>
+      }
+      expect(call.context.resourceKind).toBe('perspective')
+      expect(typeof call.context.retryLastMutation).toBe('function')
+
+      await waitFor(() =>
+        expect(mockApiCall).toHaveBeenCalledWith(
+          expect.stringContaining('/api/perspectives/test-table'),
+          expect.objectContaining({ method: 'POST' }),
+        ),
+      )
+      // The save still attaches the optimistic-lock header for the edited record.
+      expect(mockScopedHeaderCalls).toContainEqual({
+        [OPTIMISTIC_LOCK_HEADER_NAME]: '2026-06-19T00:00:00.000Z',
+      })
+    } finally {
+      queryClient.clear()
+    }
+  })
+
+  it('routes perspective delete through runMutation', async () => {
+    const { queryClient } = renderTable()
+    try {
+      fireEvent.click(screen.getByTestId('delete-perspective'))
+      await waitFor(() => expect(mockRunMutation).toHaveBeenCalledTimes(1))
+
+      const call = mockRunMutation.mock.calls[0][0] as { context: Record<string, unknown> }
+      expect(call.context.resourceKind).toBe('perspective')
+      expect(typeof call.context.retryLastMutation).toBe('function')
+
+      await waitFor(() =>
+        expect(mockApiCall).toHaveBeenCalledWith(
+          expect.stringContaining('/api/perspectives/test-table/persp-1'),
+          expect.objectContaining({ method: 'DELETE' }),
+        ),
+      )
+    } finally {
+      queryClient.clear()
+    }
+  })
+
+  it('routes role-clear through runMutation', async () => {
+    const { queryClient } = renderTable()
+    try {
+      fireEvent.click(screen.getByTestId('clear-role'))
+      await waitFor(() => expect(mockRunMutation).toHaveBeenCalledTimes(1))
+
+      const call = mockRunMutation.mock.calls[0][0] as { context: Record<string, unknown> }
+      expect(call.context.resourceKind).toBe('perspective')
+      expect(typeof call.context.retryLastMutation).toBe('function')
+
+      await waitFor(() =>
+        expect(mockApiCall).toHaveBeenCalledWith(
+          expect.stringContaining('/api/perspectives/test-table/roles/role-1'),
+          expect.objectContaining({ method: 'DELETE' }),
+        ),
+      )
+    } finally {
+      queryClient.clear()
+    }
+  })
+})

package/src/backend/__tests__/FieldDefinitionsEditor.test.tsx

@@ -1,6 +1,8 @@
 /**
  * @jest-environment jsdom
  */
+import * as fs from 'fs'
+import * as path from 'path'
 import { fireEvent, screen } from '@testing-library/react'
 import { renderWithProviders } from '@open-mercato/shared/lib/testing/renderWithProviders'
 import { FieldDefinitionsEditor, type FieldDefinition } from '../custom-fields/FieldDefinitionsEditor'
@@ -19,7 +21,22 @@ if (typeof window !== 'undefined') {
   }
 }
 
+const repoRoot = path.resolve(__dirname, '../../../../..')
+const readEditorSource = () =>
+  fs.readFileSync(path.join(repoRoot, 'packages/ui/src/backend/custom-fields/FieldDefinitionsEditor.tsx'), 'utf8')
+
 describe('FieldDefinitionsEditor', () => {
+  it('uses DS primitives and semantic status tokens for editor controls', () => {
+    const source = readEditorSource()
+
+    expect(source).not.toMatch(/<input\b/)
+    expect(source).not.toMatch(/<select\b/)
+    expect(source).not.toMatch(/<textarea\b/)
+    expect(source).not.toMatch(/\b(?:border-red|text-red|bg-amber|text-amber|text-blue)-\d{2,3}\b/)
+    expect(source).toMatch(/from ['"]\.\.\/\.\.\/primitives\/input['"]/)
+    expect(source).toMatch(/from ['"]\.\.\/\.\.\/primitives\/checkbox-field['"]/)
+  })
+
   it('assigns a field to a fieldset without triggering a render-time parent update warning', () => {
     const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {})
     const handleDefinitionChange = jest.fn()