@open-mercato/ui 0.6.3-develop.3838.1.7f2657a47c → 0.6.3-develop.3857.1.da89d7530c

package/src/backend/inputs/ComboboxInput.tsx

@@ -1,8 +1,10 @@
 "use client"
 
 import * as React from 'react'
+import { X } from 'lucide-react'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { Button } from '../../primitives/button'
+import { IconButton } from '../../primitives/icon-button'
 
 export type ComboboxOption = {
   value: string
@@ -28,6 +30,8 @@ export type ComboboxInputProps = {
   autoFocus?: boolean
   disabled?: boolean
   allowCustomValues?: boolean
+  clearable?: boolean
+  clearLabel?: string
 }
 
 function normalizeOptions(input?: Array<string | ComboboxOption>): ComboboxOption[] {
@@ -72,10 +76,15 @@ export function ComboboxInput({
   autoFocus,
   disabled = false,
   allowCustomValues = true,
+  clearable = false,
+  clearLabel,
 }: ComboboxInputProps) {
   const t = useT()
   const resolvedPlaceholder = placeholder ?? t('ui.inputs.comboboxInput.placeholder', 'Type to search...')
   const loadingLabel = t('ui.inputs.comboboxInput.loading', 'Loading suggestions…')
+  const resolvedClearLabel = clearLabel ?? t('ui.inputs.comboboxInput.clear', 'Clear value')
+  const blurCloseDelayMs = 250
+  const blurCloseMaxDelayMs = 1000
   const [input, setInput] = React.useState('')
   const [asyncOptions, setAsyncOptions] = React.useState<ComboboxOption[]>([])
   const [resolvedOptions, setResolvedOptions] = React.useState<ComboboxOption[]>([])
@@ -84,6 +93,9 @@ export function ComboboxInput({
   const [showSuggestions, setShowSuggestions] = React.useState(false)
   const [selectedIndex, setSelectedIndex] = React.useState(-1)
   const inputRef = React.useRef<HTMLInputElement>(null)
+  const loadingRef = React.useRef(false)
+  const blurCloseTimerRef = React.useRef<number | null>(null)
+  const blurClosePendingRef = React.useRef(false)
   const suppressOpenOnFocusRef = React.useRef(Boolean(autoFocus && !disabled))
   const eagerFallbackLoadedValueRef = React.useRef<string | null>(null)
 
@@ -92,22 +104,18 @@ export function ComboboxInput({
     [seedOptions, suggestions]
   )
 
-  // Options whose label is genuinely known (not a self-mapping `value === label`
-  // placeholder). Used to decide whether eager resolution still needs to run.
-  const knownLabelValues = React.useMemo(() => {
-    const set = new Set<string>()
-    for (const option of [...staticOptions, ...asyncOptions, ...resolvedOptions]) {
-      if (option.label && option.label !== option.value) set.add(option.value)
+  // Single pass over all option sources to build both coverage sets at once.
+  // knownLabelValues: values with a genuine label (not a self-mapping placeholder) —
+  //   used to decide whether eager resolution still needs to run.
+  // coveredOptionValues: all values present in any source (even self-mapped).
+  const { knownLabelValues, coveredOptionValues } = React.useMemo(() => {
+    const known = new Set<string>()
+    const covered = new Set<string>()
+    for (const opt of [...staticOptions, ...asyncOptions, ...resolvedOptions]) {
+      covered.add(opt.value)
+      if (opt.label && opt.label !== opt.value) known.add(opt.value)
     }
-    return set
-  }, [staticOptions, asyncOptions, resolvedOptions])
-
-  const coveredOptionValues = React.useMemo(() => {
-    const set = new Set<string>()
-    for (const option of [...staticOptions, ...asyncOptions, ...resolvedOptions]) {
-      set.add(option.value)
-    }
-    return set
+    return { knownLabelValues: known, coveredOptionValues: covered }
   }, [staticOptions, asyncOptions, resolvedOptions])
 
   const optionMap = React.useMemo(() => {
@@ -139,6 +147,23 @@ export function ComboboxInput({
     return Array.from(optionMap.values())
   }, [optionMap])
 
+  React.useEffect(() => {
+    loadingRef.current = loading
+  }, [loading])
+
+  const clearBlurCloseTimer = React.useCallback(() => {
+    if (blurCloseTimerRef.current === null) return
+    window.clearTimeout(blurCloseTimerRef.current)
+    blurCloseTimerRef.current = null
+  }, [])
+
+  const resetBlurCloseState = React.useCallback(() => {
+    blurClosePendingRef.current = false
+    clearBlurCloseTimer()
+  }, [clearBlurCloseTimer])
+
+  React.useEffect(() => resetBlurCloseState, [resetBlurCloseState])
+
   const filteredSuggestions = React.useMemo(() => {
     const query = input.toLowerCase().trim()
     if (!query) return availableOptions
@@ -153,17 +178,20 @@ export function ComboboxInput({
     if (!loadSuggestions || !touched || disabled) return
     const query = input.trim()
     let cancelled = false
-    const handle = window.setTimeout(async () => {
+    const handle = window.setTimeout(() => {
       setLoading(true)
-      try {
-        const items = await loadSuggestions(query)
-        if (!cancelled) {
-          const normalized = normalizeOptions(items)
-          setAsyncOptions((prev) => areOptionsEqual(prev, normalized) ? prev : normalized)
-        }
-      } finally {
-        if (!cancelled) setLoading(false)
-      }
+      Promise.resolve()
+        .then(() => loadSuggestions(query))
+        .then((items) => {
+          if (!cancelled) {
+            const normalized = normalizeOptions(items)
+            setAsyncOptions((prev) => areOptionsEqual(prev, normalized) ? prev : normalized)
+          }
+        })
+        .catch(() => {})
+        .finally(() => {
+          if (!cancelled) setLoading(false)
+        })
     }, 200)
     return () => {
       cancelled = true
@@ -198,6 +226,8 @@ export function ComboboxInput({
     eagerFallbackLoadedValueRef.current = value
     // Fallback: pull the first page of async suggestions so a remount that lost
     // its option cache can still recover the label without user interaction.
+    // Note: if the loader is paginated and the value falls outside the first page,
+    // the fallback silently fails and the raw value remains visible.
     if (loadSuggestions) {
       setLoading(true)
       Promise.resolve()
@@ -211,7 +241,8 @@ export function ComboboxInput({
         .finally(() => { if (!cancelled) setLoading(false) })
     }
     return () => { cancelled = true }
-  // eslint-disable-next-line react-hooks/exhaustive-deps
+  // eslint-disable-next-line react-hooks/exhaustive-deps — resolveDescription intentionally excluded:
+  // including it would re-run the effect on every render when the prop is an inline function
   }, [value, disabled, knownLabelValues, coveredOptionValues, eagerResolveLabel, loadSuggestions])
 
   // Sync input with value when value changes externally and input is not focused.
@@ -225,6 +256,7 @@ export function ComboboxInput({
   const selectValue = React.useCallback(
     (nextValue: string) => {
       if (disabled) return
+      resetBlurCloseState()
       const trimmed = nextValue.trim()
       onChange(trimmed)
       const option = optionMap.get(trimmed)
@@ -232,7 +264,7 @@ export function ComboboxInput({
       setShowSuggestions(false)
       setSelectedIndex(-1)
     },
-    [disabled, onChange, optionMap]
+    [disabled, onChange, optionMap, resetBlurCloseState]
   )
 
   const findOptionForInput = React.useCallback(
@@ -251,6 +283,10 @@ export function ComboboxInput({
   const confirmSelection = React.useCallback(
     (raw: string) => {
       if (disabled) return
+      if (clearable && raw.trim() === '') {
+        selectValue('')
+        return
+      }
       const option = findOptionForInput(raw)
       if (option) {
         selectValue(option.value)
@@ -271,9 +307,41 @@ export function ComboboxInput({
       }
       selectValue(raw)
     },
-    [allowCustomValues, disabled, findOptionForInput, optionMap, selectValue, value]
+    [allowCustomValues, clearable, disabled, findOptionForInput, optionMap, selectValue, value]
   )
 
+  const handleClear = React.useCallback(() => {
+    if (disabled) return
+    selectValue('')
+    inputRef.current?.focus()
+  }, [disabled, selectValue])
+
+  const closeAfterBlur = React.useCallback(() => {
+    blurCloseTimerRef.current = null
+    if (disabled) return
+    blurClosePendingRef.current = false
+    confirmSelection(input)
+    setShowSuggestions(false)
+    setSelectedIndex(-1)
+  }, [confirmSelection, disabled, input])
+
+  const attemptBlurClose = React.useCallback(() => {
+    blurCloseTimerRef.current = null
+    if (disabled) return
+    if (loadingRef.current) {
+      blurCloseTimerRef.current = window.setTimeout(closeAfterBlur, blurCloseMaxDelayMs)
+      return
+    }
+    closeAfterBlur()
+  }, [blurCloseMaxDelayMs, closeAfterBlur, disabled])
+
+  React.useEffect(() => {
+    if (!blurClosePendingRef.current) return
+    if (loading) return
+    clearBlurCloseTimer()
+    closeAfterBlur()
+  }, [clearBlurCloseTimer, closeAfterBlur, loading])
+
   const handleKeyDown = React.useCallback(
     (event: React.KeyboardEvent<HTMLInputElement>) => {
       if (disabled) return
@@ -305,6 +373,8 @@ export function ComboboxInput({
     [confirmSelection, disabled, filteredSuggestions, input, selectValue, selectedIndex, showSuggestions]
   )
 
+  const showClearButton = clearable && !disabled && (value !== '' || input !== '')
+
   return (
     <div className="relative w-full">
       {/* Use raw <input> here instead of the DS Input primitive: ComboboxInput's
@@ -314,7 +384,12 @@ export function ComboboxInput({
       <input
         ref={inputRef}
         type="text"
-        className="w-full h-9 rounded-md border border-input bg-background px-3 text-sm shadow-xs transition-colors outline-none placeholder:text-muted-foreground focus-visible:shadow-focus focus-visible:border-foreground disabled:bg-bg-disabled disabled:border-border-disabled disabled:text-muted-foreground disabled:cursor-not-allowed"
+        className={[
+          'w-full h-9 rounded-md border border-input bg-background px-3 text-sm shadow-xs transition-colors outline-none placeholder:text-muted-foreground focus-visible:shadow-focus focus-visible:border-foreground disabled:bg-bg-disabled disabled:border-border-disabled disabled:text-muted-foreground disabled:cursor-not-allowed',
+          showClearButton ? 'pr-9' : '',
+        ]
+          .filter(Boolean)
+          .join(' ')}
         value={input}
         placeholder={resolvedPlaceholder}
         autoFocus={autoFocus}
@@ -326,6 +401,10 @@ export function ComboboxInput({
             suppressOpenOnFocusRef.current = false
             return
           }
+          resetBlurCloseState()
+          if (loadSuggestions && availableOptions.length === 0) {
+            setLoading(true)
+          }
           setShowSuggestions(true)
         }}
         onChange={(event) => {
@@ -336,14 +415,33 @@ export function ComboboxInput({
         }}
         onKeyDown={handleKeyDown}
         onBlur={() => {
-          // Delay to allow click on suggestions
-          setTimeout(() => {
-            if (disabled) return
-            confirmSelection(input)
-          }, 200)
+          // Delay closing so clicks on the popup can resolve first. If async
+          // suggestions are still loading, keep the dropdown open instead of
+          // closing before the first payload arrives.
+          blurClosePendingRef.current = true
+          clearBlurCloseTimer()
+          if (loadingRef.current) {
+            blurCloseTimerRef.current = window.setTimeout(closeAfterBlur, blurCloseMaxDelayMs)
+            return
+          }
+          blurCloseTimerRef.current = window.setTimeout(attemptBlurClose, blurCloseDelayMs)
         }}
       />
 
+      {showClearButton ? (
+        <IconButton
+          type="button"
+          variant="ghost"
+          size="xs"
+          aria-label={resolvedClearLabel}
+          className="absolute right-1 top-1/2 -translate-y-1/2"
+          onMouseDown={(event) => event.preventDefault()}
+          onClick={handleClear}
+        >
+          <X className="size-3" />
+        </IconButton>
+      ) : null}
+
       {showSuggestions && !disabled && (loading || filteredSuggestions.length > 0) && (
         <div className="absolute z-popover w-full mt-1 rounded-md border border-input bg-popover p-2 shadow-md max-h-48 sm:max-h-60 overflow-auto">
           {loading && touched ? (
@@ -363,7 +461,10 @@ export function ComboboxInput({
                     .filter(Boolean)
                     .join(' ')}
                   onMouseDown={(event) => event.preventDefault()}
-                  onClick={() => selectValue(option.value)}
+                  onClick={() => {
+                    resetBlurCloseState()
+                    selectValue(option.value)
+                  }}
                   onMouseEnter={() => setSelectedIndex(index)}
                 >
                   <span className="font-medium text-foreground">{option.label}</span>

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

@@ -1,17 +1,138 @@
+/** @jest-environment jsdom */
+
 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 { act, fireEvent, render, screen, waitFor } from '@testing-library/react'
 import { ComboboxInput } from '../ComboboxInput'
 
+type HarnessProps = Partial<React.ComponentProps<typeof ComboboxInput>> & {
+  initialValue?: string
+}
+
+function Harness({ initialValue = '', onChange, ...rest }: HarnessProps) {
+  const [value, setValue] = React.useState(initialValue)
+  return (
+    <div>
+      <ComboboxInput
+        value={value}
+        onChange={(next) => {
+          setValue(next)
+          onChange?.(next)
+        }}
+        suggestions={[
+          { value: 'red', label: 'Red' },
+          { value: 'green', label: 'Green' },
+        ]}
+        {...rest}
+      />
+      <output data-testid="value">{value}</output>
+    </div>
+  )
+}
+
 function getInput(container: HTMLElement): HTMLInputElement {
   const el = container.querySelector('input')
   if (!el) throw new Error('input not found')
   return el as HTMLInputElement
 }
 
+function blurAndFlush(input: HTMLElement) {
+  act(() => {
+    fireEvent.blur(input)
+  })
+  act(() => {
+    jest.advanceTimersByTime(250)
+  })
+}
+
+describe('ComboboxInput clearable behavior', () => {
+  beforeEach(() => {
+    jest.useFakeTimers()
+  })
+
+  afterEach(() => {
+    act(() => {
+      jest.runOnlyPendingTimers()
+    })
+    jest.useRealTimers()
+  })
+
+  it('reverts to current value on blur with empty input when not clearable and custom values disallowed', () => {
+    const onChange = jest.fn()
+    render(
+      <Harness
+        initialValue="red"
+        clearable={false}
+        allowCustomValues={false}
+        onChange={onChange}
+      />
+    )
+
+    const input = screen.getByRole('textbox') as HTMLInputElement
+    expect(input.value).toBe('Red')
+
+    fireEvent.focus(input)
+    fireEvent.change(input, { target: { value: '' } })
+    expect(input.value).toBe('')
+
+    blurAndFlush(input)
+
+    expect(input.value).toBe('Red')
+    expect(screen.getByTestId('value')).toHaveTextContent('red')
+    expect(onChange).not.toHaveBeenCalled()
+  })
+
+  it('emits empty string on blur with empty input when clearable, regardless of allowCustomValues', () => {
+    const onChange = jest.fn()
+    render(
+      <Harness
+        initialValue="red"
+        clearable
+        allowCustomValues={false}
+        onChange={onChange}
+      />
+    )
+
+    const input = screen.getByRole('textbox') as HTMLInputElement
+    fireEvent.focus(input)
+    fireEvent.change(input, { target: { value: '' } })
+
+    blurAndFlush(input)
+
+    expect(onChange).toHaveBeenCalledWith('')
+    expect(screen.getByTestId('value')).toHaveTextContent('')
+    expect(input.value).toBe('')
+  })
+
+  it('renders a clear button when clearable and a value is set, and clears via click', () => {
+    const onChange = jest.fn()
+    render(<Harness initialValue="red" clearable onChange={onChange} />)
+
+    const input = screen.getByRole('textbox') as HTMLInputElement
+    expect(input.value).toBe('Red')
+
+    const clearBtn = screen.getByRole('button', { name: /clear value/i })
+    fireEvent.click(clearBtn)
+
+    expect(onChange).toHaveBeenCalledWith('')
+    expect(screen.getByTestId('value')).toHaveTextContent('')
+    expect(input.value).toBe('')
+  })
+
+  it('does not render the clear button when clearable is false', () => {
+    render(<Harness initialValue="red" clearable={false} />)
+    expect(screen.queryByRole('button', { name: /clear value/i })).toBeNull()
+  })
+
+  it('does not render the clear button when clearable is true but no value is set', () => {
+    render(<Harness initialValue="" clearable />)
+    expect(screen.queryByRole('button', { name: /clear value/i })).toBeNull()
+  })
+})
+
 describe('ComboboxInput — eager label resolution', () => {
   it('renders the raw value when nothing can resolve it', () => {
     const { container } = render(<ComboboxInput value="uuid-123" onChange={() => {}} />)
@@ -34,7 +155,6 @@ describe('ComboboxInput — eager label resolution', () => {
     const { container } = render(
       <ComboboxInput value="uuid-123" onChange={() => {}} resolveLabel={resolveLabel} />,
     )
-    // before the promise resolves, falls back to the raw value
     expect(getInput(container).value).toBe('uuid-123')
     await waitFor(() => expect(getInput(container).value).toBe('Resolved uuid-123'))
     expect(resolveLabel).toHaveBeenCalledWith('uuid-123')
@@ -52,6 +172,19 @@ describe('ComboboxInput — eager label resolution', () => {
     await waitFor(() => expect(getInput(container).value).toBe('Sync Label'))
   })
 
+  it('swallows synchronous throws from resolveLabel', async () => {
+    const resolveLabel = jest.fn(() => {
+      throw new Error('boom')
+    })
+
+    const { container } = render(
+      <ComboboxInput value="uuid-123" onChange={() => {}} resolveLabel={resolveLabel} />,
+    )
+
+    await waitFor(() => expect(resolveLabel).toHaveBeenCalledWith('uuid-123'))
+    expect(getInput(container).value).toBe('uuid-123')
+  })
+
   it('does not call resolveLabel when the value is already covered by suggestions', () => {
     const resolveLabel = jest.fn(() => 'should-not-be-used')
     render(
@@ -74,6 +207,34 @@ describe('ComboboxInput — eager label resolution', () => {
     expect(loadSuggestions).toHaveBeenCalledWith()
   })
 
+  it('swallows synchronous throws from loadSuggestions', async () => {
+    jest.useFakeTimers()
+    const loadSuggestions = jest.fn(() => {
+      throw new Error('boom')
+    })
+
+    try {
+      const { container } = render(
+        <ComboboxInput value="" onChange={() => {}} loadSuggestions={loadSuggestions} />,
+      )
+      const input = getInput(container)
+
+      act(() => {
+        fireEvent.focus(input)
+        fireEvent.change(input, { target: { value: 'a' } })
+      })
+
+      await act(async () => {
+        jest.advanceTimersByTime(200)
+      })
+
+      await waitFor(() => expect(loadSuggestions).toHaveBeenCalledWith('a'))
+      expect(getInput(container).value).toBe('a')
+    } finally {
+      jest.useRealTimers()
+    }
+  })
+
   it('does not reload suggestions after a self-labeled value is covered', async () => {
     const loadSuggestions = jest.fn(async () => [{ value: 'UTC', label: 'UTC' }])
     const { container } = render(
@@ -81,9 +242,9 @@ describe('ComboboxInput — eager label resolution', () => {
     )
 
     await waitFor(() => expect(loadSuggestions).toHaveBeenCalledTimes(1))
-    await act(async () => {
-      await new Promise((resolve) => setTimeout(resolve, 25))
-    })
+    // flush microtask queue to let any pending effects settle
+    await act(async () => { await Promise.resolve() })
+    await act(async () => { await Promise.resolve() })
 
     expect(loadSuggestions).toHaveBeenCalledTimes(1)
     expect(getInput(container).value).toBe('UTC')
@@ -96,12 +257,85 @@ describe('ComboboxInput — eager label resolution', () => {
     )
 
     await waitFor(() => expect(loadSuggestions).toHaveBeenCalledTimes(1))
+    await act(async () => { await Promise.resolve() })
+    await act(async () => { await Promise.resolve() })
+
+    expect(loadSuggestions).toHaveBeenCalledTimes(1)
+    expect(getInput(container).value).toBe('UTC')
+  })
+
+  it('keeps the popup open when blur happens while async suggestions are still loading', async () => {
+    let resolveSuggestions: (items: Array<string | { value: string; label: string }>) => void = () => {}
+    const loadSuggestions = jest.fn(
+      () =>
+        new Promise<Array<string | { value: string; label: string }>>((resolve) => {
+          resolveSuggestions = resolve
+        }),
+    )
+
+    const { container, queryByText } = render(
+      <div>
+        <ComboboxInput value="" onChange={() => {}} loadSuggestions={loadSuggestions} />
+      </div>,
+    )
+    const input = getInput(container)
+
+    act(() => {
+      fireEvent.focus(input)
+      fireEvent.change(input, { target: { value: 'a' } })
+      fireEvent.blur(input)
+    })
+
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 225))
+    })
+
+    expect(loadSuggestions).toHaveBeenCalledWith('a')
+    await waitFor(() => expect(queryByText(/Loading suggestions/i)).toBeTruthy())
+
     await act(async () => {
+      resolveSuggestions([{ value: 'acme', label: 'Acme Corp' }])
+      await Promise.resolve()
       await new Promise((resolve) => setTimeout(resolve, 25))
     })
 
-    expect(loadSuggestions).toHaveBeenCalledTimes(1)
-    expect(getInput(container).value).toBe('UTC')
+    await waitFor(() => expect(queryByText(/Loading suggestions/i)).toBeNull())
+    await waitFor(() => expect(queryByText('Acme Corp')).toBeNull())
+  })
+
+  it('closes the popup after a bounded delay when async suggestions never finish', async () => {
+    jest.useFakeTimers()
+    const loadSuggestions = jest.fn(
+      () => new Promise<Array<string | { value: string; label: string }>>(() => {}),
+    )
+
+    try {
+      const { container, queryByText } = render(
+        <ComboboxInput value="" onChange={() => {}} loadSuggestions={loadSuggestions} />,
+      )
+      const input = getInput(container)
+
+      act(() => {
+        fireEvent.focus(input)
+        fireEvent.change(input, { target: { value: 'a' } })
+        fireEvent.blur(input)
+      })
+
+      await act(async () => {
+        jest.advanceTimersByTime(450)
+      })
+
+      expect(loadSuggestions).toHaveBeenCalledWith('a')
+      expect(queryByText(/Loading suggestions/i)).toBeTruthy()
+
+      await act(async () => {
+        jest.advanceTimersByTime(1001)
+      })
+
+      expect(queryByText(/Loading suggestions/i)).toBeNull()
+    } finally {
+      jest.useRealTimers()
+    }
   })
 
   it('keeps the resolved label after a blur revert when custom values are disallowed', async () => {
@@ -141,7 +375,6 @@ describe('ComboboxInput — eager label resolution', () => {
       />,
     )
     const input = getInput(container)
-    // user clears the field before resolution lands, then blurs
     act(() => {
       fireEvent.change(input, { target: { value: '' } })
       fireEvent.blur(input)
@@ -149,9 +382,7 @@ describe('ComboboxInput — eager label resolution', () => {
     await act(async () => {
       await new Promise((res) => setTimeout(res, 250))
     })
-    // the raw uuid must not have been written into the visible input
     expect(getInput(container).value).not.toBe('uuid-123')
-    // once resolution arrives, the label shows up
     act(() => resolve('Acme Corp'))
     await waitFor(() => expect(getInput(container).value).toBe('Acme Corp'))
   })