@spree/dashboard-core 6.0.0 → 6.0.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spree/dashboard-core",
   "license": "MIT",
-  "version": "6.0.0",
+  "version": "6.0.2",
   "description": "Spree Dashboard framework — registries (table, nav, slot, settings-nav), providers (auth, permission, store), admin SDK client, generic infra hooks, and the defineDashboardPlugin extension API.",
   "author": "Vendo Connect Inc.",
   "homepage": "https://spreecommerce.org",
@@ -49,8 +49,8 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@spree/admin-sdk": ">=6.0.0 <7.0.0-0",
-    "@spree/dashboard-ui": ">=6.0.0 <7.0.0-0",
+    "@spree/admin-sdk": ">=6.0.2 <7.0.0-0",
+    "@spree/dashboard-ui": ">=6.0.2 <7.0.0-0",
     "@tanstack/react-query": "^5.100.9",
     "@tanstack/react-router": "^1.169.2",
     "i18next": "^26.2.0",
@@ -70,19 +70,24 @@
     "date-fns-tz": "^3.2.0",
     "lucide-react": "^1.60.0",
     "zod": "^4.6.7",
-    "@spree/core": "^6.0.0"
+    "@spree/core": "^6.0.2"
   },
   "devDependencies": {
     "@tanstack/react-query": "^5.104.5",
     "@tanstack/react-router": "^1.170.45",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
+    "i18next": "^26.5.3",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "react-hook-form": "^7.90.0",
+    "react-i18next": "^17.1.0",
     "tsup": "^9.0.0",
     "typescript": "~7.0.2",
     "vite": "^8.3.4",
     "vitest": "^5.0.5",
-    "@spree/dashboard-ui": "^6.0.0",
-    "@spree/admin-sdk": "^6.0.0"
+    "@spree/admin-sdk": "^6.0.2",
+    "@spree/dashboard-ui": "^6.0.2"
   },
   "scripts": {
     "lint": "biome check src",

package/src/api-client.ts

@@ -362,6 +362,8 @@ export interface PanelPackageType extends PanelNamedRecord {
    * editable.
    */
   editable?: boolean
+  /** Operator-only; the seller panel's serializer leaves it out. */
+  metadata?: Record<string, unknown> | null
   /** Whose packaging this is; null is the marketplace's own. */
   seller_id?: string | null
   seller_name?: string | null
@@ -653,6 +655,8 @@ export interface PanelStockLocation {
   pickup_stock_policy?: string
   pickup_ready_in_minutes?: number | null
   pickup_instructions?: string | null
+  /** Operator-only; the seller panel's serializer leaves it out. */
+  external_references?: Record<string, string>
 }
 
 /**

package/src/components/app-shell.tsx

@@ -32,6 +32,7 @@ export function AppShell({
   uiLocales,
   onEditProfile,
   notifications,
+  sidebarWidget,
   children,
 }: {
   /** Prefix for the nav links. Defaults to the route's `storeId`. */
@@ -49,6 +50,8 @@ export function AppShell({
    * notifications bell. The seller panel passes none.
    */
   notifications?: ReactNode
+  /** A card pinned above the account menu, such as the store setup checklist. */
+  sidebarWidget?: ReactNode
   children: ReactNode
 }) {
   // The settings area brings a full-width nav of its own, and two stacked
@@ -90,6 +93,7 @@ export function AppShell({
         uiLocales={uiLocales}
         onEditProfile={onEditProfile}
         notifications={notifications}
+        widget={sidebarWidget}
       />
       {/* The sheet is exactly as tall as the viewport and scrolls internally,
           rather than growing with the page and letting the document scroll.

package/src/components/app-sidebar.tsx

@@ -130,6 +130,7 @@ export function AppSidebar({
   uiLocales,
   onEditProfile,
   notifications,
+  widget,
   ...props
 }: ComponentProps<typeof Sidebar> & {
   /**
@@ -145,6 +146,8 @@ export function AppSidebar({
   onEditProfile?: () => void
   /** Shown beside the account menu, such as a notifications bell. */
   notifications?: ReactNode
+  /** A card pinned above the account menu. */
+  widget?: ReactNode
 }) {
   const { i18n } = useTranslation()
   const { storeId } = useParams({ strict: false }) as { storeId?: string }
@@ -175,7 +178,7 @@ export function AppSidebar({
             shell's shape steady and say the difference honestly.
 
             Keyed on `isLoading` alone, not on an empty list: entries without a
-            `subject` (Home, Getting Started) skip the permission filter, so the
+            `subject` (Home) skip the permission filter, so the
             list is never actually empty and a length check would never fire. */}
         {isLoading ? (
           <NavSkeleton />
@@ -186,6 +189,8 @@ export function AppSidebar({
                 alone below a screen of empty space, so on a phone it follows
                 the list. */}
             {isMobile && <NavBottom items={bottomItems} className="mb-2" />}
+            {/* The footer is hidden on a phone, so the widget follows the list. */}
+            {isMobile && widget && <div className="px-2 pb-2">{widget}</div>}
           </>
         )}
       </SidebarContent>
@@ -193,6 +198,7 @@ export function AppSidebar({
           list fades out above it rather than scrolling it away. */}
       {!isLoading && !isMobile && <NavBottom items={bottomItems} className="py-2" />}
       <SidebarFooter className="hidden md:flex">
+        {widget}
         {/* In icon mode the rail is too narrow for a row, so the control
             stacks above the avatar. */}
         <div

package/src/components/invitation-acceptance.tsx

@@ -0,0 +1,411 @@
+import { zodResolver } from '@hookform/resolvers/zod'
+import type { SpreeError } from '@spree/admin-sdk'
+import { Button, Input, Label } from '@spree/dashboard-ui'
+import { useQuery } from '@tanstack/react-query'
+import { useState } from 'react'
+import { useForm } from 'react-hook-form'
+import { useTranslation } from 'react-i18next'
+import { z } from 'zod/v4'
+import { useAuth } from '../hooks/use-auth'
+import { mapSpreeErrorsToForm } from '../lib/form-errors'
+import { i18n } from '../lib/i18n'
+
+/**
+ * What the acceptance page needs to know about an invitation, as both the
+ * Admin and the Seller API lookups answer it. `target` is what the invitee
+ * joins: the store on the operator's dashboard, a seller on the seller panel.
+ */
+export interface InvitationSummary {
+  email: string
+  invitee_exists: boolean
+  inviter_email?: string | null
+  role_name?: string | null
+  target: { id: string; name: string }
+}
+
+export interface InvitationAcceptanceProps {
+  invitationId: string
+  /** From the emailed link's query string; the page refuses to go on without it. */
+  token?: string
+  lookup: (invitationId: string, token: string) => Promise<InvitationSummary>
+  /** Runs once the invitee's session is established, to take them into what they joined. */
+  onAccepted: (invitation: InvitationSummary) => void | Promise<void>
+}
+
+// Lazy message factories: module-scope `i18n.t(...)` would lock the English
+// string in at import time, breaking locale switches.
+const passwordRequired = () => i18n.t('admin.validation.password_required')
+const firstNameRequired = () => i18n.t('admin.validation.first_name_required')
+const lastNameRequired = () => i18n.t('admin.validation.last_name_required')
+const passwordsDontMatch = () => i18n.t('admin.validation.passwords_dont_match')
+const passwordMinLength = () =>
+  i18n.t('admin.validation.min_length', { field: i18n.t('admin.fields.password.label'), count: 8 })
+
+/** Existing invitee confirming with their current password. */
+const signInSchema = z.object({
+  password: z.string().min(1, { error: passwordRequired }),
+})
+type SignInValues = z.infer<typeof signInSchema>
+
+/** New invitee creating an account inline — mirrors the server's `AdminUser` validations. */
+const signUpSchema = z
+  .object({
+    first_name: z.string().min(1, { error: firstNameRequired }),
+    last_name: z.string().min(1, { error: lastNameRequired }),
+    password: z.string().min(8, { error: passwordMinLength }),
+    password_confirmation: z.string(),
+  })
+  .refine((data) => data.password === data.password_confirmation, {
+    error: passwordsDontMatch,
+    path: ['password_confirmation'],
+  })
+type SignUpValues = z.infer<typeof signUpSchema>
+
+/**
+ * The screens behind an invitation link, shared by both panels. The host
+ * wraps it in its own page layout and decides where an accepted invitee goes.
+ *
+ * Someone signed out sets a password (new account) or confirms theirs
+ * (existing account). Someone already signed in as the invitee accepts with
+ * one click; signed in as anyone else, they are asked to sign out first
+ * rather than having their session swapped silently.
+ */
+export function InvitationAcceptance({
+  invitationId,
+  token,
+  lookup,
+  onAccepted,
+}: InvitationAcceptanceProps) {
+  const { t } = useTranslation()
+  const { isInitializing } = useAuth()
+
+  if (!token) {
+    return (
+      <ErrorCard
+        title={t('admin.invitation.missing_token_title')}
+        message={t('admin.invitation.missing_token_message')}
+      />
+    )
+  }
+
+  // Waits for the session check: it decides which form fits, and a failed one
+  // clears the query cache mid-lookup.
+  if (isInitializing) return <Loading />
+
+  return (
+    <InvitationLoader
+      invitationId={invitationId}
+      token={token}
+      lookup={lookup}
+      onAccepted={onAccepted}
+    />
+  )
+}
+
+type LoadedProps = Required<InvitationAcceptanceProps>
+
+function InvitationLoader({ invitationId, token, lookup, onAccepted }: LoadedProps) {
+  const { t } = useTranslation()
+  const query = useQuery({
+    queryKey: ['invitation-lookup', invitationId, token],
+    queryFn: () => lookup(invitationId, token),
+    retry: false,
+  })
+
+  if (query.isPending) return <Loading />
+
+  if (query.isError) {
+    const err = query.error as SpreeError
+    return (
+      <ErrorCard
+        title={
+          err.status === 404
+            ? t('admin.invitation.not_found_title')
+            : t('admin.invitation.generic_error_title')
+        }
+        message={
+          err.status === 404
+            ? t('admin.invitation.not_found_message')
+            : err.message || t('admin.invitation.generic_error_message')
+        }
+      />
+    )
+  }
+
+  return (
+    <AcceptForm
+      invitationId={invitationId}
+      token={token}
+      invitation={query.data}
+      onAccepted={onAccepted}
+    />
+  )
+}
+
+interface FormProps {
+  invitationId: string
+  token: string
+  invitation: InvitationSummary
+  onAccepted: LoadedProps['onAccepted']
+}
+
+function AcceptForm(props: FormProps) {
+  const { user } = useAuth()
+  const { invitation } = props
+  // Signing in through a form below sets `user` before the redirect lands;
+  // a page opened signed out keeps showing that form until then.
+  const [openedSignedOut] = useState(!user)
+  if (user && !openedSignedOut) {
+    return user.email.toLowerCase() === invitation.email.toLowerCase() ? (
+      <AcceptAsSignedIn {...props} />
+    ) : (
+      <SignedInAsAnotherAccount invitation={invitation} />
+    )
+  }
+
+  return invitation.invitee_exists ? <SignInForm {...props} /> : <SignUpForm {...props} />
+}
+
+function SignInForm({ invitationId, token, invitation, onAccepted }: FormProps) {
+  const { t } = useTranslation()
+  const { acceptInvitation, isLoading } = useAuth()
+
+  const form = useForm<SignInValues>({
+    resolver: zodResolver(signInSchema),
+    defaultValues: { password: '' },
+  })
+  const { errors } = form.formState
+
+  const onSubmit = async (data: SignInValues) => {
+    try {
+      await acceptInvitation(invitationId, token, { password: data.password })
+    } catch (err) {
+      const e = err as SpreeError
+      if (e?.status === 401) {
+        form.setError('root', { message: t('admin.validation.invalid_password') })
+        return
+      }
+      if (!mapSpreeErrorsToForm(err, form.setError)) {
+        form.setError('root', { message: e?.message || t('admin.invitation.could_not_accept') })
+      }
+      return
+    }
+    await onAccepted(invitation)
+  }
+
+  return (
+    <>
+      <InvitationIntro invitation={invitation} action={t('admin.invitation.sign_in_to_accept')} />
+      <form onSubmit={form.handleSubmit(onSubmit)} className="grid gap-6">
+        {errors.root && <p className="text-sm text-destructive">{errors.root.message}</p>}
+        <div className="grid gap-2">
+          <Label htmlFor="invitee-email">{t('admin.fields.email.label')}</Label>
+          <Input id="invitee-email" value={invitation.email} disabled />
+        </div>
+        <div className="grid gap-2">
+          <Label htmlFor="password">{t('admin.fields.password.label')}</Label>
+          <Input
+            id="password"
+            type="password"
+            autoFocus
+            aria-invalid={!!errors.password || undefined}
+            {...form.register('password')}
+          />
+          {errors.password && <p className="text-sm text-destructive">{errors.password.message}</p>}
+        </div>
+        <Button type="submit" className="w-full" disabled={isLoading}>
+          {isLoading ? t('admin.invitation.accepting') : t('admin.invitation.sign_in_and_accept')}
+        </Button>
+      </form>
+    </>
+  )
+}
+
+function SignUpForm({ invitationId, token, invitation, onAccepted }: FormProps) {
+  const { t } = useTranslation()
+  const { acceptInvitation, isLoading } = useAuth()
+
+  const form = useForm<SignUpValues>({
+    resolver: zodResolver(signUpSchema),
+    defaultValues: { first_name: '', last_name: '', password: '', password_confirmation: '' },
+  })
+  const { errors } = form.formState
+
+  const onSubmit = async (data: SignUpValues) => {
+    try {
+      await acceptInvitation(invitationId, token, data)
+    } catch (err) {
+      if (!mapSpreeErrorsToForm(err, form.setError)) {
+        const e = err as SpreeError
+        form.setError('root', { message: e?.message || t('admin.invitation.could_not_accept') })
+      }
+      return
+    }
+    await onAccepted(invitation)
+  }
+
+  return (
+    <>
+      <InvitationIntro invitation={invitation} action={t('admin.invitation.create_to_accept')} />
+      <form onSubmit={form.handleSubmit(onSubmit)} className="grid gap-6">
+        {errors.root && <p className="text-sm text-destructive">{errors.root.message}</p>}
+        <div className="grid gap-2">
+          <Label htmlFor="invitee-email">{t('admin.fields.email.label')}</Label>
+          <Input id="invitee-email" value={invitation.email} disabled />
+        </div>
+        <div className="grid grid-cols-2 gap-3">
+          <div className="grid gap-2">
+            <Label htmlFor="first_name">{t('admin.fields.first_name.label')}</Label>
+            <Input
+              id="first_name"
+              autoFocus
+              aria-invalid={!!errors.first_name || undefined}
+              {...form.register('first_name')}
+            />
+            {errors.first_name && (
+              <p className="text-sm text-destructive">{errors.first_name.message}</p>
+            )}
+          </div>
+          <div className="grid gap-2">
+            <Label htmlFor="last_name">{t('admin.fields.last_name.label')}</Label>
+            <Input
+              id="last_name"
+              aria-invalid={!!errors.last_name || undefined}
+              {...form.register('last_name')}
+            />
+            {errors.last_name && (
+              <p className="text-sm text-destructive">{errors.last_name.message}</p>
+            )}
+          </div>
+        </div>
+        <div className="grid gap-2">
+          <Label htmlFor="password">{t('admin.fields.password.label')}</Label>
+          <Input
+            id="password"
+            type="password"
+            aria-invalid={!!errors.password || undefined}
+            {...form.register('password')}
+          />
+          {errors.password && <p className="text-sm text-destructive">{errors.password.message}</p>}
+        </div>
+        <div className="grid gap-2">
+          <Label htmlFor="password_confirmation">
+            {t('admin.invitation.password_confirmation')}
+          </Label>
+          <Input
+            id="password_confirmation"
+            type="password"
+            aria-invalid={!!errors.password_confirmation || undefined}
+            {...form.register('password_confirmation')}
+          />
+          {errors.password_confirmation && (
+            <p className="text-sm text-destructive">{errors.password_confirmation.message}</p>
+          )}
+        </div>
+        <Button type="submit" className="w-full" disabled={isLoading}>
+          {isLoading ? t('admin.invitation.accepting') : t('admin.invitation.create_and_accept')}
+        </Button>
+      </form>
+    </>
+  )
+}
+
+function AcceptAsSignedIn({ invitationId, token, invitation, onAccepted }: FormProps) {
+  const { t } = useTranslation()
+  const { user, acceptInvitation, logout, isLoading } = useAuth()
+  const [error, setError] = useState<string | null>(null)
+
+  const onAccept = async () => {
+    setError(null)
+    try {
+      await acceptInvitation(invitationId, token, {})
+    } catch (err) {
+      const e = err as SpreeError
+      // The session lapsed (a laptop that slept, say): signing out brings up
+      // the password form instead of an error with no way forward.
+      if (e?.status === 401) return logout()
+      setError(e?.message || t('admin.invitation.could_not_accept'))
+      return
+    }
+    await onAccepted(invitation)
+  }
+
+  return (
+    <>
+      <InvitationIntro
+        invitation={invitation}
+        action={t('admin.invitation.signed_in_as_invitee', { email: user?.email })}
+      />
+      {error && <p className="text-sm text-destructive">{error}</p>}
+      <Button className="w-full" disabled={isLoading} onClick={onAccept}>
+        {isLoading ? t('admin.invitation.accepting') : t('admin.invitation.accept')}
+      </Button>
+    </>
+  )
+}
+
+function SignedInAsAnotherAccount({ invitation }: { invitation: InvitationSummary }) {
+  const { t } = useTranslation()
+  const { user, logout } = useAuth()
+
+  return (
+    <>
+      <div className="flex flex-col gap-2">
+        <h1 className="text-2xl font-bold">
+          {t('admin.invitation.join_store', { store: invitation.target.name })}
+        </h1>
+        <p className="text-sm text-muted-foreground">
+          {t('admin.invitation.signed_in_as_another_account', {
+            email: user?.email,
+            invitee: invitation.email,
+          })}
+        </p>
+      </div>
+      <Button variant="outline" className="w-full" onClick={() => logout()}>
+        {t('admin.auth.logout')}
+      </Button>
+    </>
+  )
+}
+
+/** "Join <target>" plus one sentence: who invited, as what, and what to do next. */
+function InvitationIntro({
+  invitation,
+  action,
+}: {
+  invitation: InvitationSummary
+  action: string
+}) {
+  const { t } = useTranslation()
+  const invitedPart = invitation.inviter_email
+    ? t('admin.invitation.invited_by', { email: invitation.inviter_email })
+    : t('admin.invitation.invited_generic')
+  const rolePart = invitation.role_name
+    ? t('admin.invitation.invited_as_role', { role: invitation.role_name })
+    : ''
+
+  return (
+    <div className="flex flex-col gap-2">
+      <h1 className="text-2xl font-bold">
+        {t('admin.invitation.join_store', { store: invitation.target.name })}
+      </h1>
+      <p className="text-sm text-muted-foreground">{`${invitedPart}${rolePart}${action}`}</p>
+    </div>
+  )
+}
+
+function Loading() {
+  const { t } = useTranslation()
+  return (
+    <div className="py-12 text-center text-muted-foreground">{t('admin.invitation.loading')}</div>
+  )
+}
+
+function ErrorCard({ title, message }: { title: string; message: string }) {
+  return (
+    <div className="flex flex-col gap-2">
+      <h1 className="text-2xl font-bold">{title}</h1>
+      <p className="text-sm text-muted-foreground">{message}</p>
+    </div>
+  )
+}

package/src/components/record-metadata.tsx

@@ -0,0 +1,118 @@
+import {
+  DropdownMenuItem,
+  hasExternalReferences,
+  hasMetadata,
+  MetadataCard,
+  MetadataSheet,
+} from '@spree/dashboard-ui'
+import { BracesIcon } from '@spree/dashboard-ui/icons'
+import { useState } from 'react'
+import { useTranslation } from 'react-i18next'
+
+type Metadata = Record<string, unknown> | null | undefined
+type ExternalReferences = Record<string, string> | null | undefined
+
+interface RecordIntegrationData {
+  metadata?: Metadata
+  /** The record's `external_references` map, on records that carry one. */
+  externalReferences?: ExternalReferences
+}
+
+function useMetadataCopy() {
+  const { t } = useTranslation()
+  return {
+    title: t('admin.components.metadata_card.title'),
+    metadataTitle: t('admin.components.metadata_card.title'),
+    externalReferencesTitle: t('admin.components.metadata_card.external_references'),
+    copyLabel: (system: string) => t('admin.components.metadata_card.copy_reference', { system }),
+    emptyTitle: t('admin.components.metadata_card.empty_title'),
+    emptyDescription: t('admin.components.metadata_card.empty_description'),
+  }
+}
+
+function hasIntegrationData({ metadata, externalReferences }: RecordIntegrationData) {
+  return hasMetadata(metadata) || hasExternalReferences(externalReferences)
+}
+
+/** Metadata card for the main column of a record's detail page. */
+export function RecordMetadataCard({ metadata, externalReferences }: RecordIntegrationData) {
+  return (
+    <MetadataCard
+      metadata={metadata}
+      externalReferences={externalReferences}
+      {...useMetadataCopy()}
+    />
+  )
+}
+
+/** Metadata of a row inside another page; pair with {@link ViewMetadataMenuItem}. */
+function RecordMetadataSheet({
+  metadata,
+  externalReferences,
+  open,
+  onOpenChange,
+  description,
+}: RecordIntegrationData & {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  /** Names the record, e.g. "Payment P123". */
+  description?: string
+}) {
+  return (
+    <MetadataSheet
+      open={open}
+      onOpenChange={onOpenChange}
+      metadata={metadata}
+      externalReferences={externalReferences}
+      description={description}
+      {...useMetadataCopy()}
+    />
+  )
+}
+
+/**
+ * One metadata sheet for a list of rows: `show` it from a row's menu and render
+ * `sheet` once beside the list. The record stays set while the sheet animates
+ * closed, so it never flashes the empty state on the way out.
+ */
+export function useMetadataSheet() {
+  const [viewing, setViewing] = useState<RecordIntegrationData & { description?: string }>()
+  const [open, setOpen] = useState(false)
+
+  return {
+    show(metadata: Metadata, description?: string, externalReferences?: ExternalReferences) {
+      setViewing({ metadata, description, externalReferences })
+      setOpen(true)
+    },
+    sheet: (
+      <RecordMetadataSheet
+        metadata={viewing?.metadata}
+        externalReferences={viewing?.externalReferences}
+        description={viewing?.description}
+        open={open}
+        onOpenChange={setOpen}
+      />
+    ),
+  }
+}
+
+/** Renders nothing when the record has no metadata, so a menu needs no check of its own. */
+export function ViewMetadataMenuItem({
+  onClick,
+  ...data
+}: RecordIntegrationData & { onClick: () => void }) {
+  const { t } = useTranslation()
+  if (!hasIntegrationData(data)) return null
+
+  return (
+    <DropdownMenuItem onClick={onClick}>
+      <BracesIcon className="size-4" />
+      {t('admin.components.metadata_card.view')}
+    </DropdownMenuItem>
+  )
+}
+
+/** Metadata at the bottom of a record's edit sheet; renders nothing when there is none. */
+export function RecordMetadataSection(data: RecordIntegrationData) {
+  return hasIntegrationData(data) ? <RecordMetadataCard {...data} /> : null
+}