Zid MUI: ابنِ شاشات تطبيقك المضمّن بمظهر لوحة التاجر نفسه

ما هي Zid MUI

Zid MUI هي مكتبة واجهات زد. مبنية على نظام التصميم MUI وتلتزم بإرشادات هوية زد، وتضم مكوّنات وأيقونات وhooks وأدوات للثيم، حتى تبدو المنتجات المبنية لزد متسقة في الشكل والسلوك.

ويوصي التوثيق بها في حالة محددة: إذا كنت تبني تطبيقًا مضمّنًا يعمل داخل لوحة تحكم التاجر في زد، فاستخدم أحد خيارات Zid MUI حتى تبقى شاشاتك متسقة مع نظام تصميم زد. ويعدّد التوثيق ما تحصل عليه:

• مظهر زد نفسه في كل تكاملات الشركاء.
• مكوّنات جاهزة تتبع إرشادات هوية زد.
• عمل أسرع على الواجهة، لأن الأنماط الشائعة مبنية مسبقًا.
• دعم الاتجاه من اليمين إلى اليسار (RTL) مباشرة.

الحزمة اسمها @zidsa/zidmui على npm، برخصة MIT. وكل مكوّن موثّق بأمثلة حيّة في Storybook الخاص بـ Zid MUI على ui.zid.sa.

الإعداد مع React

نسخة React هي مكتبة المكوّنات الكاملة مع تكامل MUI. ثبّتها مع الاعتماديات المطلوبة معها:

pnpm add @zidsa/zidmui react react-dom use-debounce @mui/material @mui/lab @emotion/styled

وقت كتابة هذا المقال، الإصدار الحالي (3.3.1) يتطلب React 19.2 وMUI 7 (@mui/material و@mui/lab) وuse-debounce 10، فراجع إصدارات مشروعك قبل إضافتها. ثم غلّف تطبيقك بـ ThemeProvider من MUI مع ثيم زد. ولكل مكوّن وأيقونة وhook مسار استيراد خاص، فلا تستورد إلا ما تستخدمه:

import { ThemeProvider, CssBaseline } from '@mui/material';
import { themeParcel } from '@zidsa/zidmui/theme/theme';

const App = ({ children }) => {
  return (
    <ThemeProvider theme={themeParcel}>
      <CssBaseline />
      {children}
    </ThemeProvider>
  );
}

// Each component, icon and hook has its own import path
import { AppButton } from '@zidsa/zidmui/components/app-button';
import { AppInputBase } from '@zidsa/zidmui/components/app-input-base';
import { IconSearchLine } from '@zidsa/zidmui/icons/system/search-line';
import { useToggle } from '@zidsa/zidmui/hooks/use-toggle';

كيف يعمل الثيم

themeParcel ثيم MUI عادي، فكل ما داخل الـ provider يأخذ ألوان زد وخطوطها وظلالها وأنماط مكوّناتها. وهذه تفاصيل من الحزمة نفسها:

• الخطوط: تبدأ قائمة الخطوط بـ IBM Plex Sans Arabic، وهو الخط نفسه الذي يطلب التوثيق تحميله في مشاريع CSS فقط.
• الشكل: نصف قطر الحواف الأساسي 8px.
• الوضع الداكن: تصدّر الحزمة أيضًا themeParcelDark من @zidsa/zidmui/theme/theme.dark.
• متغيرات CSS: تعرّف ملفات الأنماط متغيرات مثل --zid-color-primary-600 و--zid-radius-md، وقيم الوضع الداكن تحت [data-theme="dark"].

مكوّنات تستحق أن تعرفها

معظم مكوّنات React تبدأ بالبادئة App. وأكثر ما ستحتاجه غالبًا في التطبيق المضمّن:

• الإجراءات: AppButton وAppIconButton.
• النماذج: AppInputBase وAppInputBaseSearch وAppCheckbox وAppRadioGroup وAppInputRadioCard وAppSwitch وAppSwitchGroup.
• التخطيط والمحتوى: AppCard وAppAccordion وAppTabs وAppListItem وAppTypography، ومساعدا التخطيط StackRow وStackColumn.
• التنبيهات والحالات: AppAlert وAppStatus وAppEmptyState وAppDialog وAppTooltip وAppPagination.
• الـ Hooks: useToggle وuseDebounceState وusePaginatedData وuseCustomEventListener.

يحصر AppButton اللون والنمط في التركيبات التي يدعمها نظام التصميم. مثلًا color="primary" يقبل variant="contained" فقط، وcolor="secondary" يقبل text أو outlined. وسينبّهك فحص الأنواع في محررك إذا استخدمت تركيبة غير مدعومة.

وإلى جانب المكوّنات، تضم المكتبة أيقونات مصنّفة (system وarrows وbusiness وfinance وغيرها)، ورسومات توضيحية، وشعارات زد وشعارات الدفع والشحن. تصفّحها في Storybook قبل أن ترسم أيقوناتك.

لا تستخدم React؟ استخدم نسخة CSS فقط

لمشاريع Vue أو Angular أو JavaScript العادي أو أي تقنية أخرى، توفر Zid MUI ملفات CSS خالصة فيها متغيرات التصميم وكلاسات المكوّنات. ثبّت الحزمة:

pnpm add @zidsa/zidmui

في ملف الأنماط، السطر @import '@zidsa/zidmui/styles/index.css'; يحمّل كل شيء. ولتحميل ما تحتاجه فقط، استورد ملفات منفردة بدلًا منه، مثل styles/colors.css وstyles/typography.css وstyles/components/button.css وstyles/components/input.css. ثم حمّل خط IBM Plex Sans Arabic واستخدم كلاسات المكوّنات في الـ HTML:

<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans+Arabic:wght@400;500;600;700&display=swap" rel="stylesheet">

<button class="zid-button zid-button--contained zid-button--primary zid-button--md">
  Submit
</button>

<div class="zid-input zid-input--md zid-input--error">
  <input type="text" class="zid-input__field" placeholder="Email" />
</div>
<span class="zid-input-helper zid-input-helper--error">Invalid email</span>

كيف تركّبها في تطبيقك المضمّن

تغطي Zid MUI شكل تطبيقك. أما طريقة تحميله داخل اللوحة فيغطيها دليل Embedded Apps، والاثنان مطلوبان:

• تحمّل زد رابط التطبيق (Application URL) داخل iframe وتضيف إليه المعامل language، مثل ?token=...&language=en. ومن الممارسات الجيدة أن تضبط لغة الصفحة واتجاهها بناءً عليه، حتى تظهر الشاشات العربية من اليمين إلى اليسار.
• كل صفحة تُعرض داخل الـ iframe ما زالت تحتاج Headers CSP الواردة في دليل Embedded Apps، ومنها frame-ancestors، وإلا ستحجبها اللوحة.
• أبقِ access_token وauthorization على الـ Server. طبقة الواجهة يجب ألا تستلمهما أبدًا.

وقبل أن ترسل التطبيق للمراجعة، افتحه داخل اللوحة على المتجر التجريبي وقارنه بالشاشات الأصلية حوله، بالعربية والإنجليزية.