Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

16.8 KB
Raw Blame
import {
  BackButton,
  Button,
  cn,
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
  ExternalLink,
  useConfirm,
  useCopyToClipboard,
  useScrolled,
} from '@spree/dashboard-ui'
import {
  BracesIcon,
  CheckIcon,
  CopyIcon,
  EllipsisVerticalIcon,
  TrashIcon,
} from '@spree/dashboard-ui/icons'
import type { JsonPreviewDrawerProps } from '@spree/dashboard-ui/spree/json-preview-drawer'
import { lazy, type ReactNode, Suspense, useState } from 'react'
import { useTranslation } from 'react-i18next'
import { docsUrl } from '../lib/docs'
import { useRegisterPageHeader, useStickyHeaderOffset } from '../providers/sticky-header-provider'
import { Slot } from './slot'

// JSON drawer is a developer-only feature; pulling its tree (which includes
// @uiw/react-json-view at ~30KB gzip) into the route bundle is wasteful.
// Lazy-load on first open so the chunk only ships to admins who use it.
// Deep subpath import bypasses the dashboard-ui barrel so the JSON view
// libs only live in the chunk Rollup splits off here.
const JsonPreviewDrawer = lazy(() =>
  import('@spree/dashboard-ui/spree/json-preview-drawer').then((m) => ({
    default: m.JsonPreviewDrawer,
  })),
)

/** Subset of `JsonPreviewDrawerProps` callers supply; PageHeader manages open state. */
export type PageHeaderJsonPreview = Pick<
  JsonPreviewDrawerProps,
  'title' | 'fetch' | 'endpoint' | 'resolveLink'
>

/**
 * Resource-shaped value PageHeader inspects to wire the more-actions dropdown.
 * Anything not present is simply omitted — no errors, no required fields beyond `id`.
 */
export interface PageHeaderResource {
  id: string
  /** Display number for "Copy number". Used on orders. */
  number?: string | null
}

interface PageHeaderProps {
  /** Main title, on its own line. */
  title: ReactNode
  /**
   * Whether the header pins to the top of the scroll container. Default true,
   * which is right for a detail page: the title and its Save button have to
   * stay reachable down a long form.
   *
   * A list page passes `false`. There the table's own column row is the band
   * worth pinning — it is what a reader needs while scrolling rows — and two
   * stacked sticky bands spend a third of a short viewport on chrome. Turning
   * this off also stops the header publishing a sticky offset, so the column
   * row pins to the top of the sheet rather than below a header that is no
   * longer there.
   */
  sticky?: boolean
  /** Small text beside the badges (updated_at badge, customer email, etc.). */
  subtitle?: ReactNode
  /**
   * One line under the title saying what the page is for. Unlike `subtitle`,
   * which shares the badge row and answers "where is this now", this explains
   * the feature itself — worth writing for something a merchant meets for the
   * first time (catalogs, price lists, transfers) and worth leaving off a page
   * that explains itself.
   */
  description?: ReactNode
  /**
   * Documentation for the feature, linked at the end of the description.
   * Relative to the user guide, or a full URL for a plugin's own docs.
   */
  docsPath?: string
  /** Back button target — passed to <BackButton fallback="..."/>. Omit for top-level pages. */
  backTo?: string
  /** Status badges, on the line under the title. Use <StatusBadge />. */
  badges?: ReactNode
  /** Primary action buttons (rightmost, before the dropdown). Most pages use this for "Save". */
  actions?: ReactNode
  /**
   * Domain-specific items for the top group of the more-actions dropdown
   * (e.g. Preview, Resend, Approve on orders). Rendered above the
   * `page.actions_dropdown` slot and the standard Copy ID / JSON items.
   *
   * Destructive entries belong in `destructiveItems`, not here — the dropdown
   * orders its three groups itself so every page reads the same way.
   */
  dropdownItems?: ReactNode
  /**
   * Destructive domain actions (Cancel order, a delete with its own confirm).
   * Always rendered last, in the same group as the auto-wired Delete, so a
   * page can never put a red item above the standard actions.
   */
  destructiveItems?: ReactNode
  /**
   * The resource being edited. When supplied, PageHeader renders the legacy
   * "more actions" dropdown (Copy ID, Copy number, Delete). When omitted, the
   * dropdown is only rendered if a plugin has registered into `page.actions_dropdown`.
   */
  resource?: PageHeaderResource
  /** Slot context name. Defaults to inferring from `resource` keys. Optional. */
  slotContext?: Record<string, unknown>
  /**
   * Called after the user confirms the auto-rendered Delete action. When
   * provided, the Delete item is enabled. PageHeader owns the confirmation,
   * so the handler must not prompt again — pass `dropdownItems` directly if
   * you need a delete flow this cannot express.
   */
  onDelete?: () => void | Promise<void>
  /** Override the destructive label ("Delete order", "Delete product", etc.). */
  deleteLabel?: string
  /**
   * Replaces the generic "Are you sure?" prompt. Say what goes with the
   * record — "Its zones and delivery methods go with it" — since that is what
   * the reader cannot see from the button.
   */
  deleteConfirmMessage?: string
  /** Heading for the delete prompt. Defaults to none, as the message carries it. */
  deleteConfirmTitle?: string
  /**
   * When supplied, the more-actions dropdown gains a "View as JSON" item that
   * opens a developer-style drawer with the resource payload.
   */
  jsonPreview?: PageHeaderJsonPreview
}

/**
 * Top-of-page chrome: back button + title + badges + subtitle, with primary
 * actions and a more-actions dropdown on the right.
 *
 * Mirrors `spree/admin/app/views/spree/admin/shared/_content_header.html.erb`:
 * the legacy header yields `:page_title`, `:page_actions`, `:page_actions_dropdown`
 * via `content_for`. Here those become props + the `page.actions` and
 * `page.actions_dropdown` slots, so plugins extend without overriding.
 */
export function PageHeader({
  title,
  sticky = true,
  subtitle,
  description,
  docsPath,
  backTo,
  badges,
  actions,
  dropdownItems,
  destructiveItems,
  resource,
  slotContext,
  onDelete,
  deleteLabel,
  deleteConfirmMessage,
  deleteConfirmTitle,
  jsonPreview,
}: PageHeaderProps) {
  const { t } = useTranslation()
  const slotCtx = { ...slotContext, resource }
  const showDropdown = Boolean(
    resource || onDelete || dropdownItems || destructiveItems || jsonPreview,
  )
  const [jsonOpen, setJsonOpen] = useState(false)
  // Latches true on first open so the drawer (and its lazy JsonView chunk)
  // doesn't mount until the user actually invokes it, but stays mounted
  // afterwards so the close animation plays.
  const [jsonEverOpened, setJsonEverOpened] = useState(false)
  const openJson = () => {
    setJsonEverOpened(true)
    setJsonOpen(true)
  }
  const scrolled = useScrolled()
  // Publishes this header's measured height as the sticky offset every other
  // pinned band reads (`top-header-height`): the table's pinned column row,
  // the bulk-action bar. There is no top bar any more, so this header IS the
  // chrome above the scroll area — and its height genuinely varies with
  // badges, a subtitle and wrapped actions, which a fixed constant could only
  // approximate. Measured rather than assumed, so those bands sit flush
  // against it at every size.
  const headerRef = useStickyHeaderOffset(sticky)
  // Announces this header so the page's other headings pick the right level —
  // a table below one renders its title as `h2` rather than a second `h1`.
  useRegisterPageHeader()

  return (
    // Pins at the very top of the viewport — with the top bar gone, the title,
    // badges and primary actions (notably Save on form pages) are the only
    // chrome that needs to stay reachable down a long page.
    //
    // `bg-card` masks the content scrolling behind it — the same surface as
    // the content sheet this sits in, so the pinned band is invisible at rest
    // rather than a stripe of the page ground across the top of a white sheet;
    // `-mx-4 px-4 lg:-mx-6 lg:px-6` and `-mt-4 lg:-mt-6 pt-4 lg:pt-6` undo
    // and re-apply the parent padding so the sticky band runs edge-to-edge.
    //
    // The `::after` pseudo-element is the bottom hairline — it fades in
    // once the user scrolls (so the header blends at rest, separates when
    // content slides under it). A horizontal `mask-image` gradient feathers
    // the hairline's left/right edges to transparent so it doesn't visually
    // collide with the page edges; the `border-border` color it carries is
    // the same hairline used elsewhere in the app.
    <header
      ref={headerRef}
      className={cn(
        // One row at every width. The title truncates rather than wrapping,
        // so it yields space to the actions instead of pushing them onto a
        // second row — a page with only a Save button was spending two rows
        // of a short viewport on chrome.
        // Opaque for the same reason as the top bar: this band pins over the
        // page's own scrolling content, so a translucent fill lets that content
        // ghost through it.
        '-mx-4 -mt-4 flex flex-row items-start gap-2 bg-card p-4 sm:gap-3 lg:-mx-6 lg:-mt-6 lg:px-6 lg:pt-6',
        sticky && 'sticky top-0 z-20',
        'transition-[box-shadow] duration-200 ease-out motion-reduce:transition-none',
        'after:pointer-events-none after:absolute after:inset-x-0 after:bottom-0 after:h-px after:bg-border after:opacity-0 after:transition-opacity after:duration-200 after:[mask-image:linear-gradient(to_right,transparent,black_8%,black_92%,transparent)]',
        sticky && scrolled && 'after:opacity-100 shadow-xs',
      )}
    >
      {/* Row one: back button beside the title, so the arrow keeps its
          relationship to the heading rather than floating above it. */}
      <div className="flex min-w-0 flex-1 items-start gap-3">
        {backTo && <BackButton fallback={backTo} />}

        {/* The heading owns its line, with everything that qualifies it on
            the line below, so the eye reads the name first rather than
            picking it out of a row it shares. */}
        <div className="flex min-w-0 flex-1 flex-col gap-1">
          {/* Smaller and clipped on a phone: sharing the row with the actions
              leaves a long product name too little width to wrap into
              anything readable. */}
          <h1 className="min-w-0 truncate font-semibold text-xl leading-tight sm:text-2xl sm:whitespace-normal">
            {title}
          </h1>
          {/* Statuses and the timestamp share the second line: both answer
              "where is this now", so splitting them costs a row and reads as
              two separate facts. The subtitle is clamped on a phone, where a
              long one would make the sticky band tall enough to eat the page. */}
          {(badges || subtitle) && (
            <div className="flex flex-wrap items-center gap-x-3 gap-y-1">
              {badges}
              {subtitle && (
                <span className="line-clamp-2 text-sm text-muted-foreground sm:line-clamp-none">
                  {subtitle}
                </span>
              )}
            </div>
          )}
          {(description || docsPath) && (
            <p className="text-muted-foreground text-sm">
              {description}
              {docsPath && (
                <>
                  {description ? ' ' : null}
                  <ExternalLink href={docsUrl(docsPath)}>
                    {t('admin.common.learn_more')}
                  </ExternalLink>
                </>
              )}
            </p>
          )}
        </div>
      </div>

      {/* Pinned to the end of the row. `shrink-0` so the actions keep their
          full width and the title absorbs the shortfall. */}
      <div className="flex shrink-0 items-center justify-end gap-2 sm:ml-auto">
        <Slot name="page.actions" context={slotCtx} />
        {actions}
        {showDropdown && (
          <PageActionsDropdown
            resource={resource}
            slotContext={slotCtx}
            dropdownItems={dropdownItems}
            destructiveItems={destructiveItems}
            onDelete={onDelete}
            deleteLabel={deleteLabel ?? t('admin.actions.delete')}
            deleteConfirmMessage={deleteConfirmMessage}
            deleteConfirmTitle={deleteConfirmTitle}
            onOpenJson={jsonPreview ? openJson : undefined}
          />
        )}
      </div>

      {jsonPreview && jsonEverOpened && (
        <Suspense fallback={null}>
          <JsonPreviewDrawer open={jsonOpen} onOpenChange={setJsonOpen} {...jsonPreview} />
        </Suspense>
      )}
    </header>
  )
}

// ---------------------------------------------------------------------------
// More-actions dropdown
// ---------------------------------------------------------------------------

interface PageActionsDropdownProps {
  resource?: PageHeaderResource
  slotContext: Record<string, unknown>
  dropdownItems?: ReactNode
  destructiveItems?: ReactNode
  onDelete?: () => void | Promise<void>
  deleteLabel: string
  deleteConfirmMessage?: string
  deleteConfirmTitle?: string
  onOpenJson?: () => void
}

function PageActionsDropdown({
  resource,
  slotContext,
  dropdownItems,
  destructiveItems,
  onDelete,
  deleteLabel,
  deleteConfirmMessage,
  deleteConfirmTitle,
  onOpenJson,
}: PageActionsDropdownProps) {
  const { t } = useTranslation()
  const confirm = useConfirm()

  return (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button size="icon" variant="outline" aria-label={t('admin.actions.more_actions')}>
          <EllipsisVerticalIcon className="size-4" />
        </Button>
      </DropdownMenuTrigger>
      {/* Three fixed groups, in this order: domain actions, standard actions,
          destructive actions. The order lives here rather than in each caller
          so every record page's menu reads the same way.

          Dividers are drawn by CSS (`:not(:empty) ~ :not(:empty)`) rather than
          by rendering a <DropdownMenuSeparator> between groups. A group's
          content can be present as a value but render nothing — an all-false
          fragment, or a plugin slot with no registrations — which a JS check
          reads as "has content" and would leave a divider floating against the
          menu's edge. `:empty` asks the DOM what actually rendered. */}
      <DropdownMenuContent
        align="end"
        className="[&>[data-menu-group]:not(:empty)~[data-menu-group]:not(:empty)]:mt-1 [&>[data-menu-group]:not(:empty)~[data-menu-group]:not(:empty)]:border-t [&>[data-menu-group]:not(:empty)~[data-menu-group]:not(:empty)]:border-border-subtle [&>[data-menu-group]:not(:empty)~[data-menu-group]:not(:empty)]:pt-1"
      >
        <div data-menu-group>
          {dropdownItems}
          <Slot name="page.actions_dropdown" context={slotContext} />
        </div>

        <div data-menu-group>
          {onOpenJson && (
            <DropdownMenuItem onClick={onOpenJson}>
              <BracesIcon className="size-4" />
              {t('admin.components.page_header.view_as_json')}
            </DropdownMenuItem>
          )}
          {resource?.number && (
            <CopyToClipboardItem
              label={t('admin.components.page_header.copy_number')}
              value={resource.number}
            />
          )}
          {resource && (
            <CopyToClipboardItem
              label={t('admin.components.page_header.copy_id')}
              value={resource.id}
            />
          )}
        </div>

        <div data-menu-group>
          {destructiveItems}
          {onDelete && (
            <DropdownMenuItem
              variant="destructive"
              onClick={async () => {
                if (
                  await confirm({
                    title: deleteConfirmTitle,
                    message: deleteConfirmMessage ?? t('admin.common.delete_confirm_message'),
                    variant: 'destructive',
                    confirmLabel: deleteLabel,
                  })
                ) {
                  await onDelete()
                }
              }}
            >
              <TrashIcon className="size-4" />
              {deleteLabel}
            </DropdownMenuItem>
          )}
        </div>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}

// ---------------------------------------------------------------------------
// Copy-to-clipboard menu item
// ---------------------------------------------------------------------------

function CopyToClipboardItem({ label, value }: { label: string; value: string }) {
  const { t } = useTranslation()
  const { copied, copy } = useCopyToClipboard()

  return (
    <DropdownMenuItem
      // Keep the menu open after click so the user sees the confirmation flash.
      closeOnClick={false}
      onClick={(e) => {
        e.preventDefault()
        copy(value)
      }}
    >
      {copied ? <CheckIcon className="size-4" /> : <CopyIcon className="size-4" />}
      {copied ? t('admin.actions.copied') : label}
    </DropdownMenuItem>
  )
}