@spree/seller-dashboard 1.0.0-beta.1

package/src/components/orders/fulfillment-delivery-dialog.tsx

@@ -0,0 +1,82 @@
+import { zodResolver } from '@hookform/resolvers/zod'
+import {
+  type DeliveryFormValues,
+  deliveryFormSchema,
+  mapSpreeErrorsToForm,
+} from '@spree/dashboard-core'
+import { DeliveryFormDialog } from '@spree/dashboard-ui'
+import type { Delivery } from '@spree/seller-sdk'
+import { useForm } from 'react-hook-form'
+import { useFulfillmentActions } from '../../hooks/use-fulfillments'
+import { useTrackingCarriers } from '../../hooks/use-reasons'
+
+/** What the seller records against one consignment of a parcel they ship themselves. */
+export function FulfillmentDeliveryDialog({
+  orderId,
+  fulfillmentId,
+  delivery,
+  open,
+  onOpenChange,
+}: {
+  orderId: string
+  fulfillmentId: string
+  delivery?: Delivery
+  open: boolean
+  onOpenChange: (open: boolean) => void
+}) {
+  const { createDelivery, updateDelivery } = useFulfillmentActions(orderId)
+  const { data: carriersData } = useTrackingCarriers(open)
+
+  const carriers = carriersData?.data ?? []
+  const carrierKeys = carriers.map((carrier) => carrier.id)
+  const carrierLabel = (value: string) =>
+    carriers.find((carrier) => carrier.id === value)?.name ?? value
+
+  const form = useForm<DeliveryFormValues>({
+    resolver: zodResolver(deliveryFormSchema),
+    defaultValues: {
+      tracking_number: delivery?.tracking_number ?? '',
+      carrier: delivery?.carrier ?? '',
+    },
+  })
+
+  async function onSubmit(values: DeliveryFormValues) {
+    try {
+      const tracking_number = values.tracking_number.trim()
+      const carrier = values.carrier.trim()
+
+      if (delivery) {
+        // Carrier is sent even when empty: clearing it is how a merchant asks
+        // for it to be detected from the number again.
+        await updateDelivery.mutateAsync({
+          fulfillmentId,
+          deliveryId: delivery.id,
+          tracking_number,
+          carrier,
+        })
+      } else {
+        await createDelivery.mutateAsync({
+          fulfillmentId,
+          tracking_number,
+          carrier: carrier || undefined,
+        })
+      }
+      onOpenChange(false)
+    } catch (err) {
+      if (!mapSpreeErrorsToForm(err, form.setError)) throw err
+    }
+  }
+
+  return (
+    <DeliveryFormDialog
+      form={form}
+      open={open}
+      onOpenChange={onOpenChange}
+      editing={!!delivery}
+      carrierKeys={carrierKeys}
+      carrierLabel={carrierLabel}
+      onSubmit={onSubmit}
+      pending={createDelivery.isPending || updateDelivery.isPending}
+    />
+  )
+}

package/src/components/orders/fulfillment-edit-dialog.tsx

@@ -0,0 +1,95 @@
+import { FulfillmentEditDialog as SharedFulfillmentEditDialog } from '@spree/dashboard-ui'
+import { type Fulfillment, SpreeError } from '@spree/seller-sdk'
+import { useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { useFulfillmentActions } from '../../hooks/use-fulfillments'
+import { useOrder } from '../../hooks/use-order'
+import { useStockLocations } from '../../hooks/use-stock-locations'
+
+/**
+ * Where the parcel ships from and which quoted service carries it.
+ *
+ * The dialog is shared with the operator's order page; this supplies the
+ * seller's view of it. The shelves come from the seller's own endpoint, so the
+ * marketplace's warehouses never appear — and the server refuses one anyway.
+ */
+export function FulfillmentEditDialog({
+  orderId,
+  fulfillment,
+  open,
+  onOpenChange,
+}: {
+  orderId: string
+  fulfillment: Fulfillment
+  open: boolean
+  onOpenChange: (open: boolean) => void
+}) {
+  const { t } = useTranslation()
+  const { update } = useFulfillmentActions(orderId)
+  const { data: locationsData } = useStockLocations(open)
+  const { refetch: refetchOrder } = useOrder(orderId)
+  const [errorMessage, setErrorMessage] = useState<string>()
+
+  const originOptions = (locationsData?.data ?? []).map((location) => ({
+    value: location.id,
+    label: location.name,
+  }))
+
+  const rateOptions = (fulfillment.delivery_rates ?? []).map((rate) => ({
+    value: rate.id,
+    label: `${rate.name} — ${
+      Number.parseFloat(rate.cost) === 0 ? t('orders.fulfillments.free') : rate.display_cost
+    }`,
+  }))
+
+  async function handleSubmit(
+    values: { stockLocationId: string; selectedDeliveryRateId: string },
+    changed: { origin: boolean; rate: boolean },
+  ): Promise<'requote' | 'done'> {
+    setErrorMessage(undefined)
+
+    try {
+      if (changed.origin) {
+        await update.mutateAsync({
+          fulfillmentId: fulfillment.id,
+          stock_location_id: values.stockLocationId,
+        })
+
+        // Moving the parcel re-quotes it: the rates on screen were priced from
+        // the shelf it just left. Pull the fresh parcel back so the seller
+        // confirms a service that actually applies.
+        await refetchOrder()
+        return 'requote'
+      }
+
+      if (changed.rate) {
+        await update.mutateAsync({
+          fulfillmentId: fulfillment.id,
+          selected_delivery_rate_id: values.selectedDeliveryRateId,
+        })
+      }
+
+      return 'done'
+    } catch (err) {
+      // A refused save keeps the dialog open with the server's reason on it;
+      // anything else is a real fault and belongs to the caller's toast.
+      if (!(err instanceof SpreeError)) throw err
+      setErrorMessage(err.message)
+      return 'requote'
+    }
+  }
+
+  return (
+    <SharedFulfillmentEditDialog
+      open={open}
+      onOpenChange={onOpenChange}
+      originOptions={originOptions}
+      rateOptions={rateOptions}
+      currentOriginId={fulfillment.stock_location_id ?? ''}
+      currentRateId={fulfillment.selected_delivery_rate_id ?? ''}
+      onSubmit={handleSubmit}
+      pending={update.isPending}
+      errorMessage={errorMessage}
+    />
+  )
+}

package/src/components/orders/fulfillment-fulfill-form.tsx

@@ -0,0 +1,132 @@
+import { zodResolver } from '@hookform/resolvers/zod'
+import {
+  type FulfillmentItemRow,
+  fulfillmentItemRows,
+  mapSpreeErrorsToForm,
+} from '@spree/dashboard-core'
+import {
+  type FulfillableRowData,
+  FulfillItemsForm,
+  type FulfillItemsValues,
+} from '@spree/dashboard-ui'
+import type { Fulfillment, Order } from '@spree/seller-sdk'
+import { useEffect, useRef } from 'react'
+import { useForm } from 'react-hook-form'
+import { useTranslation } from 'react-i18next'
+import { useFulfillmentActions } from '../../hooks/use-fulfillments'
+import { useTrackingCarriers } from '../../hooks/use-reasons'
+import { type FulfillItemsFormValues, fulfillItemsFormSchema } from '../../schemas/fulfillment'
+
+/**
+ * Rows whose fulfillment item no longer maps to a line item are dropped: the
+ * fulfill endpoint addresses items by line item, so there is nothing to send
+ * for them. They still ship — selecting everything else sends no `items` at
+ * all, which ships the whole parcel including them.
+ */
+function fulfillableRows(rows: FulfillmentItemRow[]): FulfillableRowData[] {
+  return rows.flatMap((row) => (row.lineItem ? [{ ...row, itemId: row.lineItem.id }] : []))
+}
+
+/** What the seller sends out of one parcel. */
+export function FulfillmentFulfillForm({
+  order,
+  fulfillment,
+  onDone,
+}: {
+  order: Order
+  fulfillment: Fulfillment
+  onDone: () => void
+}) {
+  const { t } = useTranslation()
+  const { fulfill } = useFulfillmentActions(order.id)
+  const { data: carriersData } = useTrackingCarriers()
+
+  const carrierOptions = [
+    { value: '', label: t('admin.orders.detail.fulfillments.carrier_auto') },
+    ...(carriersData?.data ?? []).map((carrier) => ({ value: carrier.id, label: carrier.name })),
+  ]
+
+  const idPrefix = `fulfill-${fulfillment.id}`
+  const rows = fulfillableRows(fulfillmentItemRows(fulfillment, order.items ?? []))
+  // The parcel holds units, but none of them can be named by line item — the
+  // only case where shipping with nothing picked is right. An empty parcel
+  // has nothing to ship and stays unsubmittable.
+  const canShipWholeParcel = rows.length === 0 && (fulfillment.fulfillment_items?.length ?? 0) > 0
+
+  const form = useForm<FulfillItemsFormValues>({
+    resolver: zodResolver(fulfillItemsFormSchema),
+    defaultValues: {
+      items: rows.map((row) => ({ item_id: row.itemId, selected: true, quantity: row.quantity })),
+      tracking: fulfillment.tracking ?? '',
+      // Detected from the number, or picked in the tracking dialog once the
+      // parcel has one.
+      tracking_carrier: '',
+      notify_customer: true,
+    },
+  })
+
+  // A refetch re-renders this form with fresh rows, so the values it mirrors
+  // have to follow. The effect keys on the parcel's composition rather than on
+  // the rows array, so a refetch returning the same units does not wipe what
+  // the seller typed.
+  const rowsRef = useRef(rows)
+  rowsRef.current = rows
+  const rowsKey = rows.map((row) => `${row.itemId}:${row.quantity}`).join('|')
+  const seededKey = useRef(rowsKey)
+
+  useEffect(() => {
+    if (seededKey.current === rowsKey) return
+    seededKey.current = rowsKey
+    form.reset({
+      ...form.getValues(),
+      items: rowsRef.current.map((row) => ({
+        item_id: row.itemId,
+        selected: true,
+        quantity: row.quantity,
+      })),
+    })
+  }, [rowsKey, form])
+
+  const totalAvailable = rows.reduce((sum, row) => sum + row.quantity, 0)
+
+  async function onSubmit(values: FulfillItemsValues) {
+    const items = values.items
+      .filter((item) => item.selected && item.quantity > 0)
+      .map((item) => ({ item_id: item.item_id, quantity: item.quantity }))
+    // An omitted `items` ships the whole parcel, which is only right when
+    // nothing was addressable. A partial pick that came out empty, or an
+    // empty parcel, is a no-op worth refusing.
+    if (items.length === 0 && !canShipWholeParcel) return
+
+    const everything = items.reduce((sum, item) => sum + item.quantity, 0) === totalAvailable
+    const tracking = values.tracking.trim()
+
+    try {
+      // Omitting `items` ships the whole parcel, avoiding a pointless split
+      // when every unit was selected anyway.
+      await fulfill.mutateAsync({
+        fulfillmentId: fulfillment.id,
+        items: everything ? undefined : items,
+        tracking: tracking || undefined,
+        tracking_carrier: values.tracking_carrier || undefined,
+        notify_customer: values.notify_customer,
+      })
+      onDone()
+    } catch (err) {
+      if (!mapSpreeErrorsToForm(err, form.setError)) throw err
+    }
+  }
+
+  return (
+    <FulfillItemsForm
+      form={form}
+      rows={rows}
+      idPrefix={idPrefix}
+      carrierOptions={carrierOptions}
+      onSubmit={onSubmit}
+      onCancel={onDone}
+      canShipWholeParcel={canShipWholeParcel}
+      pending={fulfill.isPending}
+    />
+  )
+}

package/src/components/orders/fulfillment-label-upload-dialog.tsx

@@ -0,0 +1,95 @@
+import { zodResolver } from '@hookform/resolvers/zod'
+import {
+  EMPTY_FILE_UPLOAD_VALUE,
+  FileUploadField,
+  type FileUploadValue,
+  LABEL_ACCEPT,
+  type LabelUploadFormValues,
+  labelUploadFormSchema,
+  mapSpreeErrorsToForm,
+} from '@spree/dashboard-core'
+import { LabelUploadDialog } from '@spree/dashboard-ui'
+import { useState } from 'react'
+import { useForm } from 'react-hook-form'
+import { useTranslation } from 'react-i18next'
+import { useFulfillmentActions } from '../../hooks/use-fulfillments'
+import { useTrackingCarriers } from '../../hooks/use-reasons'
+
+/** Records postage the seller bought elsewhere. Buying and refunding are not here: both run through the marketplace's carrier account, and the endpoint refuses them. */
+export function FulfillmentLabelUploadDialog({
+  orderId,
+  fulfillmentId,
+  currency,
+  open,
+  onOpenChange,
+}: {
+  orderId: string
+  fulfillmentId: string
+  currency: string
+  open: boolean
+  onOpenChange: (open: boolean) => void
+}) {
+  const { t } = useTranslation()
+  const { uploadLabel } = useFulfillmentActions(orderId)
+  const { data: carriersData } = useTrackingCarriers(open)
+
+  const carriers = carriersData?.data ?? []
+  const carrierKeys = carriers.map((carrier) => carrier.id)
+  const carrierLabel = (value: string) =>
+    carriers.find((carrier) => carrier.id === value)?.name ?? value
+
+  const [file, setFile] = useState<FileUploadValue>(EMPTY_FILE_UPLOAD_VALUE)
+  // The signed id does not exist until the upload resolves, so saving during
+  // one would silently drop the file.
+  const [uploading, setUploading] = useState(false)
+
+  const form = useForm<LabelUploadFormValues>({
+    resolver: zodResolver(labelUploadFormSchema),
+    defaultValues: { tracking_number: '', carrier: '', cost: '' },
+  })
+
+  async function onSubmit(values: LabelUploadFormValues) {
+    // Guarded here as well as on the server: submitting without one would
+    // record a label with no file behind it.
+    if (!file.signedId) {
+      form.setError('root', { message: t('admin.orders.detail.fulfillments.upload_label_file') })
+      return
+    }
+
+    try {
+      await uploadLabel.mutateAsync({
+        fulfillmentId,
+        file: file.signedId,
+        tracking_number: values.tracking_number.trim(),
+        carrier: values.carrier.trim() || undefined,
+        cost: values.cost.trim() || undefined,
+        currency: values.cost.trim() ? currency : undefined,
+      })
+      onOpenChange(false)
+    } catch (err) {
+      if (!mapSpreeErrorsToForm(err, form.setError)) throw err
+    }
+  }
+
+  return (
+    <LabelUploadDialog
+      form={form}
+      open={open}
+      onOpenChange={onOpenChange}
+      fileField={
+        <FileUploadField
+          accept={LABEL_ACCEPT}
+          value={file}
+          onChange={setFile}
+          onUploadingChange={setUploading}
+          private
+        />
+      }
+      carrierKeys={carrierKeys}
+      carrierLabel={carrierLabel}
+      currency={currency}
+      onSubmit={onSubmit}
+      pending={uploadLabel.isPending || uploading}
+    />
+  )
+}

package/src/components/orders/fulfillment-split-dialog.tsx

@@ -0,0 +1,142 @@
+import {
+  Button,
+  Dialog,
+  DialogBody,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  Field,
+  FieldError,
+  FieldLabel,
+  Input,
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+  useConfirm,
+} from '@spree/dashboard-ui'
+import type { Fulfillment } from '@spree/seller-sdk'
+import { useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { useFulfillmentActions } from '../../hooks/use-fulfillments'
+import { unitLabel } from './line-label'
+
+/**
+ * Moves part of a parcel onto one of its own, for goods leaving separately.
+ *
+ * One variant at a time, which is the granularity the transfer works at —
+ * splitting several apart is several splits.
+ */
+export function FulfillmentSplitDialog({
+  orderId,
+  fulfillment,
+  open,
+  onOpenChange,
+}: {
+  orderId: string
+  fulfillment: Fulfillment
+  open: boolean
+  onOpenChange: (open: boolean) => void
+}) {
+  const { t } = useTranslation()
+  const confirm = useConfirm()
+  const { split } = useFulfillmentActions(orderId)
+
+  // The endpoint addresses what to move by variant, so a row without one is
+  // not splittable — offering it would 404 on a unit the seller just picked
+  // out of their own parcel.
+  const units = (fulfillment.fulfillment_items ?? []).flatMap((item) =>
+    item.variant_id
+      ? [{ value: item.variant_id, label: unitLabel(item), quantity: item.quantity }]
+      : [],
+  )
+
+  const [variantId, setVariantId] = useState(units[0]?.value ?? '')
+  const [quantity, setQuantity] = useState(1)
+
+  const selected = units.find((unit) => unit.value === variantId)
+  const totalUnits = units.reduce((total, unit) => total + unit.quantity, 0)
+  // Moving everything is not a split — it empties the parcel and leaves an
+  // orphan behind, which is never what was meant.
+  const wouldEmpty = quantity >= totalUnits
+  const invalid = !variantId || quantity < 1 || wouldEmpty || quantity > (selected?.quantity ?? 0)
+
+  async function handleSplit() {
+    const ok = await confirm({
+      title: t('orders.fulfillments.split_title'),
+      message: t('orders.fulfillments.confirm_split'),
+      confirmLabel: t('orders.fulfillments.split'),
+    })
+    if (!ok) return
+
+    await split
+      .mutateAsync({ fulfillmentId: fulfillment.id, variant_id: variantId, quantity })
+      .then(() => onOpenChange(false))
+      .catch(() => undefined)
+  }
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>{t('orders.fulfillments.split_title')}</DialogTitle>
+          <DialogDescription>{t('orders.fulfillments.split_description')}</DialogDescription>
+        </DialogHeader>
+
+        <DialogBody>
+          <div className="flex flex-col gap-4">
+            <Field>
+              <FieldLabel htmlFor="split-variant">{t('orders.fulfillments.split_item')}</FieldLabel>
+              <Select
+                items={units}
+                value={variantId}
+                onValueChange={(value) => setVariantId((value as string) ?? '')}
+              >
+                <SelectTrigger id="split-variant">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  {units.map((unit) => (
+                    <SelectItem key={unit.value} value={unit.value}>
+                      {unit.label}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </Field>
+
+            <Field>
+              <FieldLabel htmlFor="split-quantity">
+                {t('orders.fulfillments.split_quantity')}
+              </FieldLabel>
+              <Input
+                id="split-quantity"
+                type="number"
+                min={1}
+                max={selected?.quantity ?? 1}
+                value={quantity}
+                // Clearing the field yields NaN, which fails every comparison
+                // below — so `invalid` would read false and the split would
+                // send a null quantity.
+                onChange={(event) => setQuantity(Number(event.target.value) || 0)}
+              />
+              {wouldEmpty && <FieldError>{t('orders.fulfillments.split_would_empty')}</FieldError>}
+            </Field>
+          </div>
+        </DialogBody>
+
+        <DialogFooter>
+          <Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
+            {t('common.cancel')}
+          </Button>
+          <Button type="button" disabled={invalid || split.isPending} onClick={handleSplit}>
+            {split.isPending ? t('orders.fulfillments.splitting') : t('orders.fulfillments.split')}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}