Skip to Content
BBRICKSv0.7.4
PR PortalGifts

RecordGiftsDialog

The PR mock v3's "Record gifts for a brand" modal (recordGS / saveRecord): the warehouse banner, the brand, the brand's gift products as a checklist (ticking one shows its Units field and moves focus there), Boxes and "Where is it now" (On the way / Already at the warehouse). Save checks, in the mock's order, units 1–999 for every ticked product (1–maxUnits when set), at least one product, and boxes 1–99; the first problem is said in an alert and its field marked.

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

Examples

Record gifts a brand sent without a claim: the warehouse banner, the brand's products with units, boxes and where they are now

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

const WH: WarehouseDetails = { address: 'Warehouse 4, Industrial Zone 3, 6th of October City, Giza (sample)', hours: 'Sun–Thu · 10:00–17:00', phone: '+20 100 000 0000' };

const brands = [
  { id: 'glow', name: 'Glow Lab', products: ['Red lipstick', 'Eyeshadow palette', 'Lash mascara'].map((name, i) => ({ id: `g${i}`, name, sku: `GL-${101 + i}` })) },
  { id: 'nile', name: 'Nile Threads', products: ['Linen shirt', 'Cotton tote'].map((name, i) => ({ id: `n${i}`, name, sku: `NI-${101 + i}` })) },
];

function RecordGifts() {
  const [open, setOpen] = useState(false);
  const [last, setLast] = useState('');
  return (
    <>
      <Button onClick={() => setOpen(true)}>Record gifts for a brand</Button> <small>{last}</small>
      <RecordGiftsDialog open={open} onClose={() => setOpen(false)} brands={brands} warehouse={WH}
        onSave={(g) => { setLast(`${g.lines.reduce((a, l) => a + l.units, 0)} units, ${g.boxes} boxes, ${g.state}`); setOpen(false); }} />
    </>
  );
}

Where brands send gifts: the "Send to:" banner (with a Maps link) and the card PR edits it in

Code
import { useState } from 'react';
import { WarehouseDetailsCard, WarehouseNote, type WarehouseDetails } from '@ergasti/bricks';

const WH: WarehouseDetails = { address: 'Warehouse 4, Industrial Zone 3, 6th of October City, Giza (sample)', hours: 'Sun–Thu · 10:00–17:00', phone: '+20 100 000 0000' };

function Warehouse() {
  const [wh, setWh] = useState(WH);
  return (
    <div style={{ display: 'grid', gap: 16 }}>
      <WarehouseNote warehouse={wh} />
      <WarehouseDetailsCard value={wh} onSave={setWh} />
    </div>
  );
}

Saving

Pass busy while your request runs: Save is disabled. defaultBrandId opens the dialog on one brand (from that brand's page).

Code
import { RecordGiftsDialog, type WarehouseDetails } from '@ergasti/bricks';

const WH: WarehouseDetails = { address: 'Warehouse 4, Industrial Zone 3, 6th of October City, Giza (sample)', hours: 'Sun–Thu · 10:00–17:00', phone: '+20 100 000 0000' };

const brands = [
  { id: 'glow', name: 'Glow Lab', products: ['Red lipstick', 'Eyeshadow palette', 'Lash mascara'].map((name, i) => ({ id: `g${i}`, name, sku: `GL-${101 + i}` })) },
  { id: 'nile', name: 'Nile Threads', products: ['Linen shirt', 'Cotton tote'].map((name, i) => ({ id: `n${i}`, name, sku: `NI-${101 + i}` })) },
];

function Busy() {
  return <RecordGiftsDialog open onClose={() => {}} onSave={() => {}} busy defaultBrandId="nile" brands={brands} warehouse={WH} />;
}

Server error

When saving fails, pass its message as error: it is announced in the footer and what the user filled in stays.

Code
import { RecordGiftsDialog, type WarehouseDetails } from '@ergasti/bricks';

const WH: WarehouseDetails = { address: 'Warehouse 4, Industrial Zone 3, 6th of October City, Giza (sample)', hours: 'Sun–Thu · 10:00–17:00', phone: '+20 100 000 0000' };

const brands = [
  { id: 'glow', name: 'Glow Lab', products: ['Red lipstick', 'Eyeshadow palette', 'Lash mascara'].map((name, i) => ({ id: `g${i}`, name, sku: `GL-${101 + i}` })) },
  { id: 'nile', name: 'Nile Threads', products: ['Linen shirt', 'Cotton tote'].map((name, i) => ({ id: `n${i}`, name, sku: `NI-${101 + i}` })) },
];

function ServerError() {
  return <RecordGiftsDialog open onClose={() => {}} onSave={() => {}} error="We could not save these gifts. Try again." brands={brands} warehouse={WH} />;
}

Another cap

maxUnits (default 999, the mock's rule) is the most units one product may hold; set it, and the error names the range ("Enter 1 to 5,000 units for each ticked product"). Tick a product, type 6000 and Save to see it.

Code
import { RecordGiftsDialog } from '@ergasti/bricks';

const brands = [
  { id: 'glow', name: 'Glow Lab', products: ['Red lipstick', 'Eyeshadow palette', 'Lash mascara'].map((name, i) => ({ id: `g${i}`, name, sku: `GL-${101 + i}` })) },
  { id: 'nile', name: 'Nile Threads', products: ['Linen shirt', 'Cotton tote'].map((name, i) => ({ id: `n${i}`, name, sku: `NI-${101 + i}` })) },
];

function MaxUnits() {
  return <RecordGiftsDialog open onClose={() => {}} onSave={() => {}} maxUnits={5000} brands={brands} />;
}

Props

Prop

Type

Labels

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

prRecordGifts
KeyEnglishArabic
titleRecord gifts for a brandسجّل هدايا لبراند
subUse this when the brand tells you by phone or WhatsApp, or boxes arrive without a claim. The brand sees it in its portal.استخدمها لما البراند تقولك بالتليفون أو الواتساب، أو لما كراتين توصل من غير ما حد يبلّغ. البراند بتشوفها في البوابة بتاعتها.
brandBrandالبراند
productsTick the products the brand sentعلّم على المنتجات اللي البراند بعتتها
productsHintUnits appear next to each product you tick.خانة الوحدات بتظهر جنب كل منتج تعلّم عليه.
unitsUnitsوحدات
unitsOfUnits of {product}وحدات {product}
noProductsThis brand has no gift products yet.البراند دي لسه معندهاش منتجات هدايا.
boxesBoxesالكراتين
whereWhere is it nowهي فين دلوقتي
onTheWayOn the wayفي الطريق
atWarehouseAlready at the warehouseوصلت المخزن خلاص
cancelCancelإلغاء
saveSaveاحفظ
unitsErrEnter 1 to 999 units for each ticked productاكتب من 1 لـ 999 وحدة لكل منتج متعلّم عليه
noneErrTick at least one productعلّم على منتج واحد على الأقل
boxesErrBoxes must be a whole number from 1 to 99عدد الكراتين لازم يكون رقم صحيح من 1 لـ 99
unitsRangeEnter {min} to {max} units for each ticked productاكتب من {min} لـ {max} وحدة لكل منتج متعلّم عليه

Design guidance

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

The "Record gifts for a brand" modal: the warehouse address, the brand, its gift products as a checklist with units, boxes and where the gifts are now; use it when a brand tells PR about a shipment by phone or WhatsApp, or boxes arrive without a claim.

RecordGiftsDialog is the PR mock v3's recordGS / saveRecord, opened from the Gift stock page's "+ Record gifts for a brand". PR picks the brand, ticks the products it sent (ticking shows a Units field and moves focus there), enters boxes, and says whether the shipment is on the way or already at the warehouse. Save validates in the mock's order and the brand then sees the shipment in its portal. WarehouseNote (the "Send to:" banner) and WarehouseDetailsCard (the Gift stock page's warehouse form) live in the same family and are shown in its stories.

Anatomy

  1. Modal: kit Modal, title "Record gifts for a brand", Cancel and ink Save.
  2. Intro: "Use this when the brand tells you by phone or WhatsApp, or boxes arrive without a claim. The brand sees it in its portal." (13.5px muted, in the body so it wraps).
  3. Warehouse banner (with warehouse): WarehouseNote: "Send to: address · hours · phone · Open location in Maps ↗".
  4. Brand: a select of brands; changing it clears the ticks.
  5. Products fieldset: legend "Tick the products the brand sent"; one 64px row per product (checkbox, bold name, small SKU); ticked rows get a raspberry border and soft fill plus a Units input; the list scrolls past 260px; hint "Units appear next to each product you tick."; inline error.
  6. Boxes / Where is it now: two columns: Boxes (1-99) and a select "On the way" / "Already at the warehouse".
  7. Footer error (with error).

Variants

PropEffect
warehouseShows the "Send to:" banner
defaultBrandIdOpens on that brand (missing id falls back to the first)
maxUnitsRaises the per-product cap from 999; the units error then names the range

States

StateTrigger
Freshevery open: first (or default) brand, no ticks, boxes empty, "On the way"
Product tickedcheckbox: Units field appears and gets focus
Units invalidSave with a ticked product outside 1-999 (or maxUnits): "Enter 1 to 999 units for each ticked product", field marked
Nothing ticked"Tick at least one product"
Boxes invalid"Boxes must be a whole number from 1 to 99"
No productsbrand has none: "This brand has no gift products yet."
Busybusy: Save disabled
Errorerror: alert in the footer

Only the first problem is reported, in that order.

Types

RecordedGifts (onSave): { brandId, lines: [{ productId, product, units }], boxes, state: 'expected' | 'arrived' }. GiftBrand (brands): { id, name, products: [{ id, name, sku? }] }. WarehouseDetails (warehouse): { address, hours, phone } for the banner.

Usage

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

<RecordGiftsDialog
  open={recording}
  onClose={() => setRecording(false)}
  onSave={async (gifts) => { await recordShipment(gifts); setRecording(false); }}
  brands={[
    { id: 'glow', name: 'Glow Lab', products: [{ id: 'g1', name: 'Red lipstick', sku: 'GL-101' }, { id: 'g2', name: 'Eyeshadow palette', sku: 'GL-102' }] },
    { id: 'nile', name: 'Nile Threads', products: [{ id: 'n1', name: 'Linen shirt', sku: 'NI-101' }] },
  ]}
  warehouse={{ address: 'Warehouse 4, Industrial Zone 3, 6th of October City, Giza', hours: 'Sun–Thu · 10:00–17:00', phone: '+20 100 000 0000' }}
  busy={saving}
  error={saveError}
/>
// Gift stock: the header tool opens it; Brand detail can preselect its brand
<PageHeader title="Gift stock" actions={<Button variant="ink" onClick={() => setRecording(true)}><Icon name="plus" /> Record gifts for a brand</Button>} />
{/* stat cards, toolbar, shipments table, WarehouseDetailsCard */}
<RecordGiftsDialog open={recording} onClose={() => setRecording(false)} onSave={save} brands={myBrands} defaultBrandId={brandId} warehouse={warehouse} />

Record gifts a brand sent without a claim: the warehouse banner, the brand's products with units, boxes and where they are now. (docs example RecordGifts)

import { useState } from 'react';
import { Button, RecordGiftsDialog, WarehouseDetailsCard, WarehouseNote, type WarehouseDetails } from '@ergasti/bricks';

const WH: WarehouseDetails = { address: 'Warehouse 4, Industrial Zone 3, 6th of October City, Giza (sample)', hours: 'Sun–Thu · 10:00–17:00', phone: '+20 100 000 0000' };
const brands = [
  { id: 'glow', name: 'Glow Lab', products: ['Red lipstick', 'Eyeshadow palette', 'Lash mascara'].map((name, i) => ({ id: `g${i}`, name, sku: `GL-${101 + i}` })) },
  { id: 'nile', name: 'Nile Threads', products: ['Linen shirt', 'Cotton tote'].map((name, i) => ({ id: `n${i}`, name, sku: `NI-${101 + i}` })) },
];

export function RecordGifts() {
  const [open, setOpen] = useState(false);
  const [last, setLast] = useState('');
  return (
    <>
      <Button onClick={() => setOpen(true)}>Record gifts for a brand</Button> <small>{last}</small>
      <RecordGiftsDialog open={open} onClose={() => setOpen(false)} brands={brands} warehouse={WH}
        onSave={(g) => { setLast(`${g.lines.reduce((a, l) => a + l.units, 0)} units, ${g.boxes} boxes, ${g.state}`); setOpen(false); }} />
    </>
  );
}

Where it appears

  • PR Portal › Gift stock › "+ Record gifts for a brand" (header tool).
  • Dashboard screen: PrGifts.

Guidelines

Do

  • Pass the brands PR can act for (My brands or All brands, matching the page's scope).
  • Show the warehouse banner so PR can read the address to the brand on the phone.
  • Choose "Already at the warehouse" when boxes are physically there: the shipment opens as Arrived, ready to count.

Don't

  • Don't use it to confirm counts: that is the shipment card's job.
  • Don't raise maxUnits silently: the error names the new range.

RTL and Arabic

The modal mirrors; numeric inputs and SKUs stay dir="ltr", product names are <bdi>. Arabic-Indic digits are accepted. Arabic words: "سجّل هدايا لبراند", "علّم على المنتجات اللي البراند بعتتها", "الكراتين", "هي فين دلوقتي", "في الطريق" / "وصلت المخزن خلاص".

Tokens

--line, --rasp, --soft, --ink-3, --card, --field-radius, --focus-ring, --focus-ring-field, --radius-xs, --min-touch-target.

Accessibility

  • Kit Modal (focus trap, Escape, inert page).
  • Products are a <fieldset> with a <legend>, described by the hint and any error; each Units input is named ("Units of Red lipstick") and marked aria-invalid when wrong.
  • Ticking a product moves focus to its Units field.
  • Errors are role="alert"; checkbox labels get a focus ring and 44px targets on touch tiers (≤1024px).

Found in the source

  • Roles in the markup: alert.
  • ARIA attributes set: aria-describedby, aria-label, aria-invalid.
  • It moves focus in code.
  • Its tests cover: “a modal: the sub line, the warehouse banner, the first brand’s products; ticking one shows its Units and focuses it”; “Cancel and Escape close; reopening starts over; closed renders nothing”.

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

See also: Button · FormField · Modal · useLanguage · BrandGiftStockCard · GiftAttentionList · GiftClaimCheck

Source

src/pr/gifts/RecordGiftsDialog.tsx (line 108) on GitHub.

On this page