@spree/dashboard-core 0.13.1 → 1.0.0-beta.1

package/src/components/address-form-dialog.tsx

@@ -1,9 +1,9 @@
 import { zodResolver } from '@hookform/resolvers/zod'
-import type { Address } from '@spree/admin-sdk'
 import {
   Button,
   Checkbox,
   Field,
+  FieldDescription,
   FieldError,
   FieldGroup,
   FieldLabel,
@@ -21,33 +21,27 @@ import { Controller, useForm } from 'react-hook-form'
 import { useTranslation } from 'react-i18next'
 import { z } from 'zod/v4'
 import { mapSpreeErrorsToForm } from '../lib/form-errors'
+import { useOptionalStore } from '../providers/store-provider'
 import { CountryCombobox } from './country-combobox'
 import { StateCombobox, useCountryStates } from './country-state-fields'
 
 export interface AddressParams {
   first_name: string
   last_name: string
+  company?: string
   address1: string
   address2: string
   city: string
   postal_code: string
-  country_iso: string
-  state_abbr: string
+  country_code: string
+  state_code: string
   phone: string
   label?: string
   is_default_billing?: boolean
   is_default_shipping?: boolean
 }
 
-const addressFormSchema = z.object({
-  first_name: z
-    .string()
-    .trim()
-    .min(1, { error: requiredMessage('first_name') }),
-  last_name: z
-    .string()
-    .trim()
-    .min(1, { error: requiredMessage('last_name') }),
+const addressFormFields = {
   address1: z
     .string()
     .trim()
@@ -61,29 +55,103 @@ const addressFormSchema = z.object({
     .string()
     .trim()
     .min(1, { error: requiredMessage('address.postal_code') }),
-  country_iso: z
+  country_code: z
     .string()
     .trim()
-    .min(1, { error: requiredMessage('country_iso') }),
-  state_abbr: z.string(),
+    .min(1, { error: requiredMessage('country_code') }),
+  state_code: z.string(),
   phone: z.string(),
   label: z.string(),
   is_default_billing: z.boolean(),
   is_default_shipping: z.boolean(),
+}
+
+/**
+ * Whose address this is.
+ *
+ * A person's address is addressed to them, so it needs their name. A
+ * business's is addressed to the company — there is no person to name, and
+ * the company is the part that cannot be left out. Mirrors the same
+ * distinction `Spree::Address` makes server-side, so the form asks for
+ * exactly what the model will accept.
+ */
+const personalSchema = z.object({
+  ...addressFormFields,
+  first_name: z
+    .string()
+    .trim()
+    .min(1, { error: requiredMessage('first_name') }),
+  last_name: z
+    .string()
+    .trim()
+    .min(1, { error: requiredMessage('last_name') }),
+  company: z.string(),
+})
+
+const businessSchema = z.object({
+  ...addressFormFields,
+  first_name: z.string(),
+  last_name: z.string(),
+  company: z
+    .string()
+    .trim()
+    .min(1, { error: requiredMessage('company') }),
 })
 
-type AddressFormValues = z.infer<typeof addressFormSchema>
+type AddressFormValues = z.infer<typeof personalSchema>
+
+/**
+ * Just the fields this dialog reads.
+ *
+ * Structural rather than the Admin SDK's `Address`, which carries operator
+ * data (metadata, customer_id, timestamps) that a seller's serializer
+ * deliberately withholds — binding core to the wider type would stop the
+ * seller panel from reusing the one address form.
+ */
+export interface EditableAddress {
+  /** Re-seeds the form when the dialog is pointed at a different address. */
+  id?: string
+  first_name?: string | null
+  last_name?: string | null
+  company?: string | null
+  address1?: string | null
+  address2?: string | null
+  city?: string | null
+  postal_code?: string | null
+  country_code?: string | null
+  state_code?: string | null
+  phone?: string | null
+  label?: string | null
+  is_default_billing?: boolean | null
+  is_default_shipping?: boolean | null
+}
 
-function buildDefaults(address: Address | null | undefined): AddressFormValues {
+/**
+ * Country a new address starts with. An existing record keeps whatever it
+ * stored; a new one takes the store's default so the merchant is not asked
+ * to pick the same country every time.
+ */
+export function resolveAddressCountryCode(
+  address: EditableAddress | null | undefined,
+  storeDefaultCountryCode?: string | null,
+): string {
+  return address?.country_code || storeDefaultCountryCode || ''
+}
+
+function buildDefaults(
+  address: EditableAddress | null | undefined,
+  storeDefaultCountryCode?: string | null,
+): AddressFormValues {
   return {
     first_name: address?.first_name ?? '',
     last_name: address?.last_name ?? '',
+    company: address?.company ?? '',
     address1: address?.address1 ?? '',
     address2: address?.address2 ?? '',
     city: address?.city ?? '',
     postal_code: address?.postal_code ?? '',
-    country_iso: address?.country_iso ?? '',
-    state_abbr: address?.state_abbr ?? '',
+    country_code: resolveAddressCountryCode(address, storeDefaultCountryCode),
+    state_code: address?.state_code ?? '',
     phone: address?.phone ?? '',
     label: address?.label ?? '',
     is_default_billing: address?.is_default_billing ?? false,
@@ -100,8 +168,11 @@ export function AddressFormDialog({
   isPending = false,
   showLabel = false,
   showDefaultFlags = false,
+  business = false,
+  companyReadOnly = false,
+  description,
 }: {
-  address: Address | null | undefined
+  address: EditableAddress | null | undefined
   open: boolean
   onOpenChange: (open: boolean) => void
   onSave: (address: AddressParams) => void | Promise<void>
@@ -109,12 +180,25 @@ export function AddressFormDialog({
   isPending?: boolean
   showLabel?: boolean
   showDefaultFlags?: boolean
+  /** Addressed to a company rather than a person — see the schemas above. */
+  business?: boolean
+  /**
+   * Show the company line but do not let it be edited. For an address whose
+   * owner already answers the question — a company node names itself, so
+   * there is nothing for the merchant to type.
+   */
+  companyReadOnly?: boolean
+  /** Overrides the standard "update the address details" blurb. */
+  description?: string
 }) {
   const { t } = useTranslation()
   const resolvedTitle = title ?? t('admin.components.address_form_dialog.edit_title')
+  // Optional: the seller panel has no store context, so a new address there
+  // stays country-empty rather than refusing to render.
+  const storeDefaultCountryCode = useOptionalStore()?.defaultCountry
   const form = useForm<AddressFormValues>({
-    defaultValues: buildDefaults(address),
-    resolver: zodResolver(addressFormSchema),
+    defaultValues: buildDefaults(address, storeDefaultCountryCode),
+    resolver: zodResolver(business ? businessSchema : personalSchema),
   })
   const { errors } = form.formState
 
@@ -127,12 +211,22 @@ export function AddressFormDialog({
   useEffect(() => {
     if (address?.id !== prevAddressIdRef.current) {
       prevAddressIdRef.current = address?.id
-      form.reset(buildDefaults(address))
+      form.reset(buildDefaults(address, storeDefaultCountryCode))
     }
-  }, [address, form])
+  }, [address, form, storeDefaultCountryCode])
+
+  // The store payload can arrive after the sheet mounts. Fill country on a
+  // new record only while the field is still empty so a merchant who already
+  // picked a different country is not overwritten.
+  useEffect(() => {
+    if (address?.country_code) return
+    if (!storeDefaultCountryCode) return
+    if (form.getValues('country_code')) return
+    form.setValue('country_code', storeDefaultCountryCode)
+  }, [address?.country_code, storeDefaultCountryCode, form])
 
-  const countryIso = form.watch('country_iso')
-  const { states, statesRequired } = useCountryStates(countryIso)
+  const countryCode = form.watch('country_code')
+  const { states, statesRequired } = useCountryStates(countryCode)
   const useStateCombobox = statesRequired && states.length > 0
 
   async function onSubmit(values: AddressFormValues) {
@@ -140,12 +234,13 @@ export function AddressFormDialog({
       await onSave({
         first_name: values.first_name,
         last_name: values.last_name,
+        company: values.company,
         address1: values.address1,
         address2: values.address2,
         city: values.city,
         postal_code: values.postal_code,
-        country_iso: values.country_iso,
-        state_abbr: values.state_abbr,
+        country_code: values.country_code,
+        state_code: values.state_code,
         phone: values.phone,
         ...(showLabel && { label: values.label || undefined }),
         ...(showDefaultFlags && {
@@ -177,7 +272,7 @@ export function AddressFormDialog({
         <SheetHeader>
           <SheetTitle>{resolvedTitle}</SheetTitle>
           <SheetDescription>
-            {t('admin.components.address_form_dialog.description')}
+            {description ?? t('admin.components.address_form_dialog.description')}
           </SheetDescription>
         </SheetHeader>
         <form
@@ -199,26 +294,43 @@ export function AddressFormDialog({
                   />
                 </Field>
               )}
-              <div className="grid grid-cols-2 gap-3">
+              {business ? (
                 <Field>
-                  <FieldLabel htmlFor="addr-fn">{t('admin.fields.first_name.label')}</FieldLabel>
+                  <FieldLabel htmlFor="addr-co">{t('admin.fields.company.label')}</FieldLabel>
                   <Input
-                    id="addr-fn"
-                    aria-invalid={!!errors.first_name || undefined}
-                    {...form.register('first_name')}
+                    id="addr-co"
+                    aria-invalid={!!errors.company || undefined}
+                    disabled={companyReadOnly}
+                    readOnly={companyReadOnly}
+                    {...form.register('company')}
                   />
-                  <FieldError errors={[errors.first_name]} />
-                </Field>
-                <Field>
-                  <FieldLabel htmlFor="addr-ln">{t('admin.fields.last_name.label')}</FieldLabel>
-                  <Input
-                    id="addr-ln"
-                    aria-invalid={!!errors.last_name || undefined}
-                    {...form.register('last_name')}
-                  />
-                  <FieldError errors={[errors.last_name]} />
+                  {companyReadOnly && (
+                    <FieldDescription>{t('admin.fields.company.help')}</FieldDescription>
+                  )}
+                  <FieldError errors={[errors.company]} />
                 </Field>
-              </div>
+              ) : (
+                <div className="grid grid-cols-2 gap-3">
+                  <Field>
+                    <FieldLabel htmlFor="addr-fn">{t('admin.fields.first_name.label')}</FieldLabel>
+                    <Input
+                      id="addr-fn"
+                      aria-invalid={!!errors.first_name || undefined}
+                      {...form.register('first_name')}
+                    />
+                    <FieldError errors={[errors.first_name]} />
+                  </Field>
+                  <Field>
+                    <FieldLabel htmlFor="addr-ln">{t('admin.fields.last_name.label')}</FieldLabel>
+                    <Input
+                      id="addr-ln"
+                      aria-invalid={!!errors.last_name || undefined}
+                      {...form.register('last_name')}
+                    />
+                    <FieldError errors={[errors.last_name]} />
+                  </Field>
+                </div>
+              )}
               <Field>
                 <FieldLabel htmlFor="addr-a1">
                   {t('admin.fields.address.address1.label')}
@@ -242,21 +354,26 @@ export function AddressFormDialog({
                 <FieldError errors={[errors.address2]} />
               </Field>
               <Field>
-                <FieldLabel>{t('admin.fields.country_iso.label')}</FieldLabel>
+                <FieldLabel htmlFor="addr-country">
+                  {t('admin.fields.country_code.label')}
+                </FieldLabel>
                 <Controller
-                  name="country_iso"
+                  name="country_code"
                   control={form.control}
                   render={({ field }) => (
                     <CountryCombobox
+                      id="addr-country"
+                      invalid={!!errors.country_code}
                       value={field.value}
+                      onBlur={field.onBlur}
                       onValueChange={(iso) => {
                         field.onChange(iso)
-                        form.setValue('state_abbr', '', { shouldDirty: true })
+                        form.setValue('state_code', '', { shouldDirty: true })
                       }}
                     />
                   )}
                 />
-                <FieldError errors={[errors.country_iso]} />
+                <FieldError errors={[errors.country_code]} />
               </Field>
               <div className="grid grid-cols-2 gap-3">
                 <Field>
@@ -270,32 +387,37 @@ export function AddressFormDialog({
                 </Field>
                 {useStateCombobox ? (
                   <Field>
-                    <FieldLabel>{t('admin.fields.state_abbr.label')}</FieldLabel>
+                    <FieldLabel htmlFor="addr-state">
+                      {t('admin.fields.state_code.label')}
+                    </FieldLabel>
                     <Controller
-                      name="state_abbr"
+                      name="state_code"
                       control={form.control}
                       render={({ field }) => (
                         <StateCombobox
-                          countryIso={countryIso}
+                          id="addr-state"
+                          invalid={!!errors.state_code}
+                          countryCode={countryCode}
                           states={states}
                           value={field.value}
+                          onBlur={field.onBlur}
                           onValueChange={field.onChange}
                         />
                       )}
                     />
-                    <FieldError errors={[errors.state_abbr]} />
+                    <FieldError errors={[errors.state_code]} />
                   </Field>
                 ) : (
                   <Field>
                     <FieldLabel htmlFor="addr-state-abbr">
-                      {t('admin.fields.state_abbr.label')}
+                      {t('admin.fields.state_code.label')}
                     </FieldLabel>
                     <Input
                       id="addr-state-abbr"
-                      aria-invalid={!!errors.state_abbr || undefined}
-                      {...form.register('state_abbr')}
+                      aria-invalid={!!errors.state_code || undefined}
+                      {...form.register('state_code')}
                     />
-                    <FieldError errors={[errors.state_abbr]} />
+                    <FieldError errors={[errors.state_code]} />
                   </Field>
                 )}
               </div>
@@ -322,40 +444,42 @@ export function AddressFormDialog({
               {showDefaultFlags && (
                 <>
                   <Field>
-                    <div className="flex items-start justify-between gap-4">
-                      <FieldLabel htmlFor="addr-default-billing" className="cursor-pointer">
-                        {t('admin.fields.address.is_default_billing.label')}
-                      </FieldLabel>
-                      <Controller
-                        name="is_default_billing"
-                        control={form.control}
-                        render={({ field }) => (
+                    <Controller
+                      name="is_default_billing"
+                      control={form.control}
+                      render={({ field }) => (
+                        <label
+                          htmlFor="addr-default-billing"
+                          className="flex cursor-pointer items-center gap-2 text-sm"
+                        >
                           <Checkbox
                             id="addr-default-billing"
                             checked={!!field.value}
                             onCheckedChange={field.onChange}
                           />
-                        )}
-                      />
-                    </div>
+                          {t('admin.fields.address.is_default_billing.label')}
+                        </label>
+                      )}
+                    />
                   </Field>
                   <Field>
-                    <div className="flex items-start justify-between gap-4">
-                      <FieldLabel htmlFor="addr-default-shipping" className="cursor-pointer">
-                        {t('admin.fields.address.is_default_shipping.label')}
-                      </FieldLabel>
-                      <Controller
-                        name="is_default_shipping"
-                        control={form.control}
-                        render={({ field }) => (
+                    <Controller
+                      name="is_default_shipping"
+                      control={form.control}
+                      render={({ field }) => (
+                        <label
+                          htmlFor="addr-default-shipping"
+                          className="flex cursor-pointer items-center gap-2 text-sm"
+                        >
                           <Checkbox
                             id="addr-default-shipping"
                             checked={!!field.value}
                             onCheckedChange={field.onChange}
                           />
-                        )}
-                      />
-                    </div>
+                          {t('admin.fields.address.is_default_shipping.label')}
+                        </label>
+                      )}
+                    />
                   </Field>
                 </>
               )}

package/src/components/app-shell.tsx

@@ -0,0 +1,171 @@
+import { SidebarInset, SidebarProvider } from '@spree/dashboard-ui'
+import { useRouterState } from '@tanstack/react-router'
+import type { ReactNode } from 'react'
+import { useEffect, useRef, useState } from 'react'
+import { useAutoCollapseSidebar } from '../hooks/use-auto-collapse-sidebar'
+import { StickyHeaderProvider } from '../providers/sticky-header-provider'
+import { AppSidebar } from './app-sidebar'
+import { MobileTopBar } from './mobile-top-bar'
+import { SettingsNavSheet, SettingsSidebar } from './settings-sidebar'
+import { SheetTopBar } from './sheet-top-bar'
+import { SkipLink } from './skip-link'
+import { MobileBreadcrumbBar } from './top-bar-breadcrumbs'
+
+/**
+ * The frame every panel renders inside: the nav rail, and the page as a sheet
+ * beside it.
+ *
+ * There is no top bar. The rail carries what one used to — tenant switcher,
+ * search, account — so the only chrome above a page is the page's own header,
+ * and the content sits in an inset sheet rather than running to the window
+ * edge.
+ *
+ * Both panels mount this rather than composing the same pieces twice: the
+ * seller panel previously hand-rolled its own `<header>`, which had already
+ * drifted from the dashboard's (a different border, a translucent fill the
+ * dashboard had deliberately abandoned). One frame means one place to fix.
+ */
+export function AppShell({
+  tenantId,
+  sidebarHeader,
+  inSettings,
+  uiLocales,
+  onEditProfile,
+  children,
+}: {
+  /** Prefix for the nav links. Defaults to the route's `storeId`. */
+  tenantId?: string
+  /** Sidebar header — a store switcher by default, a seller switcher here. */
+  sidebarHeader?: ReactNode
+  /** True on a settings route, which brings its own secondary rail. */
+  inSettings: boolean
+  /** Admin UI languages for the account menu's language switcher. */
+  uiLocales?: ReadonlyArray<{ code: string; name: string }>
+  /** Opens the app's edit-profile dialog from the account menu. */
+  onEditProfile?: () => void
+  children: ReactNode
+}) {
+  // The settings area brings a full-width nav of its own, and two stacked
+  // columns leave the content squeezed, so the primary rail folds to icons
+  // while the user is in there.
+  useAutoCollapseSidebar(inSettings)
+
+  // Below `lg` the settings rail is hidden, so its sheet is the only way
+  // between two settings pages. The trigger lives in the breadcrumb bar.
+  const [settingsNavOpen, setSettingsNavOpen] = useState(false)
+
+  // Put focus on the scroll container after each navigation, so Page Up/Down,
+  // Home and End work on a freshly opened page without clicking into it first.
+  // Those keys act on the focused element, and the shell's scroller is the only
+  // thing that scrolls — left on <body>, they would have nothing to move.
+  //
+  // Skipped when focus is already inside the sheet: a route change that came
+  // from typing in a filter must not pull the caret out of the field.
+  const scrollerRef = useRef<HTMLDivElement | null>(null)
+  const pathname = useRouterState({ select: (state) => state.location.pathname })
+  useEffect(() => {
+    // Read so the dependency is a real one: this effect exists to run on every
+    // navigation, and `pathname` is what changes.
+    if (!pathname) return
+    const scroller = scrollerRef.current
+    if (!scroller) return
+    if (scroller.contains(document.activeElement)) return
+    scroller.focus({ preventScroll: true })
+  }, [pathname])
+
+  return (
+    <>
+      {/* First in the tab order by construction — it has to precede the
+          sidebar's thirty-odd links to be able to skip them. */}
+      <SkipLink />
+      <AppSidebar
+        tenantId={tenantId}
+        header={sidebarHeader}
+        uiLocales={uiLocales}
+        onEditProfile={onEditProfile}
+      />
+      {/* The sheet is exactly as tall as the viewport and scrolls internally,
+          rather than growing with the page and letting the document scroll.
+          Both of its rounded ends then stay on screen — with a document-length
+          sheet the bottom two corners sit below the fold and the shape reads as
+          a panel that has come unstuck. It also gives the page's sticky header
+          a scroll container of its own to pin inside, so it can never ride up
+          over the rail's switcher.
+
+          `flex-row` so the secondary sidebar sits flush against the primary and
+          spans the sheet's full height. */}
+      <SidebarInset className="min-h-0 flex-row overflow-hidden">
+        <SettingsSidebar open={inSettings} tenantId={tenantId} />
+        {/* `tabIndex={-1}`: Page Up/Down, Home and End act on the focused
+            element, and this is the element that scrolls. Without it focus
+            stays on <body>, which has nothing to scroll now that the sheet
+            owns the overflow — so those keys did nothing at all. `-1` keeps it
+            out of the tab order while still letting a click or the skip link
+            put focus here. `outline-none` because it is a scroll container
+            rather than a control; the focus ring belongs to what is inside.
+
+            `themed-scrollbar` because this is the last scroll container still
+            on the browser default: the sheet owns the page's overflow, so its
+            bar is the one a merchant sees most, and a chrome-grey native bar
+            down the edge of the white sheet was the one piece of the frame
+            that did not belong to the design. Not the quiet variant the
+            settings nav uses — that one hides its thumb until hover, which
+            suits chrome but not the surface being read, where the thumb is
+            how you know where you are in a long list.
+
+            `me-[5px]` insets the bar from the sheet's right edge. An arbitrary
+            value rather than a scale step because the scale has no 5px rung —
+            `1.5` is 6px — and this is measured against the sheet's edge by eye,
+            so the exact figure is the point. A native
+            scrollbar is painted by the browser at the scroll container's own
+            border edge and no property can offset it, so the box itself has to
+            end short of the sheet — margin does that, where padding would not:
+            padding is inside the box, so the container would still end flush
+            with the sheet and only the content would move, leaving the bar
+            exactly where it was. Logical `me-` rather than `mr-` so the inset
+            follows the bar to the left edge under RTL. */}
+        <div
+          ref={scrollerRef}
+          tabIndex={-1}
+          className="themed-scrollbar flex min-w-0 flex-1 flex-col overflow-y-auto me-[5px] outline-none"
+        >
+          <MobileTopBar uiLocales={uiLocales} onEditProfile={onEditProfile} />
+          <SheetTopBar tenantId={tenantId} inSettings={inSettings} />
+          <MobileBreadcrumbBar
+            tenantId={tenantId}
+            onOpenSettingsNav={() => setSettingsNavOpen(true)}
+          />
+          <SettingsNavSheet
+            open={settingsNavOpen}
+            onOpenChange={setSettingsNavOpen}
+            tenantId={tenantId}
+          />
+          {/* Settings pages own their container so the secondary rail can sit
+              flush; everything else gets the shell's. */}
+          {inSettings ? (
+            children
+          ) : (
+            <div className="container mx-auto flex flex-1 flex-col gap-4 p-4 lg:p-6">
+              {children}
+            </div>
+          )}
+        </div>
+      </SidebarInset>
+    </>
+  )
+}
+
+/**
+ * `AppShell` under the sidebar provider it needs.
+ *
+ * Split so the shell itself can call `useAutoCollapseSidebar`, which only
+ * works inside the provider. `StickyHeaderProvider` rides along: it tracks
+ * whether a page has a `PageHeader`, which decides heading levels below it.
+ */
+export function AppShellProvider({ children }: { children: ReactNode }) {
+  return (
+    <StickyHeaderProvider>
+      <SidebarProvider>{children}</SidebarProvider>
+    </StickyHeaderProvider>
+  )
+}