@spree/seller-dashboard 1.0.0-beta.1

package/src/components/read-row.tsx

@@ -0,0 +1,16 @@
+import type { ReactNode } from 'react'
+import { useTranslation } from 'react-i18next'
+
+/** One labelled value in a read-only card, with a placeholder when unset. */
+export function ReadRow({ label, children }: { label: string; children: ReactNode }) {
+  const { t } = useTranslation()
+
+  return (
+    <div className="flex items-start justify-between gap-3 text-sm">
+      <span className="text-muted-foreground">{label}</span>
+      <span className="text-right">
+        {children ?? <span className="text-muted-foreground">{t('profile.not_provided')}</span>}
+      </span>
+    </div>
+  )
+}

package/src/components/retryable-error.tsx

@@ -0,0 +1,23 @@
+import { Button } from '@spree/dashboard-ui'
+import { useTranslation } from 'react-i18next'
+import { CenteredMessage } from './centered-message'
+
+/**
+ * Shown when a page's own query failed, in place of its content.
+ *
+ * Distinct from a "not found" message on purpose: a failed request and a
+ * missing record send the seller looking for different causes, and only one
+ * of the two is worth retrying.
+ */
+export function RetryableError({ onRetry }: { onRetry: () => void }) {
+  const { t } = useTranslation()
+
+  return (
+    <CenteredMessage>
+      {t('common.error')}{' '}
+      <Button variant="outline" onClick={onRetry}>
+        {t('common.retry')}
+      </Button>
+    </CenteredMessage>
+  )
+}

package/src/components/seller-address-card.tsx

@@ -0,0 +1,123 @@
+import { AddressFormDialog } from '@spree/dashboard-core'
+import {
+  AddressBlock,
+  Badge,
+  Button,
+  Card,
+  CardAction,
+  CardContent,
+  CardHeader,
+  CardTitle,
+  StatusBadge,
+  toastManager,
+} from '@spree/dashboard-ui'
+import { PencilIcon, PlusIcon } from '@spree/dashboard-ui/icons'
+import type { Profile, SellerAddressParams } from '@spree/seller-sdk'
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+import { useParams } from '@tanstack/react-router'
+import { useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { sellerClient } from '../api-client'
+
+/**
+ * Where the seller is invoiced — read as a block, edited in the shared
+ * address dialog.
+ *
+ * Used both on the profile page and inline in the onboarding checklist, so a
+ * seller working through setup fills the address where they are told about
+ * it rather than being sent somewhere else and losing their place. Same
+ * component either way, so the two can never diverge.
+ *
+ * Returns are not here: they go to a stock location, which is a record of its
+ * own — see `SellerReturnsLocationCard`.
+ */
+export function SellerAddressCard({
+  profile,
+  headless = false,
+}: {
+  profile: Profile
+  /** Render just the body — the onboarding checklist supplies its own frame. */
+  headless?: boolean
+}) {
+  const { t } = useTranslation()
+  const { sellerId } = useParams({ from: '/_authenticated/$sellerId' })
+  const queryClient = useQueryClient()
+  const [editing, setEditing] = useState(false)
+
+  const address = profile.billing_address
+  const title = t('profile.billing_address')
+
+  const save = useMutation({
+    // Only the billing address is sent: the rest of the profile is untouched,
+    // and posting it all would rewrite fields the seller never opened.
+    mutationFn: (values: SellerAddressParams) =>
+      sellerClient().profile.update({ billing_address: values }),
+    onSuccess: (updated) => {
+      queryClient.setQueryData(['seller', sellerId, 'profile'], updated)
+      // The checklist reads addresses too, so it has to re-evaluate.
+      void queryClient.invalidateQueries({ queryKey: ['seller', sellerId, 'onboarding'] })
+      setEditing(false)
+      toastManager.add({ type: 'success', title: t('profile.saved') })
+    },
+    onError: (err) =>
+      toastManager.add({
+        type: 'error',
+        title: err instanceof Error ? err.message : t('common.error'),
+      }),
+  })
+
+  const body = address ? (
+    <AddressBlock address={address} />
+  ) : (
+    <p className="text-muted-foreground text-sm">{t('profile.address_not_provided')}</p>
+  )
+
+  const editButton = (
+    <Button variant={address ? 'outline' : 'default'} size="sm" onClick={() => setEditing(true)}>
+      {address ? <PencilIcon className="size-4" /> : <PlusIcon className="size-4" />}
+      {address ? t('profile.edit') : t('profile.add_address')}
+    </Button>
+  )
+
+  const dialog = editing && (
+    <AddressFormDialog
+      title={title}
+      address={address}
+      open
+      business
+      onOpenChange={setEditing}
+      onSave={(values) => save.mutate(values)}
+      isPending={save.isPending}
+    />
+  )
+
+  if (headless) {
+    return (
+      <div className="flex flex-col items-start gap-3">
+        {body}
+        {editButton}
+        {dialog}
+      </div>
+    )
+  }
+
+  return (
+    <>
+      <Card>
+        <CardHeader>
+          <CardTitle>
+            {title}
+            {address ? (
+              <StatusBadge status="complete" label={t('profile.address_filled')} />
+            ) : (
+              <Badge variant="outline">{t('profile.address_missing')}</Badge>
+            )}
+          </CardTitle>
+          <CardAction>{editButton}</CardAction>
+        </CardHeader>
+        <CardContent>{body}</CardContent>
+      </Card>
+      {dialog}
+    </>
+  )
+}

package/src/components/seller-business-card.tsx

@@ -0,0 +1,152 @@
+import {
+  Button,
+  Card,
+  CardAction,
+  CardContent,
+  CardHeader,
+  CardTitle,
+  Field,
+  FieldLabel,
+  Input,
+  Sheet,
+  SheetContent,
+  SheetFooter,
+  SheetHeader,
+  SheetTitle,
+  toastManager,
+} from '@spree/dashboard-ui'
+import { PencilIcon } from '@spree/dashboard-ui/icons'
+import type { Profile } from '@spree/seller-sdk'
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+import { useParams } from '@tanstack/react-router'
+import { useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { sellerClient } from '../api-client'
+
+function errorMessage(error: unknown, fallback: string) {
+  return error instanceof Error && error.message ? error.message : fallback
+}
+
+/**
+ * The business behind the seller, as the marketplace's commission invoice must
+ * address it: the legal name and registration number.
+ *
+ * The tax registrations sit in their own card beside this one, on the same
+ * panel a company's are managed from — a business trading in several regimes
+ * holds a registration in each, so they are a collection rather than a field.
+ *
+ * Separate from the billing address, which is only where post goes.
+ */
+export function SellerBusinessCard({ profile }: { profile: Profile }) {
+  const { t } = useTranslation()
+  const { sellerId } = useParams({ from: '/_authenticated/$sellerId' })
+  const queryClient = useQueryClient()
+  const [editing, setEditing] = useState(false)
+
+  const [legalName, setLegalName] = useState(profile.legal_name ?? '')
+  const [registrationNumber, setRegistrationNumber] = useState(profile.registration_number ?? '')
+  // Shown in the sheet rather than as a toast: the toast stack deliberately
+  // sits below the sheet overlay, so a rejection raised here would be hidden
+  // behind the very form that caused it.
+  const [formError, setFormError] = useState<string | null>(null)
+
+  // Opening the sheet is the seller starting over, so it shows what is on file
+  // rather than whatever they last typed — the card never remounts, so an
+  // abandoned edit would otherwise outlive the sheet that made it.
+  function setSheetOpen(open: boolean) {
+    if (open) {
+      setLegalName(profile.legal_name ?? '')
+      setRegistrationNumber(profile.registration_number ?? '')
+      setFormError(null)
+    }
+    setEditing(open)
+  }
+
+  const save = useMutation({
+    mutationFn: () => {
+      setFormError(null)
+      return sellerClient().profile.update({
+        legal_name: legalName || null,
+        registration_number: registrationNumber || null,
+      })
+    },
+    onSuccess: (updated) => {
+      queryClient.setQueryData(['seller', sellerId, 'profile'], updated)
+      // A checklist kind may read these, so it has to re-evaluate.
+      void queryClient.invalidateQueries({ queryKey: ['seller', sellerId, 'onboarding'] })
+      setEditing(false)
+      toastManager.add({ type: 'success', title: t('profile.saved') })
+    },
+    onError: (err) => setFormError(errorMessage(err, t('common.error'))),
+  })
+
+  const rows = [
+    { label: t('profile.legal_name'), value: profile.legal_name },
+    { label: t('profile.registration_number'), value: profile.registration_number },
+  ]
+
+  return (
+    <>
+      <Card>
+        <CardHeader>
+          <CardTitle>{t('profile.business_details')}</CardTitle>
+          <CardAction>
+            <Button variant="outline" size="sm" onClick={() => setSheetOpen(true)}>
+              <PencilIcon className="size-4" />
+              {t('profile.edit')}
+            </Button>
+          </CardAction>
+        </CardHeader>
+        <CardContent className="flex flex-col gap-2 text-sm">
+          {rows.map((row) => (
+            <div key={row.label} className="flex justify-between gap-4">
+              <span className="text-muted-foreground">{row.label}</span>
+              <span className="text-right">{row.value || '—'}</span>
+            </div>
+          ))}
+        </CardContent>
+      </Card>
+
+      <Sheet open={editing} onOpenChange={setSheetOpen}>
+        <SheetContent>
+          <SheetHeader>
+            <SheetTitle>{t('profile.business_details')}</SheetTitle>
+          </SheetHeader>
+          <div className="flex flex-1 flex-col gap-4 overflow-y-auto p-4">
+            {formError && (
+              <p role="alert" className="text-destructive text-sm">
+                {formError}
+              </p>
+            )}
+            <Field>
+              <FieldLabel htmlFor="legal-name">{t('profile.legal_name')}</FieldLabel>
+              <Input
+                id="legal-name"
+                value={legalName}
+                onChange={(event) => setLegalName(event.target.value)}
+              />
+            </Field>
+            <Field>
+              <FieldLabel htmlFor="registration-number">
+                {t('profile.registration_number')}
+              </FieldLabel>
+              <Input
+                id="registration-number"
+                value={registrationNumber}
+                onChange={(event) => setRegistrationNumber(event.target.value)}
+              />
+            </Field>
+          </div>
+          <SheetFooter>
+            <Button variant="outline" size="sm" onClick={() => setSheetOpen(false)}>
+              {t('common.cancel')}
+            </Button>
+            <Button size="sm" disabled={save.isPending} onClick={() => save.mutate()}>
+              {t('common.save')}
+            </Button>
+          </SheetFooter>
+        </SheetContent>
+      </Sheet>
+    </>
+  )
+}

package/src/components/seller-returns-location-card.tsx

@@ -0,0 +1,151 @@
+import {
+  AddressFormDialog,
+  editableAddressToStockLocationParams,
+  stockLocationToAddressBlock,
+  stockLocationToEditableAddress,
+} from '@spree/dashboard-core'
+import {
+  AddressBlock,
+  Badge,
+  Button,
+  Card,
+  CardAction,
+  CardContent,
+  CardHeader,
+  CardTitle,
+  StatusBadge,
+  toastManager,
+} from '@spree/dashboard-ui'
+import { PencilIcon, PlusIcon } from '@spree/dashboard-ui/icons'
+import type { StockLocationParams } from '@spree/seller-sdk'
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { useParams } from '@tanstack/react-router'
+import { useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { sellerClient } from '../api-client'
+
+/**
+ * Where customers send returns — the address on the seller's default stock
+ * location.
+ *
+ * A location rather than a loose address because returned goods have to be
+ * restocked somewhere the catalog can see: stock movements anchor to a
+ * location, so an address on its own would leave the parcel arriving nowhere.
+ * The seller sees an address form all the same — the location is the record
+ * behind it, not a concept they have to learn to fill this in.
+ */
+export function SellerReturnsLocationCard({ headless = false }: { headless?: boolean }) {
+  const { t } = useTranslation()
+  const { sellerId } = useParams({ from: '/_authenticated/$sellerId' })
+  const queryClient = useQueryClient()
+  const [editing, setEditing] = useState(false)
+
+  // Two filtered requests rather than one page filtered in the browser, to
+  // match `Seller#returns_location` exactly: a location that accepts returns
+  // wins outright, and only then does default and name decide. A seller with
+  // more locations than one page holds would otherwise see one address while
+  // the server sent their returns to another, with nothing on screen saying
+  // so — and they would edit the wrong one.
+  const activeParams = { active_true: true, limit: 1 }
+  const { data: takesReturns, isError: returnsFailed } = useQuery({
+    queryKey: ['seller', sellerId, 'stock-locations', 'returns'],
+    queryFn: () =>
+      sellerClient().stockLocations.list({ ...activeParams, returns_enabled_true: true }),
+  })
+  const hasReturnsLocation = (takesReturns?.data.length ?? 0) > 0
+  const { data: anyActive, isError: anyFailed } = useQuery({
+    queryKey: ['seller', sellerId, 'stock-locations'],
+    queryFn: () => sellerClient().stockLocations.list(activeParams),
+    enabled: !!takesReturns && !hasReturnsLocation,
+  })
+
+  const location = takesReturns?.data[0] ?? anyActive?.data[0]
+  // A failed lookup must not read as "no address yet" — that invites the
+  // seller to re-enter one they already have.
+  const failed = returnsFailed || anyFailed
+  const hasAddress = Boolean(location?.address1)
+  const title = t('profile.returns_address')
+
+  const save = useMutation({
+    mutationFn: (params: StockLocationParams) => {
+      if (!location) throw new Error(t('common.error'))
+      return sellerClient().stockLocations.update(location.id, params)
+    },
+    onSuccess: () => {
+      void queryClient.invalidateQueries({ queryKey: ['seller', sellerId, 'stock-locations'] })
+      // The checklist asks whether this address is filled in, so it has to
+      // re-evaluate.
+      void queryClient.invalidateQueries({ queryKey: ['seller', sellerId, 'onboarding'] })
+      setEditing(false)
+      toastManager.add({ type: 'success', title: t('profile.saved') })
+    },
+    onError: (err) =>
+      toastManager.add({
+        type: 'error',
+        title: err instanceof Error ? err.message : t('common.error'),
+      }),
+  })
+
+  const body =
+    hasAddress && location ? (
+      <AddressBlock address={stockLocationToAddressBlock(location)} />
+    ) : (
+      <p className={failed ? 'text-destructive text-sm' : 'text-muted-foreground text-sm'}>
+        {t(failed ? 'common.error' : 'profile.address_not_provided')}
+      </p>
+    )
+
+  const editButton = (
+    <Button
+      variant={hasAddress ? 'outline' : 'default'}
+      size="sm"
+      disabled={!location}
+      onClick={() => setEditing(true)}
+    >
+      {hasAddress ? <PencilIcon className="size-4" /> : <PlusIcon className="size-4" />}
+      {hasAddress ? t('profile.edit') : t('profile.add_address')}
+    </Button>
+  )
+
+  const dialog = editing && location && (
+    <AddressFormDialog
+      title={title}
+      address={stockLocationToEditableAddress(location)}
+      open
+      business
+      onOpenChange={setEditing}
+      onSave={(values) => save.mutate(editableAddressToStockLocationParams(values))}
+      isPending={save.isPending}
+    />
+  )
+
+  if (headless) {
+    return (
+      <div className="flex flex-col items-start gap-3">
+        {body}
+        {editButton}
+        {dialog}
+      </div>
+    )
+  }
+
+  return (
+    <>
+      <Card>
+        <CardHeader>
+          <CardTitle>
+            {title}
+            {hasAddress ? (
+              <StatusBadge status="complete" label={t('profile.address_filled')} />
+            ) : (
+              <Badge variant="outline">{t('profile.address_missing')}</Badge>
+            )}
+          </CardTitle>
+          <CardAction>{editButton}</CardAction>
+        </CardHeader>
+        <CardContent>{body}</CardContent>
+      </Card>
+      {dialog}
+    </>
+  )
+}

package/src/components/seller-switcher.tsx

@@ -0,0 +1,124 @@
+import { getInitials } from '@spree/dashboard-core'
+import {
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+  SidebarMenu,
+  SidebarMenuItem,
+  Skeleton,
+  useSidebar,
+} from '@spree/dashboard-ui'
+import { CheckIcon, ChevronsUpDownIcon } from '@spree/dashboard-ui/icons'
+import { useQuery } from '@tanstack/react-query'
+import { Link, useParams } from '@tanstack/react-router'
+import { useTranslation } from 'react-i18next'
+import { sellerClient } from '../api-client'
+
+/**
+ * Sidebar seller header, mirroring the operator's store switcher.
+ *
+ * A plain, non-interactive block when the signed-in person runs one seller —
+ * which is most of them — and a dropdown listing every seller they hold a
+ * role on once there are two or more. Switching is a link to the other
+ * seller's route, so the URL stays the source of truth for who is being
+ * acted as, exactly as the store switcher navigates by store id.
+ *
+ * Replaces the fixed "Seller panel" label, which told a seller something
+ * they already knew and left their own name off the one piece of chrome
+ * that is always on screen.
+ */
+export function SellerSwitcher() {
+  const { t } = useTranslation()
+  const { isMobile, state } = useSidebar()
+  const isCollapsed = state === 'collapsed'
+  const { sellerId } = useParams({ strict: false }) as { sellerId?: string }
+
+  // `/me` for the list, the profile for the current seller's own logo — the
+  // summary in `/me` carries no image, and the profile query is already
+  // loaded by the page behind this.
+  const { data: me, isLoading } = useQuery({
+    queryKey: ['seller', 'me'],
+    queryFn: () => sellerClient().me(),
+  })
+
+  const { data: profile } = useQuery({
+    queryKey: ['seller', sellerId, 'profile'],
+    queryFn: () => sellerClient().profile.get(),
+    enabled: Boolean(sellerId),
+  })
+
+  if (isLoading) return <Skeleton className="h-rail-header-height w-full rounded-xl" />
+
+  const sellers = me?.sellers ?? []
+  const current = sellers.find((seller) => seller.id === sellerId) ?? sellers[0]
+
+  // Capped at two characters — see the store switcher: one letter per word
+  // overflows the avatar as soon as a name runs past two words.
+  const initials = getInitials(current?.name, '?')
+
+  const header = (
+    <>
+      <Avatar>
+        {profile?.square_logo_url || profile?.logo_url ? (
+          <AvatarImage src={profile.square_logo_url ?? profile.logo_url ?? undefined} />
+        ) : null}
+        <AvatarFallback>{initials}</AvatarFallback>
+      </Avatar>
+      {!isCollapsed && (
+        <div className="grid flex-1 text-left text-sm leading-tight">
+          <span className="truncate font-medium text-foreground">{current?.name}</span>
+        </div>
+      )}
+    </>
+  )
+
+  if (sellers.length < 2) {
+    return (
+      <SidebarMenu>
+        <SidebarMenuItem className="flex h-rail-header-height items-center">
+          <div className="flex w-full items-center gap-2 p-1.5">{header}</div>
+        </SidebarMenuItem>
+      </SidebarMenu>
+    )
+  }
+
+  return (
+    <SidebarMenu>
+      <SidebarMenuItem className="flex h-rail-header-height items-center">
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild className="flex w-full items-center">
+            <button
+              type="button"
+              aria-label={t('seller_switcher.label')}
+              className="gap-2 rounded-xl p-1.5 outline-hidden transition-colors duration-100 hover:bg-sidebar-accent data-[state=open]:bg-sidebar-accent"
+            >
+              {header}
+              {!isCollapsed && (
+                <ChevronsUpDownIcon className="ml-auto size-4 text-muted-foreground" />
+              )}
+            </button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent
+            className="min-w-48"
+            side={isMobile ? 'bottom' : 'right'}
+            align="start"
+            sideOffset={8}
+          >
+            {sellers.map((seller) => (
+              <DropdownMenuItem key={seller.id} asChild>
+                <Link to="/$sellerId" params={{ sellerId: seller.id }} className="no-underline">
+                  <span className="flex-1 truncate">{seller.name}</span>
+                  {seller.id === current?.id && <CheckIcon className="size-4" />}
+                </Link>
+              </DropdownMenuItem>
+            ))}
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </SidebarMenuItem>
+    </SidebarMenu>
+  )
+}

package/src/components/seller-tax-identifiers-card.tsx

@@ -0,0 +1,63 @@
+import { mapSpreeErrorsToForm } from '@spree/dashboard-core'
+import { TaxIdentifiersCard } from '@spree/dashboard-ui'
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { useParams } from '@tanstack/react-router'
+import { sellerClient } from '../api-client'
+
+/**
+ * The seller's own tax registrations, rendered by the same panel a company's
+ * are managed from: a seller is a business like any other, and two surfaces
+ * for one job is how they come to behave differently.
+ */
+export function SellerTaxIdentifiersCard() {
+  const { sellerId } = useParams({ from: '/_authenticated/$sellerId' })
+  const queryClient = useQueryClient()
+  const queryKey = ['seller', sellerId, 'tax_identifiers']
+
+  const { data, isLoading } = useQuery({
+    queryKey,
+    queryFn: () => sellerClient().taxIdentifiers.list(),
+  })
+
+  // A registration can satisfy an onboarding requirement, so the checklist has
+  // to re-evaluate whenever one changes.
+  function refresh() {
+    void queryClient.invalidateQueries({ queryKey })
+    void queryClient.invalidateQueries({ queryKey: ['seller', sellerId, 'onboarding'] })
+  }
+
+  const create = useMutation({
+    mutationFn: (params: { kind: string; value: string }) =>
+      sellerClient().taxIdentifiers.create(params),
+    onSuccess: refresh,
+  })
+  const update = useMutation({
+    mutationFn: ({ id, params }: { id: string; params: { kind: string; value: string } }) =>
+      sellerClient().taxIdentifiers.update(id, params),
+    onSuccess: refresh,
+  })
+  const remove = useMutation({
+    mutationFn: (id: string) => sellerClient().taxIdentifiers.remove(id),
+    onSuccess: refresh,
+  })
+  const validate = useMutation({
+    mutationFn: (id: string) => sellerClient().taxIdentifiers.validate(id),
+    onSuccess: refresh,
+  })
+
+  return (
+    <TaxIdentifiersCard
+      identifiers={data?.data ?? []}
+      isLoading={isLoading}
+      canEdit
+      mutations={{
+        create: (params) => create.mutateAsync(params),
+        update: (id, params) => update.mutateAsync({ id, params }),
+        remove: (id) => remove.mutateAsync(id),
+        validate: (id) => validate.mutateAsync(id),
+        isValidating: validate.isPending,
+        mapErrors: mapSpreeErrorsToForm,
+      }}
+    />
+  )
+}

package/src/create-router.ts

@@ -0,0 +1,32 @@
+import type { AnyRoute, RouterConstructorOptions, RouterHistory } from '@tanstack/react-router'
+import { createRouter } from '@tanstack/react-router'
+
+export interface SellerRouterOptions {
+  /** Mirrors Vite's `base` so sub-path mounts route correctly. */
+  basepath?: string
+}
+
+/**
+ * Builds the panel's router from a route tree.
+ *
+ * Hosts own their entry point and pass the tree in, exactly as they do for
+ * the operator's dashboard — so a marketplace can add its own seller-facing
+ * pages without forking this package.
+ */
+export function createSellerRouter<TRouteTree extends AnyRoute>(
+  routeTree: TRouteTree,
+  { basepath }: SellerRouterOptions = {},
+) {
+  // Cast because the shell's root route requires no router context, which
+  // TypeScript cannot prove through the generic tree parameter. The return
+  // type stays parameterized by TRouteTree — that's what keeps links typed.
+  const options = { routeTree, basepath } as RouterConstructorOptions<
+    TRouteTree,
+    'never',
+    false,
+    RouterHistory,
+    Record<string, unknown>
+  >
+
+  return createRouter(options)
+}