Permission Gate System

The Permission Gate system provides a flexible way to control UI rendering based on user roles and permissions. It lets you easily render or hide pieces of UI relative to the user’s access role.

Core Concepts

The Permission Gate system operates on three main concepts:

1. Roles - Represent user access levels (e.g., ‘admin’, ‘user’, ‘partner’)
2. Components - Named UI elements or features that require permission control
3. Rules - Mappings between components and the roles that can access them

Permission Gate Provider

The PermissionGateProvider must wrap your application to make permission checks available throughout the component tree.

1. Define or get from API rules and freeze them:

import type { Rules } from 'permission-gate';

export const components = Object.freeze({
  users_roles: 'users&roles',
  change_role: 'change-role',
  permissions: 'permissions',
  admin_statistics: 'admin-statistics',
  // Add all your component identifiers here
  ...
});

2. Set up the provider with the user’s role and permission rules:

import { PermissionGateProvider } from 'permission-gate';
...

const rules = Object.freeze({
  componentName: ['admin', 'user', 'other-role'],
  anotherComponentName: ['admin'],
  // Map components to allowed roles
});

function MyApp() {
  const role = 'user'; // Get this from your authentication system

  return (
    <PermissionGateProvider role={role} rulesMap={rules}>
      <App />
    </PermissionGateProvider>
  )
}

Permission Gate Hook

The usePermission hook is the primary way to check permissions in your components. It returns an object with:

• granted: boolean — indicates whether the current user has access to the specified component
• role: string — the current user role
• rulesMap: object — the mapping of components to allowed roles

You can also use it to get the current role without specifying a component.

// Type definitions (Flow / TypeScript compatible)

/**
 * Represents a user role name, e.g., 'admin', 'user', 'partner'
 */
type RoleName = string;

/**
 * Named UI component or feature that requires permission control
 */
type ComponentName = string;

/**
 * Permission rules structure
 */
export type Rules = {|
  /** Mapping from component name to array of roles that can access it */
  rulesMap: { [key: ComponentName]: Array<RoleName>, ... },
  /** Current user's role */
  role: RoleName,
  /** Optional custom validator function for complex rules */
  validator?: (params: Rules & { name: string }) => boolean,
|};

/**
 * Hook to check permissions for a component
 * @param name - Component identifier
 * @returns Object containing rules and access info
 */
declare export function usePermission(name: ComponentName): {| ...Rules, granted: boolean |};

import { usePermission } from 'permission-gate';
import { components } from '@power-rent/lib/accessRules';

const { granted: showAdminStatistics } = usePermission(components.admin_statistics);

return (
  ...
  {showAdminStatistics && (
    <Box my={2}>
      <AdminStatistics dashboard={viewer.dashboard} />
    </Box>
  )}
  ...
)

Getting Current User Role

The usePermission hook also allows you to get the current user’s role without specifying a specific component. This is useful when you need to perform additional logic based on the role.

import { usePermission } from 'permission-gate';

const { role } = usePermission('');
const isPartner = role === 'PARTNER';

Custom Validators

You can provide a custom validator function to implement more complex permission logic:

function MyApp() {
  const customValidator = ({ name, role, rulesMap }) => {
    // Custom logic here
    if (name === 'special-feature' && role === 'premium-user') {
      return true;
    }
    // Fall back to default validation
    return rulesMap[name]?.includes(role) || false;
  };

  return (
    <PermissionGateProvider
      role={userRole}
      rulesMap={rules}
      validator={customValidator}
    >
      <App />
    </PermissionGateProvider>
  )
}