PermissionMatrix
Roles × permissions (PR team roles: who may approve, pay, change fees, message creators). A real table: permissions are row headers in groups, roles are column headers with "N of M" granted. Each cell is a native checkbox named "{permission}: {role}". One tab stop for the grid; arrow keys move between cells (mirrored in RTL), Home / End go to the row's ends, Space toggles. Locked cells stay focusable (aria-disabled, so they are still read) but do not change; the lock's reason is their description (read with the cell, not only a hover title). On touch tiers each checkbox's label is a 44px target.
import { PermissionMatrix } from '@ergasti/bricks';Examples
Roles and permissions
A grid of checkboxes: rows are permissions (grouped), columns are roles. locked freezes a cell (the Admin column here); toggling calls onToggle with the next value.
Code
import { useState } from 'react';
import { PermissionMatrix, type MatrixGroup } from '@ergasti/bricks';
const roles = [{ id: 'admin', label: 'Admin' }, { id: 'lead', label: 'PR lead' }, { id: 'pr', label: 'PR' }, { id: 'finance', label: 'Finance' }];
const groups: MatrixGroup[] = [
{ label: 'Creators', permissions: [{ id: 'approve', label: 'Approve and reject creators' }, { id: 'tiers', label: 'Move a creator down a tier' }, { id: 'message', label: 'Message creators' }] },
{ label: 'Brands and money', permissions: [{ id: 'commission', label: 'Change commission' }, { id: 'fees', label: 'Change the TRNDR fee' }, { id: 'wallet', label: 'Adjust a wallet' }, { id: 'pay', label: 'Pay creators', description: 'Upload receipts' }] },
];
function Matrix() {
const [grants, setGrants] = useState(new Set(['lead:approve', 'lead:tiers', 'lead:message', 'lead:commission', 'pr:approve', 'pr:message', 'finance:pay', 'finance:wallet']));
return (
<PermissionMatrix
caption="Roles and permissions" roles={roles} groups={groups}
granted={(role, permission) => role === 'admin' || grants.has(`${role}:${permission}`)}
locked={(role) => role === 'admin'}
onToggle={(role, permission, next) => setGrants((all) => { const copy = new Set(all); if (next) copy.add(`${role}:${permission}`); else copy.delete(`${role}:${permission}`); return copy; })}
/>
);
}Props
Prop
Type
Labels
Every word this component draws, in both languages. Override one per component and language with BricksProvider labels under the key prPermissionMatrix, or with the component's own prop where it has one. A {name} is a value the component fills in.
| Key | English | Arabic |
|---|---|---|
cell | {p}: {r} | {p}: {r} |
locked | Always on for this role | شغّالة دايماً للدور ده |
of | {a} of {b} | {a} من {b} |
permission | Permission | الصلاحية |
Design guidance
How the BRICKS design system uses PermissionMatrix. Written in docs/content/components/PermissionMatrix.md; the props above are read from the code, which wins where the two disagree.
A roles × permissions grid of checkboxes with grouped permissions, "N of M" per role and locked cells; use it on the PR Portal's roles and permissions settings.
PermissionMatrix shows who on the PR team may approve, pay, change fees or message creators. It is a real table: permissions are row headers in groups, roles are column headers with how many permissions each has. Each cell is a native checkbox named "{permission}: {role}". The whole grid is one tab stop; arrow keys move between cells (mirrored in RTL), Home / End go to the row's ends, Space toggles. Locked cells (the admin role has everything) stay focusable and are read, with the reason, but do not change. Without onToggle it is read-only. Inferred screen (the mock greys Settings as "LATER").
Anatomy
- Wrapper: bordered, radius 18px, white, scrolls sideways when narrow.
- Table: hidden caption; 13.5px.
- Head row: "PERMISSION" (11px upper-case on
--tbl-head), then one column per role: the role name and "3 of 7". - Group rows: a
rowgroupheader on--soft("Creators", "Brands and money"). - Permission rows: row header with the bold label and optional muted description; one centred checkbox per role (18px, raspberry accent, 28px hit area; 44px on touch).
Variants
| Props | Effect |
|---|---|
onToggle given | Editable |
no onToggle | Read-only (every cell aria-disabled) |
locked(role, perm) true | That cell fixed at its state, 55% opacity, lock reason |
States
| State | Trigger |
|---|---|
| Granted / not | granted(role, perm) |
| Locked | locked(...): "Always on for this role" (described-by and tooltip) |
| Focus | focus ring on the checkbox; roving tab stop |
| Narrow (≤600px) | tighter cells, 10px head |
Types
MatrixRole (roles): { id, label, description? }. MatrixGroup (groups): { label, permissions: [{ id, label, description? }] }.
Usage
import { useState } from 'react';
import { PermissionMatrix, type MatrixGroup } from '@ergasti/bricks';
const roles = [{ id: 'admin', label: 'Admin' }, { id: 'lead', label: 'PR lead' }, { id: 'pr', label: 'PR' }, { id: 'finance', label: 'Finance' }];
const groups: MatrixGroup[] = [
{ label: 'Creators', permissions: [{ id: 'approve', label: 'Approve and reject creators' }, { id: 'tiers', label: 'Move a creator down a tier' }, { id: 'message', label: 'Message creators' }] },
{ label: 'Brands and money', permissions: [{ id: 'commission', label: 'Change commission' }, { id: 'fees', label: 'Change the TRNDR fee' }, { id: 'wallet', label: 'Adjust a wallet' }, { id: 'pay', label: 'Pay creators', description: 'Upload receipts' }] },
];
export function Matrix() {
const [grants, setGrants] = useState(new Set(['lead:approve', 'lead:tiers', 'lead:message', 'lead:commission', 'pr:approve', 'pr:message', 'finance:pay', 'finance:wallet']));
return (
<PermissionMatrix
caption="Roles and permissions" roles={roles} groups={groups}
granted={(role, permission) => role === 'admin' || grants.has(`${role}:${permission}`)}
locked={(role) => role === 'admin'}
onToggle={(role, permission, next) => setGrants((all) => { const copy = new Set(all); if (next) copy.add(`${role}:${permission}`); else copy.delete(`${role}:${permission}`); return copy; })}
/>
);
}// Read-only for someone who may not edit roles, with a save bar for editors
<PermissionMatrix caption="Roles and permissions" roles={roles} groups={groups} granted={has} locked={(r) => r === 'admin'} onToggle={canEdit ? toggle : undefined} />
<SaveBar dirty={dirty} onSave={save} onDiscard={discard} />Where it appears
- Library-only (no v3 mock screen): Settings › Roles and permissions (the mock greys Settings as "LATER").
Guidelines
Do
- Lock what cannot change and let the matrix say why.
- Group permissions by area; keep labels as actions ("Pay creators").
Don't
- Don't save on every toggle without a way back; batch with a save bar.
- Don't use more than about six roles: the grid stops fitting.
RTL and Arabic
Columns mirror and arrows follow the reading direction; head text is not upper-cased in Arabic; "N of M" stays dir="ltr".
Tokens
--line, --card, --tbl-head, --ink, --ink-2, --ink-3, --soft, --rasp, --focus-ring, --min-touch-target.
Accessibility
Real table semantics (caption, scope headers, rowgroup); native checkboxes named "{permission}: {role}"; one tab stop with arrow navigation (mirrored in RTL); locked cells keep focus and announce the reason; 44px hit areas on touch.
Found in the source
- ARIA attributes set:
aria-label,aria-describedby,aria-disabled. - It moves focus in code.
- Its tests cover: “a captioned table: groups, permission row headers, roles with ”; “one tab stop; arrows move between cells; Space toggles; locked cells do not change”; “RTL: Left moves to the next role; Arabic”.
Read from the component's source and tests. See Accessibility for the patterns the library follows.
Related
SettingRow/PlatformDefaultRow: other settings.SaveBar(kit): batch saving edits.
See also: useLanguage · NumberSetting
Source
src/pr/PermissionMatrix.tsx (line 40) on GitHub.