@open-mercato/ui 0.9.1-develop.7474.1.51db10479d → 0.9.1-develop.7475.1.28ca93ed97

package/src/backend/inputs/LookupPickers.tsx

@@ -0,0 +1,181 @@
+'use client'
+
+import * as React from 'react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { ComboboxInput } from './ComboboxInput'
+import { TagsInput } from './TagsInput'
+import {
+  resolveLookupFailureReason,
+  type LookupLoadFailureReason,
+  type LookupOption,
+  type LookupSource,
+} from './lookupSources'
+
+function LookupFailureMessage({ failure }: { failure: LookupLoadFailureReason | null }) {
+  const t = useT()
+  if (!failure) return null
+  return (
+    <p className="mt-1 text-xs text-status-error-text" role="alert" data-testid="lookup-picker-failure">
+      {failure === 'forbidden'
+        ? t('ui.inputs.lookupPicker.forbidden', 'You do not have permission to load these options.')
+        : t('ui.inputs.lookupPicker.loadFailed', 'Could not load options. Try again.')}
+    </p>
+  )
+}
+
+function useLookupFailure() {
+  const [failure, setFailure] = React.useState<LookupLoadFailureReason | null>(null)
+  const guard = React.useCallback(async <TValue,>(run: () => Promise<TValue>, fallback: TValue): Promise<TValue> => {
+    try {
+      const value = await run()
+      setFailure(null)
+      return value
+    } catch (error) {
+      setFailure(resolveLookupFailureReason(error))
+      return fallback
+    }
+  }, [])
+  return { failure, setFailure, guard }
+}
+
+function useLookupLabels(source: LookupSource, ids: readonly string[]) {
+  const [options, setOptions] = React.useState<Record<string, LookupOption>>({})
+  const { failure, setFailure, guard } = useLookupFailure()
+  const requested = React.useRef(new Set<string>())
+
+  const register = React.useCallback((next: readonly LookupOption[]) => {
+    if (next.length === 0) return
+    setOptions((previous) => {
+      const merged = { ...previous }
+      for (const option of next) merged[option.value] = option
+      return merged
+    })
+  }, [])
+
+  const idsKey = ids.join(',')
+  React.useEffect(() => {
+    const missing = idsKey
+      .split(',')
+      .filter((id) => id.length > 0 && !requested.current.has(id))
+    if (missing.length === 0) return
+    for (const id of missing) requested.current.add(id)
+    let cancelled = false
+    let settled = false
+    const release = () => {
+      for (const id of missing) requested.current.delete(id)
+    }
+    void source.resolve(missing).then(
+      (resolved) => {
+        settled = true
+        if (cancelled) return
+        register(resolved)
+        setFailure(null)
+      },
+      (error: unknown) => {
+        settled = true
+        if (cancelled) return
+        release()
+        setFailure(resolveLookupFailureReason(error))
+      },
+    )
+    return () => {
+      cancelled = true
+      if (!settled) release()
+    }
+  }, [idsKey, register, setFailure, source])
+
+  const search = React.useCallback(
+    (query?: string) =>
+      guard(async () => {
+        const found = await source.search(query)
+        register(found)
+        return found
+      }, []),
+    [guard, register, source],
+  )
+
+  return { options, search, failure }
+}
+
+type LookupMultiPickerProps = {
+  source: LookupSource
+  value: string[]
+  onChange: (next: string[]) => void
+  placeholder?: string
+  disabled?: boolean
+}
+
+export function LookupMultiPicker({ source, value, onChange, placeholder, disabled }: LookupMultiPickerProps) {
+  const { options, search, failure } = useLookupLabels(source, value)
+  const suggestions = React.useMemo(() => Object.values(options), [options])
+  return (
+    <div>
+      <TagsInput
+        value={value}
+        onChange={onChange}
+        suggestions={suggestions}
+        loadSuggestions={search}
+        allowCustomValues={false}
+        closeSuggestionsOnSelect
+        resolveLabel={(id) => options[id]?.label ?? id}
+        resolveDescription={(id) => options[id]?.description ?? null}
+        placeholder={placeholder}
+        disabled={disabled}
+      />
+      <LookupFailureMessage failure={failure} />
+    </div>
+  )
+}
+
+type LookupSinglePickerProps = {
+  source: LookupSource
+  value: string
+  onChange: (next: string) => void
+  placeholder?: string
+  disabled?: boolean
+  clearable?: boolean
+}
+
+export function LookupSinglePicker({
+  source,
+  value,
+  onChange,
+  placeholder,
+  disabled,
+  clearable,
+}: LookupSinglePickerProps) {
+  const { failure, guard } = useLookupFailure()
+  const resolveLabel = React.useCallback(
+    (id: string) =>
+      guard(async () => {
+        const [option] = await source.resolve([id])
+        return option?.label ?? id
+      }, id),
+    [guard, source],
+  )
+  const search = React.useCallback((query?: string) => guard(() => source.search(query), []), [guard, source])
+  return (
+    <div>
+      <ComboboxInput
+        value={value}
+        onChange={onChange}
+        allowCustomValues={false}
+        clearable={clearable}
+        placeholder={placeholder}
+        disabled={disabled}
+        loadSuggestions={search}
+        resolveLabel={resolveLabel}
+      />
+      <LookupFailureMessage failure={failure} />
+    </div>
+  )
+}
+
+export function useLookupLabelMap(source: LookupSource, ids: readonly string[]): Record<string, string> {
+  const { options } = useLookupLabels(source, ids)
+  return React.useMemo(() => {
+    const labels: Record<string, string> = {}
+    for (const [id, option] of Object.entries(options)) labels[id] = option.label
+    return labels
+  }, [options])
+}

package/src/backend/inputs/TagsInput.tsx

@@ -25,6 +25,7 @@ export type TagsInputProps = {
   allowCustomValues?: boolean
   showSuggestionsOnFocus?: boolean
   suppressInitialSuggestionsOnFocus?: boolean
+  closeSuggestionsOnSelect?: boolean
 }
 
 function normalizeOptions(input?: Array<string | TagsInputOption>): TagsInputOption[] {
@@ -61,6 +62,7 @@ export function TagsInput({
   allowCustomValues = true,
   showSuggestionsOnFocus = true,
   suppressInitialSuggestionsOnFocus = false,
+  closeSuggestionsOnSelect = false,
 }: TagsInputProps) {
   const t = useT()
   const [input, setInput] = React.useState('')
@@ -275,6 +277,7 @@ export function TagsInput({
               event.preventDefault()
               addTag(input)
               setInput('')
+              if (closeSuggestionsOnSelect) setSuggestionsDismissed(true)
             } else if (event.key === 'Backspace' && input === '' && value.length > 0) {
               removeTag(value[value.length - 1])
             }
@@ -310,6 +313,7 @@ export function TagsInput({
                   suppressBlurCommitRef.current = false
                   addValue(option.value)
                   setInput('')
+                  if (closeSuggestionsOnSelect) setSuggestionsDismissed(true)
                 }}
               >
                 <span>{option.label}</span>

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

@@ -0,0 +1,120 @@
+/** @jest-environment jsdom */
+import * as React from 'react'
+import { fireEvent, screen } from '@testing-library/react'
+import { renderWithProviders } from '@open-mercato/shared/lib/testing/renderWithProviders'
+import { LookupMultiPicker, LookupSinglePicker } from '../LookupPickers'
+import { LookupLoadError, type LookupSource } from '../lookupSources'
+
+const options = [
+  { value: 'cat-1', label: 'Category One' },
+  { value: 'cat-2', label: 'Category Two' },
+]
+
+const source: LookupSource = {
+  id: 'test',
+  search: jest.fn().mockResolvedValue(options),
+  resolve: jest.fn().mockResolvedValue([]),
+}
+
+function Harness() {
+  const [value, setValue] = React.useState<string[]>([])
+  return <LookupMultiPicker source={source} value={value} onChange={setValue} />
+}
+
+describe('LookupMultiPicker', () => {
+  it('closes the suggestion list after a pick', async () => {
+    renderWithProviders(<Harness />)
+    fireEvent.focus(screen.getByRole('textbox'))
+    fireEvent.click(await screen.findByRole('button', { name: /Category One/ }))
+
+    expect(screen.queryByRole('button', { name: /Category Two/ })).not.toBeInTheDocument()
+  })
+})
+
+describe('LookupMultiPicker label resolution', () => {
+  it('resolves saved ids to labels under StrictMode, where the first lookup is cancelled', async () => {
+    const resolve = jest.fn(async (ids: readonly string[]) => options.filter((option) => ids.includes(option.value)))
+    const strictSource: LookupSource = { id: 'strict', search: jest.fn().mockResolvedValue([]), resolve }
+    renderWithProviders(
+      <React.StrictMode>
+        <LookupMultiPicker source={strictSource} value={['cat-2']} onChange={() => undefined} />
+      </React.StrictMode>,
+    )
+
+    expect(await screen.findByText('Category Two')).toBeInTheDocument()
+  })
+
+  it('retries ids whose lookup failed', async () => {
+    const resolve = jest
+      .fn()
+      .mockRejectedValueOnce(new Error('[internal] lookup failed'))
+      .mockImplementation(async (ids: readonly string[]) => options.filter((option) => ids.includes(option.value)))
+    const failingSource: LookupSource = { id: 'failing', search: jest.fn().mockResolvedValue([]), resolve }
+    const { rerender } = renderWithProviders(
+      <LookupMultiPicker source={failingSource} value={['cat-1']} onChange={() => undefined} />,
+    )
+    await screen.findByText('cat-1')
+    await Promise.resolve()
+    rerender(<LookupMultiPicker source={failingSource} value={['cat-1', 'cat-2']} onChange={() => undefined} />)
+
+    expect(await screen.findByText('Category One')).toBeInTheDocument()
+    expect(screen.getByText('Category Two')).toBeInTheDocument()
+  })
+})
+
+describe('LookupPickers load failures', () => {
+  it('shows an inline message when the options cannot be loaded', async () => {
+    const failingSource: LookupSource = {
+      id: 'offline',
+      search: jest.fn().mockRejectedValue(new LookupLoadError('failed', '/api/example')),
+      resolve: jest.fn().mockResolvedValue([]),
+    }
+    renderWithProviders(<LookupMultiPicker source={failingSource} value={[]} onChange={() => undefined} />)
+    fireEvent.focus(screen.getByRole('textbox'))
+
+    expect(await screen.findByTestId('lookup-picker-failure')).toHaveTextContent('Could not load options. Try again.')
+  })
+
+  it('tells the user when access to the options is forbidden', async () => {
+    const forbiddenSource: LookupSource = {
+      id: 'forbidden',
+      search: jest.fn().mockResolvedValue([]),
+      resolve: jest.fn().mockRejectedValue(new LookupLoadError('forbidden', '/api/example')),
+    }
+    renderWithProviders(<LookupMultiPicker source={forbiddenSource} value={['cat-1']} onChange={() => undefined} />)
+
+    expect(await screen.findByTestId('lookup-picker-failure')).toHaveTextContent(
+      'You do not have permission to load these options.',
+    )
+  })
+
+  it('clears the message once a later load succeeds', async () => {
+    const search = jest
+      .fn()
+      .mockRejectedValueOnce(new LookupLoadError('failed', '/api/example'))
+      .mockResolvedValue(options)
+    const flakySource: LookupSource = { id: 'flaky', search, resolve: jest.fn().mockResolvedValue([]) }
+    renderWithProviders(<LookupMultiPicker source={flakySource} value={[]} onChange={() => undefined} />)
+    const input = screen.getByRole('textbox')
+    fireEvent.focus(input)
+    await screen.findByTestId('lookup-picker-failure')
+
+    fireEvent.change(input, { target: { value: 'Cat' } })
+
+    expect(await screen.findByRole('button', { name: /Category One/ })).toBeInTheDocument()
+    expect(screen.queryByTestId('lookup-picker-failure')).not.toBeInTheDocument()
+  })
+
+  it('keeps the raw id and shows the failure when a single picker cannot resolve its label', async () => {
+    const failingSource: LookupSource = {
+      id: 'single',
+      search: jest.fn().mockResolvedValue([]),
+      resolve: jest.fn().mockRejectedValue(new LookupLoadError('forbidden', '/api/example')),
+    }
+    renderWithProviders(<LookupSinglePicker source={failingSource} value="cat-1" onChange={() => undefined} />)
+
+    expect(await screen.findByTestId('lookup-picker-failure')).toHaveTextContent(
+      'You do not have permission to load these options.',
+    )
+  })
+})

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

@@ -116,6 +116,47 @@ describe('TagsInput', () => {
     jest.useRealTimers()
   })
 
+  describe('closeSuggestionsOnSelect', () => {
+    const pickSuggestions = [
+      { value: 'cat-1', label: 'Category One' },
+      { value: 'cat-2', label: 'Category Two' },
+    ]
+
+    function PickHarness({ closeSuggestionsOnSelect }: { closeSuggestionsOnSelect?: boolean }) {
+      const [value, setValue] = React.useState<string[]>([])
+      return (
+        <TagsInput
+          value={value}
+          onChange={setValue}
+          suggestions={pickSuggestions}
+          closeSuggestionsOnSelect={closeSuggestionsOnSelect}
+        />
+      )
+    }
+
+    it('keeps the remaining suggestions open after a pick by default', () => {
+      renderWithProviders(<PickHarness />)
+      const input = screen.getByRole('textbox')
+      fireEvent.focus(input)
+      fireEvent.click(screen.getByRole('button', { name: /Category One/ }))
+
+      expect(screen.getByRole('button', { name: /Category Two/ })).toBeInTheDocument()
+    })
+
+    it('dismisses the suggestions after a pick when opted in and reopens them on the next interaction', () => {
+      renderWithProviders(<PickHarness closeSuggestionsOnSelect />)
+      const input = screen.getByRole('textbox')
+      fireEvent.focus(input)
+      fireEvent.click(screen.getByRole('button', { name: /Category One/ }))
+
+      expect(screen.queryByRole('button', { name: /Category Two/ })).not.toBeInTheDocument()
+
+      fireEvent.mouseDown(input)
+
+      expect(screen.getByRole('button', { name: /Category Two/ })).toBeInTheDocument()
+    })
+  })
+
   describe('Escape on the suggestions list', () => {
     it('closes only the suggestions and keeps Escape away from the host', () => {
       const onHostKeyDown = jest.fn()

package/src/backend/inputs/__tests__/lookupSources.test.ts

@@ -0,0 +1,87 @@
+import { readApiResultOrThrow } from '../../utils/apiCall'
+import {
+  LookupLoadError,
+  createIdsLookupSource,
+  lookupLabelWithCode,
+  pickLookupString,
+  resolveLookupFailureReason,
+} from '../lookupSources'
+
+jest.mock('../../utils/apiCall', () => ({
+  readApiResultOrThrow: jest.fn(),
+}))
+
+const readMock = readApiResultOrThrow as jest.Mock
+
+const source = createIdsLookupSource(
+  'widgets',
+  '/api/example/widgets',
+  (item) => {
+    const value = pickLookupString(item, 'id')
+    return value ? { value, label: pickLookupString(item, 'name') || value } : null
+  },
+  { view: 'manage' },
+)
+
+function httpError(status: number): Error & { status: number } {
+  return Object.assign(new Error('[internal] request failed'), { status })
+}
+
+describe('createIdsLookupSource', () => {
+  beforeEach(() => readMock.mockReset())
+
+  it('searches with extra params and drops items without an id', async () => {
+    readMock.mockResolvedValue({ items: [{ id: 'w-1', name: 'Widget' }, { name: 'no id' }] })
+    expect(await source.search(' wid ')).toEqual([{ value: 'w-1', label: 'Widget' }])
+    const url = new URL(readMock.mock.calls[0][0] as string, 'http://localhost')
+    expect(url.pathname).toBe('/api/example/widgets')
+    expect(url.searchParams.get('view')).toBe('manage')
+    expect(url.searchParams.get('search')).toBe('wid')
+  })
+
+  it('resolves selected ids without issuing a request for an empty list', async () => {
+    expect(await source.resolve([])).toEqual([])
+    expect(readMock).not.toHaveBeenCalled()
+  })
+
+  it('resolves ids in chunks of at most 100 through the ids filter', async () => {
+    const ids = Array.from({ length: 250 }, (_, index) => `id-${index}`)
+    readMock.mockImplementation(async (path: string) => {
+      const requested = new URL(path, 'http://localhost').searchParams.get('ids')?.split(',') ?? []
+      return { items: requested.map((id) => ({ id, name: id })) }
+    })
+    const options = await source.resolve([...ids, 'id-0'])
+    expect(options.map((option) => option.value)).toEqual(ids)
+    expect(readMock).toHaveBeenCalledTimes(3)
+    for (const [path] of readMock.mock.calls) {
+      const params = new URL(path as string, 'http://localhost').searchParams
+      expect(params.get('ids')?.split(',').length).toBeLessThanOrEqual(100)
+      expect(Number(params.get('pageSize'))).toBeLessThanOrEqual(100)
+    }
+  })
+
+  it('rejects with a forbidden failure when the endpoint denies access', async () => {
+    readMock.mockRejectedValue(httpError(403))
+    const error = await source.search('x').catch((err: unknown) => err)
+    expect(error).toBeInstanceOf(LookupLoadError)
+    expect(resolveLookupFailureReason(error)).toBe('forbidden')
+  })
+
+  it('rejects with a generic failure when the endpoint is unreachable', async () => {
+    readMock.mockRejectedValue(new Error('offline'))
+    const error = await source.resolve(['w-1']).catch((err: unknown) => err)
+    expect(resolveLookupFailureReason(error)).toBe('failed')
+  })
+})
+
+describe('lookup helpers', () => {
+  it('treats any non-lookup error as a generic failure', () => {
+    expect(resolveLookupFailureReason(new Error('boom'))).toBe('failed')
+    expect(resolveLookupFailureReason(undefined)).toBe('failed')
+  })
+
+  it('appends the code only when it differs from the label', () => {
+    expect(lookupLabelWithCode('Retail', 'retail')).toBe('Retail (retail)')
+    expect(lookupLabelWithCode('Retail', '')).toBe('Retail')
+  })
+})

package/src/backend/inputs/index.ts

@@ -10,3 +10,5 @@ export * from './TimePicker'
 export * from './DateTimePicker'
 export * from './DatePicker'
 export * from './DurationInput'
+export * from './lookupSources'
+export * from './LookupPickers'

package/src/backend/inputs/lookupSources.ts

@@ -0,0 +1,114 @@
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { readApiResultOrThrow } from '../utils/apiCall'
+
+const logger = createLogger('ui').child({ component: 'lookup-sources' })
+
+export type LookupOption = { value: string; label: string; description?: string | null }
+
+export type LookupSource = {
+  id: string
+  search: (query?: string) => Promise<LookupOption[]>
+  resolve: (ids: readonly string[]) => Promise<LookupOption[]>
+}
+
+export type LookupRemoteItem = Record<string, unknown>
+
+export type LookupLoadFailureReason = 'forbidden' | 'failed'
+
+export class LookupLoadError extends Error {
+  readonly reason: LookupLoadFailureReason
+
+  constructor(reason: LookupLoadFailureReason, path: string) {
+    super(`[internal] lookup load failed (${reason}) for ${path}`)
+    this.name = 'LookupLoadError'
+    this.reason = reason
+  }
+}
+
+export function resolveLookupFailureReason(error: unknown): LookupLoadFailureReason {
+  if (!error || typeof error !== 'object') return 'failed'
+  const candidate = error as { name?: unknown; reason?: unknown }
+  return candidate.name === 'LookupLoadError' && candidate.reason === 'forbidden' ? 'forbidden' : 'failed'
+}
+
+function readErrorStatus(error: unknown): number | null {
+  if (!error || typeof error !== 'object') return null
+  const status = (error as { status?: unknown }).status
+  return typeof status === 'number' ? status : null
+}
+
+const SEARCH_PAGE_SIZE = '50'
+const RESOLVE_CHUNK_SIZE = 100
+
+export function pickLookupString(item: LookupRemoteItem, ...keys: string[]): string {
+  for (const key of keys) {
+    const value = item[key]
+    if (typeof value === 'string' && value.trim().length > 0) return value.trim()
+  }
+  return ''
+}
+
+async function loadItems(path: string, params: Record<string, string>): Promise<LookupRemoteItem[]> {
+  try {
+    const search = new URLSearchParams(params)
+    const payload = await readApiResultOrThrow<{ items?: LookupRemoteItem[] }>(`${path}?${search.toString()}`, undefined, {
+      fallback: { items: [] },
+    })
+    return Array.isArray(payload?.items) ? payload.items : []
+  } catch (err) {
+    const status = readErrorStatus(err)
+    logger.warn('ui.lookups.load.failed', { err, path, status })
+    throw new LookupLoadError(status === 401 || status === 403 ? 'forbidden' : 'failed', path)
+  }
+}
+
+function mapItems(items: LookupRemoteItem[], mapItem: (item: LookupRemoteItem) => LookupOption | null): LookupOption[] {
+  return items.map(mapItem).filter((option): option is LookupOption => option !== null)
+}
+
+function chunkIds(ids: readonly string[]): string[][] {
+  const unique = Array.from(new Set(ids))
+  const chunks: string[][] = []
+  for (let start = 0; start < unique.length; start += RESOLVE_CHUNK_SIZE) {
+    chunks.push(unique.slice(start, start + RESOLVE_CHUNK_SIZE))
+  }
+  return chunks
+}
+
+/** Resolves `ids` through the `?ids=` filter in chunks of at most 100, one request per chunk. */
+async function resolveByIds(
+  path: string,
+  ids: readonly string[],
+  mapItem: (item: LookupRemoteItem) => LookupOption | null,
+  extraParams: Record<string, string> = {},
+): Promise<LookupOption[]> {
+  const chunks = chunkIds(ids)
+  const pages = await Promise.all(
+    chunks.map((chunk) =>
+      loadItems(path, { ...extraParams, ids: chunk.join(','), pageSize: String(chunk.length) }),
+    ),
+  )
+  return mapItems(pages.flat(), mapItem)
+}
+
+function searchParams(query: string | undefined, pageSize: string): Record<string, string> {
+  const trimmed = (query ?? '').trim()
+  return trimmed.length > 0 ? { search: trimmed, pageSize } : { pageSize }
+}
+
+export function createIdsLookupSource(
+  id: string,
+  path: string,
+  mapItem: (item: LookupRemoteItem) => LookupOption | null,
+  extraParams: Record<string, string> = {},
+): LookupSource {
+  return {
+    id,
+    search: async (query) => mapItems(await loadItems(path, { ...extraParams, ...searchParams(query, SEARCH_PAGE_SIZE) }), mapItem),
+    resolve: (ids) => resolveByIds(path, ids, mapItem, extraParams),
+  }
+}
+
+export function lookupLabelWithCode(label: string, code: string): string {
+  return code && code !== label ? `${label} (${code})` : label
+}