Skip to Content
BBRICKSv0.7.4
PR PortalGifts

GiftShipmentTimeline

The shipment page's Timeline card (the mock's tl rows): Sent by brand (or "Recorded by <name>"), Arrived, Confirmed, each with its date and detail, or a dash ("Not yet" to a screen reader) while it has not happened.

import { GiftShipmentTimeline } from '@ergasti/bricks';

Examples

Count a shipment that is expected: tick a product that arrived in full ("All 40 OK") or enter the good and damaged units, then the boxes received

onConfirm gets whole numbers only.

Code
import { useState } from 'react';
import { GiftShipmentCard, type GiftCount } from '@ergasti/bricks';

function CountWhatArrived() {
  const [last, setLast] = useState<GiftCount | null>(null);
  return (
    <div style={{ display: 'grid', gap: 10 }}>
      <GiftShipmentCard brand="Glow Lab" state="expected" lines={[{ id: 'powder', product: 'Face powder', claimed: 40 }]} claimedBoxes={2} onConfirm={setLast} />
      <small>{last ? `Confirmed: ${last.lines[0].good} good, ${last.lines[0].damaged} damaged, ${last.boxes} boxes` : 'Not confirmed yet'}</small>
    </div>
  );
}

After the count: Missing per product, the difference banner, and the brand's problem report with "Keep the count" / "Recount"

Code
import { useState } from 'react';
import { GiftShipmentCard } from '@ergasti/bricks';

function ProblemReported() {
  const [open, setOpen] = useState(true);
  return (
    <GiftShipmentCard
      brand="Glow Lab" state="confirmed_diff"
      lines={[{ product: 'Eyeshadow palette', claimed: 30, good: 28, damaged: 2 }, { product: 'Hand soap', claimed: 30, good: 26, damaged: 0 }]}
      problem={open ? { date: '12 Nov', text: 'We packed 30 hand soaps in box 2. Please recount.' } : null} problemKept={!open}
      onKeepCount={() => setOpen(false)} onRecount={() => setOpen(false)}
    />
  );
}

The shipment page's side column: when it was sent, arrived and confirmed, and the brand's confirmed gift stock

Code
import { BrandGiftStockCard, GiftShipmentTimeline } from '@ergasti/bricks';

function SideColumn() {
  return (
    <div style={{ display: 'grid', gap: 16, maxWidth: 420 }}>
      <GiftShipmentTimeline sent="9 Nov · 3 boxes · Own driver" arrived="10 Nov · 3 of 3 boxes" confirmed="11 Nov" />
      <BrandGiftStockCard brand="Glow Lab" left={42} total={100} />
    </div>
  );
}

Counting while the shipment refetches

Pass shipmentId: what PR has typed is kept by product (the line's id, else its name), so a refetch that reorders the lines, adds one or moves the shipment from Expected to Arrived keeps each count with its product. Only another shipment id starts a new count. Type a count, then press Refetch.

Code
import { useState } from 'react';
import { Button, GiftShipmentCard, type GiftShipmentLine } from '@ergasti/bricks';

function RefetchKeepsTheCount() {
  const first: GiftShipmentLine[] = [{ id: 'eye', product: 'Eyeshadow palette', claimed: 20 }, { id: 'lip', product: 'Red lipstick', claimed: 10 }];
  const [lines, setLines] = useState(first);
  return (
    <div style={{ display: 'grid', gap: 10 }}>
      <div><Button size="sm" onClick={() => setLines((l) => [{ id: 'oil', product: 'Lip oil', claimed: 5 }, ...[...l].reverse().filter((x) => x.id !== 'oil')])}>Refetch</Button></div>
      <GiftShipmentCard shipmentId="GS-0016" brand="Glow Lab" state="arrived" lines={lines} onConfirm={() => {}} />
    </div>
  );
}

Loading and failed loads

The claim page's cards take loading (skeleton lines under their heading) and a load error with Try again: loadError / onRetry on all four (error on GiftShipmentCard and WarehouseDetailsCard is a failed save).

Code (not run)
import { BrandGiftStockCard, GiftShipmentCard, GiftShipmentTimeline, WarehouseDetailsCard } from '@ergasti/bricks';

function LoadStates() {
  return (
    <div style={{ display: 'grid', gap: 16 }}>
      <GiftShipmentCard brand="Glow Lab" state="expected" lines={[]} loading />
      <div style={{ display: 'grid', gap: 16, maxWidth: 420 }}>
        <GiftShipmentTimeline sent="" loading />
        <BrandGiftStockCard brand="Glow Lab" left={0} loadError onRetry={() => {}} />
      </div>
      <WarehouseDetailsCard value={{ address: '', hours: '', phone: '' }} onSave={() => {}} loadError onRetry={() => {}} />
    </div>
  );
}

Props

Prop

Type

Labels

Every word this component draws, in both languages. Override one per component and language with BricksProvider labels under the key prGiftSide, or with the component's own prop where it has one. A {name} is a value the component fills in.

prGiftSide
KeyEnglishArabic
timelineTimelineالخط الزمني
sentByBrandSent by brandالبراند بعتتها
recordedByRecorded by {name}سجّلها {name}
arrivedArrivedوصلت
confirmedConfirmedاتأكدت
notYetNot yetلسه
stock{brand} gift stockمخزون هدايا {brand}
leftConfirmed units leftالوحدات المتأكدة اللي فاضلة
noteClaimed units are not counted here. A challenge with gifts can't go live until its gifts are confirmed.الوحدات اللي البراند بلّغت عنها مش محسوبة هنا. التحدي اللي فيه هدايا ما يبدأش غير لما هداياه تتأكد.
openGift stock →مخزون الهدايا ←
loadingLoading…بنحمّل…
loadErrorCouldn’t load this. Try again.مقدرناش نحمّل ده. جرّب تاني.
retryTry againجرّب تاني

Design guidance

How the BRICKS design system uses GiftShipmentTimeline. Written in docs/content/components/GiftShipmentTimeline.md; the props above are read from the code, which wins where the two disagree.

A three-row Timeline card for one gift shipment (Sent by brand, Arrived, Confirmed), each with its date and detail or a dash while it has not happened; use it in the side column of a shipment page.

It is the mock's tl card on the PR Portal shipment page (P.gship), above the brand's gift stock card. The first row reads "Recorded by <name>" instead of "Sent by brand" when PR recorded the shipment for the brand (the "Record gifts for a brand" dialog). The app formats each value; the card only lays them out.

Anatomy

  1. Card (Card with .kit-pr-gside, gap 12): a <section> named by its header.
  2. Header: Card.Header title "Timeline".
  3. Rows (.kit-pr-kv, a <dl>, 7px vertical padding, 13.5px): three <div> pairs, label (<dt>, --ink-3) at the start and value (<dd>, 700, tabular, end-aligned, in a <bdi>) at the end.
    1. "Sent by brand" or "Recorded by <name>" → sent.
    2. "Arrived" → arrived.
    3. "Confirmed" → confirmed.
  4. Dash: a missing value renders an aria-hidden "—" with visually hidden "Not yet" text (see Accessibility).

Variants

Prop / valueLookUse when
recordedBy unsetFirst row "Sent by brand"The brand submitted the shipment itself.
recordedBy="Mona Adel"First row "Recorded by Mona Adel"PR recorded it on the brand's behalf.

States

Driven by which values you pass (they follow the shipment's GiftShipmentState):

Shipment statesentarrivedconfirmed
expected"17 Nov · 2 boxes · Courier"——
arrived"14 Nov · 2 boxes · Own driver""16 Nov · 2 of 2 boxes"—
confirmed / confirmed_diff"28 Oct · 4 boxes · Courier""29 Oct · 4 of 4 boxes""30 Oct"

undefined, null and '' all count as missing. Long values wrap inside the <dd>; keep them to "date · count · method". Static: no hover, loading or error state.

Types

PrGiftSideCopy (labels): timeline, sentByBrand, recordedBy(name), arrived, confirmed, notYet, and the optional loading, loadError, retry; also labels.prGiftSide on the provider.

Usage

// PR Portal › Gift stock › GS-0016 (arrived): the side column
<div style={{ display: 'grid', gap: 16, alignContent: 'start' }}>
  <GiftShipmentTimeline sent="14 Nov · 2 boxes · Own driver" arrived="16 Nov · 2 of 2 boxes" />
  <BrandGiftStockCard brand="Glow Lab" left={42} total={100} />
</div>
// Recorded by PR, fully confirmed (GS-0009)
<GiftShipmentTimeline
  sent="28 Oct · 4 boxes · Courier"
  recordedBy="Mona Adel"
  arrived="29 Oct · 4 of 4 boxes"
  confirmed="30 Oct"
/>
// From an API shipment: pass undefined for steps not reached
<GiftShipmentTimeline sent={fmtSent(s)} arrived={s.arrivedAt ? fmtArrived(s) : undefined} confirmed={s.confirmedAt ? fmtDate(s.confirmedAt) : undefined} />

Where it appears

  • PR Portal › Gift stock › a shipment page › side column, top card (mock P.gship, tl rows). Gallery screens gifts-ship (expected), gifts-ship-arrived, gifts-ship-problem, gifts-ship-confirmed.
  • Screen: PR · Gift stock (the list that opens these pages).

Guidelines

Do

  • Format values as "date · detail" in the app's date style; keep the box count in sent and "x of y boxes" in arrived.
  • Pass recordedBy whenever PR entered the shipment, so the brand-facing record stays honest.

Don't

  • Don't write "Not yet" or "—" yourself: leave the value out and the card draws the dash.
  • Don't add rows: the problem report and the count live in GiftShipmentCard.
  • Don't use it for a generic event log: use the kit Timeline or AuditLogList.

RTL and Arabic

  • Labels sit on the right, values on the left; the dash follows.
  • Arabic copy: "الخط الزمني", "البراند بعتتها", "سجّلها <name>", "وصلت", "اتأكدت".
  • Pass Arabic-formatted values ("17 نوفمبر · 2 كرتونة · شركة شحن"): the card does not format dates.

Tokens

--card, --line, --r-lg, --ink, --ink-3, --font-family-display.

Accessibility

  • A <section> named by "Timeline"; rows are a <dl>, so each value is read with its label.
  • A missing step is an aria-hidden "—" next to visually hidden "Not yet" text ("لسه" in Arabic), so screen readers say "Arrived, Not yet". (Before 0.7.1 the words were an aria-label on a plain <span>, which screen readers usually skip.)
  • Values sit in <bdi>, keeping mixed Latin/Arabic text and numbers in order.

Found in the source

  • ARIA attributes set: aria-hidden.
  • Its tests cover: “the request page variant: the figure alone, its own note and a ”.

Read from the component's source and tests. See Accessibility for the patterns the library follows.

See also: Card · useLanguage · Button · WarehouseDetailsCard · GiftAttentionList · GiftClaimCheck

Source

src/pr/gifts/GiftSideCards.tsx (line 83) on GitHub.

On this page