npm package: @razorrisk/web-ui-lib
Description: Extendable Cloud UI library for RazorRisk web applications.
Latest version: 1.0.42

# @razorrisk/web-ui-lib

Extendable Cloud UI library for RazorRisk web applications.

## Prerequisites

Before installing `@razorrisk/web-ui-lib`, ensure your project has the following peer dependencies installed and that
you are not running React on Strict Mode. These libraries are required for compatibility and proper functionality:

| Package            | Required Version |
| ------------------ | ---------------- |
| `react`            | ^18.3.1          |
| `react-dom`        | ^18.3.1          |
| `react-router`     | 6.26.2           |
| `react-router-dom` | 6.26.2           |

You can install them using the following command:

```bash
npm install react@^18.3.1 react-dom@^18.3.1 react-router@6.26.2 react-router-dom@6.26.2
```

---

## Installation

```bash
npm install @razorrisk/web-ui-lib
```

---

## ⚙️ Usage

To bootstrap your application using the Web UI Library, set up both the `WebUiLib` component and your configuration as
follows:

```tsx
import React, { useEffect, useState } from 'react';
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import { ApolloClient } from '@apollo/client';

import {
  WebUiLib,
  initializeApolloClient,
  overrideRoutes,
  addRoutes,
  deleteRoutes,
  request,
} from '@razorrisk/web-ui-lib';

import '@razorrisk/web-ui-lib/style.css';
import { en } from './translations/en';

// Set up language translations
i18n.use(initReactI18next).init({
  resources: { en },
  lng: 'en',
  fallbackLng: 'en',
  interpolation: { escapeValue: false },
});

export function App() {
  const [apolloClient, setApolloClient] = useState<ApolloClient<unknown>>();

  useEffect(() => {
    initializeApolloClient().then(setApolloClient);
  }, []);

  return <WebUiLib apolloClient={apolloClient} />;
}

export default App;
```

Then in your `/public/config.json` file:

```json
{
  "server": {
    "hostname": "localhost",
    "port": "3000",
    "apiEndPoint": "http://127.0.1:3333",
    "workflowEndPoint": "http://127.0.1:555"
  },
  "client": {
    "maxNumber": 1000000000000,
    "navigationBarProperties": {
      "color": "#fff"
    },
    "tradeContributionPageSize": 500
  }
}
```

---

## 🈯 Setting Up Language Translations

```tsx
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import { en } from './translations/en';

i18n.use(initReactI18next).init({
  resources: {
    en,
  },
  lng: 'en',
  fallbackLng: 'en',
  interpolation: {
    escapeValue: false,
  },
});
```

---

## 🚀 Setting Up Apollo Client

```tsx
import { initializeApolloClient } from '@razorrisk/web-ui-lib';
import { ApolloClient } from '@apollo/client';
import { useEffect, useState } from 'react';

const [apolloClient, setApolloClient] = useState<ApolloClient<unknown>>();

useEffect(() => {
  initializeApolloClient().then(setApolloClient);
}, []);
```

Pass it to the UI shell:

```tsx
<WebUiLib apolloClient={apolloClient} />
```

---

## 🧠 `overrideRoutes`

Used to fully replace an existing route **by ID**, including its label, path, component, and icon.

```tsx
import { overrideRoutes } from '@razorrisk/web-ui-lib';
import { RiDashboardLine } from 'react-icons/ri';
import PrivateRoute from './PrivateRoute';
import CustomDashboard from './CustomDashboard';

overrideRoutes([
  {
    id: 'Dashboard',
    path: '/custom-dashboard',
    component: props => <PrivateRoute {...props} component={CustomDashboard} menu="Dashboard" />,
    navLabel: 'Custom Dashboard',
    navIcon: RiDashboardLine,
    propsMerger: originalProps => ({
      ...originalProps,
      customProp: 'Hello',
    }),
  },
]);
```

---

## ➕ `addRoutes`

Used to add completely new routes and navigation items.

```tsx
import { addRoutes } from '@razorrisk/web-ui-lib';
import PrivateRoute from './PrivateRoute';
import CustomAudit from './CustomAudit';
import { RiFileTextLine } from 'react-icons/ri';

addRoutes(
  [
    {
      path: '/custom-audit',
      element: <PrivateRoute component={CustomAudit} menu="CustomAudit" />,
    },
  ],
  [
    {
      id: 'Admin',
      label: 'Admin',
      icon: RiFileTextLine,
      variant: 'nav',
      children: [
        {
          id: 'CustomAudit',
          label: 'Custom Audit',
          route: '/custom-audit',
          icon: RiFileTextLine,
          variant: 'nav',
        },
      ],
    },
  ]
);
```

---

## ❌ `deleteRoutes`

Used to **hide/remove** routes and nav items by their ID:

```tsx
import { deleteRoutes } from '@razorrisk/web-ui-lib';

deleteRoutes(['Dashboard', 'Trades', 'AuditTrail']);
```

---

## 🌐 `request` Utility

Simple wrapper around `axios` to perform authenticated requests.

```tsx
import { request } from '@razorrisk/web-ui-lib';

const data = await request({
  url: '/api/some-endpoint',
  options: {
    method: 'POST',
    data: { key: 'value' },
  },
});
```

## Dynamic Runtime Configuration via config.json

Before injecting your components at runtime, you need to compile them into ES modules using the
@razorrisk/react-runtime-component-builder CLI.

After building the components you can also control route injection at runtime by defining deleteRoutes and addRoutes in
your config.json file. For example:

```json
{
  "deleteRoutes": ["AuditTrail"],
  "addRoutes": [
    {
      "id": "Admin",
      "label": "Admin",
      "icon": "MdInsertChart",
      "variant": "nav",
      "children": [
        {
          "id": "CustomAudit",
          "route": "/custom-audit",
          "componentPath": "/externals-dist/Home2.js",
          "label": "Custom Audit",
          "icon": "MdInsertChart",
          "variant": "nav"
        }
      ]
    },
    {
      "id": "custom",
      "route": "/custom-page",
      "componentPath": "/externals-dist/Home2.js",
      "label": "Custom Page",
      "icon": "MdInsertChart",
      "variant": "nav"
    }
  ]
}
```

deleteRoutes: An array of id strings for routes you want to remove from the default navigation.

addRoutes: An array of nav-item objects defining new menu entries and associated components to inject.

After placing this file at the root of your project the runtime loader will automatically inject the routes.

Supports:

- Auto-auth headers
- Smart endpoint routing for `/workflow` prefix
- Accepts custom headers or disables `Accept: application/json`
- Runtime Extension with custom functionality

---

## 🗂 Navigation Schema (IDs + Labels Overview)

```txt
Dashboard - "Dashboard"
Report - "Report"
  ├─ CounterpartyReportView - "Counterparty Report View"
  └─ CountryReportView - "Country Report View"
RiskViews - "Risk Views"
  ├─ CounterpartyRiskView - "Counterparty Risk View"
  └─ CountryReportView - "Country Risk View"
Counterparty - "Counterparty"
Country - "Country"
Portfolios - "Portfolios"
ReferenceData - "Reference Data"
Trades - "Trades"
  ├─ TradeList - "Trade List"
  ├─ PDLC - "Pre-Deal Check"
  ├─ ReservationsList - "Reservations List"
  └─ Reservations - "Reservations"
Admin - "Admin"
  ├─ AuditTrail - "Audit Trail"
  ├─ PDCAuditTrail - "Pre-Deal Check Audit Trail"
  ├─ RiskViewAuditTrail - "Risk View Audit Trail"
  ├─ BatchSummaries - "Batch Summaries"
  └─ UAM - "UAM"
```

---

## 🧩 Summary of Exports

| Function / Component     | Purpose                             |
| ------------------------ | ----------------------------------- |
| `WebUiLib`               | Main app wrapper                    |
| `initializeApolloClient` | Bootstraps Apollo Client            |
| `overrideRoutes`         | Replaces a route + nav config by ID |
| `addRoutes`              | Adds new routes + nav items         |
| `deleteRoutes`           | Removes nav/routes by ID            |
| `request`                | Secure HTTP client                  |

---

Let us know if you want additional setup examples (Remix, Next.js, etc).