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.
| Key | English | Arabic |
|---|---|---|
timeline | Timeline | الخط الزمني |
sentByBrand | Sent by brand | البراند بعتتها |
recordedBy | Recorded by {name} | سجّلها {name} |
arrived | Arrived | وصلت |
confirmed | Confirmed | اتأكدت |
notYet | Not yet | لسه |
stock | {brand} gift stock | مخزون هدايا {brand} |
left | Confirmed units left | الوحدات المتأكدة اللي فاضلة |
note | Claimed units are not counted here. A challenge with gifts can't go live until its gifts are confirmed. | الوحدات اللي البراند بلّغت عنها مش محسوبة هنا. التحدي اللي فيه هدايا ما يبدأش غير لما هداياه تتأكد. |
open | Gift stock → | مخزون الهدايا ← |
loading | Loading… | بنحمّل… |
loadError | Couldn’t load this. Try again. | مقدرناش نحمّل ده. جرّب تاني. |
retry | Try 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
- Card (
Cardwith.kit-pr-gside, gap 12): a<section>named by its header. - Header:
Card.Headertitle "Timeline". - 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.- "Sent by brand" or "Recorded by <name>" →
sent. - "Arrived" →
arrived. - "Confirmed" →
confirmed.
- "Sent by brand" or "Recorded by <name>" →
- Dash: a missing value renders an
aria-hidden"—" with visually hidden "Not yet" text (see Accessibility).
Variants
| Prop / value | Look | Use when |
|---|---|---|
recordedBy unset | First 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 state | sent | arrived | confirmed |
|---|---|---|---|
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,tlrows). Gallery screensgifts-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
sentand "x of y boxes" inarrived. - Pass
recordedBywhenever 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
TimelineorAuditLogList.
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 anaria-labelon 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.
Related
BrandGiftStockCard: the card under it.GiftShipmentCard: the shipment's main card (check table, counted table, problem report).GiftStatusPills: the shipment's state as a pill, for lists.Timeline(kit): a general vertical event list.
See also: Card · useLanguage · Button · WarehouseDetailsCard · GiftAttentionList · GiftClaimCheck
Source
src/pr/gifts/GiftSideCards.tsx (line 83) on GitHub.