@open-mercato/core 0.8.1-develop.7221.1.ece7ca874e → 0.8.1-develop.7227.1.9248c14599

package/src/modules/catalog/components/prices/PricesDataTable.tsx

@@ -0,0 +1,320 @@
+"use client"
+
+import * as React from 'react'
+import Link from 'next/link'
+import { useQuery, useQueryClient } from '@tanstack/react-query'
+import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
+import { extensionPoints } from '@open-mercato/core/modules/catalog/extension-points'
+import { DataTable } from '@open-mercato/ui/backend/DataTable'
+import { ListEmptyState } from '@open-mercato/ui/backend/filters/ListEmptyState'
+import { RowActions } from '@open-mercato/ui/backend/RowActions'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { Tag } from '@open-mercato/ui/primitives/tag'
+import { apiCall, apiCallOrThrow, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
+import { useT, type TranslateFn } from '@open-mercato/shared/lib/i18n/context'
+import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
+import { useBatchLabels } from './useBatchLabels'
+import { normalizePriceRecord, type NormalizedPriceRecord } from './normalizePriceRecord'
+
+type PriceRow = NormalizedPriceRecord
+
+type PricesResponse = {
+  items: PriceRow[]
+  total: number
+  page: number
+  pageSize: number
+  totalPages: number
+  totalIsCapped?: boolean
+}
+
+const PAGE_SIZE = 50
+
+const KIND_TAG_VARIANT: Record<string, 'brand' | 'warning' | 'info' | 'neutral'> = {
+  custom: 'brand',
+  promotion: 'warning',
+  tier: 'info',
+  regular: 'neutral',
+}
+
+function formatAmount(row: PriceRow): string {
+  const amount = row.unitPriceNet ?? row.unitPriceGross
+  if (amount == null) return '—'
+  return row.currencyCode ? `${amount} ${row.currencyCode}` : amount
+}
+
+function formatQuantityRange(row: PriceRow, t: TranslateFn): string {
+  if (row.maxQuantity != null) {
+    return `${row.minQuantity}–${row.maxQuantity}`
+  }
+  return t('catalog.prices.list.quantity.min', '{{min}}+', { min: row.minQuantity })
+}
+
+export default function PricesDataTable({ productId }: { productId?: string } = {}) {
+  const t = useT()
+  const { confirm, ConfirmDialogElement } = useConfirmDialog()
+  const queryClient = useQueryClient()
+  const scopeVersion = useOrganizationScopeVersion()
+  const [page, setPage] = React.useState(1)
+  const [search, setSearch] = React.useState('')
+  const [canManage, setCanManage] = React.useState(false)
+
+  React.useEffect(() => {
+    let cancelled = false
+    async function load() {
+      try {
+        const call = await apiCall<{ granted?: string[]; ok?: boolean }>('/api/auth/feature-check', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ features: ['catalog.pricing.manage'] }),
+        })
+        if (!cancelled) {
+          const granted = Array.isArray(call.result?.granted) ? call.result.granted : []
+          setCanManage(call.result?.ok === true || granted.includes('catalog.pricing.manage'))
+        }
+      } catch {
+        if (!cancelled) setCanManage(false)
+      }
+    }
+    load()
+    return () => {
+      cancelled = true
+    }
+  }, [])
+
+  const queryParams = React.useMemo(() => {
+    const params = new URLSearchParams()
+    params.set('page', String(page))
+    params.set('pageSize', String(PAGE_SIZE))
+    if (productId) params.set('productId', productId)
+    if (search) params.set('search', search)
+    return params.toString()
+  }, [page, productId, search])
+
+  const { data, isLoading } = useQuery<PricesResponse>({
+    queryKey: ['catalog-prices', queryParams, scopeVersion],
+    queryFn: async () => {
+      const payload = await readApiResultOrThrow<{
+        items?: Array<Record<string, unknown>>
+        total?: number
+        page?: number
+        pageSize?: number
+        totalPages?: number
+        totalIsCapped?: boolean
+      }>(
+        `/api/catalog/prices?${queryParams}`,
+        undefined,
+        { errorMessage: t('catalog.prices.list.error.load', 'Failed to load price rules') },
+      )
+      const rawItems = Array.isArray(payload.items) ? payload.items : []
+      return {
+        items: rawItems.map(normalizePriceRecord),
+        total: typeof payload.total === 'number' ? payload.total : 0,
+        page: typeof payload.page === 'number' ? payload.page : 1,
+        pageSize: typeof payload.pageSize === 'number' ? payload.pageSize : PAGE_SIZE,
+        totalPages: typeof payload.totalPages === 'number' ? payload.totalPages : 1,
+        totalIsCapped: payload.totalIsCapped === true,
+      }
+    },
+  })
+
+  const rows = data?.items ?? []
+  const total = data?.total ?? 0
+  const totalPages = data?.totalPages ?? 0
+  const totalIsCapped = data?.totalIsCapped === true
+
+  const productIds = React.useMemo(() => rows.map((row) => row.variantId ?? row.productId).filter((id): id is string => !!id), [rows])
+  const mapProduct = React.useCallback((item: Record<string, unknown>) => {
+    const id = typeof item.id === 'string' ? item.id : ''
+    if (!id) return null
+    const label = typeof item.title === 'string' ? item.title : (typeof item.name === 'string' ? item.name : id)
+    return { id, label }
+  }, [])
+  const productLabels = useBatchLabels('/api/catalog/products', rows.filter((r) => !r.variantId).map((r) => r.productId ?? ''), mapProduct)
+  const variantLabels = useBatchLabels('/api/catalog/variants', rows.filter((r) => r.variantId).map((r) => r.variantId ?? ''), mapProduct)
+
+  const customerIds = React.useMemo(() => rows.map((row) => row.customerId).filter((id): id is string => !!id), [rows])
+  const mapCustomer = React.useCallback((item: Record<string, unknown>) => {
+    const id = typeof item.id === 'string' ? item.id : ''
+    if (!id) return null
+    const label = typeof item.displayName === 'string' ? item.displayName : (typeof item.display_name === 'string' ? item.display_name : id)
+    return { id, label }
+  }, [])
+  const customerLabels = useBatchLabels('/api/customers/people', customerIds, mapCustomer)
+
+  const channelIds = React.useMemo(() => rows.map((row) => row.channelId).filter((id): id is string => !!id), [rows])
+  const mapChannel = React.useCallback((item: Record<string, unknown>) => {
+    const id = typeof item.id === 'string' ? item.id : ''
+    if (!id) return null
+    const label = typeof item.name === 'string' ? item.name : id
+    return { id, label }
+  }, [])
+  const channelLabels = useBatchLabels('/api/sales/channels', channelIds, mapChannel)
+
+  const handleDelete = React.useCallback(async (row: PriceRow) => {
+    const confirmed = await confirm({
+      title: t('catalog.prices.list.confirmDelete', 'Delete this price rule?'),
+      variant: 'destructive',
+    })
+    if (!confirmed) return
+    try {
+      // optimistic-lock-exempt: delete-only mutation — no field-level lost-update
+      await apiCallOrThrow(
+        `/api/catalog/prices?id=${encodeURIComponent(row.id)}`,
+        { method: 'DELETE' },
+        { errorMessage: t('catalog.prices.list.error.delete', 'Failed to delete price rule') },
+      )
+      await queryClient.invalidateQueries({ queryKey: ['catalog-prices'] })
+      flash(t('catalog.prices.flash.deleted', 'Price rule deleted'), 'success')
+    } catch (err: unknown) {
+      const fallback = t('catalog.prices.list.error.delete', 'Failed to delete price rule')
+      const message = err instanceof Error ? err.message : fallback
+      flash(message, 'error')
+    }
+  }, [confirm, queryClient, t])
+
+  const columns = React.useMemo<ColumnDef<PriceRow>[]>(() => [
+    {
+      id: 'product',
+      header: t('catalog.prices.list.columns.product', 'Product'),
+      meta: { priority: 1 },
+      cell: ({ row }) => {
+        const price = row.original
+        const label = price.variantId
+          ? (variantLabels[price.variantId] ?? price.variantId)
+          : (price.productId ? (productLabels[price.productId] ?? price.productId) : '—')
+        return <span className="text-sm font-medium text-foreground">{label}</span>
+      },
+    },
+    {
+      id: 'kind',
+      header: t('catalog.prices.list.columns.kind', 'Kind'),
+      meta: { priority: 2 },
+      cell: ({ row }) => {
+        const kind = row.original.kind || 'regular'
+        return <Tag variant={KIND_TAG_VARIANT[kind] ?? 'neutral'}>{kind}</Tag>
+      },
+    },
+    {
+      id: 'amount',
+      header: t('catalog.prices.list.columns.amount', 'Amount'),
+      meta: { priority: 1 },
+      cell: ({ row }) => <span className="text-sm">{formatAmount(row.original)}</span>,
+    },
+    {
+      id: 'scope',
+      header: t('catalog.prices.list.columns.scope', 'Scope'),
+      meta: { priority: 3 },
+      cell: ({ row }) => {
+        const price = row.original
+        const chips: React.ReactNode[] = []
+        if (price.customerId) {
+          chips.push(
+            <Tag key="customer" variant="info" dot>
+              {customerLabels[price.customerId] ?? t('catalog.prices.list.scope.customer', 'Customer')}
+            </Tag>,
+          )
+        }
+        if (price.customerGroupId) {
+          chips.push(
+            <Tag key="customerGroup" variant="info" dot>
+              {t('catalog.prices.list.scope.customerGroup', 'Customer group')}
+            </Tag>,
+          )
+        }
+        if (price.channelId) {
+          chips.push(
+            <Tag key="channel" variant="neutral" dot>
+              {channelLabels[price.channelId] ?? t('catalog.prices.list.scope.channel', 'Channel')}
+            </Tag>,
+          )
+        }
+        if (!chips.length) return <span className="text-xs text-muted-foreground">—</span>
+        return <div className="flex flex-wrap gap-1">{chips}</div>
+      },
+    },
+    {
+      id: 'quantity',
+      header: t('catalog.prices.list.columns.quantity', 'Quantity'),
+      meta: { priority: 4 },
+      cell: ({ row }) => <span className="text-sm">{formatQuantityRange(row.original, t)}</span>,
+    },
+    {
+      id: 'validity',
+      header: t('catalog.prices.list.columns.validity', 'Validity'),
+      meta: { priority: 5 },
+      cell: ({ row }) => {
+        const price = row.original
+        const isExpired = Boolean(price.endsAt && new Date(price.endsAt) < new Date())
+        if (!price.startsAt && !price.endsAt) {
+          return <span className="text-sm text-muted-foreground">{t('catalog.prices.list.validity.always', 'Always')}</span>
+        }
+        const from = price.startsAt ? new Date(price.startsAt).toLocaleDateString() : null
+        const until = price.endsAt ? new Date(price.endsAt).toLocaleDateString() : null
+        const label = from && until
+          ? t('catalog.prices.list.validity.range', '{{from}} – {{until}}', { from, until })
+          : from
+            ? t('catalog.prices.list.validity.from', 'From {{date}}', { date: from })
+            : t('catalog.prices.list.validity.until', 'Until {{date}}', { date: until ?? '' })
+        return (
+          <div className="flex items-center gap-2">
+            <span className="text-sm">{label}</span>
+            {isExpired ? <Tag variant="error" dot>{t('catalog.prices.list.badge.expired', 'Expired')}</Tag> : null}
+          </div>
+        )
+      },
+    },
+  ], [t, variantLabels, productLabels, customerLabels, channelLabels])
+
+  return (
+    <>
+      <DataTable
+        title={t('catalog.prices.list.title', 'Price rules')}
+        titleHeadingLevel={1}
+        actions={canManage ? (
+          <Button asChild>
+            <Link href="/backend/catalog/prices/create">
+              {t('catalog.prices.list.actions.create', 'Create')}
+            </Link>
+          </Button>
+        ) : undefined}
+        columns={columns}
+        data={rows}
+        emptyState={(
+          <ListEmptyState
+            entityName={t('catalog.prices.list.title', 'Price rules')}
+            description={t('catalog.prices.list.empty', 'No price rules yet — add one to price this product beyond its base price.')}
+            createHref={canManage ? '/backend/catalog/prices/create' : undefined}
+            createLabel={canManage ? t('catalog.prices.list.actions.create', 'Create') : undefined}
+          />
+        )}
+        searchValue={search}
+        searchPlaceholder={t('catalog.prices.list.searchPlaceholder', 'Search price rules')}
+        onSearchChange={(value) => { setSearch(value); setPage(1) }}
+        sortable={false}
+        perspective={{ tableId: extensionPoints.hosts.pricesTable.tableId }}
+        rowActions={(row) => (
+          canManage ? (
+            <RowActions
+              items={[
+                { id: 'edit', label: t('catalog.prices.list.actions.edit', 'Edit'), href: `/backend/catalog/prices/${row.id}/edit` },
+                { id: 'delete', label: t('catalog.prices.list.actions.delete', 'Delete'), destructive: true, onSelect: () => handleDelete(row) },
+              ]}
+            />
+          ) : null
+        )}
+        pagination={{
+          page,
+          pageSize: PAGE_SIZE,
+          total,
+          totalPages,
+          totalIsCapped,
+          onPageChange: setPage,
+        }}
+        isLoading={isLoading}
+      />
+      {ConfirmDialogElement}
+    </>
+  )
+}

package/src/modules/catalog/components/prices/normalizePriceRecord.ts

@@ -0,0 +1,71 @@
+// `/api/catalog/prices` list/detail responses serialize snake_case column
+// names (verified against the live route by
+// `__integration__/TC-CAT-CRUDFORM-002.spec.ts`: `variant_id`,
+// `unit_price_gross`, `min_quantity`, ...) — this normalizes either shape
+// into one camelCase record so UI code never has to guess which one it got.
+
+export type NormalizedPriceRecord = {
+  id: string
+  productId: string | null
+  variantId: string | null
+  priceKindId: string | null
+  currencyCode: string | null
+  kind: string
+  unitPriceNet: string | null
+  unitPriceGross: string | null
+  taxRate: string | null
+  minQuantity: number
+  maxQuantity: number | null
+  startsAt: string | null
+  endsAt: string | null
+  customerId: string | null
+  customerGroupId: string | null
+  channelId: string | null
+  offerId: string | null
+  userId: string | null
+  userGroupId: string | null
+  updatedAt: string | null
+}
+
+function str(record: Record<string, unknown>, camelKey: string, snakeKey: string): string | null {
+  const value = record[camelKey] ?? record[snakeKey]
+  return typeof value === 'string' && value.length ? value : null
+}
+
+function num(record: Record<string, unknown>, camelKey: string, snakeKey: string, fallback: number): number {
+  const value = record[camelKey] ?? record[snakeKey]
+  const parsed = typeof value === 'number' ? value : typeof value === 'string' ? Number(value) : NaN
+  return Number.isFinite(parsed) ? parsed : fallback
+}
+
+function numOrNull(record: Record<string, unknown>, camelKey: string, snakeKey: string): number | null {
+  const value = record[camelKey] ?? record[snakeKey]
+  if (value == null) return null
+  const parsed = typeof value === 'number' ? value : Number(value)
+  return Number.isFinite(parsed) ? parsed : null
+}
+
+export function normalizePriceRecord(record: Record<string, unknown>): NormalizedPriceRecord {
+  return {
+    id: str(record, 'id', 'id') ?? '',
+    productId: str(record, 'productId', 'product_id'),
+    variantId: str(record, 'variantId', 'variant_id'),
+    priceKindId: str(record, 'priceKindId', 'price_kind_id'),
+    currencyCode: str(record, 'currencyCode', 'currency_code'),
+    kind: str(record, 'kind', 'kind') ?? 'regular',
+    unitPriceNet: str(record, 'unitPriceNet', 'unit_price_net'),
+    unitPriceGross: str(record, 'unitPriceGross', 'unit_price_gross'),
+    taxRate: str(record, 'taxRate', 'tax_rate'),
+    minQuantity: num(record, 'minQuantity', 'min_quantity', 1),
+    maxQuantity: numOrNull(record, 'maxQuantity', 'max_quantity'),
+    startsAt: str(record, 'startsAt', 'starts_at'),
+    endsAt: str(record, 'endsAt', 'ends_at'),
+    customerId: str(record, 'customerId', 'customer_id'),
+    customerGroupId: str(record, 'customerGroupId', 'customer_group_id'),
+    channelId: str(record, 'channelId', 'channel_id'),
+    offerId: str(record, 'offerId', 'offer_id'),
+    userId: str(record, 'userId', 'user_id'),
+    userGroupId: str(record, 'userGroupId', 'user_group_id'),
+    updatedAt: str(record, 'updatedAt', 'updated_at'),
+  }
+}

package/src/modules/catalog/components/prices/priceFormFields.tsx

@@ -0,0 +1,228 @@
+"use client"
+
+import * as React from 'react'
+import type { CrudField, CrudFormGroup } from '@open-mercato/ui/backend/CrudForm'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import {
+  PriceChannelSelect,
+  PriceCurrencySelect,
+  PriceCustomerSelect,
+  PricePriceKindSelect,
+  PriceProductSelect,
+  PriceVariantSelect,
+} from './PriceScopeSelectors'
+
+export type PriceFormValues = {
+  id?: string
+  productId?: string
+  variantId?: string
+  priceKindId?: string
+  currencyCode?: string
+  unitPriceNet?: string
+  unitPriceGross?: string
+  taxRate?: string
+  minQuantity?: number
+  maxQuantity?: number
+  startsAt?: string
+  endsAt?: string
+  customerId?: string
+  customerGroupId?: string
+  channelId?: string
+  offerId?: string
+  userId?: string
+  userGroupId?: string
+  updatedAt?: string | null
+}
+
+export const PRICE_FORM_INITIAL_VALUES: PriceFormValues = {
+  productId: '',
+  variantId: '',
+  priceKindId: '',
+  currencyCode: '',
+  unitPriceNet: '',
+  unitPriceGross: '',
+  taxRate: '',
+  minQuantity: 1,
+  maxQuantity: undefined,
+  startsAt: '',
+  endsAt: '',
+  customerId: '',
+  customerGroupId: '',
+  channelId: '',
+  offerId: '',
+  userId: '',
+  userGroupId: '',
+}
+
+/** Shared field/group config for the price-rule create and edit CrudForms. */
+export function usePriceFormFields(): { fields: CrudField[]; groups: CrudFormGroup[] } {
+  const t = useT()
+
+  const fields = React.useMemo<CrudField[]>(() => [
+    {
+      id: 'productId',
+      label: t('catalog.prices.form.field.product', 'Product'),
+      type: 'custom',
+      component: ({ value, setValue }) => (
+        <PriceProductSelect value={typeof value === 'string' ? value : ''} onChange={setValue} />
+      ),
+    },
+    {
+      id: 'variantId',
+      label: t('catalog.prices.form.field.variant', 'Variant'),
+      type: 'custom',
+      component: ({ value, setValue, values }) => (
+        <PriceVariantSelect
+          productId={typeof values?.productId === 'string' ? values.productId : ''}
+          value={typeof value === 'string' ? value : ''}
+          onChange={setValue}
+        />
+      ),
+    },
+    {
+      id: 'priceKindId',
+      label: t('catalog.prices.form.field.priceKind', 'Price kind'),
+      type: 'custom',
+      required: true,
+      component: ({ value, setValue }) => (
+        <PricePriceKindSelect value={typeof value === 'string' ? value : ''} onChange={setValue} />
+      ),
+    },
+    {
+      id: 'currencyCode',
+      label: t('catalog.prices.form.field.currency', 'Currency'),
+      type: 'custom',
+      required: true,
+      component: ({ value, setValue }) => (
+        <PriceCurrencySelect value={typeof value === 'string' ? value : ''} onChange={setValue} />
+      ),
+    },
+    {
+      id: 'unitPriceNet',
+      label: t('catalog.prices.form.field.unitPriceNet', 'Unit price (net)'),
+      type: 'text',
+      layout: 'half',
+    },
+    {
+      id: 'unitPriceGross',
+      label: t('catalog.prices.form.field.unitPriceGross', 'Unit price (gross)'),
+      type: 'text',
+      layout: 'half',
+    },
+    {
+      id: 'taxRate',
+      label: t('catalog.prices.form.field.taxRate', 'Tax rate'),
+      type: 'text',
+      layout: 'half',
+    },
+    {
+      id: 'minQuantity',
+      label: t('catalog.prices.form.field.minQuantity', 'Minimum quantity'),
+      type: 'number',
+      layout: 'half',
+    },
+    {
+      id: 'maxQuantity',
+      label: t('catalog.prices.form.field.maxQuantity', 'Maximum quantity'),
+      type: 'number',
+      layout: 'half',
+      description: t('catalog.prices.form.field.maxQuantityHint', 'Leave empty for "and above"'),
+    },
+    {
+      id: 'startsAt',
+      label: t('catalog.prices.form.field.startsAt', 'Starts at'),
+      type: 'datepicker',
+      layout: 'half',
+    },
+    {
+      id: 'endsAt',
+      label: t('catalog.prices.form.field.endsAt', 'Ends at'),
+      type: 'datepicker',
+      layout: 'half',
+    },
+    {
+      id: 'customerId',
+      label: t('catalog.prices.form.field.customer', 'Customer'),
+      type: 'custom',
+      component: ({ value, setValue }) => (
+        <PriceCustomerSelect value={typeof value === 'string' ? value : ''} onChange={setValue} />
+      ),
+    },
+    {
+      id: 'customerGroupId',
+      label: t('catalog.prices.form.field.customerGroupId', 'Customer group ID'),
+      type: 'text',
+      description: t(
+        'catalog.prices.form.field.customerGroupIdHint',
+        'Raw customer-group identifier — no customer-group directory yet.',
+      ),
+    },
+    {
+      id: 'channelId',
+      label: t('catalog.prices.form.field.channel', 'Channel'),
+      type: 'custom',
+      component: ({ value, setValue }) => (
+        <PriceChannelSelect value={typeof value === 'string' ? value : ''} onChange={setValue} />
+      ),
+    },
+    {
+      id: 'offerId',
+      label: t('catalog.prices.form.field.offer', 'Offer'),
+      type: 'text',
+      layout: 'half',
+    },
+    {
+      id: 'userId',
+      label: t('catalog.prices.form.field.userId', 'User ID'),
+      type: 'text',
+      layout: 'half',
+    },
+    {
+      id: 'userGroupId',
+      label: t('catalog.prices.form.field.userGroupId', 'User group ID'),
+      type: 'text',
+      layout: 'half',
+    },
+  ], [t])
+
+  const groups = React.useMemo<CrudFormGroup[]>(() => [
+    {
+      id: 'product',
+      title: t('catalog.prices.form.group.product', 'Product'),
+      column: 1,
+      fields: ['productId', 'variantId'],
+    },
+    {
+      id: 'pricing',
+      title: t('catalog.prices.form.group.pricing', 'Pricing'),
+      column: 1,
+      fields: ['priceKindId', 'currencyCode', 'unitPriceNet', 'unitPriceGross', 'taxRate'],
+    },
+    {
+      id: 'quantity',
+      title: t('catalog.prices.form.group.quantity', 'Quantity tier'),
+      column: 1,
+      fields: ['minQuantity', 'maxQuantity'],
+    },
+    {
+      id: 'validity',
+      title: t('catalog.prices.form.group.validity', 'Validity window'),
+      column: 1,
+      fields: ['startsAt', 'endsAt'],
+    },
+    {
+      id: 'scope',
+      title: t('catalog.prices.form.group.scope', 'Scope'),
+      column: 2,
+      fields: ['customerId', 'customerGroupId', 'channelId'],
+    },
+    {
+      id: 'advanced',
+      title: t('catalog.prices.form.group.advanced', 'Advanced scope'),
+      column: 2,
+      fields: ['offerId', 'userId', 'userGroupId'],
+    },
+  ], [t])
+
+  return { fields, groups }
+}

package/src/modules/catalog/components/prices/useBatchLabels.ts

@@ -0,0 +1,57 @@
+"use client"
+
+import * as React from 'react'
+import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+
+type LabelMap = Record<string, string>
+
+/**
+ * Resolves display names for a page's worth of foreign ids in one batched
+ * request via the CRUD factory's generic `?ids=` narrowing (see
+ * `packages/core/AGENTS.md` § API Interceptors) instead of one lookup per row.
+ */
+export function useBatchLabels(
+  path: string,
+  ids: string[],
+  mapItem: (item: Record<string, unknown>) => { id: string; label: string } | null,
+): LabelMap {
+  const [labels, setLabels] = React.useState<LabelMap>({})
+  const key = React.useMemo(
+    () =>
+      Array.from(new Set(ids.filter((id): id is string => typeof id === 'string' && id.length > 0)))
+        .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+        .join(','),
+    [ids],
+  )
+
+  React.useEffect(() => {
+    if (!key) return
+    let cancelled = false
+    async function load() {
+      try {
+        const idCount = key.split(',').length
+        const payload = await readApiResultOrThrow<{ items?: Array<Record<string, unknown>> }>(
+          `${path}?ids=${encodeURIComponent(key)}&pageSize=${Math.min(100, idCount)}`,
+          undefined,
+          { fallback: { items: [] } },
+        )
+        if (cancelled) return
+        const items = Array.isArray(payload.items) ? payload.items : []
+        const next: LabelMap = {}
+        for (const item of items) {
+          const mapped = mapItem(item)
+          if (mapped) next[mapped.id] = mapped.label
+        }
+        setLabels((prev) => ({ ...prev, ...next }))
+      } catch {
+        // Best-effort: callers fall back to the raw id when a label is missing.
+      }
+    }
+    void load()
+    return () => {
+      cancelled = true
+    }
+  }, [key, path, mapItem])
+
+  return labels
+}