Skip to Content
BBRICKSv0.7.4
Getting started

Migration

What an app changes when it moves from one release to the next, 0.1.0 to the pending 0.6.0, rendered from MIGRATION.md.

Rendered from MIGRATION.md at build time. Where it disagrees with the code, the code wins.

This guide says what an app changes when it raises @ergasti/bricks from one release to the next. Read every part between the version you are on and the one you are moving to; the parts add up, so an app can skip releases.

FromToRead
0.1.00.2.0 / 0.3.0parts 1 to 7
0.3.00.4.0part 8
0.4.00.5.0part 9
0.5.00.6.0part 10
0.6.00.7.0part 11

Each part says what looks or behaves differently with no code change, what is deprecated and what replaces it, and what may need a code change. Deprecated APIs keep working until 1.0. The full list of changes for each release is in packages/bricks/CHANGELOG.md (the Changelog page of the docs, with any changesets not yet released).

Upgrade one screen at a time: bump the package, review each screen against its v3 mock (F6), then move that screen's deprecated calls.

From 0.1.0: parts 1 to 7

Use 0.3.0, not 0.2.0. 0.2.0 was published from the code as it stood before the review. The review fixes (part 5: logic, data, security, packaging, accessibility), the money display options and the screenshot edits are in 0.3.0. Everything below marked 0.2.0 holds for 0.3.0 too; an app on 0.1.0 can move straight to 0.3.0.

0.2.0 makes the Brand Dashboard v3 mock the default look, makes the v3 list pieces the standard, and moves the TRNDR-specific tables into a preset behind a provider. It also adds what a 0.1.0 app did not have: the shell, the data hooks, the brand blocks, and the PR blocks and theme (part 7). Code written for 0.1.0 still compiles. Some things look or behave differently with no code change (part 1); the console-era duplicates still work but are deprecated and will be removed once the Brand Console has moved (parts 2 and 4); the provider is optional (part 3); a few review fixes may need a code change (part 5).

1. What changes with no code change

Switch: the iOS switch is the default

0.1.0 drew a 38 × 22 accent-coloured track unless you passed variant="ios". 0.2.0 draws the 51 × 31 iOS switch (green when on) by default. variant="ios" still works and changes nothing. For a dense row that needs the old size:

// 0.1.0: the small track
<Switch label="Payout requests" checked={on} onChange={setOn} />
// 0.2.0: the same small track
<Switch label="Payout requests" checked={on} onChange={setOn} variant="compact" />

New: id (for a <label htmlFor>) and aria-describedby (a hint read with the switch).

<label htmlFor="gifts">Gifts</label>
<Switch id="gifts" aria-describedby="gifts-hint" label="Creators can pick gifts" checked={on} onChange={setOn} />
<p id="gifts-hint">One gift per challenge.</p>

Pager: always the v3 numbered-range pager

Pager draws the v3 ‹ 1 … 4 5 6 … 31 › pager with 36px rounded buttons whatever you pass. The 0.1.0 console pager ("Previous" / "Next" words, the console-list-pager classes) is gone. Pass perPage to get the mock's summary:

// 0.1.0: "Page 5 of 31 · 304 in total", Previous / Next
<Pager page={5} lastPage={31} total={304} loading={false} language="en" label="Creators" onPage={setPage} />
// 0.2.0: "Showing 41–50 of 304", ‹ 1 … 4 5 6 … 31 ›
<Pager page={5} lastPage={31} total={304} perPage={10} loading={false} language="en" label="Creators" onPage={setPage} />

Without perPage the summary still reads "Page 5 of 31 · 304 in total" (the range cannot be known), inside the v3 pager. A list on one page says "304 items" and shows no buttons. The arrows are named "Previous page" / "Next page" (they were "Previous" / "Next"); while loading, the other page buttons are disabled (they were aria-disabled). Tests that find the pager by those names or classes need updating.

Form fields (FormField)

The v3 field: 42px controls, radius 12 (was 14), the kit's own select chevron (14px at 14px from the edge, mirrored in RTL), a raspberry border with a second raspberry pixel and a soft 4px halo on focus (--focus-ring-field) instead of the browser outline, #CFD1DA on hover, a bad-red outline when error is set (or the control has the class err), raspberry 18px checkboxes, a 96px textarea, and an ink label. No prop changes.

Tables, tiers, tiles

  • RowList (and the rows of a sortable RowList): the v3 .tbl look: a #FAFAFC head, cells padded 12 × 14 (were 12 × 18), 13.5px text, a #FBF6F8 row hover, 18px raspberry checkboxes and a 40px empty state.
  • TierBadge: the v3 tier chip, the same as TierChip (a dot, 11/700; Rising lime, Established sky, Elite gold with a star, Influential teal). Its classes (kit-tier kit-tier--<key>) are unchanged.
  • Tile corner shape (deco): the v3 size, 150px at .12 (was 110px at .16).

styles.css is bigger; kit.css is the kit alone

styles.css now also holds the shell, blocks and PR blocks' styles (about 150 KiB minified, 153,653 bytes, and about 25 KiB gzipped; all four packages: kit.css is 63 KiB of it, pr.css 39, blocks.css 28 and shell.css 19; tokens.css, 10 KiB, is separate). If the app uses only the kit, load the kit's own file instead:

// 0.1.0
import '@ergasti/bricks/tokens.css';
import '@ergasti/bricks/styles.css';
// 0.2.0, kit only (add shell.css / blocks.css / pr.css after it for those packages)
import '@ergasti/bricks/tokens.css';
import '@ergasti/bricks/kit.css';

Theme hooks are declared on :root

tokens.css now declares the theme hooks (--seg-*, --btn-ghost-*, --field-*, --modal-*, --drawer-*, --page-*, --bulk-*, --chipf-pad, --shell-*) with the brand values, several as aliases (--seg-track: var(--soft), --btn-ghost-ink: var(--rasp-d), --bulk-line: var(--color-accent-border), --shell-side-bg: var(--color-sidebar), …). An alias is resolved where it is declared, so an app that re-themes on a wrapper (not on :root) by changing --soft, --card, --ink, --rasp-d, --rasp-50, --color-accent-border, --color-sidebar or --color-nav-active must set the hooks built on them in the same block, as themes/pr.css does. Overrides on :root need nothing.

Data in drawers and lists

  • useDrawerResource with no fetcher now GETs through the DataProvider's HTTP client (or a same-origin default client): the request gains X-Requested-With, onUnauthorized runs on a 401/419, and the error's message is the server's viewer-facing message (it was always ''). A DataProvider with a baseUrl now prefixes drawer URLs too: pass them relative to that base (/creators/7, not /api/creators/7). fetchJson still works as an explicit fetcher, but is deprecated.
  • useListState's error is a DataError: message (the server's, when meant for the viewer, else ''), and code / errors when sent. Code that showed its own text only when message === '' keeps working.
  • LIST_STATE_EVENT is now URL_STATE_EVENT (same bc:url value).

gallery.html is one page with sections and shows one language at a time. Old links still land: #blocks and #pr open those sections (#pr in the pr theme), ?shell=ar&look=pr still opens the full shell page. The default view (the Kit section, English) still holds the [data-fragment] blocks. A test that expected English and Arabic stacked on one page opens ?section=kit&lang=ar for the Arabic half.

The select chevron no longer reaches every select

0.1.0 shipped html body select { … }: every single <select> on a page that loaded styles.css got the kit's chevron. 0.2.0 scopes it to the kit's console-era selects (SelectBox, SortSelect, a select in Toolbar's filters slot). FormField and ListToolbar selects draw the v3 chevron from their own rules. A select of your own that relied on the global rule:

// 0.1.0: styled by the global rule
<select value={tier} onChange={onTier}>…</select>
// 0.2.0: opt in with the class the kit's selects carry
<select className="kit-select" value={tier} onChange={onTier}>…</select>

2. Deprecated: the console-era duplicates (still working, removed later)

Each of these has a @deprecated TSDoc tag naming its replacement, so your editor strikes it through.

Sortable RowList → DataTable

RowList stays as the plain, non-sortable list. Its sorting props are deprecated: sort, onSort, and the column's sortKey and sortFirst (and the SortState type; DataTable takes the same shape as DataSort).

RowList (0.1.0)DataTable (0.2.0)
columns[].idcolumns[].key
columns[].headercolumns[].label (a string also labels the phone card; a node needs cardLabel)
columns[].cell(row)columns[].render(row)
columns[].type: 'num'columns[].align: 'end' (tabular digits)
columns[].width (a grid track)columns[].width (a CSS width such as '30%')
columns[].sortKeycolumns[].sortKey
columns[].sortFirst (default: num high to low, others A–Z)columns[].sortFirst (default high to low: set 'asc' on name columns)
columns[].figurecolumns[].figure (the "?" sits beside the sort button)
columns[].terma label node, plain words in cardLabel
sort / onSort (SortState)sort / onSort (DataSort)
onRowClick, selection, isDim, loading, error, onRetrythe same props
empty / emptyTextempty (default "Nothing matches these filters." with onClearFilters)
// 0.1.0
<RowList label="Creators" language={language} rows={rows} rowKey={(r) => r.id} sort={sort} onSort={setSort} onRowClick={open}
  columns={[
    { id: 'name', header: 'Creator', type: 'main', sortKey: 'name', cell: (r) => <CreatorCell id={r.id} name={r.name} identity={r.identity} /> },
    { id: 'sales', header: 'Sales', type: 'num', sortKey: 'sales', figure: 'creator_sales', cell: (r) => <Money value={r.sales} /> },
  ]} />
// 0.2.0
<DataTable label="Creators" language={language} rows={rows} rowKey={(r) => r.id} sort={sort} onSort={setSort} onRowClick={open}
  columns={[
    { key: 'name', label: 'Creator', sortKey: 'name', sortFirst: 'asc', render: (r) => <CreatorCell id={r.id} name={r.name} identity={r.identity} /> },
    { key: 'sales', label: 'Sales', figure: 'creator_sales', sortKey: 'sales', align: 'end', render: (r) => <Money value={r.sales} /> },
  ]}
  footer={<Pager page={page} lastPage={lastPage} total={total} perPage={20} loading={loading} label="Creators" onPage={setPage} />} />

SortSelect → ListToolbar sort

SortSelect and its SortOption / SortValue types are deprecated. ListToolbar's sort does the same: an option may carry its own starting order, picking it passes that order, the ⇅ button flips, an unknown value shows the first option, and no options means no "Sort by".

SortSelect (0.1.0)ListToolbar sort (0.2.0)
options: [{ key, dir, label }]options: [[key, label, dir]] (dir optional)
value: { key, dir }value: key, dir
onChange({ key, dir }) (a pick or a flip)onChange(key, dir?) for a pick, onFlip() for ⇅
label ("Sort by")label (default "Sort by" / "رتّب حسب")
idnot needed: the visible label wraps the select
// 0.1.0
<SortSelect id="sort" label="Sort by" language={language} value={sort} onChange={setSort}
  options={[{ key: 'sales', dir: 'desc', label: 'Sales' }, { key: 'name', dir: 'asc', label: 'Name (A–Z)' }]} />
// 0.2.0
<ListToolbar language={language}
  sort={{ value: sort.key, dir: sort.dir, options: [['sales', 'Sales', 'desc'], ['name', 'Name (A–Z)', 'asc']],
    onChange: (key, dir) => setSort({ key, dir: dir ?? sort.dir }), onFlip: () => setSort({ ...sort, dir: sort.dir === 'asc' ? 'desc' : 'asc' }) }} />

Toolbar is not deprecated, but ListToolbar is the standard toolbar for a list and now covers everything Toolbar did: reset ("Reset filters", shown only while a filter is set) and a filters slot for any other control.

Toolbar (0.1.0)ListToolbar (0.2.0)
search={<SearchBox …/>}search={{ value, onChange, placeholder }} (waits for a pause in typing)
chips={<FilterChips …/>}chips={{ label, value, options, onChange }}
filters={<SelectBox …/>}selects={[{ id, label, value, options, onChange }]}
filters={<Segmented …/>} (any node)filters={<Segmented …/>}
sort={<SortSelect …/>}sort={{ … }} (above)
reset={{ active, onReset, language }}reset={{ active, onReset }}
actionsactions
// 0.1.0
<Toolbar search={<SearchBox id="q" label="Search" value={q} onChange={setQ} />}
  filters={<SelectBox id="tier" label="Tier" hideLabel value={tier} options={TIERS} onChange={setTier} />}
  reset={{ active: q !== '' || tier !== '', onReset: reset, language }} actions={<Button size="sm">Export CSV</Button>} />
// 0.2.0
<ListToolbar language={language} search={{ value: q, onChange: setQ, placeholder: 'Search name or coupon' }}
  selects={[{ id: 'tier', label: 'Tier', value: tier, options: TIERS, onChange: setTier }]}
  reset={{ active: q !== '' || tier !== '', onReset: reset }} actions={<Button size="sm">Export CSV</Button>} />

PersonCell avatarSrc / photo → CreatorCell

PersonCell stays (a name, the handle line, a sub). Its photo path is deprecated: CreatorCell draws identity.avatarUrl (initials when there is none or it fails), the handle, the tier chip and sub on one muted line.

// 0.1.0
<PersonCell id={c.id} name={c.name} identity={c.identity} language={language} photo tier={c.tier} />
<PersonCell id={c.id} name={c.name} identity={c.identity} language={language} avatarSrc={c.identity.avatarUrl} />
// 0.2.0
<CreatorCell id={c.id} name={c.name} identity={c.identity} language={language} tier={c.tier} />

3. The provider and the TRNDR preset (optional)

Every component's language prop is now optional (kit, shell, blocks and PR blocks alike). A BricksProvider near the root gives the language, the statuses, the tiers, the currency, the money "?" dictionary and label overrides to everything below it, and the data hooks' DataProvider takes its language when it is not given one. With no provider the kit behaves exactly as 0.1.0 (TRNDR statuses and tiers, EGP); <BricksProvider preset={trndrPreset}> draws the same markup (a test compares it with 0.1.0's).

// 0.1.0: the language on every component, the notes in their own provider
<MoneyNotesProvider notes={bootstrap.money_notes}>
  <StatusPill status="paid" language={language} />
  <Money value={row.total} language={language} />
</MoneyNotesProvider>
// 0.2.0: once at the root (a component's own `language` still wins)
<BricksProvider preset={trndrPreset} language={language} moneyNotes={bootstrap.money_notes}>
  <StatusPill status="paid" />
  <Money value={row.total} />
</BricksProvider>
PropWhat it does
presetStarts from the generic core with this preset over it (trndrPreset). Without it, the provider extends the one above it (or the built-in default).
language'en' / 'ar' for every component without its own language.
statuses{ key: { tone, en, ar } }, added to or replacing the preset's (StatusPill).
tiers, defaultTier{ key: { en, ar, bg?, ink? } } (TierChip, TierBadge); without bg / ink the --tier-<key>-* tokens colour the chip.
currency{ code, label: { en, ar }, format? } (Money, MoneyFigure, MoneyNote amounts, HeroCard).
moneyNotesThe money "?" dictionary. A MoneyNotesProvider below still wins.
labelsPer component and language: labels={{ saveBar: { en: { save: 'Publish' } } }}. Kit keys are in KitCopy; the packages' in PackageCopy (shell, walletHealthCard, groupCard, prApprovals, …). A component's own labels / copy prop still wins.
statusTablesNamed status tables a package reads apart from statuses: pr (PrStatusPill), prAudit (AuditAreaPill), prFraud (the fraud signal words, FraudSignalPill; extends FRAUD_SIGNALS). The TRNDR preset has pr and prAudit.
moneyHow every money figure is shown, a MoneyDisplay: { showCurrency, decimals: 0 | 2 | 'auto', compact, sign: 'negative' | 'always' }, over each slot's default.
moneyForThe same for one slot app-wide, keyed by MoneySlot (MONEY_SLOTS): moneyFor={{ 'walletLedger.entry': { showCurrency: true } }}. A component's own money prop still wins.

What moved to the preset: CONSOLE_STATUSES is now TRNDR_STATUSES (the old name still exports it), the tier names, CURRENCY (TRNDR_CURRENCY.label), the coupon chip wording, "TRNDR score" and "Managed by TRNDR". Inside a <BricksProvider preset={…}> that is not TRNDR's, those kit words fall back to the generic core ("Score", "Managed by the platform", no currency word) unless that preset gives its own.

Not yet generic: the brand blocks' and PR blocks' default words still name TRNDR and Paymob in places ("Set by TRNDR", "Send to TRNDR", "Card (Paymob)", about 67 strings). Another preset does not change them; override them per component with labels (or a component's labels prop) until the 1.0 clean-up moves them into trndrPreset.labels.

4. Deprecated names (still exported, removed in 1.0)

Each has a @deprecated tag naming its replacement:

DeprecatedUse
CONSOLE_STATUSESTRNDR_STATUSES, or the provider's statuses
isConsoleStatus(key)key in TRNDR_STATUSES, or the provider's statuses
ConsoleStatuskeyof typeof TRNDR_STATUSES, or string with the provider's statuses
CURRENCYTRNDR_CURRENCY.label, or the provider's currency
LIST_STATE_EVENTURL_STATE_EVENT (the same bc:url value)
formatAmount(value)formatMoney(value, { language, showCurrency: false, decimals: 'auto' }), the one money formatter
fetchJsonuseDrawerResource with no fetcher (the DataProvider's client)

DetailsDrawer → the composed v3 drawer body (0.5.0)

DetailsDrawer is deprecated: its tiles are bordered and its section headings 800 Inter, where the v3 mock's drawers use soft 14px tiles and 14/700 Jakarta headings. Compose the body from the pieces the blocks' panels use:

<Drawer open={open} onClose={close} title={<span className="kit-sr">{order.ref}</span>} hideTitle>
  <DrawerHead tone="butter" title={order.ref} sub={order.date} />
  <KeyValue items={[{ label: 'Order value', figure: 'order_line', value: <Money value={order.value} /> }, { label: 'Status', value: <StatusPill status={order.status} /> }]} />
  <h3 className="kit-blk-h3">Where the commission is</h3>
  <StepTimeline steps={steps} />
  <RowItems heading="Creator" label="Creator" items={[{ id: order.creatorId, lead: order.creatorName, onSelect: openCreator }]} />
</Drawer>
DetailsDrawerThe composed body
title, subtitle, lead (the plain header)Drawer title, hint, lead
heroDrawer hideTitle with a DrawerHead (tone, title, sub, lead) as the first child
tiles, sections[].rowsKeyValue (columns 1, 2 or 3)
sections[].title<h3 className="kit-blk-h3">, the 14/700 Jakarta heading
sections[].barsDetailsBars, a component of its own since 0.6.0 and not deprecated (variant="stacked" for the PR mock's score rows)
sections[].rankedRankList
sections[].contentthe node itself
actions, primary, noteDrawer footer

DetailsDrawer itself gets no new props: new looks go to the composed body. The recipe "Details drawer with one loading state" in the docs builds a composed drawer end to end.

5. Review fixes that may need a code change (0.3.0)

Found by the review of 0.2.0; the full list is the review-fixes changeset.

  • The HTTP client sends credentials only to trusted origins. The CSRF token, X-Requested-With and the shared headers go to the page's origin and to an absolute baseUrl's origin, never to another origin's absolute URL. A second API that must get them is listed:

    createHttpClient({ baseUrl: '/api', headers: { Authorization: `Bearer ${token}` }, trustedOrigins: ['https://files.example.com'] });
  • A 2xx page that is not JSON throws HttpError with code: 'not_json' (it resolved null). useAction shows it as a failure; a caller of the client that treated null as "the session ended" checks the code instead.

  • useAction has a busy result. A second run with another input while one is pending is not sent and resolves { ok: false, kind: 'busy' }. An exhaustive switch (result.kind) adds the case. An exception from your own action function is kind: 'error' (logged), no longer 'network'.

  • Pass a stable client to the data hooks. useResource reads again when its client changes; create the client once (DataProvider, a module constant or useMemo), not on every render.

  • CommissionInput is a text field (inputMode="decimal"): tests that found it as spinbutton find a textbox.

  • Select-all keeps other pages' picks in DataTable and RowList; a screen that cleared the selection on a page change does so itself.

  • Links from data go through safeHref: a javascript: (or data:, …) URL renders without an href. Use safeHref for your own links built from API data.

  • ESM only. dist has no CommonJS build. Jest with CommonJS transforms needs transformIgnorePatterns to let @ergasti/bricks through Babel / ts-jest, or run the tests with Vitest or Jest's ESM mode.

6. Small additions

// SaveBar: Save off while the draft has an error, Discard still works
<SaveBar dirty={dirty} saveDisabled={hasErrors} onSave={save} onDiscard={discard} />
// DataTable: dim a row, as RowList's isDim
<DataTable … isDim={(row) => !row.is_active} />
// formatMoney / amountInText: another currency word
formatMoney('1500.00', { language: 'en', currency: { en: 'SAR', ar: 'ر.س' } }); // "SAR 1,500.00"
// KeyValue: a money row's label becomes its "?" term
<KeyValue items={[{ label: 'Sales', figure: 'sales', value: <Money value={sales} /> }]} />

7. New packages (nothing to change; for reference)

PackageImportStyles
Shell: AppShell, Sidebar, AppHeader, HeaderSearch, BottomNav, …@ergasti/bricksshell.css (in styles.css)
Data hooks: createHttpClient, DataProvider, useResource, usePaged, useAction, useHashState, useUrlSort, …@ergasti/bricksnone
Brand blocks: WalletHealthCard, WalletLedger, GroupCard, ChallengeCard, FindCreatorCard, …@ergasti/bricksblocks.css (in styles.css)
PR blocks: ApprovalRow, AnnouncementComposer, BrandWalletCard, PrStatusPill, column presets, …@ergasti/brickspr.css (in styles.css)
pr theme@ergasti/bricks/themes/pr.css + data-bricks-theme="pr"variables only

The console moving its own shell, data hooks and screens onto these is W7 (PLAN.md §10), screen by screen.

8. 0.4.0: the console's group rate and gift rules

Nothing to change for an app on 0.3.0, apart from the gift rules' new hint wording. To replace a hand-built group rate dialog or gift rules card:

// The rate dialog: the server's bounds, set directly, the button says who it reaches ("… for creators who join later" when empty)
<SpecialCommissionForm mode="set" members={group.members} initial={{ kind, value }}
  limits={{ percent: { min: '0.01', max: 50 }, perItem: { min: '0.01', max: 10000 } }}
  onSubmit={({ kind, value }) => save(kind === 'per_item' ? 'fixed_per_item' : 'percent', value)}
  onCancel={close} onBackToStandard={group.commission ? backToStandard : undefined} />
// A rate wherever it is shown: "15%" / "EGP 30 per item"
<Pill tone="lime"><CommissionRate kind="per_item" value={group.commission.value} /></Pill>
// The cooldown follows best-gift-only
<GiftRulesCard value={rules} onChange={setRules} bestGiftOnly={bestInForce} />

9. 0.5.0: the Brand Console v3

0.5.0 adds what the Brand Console's v3 screens need. Most of it is opt-in. Check these before you upgrade:

  • An unnamed Switch no longer compiles. SwitchProps is a union: pass label, aria-labelledby, or rowLabelled (a switch in a KeyValue row's control, named by the row). Code that spreads a props object into Switch may need to pass the name explicitly.
  • Exhaustive code over widened types: ChallengeStatus gains 'scheduled' | 'paused' | 'closed', GroupCommission gains 'set' and 'mixed', and ButtonProps['variant'] gains 'danger' | 'ok'. Some fields are now optional (MyCreator.coupon, KeyValueItem.value, GroupCardProps.sales, …) and some copy interfaces gained required keys (a whole copy object typed as one of them must add them; labels overrides are partial and unaffected). BricksConfig has a new platforms field.
  • Looks that change with no code change: dialog titles are 700 (the theme hook --dlg-title-fw; the pr theme keeps 800), a money "?" inside a heading no longer makes it taller, WalletHealthCard draws only the thresholds you pass (below), and SpecialCommissionForm mode="set" says "Set special commission" (pass namesRate for 0.4.0's words).
  • Tests: the Invite button of FindCreatorCard and CreatorProfilePanel is aria-disabled when off, not natively disabled.
  • Deprecated: DetailsDrawer. Compose the v3 drawer body instead (part 4).

Kit pieces

Nothing to change for an app on 0.4.0. What the console's v3 screens use in place of their own pieces:

// Raw <a className="kit-btn …"> → ButtonLink (safeHref, new-tab words, download)
<ButtonLink href={whatsappUrl} variant="lime" size="sm" external>Contact TRNDR</ButtonLink>
<ButtonLink href={csvUrl} size="sm" download>Export CSV</ButtonLink>
// className="kit-btn--danger" on a Button → a variant
<Button variant="danger">Remove creator</Button>
// No YouTube anywhere in this app: once, at the provider (the PR portal keeps all three)
<BricksProvider preset={trndrPreset} platforms={['instagram', 'tiktok']}>…</BricksProvider>
// The bell with the server's count and its fetch states
<NotificationsMenu items={latest} unreadCount={unread_count} status={status} onRetry={reload} onOpen={reload} … />
// An average price without floats
<Money value={divideAmount(product.sales, product.units)} />

Drawers and cards

Nothing to change for an app on 0.4.0, unless it switches exhaustively over ChallengeStatus (three new states). To replace the console's own drawer bodies and cards:

// The creator drawer: the store's own facts and buttons; no coupon, no Copy coupon
<MyCreatorPanel creator={{ ...creator, coupon: creator.coupon ?? null }} tone="lime" groups={groups}
  facts={(builtIn) => [...builtIn, { key: 'sold90', label: 'Sold in your store · 90 days', figure: 'creator_sales', value: <Money value={sold90} /> }]}
  actions={<><Button variant="danger" onClick={remove}>Remove creator</Button><ButtonLink href={profileUrl}>Open full profile</ButtonLink></>} />
// The console's challenge states, as its card draws them
<ChallengeCard status="scheduled" … />   // also 'paused', 'closed' ("Ended")
// Receipts
<ProofButton kind="download" href={receiptUrl} context={`ref ${ref}`} />
<PayoutBatchDetail date={date} amount={amount} creators={n} receiptHref={receiptUrl} />   // method, reference, paidTo when the API sends them
<WalletLedger groups={groups} balance={balance} footer={<Pager … />} />
// The owner's settings card
<SettingsSection editable title="Motivation" tone="butter" rows={[{ label, control: <Switch … /> }]} action={{ label: 'Open payouts', onClick }} />

Find creators without cross-store figures

Nothing to change for an app on 0.4.0. The console's Find card and mini profile show only the creator's own facts:

<FindCreatorCard creator={creator} onOpen={open} onInvite={invite} inviting={sending} inviteDisabled={seatsLeft === 0} inviteDisabledReason="No seats left"
  stats={[{ key: 'engagement', label: 'Engagement', value: `${creator.engagement}%` }, { key: 'followers', label: 'Followers', value: compactCount(total) }, { key: 'since', label: 'On TRNDR since', value: creator.since }]} />
<CreatorProfilePanel creator={creator} tone="lilac" tiles={[/* Engagement, Followers, TRNDR score, On TRNDR since */]} note={seatsLeft === 0 ? noSeats : undefined} … />

Groups without TRNDR approval

Nothing to change for an app on 0.4.0, unless it switches exhaustively over GroupCommission (two new states) or relies on SpecialCommissionForm mode="set" naming the rate in its button (pass namesRate). The console's direct special commission, a % of sale or EGP per item:

// The card: an ok pill "20% of sale" / "EGP 30 per item", or "Mixed"; no sales figure until the API sends it
<GroupCard name={g.name} tone={g.tone} members={g.first_faces} memberCount={g.member_count}
  commission={g.rate ? { state: 'set', kind: g.rate.kind, value: g.rate.value } : g.mixed ? { state: 'mixed' } : { state: 'standard' }} onOpen={open} />
// The drawer
<GroupPanel commissionMode="set" … setOn={g.rate?.set_on} moreMembers={g.member_count - g.members.length}
  onAskCommission={openSetForm} onBackToStandard={backToStandard} />
// The form: % or EGP per item, the optional note
<SpecialCommissionForm mode="set" note members={g.member_count} … />

WalletHealthCard no longer assumes 20 % and 7 days

0.4.0 drew the "Low:" warning below 20 % of the last top-up and said "7 days" in its banners and legend when you passed neither lowPercent nor pauseDays. Those were invented, so 0.5.0 draws only what you pass: with neither, there is no "Low:" warning of the card's own, no legend, and no day count. To keep 0.4.0's card, pass the program's values (the server's, or the mock's 20 and 7), or pass health from the server:

<WalletHealthCard leftPercent={w.left_percent} lastTopup={w.last_topup} lowPercent={w.low_percent} pauseDays={w.pause_days} />
// or the server's verdict
<WalletHealthCard leftPercent={w.left_percent} lastTopup={w.last_topup} health={w.health} />

10. 0.6.0: v3 mock fidelity

0.6.0 adds on 0.5.0: options that let a screen match the Brand Dashboard v3 and PR Portal v3 mocks, a few PR Portal blocks, and default looks corrected to the mocks. Nothing is removed or renamed. Every export of 0.5.0 is still exported under the same name, and every prop of 0.5.0 still exists; new props are optional, and the changed types are wider (below). An app on 0.5.0 compiles unchanged, unless it switches exhaustively over PrStatus (see Changed types). Review the screens that use the components under "What looks different".

What looks different with no code change

Where an option brings the 0.5.0 look back, it is named.

Shell

  • Switch inside the shell's Sidebar or MobileNavSheet is small (41 × 25) and dark, the PR mock's sidebar switch. 0.5.0's look there: <Switch size="md" surface="light" … />. Switches elsewhere are unchanged. A DecisionsCard in the sidebar gets the small switch too.
  • HeaderSearch under 600px folds into a 44px search button that opens the box over the tools row. The pill: collapsible={false}. The search field is 44px tall on touch tiers (1024px and under).
  • The phone header (under 860px) keeps its tools on one row, scrolling sideways with a hidden scrollbar if they must, instead of wrapping; menus and the notifications panel hang from the header. Under 600px the raspberry "+ New" pill shows its icon only. No option.
  • Breadcrumb links are 44px tall tap targets on touch tiers (no visible change).
  • The pr theme's search pill is 190px at 1240px and under (260px above). 0.5.0's width: set --shell-search-w-narrow: 260px in your own [data-bricks-theme='pr'] rule, loaded after themes/pr.css.

Kit

  • In the pr theme, the Influential tier chip (TierChip, TierBadge) is the PR Portal v3 mock's lilac (--tier-influential-bg: #F0E8FF, --tier-influential-ink: #5B34A0). The brand default keeps 0.5.0's teal. 0.5.0's teal in the pr theme: set those two tokens to #E0F4F1 and #0F6A5C in your own [data-bricks-theme='pr'] rule, or pass bg / ink for the tier in the provider's tiers. In the pr theme the Influential chip looks like the other lilac chips there (the mock's own values): the group audience chip in Messages and the lilac status pills (gift_arrived, public_challenge, and the audit log's tiers and messages areas).
  • DataTable's footer sits in its own block 14px under the table, so a line such as "7 items" no longer touches it. A Pager footer keeps its own 14px; the footer is a plain block, so an inline item keeps its own width (a "Load more" button is not stretched). On touch tiers the head row has 3px more top padding (full 44px hit areas for the "?" and a tipped header's term). With chevron={false} the phone card's end padding is narrower. No option.
  • The pr theme's ListToolbar search box is 248px (was 260px). 0.5.0's width: --lt-search-w: 260px in your own [data-bricks-theme='pr'] rule.
  • CreatorCell with onOpen: the name button is 700 at the cell's font size (was 13.5px / 600). No option.
  • A Modal hint no longer keeps the browser's bottom margin: the body starts 12px higher. No option.
  • Gauge keeps 5.3px under the arc, so its card is about 5px taller. No option.
  • Card with a title (or a Card.Header inside it) is a region named by its heading. Nothing visible changes; screen readers list it as a named region. labelledBy still wins.
  • OpenRate, ShareBar and ProgressRow draw their figure as one text node ("62%", "8 / 20"). Nothing visible changes; a test that matched the number and the "%" as separate nodes needs updating.

Brand blocks

  • ChallengeRequestForm, SpecialCommissionForm, GroupForm: the actions row no longer adds 20px under the last field; a fieldset hint sits 6px under its legend (was 12); the request form's gift rows start 6px under the hint (was 8). ChallengeRequestForm draws the "(optional)" at the end of its dates and notes labels as a muted 12px span (the words are unchanged).
  • MembersPicker names are 13px (was 14) and sit 7px further in. GiftStockList rows are 75px (were 68). BonusDetail's "Open the challenge" sits 12px under the progress list (was 18).
  • ChallengeDetail's "Top creators in this challenge" sits 22px under the progress rows (was 34).
  • CreatorProfilePanel: a figure caption with a "?" keeps its 17.4px lines (a two-line caption is 35px, was 31).
  • CalloutCard layout="row": the title has no 4px under it, so the card is 2px shorter.

PR blocks

  • Leaderboard uses the mock's row grid: a 16px header line, cells padded 12px 6px, an 8px bar, rows 62px tall and 8px apart (the row pitch drops from 75px to 70px). With showPercent={false} the "% of #1" figure is now left out of the page instead of hidden with CSS. No option for the grid.
  • SenderCell: a brand sender's square is 28px (was the 38px brand cell square). The 38px square: avatarSize="md".
  • WaitingCell's days figure is 700 (it rendered at 900).
  • LoginCard: "Welcome back" is 700 (was 800) with −0.2px tracking; the footnote is 12px (was 13).
  • NumberSetting: "Reset to {default}" is centred on the input line (it sat at the top).
  • BrandWalletCard: the header no longer adds 8px under itself, so the Available / Held / Balance rows sit 8px higher.
  • TierLadder with basis="score": a range whose end falls below its start reads "40+" (it read "40–39").

New options, by area

All optional; left out, each keeps 0.5.0's look. The component pages list each prop.

  • Shell: Switch size and surface; AppHeader leading (a screen's tools before the search, the bell and "+ New" staying after it) and subtitleLines; HeaderSearch collapsible; SidebarUser avatarSize; the Icon name messages (an alias of speech); the theme hook --shell-search-w-narrow.
  • Kit: Card title, sub, badge, actions, headingLevel and variant="inset" (and Card.Header level); DataTable density="tight" and headDensity="compact"; ListToolbar extra and extraPlacement="newRow", and the hook --lt-search-w; Segmented size="sm"; KpiCard size="short" and an icon that takes an element; KpiGrid columns={2}; Tile size="kpi" and --tile-min-h for size="short"; ShareBar showValue; RankMedal size="lg"; Drawer headerStyle="pr", closeButton="float" and footerDivider; Drawer and Modal className; the new Quote.
  • Brand blocks: CalloutCard tones lilac, sky and butter; ProgressRow variant="bar"; RowItem valueTone="muted"; GiftStockItem seed; FindCreatorCard's --fc-cols hook.
  • PR blocks: Leaderboard rankSize, rankStyle, highlightTop, textSize, cutTone, noteSize and tieDetail; TierLadder scoreMax, scoreInfoHref, openTagTip and scoreText; DecisionTag and DecisionsCard tip="focus"; NumberSetting alwaysShowReset; SettingRow density="tight"; SenderCell avatarSize; AuditLogList / AuditLogEntry dot; BrandWalletCard topUpMethods; ApprovalActions fullWidth; RecordGiftsDialog maxUnits and defaultBrandId; PrChallengeCard rewardNote, an optional onOpen and PrChallengeLeader.seed; TaskRow action (and optional lead and onOpen); campaignColumns options ({ wrap: true }); ChallengeSummary flatDensity; SummaryLine inlineHint; challengeRequestColumns and prCreatorColumns take a money option; ChoiceGroup option icon as a PrIcon name or an element.
  • New PR Portal pieces: GiftClaimCheck, ShipmentSummary, the giftClaimColumns and giftAnalyticsColumns presets, PrCountPill, the challengeRequestColumns and prCreatorColumns presets, and the statuses pauses_in, waiting_count and trndr_wide in TRNDR_PR_STATUSES. Their styles are in pr.css and styles.css; there is no new import path.
  • DetailsBars: the score bars as a component of their own (variant="inline" or "stacked", the PR mock's score rows), for a bar block inside a composed drawer. DetailsDrawer gets no new props and stays deprecated (part 4).

Changed types

  • Wider, so existing code compiles: ChoiceOption.icon (PrIconName | ReactElement; 0.5.0 took PrIconName only), KpiCard icon (IconName | ReactElement; 0.5.0 took IconName only), KpiGrid columns (adds 2), Tile size (adds 'kpi'), CalloutCard tone (adds lilac, sky, butter), PrChallengeCard goal and reward (any node; onOpen optional), TaskRow lead and onOpen (optional).
  • ChallengeRequestCopy has a new optional key optional, so copy objects typed before it still compile. In PrLeaderboardCopy, tieFirst and tieShared take an optional last argument (on), so overrides written for the shorter signatures keep working.
  • PrStatus gains pauses_in, waiting_count and trndr_wide (the new statuses in TRNDR_PR_STATUSES): an exhaustive switch over it needs the three cases.
  • Exported copy types gain only optional keys (PrLeaderboardCopy tieOn, PrTierLadderCopy scoreFromOnly, PrRecordGiftsCopy unitsRange, the prBrandDetail copy's topupsCard), so a whole copy object typed before 0.6.0 still compiles; a missing key falls back to the language's default.
  • New exported types: CardProps, CardHeadingLevel, CalloutCardProps, CalloutTone, SidebarUserProps, TaskRowProps, QuoteProps, DetailsBarsProps, CampaignColumnsOptions, and the types of the new PR pieces.

Deprecated

Nothing new is deprecated in 0.6.0. DetailsDrawer stays deprecated since 0.5.0, and the other deprecations in parts 2 and 4 are unchanged.

11. 0.7.0: every PR Portal v3 piece as a component

0.7.0 adds on 0.6.0: every piece of the PR Portal v3 design is now a library component or an option, so a PR screen no longer needs hand-built markup or CSS. Using them is optional. No export or prop is removed or renamed: every export and prop of 0.6.0 is still there, and new props are optional. A few default looks change and the campaign blocks' internal row classes are renamed (Default look changes), a few types are wider (Changed types), and two 0.6.0 duplicates are deprecated in favour of the pieces they duplicated. Each component below has its own page in the docs, with live examples.

What's new, by area

  • Kit layout and text: PageGrid (the PR page grid: split="8-4", "7-5", "6-6", cols={2 | 3 | 4}, stickyAside), TextLink (the raspberry text link, a link or a button), Muted and Note (muted text and a muted paragraph), ReadOnlyFrame (the View as panel: nothing in it can be used) and SectionHeading (a heading over a group of cards). New options: FormField as="group" / as="fieldset" and adornment, Tile valueSize, Card footer and footerAlign, DataTable cardColumns for the cards mode.
  • Shell and the PR frame: PrPortalFrame (the whole PR portal v3 frame from one component) with PR_PORTAL_NAV; BrandMark (the sidebar's brand mark, for the sign-in page); AppHeader titleLead; MobileNavSheet card. The docs' recipe "Use the PR portal frame" walks it, and builds the same frame by hand.
  • Challenges and creators: challengeTableColumns with the PrChallengeRow / PrChallengeData types and toPrChallengeCard (one row type for the cards and the table), newCreatorColumns (Approvals › New creators), CreatorPickDialog ("Add creators"), creatorColumns options (CreatorColumnsOptions: onOpen, reapply, nullableSales with PrNullableSalesCreatorRow rows), WaitingCell and ApprovalRow ageTag, ScoreBreakdown variant="card", PrCreatorDrawer scoreVariant and headerStyle.
  • Challenge builder: BuilderStepCard with the step fields ChallengeBasicsFields, ChallengeRewardFields (part="goal" / "payout") and ChallengeAudienceFields, one ChallengeDraft (defaultChallengeDraft) and its checks (challengeIssues). The docs' recipe "Challenge builder" uses them beside ChallengeSummary layout="flat".
  • Campaigns and brand requests: CommissionChangeForm with commissionText (and useCommissionText, which uses the provider's currency and words) and commissionChangeError, ProgramStatusCard, AffiliateProgramCard, RequestWalletCard, RequestGiftsCard, RequestHandled, RequestChallengeCard and DecisionLine. CampaignChangeRequests, CustomerAffiliatesSwitch, BrandRequestCard and ChallengeSummary take error and onRetry.
  • Gifts: GiftShipmentCard shipmentId (a half-finished count survives refetches) and loading / loadError / onRetry; load states on GiftShipmentTimeline, BrandGiftStockCard and WarehouseDetailsCard; GiftAttentionList (Gift analytics' "Needs attention"); a gift glyph in PrIcon. The docs' recipe "Gift stock flow" now uses the 0.4.0 gift family throughout.
  • Messages and brand dialogs: AnnouncementComposer layout="modal" and preview; MessageDrawer (a sent message, with messageNotOpened); ChangeOwnerDialog, AdjustWalletDialog (with parseWalletAdjustment) and BrandFeeDialog (with parseBrandFee).

All their styles ship in styles.css, kit.css and pr.css; there is no new import path.

Default look changes

Each is the mock's look, on a component the mock was the only consumer of. Where there is a way back, it is named.

  • MiniRow: no 1px gap between the title and the muted line. The gap came from a class name the row shared with the campaign blocks (CampaignChallenges, CampaignChangeRequests); their rows now have class names of their own and look as before. To get the gap back on MiniRow: .kit-pr-mini-t { gap: 1px; } in your CSS.

  • The campaign blocks' row classes are renamed, on CampaignChallenges and CampaignChangeRequests only (they are internal classes, and there are no aliases). The blocks look the same; CSS of your own that targeted their rows must use the new names. MiniList / MiniRow keep the .kit-pr-mini* classes.

    0.6.00.7.0
    .kit-pr-mini.kit-pr-cmini
    .kit-pr-mini-row.kit-pr-cmini-row
    .kit-pr-mini-btn.kit-pr-cmini-btn
    .kit-pr-mini-t.kit-pr-cmini-t
  • AnnouncementComposer with channels={[]} no longer draws an empty channel picker (0.6.0 did). One channel or more draws it in the page layout as before.

  • PrCreatorDrawer's head, footer and spacing. It opens with the kit Drawer's headerStyle="pr" and footerDivider: a 64px photo before a 20px name (was 22px), the close button at the top end, a line over Reject / Approve, which share the full width, and 16px between the join banner and the figures (was 32px). The 0.6.0 head: headerStyle="default". The footer line and the spacing have no switch.

  • creatorColumns' orders and sales cells use the mock's number style: the display font, 15px, weight 800, tabular figures (they were the body font, bold). The orders cell keeps its kit-pr-cnt class and the sales cell gains kit-pr-money; restyle either class in your own CSS.

  • The phone sheet of an AppShell with sidebarCard or sidebarFooter (and no sheetFooter) now shows them, under the nav and as the footer, so the sidebar's card and user row are reachable on phones. To keep 0.6.0's sheet, pass sheetFooter (sheetFooter={null} for no footer at all); sheetFooter still wins over both.

Deprecated in 0.7.0

Still exported and still working, each marked @deprecated with its replacement; removed in 1.0.

prCreatorColumns and PrCreatorListRow → creatorColumns with options. creatorColumns is the one PR creators preset:

// 0.6.0
columns={prCreatorColumns(language, { onOpen }, undefined, { decimals: 'auto' })}   // rows: PrCreatorListRow
// 0.7.0
columns={creatorColumns(language, { decimals: 'auto' }, { onOpen, reapply: true, nullableSales: true })}   // rows: PrNullableSalesCreatorRow
PrCreatorListRow (0.6.0)PrNullableSalesCreatorRow (0.7.0: PrCreatorRow with sales that can be null)
id (string or number)id (number)
creator.name, creator.seed, creator.srcname, seed, avatarUrl
creator.handlenot shown (the sub line is "Since …")
customer: truetrack: 'customer'
reapplyreapplyOn (shown with the reapply option)
score?, followers? (optional)score (number or null), followers (required)
sales (string or null)sales (string or null; null or "0.00" shows a dash)
status, tier, brands, orders, joinedthe same

The money slot moves from prCreatorColumns.sales to creatorColumns.figures; set moneyFor for the new key if you had one for the old.

The 0.6.0 gift claim family → the 0.4.0 gift family. 0.6.0 added gift claim components beside the 0.4.0 gift shipment ones; 0.7.0 makes the 0.4.0 family the only one:

Deprecated (0.6.0)Use instead (0.4.0)
GiftClaimCheck, GiftClaimCheckProps, GiftClaimCheckResult, GiftClaimLineGiftShipmentCard with shipmentId, GiftShipmentCardProps, GiftCount, GiftShipmentLine
giftClaimColumns, GiftClaimRow, GiftClaimStatusgiftShipmentColumns, GiftShipmentRow, GiftShipmentState (giftStatusKey gives the gift_* keys)
giftAnalyticsColumns, GiftBrandStockRowgiftBrandColumns, GiftBrandRow
ShipmentSummary, ShipmentSummaryPropsGiftShipmentCounts inside a Card with a title
PrGiftsCopyPrGiftShipmentCopy, PrGiftColumnsCopy, PrGiftAnalyticsCopy

The fields that move:

0.6.00.4.0
GiftClaimCheck claimId, brandName, status: 'gift_expected'…, expectedBoxesGiftShipmentCard shipmentId, brand, state: 'expected'…, claimedBoxes
GiftClaimLine.productIdGiftShipmentLine.id (string or number)
GiftClaimCheckResult { boxes: number | null, lines: [{ good, damaged }] }GiftCount { boxes?: number, lines: [{ id, good, damaged }] }
GiftClaimRow sentOn, status (gift_*)GiftShipmentRow sent, state (no gift_ prefix)
giftClaimColumns(language, { onOpen }) (the reference as a link)giftShipmentColumns(language) with the table's onRowClick
GiftBrandStockRow brand: { name, color }, left, receivedPercent, stateGiftBrandRow name, color, used (total − left), received, status (optional: giftStockStatus(used, total) by default)
ShipmentSummary counts: [{ status, count }], problems (default 0), titleGiftShipmentCounts counts: { gift_expected: 3, … }, problems (left out: no line), the title on the Card

GiftShipmentCard keeps a half-typed count by product and takes lines over 999 units (up to the line's claim), as GiftClaimCheck did. Three differences to check when you move:

GiftClaimCheckGiftShipmentCard
When a half-typed count restartsWith claimId: when the id, the status or expectedBoxes changes (Expected → Arrived restarts it). Without: also when a product or its claim changes.With shipmentId: only when the id changes, or counting starts again after a confirm (Expected → Arrived keeps it). Without: when the brand, the state, or a product or its claim changes (so Expected → Arrived restarts it).
"Boxes received" in the resultboxes: null when the shipment is not Expectedboxes left out when the shipment is not Expected (GiftCount.boxes is optional)
Lines in the result{ good, damaged } in the order given{ id, good, damaged }, id being the line's id or else its index

So pass shipmentId to keep a count across states, and read count.boxes ?? null where your code expects null.

Changed types

Code written for 0.6.0 compiles unchanged unless it reads these:

  • AnnouncementComposerProps['channels'] is optional (ReadonlyArray<ChannelOption> | undefined). Code that reads props.channels.length from that type needs props.channels?.length ?? 0; passing channels works as before. Left out or empty, the channel picker is not drawn; the modal layout draws it only with two or more channels.
  • PrCreatorRow gains the optional reapplyOn; its sales stays a string. creatorColumns gains a third argument, CreatorColumnsOptions, and is overloaded: with { nullableSales: true } it takes the new PrNullableSalesCreatorRow rows (PrCreatorRow with sales: string | null), and onOpen receives that row type. PrCreatorRow rows fit it too.
  • PrChallengeCardProps now extends PrChallengeData; its props are the same as before.
  • FormField's props are a named type, FormFieldProps, and children also accepts content other than one element (for the group forms). New: FormFieldAs, PageGridProps, PageGridSplit, MutedProps, MutedSize, NoteProps, ReadOnlyFrameProps, SectionHeadingProps, GiftCardLoadProps, and the types of the new pieces.
  • Exported copy types gain only optional keys, so a whole copy object typed against 0.6.0 still compiles and a missing key falls back to the language's default: loading, loadError and retry in PrGiftShipmentCopy, PrGiftSideCopy and PrWarehouseCopy; error and retry in the copy types of CampaignChangeRequests, CustomerAffiliatesSwitch, BrandRequestCard (PrBrandRequestCopy) and ChallengeSummary (PrChallengeSummaryCopy). Code that reads those keys from a copy type gets | undefined.

On this page