@cartoriocriciuma/rbac-frontend v1.0.0-alpha.1

@cartoriocriciuma/rbac-frontend

Componentes React e hooks para integração do sistema RBAC com aplicações frontend.

Instalação

npm install @cartoriocriciuma/rbac-frontend

Configuração

Antes de usar os componentes e hooks, configure os adaptadores necessários:

import { 
  configureAuthContextAdapter, 
  configureNavigationAdapter, 
  configureNotificationAdapter 
} from '@cartoriocriciuma/rbac-frontend';

// Configurar adaptador de autenticação
configureAuthContextAdapter(() => ({
  // Map de permissões do usuário atual
  userPermissions: {
    'usuarios:view': { 
      id: 'usuarios:view', 
      codigo: 'usuarios:view', 
      nome: 'Ver usuários',
      description: 'Permite visualizar usuários',
      recurso: 'usuarios',
      acao: 'view',
      ativo: true
    }
  },
  // Flag para indicar se o usuário é superadmin
  isSuperAdmin: false,
  // Função para atualizar permissões
  refreshPermissions: async () => {
    // Lógica para recarregar permissões
  }
}));

// Configurar adaptador de navegação
configureNavigationAdapter({
  navigate: (path) => {
    // Usar router da aplicação
    history.push(path);
  }
});

// Configurar adaptador de notificações
configureNotificationAdapter({
  showNotification: (options) => {
    // Usar sistema de notificações da aplicação
    toast({
      title: options.title,
      description: options.message,
      status: options.type,
      // ...outros parâmetros
    });
  }
});

Componentes

PermissionCheck

Componente para renderização condicional baseada em permissões:

import { PermissionCheck } from '@cartoriocriciuma/rbac-frontend';

// Verificar uma única permissão
<PermissionCheck permission="usuarios:view">
  <button>Ver Usuários</button>
</PermissionCheck>

// Verificar múltiplas permissões (deve ter todas)
<PermissionCheck 
  permissions={['usuarios:view', 'usuarios:edit']} 
  requireAll={true}
>
  <button>Editar Usuários</button>
</PermissionCheck>

// Com conteúdo alternativo quando não tem permissão
<PermissionCheck 
  permission="relatorios:view"
  fallback={<p>Você não tem permissão para ver relatórios</p>}
>
  <ReportViewer />
</PermissionCheck>

ProtectedRoute

Componente para proteger rotas baseado em permissões:

import { ProtectedRoute } from '@cartoriocriciuma/rbac-frontend';

// Rota protegida por uma permissão
<ProtectedRoute 
  permission="usuarios:view"
  redirectTo="/acesso-negado"
>
  <UserListPage />
</ProtectedRoute>

// Rota protegida por múltiplas permissões
<ProtectedRoute 
  permissions={['config:view', 'config:edit']}
  requireAll={false} // Precisa de pelo menos uma
  redirectTo="/acesso-negado"
  silentRedirect={true} // Não mostra notificação
>
  <ConfigPage />
</ProtectedRoute>

Hooks

useHasPermission

Hook para verificar se o usuário tem uma permissão específica:

import { useHasPermission } from '@cartoriocriciuma/rbac-frontend';

function MyComponent() {
  // Verificar uma permissão
  const canViewUsers = useHasPermission('usuarios:view');
  
  return (
    <div>
      {canViewUsers && <button>Ver Usuários</button>}
    </div>
  );
}

useHasPermissions

Hook para verificar múltiplas permissões:

import { useHasPermissions } from '@cartoriocriciuma/rbac-frontend';

function MyComponent() {
  // Verificar se tem todas as permissões
  const canManageUsers = useHasPermissions([
    'usuarios:view', 
    'usuarios:edit',
    'usuarios:delete'
  ], true);
  
  // Verificar se tem pelo menos uma das permissões
  const canDoSomething = useHasPermissions([
    'feature1:use', 
    'feature2:use'
  ], false);
  
  return (
    <div>
      {canManageUsers && <button>Gerenciar Usuários</button>}
      {canDoSomething && <button>Usar Recursos</button>}
    </div>
  );
}

usePermissions

Hook para gerenciar permissões e grupos:

import { usePermissions } from '@cartoriocriciuma/rbac-frontend';

function PermissionsManager() {
  // Obter estado e ações para gerenciar permissões
  const [
    { permissoes, gruposPermissao, loading, error },
    { 
      buscarPermissoes,
      buscarGrupos,
      buscarPermissoesAgrupadas
    }
  ] = usePermissions();
  
  // Carregar permissões quando o componente montar
  useEffect(() => {
    buscarPermissoes();
    buscarGrupos();
  }, []);
  
  return (
    <div>
      {loading && <Spinner />}
      {error && <ErrorAlert message={error.message} />}
      
      <h2>Permissões ({permissoes.length})</h2>
      <ul>
        {permissoes.map(perm => (
          <li key={perm.id}>{perm.nome}</li>
        ))}
      </ul>
      
      <h2>Grupos ({gruposPermissao.length})</h2>
      {/* ... */}
    </div>
  );
}

API de Adaptadores

Adaptador de Autenticação

interface AuthContextType {
  userPermissions: Record<string, Permission>;
  isSuperAdmin?: boolean;
  refreshPermissions: () => Promise<void>;
}

Adaptador de Navegação

interface NavigationAdapter {
  navigate: (path: string) => void;
}

Adaptador de Notificações

interface NotificationAdapter {
  showNotification: (options: {
    message: string;
    type: 'error' | 'warning' | 'info' | 'success';
    title?: string;
    actionText?: string;
    actionPath?: string;
    onAction?: () => void;
  }) => void;
}