@open-mercato/ui 0.6.4-develop.4371.1.8f3030407e → 0.6.4

package/src/backend/sidebar/SidebarCustomizationEditor.tsx

@@ -21,7 +21,9 @@ import {
   SelectTrigger,
   SelectValue,
 } from '../../primitives/select'
-import { apiCall } from '../utils/apiCall'
+import { apiCall, withScopedApiRequestHeaders } from '../utils/apiCall'
+import { buildOptimisticLockHeader } from '../utils/optimisticLock'
+import { surfaceRecordConflict } from '../conflicts'
 import { flash } from '../FlashMessages'
 import { Page, PageBody } from '../Page'
 import { useBackendChrome } from '../BackendChromeProvider'
@@ -231,6 +233,9 @@ export function SidebarCustomizationEditor({
   const [addDialogError, setAddDialogError] = React.useState<string | null>(null)
   const baseSnapshotRef = React.useRef<SidebarGroup[] | null>(null)
   const hasInitializedRef = React.useRef(false)
+  // Tracks the user-scope sidebar-preference version so concurrent edits from another
+  // tab are caught by the server's optimistic-lock guard (409 → conflict bar).
+  const preferencesUpdatedAtRef = React.useRef<string | null>(null)
 
   const { runMutation, retryLastMutation } = useGuardedMutation<{
     formId: string
@@ -285,11 +290,12 @@ export function SidebarCustomizationEditor({
   }, [variantsApiPath])
 
   const loadRolesPayload = React.useCallback(async (): Promise<{ canApplyToRoles: boolean; roles: RoleTarget[] }> => {
-    const call = await apiCall<{ canApplyToRoles?: boolean; roles?: Array<{ id?: string; name?: string; hasPreference?: boolean }> }>(preferencesApiPath)
+    const call = await apiCall<{ canApplyToRoles?: boolean; roles?: Array<{ id?: string; name?: string; hasPreference?: boolean }>; updatedAt?: string | null }>(preferencesApiPath)
     if (!call.ok) {
       return { canApplyToRoles: false, roles: [] }
     }
     const data = call.result ?? null
+    preferencesUpdatedAtRef.current = typeof data?.updatedAt === 'string' ? data.updatedAt : null
     const can = data?.canApplyToRoles === true
     const roles = Array.isArray(data?.roles)
       ? (data!.roles as Array<{ id?: string; name?: string; hasPreference?: boolean }>)
@@ -695,19 +701,37 @@ export function SidebarCustomizationEditor({
       }
       const preferencesCall = await runMutation({
         operation: () =>
-          apiCall(preferencesApiPath, {
-            method: 'PUT',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify(preferencesPayload),
-          }),
+          withScopedApiRequestHeaders(
+            buildOptimisticLockHeader(preferencesUpdatedAtRef.current),
+            () =>
+              apiCall<{ updatedAt?: string | null }>(preferencesApiPath, {
+                method: 'PUT',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(preferencesPayload),
+              }),
+          ),
         context: buildMutationContext('savePreferences', selectedVariantId),
         mutationPayload: preferencesPayload,
       })
+      if (preferencesCall.ok) {
+        preferencesUpdatedAtRef.current =
+          typeof preferencesCall.result?.updatedAt === 'string' ? preferencesCall.result.updatedAt : null
+      }
       if (!preferencesCall.ok) {
-        // The variant entity is the canonical layout; the preferences sync is what the
-        // AppShell sidebar actually reads. A failed sync would leave the saved variant
-        // not reflected live, so surface it as a save error rather than flashing success.
-        setError(formatVariantApiError(preferencesCall, t))
+        // A stale save (another tab changed the sidebar customization first) returns a
+        // 409 with `code: 'optimistic_lock_conflict'`. apiCall does not throw, so surface
+        // the conflict explicitly on the shared, persistent conflict bar instead of a
+        // generic save error.
+        const surfaced = surfaceRecordConflict(
+          { status: preferencesCall.status, body: preferencesCall.result },
+          t,
+        )
+        if (!surfaced) {
+          // The variant entity is the canonical layout; the preferences sync is what the
+          // AppShell sidebar actually reads. A failed sync would leave the saved variant
+          // not reflected live, so surface it as a save error rather than flashing success.
+          setError(formatVariantApiError(preferencesCall, t))
+        }
         return
       }
       try { window.dispatchEvent(new Event(REFRESH_SIDEBAR_EVENT)) } catch { /* no listener attached — fine, AppShell will refresh on next navigation */ }

package/src/backend/utils/__tests__/optimisticLock.test.ts

@@ -0,0 +1,126 @@
+import { buildOptimisticLockHeader, extractOptimisticLockConflict } from '../optimisticLock'
+import {
+  OPTIMISTIC_LOCK_CONFLICT_CODE,
+  OPTIMISTIC_LOCK_HEADER_NAME,
+} from '@open-mercato/shared/lib/crud/optimistic-lock-headers'
+
+describe('buildOptimisticLockHeader', () => {
+  it('returns the extension header when updatedAt is a non-empty string', () => {
+    expect(buildOptimisticLockHeader('2026-05-25T08:42:18.123Z')).toEqual({
+      [OPTIMISTIC_LOCK_HEADER_NAME]: '2026-05-25T08:42:18.123Z',
+    })
+  })
+
+  it('trims surrounding whitespace', () => {
+    expect(buildOptimisticLockHeader('   2026-05-25T08:42:18.123Z   ')).toEqual({
+      [OPTIMISTIC_LOCK_HEADER_NAME]: '2026-05-25T08:42:18.123Z',
+    })
+  })
+
+  it('returns an empty object for null / undefined / empty / whitespace input', () => {
+    expect(buildOptimisticLockHeader(null)).toEqual({})
+    expect(buildOptimisticLockHeader(undefined)).toEqual({})
+    expect(buildOptimisticLockHeader('')).toEqual({})
+    expect(buildOptimisticLockHeader('   ')).toEqual({})
+  })
+
+  it('returns an empty object for non-string input (defensive)', () => {
+    // @ts-expect-error intentional misuse
+    expect(buildOptimisticLockHeader(12345)).toEqual({})
+    // @ts-expect-error intentional misuse
+    expect(buildOptimisticLockHeader({ updatedAt: '2026' })).toEqual({})
+  })
+})
+
+describe('extractOptimisticLockConflict', () => {
+  it('returns the conflict body when the error has status 409 + optimistic-lock code + both timestamps', () => {
+    const err = {
+      status: 409,
+      body: {
+        error: 'record_modified',
+        code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+        currentUpdatedAt: '2026-05-25T08:42:19.000Z',
+        expectedUpdatedAt: '2026-05-25T08:42:18.000Z',
+      },
+    }
+    expect(extractOptimisticLockConflict(err)).toEqual({
+      error: 'record_modified',
+      code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+      currentUpdatedAt: '2026-05-25T08:42:19.000Z',
+      expectedUpdatedAt: '2026-05-25T08:42:18.000Z',
+    })
+  })
+
+  it('returns the conflict body when raiseCrudError attached the response fields directly to the error', () => {
+    const err = {
+      status: 409,
+      error: 'record_modified',
+      code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+      currentUpdatedAt: '2026-05-25T08:42:19.000Z',
+      expectedUpdatedAt: '2026-05-25T08:42:18.000Z',
+    }
+    expect(extractOptimisticLockConflict(err)).toEqual({
+      error: 'record_modified',
+      code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+      currentUpdatedAt: '2026-05-25T08:42:19.000Z',
+      expectedUpdatedAt: '2026-05-25T08:42:18.000Z',
+    })
+  })
+
+  it('returns null for non-409 errors', () => {
+    expect(
+      extractOptimisticLockConflict({
+        status: 422,
+        body: { error: 'validation_failed', code: OPTIMISTIC_LOCK_CONFLICT_CODE },
+      }),
+    ).toBeNull()
+  })
+
+  it('returns null for 409 errors that are not optimistic-lock conflicts', () => {
+    expect(
+      extractOptimisticLockConflict({
+        status: 409,
+        body: { error: 'duplicate', code: 'duplicate_resource' },
+      }),
+    ).toBeNull()
+  })
+
+  it('returns null when the conflict body is missing required timestamp fields', () => {
+    expect(
+      extractOptimisticLockConflict({
+        status: 409,
+        body: { error: 'record_modified', code: OPTIMISTIC_LOCK_CONFLICT_CODE },
+      }),
+    ).toBeNull()
+    expect(
+      extractOptimisticLockConflict({
+        status: 409,
+        body: {
+          error: 'record_modified',
+          code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+          currentUpdatedAt: 123,
+          expectedUpdatedAt: '2026-05-25T08:42:18.000Z',
+        },
+      }),
+    ).toBeNull()
+  })
+
+  it('returns null for non-object inputs', () => {
+    expect(extractOptimisticLockConflict(null)).toBeNull()
+    expect(extractOptimisticLockConflict(undefined)).toBeNull()
+    expect(extractOptimisticLockConflict('boom')).toBeNull()
+    expect(extractOptimisticLockConflict(409)).toBeNull()
+  })
+
+  it('falls back to the canonical error token when body.error is missing', () => {
+    const result = extractOptimisticLockConflict({
+      status: 409,
+      body: {
+        code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+        currentUpdatedAt: '2026-05-25T08:42:19.000Z',
+        expectedUpdatedAt: '2026-05-25T08:42:18.000Z',
+      },
+    })
+    expect(result?.error).toBe('record_modified')
+  })
+})

package/src/backend/utils/optimisticLock.ts

@@ -0,0 +1,70 @@
+/**
+ * Client-side helpers for the OSS opt-in optimistic-locking guard
+ * (spec: .ai/specs/2026-05-25-oss-optimistic-locking.md).
+ *
+ * These are deliberately small and dependency-light so they can be wired
+ * into any backend page without touching the shared CrudForm / useGuardedMutation
+ * components. A future PR may pull them into CrudForm directly once the
+ * reference rollout is broader.
+ */
+import {
+  OPTIMISTIC_LOCK_CONFLICT_CODE,
+  OPTIMISTIC_LOCK_HEADER_NAME,
+  type OptimisticLockConflictBody,
+} from '@open-mercato/shared/lib/crud/optimistic-lock-headers'
+
+/**
+ * Build the extension-header bag for an `apiCall` request. Pass into
+ * `withScopedApiRequestHeaders(buildOptimisticLockHeader(updatedAt), ...)`
+ * when issuing a `PUT`/`PATCH`/`DELETE` for a record that exposes
+ * `updatedAt`. Returns an empty object when the input is missing/empty so
+ * the call site stays unconditional:
+ *
+ * ```ts
+ * await withScopedApiRequestHeaders(
+ *   buildOptimisticLockHeader(record.updatedAt),
+ *   () => updateCrud('customers/companies', id, { ... }),
+ * )
+ * ```
+ */
+export function buildOptimisticLockHeader(
+  updatedAt: string | null | undefined,
+): Record<string, string> {
+  if (typeof updatedAt !== 'string') return {}
+  const trimmed = updatedAt.trim()
+  if (!trimmed) return {}
+  return { [OPTIMISTIC_LOCK_HEADER_NAME]: trimmed }
+}
+
+/**
+ * Detect whether an error thrown by `raiseCrudError`/`apiCallOrThrow` is an
+ * optimistic-lock conflict (HTTP 409 with `code: 'optimistic_lock_conflict'`).
+ *
+ * Returns the typed conflict body when matched so the caller can show a
+ * UI that includes the server's `currentUpdatedAt`, or `null` otherwise.
+ */
+export function extractOptimisticLockConflict(
+  err: unknown,
+): OptimisticLockConflictBody | null {
+  if (!err || typeof err !== 'object') return null
+  const candidate = err as Record<string, unknown>
+  const status = candidate.status
+  if (status !== 409) return null
+  const body = candidate.body && typeof candidate.body === 'object'
+    ? candidate.body
+    : candidate
+  if (!body || typeof body !== 'object') return null
+  const bodyRecord = body as Record<string, unknown>
+  if (bodyRecord.code !== OPTIMISTIC_LOCK_CONFLICT_CODE) return null
+  const currentUpdatedAt = bodyRecord.currentUpdatedAt
+  const expectedUpdatedAt = bodyRecord.expectedUpdatedAt
+  if (typeof currentUpdatedAt !== 'string' || typeof expectedUpdatedAt !== 'string') return null
+  return {
+    error: typeof bodyRecord.error === 'string'
+      ? (bodyRecord.error as OptimisticLockConflictBody['error'])
+      : 'record_modified',
+    code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+    currentUpdatedAt,
+    expectedUpdatedAt,
+  }
+}

package/src/portal/hooks/useTenantContext.ts

@@ -3,6 +3,11 @@ import { useEffect, useState } from 'react'
 import { apiCall } from '../../backend/utils/apiCall'
 
 type OrgContext = {
+  /**
+   * @deprecated The public org lookup no longer returns a tenant id; portal
+   * flows send `organizationId` and the server resolves the tenant. Always
+   * `undefined` — kept for backward compatibility with existing consumers.
+   */
   tenantId: string | undefined
   organizationId: string | undefined
   organizationName: string | undefined
@@ -49,7 +54,7 @@ export function useTenantContext(orgSlug: string): OrgContext {
       }
 
       try {
-        const { ok, result: data } = await apiCall<{ ok: boolean; organization: { id: string; tenantId: string; name: string }; error?: string }>(`/api/directory/organizations/lookup?slug=${encodeURIComponent(orgSlug)}`)
+        const { ok, result: data } = await apiCall<{ ok: boolean; organization: { id: string; name: string }; error?: string }>(`/api/directory/organizations/lookup?slug=${encodeURIComponent(orgSlug)}`)
         if (cancelled) return
 
         if (!ok || !data?.ok || !data.organization) {
@@ -62,7 +67,7 @@ export function useTenantContext(orgSlug: string): OrgContext {
         }
 
         setState({
-          tenantId: data.organization.tenantId ?? undefined,
+          tenantId: undefined,
           organizationId: data.organization.id,
           organizationName: data.organization.name,
           loading: false,

package/src/primitives/__tests__/checkbox.test.tsx

@@ -0,0 +1,28 @@
+/** @jest-environment jsdom */
+
+import * as React from 'react'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { Checkbox } from '../checkbox'
+
+describe('Checkbox', () => {
+  it('does not submit a parent form by default', () => {
+    const onSubmit = jest.fn((event: React.FormEvent<HTMLFormElement>) => {
+      event.preventDefault()
+    })
+    const onCheckedChange = jest.fn()
+
+    render(
+      <form onSubmit={onSubmit}>
+        <Checkbox aria-label="Assignee alice" onCheckedChange={onCheckedChange} />
+      </form>,
+    )
+
+    const checkbox = screen.getByRole('checkbox', { name: 'Assignee alice' })
+    expect(checkbox).toHaveAttribute('type', 'button')
+
+    fireEvent.click(checkbox)
+
+    expect(onCheckedChange).toHaveBeenCalled()
+    expect(onSubmit).not.toHaveBeenCalled()
+  })
+})

package/src/primitives/alert.tsx

@@ -133,7 +133,7 @@ const defaultStatusIcons: Record<AlertStatus, React.ComponentType<{ className?:
   feature: Rocket,
 }
 
-export type AlertProps = Omit<React.HTMLAttributes<HTMLDivElement>, 'role'> &
+export type AlertProps = Omit<React.HTMLAttributes<HTMLDivElement>, 'role' | 'style'> &
   Omit<VariantProps<typeof alertVariants>, 'status' | 'style' | 'size'> & {
     status?: AlertStatus
     style?: AlertStyle

package/src/primitives/checkbox.tsx

@@ -31,11 +31,12 @@ export type CheckboxProps = React.ComponentPropsWithoutRef<typeof CheckboxPrimit
 const Checkbox = React.forwardRef<
   React.ElementRef<typeof CheckboxPrimitive.Root>,
   CheckboxProps
->(({ className, size, ...props }, ref) => {
+>(({ className, size, type = "button", ...props }, ref) => {
   const iconClass = indicatorIconBySize[size ?? "sm"]
   return (
     <CheckboxPrimitive.Root
       ref={ref}
+      type={type}
       className={cn(checkboxVariants({ size, className }))}
       {...props}
     >

package/src/types/css.d.ts

@@ -0,0 +1,5 @@
+// Ambient declaration so side-effect CSS imports from third-party packages
+// (e.g. `import '@mdxeditor/editor/style.css'`) type-check. Packages that consume
+// @open-mercato/ui as source type-check this file's `.tsx` too, so MdxEditorImpl.tsx
+// pulls this declaration into their program via a `/// <reference path>` directive.
+declare module '*.css'