@open-mercato/ui 0.6.6-develop.6229.1.ebe6706732 → 0.6.6-develop.6241.1.47c01ad4ed

package/dist/primitives/icon-button.js

@@ -7,6 +7,8 @@ const iconButtonVariants = cva(
   {
     variants: {
       variant: {
+        primary: "bg-primary text-primary-foreground shadow-xs hover:bg-primary-hover",
+        destructive: "bg-destructive text-white shadow-xs hover:bg-destructive/90",
         outline: "border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50",
         ghost: "hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50",
         white: "bg-background text-muted-foreground shadow-xs hover:bg-accent hover:text-accent-foreground",

package/dist/primitives/icon-button.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/primitives/icon-button.tsx"],
-  "sourcesContent": ["import * as React from 'react'\nimport { Slot } from '@radix-ui/react-slot'\nimport { cva, type VariantProps } from 'class-variance-authority'\nimport { cn } from '@open-mercato/shared/lib/utils'\n\nconst iconButtonVariants = cva(\n  \"inline-flex items-center justify-center cursor-pointer transition-all outline-none disabled:pointer-events-none disabled:bg-bg-disabled disabled:text-text-disabled disabled:border-border-disabled disabled:shadow-none [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 [&_svg]:shrink-0 focus-visible:outline-none focus-visible:shadow-focus aria-pressed:bg-primary aria-pressed:text-primary-foreground aria-pressed:hover:bg-primary-hover\",\n  {\n    variants: {\n      variant: {\n        outline:\n          'border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50',\n        ghost: 'hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50',\n        white:\n          'bg-background text-muted-foreground shadow-xs hover:bg-accent hover:text-accent-foreground',\n        modifiable:\n          'bg-transparent text-current hover:bg-foreground/10',\n      },\n      size: {\n        xs: 'size-6',\n        sm: 'size-7',\n        default: 'size-8',\n        lg: 'size-9',\n      },\n      fullRadius: {\n        true: 'rounded-full',\n        false: 'rounded-md',\n      },\n    },\n    defaultVariants: {\n      variant: 'outline',\n      size: 'default',\n      fullRadius: false,\n    },\n  }\n)\n\nexport function IconButton({\n  className,\n  variant,\n  size,\n  fullRadius,\n  asChild = false,\n  ...props\n}: React.ComponentProps<'button'> &\n  VariantProps<typeof iconButtonVariants> & { asChild?: boolean }) {\n  const Comp = asChild ? Slot : 'button'\n  return (\n    <Comp\n      data-slot=\"icon-button\"\n      type={asChild ? undefined : 'button'}\n      className={cn(iconButtonVariants({ variant, size, fullRadius, className }))}\n      {...props}\n    />\n  )\n}\n\nexport { iconButtonVariants }\n"],
-  "mappings": "AAgDI;AA/CJ,SAAS,YAAY;AACrB,SAAS,WAA8B;AACvC,SAAS,UAAU;AAEnB,MAAM,qBAAqB;AAAA,EACzB;AAAA,EACA;AAAA,IACE,UAAU;AAAA,MACR,SAAS;AAAA,QACP,SACE;AAAA,QACF,OAAO;AAAA,QACP,OACE;AAAA,QACF,YACE;AAAA,MACJ;AAAA,MACA,MAAM;AAAA,QACJ,IAAI;AAAA,QACJ,IAAI;AAAA,QACJ,SAAS;AAAA,QACT,IAAI;AAAA,MACN;AAAA,MACA,YAAY;AAAA,QACV,MAAM;AAAA,QACN,OAAO;AAAA,MACT;AAAA,IACF;AAAA,IACA,iBAAiB;AAAA,MACf,SAAS;AAAA,MACT,MAAM;AAAA,MACN,YAAY;AAAA,IACd;AAAA,EACF;AACF;AAEO,SAAS,WAAW;AAAA,EACzB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,UAAU;AAAA,EACV,GAAG;AACL,GACmE;AACjE,QAAM,OAAO,UAAU,OAAO;AAC9B,SACE;AAAA,IAAC;AAAA;AAAA,MACC,aAAU;AAAA,MACV,MAAM,UAAU,SAAY;AAAA,MAC5B,WAAW,GAAG,mBAAmB,EAAE,SAAS,MAAM,YAAY,UAAU,CAAC,CAAC;AAAA,MACzE,GAAG;AAAA;AAAA,EACN;AAEJ;",
+  "sourcesContent": ["import * as React from 'react'\nimport { Slot } from '@radix-ui/react-slot'\nimport { cva, type VariantProps } from 'class-variance-authority'\nimport { cn } from '@open-mercato/shared/lib/utils'\n\nconst iconButtonVariants = cva(\n  \"inline-flex items-center justify-center cursor-pointer transition-all outline-none disabled:pointer-events-none disabled:bg-bg-disabled disabled:text-text-disabled disabled:border-border-disabled disabled:shadow-none [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 [&_svg]:shrink-0 focus-visible:outline-none focus-visible:shadow-focus aria-pressed:bg-primary aria-pressed:text-primary-foreground aria-pressed:hover:bg-primary-hover\",\n  {\n    variants: {\n      variant: {\n        primary:\n          'bg-primary text-primary-foreground shadow-xs hover:bg-primary-hover',\n        destructive:\n          'bg-destructive text-white shadow-xs hover:bg-destructive/90',\n        outline:\n          'border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50',\n        ghost: 'hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50',\n        white:\n          'bg-background text-muted-foreground shadow-xs hover:bg-accent hover:text-accent-foreground',\n        modifiable:\n          'bg-transparent text-current hover:bg-foreground/10',\n      },\n      size: {\n        xs: 'size-6',\n        sm: 'size-7',\n        default: 'size-8',\n        lg: 'size-9',\n      },\n      fullRadius: {\n        true: 'rounded-full',\n        false: 'rounded-md',\n      },\n    },\n    defaultVariants: {\n      variant: 'outline',\n      size: 'default',\n      fullRadius: false,\n    },\n  }\n)\n\nexport function IconButton({\n  className,\n  variant,\n  size,\n  fullRadius,\n  asChild = false,\n  ...props\n}: React.ComponentProps<'button'> &\n  VariantProps<typeof iconButtonVariants> & { asChild?: boolean }) {\n  const Comp = asChild ? Slot : 'button'\n  return (\n    <Comp\n      data-slot=\"icon-button\"\n      type={asChild ? undefined : 'button'}\n      className={cn(iconButtonVariants({ variant, size, fullRadius, className }))}\n      {...props}\n    />\n  )\n}\n\nexport { iconButtonVariants }\n"],
+  "mappings": "AAoDI;AAnDJ,SAAS,YAAY;AACrB,SAAS,WAA8B;AACvC,SAAS,UAAU;AAEnB,MAAM,qBAAqB;AAAA,EACzB;AAAA,EACA;AAAA,IACE,UAAU;AAAA,MACR,SAAS;AAAA,QACP,SACE;AAAA,QACF,aACE;AAAA,QACF,SACE;AAAA,QACF,OAAO;AAAA,QACP,OACE;AAAA,QACF,YACE;AAAA,MACJ;AAAA,MACA,MAAM;AAAA,QACJ,IAAI;AAAA,QACJ,IAAI;AAAA,QACJ,SAAS;AAAA,QACT,IAAI;AAAA,MACN;AAAA,MACA,YAAY;AAAA,QACV,MAAM;AAAA,QACN,OAAO;AAAA,MACT;AAAA,IACF;AAAA,IACA,iBAAiB;AAAA,MACf,SAAS;AAAA,MACT,MAAM;AAAA,MACN,YAAY;AAAA,IACd;AAAA,EACF;AACF;AAEO,SAAS,WAAW;AAAA,EACzB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,UAAU;AAAA,EACV,GAAG;AACL,GACmE;AACjE,QAAM,OAAO,UAAU,OAAO;AAC9B,SACE;AAAA,IAAC;AAAA;AAAA,MACC,aAAU;AAAA,MACV,MAAM,UAAU,SAAY;AAAA,MAC5B,WAAW,GAAG,mBAAmB,EAAE,SAAS,MAAM,YAAY,UAAU,CAAC,CAAC;AAAA,MACzE,GAAG;AAAA;AAAA,EACN;AAEJ;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/ui",
-  "version": "0.6.6-develop.6229.1.ebe6706732",
+  "version": "0.6.6-develop.6241.1.47c01ad4ed",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -155,13 +155,13 @@
     "remark-gfm": "^4.0.1"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.6.6-develop.6229.1.ebe6706732",
+    "@open-mercato/shared": "0.6.6-develop.6241.1.47c01ad4ed",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",
     "react-is": ">=18.0.0"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.6-develop.6229.1.ebe6706732",
+    "@open-mercato/shared": "0.6.6-develop.6241.1.47c01ad4ed",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.1",

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/primitives/__tests__/icon-button.test.tsx

@@ -0,0 +1,40 @@
+/** @jest-environment jsdom */
+
+import * as React from 'react'
+import { render } from '@testing-library/react'
+import { IconButton, iconButtonVariants } from '../icon-button'
+
+describe('IconButton solid variants', () => {
+  // Regression for issue #3507 (BUG-003): the timesheets TimerBar Start/Stop
+  // icon buttons used `variant="outline"` and forced their fill via a
+  // `bg-primary`/`bg-destructive` className. The outline variant ships a
+  // `dark:bg-input/30` override that tailwind-merge cannot reconcile with a
+  // base `bg-*` class, so in dark mode the intended solid fill was replaced by
+  // the muted input surface and the dark `text-primary-foreground` play icon
+  // became near-invisible. The fix is a proper solid `primary`/`destructive`
+  // variant with NO `dark:` background override.
+
+  it('primary variant applies the solid primary surface without a dark override', () => {
+    const classes = iconButtonVariants({ variant: 'primary' })
+    expect(classes).toContain('bg-primary')
+    expect(classes).toContain('text-primary-foreground')
+    expect(classes).not.toContain('dark:bg-input')
+  })
+
+  it('destructive variant applies the solid destructive surface without a dark override', () => {
+    const classes = iconButtonVariants({ variant: 'destructive' })
+    expect(classes).toContain('bg-destructive')
+    expect(classes).not.toContain('dark:bg-input')
+  })
+
+  it('renders the primary fill on the element so the icon keeps contrast in both themes', () => {
+    const { getByRole } = render(
+      <IconButton variant="primary" aria-label="Start timer">
+        <svg />
+      </IconButton>,
+    )
+    const className = getByRole('button').className
+    expect(className).toContain('bg-primary')
+    expect(className).not.toContain('dark:bg-input')
+  })
+})

package/src/primitives/icon-button.tsx

@@ -8,6 +8,10 @@ const iconButtonVariants = cva(
   {
     variants: {
       variant: {
+        primary:
+          'bg-primary text-primary-foreground shadow-xs hover:bg-primary-hover',
+        destructive:
+          'bg-destructive text-white shadow-xs hover:bg-destructive/90',
         outline:
           'border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50',
         ghost: 'hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50',