Building UI with PermDock

The UI half of PermDock has one job: render what the current subject may do, in the active tenant, without a round trip per element and without a second copy of the policy. Everything on this page is built on the snapshot-backed client instance (snapshots): a PermDock with the same can, decide, filter and pick as the server, evaluated against the same portable conditions, plus the tenancy introspection from tenancy. Client answers are hints; the server adapter that performs a mutation checks again (threat model). Use pick after filter when a grant lists fields.

The hooks below are direct exports of permdock/react and permdock/react-native; permdock/vue exports them as composables, permdock/svelte as stores and permdock/solid as signals, with the same names and the same return shapes (parity table). Nothing here imports a policy, a closure or a Node built-in (invariant 8).

Hidden or disabledCopy Anchor Link

Two honest ways to show a denied action:

<Protected> hides. It does not grow a disabled mode: a disabled control needs a reason, a tooltip and an accessible name, and those are the component library's job. PermDock gives the reason:

const { allowed, status, decision } = usePermission(permissions.post.publish, post)
const why = describe(decision)   // { title: 'Approval required', detail: 'Publishing needs a reviewer', kind: 'approval' }

<Button disabled={!allowed} aria-disabled={!allowed} title={allowed ? undefined : why.detail}>Publish</Button>

describe(decision) is a pure function (importable from permdock, no React) that turns a Decision into { kind, title, detail, alternatives } with kind one of granted, denied, approval, tenant, delegation, server-only, upgrade. upgrade means every denial is not-entitled, and adds plans: the plan keys that would grant the permission, for an upgrade link. requiredPlans(decision) returns the same list from any decision (empty unless every denial is not-entitled). A decision carries the permission key, not the leaf, so pass the leaf as describe(decision, { permission }) to use its meta.title in place of the key in the granted and approval text. It never includes role names or condition internals a user should not see. Adapters use the same function for Problem Details detail, so the tooltip and the API error say the same thing. describe(decision, { messages }) localises the text: messages has titles per kind, reasons per denial reason (joined with separator, default ', ') as a record or as (reason, decision) => string | undefined, and the functions granted(permission), approval(permission, approvers) and upgrade(plans). Anything left out keeps the English default. The reasons function sees the whole denied decision, for a translation layer that needs more than the code; returning undefined keeps the reason code, as a missing record entry does.

describe(decision, {
  messages: {
    titles: { denied: "Geweigerd", approval: "Goedkeuring nodig" },
    approval: (permission, approvers) =>
      `${permission} wacht op ${approvers.join(" en ")}.`,
    reasons: (reason, decision) =>
      reason === "no-grant"
        ? t("denied.noGrant", { count: decision.alternatives.length })
        : undefined,
  },
});

There is no useDecision alias; usePermission already returns the decision.

Provider defaultsCopy Anchor Link

Set what every <Protected> renders for a slot it leaves out, and the localised describe text, once on the provider:

<PermDockProvider
  snapshot={snapshot}
  defaults={{
    pending: <Skeleton />,
    fallback: null,
    approval: (decision) => <RequestAccess token={decision.token} />,
  }}
  messages={{ titles: { denied: "Geweigerd" } }}
  onSnapshot={(snapshot) => cache.set(snapshot)}
>
  {children}
</PermDockProvider>

<Protected approval> renders for an approval-required decision and receives it, so the slot can offer a request-access button with the token. Resolution runs from the component's own prop to the provider default: approval falls back to the component's fallback, then the provider's approval, then the provider's fallback. A component that sets fallback={null} therefore stays hidden whatever the provider sets. In Svelte the props are snippets, and the children snippet receives a GrantedDecision. In Vue the defaults are render functions that get the slot props. The Next.js server provider takes nodes and message records only, because a function cannot cross from a Server Component to the client.

const explain = useDescribe();
const why = explain(decision, { permission: permissions.post.publish });

Menus and toolbarsCopy Anchor Link

A menu is a list of permissions on one resource. usePermissions evaluates several references at once and returns one entry per reference, so a toolbar renders from a single snapshot pass:

const actions = usePermissions(
  [permissions.post.update, permissions.post.publish, permissions.post.delete],
  post,
);
// actions[permissions.post.update.key] -> { allowed, status, decision }
// actions.granted -> [permissions.post.update]      references, not strings

It is the client form of AuthZEN action search. The input is references (typed, rename-safe), the output is keyed by .key for lookup and exposes the granted references as an array. Entries that need the endpoint batch into one evaluations call.

ListsCopy Anchor Link

useFilter(permission, rows) runs filter against the snapshot and returns the rows the subject may act on, memoised on the row identities:

const editable = useFilter(permissions.post.update, posts);

For rows with a closure-backed grant the hook returns { rows, partial: true } and the list should render a pending state for the excluded rows or ask the server for the filtered page; a list should never be assembled client-side from an unfiltered query the server would have refused. Server components use permdock.filter directly.

Tenant switcherCopy Anchor Link

const { tenant, tenants, switchTo } = useTenant();
// tenant: 'o_acme' | null       the active tenant of the snapshot
// tenants: string[]             every membership tenant, from the snapshot
// switchTo(id): Promise<void>   see below

switchTo does one of two things depending on the provider. With snapshot({ tenants: 'all' }) the client already holds every membership's grants and the switch is local and synchronous. With the default per-tenant snapshot the provider calls refresh({ tenant }), which asks the server for a snapshot with another active tenant; the server resolves the request against the subject's memberships and answers with no-membership for a tenant it does not hold, so a forged id yields an empty snapshot, not another tenant's grants. PermDockProvider accepts a tenant prop for the initial value, and <Protected> accepts tenant to render against a derived instance:

<Protected
  permission={permissions.billing.plan.change}
  tenant="o_globex"
  fallback={null}
>
  ...
</Protected>

Provider hooks such as Clerk's useOrganization, Better Auth's useActiveOrganization or WorkOS AuthKit's organizationId remain the source of truth for which organisation the session is in; the recipe wires their change handler to switchTo, and PermDock adds the permission-aware half. Display names and logos come from the provider; PermDock only knows ids.

Memberships and role chipsCopy Anchor Link

const memberships = useMemberships(); // Membership[] from the snapshot
const roles = useRoles(); // Role[] held in the active tenant
const { roles: teamRoles } = useRoles({ team: "t_design" });

Render a "Your roles in Acme" chip list from useRoles(), an organisation list from useMemberships() filtered to tenant entries, and a shared-with-me list from on entries. The display label for a role is role.meta.title on the Role leaf; the snapshot's vocabulary carries it, so the client needs no catalog for titles.

Request accessCopy Anchor Link

useApproval handles the approval-required outcome end to end on the client:

const { decision } = usePermission(permissions.post.delete, post);
const approval = useApproval(decision);
// approval.state: 'not-needed' | 'required' | 'pending' | 'approved' | 'rejected' | 'expired'
// approval.request(note?): Promise<void>   POSTs to approvalsHandler, creates the ApprovalRequest
// approval.token                            the replay-safe token, for the retry header

request posts to the approvals URL (approvals adapter); while a component subscribes, state polls GET <approvals>/<token> on the approvalsHandler every two seconds until the request is approved, rejected or expired (a 404 reads as expired), and never during a server render or after logout; when approved, the retry helper approvalHeaders(token) returns { 'PermDock-Approval': token } for the mutation call (security: approvals). The approver never answers through this hook: approving happens in the inbox or a chat surface, authenticated as the approver. The hook never fabricates a token; it only carries the one the decision returned.

Impersonation bannerCopy Anchor Link

Support access is modelled as the customer being the principal and the support engineer the actor with a time-bound delegation (tenancy adjacent features). The client can tell:

const { principal, actor, delegation, expiresAt } = useSubject();
{
  actor && (
    <Banner>
      Viewing as {principal.id} · acting as {actor.id} · until{" "}
      {format(expiresAt)}
    </Banner>
  );
}

useSubject exposes the snapshot's subject: the principal summary, the actor (id and kind, never its secrets) and the delegation. It is also the right hook for "signed in as a service account" and for hiding personal settings when principal.kind is not 'user'.

View as (simulated snapshots)Copy Anchor Link

An admin wants to see the app as a Globex viewer would. On the server:

const preview = permdock
  .simulate({ tenant: "o_globex", roles: ["viewer"] })
  .snapshot();
// preview.simulated === true

The provider renders from it like any snapshot, useSubject().simulated is true so the app can show a "Preview" bar, and the decision endpoint refuses evaluations and approval requests whose snapshot is simulated, so a preview can never produce a real token or a real mutation. Simulated snapshots are for admins; the server only produces one for a subject that holds permissions.admin.previewAs or an equivalent grant you declare.

Role editor recipeCopy Anchor Link

A tenant admin composes a custom role from assignable declared roles, single permissions, or both. The pieces are already there:

1. permdock catalog --format json gives the assignable roles with meta.title, meta.description and the permissions each contains; render it as the palette.
2. useAssignableRoles() and useAssignablePermissions() return the roles and the ceiling permissions the current subject may hand out in the active tenant: the ceiling of assignable declared roles, narrowed by RoleSource.assignable(activeTenant), intersected with what the subject holds there. A viewer cannot compose an admin; a role marked meta.manageRoles lifts the intersection.
3. The form submits { tenant, name, includes, grants } to a server action that validates it against the published Standard JSON Schema for CustomRole, checks permissions.member.assignRole, runs validateCustomRole(policy, role) and compares it with permdock.assignablePermissions() again on the server, shows any dropped keys, and writes to the app's own RoleSource backing table. Custom roles has the matrix-editor code.
4. Assigning the role to a member is a write to the auth provider's membership (Better Auth member.role, Clerk organization membership, your table) followed by refresh() on the affected client, or a CAEP event when the provider emits one.

A hosted editor over the same shape is a PermDock Cloud candidate; the open-source recipe is complete without it.

Data-fetching librariesCopy Anchor Link

The snapshot is state, not server data: it lives in the provider's external store and is read through useSyncExternalStore, so it composes with TanStack Query, SWR or a router loader without wrapping. Recipes:

• Loader: fetch the snapshot in the route loader (TanStack Router, React Router) and pass it to PermDockProvider; call refresh() after mutations that change roles.
• TanStack Query: queryClient.invalidateQueries and permdock.invalidate(permissions.post) in the same onSuccess, so cached rows and cached endpoint answers expire together.
• Server Components: no hook; getPermission and permdock.filter on the server, snapshot only for the client tree. Pass the snapshot unawaited as snapshotPromise so the layout never blocks: hooks answer status: 'pending' until it resolves and <Protected pending> renders its pending slot, so permission UI stays in the static shell; the suspend prop suspends readers through use() instead (Next.js adapter).

Status handlingCopy Anchor Link

Every hook returns status from the same vocabulary (ready, pending, stale, server-only) and allowed is always a boolean (snapshots). Rules that keep the UI honest: never block navigation on pending; render the last answer on stale; treat server-only as denied; and never flash a denied state for a portable grant (the React example asserts this in a browser-mode test).

TestingCopy Anchor Link

snapshotFixture(policy, subject, { tenant, tenants: 'all', simulated }) from permdock/testing builds every snapshot shape above, so a tenant switcher, a role-chip list or a preview bar renders in a component test or a Storybook story without a server (testing). mswHandlers answers the decision endpoint and approvalsHandler route for the request-access flow.

What PermDock does not shipCopy Anchor Link

• Components beyond <Protected> and the <PermissionBoundary> error boundary (in permdock/next/client, permdock/vue, permdock/svelte and permdock/solid): no <Can>, no tenant-switcher dropdown, no role badge, no approval dialog. Hooks return data; your design system renders it (tenancy alternatives). The devtools panel on the docs site is a canned explorer, not a package export (devtools).
• Tenant display names, logos or invitation flows: the auth provider owns them.
• A client-side copy of the policy: conditions travel in the snapshot, closures stay on the server.