@spree/dashboard-ui 0.13.0 → 1.0.0-beta.1

package/src/spree/fulfill-items-form.tsx

@@ -0,0 +1,282 @@
+import type { UseFormReturn } from 'react-hook-form'
+import { Controller } from 'react-hook-form'
+import { useTranslation } from 'react-i18next'
+import { cn } from '../lib/utils'
+import { Alert, AlertDescription } from '../ui/alert'
+import { Button } from '../ui/button'
+import { Checkbox } from '../ui/checkbox'
+import { Field, FieldLabel } from '../ui/field'
+import { Input } from '../ui/input'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../ui/select'
+import { Thumbnail } from '../ui/thumbnail'
+import { PackageIcon, TriangleAlertIcon } from './icons'
+
+/** A pickable row: what it looks like and how many units are on offer. */
+export type FulfillableRowData = {
+  key: string
+  itemId: string
+  name: string
+  optionsText?: string | null
+  thumbnailUrl?: string | null
+  quantity: number
+}
+
+/** The form shape both panels bind — see the shared fulfillment schema. */
+export type FulfillItemsValues = {
+  items: Array<{ item_id: string; selected: boolean; quantity: number }>
+  tracking: string
+  tracking_carrier: string
+  notify_customer: boolean
+}
+
+function ItemQuantityRow({
+  row,
+  index,
+  selected,
+  idPrefix,
+  form,
+}: {
+  row: FulfillableRowData
+  index: number
+  selected: boolean
+  /** Scopes the field ids, since an order can show several of these forms. */
+  idPrefix: string
+  form: UseFormReturn<FulfillItemsValues>
+}) {
+  const { t } = useTranslation()
+  const checkboxId = `${idPrefix}-item-${index}`
+
+  return (
+    <div
+      className={cn(
+        'my-2 flex items-center gap-3 rounded-lg py-2 pl-2',
+        selected && 'bg-accent-strong',
+      )}
+    >
+      <Controller
+        control={form.control}
+        name={`items.${index}.selected`}
+        render={({ field }) => (
+          <Checkbox
+            id={checkboxId}
+            checked={field.value}
+            aria-label={t('admin.orders.fulfill.include_item', { name: row.name })}
+            onCheckedChange={(checked) => {
+              const include = checked === true
+              field.onChange(include)
+              // Re-checking restores the full held quantity, so the merchant
+              // never has to retype what they just excluded.
+              form.setValue(`items.${index}.quantity`, include ? row.quantity : 0, {
+                shouldDirty: true,
+              })
+            }}
+          />
+        )}
+      />
+
+      <Thumbnail src={row.thumbnailUrl} fallback={<PackageIcon />} />
+
+      <div className="min-w-0 flex-1">
+        <div className="truncate font-medium text-sm">{row.name}</div>
+        {row.optionsText && (
+          <div className="truncate text-muted-foreground text-xs">{row.optionsText}</div>
+        )}
+      </div>
+
+      <Controller
+        control={form.control}
+        name={`items.${index}.quantity`}
+        render={({ field }) => (
+          <div className="flex shrink-0 items-center gap-2">
+            <Input
+              type="number"
+              min={0}
+              max={row.quantity}
+              className="w-20 text-right"
+              disabled={!selected}
+              aria-label={t('admin.orders.fulfill.quantity_for', { name: row.name })}
+              value={field.value}
+              onChange={(event) => {
+                const parsed = Number(event.target.value)
+                const quantity = Number.isFinite(parsed)
+                  ? Math.max(0, Math.min(parsed, row.quantity))
+                  : 0
+                field.onChange(quantity)
+                // Typing the quantity down to zero is the same statement as
+                // unticking the row, so keep the two in step.
+                form.setValue(`items.${index}.selected`, quantity > 0, { shouldDirty: true })
+              }}
+              onBlur={field.onBlur}
+            />
+            <span className="w-16 whitespace-nowrap text-muted-foreground text-sm">
+              {t('admin.orders.fulfill.of_units', { count: row.quantity })}
+            </span>
+          </div>
+        )}
+      />
+    </div>
+  )
+}
+
+/**
+ * Picks what to ship out of one fulfillment, in place of the card's normal
+ * contents. Shipping everything is the default; lowering a quantity or
+ * unticking an item splits the chosen units into a new fulfillment that ships,
+ * leaving the rest of this one open.
+ *
+ * Shared by the operator's order page and the seller's. Headless: the caller
+ * owns the form instance and the submit, so each panel keeps its own mutation
+ * and its own idea of who may ship — this holds the shape and the
+ * select/quantity coupling so the two cannot drift.
+ */
+export function FulfillItemsForm({
+  form,
+  rows,
+  idPrefix,
+  carrierOptions,
+  onSubmit,
+  onCancel,
+  canShipWholeParcel = false,
+  pending = false,
+}: {
+  form: UseFormReturn<FulfillItemsValues>
+  rows: FulfillableRowData[]
+  idPrefix: string
+  /** Carriers to choose between; the first is normally "detect from number". */
+  carrierOptions: Array<{ value: string; label: string }>
+  onSubmit: (values: FulfillItemsValues) => void | Promise<void>
+  onCancel: () => void
+  /**
+   * Whether the parcel can ship with nothing picked.
+   *
+   * True when it holds items that no row can address — the workflow reads an
+   * empty selection as "everything", so blocking submit would leave such a
+   * parcel unshippable. Never inferred from `rows` being empty here: that
+   * cannot tell an unaddressable parcel from an empty one, and an empty
+   * fulfillment must stay unsubmittable.
+   */
+  canShipWholeParcel?: boolean
+  pending?: boolean
+}) {
+  const { t } = useTranslation()
+  const { errors } = form.formState
+
+  const watched = form.watch('items')
+  const totalSelected = watched.reduce(
+    (sum, item) => sum + (item.selected ? item.quantity || 0 : 0),
+    0,
+  )
+  const totalAvailable = rows.reduce((sum, row) => sum + row.quantity, 0)
+  const shipsEverything = totalSelected === totalAvailable
+
+  return (
+    <form onSubmit={form.handleSubmit(onSubmit)} className="flex flex-col">
+      {errors.root?.message && (
+        <p className="text-destructive text-sm" role="alert">
+          {errors.root.message}
+        </p>
+      )}
+
+      {rows.length === 0 ? (
+        <p className="py-6 text-center text-muted-foreground">{t('admin.orders.fulfill.empty')}</p>
+      ) : (
+        <div className="divide-y">
+          {rows.map((row, index) => (
+            <ItemQuantityRow
+              key={row.key}
+              row={row}
+              index={index}
+              selected={watched[index]?.selected ?? true}
+              idPrefix={idPrefix}
+              form={form}
+            />
+          ))}
+        </div>
+      )}
+
+      <div className="grid grid-cols-1 gap-4 border-border-subtle border-t py-3 sm:grid-cols-2">
+        <Field>
+          <FieldLabel htmlFor={`${idPrefix}-tracking`}>
+            {t('admin.orders.fulfill.tracking_label')}
+          </FieldLabel>
+          <Input
+            id={`${idPrefix}-tracking`}
+            placeholder={t('admin.orders.fulfill.tracking_placeholder')}
+            {...form.register('tracking')}
+          />
+        </Field>
+
+        <Field>
+          <FieldLabel htmlFor={`${idPrefix}-tracking-carrier`}>
+            {t('admin.orders.detail.fulfillments.carrier_label')}
+          </FieldLabel>
+          <Controller
+            control={form.control}
+            name="tracking_carrier"
+            render={({ field }) => (
+              <Select
+                items={carrierOptions}
+                value={field.value}
+                onValueChange={(value) => field.onChange(value ?? '')}
+              >
+                <SelectTrigger id={`${idPrefix}-tracking-carrier`}>
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  {carrierOptions.map((option) => (
+                    <SelectItem key={option.value} value={option.value}>
+                      {option.label}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            )}
+          />
+        </Field>
+      </div>
+
+      <Controller
+        control={form.control}
+        name="notify_customer"
+        render={({ field }) => (
+          <label
+            htmlFor={`${idPrefix}-notify`}
+            className="flex cursor-pointer items-center gap-2 py-3 text-sm"
+          >
+            <Checkbox
+              id={`${idPrefix}-notify`}
+              checked={field.value}
+              onCheckedChange={(checked) => field.onChange(checked === true)}
+            />
+            {t('admin.orders.fulfill.notify_customer')}
+          </label>
+        )}
+      />
+
+      {!shipsEverything && totalSelected > 0 && (
+        <div className="px-3 pb-3">
+          <Alert variant="warning">
+            <TriangleAlertIcon />
+            <AlertDescription>{t('admin.orders.fulfill.partial_hint')}</AlertDescription>
+          </Alert>
+        </div>
+      )}
+
+      <div className="flex items-center justify-end gap-2 border-border-subtle border-t py-3">
+        <span className="mr-auto text-muted-foreground text-sm">
+          {t('admin.orders.fulfill.units_selected')}: {totalSelected} / {totalAvailable}
+        </span>
+        <Button type="button" size="sm" variant="outline" onClick={onCancel}>
+          {t('admin.actions.cancel')}
+        </Button>
+        <Button
+          type="submit"
+          size="sm"
+          disabled={(totalSelected === 0 && !canShipWholeParcel) || pending}
+        >
+          {pending ? t('admin.actions.saving') : t('admin.orders.fulfill.submit')}
+        </Button>
+      </div>
+    </form>
+  )
+}

package/src/spree/fulfillment-edit-dialog.tsx

@@ -0,0 +1,211 @@
+import { useEffect, useRef, useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { Button } from '../ui/button'
+import {
+  Dialog,
+  DialogBody,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '../ui/dialog'
+import { Field, FieldError, FieldLabel } from '../ui/field'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../ui/select'
+
+/** A shelf a parcel can ship from, already labelled by the caller. */
+export type FulfillmentOriginOption = {
+  value: string
+  label: string
+}
+
+/** A priced service the parcel can be carried by, already labelled. */
+export type FulfillmentRateOption = {
+  value: string
+  label: string
+}
+
+export type FulfillmentEditValues = {
+  stockLocationId: string
+  selectedDeliveryRateId: string
+}
+
+/**
+ * Where a parcel ships from and which priced service carries it.
+ *
+ * The two fields are coupled: rates are quoted against an origin, so moving
+ * the parcel invalidates the list on screen. Rather than offering stale
+ * options, a save that changes the origin writes the location first and the
+ * method field stands down until the caller re-quotes — which is why
+ * `onSubmit` reports *which* fields changed and the caller decides the order
+ * of writes.
+ *
+ * Headless: both panels label their own options (the operator marks shelves
+ * that cannot cover the parcel; a seller sees only their own), and both own
+ * their mutations. This holds the shape and the coupling rule so the two
+ * cannot drift.
+ */
+export function FulfillmentEditDialog({
+  open,
+  onOpenChange,
+  originOptions,
+  rateOptions,
+  currentOriginId,
+  currentRateId,
+  onSubmit,
+  pending = false,
+  errorMessage,
+}: {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  originOptions: FulfillmentOriginOption[]
+  rateOptions: FulfillmentRateOption[]
+  currentOriginId: string
+  currentRateId: string
+  /**
+   * Applies the change. Returning `'requote'` keeps the dialog open and
+   * re-seeds it from the caller's refreshed record — the origin moved, so the
+   * rates on screen described a route the parcel has left.
+   */
+  onSubmit: (
+    values: FulfillmentEditValues,
+    changed: { origin: boolean; rate: boolean },
+  ) => Promise<'requote' | 'done'>
+  pending?: boolean
+  errorMessage?: string
+}) {
+  const { t } = useTranslation()
+
+  const [originId, setOriginId] = useState(currentOriginId)
+  const [rateId, setRateId] = useState(currentRateId)
+
+  // A re-quote lands as a changed record: the caller has moved the parcel and
+  // the server has re-selected a method for the new origin. Adopt that pick,
+  // so the second save confirms a rate that actually applies rather than
+  // re-sending the one quoted for the origin the parcel just left.
+  const seededOrigin = useRef(currentOriginId)
+  useEffect(() => {
+    if (seededOrigin.current === currentOriginId) return
+    seededOrigin.current = currentOriginId
+    setOriginId(currentOriginId)
+    setRateId(currentRateId)
+  }, [currentOriginId, currentRateId])
+
+  // The rates on the record were quoted for the origin it currently has. Once
+  // a different one is picked they describe a route no longer on offer, so the
+  // method field stands down until the server re-quotes.
+  const originMoved = originId !== currentOriginId
+  const originMissing = originId.length === 0
+
+  async function handleSubmit(event: React.FormEvent) {
+    // The order page renders its cards inside their own forms — without
+    // stopping the bubble the browser submits the outer one.
+    event.preventDefault()
+    event.stopPropagation()
+    if (originMissing) return
+
+    const outcome = await onSubmit(
+      { stockLocationId: originId, selectedDeliveryRateId: rateId },
+      { origin: originMoved, rate: rateId !== currentRateId },
+    )
+
+    if (outcome === 'done') onOpenChange(false)
+  }
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent>
+        <form onSubmit={handleSubmit}>
+          <DialogHeader>
+            <DialogTitle>{t('admin.orders.detail.fulfillments.edit_title')}</DialogTitle>
+            <DialogDescription>
+              {t('admin.orders.detail.fulfillments.edit_description')}
+            </DialogDescription>
+          </DialogHeader>
+
+          <DialogBody className="flex flex-col gap-4">
+            {errorMessage && (
+              <p className="text-sm text-destructive" role="alert">
+                {errorMessage}
+              </p>
+            )}
+
+            <Field>
+              <FieldLabel htmlFor="fulfillment-location">
+                {t('admin.orders.detail.fulfillments.ships_from')}
+              </FieldLabel>
+              <Select
+                items={originOptions}
+                value={originId}
+                onValueChange={(value) => setOriginId((value as string) ?? '')}
+              >
+                <SelectTrigger id="fulfillment-location">
+                  <SelectValue placeholder={t('admin.common.select_placeholder')} />
+                </SelectTrigger>
+                <SelectContent>
+                  {originOptions.map((option) => (
+                    <SelectItem key={option.value} value={option.value}>
+                      {option.label}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+              {originMissing && <FieldError>{t('admin.errors.required')}</FieldError>}
+            </Field>
+
+            <Field>
+              <FieldLabel htmlFor="fulfillment-rate">
+                {t('admin.orders.detail.fulfillments.delivery_method')}
+              </FieldLabel>
+              <Select
+                items={rateOptions}
+                value={rateId}
+                disabled={originMoved || rateOptions.length === 0}
+                onValueChange={(value) => setRateId((value as string) ?? '')}
+              >
+                <SelectTrigger id="fulfillment-rate">
+                  <SelectValue placeholder={t('admin.common.select_placeholder')} />
+                </SelectTrigger>
+                <SelectContent>
+                  {rateOptions.map((option) => (
+                    <SelectItem key={option.value} value={option.value}>
+                      {option.label}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+              {originMoved && (
+                <span className="text-muted-foreground text-xs">
+                  {t('admin.orders.detail.fulfillments.rates_pending_origin')}
+                </span>
+              )}
+              {!originMoved && rateOptions.length === 0 && (
+                <span className="text-muted-foreground text-xs">
+                  {t('admin.orders.detail.fulfillments.no_rates')}
+                </span>
+              )}
+            </Field>
+          </DialogBody>
+
+          <DialogFooter>
+            <Button
+              type="button"
+              variant="outline"
+              onClick={() => onOpenChange(false)}
+              disabled={pending}
+            >
+              {t('admin.actions.cancel')}
+            </Button>
+            <Button type="submit" disabled={pending || originMissing}>
+              {pending
+                ? t('admin.actions.saving')
+                : originMoved
+                  ? t('admin.orders.detail.fulfillments.move_and_requote')
+                  : t('admin.actions.save')}
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  )
+}

package/src/spree/fulfillment-item-list.tsx

@@ -0,0 +1,61 @@
+import { Thumbnail } from '../ui/thumbnail'
+import { PackageIcon } from './icons'
+
+/**
+ * One row of a fulfillment's item list, already joined to its line item by
+ * the caller. The image and the price are optional: a surface that does not
+ * expose them renders the name and the count alone.
+ */
+export type FulfillmentItemRowData = {
+  key: string
+  name: string
+  optionsText?: string | null
+  thumbnailUrl?: string | null
+  displayPrice?: string | null
+  quantity: number
+}
+
+/**
+ * What a fulfillment holds: what it looks like, what it costs and how many
+ * units travel together.
+ *
+ * Read-only — changing what an order contains after placement belongs to the
+ * order edit screen, not here. Shared by the operator's order page and the
+ * seller's so a parcel's contents read the same on both.
+ */
+function ItemRow({ row }: { row: FulfillmentItemRowData }) {
+  return (
+    <div className="flex items-center gap-3 p-3">
+      <Thumbnail src={row.thumbnailUrl} fallback={<PackageIcon />} />
+
+      <div className="min-w-0 flex-1">
+        <div className="truncate text-sm font-medium">{row.name}</div>
+        {row.optionsText && (
+          <div className="truncate text-xs text-muted-foreground">{row.optionsText}</div>
+        )}
+      </div>
+
+      <div className="shrink-0 whitespace-nowrap text-right text-muted-foreground text-sm">
+        {row.displayPrice ? (
+          <span>
+            {row.displayPrice} × {row.quantity}
+          </span>
+        ) : (
+          <span>× {row.quantity}</span>
+        )}
+      </div>
+    </div>
+  )
+}
+
+export function FulfillmentItemList({ rows }: { rows: FulfillmentItemRowData[] }) {
+  if (rows.length === 0) return null
+
+  return (
+    <div className="divide-y">
+      {rows.map((row) => (
+        <ItemRow key={row.key} row={row} />
+      ))}
+    </div>
+  )
+}

package/src/spree/fulfillment-panel.tsx

@@ -0,0 +1,53 @@
+import type { ReactNode } from 'react'
+import { StatusBadge } from '../ui/badge'
+import { Card, CardAction, CardHeader, CardTitle } from '../ui/card'
+import { MapPinIcon } from './icons'
+
+/**
+ * The nested card one parcel occupies on an order page: what state it is in,
+ * where it ships from, and its own menu.
+ *
+ * Shared by the operator's order page and the seller's, so a parcel reads the
+ * same on both sides of a marketplace. Headless — the status label and every
+ * action come from the caller.
+ */
+export function FulfillmentPanel({
+  status,
+  statusLabel,
+  location,
+  meta,
+  actions,
+  children,
+}: {
+  status: string
+  /** Omit to let the badge humanize the status itself. */
+  statusLabel?: string
+  /** Where it ships from. Absent until a fulfillment exists. */
+  location?: string | null
+  /** Trailing header detail, e.g. when it shipped. */
+  meta?: ReactNode
+  /** The panel's own menu. Absent when there is nothing to act on. */
+  actions?: ReactNode
+  children: ReactNode
+}) {
+  return (
+    <Card variant="nested">
+      <CardHeader>
+        <CardTitle className="min-w-0 font-normal text-sm">
+          <StatusBadge status={status} label={statusLabel} />
+          {location && (
+            <div className="flex min-w-0 items-center gap-1.5 text-muted-foreground text-xs">
+              <MapPinIcon className="size-3 shrink-0" />
+              {/* The card clips its overflow, so a long warehouse name has to
+                  truncate here or it is simply cut off. */}
+              <span className="truncate">{location}</span>
+            </div>
+          )}
+          {meta}
+        </CardTitle>
+        {actions && <CardAction>{actions}</CardAction>}
+      </CardHeader>
+      {children}
+    </Card>
+  )
+}