Skip to Content
BBRICKSv0.7.4
Recipes

Gift stock flow

From the shipments list to counting a shipment and on to gift analytics, with the PR portal's gift components.

Brands send gifts to the warehouse and say what they sent (a shipment). Nothing counts as gift stock until PR counts what arrived. This recipe walks the three screens of that flow: the shipments list, one shipment's count, and the analytics that add it all up. It uses the 0.4.0 gift family; the 0.6.0 gift claim components (GiftClaimCheck, giftClaimColumns, giftAnalyticsColumns, ShipmentSummary) are deprecated since 0.7.0 in its favour (see the migration guide).

Shipments list, then the count

Status tiles and the shipments table (giftShipmentColumns); a row opens the shipment with GiftShipmentCard. Confirming a count moves the shipment to Confirmed, or to "Confirmed with difference" when the good units fall short, and the tiles follow. "Record gifts for a brand" opens RecordGiftsDialog and adds an Expected (or Arrived) shipment.

Pinned to TRNDR presetPR theme
Code
import { useState } from 'react';
import { Button, DataTable, GiftShipmentCard, GiftStatusFilter, Icon, KpiGrid, ListToolbar, PageGrid, PageHeader, RecordGiftsDialog, TextLink, Tile, giftShipmentColumns, giftShipmentMatches, useLanguage, type GiftCount, type GiftShipmentFilter, type GiftShipmentLine, type GiftShipmentRow, type GiftShipmentState, type RecordedGifts } from '@ergasti/bricks';
import { giftBrands, giftShipments, prBrands, shipmentLines, warehouse } from './recipes';

function Flow() {
  const language = useLanguage();
  const [shipments, setShipments] = useState<GiftShipmentRow[]>(giftShipments);
  const [lines, setLines] = useState<Record<string, GiftShipmentLine[]>>(shipmentLines);
  const [openId, setOpenId] = useState<string | null>(null);
  const [recording, setRecording] = useState(false);
  const [chip, setChip] = useState<GiftShipmentFilter | 'all'>('all');
  const [busy, setBusy] = useState(false);
  const shown = shipments.filter((s) => giftShipmentMatches(chip, s));
  const open = shipments.find((s) => s.id === openId);
  const countOf = (state: GiftShipmentState) => shipments.filter((s) => s.state === state).length;

  const confirm = (shipment: GiftShipmentRow, result: GiftCount) => {
    setBusy(true);
    window.setTimeout(() => {
      const counted = (lines[shipment.id] ?? []).map((l, i) => ({ ...l, good: result.lines[i].good, damaged: result.lines[i].damaged }));
      const good = counted.reduce((n, l) => n + (l.good ?? 0), 0);
      setLines((all) => ({ ...all, [shipment.id]: counted }));
      setShipments((all) => all.map((s) => (s.id === shipment.id ? { ...s, confirmed: good, state: good < s.claimed ? 'confirmed_diff' : 'confirmed' } : s)));
      setBusy(false);
    }, 700);
  };
  const record = (r: RecordedGifts) => {
    const id = `GS-00${20 + shipments.length}`;
    const brand = Object.values(prBrands).find((b) => b.id === String(r.brandId)) ?? prBrands.glow;
    setShipments((all) => [{ id, sent: 'Today', brand, for: 'December glow', claimed: r.lines.reduce((n, l) => n + l.units, 0), confirmed: null, state: r.state }, ...all]);
    setLines((all) => ({ ...all, [id]: r.lines.map((l) => ({ id: l.productId, product: l.product, claimed: l.units })) }));
    setRecording(false);
  };

  if (open) {
    return (
      <PageGrid>
        <div><TextLink onClick={() => setOpenId(null)}>← Gift stock</TextLink></div>
        <PageHeader title={`${open.id} · ${open.brand.name}`} subtitle={`For ${open.for}`} />
        <GiftShipmentCard
          shipmentId={open.id} brand={open.brand.name} state={open.state} lines={lines[open.id] ?? []} claimedBoxes={2}
          problem={open.problem ? { text: 'We sent 60, you counted 54. Please check the second box again.', date: '12 Nov' } : undefined}
          busy={busy} onConfirm={(result) => confirm(open, result)} onKeepCount={() => {}} onRecount={() => {}}
        />
      </PageGrid>
    );
  }
  return (
    <PageGrid>
      <PageHeader title="Gift stock" subtitle="Nothing counts as gift stock until you confirm what arrived." actions={<Button onClick={() => setRecording(true)}><Icon name="plus" />Record gifts for a brand</Button>} />
      <KpiGrid>
        <Tile size="stat" tone="rasp" label="Expected" value={countOf('expected')} sub="Claimed, not arrived" />
        <Tile size="stat" tone="lime" label="To count" value={countOf('arrived')} sub="At the warehouse" />
        <Tile size="stat" tone="sky" label="With a difference" value={countOf('confirmed_diff')} sub="Fewer good units than claimed" />
        <Tile size="stat" tone="lilac" label="Confirmed" value={countOf('confirmed')} sub="Matched the claim" />
      </KpiGrid>
      <ListToolbar filters={<GiftStatusFilter value={chip} onChange={setChip} />} />
      <DataTable label="Gift shipments" rows={shown} rowKey={(r) => r.id} columns={giftShipmentColumns(language)} onRowClick={(r) => setOpenId(r.id)} />
      <RecordGiftsDialog open={recording} onClose={() => setRecording(false)} onSave={record} brands={giftBrands} warehouse={warehouse} />
    </PageGrid>
  );
}

Steps

  1. List the shipments. Status tiles (Tile with size="stat", in a KpiGrid) count shipments per state; GiftStatusFilter in a ListToolbar filters them, with giftShipmentMatches as the rule; a DataTable with giftShipmentColumns draws the reference, brand, what it is for, units claimed and confirmed, and the status (with a red "Problem reported" pill when the brand disputes the count). Open a row with the table's onRowClick.
  2. Record a shipment for a brand. RecordGiftsDialog asks for the brand, the products and units, the boxes, and whether the gifts are on the way or already at the warehouse. productsFor(brandId) gives each brand's product list; onSave gets valid values only.
  3. Count the shipment. A row opens GiftShipmentCard with the shipment's state and lines. While Expected or Arrived it asks for boxes received and the good and damaged units per product, and onConfirm gets valid numbers only (a GiftCount, each line with its id). Set busy while you save and error when the save fails. Give shipmentId and an id per line so a half-typed count survives refetches: it is kept by product, even when the lines come back in another order or the state moves from Expected to Arrived. A TextLink takes PR back to the list.
  4. Move the state on. Your server decides: all good units means confirmed, fewer means confirmed_diff. Pass the new state back and the card shows the count read-only; with problem it shows the brand's report and offers onKeepCount and onRecount.
  5. Add it up. KpiGrid and KpiCard show stock, gifts sent and delivered. In a PageGrid split="8-4", a table with giftBrandColumns shows each brand's stock (the status follows giftStockStatus unless you pass one), and the side column holds GiftAttentionList (brands out of gifts, shipments still to count) and GiftShipmentCounts (shipments per status and the open problem reports), each in a Card with a title.

Analytics

What the shipments add up to: four KPIs, stock by brand (giftBrandColumns), what needs attention (GiftAttentionList), and GiftShipmentCounts with a line per shipment status and the open problem reports.

Pinned to TRNDR presetPR theme
Code
import { Card, DataTable, GiftAttentionList, GiftShipmentCounts, KpiCard, KpiGrid, PageGrid, PageHeader, giftBrandColumns, useLanguage, type GiftShipmentState, type GiftShipmentStatus } from '@ergasti/bricks';
import { giftBrandStock, giftShipments, prBrands } from './recipes';

const STATUSES: GiftShipmentState[] = ['expected', 'arrived', 'confirmed', 'confirmed_diff'];

function Analytics() {
  const language = useLanguage();
  const counts: Partial<Record<GiftShipmentStatus, number>> = Object.fromEntries(STATUSES.map((state) => [`gift_${state}`, giftShipments.filter((s) => s.state === state).length]));
  const total = giftBrandStock.reduce((n, s) => n + s.total, 0);
  const used = giftBrandStock.reduce((n, s) => n + s.used, 0);
  return (
    <PageGrid>
      <PageHeader title="Gift analytics" subtitle="Gift stock, gifts sent to creators, and what brands sent against what arrived." />
      <KpiGrid>
        <KpiCard tone="lime" icon="gift" label="Confirmed gift stock" value={total} sub={`${total - used} units left to pick`} progress={Math.round((used / total) * 100)} />
        <KpiCard tone="sky" icon="user" label="Gifts sent to creators" value={giftBrandStock.reduce((n, s) => n + s.delivered + s.notDelivered, 0)} sub="All brands" />
        <KpiCard tone="lilac" icon="check" label="Delivered" value={giftBrandStock.reduce((n, s) => n + s.delivered, 0)} sub="To creators" />
        <KpiCard tone="butter" icon="alert" label="Received vs claimed" value="97%" sub="Counted shipments only" />
      </KpiGrid>
      <PageGrid split="8-4" align="start">
        <Card title="By brand" sub="Click a brand to see its gift stock">
          <DataTable label="Gift stock by brand" rows={giftBrandStock} rowKey={(r) => r.id} columns={giftBrandColumns(language)} onRowClick={() => {}} />
        </Card>
        <PageGrid align="start">
          <Card title="Needs attention">
            <GiftAttentionList items={[
              { id: 'mira', kind: 'out', brand: prBrands.mira },
              ...giftShipments.filter((s) => s.state === 'expected' || s.state === 'arrived').map((s) => ({ id: s.id, kind: 'check' as const, brand: s.brand, reference: s.id, units: s.claimed, state: s.state })),
            ]} />
          </Card>
          <Card title="Shipments from brands">
            <GiftShipmentCounts counts={counts} problems={giftShipments.filter((s) => s.problem).length} />
          </Card>
        </PageGrid>
      </PageGrid>
    </PageGrid>
  );
}

Notes

  • States are expected, arrived, confirmed, confirmed_diff and cancelled. giftStatusKey turns one into its PR status key (gift_expected…), whose words come from the PR status table, so they follow the language. GiftShipmentCounts takes its counts by those keys.
  • Units are whole numbers. The count fields refuse anything else and say why.

Related: PR gift stock screen, PR gift claim screen, PR gift analytics screen.

On this page