BuilderStepCard
One step of the challenge builder (the v3 mock's builder card): the step's name with "Step n of 4" at the end of the header, its fields, then a ruled footer with Back at the start and "Continue →" at the end, or, on the last step, "Check the summary, then launch →" (the summary card beside it launches). Put a Stepper above it and the ChallengeSummary (layout="flat") beside it, in a PageGrid split="8-4" stickyAside.
import { BuilderStepCard } 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 prBuilderStep, or with the component's own prop where it has one. A {name} is a value the component fills in.
| Key | English | Arabic |
|---|---|---|
stepOf | Step {n} of {of} | خطوة {n} من {of} |
back | Back | رجوع |
next | Continue | كمّل |
last | Check the summary, then launch → | راجع الملخص، وبعدين ابدأ ← |
working | Working… | لحظة… |
Design guidance
How the BRICKS design system uses BuilderStepCard. Written in docs/content/components/BuilderStepCard.md; the props above are read from the code, which wins where the two disagree.
One step of the challenge builder: the step's name with "Step n of 4", its fields, and a ruled footer with Back and "Continue →"; wrap each builder step's fields in it.
BuilderStepCard is the PR v3 mock's builder card in P.builder (New challenge), which the design system used to compose by hand from a card, a header line and a footer. It holds one of ChallengeBasicsFields (step 1), ChallengeRewardFields (steps 2 and 4) or ChallengeAudienceFields (step 3). On the last step the footer's end becomes the muted "Check the summary, then launch →": the ChallengeSummary beside it launches. Put a Stepper above it and the summary (layout="flat") beside it in a PageGrid split="8-4" stickyAside.
Anatomy
- Card (
.kit-pr-bstep): the step's name as its heading (headingLevel, default 2). - Step count: muted "Step 1 of 4" at the header's end (no wrap).
- Body:
children, the step's fields. - Footer (
footerAlign="between", ruled): Back (ghost) at the start; at the end Continue → (ink, arrow icon) or, on the last step, the mutedlastHint/ "Check the summary, then launch →".
Variants
| Prop | Value | Look | When to use |
|---|---|---|---|
step | 1 | Back disabled | The first step |
< steps | Back + Continue → | Middle steps | |
>= steps | Back + last-step hint, no Continue | The last step (Reward) | |
steps | default 4 | "Step n of 4" | The builder's four steps |
lastHint | node | Replaces the last-step hint | A different hand-off to the summary |
headingLevel | 2 (default), 3, 4 | Heading level only | Under a page heading of another level |
States
| State | Trigger |
|---|---|
| Back disabled | step <= 1, or no onBack |
| No Continue | onContinue not set (and not the last step): nothing at the footer's end |
| Busy | busy: Continue disabled, aria-busy, reads "Working…" |
| Blocked | continueDisabled: Continue disabled. Default false: the mock lets PR move on and the summary lists what is missing |
Usage
import { useState } from 'react';
import {
BuilderStepCard, ChallengeAudienceFields, ChallengeBasicsFields, ChallengeRewardFields, ChallengeSummary, PageGrid, Stepper,
defaultChallengeDraft, type ChallengeDraft,
} from '@ergasti/bricks';
const STEPS = ['Basics', 'Type & goal', 'Who can join', 'Reward'];
const BRANDS = [{ id: 'glow', name: 'Glow Lab' }, { id: 'nile', name: 'Nile Threads' }, { id: 'kemet', name: 'Kemet Home', paused: true }];
export function NewChallenge() {
const [step, setStep] = useState(0);
const [draft, setDraft] = useState<ChallengeDraft>({ ...defaultChallengeDraft('glow'), starts: '2026-12-01', ends: '2026-12-31' });
const brandName = BRANDS.find((b) => b.id === draft.brand)?.name ?? '';
const fields = [
<ChallengeBasicsFields key="basics" value={draft} onChange={(next) => setDraft(next)} brands={BRANDS} />,
<ChallengeRewardFields key="goal" value={draft} onChange={(next) => setDraft(next)} money={{ decimals: 'auto' }} />,
<ChallengeAudienceFields key="join" value={draft} onChange={(next) => setDraft(next)} brandName={brandName} trndrWide={draft.brand === 'all'} />,
<ChallengeRewardFields key="reward" part="payout" value={draft} onChange={(next) => setDraft(next)} brandName={brandName} money={{ decimals: 'auto' }} />,
];
return (
<PageGrid split="8-4" align="start" stickyAside>
<div>
<Stepper steps={STEPS} current={step} onStep={setStep} />
<BuilderStepCard title={STEPS[step]} step={step + 1} onBack={() => setStep(step - 1)} onContinue={() => setStep(step + 1)}>
{fields[step]}
</BuilderStepCard>
</div>
<ChallengeSummary layout="flat" flatDensity="mock" name={draft.name} brand={{ id: draft.brand, name: brandName || 'All brands' }} status="upcoming"
dates="1 Dec → 31 Dec" goal="Top 10 by sales" 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' }} onPrimary={() => {}} onSaveDraft={() => {}} money={{ decimals: 'auto' }} />
</PageGrid>
);
}// A step saved before moving on
import { BuilderStepCard } from '@ergasti/bricks';
export function SavingStep({ saving }: { saving: boolean }) {
return (
<BuilderStepCard title="Type & goal" step={2} busy={saving} onBack={() => {}} onContinue={() => {}}>
<p>Leaderboard · top 10 by delivered sales</p>
</BuilderStepCard>
);
}Where it appears
- PR Portal › Affiliate programs › Challenges › New challenge (the mock's
P.builder; also "Build the requested challenge" from a brand request), every step. Screens: PR · Challenge builder, PR · Challenge builder · Reward.
Guidelines
Do
- Keep the step names the mock's: Basics, Type & goal, Who can join, Reward; use the same list for the
Stepper. - Let PR move on with gaps; the summary card's warnings and
onEditStepbring them back. - Use
busywhile a step is saved as a draft.
Don't
- Don't put Launch in the card; the summary card launches.
- Don't set
continueDisabledjust because a field is empty. - Don't change Continue's colour: PR Portal commits in
ink; theraspLaunch belongs to the summary.
RTL and Arabic
The header and footer mirror (Back on the right, Continue on the left), and the Continue arrow flips (scaleX(-1) under [dir='rtl']). Arabic: "خطوة 1 من 4", "رجوع", "كمّل", "راجع الملخص، وبعدين ابدأ ←", "لحظة…"; numbers through count(). Override with labels or labels.prBuilderStep.
Tokens
--ink-3 (step count, last hint), Card tokens (--card, --line, --r-lg), Button ink / ghost tokens.
Accessibility
- A
Cardwith a real heading (headingLevel); the step count is plain text after it. - Back and Continue are buttons; the arrow is
aria-hidden. Busy setsaria-busy.
Found in the source
- ARIA attributes set:
aria-busy,aria-hidden.
Read from the component's source and tests. See Accessibility for the patterns the library follows.
Related
ChallengeBasicsFields,ChallengeRewardFields,ChallengeAudienceFields: the step bodies.Stepper: the step tabs above it.ChallengeSummary: the sticky summary that launches.
See also: Button · Card · useLanguage · PrIcon · PageGrid · BrandRequestCard · ChallengeGiftPicker
Source
src/pr/challenges/BuilderStepCard.tsx (line 59) on GitHub.