diff --git a/README.md b/README.md index ecf8cc1..83860cd 100644 --- a/README.md +++ b/README.md @@ -111,19 +111,9 @@ function AppHeader() { --- -# استفاده از core +# Core -بخش core شامل این موارد است: - -* API config -* `createApi` -* `BiProvider` -* Keycloak -* Permission -* React Query provider -* Chakra provider - -Required dependencies: +required dependencies: ```bash yarn add @chakra-ui/react @emotion/react @emotion/styled framer-motion @tanstack/react-query axios keycloak-js @@ -131,7 +121,7 @@ yarn add @chakra-ui/react @emotion/react @emotion/styled framer-motion @tanstack --- -## استفاده از BiProvider +## BiProvider ```jsx import { BiProvider } from "uikit/core"; @@ -149,37 +139,27 @@ export default function App() { } ``` -`BiProvider` به صورت داخلی این کارها را انجام می‌دهد: +--- -* تنظیم base url برای API -* راه‌اندازی Keycloak در صورت فعال بودن -* گرفتن permissionها در صورت فعال بودن -* اضافه کردن `ChakraProvider` -* اضافه کردن `QueryClientProvider` -* اضافه کردن فونت و theme داخلی -* فعال کردن اختیاری `UpdateChecker` +## BiProvider props + +| Prop | +| -------------------- | +| `apiBaseUrl` | +| `keycloakClientId` | +| `permissionClientId` | +| `loading` | +| `updateChecker` | +| `updateCheckerProps` | +| `keycloakUrl` | +| `keycloakRealm` | +| `permissionUrl` | +| `keycloakEnabled` | +| `permissionEnabled` | --- -## props مربوط به BiProvider - -| Prop | توضیح | -| -------------------- | ------------------------------------------------------ | -| `apiBaseUrl` | آدرس اصلی API | -| `keycloakClientId` | client id مربوط به Keycloak | -| `permissionClientId` | client id مربوط به Permission | -| `loading` | کامپوننت loading هنگام init شدن Keycloak یا Permission | -| `updateChecker` | فعال یا غیرفعال کردن بررسی آپدیت | -| `updateCheckerProps` | props مربوط به UpdateChecker | -| `keycloakUrl` | آدرس Keycloak | -| `keycloakRealm` | realm مربوط به Keycloak | -| `permissionUrl` | آدرس API مربوط به permission | -| `keycloakEnabled` | فعال یا غیرفعال کردن Keycloak به صورت دستی | -| `permissionEnabled` | فعال یا غیرفعال کردن Permission به صورت دستی | - ---- - -## مقدارهای پیش‌فرض BiProvider +## BiProvider defaults ```js keycloakUrl = "https://auth.ibagher.ir"; @@ -188,42 +168,9 @@ permissionUrl = "https://api.d.aiengines.ir/user_api/v1/permissions/list"; updateChecker = false; ``` -نکته: اگر `keycloakClientId` داده شود، Keycloak فعال می‌شود. اگر `permissionClientId` داده شود، Permission فعال می‌شود. - -برای کنترل دستی: - -```jsx - - - -``` - --- -# UpdateChecker - -به صورت پیش‌فرض `updateChecker` خاموش است. - -برای فعال کردن: - -```jsx - - - -``` - -اگر `updateChecker` را فعال می‌کنی، پروژه باید فایل version تولید کند. معمولاً باید یک اسکریپت مثل `write-version.js` در root پروژه داشته باشی و در `package.json` پروژه target، قبل از build اجرا شود. - -نمونه: +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 { @@ -236,23 +183,18 @@ updateChecker = false; --- -# استفاده از API پایه +# API ```js import { api, fetcher, configureApi, getApi } from "uikit/core"; ``` -اگر از `BiProvider` استفاده می‌کنی، معمولاً نیازی نیست دستی `configureApi` را صدا بزنی، چون `BiProvider` این کار را انجام می‌دهد. - -نمونه استفاده مستقیم: - ```js import { api } from "uikit/core"; const response = await api.get("/users"); ``` - -یا: +or ```js import { fetcher } from "uikit/core"; @@ -262,35 +204,39 @@ const data = await fetcher("/users"); --- -# استفاده از createApi - -`createApi` برای ساختن یک API ساده بر پایه React Query استفاده می‌شود. +# createApi ```js import { createApi } from "uikit/core"; -export const profileApi = createApi({ - key: "profile", - url: "/content/rokn/profiles", +export const sampleApi = createApi({ + key: "sample", + url: "/...", actions: { + create: { + method: "post", + url: "/...", + }, + update: { method: "patch", - url: (id) => `/content/rokn/profiles/${id}`, + url: (id) => `/.../${id}`, }, delete: { method: "delete", + url: (id) => `/.../${id}`, }, - generate: { + confirm: { method: "post", - url: "/content/rokn/generate/profile", + url: "/...", }, - updateImages: { + updateImage: { method: "post", - url: (id) => `/content/rokn/profile-update/${id}/images`, + url: (id) => `/.../${id}/image`, body: ({ formData }) => formData, }, }, @@ -299,120 +245,17 @@ export const profileApi = createApi({ --- -## گرفتن لیست - -```jsx -const { data, isLoading, error } = profileApi.useGet({ - page: 1, - size: 20, - is_confirmed: true, -}); -``` - -این request ساخته می‌شود: - -```txt -GET /content/rokn/profiles?page=1&size=20&is_confirmed=true -``` - ---- - -## اجرای action - -```jsx -const updateProfile = profileApi.useAction("update"); - -await updateProfile.mutateAsync({ - id: 10, - username: "new_username", -}); -``` - -در این حالت: - -```txt -PATCH /content/rokn/profiles/10 -``` - -body: - -```js -{ - username: "new_username" -} -``` - -`id` به صورت پیش‌فرض از body حذف می‌شود، چون برای ساختن URL استفاده شده است. - ---- - -## action با همان URL اصلی - -اگر action همان URL اصلی را لازم دارد، نیازی نیست `url` را دوباره بنویسی. - -```js -export const identityGenerateApi = createApi({ - key: "identity-generate", - url: "/content/rokn/identity-generate/logs", - - actions: { - delete: { - method: "delete", - }, - }, -}); -``` - -یعنی: - -```txt -DELETE /content/rokn/identity-generate/logs -``` - ---- - -## action با FormData - -```js -const updateImages = profileApi.useAction("updateImages"); - -const formData = new FormData(); -formData.append("image", file); - -await updateImages.mutateAsync({ - id: 10, - formData, -}); -``` - -در تعریف action: - -```js -updateImages: { - method: "post", - url: (id) => `/content/rokn/profile-update/${id}/images`, - body: ({ formData }) => formData, -} -``` - -`body` مشخص می‌کند چه چیزی واقعاً به عنوان body ارسال شود. - ---- - -# استفاده از Keycloak +# Keycloak ```js import { getKeycloakToken, loginKeycloak, logoutKeycloak, - updateKeycloakToken, } from "uikit/core"; const token = getKeycloakToken(); -await updateKeycloakToken(30); - loginKeycloak(); logoutKeycloak({ @@ -422,7 +265,7 @@ logoutKeycloak({ --- -# استفاده از Permission +# Permission ```jsx import { Can, usePermission } from "uikit/core"; @@ -442,27 +285,16 @@ function Page() { } ``` -نکته: prop کامپوننت `Can` برابر `perm` است. - -```jsx - - - -``` - --- -# استفاده از DataTable +# DataTable -`DataTable` داخل مسیر `uikit/table` قرار دارد. - -dependencyهای لازم: +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";