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.
| From | To | Read |
|---|---|---|
| 0.1.0 | 0.2.0 / 0.3.0 | parts 1 to 7 |
| 0.3.0 | 0.4.0 | part 8 |
| 0.4.0 | 0.5.0 | part 9 |
| 0.5.0 | 0.6.0 | part 10 |
| 0.6.0 | 0.7.0 | part 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 sortableRowList): the v3.tbllook: a#FAFAFChead, cells padded 12 × 14 (were 12 × 18), 13.5px text, a#FBF6F8row hover, 18px raspberry checkboxes and a 40px empty state.TierBadge: the v3 tier chip, the same asTierChip(a dot, 11/700; Rising lime, Established sky, Elite gold with a star, Influential teal). Its classes (kit-tier kit-tier--<key>) are unchanged.Tilecorner 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
useDrawerResourcewith nofetchernow GETs through theDataProvider's HTTP client (or a same-origin default client): the request gainsX-Requested-With,onUnauthorizedruns on a 401/419, and the error'smessageis the server's viewer-facing message (it was always''). ADataProviderwith abaseUrlnow prefixes drawer URLs too: pass them relative to that base (/creators/7, not/api/creators/7).fetchJsonstill works as an explicitfetcher, but is deprecated.useListState'serroris aDataError:message(the server's, when meant for the viewer, else''), andcode/errorswhen sent. Code that showed its own text only whenmessage === ''keeps working.LIST_STATE_EVENTis nowURL_STATE_EVENT(samebc:urlvalue).
The gallery page (for the console's screenshot tests)
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[].id | columns[].key |
columns[].header | columns[].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[].sortKey | columns[].sortKey |
columns[].sortFirst (default: num high to low, others A–Z) | columns[].sortFirst (default high to low: set 'asc' on name columns) |
columns[].figure | columns[].figure (the "?" sits beside the sort button) |
columns[].term | a label node, plain words in cardLabel |
sort / onSort (SortState) | sort / onSort (DataSort) |
onRowClick, selection, isDim, loading, error, onRetry | the same props |
empty / emptyText | empty (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" / "رتّب حسب") |
id | not 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 + SelectBox + FilterChips → ListToolbar (recommended)
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 }} |
actions | actions |
// 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>| Prop | What it does |
|---|---|
preset | Starts 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). |
moneyNotes | The money "?" dictionary. A MoneyNotesProvider below still wins. |
labels | Per 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. |
statusTables | Named 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. |
money | How every money figure is shown, a MoneyDisplay: { showCurrency, decimals: 0 | 2 | 'auto', compact, sign: 'negative' | 'always' }, over each slot's default. |
moneyFor | The 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:
| Deprecated | Use |
|---|---|
CONSOLE_STATUSES | TRNDR_STATUSES, or the provider's statuses |
isConsoleStatus(key) | key in TRNDR_STATUSES, or the provider's statuses |
ConsoleStatus | keyof typeof TRNDR_STATUSES, or string with the provider's statuses |
CURRENCY | TRNDR_CURRENCY.label, or the provider's currency |
LIST_STATE_EVENT | URL_STATE_EVENT (the same bc:url value) |
formatAmount(value) | formatMoney(value, { language, showCurrency: false, decimals: 'auto' }), the one money formatter |
fetchJson | useDrawerResource 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>| DetailsDrawer | The composed body |
|---|---|
title, subtitle, lead (the plain header) | Drawer title, hint, lead |
hero | Drawer hideTitle with a DrawerHead (tone, title, sub, lead) as the first child |
tiles, sections[].rows | KeyValue (columns 1, 2 or 3) |
sections[].title | <h3 className="kit-blk-h3">, the 14/700 Jakarta heading |
sections[].bars | DetailsBars, a component of its own since 0.6.0 and not deprecated (variant="stacked" for the PR mock's score rows) |
sections[].ranked | RankList |
sections[].content | the node itself |
actions, primary, note | Drawer 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-Withand the sharedheadersgo to the page's origin and to an absolutebaseUrl'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
HttpErrorwithcode: 'not_json'(it resolvednull).useActionshows it as a failure; a caller of the client that treatednullas "the session ended" checks the code instead. -
useActionhas abusyresult. A secondrunwith another input while one is pending is not sent and resolves{ ok: false, kind: 'busy' }. An exhaustiveswitch (result.kind)adds the case. An exception from your own action function iskind: 'error'(logged), no longer'network'. -
Pass a stable client to the data hooks.
useResourcereads again when its client changes; create the client once (DataProvider, a module constant oruseMemo), not on every render. -
CommissionInputis a text field (inputMode="decimal"): tests that found it asspinbuttonfind atextbox. -
Select-all keeps other pages' picks in
DataTableandRowList; a screen that cleared the selection on a page change does so itself. -
Links from data go through
safeHref: ajavascript:(ordata:, …) URL renders without anhref. UsesafeHreffor your own links built from API data. -
ESM only.
disthas no CommonJS build. Jest with CommonJS transforms needstransformIgnorePatternsto let@ergasti/bricksthrough 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)
| Package | Import | Styles |
|---|---|---|
Shell: AppShell, Sidebar, AppHeader, HeaderSearch, BottomNav, … | @ergasti/bricks | shell.css (in styles.css) |
Data hooks: createHttpClient, DataProvider, useResource, usePaged, useAction, useHashState, useUrlSort, … | @ergasti/bricks | none |
Brand blocks: WalletHealthCard, WalletLedger, GroupCard, ChallengeCard, FindCreatorCard, … | @ergasti/bricks | blocks.css (in styles.css) |
PR blocks: ApprovalRow, AnnouncementComposer, BrandWalletCard, PrStatusPill, column presets, … | @ergasti/bricks | pr.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
Switchno longer compiles.SwitchPropsis a union: passlabel,aria-labelledby, orrowLabelled(a switch in aKeyValuerow'scontrol, named by the row). Code that spreads a props object intoSwitchmay need to pass the name explicitly. - Exhaustive code over widened types:
ChallengeStatusgains'scheduled' | 'paused' | 'closed',GroupCommissiongains'set'and'mixed', andButtonProps['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;labelsoverrides are partial and unaffected).BricksConfighas a newplatformsfield. - Looks that change with no code change: dialog titles are 700 (the theme hook
--dlg-title-fw; theprtheme keeps 800), a money "?" inside a heading no longer makes it taller,WalletHealthCarddraws only the thresholds you pass (below), andSpecialCommissionForm mode="set"says "Set special commission" (passnamesRatefor 0.4.0's words). - Tests: the Invite button of
FindCreatorCardandCreatorProfilePanelisaria-disabledwhen off, not nativelydisabled. - 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
Switchinside the shell'sSidebarorMobileNavSheetis 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. ADecisionsCardin the sidebar gets the small switch too.HeaderSearchunder 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
prtheme's search pill is 190px at 1240px and under (260px above). 0.5.0's width: set--shell-search-w-narrow: 260pxin your own[data-bricks-theme='pr']rule, loaded afterthemes/pr.css.
Kit
- In the
prtheme, 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 theprtheme: set those two tokens to#E0F4F1and#0F6A5Cin your own[data-bricks-theme='pr']rule, or passbg/inkfor the tier in the provider'stiers. In theprtheme 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'sfootersits in its own block 14px under the table, so a line such as "7 items" no longer touches it. APagerfooter 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). Withchevron={false}the phone card's end padding is narrower. No option.- The
prtheme'sListToolbarsearch box is 248px (was 260px). 0.5.0's width:--lt-search-w: 260pxin your own[data-bricks-theme='pr']rule. CreatorCellwithonOpen: the name button is 700 at the cell's font size (was 13.5px / 600). No option.- A
Modalhintno longer keeps the browser's bottom margin: the body starts 12px higher. No option. Gaugekeeps 5.3px under the arc, so its card is about 5px taller. No option.Cardwith atitle(or aCard.Headerinside it) is a region named by its heading. Nothing visible changes; screen readers list it as a named region.labelledBystill wins.OpenRate,ShareBarandProgressRowdraw 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).ChallengeRequestFormdraws the "(optional)" at the end of itsdatesandnoteslabels as a muted 12px span (the words are unchanged).MembersPickernames are 13px (was 14) and sit 7px further in.GiftStockListrows 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
Leaderboarduses 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). WithshowPercent={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.TierLadderwithbasis="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:
Switchsizeandsurface;AppHeaderleading(a screen's tools before the search, the bell and "+ New" staying after it) andsubtitleLines;HeaderSearchcollapsible;SidebarUseravatarSize; theIconnamemessages(an alias ofspeech); the theme hook--shell-search-w-narrow. - Kit:
Cardtitle,sub,badge,actions,headingLevelandvariant="inset"(andCard.Headerlevel);DataTabledensity="tight"andheadDensity="compact";ListToolbarextraandextraPlacement="newRow", and the hook--lt-search-w;Segmentedsize="sm";KpiCardsize="short"and aniconthat takes an element;KpiGridcolumns={2};Tilesize="kpi"and--tile-min-hforsize="short";ShareBarshowValue;RankMedalsize="lg";DrawerheaderStyle="pr",closeButton="float"andfooterDivider;DrawerandModalclassName; the newQuote. - Brand blocks:
CalloutCardtoneslilac,skyandbutter;ProgressRowvariant="bar";RowItemvalueTone="muted";GiftStockItemseed;FindCreatorCard's--fc-colshook. - PR blocks:
LeaderboardrankSize,rankStyle,highlightTop,textSize,cutTone,noteSizeandtieDetail;TierLadderscoreMax,scoreInfoHref,openTagTipandscoreText;DecisionTagandDecisionsCardtip="focus";NumberSettingalwaysShowReset;SettingRowdensity="tight";SenderCellavatarSize;AuditLogList/AuditLogEntrydot;BrandWalletCardtopUpMethods;ApprovalActionsfullWidth;RecordGiftsDialogmaxUnitsanddefaultBrandId;PrChallengeCardrewardNote, an optionalonOpenandPrChallengeLeader.seed;TaskRowaction(and optionalleadandonOpen);campaignColumnsoptions ({ wrap: true });ChallengeSummaryflatDensity;SummaryLineinlineHint;challengeRequestColumnsandprCreatorColumnstake amoneyoption;ChoiceGroupoptioniconas a PrIcon name or an element. - New PR Portal pieces:
GiftClaimCheck,ShipmentSummary, thegiftClaimColumnsandgiftAnalyticsColumnspresets,PrCountPill, thechallengeRequestColumnsandprCreatorColumnspresets, and the statusespauses_in,waiting_countandtrndr_wideinTRNDR_PR_STATUSES. Their styles are inpr.cssandstyles.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.DetailsDrawergets no new props and stays deprecated (part 4).
Changed types
- Wider, so existing code compiles:
ChoiceOption.icon(PrIconName | ReactElement; 0.5.0 tookPrIconNameonly),KpiCardicon(IconName | ReactElement; 0.5.0 tookIconNameonly),KpiGridcolumns(adds2),Tilesize(adds'kpi'),CalloutCardtone(addslilac,sky,butter),PrChallengeCardgoalandreward(any node;onOpenoptional),TaskRowleadandonOpen(optional). ChallengeRequestCopyhas a new optional keyoptional, so copy objects typed before it still compile. InPrLeaderboardCopy,tieFirstandtieSharedtake an optional last argument (on), so overrides written for the shorter signatures keep working.PrStatusgainspauses_in,waiting_countandtrndr_wide(the new statuses inTRNDR_PR_STATUSES): an exhaustiveswitchover it needs the three cases.- Exported copy types gain only optional keys (
PrLeaderboardCopytieOn,PrTierLadderCopyscoreFromOnly,PrRecordGiftsCopyunitsRange, theprBrandDetailcopy'stopupsCard), 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),MutedandNote(muted text and a muted paragraph),ReadOnlyFrame(the View as panel: nothing in it can be used) andSectionHeading(a heading over a group of cards). New options:FormFieldas="group"/as="fieldset"andadornment,TilevalueSize,CardfooterandfooterAlign,DataTablecardColumnsfor the cards mode. - Shell and the PR frame:
PrPortalFrame(the whole PR portal v3 frame from one component) withPR_PORTAL_NAV;BrandMark(the sidebar's brand mark, for the sign-in page);AppHeadertitleLead;MobileNavSheetcard. The docs' recipe "Use the PR portal frame" walks it, and builds the same frame by hand. - Challenges and creators:
challengeTableColumnswith thePrChallengeRow/PrChallengeDatatypes andtoPrChallengeCard(one row type for the cards and the table),newCreatorColumns(Approvals › New creators),CreatorPickDialog("Add creators"),creatorColumnsoptions (CreatorColumnsOptions:onOpen,reapply,nullableSaleswithPrNullableSalesCreatorRowrows),WaitingCellandApprovalRowageTag,ScoreBreakdownvariant="card",PrCreatorDrawerscoreVariantandheaderStyle. - Challenge builder:
BuilderStepCardwith the step fieldsChallengeBasicsFields,ChallengeRewardFields(part="goal"/"payout") andChallengeAudienceFields, oneChallengeDraft(defaultChallengeDraft) and its checks (challengeIssues). The docs' recipe "Challenge builder" uses them besideChallengeSummary layout="flat". - Campaigns and brand requests:
CommissionChangeFormwithcommissionText(anduseCommissionText, which uses the provider's currency and words) andcommissionChangeError,ProgramStatusCard,AffiliateProgramCard,RequestWalletCard,RequestGiftsCard,RequestHandled,RequestChallengeCardandDecisionLine.CampaignChangeRequests,CustomerAffiliatesSwitch,BrandRequestCardandChallengeSummarytakeerrorandonRetry. - Gifts:
GiftShipmentCardshipmentId(a half-finished count survives refetches) andloading/loadError/onRetry; load states onGiftShipmentTimeline,BrandGiftStockCardandWarehouseDetailsCard;GiftAttentionList(Gift analytics' "Needs attention"); agiftglyph inPrIcon. The docs' recipe "Gift stock flow" now uses the 0.4.0 gift family throughout. - Messages and brand dialogs:
AnnouncementComposerlayout="modal"andpreview;MessageDrawer(a sent message, withmessageNotOpened);ChangeOwnerDialog,AdjustWalletDialog(withparseWalletAdjustment) andBrandFeeDialog(withparseBrandFee).
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 onMiniRow:.kit-pr-mini-t { gap: 1px; }in your CSS. -
The campaign blocks' row classes are renamed, on
CampaignChallengesandCampaignChangeRequestsonly (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/MiniRowkeep the.kit-pr-mini*classes.0.6.0 0.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 -
AnnouncementComposerwithchannels={[]}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 kitDrawer'sheaderStyle="pr"andfooterDivider: 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 itskit-pr-cntclass and the sales cell gainskit-pr-money; restyle either class in your own CSS. -
The phone sheet of an
AppShellwithsidebarCardorsidebarFooter(and nosheetFooter) 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, passsheetFooter(sheetFooter={null}for no footer at all);sheetFooterstill 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: PrNullableSalesCreatorRowPrCreatorListRow (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.src | name, seed, avatarUrl |
creator.handle | not shown (the sub line is "Since …") |
customer: true | track: 'customer' |
reapply | reapplyOn (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, joined | the 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, GiftClaimLine | GiftShipmentCard with shipmentId, GiftShipmentCardProps, GiftCount, GiftShipmentLine |
giftClaimColumns, GiftClaimRow, GiftClaimStatus | giftShipmentColumns, GiftShipmentRow, GiftShipmentState (giftStatusKey gives the gift_* keys) |
giftAnalyticsColumns, GiftBrandStockRow | giftBrandColumns, GiftBrandRow |
ShipmentSummary, ShipmentSummaryProps | GiftShipmentCounts inside a Card with a title |
PrGiftsCopy | PrGiftShipmentCopy, PrGiftColumnsCopy, PrGiftAnalyticsCopy |
The fields that move:
| 0.6.0 | 0.4.0 |
|---|---|
GiftClaimCheck claimId, brandName, status: 'gift_expected'…, expectedBoxes | GiftShipmentCard shipmentId, brand, state: 'expected'…, claimedBoxes |
GiftClaimLine.productId | GiftShipmentLine.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, state | GiftBrandRow name, color, used (total − left), received, status (optional: giftStockStatus(used, total) by default) |
ShipmentSummary counts: [{ status, count }], problems (default 0), title | GiftShipmentCounts 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:
GiftClaimCheck | GiftShipmentCard | |
|---|---|---|
| When a half-typed count restarts | With 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 result | boxes: null when the shipment is not Expected | boxes 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 readsprops.channels.lengthfrom that type needsprops.channels?.length ?? 0; passingchannelsworks as before. Left out or empty, the channel picker is not drawn; the modal layout draws it only with two or more channels.PrCreatorRowgains the optionalreapplyOn; itssalesstays astring.creatorColumnsgains a third argument,CreatorColumnsOptions, and is overloaded: with{ nullableSales: true }it takes the newPrNullableSalesCreatorRowrows (PrCreatorRowwithsales: string | null), andonOpenreceives that row type.PrCreatorRowrows fit it too.PrChallengeCardPropsnow extendsPrChallengeData; its props are the same as before.FormField's props are a named type,FormFieldProps, andchildrenalso 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,loadErrorandretryinPrGiftShipmentCopy,PrGiftSideCopyandPrWarehouseCopy;errorandretryin the copy types ofCampaignChangeRequests,CustomerAffiliatesSwitch,BrandRequestCard(PrBrandRequestCopy) andChallengeSummary(PrChallengeSummaryCopy). Code that reads those keys from a copy type gets| undefined.