@dainamite/cpq 0.4.0 → 0.6.0

package/src/modules/cpq/backend/cpq/quotes/[id]/_components/PriceAdjustmentDialog.tsx

@@ -0,0 +1,260 @@
+'use client'
+
+import * as React from 'react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { Input } from '@open-mercato/ui/primitives/input'
+import { Textarea } from '@open-mercato/ui/primitives/textarea'
+import { Alert, AlertDescription } from '@open-mercato/ui/primitives/alert'
+import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle } from '@open-mercato/ui/primitives/dialog'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@open-mercato/ui/primitives/select'
+import {
+  ADJUSTMENT_ERROR_FALLBACKS,
+  adjustmentErrorCode,
+  allowedAdjustmentTypes,
+  buildAdjustmentDraft,
+  formatDepth,
+  discountDepth,
+  toAdjustmentPatch,
+  type AdjustmentForm,
+  type AdjustmentTarget,
+  type AdjustmentType,
+  type WaterfallChargeInput,
+} from '../../../../../lib/priceAdjustmentView'
+
+export type AdjustmentReason = { value: string; label: string }
+
+/** Minimal view of the quote the dialog needs, kept local so the page owns the full type. */
+type PreviewQuote = {
+  pricingRevision?: number
+  lines: Array<{ lineId: string; mrcTotal: number; nrcTotal: number; charges: Array<WaterfallChargeInput & { chargeCode: string; adjustmentErrors?: Array<{ adjustmentId: string; code: string }> }> }>
+}
+
+export type ExistingAdjustment = {
+  id: string
+  adjustmentType: AdjustmentType
+  value: number
+  reasonCode: string
+  reasonNote?: string | null
+  chargeTypeFilter?: 'nrc' | 'mrc' | null
+}
+
+export type PriceAdjustmentDialogProps<Q extends PreviewQuote> = {
+  open: boolean
+  quoteId: string
+  currency: string
+  pricingRevision: number
+  target: AdjustmentTarget
+  /** Display name of the line / charge being adjusted. */
+  targetLabel: string
+  /** The charge for charge-level targets (drives type options and the current price). */
+  charge?: WaterfallChargeInput & { chargeCode: string; chargeName: string }
+  existing?: ExistingAdjustment | null
+  /** Ids of adjustments already stored on the quote; their errors don't block this draft. */
+  storedAdjustmentIds: string[]
+  reasons: AdjustmentReason[]
+  onClose: () => void
+  onSaved: (quote: Q) => void
+  /** Called when the server reports a stale revision; the page reloads the quote. */
+  onStale: () => void
+}
+
+const TYPE_FALLBACKS: Record<AdjustmentType, string> = {
+  price_override: 'Set a new unit price',
+  discount_percent: 'Percentage discount',
+  discount_absolute: 'Amount off the charge total',
+}
+
+function money(amount: number, currency: string) {
+  return new Intl.NumberFormat('en-US', { style: 'currency', currency }).format(amount)
+}
+
+export function PriceAdjustmentDialog<Q extends PreviewQuote>(props: PriceAdjustmentDialogProps<Q>) {
+  const { open, quoteId, currency, pricingRevision, target, targetLabel, charge, existing, storedAdjustmentIds, reasons, onClose, onSaved, onStale } = props
+  const t = useT()
+  const types = allowedAdjustmentTypes(target.level, charge)
+  const initialForm = React.useCallback((): AdjustmentForm => ({
+    adjustmentType: existing?.adjustmentType ?? types[0] ?? 'discount_percent',
+    value: existing ? String(existing.value) : '',
+    reasonCode: existing?.reasonCode ?? '',
+    reasonNote: existing?.reasonNote ?? '',
+    chargeTypeFilter: existing?.chargeTypeFilter ?? '',
+  }), [existing, types])
+  const [form, setForm] = React.useState<AdjustmentForm>(initialForm)
+  const [preview, setPreview] = React.useState<{ quote: Q; errors: Array<{ adjustmentId: string; code: string }> } | null>(null)
+  const [previewing, setPreviewing] = React.useState(false)
+  const [errorCode, setErrorCode] = React.useState<string | null>(null)
+  const [saving, setSaving] = React.useState(false)
+
+  React.useEffect(() => {
+    if (open) { setForm(initialForm()); setPreview(null); setErrorCode(null) }
+    // Reset only when the dialog (re)opens.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [open])
+
+  const draft = buildAdjustmentDraft(form, target, currency, pricingRevision)
+  const draftKey = draft && form.reasonCode ? JSON.stringify(draft) : null
+  const message = (code: string) => t(`cpq.priceAdjustments.errors.${code}`, ADJUSTMENT_ERROR_FALLBACKS[code] ?? code)
+
+  // Debounced, side-effect-free preview of the draft.
+  React.useEffect(() => {
+    if (!open || !draftKey) { setPreview(null); return }
+    let cancelled = false
+    const timer = window.setTimeout(async () => {
+      setPreviewing(true)
+      const call = await apiCall<{ quote: Q; errors: Array<{ adjustmentId: string; code: string }> }>(
+        `/api/cpq/quotes/${quoteId}/price-adjustments/preview`,
+        { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ draft: JSON.parse(draftKey), ...(existing ? { replaceAdjustmentId: existing.id } : {}) }) },
+      )
+      if (cancelled) return
+      setPreviewing(false)
+      if (call.ok && call.result) { setPreview(call.result); setErrorCode(null) }
+      else { setPreview(null); setErrorCode(adjustmentErrorCode(call.status, call.result)) }
+    }, 400)
+    return () => { cancelled = true; window.clearTimeout(timer) }
+  }, [open, draftKey, quoteId, existing])
+
+  const previewLine = preview?.quote.lines.find((line) => line.lineId === target.quoteLineId)
+  const previewCharge = target.level === 'charge' ? previewLine?.charges.find((entry) => entry.chargeCode === target.chargeCode) : undefined
+  // The draft's id is server-generated on create, so "not stored" identifies it; on edit it keeps its id.
+  const previewErrors = preview?.errors.filter((error) => existing ? error.adjustmentId === existing.id : !storedAdjustmentIds.includes(error.adjustmentId)) ?? []
+  const noteRequired = form.reasonCode === 'other' && !form.reasonNote.trim()
+  const canSave = !!draft && !!form.reasonCode && !noteRequired && !saving && previewErrors.length === 0
+
+  const save = async () => {
+    if (!draft || !canSave) return
+    setSaving(true); setErrorCode(null)
+    const call = existing
+      ? await apiCall<{ quote: Q }>(`/api/cpq/quotes/${quoteId}/price-adjustments/${existing.id}`, {
+        method: 'PATCH', headers: { 'content-type': 'application/json' }, body: JSON.stringify(toAdjustmentPatch(draft)),
+      })
+      : await apiCall<{ quote: Q }>(`/api/cpq/quotes/${quoteId}/price-adjustments`, {
+        method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(draft),
+      })
+    setSaving(false)
+    if (call.ok && call.result?.quote) { onSaved(call.result.quote); onClose(); return }
+    setErrorCode(adjustmentErrorCode(call.status, call.result))
+  }
+
+  const onKeyDown = (event: React.KeyboardEvent) => {
+    if ((event.metaKey || event.ctrlKey) && event.key === 'Enter') { event.preventDefault(); void save() }
+  }
+
+  const standardUnit = charge?.standardUnitPrice ?? charge?.unitPrice
+  const valueHint = form.adjustmentType === 'discount_percent'
+    ? t('cpq.priceAdjustments.dialog.percentHint', 'Percent off the standard price (0–100)')
+    : form.adjustmentType === 'price_override'
+      ? t('cpq.priceAdjustments.dialog.overrideHint', 'New unit price, at most the standard price')
+      : t('cpq.priceAdjustments.dialog.absoluteHint', 'Amount taken off this charge’s total')
+
+  return (
+    <Dialog open={open} onOpenChange={(next) => { if (!next) onClose() }}>
+      <DialogContent onKeyDown={onKeyDown} data-testid="cpq-price-adjustment-dialog">
+        <DialogHeader>
+          <DialogTitle>
+            {existing
+              ? t('cpq.priceAdjustments.dialog.editTitle', 'Edit price adjustment')
+              : target.level === 'line'
+                ? t('cpq.priceAdjustments.dialog.lineTitle', 'Discount line')
+                : t('cpq.priceAdjustments.dialog.chargeTitle', 'Adjust price')}
+          </DialogTitle>
+          <DialogDescription>
+            {targetLabel}
+            {charge && standardUnit !== undefined && (
+              <> · {t('cpq.priceAdjustments.dialog.standard', 'Standard')} {money(standardUnit, currency)}</>
+            )}
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="space-y-3 text-sm">
+          <label className="block space-y-1">
+            <span className="text-xs font-medium">{t('cpq.priceAdjustments.dialog.type', 'Adjustment')}</span>
+            <Select value={form.adjustmentType} onValueChange={(value) => setForm({ ...form, adjustmentType: value as AdjustmentType })}>
+              <SelectTrigger><SelectValue /></SelectTrigger>
+              <SelectContent>
+                {types.map((type) => (
+                  <SelectItem key={type} value={type}>{t(`cpq.priceAdjustments.dialog.types.${type}`, TYPE_FALLBACKS[type])}</SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          </label>
+
+          {target.level === 'line' && (
+            <label className="block space-y-1">
+              <span className="text-xs font-medium">{t('cpq.priceAdjustments.dialog.appliesTo', 'Applies to')}</span>
+              <Select value={form.chargeTypeFilter || 'all'} onValueChange={(value) => setForm({ ...form, chargeTypeFilter: value === 'all' ? '' : value as 'nrc' | 'mrc' })}>
+                <SelectTrigger><SelectValue /></SelectTrigger>
+                <SelectContent>
+                  <SelectItem value="all">{t('cpq.priceAdjustments.dialog.allCharges', 'All one-time and recurring charges')}</SelectItem>
+                  <SelectItem value="mrc">{t('cpq.priceAdjustments.dialog.mrcOnly', 'Recurring charges only')}</SelectItem>
+                  <SelectItem value="nrc">{t('cpq.priceAdjustments.dialog.nrcOnly', 'One-time charges only')}</SelectItem>
+                </SelectContent>
+              </Select>
+            </label>
+          )}
+
+          <label className="block space-y-1">
+            <span className="text-xs font-medium">{t('cpq.priceAdjustments.dialog.value', 'Value')}</span>
+            <Input inputMode="decimal" autoFocus value={form.value} onChange={(event) => setForm({ ...form, value: event.target.value })} aria-describedby="cpq-adjustment-value-hint" />
+            <span id="cpq-adjustment-value-hint" className="block text-xs text-muted-foreground">{valueHint}</span>
+          </label>
+
+          <label className="block space-y-1">
+            <span className="text-xs font-medium">{t('cpq.priceAdjustments.dialog.reason', 'Reason')}</span>
+            <Select value={form.reasonCode} onValueChange={(value) => setForm({ ...form, reasonCode: value })}>
+              <SelectTrigger><SelectValue placeholder={t('cpq.priceAdjustments.dialog.reasonPlaceholder', 'Pick a reason')} /></SelectTrigger>
+              <SelectContent>
+                {reasons.map((reason) => <SelectItem key={reason.value} value={reason.value}>{reason.label}</SelectItem>)}
+              </SelectContent>
+            </Select>
+          </label>
+
+          <label className="block space-y-1">
+            <span className="text-xs font-medium">
+              {t('cpq.priceAdjustments.dialog.note', 'Note')}{form.reasonCode === 'other' ? ' *' : ''}
+            </span>
+            <Textarea rows={2} maxLength={500} value={form.reasonNote} onChange={(event) => setForm({ ...form, reasonNote: event.target.value })} />
+          </label>
+
+          <div className="rounded border bg-muted/20 p-2 text-xs" aria-live="polite" data-testid="cpq-adjustment-preview">
+            {!draftKey && <span className="text-muted-foreground">{t('cpq.priceAdjustments.dialog.previewEmpty', 'Enter a value and reason to preview the new price.')}</span>}
+            {draftKey && previewing && <span className="text-muted-foreground">{t('cpq.priceAdjustments.dialog.previewing', 'Calculating…')}</span>}
+            {draftKey && !previewing && previewCharge && (
+              <span>
+                {t('cpq.priceAdjustments.dialog.previewCharge', 'New offer price')}: <span className="font-mono font-medium">{money(previewCharge.unitPrice, currency)}</span>
+                {' '}{formatDepth(discountDepth(previewCharge.standardUnitPrice ?? standardUnit, previewCharge.unitPrice)) ?? ''}
+              </span>
+            )}
+            {draftKey && !previewing && !previewCharge && previewLine && (
+              <span>
+                {t('cpq.priceAdjustments.dialog.previewLine', 'Line totals')}: MRC <span className="font-mono font-medium">{money(previewLine.mrcTotal, currency)}</span>
+                {' · '}NRC <span className="font-mono font-medium">{money(previewLine.nrcTotal, currency)}</span>
+              </span>
+            )}
+          </div>
+
+          {(errorCode || previewErrors.length > 0 || noteRequired) && (
+            <Alert variant="warning">
+              <AlertDescription>
+                {errorCode ? message(errorCode) : previewErrors.length > 0 ? message(previewErrors[0].code) : message('REASON_NOTE_REQUIRED')}
+                {errorCode === 'STALE_REVISION' && (
+                  <Button variant="outline" size="sm" className="ml-2" onClick={() => { onStale(); onClose() }}>
+                    {t('cpq.priceAdjustments.dialog.reload', 'Reload')}
+                  </Button>
+                )}
+              </AlertDescription>
+            </Alert>
+          )}
+        </div>
+
+        <DialogFooter>
+          <Button variant="outline" onClick={onClose}>{t('cpq.priceAdjustments.dialog.cancel', 'Cancel')}</Button>
+          <Button onClick={() => void save()} disabled={!canSave} title="Ctrl/Cmd+Enter">
+            {saving ? t('cpq.priceAdjustments.dialog.saving', 'Saving…') : t('cpq.priceAdjustments.dialog.save', 'Save')}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}

package/src/modules/cpq/backend/cpq/quotes/[id]/_components/PriceAdjustmentsPanel.tsx

@@ -0,0 +1,124 @@
+'use client'
+
+import * as React from 'react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { Tag } from '@open-mercato/ui/primitives/tag'
+import { InjectionSpot } from '@open-mercato/ui/backend/injection/InjectionSpot'
+import { ADJUSTMENT_ERROR_FALLBACKS } from '../../../../../lib/priceAdjustmentView'
+import { ManualAdjustmentActions, useAccessReasonText, usePriceAdjustmentUi } from './priceAdjustmentContext'
+
+export const PRICE_ADJUSTMENTS_SPOT_ID = 'data-table:cpq.quote_price_adjustments'
+
+export type StoredAdjustment = {
+  id: string
+  level: 'charge' | 'line'
+  quoteLineId: string
+  chargeCode?: string | null
+  chargeTypeFilter?: 'nrc' | 'mrc' | null
+  adjustmentType: 'discount_percent' | 'discount_absolute' | 'price_override'
+  value: number
+  currencyCode?: string | null
+  reasonCode: string
+  reasonNote?: string | null
+  createdByUserId: string
+  createdAt: string
+}
+
+type LineRef = { lineId: string; offeringName: string; offeringId: string | null; configuration?: Record<string, unknown> | null; charges: Array<{ chargeCode: string; chargeName: string }> }
+
+const TYPE_FALLBACKS: Record<StoredAdjustment['adjustmentType'], string> = {
+  price_override: 'Price override',
+  discount_percent: '% discount',
+  discount_absolute: 'Amount off',
+}
+
+function money(amount: number, currency: string) {
+  return new Intl.NumberFormat('en-US', { style: 'currency', currency }).format(amount)
+}
+
+export function PriceAdjustmentsPanel({ quoteId, items, total, lines, currency, errorsById }: {
+  quoteId: string
+  items: StoredAdjustment[]
+  total: number
+  lines: LineRef[]
+  currency: string
+  /** adjustmentId → first error code reported by the latest pricing. */
+  errorsById: Map<string, string>
+}) {
+  const t = useT()
+  const ui = usePriceAdjustmentUi()
+  const lineById = React.useMemo(() => new Map(lines.map((line) => [line.lineId, line])), [lines])
+  const accessText = useAccessReasonText()
+  // Toggle off: stored adjustments still price the quote, so keep them visible (read-only).
+  if (!ui || (ui.access.reason === 'disabled' && items.length === 0)) return null
+
+  return (
+    <div className="rounded-lg border bg-card" data-testid="cpq-price-adjustments-panel">
+      <div className="flex items-center justify-between border-b px-4 py-3">
+        <h3 className="text-sm font-medium">
+          {t('cpq.priceAdjustments.panel.title', 'Price adjustments')}
+          <span className="ml-2 text-xs text-muted-foreground">{total}</span>
+        </h3>
+        {accessText && ui.access.reason !== 'loading' && (
+          <span className="text-xs text-muted-foreground" data-testid="cpq-price-adjustments-locked">{accessText}</span>
+        )}
+      </div>
+      {items.length === 0 ? (
+        <p className="px-4 py-3 text-xs text-muted-foreground">
+          {t('cpq.priceAdjustments.panel.empty', 'No negotiated prices yet. Use “Adjust price” on a charge or “Discount line” on a line.')}
+        </p>
+      ) : (
+        <table className="w-full text-xs">
+          <thead>
+            <tr className="text-muted-foreground">
+              <th className="px-4 py-1.5 text-left font-medium">{t('cpq.priceAdjustments.panel.target', 'Applies to')}</th>
+              <th className="py-1.5 text-left font-medium">{t('cpq.priceAdjustments.panel.type', 'Type')}</th>
+              <th className="py-1.5 text-right font-medium">{t('cpq.priceAdjustments.panel.value', 'Value')}</th>
+              <th className="py-1.5 pl-4 text-left font-medium">{t('cpq.priceAdjustments.panel.reason', 'Reason')}</th>
+              <th className="py-1.5 text-left font-medium">{t('cpq.priceAdjustments.panel.author', 'Author')}</th>
+              <th className="py-1.5 text-left font-medium">{t('cpq.priceAdjustments.panel.date', 'Date')}</th>
+              <th className="w-16" />
+            </tr>
+          </thead>
+          <tbody>
+            {items.map((item) => {
+              const line = lineById.get(item.quoteLineId)
+              const chargeName = item.chargeCode ? line?.charges.find((charge) => charge.chargeCode === item.chargeCode)?.chargeName ?? item.chargeCode : null
+              const scope = item.level === 'line'
+                ? item.chargeTypeFilter === 'mrc' ? t('cpq.priceAdjustments.panel.lineMrc', 'whole line, recurring')
+                  : item.chargeTypeFilter === 'nrc' ? t('cpq.priceAdjustments.panel.lineNrc', 'whole line, one-time')
+                    : t('cpq.priceAdjustments.panel.line', 'whole line')
+                : chargeName
+              const error = errorsById.get(item.id)
+              return (
+                <tr key={item.id} className="border-t" data-testid="cpq-price-adjustment-row">
+                  <td className="px-4 py-1.5">
+                    <span className="font-medium">{line?.offeringName ?? t('cpq.priceAdjustments.panel.removedLine', 'Removed line')}</span>
+                    <span className="text-muted-foreground"> · {scope}</span>
+                    {error && (
+                      <Tag variant="warning" className="ml-1.5 px-1.5 text-xs">
+                        {t('cpq.priceAdjustments.invalid', 'Invalid')}: {t(`cpq.priceAdjustments.errors.${error}`, ADJUSTMENT_ERROR_FALLBACKS[error] ?? error)}
+                      </Tag>
+                    )}
+                  </td>
+                  <td className="py-1.5">{t(`cpq.priceAdjustments.panel.types.${item.adjustmentType}`, TYPE_FALLBACKS[item.adjustmentType])}</td>
+                  <td className="py-1.5 text-right font-mono">
+                    {item.adjustmentType === 'discount_percent' ? `${item.value}%` : money(item.value, item.currencyCode ?? currency)}
+                  </td>
+                  <td className="py-1.5 pl-4">
+                    {ui.reasonLabels[item.reasonCode] ?? item.reasonCode}
+                    {item.reasonNote && <span className="block text-muted-foreground">{item.reasonNote}</span>}
+                  </td>
+                  <td className="py-1.5 font-mono text-muted-foreground" title={item.createdByUserId}>{item.createdByUserId.slice(0, 8)}</td>
+                  <td className="py-1.5 text-muted-foreground">{new Date(item.createdAt).toLocaleDateString()}</td>
+                  <td className="py-1.5 pr-2 text-right"><ManualAdjustmentActions adjustmentId={item.id} /></td>
+                </tr>
+              )
+            })}
+          </tbody>
+        </table>
+      )}
+      <InjectionSpot spotId={PRICE_ADJUSTMENTS_SPOT_ID} context={{ quoteId, adjustments: items }} />
+    </div>
+  )
+}

package/src/modules/cpq/backend/cpq/quotes/[id]/_components/__tests__/PriceAdjustmentsPanel.test.tsx

@@ -0,0 +1,76 @@
+import * as React from 'react'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { I18nProvider } from '@open-mercato/shared/lib/i18n/context'
+import { PriceAdjustmentsPanel, PRICE_ADJUSTMENTS_SPOT_ID } from '../PriceAdjustmentsPanel'
+import { AdjustChargeAction, DiscountLineAction, PriceAdjustmentProvider, type PriceAdjustmentUi } from '../priceAdjustmentContext'
+import { adjustmentAccess } from '../../../../../../lib/priceAdjustmentView'
+
+jest.mock('@open-mercato/ui/backend/injection/InjectionSpot', () => ({
+  InjectionSpot: ({ spotId }: { spotId: string }) => <div data-spot={spotId} />,
+}))
+
+const text = (html: string) => html.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim()
+const line = { lineId: 'l1', offeringName: 'Fiber 1G', offeringId: 'o1', configuration: {}, charges: [{ chargeCode: 'fee', chargeName: 'Monthly fee' }] }
+const item = {
+  id: 'a1', level: 'charge' as const, quoteLineId: 'l1', chargeCode: 'fee', adjustmentType: 'price_override' as const, value: 80,
+  currencyCode: 'USD', reasonCode: 'competitive_match', reasonNote: 'Beat rival', createdByUserId: '77777777-7777-4777-8777-777777777777', createdAt: '2026-11-10T10:00:00.000Z',
+}
+
+function ui(patch: Partial<Parameters<typeof adjustmentAccess>[0]> = {}, extra: Partial<PriceAdjustmentUi> = {}): PriceAdjustmentUi {
+  const input = { enabled: true, canAdjust: true, cpqStatus: 'ready', convertedOrderId: null, ...patch }
+  return {
+    access: adjustmentAccess(input), quoteType: 'new', cpqStatus: input.cpqStatus, reasonLabels: { competitive_match: 'Competitive match' },
+    invalidIds: new Set(), canDeleteInvalid: false, openCharge: jest.fn(), openLine: jest.fn(), edit: jest.fn(), remove: jest.fn(), ...extra,
+  }
+}
+const render = (value: PriceAdjustmentUi, node: React.ReactNode) =>
+  renderToStaticMarkup(<I18nProvider locale="en" dict={{}}><PriceAdjustmentProvider value={value}>{node}</PriceAdjustmentProvider></I18nProvider>)
+const panel = (errors = new Map<string, string>()) => <PriceAdjustmentsPanel quoteId="q1" items={[item]} total={1} lines={[line]} currency="USD" errorsById={errors} />
+
+it('lists the adjustment with target, value, reason label, note and edit/delete, plus the injection spot', () => {
+  const html = render(ui(), panel())
+  const content = text(html)
+  expect(content).toContain('Fiber 1G · Monthly fee')
+  expect(content).toContain('Price override')
+  expect(content).toContain('$80.00')
+  expect(content).toContain('Competitive match Beat rival')
+  expect(html).toContain('aria-label="Edit adjustment"')
+  expect(html).toContain('aria-label="Delete adjustment"')
+  expect(html).toContain(`data-spot="${PRICE_ADJUSTMENTS_SPOT_ID}"`)
+})
+
+it('when locked, explains why and offers no edit or delete for valid rows', () => {
+  const html = render(ui({ cpqStatus: 'in_approval' }), panel())
+  expect(text(html)).toContain('Adjustments are locked in status in_approval')
+  expect(html).not.toContain('Edit adjustment')
+  expect(html).not.toContain('Delete adjustment')
+})
+
+it('keeps Delete for an invalid row while locked and names the error in text', () => {
+  const html = render(ui({ cpqStatus: 'in_approval' }, { invalidIds: new Set(['a1']), canDeleteInvalid: true }), panel(new Map([['a1', 'ABOVE_STANDARD']])))
+  expect(text(html)).toContain('Invalid: The price is above the standard price')
+  expect(html).toContain('Delete adjustment')
+  expect(html).not.toContain('Edit adjustment')
+})
+
+it('stays visible but read-only when the toggle is off and adjustments exist', () => {
+  const html = render(ui({ enabled: false }), panel())
+  expect(text(html)).toContain('Manual price adjustments are turned off')
+  expect(text(html)).toContain('Competitive match')
+  expect(html).not.toContain('Edit adjustment')
+  expect(html).not.toContain('Delete adjustment')
+})
+
+it('renders nothing when the toggle is off and nothing is stored', () => {
+  expect(render(ui({ enabled: false }), <PriceAdjustmentsPanel quoteId="q1" items={[]} total={0} lines={[line]} currency="USD" errorsById={new Map()} />)).toBe('')
+})
+
+it('hides actions without permission and disables them with a tooltip on ARC mirror lines', () => {
+  const charge = { chargeCode: 'fee', chargeName: 'Monthly fee', chargeType: 'mrc' as const, unitPrice: 100, totalPrice: 100 }
+  expect(render(ui({ canAdjust: false }), <><DiscountLineAction line={line} /><AdjustChargeAction line={line} charge={charge} /></>)).toBe('')
+  const mirror = { ...line, configuration: { _arcMirroredFromItemId: 'item' } }
+  const html = render(ui({}, { quoteType: 'amend' }), <AdjustChargeAction line={mirror} charge={charge} />)
+  expect(html).toContain('disabled')
+  expect(html).toContain('Price changes on existing subscription items arrive with a later release')
+  expect(render(ui(), <AdjustChargeAction line={line} charge={{ ...charge, chargeType: 'usage' }} />)).toBe('')
+})

package/src/modules/cpq/backend/cpq/quotes/[id]/_components/arcLineRemoval.tsx

@@ -0,0 +1,76 @@
+'use client'
+
+import * as React from 'react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
+import { isArcCancelledLine, removalCancelsItem, type ArcRemovalLine } from '../../../../../services/arcLineRemoval'
+
+type RemovableLine = Pick<ArcRemovalLine, 'action' | 'configuration'> & { lineId: string; offeringName: string }
+
+export type ArcLineRemovalUi = {
+  /** The line is an existing subscription item marked for removal. */
+  isRemoved: (line: Pick<RemovableLine, 'action'>) => boolean
+  restore: (lineId: string) => void
+}
+
+const ArcLineRemovalContext = React.createContext<ArcLineRemovalUi | null>(null)
+
+export const ArcLineRemovalProvider = ArcLineRemovalContext.Provider
+
+export function useArcLineRemovalUi(): ArcLineRemovalUi | null {
+  return React.useContext(ArcLineRemovalContext)
+}
+
+/**
+ * Line removal on the quote page. On an Amend / Renew quote, removing a line
+ * that mirrors a live subscription item asks for confirmation and marks the
+ * item for removal (server turns it into a `cancel` line); it can be restored.
+ * Other lines are deleted as before.
+ */
+export function useArcLineRemoval<Q extends { id: string; lines: RemovableLine[] }>({ quote, quoteType, onQuote, onError }: {
+  quote: Q | null
+  quoteType: string
+  onQuote: (quote: Q) => void
+  onError: (message: string | null) => void
+}) {
+  const t = useT()
+  const { confirm, ConfirmDialogElement } = useConfirmDialog()
+
+  const send = React.useCallback(async (url: string, method: 'DELETE' | 'POST') => {
+    onError(null)
+    const call = await apiCall<Q & { error?: string }>(url, { method })
+    if (call.ok && call.result) onQuote(call.result)
+    else onError(call.result?.error ?? t('cpq.quotes.lineUpdateFailed', 'Could not update the line'))
+  }, [onError, onQuote, t])
+
+  const remove = React.useCallback(async (lineId: string) => {
+    if (!quote) return
+    const line = quote.lines.find((candidate) => candidate.lineId === lineId)
+    if (line && removalCancelsItem(line, quoteType)) {
+      const ok = await confirm({
+        title: t('cpq.quotes.arc.removeConfirm.title', 'Remove {name} from the subscription?').replace('{name}', line.offeringName),
+        text: t(
+          'cpq.quotes.arc.removeConfirm.text',
+          'This item already exists on the subscription. Removing it here does not delete it from the quote — it stays as a "remove" line, and when the order is activated the item (and its components) is cancelled on the subscription and its recurring charge stops. You can restore it until then.',
+        ),
+        confirmText: t('cpq.quotes.arc.removeConfirm.confirm', 'Remove item'),
+        variant: 'destructive',
+      })
+      if (!ok) return
+    }
+    await send(`/api/cpq/quotes/${quote.id}/items/${lineId}`, 'DELETE')
+  }, [confirm, quote, quoteType, send, t])
+
+  const restore = React.useCallback((lineId: string) => {
+    if (!quote) return
+    void send(`/api/cpq/quotes/${quote.id}/items/${lineId}/restore`, 'POST')
+  }, [quote, send])
+
+  const ui = React.useMemo<ArcLineRemovalUi>(() => ({
+    isRemoved: (line) => isArcCancelledLine(line, quoteType),
+    restore,
+  }), [quoteType, restore])
+
+  return { remove, ui, ConfirmDialogElement }
+}