Update README.md
This commit is contained in:
parent
fa06461e4b
commit
2ae702a8b3
426
README.md
426
README.md
@ -2,7 +2,6 @@
|
||||
|
||||
Shared library for BI next.js projects.
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Install
|
||||
@ -18,7 +17,9 @@ yarn add git+https://git.d.aiengines.ir/bi/uikit.git
|
||||
```bash
|
||||
yarn upgrade uikit
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```bash
|
||||
rm -rf .next
|
||||
rm -rf node_modules/.vite
|
||||
@ -32,14 +33,15 @@ yarn upgrade uikit
|
||||
|
||||
# imports
|
||||
|
||||
| مسیر | کاربرد | dependency اضافی |
|
||||
| مسیر | کاربرد | 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/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 |
|
||||
|
||||
---
|
||||
|
||||
@ -52,6 +54,7 @@ toFaDigits(123456);
|
||||
toEnDigits("۱۲۳۴۵۶");
|
||||
toFaNumber(123456);
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```js
|
||||
@ -159,19 +162,22 @@ export default function App() {
|
||||
|
||||
## BiProvider props
|
||||
|
||||
| Prop |
|
||||
| -------------------- |
|
||||
| `apiBaseUrl` |
|
||||
| `keycloakClientId` |
|
||||
| `permissionClientId` |
|
||||
| `loading` |
|
||||
| `updateChecker` |
|
||||
| `updateCheckerProps` |
|
||||
| `keycloakUrl` |
|
||||
| `keycloakRealm` |
|
||||
| `permissionUrl` |
|
||||
| `keycloakEnabled` |
|
||||
| `permissionEnabled` |
|
||||
| Prop |
|
||||
| ----------------------------- |
|
||||
| `apiBaseUrl` |
|
||||
| `keycloakClientId` |
|
||||
| `permissionClientId` |
|
||||
| `loading` |
|
||||
| `updateChecker` |
|
||||
| `updateCheckerProps` |
|
||||
| `keycloakUrl` |
|
||||
| `keycloakRealm` |
|
||||
| `permissionUrl` |
|
||||
| `keycloakEnabled` |
|
||||
| `permissionEnabled` |
|
||||
| `remoteUiEnabled` |
|
||||
| `remoteUiUrl` |
|
||||
| `remoteUiChakraProviderProps` |
|
||||
|
||||
---
|
||||
|
||||
@ -182,6 +188,85 @@ 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` کار اضافهای لازم نیست.
|
||||
|
||||
```jsx
|
||||
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 شده باشد:
|
||||
|
||||
```jsx
|
||||
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 کند:
|
||||
|
||||
```jsx
|
||||
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>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
@ -210,6 +295,7 @@ import { api } from "uikit/core";
|
||||
|
||||
const response = await api.get("/users");
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```js
|
||||
@ -303,6 +389,311 @@ function Page() {
|
||||
|
||||
---
|
||||
|
||||
# Remote UI
|
||||
|
||||
`remote/ui` برای کامپوننتهایی است که باید بدون build مجدد سامانه مقصد، از طریق فایل remote بهروزرسانی شوند.
|
||||
|
||||
مثلاً `GBadge` از این مسیر استفاده میشود:
|
||||
|
||||
```jsx
|
||||
import { GBadge } from "uikit/remote/ui";
|
||||
|
||||
function Page() {
|
||||
return (
|
||||
<GBadge colorScheme="blue" py={1} px={2} borderRadius="full">
|
||||
فعال
|
||||
</GBadge>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GBadge
|
||||
|
||||
required dependencies:
|
||||
|
||||
```bash
|
||||
yarn add @chakra-ui/react @emotion/react @emotion/styled framer-motion
|
||||
```
|
||||
|
||||
using:
|
||||
|
||||
```jsx
|
||||
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 نمیشوند:
|
||||
|
||||
```txt
|
||||
React
|
||||
ReactDOM
|
||||
Chakra
|
||||
Emotion
|
||||
theme
|
||||
Fonts
|
||||
font files
|
||||
```
|
||||
|
||||
این موارد باید در سامانه مقصد وجود داشته باشند.
|
||||
|
||||
---
|
||||
|
||||
## GBadge with BiProvider
|
||||
|
||||
اگر سامانه مقصد از `BiProvider` استفاده میکند، نیازی به setup دستی نیست:
|
||||
|
||||
```jsx
|
||||
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` کافی است:
|
||||
|
||||
```jsx
|
||||
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`:
|
||||
|
||||
```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:
|
||||
|
||||
```jsx
|
||||
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 متفاوت است:
|
||||
|
||||
```jsx
|
||||
import { setupUikitRemoteDeps } from "uikit/remote/ui";
|
||||
import { theme } from "./theme";
|
||||
|
||||
setupUikitRemoteDeps({
|
||||
theme,
|
||||
remoteUrl: "https://static.example.com/uikit/GBadge.js",
|
||||
});
|
||||
```
|
||||
|
||||
یا مستقیم روی خود کامپوننت:
|
||||
|
||||
```jsx
|
||||
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` ندارد، فونت را در خود سامانه مقصد ست کنید:
|
||||
|
||||
```css
|
||||
@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` از این مقدار استفاده میکند:
|
||||
|
||||
```css
|
||||
var(--uikit-font-family, inherit)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Build Remote UI
|
||||
|
||||
برای ساخت فایل remote:
|
||||
|
||||
```bash
|
||||
yarn build:remote
|
||||
```
|
||||
|
||||
خروجی remote:
|
||||
|
||||
```txt
|
||||
dist/remote/GBadge.js
|
||||
```
|
||||
|
||||
این فایل باید روی static server یا CDN داخلی deploy شود.
|
||||
|
||||
مثلاً:
|
||||
|
||||
```txt
|
||||
https://uikit.d.aiengines.ir/GBadge.js
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deploy Remote UI
|
||||
|
||||
بعد از تغییر در `GBadge.remote.jsx` یا کامپوننتهای remote:
|
||||
|
||||
```bash
|
||||
yarn build:remote
|
||||
```
|
||||
|
||||
سپس فایل زیر را deploy کنید:
|
||||
|
||||
```txt
|
||||
dist/remote/GBadge.js
|
||||
```
|
||||
|
||||
سامانههای مقصد بعد از reload صفحه، نسخه جدید remote را دریافت میکنند.
|
||||
|
||||
اگر cache سمت browser یا CDN فعال است، باید cache فایل remote کنترل شود.
|
||||
|
||||
---
|
||||
|
||||
## Important Notes
|
||||
|
||||
اگر از مسیر زیر استفاده شود:
|
||||
|
||||
```js
|
||||
import { GBadge } from "uikit/remote/ui";
|
||||
```
|
||||
|
||||
خود کامپوننت از فایل remote استفاده میکند.
|
||||
|
||||
اما اگر کامپوننتی از مسیر معمولی package import شود، مثل:
|
||||
|
||||
```js
|
||||
import { SomeComponent } from "uikit";
|
||||
```
|
||||
|
||||
یا:
|
||||
|
||||
```js
|
||||
import { SomeComponent } from "uikit/table";
|
||||
```
|
||||
|
||||
آن کامپوننت داخل build سامانه مقصد bundle میشود و برای آپدیت شدن نیاز به rebuild یا `yarn upgrade` دارد.
|
||||
|
||||
پس:
|
||||
|
||||
```txt
|
||||
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:
|
||||
@ -310,6 +701,7 @@ required dependencies:
|
||||
```bash
|
||||
yarn add @chakra-ui/react @emotion/react @emotion/styled framer-motion @tanstack/react-table react-icons
|
||||
```
|
||||
|
||||
using:
|
||||
|
||||
```jsx
|
||||
@ -347,5 +739,3 @@ function UsersTable({ data, columns }) {
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user