@spree/dashboard-ui 0.13.0 → 1.0.0-beta.1

package/src/spree/product-membership-list.tsx

@@ -0,0 +1,453 @@
+import {
+  closestCenter,
+  DndContext,
+  type DragEndEvent,
+  KeyboardSensor,
+  PointerSensor,
+  useSensor,
+  useSensors,
+} from '@dnd-kit/core'
+import {
+  arrayMove,
+  SortableContext,
+  sortableKeyboardCoordinates,
+  useSortable,
+  verticalListSortingStrategy,
+} from '@dnd-kit/sortable'
+import { CSS } from '@dnd-kit/utilities'
+import { Fragment, type ReactNode, useEffect, useMemo, useState } from 'react'
+import { cn } from '../lib/utils'
+import { Badge } from '../ui/badge'
+import { Button } from '../ui/button'
+import { Checkbox } from '../ui/checkbox'
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '../ui/data-table'
+import { Pagination, type PaginationMeta } from '../ui/pagination'
+import { Thumbnail } from '../ui/thumbnail'
+import { DragHandle } from './drag-handle'
+import { Undo2Icon, XIcon } from './icons'
+import { SearchInput } from './search-input'
+
+/** One product row in a membership list. */
+/**
+ * How many cells a sub-row must emit before and after the extra columns to
+ * line up with the product rows above it. Reported by the list rather than
+ * counted by the caller, since the leading cells depend on whether the list
+ * is curatable and reorderable.
+ */
+export interface SubRowLayout {
+  /** Cells before the product-name column (selection checkbox, drag handle). */
+  leadingCells: number
+  /** How many extra columns the caller's own `extraColumns` set contributes. */
+  extraColumnCount: number
+  /** Cells after the extra columns (the row-action column). */
+  trailingCells: number
+}
+
+export interface ProductMembershipRow {
+  id: string
+  name?: string | null
+  thumbnailUrl?: string | null
+  /**
+   * Deferred-editing state: `added` rows are staged locally and not yet
+   * persisted (badged, not draggable); `removed` rows are struck through and
+   * their remove button becomes a restore.
+   */
+  pending?: 'added' | 'removed'
+}
+
+/** All user-visible copy, so the component stays free of locale namespaces. */
+export interface ProductMembershipListLabels {
+  filterPlaceholder: string
+  clearFilter: string
+  noMatches: string
+  empty: string
+  loading: string
+  columnProduct: string
+  selectAll: string
+  selectRow: string
+  remove: string
+  /** Required when any row can be `pending: 'removed'`. */
+  restore?: string
+  /** Badge on `pending: 'added'` rows. */
+  pendingAddedBadge?: string
+}
+
+export interface ProductMembershipListProps {
+  rows: ProductMembershipRow[]
+  labels: ProductMembershipListLabels
+  loading?: boolean
+  meta?: PaginationMeta | null
+  onPageChange?: (page: number) => void
+  /** Hides checkboxes, drag handles and remove buttons. */
+  readOnly?: boolean
+  /** Controlled selection — the host renders the bulk actions that consume it. */
+  selected?: string[]
+  onSelectedChange?: (ids: string[]) => void
+  onRemove?: (id: string) => void
+  onRestore?: (id: string) => void
+  /** Enables drag-to-reorder. Filtered views never reorder. */
+  reorderable?: boolean
+  /**
+   * Persist a drag. `position` is the 0-based index across the whole set
+   * (page offset already applied). A rejected promise rolls the row back.
+   */
+  onReorder?: (id: string, position: number) => Promise<unknown> | undefined
+  /** Row title cell — pass a link to the product page; defaults to plain text. */
+  renderTitle?: (row: ProductMembershipRow) => ReactNode
+  /**
+   * Extra columns between the product name and the remove button, for a
+   * parent whose membership carries data of its own — a catalog's quantity
+   * terms, say. Headers and cells are passed separately so the host stays in
+   * charge of what a row means to it; both must return the same number of
+   * cells or the table misaligns.
+   */
+  /**
+   * Rows rendered beneath a product's own, spanning the same columns — a
+   * catalog lists each variant's price this way, since one figure on the
+   * product row names a single variant's deal and hides the others
+   * (docs/plans/6.0-volume-pricing.md). Omitted by every other consumer, so
+   * their rows are unchanged.
+   */
+  renderSubRows?: (row: ProductMembershipRow, layout: SubRowLayout) => ReactNode
+  extraColumns?: {
+    /**
+     * How many columns this set contributes. Stated rather than counted from
+     * the rendered headers, so a sub-row can span the columns it does not
+     * fill without the table coming up short.
+     */
+    columnCount?: number
+    headers: ReactNode
+    renderCells: (row: ProductMembershipRow) => ReactNode
+  }
+}
+
+/**
+ * The shared membership table for "products in a grouping" panels —
+ * categories, collections, catalogs, price lists. Headless: rows, selection
+ * and every mutation come through props; the host owns data fetching, the
+ * picker, confirms and save semantics (immediate writes or form state).
+ *
+ * Renders the client-side quick filter, the selectable rows with thumbnails,
+ * optional drag-to-reorder with optimistic rollback, and pagination.
+ */
+export function ProductMembershipList({
+  rows,
+  labels,
+  loading = false,
+  meta,
+  onPageChange,
+  readOnly = false,
+  selected = [],
+  onSelectedChange,
+  onRemove,
+  onRestore,
+  reorderable = false,
+  onReorder,
+  renderTitle,
+  renderSubRows,
+  extraColumns,
+}: ProductMembershipListProps) {
+  const [query, setQuery] = useState('')
+
+  // Local order mirrors the incoming rows so a drag re-renders instantly;
+  // a resolved onReorder re-syncs through the next rows prop.
+  const [order, setOrder] = useState<ProductMembershipRow[]>(rows)
+
+  useEffect(() => {
+    setOrder(rows)
+  }, [rows])
+
+  const sensors = useSensors(
+    useSensor(PointerSensor, { activationConstraint: { distance: 5 } }),
+    useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates }),
+  )
+
+  const ids = useMemo(() => order.map((row) => row.id), [order])
+
+  // Client-side quick filter over the current page. While a filter is active,
+  // drag-reorder is disabled — reordering a filtered subset would compute
+  // positions against the wrong neighbours.
+  const trimmedQuery = query.trim().toLowerCase()
+  const filtering = trimmedQuery.length > 0
+  const visible = useMemo(
+    () =>
+      filtering
+        ? order.filter((row) => (row.name ?? '').toLowerCase().includes(trimmedQuery))
+        : order,
+    [order, filtering, trimmedQuery],
+  )
+
+  // Rows a checkbox makes sense for — pending removals restore instead.
+  const selectableIds = useMemo(
+    () => visible.filter((row) => row.pending !== 'removed').map((row) => row.id),
+    [visible],
+  )
+  const selectedSet = useMemo(() => new Set(selected), [selected])
+  const allSelected = selectableIds.length > 0 && selectableIds.every((id) => selectedSet.has(id))
+
+  function toggleSelected(id: string) {
+    if (!onSelectedChange) return
+    onSelectedChange(
+      selectedSet.has(id) ? selected.filter((existing) => existing !== id) : [...selected, id],
+    )
+  }
+
+  // Operate only on the currently-visible (filtered) rows so "select all"
+  // never pulls in hidden products a later bulk action would touch unseen.
+  function toggleAll() {
+    if (!onSelectedChange) return
+    if (allSelected) {
+      const visibleSet = new Set(selectableIds)
+      onSelectedChange(selected.filter((id) => !visibleSet.has(id)))
+    } else {
+      onSelectedChange([...new Set([...selected, ...selectableIds])])
+    }
+  }
+
+  function handleDragEnd(event: DragEndEvent) {
+    const { active, over } = event
+    if (!over || active.id === over.id || !onReorder) return
+    const from = order.findIndex((row) => row.id === active.id)
+    const to = order.findIndex((row) => row.id === over.id)
+    if (from === -1 || to === -1) return
+    const previousOrder = order
+    setOrder(arrayMove(order, from, to)) // optimistic
+    // `to` is an index within the current page; the caller wants a 0-based
+    // index across the whole grouping. `meta.from` is 1-based.
+    const result = onReorder(String(active.id), (meta?.from ?? 1) - 1 + to)
+    Promise.resolve(result).catch(() => setOrder(previousOrder))
+  }
+
+  const curatable = !readOnly
+
+  // The leading cells are conditional, so the list states the shape rather
+  // than leaving each caller to re-derive it and drift.
+  const subRowLayout: SubRowLayout = {
+    leadingCells: (curatable ? 1 : 0) + (reorderable ? 1 : 0),
+    extraColumnCount: extraColumns?.columnCount ?? 0,
+    trailingCells: 1,
+  }
+
+  if (loading) {
+    return <p className="p-6 text-muted-foreground text-sm">{labels.loading}</p>
+  }
+
+  if (order.length === 0) {
+    return <p className="p-6 text-muted-foreground text-sm">{labels.empty}</p>
+  }
+
+  return (
+    <>
+      <div className="border-border-subtle border-b p-3">
+        <SearchInput
+          value={query}
+          onValueChange={setQuery}
+          onKeyDown={(e) => e.key === 'Enter' && e.preventDefault()}
+          placeholder={labels.filterPlaceholder}
+          clearLabel={labels.clearFilter}
+        />
+      </div>
+      {visible.length === 0 ? (
+        <p className="p-6 text-muted-foreground text-sm">{labels.noMatches}</p>
+      ) : (
+        <DndContext sensors={sensors} collisionDetection={closestCenter} onDragEnd={handleDragEnd}>
+          <Table>
+            <TableHeader>
+              <TableRow>
+                {curatable && (
+                  <TableHead className="w-10">
+                    <Checkbox
+                      checked={allSelected}
+                      onCheckedChange={toggleAll}
+                      aria-label={labels.selectAll}
+                    />
+                  </TableHead>
+                )}
+                {reorderable && <TableHead className="w-8" />}
+                {/* `w-full max-w-0`: table layout sizes a column to its
+                    content, so a long product or variant name would push the
+                    columns beside it out of the card — which clips them
+                    rather than scrolling. This makes the product column take
+                    whatever is left instead, and its content truncate. */}
+                <TableHead className="w-full max-w-0">{labels.columnProduct}</TableHead>
+                {extraColumns?.headers}
+                <TableHead className="w-10" />
+              </TableRow>
+            </TableHeader>
+            <SortableContext items={ids} strategy={verticalListSortingStrategy}>
+              {/* No border-t: TableHead draws the rule as an inset shadow,
+                  and a border alongside it stacks into a 2px line. */}
+              <TableBody>
+                {visible.map((row) => (
+                  <MembershipRow
+                    key={row.id}
+                    row={row}
+                    curatable={curatable}
+                    // Reorder only makes sense over the full page of settled
+                    // rows; staged rows have no position yet.
+                    reorderable={reorderable && curatable && !filtering && !row.pending}
+                    showDragColumn={reorderable}
+                    selected={selectedSet.has(row.id)}
+                    onToggleSelected={() => toggleSelected(row.id)}
+                    onRemove={onRemove ? () => onRemove(row.id) : undefined}
+                    onRestore={onRestore ? () => onRestore(row.id) : undefined}
+                    labels={labels}
+                    renderTitle={renderTitle}
+                    extraCells={extraColumns?.renderCells(row)}
+                    subRows={renderSubRows?.(row, subRowLayout)}
+                  />
+                ))}
+              </TableBody>
+            </SortableContext>
+          </Table>
+        </DndContext>
+      )}
+      {/* Pagination brings its own top border + padding. */}
+      {meta && onPageChange && <Pagination meta={meta} onPageChange={onPageChange} />}
+    </>
+  )
+}
+
+function MembershipRow({
+  row,
+  curatable,
+  reorderable,
+  showDragColumn,
+  selected,
+  onToggleSelected,
+  onRemove,
+  onRestore,
+  labels,
+  renderTitle,
+  extraCells,
+  subRows,
+}: {
+  row: ProductMembershipRow
+  curatable: boolean
+  reorderable: boolean
+  showDragColumn: boolean
+  selected: boolean
+  onToggleSelected: () => void
+  onRemove?: () => void
+  onRestore?: () => void
+  labels: ProductMembershipListLabels
+  renderTitle?: (row: ProductMembershipRow) => ReactNode
+  extraCells?: ReactNode
+  subRows?: ReactNode
+}) {
+  const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({
+    id: row.id,
+    disabled: !reorderable,
+  })
+
+  const removed = row.pending === 'removed'
+  const added = row.pending === 'added'
+
+  return (
+    <>
+      <tr
+        ref={setNodeRef}
+        style={{ transform: CSS.Transform.toString(transform), transition }}
+        // Mirror <TableRow> styling — a plain <tr> is required so dnd-kit's
+        // setNodeRef attaches (TableRow doesn't forward refs).
+        className={cn(
+          'group/row last:*:border-b-0 hover:bg-accent-strong/50',
+          selected && 'bg-accent-strong/75 hover:bg-accent-strong-hover',
+          isDragging && 'relative z-10 opacity-70',
+          removed && 'opacity-60',
+        )}
+      >
+        {curatable && (
+          <TableCell>
+            {!removed && (
+              <Checkbox
+                checked={selected}
+                onCheckedChange={onToggleSelected}
+                aria-label={labels.selectRow}
+              />
+            )}
+          </TableCell>
+        )}
+        {showDragColumn && (
+          <TableCell className="pr-0">
+            {reorderable && <DragHandle attributes={attributes} listeners={listeners} />}
+          </TableCell>
+        )}
+        <TableCell className="max-w-0">
+          <span className={cn('flex min-w-0 items-center gap-3', removed && 'line-through')}>
+            <Thumbnail src={row.thumbnailUrl} size="sm" />
+            {renderTitle ? renderTitle(row) : <span className="truncate text-sm">{row.name}</span>}
+            {added && labels.pendingAddedBadge && (
+              <Badge variant="secondary">{labels.pendingAddedBadge}</Badge>
+            )}
+          </span>
+        </TableCell>
+        {extraCells}
+        <TableCell className="text-right">
+          {curatable &&
+            (removed
+              ? onRestore && (
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="icon"
+                    onClick={onRestore}
+                    aria-label={labels.restore ?? labels.remove}
+                  >
+                    <Undo2Icon className="size-4" />
+                  </Button>
+                )
+              : onRemove && (
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="icon"
+                    onClick={onRemove}
+                    aria-label={labels.remove}
+                  >
+                    <XIcon className="size-4" />
+                  </Button>
+                ))}
+        </TableCell>
+      </tr>
+      {/* Sub-rows sit outside the sortable <tr> so dragging a product still
+        moves one row, and so a removed product's rows dim with it. */}
+      {!removed && subRows}
+    </>
+  )
+}
+
+/**
+ * Renders several `extraColumns` sets side by side, for a parent whose rows
+ * carry more than one kind of data — a catalog states both what it charges for
+ * a product and what quantities it may be ordered in.
+ *
+ * Composed here rather than at each call site because the contract being kept
+ * is this file's: every set must emit the same number of header cells as body
+ * cells, or the table misaligns.
+ */
+export function mergeExtraColumns(
+  ...sets: NonNullable<ProductMembershipListProps['extraColumns']>[]
+): NonNullable<ProductMembershipListProps['extraColumns']> {
+  return {
+    columnCount: sets.reduce((total, set) => total + (set.columnCount ?? 0), 0),
+    headers: (
+      <>
+        {sets.map((set, index) => (
+          // Column sets are positional and fixed for the life of the table —
+          // there is no identity to key on but their order.
+          // biome-ignore lint/suspicious/noArrayIndexKey: positional by nature
+          <Fragment key={index}>{set.headers}</Fragment>
+        ))}
+      </>
+    ),
+    renderCells: (row: ProductMembershipRow) => (
+      <>
+        {sets.map((set, index) => (
+          // biome-ignore lint/suspicious/noArrayIndexKey: positional by nature
+          <Fragment key={index}>{set.renderCells(row)}</Fragment>
+        ))}
+      </>
+    ),
+  }
+}

package/src/spree/products/status-card.tsx

@@ -0,0 +1,79 @@
+import type * as React from 'react'
+import type { Control, FieldValues, Path } from 'react-hook-form'
+import { Controller } from 'react-hook-form'
+import { Card, CardContent, CardHeader, CardTitle } from '../../ui/card'
+import { Field, FieldLabel } from '../../ui/field'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../../ui/select'
+
+export type StatusOption = { value: string; label: string }
+
+/**
+ * The product's status, chosen from whatever the caller allows.
+ *
+ * The options are a prop rather than a constant because the two dashboards
+ * offer different ones: an operator publishes directly, while a seller submits
+ * for review and can only take a listing back down. Headless, so the labels
+ * arrive translated.
+ */
+export function StatusCard<TFieldValues extends FieldValues>({
+  control,
+  name,
+  title,
+  label,
+  options,
+  disabled,
+  description,
+  actions,
+}: {
+  control: Control<TFieldValues>
+  name: Path<TFieldValues>
+  title: string
+  label: string
+  options: StatusOption[]
+  disabled?: boolean
+  description?: string
+  /**
+   * Rendered under the field. The moves out of a status this picker cannot
+   * assign live here — a review decision is a mutation, which the panel owns
+   * rather than the design system.
+   */
+  actions?: React.ReactNode
+}) {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>{title}</CardTitle>
+      </CardHeader>
+      <CardContent className="flex flex-col gap-4">
+        <Field>
+          <FieldLabel>{label}</FieldLabel>
+          <Controller
+            name={name}
+            control={control}
+            render={({ field }) => (
+              <Select
+                items={options as never}
+                value={field.value}
+                onValueChange={field.onChange}
+                disabled={disabled}
+              >
+                <SelectTrigger className="w-full">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  {options.map((option) => (
+                    <SelectItem key={option.value} value={option.value}>
+                      {option.label}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            )}
+          />
+          {description && <p className="text-muted-foreground text-sm">{description}</p>}
+        </Field>
+        {actions && <div className="flex flex-wrap gap-2">{actions}</div>}
+      </CardContent>
+    </Card>
+  )
+}

package/src/spree/quantity-tier-editor.tsx

@@ -0,0 +1,162 @@
+import { PlusIcon, XIcon } from 'lucide-react'
+import { Button } from '../ui/button'
+import { Input } from '../ui/input'
+import { InputGroup, InputGroupAddon, InputGroupInput } from '../ui/input-group'
+
+/**
+ * One rung of a quantity ladder: from `minQuantity` units up, the value is
+ * `value`. What the value means is the caller's business — a unit price on a
+ * price row, a percentage on a list's adjustment.
+ */
+export interface QuantityTierRow {
+  /** Stable key for React. The caller owns it; a client-side id is fine. */
+  id: string
+  /** The quantity this rung applies from, as typed. */
+  minQuantity: string
+  /** The rung's figure, as typed. */
+  value: string
+  /**
+   * Locked rungs render their quantity read-only. Used for the bottom rung of
+   * a price ladder, which is the list's ordinary price and always quantity 1.
+   */
+  locked?: boolean
+}
+
+export interface QuantityTierEditorLabels {
+  /** Column header over the quantity inputs. */
+  quantity: string
+  /** Column header over the value inputs. */
+  value: string
+  /** The "add a rung" button. */
+  add: string
+  /** Accessible name for a rung's remove button. `{quantity}` is substituted. */
+  remove: string
+  /** Shown in place of the rows when the ladder is empty. */
+  empty?: string
+  /** Shown under the rows — a validation message, or a hint. */
+  hint?: string
+}
+
+export interface QuantityTierEditorProps {
+  rows: QuantityTierRow[]
+  labels: QuantityTierEditorLabels
+  onChange: (id: string, field: 'minQuantity' | 'value', next: string) => void
+  onAdd: () => void
+  onRemove: (id: string) => void
+  /** Prefix or suffix rendered inside the value input — a currency symbol, a `%`. */
+  valueAddon?: string
+  /** Which side the addon sits on. Defaults to a leading addon. */
+  valueAddonAlign?: 'inline-start' | 'inline-end'
+  /** Hides "add" once the ladder is full, so the cap is visible rather than a surprise. */
+  canAdd?: boolean
+  disabled?: boolean
+  /** Rendered in destructive styling under the rows. */
+  error?: string
+}
+
+/**
+ * The `[Min qty | value]` ladder both halves of volume pricing are edited
+ * through: fixed breaks on a variant's price rows, and quantity bands on a
+ * price list's percentage (docs/plans/6.0-volume-pricing.md).
+ *
+ * Headless — it holds no state, fetches nothing and knows no translations.
+ * The caller owns the rows and every string.
+ */
+export function QuantityTierEditor({
+  rows,
+  labels,
+  onChange,
+  onAdd,
+  onRemove,
+  valueAddon,
+  valueAddonAlign = 'inline-start',
+  canAdd = true,
+  disabled,
+  error,
+}: QuantityTierEditorProps) {
+  return (
+    <div className="flex flex-col gap-2">
+      {rows.length === 0 ? (
+        labels.empty ? (
+          <p className="text-xs text-muted-foreground">{labels.empty}</p>
+        ) : null
+      ) : (
+        <div className="flex flex-col gap-1.5">
+          <div className="flex items-center gap-2 text-xs text-muted-foreground">
+            <span className="w-24">{labels.quantity}</span>
+            <span className="flex-1">{labels.value}</span>
+            <span className="w-8" />
+          </div>
+          {rows.map((row) => (
+            <div key={row.id} className="flex items-center gap-2">
+              <Input
+                type="number"
+                step="1"
+                min="1"
+                className="w-24"
+                value={row.minQuantity}
+                readOnly={row.locked}
+                disabled={disabled}
+                aria-label={labels.quantity}
+                onChange={(event) => onChange(row.id, 'minQuantity', event.target.value)}
+              />
+              <InputGroup className="flex-1">
+                {valueAddon && valueAddonAlign === 'inline-start' && (
+                  <InputGroupAddon>{valueAddon}</InputGroupAddon>
+                )}
+                <InputGroupInput
+                  type="number"
+                  step="0.01"
+                  value={row.value}
+                  disabled={disabled}
+                  aria-label={labels.value}
+                  onChange={(event) => onChange(row.id, 'value', event.target.value)}
+                />
+                {valueAddon && valueAddonAlign === 'inline-end' && (
+                  <InputGroupAddon align="inline-end">{valueAddon}</InputGroupAddon>
+                )}
+              </InputGroup>
+              {/* The bottom rung is the ordinary price, not a tier — removing
+                  it would be removing the price itself. */}
+              {row.locked ? (
+                <span className="w-8" />
+              ) : (
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="icon"
+                  className="size-8 shrink-0"
+                  disabled={disabled}
+                  aria-label={labels.remove.replace('{quantity}', row.minQuantity)}
+                  onClick={() => onRemove(row.id)}
+                >
+                  <XIcon className="size-4" />
+                </Button>
+              )}
+            </div>
+          ))}
+        </div>
+      )}
+
+      {canAdd && (
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          className="self-start"
+          disabled={disabled}
+          onClick={onAdd}
+        >
+          <PlusIcon className="size-4" />
+          {labels.add}
+        </Button>
+      )}
+
+      {error ? (
+        <p className="text-xs text-destructive">{error}</p>
+      ) : labels.hint ? (
+        <p className="text-xs text-muted-foreground">{labels.hint}</p>
+      ) : null}
+    </div>
+  )
+}