Mohamadzadeh 65faa63059
All checks were successful
Build and Deploy Next.js + Nginx Docker Image / build-and-deploy (push) Successful in 50s
Build and Deploy Next.js + Nginx Docker Image / deploy (push) Successful in 7s
v1.9.1 — Fix TabSelector Bar Height to 36px
2026-11-21 11:48:02 +03:30
2026-07-09 13:34:48 +03:30
2026-10-19 17:27:38 +03:30
2026-06-11 18:49:00 +03:30
2026-10-27 13:55:26 +03:30
2026-07-09 16:33:43 +03:30
2026-10-03 13:49:35 +03:30
2026-10-25 19:17:00 +03:30
2026-09-01 18:17:08 +03:30

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.Exit is 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.Exit are rendered in the bottom drawer.
  • hidden items 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/h accept { base, lg } and numeric spacing values use 4px units. fullWidth stretches the rail.
  • showTooltip={false} hides the built-in hover/focus tooltip.
  • selectionMode="options" (default) uses aria-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-only sx and theme-token shorthands are not available without Chakra.
  • The demo source uses the exact same remote module as deployments. Run npm install && npm run dev to test locally, or build and serve dist/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.

Description
No description provided
Readme 14 MiB
v1.9.1 Latest
2026-11-21 08:18:23 +00:00
Languages
JavaScript 85%
HTML 12.4%
Python 2.6%