Skip to content
View as Markdown

DocumentProgressCard ​

DocumentProgressCard is a generic, presentational card for communicating the lifecycle/fulfilment state of a document in a record detail right rail. It shows an optional completion percentage, a stacked progress bar, and a legend — driven by an arbitrary set of status segments.

It is view-only and domain-agnostic: pass the segments and an explicit percent. Any domain-specific math — deriving the percentage, or decomposing overlapping buckets into bar segments — lives in the consumer. See Example: purchase-order fulfilment for a complete, copyable pattern.

Import ​

tsx
import { DocumentProgressCard } from "@tailor-platform/app-shell";

Basic Usage ​

tsx
function BasicUsage() {
  return (
    <DocumentProgressCard
      title="Shipment status"
      percent={60}
      segments={[
        { label: "Shipped", value: 30, color: "green" },
        { label: "Returned", value: 3, color: "red" },
        { label: "Pending", value: 17, color: "neutral" },
      ]}
    />
  );
}

Props ​

Generated from the type surface — first-party props only.

DocumentProgressCardProps ​

PropTypeDefaultDescription
className?string-Additional CSS classes for the card root.
legend?DocumentProgressSegment[]-Legend rows. Defaults to segments. Provide this only when the legend should differ from the bar (e.g. overlapping buckets shown distinctly).
percent?number-Headline percentage shown top-right (0–100). Optional and explicit — the generic card has no notion of "complete", so the consumer supplies it.
segmentsDocumentProgressSegment[]-Status segments rendered as a single stacked bar (and, by default, the legend).
title?ReactNode-Optional card title shown top-left.
total?number-Denominator used to size the bar. Defaults to the sum of segment values (the bar is fully tiled). A larger value leaves an unfilled track remainder.

Exports ​

  • DocumentProgressCard — function
  • DocumentProgressCardProps — interface

DocumentProgressSegment ​

FieldTypeDescription
labelstringLegend label.
valuenumberAmount — shown in the legend and used to size the bar.
colorDocumentProgressColorBar / marker color (required).

DocumentProgressColor is one of: "indigo", "pink", "green", "amber", "red", "blue", "neutral".

Progress Bar ​

The bar tiles segments left-to-right, each sized as value / (total ?? sum of values). When total exceeds the segment sum, the shortfall renders as an empty bg-muted track — useful for a "remaining" portion you don't want as a colored segment. A "neutral" segment reads as a muted/track-like fill.

Legend ​

By default the legend mirrors segments. Pass legend to render different rows — for example when buckets overlap and the bar shows a decomposition while the legend shows the raw figures:

tsx
function CustomLegend() {
  return (
    <DocumentProgressCard
      title="Receiving status"
      percent={30}
      total={40}
      segments={[
        { label: "Net received", value: 10, color: "indigo" },
        { label: "Returned", value: 2, color: "pink" },
      ]}
      legend={[
        { label: "Received items", value: 12, color: "indigo" },
        { label: "Returned items", value: 2, color: "pink" },
        { label: "Yet to receive", value: 28, color: "neutral" },
      ]}
    />
  );
}

Example: purchase-order fulfilment ​

A common use is communicating a purchase order's receiving state — received, returned, and yet to receive. DocumentProgressCard stays generic, so derive the percentage and the bar breakdown in your component and pass them in. This recipe reproduces the recommended look (labels, indigo/pink/neutral colors, and a bar that decomposes received into "kept" + "returned" against the ordered total):

tsx
function PurchaseOrderFulfilment() {
  function Fulfilment({
    received,
    returned,
    yetToReceive,
    returnedCountsAsComplete = true,
  }: {
    received: number;
    returned: number;
    yetToReceive: number;
    returnedCountsAsComplete?: boolean;
  }) {
    // Returned is a subset of received; clamp so the breakdown cannot exceed it.
    const effectiveReturned = Math.min(Math.max(returned, 0), Math.max(received, 0));
    const total = Math.max(received, 0) + Math.max(yetToReceive, 0);
    const complete = returnedCountsAsComplete ? received : received - effectiveReturned;
    const percent = total > 0 ? Math.round((complete / total) * 100) : 0;

    return (
      <DocumentProgressCard
        title={
          returnedCountsAsComplete ? "Returns count as fulfilled" : "Returns reduce fulfilment"
        }
        percent={percent}
        total={total}
        segments={[
          { label: "Received items", value: received - effectiveReturned, color: "indigo" },
          { label: "Returned items", value: effectiveReturned, color: "pink" },
        ]}
        legend={[
          { label: "Received items", value: received, color: "indigo" },
          { label: "Returned items", value: returned, color: "pink" },
          { label: "Yet to receive", value: yetToReceive, color: "neutral" },
        ]}
      />
    );
  }

  return (
    <div className="grid gap-4 md:grid-cols-2">
      <Fulfilment received={12} returned={2} yetToReceive={28} />
      <Fulfilment received={12} returned={2} yetToReceive={28} returnedCountsAsComplete={false} />
    </div>
  );
}

Notes for adapting it:

  • Colors: indigo (received), pink (returned), neutral (yet to receive) is the recommended set; swap any of the seven palette colors to fit your domain.
  • Bar vs. legend: the bar uses received − returned so the two colored segments don't double-count the returned items, while the legend override keeps "Received items" showing the full received figure.
  • total: pass the ordered quantity so the unfilled portion of the bar represents "yet to receive". Omit it (or use the segment sum) if you want a fully-tiled bar instead.
  • Percentage policy: flip returnedCountsAsComplete to decide whether returned items count toward completion.

Input handling ​

Segment values are expected to be non-negative numbers. Non-finite or negative values are coerced to 0, and percent is rounded and clamped to [0, 100].

  • MetricCard — Compact KPI summary card.
  • Card — The underlying card primitive.