Users({ data.totalElements }) < /h2>
< ul >
{
data.content.map(user =>

{ user.name } < /li>)}
< /ul>
< /div>
);
}
`

#### API Context Provider

The ApiProvider component makes the API client available throughout your application.

`typescript
import { ApiProvider, createApiClient } from 'pagamio-frontend-commons-lib';

// Create API client
const apiClient = createApiClient({
baseURL: 'https://api.example.com',
tokenManager: tokenManager,
});

// Wrap your application with the provider
function App() {
return (



);
}
`

#### API Mutations

The API module provides hooks for performing mutations (create, update, delete operations).

`typescript
import { useApiMutation, useApiSWRWithMutation } from 'pagamio-frontend-commons-lib';

// Using the mutation hook
function CreateUserForm() {
const mutation = useApiMutation();

const handleSubmit = async (userData) => {
try {
const newUser = await mutation.post('/users', userData);
alert(User ${newUser.name} created successfully!);
} catch (error) {
console.error('Failed to create user:', error);
}
};

return

{/ form fields / } < /form>;
}

// Combined SWR and mutation hook
function EditUserProfile({ userId }) {
const { data, error, isLoading, mutate } = useApiSWRWithMutation(
/users/${userId}
);

const handleUpdate = async (updatedData) => {
try {
await mutate.patch(/users/${userId}, updatedData);
alert('Profile updated successfully!');
} catch (error) {
console.error('Failed to update profile:', error);
}
};

if (isLoading) return

Loading
...


;

return onSubmit = { handleUpdate }
/>;
}
`

$3

The API module supports mocking API requests for testing and development.

`typescript
import { ApiProvider, createApiClient, MockConfig } from 'pagamio-frontend-commons-lib';

// Define mock configurations
const mockConfig: MockConfig[] = [
{
path: '/users',
method: 'GET',
response: [
{ id: 1, name: 'John Doe', email: 'john@example.com' },
{ id: 2, name: 'Jane Smith', email: 'jane@example.com' }
]
},
{
path: '/users',
method: 'POST',
params: { name: 'Alice', email: 'alice@example.com' },
response: { id: 3, name: 'Alice', email: 'alice@example.com' }
}
];

// Enable mocking in the provider
function TestApp() {
return (
apiClient = { apiClient }
mocked = { true }
mockConfig = { mockConfig } >


)
;
}
`

$3

The API client integrates with the token manager for authentication.

`typescript
import { createApiClient, createTokenManager } from 'pagamio-frontend-commons-lib';

// Create a token manager
const tokenManager = createTokenManager({
baseUrl: 'https://api.example.com',
refreshEndpoint: '/auth/refresh',
cookieOptions: {
secure: true,
sameSite: 'strict'
}
});

// Create API client with authentication
const apiClient = createApiClient({
baseURL: 'https://api.example.com',
tokenManager: tokenManager,
onUnauthorized: () => {
// Handle unauthorized access (e.g., redirect to login)
window.location.href = '/login';
}
});
`

$3

#### Custom Request/Response Handling

`typescript
const apiClient = createApiClient({
baseURL: 'https://api.example.com',
tokenManager: tokenManager,
onRequest: async (config) => {
// Add custom headers or modify request configuration
config.headers = {
...config.headers,
'X-Custom-Header': 'CustomValue'
};
return config;
},
onResponse: async (response, data) => {
// Transform or process response data
return data.results || data;
},
onError: async (error) => {
// Log or handle errors
console.error(API Error (${error.status}):, error.message);
}
});
`

#### Pagination and Filtering

`typescript
// Custom pagination params
const { data } = useApiSWR('/users', {
params: {
page: 0,
size: 25,
sortBy: 'createdAt',
sortDir: 'desc',
name: 'John'
}
});
`

$3

The API module is fully typed with TypeScript, providing type safety and better developer experience.

`typescript
// Define your auth configuration
interface MyAuthConfig extends CustomAuthConfig {
UserInfo: {
id: string;
username: string;
email: string;
roles: string[];
};
TokenInfo: {
token: string;
expiresIn: number;
};
Credentials: {
username: string;
password: string;
};
}

// Use your custom types with the API client
const apiClient = createApiClient({
baseURL: 'https://api.example.com',
tokenManager: tokenManager
});

// Type-safe API calls
interface Product {
id: string;
name: string;
price: number;
}

const { data: products } = useApiSWR('/products');
`

$3

1. Centralize API Configuration: Create a central API configuration file that sets up the API client and exports
hooks for use throughout your application.

2. Use TypeScript: Leverage TypeScript definitions for type-safe API calls and better developer experience.

3. Handle Loading and Error States: Always handle loading and error states in your components when using API hooks.

4. Implement Proper Error Handling: Configure error handling with the onError callback and handle errors
appropriately in your UI.

5. Use Mocking for Development: Enable mocking during development to work without a backend or to test specific
scenarios.

6. Optimize Cache Invalidation: Use SWR's mutate function to keep your data fresh and update the UI after
mutations.

7. Set Appropriate Timeouts: Configure request timeouts based on the expected response time of your API endpoints.

:globe_with_meridians: Translations

The library provides a complete translation system that supports internationalization for your applications.

$3

The library comes with built-in support for the following languages:

- English (en)
- Spanish (es)
- French (fr)
- Portuguese (pt)

$3

Follow these steps to implement translations in your project:

#### 1. Setup Translation Provider

Wrap your application with the TranslationProvider:

`tsx
import { TranslationProvider } from 'pagamio-frontend-commons-lib';

function App() {
return (
defaultLocale="en"
loadPath="/translations" // Path to your translation files
>


);
}
`

Alternatively, if you're using the AppLayout component:

`tsx
import { AppLayout } from 'pagamio-frontend-commons-lib';

function App() {
return (
// other props...
enableTranslations={true}
translationConfig={{
defaultLocale: 'en',
loadPath: '/translations',
}}
>
{/ Your content /}

);
}
`

#### 2. Create Translation Files

Create JSON files for each language in your project:

`
/public
/translations
en.json
es.json
fr.json
pt.json
`

Example of a translation file (en.json):

`json
{
"common": {
"save": "Save",
"cancel": "Cancel",
"submit": "Submit"
},
"auth": {
"login": "Login",
"register": "Register",
"forgotPassword": "Forgot Password?"
}
}
`

#### 3. Add i18next-scanner Config

Create an i18next-scanner.config.js in your project root:

`js
module.exports = {
input: ['src//.{js,jsx,ts,tsx}', '!src//.test.{js,jsx,ts,tsx}', '!/node_modules/'],
output: './public/translations/',
options: {
debug: true,
func: {
list: ['t', 'tLib'],
extensions: ['.js', '.jsx', '.ts', '.tsx'],
},
lngs: ['en', 'es', 'fr', 'pt'],
defaultLng: 'en',
defaultValue: function(lng, ns, key) {
return key;
},
resource: {
loadPath: 'public/translations/{{lng}}.json',
savePath: '{{lng}}.json',
jsonIndent: 2,
lineEnding: '\n',
},
removeUnusedKeys: false,
nsSeparator: false,
keySeparator: '.',
},
};
`

#### 4. Add Extraction Script to package.json

`json
"scripts": {
"extract-translations": "i18next-scanner --config i18next-scanner.config.js 'src/*/.{js,jsx,ts,tsx}'"
}
`

#### 5. Install Required Dependencies

Install the necessary dev dependencies:

`bash
yarn add -D i18next-scanner
`

Or if you're using npm:

`bash
npm install --save-dev i18next-scanner
`

#### 6. Use Translations in Components

`tsx
import { useTranslation } from 'pagamio-frontend-commons-lib';

function YourComponent() {
const { t } = useTranslation();

return (


{t('common.title', 'Default Title')}

{t('common.description', 'This is a default description')}

{t('common.save', 'Save')}


);
}
`

#### 7. Use Library Translations

The library provides common translations for frequently used UI elements:

`tsx
import { useLibTranslations } from 'pagamio-frontend-commons-lib';

function YourComponent() {
const { tLib } = useLibTranslations();

return (



{tLib('save')}
{tLib('cancel')}
{tLib('submit')}



);
}
`

#### 8. Add Locale Switcher

Add a language switcher to allow users to change the application language:

`tsx
import { LocaleSwitcher } from 'pagamio-frontend-commons-lib';

function Header() {
return (







);
}
`

You can customize language display names:

`tsx
localeNames={{
en: 'English',
es: 'Español',
fr: 'Français',
pt: 'Português'
}}
/>
`

#### 9. Run the Extraction Script

Extract all translation keys from your application:

`bash
yarn extract-translations
`

This will scan your code for translation keys and update your translation files.

$3

#### Custom Locale Detector

You can configure the translation system to detect the browser's locale:

`tsx
import { TranslationProvider, detectBrowserLocale } from 'pagamio-frontend-commons-lib';

function App() {
const browserLocale = detectBrowserLocale(); // Returns 'en', 'es', etc.

return (
defaultLocale={browserLocale}
loadPath="/translations"
>


);
}
`

#### Direct Loading of Translation Data

Instead of loading translations from files, you can provide them directly:

`tsx
import { TranslationProvider } from 'pagamio-frontend-commons-lib';

const translations = [
{
locale: 'en',
messages: {
common: {
save: 'Save',
cancel: 'Cancel'
}
}
},
{
locale: 'es',
messages: {
common: {
save: 'Guardar',
cancel: 'Cancelar'
}
}
}
];

function App() {
return (
defaultLocale="en"
localeData={translations}
>


);
}
``