uikit
Shared library for BI next.js projects.
Install
yarn add git+https://git.d.aiengines.ir/bi/uikit.git
Update
yarn upgrade uikit
اگر نیاز به پاکسازی cache و نصب مجدد uikit بود:
Bash
rm -rf .next
rm -rf node_modules/.vite
rm -rf node_modules/.cache
rm -rf node_modules/uikit
yarn upgrade uikit
PowerShell
Remove-Item -Recurse -Force .next -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force node_modules/.vite -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force node_modules/.cache -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force node_modules/uikit -ErrorAction SilentlyContinue
yarn upgrade uikit
imports
| مسیر | کاربرد | dependency اضافی |
|---|---|---|
uikit |
utility functions | - |
uikit/utils |
utility functions | - |
uikit/pagination |
pagination | Chakra + React |
uikit/layout |
Header, Sidebar | Chakra + React |
uikit/core |
API، BiProvider قدیمی، Keycloak، Permission | Chakra + React Query + Axios + Keycloak + Query Params |
uikit/provider |
BiProvider جدید با قابلیتهای مستقل | React؛ هر قابلیت فقط نیازمندی مسیر خودش |
uikit/chakra |
Chakra, defaultBiTheme |
Chakra UI v2 و Emotion |
uikit/query |
Query |
TanStack React Query v5 |
uikit/next-pages-router |
NextPagesRouter |
Next.js Pages، next-query-params، use-query-params |
uikit/keycloak |
Keycloak, useKeycloak |
keycloak-js |
uikit/api |
Api, useApi, fetcher |
axios |
uikit/permission |
Permission, usePermission و guardها و توابع cache |
React |
uikit/table |
DataTable | Chakra + TanStack Table + Pagination |
uikit/remote/ui |
Remote UI components مثل GBadge |
Chakra + React + remote static file |
uikit/remote/ui/BiImage |
BiImage با تغییر اندازه خودکار و fallback |
فقط React (بدون Chakra و BiProvider) |
BiImage — تصویر ریموت و بهینهسازی خودکار (v1.3.0)
این قابلیت از سورس BiImage مستقل منتقل شده و با uikit/provider، <Chakra />، Next/Image یا تم سامانه مقصد وابستگی ندارد. برای مصرف React در Vite یا Next.js:
import { BiImage } from "uikit/remote/ui/BiImage";
// همچنین: import { BiImage } from "uikit/remote/ui";
// تصویر با عرض و ارتفاع ثابت (پیکسل)
<BiImage src={image_url} width={70} height={70} alt="نشان" />
// ارتفاع ثابت، عرض متناسب با نسبت اصلی تصویر
<BiImage src={image_url} height={80} width="auto" alt="تصویر کاربر" />
// عرض ریسپانسیو، ارتفاع متناسب با نسبت اصلی تصویر
<BiImage src={image_url} style={{ width: "100%", height: "auto" }} alt="تصویر ریسپانسیو" />
// جایگزین مستقیم Chakra Image با عرض/ارتفاع واکنشگرا و Hover
<BiImage
src={image_url}
w={{ base: "60px", sm: "70px" }}
h={{ base: "60px", sm: "70px" }}
objectFit="contain"
transition="transform 0.3s ease-in-out"
_hover={{ transform: "scale(1.3)" }}
fallbackSrc="/default.svg"
/>
// تصویر جایگزین اختیاری؛ آدرس fallback بدون عبور از Image Proxy مصرف میشود
<BiImage src={image_url} fallbackSrc="/default.svg" width={70} height={70} alt="نشان" />
API و رفتار کامپوننت
| پراپ | توضیح |
|---|---|
src |
URL کامل http/https، آدرس CDN بدون دامنه (از https://cdn.d.aiengines.ir/)، پروتکلنسبی، blob: یا data:image/...؛ خالی بودن مجاز است. |
width, height |
عدد (px) یا رشته CSS مثل "70px"، "auto"، "100%"؛ برای حفظ نسبت اصلی، یکی از ابعاد را auto بگذارید. |
w, h, width, height, boxSize |
عدد یا CSS و مقادیر ریسپانسیو چاکرا به شکل {base, sm, md, lg, xl, "2xl"} یا آرایه. width/height بر w/h اولویت دارند. |
style, className, sx |
استایل خود <img>؛ اغلب پراپهای CSS و میانبرهای Chakra (مثل minW, maxW, rounded, bg, mx, p) نیز پشتیبانی میشوند. |
transition, transform, _hover, _focus, _active, _focusVisible |
CSS تعاملی و انیمیشن با استایل Scoped و بدون ChakraProvider. |
objectFit, objectPosition |
کنترل نحوه نمایش در قاب محدود. |
fallbackSrc |
جایگزین در نبودن یا خطای تصویر اصلی، بدون بهینهسازی؛ اگر آن هم خطا دهد، تصویر بدون پسزمینه اجباری باقی میماند. |
alt, loading, decoding, sizes, onLoad, onError, onClick |
پراپهای تصویر استاندارد که کامپوننت پشتیبانی میکند؛ alt را برای دسترسپذیری بدهید. |
- Breakpointهای پیشفرض مانند Chakra v2 هستند:
sm=30em،md=48em،lg=62em،xl=80em،2xl=96em. تغییر breakpointهای سفارشی در تم Chakra بهصورت خودکار به کامپوننت مستقل منتقل نمیشود. - این کامپوننت بدون
ChakraProviderکار میکند، اما موتور کامل Theme/StyleConfig چاکرا نیست؛ توکنهای سفارشی Theme، پراپfallbackاز نوع React element و همه انتخابگرهای پیچیدهsxمعادل دقیق Chakra نیستند. مثالهای معمول Chakra Image (ابعاد ریسپانسیو، objectFit، Hover و Transition) پشتیبانی و در مرورگر تست شدهاند. - بهینهسازی CDN/HTTP با
processImageموجود درuikit/utilsانجام میشود؛ اندازه از layout باResizeObserverگرفته میشود و تصویر باq:100در قالب WebP درخواست میشود.data:imageوblob:از proxy عبور نمیکنند. - پسزمینه
BiImageبهصورت پیشفرض شفاف است؛ اگرsrcخالی باشد یا تصویر و fallback هر دو خطا بدهند، پسزمینه خاکستری اجباری نمایش داده نمیشود. برای رنگ دلخواه،bgیاbackgroundColorرا صریحاً ارسال کنید. برای تصویر با ارتفاع خودکار و بدون منبع، ارتفاعی تضمین نمیشود؛ در صورت نیاز ابعاد ثابت بدهید. - فایل remote مستقل از Chakra و سایر فایلهای remote در
https://uikit.d.aiengines.ir/BiImage.jsمنتشر میشود؛ wrapper React آن پس از Mount شدن در مرورگر بارگذاری میشود. پس از انتشار پکیج، خود فایل remote نیز باید همراه خروجیdist/remote/BiImage.jsروی CDN منتشر شود. یک صفحه نمونه مستقل با چهار حالت درdist/remote/BiImage-demo.htmlهم موجود است؛ نسخه React دمو درsrc/dev/AppHeaderPreview.jsxمستند شده و هنگام build:demo بهروز میشود. بدون دسترسی به این فایل، تصویر رندر نمیشود. - هنگام تغییر نسخه import یا fallback، نام
BiImageو این مسیر عمومی ثابت میماند. تغییرات بعدی فایل remote ممکن است با cache مرورگر/CDN تا refresh بعدی تأخیر داشته باشد.
utils
import { toFaDigits, toEnDigits, toFaNumber, processImage, truncateText, thinScrollbar } from "uikit/utils";
toFaDigits(123456);
toEnDigits("۱۲۳۴۵۶");
toFaNumber(123456);
processImage("https://example.com/image.jpg");
processImage("https://example.com/image.jpg", { w: 300, h: 200, q: 70, webp: true, g: "sm" });
truncateText("این یک متن طولانی برای تست است", 12); // "این یک متن ط..."
// در Chakra UI، بدون dependency اضافه:
// <Box overflowY="auto" sx={thinScrollbar}>...</Box>
or
import { toFaDigits } from "uikit";
pagination
required dependencies
yarn add @chakra-ui/react@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
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@2
yarn add @emotion/react@11
yarn add @emotion/styled@11
yarn add framer-motion@10
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>
);
}
Sidebar
required dependencies:
yarn add @chakra-ui/react @emotion/react @emotion/styled framer-motion
yarn add @tanstack/react-query axios keycloak-js
yarn add next-query-params@^5.1.0 use-query-params@^2.2.2
Sidebar همان UI ناوبری سامانه را برای دسکتاپ و موبایل ارائه میدهد. در دسکتاپ به صورت نوار آیکون کناری و در موبایل به صورت bottom navigation + drawer «بیشتر» نمایش داده میشود.
آیتمها به صورت config به کامپوننت داده میشوند:
import { SlUserFollowing } from "react-icons/sl";
const navigationItems = [
{
title: "آنالیز شبکه متعارف - فالوور/فالووینگ",
mobileTitle: "ارتباط کاربران",
icon: SlUserFollowing,
path: "/user-connections/analyze",
perm: ["analyze"],
},
];
نمونه استفاده در Next.js Pages Router:
import NextLink from "next/link";
import { useRouter } from "next/router";
import { Sidebar } from "uikit/layout";
function AppSidebar() {
const router = useRouter();
return (
<Sidebar
items={navigationItems}
currentPath={router.asPath}
linkComponent={NextLink}
/>
);
}
Sidebar باید داخل BiProvider استفاده شود. Permission هر آیتم از perm توسط خود UI Kit بررسی میشود و خروج با Keycloak توسط خود UI Kit انجام میشود. سامانه مقصد نیازی به usePermission یا logoutKeycloak برای Sidebar ندارد.
کنترل دسترسی کلی panel_access عمداً داخل Sidebar انجام نمیشود تا navigation هنگام render باعث redirect و لغو route در Next.js نشود. اگر سامانه به این guard نیاز دارد، از PanelAccessGuard موجود در uikit/core در سطح Layout/App استفاده کنید.
aliases نیز پشتیبانی میشود و برای تشخیص آیتم active استفاده میشود:
{
title: "آنالیز شبکه های اجتماعی خارجی",
mobileTitle: "شبکه خارجی",
icon: TbAnalyze,
path: "/posts/final_analyze",
aliases: ["/posts/analyze"],
perm: ["analyze"],
}
اگر perm آرایه باشد، همه permissionهای داخل آرایه برای فعال بودن آیتم لازم هستند. آیتم بدون perm محدودیت permission ندارد.
Provider (ماژولار و مستقل از Core)
نسخه جدید و مستقل BiProvider فقط به React 18/19 نیاز دارد. هیچکدام از
@chakra-ui/react، keycloak-js، axios، React Query یا Next.js با import زیر
بهتنهایی بارگذاری یا الزامی نمیشوند:
import { BiProvider } from "uikit/provider";
// حتی در React ساده (بدون Next، Chakra و Keycloak):
<BiProvider><App /></BiProvider>
قابلیتها کامپوننتهای پیکربندیِ مستقیم در کنار App هستند؛ BiProvider
آنها را بر اساس وابستگی و ترتیب امن مرتب و به Providerهای تودرتو تبدیل میکند.
برای جلوگیری از نصب اجباری dependencyهای اختیاری، هر قابلیت را از subpath خودش import کنید. مسیرهای پیشین uikit/provider/<feature> برای سازگاری موقت باقی ماندهاند و دقیقاً به همان فایل خروجی مسیر جدید اشاره میکنند.
ورودیها و نیازمندیهای مستقل
| قابلیت / import | کتابخانه لازم در سامانه مقصد |
|---|---|
BiProvider — uikit/provider |
react |
Keycloak — uikit/keycloak |
keycloak-js |
Permission — uikit/permission |
بدون کتابخانه اضافه (Fetch مرورگر) |
Api — uikit/api |
axios |
Query — uikit/query |
@tanstack/react-query@^5 |
Chakra — uikit/chakra |
@chakra-ui/react@^2، @emotion/react@^11، @emotion/styled@^11، framer-motion@^10/^11/^12، react-dom |
NextPagesRouter — uikit/next-pages-router |
Next.js Pages Router، next-query-params@^5.1.0، use-query-params@^2.2.2 |
NextAppRouter — uikit/next-app-router |
Next.js App Router، next-query-params@^5.1.0، use-query-params@^2.2.2 |
Vite — uikit/vite |
react-router-dom@^6 و use-query-params@^2 (برای React Router v6 و Query Params) |
SWR — uikit/swr |
swr@^2 (اختیاری؛ مستقل از TanStack Query و Api) |
Updates — uikit/update-checker |
بدون کتابخانه اضافه |
ReactDOM مانند React باید با نسخه React سامانه سازگار باشد. برای Keycloak فقط
keycloak-js نصب میشود؛ Permission مستقل است و با یا بدون Keycloak میتواند
درخواست ارسال کند. بخش <Chakra /> بهصورت پیشفرض Theme، فونت Estedad و
پیشنیازهای Remoteهای Chakra-based را مانند Core تنظیم میکند.
مثال با Next.js Pages Router
import { BiProvider } from "uikit/provider";
import { Keycloak } from "uikit/keycloak";
import { Permission } from "uikit/permission";
import { Api } from "uikit/api";
import { Query } from "uikit/query";
import { Chakra } from "uikit/chakra";
import { NextPagesRouter } from "uikit/next-pages-router";
export default function AppProviders({ children }) {
return (
<BiProvider>
<Chakra />
<Query />
<NextPagesRouter />
<Keycloak clientId="front-client" />
<Permission clientId="permission-client" />
<Api baseUrl="https://api.example.com" />
{children}
</BiProvider>
);
}
ترتیب نوشتن قابلیتها مهم نیست. ترتیب مؤثر داخلی:
Chakra → Query → SWR → Router → Keycloak → Api → Permission → App (فقط ماژولهای فعال) است.
در این حالت Keycloak ابتدا تأیید هویت میکند؛ سپس Permission با Bearer Token
درخواست میفرستد و Api interceptor احراز هویت را فعال میکند.
مثال React + Vite بدون Chakra یا Next
import { BiProvider } from "uikit/provider";
import { Keycloak, useKeycloak } from "uikit/keycloak";
function AppProviders({ children }) {
return (
<BiProvider>
<Keycloak clientId="my-react-app" />
{children}
</BiProvider>
);
}
// در کامپوننتهای فرزند:
// const { authenticated, token, login, logout, updateToken } = useKeycloak();
از نسخه 1.3.0، <Vite /> بهصورت پیشفرض BrowserRouter و QueryParamProvider همراه با ReactRouter6Adapter را با enableBatching: true میسازد. دیگر در App نباید این Providerها را جداگانه اضافه کنید. برای پروژهای که خودش یک Router خارجی دارد، router={false} و برای نداشتن Query Params، queryParams={false} قابل استفادهاند.
برای API بدون Keycloak میتوان فقط <Api baseUrl="..." /> گذاشت و داخل
کامپوننتهای فرزند const api = useApi() از uikit/api گرفت.
Permission همان context دسترسی مورد استفاده Sidebar در uikit/layout را فراهم میکند؛ hook از uikit/permission import میشود.
مثال React + Vite با React Router و SWR — نسخه 1.3.0
// src/main.jsx
import { BiProvider } from "uikit/provider";
import { Chakra } from "uikit/chakra";
import { Vite } from "uikit/vite";
import { SWR } from "uikit/swr";
import { Keycloak } from "uikit/keycloak";
import { Permission } from "uikit/permission";
import { fetcher } from "./api";
<BiProvider>
<Chakra />
<Vite />
<SWR value={{ fetcher }} />
<Keycloak clientId="agent" />
<Permission clientId="your-permission-client" />
<App />
</BiProvider>;
- داخل
App.jsxفقط<Routes>و<Route>بگذارید؛BrowserRouter،QueryParamProviderوSWRConfigرا دوباره ننویسید. Viteهمان React Router v6 و آداپتور آن را آماده میکند؛useNavigate،useLocationوuseQueryParamمانند قبل کار میکنند.SWRصرفاً SWRConfig است و بهApiنیازی ندارد. اگر از Axios مستقل استفاده میکنید، توکن آن را به Keycloak جدید متصل کنید.- برخلاف
<Query />که مخصوص TanStack است،<SWR />مخصوص SWR است؛ آنها را بدون نیاز همزمان اضافه نکنید. - این تغییر نسبت به 1.2.7 معنی
<Vite />را تغییر میدهد: اگر قبلاً Router دستی دارید، آن را حذف کنید یا از<Vite router={false} />استفاده کنید. - مسیر قدیمی
uikit/provider/viteو مسیر جدیدuikit/viteبه یک ماژول اشاره میکنند.uikit/provider/swrنیز alias مسیر جدید است. - مدیریت فونت از
<Chakra />بهصورت پیشفرض انجام میشود؛ برای انتخاب فونت UI Kit بهfonts={false}یا تم با فونت سفارشی نیازی نیست.
مثال Next.js App Router
// app/app-providers.jsx
"use client";
import { BiProvider } from "uikit/provider";
import { NextAppRouter } from "uikit/next-app-router";
export default function AppProviders({ children }) {
return (
<BiProvider>
<NextAppRouter />
{children}
</BiProvider>
);
}
// app/layout.jsx (Server Component)
// import AppProviders from "./app-providers";
// <html><body><AppProviders>{children}</AppProviders></body></html>
در App Router، فایل مصرفکننده که BiProvider و markerها را رندر میکند باید
Client Component باشد. استفاده از NextAppRouter فقط برای use-query-params
است؛ اگر از آن کتابخانه استفاده نمیکنید، اصلاً marker مربوط به Router لازم نیست.
در صورت نیاز به Suspense برای useSearchParams، boundary مناسب را در سامانه مقصد قرار دهید.
تنظیمات
Keycloak:clientIdاجباری؛urlپیشفرضhttps://auth.ibagher.ir،realm="bi"،initOptions،loading،errorFallback،onErrorوallowUnauthenticated. برای حفظ رفتار Core،onLoad="login-required"وflow="implicit"پیشفرضاند و قابل override هستند.Permission:clientIdاجباری؛urlپیشفرض endpoint دسترسی،getTokenاختیاری برای نبود توکن Keycloak،storageKeyپیشفرضpermissions:<clientId>:<user-id>،loading،errorFallbackوenabled.Api:baseUrl،auth(پیشفرضtrue)،getTokenاختیاری،onUnauthorizedوaxiosConfig؛ دریافت باuseApiدر زیردرخت همان Provider است. با Keycloak، Bearer Token اضافه و خطای 401 یکبار پس از refresh تکرار میشود.Query:clientیاdefaultOptions؛ اگر کلاینت پاس داده نشود برای هر BiProvider یک QueryClient ساخته میشود.SWR:valueدقیقاً مانند پراپSWRConfig؛ خودش Fetcher نمیسازد. اگر SWR ندارید، این ماژول را اضافه نکنید.Vite: پیشفرضrouter=trueوqueryParams=true، باbasename،routerProps،adapterوoptionsبرای سفارشیسازی. برخلاف NextPagesRouter مقدارenableBatchingرا تغییر نمیدهد؛optionsعیناً بهQueryParamProviderمنتقل میشود.Chakra:theme،fonts(پیشفرضtrue)،remoteUiEnabled(پیشفرضtrue) وremoteUiChakraProviderProps؛ Props استاندارد ChakraProvider نیز پاس داده میشوند.Updates:endpoint="/version.json"،interval=30000وmessage، اختیاری.
محدودیت عمدی: این یک معماری جدید و opt-in است؛ uikit/core و
core/BiProvider هیچ تغییری نکردهاند. Api جدید Context اختصاصی دارد؛ بنابراین
getApi() / api از uikit/core را پیکربندی نمیکند. برای API جدید از useApi()
استفاده کنید. usePermission و اکشن خروج در uikit/layout به runtime سبک قبلی
متصل میمانند. کامپوننتهای پیکربندی باید در فرزندان مستقیم BiProvider یا
داخل Fragment باشند؛ داخل کامپوننت دلخواه دیگر شناسایی نمیشوند. استفاده
همزمان از NextPagesRouter و NextAppRouter مجاز نیست.
بهروزرسانی: برای استفاده از این مسیر جدید یکبار UI Kit سامانه مقصد را
ارتقا دهید. رفتار قبلی uikit/core ثابت میماند. این بخش Provider محلی پکیج
است، نه Remote روی CDN؛ بنابراین تغییرات بعدی آن با انتشار پکیج جدید دریافت میشوند.
مرجع کامل API عمومی شش مسیر ماژولار (v1.2.1)
این بخش با خواندن src/<module>/index.jsx و امضاهای index.d.ts تهیه شده و نمونههای آن با صفحه دمو یکسان است. همه مثالها برای کپی و استفاده در سامانه مقصد هستند؛ صفحه دمو درخواست واقعی به Keycloak یا API ارسال نمیکند.
| مسیر | تمام exportهای عمومی |
|---|---|
uikit/chakra |
Chakra, defaultBiTheme |
uikit/query |
Query |
uikit/next-pages-router |
NextPagesRouter |
uikit/keycloak |
Keycloak, useKeycloak |
uikit/api |
Api, useApi, fetcher |
uikit/permission |
Permission, usePermission, Can, AdminGuard, PanelAccessGuard, createPermissionSet, checkPermission, getCachedPermissions, setCachedPermissions, clearCachedPermissions |
پیشنیاز و رفتار مشترک
- markerهای
Chakra،Query،NextPagesRouter،Keycloak،ApiوPermissionرا مستقیماً در<BiProvider>یا داخل Fragment قرار دهید، نه در کامپوننت واسطه. ترتیب اجرای Providerها راBiProviderتنظیم میکند. - همه Hookها فقط داخل فرزندان Provider متناظر و در بدنه یک React Component یا Custom Hook فراخوانی شوند.
useApiوuseKeycloakوusePermissionبدون Context متناظر خطا میدهند. - markerهای اختیاری را فقط هنگام نیاز وارد کنید؛
uikit/providerبهتنهایی وابستگیهای Chakra/Keycloak/Axios/React Query را بارگذاری نمیکند. uikit/provider/legacyوuikit/coreجداگانهاند؛ مثالهای زیر متعلق به معماری جدید هستند، نه API سراسری قدیمی.
uikit/chakra
پالت پیشفرض facebook در همه سامانهها: از نسخه 1.2.2 هر دو تم پیشفرض uikit/chakra (ماژولار) و uikit/core (قدیمی) شامل رنگهای facebook.50 تا facebook.900 هستند. اگر از تم پیشفرض استفاده میکنید، دیگر نیازی به ProjectChakraThemeProvider یا extendTheme صرفاً برای این پالت ندارید. نمونه: <Button colorScheme="facebook">تأیید</Button> یا bg="facebook.500".
کدهای پالت: 50 #E8F4F9، 100 #D9DEE9، 200 #B7C2DA، 300 #6482C0، 400 #4267B2، 500 #385898، 600 #314E89، 700 #29487D، 800 #223B67، 900 #1E355B.
توجه: اگر به <Chakra theme={customTheme} /> تم کاملاً سفارشی پاس میدهید، وجود این رنگها در آن تم به تنظیمات همان customTheme بستگی دارد. برای حفظ پالت پیشفرض از extendTheme({ ... }, defaultBiTheme) استفاده کنید.
Chakra: یک marker برای ساخت ChakraProvider با تنظیمات theme، fonts (پیشفرض true)، remoteUiEnabled (پیشفرض true)، remoteUiChakraProviderProps و props استاندارد ChakraProvider. defaultBiTheme: theme آماده پیشفرض؛ hook دیگری export نشده است.
import { Chakra, defaultBiTheme } from "uikit/chakra";
import { BiProvider } from "uikit/provider";
export default function Providers({ children }) {
return (
<BiProvider>
<Chakra
theme={defaultBiTheme}
fonts={true}
remoteUiEnabled={true}
// remoteUiChakraProviderProps={{ resetCSS: true }}
/>
{children}
</BiProvider>
);
}
// Chakra سایر props استاندارد ChakraProvider را هم میپذیرد.
// اگر ChakraProvider از قبل در برنامه هست، دوباره Chakra نسازید.
uikit/query
Query: marker برای QueryClientProvider. client?: QueryClient یا defaultOptions?: DefaultOptions میگیرد؛ اگر client ارسال نشود، instance مستقل ساخته میشود. useQuery، useMutation، useQueryClient از @tanstack/react-query هستند، نه uikit/query.
import { QueryClient, useQuery } from "@tanstack/react-query";
import { BiProvider } from "uikit/provider";
import { Query } from "uikit/query";
import { Api, useApi, fetcher } from "uikit/api";
// اختیاری: میتوانید client آماده را تزریق کنید.
const client = new QueryClient();
export function Providers({ children }) {
return (
<BiProvider>
<Query client={client} />
<Api baseUrl="https://api.example.com" />
{/* یا <Query defaultOptions={{ queries: { retry: 1 } }} /> */}
{children}
</BiProvider>
);
}
// useQuery خروجی uikit/query نیست؛ از TanStack میآید.
function Users() {
const api = useApi(); // فقط وقتی <Api /> هم فعال باشد
const { data, isPending, error } = useQuery({
queryKey: ["users"],
queryFn: () => fetcher(api, "/users"),
});
if (isPending) return <span>Loading...</span>;
if (error) return <span>Failed</span>;
return <pre>{JSON.stringify(data, null, 2)}</pre>;
}
uikit/next-pages-router
NextPagesRouter: marker برای QueryParamProvider در Next.js Pages Router. shallow و options.enableBatching هر دو به صورت پیشفرض true هستند. سایر گزینههای options به QueryParamProvider منتقل میشوند؛ در صورت نیاز میتوانید با options={{ enableBatching: false }} پیشفرض را غیرفعال کنید. از useQueryParam و StringParam در use-query-params استفاده کنید؛ اینها export مسیر UI Kit نیستند. با QueryParamProvider دستی یا NextAppRouter همزمان اضافه نشود.
// Next.js Pages Router: pages/_app.jsx
import { BiProvider } from "uikit/provider";
import { NextPagesRouter } from "uikit/next-pages-router";
import { useQueryParam, StringParam } from "use-query-params";
export default function MyApp({ Component, pageProps }) {
return (
<BiProvider>
<NextPagesRouter />
<Component {...pageProps} />
</BiProvider>
);
}
// نمونه استفاده در یک صفحه:
export function SearchFilter() {
const [q, setQ] = useQueryParam("q", StringParam);
return (
<input value={q ?? ""} onChange={(e) => setQ(e.target.value)} />
);
}
// پیشفرضها: shallow=true و enableBatching=true
// برای غیرفعالسازی batching: <NextPagesRouter options={{ enableBatching: false }} />
// NextPagesRouter فقط برای Pages Router است؛ اگر از قبل
// QueryParamProvider دارید، هر دو را همزمان اضافه نکنید.
uikit/keycloak
رفتار Hydration در نسخه 1.2.7: وقتی <Chakra /> داخل <BiProvider> ماژولار وجود دارد، تمام محتوای آن ابتدا روی سرور و در اولین رندر کلاینت null خواهد بود و پس از Mount شدن نمایش داده میشود. این محافظ همان رفتار نسخه قدیمی است و نیاز به mounted دستی در Next.js App Router ندارد. بدون Chakra، SSR همان رفتار نسخه 1.2.6 را دارد. این راهکار SSR محتوا را برای ترکیب دارای Chakra غیرفعال میکند (اثر بر SEO و HTML اولیه) و نقص خود Turbopack/Emotion را تغییر نمیدهد.
پیشفرض Loading در نسخه 1.2.5: اگر <Chakra /> در BiProvider وجود داشته باشد، Keycloak و Permission بدون نیاز به تنظیم loading یک <Spinner /> از Chakra نمایش میدهند. اگر مقدار loading صریحاً ارسال شود (حتی null)، همان مقدار اولویت دارد. بدون <Chakra />، رفتار قبلی حفظ میشود: Keycloak مقدار null و Permission متن Loading permissions... را نمایش میدهد. این دو ماژول همچنان مستقل از Chakra هستند.
<BiProvider>
<Chakra />
<Keycloak clientId={KEYCLOAK_CLIENT_ID} />
<Permission clientId={PERMISSION_CLIENT_ID} />
<App />
</BiProvider>
// نمونه سفارشی: <Keycloak clientId="..." loading={<CustomLoader />} />
// غیرفعالکردن نمایش: <Permission clientId="..." loading={null} />
Keycloak: clientId الزامی و url، realm، initOptions، loading، errorFallback، allowUnauthenticated و onError اختیاری هستند. useKeycloak() مقدارهای instance، initialized، authenticated، token، error و متدهای login(options?)، logout(options?)، updateToken(minValidity?) را برمیگرداند. پیشفرض onLoad: "login-required" و flow: "implicit" است؛ updateToken() نتیجه boolean برمیگرداند.
import { BiProvider } from "uikit/provider";
import { Keycloak, useKeycloak } from "uikit/keycloak";
export function Providers({ children }) {
return (
<BiProvider>
<Keycloak
clientId="front-client" // الزامی
// url="https://auth.example.com"
// realm="my-realm"
// initOptions={{ onLoad: "login-required" }}
loading={<span>Loading auth...</span>}
errorFallback={<span>Auth failed</span>}
onError={(error) => console.error(error)}
/>
{children}
</BiProvider>
);
}
// این Hook فقط داخل فرزندان <Keycloak /> قابل استفاده است.
export function AccountActions() {
const {
instance, initialized, authenticated, token, error,
login, logout, updateToken,
} = useKeycloak();
const refresh = async () => {
const refreshed = await updateToken(30); // boolean
return refreshed;
};
return (
<div>
<span>{authenticated ? "Signed in" : "Signed out"}</span>
<button onClick={() => login()}>Login</button>
<button onClick={() => logout()}>Logout</button>
<button onClick={refresh}>Refresh token</button>
</div>
);
}
// instance: شیء keycloak-js؛ token: مقدار لحظهای context.
// allowUnauthenticated پیشفرض false است.
uikit/api
Api: marker با baseUrl (پیشفرض "")، auth (پیشفرض true)، getToken اختیاری، axiosConfig، logoutOnUnauthorized (پیشفرض false) و onUnauthorized. useApi() یک AxiosInstance از Context میدهد و تنها در کامپوننت/هوک داخل <Api /> قابل فراخوانی است. fetcher(api, url) یک Promise از response.data میدهد. خارج از React باید instance را به service بهصورت پارامتر تزریق کرد؛ api سراسری قدیمی uikit/core با این مسیر پر نمیشود.
import { BiProvider } from "uikit/provider";
import { Api, useApi, fetcher } from "uikit/api";
export function Providers({ children }) {
return (
<BiProvider>
<Api
baseUrl="https://api.example.com"
auth={true}
// فقط اگر Keycloak توکن نداشته باشد از این تابع استفاده میشود:
getToken={() => localStorage.getItem("access_token")}
axiosConfig={{ timeout: 15000 }}
logoutOnUnauthorized={false}
onUnauthorized={(error) => console.error(error)}
/>
{children}
</BiProvider>
);
}
// فقط در React Component یا Custom Hook داخل <Api />:
export function useUsersService() {
const api = useApi(); // AxiosInstance
return {
getResponse: () => api.get("/users"), // AxiosResponse
getData: () => fetcher(api, "/users"), // response.data
create: (payload) => api.post("/users", payload),
};
}
// fetcher(api, url) دو آرگومان میگیرد، نه fetcher(url).
// useApi() را در فایل service خارج از React فراخوانی نکنید.
// api قدیمی در uikit/core، با این Provider مقداردهی نمیشود.
اولویت توکن در Api و Permission (نسخه 1.2.1): ابتدا توکن Keycloak (اگر Keycloak نصب شده و احراز هویت شده باشد، پس از تلاش برای refresh)، سپس خروجی getToken() که میتواند async باشد، و اگر هیچکدام موجود نباشد درخواست بدون هدر Bearer ارسال میشود. اگر هر دو موجود باشند getToken فراخوانی نمیشود. برای Api، auth={false} کل افزودن خودکار توکن را غیرفعال میکند. هیچیک از این دو ماژول برای اجرا نیاز اجباری به <Keycloak /> ندارند. در نبود توکن و در صورت محافظتشدن endpoint، سرور ممکن است 401 برگرداند. در سناریوی توکن خارجی و چند کاربر، برای جلوگیری از اشتراک ناخواسته cache دسترسیها، storageKey متناسب با کاربر بدهید.
uikit/permission
Permission: clientId الزامی؛ url، user، getToken (توکن بیرونی جایگزین)، storageKey، loading، errorFallback و enabled اختیاری. usePermission() مقدارهای user، permissions، isLoading، error، can(perm)، cannot(perm)، refresh() و clear() را برمیگرداند. Can محتوا/fallback را بر اساس perm نشان میدهد؛ AdminGuard محتوا را در نبود مجوز admin رندر نمیکند؛ PanelAccessGuard با نبود panel_access، تابع onNoAccess را فراخوانی یا logout میکند، ولی فرزندان را همچنان رندر میکند. forceNoAccess برای اجبار این رفتار قابل استفاده است. اینها جایگزین کنترل دسترسی سمت سرور نیستند.
import { BiProvider } from "uikit/provider";
import {
Permission, usePermission, Can, AdminGuard, PanelAccessGuard,
} from "uikit/permission";
export function Providers({ children }) {
return (
<BiProvider>
<Permission
clientId="permission-client" // الزامی
// فقط اگر Keycloak توکن نداشته باشد:
getToken={() => localStorage.getItem("access_token")}
// url="https://api.example.com/permissions/list"
// storageKey="permissions:permission-client:my-user"
loading={<span>Loading permissions...</span>}
errorFallback={<span>Permission error</span>}
/>
{children}
</BiProvider>
);
}
export function ProtectedScreen() {
const {
user, permissions, isLoading, error,
can, cannot, refresh, clear,
} = usePermission();
if (isLoading) return <span>Loading...</span>;
if (error) return <span>Could not refresh permissions</span>;
return (
<>
<button disabled={cannot("activity:read")}>Read activity</button>
{can("activity:write") && <button>Write activity</button>}
<button onClick={refresh}>Reload permissions</button>
<button onClick={clear}>Clear cache and reload</button>
<Can perm="activity:read" fallback={<span>Not allowed</span>}>
<div>Visible to permitted users</div>
</Can>
<AdminGuard><div>Admin content</div></AdminGuard>
<PanelAccessGuard onNoAccess={() => console.warn("No panel access")}>
<div>App layout</div>
</PanelAccessGuard>
</>
);
}
// PanelAccessGuard فرزندان را مخفی/مسدود نمیکند؛ فقط
// در نبود panel_access callback را اجرا یا Keycloak logout میکند.
// مجوز واقعی همیشه باید سمت سرور نیز بررسی شود.
uikit/permission — توابع کمکی
createPermissionSet(permissions) آرایه {name} را به Set<string> تبدیل میکند؛ checkPermission(permissionSet, perm) قواعد تطبیق permission و wildcard را اعمال میکند (شامل بررسی پیشوندها). getCachedPermissions(key?)، setCachedPermissions(key, permissions) و clearCachedPermissions(key?) ذخیرهسازی در localStorage را مدیریت میکنند؛ خارج از مرورگر بدون دسترسی به localStorage عمل میکنند. کلید پیشفرض توابع cache مقدار "permissions" است، اما کامپوننت Permission بهطور پیشفرض از permissions:<clientId>:<subject-or-user-id> استفاده میکند؛ بنابراین برای استفاده مستقیم، storageKey را هماهنگ وارد کنید.
import {
createPermissionSet, checkPermission,
getCachedPermissions, setCachedPermissions, clearCachedPermissions,
} from "uikit/permission";
// توابع مستقل برای بررسی یک مجموعه permission:
const set = createPermissionSet([
{ name: "activity:read" },
{ name: "reports:*" },
]);
checkPermission(set, "activity:read"); // true
checkPermission(set, "reports:download"); // true با قاعده wildcard
// ابزارهای کش صرفاً در مرورگر از localStorage استفاده میکنند.
// بهتر است کلید را دقیقاً همان storageKey تعریفشده در <Permission /> بگذارید:
const storageKey = "permissions:permission-client:my-user";
const cached = getCachedPermissions(storageKey); // array | undefined
setCachedPermissions(storageKey, [{ name: "activity:read" }]);
clearCachedPermissions(storageKey);
// این توابع جایگزین authorization سمت سرور نیستند.
// در برنامه عادی، refresh() / clear() از usePermission() مناسبتر است.
ملاحظه امنیتی:
Can،AdminGuardوcheckPermissionابزارهای نمایش/تعامل در رابط کاربریاند؛ بررسی مجوز درخواستها باید در Backend هم اجباری باشد. کلیدهای localStorage بهتنهایی اثباتکننده دسترسی نیستند.
Core
required dependencies:
yarn add @chakra-ui/react@^2
yarn add @emotion/react@^11
yarn add @emotion/styled@^11
yarn add framer-motion@^12
yarn add @tanstack/react-query@^5
yarn add axios@^1
yarn add keycloak-js
yarn add next-query-params@^5.1.0
yarn add use-query-params@^2.2.2
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 @tanstack/react-table@^8
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>
);
}
Sidebar.Exit
Sidebar بهصورت پیشفرض گزینه خروج را نمایش نمیدهد. برای فعالکردن خروج Keycloak داخلی UI Kit، آن را بهصورت compound component اضافه کنید:
<Sidebar
items={items}
currentPath={router.asPath}
linkComponent={NextLink}
>
<Sidebar.Exit />
</Sidebar>
عنوان و آیکون خروج قابل تغییر هستند:
<Sidebar.Exit title="خروج از سامانه" icon={MyExitIcon} />
Sidebar.Exit از logoutKeycloak داخلی UI Kit استفاده میکند و callback خروج از سامانه مقصد نیاز ندارد.
Sidebar active route notes
Sidebar compares currentPath with each item's path and aliases, ignoring query strings, hashes, and trailing slashes. Use the actual application route as path; use aliases only for alternate routes that should keep the same item active.
Active sidebar items are rendered as non-links to avoid redundant same-route navigations. This is especially useful on pages that synchronize URL query params.
Remote AppHeader (self-contained)
AppHeader یک remote مستقل است و برای فایل remote خودش از setupUikitRemoteDeps یا
window.__UIKIT_REMOTE_DEPS__ استفاده نمیکند.
import { AppHeader } from "uikit/remote/ui";
function ExampleAppHeader() {
return (
<AppHeader bg="#314E89">
<AppHeader.BrandSection>
<AppHeader.Logo src="/logo.png" optimize />
<AppHeader.Brand>
<AppHeader.Title>عنوان سامانه</AppHeader.Title>
<AppHeader.Description>توضیحات سامانه</AppHeader.Description>
</AppHeader.Brand>
</AppHeader.BrandSection>
<AppHeader.Extra
src="/secondary-logo.png"
text="متن دلخواه"
/>
<AppHeader.Bi optimize />
</AppHeader>
);
}
AppHeader در flow عادی صفحه باقی میماند و عرض کامل میگیرد؛ بنابراین اگر داخل VStack/Stack قرار بگیرد، محتوای بعدی زیر Header قرار نمیگیرد.
برای مشاهده قابلیت روی دمو، لوگوی PNG نمونه با ابعاد 1254×1254 از مسیر /logo.png سرو میشود. دمو به طور پیشفرض optimize را فعال میکند؛ با دکمهٔ زیر هدر میتوان PNG اصلی و نسخه بهینهشده را مقایسه کرد و وضعیت WebP/Fallback را دید. در اجرای لوکال ممکن است سرویس تصاویر به فایل روی localhost دسترسی نداشته باشد.
AppHeader.Logo بهصورت پیشفرض URL را تغییر نمیدهد. اگر optimize را پاس بدهید، فقط در مرورگر URL نسبی (مثل /logo.png) با origin همان سامانه مقصد کامل میشود، سپس processImage با ابعاد نمایش لوگو، q: 100 و webp: true صدا زده میشود. تغییر عرض نمایش (مثلاً breakpoint موبایل/دسکتاپ) باعث بروزرسانی تصویر میشود. اگر سرویس بهینهسازی خطا بدهد، لوگوی اصلی جایگزین میشود. این قابلیت به domain یا هیچ dependency اضافی در پروژه مقصد نیاز ندارد. برای استفاده از optimize باید نسخه npm/Git UI Kit حاوی این prop را در سامانه مقصد نصب کرد؛ اما سامانههای قبلی که optimize نمیدهند نیازی به آپدیت ندارند.
در نسخه 1.3.4، لوگوی AppHeader.Logo با optimize در نمایش موبایل (عرض کمتر از 62em) پدینگ ندارد؛ در دسکتاپ همان پدینگ 8px حفظ شده است. اندازه تصویر بهینهشده نیز بر اساس پدینگ واقعی محاسبه میشود. لوگوهای بدون optimize تغییری نکردهاند.
UI Kit v1.6.0 — بهینهسازی لوگوی BI: حالا AppHeader.Bi نیز پراپ اختیاری optimize دارد. همانند AppHeader.Logo، در مرورگر URL تصویر را (در صورت نیاز با origin سامانه مقصد) کامل میکند، ابعاد نمایش را با ResizeObserver اندازه میگیرد و تصویر کوچکشده WebP را از https://img.d.aiengines.ir درخواست میکند. در صورت خطای سرویس، تصویر اصلی نمایش داده میشود. اگر optimize پاس داده نشود، هیچ تبدیلی روی URL انجام نمیشود. API مستقیم biLogoOptimize نیز پشتیبانی میشود: <AppHeader biLogoOptimize biLogoSrc="..." />.
اصلاح v1.6.1 — لوگوی اصلی، بدون Thumbnail: تصویر BI از همان سورس اصلی src/assets/bi-logo.webp با ابعاد ۵۰۰×۵۰۰ استفاده میکند؛ فایل ۱۹۲×۱۹۲ bi-logo-header.webp حذف شده است. در حالت <AppHeader.Bi optimize />، درست مانند <AppHeader.Logo optimize />، تصویر اصلی به سرویس processImage ارسال میشود و نسخه متناسب با اندازه نمایش (q:100 و WebP) در لحظه درخواست میشود. در صورت خطا، همان تصویر اصلی بهعنوان Fallback نمایش داده میشود. اگر optimize نباشد، تصویر اصلی بدون کوچکسازی درخواست میشود. فایل AppHeader.js همچنان تصویر را Base64 نمیکند و سبک باقی میماند. برای استقرار نسخه پیشساخته، فایلهای dist/remote/AppHeader.js و dist/remote/bi-logo.webp را کنار هم روی سرور Remote منتشر کنید؛ در نسخه 1.6.2، خروجی نهایی build:remote با مرحله اختصاصی build-app-header-remote.mjs ساخته میشود و فایل اصلی bi-logo.webp بدون تغییر کنار AppHeader.js کپی میشود؛ Vite بهتنهایی در حالت Library فایل تصویر را Base64 میکند. تعویض پکیج بدون انتشار فایل Remote کافی نیست.
نمونه استفاده: <AppHeader.Bi optimize /> برای لوگوی پیشفرض یا <AppHeader.Bi src="/bi.svg" optimize /> برای تصویر سفارشی. در AppHeader.Bi بدون optimize و در AppHeader.Logo بدون optimize هیچ تغییری در منطق بهینهسازی اعمال نشده است. مقایسه در دمو: dist/remote/AppHeader-demo.html.
bg اختیاری است و رنگ پسزمینه پیشفرض Header را override میکند. AppHeader.Extra نیز اختیاری است و لوگو + متن دلخواه میگیرد. AppHeader.Extra و AppHeader.Bi مستقل از هم هستند و میتوان هرکدام را حذف کرد. اگر هر دو وجود داشته باشند، در انتهای Header ترتیب نمایشی Extra سپس Bi است.
فایل remote از این آدرس بارگذاری میشود:
https://uikit.d.aiengines.ir/AppHeader.js
برای AppHeader.js هیچ dependency از host تزریق نمیشود. خود remote به صورت Web Component
ایزوله با Shadow DOM اجرا میشود. تنها font-family از سامانه مقصد inherit میشود تا AppHeader
از همان فونت برنامه استفاده کند؛ سایر استایلها همچنان ایزوله هستند. مسیر React wrapper فقط
react خود برنامه را برای mount کردن custom element استفاده میکند و هیچ وابستگی به Chakra ندارد.
AppHeader local preview
برای دیدن remote/ui/AppHeader قبل از انتشار:
yarn install
yarn dev
سپس آدرس Vite که در ترمینال نمایش داده میشود (معمولاً http://localhost:5173) را باز کنید. در حالت dev، همان سورس src/remote/ui/AppHeader/AppHeader.remote.jsx بهصورت remote لوکال لود میشود.
Remote AppSidebar
AppSidebar is an isolated desktop sidebar. Its visual layer lives inside Shadow DOM and does not depend on Chakra, Tailwind, router, permission or authentication packages from the host. The host supplies the menu data and application logic.
Prefer the dedicated entry so projects that only need AppSidebar do not load the Chakra-oriented remote setup used by older components:
import { AppSidebar } from "uikit/remote/ui/AppSidebar";
<AppSidebar
items={[
{
id: "home",
title: "عنوان آیتم",
mobileTitle: "عنوان کوتاه",
icon: <YourSvgIcon />,
active: true,
onClick: () => navigate("/home"),
},
]}
>
<AppSidebar.Exit onClick={logout} />
</AppSidebar>
Permission and routing decisions belong to the host. Filter inaccessible items before passing them, or pass disabled: true when the disabled state should remain visible.
متن AppSidebar.Exit داخل خود UI Kit ثابت و همیشه «خروج» است؛ Host فقط callback و در صورت نیاز disabled را پاس میدهد.
AppSidebar responsive behavior
On widths below the desktop breakpoint (62em), AppSidebar renders a fixed bottom navigation bar:
- Up to 4 visible items: all items are shown directly; when
AppSidebar.Exitis enabled, exit is the final direct item and there is no More button. - More than 4 visible items: the first 4 items stay in the bottom bar; More is added as the fifth slot; item 5 onward plus
AppSidebar.Exitare rendered in the bottom drawer. hiddenitems are excluded before this count is calculated.
The host remains responsible for route, permission and logout logic.
Pagination
remote/ui/Pagination چهار حالت نمایشی دارد و قرارداد props در همه آنها یکسان است:
full
compact
simple
minimal
حالت minimal فقط نحوه نمایش را سادهتر میکند. همه variantها API یکسان دارند و loading نیز یک prop اختیاری است:
import { Pagination } from "uikit/remote/ui";
<Pagination
level="minimal"
currentPage={page}
totalPages={totalPages}
totalCount={totalCount}
pageSize={10}
loading={isLoading}
onPageChange={setPage}
/>
اگر loading پاس داده نشود، رفتار Pagination مانند قبل است.
loading=trueوtotalPages/totalCountهنوز در دسترس نیستند: صفحه جاری1است و جای مقادیر نامشخص loader نمایش داده میشود.loading=trueو totals قبلاً موجودند: totals ثابت میمانند و فقط صفحه جاری تا رسیدن پاسخ جدید loader نمایش میدهد.- در جابهجایی بین صفحات، اگر loader داخل دکمه صفحه جاری نمایش داده شود، spinner سفید است تا روی پسزمینه active خوانا بماند.
Deployed remote demo
The production build now also creates a static preview at dist/remote/index.html.
Because the Docker server already serves dist/remote as its document root, opening
https://uikit.d.aiengines.ir/ shows the UI Kit preview instead of a directory listing.
The remote module URLs stay unchanged, for example /AppHeader.js, /AppSidebar.js,
/Pagination.js, and /GBadge.js.
AppHeader.Extra بدون متن
اگر text پاس داده نشود، فقط لوگو نمایش داده میشود و تصویر تمام ارتفاع قابلاستفادهی AppHeader.Extra را میگیرد.
Remote SegmentedSelector (Chakra-independent)
SegmentedSelector is served from https://uikit.d.aiengines.ir/SegmentedSelector.js.
Its visual implementation, option selection and tooltips live in Shadow DOM; the
remote relies only on host React, ReactDOM (createRoot) and the inherited font.
It does not import Chakra, Emotion, icon packages, or other host dependencies.
Releasing a compatible update to SegmentedSelector.js updates consuming applications
on their next remote module fetch (subject to browser/CDN caching), without rebuilding
those applications.
Use either uikit/remote/ui or uikit/remote/ui/SegmentedSelector:
import { SegmentedSelector } from "uikit/remote/ui";
const items = [
{ value: "all", title: "همه", icon: GridIcon },
{ value: "users", title: "کاربران", tooltip: "لیست کاربران", icon: UsersIcon },
{ value: "reports", title: "گزارشها", icon: ReportsIcon, isDisabled: true },
];
function Example() {
const [selected, setSelected] = React.useState("all");
return (
<SegmentedSelector
items={items}
mode="text"
value={selected}
onChange={setSelected}
/>
);
}
- White outlined rail, 36px default height on mobile and desktop, 8px radius,
36×28px icon buttons; responsive
w/haccept{ base, lg }and numeric spacing values use 4px units.fullWidthstretches the rail. showTooltip={false}hides the built-in hover/focus tooltip.selectionMode="options"(default) usesaria-pressed;selectionMode="tabs"uses tab semantics and RTL-aware arrows/Home/End, skipping disabled items.renderItem(element, item, index)can wrap the supplied React button element, but any third-party wrapper that needs React context from the parent tree will not receive it across the independent remote React root.- Styling overrides should use plain CSS
style; Chakra-onlysxand theme-token shorthands are not available without Chakra. - The demo source uses the exact same remote module as deployments. Run
npm install && npm run devto test locally, or build and servedist/remote.
Provider ماژولار و مهاجرت ایمن از core/BiProvider
برای سامانه قدیمی که نباید هیچ رفتاری عوض شود: فقط مسیر import را تغییر دهید:
-import { BiProvider } from "uikit/core";
+import { BiProvider } from "uikit/provider/legacy";
کد JSX قبلی، تمام props قدیمی (apiBaseUrl, keycloakClientId, permissionClientId,
updateChecker, theme, ...) و تمام importهای دیگر از uikit/core بدون تغییر
باقی میمانند. مسیر provider/legacy فقط نسخه اصلی و دستنخورده core/BiProvider
را re-export میکند؛ این روش از همان Keycloak singleton، Axios instance، React
Query client، Permission cache/guards، Chakra theme، Fonts و Next Pages adapter
استفاده میکند. وابستگیهای قدیمی نیز همچنان لازماند.
برای سامانه جدید Vite/React/Next با استفاده انتخابی از قابلیتها:
import { BiProvider } from "uikit/provider";
import { Keycloak } from "uikit/keycloak";
import { Permission } from "uikit/permission";
import { Api } from "uikit/api";
export function Providers({ children }) {
return (
<BiProvider>
<Keycloak clientId="my-app" />
<Permission clientId="my-app" />
<Api baseUrl="https://api.example.com" logoutOnUnauthorized />
{children}
</BiProvider>
);
}
uikit/provider خودش فقط React را import میکند و نیازی به Chakra، Next.js،
Axios یا Keycloak ندارد. هر قابلیت فقط از ورودی مستقل خودش import میشود؛ Api
از useApi() و Keycloak از useKeycloak() پشتیبانی میکنند. Permission
از همان React-only PermissionContext مشترک با layout استفاده میکند؛ اما توابع
قدیمی getKeycloakToken, api و usePermissionsQuery در uikit/core به instance
و ماژولهای قدیمی وصل میمانند؛ برای همین نمیتوان با جایگزینی صرف BiProvider
ماژولار، مصرفکنندههای قدیمی این توابع را بدون تغییر نگه داشت. برای مهاجرت
صفر-تغییر از مسیر provider/legacy استفاده کنید.
Permission جدید با fetch مستقل است، cache جداگانه بر اساس شناسه client و
کاربر دارد، refresh, clear, AdminGuard و PanelAccessGuard را ارائه میدهد.
Api جدید هنگام 401 یکبار تلاش به تمدید توکن میکند؛ logout اختیاری و با
logoutOnUnauthorized فعال میشود. در حالت Legacy رفتار 401، logout و cache
دقیقاً همان نسخه قدیمی است.
Provider عمومی RemoteUi حذف شده است؛ wrapperهای Remote خودشان بارگذاری لازم را
انجام میدهند. فایلهای Remote قبلی و uikit/core بدون تغییرند.
محدودیت مهم: یک مسیر ورود نمیتواند همزمان هم بدون هیچ وابستگی اختیاری بماند
و هم تمام توابع سراسری core را بدون تغییر و بدون استفاده از پیادهسازی قدیمی
پشتیبانی کند. به همین دلیل دو ورودی مستقل برای این دو قرارداد تعریف شده است.
تغییر مسیر import در نسخه 1.2.0
import { BiProvider } from "uikit/provider";
import { useApi, fetcher } from "uikit/api";
import { useKeycloak } from "uikit/keycloak";
import { usePermission } from "uikit/permission";
تمام مسیرهای جدید و مسیرهای قدیمی سازگار در فایل MIGRATION_1.2.0.md فهرست شدهاند.
Query Params — مقادیر پیشفرض سه Router (v1.3.0)
برای <Vite />، <NextPagesRouter /> و <NextAppRouter />، مقدار پیشفرض options.enableBatching اکنون true است. هر سه خودشان QueryParamProvider دارند؛ نباید Provider دستی دوباره اضافه شود.
<Vite /> // React Router 6 + QueryParamProvider، batching=true
<NextPagesRouter /> // Next.js Pages Router، shallow=true و batching=true
<NextAppRouter /> // Next.js App Router، batching=true
// در صورت نیاز هر کدام را جدا میتوان غیرفعال کرد:
<Vite options={{ enableBatching: false }} />
<NextPagesRouter options={{ enableBatching: false }} />
<NextAppRouter options={{ enableBatching: false }} />
options ارسالی با مقدار پیشفرض merge میشود؛ سایر optionهای use-query-params حفظ میشوند. فقط یکی از Routerهای متناسب با نوع سامانه را استفاده کنید.
Remote UI persistence (v1.3.3)
AppSidebar now updates the active item in place without destroying icon React roots on route changes when the item structure is stable. AppHeader skips DOM reconstruction for identical property updates. Keep the destination application's AppShell mounted across client-side navigation. The remotely hosted /AppHeader.js and /AppSidebar.js must also be deployed; installing the npm package alone does not update independently hosted scripts. See REMOTE_PERSISTENCE_1.3.3.md.
Watermark — UI Kit v1.8.0 (WM-v6 Numeric5)
این ماژول، نسخه React کتابخانه forensic_watermark_frontend_sdk را بهصورت اختیاری و مستقل از بخشهای دیگر در UI Kit ارائه میکند. ابزار Python Decode عمداً به UI Kit اضافه نشده است.
همراه Keycloak داخل BiProvider
import { BiProvider } from "uikit/provider";
import { Keycloak } from "uikit/keycloak";
import { Watermark } from "uikit/watermark";
function Providers({ children }) {
return (
<BiProvider>
<Keycloak clientId={KEYCLOAK_CLIENT_ID} />
<Watermark />
{children}
</BiProvider>
);
}
نصب سراسری یکباره: Watermark را در بالاترین BiProvider که با جابهجایی صفحات و تبها حفظ میشود قرار دهید. در هیچ صفحه، هدر، سایدبار، تب یا کامپوننت دیگری نباید آن را تکرار کنید. Canvas به document.body اضافه میشود و با ناوبری معمول Client-Side در سامانه باقی میماند. خروج از نشست، تغییر کاربر، Unmount/Refresh کامل باعث بازنشانی چرخه آن میشود.
Watermark فقط یک feature marker است و باید فرزند مستقیم BiProvider (یا داخل Fragment مستقیم آن) باشد. ترتیب تعریف markerها در JSX مهم نیست؛ UI Kit ماژول Keycloak (اولویت ۴۰)، Permission (۶۰) و Watermark (۶۵) را به ترتیب ترکیب میکند. این ماژول به <Api />، <Permission />، <Chakra />، <Query /> یا <Vite /> وابسته نیست و هیچ Axios instance یا Client Context متعلق به سامانه مقصد را نمیخواند. در صورت وجود Keycloak، توکن معتبر آن استفاده میشود. توکن در Canvas رمزگذاری یا ذخیره نمیشود.
توکن خارجی در نبود Keycloak
import { BiProvider } from "uikit/provider";
import { Watermark } from "uikit/watermark";
<BiProvider>
<Watermark
getAccessToken={getAccessToken}
sessionKey={currentUserId}
onError={(error) => reportSafeError(error)}
/>
<App />
</BiProvider>
میتوان بهجای getAccessToken از پراپ getToken نیز استفاده کرد. اولویت انتخاب توکن Keycloak معتبر → توکن خارجی → بدون درخواست است. اگر هیچ توکن معتبری وجود نداشته باشد، واترمارک ساخته نمیشود و onError فراخوانی میشود. تابع getAccessToken باید توکن را در لحظه برگرداند، نه مقدار ثابت قدیمی. بدون Keycloak، هنگام تعویض کاربر یا نشست، مقدار sessionKey را تغییر دهید. فقط تغییر مقدار توکن در Storage، بدون تغییر sessionKey، خودبهخود باعث درخواست مجدد نمیشود.
کامپوننت مستقیم React؛ بدون BiProvider
import { ForensicWatermark } from "uikit/watermark";
function Application({ getAccessToken, currentUserId }) {
return <>
<ForensicWatermark
getAccessToken={getAccessToken}
sessionKey={currentUserId}
/>
<App />
</>;
}
ForensicWatermark فقط با React و Web APIs استاندارد اجرا میشود. getAccessToken برای استفاده مستقیم الزامی است. هنگام enabled={false} یا Unmount، Canvas حذف و درخواست جاری لغو میشود. در BiProvider، Logout نیز از طریق حذف زیردرخت Keycloak باعث cleanup میشود.
API و رفتار خطا
| Prop | کاربرد | پیشفرض |
|---|---|---|
enabled |
فعال/غیرفعال کردن واترمارک | true |
getAccessToken / getToken |
تابع دریافت توکن خارجی (در حالت مستقل فقط getAccessToken) |
بدون مقدار |
sessionKey |
کلید نشست برای تغییر کاربر و حذف واترمارک قبلی | بدون مقدار |
userUrl |
آدرس API دریافت شناسه کاربر | https://api.d.aiengines.ir/user_api/v1/users/my_user |
version |
نسخه الگوریتم: 6 (WM-v6 Numeric5)، 5 (WM-v5 Numeric5)، و 4، 3، 2 برای UUID قدیمی |
6 |
spatialProfile |
legacy (پیشفرض)، webp-research برای نسخههای ۵/۶ و multi-scale فقط برای نسخه ۶ (تحقیقاتی) |
legacy |
opacity |
شفافیت نقش؛ فقط مقادیر 0 < opacity <= 0.08 |
برای همه نسخهها 0.014 |
onReady |
پس از رسم موفق Canvas | — |
onError |
خطا در توکن، شبکه، شناسه یا Canvas | — |
blockUntilReady |
فقط Watermark در BiProvider: توقف رندر محتوای فرزندان تا آمادهشدن واترمارک | false |
onStatusChange |
فقط ForensicWatermark: مقدارهای loading, ready, error, disabled |
— |
در حالت پیشفرض، خطا در واترمارک مانع نمایش محتوا نمیشود. اگر blockUntilReady فعال شود، در خطا نیز محتوا نمایش داده نمیشود تا مشکل برطرف شود؛ حالت بازیابی و UI خطا را باید متناسب با محصول طراحی کرد. این گزینه کنترل سمت سرور را جایگزین نمیکند.
تاریخچه نسخه 1.7.0 (SDK 0.2.1): بهصورت پیشفرض WM-v3.1-luma-spread-fec با version={4} و opacity=0.014 رسم میشود. الگوی نسخه ۴ با Decoder نسخه ۳ سازگار نیست؛ قبل از ارتقای سامانههای مقصد، دیکودر بکاند را برای wire version 4 آماده کنید. نسخههای ۳ و ۲ همچنان قابل انتخاب هستند؛ پیشفرض opacity هر دو 0.014 است. برای حفظ خروجی دقیق پیشفرض UI Kit 1.6.2 از <Watermark version={3} opacity={0.03} /> استفاده کنید. مقدار opacity صریح اولویت دارد. در نسخه 1.8.0، تغییر version شناسه را دوباره از API میگیرد تا نوع UUID یا Numeric5 درست انتخاب شود.
دیکودرِ مستقلِ سامانه باید با نسخه انتخابی واترمارک (بهصورت پیشفرض wire version 6) سازگار باشد؛ این بسته شامل Decoder نیست. اعتبار CRC/FEC دلالت بر هویت فرد منتشرکننده یا اصالت تصویر ندارد.
نمونه فعالسازی نسخه و بازگشت به قالب قبل
// پیشفرض: WM-v6 Numeric5 / version=6 / opacity=0.014
<Watermark />
// WM-v5 Numeric5 (numeric_id از API)
<Watermark version={5} />
// WM-v6 با spatial profile آزمایشی؛ پیشفرض legacy است
<Watermark version={6} spatialProfile="webp-research" />
// بازگشت به الگوریتم v3، شفافیت جدید SDK
<Watermark version={3} />
// رفتار قبلی UI Kit 1.6.2 از نظر نسخه و شفافیت
<Watermark version={3} opacity={0.03} />
// بازگشت به WM-v2
<Watermark version={2} />
// مستقل از BiProvider؛ WM-v6
<ForensicWatermark getAccessToken={getAccessToken} sessionKey={userId} />
در نسخه پیشفرض ۶ و نسخه ۵، شناسه باید از response.attributes.numeric_id[0] بهشکل رشته دقیقاً پنجرقمی ASCII (مثلاً "00042") دریافت شود؛ اگر این مقدار نامعتبر یا غایب باشد onError اجرا میشود و هیچ fallback به UUID یا شناسه ساختگی رخ نمیدهد. در نسخههای ۲، ۳ و ۴، response.id باید UUID معتبر باشد. الگوریتم Codec و الگوی Canvas از SDK ارسالی حفظ شدهاند. این ابزار آزمایشی و قابل حذف با DevTools است؛ اطلاعات UUID از اسکرینشات قابل بازیابیاند و واترمارک اثبات نمیکند چه کسی تصویر را گرفته یا منتشر کرده است. برخی حالتهای fullscreen/iframe، crop، فشردهسازی و عکس از نمایشگر ممکن است بازیابی را مختل کنند. در هر سامانه یک Watermark نصب کنید؛ استفاده از چند Canvas موازی توصیه نمیشود.
انتشار: ماژول داخل خود پکیج uikit/watermark قرار دارد و به انتشار فایل روی سرور Remote UI نیاز ندارد. بعد از انتشار تگ v1.8.0 و نصب در سامانه مقصد، از این مسیر import کنید.
همگامسازی WM-v6 Numeric5 در UI Kit v1.8.0
در UI Kit نسخه ۶ پیشفرض است؛ برخلاف خود کامپوننت SDK ارسالی که همچنان version=5 را پیشفرض گذاشته بود. این انتخاب مطابق درخواست محصول است. در هر نشست واقعی، پس از دریافت توکن Keycloak یا توکن خارجی، همان درخواست GET /user_api/v1/users/my_user زده میشود؛ برای نسخه ۶/۵، فقط attributes.numeric_id[0] خوانده و به صورت Numeric5 کدگذاری میشود (بدون مولد شناسه، mock یا fallback). برای ۲/۳/۴ پروتکل UUID قدیمی پابرجاست. تغییر version باعث Abort درخواست قدیمی و دریافت مجدد شناسه متناسب با نسخه جدید میشود و Canvas قدیمی پاکسازی میشود.
src/watermark/codec.js, v3.js, v31.js, short8.js, v6.js, identity.js, render.js از نظر محتوا مطابق SDK جدید هستند. spatialProfile="legacy" حالت پایدار پیشفرض است. دو گزینه webp-research و multi-scale مخصوص تحقیقات SDK هستند و بدون آزمون واقعی مرورگر/دیکودر نباید در محیط عملیاتی فعال شوند. پیادهسازی Keycloak، BiProvider، مدیریت نشست، خطا و Canvas متعلق به UI Kit حفظ شده است. ابزارهای تولید دیتاست، Decoder پایتون، Benchmark، Screenshot، UI آزمایشی و کد Mock SDK منتقل نشدهاند.
تاریخچه: ارتقای واترمارک به WM-v3.1 در v1.7.0
src/watermark/v31.js و نسخههای جدید v3.js و render.js عین سورس SDK 0.2.1 هستند. codec.js تغییر نکرده و Python Decoder، benchmark، automation و رابط آزمایشی SDK به UI Kit افزوده نشدهاند. قابلیتهای سراسری Keycloak، توکن خارجی، sessionKey، Abort، حذف Canvas و blockUntilReady حفظ شدهاند. تست خوانایی نسخه ۴ در اسکرینشاتهای واقعی موبایل و تمهای سامانه مقصد الزامی است؛ نامحسوسی و بازیابی صددرصدی تضمین نمیشوند.
اصلاح v1.6.2 — جلوگیری از Base64 در Build واقعی AppHeader
در حالت build.lib در Vite، حتی با assetsInlineLimit: 8192 نیز تصویر BI در JavaScript جاسازی میشد و حجم AppHeader.js بعد از build:remote دوباره به حدود ۹۵ کیلوبایت میرسید. اکنون build:remote در انتها اسکریپت scripts/build-app-header-remote.mjs را اجرا میکند تا خود هدر بهصورت Remote مستقل از سورس ساخته شود و فایل اصلی src/assets/bi-logo.webp بایتبهبایت به dist/remote/bi-logo.webp منتقل شود. خروجی نهایی به Image Base64 وابسته نیست. برای انتشار باید هم dist/remote/AppHeader.js و هم dist/remote/bi-logo.webp روی سرور قرار گیرند.
Remote TabSelector
Update uikit and import directly; no Provider or extra UI dependencies are required:
import { useState } from 'react';
import { TabSelector, SegmentedSelector } from 'uikit/remote/ui';
function Tabs() {
const [value, onChange] = useState('all');
return <TabSelector value={value} onChange={onChange} items={[
{ id: 'all', desktopTitle: { title: 'همه', subtitle: 'تمام موارد' }, count: 12 },
{ id: 'users', label: 'کاربران', count: 0 },
]} />;
}
TabSelector supports mobile/desktop titles, caller-supplied icons, counts/formatCount, compact density, RTL/LTR keyboard navigation and disabled items. Styles are isolated in Shadow DOM; the font is inherited. The controlled value and routing remain with the caller. Both selectors have interactive examples in the demo page. The remote files must be deployed together with this package release.