@spree/dashboard-ui 0.13.1 → 1.0.0-beta.2

package/src/spree/delivery-form-dialog.tsx

@@ -0,0 +1,166 @@
+import type { UseFormReturn } from 'react-hook-form'
+import { Controller } from 'react-hook-form'
+import { useTranslation } from 'react-i18next'
+import { Button } from '../ui/button'
+import {
+  Combobox,
+  ComboboxButtonTrigger,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxItem,
+  ComboboxList,
+  ComboboxSearch,
+  ComboboxTriggerPlaceholder,
+  ComboboxValue,
+} from '../ui/combobox'
+import {
+  Dialog,
+  DialogBody,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '../ui/dialog'
+import { Field, FieldError, FieldLabel } from '../ui/field'
+import { Input } from '../ui/input'
+
+/** The form shape both panels bind for one consignment. */
+export type DeliveryFormFields = {
+  tracking_number: string
+  carrier: string
+}
+
+/**
+ * Records a tracked consignment on a parcel, or corrects one. A parcel can
+ * carry several — three boxes, or a freight PRO number covering a pallet —
+ * and each travels on its own carrier status.
+ *
+ * Shared by the operator's order page and the seller's. Headless: the caller
+ * owns the form and the submit, so each panel keeps its own mutation, while
+ * the carrier field's contract lives here — the value stored is the carrier's
+ * key rather than its display name, and anything off the list stays as typed
+ * because a forwarder's own name has to be enterable.
+ */
+export function DeliveryFormDialog({
+  form,
+  open,
+  onOpenChange,
+  editing,
+  carrierKeys,
+  carrierLabel,
+  onSubmit,
+  pending = false,
+}: {
+  form: UseFormReturn<DeliveryFormFields>
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  /** Correcting an existing consignment rather than adding one. */
+  editing: boolean
+  carrierKeys: string[]
+  carrierLabel: (key: string) => string
+  onSubmit: (values: DeliveryFormFields) => void | Promise<void>
+  pending?: boolean
+}) {
+  const { t } = useTranslation()
+  const { errors } = form.formState
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent>
+        <form
+          onSubmit={(event) => {
+            // The order page renders its cards inside their own forms — without
+            // stopping the bubble the browser submits the outer one.
+            form.handleSubmit(onSubmit)(event)
+            event.stopPropagation()
+          }}
+        >
+          <DialogHeader>
+            <DialogTitle>
+              {editing
+                ? t('admin.orders.detail.fulfillments.edit_tracking_title')
+                : t('admin.orders.detail.fulfillments.add_tracking_title')}
+            </DialogTitle>
+            <DialogDescription>
+              {t('admin.orders.detail.fulfillments.tracking_description')}
+            </DialogDescription>
+          </DialogHeader>
+
+          <DialogBody className="flex flex-col gap-4">
+            {errors.root?.message && (
+              <p className="text-destructive text-sm" role="alert">
+                {errors.root.message}
+              </p>
+            )}
+
+            <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
+              <Field>
+                <FieldLabel htmlFor="delivery-tracking-number">
+                  {t('admin.orders.fulfill.tracking_label')}
+                </FieldLabel>
+                <Input
+                  id="delivery-tracking-number"
+                  placeholder={t('admin.orders.fulfill.tracking_placeholder')}
+                  aria-invalid={!!errors.tracking_number}
+                  {...form.register('tracking_number')}
+                />
+                <FieldError errors={[errors.tracking_number]} />
+              </Field>
+
+              <Field>
+                <FieldLabel htmlFor="delivery-carrier">
+                  {t('admin.orders.detail.fulfillments.carrier_label')}
+                </FieldLabel>
+                <Controller
+                  control={form.control}
+                  name="carrier"
+                  render={({ field }) => (
+                    <Combobox
+                      items={carrierKeys}
+                      value={field.value}
+                      onValueChange={(value: string | null) => field.onChange(value ?? '')}
+                      itemToStringLabel={carrierLabel}
+                    >
+                      <ComboboxButtonTrigger id="delivery-carrier" onBlur={field.onBlur}>
+                        {field.value ? (
+                          <ComboboxValue />
+                        ) : (
+                          <ComboboxTriggerPlaceholder>
+                            {t('admin.orders.detail.fulfillments.carrier_auto')}
+                          </ComboboxTriggerPlaceholder>
+                        )}
+                      </ComboboxButtonTrigger>
+                      <ComboboxContent>
+                        <ComboboxSearch
+                          placeholder={t('admin.orders.detail.fulfillments.carrier_search')}
+                        />
+                        <ComboboxEmpty>{t('admin.common.no_results')}</ComboboxEmpty>
+                        <ComboboxList>
+                          {(value: string) => (
+                            <ComboboxItem key={value} value={value}>
+                              {carrierLabel(value)}
+                            </ComboboxItem>
+                          )}
+                        </ComboboxList>
+                      </ComboboxContent>
+                    </Combobox>
+                  )}
+                />
+              </Field>
+            </div>
+          </DialogBody>
+
+          <DialogFooter>
+            <Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
+              {t('admin.actions.cancel')}
+            </Button>
+            <Button type="submit" disabled={pending}>
+              {pending ? t('admin.actions.saving') : t('admin.actions.save')}
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  )
+}

package/src/spree/drag-handle.tsx

@@ -1,8 +1,8 @@
 import type { DraggableAttributes, DraggableSyntheticListeners } from '@dnd-kit/core'
-import { GripVerticalIcon } from 'lucide-react'
 import type { ComponentProps } from 'react'
 import { useTranslation } from 'react-i18next'
 import { cn } from '../lib/utils'
+import { GripVerticalIcon } from './icons'
 
 interface DragHandleProps extends Omit<ComponentProps<'button'>, 'type'> {
   /** `attributes` from `useSortable` / `useDraggable`. */
@@ -38,7 +38,7 @@ export function DragHandle({ attributes, listeners, className, ...props }: DragH
       type="button"
       aria-label={t('admin.a11y.drag_to_reorder')}
       className={cn(
-        'flex h-full w-full items-center justify-center rounded-lg p-2 text-muted-foreground cursor-grab active:cursor-grabbing hover:bg-accent',
+        'flex h-full w-full items-center justify-center rounded-lg p-2 text-muted-foreground cursor-grab active:cursor-grabbing hover:bg-accent-strong hover:text-accent-foreground',
         className,
       )}
       {...attributes}

package/src/spree/editable-note-card.tsx

@@ -0,0 +1,103 @@
+import type { ReactNode } from 'react'
+import { useTranslation } from 'react-i18next'
+import { Button } from '../ui/button'
+import { Card, CardAction, CardContent, CardHeader, CardTitle } from '../ui/card'
+import { PencilIcon } from './icons'
+
+/**
+ * A note on a record: shown as read-only text, edited in place behind a
+ * pencil, and reading "None" while empty.
+ *
+ * Shared by every note card on an order — the buyer's instructions, the
+ * merchant's own working note — so they cannot drift into different shapes.
+ * The editor itself comes from the caller, because a plain note and a
+ * rich-text one need different ones.
+ */
+export function EditableNoteCard({
+  title,
+  editing,
+  onEditingChange,
+  children,
+  editor,
+  onSave,
+  pending = false,
+}: {
+  title: string
+  editing: boolean
+  onEditingChange: (editing: boolean) => void
+  /** The read view. Falsy renders the empty state instead. */
+  children?: ReactNode
+  editor: ReactNode
+  onSave: () => void
+  pending?: boolean
+}) {
+  const { t } = useTranslation()
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>{title}</CardTitle>
+        <CardAction>
+          <Button
+            // Explicit: a card on the order page sits inside that page's own
+            // form, and a button with no type submits it.
+            type="button"
+            variant="ghost"
+            size="icon-sm"
+            onClick={() => onEditingChange(!editing)}
+            aria-label={t('admin.actions.edit')}
+          >
+            <PencilIcon className="size-4" />
+          </Button>
+        </CardAction>
+      </CardHeader>
+      <CardContent>
+        {editing ? (
+          <form
+            className="flex flex-col gap-3"
+            onSubmit={(event) => {
+              // The order page renders its cards inside their own forms —
+              // without stopping the bubble the browser submits the outer one.
+              event.preventDefault()
+              event.stopPropagation()
+              onSave()
+            }}
+          >
+            {editor}
+            <div className="flex justify-end gap-2">
+              <Button
+                type="button"
+                variant="outline"
+                size="sm"
+                onClick={() => onEditingChange(false)}
+              >
+                {t('admin.actions.cancel')}
+              </Button>
+              <Button type="submit" size="sm" disabled={pending}>
+                {pending ? t('admin.actions.saving') : t('admin.actions.save')}
+              </Button>
+            </div>
+          </form>
+        ) : (
+          (children ?? <p className="text-muted-foreground text-sm">{t('admin.common.none')}</p>)
+        )}
+      </CardContent>
+    </Card>
+  )
+}
+
+/** A plain-text note as it reads when not being edited. */
+export function NoteText({ value }: { value: string }) {
+  return <p className="whitespace-pre-wrap text-muted-foreground text-sm">{value}</p>
+}
+
+/** A rich-text note as it reads when not being edited. */
+export function NoteHtml({ html }: { html: string }) {
+  return (
+    <div
+      className="prose prose-sm dark:prose-invert max-w-none text-muted-foreground"
+      // biome-ignore lint/security/noDangerouslySetInnerHtml: HTML is sanitized server-side via the rich-text pipeline
+      dangerouslySetInnerHTML={{ __html: html }}
+    />
+  )
+}

package/src/spree/external-link.tsx

@@ -0,0 +1,56 @@
+import type * as React from 'react'
+import { cn } from '../lib/utils'
+import { ExternalLinkIcon } from './icons'
+
+/**
+ * A link that leaves the dashboard — documentation, a storefront, a carrier's
+ * tracking page, a provider's console.
+ *
+ * The trailing arrow is the point: it tells the reader this one opens a new tab
+ * before they click it, which a bare link cannot. Four hand-rolled versions of
+ * this had grown across the two panels, each with its own colour, gap and icon
+ * size, so a docs link looked like one thing next to a title and another inside
+ * a card.
+ *
+ * `rel="noopener noreferrer"` is not optional on a `_blank` link: without
+ * `noopener` the opened page can reach back through `window.opener` and
+ * navigate this one. `target` and `rel` are therefore not part of the public
+ * props — a caller cannot spread them back in and undo the isolation.
+ */
+export function ExternalLink({
+  className,
+  children,
+  // Pulled out of `props` so they cannot be spread back in below, and typed
+  // `never` so a caller is told at compile time too. Types alone would not be
+  // enough: they vanish at runtime, so an untyped caller or a plain-JS
+  // consumer of this source-shipped package could still land its own
+  // `target`/`rel` after ours and undo the isolation.
+  target: _target,
+  rel: _rel,
+  ...props
+}: Omit<React.ComponentProps<'a'>, 'target' | 'rel'> & {
+  href: string
+  target?: never
+  rel?: never
+}) {
+  return (
+    <a
+      data-slot="external-link"
+      target="_blank"
+      rel="noopener noreferrer"
+      className={cn(
+        // `--link` rather than the accent: this is body-copy text, and the
+        // accent fails 4.5:1 on both the card and the page.
+        'inline-flex items-center gap-1 text-link transition-colors duration-100 ease-out hover:text-link-hover',
+        // Sized relative to the text it sits in, so the arrow stays in
+        // proportion whether the link is in a heading or a caption.
+        '[&>svg]:size-[1em] [&>svg]:shrink-0',
+        className,
+      )}
+      {...props}
+    >
+      {children}
+      <ExternalLinkIcon aria-hidden />
+    </a>
+  )
+}

package/src/spree/file-type-icon.tsx

@@ -0,0 +1,68 @@
+import type { ComponentType } from 'react'
+import {
+  FileArchiveIcon,
+  FileAudioIcon,
+  FileCodeIcon,
+  FileIcon,
+  FileImageIcon,
+  FileSpreadsheetIcon,
+  FileTextIcon,
+  FileVideoIcon,
+} from './icons'
+
+type IconComponent = ComponentType<{ className?: string }>
+
+// Matched on the MIME type where it is specific enough, then on the extension —
+// servers routinely hand back `application/octet-stream` for anything they do
+// not recognise, which would otherwise flatten every row to a blank page icon.
+const BY_SUBTYPE: Array<[RegExp, IconComponent]> = [
+  [/^image\//, FileImageIcon],
+  [/^audio\//, FileAudioIcon],
+  [/^video\//, FileVideoIcon],
+  [/(zip|compressed|tar|gzip|rar|7z)/, FileArchiveIcon],
+  [/(spreadsheet|excel|csv)/, FileSpreadsheetIcon],
+  [/(json|xml|javascript|typescript|html|x-ruby|x-python|x-sh)/, FileCodeIcon],
+  [/(pdf|word|document|text|rtf|epub)/, FileTextIcon],
+]
+
+const BY_EXTENSION: Array<[RegExp, IconComponent]> = [
+  [/\.(png|jpe?g|gif|webp|svg|avif|heic|tiff?)$/i, FileImageIcon],
+  [/\.(mp3|wav|flac|aac|ogg|m4a|aiff?)$/i, FileAudioIcon],
+  [/\.(mp4|mov|avi|mkv|webm|m4v)$/i, FileVideoIcon],
+  [/\.(zip|rar|7z|tar|gz|bz2|dmg|iso)$/i, FileArchiveIcon],
+  [/\.(csv|tsv|xlsx?|numbers|ods)$/i, FileSpreadsheetIcon],
+  [/\.(json|xml|ya?ml|js|ts|tsx|rb|py|sh|css|html?)$/i, FileCodeIcon],
+  [/\.(pdf|docx?|txt|rtf|md|epub|pages)$/i, FileTextIcon],
+]
+
+/**
+ * Picks the icon for a downloadable file. Falls back to a plain page rather
+ * than guessing, so an unknown type reads as "a file" instead of the wrong one.
+ */
+export function fileTypeIcon(filename?: string | null, contentType?: string | null): IconComponent {
+  const type = contentType?.toLowerCase() ?? ''
+  for (const [pattern, icon] of BY_SUBTYPE) {
+    if (pattern.test(type)) return icon
+  }
+
+  const name = filename ?? ''
+  for (const [pattern, icon] of BY_EXTENSION) {
+    if (pattern.test(name)) return icon
+  }
+
+  return FileIcon
+}
+
+/** Convenience wrapper for the common `<FileTypeIcon .../>` call site. */
+export function FileTypeIcon({
+  filename,
+  contentType,
+  className,
+}: {
+  filename?: string | null
+  contentType?: string | null
+  className?: string
+}) {
+  const Icon = fileTypeIcon(filename, contentType)
+  return <Icon className={className} />
+}

package/src/spree/form-actions.tsx

@@ -1,9 +1,9 @@
 import { useHotkey } from '@tanstack/react-hotkeys'
-import { Loader2Icon } from 'lucide-react'
 import { useEffect } from 'react'
 import { type FieldValues, type UseFormReturn, useFormState } from 'react-hook-form'
 import { useTranslation } from 'react-i18next'
 import { Button } from '../ui/button'
+import { Loader2Icon } from './icons'
 
 /**
  * Submit button wired to a `react-hook-form` instance. Always rendered,
@@ -31,7 +31,7 @@ export function FormSaveButton<TFieldValues extends FieldValues>({
   const { isDirty, isSubmitting } = useFormState({ control: form.control })
 
   return (
-    <Button type="submit" size="sm" disabled={!isDirty || isSubmitting}>
+    <Button type="submit" disabled={!isDirty || isSubmitting}>
       {isSubmitting && <Loader2Icon className="animate-spin" />}
       {isSubmitting
         ? (savingLabel ?? t('admin.actions.saving'))
@@ -65,7 +65,6 @@ export function FormDiscardButton<TFieldValues extends FieldValues>({
   return (
     <Button
       type="button"
-      size="sm"
       variant="outline"
       disabled={isSubmitting}
       onClick={onDiscard ?? (() => form.reset())}

package/src/spree/form-section.tsx

@@ -0,0 +1,46 @@
+import type { ReactNode } from 'react'
+import { FieldGroup, FieldLegend, FieldSet } from '../ui/field'
+
+interface FormSectionProps {
+  /** Names the group. Rendered as a legend, so it labels the fields inside it
+   *  rather than merely preceding them. */
+  title?: string
+  description?: string
+  /** Right-aligned beside the title — an "Add" button, a count, a toggle. */
+  action?: ReactNode
+  children: ReactNode
+}
+
+/**
+ * A titled group of form fields.
+ *
+ * Built on FieldSet/FieldLegend rather than a heading beside a div: a heading
+ * only precedes the inputs, while a legend is announced as the group they
+ * belong to — the difference between "Pickup" read once and every control
+ * under it being understood as part of pickup.
+ */
+export function FormSection({ title, description, action, children }: FormSectionProps) {
+  const hasHeading = title || description || action
+
+  return (
+    <FieldSet className="gap-3">
+      {hasHeading && (
+        <div className="flex items-start justify-between gap-2">
+          <div className="flex flex-col gap-0.5">
+            {title && (
+              <FieldLegend variant="label" className="mb-0">
+                {title}
+              </FieldLegend>
+            )}
+            {description && <p className="text-muted-foreground text-xs">{description}</p>}
+          </div>
+          {action}
+        </div>
+      )}
+      {/* The group paints the card that separates one section from the next.
+          Sections are siblings, never nested, so no card ever sits inside
+          another. */}
+      <FieldGroup>{children}</FieldGroup>
+    </FieldSet>
+  )
+}