@dainamite/billing 0.17.0

package/src/modules/billing/components/LineFormDialog.tsx

@@ -0,0 +1,253 @@
+"use client"
+import * as React from 'react'
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@open-mercato/ui/primitives/dialog'
+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 { Kbd, KbdShortcut } from '@open-mercato/ui/primitives/kbd'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+
+/**
+ * Shared dialog for add / edit of an invoice line.
+ *
+ * - `mode='add'` shows empty fields and calls the
+ *   `billing.invoices.add_draft_line` route on submit.
+ * - `mode='edit'` pre-fills from `initial` and calls
+ *   `billing.invoices.edit_draft_line`.
+ *
+ * The caller owns the network call (so we can stay simple and avoid
+ * threading apiCall context through the component). On submit, this
+ * dialog only emits `onSubmit(values)` and the parent decides which
+ * command to hit.
+ *
+ * UX conventions per `@open-mercato/ui`:
+ *   - `Cmd/Ctrl + Enter` submits.
+ *   - `Escape` cancels (Radix Dialog handles this for free).
+ *   - Hint row at the bottom lists both shortcuts via `Kbd` /
+ *     `KbdShortcut` (not raw `<span>`).
+ */
+
+export type LineFormValues = {
+  description: string
+  quantity: number
+  unitPriceNet: number
+  /** Optional explicit total override (operator "I know better" path). */
+  totalNetAmount?: number
+}
+
+export type LineFormDialogProps = {
+  open: boolean
+  mode: 'add' | 'edit'
+  /** Pre-fill values for edit mode. */
+  initial?: Partial<LineFormValues>
+  submitting?: boolean
+  onSubmit: (values: LineFormValues) => Promise<void> | void
+  onCancel: () => void
+}
+
+function toNumber(raw: string): number | null {
+  if (raw.trim() === '') return null
+  const n = Number.parseFloat(raw)
+  return Number.isFinite(n) ? n : null
+}
+
+export function LineFormDialog({
+  open,
+  mode,
+  initial,
+  submitting = false,
+  onSubmit,
+  onCancel,
+}: LineFormDialogProps) {
+  const t = useT()
+  const [description, setDescription] = React.useState(initial?.description ?? '')
+  const [quantity, setQuantity] = React.useState(
+    initial?.quantity != null ? String(initial.quantity) : '',
+  )
+  const [unitPriceNet, setUnitPriceNet] = React.useState(
+    initial?.unitPriceNet != null ? String(initial.unitPriceNet) : '',
+  )
+  const [totalOverride, setTotalOverride] = React.useState(
+    initial?.totalNetAmount != null ? String(initial.totalNetAmount) : '',
+  )
+  const [error, setError] = React.useState<string | null>(null)
+
+  React.useEffect(() => {
+    if (open) {
+      setDescription(initial?.description ?? '')
+      setQuantity(initial?.quantity != null ? String(initial.quantity) : '')
+      setUnitPriceNet(initial?.unitPriceNet != null ? String(initial.unitPriceNet) : '')
+      setTotalOverride(initial?.totalNetAmount != null ? String(initial.totalNetAmount) : '')
+      setError(null)
+    }
+  }, [open, initial])
+
+  const handleSubmit = React.useCallback(async () => {
+    const trimmedDescription = description.trim()
+    if (!trimmedDescription) {
+      setError(t('billing.invoices.lines.form.error.description_required', 'Description is required'))
+      return
+    }
+    const quantityValue = toNumber(quantity)
+    if (quantityValue == null || quantityValue < 0) {
+      setError(t('billing.invoices.lines.form.error.quantity_invalid', 'Quantity must be a non-negative number'))
+      return
+    }
+    const unitPriceValue = toNumber(unitPriceNet)
+    if (unitPriceValue == null) {
+      setError(t('billing.invoices.lines.form.error.unit_price_invalid', 'Unit price must be a number'))
+      return
+    }
+    const totalOverrideRaw = totalOverride.trim()
+    let totalOverrideValue: number | undefined
+    if (totalOverrideRaw !== '') {
+      const parsed = toNumber(totalOverrideRaw)
+      if (parsed == null) {
+        setError(t('billing.invoices.lines.form.error.total_invalid', 'Total override must be a number when set'))
+        return
+      }
+      totalOverrideValue = parsed
+    }
+    setError(null)
+    await onSubmit({
+      description: trimmedDescription,
+      quantity: quantityValue,
+      unitPriceNet: unitPriceValue,
+      totalNetAmount: totalOverrideValue,
+    })
+  }, [description, onSubmit, quantity, t, totalOverride, unitPriceNet])
+
+  const handleKeyDown = React.useCallback(
+    (event: React.KeyboardEvent<HTMLDivElement>) => {
+      // Cmd/Ctrl + Enter submits — required by the OM UX convention
+      // for every dialog. Escape is handled by Radix Dialog itself.
+      if ((event.metaKey || event.ctrlKey) && event.key === 'Enter') {
+        event.preventDefault()
+        void handleSubmit()
+      }
+    },
+    [handleSubmit],
+  )
+
+  // Auto-compute total for the helper text — purely informational, not
+  // submitted unless the operator types into `totalOverride`.
+  const computedTotal = React.useMemo(() => {
+    const q = toNumber(quantity)
+    const u = toNumber(unitPriceNet)
+    if (q == null || u == null) return null
+    return (Math.round(q * u * 100) / 100).toFixed(2)
+  }, [quantity, unitPriceNet])
+
+  return (
+    <Dialog open={open} onOpenChange={(next) => { if (!next) onCancel() }}>
+      <DialogContent onKeyDown={handleKeyDown}>
+        <DialogHeader>
+          <DialogTitle>
+            {mode === 'add'
+              ? t('billing.invoices.lines.form.title_add', 'Add invoice line')
+              : t('billing.invoices.lines.form.title_edit', 'Edit invoice line')}
+          </DialogTitle>
+          <DialogDescription>
+            {t(
+              'billing.invoices.lines.form.help',
+              'Changes are recorded in the draft-edit audit log.',
+            )}
+          </DialogDescription>
+        </DialogHeader>
+        <div className="flex flex-col gap-4 py-2">
+          <label className="flex flex-col gap-1 text-sm">
+            <span className="text-muted-foreground">
+              {t('billing.invoices.lines.form.description', 'Description')}
+            </span>
+            <Textarea
+              value={description}
+              onChange={(event) => setDescription(event.currentTarget.value)}
+              rows={2}
+            />
+          </label>
+          <div className="grid grid-cols-2 gap-3">
+            <label className="flex flex-col gap-1 text-sm">
+              <span className="text-muted-foreground">
+                {t('billing.invoices.lines.form.quantity', 'Quantity')}
+              </span>
+              <Input
+                type="number"
+                value={quantity}
+                step="0.0001"
+                onChange={(event) => setQuantity(event.currentTarget.value)}
+              />
+            </label>
+            <label className="flex flex-col gap-1 text-sm">
+              <span className="text-muted-foreground">
+                {t('billing.invoices.lines.form.unit_price', 'Unit price (net)')}
+              </span>
+              <Input
+                type="number"
+                value={unitPriceNet}
+                step="0.0001"
+                onChange={(event) => setUnitPriceNet(event.currentTarget.value)}
+              />
+            </label>
+          </div>
+          <label className="flex flex-col gap-1 text-sm">
+            <span className="text-muted-foreground">
+              {t('billing.invoices.lines.form.total_override', 'Total override (optional)')}
+            </span>
+            <Input
+              type="number"
+              value={totalOverride}
+              step="0.0001"
+              placeholder={computedTotal ?? ''}
+              onChange={(event) => setTotalOverride(event.currentTarget.value)}
+            />
+            <span className="text-xs text-muted-foreground">
+              {computedTotal != null
+                ? t(
+                    'billing.invoices.lines.form.computed_total',
+                    'Computed total: {computed}',
+                  ).replace('{computed}', computedTotal)
+                : null}
+            </span>
+          </label>
+          {error ? (
+            <div className="text-sm text-destructive">{error}</div>
+          ) : null}
+        </div>
+        <DialogFooter>
+          <div className="flex items-center justify-between gap-3 w-full">
+            <span className="text-xs text-muted-foreground">
+              <KbdShortcut keys={['Ctrl/⌘', 'Enter']} />
+              {' '}
+              {t('billing.invoices.lines.form.submit_hint', 'to save,')}
+              {' '}
+              <Kbd>Esc</Kbd>
+              {' '}
+              {t('billing.invoices.lines.form.cancel_hint', 'to cancel')}
+            </span>
+            <div className="flex items-center gap-2">
+              <Button type="button" variant="outline" onClick={onCancel}>
+                {t('billing.common.cancel', 'Cancel')}
+              </Button>
+              <Button
+                type="button"
+                onClick={() => void handleSubmit()}
+                disabled={submitting}
+              >
+                {submitting
+                  ? t('billing.invoices.lines.form.saving', 'Saving…')
+                  : t('billing.common.save', 'Save')}
+              </Button>
+            </div>
+          </div>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}

package/src/modules/billing/components/UsageForm.tsx

@@ -0,0 +1,326 @@
+"use client"
+import * as React from 'react'
+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 {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@open-mercato/ui/primitives/select'
+import { Kbd, KbdShortcut } from '@open-mercato/ui/primitives/kbd'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+
+/**
+ * Manual Billing Account Usage entry form.
+ *
+ * Usage is normally ingested by an external metering system via
+ * `POST /api/billing/usage` + an `X-Api-Key` scoped to
+ * `billing.usage.ingest`. This form gives operators the same path from
+ * the admin UI — for corrections, demos, or customers without an
+ * automated meter. It POSTs to the very same endpoint, so the
+ * idempotency (`sourceRef`) and append-only guarantees are identical.
+ *
+ * Usage records are immutable once written — there is no edit/delete,
+ * hence this is a create-only form (mirrors the `billing.usage.create`
+ * command, which has no update sibling).
+ */
+
+// The accounts list API returns snake_case rows — mirror that here so
+// the picker reads real values (camelCase would resolve to `undefined`).
+export type UsageAccountOption = {
+  id: string
+  name: string
+  customer_id: string
+  currency_code: string
+}
+
+export type UsageFormValues = {
+  billAccountId: string
+  uomCode: string
+  quantity: string
+  periodStart: string
+  periodEnd: string
+  lineDescription: string
+  sourceRef: string
+}
+
+export type AssembledUsagePayload = {
+  billAccountId: string
+  uomCode: string
+  quantity: number
+  periodStart: string
+  periodEnd: string
+  lineDescription?: string
+  sourceRef?: string
+}
+
+export type UsageFormProps = {
+  accountOptions: UsageAccountOption[]
+  initial?: Partial<UsageFormValues>
+  submitting?: boolean
+  onSubmit: (assembled: AssembledUsagePayload) => Promise<void> | void
+  onCancel: () => void
+}
+
+const EMPTY_VALUES: UsageFormValues = {
+  billAccountId: '',
+  uomCode: '',
+  quantity: '',
+  periodStart: '',
+  periodEnd: '',
+  lineDescription: '',
+  sourceRef: '',
+}
+
+function firstOfMonthIso(): string {
+  const now = new Date()
+  return new Date(now.getFullYear(), now.getMonth(), 1).toISOString().slice(0, 10)
+}
+
+function todayIso(): string {
+  return new Date().toISOString().slice(0, 10)
+}
+
+function mergeInitial(initial: Partial<UsageFormValues> | undefined): UsageFormValues {
+  return {
+    ...EMPTY_VALUES,
+    periodStart: EMPTY_VALUES.periodStart || firstOfMonthIso(),
+    periodEnd: EMPTY_VALUES.periodEnd || todayIso(),
+    ...initial,
+  }
+}
+
+function toNumber(raw: string): number | null {
+  if (raw.trim() === '') return null
+  const n = Number.parseFloat(raw)
+  return Number.isFinite(n) ? n : null
+}
+
+export function UsageForm({
+  accountOptions,
+  initial,
+  submitting = false,
+  onSubmit,
+  onCancel,
+}: UsageFormProps) {
+  const t = useT()
+  const [values, setValues] = React.useState<UsageFormValues>(() => mergeInitial(initial))
+  const [error, setError] = React.useState<string | null>(null)
+
+  const initialKey = React.useMemo(() => JSON.stringify(initial ?? null), [initial])
+  React.useEffect(() => {
+    // Depend on the serialized key only — `initial` is a fresh object ref on
+    // every parent render, so including it would re-run this effect (and wipe
+    // in-progress edits) whenever the parent re-renders for an unrelated reason.
+    setValues(mergeInitial(initial))
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [initialKey])
+
+  const set = React.useCallback(
+    <K extends keyof UsageFormValues>(key: K, value: UsageFormValues[K]) => {
+      setValues((prev) => ({ ...prev, [key]: value }))
+    },
+    [],
+  )
+
+  const handleSubmit = React.useCallback(async () => {
+    if (!values.billAccountId.trim()) {
+      setError(t('billing.usage.form.error.account_required', 'Billing Account is required'))
+      return
+    }
+    if (!values.uomCode.trim()) {
+      setError(t('billing.usage.form.error.uom_required', 'UoM code is required'))
+      return
+    }
+    const quantity = toNumber(values.quantity)
+    if (quantity == null || quantity < 0) {
+      setError(
+        t('billing.usage.form.error.quantity_invalid', 'Quantity must be a non-negative number'),
+      )
+      return
+    }
+    if (!values.periodStart || !values.periodEnd) {
+      setError(t('billing.usage.form.error.period_required', 'Period start and end are required'))
+      return
+    }
+    if (values.periodEnd < values.periodStart) {
+      setError(
+        t('billing.usage.form.error.period_order', 'Period end must be on or after period start'),
+      )
+      return
+    }
+    setError(null)
+
+    const payload: AssembledUsagePayload = {
+      billAccountId: values.billAccountId,
+      uomCode: values.uomCode.trim(),
+      quantity,
+      periodStart: values.periodStart,
+      periodEnd: values.periodEnd,
+    }
+    if (values.lineDescription.trim()) payload.lineDescription = values.lineDescription.trim()
+    if (values.sourceRef.trim()) payload.sourceRef = values.sourceRef.trim()
+    await onSubmit(payload)
+  }, [onSubmit, t, values])
+
+  const handleKeyDown = React.useCallback(
+    (event: React.KeyboardEvent<HTMLDivElement>) => {
+      if ((event.metaKey || event.ctrlKey) && event.key === 'Enter') {
+        event.preventDefault()
+        void handleSubmit()
+      } else if (event.key === 'Escape') {
+        event.preventDefault()
+        onCancel()
+      }
+    },
+    [handleSubmit, onCancel],
+  )
+
+  return (
+    <div className="rounded-lg border border-border bg-card p-6" onKeyDown={handleKeyDown}>
+      <div className="grid grid-cols-2 gap-4">
+        <label className="flex flex-col gap-1 text-sm col-span-2">
+          <span className="text-muted-foreground">
+            {t('billing.usage.form.account', 'Billing Account')}
+            <span className="text-destructive"> *</span>
+          </span>
+          <Select
+            value={values.billAccountId}
+            onValueChange={(next) => set('billAccountId', next)}
+          >
+            <SelectTrigger>
+              <SelectValue
+                placeholder={t('billing.usage.form.account.placeholder', 'Select an account')}
+              />
+            </SelectTrigger>
+            <SelectContent>
+              {accountOptions.map((opt) => (
+                <SelectItem key={opt.id} value={opt.id}>
+                  {opt.name} · {opt.customer_id} · {opt.currency_code}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        </label>
+
+        <label className="flex flex-col gap-1 text-sm">
+          <span className="text-muted-foreground">
+            {t('billing.usage.form.uom_code', 'UoM code')}
+            <span className="text-destructive"> *</span>
+          </span>
+          <Input
+            value={values.uomCode}
+            placeholder={t('billing.usage.form.uom_code.placeholder', 'api_request, gb, seat, …')}
+            onChange={(event) => set('uomCode', event.currentTarget.value)}
+          />
+          <span className="text-xs text-muted-foreground">
+            {t(
+              'billing.usage.form.uom_code.help',
+              'Must exactly match the UoM on a usage Billing Item for this account — no conversion.',
+            )}
+          </span>
+        </label>
+
+        <label className="flex flex-col gap-1 text-sm">
+          <span className="text-muted-foreground">
+            {t('billing.usage.form.quantity', 'Quantity')}
+            <span className="text-destructive"> *</span>
+          </span>
+          <Input
+            type="number"
+            step="0.0001"
+            min="0"
+            value={values.quantity}
+            onChange={(event) => set('quantity', event.currentTarget.value)}
+          />
+          <span className="text-xs text-muted-foreground">
+            {t(
+              'billing.usage.form.quantity.help',
+              'Total units consumed in the period (pre-aggregated).',
+            )}
+          </span>
+        </label>
+
+        <label className="flex flex-col gap-1 text-sm">
+          <span className="text-muted-foreground">
+            {t('billing.usage.form.period_start', 'Period start')}
+            <span className="text-destructive"> *</span>
+          </span>
+          <Input
+            type="date"
+            value={values.periodStart}
+            onChange={(event) => set('periodStart', event.currentTarget.value)}
+          />
+        </label>
+
+        <label className="flex flex-col gap-1 text-sm">
+          <span className="text-muted-foreground">
+            {t('billing.usage.form.period_end', 'Period end')}
+            <span className="text-destructive"> *</span>
+          </span>
+          <Input
+            type="date"
+            value={values.periodEnd}
+            onChange={(event) => set('periodEnd', event.currentTarget.value)}
+          />
+        </label>
+
+        <label className="flex flex-col gap-1 text-sm col-span-2">
+          <span className="text-muted-foreground">
+            {t('billing.usage.form.description', 'Description (optional)')}
+          </span>
+          <Textarea
+            value={values.lineDescription}
+            rows={2}
+            onChange={(event) => set('lineDescription', event.currentTarget.value)}
+          />
+          <span className="text-xs text-muted-foreground">
+            {t(
+              'billing.usage.form.description.help',
+              'Shown on its own invoice line when set; otherwise matching records are aggregated into one line.',
+            )}
+          </span>
+        </label>
+
+        <label className="flex flex-col gap-1 text-sm col-span-2">
+          <span className="text-muted-foreground">
+            {t('billing.usage.form.source_ref', 'Source reference (optional)')}
+          </span>
+          <Input
+            value={values.sourceRef}
+            onChange={(event) => set('sourceRef', event.currentTarget.value)}
+          />
+          <span className="text-xs text-muted-foreground">
+            {t(
+              'billing.usage.form.source_ref.help',
+              'Idempotency key — re-submitting the same reference for this account is deduplicated.',
+            )}
+          </span>
+        </label>
+      </div>
+
+      {error ? <div className="mt-4 text-sm text-destructive">{error}</div> : null}
+
+      <div className="mt-6 flex items-center justify-between gap-3">
+        <span className="text-xs text-muted-foreground">
+          <KbdShortcut keys={['Ctrl/⌘', 'Enter']} />{' '}
+          {t('billing.usage.form.submit_hint', 'to save,')} <Kbd>Esc</Kbd>{' '}
+          {t('billing.usage.form.cancel_hint', 'to discard')}
+        </span>
+        <div className="flex items-center gap-2">
+          <Button type="button" variant="outline" onClick={onCancel}>
+            {t('billing.common.cancel', 'Cancel')}
+          </Button>
+          <Button type="button" onClick={() => void handleSubmit()} disabled={submitting}>
+            {submitting
+              ? t('billing.usage.form.saving', 'Saving…')
+              : t('billing.usage.form.create', 'Record usage')}
+          </Button>
+        </div>
+      </div>
+    </div>
+  )
+}