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.
| Key | English | Arabic |
|---|---|---|
title | Record gifts for a brand | سجّل هدايا لبراند |
sub | Use this when the brand tells you by phone or WhatsApp, or boxes arrive without a claim. The brand sees it in its portal. | استخدمها لما البراند تقولك بالتليفون أو الواتساب، أو لما كراتين توصل من غير ما حد يبلّغ. البراند بتشوفها في البوابة بتاعتها. |
brand | Brand | البراند |
products | Tick the products the brand sent | علّم على المنتجات اللي البراند بعتتها |
productsHint | Units appear next to each product you tick. | خانة الوحدات بتظهر جنب كل منتج تعلّم عليه. |
units | Units | وحدات |
unitsOf | Units of {product} | وحدات {product} |
noProducts | This brand has no gift products yet. | البراند دي لسه معندهاش منتجات هدايا. |
boxes | Boxes | الكراتين |
where | Where is it now | هي فين دلوقتي |
onTheWay | On the way | في الطريق |
atWarehouse | Already at the warehouse | وصلت المخزن خلاص |
cancel | Cancel | إلغاء |
save | Save | احفظ |
unitsErr | Enter 1 to 999 units for each ticked product | اكتب من 1 لـ 999 وحدة لكل منتج متعلّم عليه |
noneErr | Tick at least one product | علّم على منتج واحد على الأقل |
boxesErr | Boxes must be a whole number from 1 to 99 | عدد الكراتين لازم يكون رقم صحيح من 1 لـ 99 |
unitsRange | Enter {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
- Modal: kit
Modal, title "Record gifts for a brand", Cancel and ink Save. - 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).
- Warehouse banner (with
warehouse):WarehouseNote: "Send to: address · hours · phone · Open location in Maps ↗". - Brand: a select of
brands; changing it clears the ticks. - 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.
- Boxes / Where is it now: two columns: Boxes (1-99) and a select "On the way" / "Already at the warehouse".
- Footer error (with
error).
Variants
| Prop | Effect |
|---|---|
warehouse | Shows the "Send to:" banner |
defaultBrandId | Opens on that brand (missing id falls back to the first) |
maxUnits | Raises the per-product cap from 999; the units error then names the range |
States
| State | Trigger |
|---|---|
| Fresh | every open: first (or default) brand, no ticks, boxes empty, "On the way" |
| Product ticked | checkbox: Units field appears and gets focus |
| Units invalid | Save 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 products | brand has none: "This brand has no gift products yet." |
| Busy | busy: Save disabled |
| Error | error: 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
maxUnitssilently: 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 markedaria-invalidwhen 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.
Related
GiftShipmentCard: counting the shipment once it arrives.WarehouseNote/WarehouseDetailsCard: the warehouse banner and the settings form.GiftStatusPills: the new shipment's status in the list.
See also: Button · FormField · Modal · useLanguage · BrandGiftStockCard · GiftAttentionList · GiftClaimCheck
Source
src/pr/gifts/RecordGiftsDialog.tsx (line 108) on GitHub.