Skip to Content
BBRICKSv0.7.4
PR PortalChallenges

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.

Pinned to Arabic
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.

prBuilderStep
KeyEnglishArabic
stepOfStep {n} of {of}خطوة {n} من {of}
backBackرجوع
nextContinueكمّل
lastCheck the summary, then launch →راجع الملخص، وبعدين ابدأ ←
workingWorking…لحظة…

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

  1. Card (.kit-pr-bstep): the step's name as its heading (headingLevel, default 2).
  2. Step count: muted "Step 1 of 4" at the header's end (no wrap).
  3. Body: children, the step's fields.
  4. Footer (footerAlign="between", ruled): Back (ghost) at the start; at the end Continue → (ink, arrow icon) or, on the last step, the muted lastHint / "Check the summary, then launch →".

Variants

PropValueLookWhen to use
step1Back disabledThe first step
< stepsBack + Continue →Middle steps
>= stepsBack + last-step hint, no ContinueThe last step (Reward)
stepsdefault 4"Step n of 4"The builder's four steps
lastHintnodeReplaces the last-step hintA different hand-off to the summary
headingLevel2 (default), 3, 4Heading level onlyUnder a page heading of another level

States

StateTrigger
Back disabledstep <= 1, or no onBack
No ContinueonContinue not set (and not the last step): nothing at the footer's end
Busybusy: Continue disabled, aria-busy, reads "Working…"
BlockedcontinueDisabled: 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

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 onEditStep bring them back.
  • Use busy while a step is saved as a draft.

Don't

  • Don't put Launch in the card; the summary card launches.
  • Don't set continueDisabled just because a field is empty.
  • Don't change Continue's colour: PR Portal commits in ink; the rasp Launch 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 Card with a real heading (headingLevel); the step count is plain text after it.
  • Back and Continue are buttons; the arrow is aria-hidden. Busy sets aria-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.

See also: Button · Card · useLanguage · PrIcon · PageGrid · BrandRequestCard · ChallengeGiftPicker

Source

src/pr/challenges/BuilderStepCard.tsx (line 59) on GitHub.

On this page