@spree/seller-dashboard 1.0.0-beta.1

package/src/components/orders/fulfillments-card.tsx

@@ -0,0 +1,289 @@
+import { fulfillmentItemRows } from '@spree/dashboard-core'
+import {
+  Badge,
+  Button,
+  Card,
+  CardAction,
+  CardContent,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+  FulfillmentItemList,
+  FulfillmentPanel,
+  StatusBadge,
+  useConfirm,
+} from '@spree/dashboard-ui'
+import {
+  EllipsisVerticalIcon,
+  PencilIcon,
+  PlusIcon,
+  PrinterIcon,
+  SplitIcon,
+  TagIcon,
+  TruckIcon,
+  XCircleIcon,
+} from '@spree/dashboard-ui/icons'
+import type { Delivery, Fulfillment, Order } from '@spree/seller-sdk'
+import { useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { useFulfillmentActions } from '../../hooks/use-fulfillments'
+import { printPackingSlip } from '../../lib/packing-slip'
+import { FulfillmentDeliveries } from './fulfillment-deliveries'
+import { FulfillmentDeliveryDialog } from './fulfillment-delivery-dialog'
+import { FulfillmentEditDialog } from './fulfillment-edit-dialog'
+import { FulfillmentFulfillForm } from './fulfillment-fulfill-form'
+import { FulfillmentLabelUploadDialog } from './fulfillment-label-upload-dialog'
+import { FulfillmentSplitDialog } from './fulfillment-split-dialog'
+import { ShippingLabelRow } from './shipping-label-row'
+
+// A parcel that has not gone out is the only one still to ship or cancel.
+// Reading these off "not unfulfilled" once badged a canceled parcel as a
+// success.
+const CAN_SHIP = ['unfulfilled']
+const CAN_CANCEL = ['unfulfilled']
+
+/** Every parcel owed on this order, and what the seller can do with each. */
+export function FulfillmentsCard({ order }: { order: Order }) {
+  const { t } = useTranslation()
+  const fulfillments = order.fulfillments ?? []
+
+  return (
+    <Card variant="container">
+      <CardHeader>
+        <CardTitle>
+          <TruckIcon className="size-4" />
+          {t('orders.fulfillments.title')}
+          {fulfillments.length > 0 && <Badge variant="outline">{fulfillments.length}</Badge>}
+        </CardTitle>
+        <CardAction>
+          {order.fulfillment_status && (
+            <StatusBadge
+              status={order.fulfillment_status}
+              label={t(`orders.fulfillment_statuses.${order.fulfillment_status}`, {
+                defaultValue: order.fulfillment_status,
+              })}
+            />
+          )}
+        </CardAction>
+      </CardHeader>
+
+      {fulfillments.length === 0 ? (
+        <CardContent>
+          <p className="py-8 text-center text-muted-foreground">{t('orders.fulfillments.empty')}</p>
+        </CardContent>
+      ) : (
+        <CardContent className="flex flex-col gap-4">
+          {fulfillments.map((fulfillment) => (
+            <FulfillmentRow key={fulfillment.id} order={order} fulfillment={fulfillment} />
+          ))}
+        </CardContent>
+      )}
+    </Card>
+  )
+}
+
+function FulfillmentRow({ order, fulfillment }: { order: Order; fulfillment: Fulfillment }) {
+  const orderId = order.id
+  const { t } = useTranslation()
+  const confirm = useConfirm()
+  const { cancel } = useFulfillmentActions(orderId)
+
+  const [fulfilling, setFulfilling] = useState(false)
+  const [deliveryOpen, setDeliveryOpen] = useState(false)
+  const [editingDelivery, setEditingDelivery] = useState<Delivery | undefined>()
+  const [labelOpen, setLabelOpen] = useState(false)
+  const [editOpen, setEditOpen] = useState(false)
+  const [splitOpen, setSplitOpen] = useState(false)
+
+  const status = fulfillment.status ?? ''
+  const shippable = CAN_SHIP.includes(status)
+  const cancelable = CAN_CANCEL.includes(status)
+  const splittable = shippable && (fulfillment.fulfillment_items?.length ?? 0) > 0
+  const deliveries = fulfillment.deliveries ?? []
+  // At most one label binds a parcel: the workflows refuse a second while one
+  // is active, and a refunded one stays as history.
+  const activeLabel = (fulfillment.labels ?? []).find((label) => label.status !== 'refunded')
+  // A seller buys postage elsewhere and uploads it, so the slot is offered
+  // only while the parcel has no label and has not gone out.
+  const canUploadLabel = shippable && !activeLabel
+
+  async function handleCancel() {
+    const ok = await confirm({
+      title: t('orders.fulfillments.cancel_title'),
+      message: t('orders.fulfillments.cancel_message'),
+      variant: 'destructive',
+      confirmLabel: t('orders.fulfillments.cancel'),
+    })
+    if (!ok) return
+    cancel.mutate(fulfillment.id)
+  }
+
+  return (
+    <FulfillmentPanel
+      status={status}
+      statusLabel={t(`orders.fulfillment_statuses.${status}`, { defaultValue: status })}
+      location={fulfillment.stock_location_name}
+      actions={
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button variant="ghost" size="icon-xs">
+              <EllipsisVerticalIcon className="size-4" />
+              <span className="sr-only">{t('admin.actions.actions_menu')}</span>
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end">
+            {shippable && (
+              <DropdownMenuItem onClick={() => setEditOpen(true)}>
+                <PencilIcon className="size-4" />
+                {t('admin.actions.edit')}
+              </DropdownMenuItem>
+            )}
+            {splittable && (
+              <DropdownMenuItem onClick={() => setSplitOpen(true)}>
+                <SplitIcon className="size-4" />
+                {t('orders.fulfillments.split')}
+              </DropdownMenuItem>
+            )}
+            <DropdownMenuItem onClick={() => printPackingSlip(order, fulfillment, t)}>
+              <PrinterIcon className="size-4" />
+              {t('orders.fulfillments.print_packing_slip')}
+            </DropdownMenuItem>
+            <DropdownMenuItem
+              onClick={() => {
+                setEditingDelivery(undefined)
+                setDeliveryOpen(true)
+              }}
+            >
+              <TruckIcon className="size-4" />
+              {t('orders.fulfillments.add_delivery')}
+            </DropdownMenuItem>
+            {canUploadLabel && (
+              <DropdownMenuItem onClick={() => setLabelOpen(true)}>
+                <TagIcon className="size-4" />
+                {t('orders.fulfillments.upload_label')}
+              </DropdownMenuItem>
+            )}
+            {cancelable && (
+              <>
+                <DropdownMenuSeparator />
+                <DropdownMenuItem
+                  variant="destructive"
+                  disabled={cancel.isPending}
+                  onClick={handleCancel}
+                >
+                  <XCircleIcon className="size-4" />
+                  {t('orders.fulfillments.cancel')}
+                </DropdownMenuItem>
+              </>
+            )}
+          </DropdownMenuContent>
+        </DropdownMenu>
+      }
+    >
+      {fulfillment.delivery_method_name && (
+        <CardContent className="flex items-center justify-between border-border-subtle border-b py-3 text-sm">
+          <span className="text-muted-foreground">{fulfillment.delivery_method_name}</span>
+        </CardContent>
+      )}
+
+      {activeLabel && !fulfilling && (
+        <ShippingLabelRow orderId={orderId} fulfillmentId={fulfillment.id} label={activeLabel} />
+      )}
+
+      <FulfillmentDeliveries
+        orderId={orderId}
+        fulfillmentId={fulfillment.id}
+        deliveries={deliveries}
+        onEdit={(delivery) => {
+          setEditingDelivery(delivery)
+          setDeliveryOpen(true)
+        }}
+      />
+
+      {fulfilling ? (
+        <FulfillmentFulfillForm
+          order={order}
+          fulfillment={fulfillment}
+          onDone={() => setFulfilling(false)}
+        />
+      ) : (
+        <>
+          <FulfillmentItemList rows={fulfillmentItemRows(fulfillment, order.items ?? [])} />
+
+          {shippable && (
+            <CardFooter className="justify-end gap-2 py-3">
+              <Button type="button" size="sm" onClick={() => setFulfilling(true)}>
+                <TruckIcon data-icon="inline-start" />
+                {t('orders.fulfill')}
+              </Button>
+            </CardFooter>
+          )}
+
+          {!shippable && deliveries.length === 0 && (
+            <CardFooter className="justify-end gap-2 py-3">
+              <Button
+                type="button"
+                size="sm"
+                variant="outline"
+                onClick={() => {
+                  setEditingDelivery(undefined)
+                  setDeliveryOpen(true)
+                }}
+              >
+                <PlusIcon data-icon="inline-start" />
+                {t('orders.fulfillments.add_tracking')}
+              </Button>
+            </CardFooter>
+          )}
+        </>
+      )}
+
+      {/* Mounted only while open, so each form seeds from the parcel as it is
+          now. Left mounted, their defaults froze at first render — and after
+          shipping, an edit would open empty and save that emptiness over a
+          real number. */}
+      {deliveryOpen && (
+        <FulfillmentDeliveryDialog
+          orderId={orderId}
+          fulfillmentId={fulfillment.id}
+          delivery={editingDelivery}
+          open
+          onOpenChange={(next) => {
+            setDeliveryOpen(next)
+            if (!next) setEditingDelivery(undefined)
+          }}
+        />
+      )}
+      {editOpen && (
+        <FulfillmentEditDialog
+          orderId={orderId}
+          fulfillment={fulfillment}
+          open
+          onOpenChange={setEditOpen}
+        />
+      )}
+      {labelOpen && (
+        <FulfillmentLabelUploadDialog
+          orderId={orderId}
+          fulfillmentId={fulfillment.id}
+          currency={order.currency}
+          open
+          onOpenChange={setLabelOpen}
+        />
+      )}
+      {splittable && (
+        <FulfillmentSplitDialog
+          orderId={orderId}
+          fulfillment={fulfillment}
+          open={splitOpen}
+          onOpenChange={setSplitOpen}
+        />
+      )}
+    </FulfillmentPanel>
+  )
+}

package/src/components/orders/line-label.ts

@@ -0,0 +1,28 @@
+/**
+ * How one unit of an order reads wherever it is listed.
+ *
+ * A variant carries a SKU and its option values but never a name — the name
+ * lives on the product — so the label is built from the line's own name with
+ * the options after it, falling back to the SKU and then the raw id.
+ *
+ * One helper because the same unit appears on the parcel, the fulfil form,
+ * the split dialog and all three post-sale cards: built separately they drift,
+ * and the same goods were reading as "Shirt — Blue" in one card and
+ * "Shirt · Blue" in the next.
+ */
+export function lineLabel(
+  name: string | null | undefined,
+  variant: { sku?: string | null; options_text?: string | null } | null | undefined,
+  fallback: string | null | undefined,
+): string {
+  return [name, variant?.options_text].filter(Boolean).join(' · ') || variant?.sku || fallback || ''
+}
+
+/** The same label for a row that carries its own name and options directly. */
+export function unitLabel(item: {
+  name?: string | null
+  options_text?: string | null
+  id: string
+}): string {
+  return lineLabel(item.name, { options_text: item.options_text }, item.id)
+}

package/src/components/orders/order-cancel-dialog.tsx

@@ -0,0 +1,74 @@
+import { zodResolver } from '@hookform/resolvers/zod'
+import {
+  CANCEL_ORDER_DEFAULTS,
+  type CancelOrderFormValues,
+  cancelOrderFormSchema,
+  mapSpreeErrorsToForm,
+} from '@spree/dashboard-core'
+import { ReasonField, OrderCancelDialog as SharedOrderCancelDialog } from '@spree/dashboard-ui'
+import { Controller, useForm } from 'react-hook-form'
+import { useTranslation } from 'react-i18next'
+import { useCancelOrder } from '../../hooks/use-order'
+import { useReasons } from '../../hooks/use-reasons'
+
+/**
+ * Withdrawing from an order this seller cannot fulfil.
+ *
+ * The refund is offered because a seller is merchant of record for their own
+ * child order — the party who owes the buyer their money back is the party
+ * who took it. On a split checkout the workflow settles through this order's
+ * own payment shares, so a seller can never reach a sibling's money.
+ */
+export function OrderCancelDialog({ orderId, onClose }: { orderId: string; onClose: () => void }) {
+  const { t } = useTranslation()
+  const cancel = useCancelOrder(orderId)
+  const { data: reasonsData } = useReasons('order-cancellation-reasons')
+
+  const form = useForm<CancelOrderFormValues>({
+    resolver: zodResolver(cancelOrderFormSchema),
+    defaultValues: CANCEL_ORDER_DEFAULTS,
+  })
+
+  async function onSubmit(values: CancelOrderFormValues) {
+    try {
+      await cancel.mutateAsync({
+        cancel_reason_id: values.cancel_reason_id || undefined,
+        cancel_note: values.cancel_note.trim() || undefined,
+        refund_payments: values.refund_payments,
+        notify_customer: values.notify_customer,
+      })
+      onClose()
+    } catch (err) {
+      if (!mapSpreeErrorsToForm(err, form.setError)) throw err
+    }
+  }
+
+  return (
+    <SharedOrderCancelDialog
+      form={form}
+      showRefund
+      reasonField={
+        /* The reasons are the marketplace's — the operator decides what they
+           are. A marketplace that has not curated them can still be pulled
+           out of, so the empty choice stays rather than forcing one. */
+        <Controller
+          control={form.control}
+          name="cancel_reason_id"
+          render={({ field }) => (
+            <ReasonField
+              id="order-cancellation"
+              reasons={(reasonsData?.data ?? []).filter((reason) => reason.active)}
+              value={field.value}
+              onChange={field.onChange}
+              label={t('admin.orders.detail.cancel.reason_label')}
+              emptyOptionLabel={t('admin.orders.detail.cancel.no_reason')}
+            />
+          )}
+        />
+      }
+      onSubmit={onSubmit}
+      onClose={onClose}
+      pending={cancel.isPending}
+    />
+  )
+}

package/src/components/orders/order-cards.tsx

@@ -0,0 +1,297 @@
+import { AddressFormDialog, formatStoreDateTime } from '@spree/dashboard-core'
+import {
+  AddressBlock,
+  Button,
+  Card,
+  CardAction,
+  CardHeader,
+  CardTitle,
+  cn,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+  Separator,
+} from '@spree/dashboard-ui'
+import { EllipsisVerticalIcon, PencilIcon } from '@spree/dashboard-ui/icons'
+import type { Order, OrderAddressParams } from '@spree/seller-sdk'
+import { type ReactNode, useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { sellerClient } from '../../api-client'
+import { useOrderMutation } from '../../hooks/use-order'
+import { useStoreTimezone } from '../../hooks/use-store-timezone'
+
+function SummaryRow({
+  label,
+  value,
+  bold,
+  danger,
+  highlight,
+}: {
+  label: string
+  value: ReactNode
+  bold?: boolean
+  danger?: boolean
+  highlight?: boolean
+}) {
+  return (
+    <div
+      className={cn('flex items-center justify-between px-5 py-2.5', highlight && 'bg-accent/50')}
+    >
+      <span className="text-sm">{label}</span>
+      <span
+        className={cn('text-sm tabular-nums', bold && 'font-bold', danger && 'text-destructive')}
+      >
+        {value}
+      </span>
+    </div>
+  )
+}
+
+// The marketplace's zone, not the browser's: a seller trading away from the
+// marketplace would otherwise see an order fall on the wrong day.
+function formatDate(iso: string | null | undefined, timezone: string) {
+  if (!iso) return '—'
+
+  return formatStoreDateTime(iso, timezone)
+}
+
+/**
+ * What the sale came to, and what has been paid against it.
+ *
+ * The same rows the operator sees on their own order page, so a seller
+ * reconciling a payout is reading the same arithmetic — a row appears only
+ * when it carries a figure, which is why a simple order shows three lines and
+ * a discounted, taxed, shipped one shows eight.
+ *
+ * The items themselves are listed on the parcels above rather than repeated
+ * here: what a seller needs from a line is which parcel it travels in.
+ */
+export function OrderSummaryCard({ order }: { order: Order }) {
+  const { t } = useTranslation()
+  const timezone = useStoreTimezone()
+
+  const amount = (value: string | null | undefined) => Number.parseFloat(value ?? '0')
+  const outstanding = amount(order.amount_due)
+  const placed = Boolean(order.completed_at)
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>{t('orders.summary.title')}</CardTitle>
+      </CardHeader>
+
+      <div className="py-1">
+        <SummaryRow
+          label={t('orders.summary.created_at')}
+          value={formatDate(order.created_at, timezone)}
+        />
+        {order.completed_at && (
+          <SummaryRow
+            label={t('orders.summary.completed_at')}
+            value={formatDate(order.completed_at, timezone)}
+          />
+        )}
+
+        {order.canceled_at && (
+          <>
+            <Separator />
+            <SummaryRow
+              label={t('orders.summary.canceled_at')}
+              value={formatDate(order.canceled_at, timezone)}
+            />
+            {order.cancel_reason_name && (
+              <SummaryRow
+                label={t('orders.summary.cancel_reason')}
+                value={order.cancel_reason_name}
+              />
+            )}
+            {order.cancel_note && (
+              <SummaryRow label={t('orders.summary.cancel_note')} value={order.cancel_note} />
+            )}
+          </>
+        )}
+
+        <Separator />
+
+        <SummaryRow label={t('orders.summary.currency')} value={order.currency} />
+
+        <Separator />
+
+        <SummaryRow label={t('orders.summary.subtotal')} value={order.display_item_total} />
+
+        {amount(order.delivery_total) > 0 && (
+          <SummaryRow label={t('orders.summary.shipping')} value={order.display_delivery_total} />
+        )}
+
+        {amount(order.discount_total) !== 0 && (
+          <SummaryRow label={t('orders.summary.promotions')} value={order.display_discount_total} />
+        )}
+
+        {amount(order.adjustment_total) !== 0 && (
+          <SummaryRow
+            label={t('orders.summary.adjustments')}
+            value={order.display_adjustment_total}
+          />
+        )}
+
+        {amount(order.included_tax_total) > 0 && (
+          <SummaryRow
+            label={t('orders.summary.tax_included')}
+            value={order.display_included_tax_total}
+          />
+        )}
+
+        {/* Shown on a placed order even at zero, so "no tax was charged" reads
+            as an answer rather than a missing row. */}
+        {(amount(order.additional_tax_total) > 0 ||
+          (placed && amount(order.included_tax_total) === 0)) && (
+          <SummaryRow
+            label={t('orders.summary.tax_additional')}
+            value={order.display_additional_tax_total}
+          />
+        )}
+
+        <Separator />
+
+        <SummaryRow label={t('orders.summary.total')} value={order.display_total} bold />
+
+        {/* What the marketplace charged the seller on this sale. Below the
+            order total because it is not part of what the buyer paid — it is
+            billed to the seller separately.
+
+            Always qualified as a marketplace fee, never a bare "fee":
+            Spree::Fee is a buyer-facing charge (handling, gift wrap, COD)
+            that does roll into the order total, and a bare "total fee" beside
+            an order would reasonably be taken for that.
+
+            The tax is its own row because the seller reclaims it as input
+            tax, and that has to be attributable to the sale that produced
+            it.
+
+            Shown on every placed order, including one whose fee came to
+            zero: a zero-rated or exempt rate is an answer the seller needs,
+            and every order here is a seller's by definition. */}
+        {placed && (
+          <>
+            <Separator />
+
+            <SummaryRow
+              label={t('orders.summary.commission_fee')}
+              value={order.display_commission_amount_total}
+            />
+
+            {amount(order.commission_tax_total) > 0 && (
+              <SummaryRow
+                label={t('orders.summary.commission_tax')}
+                value={order.display_commission_tax_total}
+              />
+            )}
+
+            <SummaryRow
+              label={t('orders.summary.commission_total')}
+              value={order.display_commission_total}
+              bold
+            />
+          </>
+        )}
+
+        <Separator />
+
+        <SummaryRow
+          label={t('orders.summary.payment_total')}
+          value={order.display_payment_total}
+          highlight
+        />
+        <SummaryRow
+          label={t('orders.summary.outstanding_balance')}
+          value={order.display_amount_due}
+          highlight
+          danger={outstanding > 0}
+        />
+      </div>
+    </Card>
+  )
+}
+
+/**
+ * Where the parcel goes and who the invoice is for, and correcting either.
+ *
+ * The seller is merchant of record for their own child order, so a delivery
+ * address the buyer got wrong is theirs to fix and the invoice address is
+ * what they bill against.
+ *
+ * No email address: a seller reaching the customer about a delivery has the
+ * phone on the shipping address, and an email is the one contact detail that
+ * would let a marketplace's customer be taken off it.
+ */
+export function OrderCustomerCard({ order }: { order: Order }) {
+  const { t } = useTranslation()
+  const [editing, setEditing] = useState<'shipping_address' | 'billing_address' | null>(null)
+
+  const save = useOrderMutation(order.id, (params: { type: string; address: OrderAddressParams }) =>
+    sellerClient().orders.address(order.id, { [params.type]: params.address }),
+  )
+
+  const editable = !order.canceled_at
+
+  return (
+    <>
+      <Card>
+        <CardHeader>
+          <CardTitle>{t('orders.customer.title')}</CardTitle>
+          {editable && (
+            <CardAction>
+              <DropdownMenu>
+                <DropdownMenuTrigger
+                  render={
+                    <Button variant="ghost" size="icon-xs" aria-label={t('common.actions')}>
+                      <EllipsisVerticalIcon className="size-4" />
+                    </Button>
+                  }
+                />
+                <DropdownMenuContent align="end">
+                  <DropdownMenuItem onClick={() => setEditing('shipping_address')}>
+                    <PencilIcon className="size-4" />
+                    {t('orders.address_edit.shipping_title')}
+                  </DropdownMenuItem>
+                  <DropdownMenuItem onClick={() => setEditing('billing_address')}>
+                    <PencilIcon className="size-4" />
+                    {t('orders.address_edit.billing_title')}
+                  </DropdownMenuItem>
+                </DropdownMenuContent>
+              </DropdownMenu>
+            </CardAction>
+          )}
+        </CardHeader>
+        <div className="flex flex-col gap-4 px-6 pb-6">
+          <AddressBlock title={t('orders.shipping_address')} address={order.shipping_address} />
+          <AddressBlock title={t('orders.billing_address')} address={order.billing_address} />
+        </div>
+      </Card>
+
+      {/* Mounted only while open, so the form seeds from the address as it is
+          now rather than freezing at first render. */}
+      {editing && (
+        <AddressFormDialog
+          title={
+            editing === 'shipping_address'
+              ? t('orders.address_edit.shipping_title')
+              : t('orders.address_edit.billing_title')
+          }
+          address={editing === 'shipping_address' ? order.shipping_address : order.billing_address}
+          open
+          onOpenChange={(open) => !open && setEditing(null)}
+          onSave={(address) =>
+            save.mutate(
+              { type: editing, address },
+              // Kept open on failure so the entered address is not lost.
+              { onSuccess: () => setEditing(null) },
+            )
+          }
+          isPending={save.isPending}
+        />
+      )}
+    </>
+  )
+}