uikit

Shared library for BI next.js projects.

---

Install

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

---

Update

yarn upgrade uikit

or

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
uikit/remote/ui	Remote UI components مثل GBadge	Chakra + React + remote static file

---

utils

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

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

or

import { toFaDigits } from "uikit";

---

pagination

required dependencies

yarn add @chakra-ui/react@2
yarn add @chakra-ui/icons@2
yarn add @emotion/react@11
yarn add @emotion/styled@11
yarn add chakra-react-select@5
yarn add react-select@5
yarn add framer-motion@10
yarn add react-icons

using

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:

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

using:

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:

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

---

BiProvider

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
remoteUiEnabled
remoteUiUrl
remoteUiChakraProviderProps

---

BiProvider defaults

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

---

BiProvider with Remote UI

BiProvider به صورت خودکار dependencyهای لازم برای کامپوننت‌های remote/ui را setup می‌کند.

پس اگر سامانه مقصد از BiProvider استفاده می‌کند، برای استفاده از GBadge کار اضافه‌ای لازم نیست.

import { BiProvider } from "uikit/core";
import { GBadge } from "uikit/remote/ui";

export default function App() {
  return (
    <BiProvider
      apiBaseUrl="https://api.example.com"
      keycloakClientId="front-client"
      permissionClientId="permission-client"
    >
      <GBadge colorScheme="blue" py={1} px={2} borderRadius="full">
        فعال
      </GBadge>
    </BiProvider>
  );
}

در این حالت GBadge همچنان از Chakra استفاده می‌کند، ولی فایل remote آن، یعنی GBadge.js، خودش Chakra و React و font را داخل bundle نمی‌آورد.

dependencyهای لازم از خود سامانه مقصد گرفته می‌شوند.

---

Change Remote UI URL

اگر فایل remote روی آدرس دیگری deploy شده باشد:

import { BiProvider } from "uikit/core";

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

---

Disable Remote UI setup in BiProvider

اگر نمی‌خواهید BiProvider به صورت خودکار remote ui را setup کند:

import { BiProvider } from "uikit/core";

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

---

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:

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

---

API

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

import { api } from "uikit/core";

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

or

import { fetcher } from "uikit/core";

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

---

createApi

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

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

const token = getKeycloakToken();

loginKeycloak();

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

---

Permission

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>
    </>
  );
}

---

Remote UI

remote/ui برای کامپوننت‌هایی است که باید بدون build مجدد سامانه مقصد، از طریق فایل remote به‌روزرسانی شوند.

مثلاً GBadge از این مسیر استفاده می‌شود:

import { GBadge } from "uikit/remote/ui";

function Page() {
  return (
    <GBadge colorScheme="blue" py={1} px={2} borderRadius="full">
      فعال
    </GBadge>
  );
}

---

GBadge

required dependencies:

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

using:

import { GBadge } from "uikit/remote/ui";

function Page({ item }) {
  return (
    <GBadge colorScheme="blue" py={1} px={2} borderRadius="full">
      {item}
    </GBadge>
  );
}

GBadge از Chakra Badge استفاده می‌کند.

اما برای کم شدن حجم فایل remote، این موارد داخل GBadge.js bundle نمی‌شوند:

React
ReactDOM
Chakra
Emotion
theme
Fonts
font files

این موارد باید در سامانه مقصد وجود داشته باشند.

---

GBadge with BiProvider

اگر سامانه مقصد از BiProvider استفاده می‌کند، نیازی به setup دستی نیست:

import { BiProvider } from "uikit/core";
import { GBadge } from "uikit/remote/ui";

function App() {
  return (
    <BiProvider
      apiBaseUrl="https://api.example.com"
      keycloakClientId="front-client"
      permissionClientId="permission-client"
    >
      <GBadge colorScheme="blue" py={1} px={2} borderRadius="full">
        فعال
      </GBadge>
    </BiProvider>
  );
}

---

GBadge without BiProvider

اگر سامانه مقصد از BiProvider استفاده نمی‌کند، دو حالت وجود دارد.

حالت ساده

اگر theme خاصی ندارید، فقط استفاده از GBadge کافی است:

import { GBadge } from "uikit/remote/ui";

function Page() {
  return (
    <GBadge colorScheme="blue" py={1} px={2} borderRadius="full">
      فعال
    </GBadge>
  );
}

در این حالت wrapper مربوط به GBadge خودش dependencyهای لازم را setup می‌کند.

---

حالت با theme اختصاصی

اگر سامانه مقصد theme اختصاصی Chakra دارد، بهتر است در entry اصلی پروژه یک بار setup انجام شود.

مثلاً در main.jsx، App.jsx یا _app.jsx:

import React from "react";
import { createRoot } from "react-dom/client";
import { ChakraProvider } from "@chakra-ui/react";
import { setupUikitRemoteDeps } from "uikit/remote/ui";
import { theme } from "./theme";
import App from "./App";

setupUikitRemoteDeps({
  theme,
});

createRoot(document.getElementById("root")).render(
  <ChakraProvider theme={theme}>
    <App />
  </ChakraProvider>,
);

برای Next.js:

import { ChakraProvider } from "@chakra-ui/react";
import { setupUikitRemoteDeps } from "uikit/remote/ui";
import { theme } from "@/theme";

setupUikitRemoteDeps({
  theme,
});

export default function App({ Component, pageProps }) {
  return (
    <ChakraProvider theme={theme}>
      <Component {...pageProps} />
    </ChakraProvider>
  );
}

---

Remote URL without BiProvider

اگر سامانه مقصد از BiProvider استفاده نمی‌کند و آدرس فایل remote متفاوت است:

import { setupUikitRemoteDeps } from "uikit/remote/ui";
import { theme } from "./theme";

setupUikitRemoteDeps({
  theme,
  remoteUrl: "https://static.example.com/uikit/GBadge.js",
});

یا مستقیم روی خود کامپوننت:

import { GBadge } from "uikit/remote/ui";

function Page() {
  return (
    <GBadge
      remoteUrl="https://static.example.com/uikit/GBadge.js"
      colorScheme="blue"
      py={1}
      px={2}
      borderRadius="full"
    >
      فعال
    </GBadge>
  );
}

---

Font

فونت داخل فایل remote باندل نمی‌شود.

اگر سامانه مقصد از BiProvider استفاده می‌کند، فونت و theme اصلی از همان BiProvider می‌آید.

اگر سامانه مقصد BiProvider ندارد، فونت را در خود سامانه مقصد ست کنید:

@font-face {
  font-family: Estedad;
  src: url("/fonts/estedad.woff2") format("woff2");
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}

:root {
  --uikit-font-family: Estedad, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
}

body {
  font-family: var(--uikit-font-family);
}

GBadge از این مقدار استفاده می‌کند:

var(--uikit-font-family, inherit)

---

Build Remote UI

برای ساخت فایل remote:

yarn build:remote

خروجی remote:

dist/remote/GBadge.js

این فایل باید روی static server یا CDN داخلی deploy شود.

مثلاً:

https://uikit.d.aiengines.ir/GBadge.js

---

Deploy Remote UI

بعد از تغییر در GBadge.remote.jsx یا کامپوننت‌های remote:

yarn build:remote

سپس فایل زیر را deploy کنید:

dist/remote/GBadge.js

سامانه‌های مقصد بعد از reload صفحه، نسخه جدید remote را دریافت می‌کنند.

اگر cache سمت browser یا CDN فعال است، باید cache فایل remote کنترل شود.

---

Important Notes

اگر از مسیر زیر استفاده شود:

import { GBadge } from "uikit/remote/ui";

خود کامپوننت از فایل remote استفاده می‌کند.

اما اگر کامپوننتی از مسیر معمولی package import شود، مثل:

import { SomeComponent } from "uikit";

یا:

import { SomeComponent } from "uikit/table";

آن کامپوننت داخل build سامانه مقصد bundle می‌شود و برای آپدیت شدن نیاز به rebuild یا yarn upgrade دارد.

پس:

uikit/remote/ui  => update by remote file
uikit/table      => update by package upgrade
uikit/core       => update by package upgrade
uikit/layout     => update by package upgrade

---

DataTable

required dependencies:

yarn add @chakra-ui/react @emotion/react @emotion/styled framer-motion @tanstack/react-table react-icons

using:

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>
  );
}