uikit/README.md

# uikit

Shared library for BI next.js projects.


---

## Install

```bash
yarn add git+https://git.d.aiengines.ir/bi/uikit.git
```

---

## Update

```bash
yarn upgrade uikit
```
or
```bash
rm -rf .next
rm -rf node_modules/.vite
rm -rf node_modules/.cache
rm -rf node_modules/uikit

yarn upgrade uikit
```

---

# imports

| مسیر               | کاربرد                                   | dependency اضافی                        |
| ------------------ | ------------------------------------- | --------------------------------------- |
| `uikit`            | utility functions                     | -                                       |
| `uikit/utils`      | utility functions                     | -                                       |
| `uikit/pagination` | pagination                            | Chakra + React + react-icons            |
| `uikit/layout`     | Header                                | Chakra + React                          |
| `uikit/core`       | API، BiProvider، Keycloak، Permission  | Chakra + React Query + Axios + Keycloak |
| `uikit/table`      | DataTable                             | Chakra + TanStack Table + Pagination    |

---

# utils

```js
import { toFaDigits, toEnDigits, toFaNumber } from "uikit/utils";

toFaDigits(123456);
toEnDigits("۱۲۳۴۵۶");
toFaNumber(123456);
```
or

```js
import { toFaDigits } from "uikit";
```

---

# pagination

required dependencies

```bash
yarn add @chakra-ui/react @emotion/react @emotion/styled framer-motion react-icons
```

using

```jsx
import { Pagination, LightPagination, SimplePagination } from "uikit/pagination";

function Page() {
  return (
    <Pagination
      currentPage={1}
      totalCount={100}
      totalPages={5}
      onPageChange={(page) => console.log(page)}
    />
  );
}
```

---

# Header

required dependencies:

```bash
yarn add @chakra-ui/react @emotion/react @emotion/styled framer-motion
```

using:

```jsx
import { Header } from "uikit/layout";

function AppHeader() {
  return (
    <Header>
      <Header.BrandSection>
        <Header.Logo src="/logo.png" />

        <Header.Brand>
          <Header.Title>عنوان سامانه</Header.Title>
          <Header.Description>توضیح کوتاه سامانه</Header.Description>
        </Header.Brand>
      </Header.BrandSection>

      <Header.Bi />
    </Header>
  );
}
```

---

# Core

required dependencies:

```bash
yarn add @chakra-ui/react @emotion/react @emotion/styled framer-motion @tanstack/react-query axios keycloak-js
```

---

## BiProvider

```jsx
import { BiProvider } from "uikit/core";

export default function App() {
  return (
    <BiProvider
      apiBaseUrl="https://api.example.com"
      keycloakClientId="front-client"
      permissionClientId="permission-client"
    >
      <YourApp />
    </BiProvider>
  );
}
```

---

## BiProvider props

| Prop                 |
| -------------------- |
| `apiBaseUrl`         |
| `keycloakClientId`   |
| `permissionClientId` |
| `loading`            |
| `updateChecker`      |
| `updateCheckerProps` |
| `keycloakUrl`        |
| `keycloakRealm`      |
| `permissionUrl`      |
| `keycloakEnabled`    |
| `permissionEnabled`  |

---

## BiProvider defaults

```js
keycloakUrl = "https://auth.ibagher.ir";
keycloakRealm = "bi";
permissionUrl = "https://api.d.aiengines.ir/user_api/v1/permissions/list";
updateChecker = false;
```

---

To enable `updateChecker` you should have a script `write-version.js` in the root of the project and in the `package.json` of the target project, run before the build:

```json
{
  "scripts": {
    "prebuild": "node write-version.js",
    "build": "next build"
  }
}
```

---

# API

```js
import { api, fetcher, configureApi, getApi } from "uikit/core";
```

```js
import { api } from "uikit/core";

const response = await api.get("/users");
```
or

```js
import { fetcher } from "uikit/core";

const data = await fetcher("/users");
```

---

# createApi

```js
import { createApi } from "uikit/core";

export const sampleApi = createApi({
  key: "sample",
  url: "/...",

  actions: {
    create: {
      method: "post",
      url: "/...",
    },

    update: {
      method: "patch",
      url: (id) => `/.../${id}`,
    },

    delete: {
      method: "delete",
      url: (id) => `/.../${id}`,
    },

    confirm: {
      method: "post",
      url: "/...",
    },

    updateImage: {
      method: "post",
      url: (id) => `/.../${id}/image`,
      body: ({ formData }) => formData,
    },
  },
});
```

---

# Keycloak

```js
import {
  getKeycloakToken,
  loginKeycloak,
  logoutKeycloak,
} from "uikit/core";

const token = getKeycloakToken();

loginKeycloak();

logoutKeycloak({
  redirectUri: window.location.origin,
});
```

---

# Permission

```jsx
import { Can, usePermission } from "uikit/core";

function Page() {
  const { can, cannot, permissions } = usePermission();

  return (
    <>
      {can("users:list") && <div>لیست کاربران</div>}

      <Can perm="users:create" fallback={null}>
        <button>ایجاد کاربر</button>
      </Can>
    </>
  );
}
```

---

# DataTable

required dependencies:

```bash
yarn add @chakra-ui/react @emotion/react @emotion/styled framer-motion @tanstack/react-table react-icons
```
using:

```jsx
import { DataTable } from "uikit/table";

function UsersTable({ data, columns }) {
  return (
    <DataTable
      data={data}
      columns={columns}
      page={1}
      size={20}
      pagination={{
        totalCount: 100,
        totalPages: 5,
      }}
      onPageChange={(page) => console.log(page)}
      getRowId={(row) => String(row.id)}
      enableSelection
      showIndex
    >
      <DataTable.Topbar>
        <DataTable.Title>لیست کاربران</DataTable.Title>
        <DataTable.Spacer />
        <DataTable.Actions>
          <DataTable.SelectAll />
        </DataTable.Actions>
      </DataTable.Topbar>

      <DataTable.Content>
        <DataTable.Table />
        <DataTable.Pagination />
      </DataTable.Content>
    </DataTable>
  );
}
```

---