@open-mercato/core 0.8.1-develop.7297.1.67605e74f9 → 0.9.0

package/src/modules/customer_groups/components/CustomerGroupTermsSection.tsx

@@ -0,0 +1,277 @@
+"use client"
+
+import * as React from 'react'
+import { z } from 'zod'
+import { FileText } from 'lucide-react'
+import { CrudForm, type CrudField } from '@open-mercato/ui/backend/CrudForm'
+import { updateCrud } from '@open-mercato/ui/backend/utils/crud'
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { ErrorMessage, LoadingMessage } from '@open-mercato/ui/backend/detail'
+import { SectionHeader } from '@open-mercato/ui/backend/SectionHeader'
+import { EmptyState } from '@open-mercato/ui/primitives/empty-state'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { CustomerGroupTermsPriceKindField } from './CustomerGroupTermsPriceKindField'
+
+export type CustomerGroupTermsDTO = {
+  id: string
+  groupId: string
+  organizationId: string | null
+  tenantId: string
+  priceKindId: string | null
+  paymentTermsDays: number | null
+  allowPurchaseOnAccount: boolean | null
+  defaultCreditLimit: number | null
+  creditCurrencyCode: string | null
+  approvalRequiredAbove: number | null
+  minOrderValue: number | null
+  metadata: Record<string, unknown> | null
+  createdAt: string
+  updatedAt: string
+}
+
+// Lock token sent with the first save of a group that has no terms row yet. No real
+// row can carry this `updated_at`, so if another editor created the row meanwhile the
+// route's lock check against that row answers 409 instead of silently overwriting it.
+export const TERMS_NOT_YET_CREATED_LOCK_TOKEN = new Date(0).toISOString()
+
+// `inherit` maps to `null` on the wire: the field is left unset on this group and
+// resolves from the parent chain / tenant default, like the other terms fields.
+const PURCHASE_ON_ACCOUNT_VALUES = ['inherit', 'allow', 'deny'] as const
+type PurchaseOnAccountValue = (typeof PURCHASE_ON_ACCOUNT_VALUES)[number]
+
+function toPurchaseOnAccountValue(value: boolean | null | undefined): PurchaseOnAccountValue {
+  if (value === true) return 'allow'
+  if (value === false) return 'deny'
+  return 'inherit'
+}
+
+function fromPurchaseOnAccountValue(value: string | undefined): boolean | null {
+  if (value === 'allow') return true
+  if (value === 'deny') return false
+  return null
+}
+
+type CustomerGroupTermsFormValues = {
+  priceKindId: string
+  paymentTermsDays?: number
+  allowPurchaseOnAccount: PurchaseOnAccountValue
+  defaultCreditLimit?: number
+  creditCurrencyCode: string
+  approvalRequiredAbove?: number
+  minOrderValue?: number
+}
+
+function mapTermsToFormValues(terms: CustomerGroupTermsDTO | null): CustomerGroupTermsFormValues {
+  return {
+    priceKindId: terms?.priceKindId ?? '',
+    paymentTermsDays: terms?.paymentTermsDays ?? undefined,
+    allowPurchaseOnAccount: toPurchaseOnAccountValue(terms?.allowPurchaseOnAccount),
+    defaultCreditLimit: terms?.defaultCreditLimit ?? undefined,
+    creditCurrencyCode: terms?.creditCurrencyCode ?? '',
+    approvalRequiredAbove: terms?.approvalRequiredAbove ?? undefined,
+    minOrderValue: terms?.minOrderValue ?? undefined,
+  }
+}
+
+export function CustomerGroupTermsSection({
+  groupId,
+  terms,
+  loading,
+  loadError,
+  canManage,
+  onSaved,
+}: {
+  groupId: string
+  // `undefined` = still loading, `null` = confirmed no terms row for this group
+  // (spec: "No terms set — inheriting from parent / tenant defaults"), object = loaded row.
+  terms: CustomerGroupTermsDTO | null | undefined
+  loading: boolean
+  // Set when the terms GET failed for a reason other than "no row" — the form is
+  // then withheld so a save can never overwrite terms it could not read.
+  loadError?: string | null
+  // Without `customer_groups.terms.manage` the terms stay viewable but the form is
+  // read-only and the empty state offers no "set terms" action — a save would 403.
+  canManage: boolean
+  onSaved: (next: CustomerGroupTermsDTO) => void
+}) {
+  const t = useT()
+  // Once the user starts filling out terms for a group that has none yet, keep the
+  // form mounted even while the in-flight save briefly leaves `terms` as `null` —
+  // otherwise the empty state would flash back before `onSaved` lands.
+  const [editing, setEditing] = React.useState(false)
+  const hasTerms = terms != null
+  const showForm = hasTerms || editing
+
+  const negativeMessage = t('customer_groups.groups.form.terms.errors.negative', 'Must be zero or greater.')
+
+  const schema = React.useMemo(
+    () =>
+      z.object({
+        priceKindId: z.string().trim(),
+        paymentTermsDays: z.coerce.number().int().min(0, negativeMessage).optional(),
+        allowPurchaseOnAccount: z.enum(PURCHASE_ON_ACCOUNT_VALUES),
+        defaultCreditLimit: z.coerce.number().min(0, negativeMessage).optional(),
+        creditCurrencyCode: z
+          .string()
+          .trim()
+          .max(4, t('customer_groups.groups.form.terms.errors.currencyLength', 'Use up to 4 characters.')),
+        approvalRequiredAbove: z.coerce.number().min(0, negativeMessage).optional(),
+        minOrderValue: z.coerce.number().min(0, negativeMessage).optional(),
+      }),
+    [negativeMessage, t],
+  )
+
+  const fields = React.useMemo<CrudField[]>(
+    () => [
+      {
+        id: 'priceKindId',
+        label: t('customer_groups.groups.form.terms.field.priceKind', 'Price kind'),
+        type: 'custom',
+        component: ({ value, setValue, disabled }) => (
+          <CustomerGroupTermsPriceKindField
+            value={typeof value === 'string' ? value : ''}
+            onChange={setValue}
+            disabled={disabled}
+          />
+        ),
+      },
+      {
+        id: 'paymentTermsDays',
+        label: t('customer_groups.groups.form.terms.field.paymentTermsDays', 'Payment terms (days)'),
+        type: 'number',
+        layout: 'half',
+      },
+      {
+        id: 'allowPurchaseOnAccount',
+        label: t('customer_groups.groups.form.terms.field.allowPurchaseOnAccount', 'Allow purchase on account'),
+        type: 'select',
+        layout: 'half',
+        required: true,
+        options: [
+          {
+            value: 'inherit',
+            label: t('customer_groups.groups.form.terms.field.allowPurchaseOnAccountOptions.inherit', 'Inherit'),
+          },
+          {
+            value: 'allow',
+            label: t('customer_groups.groups.form.terms.field.allowPurchaseOnAccountOptions.allow', 'Allow'),
+          },
+          {
+            value: 'deny',
+            label: t('customer_groups.groups.form.terms.field.allowPurchaseOnAccountOptions.deny', 'Do not allow'),
+          },
+        ],
+      },
+      {
+        id: 'defaultCreditLimit',
+        label: t('customer_groups.groups.form.terms.field.defaultCreditLimit', 'Default credit limit'),
+        type: 'number',
+        layout: 'half',
+      },
+      {
+        id: 'creditCurrencyCode',
+        label: t('customer_groups.groups.form.terms.field.creditCurrencyCode', 'Credit currency'),
+        type: 'text',
+        layout: 'half',
+        placeholder: t('customer_groups.groups.form.terms.field.creditCurrencyCodePlaceholder', 'e.g., USD'),
+        maxLength: 4,
+      },
+      {
+        id: 'approvalRequiredAbove',
+        label: t('customer_groups.groups.form.terms.field.approvalRequiredAbove', 'Approval required above'),
+        type: 'number',
+        layout: 'half',
+      },
+      {
+        id: 'minOrderValue',
+        label: t('customer_groups.groups.form.terms.field.minOrderValue', 'Minimum order value'),
+        type: 'number',
+        layout: 'half',
+      },
+    ],
+    [t],
+  )
+
+  const initialValues = React.useMemo(() => mapTermsToFormValues(terms ?? null), [terms])
+
+  const handleSubmit = React.useCallback(
+    async (values: CustomerGroupTermsFormValues) => {
+      const payload: Record<string, unknown> = {
+        priceKindId: values.priceKindId && values.priceKindId.trim().length ? values.priceKindId : null,
+        paymentTermsDays: typeof values.paymentTermsDays === 'number' ? values.paymentTermsDays : null,
+        allowPurchaseOnAccount: fromPurchaseOnAccountValue(values.allowPurchaseOnAccount),
+        defaultCreditLimit: typeof values.defaultCreditLimit === 'number' ? values.defaultCreditLimit : null,
+        creditCurrencyCode:
+          values.creditCurrencyCode && values.creditCurrencyCode.trim().length
+            ? values.creditCurrencyCode.trim().toUpperCase()
+            : null,
+        approvalRequiredAbove:
+          typeof values.approvalRequiredAbove === 'number' ? values.approvalRequiredAbove : null,
+        minOrderValue: typeof values.minOrderValue === 'number' ? values.minOrderValue : null,
+      }
+      // `updateCrud` PUTs to `/api/customer_groups/customer-groups/{groupId}/terms`, matching the
+      // upsert route (Step 2.4). `optimisticLockUpdatedAt` below is
+      // `TERMS_NOT_YET_CREATED_LOCK_TOKEN` on the first save (no `terms` row yet).
+      const call = await updateCrud<{ terms: CustomerGroupTermsDTO }>(`customer_groups/customer-groups/${groupId}/terms`, payload, {
+        errorMessage: t('customer_groups.groups.form.terms.errors.save', 'Failed to save commercial terms.'),
+      })
+      if (call.result?.terms) onSaved(call.result.terms)
+      flash(t('customer_groups.groups.form.terms.flash.saved', 'Commercial terms saved.'), 'success')
+    },
+    [groupId, onSaved, t],
+  )
+
+  return (
+    <div className="rounded-md border border-border bg-card p-4 space-y-4">
+      <SectionHeader title={t('customer_groups.groups.form.terms.title', 'Commercial terms')} />
+      {loading ? (
+        <LoadingMessage label={t('customer_groups.groups.form.terms.loading', 'Loading commercial terms…')} />
+      ) : loadError ? (
+        <ErrorMessage label={loadError} />
+      ) : !showForm ? (
+        <EmptyState
+          size="sm"
+          variant="subtle"
+          icon={<FileText className="h-5 w-5" aria-hidden />}
+          title={t(
+            'customer_groups.groups.form.terms.empty.title',
+            'No terms set — inheriting from parent / tenant defaults',
+          )}
+          description={t(
+            'customer_groups.groups.form.terms.empty.description',
+            'This group currently uses commercial terms inherited from its parent group or the tenant defaults. Set explicit terms to override them for this group.',
+          )}
+          actions={canManage ? (
+            <Button type="button" size="sm" variant="outline" onClick={() => setEditing(true)}>
+              {t('customer_groups.groups.form.terms.empty.action', 'Set terms for this group')}
+            </Button>
+          ) : undefined}
+          className="border border-dashed border-border"
+        />
+      ) : (
+        <CrudForm<CustomerGroupTermsFormValues>
+          key={terms?.updatedAt ?? 'new'}
+          embedded
+          schema={schema}
+          fields={fields}
+          initialValues={initialValues}
+          optimisticLockUpdatedAt={terms?.updatedAt ?? TERMS_NOT_YET_CREATED_LOCK_TOKEN}
+          readOnly={!canManage}
+          readOnlyOverlay={(
+            <div className="rounded-xl border border-border/70 bg-background/95 px-4 py-3 text-sm text-muted-foreground shadow-sm">
+              {t(
+                'customer_groups.groups.form.terms.readOnly',
+                'You do not have permission to change commercial terms.',
+              )}
+            </div>
+          )}
+          submitLabel={t('customer_groups.groups.form.terms.action.save', 'Save terms')}
+          onSubmit={handleSubmit}
+        />
+      )}
+    </div>
+  )
+}
+
+export default CustomerGroupTermsSection

package/src/modules/customer_groups/components/GroupPickerField.tsx

@@ -0,0 +1,142 @@
+"use client"
+
+import * as React from 'react'
+import { ComboboxInput, type ComboboxOption } from '@open-mercato/ui/backend/inputs/ComboboxInput'
+import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { Tag } from '@open-mercato/ui/primitives/tag'
+import { Label } from '@open-mercato/ui/primitives/label'
+import { useT, type TranslateFn } from '@open-mercato/shared/lib/i18n/context'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import type { CustomFieldProps } from '@open-mercato/shared/modules/widgets/injection'
+
+const logger = createLogger('customer_groups').child({ component: 'GroupPickerField' })
+
+type RemoteGroup = Record<string, unknown>
+
+function pickString(item: RemoteGroup, ...keys: string[]): string {
+  for (const key of keys) {
+    const value = item[key]
+    if (typeof value === 'string' && value.length) return value
+  }
+  return ''
+}
+
+function pickNumber(item: RemoteGroup, ...keys: string[]): number | null {
+  for (const key of keys) {
+    const value = item[key]
+    if (typeof value === 'number' && Number.isFinite(value)) return value
+  }
+  return null
+}
+
+function mapGroup(item: RemoteGroup, t: TranslateFn): ComboboxOption | null {
+  const id = pickString(item, 'id')
+  if (!id) return null
+  const code = pickString(item, 'code')
+  const name = pickString(item, 'name') || id
+  const priority = pickNumber(item, 'priority')
+  return {
+    value: id,
+    label: code ? `${name} (${code})` : name,
+    description: priority !== null
+      ? t('customer_groups.widgets.groupPicker.priority', 'Priority {priority}', { priority })
+      : null,
+  }
+}
+
+async function loadGroups(query: string | undefined, pageSize: string, t: TranslateFn): Promise<ComboboxOption[]> {
+  try {
+    const params = new URLSearchParams({ pageSize, sortField: 'priority', sortDir: 'asc' })
+    const trimmed = (query ?? '').trim()
+    if (trimmed) params.set('search', trimmed)
+    const payload = await readApiResultOrThrow<{ items?: RemoteGroup[] }>(
+      `/api/customer_groups/customer-groups?${params.toString()}`,
+      undefined,
+      { fallback: { items: [] } },
+    )
+    const items = Array.isArray(payload.items) ? payload.items : []
+    return items
+      .map((item) => mapGroup(item, t))
+      .filter((option): option is ComboboxOption => option !== null)
+  } catch (err) {
+    logger.error('customer_groups.groupPicker.load failed', { err })
+    return []
+  }
+}
+
+async function lookupGroup(id: string): Promise<RemoteGroup | null> {
+  try {
+    const payload = await readApiResultOrThrow<{ items?: RemoteGroup[] }>(
+      `/api/customer_groups/customer-groups?ids=${encodeURIComponent(id)}&pageSize=1`,
+      undefined,
+      { fallback: { items: [] } },
+    )
+    const items = Array.isArray(payload.items) ? payload.items : []
+    return items[0] ?? null
+  } catch (err) {
+    logger.error('customer_groups.groupPicker.lookup failed', { err, id })
+    return null
+  }
+}
+
+/**
+ * Injected `crud-form:<entityId>:fields` custom field — replaces the free-text
+ * `customerGroupId` UUID input on the catalog price editor with a searchable
+ * picker sourced from `/api/customer_groups/customer-groups`.
+ *
+ * A stored value that does not resolve to any group is never silently hidden —
+ * it renders an explicit "Unknown group (<uuid>)" chip alongside the picker so
+ * the gap stays visible (spec §7.3: "it is not hidden").
+ */
+export function GroupPickerField({ value, onChange, disabled }: CustomFieldProps) {
+  const t = useT()
+  const labelId = React.useId()
+  const currentId = typeof value === 'string' ? value.trim() : ''
+  const [unknownId, setUnknownId] = React.useState<string | null>(null)
+  const [isLoading, setIsLoading] = React.useState(false)
+
+  React.useEffect(() => {
+    let cancelled = false
+    if (!currentId) {
+      setUnknownId(null)
+      setIsLoading(false)
+      return
+    }
+    setIsLoading(true)
+    lookupGroup(currentId).then((group) => {
+      if (cancelled) return
+      setUnknownId(group ? null : currentId)
+      setIsLoading(false)
+    })
+    return () => {
+      cancelled = true
+    }
+  }, [currentId])
+
+  return (
+    <div className="space-y-2" data-crud-field-id="customerGroupId" role="group" aria-labelledby={labelId}>
+      <Label id={labelId}>
+        {t('customer_groups.widgets.groupPicker.label', 'Customer group')}
+      </Label>
+      <ComboboxInput
+        value={currentId}
+        onChange={(next) => onChange(next || null)}
+        disabled={disabled || isLoading}
+        allowCustomValues={false}
+        placeholder={t('customer_groups.widgets.groupPicker.placeholder', 'Search customer groups…')}
+        loadSuggestions={(query) => loadGroups(query, '20', t)}
+        resolveLabel={async (id) => {
+          const group = await lookupGroup(id)
+          return group ? mapGroup(group, t)?.label ?? id : id
+        }}
+      />
+      {unknownId ? (
+        <Tag variant="error" dot>
+          {t('customer_groups.widgets.groupPicker.unknownGroup', 'Unknown group ({id})', { id: unknownId })}
+        </Tag>
+      ) : null}
+    </div>
+  )
+}
+
+export default GroupPickerField

package/src/modules/customer_groups/components/OrphanBanner.tsx

@@ -0,0 +1,92 @@
+"use client"
+
+import * as React from 'react'
+import Link from 'next/link'
+import { AlertTriangle } from 'lucide-react'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+
+const logger = createLogger('customer_groups').child({ component: 'OrphanBanner' })
+
+type ReconcileResponse = {
+  orphans?: Array<{ groupId: string }>
+}
+
+// Mirrors `packages/ui/src/backend/indexes/PartialIndexBanner.tsx`'s shape
+// (status-warning tokens, AlertTriangle icon, no hardcoded colors). Renders
+// nothing while loading and nothing once loaded with zero orphans — the empty
+// state lives on the report page (`backend/customer-groups/orphans/page.tsx`),
+// not here.
+export function OrphanBanner() {
+  const t = useT()
+  const [orphanCount, setOrphanCount] = React.useState<number | null>(null)
+  const [isLoading, setIsLoading] = React.useState(true)
+
+  React.useEffect(() => {
+    let cancelled = false
+    async function load() {
+      setIsLoading(true)
+      try {
+        const fallback: ReconcileResponse = { orphans: [] }
+        const call = await apiCall<ReconcileResponse>('/api/customer_groups/customer-groups/reconcile', undefined, { fallback })
+        if (cancelled) return
+        if (!call.ok) {
+          setOrphanCount(null)
+          return
+        }
+        const orphans = Array.isArray(call.result?.orphans) ? call.result.orphans : []
+        setOrphanCount(orphans.length)
+      } catch (err) {
+        if (!cancelled) {
+          logger.error('customer_groups.orphanBanner.load failed', { err })
+          getTelemetryRuntime()?.reportError(err, {
+            module: 'customer_groups',
+            code: 'customer_groups.orphan_banner_load_failed',
+          })
+          setOrphanCount(null)
+        }
+      } finally {
+        if (!cancelled) setIsLoading(false)
+      }
+    }
+    void load()
+    return () => {
+      cancelled = true
+    }
+  }, [])
+
+  // Intentionally silent while loading and once resolved with zero orphans —
+  // a warning banner that flashes in then disappears reads as a bug, so this
+  // banner only ever renders in the "found N orphans" state.
+  if (isLoading || !orphanCount) return null
+
+  return (
+    <div className="mb-4 flex flex-col gap-3 rounded-md border border-status-warning-border bg-status-warning-bg px-3 py-3 text-sm text-status-warning-text md:flex-row md:items-center md:justify-between">
+      <div className="flex items-center gap-2 font-medium text-status-warning-text">
+        <AlertTriangle className="size-4" aria-hidden="true" />
+        <span>
+          {t(
+            'customer_groups.groups.orphanBanner.title',
+            '{count} orphaned customer-group reference(s) found',
+            { count: orphanCount },
+          )}
+        </span>
+      </div>
+      <Button
+        asChild
+        variant="outline"
+        size="sm"
+        className="border-status-warning-border text-status-warning-text hover:bg-status-warning-bg"
+      >
+        <Link href="/backend/customer-groups/orphans">
+          {t('customer_groups.groups.orphanBanner.viewReport', 'View report')}
+        </Link>
+      </Button>
+    </div>
+  )
+}
+
+export default OrphanBanner

package/src/modules/customer_groups/components/customerGroupTree.ts

@@ -0,0 +1,84 @@
+// Pure helpers shared by the create/edit `CustomerGroup` admin pages and widgets: list
+// item → summary mapping, the depth-warning threshold (spec §5.1 caps nesting at depth
+// 5), and the "another group is already default" lookup used by the isDefault conflict
+// notice. No React here so any consumer can reuse it without a component import.
+
+export type CustomerGroupSummary = {
+  id: string
+  code: string
+  name: string
+  parentId: string | null
+  isDefault: boolean
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value : ''
+}
+
+// The `/api/customer_groups/customer-groups` list route returns the query-index column projection
+// (snake_case keys, e.g. `parent_id`, `is_default`) rather than the camelCase shape
+// other CRUD routes normalize to — see `api/customer-groups/crud.ts` `customerGroupListFields`.
+// Accept both spellings so this helper keeps working if that ever changes.
+function readNullableId(record: Record<string, unknown>, camelKey: string, snakeKey: string): string | null {
+  const camel = record[camelKey]
+  if (typeof camel === 'string' && camel.length) return camel
+  const snake = record[snakeKey]
+  if (typeof snake === 'string' && snake.length) return snake
+  return null
+}
+
+function readBoolean(record: Record<string, unknown>, camelKey: string, snakeKey: string): boolean {
+  return record[camelKey] === true || record[snakeKey] === true
+}
+
+export function mapListItemToSummary(item: unknown): CustomerGroupSummary | null {
+  if (!item || typeof item !== 'object') return null
+  const record = item as Record<string, unknown>
+  const id = readString(record.id)
+  if (!id) return null
+  return {
+    id,
+    code: readString(record.code),
+    name: readString(record.name),
+    parentId: readNullableId(record, 'parentId', 'parent_id'),
+    isDefault: readBoolean(record, 'isDefault', 'is_default'),
+  }
+}
+
+export function mapListItemsToSummaries(items: unknown): CustomerGroupSummary[] {
+  if (!Array.isArray(items)) return []
+  return items.reduce<CustomerGroupSummary[]>((acc, item) => {
+    const summary = mapListItemToSummary(item)
+    if (summary) acc.push(summary)
+    return acc
+  }, [])
+}
+
+// Spec §5.1: hierarchy depth is capped at 5. A candidate parent whose own ancestor
+// chain is already 4+ levels deep would put the group being created/edited at depth 5
+// or deeper — surfaced as a non-blocking warning (the spec says "warns", not "prevents").
+export const CUSTOMER_GROUP_DEPTH_WARNING_THRESHOLD = 4
+
+// The tenant's current default group, if any, excluding the group being edited.
+export function findDefaultConflict(
+  groups: CustomerGroupSummary[],
+  excludeId?: string | null,
+): CustomerGroupSummary | null {
+  return groups.find((group) => group.isDefault && group.id !== excludeId) ?? null
+}
+
+// The priority a new group is pre-filled with: one reorder step (the drag-reorder
+// command renumbers in gaps of 10) above the highest live priority, since `priority`
+// is unique per tenant and a fixed default would collide on every create but the first.
+const PRIORITY_STEP = 10
+
+export function nextFreePriority(items: unknown[] | undefined | null): number {
+  if (!Array.isArray(items)) return 0
+  let highest: number | null = null
+  for (const item of items) {
+    const priority = item && typeof item === 'object' ? (item as { priority?: unknown }).priority : null
+    if (typeof priority !== 'number' || !Number.isFinite(priority)) continue
+    if (highest === null || priority > highest) highest = priority
+  }
+  return highest === null ? 0 : highest + PRIORITY_STEP
+}