@50arms/ui 0.0.0-stage → 35.1.0

package/dist/types/components/rbac/AccountMenu.d.ts

@@ -0,0 +1,46 @@
+import type { ReactNode } from "react";
+import { type IconName } from "../Icon";
+/** DX-4067 — one titled block inside the menu, drawn exactly like the built-in "Your access" block so a consumer's extra section cannot look foreign. */
+export declare function AccountMenuSection({ title, children }: {
+    title: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** DX-5319 - one header control that no longer fits the header and lives in the account menu instead. */
+export interface AccountMenuAction {
+    id: string;
+    label: string;
+    icon: IconName;
+    /** Runs when the row is chosen; the menu closes with it (`PopoverClose`), so what it opens (a dialog, a page) is not left under the popover. */
+    onSelect: () => void;
+    /**
+     * DX-5319 - a count the control's header button carried (unread replies), kept on its row so folding it does not hide the number.
+     * `label` is required: the chip is a number with no words, so the row's assistive name needs them (the same reason `BadgeDismiss.label` is).
+     * Omitted, or `value` of 0 -> no chip.
+     */
+    badge?: {
+        value: number;
+        label: string;
+    };
+}
+export interface AccountMenuProps {
+    /**
+     * DX-5319 - header controls folded into the menu because the header ran out of room (`useHeaderFold`), as the first group of
+     * rows, in the order given. The consumer passes only the controls that are folded right now, so a control is in the header
+     * or in this list, never both and never neither. Omitted or empty -> no group.
+     */
+    actions?: AccountMenuAction[];
+    /** DX-4067 — a mark beside the person's name in the header (a "Beta" badge). Presentational: the menu only places it. */
+    nameBadge?: ReactNode;
+    /** DX-4067 — extra blocks, drawn after "Your access". Wrap each in `AccountMenuSection`. */
+    sections?: ReactNode;
+    /** DX-4067 — a muted line at the very bottom (the running version). Omitted → no footer. */
+    footer?: ReactNode;
+    onNavigateProfile?: () => void;
+    onNavigateRoles?: () => void;
+    /** Where the role line leads — the page listing every granted permission. Omitted → the line is plain text. */
+    onNavigateAccess?: () => void;
+    onSwitchTeam?: (teamId: string) => void;
+    onSignOut?: () => void;
+    className?: string;
+}
+export declare function AccountMenu({ actions, nameBadge, sections, footer, onNavigateProfile, onNavigateRoles, onNavigateAccess, onSwitchTeam, onSignOut, className, }: AccountMenuProps): import("react").JSX.Element;

package/dist/types/components/rbac/AgentKeysList.d.ts

@@ -0,0 +1,20 @@
+import type { ReactNode } from "react";
+import { type ApiKey, type KeyRoleEditor } from "./ApiKeysTable";
+export interface AgentKeysListProps {
+    /** The keys agents hold, already scoped to the person. */
+    keys: ApiKey[];
+    onRevoke: (id: number) => Promise<void>;
+    /** The id of a key currently mid-revoke, mid-role-change or mid-grant-removal. Disables just that row's controls. */
+    busyId?: number | null;
+    /** Makes each key's role editable in place. Omit for a read-only role badge. */
+    roleEditor?: KeyRoleEditor;
+    /** Makes each key's grant chips removable (DX-4433). Omit and keys that carry grants show them read-only. */
+    onRevokeGrant?: (keyId: number, grantId: number) => Promise<void>;
+    /** Replaces a key's name text, e.g. with a link to the worker the key belongs to (DX-4487). Return `null` to keep the plain name. */
+    renderName?: (apiKey: ApiKey) => ReactNode;
+    /** One line under a key's name, e.g. the worker's readiness badge (DX-4487). Return `null` for a key with none. */
+    renderStatus?: (apiKey: ApiKey) => ReactNode;
+    emptyState?: ReactNode;
+    className?: string;
+}
+export declare function AgentKeysList({ keys, onRevoke, busyId, roleEditor, onRevokeGrant, renderName, renderStatus, emptyState, className }: AgentKeysListProps): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined>;

package/dist/types/components/rbac/ApiKeysPanel.d.ts

@@ -0,0 +1,26 @@
+import type { ReactNode } from "react";
+import { type ApiKey } from "./ApiKeysTable";
+import type { Permission, Role } from "./types";
+export interface ApiKeysPanelProps {
+    /** The keys the person made for themselves. */
+    keys: ApiKey[];
+    /** The roles the create dialog offers. */
+    roles: Role[];
+    /** The permission catalog, used to name the permissions that make a role unavailable. */
+    permissions: Permission[];
+    /** What the key's owner holds. A role holding anything outside this set cannot be chosen. */
+    ownPermissionKeys: string[];
+    onCreate: (input: {
+        name: string;
+        roleId: string;
+        expiresInDays?: number | null;
+    }) => Promise<{
+        token: string;
+    }>;
+    onRevoke: (id: number) => Promise<void>;
+    /** The id of a key currently mid-revoke. Disables just that row. */
+    busyId?: number | null;
+    emptyState?: ReactNode;
+    className?: string;
+}
+export declare function ApiKeysPanel({ keys, roles, permissions, ownPermissionKeys, onCreate, onRevoke, busyId, emptyState, className, }: ApiKeysPanelProps): import("react").JSX.Element;

package/dist/types/components/rbac/ApiKeysTable.d.ts

@@ -0,0 +1,63 @@
+import { type ReactNode } from "react";
+import type { Permission, Role } from "./types";
+import { type EndedState, type IdleState } from "./EndedLine";
+export interface ApiKey {
+    id: number;
+    name: string;
+    /** The label of the role this key acts with. A label, not an id: a key can carry a role of a team other than the one whose
+     *  `roles` the create dialog offers, and only the consumer's server can name that one. */
+    roleLabel: string;
+    /** The id of that role, matching a `Role.id` in `roleEditor.roles`. Needed only for a key whose role is editable. */
+    roleId?: string;
+    /** ISO instant. */
+    createdAt: string;
+    /** ISO instant, or `null`/omitted if it has never been used. */
+    lastUsedAt?: string | null;
+    /** ISO instant, or `null`/omitted for a key with no expiry. */
+    expiresAt?: string | null;
+    /** Permissions added to this key on top of its role (DX-4433). Omit, or leave empty, for a key that holds only its role. */
+    grants?: KeyGrant[];
+    /** DX-5246: set on a key that has ended (revoked, expired or retired): the consumer's own words for how it ended (`label`) and the ISO instant it did (`at`). An ended row shows them under its name and offers no revoke, role change or grant removal. */
+    ended?: EndedState;
+    /** DX-5246: set on a key that still works but nobody is using (its session gone quiet, a script that stopped): the consumer's own words (`label`) and the ISO instant it was last in use (`at`). An idle row shows them under its name and keeps its revoke, role change and grant removal. */
+    idle?: IdleState;
+}
+/** One permission an approved request added to a key, on top of its role. */
+export interface KeyGrant {
+    id: number;
+    /** The permission key granted. Compared for equality only. */
+    permissionKey: string;
+    /** The permission's label, as shown on the chip and in the confirm. */
+    label: string;
+    /** ISO instant. */
+    grantedAt: string;
+    /** The reason the agent gave when it asked. Plain text. */
+    reason?: string;
+}
+/** Makes a key's role editable in place. `roles` are the roles the owner may pick from: one list for every key, or a function
+ *  of the key when the keys do not share one (DX-4431: an agent session takes agent roles, a worker a human role that can manage workers). */
+export interface KeyRoleEditor {
+    roles: Role[] | ((apiKey: ApiKey) => Role[]);
+    /** The permission catalog, used to name the permissions that make a role unavailable. */
+    permissions: Permission[];
+    /** What the owner holds. A role holding anything outside this set is listed but cannot be chosen. */
+    ownPermissionKeys: string[];
+    /** Fired when a different role is picked. The consumer saves it and refreshes `keys`. */
+    onChange: (id: number, roleId: string) => Promise<void>;
+}
+export interface ApiKeysTableProps {
+    keys: ApiKey[];
+    onRevoke: (id: number) => Promise<void>;
+    /** The id of a key currently mid-revoke, mid-role-change or mid-grant-removal. Disables just that row's controls. */
+    busyId?: number | null;
+    /** Makes each key's role editable in place (DX-4427). Omit for a read-only role badge. */
+    roleEditor?: KeyRoleEditor;
+    /** Makes each grant's chip removable (DX-4433). Fired only after the confirm dialog. Omit for read-only grant chips. */
+    onRevokeGrant?: (keyId: number, grantId: number) => Promise<void>;
+    /** Replaces a key's name text, e.g. with a link to what the key belongs to (DX-4487). Return `null` to keep the plain name. */
+    renderName?: (apiKey: ApiKey) => ReactNode;
+    /** One line under a key's name, e.g. a live status badge (DX-4487). Return `null` for a key with none. */
+    renderStatus?: (apiKey: ApiKey) => ReactNode;
+    className?: string;
+}
+export declare function ApiKeysTable({ keys, onRevoke, busyId, roleEditor, onRevokeGrant, renderName, renderStatus, className }: ApiKeysTableProps): import("react").JSX.Element;

package/dist/types/components/rbac/Brand.d.ts

@@ -0,0 +1,8 @@
+export interface BrandProps {
+    name: string;
+    logoUrl?: string | null;
+    /** Logo only, no team name — the collapsed-rail / icon-only rendering. */
+    compact?: boolean;
+    className?: string;
+}
+export declare function Brand({ name, logoUrl, compact, className }: BrandProps): import("react").JSX.Element;

package/dist/types/components/rbac/Can.d.ts

@@ -0,0 +1,19 @@
+import type { ReactNode } from "react";
+export interface CanProps {
+    /** A single permission key the effective role must carry. */
+    permission?: string;
+    /** Rendered when the effective role carries ANY of these keys. */
+    anyOf?: string[];
+    /** Shown when the permission check fails. Defaults to nothing at all. */
+    fallback?: ReactNode;
+    children: ReactNode;
+}
+/**
+ * Reads `hasPermission` off `useRBAC()` directly — the same derived function
+ * `Can` itself calls — so a consumer that needs the boolean without wanting
+ * `Can`'s all-or-nothing render (to feed a `disabled` prop, a tooltip, a
+ * conditional menu section) never has to reach past this component's own
+ * public surface to get it.
+ */
+export declare function useHasPermission(key: string): boolean;
+export declare function Can({ permission, anyOf, fallback, children }: CanProps): ReactNode;

package/dist/types/components/rbac/ChangePasswordForm.d.ts

@@ -0,0 +1,18 @@
+import { type PasswordRequirementRule } from "../PasswordRequirements";
+interface ChangePasswordFormBaseProps {
+    /** Pure — recomputed against the current draft of the new password on every
+     *  render. See the module header for why this is a function rather than a
+     *  precomputed `rules[]`. */
+    passwordRules: (nextPassword: string) => PasswordRequirementRule[];
+    submitLabel?: string;
+    className?: string;
+}
+export type ChangePasswordFormProps = ChangePasswordFormBaseProps & ({
+    hasCurrentPassword?: true;
+    onSubmit: (current: string, next: string) => Promise<void>;
+} | {
+    hasCurrentPassword: false;
+    onSubmit: (next: string) => Promise<void>;
+});
+export declare function ChangePasswordForm(props: ChangePasswordFormProps): import("react").JSX.Element;
+export {};

package/dist/types/components/rbac/DangerZone.d.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from "react";
+export interface DangerZoneProps {
+    title?: string;
+    description?: string;
+    children?: ReactNode;
+    className?: string;
+}
+export declare function DangerZone({ title, description, children, className }: DangerZoneProps): import("react").JSX.Element;

package/dist/types/components/rbac/DevToolsPopover.d.ts

@@ -0,0 +1,36 @@
+/** The glyph of the Dev tools button. An app that folds the button into its account menu (`useHeaderFold`) draws the entry with this same glyph. */
+export declare const DEV_TOOLS_ICON: "wrench";
+export interface DevToolsPopoverProps {
+    /** Deep link to the dev-only Use Case Ledger. Omit and the row does not render. */
+    onOpenUseCaseLedger?: () => void;
+    /**
+     * Shows the Data source / Network speed / Regenerate demo data section —
+     * all three read and write THIS LIBRARY's OWN `src/lib/sim/` layer
+     * (`createSimStore`), which exists for the pitch-deck demo and has nothing
+     * to do with role-based access control. Defaults `true` so this package's
+     * own demo pages need no change. A consuming app with a real backend and no
+     * `createSimStore` usage of its own sets this `false` — otherwise the panel
+     * shows a "Simulated ↔ Live" toggle and a "Regenerate demo data" button
+     * that do nothing observable in that app, which reads as broken rather than
+     * inert. "View as" role impersonation (the RBAC feature this component
+     * exists to gate) and "Reset to actual" are unaffected either way — they
+     * have nothing to do with the sim layer.
+     */
+    showSimControls?: boolean;
+    /**
+     * Renders the trigger as a square wrench-only button with no "Dev tools"
+     * label, the same mode as `ThemeMenu.iconOnly` (whose doc explains why it is
+     * a mode and not a class). The accessible name stays
+     * `aria-label="Developer tools"` either way.
+     */
+    iconOnly?: boolean;
+}
+export declare function DevToolsPopover({ onOpenUseCaseLedger, showSimControls, iconOnly, }?: DevToolsPopoverProps): import("react").JSX.Element | null;
+export type DevToolsPanelProps = Pick<DevToolsPopoverProps, "onOpenUseCaseLedger" | "showSimControls">;
+/**
+ * DX-5319 - the Dev tools popup's body on its own: view as a role, and the sim controls. `DevToolsPopover` draws it in its
+ * popover; an app whose header folded the wrench into the account menu (`useHeaderFold`) draws this same panel in a `Dialog`.
+ * It carries the SAME structural gate as the popover - nothing at all unless `canAccessDevTools` - so a folded entry cannot be
+ * the way round it.
+ */
+export declare function DevToolsPanel({ onOpenUseCaseLedger, showSimControls }?: DevToolsPanelProps): import("react").JSX.Element | null;

package/dist/types/components/rbac/EndedLine.d.ts

@@ -0,0 +1,21 @@
+/** DX-5246: how a credential ended, in the consumer's own words (`label`, e.g. "Revoked") and when (`at`, an ISO instant). */
+export interface EndedState {
+    label: string;
+    at: string;
+    /** What follows from it, in the consumer's own words (e.g. "counts until Oct 24"): shown after the time, after a comma. */
+    after?: string;
+}
+/** The muted "<label> <time ago>[, <after>]" line an ended session or key shows under its name (shared by `SessionsList` and `ApiKeysTable`). */
+export declare function EndedLine({ ended }: {
+    ended: EndedState;
+}): import("react").JSX.Element;
+/** DX-5246: a credential that still works but nobody is using: the consumer's own words (`label`, e.g. "Idle, last used") and, when known, the ISO instant it was last in use (`at`). */
+export interface IdleState {
+    label: string;
+    /** ISO instant of its last use; `null`/omitted for one never used, which shows the label alone. */
+    at?: string | null;
+}
+/** The muted "<label> <time ago>" line an idle session or key shows under its name (shared by `SessionsList` and `ApiKeysTable`). Unlike an ended row it keeps every action. */
+export declare function IdleLine({ idle }: {
+    idle: IdleState;
+}): import("react").JSX.Element;

package/dist/types/components/rbac/InvitationsList.d.ts

@@ -0,0 +1,39 @@
+export type InvitationStatus = "pending" | "accepted" | "revoked" | "expired";
+export interface InvitationsListItem {
+    id: string;
+    email: string;
+    roleLabel: string;
+    status: InvitationStatus;
+    createdAt: string;
+    invitedByName?: string;
+    /**
+     * The MOST RECENT send attempt's outcome for this invitation (create or a
+     * later resend), when the consumer's read surfaced one. `undefined` means
+     * the consumer's data source has no send-history correlation — the list
+     * renders no delivery indicator at all in that case (never assumed "sent"
+     * from absence). Omit `lastEmailBounced`/`lastEmailComplained` the same
+     * way when unknown, rather than defaulting to `false`.
+     */
+    lastEmailStatus?: "sent" | "failed" | "suppressed";
+    /** A LATER async bounce notification arrived for the most recent send. */
+    lastEmailBounced?: boolean;
+    /** A LATER async complaint notification arrived for the most recent send. */
+    lastEmailComplained?: boolean;
+}
+export interface InvitationsListProps {
+    invitations: InvitationsListItem[];
+    onResend: (id: string) => void;
+    onRevoke: (id: string) => void;
+    /**
+     * Copies the invite link for manual sharing (card architecture: "the admin
+     * UI can also copy the invite link"). Omit to hide the copy control
+     * entirely — a consumer whose invite creation response never surfaced a raw
+     * token (e.g. a page reload after create) has nothing to copy.
+     */
+    onCopyLink?: (id: string) => void;
+    /** The id of a row currently mid-mutation (resend or revoke). */
+    busyId?: string | null;
+    emptyState?: React.ReactNode;
+    className?: string;
+}
+export declare function InvitationsList({ invitations, onResend, onRevoke, onCopyLink, busyId, emptyState, className, }: InvitationsListProps): string | number | bigint | boolean | import("react").JSX.Element | Iterable<import("react").ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<import("react").ReactNode> | null | undefined>;

package/dist/types/components/rbac/InviteMembersDialog.d.ts

@@ -0,0 +1,21 @@
+import type { Role } from "./types";
+export interface InviteMembersDialogProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** The roles an invitee may be given — the role Select's options. */
+    assignableRoles: Role[];
+    /** Disables the form and shows a busy submit button while the invite request is in flight. */
+    loading?: boolean;
+    /**
+     * A server-side error surfaced after a failed submit (e.g. "invite_exists"
+     * for one address) — rendered as a `Callout`. The dialog has no notion of
+     * WHY a send failed; the consumer's own error copy goes here verbatim.
+     */
+    error?: string;
+    onSubmit: (input: {
+        emails: string[];
+        roleId: string;
+    }) => void;
+    className?: string;
+}
+export declare function InviteMembersDialog({ open, onOpenChange, assignableRoles, loading, error, onSubmit, className, }: InviteMembersDialogProps): import("react").JSX.Element;

package/dist/types/components/rbac/MembersPanel.d.ts

@@ -0,0 +1,31 @@
+import type { ReactNode } from "react";
+import type { Role, User } from "./types";
+export interface MembersPanelMember {
+    user: User;
+    /** The member's CURRENT role. */
+    role: Role;
+    /** ISO timestamp of when the member joined the team. */
+    joinedAt: string;
+    /** Non-null disables this row's role Select and remove control, with this
+     *  text as the reason shown alongside them (e.g. "The team's only owner"). */
+    disabledReason?: string;
+}
+export interface MembersPanelProps {
+    members: MembersPanelMember[];
+    /** The roles a member may be changed TO — the role Select's options. A row
+     *  whose own role is not listed still shows that role (its label is kept as
+     *  that row's one extra option); it is never offered to any other row. */
+    assignableRoles: Role[];
+    onChangeRole: (userId: string, roleId: string) => void;
+    onRemove: (userId: string) => void;
+    /** The id of a row currently mid-mutation. Disables just that row rather
+     *  than the whole panel, so an operator working through several rows in a
+     *  row is never blocked on the last one's round trip. */
+    busyUserId?: string | null;
+    /** Extra content drawn inside each member's row, below the name and email,
+     *  given that row's member. Absent, the row is exactly the default one. */
+    renderMemberExtra?: (member: MembersPanelMember) => ReactNode;
+    emptyState?: ReactNode;
+    className?: string;
+}
+export declare function MembersPanel({ members, assignableRoles, onChangeRole, onRemove, busyUserId, renderMemberExtra, emptyState, className, }: MembersPanelProps): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined>;

package/dist/types/components/rbac/PermissionRequestPanel.d.ts

@@ -0,0 +1,36 @@
+import { type AccessRequestState, type ExpiredNote } from "./approvalPanelParts";
+import type { Permission } from "./types";
+export interface PermissionRequest {
+    /** The name of the key that is asking: what the agent's key is called. */
+    keyName: string;
+    /** The agent's stated reason, plain text. */
+    reason: string;
+    /** The permission keys requested, in the order the agent listed them. */
+    permissionKeys: string[];
+    /** ISO instant. */
+    requestedAt: string;
+    /** ISO instant. Shown while the request is pending. */
+    expiresAt?: string;
+    /** The short code the agent also displays. Compared by eye, never entered. */
+    confirmCode: string;
+    /** What was actually granted (a subset of `permissionKeys`). Shown once the request is approved or claimed. */
+    grantedKeys?: string[];
+}
+export interface PermissionRequestPanelProps {
+    request: PermissionRequest;
+    state: AccessRequestState;
+    /** The permission catalog: labels, categories and descriptions for the requested keys. */
+    permissions: Permission[];
+    /** What the approver holds. A requested permission outside this set is shown disabled and can never be granted. */
+    ownPermissionKeys: string[];
+    /** Receives exactly the permission keys left checked. */
+    onApprove: (permissionKeys: string[]) => Promise<void>;
+    onDeny: () => Promise<void>;
+    /**
+     * Why an expired request expired and what its requester does next. Used only in the `expired` state; without it the readout says only
+     * that nothing was granted.
+     */
+    expiredNote?: ExpiredNote;
+    className?: string;
+}
+export declare function PermissionRequestPanel({ request, state, permissions, ownPermissionKeys, onApprove, onDeny, expiredNote, className, }: PermissionRequestPanelProps): import("react").JSX.Element;

package/dist/types/components/rbac/ProfileForm.d.ts

@@ -0,0 +1,27 @@
+export interface ProfileFormAccount {
+    name: string;
+    /** Omit entirely for a consumer whose account model has no separate
+     *  username concept — the field simply does not render (see `types.ts`'s
+     *  own `User.username` doc for the same optional-field convention). */
+    username?: string;
+    email: string;
+    avatarUrl?: string | null;
+}
+export interface ProfileFormSaveInput {
+    name: string;
+    username?: string;
+    email: string;
+    /** Present only when the avatar changed: a URL sets it, `null` removes it. */
+    avatarUrl?: string | null;
+}
+export interface ProfileFormProps {
+    account: ProfileFormAccount;
+    onSave: (input: ProfileFormSaveInput) => Promise<void>;
+    /** Uploads the file to storage and resolves with its URL. Must NOT change the
+     *  account — the avatar is only persisted by `onSave`. */
+    onUploadAvatar: (file: File) => Promise<string>;
+    saveLabel?: string;
+    discardLabel?: string;
+    className?: string;
+}
+export declare function ProfileForm({ account, onSave, onUploadAvatar, saveLabel, discardLabel, className, }: ProfileFormProps): import("react").JSX.Element;

package/dist/types/components/rbac/ProfilePage.d.ts

@@ -0,0 +1,16 @@
+import { type ProfileFormAccount, type ProfileFormSaveInput } from "./ProfileForm";
+export interface ProfilePageProps {
+    /** The identity fields to edit. Omit to keep the original read-only (but
+     *  still locally-editable) `actualUser` display. */
+    account?: ProfileFormAccount;
+    onSave?: (input: ProfileFormSaveInput) => Promise<void>;
+    /** Uploads the file and resolves with its URL; the avatar is persisted only by `onSave` (DX-4131). */
+    onUploadAvatar?: (file: File) => Promise<string>;
+    /** DX-4029: `false` omits the page's own title text (the `<h1>` and the
+     *  team-name line) so a host layout can own the screen's one `<h1>`. The
+     *  read-only avatar (content, not title) stays, and the default `true` is
+     *  the unchanged render. */
+    heading?: boolean;
+    className?: string;
+}
+export declare function ProfilePage({ account, onSave, onUploadAvatar, heading, className, }: ProfilePageProps): import("react").JSX.Element;

package/dist/types/components/rbac/RBACProvider.d.ts

@@ -0,0 +1,69 @@
+import { type ReactNode } from "react";
+import type { Permission, Role, Team, TeamMembership, User } from "./types";
+export interface RBACProviderProps {
+    currentUser: User;
+    roles: Role[];
+    permissions: Permission[];
+    teams: Team[];
+    /** All memberships for `currentUser`, across every team — not just the current one. */
+    memberships: TeamMembership[];
+    currentTeamId: string;
+    /**
+     * Decides who may open the Dev Tools "view as" escape hatch.
+     *
+     * Deliberately a predicate over the consumer's OWN data (`user`, `roles`,
+     * `memberships`) rather than a boolean prop or a hardcoded role check. The
+     * library has no idea what "admin enough to use dev tools" means for any
+     * given consumer — one app might key it off a role id, another off a team
+     * membership count, another off a flag on `User` this contract doesn't even
+     * define. Only the consumer's own data model can answer that, so the
+     * decision is handed back to them wholesale.
+     */
+    canAccessDevTools: (user: User, roles: Role[], memberships: TeamMembership[]) => boolean;
+    children: ReactNode;
+}
+export interface RBACHookResult {
+    actualUser: User;
+    currentTeam: Team | undefined;
+    /** The role backing `actualUser`'s own membership in `currentTeamId` — never affected by impersonation. */
+    actualRole: Role | undefined;
+    /** `null` when not impersonating. */
+    viewingAsRoleId: string | null;
+    setViewingAsRoleId: (id: string | null) => void;
+    /** `actualRole`, unless impersonating — then the impersonated role. */
+    effectiveRole: Role | undefined;
+    effectivePermissionKeys: Set<string>;
+    /** `permissions`, filtered to the ones `effectiveRole` actually grants —
+     *  every surface that lists "what can this role do" (`AccountMenu`,
+     *  `ProfilePage`) reads this instead of re-deriving the same filter
+     *  (DX-3254: the two used to keep independent copies of it). */
+    grantedPermissions: Permission[];
+    hasPermission: (key: string) => boolean;
+    /**
+     * Whether the REAL logged-in user may open Dev Tools.
+     *
+     * See the block comment above `evaluateCanAccessDevTools` below for why this
+     * is computed from `actualUser`/`roles`/`memberships` and can NEVER be
+     * re-derived from `effectiveRole` / `viewingAsRoleId` — that is the entire
+     * point of this field existing on the hook at all.
+     */
+    canAccessDevTools: boolean;
+    isImpersonating: boolean;
+    roles: Role[];
+    permissions: Permission[];
+    teams: Team[];
+}
+export declare function RBACProvider({ currentUser, roles, permissions, teams, memberships, currentTeamId, canAccessDevTools, children, }: RBACProviderProps): import("react").JSX.Element;
+/**
+ * Reads the RBAC context.
+ *
+ * Throws rather than returning `undefined` — the same shape as
+ * `useDragDrop` / `useDragDropContainer` (`drag-drop/context.ts`) and every
+ * other multi-part context in this library. A component that silently
+ * received `undefined` here would fail wherever it FIRST tries to read a
+ * field off the result, several lines and possibly several components away
+ * from the actual mistake (forgetting the `<RBACProvider>` wrapper) — a
+ * blank permissions list is a much harder bug to trace back than a thrown
+ * error naming the missing provider.
+ */
+export declare function useRBAC(): RBACHookResult;

package/dist/types/components/rbac/RoleEditorDialog.d.ts

@@ -0,0 +1,28 @@
+import type { Role } from "./types";
+export interface RoleEditorDialogSubmitInput {
+    label: string;
+    description: string;
+    /** Only ever sent from CREATE mode — see this file's own header. `undefined` when no clone-from role was picked. */
+    cloneFromRoleId?: string;
+}
+export interface RoleEditorDialogProps {
+    mode: "create" | "edit";
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /**
+     * CREATE mode only — the roles offered as "clone permissions from" (a
+     * consumer typically hands every role the matrix already shows, owner
+     * included: cloning owner's COMPUTED set is a legitimate way to seed a
+     * near-owner role). Omitted or empty simply hides the field — a consumer
+     * with nothing to clone from does not owe this dialog an empty array.
+     */
+    cloneFromRoles?: Role[];
+    /** EDIT mode — the role's current values, so the fields open pre-filled rather than blank. */
+    initialLabel?: string;
+    initialDescription?: string;
+    /** Disables the form and shows a busy submit button while a save is in flight. */
+    loading?: boolean;
+    onSubmit: (input: RoleEditorDialogSubmitInput) => void;
+    className?: string;
+}
+export declare function RoleEditorDialog({ mode, open, onOpenChange, cloneFromRoles, initialLabel, initialDescription, loading, onSubmit, className, }: RoleEditorDialogProps): import("react").JSX.Element;

package/dist/types/components/rbac/RoleKeyPicker.d.ts

@@ -0,0 +1,24 @@
+import type { Permission, Role } from "./types";
+export interface RoleKeyPickerProps {
+    roles: Role[];
+    /** The permission catalog, used to name the permissions that make a role unavailable. */
+    permissions: Permission[];
+    /** What the issuer holds. A role holding anything outside this set cannot be chosen. */
+    ownPermissionKeys: string[];
+    /** The chosen role id, or `""` for none. */
+    value: string;
+    onValueChange: (roleId: string) => void;
+    /** The group's visible heading. */
+    label?: string;
+    /** One line under the heading. */
+    description?: string;
+    disabled?: boolean;
+    className?: string;
+}
+/** Why `role` can't be chosen, naming the missing permissions by label. `null` when it can. */
+export declare function roleUnavailableReason(role: Role, own: ReadonlySet<string>, permissions: Permission[], unavailable: (permissionLabels: string[]) => string): string | null;
+/** Whether `roleId` names a role in `roles` that the issuer may choose. */
+export declare function isRoleSelectable(roleId: string, roles: Role[], own: ReadonlySet<string>): boolean;
+/** The id of the selectable role holding the fewest permissions (the first of any tie), or `""` when none is selectable. */
+export declare function leastPrivilegeRoleId(roles: Role[], own: ReadonlySet<string>): string;
+export declare function RoleKeyPicker({ roles, permissions, ownPermissionKeys, value, onValueChange, label, description, disabled, className, }: RoleKeyPickerProps): import("react").JSX.Element;

package/dist/types/components/rbac/RolePermissionMatrix.d.ts

@@ -0,0 +1,21 @@
+import type { Permission, Role } from "./types";
+export interface RolePermissionMatrixProps {
+    roles: Role[];
+    permissions: Permission[];
+    /**
+     * DX-3414 — turns each cell into a toggle. Defaults to `false` (the
+     * original read-only matrix, unchanged pixel-for-pixel and test-for-test).
+     * A `role.locked` column stays READ-ONLY even when `editable` — see
+     * `Role.locked`'s own doc comment (`types.ts`): a consumer's rules forbid
+     * touching that role at all, and the matrix has no business knowing why.
+     */
+    editable?: boolean;
+    /**
+     * Fired when an editable, unlocked cell is toggled. `granted` is the NEW
+     * value the caller should persist — the matrix holds no state of its own
+     * (PLN-13 R-3: presentational, no fetch); a consumer wires this to its own
+     * mutation and re-renders with the updated `roles` once it lands.
+     */
+    onChange?: (roleId: string, permissionKey: string, granted: boolean) => void;
+}
+export declare function RolePermissionMatrix({ roles, permissions, editable, onChange, }: RolePermissionMatrixProps): import("react").JSX.Element;

package/dist/types/components/rbac/RolesPermissionsPage.d.ts

@@ -0,0 +1,24 @@
+import { type RoleEditorDialogSubmitInput } from "./RoleEditorDialog";
+import type { Permission, Role } from "./types";
+export interface RolesPermissionsPageProps {
+    roles: Role[];
+    permissions: Permission[];
+    /** Gates the "New role" button, the manage-roles list, and the matrix's own `editable`. Defaults to `false` — read-only, pixel-identical to the page before this card. */
+    editable?: boolean;
+    /** Fired when an editable, unlocked matrix cell is toggled. Required to make the matrix respond; omit alongside `editable={false}`. */
+    onChangePermission?: (roleId: string, permissionKey: string, granted: boolean) => void;
+    onCreateRole?: (input: RoleEditorDialogSubmitInput) => void;
+    onRenameRole?: (roleId: string, input: {
+        label: string;
+        description: string;
+    }) => void;
+    onDeleteRole?: (roleId: string) => void;
+    /** Restores a SYSTEM role's seeded permission set — offered only for a role with `role.system` true (never `locked`; see `Role.locked`'s own doc comment for why owner never reaches this list at all). */
+    onResetRole?: (roleId: string) => void;
+    /** The id of a role currently mid-mutation. Disables just that row's controls, not the whole page. */
+    busyRoleId?: string | null;
+    /** DX-4029: `false` omits the page's own title text (the `<h1>` and the explanatory line) so a host layout can own the screen's one `<h1>`. The "New role" button stays: it is the only create-role entry point. Default `true` is the unchanged render. */
+    heading?: boolean;
+    className?: string;
+}
+export declare function RolesPermissionsPage({ roles, permissions, editable, onChangePermission, onCreateRole, onRenameRole, onDeleteRole, onResetRole, busyRoleId, heading, className, }: RolesPermissionsPageProps): import("react").JSX.Element;