@open-mercato/ui 0.6.4-develop.4382.1.6b4f656b77 → 0.6.4

package/src/backend/detail/RecordNotFoundState.tsx

@@ -2,8 +2,10 @@
 
 import * as React from "react";
 import Link from "next/link";
+import { SearchX } from "lucide-react";
 import { Button } from "@open-mercato/ui/primitives/button";
-import { ErrorMessage } from "./ErrorMessage";
+import { EmptyState } from "@open-mercato/ui/primitives/empty-state";
+import { formatErrorMessageLabel } from "./ErrorMessage";
 import { cn } from "@open-mercato/shared/lib/utils";
 import { useT } from "@open-mercato/shared/lib/i18n/context";
 
@@ -13,6 +15,8 @@ export type RecordNotFoundStateProps = {
   backHref?: string;
   backLabel?: string;
   action?: React.ReactNode;
+  /** Optional leading icon. Defaults to a neutral "search / not found" glyph. */
+  icon?: React.ReactNode;
   className?: string;
 };
 
@@ -22,12 +26,13 @@ export function RecordNotFoundState({
   backHref,
   backLabel,
   action,
+  icon,
   className,
 }: RecordNotFoundStateProps) {
   const t = useT();
   const defaultAction = backHref ? (
     <Button asChild variant="outline" size="sm">
-      <Link href={backHref}>{backLabel ?? t('ui.recordNotFound.backToList','Back to list')}</Link>
+      <Link href={backHref}>{backLabel ?? t('ui.recordNotFound.backToList', 'Back to list')}</Link>
     </Button>
   ) : null;
 
@@ -38,10 +43,12 @@ export function RecordNotFoundState({
         className,
       )}
     >
-      <ErrorMessage
-        label={label}
-        description={description}
-        action={action ?? defaultAction}
+      <EmptyState
+        variant="subtle"
+        icon={icon ?? <SearchX className="h-6 w-6" aria-hidden />}
+        title={formatErrorMessageLabel(label)}
+        description={description ? formatErrorMessageLabel(description) : undefined}
+        actions={action ?? defaultAction}
       />
     </div>
   );

package/src/backend/detail/__tests__/RecordNotFoundState.test.tsx

@@ -0,0 +1,80 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import * as React from 'react'
+import { render, screen } from '@testing-library/react'
+import { RecordNotFoundState } from '../RecordNotFoundState'
+
+jest.mock('@open-mercato/shared/lib/i18n/context', () => ({
+  useT: () => (_key: string, fallback?: string) => fallback ?? _key,
+}))
+
+jest.mock('next/link', () => {
+  const React = require('react')
+  return React.forwardRef(
+    ({ children, href, ...rest }: any, ref: React.ForwardedRef<HTMLAnchorElement>) => (
+      <a href={typeof href === 'string' ? href : href?.toString?.()} ref={ref} {...rest}>
+        {children}
+      </a>
+    ),
+  )
+})
+
+describe('RecordNotFoundState', () => {
+  it('renders the label as the empty-state title', () => {
+    render(<RecordNotFoundState label="Company not found." />)
+    expect(screen.getByText('Company not found.')).toBeInTheDocument()
+  })
+
+  it('renders a back link (role=link) with the given href and default label', () => {
+    render(<RecordNotFoundState label="Company not found." backHref="/backend/customers/companies" />)
+    const backLink = screen.getByRole('link', { name: /back to list/i })
+    expect(backLink).toBeInTheDocument()
+    expect(backLink).toHaveAttribute('href', '/backend/customers/companies')
+  })
+
+  it('uses a custom backLabel when provided', () => {
+    render(
+      <RecordNotFoundState
+        label="Company not found."
+        backHref="/backend/customers/companies"
+        backLabel="Back to companies"
+      />,
+    )
+    expect(screen.getByRole('link', { name: /back to companies/i })).toBeInTheDocument()
+  })
+
+  it('renders a custom action instead of the default back link', () => {
+    render(
+      <RecordNotFoundState
+        label="Company not found."
+        backHref="/ignored"
+        action={<button type="button">Retry</button>}
+      />,
+    )
+    expect(screen.getByRole('button', { name: 'Retry' })).toBeInTheDocument()
+    expect(screen.queryByRole('link')).not.toBeInTheDocument()
+  })
+
+  it('renders no action when neither backHref nor action is provided', () => {
+    render(<RecordNotFoundState label="Company not found." />)
+    expect(screen.queryByRole('link')).not.toBeInTheDocument()
+    expect(screen.queryByRole('button')).not.toBeInTheDocument()
+  })
+
+  it('is a neutral empty state, not a destructive alert (regression guard for #2127)', () => {
+    render(<RecordNotFoundState label="Company not found." backHref="/backend/customers/companies" />)
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument()
+  })
+
+  it('renders a custom icon when provided', () => {
+    render(
+      <RecordNotFoundState
+        label="Company not found."
+        icon={<svg data-testid="custom-icon" />}
+      />,
+    )
+    expect(screen.getByTestId('custom-icon')).toBeInTheDocument()
+  })
+})

package/src/backend/filters/AdvancedFilterPanel.tsx

@@ -295,6 +295,33 @@ export function AdvancedFilterPanel(props: AdvancedFilterPanelProps) {
     props.onOpenChange(false)
   }
 
+  const { onFlush, onOpenChange, open } = props
+
+  React.useEffect(() => {
+    if (!open || pickerOpen || saveDialogOpen) return
+    const closeOnEscape = (event: KeyboardEvent) => {
+      if (event.key !== 'Escape') return
+      // Do NOT gate on `event.defaultPrevented`. Radix keeps a just-closed
+      // dropdown's dismissable layer mounted while its exit animation plays, and
+      // that layer still calls preventDefault() on Escape. Picking a value in the
+      // operator/value Select therefore leaves a layer that swallows the next
+      // Escape, so the panel never closes and the active-filter chips never render
+      // (regression seen on loaded standalone CI runners where the exit-animation
+      // unmount is delayed). Instead, only defer Escape to an inner dropdown that
+      // is *actually* open — a Radix Select trigger flips aria-expanded to "false"
+      // synchronously on selection, so a closing-but-animating dropdown is no
+      // longer treated as open here.
+      if (typeof document !== 'undefined'
+        && document.querySelector('[role="combobox"][aria-expanded="true"]')) {
+        return
+      }
+      onOpenChange(false)
+      onFlush?.()
+    }
+    window.addEventListener('keydown', closeOnEscape)
+    return () => window.removeEventListener('keydown', closeOnEscape)
+  }, [onFlush, onOpenChange, open, pickerOpen, saveDialogOpen])
+
   React.useEffect(() => {
     if (!savedFilterStorageKey) {
       setSavedFilters([])

package/src/backend/filters/FilteredEmptyResults.tsx

@@ -9,27 +9,40 @@ export type FilteredEmptyResultsProps = {
   canRemoveLast: boolean
   onClearAll: () => void
   onRemoveLast: () => void
+  /**
+   * When provided, a search is ALSO active alongside the filters. Switches the
+   * copy to a combined search+filter message and makes the primary action clear
+   * both the search and the filters (so a single click shows everyone).
+   */
+  onClearSearch?: () => void
 }
 
-export function FilteredEmptyResults({ entityNamePlural, canRemoveLast, onClearAll, onRemoveLast }: FilteredEmptyResultsProps) {
+export function FilteredEmptyResults({ entityNamePlural, canRemoveLast, onClearAll, onRemoveLast, onClearSearch }: FilteredEmptyResultsProps) {
   const t = useT()
+  const searchActive = typeof onClearSearch === 'function'
+  const title = searchActive
+    ? t('ui.advancedFilter.empty.noMatchesSearchFilters', 'No {entity} match your search and filters', { entity: entityNamePlural })
+    : t('ui.advancedFilter.empty.noMatches', 'No {entity} match these filters', { entity: entityNamePlural })
+  const description = searchActive
+    ? t('ui.advancedFilter.empty.tryRemovingSearchFilters', 'Try a different search, remove a filter, or clear everything to see everyone.')
+    : t('ui.advancedFilter.empty.tryRemoving', 'Try removing the most restrictive filter, or clear all filters to see everyone.')
+  const primaryLabel = searchActive
+    ? t('ui.advancedFilter.empty.clearSearchAndFilters', 'Clear search and filters')
+    : t('ui.advancedFilter.empty.clearAll', 'Clear all filters')
+  const handlePrimary = searchActive
+    ? () => { onClearSearch?.(); onClearAll() }
+    : onClearAll
   return (
     <div className="flex flex-col items-center justify-center gap-4 py-12" data-testid="filtered-empty-results">
       <div className="flex size-14 items-center justify-center rounded-full bg-muted">
         <SearchX className="size-6 text-muted-foreground" />
       </div>
       <div className="flex flex-col items-center gap-1">
-        <div className="text-base font-semibold">
-          {t('ui.advancedFilter.empty.noMatches', 'No {entity} match these filters', { entity: entityNamePlural })}
-        </div>
-        <div className="text-sm text-muted-foreground max-w-md text-center">
-          {t('ui.advancedFilter.empty.tryRemoving', 'Try removing the most restrictive filter, or clear all filters to see everyone.')}
-        </div>
+        <div className="text-base font-semibold">{title}</div>
+        <div className="text-sm text-muted-foreground max-w-md text-center">{description}</div>
       </div>
       <div className="flex items-center gap-2">
-        <Button type="button" onClick={onClearAll}>
-          {t('ui.advancedFilter.empty.clearAll', 'Clear all filters')}
-        </Button>
+        <Button type="button" onClick={handlePrimary}>{primaryLabel}</Button>
         <Button type="button" variant="outline" disabled={!canRemoveLast} onClick={onRemoveLast}>
           <Undo2 className="size-4" />
           {t('ui.advancedFilter.empty.removeLast', 'Remove last filter')}

package/src/backend/filters/ListEmptyState.tsx

@@ -0,0 +1,69 @@
+'use client'
+import * as React from 'react'
+import Link from 'next/link'
+import { Inbox, Plus } from 'lucide-react'
+import { Button } from '../../primitives/button'
+import { EmptyState } from '../../primitives/empty-state'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+
+export type ListEmptyStateProps = {
+  /** Plural entity label, e.g. "companies". Used to build the default title. */
+  entityName?: string
+  /** Overrides the generated title. */
+  title?: string
+  /** Overrides the generated description. */
+  description?: string
+  /** Create link target; renders the primary "create" action. */
+  createHref?: string
+  /** Create click handler (alternative to createHref). */
+  onCreate?: () => void
+  /** Label for the create action (defaults to a generic "Create"). */
+  createLabel?: string
+  /** Optional leading icon (defaults to a neutral inbox glyph). */
+  icon?: React.ReactNode
+}
+
+/**
+ * Standardized zero-records empty state for list views (DataTable `emptyState`).
+ * Use this when a list has no records yet (no active search/filter). For
+ * no-results-after-search the DataTable renders SearchEmptyResults, and for
+ * no-results-after-filter it renders FilteredEmptyResults.
+ */
+export function ListEmptyState({
+  entityName,
+  title,
+  description,
+  createHref,
+  onCreate,
+  createLabel,
+  icon,
+}: ListEmptyStateProps) {
+  const t = useT()
+  const entity = entityName ?? t('ui.dataTable.empty.genericEntity', 'records')
+  const resolvedTitle = title ?? t('ui.dataTable.empty.title', 'No {entity} yet', { entity })
+  const resolvedDescription = description ?? t('ui.dataTable.empty.description', 'Items you add will show up here.')
+  const resolvedCreateLabel = createLabel ?? t('ui.dataTable.empty.create', 'Create')
+  const action = createHref ? (
+    <Button asChild>
+      <Link href={createHref}>
+        <Plus className="size-4" aria-hidden />
+        {resolvedCreateLabel}
+      </Link>
+    </Button>
+  ) : onCreate ? (
+    <Button type="button" onClick={onCreate}>
+      <Plus className="size-4" aria-hidden />
+      {resolvedCreateLabel}
+    </Button>
+  ) : null
+  return (
+    <EmptyState
+      variant="subtle"
+      size="lg"
+      icon={icon ?? <Inbox className="size-7" aria-hidden />}
+      title={resolvedTitle}
+      description={resolvedDescription}
+      actions={action}
+    />
+  )
+}

package/src/backend/filters/SearchEmptyResults.tsx

@@ -0,0 +1,42 @@
+'use client'
+import * as React from 'react'
+import { SearchX, X } from 'lucide-react'
+import { Button } from '../../primitives/button'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+
+export type SearchEmptyResultsProps = {
+  /** The active search query, shown back to the user. */
+  query: string
+  /** Plural entity label (e.g. "companies"); falls back to a generic word. */
+  entityNamePlural?: string
+  /** Clears the active search. */
+  onClearSearch: () => void
+}
+
+export function SearchEmptyResults({ query, entityNamePlural, onClearSearch }: SearchEmptyResultsProps) {
+  const t = useT()
+  const entity = entityNamePlural ?? t('ui.dataTable.search.empty.genericEntity', 'results')
+  return (
+    <div className="flex w-full max-w-md flex-col items-center gap-4 py-10 text-center" data-testid="search-empty-results">
+      <div className="flex size-16 items-center justify-center rounded-full bg-muted">
+        <SearchX className="size-7 text-muted-foreground" aria-hidden />
+      </div>
+      <div className="flex flex-col items-center gap-1">
+        <div className="text-base font-semibold text-foreground">
+          {t('ui.dataTable.search.empty.title', 'No results found')}
+        </div>
+        <p className="text-sm text-muted-foreground">
+          {t(
+            'ui.dataTable.search.empty.description',
+            'We couldn’t find any {entity} matching “{query}”. Try adjusting your search or filters.',
+            { entity, query },
+          )}
+        </p>
+      </div>
+      <Button type="button" onClick={onClearSearch}>
+        <X className="size-4" aria-hidden />
+        {t('ui.dataTable.search.empty.clear', 'Clear search')}
+      </Button>
+    </div>
+  )
+}

package/src/backend/filters/__tests__/AdvancedFilterPanel.test.tsx

@@ -106,6 +106,74 @@ describe('AdvancedFilterPanel', () => {
     expect(screen.queryByText(/no filters applied/i)).not.toBeInTheDocument()
   })
 
+  it('closes the panel on Escape even when a closing dropdown layer marked the event prevented', () => {
+    const onOpenChange = jest.fn()
+    const onFlush = jest.fn()
+    render(
+      <AdvancedFilterPanel
+        fields={fields}
+        value={createEmptyTree()}
+        onChange={() => {}}
+        onApply={() => {}}
+        onClear={() => {}}
+        onFlush={onFlush}
+        pendingErrors={[]}
+        userId="u1"
+        presets={[]}
+        open
+        onOpenChange={onOpenChange}
+        triggerRef={{ current: null }}
+      />,
+    )
+
+    // Simulate a just-closed Select whose dismissable layer is still mounted during
+    // its exit animation: it consumes Escape (defaultPrevented) but its trigger has
+    // already flipped aria-expanded to "false". The panel must still close.
+    const swallow = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') event.preventDefault()
+    }
+    window.addEventListener('keydown', swallow, true)
+    try {
+      fireEvent.keyDown(window, { key: 'Escape' })
+    } finally {
+      window.removeEventListener('keydown', swallow, true)
+    }
+
+    expect(onOpenChange).toHaveBeenCalledWith(false)
+    expect(onFlush).toHaveBeenCalled()
+  })
+
+  it('keeps the panel open on Escape while an inner dropdown is actually open', () => {
+    const onOpenChange = jest.fn()
+    render(
+      <AdvancedFilterPanel
+        fields={fields}
+        value={createEmptyTree()}
+        onChange={() => {}}
+        onApply={() => {}}
+        onClear={() => {}}
+        pendingErrors={[]}
+        userId="u1"
+        presets={[]}
+        open
+        onOpenChange={onOpenChange}
+        triggerRef={{ current: null }}
+      />,
+    )
+
+    // A genuinely-open Radix Select keeps its trigger at aria-expanded="true".
+    const openSelect = document.createElement('div')
+    openSelect.setAttribute('role', 'combobox')
+    openSelect.setAttribute('aria-expanded', 'true')
+    document.body.appendChild(openSelect)
+    try {
+      fireEvent.keyDown(window, { key: 'Escape' })
+      expect(onOpenChange).not.toHaveBeenCalled()
+    } finally {
+      document.body.removeChild(openSelect)
+    }
+  })
+
   it('saves filters separately from perspectives', async () => {
     const tree = { root: { id: 'r', type: 'group' as const, combinator: 'and' as const, children: [
       { id: 'a', type: 'rule' as const, field: 'name', operator: 'contains' as const, value: 'Alice' } as any,
@@ -209,4 +277,34 @@ describe('AdvancedFilterPanel', () => {
     }))
     expect(onOpenChange).toHaveBeenCalledWith(false)
   })
+
+  it('closes and flushes the panel when Escape is pressed after manual filter editing', () => {
+    const onOpenChange = jest.fn()
+    const onFlush = jest.fn()
+    const tree = { root: { id: 'r', type: 'group' as const, combinator: 'and' as const, children: [
+      { id: 'a', type: 'rule' as const, field: 'name', operator: 'contains' as const, value: 'Alice' } as any,
+    ] } }
+
+    render(
+      <AdvancedFilterPanel
+        fields={fields}
+        value={tree}
+        onChange={() => {}}
+        onApply={() => {}}
+        onClear={() => {}}
+        onFlush={onFlush}
+        pendingErrors={[]}
+        userId="u1"
+        presets={[]}
+        open
+        onOpenChange={onOpenChange}
+        triggerRef={{ current: null }}
+      />,
+    )
+
+    fireEvent.keyDown(window, { key: 'Escape' })
+
+    expect(onOpenChange).toHaveBeenCalledWith(false)
+    expect(onFlush).toHaveBeenCalledTimes(1)
+  })
 })

package/src/backend/filters/__tests__/ListEmptyState.test.tsx

@@ -0,0 +1,53 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import * as React from 'react'
+import { render, screen } from '@testing-library/react'
+import { ListEmptyState } from '../ListEmptyState'
+
+jest.mock('@open-mercato/shared/lib/i18n/context', () => ({
+  useT: () => (_key: string, fallback?: string, params?: Record<string, unknown>) => {
+    let out = fallback ?? _key
+    if (params) for (const k of Object.keys(params)) out = out.replace(`{${k}}`, String(params[k]))
+    return out
+  },
+}))
+
+jest.mock('next/link', () => {
+  const React = require('react')
+  return React.forwardRef(
+    ({ children, href, ...rest }: any, ref: React.ForwardedRef<HTMLAnchorElement>) => (
+      <a href={typeof href === 'string' ? href : href?.toString?.()} ref={ref} {...rest}>
+        {children}
+      </a>
+    ),
+  )
+})
+
+describe('ListEmptyState', () => {
+  it('builds the title from entityName', () => {
+    render(<ListEmptyState entityName="companies" />)
+    expect(screen.getByText('No companies yet')).toBeInTheDocument()
+  })
+
+  it('renders a create link (role=link) with href and label when createHref is set', () => {
+    render(<ListEmptyState entityName="companies" createHref="/backend/customers/companies/create" createLabel="New company" />)
+    const link = screen.getByRole('link', { name: /new company/i })
+    expect(link).toBeInTheDocument()
+    expect(link).toHaveAttribute('href', '/backend/customers/companies/create')
+  })
+
+  it('renders a create button when onCreate is provided', () => {
+    const onCreate = jest.fn()
+    render(<ListEmptyState entityName="users" onCreate={onCreate} createLabel="Add user" />)
+    expect(screen.getByRole('button', { name: /add user/i })).toBeInTheDocument()
+    expect(screen.queryByRole('link')).not.toBeInTheDocument()
+  })
+
+  it('renders no action when neither createHref nor onCreate is provided', () => {
+    render(<ListEmptyState entityName="records" />)
+    expect(screen.queryByRole('link')).not.toBeInTheDocument()
+    expect(screen.queryByRole('button')).not.toBeInTheDocument()
+  })
+})

package/src/backend/icons/lucideRegistry.generated.tsx

@@ -18,6 +18,7 @@ import {
   BarChart3,
   Bell,
   Bolt,
+  Book,
   Bookmark,
   Box,
   Briefcase,
@@ -83,6 +84,7 @@ import {
   Mail,
   MailOpen,
   MapPin,
+  MessageCircle,
   MinusCircle,
   Notebook,
   Package,
@@ -98,6 +100,7 @@ import {
   Receipt,
   ReceiptText,
   RefreshCcw,
+  RefreshCw,
   Reply,
   RotateCcw,
   Ruler,
@@ -139,6 +142,7 @@ import {
   UserX,
   Wallet,
   Webhook,
+  Workflow,
   Wrench,
   X,
   XCircle,
@@ -158,6 +162,7 @@ export const LUCIDE_ICON_REGISTRY: Record<string, LucideIcon> = {
   'bar-chart-3': BarChart3,
   'bell': Bell,
   'bolt': Bolt,
+  'book': Book,
   'bookmark': Bookmark,
   'box': Box,
   'briefcase': Briefcase,
@@ -223,6 +228,7 @@ export const LUCIDE_ICON_REGISTRY: Record<string, LucideIcon> = {
   'mail': Mail,
   'mail-open': MailOpen,
   'map-pin': MapPin,
+  'message-circle': MessageCircle,
   'minus-circle': MinusCircle,
   'notebook': Notebook,
   'package': Package,
@@ -238,6 +244,7 @@ export const LUCIDE_ICON_REGISTRY: Record<string, LucideIcon> = {
   'receipt': Receipt,
   'receipt-text': ReceiptText,
   'refresh-ccw': RefreshCcw,
+  'refresh-cw': RefreshCw,
   'reply': Reply,
   'rotate-ccw': RotateCcw,
   'ruler': Ruler,
@@ -279,6 +286,7 @@ export const LUCIDE_ICON_REGISTRY: Record<string, LucideIcon> = {
   'users': Users,
   'wallet': Wallet,
   'webhook': Webhook,
+  'workflow': Workflow,
   'wrench': Wrench,
   'x': X,
   'x-circle': XCircle,

package/src/backend/injection/__tests__/useGuardedMutation.optimisticLock.test.tsx

@@ -0,0 +1,118 @@
+/** @jest-environment jsdom */
+
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { OPTIMISTIC_LOCK_CONFLICT_CODE } from '@open-mercato/shared/lib/crud/optimistic-lock-headers'
+
+const triggerEventMock = jest.fn()
+
+jest.mock('../InjectionSpot', () => ({
+  useInjectionSpotEvents: () => ({
+    triggerEvent: (...args: unknown[]) => triggerEventMock(...args),
+  }),
+}))
+
+jest.mock('@open-mercato/shared/lib/i18n/context', () => ({
+  useT: () => (key: string, fallback?: string) => fallback ?? key,
+}))
+
+import { act, renderHook } from '@testing-library/react'
+import { useGuardedMutation } from '../useGuardedMutation'
+import { dismissRecordConflict, getRecordConflictForTest } from '../../conflicts'
+
+function setupTriggerEventOk() {
+  triggerEventMock.mockImplementation(async () => ({ ok: true, requestHeaders: undefined }))
+}
+
+describe('useGuardedMutation — surfaces optimistic-lock conflict on the unified bar', () => {
+  beforeEach(() => {
+    triggerEventMock.mockClear()
+    dismissRecordConflict()
+  })
+
+  it('shows the record-conflict bar when the operation throws CrudHttpError(409, optimistic_lock_conflict)', async () => {
+    setupTriggerEventOk()
+    const { result } = renderHook(() => useGuardedMutation<Record<string, unknown>>({ contextId: 'test-form' }))
+    const conflict = new CrudHttpError(409, {
+      error: 'record_modified',
+      code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+      currentUpdatedAt: '2026-05-25T08:00:01.000Z',
+      expectedUpdatedAt: '2026-05-25T08:00:00.000Z',
+    })
+
+    await act(async () => {
+      try {
+        await result.current.runMutation({
+          operation: async () => { throw conflict },
+          context: {},
+          mutationPayload: {},
+        })
+      } catch (err) {
+        expect(err).toBe(conflict)
+      }
+    })
+
+    const entry = getRecordConflictForTest()
+    expect(entry).not.toBeNull()
+    expect(entry?.message).toBe('This record was modified by someone else. Refresh and try again.')
+    expect(entry?.currentUpdatedAt).toBe('2026-05-25T08:00:01.000Z')
+  })
+
+  it('does NOT show the bar for non-optimistic-lock 409s (e.g. plain conflicts)', async () => {
+    setupTriggerEventOk()
+    const { result } = renderHook(() => useGuardedMutation<Record<string, unknown>>({ contextId: 'test-form' }))
+    const otherConflict = new CrudHttpError(409, {
+      error: 'duplicate',
+      code: 'duplicate_resource',
+    })
+
+    await act(async () => {
+      try {
+        await result.current.runMutation({
+          operation: async () => { throw otherConflict },
+          context: {},
+          mutationPayload: {},
+        })
+      } catch (err) {
+        expect(err).toBe(otherConflict)
+      }
+    })
+
+    expect(getRecordConflictForTest()).toBeNull()
+  })
+
+  it('does NOT show the bar for non-409 errors', async () => {
+    setupTriggerEventOk()
+    const { result } = renderHook(() => useGuardedMutation<Record<string, unknown>>({ contextId: 'test-form' }))
+    const validationError = new CrudHttpError(422, { error: 'validation_failed' })
+
+    await act(async () => {
+      try {
+        await result.current.runMutation({
+          operation: async () => { throw validationError },
+          context: {},
+          mutationPayload: {},
+        })
+      } catch (err) {
+        expect(err).toBe(validationError)
+      }
+    })
+
+    expect(getRecordConflictForTest()).toBeNull()
+  })
+
+  it('does NOT show the bar when the operation resolves successfully', async () => {
+    setupTriggerEventOk()
+    const { result } = renderHook(() => useGuardedMutation<Record<string, unknown>>({ contextId: 'test-form' }))
+
+    await act(async () => {
+      const value = await result.current.runMutation({
+        operation: async () => 'ok',
+        context: {},
+        mutationPayload: {},
+      })
+      expect(value).toBe('ok')
+    })
+
+    expect(getRecordConflictForTest()).toBeNull()
+  })
+})