@open-mercato/ui 0.6.1-develop.3278.1.a4d26475e4 → 0.6.1-develop.3287.1.450f4ffb56

package/src/backend/inputs/LookupSelect.tsx

@@ -1,7 +1,8 @@
 "use client"
 
 import * as React from 'react'
-import { Loader2, Search, X } from 'lucide-react'
+import { Check, Loader2, Search, X } from 'lucide-react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { Button } from '../../primitives/button'
 import { cn } from '@open-mercato/shared/lib/utils'
 
@@ -50,19 +51,32 @@ export function LookupSelect({
   actionSlot,
   onReady,
   placeholder,
-  searchPlaceholder = placeholder ?? 'Search…',
-  clearLabel = 'Clear selection',
-  emptyLabel = 'No results',
-  loadingLabel = 'Searching…',
-  selectLabel = 'Select',
-  selectedLabel = 'Selected',
+  searchPlaceholder,
+  clearLabel,
+  emptyLabel,
+  loadingLabel,
+  selectLabel,
+  selectedLabel,
   minQueryHintLabel,
-  startTypingLabel = 'Start typing to search.',
+  startTypingLabel,
   selectedHintLabel,
   disabled = false,
   loading: loadingProp = false,
   defaultOpen = false,
 }: LookupSelectProps) {
+  const t = useT()
+  const resolvedSearchPlaceholder = searchPlaceholder ?? placeholder ?? t('ui.lookupSelect.searchPlaceholder', 'Search…')
+  const resolvedClearLabel = clearLabel ?? t('ui.lookupSelect.clearSelection', 'Clear selection')
+  const resolvedEmptyLabel = emptyLabel ?? t('ui.lookupSelect.noResults', 'No results')
+  const resolvedLoadingLabel = loadingLabel ?? t('ui.lookupSelect.searching', 'Searching…')
+  const resolvedSelectLabel = selectLabel ?? t('ui.lookupSelect.select', 'Select')
+  const resolvedSelectedLabel = selectedLabel ?? t('ui.lookupSelect.selected', 'Selected')
+  const resolvedStartTypingLabel = startTypingLabel ?? t('ui.lookupSelect.startTyping', 'Start typing to search.')
+  const resolvedMinQueryHintLabel = minQueryHintLabel ?? t(
+    'ui.lookupSelect.minQueryHint',
+    'Type at least {minQuery} characters or paste an id to search.',
+    { minQuery: String(minQuery) }
+  )
   const [query, setQuery] = React.useState('')
   const [items, setItems] = React.useState<LookupSelectItem[]>(options ?? [])
   const [loading, setLoading] = React.useState(false)
@@ -139,15 +153,15 @@ export function LookupSelect({
     <div className="space-y-3">
       <div className="flex flex-col gap-2 sm:flex-row sm:items-center sm:gap-3">
         <div className="relative flex-1">
-          <Search className="pointer-events-none absolute left-2 top-2.5 h-4 w-4 text-muted-foreground" />
+          <Search className="pointer-events-none absolute left-3.5 top-1/2 -translate-y-1/2 h-4 w-4 text-muted-foreground" />
           <input
-            className="w-full rounded border pl-8 pr-2 py-2 text-sm"
+            className="w-full h-10 rounded-lg border border-input bg-background pl-10 pr-3 text-sm shadow-xs transition-colors outline-none placeholder:text-muted-foreground hover:border-foreground/20 focus-visible:shadow-focus focus-visible:border-brand-violet disabled:bg-bg-disabled disabled:border-border-disabled disabled:text-muted-foreground disabled:cursor-not-allowed"
             value={query}
             onChange={(event) => {
               setQuery(event.target.value)
               setHasTyped(true)
             }}
-            placeholder={searchPlaceholder}
+            placeholder={resolvedSearchPlaceholder}
             disabled={disabled}
           />
         </div>
@@ -158,71 +172,79 @@ export function LookupSelect({
           {loading || loadingProp ? (
             <div className="flex items-center gap-2 text-sm text-muted-foreground">
               <Loader2 className="h-4 w-4 animate-spin" />
-              {loadingLabel}
+              {resolvedLoadingLabel}
             </div>
           ) : null}
           {!loading && !loadingProp && !items.length ? (
-            <p className="text-xs text-muted-foreground">{emptyLabel}</p>
+            <p className="text-xs text-muted-foreground">{resolvedEmptyLabel}</p>
           ) : null}
-          <div className="space-y-2 max-h-80 overflow-y-auto">
+          <div className="flex flex-col gap-1.5 max-h-80 overflow-y-auto -mx-0.5 px-0.5 py-0.5">
             {items.map((item) => {
               const isSelected = value === item.id
+              const isInteractive = !item.disabled || isSelected
               return (
                 <div
                   key={item.id}
                   className={cn(
-                    'flex gap-3 rounded border bg-card p-3 transition-colors cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50 focus-visible:ring-offset-2 focus-visible:ring-offset-background',
-                    isSelected ? 'border-primary/70 bg-primary/5' : 'hover:border-primary/50'
+                    'group flex items-center gap-4 rounded-xl border p-4 transition-all duration-150 focus-visible:outline-none focus-visible:shadow-focus',
+                    isInteractive ? 'cursor-pointer' : 'cursor-not-allowed opacity-60',
+                    isSelected
+                      ? 'border-brand-violet bg-brand-violet/5 shadow-sm'
+                      : 'border-input bg-card hover:border-foreground/20 hover:bg-muted/30 hover:shadow-sm'
                   )}
                   role="button"
                   tabIndex={item.disabled ? -1 : 0}
                   onClick={() => {
-                    if (item.disabled && !isSelected) return
+                    if (!isInteractive) return
                     onChange(item.id)
                   }}
                   onKeyDown={(event) => {
                     if (event.key === 'Enter' || event.key === ' ') {
                       event.preventDefault()
-                      if (item.disabled && !isSelected) return
+                      if (!isInteractive) return
                       onChange(item.id)
                     }
                   }}
                   aria-pressed={isSelected}
+                  aria-disabled={item.disabled && !isSelected ? true : undefined}
+                  title={isSelected ? resolvedSelectedLabel : resolvedSelectLabel}
                 >
-                  <div className="flex h-10 w-10 sm:h-12 sm:w-12 shrink-0 items-center justify-center overflow-hidden rounded border bg-muted">
-                    {item.icon ?? <span className="text-muted-foreground">•</span>}
-                  </div>
-                  <div className="flex min-w-0 flex-1 flex-col gap-1">
-                    <div className="flex items-start justify-between gap-2">
-                      <div className="min-w-0">
-                        <div className="truncate text-sm font-medium">{item.title}</div>
-                        {item.subtitle ? (
-                          <div className="text-xs text-muted-foreground truncate">{item.subtitle}</div>
-                        ) : null}
-                        {item.description ? (
-                          <div className="text-xs text-muted-foreground truncate">{item.description}</div>
-                        ) : null}
-                      </div>
+                  {item.icon ? (
+                    <div className="flex h-12 w-12 shrink-0 items-center justify-center overflow-hidden [&>svg]:size-6 [&_svg]:text-muted-foreground">
+                      {item.icon}
+                    </div>
+                  ) : (
+                    <div className={cn(
+                      'flex h-12 w-12 shrink-0 items-center justify-center overflow-hidden rounded-lg border transition-colors',
+                      isSelected
+                        ? 'border-brand-violet/40 bg-brand-violet/10 text-brand-violet'
+                        : 'border-input bg-muted text-muted-foreground group-hover:border-foreground/20'
+                    )}>
+                      <span className="text-base font-semibold uppercase">{item.title.slice(0, 1)}</span>
+                    </div>
+                  )}
+                  <div className="flex min-w-0 flex-1 flex-col gap-0.5">
+                    <div className="flex items-center justify-between gap-3">
+                      <div className="truncate text-sm font-semibold text-foreground">{item.title}</div>
                       {item.rightLabel ? (
-                        <div className="shrink-0 text-xs font-medium text-muted-foreground">{item.rightLabel}</div>
+                        <div className="shrink-0 text-overline font-medium uppercase tracking-wider text-muted-foreground">
+                          {item.rightLabel}
+                        </div>
                       ) : null}
                     </div>
-                    <div className="flex justify-end">
-                      <Button
-                        type="button"
-                        variant={isSelected ? 'secondary' : 'outline'}
-                        size="sm"
-                        className="shrink-0"
-                        onClick={(event) => {
-                          event.stopPropagation()
-                          if (item.disabled && !isSelected) return
-                          onChange(item.id)
-                        }}
-                        disabled={item.disabled && !isSelected}
-                      >
-                        {isSelected ? selectedLabel : selectLabel}
-                      </Button>
-                    </div>
+                    {item.subtitle ? (
+                      <div className="text-xs text-muted-foreground truncate">{item.subtitle}</div>
+                    ) : null}
+                    {item.description ? (
+                      <div className="text-xs text-muted-foreground/70 truncate">{item.description}</div>
+                    ) : null}
+                  </div>
+                  <div className="flex shrink-0 items-center justify-center">
+                    {isSelected ? (
+                      <Check className="size-5 text-brand-violet" aria-hidden="true" />
+                    ) : (
+                      <div className="size-5" aria-hidden="true" />
+                    )}
                   </div>
                 </div>
               )
@@ -237,18 +259,18 @@ export function LookupSelect({
               onClick={() => onChange(null)}
             >
               <X className="h-4 w-4" />
-              {clearLabel}
+              {resolvedClearLabel}
             </Button>
           ) : null}
         </div>
       ) : hasTyped ? (
         <p className="text-xs text-muted-foreground">
-          {minQueryHintLabel ?? `Type at least ${minQuery} characters or paste an id to search.`}
+          {resolvedMinQueryHintLabel}
         </p>
       ) : (
-        <p className="text-xs text-muted-foreground">{startTypingLabel}</p>
+        <p className="text-xs text-muted-foreground">{resolvedStartTypingLabel}</p>
       )}
-      {error ? <p className="text-xs text-destructive">{emptyLabel}</p> : null}
+      {error ? <p className="text-xs text-status-error-text" role="alert">{resolvedEmptyLabel}</p> : null}
     </div>
   )
 }

package/src/backend/inputs/PhoneNumberField.tsx

@@ -1,8 +1,16 @@
 "use client"
 
 import * as React from 'react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { extractPhoneDigits, validatePhoneNumber } from '@open-mercato/shared/lib/phone'
-import { Input } from '../../primitives/input'
+import { cn } from '@open-mercato/shared/lib/utils'
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectItemLeading,
+  SelectTrigger,
+} from '../../primitives/select'
 
 export type PhoneDuplicateMatch = {
   id: string
@@ -10,6 +18,76 @@ export type PhoneDuplicateMatch = {
   href: string
 }
 
+export type PhoneCountry = {
+  /** ISO 3166-1 alpha-2 code. */
+  iso2: string
+  /** International dial code (with `+`). */
+  dialCode: string
+  /** Human-readable country name (English). Override per surface for i18n. */
+  label: string
+  /** Emoji flag (no asset dependency). */
+  flag: string
+}
+
+/**
+ * Static country list — focused on EU + Americas markets where Open Mercato
+ * currently operates. Extend as needed; longest dial codes MUST appear before
+ * their shorter ancestors (e.g. `+380` before `+38`) to keep prefix matching
+ * deterministic. The default fallback is the first entry.
+ */
+export const PHONE_COUNTRIES: PhoneCountry[] = [
+  { iso2: 'US', dialCode: '+1', label: 'United States', flag: '🇺🇸' },
+  { iso2: 'CA', dialCode: '+1', label: 'Canada', flag: '🇨🇦' },
+  { iso2: 'GB', dialCode: '+44', label: 'United Kingdom', flag: '🇬🇧' },
+  { iso2: 'PL', dialCode: '+48', label: 'Poland', flag: '🇵🇱' },
+  { iso2: 'DE', dialCode: '+49', label: 'Germany', flag: '🇩🇪' },
+  { iso2: 'FR', dialCode: '+33', label: 'France', flag: '🇫🇷' },
+  { iso2: 'ES', dialCode: '+34', label: 'Spain', flag: '🇪🇸' },
+  { iso2: 'IT', dialCode: '+39', label: 'Italy', flag: '🇮🇹' },
+  { iso2: 'NL', dialCode: '+31', label: 'Netherlands', flag: '🇳🇱' },
+  { iso2: 'SE', dialCode: '+46', label: 'Sweden', flag: '🇸🇪' },
+  { iso2: 'AT', dialCode: '+43', label: 'Austria', flag: '🇦🇹' },
+  { iso2: 'CH', dialCode: '+41', label: 'Switzerland', flag: '🇨🇭' },
+  { iso2: 'PT', dialCode: '+351', label: 'Portugal', flag: '🇵🇹' },
+  { iso2: 'CZ', dialCode: '+420', label: 'Czechia', flag: '🇨🇿' },
+  { iso2: 'RO', dialCode: '+40', label: 'Romania', flag: '🇷🇴' },
+  { iso2: 'UA', dialCode: '+380', label: 'Ukraine', flag: '🇺🇦' },
+]
+
+const DEFAULT_COUNTRY = PHONE_COUNTRIES[0]
+// Match longer prefixes first to avoid e.g. `+1` shadowing `+1234` if any.
+const COUNTRIES_BY_DIAL_LENGTH = [...PHONE_COUNTRIES].sort(
+  (a, b) => b.dialCode.length - a.dialCode.length,
+)
+
+function findCountryByIso(iso2: string): PhoneCountry | undefined {
+  return PHONE_COUNTRIES.find((c) => c.iso2 === iso2)
+}
+
+function parseCountryFromValue(value: string | null | undefined): PhoneCountry | null {
+  if (!value) return null
+  const trimmed = value.trim()
+  if (!trimmed.startsWith('+')) return null
+  for (const country of COUNTRIES_BY_DIAL_LENGTH) {
+    if (trimmed.startsWith(country.dialCode)) return country
+  }
+  return null
+}
+
+function extractLocalNumber(value: string | null | undefined, dialCode: string): string {
+  if (!value) return ''
+  const trimmed = value.trim()
+  if (!trimmed.startsWith(dialCode)) return trimmed
+  return trimmed.slice(dialCode.length).trim()
+}
+
+function composeValue(country: PhoneCountry, localNumber: string): string {
+  const trimmed = localNumber.trim()
+  if (!trimmed) return ''
+  if (trimmed.startsWith('+')) return trimmed
+  return `${country.dialCode} ${trimmed}`
+}
+
 export type PhoneNumberFieldProps = {
   id?: string
   value?: string | null
@@ -27,10 +105,14 @@ export type PhoneNumberFieldProps = {
   duplicateLinkLabel?: string
   invalidLabel?: string
   onDuplicateLookup?: (normalizedValue: string) => Promise<PhoneDuplicateMatch | null>
+  /** Override the static country list (e.g. limit to specific markets). */
+  countries?: PhoneCountry[]
+  /** Initial country shown when `value` is empty / unparseable. Defaults to US. */
+  defaultCountryIso2?: string
 }
 
 const DEFAULT_MIN_DIGITS = 6
-const DEFAULT_INVALID_LABEL = 'Enter a valid phone number with country code (e.g. +1 212 555 1234)'
+const DEFAULT_PLACEHOLDER = '(555) 000-0000'
 
 export function PhoneNumberField({
   id,
@@ -49,39 +131,74 @@ export function PhoneNumberField({
   duplicateLinkLabel,
   invalidLabel,
   onDuplicateLookup,
+  countries: countriesProp,
+  defaultCountryIso2,
 }: PhoneNumberFieldProps) {
-  const [local, setLocal] = React.useState<string>(() => {
-    if (value == null || value === '') return ''
-    return String(value)
-  })
+  const t = useT()
+  const resolvedInvalidLabel = invalidLabel ?? t(
+    'ui.inputs.phoneNumberField.invalid',
+    'Enter a valid phone number with country code (e.g. +1 212 555 1234)'
+  )
+  const resolvedCheckingLabel = checkingLabel ?? t(
+    'ui.inputs.phoneNumberField.checking',
+    'Checking for duplicates…'
+  )
+  const resolvedDuplicateLinkLabel = duplicateLinkLabel ?? t(
+    'ui.inputs.phoneNumberField.duplicateLink',
+    'Open record'
+  )
+  const resolvedPlaceholder = placeholder ?? DEFAULT_PLACEHOLDER
+  const countries = countriesProp ?? PHONE_COUNTRIES
+  const fallbackCountry = React.useMemo(
+    () => (defaultCountryIso2 && findCountryByIso(defaultCountryIso2)) || DEFAULT_COUNTRY,
+    [defaultCountryIso2],
+  )
+
+  const initialCountry = React.useMemo(
+    () => parseCountryFromValue(value) ?? fallbackCountry,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  )
+  const [country, setCountry] = React.useState<PhoneCountry>(initialCountry)
+  const [localNumber, setLocalNumber] = React.useState<string>(() =>
+    extractLocalNumber(value, initialCountry.dialCode),
+  )
   const [duplicate, setDuplicate] = React.useState<PhoneDuplicateMatch | null>(null)
   const [checking, setChecking] = React.useState(false)
   const [validationHint, setValidationHint] = React.useState<string | null>(null)
+  const [focused, setFocused] = React.useState(false)
   const userEditingRef = React.useRef(false)
+
   const externalFieldError = externalError && externalError.trim().length > 0 ? externalError : null
   const errorMessage = externalFieldError ?? validationHint
   const errorId = errorMessage && id ? `${id}-error` : undefined
   const describedBy = [ariaDescribedBy, errorId].filter((part): part is string => Boolean(part)).join(' ') || undefined
+  const composedValue = composeValue(country, localNumber)
 
+  // Sync local state when `value` updates externally and the user is not editing.
   React.useEffect(() => {
     if (userEditingRef.current) return
     if (value == null || value === '') {
-      setLocal('')
+      setLocalNumber('')
       onDigitsChange?.(null)
       return
     }
-    const nextValue = String(value)
-    setLocal(nextValue)
-    onDigitsChange?.(extractPhoneDigits(nextValue) || null)
-  }, [value, onDigitsChange])
+    const parsed = parseCountryFromValue(value)
+    if (parsed) setCountry(parsed)
+    const next = extractLocalNumber(value, parsed?.dialCode ?? country.dialCode)
+    setLocalNumber(next)
+    onDigitsChange?.(extractPhoneDigits(String(value)) || null)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [value])
 
+  // Debounced duplicate lookup.
   React.useEffect(() => {
     if (!onDuplicateLookup || disabled) {
       setDuplicate(null)
       setChecking(false)
       return
     }
-    const digits = extractPhoneDigits(local)
+    const digits = extractPhoneDigits(composedValue)
     if (!digits || digits.length < minDigits) {
       setDuplicate(null)
       setChecking(false)
@@ -105,74 +222,147 @@ export function PhoneNumberField({
       cancelled = true
       window.clearTimeout(handle)
     }
-  }, [local, disabled, minDigits, onDuplicateLookup])
+  }, [composedValue, disabled, minDigits, onDuplicateLookup])
 
-  const handleChange = React.useCallback(
+  const emit = React.useCallback(
+    (nextCountry: PhoneCountry, nextLocal: string) => {
+      const composed = composeValue(nextCountry, nextLocal)
+      onValueChange(composed.length ? composed : undefined)
+      onDigitsChange?.(extractPhoneDigits(composed) || null)
+    },
+    [onDigitsChange, onValueChange],
+  )
+
+  const handleCountryChange = React.useCallback(
+    (iso2: string) => {
+      const next = findCountryByIso(iso2)
+      if (!next) return
+      userEditingRef.current = true
+      setCountry(next)
+      setValidationHint(null)
+      emit(next, localNumber)
+    },
+    [emit, localNumber],
+  )
+
+  const handleLocalChange = React.useCallback(
     (event: React.ChangeEvent<HTMLInputElement>) => {
       const next = event.target.value
-      const cleanDigits = extractPhoneDigits(next)
       userEditingRef.current = true
-      setLocal(next)
+      setLocalNumber(next)
       setValidationHint(null)
-      onValueChange(next.length ? next : undefined)
-      onDigitsChange?.(cleanDigits.length ? cleanDigits : null)
+      emit(country, next)
     },
-    [onValueChange, onDigitsChange]
+    [country, emit],
   )
 
   const handleBlur = React.useCallback(() => {
     userEditingRef.current = false
-    const trimmed = local.trim()
+    setFocused(false)
+    const trimmed = localNumber.trim()
     if (!trimmed) {
-      setLocal('')
+      setLocalNumber('')
       setValidationHint(null)
       onValueChange(undefined)
       onDigitsChange?.(null)
       return
     }
-    const result = validatePhoneNumber(trimmed)
+    const composed = composeValue(country, trimmed)
+    const result = validatePhoneNumber(composed)
     if (result.valid) {
-      setLocal(result.normalized ?? '')
+      const normalizedLocal = extractLocalNumber(result.normalized ?? composed, country.dialCode)
+      setLocalNumber(normalizedLocal)
       setValidationHint(null)
       onValueChange(result.normalized || undefined)
       onDigitsChange?.(result.digits || null)
     } else {
-      setLocal(trimmed)
-      setValidationHint(invalidLabel ?? DEFAULT_INVALID_LABEL)
-      onValueChange(trimmed)
+      setValidationHint(resolvedInvalidLabel)
+      onValueChange(composed)
       onDigitsChange?.(result.digits || null)
     }
-  }, [invalidLabel, local, onDigitsChange, onValueChange])
+  }, [country, localNumber, onDigitsChange, onValueChange, resolvedInvalidLabel])
+
+  const containerErrorBorder = errorMessage ? 'border-status-error-icon' : 'border-input'
+  const containerFocusBorder = errorMessage
+    ? 'border-status-error-icon shadow-focus'
+    : 'border-brand-violet shadow-focus'
 
   return (
     <div className="space-y-2">
-      <Input
-        type="tel"
-        value={local}
-        onChange={handleChange}
-        onBlur={handleBlur}
-        placeholder={placeholder}
-        autoFocus={autoFocus}
-        disabled={disabled}
-        id={id}
-        aria-label={ariaLabel}
-        aria-describedby={describedBy}
+      <div
+        className={cn(
+          'flex items-stretch w-full rounded-md border bg-background shadow-xs transition-colors',
+          disabled
+            ? 'bg-bg-disabled border-border-disabled cursor-not-allowed'
+            : focused
+              ? containerFocusBorder
+              : `${containerErrorBorder} hover:border-foreground/30`,
+        )}
         aria-invalid={errorMessage ? 'true' : undefined}
-        data-crud-focus-target=""
-      />
+      >
+        <Select value={country.iso2} onValueChange={handleCountryChange} disabled={disabled}>
+          <SelectTrigger
+            aria-label={ariaLabel ? `${ariaLabel} country` : 'Country code'}
+            className={cn(
+              'h-auto w-auto shrink-0 gap-1.5 rounded-none rounded-l-md border-0 bg-transparent px-2.5 py-2 shadow-none',
+              'hover:bg-muted/40 focus:bg-muted/40 focus-visible:shadow-none focus-visible:border-0',
+              'disabled:bg-transparent disabled:hover:bg-transparent',
+            )}
+            onFocus={() => setFocused(true)}
+            onBlur={() => setFocused(false)}
+          >
+            <span className="text-base leading-none" aria-hidden="true">{country.flag}</span>
+            <span className="text-sm text-foreground tabular-nums">{country.dialCode}</span>
+          </SelectTrigger>
+          <SelectContent align="start">
+            {countries.map((c) => (
+              <SelectItem key={`${c.iso2}-${c.dialCode}`} value={c.iso2}>
+                <SelectItemLeading>
+                  <span className="text-base leading-none">{c.flag}</span>
+                </SelectItemLeading>
+                <span className="flex-1 truncate">{c.label}</span>
+                <span className="ml-2 text-xs text-muted-foreground tabular-nums">{c.dialCode}</span>
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+        <div aria-hidden="true" className="w-px self-stretch bg-input" />
+        <input
+          type="tel"
+          inputMode="tel"
+          autoComplete="tel-national"
+          value={localNumber}
+          onChange={handleLocalChange}
+          onBlur={handleBlur}
+          onFocus={() => setFocused(true)}
+          placeholder={resolvedPlaceholder}
+          autoFocus={autoFocus}
+          disabled={disabled}
+          id={id}
+          aria-label={ariaLabel}
+          aria-describedby={describedBy}
+          aria-invalid={errorMessage ? 'true' : undefined}
+          data-crud-focus-target=""
+          className={cn(
+            'flex-1 min-w-0 bg-transparent px-3 py-2 text-sm leading-5 outline-none',
+            'placeholder:text-muted-foreground',
+            'disabled:cursor-not-allowed disabled:text-muted-foreground',
+          )}
+        />
+      </div>
       {errorMessage ? (
-        <p id={errorId} className="text-xs text-destructive">{errorMessage}</p>
+        <p id={errorId} role="alert" className="text-xs text-status-error-text">{errorMessage}</p>
       ) : null}
-      {!disabled && duplicate && duplicateLabel && duplicateLinkLabel ? (
-        <p className="text-xs text-amber-600">
+      {!disabled && duplicate && duplicateLabel ? (
+        <p className="text-xs text-status-warning-text">
           {duplicateLabel(duplicate)}{' '}
-          <a className="font-medium text-primary underline underline-offset-2" href={duplicate.href}>
-            {duplicateLinkLabel}
+          <a className="font-medium text-brand-violet underline underline-offset-2" href={duplicate.href}>
+            {resolvedDuplicateLinkLabel}
           </a>
         </p>
       ) : null}
-      {!disabled && !duplicate && checking && checkingLabel ? (
-        <p className="text-xs text-muted-foreground">{checkingLabel}</p>
+      {!disabled && !duplicate && checking ? (
+        <p className="text-xs text-muted-foreground">{resolvedCheckingLabel}</p>
       ) : null}
     </div>
   )

package/src/backend/inputs/SwitchableMarkdownInput.tsx

@@ -1,3 +1,31 @@
+/**
+ * @deprecated Prefer the DS `RichEditor` primitive from
+ * `@open-mercato/ui/primitives/rich-editor` for any new rich-text input.
+ *
+ * `RichEditor` produces sanitized HTML (with the DS toolbar, color palette,
+ * Figma-aligned styling, and auto-overflow toolbar variants). The DS direction
+ * is to consolidate on a single rich-text format (HTML) so that user-authored
+ * content renders consistently across email, exports, and the customer portal.
+ *
+ * `SwitchableMarkdownInput` is kept as a backward-compatibility shim for
+ * existing Markdown-backed surfaces (notably `customers` Notes). It will be
+ * removed once those surfaces migrate their storage format from Markdown to
+ * sanitized HTML — track the migration in the spec referenced from
+ * `customers/AGENTS.md`.
+ *
+ * Migration:
+ *
+ * ```diff
+ * - import { SwitchableMarkdownInput } from '@open-mercato/ui/backend/inputs/SwitchableMarkdownInput'
+ * - <SwitchableMarkdownInput value={md} onChange={setMd} isMarkdownEnabled={enabled} />
+ * + import { RichEditor } from '@open-mercato/ui/primitives/rich-editor'
+ * + <RichEditor value={html} onChange={setHtml} variant="basic" />
+ * ```
+ *
+ * For surfaces that genuinely need plain Markdown storage (e.g. agent prompts,
+ * code-adjacent docs), keep using `SwitchableMarkdownInput` until a Markdown
+ * mode lands on `RichEditor` — but do NOT introduce new Markdown surfaces.
+ */
 "use client"
 
 import * as React from 'react'
@@ -7,6 +35,7 @@ import { LoadingMessage } from '../detail/LoadingMessage'
 import { useMarkdownRemarkPlugins } from '../markdown/useMarkdownRemarkPlugins'
 import { useTheme } from '../../theme'
 
+/** @deprecated See module-level JSDoc. */
 export type SwitchableMarkdownInputProps = {
   value: string
   onChange: (value: string) => void
@@ -55,6 +84,7 @@ const UiMarkdownEditor = isTestEnv
       ),
     }) as unknown as React.ComponentType<UiMarkdownEditorProps>)
 
+/** @deprecated Use `RichEditor` from `@open-mercato/ui/primitives/rich-editor` for new code. See module JSDoc. */
 export function SwitchableMarkdownInput({
   value,
   onChange,

package/src/backend/inputs/__tests__/ComboboxInput.test.tsx

@@ -1,3 +1,7 @@
+jest.mock('@open-mercato/shared/lib/i18n/context', () => ({
+  useT: () => (_key: string, fallback: string) => fallback,
+}))
+
 import * as React from 'react'
 import { act, render, fireEvent, waitFor } from '@testing-library/react'
 import { ComboboxInput } from '../ComboboxInput'

package/src/backend/inputs/__tests__/PhoneNumberField.test.tsx

@@ -1,5 +1,9 @@
 /** @jest-environment jsdom */
 
+jest.mock('@open-mercato/shared/lib/i18n/context', () => ({
+  useT: () => (_key: string, fallback: string) => fallback,
+}))
+
 jest.mock('@open-mercato/shared/lib/phone', () => ({
   extractPhoneDigits: (value: string | null | undefined) => {
     if (typeof value !== 'string') return ''