@pagopa/selfcare-common-frontend v1.34.16

SelfCare's common components & features

This library contains utilities, components, decorators, custom hooks and features built for the selfcare project.

Localization

This libray has been built using react-i18next and string inside of it are also localizated. Actually the library contains the only "it" translation. The translations for the keys of the common components can be overwritten using the resources used during configuration. In order to configure it call the method configureI18n of the module locale/locale-utils which accept the following parameters: | Param | Type | Mandatory | Description | |-------|------|-----------|-------------| | resources | Y | { lang: string: any } | a map containing the language as key and the map containing the key/translated messages as value. These values overwrite common's component keys if desired | | defaultLanguage | N | string | as default it language |

Configuration

In order to use these components it's necessary to set the following keys of the CONFIG object imported from /config/env as first things inside the application:

Components

Header

SelfCare Header component

Footer

SelfCare Footer component

CustomAvatar

Avatar to use to load Organization logo

CustomPagination

Selfcare custom table available pages component

FilterModal

Modal used to show a list of values from which to choose a single value

FilterModalConfig fields: | Field | Type | Mandatory | Description | |-------|------|-----------|-------------| | data | Array<T> | Y | The list of values between to which choose | | getLabel | (e: T) => string | Y | A function that will select the label to show | | getValue | (e: T) => string | Y | A function that will select the value to return when selecting an item | | onFilterChange | (v: V) => void | Y | The function invoked when selecting a value |

SessionModal

Selfcare's popup

TitleBox

Selfcare's page title

Toast

Selfcare's toast

ToastWrapper

To stack multiple Toast component. Each Toast should have the prop wrapped setted to true

Ending Page

Selfcare's ending page

NavigationBar

Selfcare's navigation bar

NavigationPath's fields: | field | Type | Mandatory | Description | |------|------|-----------|-------------| | description | string | Y | The text displayed | | onClick | () => void | N | If defined, it will represent the function executed when clicking on the element. Moreover it will be displayed in bold |

LoadingOverlayComponent

A component which render an overlay loading

NavigationPath's fields: | field | Type | Mandatory | Description | |------|------|-----------|-------------| | description | string | Y | The text displayed | | onClick | () => void | N | If defined, it will represent the function executed when clicking on the element. Moreover it will be displayed in bold |

Utilities

api-utils

onRedirectToLogin: (store: EnhancedStore) => void

To show an error popup to inform of the not valid session

buildFetchApi = (timeoutMs: number = 300000) => fetch

Return the implementation of fetch configured with a timeout

extractResponse <R>(response: t.Validation<TypeofApiResponse<any>>, successHttpStatus: number, onRedirectToLogin: () => void, notValidTokenHttpStatus: number | null = 401, notAuthorizedTokenHttpStatus: number | null = 403, emptyResponseHttpStatus: number | null = 404): Promise<R>

Extract the response of a @pagopa/openapi-codegen-ts generated client rest invocation having status code successHttpStatus. If notValidTokenHttpStatus is not null and the returned status is equal to notValidTokenHttpStatus, it will call the onRedirectToLogin function and will schedule the redirect towards logout path. If notAuthorizedTokenHttpStatus is not null and the returned status is equal to notAuthorizedTokenHttpStatus, it will throw an Error with message "Operation not allowed". If emptyResponseHttpStatus is not null and the returned status is equal to emptyResponseHttpStatus, it will return a promise that resolve to null value. Other statuses will return will throw a generic error.

constants

roleLabels: { key in UserRole: { shortLabel: string; longLabel: string } }

The short and long labels used for the roles of selfcare's projects

routes-utils

resolvePathVariables: (path: string, pathVariables: { key: string: string }): string

It will resolve the path variables in path using the provided map

storage-utils

storageDelete: (key: string, local?: boolean) => void

It will delete a key from the session storage. If local is true, it will use the local session storage instead.

storageWrite: (key: string, value: StorageValue, type: StorageValueType, local?: boolean) => void

It will store a key/value pair in the session storage. If local is true, it will use the local session storage instead.

storageRead: (key: string, type: StorageValueType, local?: boolean) => void

It will read a key from the session storage. If local is true, it will use the local session storage instead.

storageOpsBuilder(key: string, type: StorageValueType, local: boolean): StorageOps

It will build an object containing a complete set of operation to perform on the same key.

utils

formatDateAsLongString: (date: Date) => string

It will return a string representing the provided date in the italian format gg mmm aaaa

fixSwagger20ArraySchemaDef.js

An utility script to use when generating the stub through @pagopa/openapi-codegen-ts in order to handle the REST api whose operations returns an array of objects

storage

storageTokenOps

An object containing a complete set of operation on the storage regarding the key used to store in the storage the loggedUser token in selfcare projects.

storageUserOps

An object containing a complete set of operation on the storage regarding the key used to store in the storage the loggedUser in selfcare projects.

parseJwt

Decode and then convert the jwt into a JWTUser object

isExpiredToken

Determines whether the token has expired

Decorators

withLogin

This feature is based on react-redux library and require to register the reducer build in userSlice into the application's redux store. This decorator has to be applied to components whose acces require an active session. Accessing to the components decorated with it without a session will brought to the login page. It's possible to modify the login path changing the value in CONFIG.URL_FE.LOGIN inside the index.tsx file

withRetrievedValue

Decorator to retrieve a value and serve it once ready to the decorated component, moreover it will provide the decorated component a function to re-execute the retrieve method.

Using it together with useReduxCachedValue will allow to build a component which will use centralized and cached data (the reload function in this case will call again the function that will retrieve cached data).

See withRetrievedValue.test.tsx file for an example.

Given the following type parameters:

• ENTITY_TYPE extends Record<string, any>,
• PROP_NAME extends string,
• PROPS extends Record<PROP_NAME, ENTITY_TYPE>

The arguments to provide to the decorator are the following:

Custom Hooks

useFakePagination

Custom hook used to simulate paginated resources when the external service doesn't implement it, caching values when filter doesn't change and serving them a page at time. Cached values are stored using useRef, so they are local to the component using this hook. The sorting actually is applied using string representation

useReduxCachedValue

See useReduxCachedValueParametricRetrieverTranscoded when there is not RETRIEVER_ARGS and RETRIEVED_VALUE === RETRIEVER_ARGS

useReduxCachedValueParametricRetriever

See useReduxCachedValueParametricRetrieverTranscoded when RETRIEVED_VALUE === RETRIEVER_ARGS

useReduxCachedValueTranscoded

See useReduxCachedValueParametricRetrieverTranscoded when there is not RETRIEVER_ARGS

useReduxCachedValueParametricRetrieverTranscoded

It will return a method that will call the retrieverService only when there are not storing values, or a condition on them is not more verified. See useReduxCachedValue.test.tsx file for an example.

Given the following type parametes:

• RETRIEVED_VALUE the type desired
• STORED_VALUE the type stored

The arguments to provide to the custom hook are the following:

Features

LoadingOverlay

This feature is based on react-redux library and require to register the reducer build in appStateSlice into the application's redux store. It allows to draw a loader when an async task to wait is running.

To use this feature you have to put LoadingOverlay in your App as a child of a redux Provider component. In order to register the start of an async task you have to use the custom hook useLoading passing the id of the task to await, which will return a setter function used to start and end the loading behavior.

ErrorBoundary

This feature is based on react-redux library and require to register the reducer build in appStateSlice into the application's redux store. It allows to dispatch errors in order to display a warning or the error page to the user. Errors dispatched will be notified using errorService

To use this feature you have to put ErrorBOundary in your App as a child of a redux Provider component. In order to dispatch an error you have to use the custom hook useErrorDispatcher which will return a fuction to be used to dispatch the error.

The error to be submitted has type AppError which has the following fields:

The error will be notified as a GENERIC_ERROR through the analytcs feature

UserNotifyHandle

This feature is based on react-redux library and require to register the reducer build in appStateSlice into the application's redux store. It allows to dispatch User Notifies in order to display a pop up or a toast notification.

To use this feature you have to put UserNotifyHandle in your App as a child of a redux Provider component. In order to dispatch a User Notify, you have to use the custom hook useUserNotify which will return a fuction to be used to dispatch the User Notify.

The user notify to be submitted has type UserNotify which has the following fields:

UnloadEventHandler

This feature is based on react-redux library and require to register the reducer build in appStateSlice into the application's redux store. It allows to intercept when the user try to exit from the current page and ask him if he wants to continue or not.

To use this feature you have to put UnloadEventHandler in your App as a child of a redux Provider component. In order to use this feature you have to use the custom hook useUnloadEventInterceptor, which will return an object having the following keys: 1. registerUnloadEvent: an arrow function which takes two optional parameters to customize the title and the description of the pop-up opened when invoking the exitAction function (see below) and enable the functionality. 2. unregisterUnloadEvent: an arrow function to call in order to disable this functionality.

If you wont to enable immediately this functionality when invoking the custom hook you can use the hook useUnloadEventInterceptorAndActivate, which will enable the functionality and will disable it when unmounting the component.

In order to show a custom pop-up when the user trigger an exit action you have to use the custom hook useUnloadEventOnExit which will return an arrow function to invoke instead of the exit action passing to it the exitAction itself.

When the exitAction is the Logout you can use the custom hook useUnloadEventLogout which is the customization of the useUnloadEventOnExit using the logout as an exit action.

Analytics

This feature allow to track the application events through an analytics tool. The actual version of the library make use of mixpanel tool to handle the tracking.

In order to start the analytics you have to call the initAnalytics method imported from the service/analyticsService module, otherwise this feature will be ignored

This feature can be configured with the following keys of the CONFIG object (each key has the ANALYTCS. prefix):

In order track an event (once the initAnalytics method has been invoked) you have to call the trackEvent(event_name: string, properties?: any, callback?: () => void)=> void method where:

• event_name: the name of the event
• properties: the additional payload sent with the event
• callback: an action taken when the track has completed (If the action taken immediately after the track is an exit action from the application, it's better to use this callback to perform the exit, in order to give to mixPanel the time to send the event)

Consent management

This feature allows the automatic enabling of the analytics feature only when the user accept to send that data.

The tool used is OneTrust, and in order to be able to use it, you have: 1. to put the script tag obtained when registering to the service inside the head section of your index.html file. 2. import the consentManagementConfigure.ts script inside your index.ts file (after the configuration of the common library)