Documentação da API

Introdução

A seguir são documentados os módulos e componentes do Cloudsupport for React e seus parâmetros.

As funcionalidades do Cloudsupport for React são organizadas em cinco grupos:

• Foundation: Módulos e componentes estruturantes, que podem ser utilizadados em qualquer aplicação web React.

• Prime: Módulos e componentes para aplicações baseadas em PrimeReact.

• Next: Módulos e componentes para aplicações baseadas em Next.js.

• Mixed: Módulos e componentes em envolvem dois mais grupos acima (Foundation, Prime e Next).

• Resources: Assets estáticos, como CSS.

Foundation Hooks

useAuth

Retorna objeto que contém o estado da autenticação OIDC e API de eventos e de autenticação:

{
    // Estado da autenticação
    isLoading,          // true ou false
    error,              // objeto Error do JavaScript
    isAuthenticated,    // true ou false
    user,               // objeto User (usuário autenticado) do react-oidc-context

    // API de eventos
    events,             

    // API de autenticação
    signinRedirect,     // função que inicia o fluxo de login
    signOutRedirect     // função que inicia o fluxo de logout
}

O useAuth da arquitetura é uma extensão do framework reat-oidc-context, que por sua vez é baseado no oidc-client-ts, ambos do autor authts.

Documentação dos atributos do user: https://authts.github.io/oidc-client-ts/classes/User.html.

Sobre a API de eventos: https://github.com/authts/react-oidc-context?tab=readme-ov-file#adding-event-listeners.

Sobre a função de login: https://authts.github.io/oidc-client-ts/classes/UserManager.html#signinRedirect.

Sobre a função de logout: https://authts.github.io/oidc-client-ts/classes/UserManager.html#signoutRedirect.

Outras funções de autenticação estão disponíveis na documentação do oidc-client-ts (“signinPopup”, “signinSilent”, “signinResourceOwnerCredentials”, “signoutPopup” e “signoutSilent”).

O estado inclui também o atributo activeNavigator, que é uma string que indica a operação transitória sendo executada pelo react-oidc-context. Sugere-se não tratar essa variável.

Modo desenvolvedor (mocado):

O “Modo desenvolvedor” é uma extensão do contexto de autenticação oferecida pela arquitetura. Ela permite executar a aplicação em ambiente de desenvolvimento mocando-se os dados do usuário autenticado, que inclui todos os claims possíveis do OIDC, sem necessidade de fazer a integração com um provedor (IdP) OIDC real.

Funciona assim: Caso o profile da aplicação possuir o atributo mockAuthContext, o estado retornado pelo Hook useAuth incluirá o atributo mocked: true. Além disso, o atributo user do estado será substituído completamente pelo conteúdo de mockAuthContext. O campo isAuthenticated é forçado para true.

É importante, ao configurar o profile, que mockAuthContext tenha a mesma estrutura do objeto esperado User.

Importação:

import { useAuth } from '@bernardo-dias/react-cloudsupport';

Uso:

function MeuComponente() {

    const auth = useAuth();

    if (auth.isAuthenticated === true) {
        console.log("Identidade do usuário (OIDC subject claim): ", auth.user.profile.sub);
        console.log("Nome do usuário: ", auth.user.profile.name);
        console.log("E-mail do usuário: ", auth.user.profile.email);
    }
    // ...

Notas:

Esse Hook deve ser utilizado dentro do contexto de AuthProvider, seja a versão do grupo Foundation ou do grupo Next.

Não é necessário declarar AuthProvider caso esteja utilizando o EnableCloudsupport.

Para proteger páginas/componentes com autenticação, considere o uso de AuthRequired, podendo ser do grupo Foundation ou Prime.

Importante: Evite implementar o exemplo oficial do react-oidc-context sobre como proteger páginas/componentes com autenticação. O exemplo oficial é um código simples que possui limitações em alguns fluxos (podendo resultar no erro “No matching state found in storage”). Utilize o componente oferecido pelo Cloudsupport AuthRequired.

useAccessToken

Retorna o Access Token (usualmente JWT) do usuário autenticado, ou undefined.

Equivale a useAuth()?.user?.access_token.

Importação:

import { useAccessToken } from '@bernardo-dias/react-cloudsupport';

Uso:

function MeuComponente() {

    const accessToken = useAccessToken();

    if (accessToken !== undefined) {
        console.log(`Header para autenticação OAuth2 do backend: "Authorization: Bearer ${accessToken}"`);
    }
    // ...

Notas:

Esse Hook deve ser utilizado dentro do contexto de AuthProvider, seja a versão do grupo Foundation ou do grupo Next.

Para injetar automaticamente o Access Token nas requisições webservice considere o componente da arquitetura AuthAwareNetworking e utilize Networking.fetch.

Não é necessário declarar AuthProvider e AuthAwareNetworking caso esteja utilizando o EnableCloudsupport.

hasAuthority

Retorna booleano indicando se usuário autenticado possui a permissão informada.

É feita a busca da permissão no claim OIDC de nome roles, que pode estar presente no ID Token ou User Info. As permissões do usuário ficam disponíveis no array useAuth()?.user?.profile.roles.

Importação:

import { hasAuthority } from '@bernardo-dias/react-cloudsupport';

Uso:

function MeuComponente() {

    const temPermissao = hasAuthority("roleName");

    // ...

Notas:

Esse Hook deve ser utilizado dentro do contexto de AuthProvider, seja a versão do grupo Foundation ou do grupo Next.

Não é necessário declarar AuthProvider e AuthAwareNetworking caso esteja utilizando o EnableCloudsupport.

hasAnyAuthority

Retorna booleano indicando se usuário autenticado possui pelo menos uma das permissãos informadas.

É feita a busca das permissões no claim OIDC de nome roles, que pode estar presente no ID Token ou User Info. As permissões do usuário ficam disponíveis no array useAuth()?.user?.profile.roles.

Importação:

import { hasAnyAuthority } from '@bernardo-dias/react-cloudsupport';

Uso:

function MeuComponente() {

    const temPermissao = hasAnyAuthority(["role1", "role2"]);

    // ...

Notas:

Esse Hook deve ser utilizado dentro do contexto de AuthProvider, seja a versão do grupo Foundation ou do grupo Next.

Não é necessário declarar AuthProvider e AuthAwareNetworking caso esteja utilizando o EnableCloudsupport.

useProfile

Retorna o objeto que contém as propriedades da aplicação. O retorno sempre será um objeto, nunca null ou undefined.

Importação:

import { useProfile } from '@bernardo-dias/react-cloudsupport';

Uso:

function MeuComponente() {

    const profile = useProfile();

    console.log(`As propriedades da aplicação são: ${JSON.stringify(profile)}"`);
    // ...

Notas:

Esse Hook deve ser utilizado dentro do contexto de ProfileProvider, seja a versão do grupo Foundation ou do grupo Prime.

Não é necessário declarar ProfileProvider caso esteja utilizando o EnableCloudsupport.

O profile é carregado a partir de um endpoint mapeado no Provider. Consulte sua documentação.

O profile também está disponível através da função utilitária getProfile, que pode ser utilizada fora do contexto de componentes React. Essa função retornará undefined até que profile esteja devidamente carregado pelo ProfileProvider.

useProfileStatus

Retorna o objeto que indica a situação do profile:

{
    outdated      // true ou false
}

O profile é marcado como outdated (desatualizado) quando o endpoint mapeado no ProfileProvider retorna um objeto diferente do profile carregado na aplicação. O Provider confere o endpoint periodicamente. Consulte sua documentação.

Importação:

import { useProfileStatus } from '@bernardo-dias/react-cloudsupport';

Uso:

function MeuComponente() {
        
    const status = useProfileStatus();

    if (!status.outdated) {
        console.log("A aplicação está carregada com as propriedades mais recentes");
    } else {
        console.log("As propriedades da aplicação estão desatualizadas");
    }
    // ...

Notas:

Esse Hook deve ser utilizado dentro do contexto de ProfileProvider, seja a versão do grupo Foundation ou do grupo Prime.

Não é necessário declarar ProfileProvider caso esteja utilizando o EnableCloudsupport.

Normalmente não será necessário utilizar esse Hook em aplicações com PrimeReact. O componente da arquitetura ReloadBanner, do grupo Prime, monitora a mudança do status do profile e exibe um aviso de atualização pendente.

useProcessing

Retorna API para sinalização de início e de fim de processamento e o estado do processamento:

{
    notifyStart(),
    notifyStop(),
    isProcessing       // true ou false
}

Esse módulo suporta concorrência de processamentos de longa duração, de forma que notifyStop() surtirá efeito, ou seja, fará isProcessing valer false, somente após ser executado na mesma quantidade de vezes que notifyStart() foi executado. Por exemplo:

1. Executa-se notifyStart() (isProcessing muda para true).

2. Executa-se notifyStart() (isProcessing continua true).

3. Executa-se notifyStop() (isProcessing continua true, pois ainda há um processamento em andamento).

4. Executa-se notifyStop() (isProcessing muda para false).

Importação:

import { useProcessing } from '@bernardo-dias/react-cloudsupport';

Uso:

function MeuComponente() {

    const processing = useProcessing();

    // Carrega os dados remotos
    React.useEffect(() => {
        processing.notifyStart(); // Sinaliza início

        pesquisarDados()
        .then(setLista)
        .catch(toast.showError)
        .finally(processing.notifyEnd); // Sinaliza fim
    }, []);
    // ...

Notas:

Esse Hook deve ser utilizado dentro do contexto de ProcessingProvider.

Não é necessário declarar ProcessingProvider caso esteja utilizando o EnableCloudsupport.

Para exibir graficamente um indicador de processamento, considere o componente ProcessingIndicator, podendo ser do grupo Foundation ou Prime. O primeiro é uma barra de progresso baseada em nprogress e o segundo é baseado no LoadingBar.

useGlobal

Permite adicionar um estado de uso global na aplicação, para fins de sessão em memória no escopo da SPA (Single Page Application).

Retorna um array com dois valores:

1. O estado corrente, inicialmente {}.

2. Uma função que permite atualizar atributos do estado por merge de objetos.

Importação:

import { useGlobal } from '@bernardo-dias/react-cloudsupport';

Uso:

function MeuComponente() {
        
    const [ global, updateGlobal ] = useGlobal();

    // Atualizado o estado global:
    updateGlobal( { tema: "Light", menu: "recolhido"} );

    // Modificando apenas um atributo do estado global:
    updateGlobal( { menu: "expandido"} );
    // ...

Notas:

Esse Hook deve ser utilizado dentro do contexto de GlobalProvider.

Não é necessário declarar GlobalProvider caso esteja utilizando o EnableCloudsupport.

Note que a atribuição do retorno de useGlobal utiliza Desestruturação de Array do JavaScript.

Foundation UI

AuthRequired

Protege os elementos filhos contra acesso não autenticado por OIDC.

Caso não exista usuário autenticado, será realizado redirect automático para o SSO do provedor (IdP) OIDC, conforme configurações no AuthProvider.

Após autenticação com sucesso, o usuário retorna para a página em que estava antes da autenticação. Isso ocorre porque o AuthRequired envia para o SSO a URL corrente como parâmetro de URL de retorno.

Por padrão, os parâmetros state, session_state e code são removidos da URL de retorno, pois são palavras-chave do padrão OIDC.

Os elementos filhos de AuthProvider são exibidos somente após a autenticação bem-sucedida.

Um vez ocorrida a autentação bem-sucedida, os elementos filhos são exibidos e continuarão sendo exibidos mesmo que o Access Token venha a expirar. Esse comportamento é desejado para que a aplicação possa implementar a melhor UX neste cenário, como exibir um banner, bloquear a página ou simplesmente mostrar um popup ou notificação.

O componente da arquitetura SessionExpiredBanner, do grupo Prime, monitora o evento de sessão expirada e exibe um banner com botão para login. É conveniente que ele seja declarado dentro de AuthRequired conforme exemplos abaixo.

Uma alternativa ao SessionExpiredBanner seria implementar manualmente os eventos disponíveis no Hook useAuth.

Importação:

import { AuthRequired } from '@bernardo-dias/react-cloudsupport';

Uso básico:

function MeuLayout(props) {

    return (
        <AuthRequired>
            <SessionExpiredBanner />
            
            {props.children}
        </AuthRequired>
    );
}

Uso avançado:

function MeuLayout(props) {

    return (
        <AuthRequired
            Loading={({action}) => <center><h4>Loading auth... ({action})</h4></center>}
            Failed={({error}) => <center><h4>{error.message}</h4></center>}
            getSigninOptions={() => ({ redirect_uri: "https://app.dominio.com" })}>

            <SessionExpiredBanner />
            
            {props.children}
        </AuthRequired>
    );
}

Parâmetros:

Notas:

Caso a aplicação seja baseada no PrimeReact, considere o uso do componente AuthRequired do grupo Prime da arquitetura, que implementa elementos padrões de UI baseados no LoadingBar (durante processamento de tarefa) e MessageBlock (em caso de erro), ambos customizáveis.

Esse Hook deve ser utilizado dentro do contexto de AuthProvider, seja a versão do grupo Foundation ou do grupo Next.

Não é necessário declarar AuthProvider caso esteja utilizando o EnableCloudsupport.

HasAuthority

Protege os elementos filhos contra acesso não autorizado por OIDC. Aplica o efeito do Hook hasAuthority.

Importação:

import { HasAuthority } from '@bernardo-dias/react-cloudsupport';

Uso básico:

function MeuLayout(props) {

    return (
        <HasAuthority value='roleName'>            
            {props.children}
        </HasAuthority>
    );
}

Uso avançado:

function MeuLayout(props) {

    return (
        <HasAuthority 
            value='roleName' 
            Denied={({authority}) => <center><h4>Access denied</h4></center>}>

            {props.children}
        </HasAuthority>
    );
}

Parâmetros:

HasAnyAuthority

Protege os elementos filhos contra acesso não autorizado por OIDC. Aplica o efeito do Hook hasAnyAuthority.

Importação:

import { HasAnyAuthority } from '@bernardo-dias/react-cloudsupport';

Uso básico:

function MeuLayout(props) {

    return (
        <HasAnyAuthority value={['role1', 'role2']}>            
            {props.children}
        </HasAnyAuthority>
    );
}

Uso avançado:

function MeuLayout(props) {

    return (
        <HasAnyAuthority 
            value={['role1', 'role2']}
            Denied={({authority}) => <center><h4>Access denied</h4></center>}>

            {props.children}
        </HasAnyAuthority>
    );
}

Parâmetros:

ProcessingIndicator

Exibe uma barra de progresso via nprogress.js conforme a sinalização de processamento via Hook useProcessing.

Para melhor UX, a barra é mostrada somente após um delay proposital.

Importação:

import { ProcessingIndicator } from '@bernardo-dias/react-cloudsupport';

Uso:

function MeuLayout(props) {

    return (
        <>
            <ProcessingIndicator />
            
            {props.children}
        </>
    );
}

Notas:

Caso a aplicação seja baseada no PrimeReact, considere o uso do componente ProcessingIndicator do grupo Prime da arquitetura, que exibe uma UI padrão de carregamento baseada no LoadingBar (podendo ser customizada). Entretanto, a UX do ProcessingIndicator do grupo Foundation é interessante, por ser baseada no nprogress.js.

Esse componente deve ser utilizado dentro do contexto de ProcessingProvider.

Não é necessário declarar ProcessingIndicator e ProcessingProvider caso esteja utilizando o EnableCloudsupport.

Foundation Utils

getProfile

Função que retorna o mesmo objeto que o Hook useProfile. Entretanto, essa função retorna undefined até que o profile tenha sido carregado pelo ProfileProvider.

Para uso indicado fora do contexto de componentes React.

Importação:

import { getProfile } from '@bernardo-dias/react-cloudsupport';

Uso:

const profile = getProfile();

Notas:

É necessário declarar ProfileProvider, seja a versão do grupo Foundation ou do grupo Prime ou EnableCloudsupport para que o profile seja carregado.

Networking

Módulo que oferece versão estendida do fetch do JavaScript.

As extensões estão disponíveis no parâmetro options do fetch. Todos os atributos nativos do options são suportados, com a adição do cs:

options = {
    // Todos os atributos nativos do options são suportados
    ...,

    // Bloco de extensões do Cloudsupport
    cs: {        

        // Timeout, onde 0 ou undefined desativa o controle de timeout
        timeout: 5000,     
        
        // Mensagem de erro de timeout
        timeoutMessage: "Internet or service unavailable",  

        // Mensagem de erro padrão em caso de falha no fetch
        fetchErrorMessage: "Failed to process the request", 

        // Parâmetros extras a serem adicionados na URL
        extraUrlParams: {                                   
            "key": "value",  
            "key": "value",
        }
    }
}

Importação:

import { Networking } from '@bernardo-dias/react-cloudsupport';

Uso básico:

// Exemplo de configuração do Networking
Networking.setDefaultOptions({
    headers: {
        Authorization: `Bearer ${JWT}`, // Header padrão
    },
    cs: {
        timeout: 2000 // Timeout padrão de 2 segundos
    }
});

// Exemplo de uso do Networking
Networking.fetch("https://api.dominio.com/operacao", {
    cs: {
        timeout: 15000 // Timeout ajustado para 15 segundos nesta requisição
    }
})
.then(...)
.catch(...);

API:

Métodos disponíveis em Networking:

Notas:

O Networking emite o evento de nome "Networking.isFetching" módulo EventEmitter com valor true ou false indicando início e fim global de processamento.

Objects

Módulo que oferece alguns métodos utilitários para a linguagem JavaScript.

Importação:

import { Objects } from '@bernardo-dias/react-cloudsupport';

Uso:

// Exemplo de merge de objetos
const src = {nome: "Bernardo Dias", id: 12345};
const dest = {nome: "Bernardo", ativo: true};

Objects.merge(dest, src); 
// O objeto dest será: {nome: "Bernardo Dias", ativo: true, id: 12345}

// Exemplo de limpeza de objeto
const dto = {nome: "Bernardo Dias", id: 12345, idade: null};

const novoDto = Objects.cleanNullUndefined(dto); 
// O objeto novoDto será: {nome: "Bernardo Dias", id: 12345}

API:

EventEmitter

Módulo que oferece um barramento simples em memória para publicação e escuta de eventos, com escopo de aplicação (SPA).

Importação:

import { EventEmitter } from '@bernardo-dias/react-cloudsupport';

Uso:

// Escuta um canal
EventEmitter.subscribe("CadastroPessoa", 
    dto => console.log("Ocorreu o evento de cadastro da pessoa: ", dto)
);

// Emite evento no canal
EventEmitter.emit("CadastroPessoa", {nome: "Bernardo", ativo: true});

API:

Async

Módulo que oferece alguns complementos para Promise.

Importação:

import { Async } from '@bernardo-dias/react-cloudsupport';

Uso:

// Retorna Promise que executa o fetch, porém demora pelo menos 2 segundos
const p1 = Async.withMinimumDuration(2000, fetch("https://api.dominio.com/operacao"));

// Retorna Promise que executa o fetch, porém lança erro se demorar mais que 2 segundos
const p2 = Async.withTimeout(2000, "Demorou muito", fetch("https://api.dominio.com/operacao"));

API:

Foundation Configurators

AuthProvider

Componente que:

• Habilita a integração OIDC, baseada no framework react-oidc-context mais extensões do Cloudsupport for React.

• Habilita o Hook useAuth(), que dá acesso aos dados do usuário autenticado, bem como à API de eventos e de autenticação.

• Habilita o Hook useAccessToken(), que retorna o Access Token / JWT.

• Habilita a propagação automática de logout todas as abas do browser.

• Habilita o redirect automático de pós login, em que usuário volta para a página desejada.

• Habilita o redirect automático de pós logout, em que o usuário é direcionado para uma página de “sessão encerrada” da aplicação.

Importação:

import { AuthProvider } from '@bernardo-dias/react-cloudsupport';

Uso básico:

function MeuLayout(props) {

    return (
        <ProfileProvider>
            <AuthProvider>
                {props.children}
            </AuthProvider>
        </ProfileProvider>
    );
}

Uso avançado:

function MeuLayout(props) {

    return (
        <ProfileProvider>
            <AuthProvider 
                automaticSilentRenew={true}
                fromProfile={false}
                oidcConfig={{
                    authority: "https://sso.dominio.com/realms/realm-name",
                    client_id: "client-name",
                    redirect_uri: "https://app.dominio.com:3000",
                    post_logout_redirect_uri: "https://app.dominio.com:3000/loggedOut",
                    scope: "openid profile email offline_access"
                }}>
                {props.children}
            </AuthProvider>
        </ProfileProvider>
    );
}

Parâmetros:

Notas:

Caso a aplicação seja baseada no Next.js, considere o uso do componente AuthProvider do grupo Next da arquitetura, que implementa o evento onSigninCallback (remoção dos parâmetros de OIDC após login bem-sucedido) via AppRouter (podendo ser customizado).

Esse componente deve ser declarado dentro de ProfileProvider, seja a versão do grupo Foundation ou do grupo Prime.

Não é necessário declarar AuthProvider e ProfileProvider caso esteja utilizando o EnableCloudsupport.

ProfileProvider

Habilita o Hook useProfile(), que oferece uma solução para configuração de propriedades a aplicação por ambiente (ex: local, teste / homologação e produção).

Um componente visual é apresentado enquanto o profile é carregado. Em caso de falha, o Provider lança erro (que deve ser tratado pelo framework web utilizado). Somente após o carregamento do profile os elementos filhos são exibidos.

Importação:

import { ProfileProvider } from '@bernardo-dias/react-cloudsupport';

Uso básico:

function MeuLayout(props) {

    return (
        <ProfileProvider>
            {props.children}
        </ProfileProvider>
    );
}

Uso avançado:

function MeuLayout(props) {

    return (
        <ProfileProvider
            url="/.well-known/profile.json"
            fetchOptions={{ cache: 'no-store' }}
            Loading={() => <center><h4>Loading profile...</h4></center>}
            reloadCheckIntervalMin={1}>
            {props.children}
        </ProfileProvider>
    );
}

Parâmetros:

Notas:

Em ambiente de desenvolvimento (process.env.NODE_ENV === "development") o profile é verificado em intervalos curtos (10 segundos).

Caso a aplicação seja baseada no PrimeReact, considere o uso do componente ProfileProvider do grupo Prime da arquitetura, que exibe uma UI padrão de carregamento baseada no LoadingBar (podendo ser customizada).

ProcessingProvider

Habilita o Hook useProcessing(), que oferece uma API para sinalização de processamento em andamento.

Importação:

import { ProcessingProvider } from '@bernardo-dias/react-cloudsupport';

Uso:

function MeuLayout(props) {

    return (
        <ProcessingProvider>
            {props.children}
        </ProcessingProvider>
    );
}

Notas:

Não é necessário declarar ProcessingProvider caso esteja utilizando o EnableCloudsupport.

GlobalProvider

Habilita o Hook useGlobal(), que oferece um estado em escopo de aplicação.

Importação:

import { GlobalProvider } from '@bernardo-dias/react-cloudsupport';

Uso:

function MeuLayout(props) {

    return (
        <GlobalProvider>
            {props.children}
        </GlobalProvider>
    );
}

Notas:

Não é necessário declarar GlobalProvider caso esteja utilizando o EnableCloudsupport.

DefaultConfiguredNetworking

Aplica as configurações padrão de Networking.fetch:

• Log de requisições para o ambiente de desenvolvimento (process.env.NODE_ENV === "development")

• Timeout padrão de 5 segundos para requisições webservice.

As configurações são estáticas e terão efeito em toda a aplicação, independentemente da hierarquia de componentes React.

Importação:

import { DefaultConfiguredNetworking } from '@bernardo-dias/react-cloudsupport';

Uso:

function MeuLayout(props) {

    return (
        <>
            <DefaultConfiguredNetworking />
            
            {props.children}
        </>
    );
}

Notas:

Não é necessário declarar DefaultConfiguredNetworking caso esteja utilizando o EnableCloudsupport.

ProfileAwareNetworking

Habilita a inclusão automática do parâmetro de URL appOrigin nas requisições webservice quando utilizada a API Networking.fetch.

O valor padrão de appOrigin tem o formato <nomeAplicacao><separador><versao>.

A versão é obtida da propriedade appVersion do profile.

As configurações são estáticas e terão efeito em toda a aplicação, independentemente da hierarquia de componentes React.

Importação:

import { ProfileAwareNetworking } from '@bernardo-dias/react-cloudsupport';

Uso:

function MeuLayout(props) {

    return (
        <>
            <ProfileAwareNetworking appName="aplicacao-web" versionSeparator=";" />
            
            {props.children}
        </>
    );
}

O valor padrão de versionSeparator é ;.

Notas:

Esse componente deve ser utilizado dentro do contexto de ProfileProvider, seja a versão do grupo Foundation ou do grupo Prime.

Não é necessário declarar ProfileProvider e ProfileAwareNetworking caso esteja utilizando o EnableCloudsupport.

AuthAwareNetworking

Habilita a injeção automática do Access Token OIDC nas requisições webservice quando utilizada a API Networking.fetch.

As configurações são estáticas e terão efeito em toda a aplicação, independentemente da hierarquia de componentes React.

Importação:

import { AuthAwareNetworking } from '@bernardo-dias/react-cloudsupport';

Uso:

function MeuLayout(props) {

    return (
        <>
            <AuthAwareNetworking />
            
            {props.children}
        </>
    );
}

Notas:

Esse componente deve ser utilizado dentro do contexto de AuthProvider, seja a versão do grupo Foundation ou do grupo Next.

Não é necessário declarar AuthProvider e AuthAwareNetworking caso esteja utilizando o EnableCloudsupport.

Prime Hooks

useToast

Retorna uma API para exibição de notificações. Baseia-se no Toast do PrimeReact.

{
    showInfo(title, message, duration), // Notificação de informação
    showWarn(title, message),           // Notificação de aviso
    showError(title, message),          // Notificação de erro
    showError(error),                   // O título do Toast será error.message
    showError(title, error),            // O texto do Toast será error.message

    // API original do Toast do Prime
    show(ToastMessage | ToastMessage[])
}

Importação:

import { useToast } from '@bernardo-dias/react-cloudsupport/prime';

Uso:

function MeuComponente() {

    const toast = useToast();

    React.useEffect(() => {
        carregar()
        .then(() => toast.showInfo("Operação executada com sucesso!"))
        .catch(toast.showError);
    }, []);
    // ...

API:

Notas:

Esse componente deve ser utilizado dentro do contexto de ToastProvider.

Não é necessário declarar ToastProvider caso esteja utilizando o EnableCloudsupport.

Prime UI

AuthRequired

Estende o componente AuthRequired do grupo Foundation, em que os valores padrões dos seus parâmetros passam a ser:

• Loading: Um LoadingBar.

• Failed: Um MessageBlock com a mensagem “There was a problem communicating with the identity provider.”

Importação:

import { AuthRequired } from '@bernardo-dias/react-cloudsupport/prime';

Uso:

function MeuLayout(props) {

    return (
        <AuthRequired>
            <SessionExpiredBanner />
            
            {props.children}
        </AuthRequired>
    );
}

Sugere-se a inclusão do SessionExpiredBanner, que exibe aviso de sessão expirada.

Notas:

Esse Hook deve ser utilizado dentro do contexto de AuthProvider, seja a versão do grupo Foundation ou do grupo Next.

Não é necessário declarar AuthProvider caso esteja utilizando o EnableCloudsupport.

Caso a aplicação não seja baseada no PrimeReact, considere o uso do componente AuthRequired do grupo Foundation da arquitetura, que implementa elementos padrões de UI baseados em HTML (podendo ser customizados).

Box

Exibe o conteúdo com margens (paddings).

Classe de estilo: cs-box.

Importação:

import { Box } from '@bernardo-dias/react-cloudsupport/prime';

Uso:

function MeuComponente() {

    return (
        <Box>
            Conteúdo aqui
        </Box>
        
        // ...
    )

Notas:

O Cloudsupport for React não pretende ser uma suite de componentes de UI. São oferecidos apenas componentes facilitadores básicos.

ContextBar

Estende o Toolbar do PrimeReact incluindo suporte a um título (parâmetro title).

Classe de estilo no Toolbar: cs-context-bar.

Classe de estilo no título: cs-context-bar-title.

Importação:

import { ContextBar } from '@bernardo-dias/react-cloudsupport/prime';

Uso:

function MeuComponente() {

    return (
        <ContextBar 
            title="Título da página"
            start={...} 
            end={...} />
        
        // ...
    )

Notas:

O Cloudsupport for React não pretende ser uma suite de componentes de UI. São oferecidos apenas componentes facilitadores básicos.

ErrorMessage

Exibe uma mensagem centralizada via componente Message do PrimeReact, com nível de severidade de erro.

Se o parâmetro text for Falsy, o componente não é renderizado.

Classe de estilo no container: cs-error-message.

Importação:

import { ErrorMessage } from '@bernardo-dias/react-cloudsupport/prime';

Uso:

function MeuComponente() {

    return (
        <ErrorMessage text="Ocorreu um problema" />

        // ...
    )

Notas:

O Cloudsupport for React não pretende ser uma suite de componentes de UI. São oferecidos apenas componentes facilitadores básicos.

Field

Exibe uma etiqueta para o conteúdo do componente. O Field pode ser utilizado, por exemplo, para tabular dados na forma campo/valor ou alinhar campos de formulários.

Suporta responsividade: em desktops o conteúdo é exibido à direita da etiqueta, porém celulares e tablets ele é exibido abaixo da etiqueta (efeito stack).

Parâmetros:

• label: Etiqueta.

• labelWidth: Largura numérica da etiqueta, em unidade rem. Por padrão 12. Não surte efeito quando em modo responsivo (celulares e tablets).

• errorMessage: Mensagem exibida abaixo da etiqueta, em fonte small.

• responsive: Indica se a responsividade está ativada. Por padrão true.

Classe de estilo no container do Field: cs-field.

Classe de estilo na etiqueta: cs-field-label.

Classe de estilo no container do conteúdo: cs-field-content.

Classe de estilo na mensagem de erro: cs-field-error.

Importação:

import { Field } from '@bernardo-dias/react-cloudsupport/prime';

Uso:

function MeuComponente() {

    return (
        <Field label="Informe seu nome: *" 
               errorMessage="Campo obrigatório">
            <InputText ... />
        </Field>

        // ...
    )

Notas:

O Cloudsupport for React não pretende ser uma suite de componentes de UI. São oferecidos apenas componentes facilitadores básicos.

InlineField

Exibe uma etiqueta para o conteúdo do componente, que é apresentado à direita da etiqueta, de maneira inline. Por ser utilizado para alinhar campos de formulários horizontais, como filtros de pesquisa.

Parâmetros:

• label: Etiqueta.

Classe de estilo: cs-inline-field.

Importação:

import { InlineField } from '@bernardo-dias/react-cloudsupport/prime';

Uso:

function MeuComponente() {

    return (
        <InlineField label="Busca:">
            <InputText ... />
        </InlineField>

        // ...
    )

Notas:

O Cloudsupport for React não pretende ser uma suite de componentes de UI. São oferecidos apenas componentes facilitadores básicos.

LoadingBar

Exibe após determinado delay (aprox. 1 segundo) um ProgressBar do PrimeReact em modo infinito (“indeterminate”).

Classe de estilo: cs-loading-bar.

Importação:

import { LoadingBar } from '@bernardo-dias/react-cloudsupport/prime';

Uso:

function MeuComponente() {

    return (
        <LoadingBar />

        // ...
    )

Notas:

O Cloudsupport for React não pretende ser uma suite de componentes de UI. São oferecidos apenas componentes facilitadores básicos.

LoggedOut

Exibe o conteúdo do componente caso o AccessToken OIDC tenha expirado.

Se não houver conteúdo, é exibida uma UI padrão contendo um MessageBlock.

Parâmetros aplicáveis à UI padrão:

• message: Texto da mensagem. Por padrão "Your session has been closed".

• label: Título do botão para iniciar a autenticação. Por padrão "Press to enter".

Importação:

import { LoggedOut } from '@bernardo-dias/react-cloudsupport/prime';

Uso:

function MeuComponente() {

    return (
        <LoggedOut label="Entrar" message="Sua sessão foi encerrada." />
    )

Notas:

Esse Hook deve ser utilizado dentro do contexto de AuthProvider, seja a versão do grupo Foundation ou do grupo Next.

Não é necessário declarar AuthProvider caso esteja utilizando o EnableCloudsupport.

O Cloudsupport for React não pretende ser uma suite de componentes de UI. São oferecidos apenas componentes facilitadores básicos.

MenuButton

Exibe um Button do PrimeReact em modo text e small com ícone fa-bars, indicado para uso em células de tabelas que abrem menu de contexto.

Importação:

import { MenuButton } from '@bernardo-dias/react-cloudsupport/prime';

Uso:

function MeuComponente() {

    return (
        <DataTable>
            <Column body={item => <MenuButton onClick={...} />} />
            
            // ...
        </DataTable>

        // ...
    )

Notas:

O Cloudsupport for React não pretende ser uma suite de componentes de UI. São oferecidos apenas componentes facilitadores básicos.

MessageBlock

Exibe uma mensagem centralizada e que preenche todo o container, horizontal e verticalmente. É baseado no PrimeFlex apenas.

Parâmetros:

• icon: Classe de estilo do ícone a ser exibido (ex: "fa fa-triangle-exclamation").

• iconClass: Classe adicional de estilo do ícone, por padrão "text-primary".

• text: Texto da mensagem.

• end: Componente React a ser exibido abaixo do texto.

Classe de estilo: cs-message-box.

Importação:

import { MessageBlock } from '@bernardo-dias/react-cloudsupport/prime';

Uso:

function MeuComponente() {

    return (
        <MessageBlock icon='fa fa-triangle-exclamation' 
                      iconClass='text-orange-500' 
                      text="Esse cadastro está em uso, por favor considere outro." />

        // ...
    )

Notas:

O Cloudsupport for React não pretende ser uma suite de componentes de UI. São oferecidos apenas componentes facilitadores básicos.

ProcessingIndicator

Estende o componente ProcessingIndicator do grupo Foundation, em que a UI que indica o carregamento do profile passa a ser, por padrão, um LoadingBar.

Classe de estilo no LoadingBar: cs-processing-indicator.

Importação:

import { ProcessingIndicator } from '@bernardo-dias/react-cloudsupport/prime';

Uso:

function MeuLayout(props) {

    return (
        <>
            <ProcessingIndicator />
            
            {props.children}
        </>
    );
}

Notas:

Esse componente deve ser utilizado dentro do contexto de ProcessingProvider.

Não é necessário declarar ProcessingIndicator e ProcessingProvider caso esteja utilizando o EnableCloudsupport.

Considere o uso do componente ProcessingIndicator do grupo Foundation da arquitetura, que exibe uma UI padrão de carregamento baseada no nprogress.js (podendo ser customizada).

O Cloudsupport for React não pretende ser uma suite de componentes de UI. São oferecidos apenas componentes facilitadores básicos.

RefreshingIcon

Exibe um ícone animado de refreshing que permanece vísivel por um tempo mínimo (aprox. 0,5 segundos).

Útil em cenários onde a aplicação deseja que o usuário perceba que ocorreu um processamento, ainda que tenha sido muito rápido. Por ser utilizado, por exemplo, em botões que atualizam dados presentes na página.

É baseado no PrimeFlex apenas.

Para exibir ou ocultar o ícone, utilize a API disponibilizada pelo componente:

• show(): Exibe o ícone.

• hide(): Oculta o ícone.

Classe de estilo: cs-refreshing-icon.

Importação:

import { RefreshingIcon } from '@bernardo-dias/react-cloudsupport/prime';

Uso:

function MeuComponente() {

    const refreshing = React.useRef(); // Bind do componente

    const atualizar = () => {
        refreshing.current.show(); // Sinaliza início

        pesquisarDados()
        .then(...)
        .catch(...)
        .finally(refreshing.current.hide); // Sinaliza fim
    }

    return (
        <RefreshingIcon ref={refreshing} />

        // ...
    );

Notas:

O Cloudsupport for React não pretende ser uma suite de componentes de UI. São oferecidos apenas componentes facilitadores básicos.

ReloadBanner

Exibe um banner de aviso de que a aplicação estaria desatualizada. O texto do banner é um Button que permite ao usuário reiniciar a aplicação (tecnicamente um refresh de página no browser).

Este componente monitora o evento que indica que há profile novo da aplicação via integração com useProfileStatus.

Parâmetros:

• actionLabel: Texto do aviso, por padrão “New version available! Click here to update”

• confirmText: Texto de confirmação ao acionar o botão, por padrão “This application will be restarted. Complete your activity before continuing.”

Classe de estilo: cs-reload-banner.

Importação:

import { ReloadBanner } from '@bernardo-dias/react-cloudsupport/prime';

Uso:

function MeuLayout(props) {

    return (
        <>
            <ReloadBanner />
            
            {props.children}
        </>
    );
}

Notas:

Esse Hook deve ser utilizado dentro do contexto de ProfileProvider, seja a versão do grupo Foundation ou do grupo Prime.

Não é necessário declarar ProfileProvider e ReloadBanner caso esteja utilizando o EnableCloudsupport.

O Cloudsupport for React não pretende ser uma suite de componentes de UI. São oferecidos apenas componentes facilitadores básicos.

RowExpansionBox

Exibe o conteúdo com margens (paddings). Indicado para uso dentro de RowExpansion de DataTable. O tema padrão inclui uma leve sombra no topo e cabeçalho.

Classe de estilo: cs-row-expansion-box.

Importação:

import { RowExpansionBox } from '@bernardo-dias/react-cloudsupport/prime';

Uso:

function MeuComponente() {

    return (
        <DataTable rowExpansionTemplate={() => (
            <RowExpansionBox>
                Conteúdo da expansão de linha
            </RowExpansionBox>
        )}>

            // ...
        </DataTable>

        // ...
    )

Notas:

O Cloudsupport for React não pretende ser uma suite de componentes de UI. São oferecidos apenas componentes facilitadores básicos.

SessionExpiredBanner

Exibe um banner de aviso de sessão expirada. O texto do banner é um Button, que permite ao usuário autenticar novamente. Ao acionar o botão, o fluxo é redirecionado para o SSO do provedor (IdP) OIDC.

Este componente monitora o evento de expiração de Access Token OIDC pela integração com useAuth.

Parâmetros:

• actionLabel: Texto do aviso, por padrão “Session has expired. Please log in to continue.”

• confirmText: Texto de confirmação ao acionar o botão, por padrão “This application will be restarted. Confirm to continue.”

Classe de estilo: cs-session-expired-banner.

Importação:

import { SessionExpiredBanner } from '@bernardo-dias/react-cloudsupport/prime';

Uso:

function MeuLayout(props) {

    return (
        <>
            <SessionExpiredBanner />
            
            {props.children}
        </>
    );
}

Notas:

Esse Hook deve ser utilizado dentro do contexto de AuthProvider, seja a versão do grupo Foundation ou do grupo Next.

Não é necessário declarar AuthProvider caso esteja utilizando o EnableCloudsupport.

O Cloudsupport for React não pretende ser uma suite de componentes de UI. São oferecidos apenas componentes facilitadores básicos.

Prime Configurators

ProfileProvider

Estende o componente ProfileProvider do grupo Foundation, em que a UI que indica o carregamento do profile passa a ser, por padrão, o LoadingBar.

Importação:

import { ProfileProvider } from '@bernardo-dias/react-cloudsupport/prime';

Uso:

function MeuLayout(props) {

    return (
        <ProfileProvider>
            {props.children}
        </ProfileProvider>
    );
}

Notas:

Não é necessário declarar ProfileProvider caso esteja utilizando o EnableCloudsupport.

Caso a aplicação não seja baseada no PrimeReact, considere o uso do componente ProfileProvider do grupo Foundation da arquitetura, que implementa elementos padrões de UI baseados em HTML (podendo ser customizados).

ToastProvider

Habilita o Hook useToast(), que oferece uma API para exibição de notificações baseadas no Toast do PrimeReact.

Importação:

import { ToastProvider } from '@bernardo-dias/react-cloudsupport/prime';

Uso:

function MeuLayout(props) {

    return (
        <ToastProvider>
            {props.children}
        </ToastProvider>
    );
}

Notas:

Não é necessário declarar ToastProvider caso esteja utilizando o EnableCloudsupport.

Next

getProfile

Função Router para Next.js que permite servir um profile em formato JSON.

Essa função faz o merge do arquivo public/profile.json com o conteúdo da variável de ambiente CLOUDSUPPORT_PROFILE do sistema operacional.

A variável de ambiente, se declarada, deve possui JSON como valor.

Para que a função seja dinâmica (processada em tempo de execução) é preciso exportá-la como GET e POST no route.js.

Importação:

import { getProfile } from '@bernardo-dias/react-cloudsupport/next/server';

Uso:

Arquivo app/services/getProfile/route.js:

export { getProfile as GET, getProfile as POST } from '@bernardo-dias/react-cloudsupport/next/server';

Exemplo de trecho do arquivo next.config.js, caso deseje mapear, por exemplo, o endpoint no endereço padrão /.well-known/profile.json:

const nextConfig = {

    async rewrites() {
        return [
            {
                source: '/.well-known/profile.json',
                destination: '/services/getProfile',
            },
        ]
    }

    // ...
}
module.exports = nextConfig;

AuthProvider

Estende o componente AuthProvider do grupo Foundation, em que:

1. O atributo onSigninCallback do parâmetro oidcConfig, que trata o redirect do usuário após o login bem-sucedido no SSO do OIDC, implementa a remoção dos parâmetros de OIDC (state, session_state e code) via AppRouter, o que aumenta o desempenho por evitar o carregamento completo da aplicação React.

2. O atributo onRemoveUser do parâmetro oidcConfig, que trata o redirect do usuário após o logout bem-sucedidoC, implementa a mudança de URL para post_logout_redirect_uri via AppRouter, o que aumenta o desempenho por evitar o carregamento completo da aplicação React.

Importação:

import { getProfile } from '@bernardo-dias/react-cloudsupport/next/client';

Uso:

function MeuLayout(props) {

    return (
        <ProfileProvider>
            <AuthProvider>
                {props.children}
            </AuthProvider>
        </ProfileProvider>
    );
}

Notas:

Esse componente deve ser declarado dentro de ProfileProvider, seja a versão do grupo Foundation ou do grupo Prime.

Não é necessário declarar AuthProvider e ProfileProvider caso esteja utilizando o EnableCloudsupport.

Caso a aplicação não seja baseada no Next.js, considere o uso do componente AuthProvider do grupo Foundation da arquitetura, que implementa o evento onSigninCallback (remoção dos parâmetros de OIDC após login bem-sucedido) via window.history.replaceState (podendo ser customizado).

Mixed

EnableCloudsupport

Ativa o Cloudsupport na aplicação.

Sugere-se que EnableCloudsupport seja declarado no layout raiz da aplicação, para que o OIDC possa funcionar em qualquer path de URL.

O EnableCloudsupport faz a inclusão de Providers, Configurators e componentes de UI de maneira recomendada e supondo ambiente com Next.js e PrimeReact.

Importação:

import { EnableCloudsupport } from '@bernardo-dias/react-cloudsupport/mixed';

Uso básico:

function MeuLayout(props) {

    return (
        <EnableCloudsupport>
            {props.children}
        </EnableCloudsupport>
    );
}

Uso avançado:

const options = {
    networking: {
        appName: "atendimento-web"
    },
    reloadBanner: {
        actionLabel: "Nova versão disponível! Clique aqui para atualizar",
        confirmText: "Esta aplicação será reiniciada. Conclua sua atividade antes de continuar."
    }
};

function MeuLayout(props) {

    return (
        <EnableCloudsupport options={options}>
            {props.children}
        </EnableCloudsupport>
    );
}

Parâmetros:

O parâmetro único options é um objeto cujos atributos serão repassados para os elementos internos, conforme:

• options.networking repassado para o configurador ProfileAwareNetworking.

• options.reloadBanner repassado para o componente de UI ReloadBanner.

• options.profile repassado para o Provider ProfileProvider do grupo Prime e para o ProfileProvider do grupo Foundation (por herança).

• options.auth repassado para o Provider AuthProvider do grupo Next e para o AuthProvider do grupo Foundation (por herança).

Consulte a documentação específica de cada elemento mencionado acima. Todas as configurações de cada elemento são suportadas.

Notas:

Consulte a seção de Resources para incluir os assets indicados.

A alternativa ao EnableCloudsupport seria a declaração explícita dos Providers, Configurators e componentes de UI desejados. O EnableCloudsupport faz a seguinte composição:

<GlobalProvider>
    <ProfileProvider {...options.profile}>
        <AuthProvider {...options.auth}>
            <ToastProvider>
                <ProcessingProvider>

                    <DefaultConfiguredNetworking />
                    <ProfileAwareNetworking {...options.networking} />                    
                    <AuthAwareNetworking />                               
                    <ReloadBanner {...options.reloadBanner} />
                    <ProcessingIndicator />

                    {children}                                
                    
                </ProcessingProvider> 
            </ToastProvider>    
        </AuthProvider>      
    </ProfileProvider>  
</GlobalProvider> 

AuthProvider é importado do grupo Next.

ProfileProvider, ToastProvider e ReloadBanner são importados do grupo Prime.

Demais componentes são do grupo Foundation.

NextErrorBoundary

Página de erro para Next.js que exibe o erro dentro de um componente MessageBlock.

Uso:

Em arquivo error.js do Next.js:

'use client'
import { NextErrorBoundary } from '@bernardo-dias/react-cloudsupport/mixed';

export default NextErrorBoundary;

Resources

Styles

Estilos CSS indicados para inclusão no layout raiz da aplicação:

import '@bernardo-dias/react-cloudsupport/resources/foundation/normalize.css';
// (incluir aqui imports do Prime React / Icons / Flex)
import '@bernardo-dias/react-cloudsupport/resources/foundation/theme.css';
import '@bernardo-dias/react-cloudsupport/resources/prime/theme.css';
import '@bernardo-dias/react-cloudsupport/resources/prime/tweaks.css';

• foundation/normalize: Versão do necolas/normalize.css com pequeno ajuste para compatibilidade com PrimeReact.

• foundation/theme.css: CSS relativo a componentes de UI do grupo Foundation da arquitetura.

• prime/theme.css: CSS relativo a componentes de UI do grupo Prime da arquitetura.

• prime/tweaks.css: Refinamentos no tema original do PrimeReact.