ChallengeRewardFields
The challenge builder's reward steps (the v3 mock's P.builder steps 2 and 4). part="goal": the type as three choice cards (Leaderboard: the top creators win; Target: everyone who hits the goal wins; Commission boost: every delivered sale earns more) and that type's fields, with what counts under them. part="payout": Cash / Gift ("From confirmed gift stock only"), the cash per winner or the gift, and when winners are paid. Controlled: every change calls onChange with the whole value. Put each in a BuilderStepCard.
import { ChallengeRewardFields } from '@ergasti/bricks';Examples
The challenge builder
A Stepper, one BuilderStepCard per step around that step's fields, and the flat ChallengeSummary in a sticky side column (PageGrid split="8-4" stickyAside). One ChallengeDraft state feeds every step; challengeIssues(draft) finds what is missing, and the summary turns it into red lines that go back to the step. Try Continue with an empty name.
Code
import { useState } from 'react';
import { BuilderStepCard, ChallengeAudienceFields, ChallengeBasicsFields, ChallengeRewardFields, ChallengeSummary, PageGrid, Stepper, challengeIssues, defaultChallengeDraft, type ChallengeDraft } from '@ergasti/bricks';
import { brands } from './pr';
const BRANDS = [brands.glow, brands.nile, { ...brands.kemet, paused: true }];
const GIFTS = [{ id: 'serum', name: 'Glow serum', cost: '300.00', left: 18 }];
const STEPS = ['Basics', 'Type & goal', 'Who can join', 'Reward'];
function Builder() {
const [step, setStep] = useState(1);
const [draft, setDraft] = useState<ChallengeDraft>(defaultChallengeDraft('glow'));
const brand = BRANDS.find((b) => b.id === draft.brand);
const issues = challengeIssues(draft);
const fields = [
<ChallengeBasicsFields key="1" value={draft} onChange={setDraft} brands={BRANDS} validate={step > 1 || !!draft.name} />,
<ChallengeRewardFields key="2" value={draft} onChange={setDraft} validate />,
<ChallengeAudienceFields key="3" value={draft} onChange={setDraft} brandName={brand?.name ?? ''} trndrWide={draft.brand === 'all'} />,
<ChallengeRewardFields key="4" part="payout" value={draft} onChange={setDraft} gifts={GIFTS} brandName={brand?.name ?? ''} validate />,
][step - 1];
return (
<PageGrid split="8-4" align="start" stickyAside>
<div>
<Stepper steps={STEPS} current={step - 1} onStep={(i) => setStep(i + 1)} />
<BuilderStepCard title={STEPS[step - 1]} step={step} onBack={() => setStep(step - 1)} onContinue={() => setStep(step + 1)}>{fields}</BuilderStepCard>
</div>
<ChallengeSummary layout="flat" flatDensity="mock" name={draft.name} brand={brand ?? { id: 'all', name: 'All brands' }} payer={draft.brand === 'all' ? 'trndr' : 'brand'}
status="upcoming" dates={draft.starts && draft.ends ? `${draft.starts} → ${draft.ends}` : '—'} goal={`Top ${draft.winners} by ${draft.rankBy}`} eligibility={{ audience: draft.audience }}
rewards={[{ key: 'per', label: 'Reward', amount: '1000.00', figure: 'challenge_commission', hint: 'each', inlineHint: true }]} budget={{ hold: '10000.00', available: '43390.00' }}
warnings={Object.keys(issues).map((field) => ({ id: field, text: `Fix ${field}`, tone: 'bad' as const, step: field === 'name' || field === 'starts' || field === 'ends' ? 'basics' : 'reward' }))}
steps={{ basics: '1', goal: '2', join: '3', reward: '4' }} onEditStep={(s) => setStep(Number(s))} onPrimary={() => {}} onSaveDraft={() => {}} money={{ decimals: 'auto' }} />
</PageGrid>
);
}Type & goal
ChallengeRewardFields (part="goal", the default) asks Leaderboard (rank by, winners), Target (goal, what it counts, the most winners) or Commission boost (×1.5 / 2 / 3, the cap on the extra). Pick each card.
Code
import { useState } from 'react';
import { BuilderStepCard, ChallengeRewardFields, defaultChallengeDraft, type ChallengeDraft } from '@ergasti/bricks';
function TypeAndGoal() {
const [draft, setDraft] = useState<ChallengeDraft>({ ...defaultChallengeDraft('glow'), type: 'boost' });
return <BuilderStepCard title="Type & goal" step={2} onBack={() => {}} onContinue={() => {}}><ChallengeRewardFields value={draft} onChange={setDraft} validate /></BuilderStepCard>;
}Reward
part="payout": Cash per winner, or a Gift from the brand's confirmed stock (the ChallengeGiftPicker), then when winners are paid (an open decision until someone decides it; pass paidWhen once it is). A boost has no reward step: the boost is the reward.
Code
import { useState } from 'react';
import { BuilderStepCard, ChallengeRewardFields, defaultChallengeDraft, type ChallengeDraft } from '@ergasti/bricks';
const GIFTS = [{ id: 'serum', name: 'Glow serum', cost: '300.00', left: 18 }];
function Reward() {
const [draft, setDraft] = useState<ChallengeDraft>(defaultChallengeDraft('glow'));
return <BuilderStepCard title="Reward" step={4} onBack={() => {}}><ChallengeRewardFields part="payout" value={draft} onChange={setDraft} gifts={GIFTS} brandName="Glow Lab" money={{ decimals: 'auto' }} /></BuilderStepCard>;
}Who can join, and in Arabic
Public or the brand's affiliates only; a TRNDR-wide challenge (trndrWide) has no choice, just the sentence.
Code
import { useState } from 'react';
import { BuilderStepCard, ChallengeAudienceFields, defaultChallengeDraft, type ChallengeDraft } from '@ergasti/bricks';
function WhoCanJoinArabic() {
const [draft, setDraft] = useState<ChallengeDraft>(defaultChallengeDraft('glow'));
return <BuilderStepCard title="مين يقدر يشترك" step={3} onBack={() => {}} onContinue={() => {}}><ChallengeAudienceFields value={draft} onChange={setDraft} brandName="Glow Lab" /></BuilderStepCard>;
}Props
Prop
Type
Labels
Every word this component draws, in both languages. Override one per component and language with BricksProvider labels under the key prChallengeBuilder, or with the component's own prop where it has one. A {name} is a value the component fills in.
| Key | English | Arabic |
|---|---|---|
forWho | Who it’s for | التحدي لمين |
allBrands | All brands · TRNDR-wide | كل البراندات · على مستوى TRNDR |
paused | {brand} (paused) | {brand} (متوقف) |
choose | Choose a brand | اختار براند |
brandHint | Runs inside this brand’s active campaign. Paid from its wallet. | بيشتغل جوه الحملة الشغّالة للبراند ده. بيتدفع من محفظته. |
allHint | Runs on every brand’s active campaign. TRNDR pays the rewards, not the brands. | بيشتغل على الحملة الشغّالة لكل براند. TRNDR بيدفع الجوايز، مش البراندات. |
name | Challenge name | اسم التحدي |
namePh | e.g. Winter top 10 | مثلاً Winter top 10 |
starts | Starts | بيبدأ |
ends | Ends | بيخلص |
read | What creators will read | صنّاع المحتوى هيقروا إيه |
readPh | Short and exciting. Shown in the creator app. | قصير ومشوّق. بيظهر في تطبيق صنّاع المحتوى. |
type | Type | النوع |
leader | Leaderboard | لوحة ترتيب |
leaderD | The top creators win | الأوائل بيكسبوا |
target | Target | هدف |
targetD | Everyone who hits the goal wins | كل اللي يوصل للهدف بيكسب |
boost | Commission boost | زيادة العمولة |
boostD | Every delivered sale earns more | كل بيعة بتتسلّم بتكسب أكتر |
rankBy | Rank by | الترتيب بـ |
bySales | Delivered sales ({currency}) | المبيعات اللي اتسلّمت ({currency}) |
byOrders | Delivered orders | الطلبات اللي اتسلّمت |
winners | Number of winners | عدد الفايزين |
goal | Goal | الهدف |
goalKind | Goal counts | الهدف بيتحسب بـ |
kindOrders | delivered orders | طلبات اتسلّمت |
kindSales | {currency} delivered sales | {currency} مبيعات اتسلّمت |
maxWinners | Max winners | أقصى عدد فايزين |
maxHint | Caps the budget held from the wallet. | بيحدد أقصى ميزانية بتتحجز من المحفظة. |
boostL | Boost | الزيادة |
times | ×{n} commission | ×{n} عمولة |
cap | Cap on the extra commission ({currency}) | أقصى عمولة زيادة ({currency}) |
capHint | The boost stops once the extra paid reaches this. | الزيادة بتقف لما اللي اتدفع زيادة يوصل للرقم ده. |
delivered | [object Object] | [object Object] |
leaderNote | [object Object] | [object Object] |
boostNote | [object Object] | [object Object] |
join | Who can join | مين يقدر يشترك |
public | Public | عام |
publicD | Any approved creator. Non-members send a join request you approve | أي صانع محتوى متقبل. اللي مش مشترك بيبعت طلب انضمام إنت بتوافق عليه |
affiliates | {brand} affiliates only | المشتركين في {brand} بس |
affiliatesD | Only creators already in the program | صنّاع المحتوى اللي في البرنامج بس |
everyone | Every approved creator with a code at any brand that has an active campaign can take part. | أي صانع محتوى متقبل عنده كود عند أي براند ليه حملة شغّالة يقدر يشترك. |
invite | You can also invite specific creators after launch. Customer affiliates can’t join challenges or get gifts. | تقدر كمان تدعو صنّاع محتوى بعينهم بعد الإطلاق. عملاء الأفلييت مينفعش يدخلوا تحديات ولا ياخدوا هدايا. |
rewardL | How winners are paid | الفايزين بياخدوا إيه |
cash | Cash | كاش |
cashD | Paid to each winner | بيتدفع لكل فايز |
gift | Gift | هدية |
giftD | From confirmed gift stock only | من مخزون الهدايا المتأكد بس |
perWinner | Per winner ({currency}) | لكل فايز ({currency}) |
paidWhen | Winners are paid: | الفايزين بياخدوا فلوسهم: |
boostReward | [object Object] | [object Object] |
boostExtra | extra. | زيادة. |
issue.brand | Choose who it’s for. | اختار التحدي لمين. |
issue.name | Add a name. | اكتب اسم. |
issue.starts | Pick a start date. | اختار تاريخ البداية. |
issue.ends | Pick an end date. | اختار تاريخ النهاية. |
issue.order | It must end after it starts. | لازم يخلص بعد ما يبدأ. |
issue.whole | Enter a whole number, 1 or more. | اكتب رقم صحيح، 1 أو أكتر. |
issue.amount | Enter an amount above 0 (up to 2 decimals). | اكتب مبلغ أكبر من صفر (لحد رقمين بعد العلامة). |
issue.giftId | Choose a gift. | اختار هدية. |
issue.required | Required. | لازم. |
Design guidance
How the BRICKS design system uses ChallengeRewardFields. Written in docs/content/components/ChallengeRewardFields.md; the props above are read from the code, which wins where the two disagree.
The challenge builder's reward steps: part="goal" is step 2 (Leaderboard, Target or Commission boost and that type's fields), part="payout" is step 4 (cash per winner or a gift from confirmed stock, and when winners are paid); put each in a BuilderStepCard.
ChallengeRewardFields draws steps 2 and 4 of the PR v3 mock's P.builder, which the design system used to compose by hand. Step 2 offers the type as three choice cards (Leaderboard · "The top creators win", rasp; Target · "Everyone who hits the goal wins", lime; Commission boost · "Every delivered sale earns more", sky) and only that type's fields, with "Only delivered orders count." under them. Step 4 offers Cash · "Paid to each winner" or Gift · "From confirmed gift stock only" (a ChallengeGiftPicker), then "Winners are paid:" with the open decision T4. For a commission boost step 4 has no choice: one line says the boost is the reward ("×2 commission, capped at EGP 5,000 extra."). Controlled and generic over the draft, like the other steps.
Anatomy
part="goal"
- Type: a three-column
ChoiceGroup(.kit-pr-bchoices, 18px over the fields). - Leaderboard: "Rank by" (Delivered sales (EGP) / Delivered orders, S6 tag) and "Number of winners"; note "Only delivered orders count. On a tie, whoever reached the number first ranks higher." (T3, T7).
- Target: "Goal" (a 110px number + a "Goal counts" select: delivered orders / EGP delivered sales, S6 tag) and "Max winners" ("Caps the budget held from the wallet."); note with T3.
- Commission boost: "Boost" (×1.5 / ×2 / ×3 commission) and "Cap on the extra commission (EGP)" ("The boost stops once the extra paid reaches this."); note on overlapping boosts (T3, C4).
part="payout"
- How winners are paid: a two-column
ChoiceGroup(Cash, Gift). - Cash: "Per winner (EGP)" (S7 tag). Gift:
ChallengeGiftPickerovergifts, needing as many units as winners, with "Gift stock →" (onOpenStock); its error line under it. - Paid when: "Winners are paid:" +
paidWhenor the "Open · T4" tag.
Variants
| Prop | Value | Draws | When to use |
|---|---|---|---|
part | goal (default) | Step 2, Type & goal | The type and its target |
payout | Step 4, Reward | Cash or gift; a boost's one-line reward | |
value.type | leader / target / boost | That type's fields only | Set by the type cards |
value.reward | cash / gift | Per-winner amount or the gift picker | Set by the reward cards |
validate | false (default) / true | Built-in messages under this step's fields | Show problems in place |
money | e.g. { decimals: 'auto' } | "EGP 5,000" for the cap and gift cost | The mock's whole-pound money |
States
| State | Trigger |
|---|---|
| Field errors | validate: "Enter a whole number, 1 or more." (winners, goal orders), "Enter an amount above 0 (up to 2 decimals)." (sales goal, cap, per winner), "Choose a gift." |
| Server errors | errors={{ perWinner: '…' }}: shown under the field, over the built-in checks |
| No gift stock | gifts empty: the picker's empty state with brandName and "Gift stock →" |
| Gift out | a ConfirmedGift with left: 0: listed, not choosable |
| Boost reward | part="payout" with type: 'boost': the one-line reward, no fields |
| Decision tags | inside a DecisionTagsProvider visible: S6, S7, T3, T7, C4 tags; T4 always shows as an open pill |
Usage
import { useState } from 'react';
import { BuilderStepCard, ChallengeRewardFields, defaultChallengeDraft, type ChallengeDraft } from '@ergasti/bricks';
export function TypeAndGoalStep() {
const [draft, setDraft] = useState<ChallengeDraft>(defaultChallengeDraft('glow'));
return (
<BuilderStepCard title="Type & goal" step={2} onBack={() => {}} onContinue={() => {}}>
<ChallengeRewardFields value={draft} onChange={(next) => setDraft(next)} money={{ decimals: 'auto' }} />
</BuilderStepCard>
);
}// Step 4 with a gift from Glow Lab's confirmed stock
import { useState } from 'react';
import { BuilderStepCard, ChallengeRewardFields, defaultChallengeDraft, type ChallengeDraft, type ConfirmedGift } from '@ergasti/bricks';
const gifts: ConfirmedGift[] = [{ id: 'serum', name: 'Glow serum', cost: '300.00', left: 18 }, { id: 'kit', name: 'Lip kit', cost: '450.00', left: 0 }];
export function RewardStep() {
const [draft, setDraft] = useState<ChallengeDraft>({ ...defaultChallengeDraft('glow'), reward: 'gift' });
return (
<BuilderStepCard title="Reward" step={4} onBack={() => {}}>
<ChallengeRewardFields part="payout" value={draft} onChange={(next) => setDraft(next)} gifts={gifts} brandName="Glow Lab" onOpenStock={() => {}}
decisions={[{ id: 'T4', question: 'When challenge rewards are paid' }]} money={{ decimals: 'auto' }} validate />
</BuilderStepCard>
);
}Where it appears
- PR Portal › Affiliate programs › Challenges › New challenge › step 2, Type & goal, and step 4, Reward (the mock's
P.builder,st===2andst===4). Screens: PR · Challenge builder, PR · Challenge builder · Reward.
Guidelines
Do
- Use one
ChallengeDraftfor every step; switching type keeps the other types' values. - Pass the brand's confirmed stock only in
gifts; the picker greys out gifts with nothing left. - Leave
paidWhento the T4 tag until the product decides it.
Don't
- Don't show a reward choice for a boost;
part="payout"already says the boost is the reward. - Don't parse the typed money as floats;
challengeIssueschecks in cents and the server checks again. - Don't add a fourth type card; the three are the product's types (
ChallengeType).
RTL and Arabic
Cards and the paired fields mirror; amounts stay dir="ltr". Arabic: "النوع", "لوحة ترتيب", "هدف", "زيادة العمولة", "عدد الفايزين", "أقصى عدد فايزين", "×2 عمولة", "الفايزين بياخدوا إيه", "كاش" / "هدية", "لكل فايز (…)", "الفايزين بياخدوا فلوسهم:". Arabic-Indic digits are accepted in every number field. Override with labels or labels.prChallengeBuilder.
Tokens
--line, --card, --ink, --ink-3, --rasp, --bad, --field-h, --field-radius, --focus-ring-field, --kit-chevron (fields), --color-control-border-hover, --focus-ring (choice cards), --butter, --butter-ink (T4 pill), --sky, --sky-ink (tags).
Accessibility
- The type and reward cards are
ChoiceGroups:role="radiogroup"named "Type" / "How winners are paid", one tab stop, arrow keys choose. - Fields are
FormFields with labels; the Target goal pairs a labelled input with a select named "Goal counts", and its error is tied byaria-describedbywitharia-invalid. - The gift error is
role="alert".
Found in the source
- Roles in the markup:
alert. - ARIA attributes set:
aria-invalid,aria-describedby,aria-label.
Read from the component's source and tests. See Accessibility for the patterns the library follows.
Related
BuilderStepCard: the card around each part.ChallengeGiftPicker: the gift choice insidepart="payout".ChallengeBasicsFields,ChallengeAudienceFields: the other steps.ChallengeSummary: totals the reward into the budget held.
See also: FormField · Icon · Money · MoneyNote · useBricks · useLanguage · ChoiceGroup · useDecisionTagsVisible · PageGrid · Stepper
Source
src/pr/challenges/ChallengeRewardFields.tsx (line 55) on GitHub.