Skip to Content
BBRICKSv0.7.4
PR PortalSidebar

PrPortalFrame

The whole PR portal v3 frame in one opt-in component, built from public exports: AppShell in the PR theme (the dark sidebar with the v3 nav), DecisionsCard tip="focus" in the sidebar card slot, SidebarUser (34px avatar) with a sign-out button, and AppHeader with the screen's tools first (leading), HeaderSearch, NotificationsMenu and the raspberry "+ New" TopbarMenu, the subtitle clamped to two lines on phones. Everything sits in a DecisionTagsProvider driven by the card's "Show decision tags" switch, inside data-bricks-theme="pr". On phones the card and the user row are in the nav sheet. Each part is a prop; build the frame by hand from the same parts when you need something it does not do. Wrap it in your BricksProvider (the PR mock's money={{ decimals: 'auto' }}) and import themes/pr.css.

import { PrPortalFrame } from '@ergasti/bricks';

Examples

The PR portal frame

One component for the whole PR portal v3 frame: the dark sidebar with the v3 nav, the Open decisions card, the signed-in person with sign-out, and the header with the screen's own tools, search, the bell and the raspberry "+ New". The card's "Show decision tags" switch drives a DecisionTagsProvider around the page, so the tag after "Shipments from brands" comes and goes. Pick another item in the sidebar to move.

Pinned to TRNDR presetPR theme
Code
import { useState } from 'react';
import { Button, Card, DecisionTag, Icon, PR_PORTAL_NAV, PrPortalFrame, type NavItem, type NotificationItem } from '@ergasti/bricks';

const OPEN = [
  { id: 'C3', question: 'Can a brand opt out of a TRNDR-wide challenge?' },
  { id: 'R10', question: 'What a tier gives creators' },
  { id: 'GS1', question: 'Damaged or extra units: brand collects within 14 days?' },
];

const NOTIFS: NotificationItem[] = [
  { id: 1, text: <><b>Sara Ali</b> has waited 8 days to join Glow Lab.</>, when: '1 hour ago', icon: 'approvals', tone: 'rasp', unread: true },
  { id: 2, text: <><b>Kemet Home</b> wallet is below zero (day 4 of 7).</>, when: 'Today', icon: 'wallet', tone: 'butter', unread: true },
  { id: 3, text: <><b>4 new creators</b> are waiting for approval.</>, when: 'Yesterday', icon: 'user', tone: 'sky', unread: false },
];

const COUNTS: Record<string, number> = { approvals: 9, programs: 3, gifts: 3 };

const nav = PR_PORTAL_NAV.map((group) => ({ ...group, items: group.items.map((item) => (COUNTS[item.id] ? { ...item, count: COUNTS[item.id] } : item)) }));

function Frame() {
  const [active, setActive] = useState('gifts');
  const [items, setItems] = useState(NOTIFS);
  return (
    <PrPortalFrame
      nav={nav} activeId={active} onNavigate={(item: NavItem) => setActive(item.id)}
      decisions={OPEN} user={{ name: 'Mona Adel', seed: 1 }} onSignOut={() => {}}
      title="Gift stock" subtitle="Brands send gifts to the warehouse and tell us what they sent. Nothing counts as gift stock until you confirm what arrived."
      tools={<Button><Icon name="plus" />Record gifts for a brand</Button>}
      search={{ fetcher: async () => [], onSelect: () => {} }}
      notifications={{ items, onOpenItem: (id) => setItems((all) => all.map((n) => (n.id === id ? { ...n, unread: false } : n))), onMarkAllRead: () => setItems((all) => all.map((n) => ({ ...n, unread: false }))), onSeeAll: () => setActive('activity') }}
      newMenu={[{ id: 'gift', label: 'Record gifts', sub: 'Boxes a brand sent without a claim', icon: 'gift' }]}
    >
      <Card title={<>Shipments from brands<DecisionTag id="GS1" question="Damaged or extra units: brand collects within 14 days?" /></>}>The screen goes here.</Card>
    </PrPortalFrame>
  );
}

A brand page

titleLead puts the brand's big square before its name in the h1, breadcrumbs the crumb above it, and tools the page's own "View as brand" before the search. On brand pages the "+ New" menu offers both a challenge and gifts.

Pinned to TRNDR presetPR theme
Code
import { BrandAvatar, Button, Card, Icon, PR_PORTAL_NAV, PrPortalFrame } from '@ergasti/bricks';

const OPEN = [
  { id: 'C3', question: 'Can a brand opt out of a TRNDR-wide challenge?' },
  { id: 'R10', question: 'What a tier gives creators' },
  { id: 'GS1', question: 'Damaged or extra units: brand collects within 14 days?' },
];

const COUNTS: Record<string, number> = { approvals: 9, programs: 3, gifts: 3 };

const nav = PR_PORTAL_NAV.map((group) => ({ ...group, items: group.items.map((item) => (COUNTS[item.id] ? { ...item, count: COUNTS[item.id] } : item)) }));

function BrandPage() {
  return (
    <PrPortalFrame
      nav={nav} activeId="brands" decisions={OPEN} user={{ name: 'Mona Adel', seed: 1 }} onSignOut={() => {}}
      title="Glow Lab" titleLead={<BrandAvatar name="Glow Lab" color="#C7325C" size="lg" />} breadcrumbs={<><a href="#brands">Brands</a> / Glow Lab</>}
      tools={<Button><Icon name="eye" />View as brand</Button>}
      search={{ fetcher: async () => [], onSelect: () => {} }}
      newMenu={[{ id: 'ch', label: 'Challenge', sub: 'For one brand or all brands', icon: 'star' }, { id: 'gift', label: 'Record gifts', icon: 'gift' }]}
    >
      <Card title="Affiliate program">10% of sale</Card>
    </PrPortalFrame>
  );
}

On a phone

Under 860px the sidebar becomes a tab bar and a "More" sheet; the sheet holds the whole nav, then the Open decisions card with its switch, then the person's row with sign-out. Open "More" to see them.

Pinned to ArabicTRNDR presetPR theme
Code
import { useState } from 'react';
import { Card, PR_PORTAL_NAV, PrPortalFrame, Segmented } from '@ergasti/bricks';

const OPEN = [
  { id: 'C3', question: 'Can a brand opt out of a TRNDR-wide challenge?' },
  { id: 'R10', question: 'What a tier gives creators' },
  { id: 'GS1', question: 'Damaged or extra units: brand collects within 14 days?' },
];

const COUNTS: Record<string, number> = { approvals: 9, programs: 3, gifts: 3 };

const nav = PR_PORTAL_NAV.map((group) => ({ ...group, items: group.items.map((item) => (COUNTS[item.id] ? { ...item, count: COUNTS[item.id] } : item)) }));

function Phone() {
  const [scope, setScope] = useState<'my' | 'all'>('my');
  return (
    <div style={{ maxWidth: 390 }}>
      <PrPortalFrame
        tier="mobile" nav={nav} activeId="home" decisions={OPEN} user={{ name: 'منى عادل', seed: 1 }} onSignOut={() => {}}
        title="صباح الخير يا منى" subtitle="13 حاجة مستنياك. الأهم الأول."
        tools={<Segmented label="البراندات اللي ظاهرة" size="sm" value={scope} onChange={setScope} options={[['my', 'براندات بتاعتي'], ['all', 'كل البراندات']]} />}
        search={{ fetcher: async () => [], onSelect: () => {} }}
      >
        <Card title="محتاجك">…</Card>
      </PrPortalFrame>
    </div>
  );
}

Props

Prop

Type

Labels

Every word this component draws, in both languages. Override one per component and language with BricksProvider labels under the key prPortalFrame, or with the component's own prop where it has one. A {name} is a value the component fills in.

prPortalFrame
KeyEnglishArabic
taglinePR portalبوابة الـ PR
searchSearch brands, creators…دوّر على براندات أو صنّاع محتوى…
brandsBrandsالبراندات
creatorsCreatorsصنّاع المحتوى
newLabelNewجديد
teamPR teamفريق الـ PR
signOutSign outاخرج
homeHomeالرئيسية
approvalsApprovalsالموافقات
campaignsCampaignsالحملات
programsAffiliate programsبرامج الأفلييت
giftsGift stockمخزون الهدايا
ganalyticsGift analyticsتحليلات الهدايا
tiersTiersالمستويات
messagesMessagesالرسايل
activityActivity logسجل النشاط
nextSprintNext sprintالسبرنت الجاي
payoutsPayoutsالمدفوعات
settingsSettingsالإعدادات
laterLATERبعدين

Design guidance

How the BRICKS design system uses PrPortalFrame. Written in docs/content/components/PrPortalFrame.md; the props above are read from the code, which wins where the two disagree.

The whole PR Portal v3 frame in one component: the dark sidebar with the v3 nav, the Open decisions card, the signed-in PR person with sign-out, and the header with the screen's tools, search, bell and raspberry "+ New"; use it once around every PR Portal screen.

It is the PR v3 mock's frame (MENU, the "Open decisions" sidebar card, Mona Adel's row, and the top bar). Before 0.7 every app built it by hand from AppShell, DecisionsCard, SidebarUser, AppHeader, HeaderSearch, NotificationsMenu, TopbarMenu and a DecisionTagsProvider (the gallery's own PrScreenFrame still does). Use PrPortalFrame instead; build the frame from those parts only when you need something it does not do (recipe PortalFrameRecipe, ByHand). It sets data-bricks-theme="pr" on its own wrapper and holds the DecisionTagsProvider driven by the card's "Show decision tags" switch. Wrap it in your BricksProvider (the PR mock's money={{ decimals: 'auto' }}) and import themes/pr.css.

Anatomy

  1. DecisionTagsProvider, then a <div data-bricks-theme="pr"> (className goes here).
  2. AppShell with:
    • Brand block: default the raspberry "T" square, "TRNDR." with the lime dot, and "PR portal" (brand).
    • Nav: default PR_PORTAL_NAV in the frame's words: Home, Approvals, Brands; "Campaigns" with Affiliate programs, Gift stock and Gift analytics indented; Creators, Tiers, Messages, Activity log; "Next sprint" with Payouts and Settings disabled with a LATER badge (nav, activeId, onNavigate).
    • Sidebar card: DecisionsCard tip="focus" from decisions, or your sidebarCard.
    • User row: SidebarUser with a 34px Avatar (user), "PR team" by default, and a sign-out LogoutButton (onSignOut or signOutUrl + csrfToken).
  3. AppHeader: breadcrumbs, titleLead + title (the h1), subtitle (two lines on phones, subtitleLines), then tools (leading), search (HeaderSearch, "Search brands, creators…", Brands / Creators groups), actions, the bell (NotificationsMenu) and the raspberry pill "+ New" (TopbarMenu).
  4. Children: the screen, in <main>.

Variants

PropLookWhen to use
decisionsOpen decisions card with the "Show decision tags" switchWhile product decisions are open; left out, no card.
sidebarCardYour card insteadA different sidebar card.
user + onSignOut / signOutUrlPerson row with sign-outAlways in the app. Sign-out without user draws a row with only the button.
search as props / elementHeaderSearch with PR defaults / your ownSearch on every page; left out, none.
notifications as props / elementThe bellLeft out, none.
newMenu items / elementRaspberry "+ New"Items per page (Challenge, Record gifts); an empty list or nothing: no menu.
toolsPage tools before the searchThe scope Segmented, "Record gifts for a brand", "View as brand", a live status pill.
titleLeadBrand square before the h1Brand detail (BrandAvatar size="lg").
onToggleLanguageLanguage circleThe PR mock has none; leave it out.
tierForces desktop / tablet / mobileTests and previews.

States

StateHow
Active destinationactiveId (default 'home').
Decision tags shownUncontrolled from defaultShowTags (default false), or controlled with showTags + onShowTagsChange.
Phone (<860px)Tab bar; the Open decisions card and the user row move into the "More" sheet.
Wordslabels (or BricksProvider labels.prPortalFrame) for its own words; shellCopy for the shell's.

Usage

// PR Portal › Gift stock: nav with counts, decisions, user, the page tool, search, bell and "+ New"
import { useState } from 'react';
import { Button, Card, Icon, PR_PORTAL_NAV, PrPortalFrame, type NavItem, type NotificationItem } from '@ergasti/bricks';

const OPEN = [
  { id: 'C3', question: 'Can a brand opt out of a TRNDR-wide challenge?' },
  { id: 'GS1', question: 'Damaged or extra units: brand collects within 14 days?' },
];
const NOTIFS: NotificationItem[] = [
  { id: 1, text: <><b>Sara Ali</b> has waited 8 days to join Glow Lab.</>, when: '1 hour ago', icon: 'approvals', tone: 'rasp', unread: true },
];
const COUNTS: Record<string, number> = { approvals: 9, programs: 3, gifts: 3 };
const nav = PR_PORTAL_NAV.map((group) => ({ ...group, items: group.items.map((item) => (COUNTS[item.id] ? { ...item, count: COUNTS[item.id] } : item)) }));

export function GiftStockPage({ signOut, openRecord }: { signOut: () => void; openRecord: () => void }) {
  const [active, setActive] = useState('gifts');
  return (
    <PrPortalFrame
      nav={nav} activeId={active} onNavigate={(item: NavItem) => setActive(item.id)}
      decisions={OPEN} user={{ name: 'Mona Adel', seed: 1 }} onSignOut={signOut}
      title="Gift stock"
      subtitle="Brands send gifts to the warehouse and tell us what they sent. Nothing counts as gift stock until you confirm what arrived."
      tools={<Button onClick={openRecord}><Icon name="plus" />Record gifts for a brand</Button>}
      search={{ fetcher: async () => [], onSelect: () => {} }}
      notifications={{ items: NOTIFS, onOpenItem: () => {}, onSeeAll: () => setActive('activity') }}
      newMenu={[{ id: 'gift', label: 'Record gifts', sub: 'Boxes a brand sent without a claim', icon: 'gift' }]}
    >
      <Card title="Shipments from brands">The screen goes here.</Card>
    </PrPortalFrame>
  );
}
// PR Portal › Brand detail: the brand square in the h1, the crumb, and "View as brand" as the page tool
import { BrandAvatar, Button, Card, Icon, PrPortalFrame } from '@ergasti/bricks';

export function BrandDetailPage({ viewAs }: { viewAs: () => void }) {
  return (
    <PrPortalFrame
      activeId="brands" user={{ name: 'Mona Adel', seed: 1 }} onSignOut={() => {}}
      title="Glow Lab" titleLead={<BrandAvatar name="Glow Lab" color="#C7325C" size="lg" />}
      breadcrumbs={<><a href="/brands">Brands</a> / Glow Lab</>}
      tools={<Button onClick={viewAs}><Icon name="eye" />View as brand</Button>}
      newMenu={[{ id: 'ch', label: 'Challenge', sub: 'For one brand or all brands', icon: 'star' }, { id: 'gift', label: 'Record gifts', icon: 'gift' }]}
    >
      <Card title="Affiliate program">10% of sale</Card>
    </PrPortalFrame>
  );
}
// App root: the provider once, then the frame (sign-out by form post)
import { BricksProvider, Card, PrPortalFrame, trndrPreset } from '@ergasti/bricks';

export function App({ csrf }: { csrf: string }) {
  return (
    <BricksProvider preset={trndrPreset} money={{ decimals: 'auto' }}>
      <PrPortalFrame title="Brands" subtitle="Every brand on TRNDR, its wallet and its program." activeId="brands"
        user={{ name: 'Mona Adel', seed: 1 }} signOutUrl="/logout" csrfToken={csrf}>
        <Card title="Brands">The list goes here.</Card>
      </PrPortalFrame>
    </BricksProvider>
  );
}

Where it appears

Guidelines

Do

  • Keep one frame for the whole app; change title, tools, newMenu and activeId per page.
  • Add counts by copying PR_PORTAL_NAV and setting count on items.
  • Put page-specific controls in tools, not in the children's first row.
  • Follow the PR Portal button rule in tools and the screen: commits in ink, rasp only for creating/sending and destructive confirms (the "+ New" menu is already raspberry), default for Cancel and secondary tools.

Don't

  • Don't wrap it in another data-bricks-theme="pr" div or another DecisionTagsProvider; it has both.
  • Don't nest it or put it in a scrolling container (the sidebar is fixed, as in AppShell).
  • Don't show the language circle unless the product asks for it; the mock has none.
  • Don't remove the disabled "Next sprint" items to save space; they tell PR what is coming.

RTL and Arabic

  • language="ar" (or the provider's) mirrors the whole frame: the sidebar on the right, the sheet from the right.
  • Its own Arabic: "بوابة الـ PR", "دوّر على براندات أو صنّاع محتوى…", "جديد", "فريق الـ PR", "اخرج", and the nav ("الرئيسية", "الموافقات", "البراندات", "الحملات", "برامج الأفلييت", "مخزون الهدايا", "تحليلات الهدايا", …, "بعدين").
  • PR_PORTAL_NAV carries { en, ar } labels; a nav you build should too.

Tokens

The PR theme (themes/pr.css, data-bricks-theme="pr"): --sidebar-width-desktop (248px in PR), --shell-side-bg, --shell-side-ink, --rasp (the "+ New" pill, the brand square), plus AppShell's shell tokens.

Accessibility

  • All of AppShell's: skip link, sidebar <nav>, <header>, <main> that takes focus on route change, the phone nav sheet as a modal dialog.
  • The title is the page's h1; titleLead sits inside it before the name.
  • Sign-out is an icon button with a visually hidden "Sign out" name.
  • The "+ New" pill is named by its visible words ("New"); its panel is a region named "New". The bell and search carry their own names (see NotificationsMenu, HeaderSearch).

Found in the source

  • Its tests cover: “a provider labels override reaches the default nav and words; own elements replace the slots”.

Read from the component's source and tests. See Accessibility for the patterns the library follows.

See also: Avatar · Icon · useLanguage · Button · Card

Source

src/pr/portal/PrPortalFrame.tsx (line 194) on GitHub.

On this page