Skip to Content
التصميم

تكامل المكونات

عقد التكامل العام لمشاركة مكونات Qokit، والأنماط، وSkin، ورموز التصميم.

تكامل المكونات

تستخدم Qokit نموذج "الهيكل المشترك + وصفات Skin". تعتمد الأطراف المتكاملة الخارجية على العقود الدلالية والتفاعلية للمكونات، وتقوم بتكييف المظهر البصري عبر Skin والرموز (Tokens).

2026-10-20 · إجراءات مستقلة لبطاقات الاختيار المرئي

تقبل خيارات EditorVisualChoiceGroup قيمة accessory اختيارية لقوائم البطاقات أو محررات الأسماء المستقلة. يضعها RadioGroup المشترك بجانب التسمية الأصلية، فلا تؤدي إدارة البطاقة إلى تحديد زر الاختيار. تضيف afterOptions إجراء فهرس مستقلاً، مثل إنشاء بطاقة، بعد الخيارات. يحتفظ المضيف بمسؤولية الحفظ والأذونات والتحقق والتركيز بعد استبدال البطاقة أو حذفها. وتحافظ الخيارات دون إضافات على بنيتها وسلوكها.

17-10-2026 · حركة لوحة العمل المشتركة

يرسم EditorWorkbenchChrome المسارات المدخلة للبداية/النهاية عبر BuilderWorkbenchFrame، وهي هيكل اللوحة نفسه المستخدم في Creator وتحرير المحتوى. توفر المضيفون المحتوى وتفضيلات الظهور والعرض. يتتبع سطح المكتب ويشارك شفافية اللوحة وترجمتها --qk-sidebar-motion-duration و--qk-sidebar-motion-easing؛ ويعطل السحب الانتقالات، ويحول وضع تقليل الحركة فوراً.

تبقى اللوحات المطوية مُثبتة للحفاظ على المسودات. تطبق الإطار المشترك فوراً inert وaria-hidden، بينما يكمل مظهر المنصة الخروج قبل إخفاء الظهور. تحتفظ اللوحات المدمجة بهندستها فوقية طوال عملية الخروج؛ ولا يجب أن تضيف المضيفون hidden أو display: none إلى غلاف اللوحة. تحافظ لوحات الإلقاء الصريحة على سلوك الكشف التفاعلي الحالي الخاص بها. تبقى خيارات الرأس متاحة عبر الحالات المفتوحة/المغلقة؛ استخدم EditorPanelChoiceShortcuts.mobileMenu عندما يجب أن تشارك وجهات الهاتف قائمة واحدة.

17-10-2026 · افتراضيات المحرر المقاسة

يقبل useWorkspaceResponsiveProfile خياراً لـ onWidthChange(width)، مُبلغاً عن نفس عرض منطقة العمل المتاحة المستخدم لملفات تعريف الاستجابة بعد خصم الحشو الداخلي. استخدم استدعاءً مستقلاً لاستنتاج افتراضيات متناسبة دون إضافة مراقب آخر. يطبق useEditorLayout sharedWidths.limits على تفضيلات المضيف وكذلك تخزين العرض المشترك؛ ويقبل readEditorLayout نفس الحدود كحجة رابعة اختيارية. يحتفظ المتصلون الحاليون بحدودهم وسلوكهم الافتراضي.

2026-09-30 · إمكانية الوصول في SelectionToolbar

يمكن لـ SelectionToolbar.ariaLabel تسمية شريط الأدوات كمنطقة بشكل اختياري. يظل العدد رسالة حالة حية. يوفر التطبيق المضيف تسميات مترجمة، ويمكنه استخدام actionContent لدمج المكوّنين المشتركين EditorToolGroup وActionMenu؛ وتبقى عمليات التحقق من الأذونات ومعالجات الإجراءات ضمن مسؤولية المضيف.

2026-09-10 · شارات هوية مساحة العمل

يقبل ProjectSwitcherProject.badge محتوى React اختياريًا وغير تفاعلي. تظهر الشارة بجانب اسم كل عنصر، وفي صف السياق الحالي غير المدرج، وبجوار الاسم الحالي في المشغّل النصي. تظل المشغّلات ذات الأيقونة فقط مضغوطة؛ وتخفي مشغّلات المنصة النصية الشارة بعرض الهاتف للحفاظ على مساحة اسم مساحة العمل. تستمر القائمة المفتوحة في عرض الشارة. يوفّر المضيف بيانات ذات نطاق صحيح وتسميات مترجمة وأنماط عرض؛ ويؤدي حذف الحقل إلى الاحتفاظ بالمظهر الحالي.

2026-09-08 · EmptyState

يوسّط EmptyState الرمز الزخرفي الاختياري icon وtitle والوصف الاختياري description وaction على سطح شفاف. layout="section" هو الافتراضي المدمج، وlayout="workspace" يحجز مساحة أكبر. ضع الإجراءات مباشرة في action واستخدم fragment لعدة أزرار؛ تتولى الحاوية التباعد والتسميات الطويلة. العنوان هو h2؛ استخدم فتحة title بدلًا من strong. تُحفظ فئات الجذر الحالية مع دعم skin.vars وstyle. يحتفظ المضيف بالنصوص المترجمة والصلاحيات والتنقل والإنشاء؛ وتحتفظ نتائج البحث والأخطاء برسائلها وإجراءاتها الخاصة.

2026-09-08 · SidebarNavigation

يحمّل SidebarNavigation مسارات المصدر نفسه مسبقًا بعد بقاء المؤشر 180 مللي ثانية أو عند تركيز لوحة المفاتيح. تشترك القوائم الثابتة والمنبثقة في حد 8 وجهات كل 30 ثانية. يتوقف التحميل دون اتصال وفي الألسنة المخفية ومع Save-Data أو 2G؛ وتُستثنى التنزيلات والروابط المعطلة والنوافذ الجديدة وروابط الصفحة الداخلية. تبقى حماية التغييرات غير المحفوظة والتنقل كما هي.

2026-09-07 - AccountDropdown / SidebarProfile

يقبل AccountDropdown الخيارين compact وpreferences: يخفي الوضع المختصر المعرّفات وسجل الإنشاء، ويحافظ الوضع الافتراضي على المحتوى السابق. يقبل Appearance وLanguage القيمة triggerRole="menuitem" داخل قائمة الحساب. يعيد التنقل بلوحة المفاتيح التركيز، وتعالج حوارات اللغة المتداخلة مفتاح Escape بشكل مستقل. القيمة الافتراضية لـ SidebarNavigation.searchEnabled هي true؛ استخدم false للتنقل القصير والثابت. يفتح SidebarProfile الذي يتضمن href دون قائمة الوجهة نفسها في وضع التوسيع ووضع الرموز.

2026-09-07 - FormField / AdminEntityDialog / EditorWorkspace

تشترك النماذج في مقياس الخط وتلتف النصوص الطويلة مع الحفاظ على الأشكال المستديرة وألوان العلامة. يسمي FormField المجموعات؛ يربط controlId وid الداخلي التسمية. يعيد SearchField التركيز بعد المسح. يدعم Segmented وControlMenu الخيارات المعطلة؛ عناصر ActionMenu المعطلة بلا روابط. تحافظ الأزرار المشغولة على الحجم والمؤشر. يتحقق AdminEntityDialog من الحقول المطلوبة والبريد وJSON ويركز الأخطاء ويمنع الحفظ المتكرر ويحفظ الإدخال عند الفشل. يوفر EditorWorkspace الدالة ref.focusControl(element) لإظهار اللوحات المخفية قبل التركيز. يوقف تقليل الحركة انتقالات عناصر التحكم. يمرر WorkspaceDialog المحتوى الطويل مع إبقاء العنوان والإجراءات مرئية؛ تتناسب الحوارات القصيرة على الهاتف مع المحتوى.

2026-09-07 · WorkspaceLocationSync / ProjectSwitcher

بعد اكتمال الانتقال بين المسارات، يغلق WorkspaceLocationSync لوحة اختيار المساحات المؤقتة لعرض أدوات الوجهة مباشرة. تبقى تفضيلات البحث والأقسام محفوظة. يظهر اسم النطاق وسياقه في سطرين منفصلين، وتُختصر الأسماء الطويلة في الرأس داخل الزر.

2026-09-07 · تنقل موحد وأسطح Qokit المستديرة

يعيد WorkspaceNavigationDock استخدام تنقل المضيف وصلاحياته عبر items وfallback وclassName وonClickCapture دون تحميل جلسة أخرى. تبقى تفضيلات العرض الموسع والأيقونات والإخفاء مشتركة، ويستخدم درج التنقل عند عرض 860px أو أقل. يظهر PlatformHeader.leadingContext أيضًا داخل EditorHeader. تُحفظ الأزرار البيضاوية والأسطح المستديرة وتُزال الحدود المتكررة.

على سطح المكتب، يؤدي النقر على القائمة إلى إخفاء الشريط الجانبي بالكامل أو استعادة آخر وضع ظاهر. يبدّل سحب القائمة أو حافة الشريط بين الإخفاء والأيقونات فقط والتوسيع. تتبع مفاتيح السهمين الأيسر والأيمن اتجاه القراءة. لا يغيّر إلغاء السحب التفضيل المحفوظ، ويظل درج التنقل مستخدمًا على الهاتف.

ثبّت WorkspaceLocationSync مرة واحدة تحت Suspense في تخطيط Next. يعيد useWorkspaceQueryState(key, defaultValue, validate) القيم [value, setValue, ready]، بينما يستعيد useWorkspaceQueryRecord(key, defaults, validators) المرشحات المسطحة المعلنة فقط. لا تحفظ بيانات الاعتماد أو المسودات في URL. يستعيد WorkspacePage مواضع تمرير محدودة في الجلسة، وتستخدم المناطق الداخلية data-workspace-scroll-region وWorkspaceScrollRestoration. تعيد عمليات الرجوع والتقدم الأصلية القابلة للإلغاء استخدام حماية المغادرة دون إضافة سجل. يحتفظ AdminEntityDialog بالمدخلات بعد فشل الحفظ وإعادة العرض؛ ويظل المضيف مسؤولًا عن الإصدارات ونتائج الحفظ.

تستخدم الإدارة أدوارًا ثابتة للنص: عنوان الصفحة 20px/650 وعنوان القسم 16px/600 والنص والتنقل 14px والتسميات 13px والملاحظات 12px. يُشتق --qk-workspace-body-ink و--qk-workspace-active-ink من الألوان الحالية.

تحتفظ الأزرار الأساسية بأزرق Logo الأصلي #4695D8 وتستخدم نصوصًا وأيقونات ومؤشرات تحميل بيضاء في السمتين. يبقى التفتيح الطفيف عند التحويم. تحتفظ الأزرار الثانوية والخطرة بألوانها الدلالية.

تستخدم القوائم المنسدلة ومبدلات مساحات العمل --menu-option-font-size (14px) و--menu-option-font-weight (500) بارتفاع سطر 1.45؛ تستخدم الخيارات المحددة وزن 600 والبيانات المساعدة 12px/400. يحمّل WorkspaceNavigationDock الوجهات من المصدر نفسه مسبقًا عند مرور المؤشر أو تركيز لوحة المفاتيح، مع سجل محدود لمنع التكرار. يستمر التنقل عبر حواجز المغادرة ومسارات المضيف الحالية.

2026-09-07 - ColumnLayout

يملأ ColumnLayout نافذة الإدارة بتنقل مثبت ومنطقة تمرير مستقلة وشريط أدوات صفحة ثابت. يستخدم WorkspacePage أقسامًا مسطحة ورموز تدوير زوايا مشتركة. عند عرض 860px أو أقل، يبقى التنقل درجًا غير تفاعلي عند إغلاقه. لا تتغير الخصائص أو سلوك الأعمال. أزل الهوامش الخارجية المكررة وحدد عرض القراءة داخل النماذج.

نقاط الاستيراد

import { Button, Card, Dialog, IconButton } from '@qokit/components/ui';
import { PlatformHeader, SiteFooter } from '@qokit/components/patterns';
import { platformButtonSkin } from '@qokit/components/skins/platform';
import { siteCardSkin } from '@qokit/components/skins/site';
نقطة الاستيرادالغرض
@qokit/components/uiالمكونات الأساسية مثل Button، Card، Dialog، Menu، Pill
@qokit/components/patternsالتركيبات مثل Header، Footer، مساحة العمل، الجدول، الموارد، ومساعد AI
@qokit/components/skins/platformوصفات بصرية للمنصة ومساحة العمل
@qokit/components/skins/adminالوصفة البصرية لـ Admin
@qokit/components/skins/siteتوليد الوصفة البصرية للموقع

حدود المسؤوليات العامة

PromptPanel يقبل خصائص referenceReader الاختيارية وخصائص referenceCopy المحلية. يقوم القارئ بإرجاع علامات contentExcerpt و truncated المستخرجة عبر استدعاءات غير متزامنة لـ file(File, AbortSignal) و website(url, AbortSignal)، بينما يتولى المضيف مسؤولية المصادقة والوصول إلى الـ API. يدير المكون عملية القراءة والمعاينة وإعادة المحاولة والإزالة؛ وعند عدم وجود نص تلميح لعنوان URL صالح، يتم استكمال الطلب بواسطة referenceCopy.websitePrompt، وفي حال وجود خطأ في التنسيق يُستخدم referenceCopy.errors.url ويتم منع القراءة. عند الإرسال قبل اكتمال القراءة أو أثناءها، سيتم انتظار أحدث محتوى وسيتم الإرسال مرة واحدة فقط؛ وإذا تغير الإدخال أو فشلت القراءة، سيتم إلغاء العملية المعلقة، ولن تستعيد إعادة المحاولة الإرسال القديم. يجب أن تكون الملفات جاهزة قبل الإرسال. يتم قراءة عنوان URL الكامل تلقائيًا عند اللصق أو فقدان التركيز أو الضغط على Enter، كما سيتم قراءة عنوان URL الأولي وإعادة استخدام النتائج قيد التنفيذ أو المكتملة؛ وفي حالة الفشل يتم تقديم خيار إعادة محاولة واضح. يؤدي التحرير أو إزالة عنوان URL إلى إلغاء القراءة القديمة ومسح النتائج. عند عدم توفير قارئ، يستمر الإرسال الأصلي دون معالجة مرجعية غير متزامنة.

أُضيفت قدرة استهلاك المرجع في سبتمبر 2026 كميزة اختيارية ومتوافقة مع الإصدارات السابقة.

يضمن هيكل المكونات:

  • علامات DOM والدلالة؛
  • سلوك ARIA، ولوحة المفاتيح، والتركيز، وحالة disabled؛
  • الحالة والتفاعل الأساسي؛
  • فئات افتراضية مستقرة؛
  • خانات Skin ذات أسماء محددة.

يمكن لـ Skin:

  • إضافة فئات لخانات مثل root، وheader، وbody، وitem، وaction؛
  • تمرير متغيرات CSS عبر vars؛
  • استخدام مفاتيح tone، أو layer، أو التكيّف البصري التي أعلنتها المكونات بالفعل.

لا يجوز لـ Skin طلب البيانات، أو تغيير DOM، أو الاحتفاظ بقواعد الأعمال، أو تجاوز سلوك إمكانية الوصول.

محتوى العناصر المُولَّدة

تستمر الكتل المخصصة المُولَّدة في استخدام عنصر html-* المسجل ضمن Schema v2، دون استخدام HTML قابل للتنفيذ أو أنواع كتل جديدة. اعتبارًا من سبتمبر 2026، يوفر @qokit/site-schema كلًا من bindSiteModuleContent و updateSiteModuleBoundContent و forkSiteModuleContentBindings لربط محتوى اللغة. تُحفظ مسارات المحتوى في الوحدة النمطية، ويُحفظ نص الزوار في خريطة محتوى اللغة، وتُطبق التحديثات باستخدام معاملات التراجع والحفظ؛ وعند نسخ أو نقل العناصر عبر الكتل، يجب اشتقاق الربط لتجنب تعديل المصدر.

يسجل الحقل الاختياري extensionRequirements متطلبات وقت التشغيل غير المحلولة، وهو ليس قائمة تثبيت أو منح صلاحيات. يصدر createSiteExtensionHandoff طلبات تطوير v1 غير القابلة للتنفيذ؛ ويجب حل هذه المتطلبات أو استبعادها بوضوح بعد المراجعة قبل نشر موقع قابل للتشغيل.

عناصر تحكم النموذج

تستخدم النماذج المشتركة FormField لربط التسمية والوصف وبيانات الحقول الإلزامية والأخطاء ومعرّف عنصر التحكم. تستخدم عناصر التحكم النصية Input، والمحتوى متعدد الأسطر Textarea، وعناصر التحكم في الاختيار Checkbox و RadioGroup و Switch؛ بينما تستخدم كل من Select و SearchField الحالية نفس عقد الحجم والحالة.

import { FormField, Input } from '@qokit/components/ui';

<FormField label="Site name" description="Up to 60 characters" error={errors.name} required>
  <Input name="name" value={name} onChange={handleChange} />
</FormField>;

يربط FormField التسمية والوصف والخطأ بعنصر تحكم فردي فريد عبر id و aria-describedby و aria-invalid و required. لا تغلف عناصر التحكم المشتركة بعد الآن بـ <label> إضافي.

تدعم كل من Input و Textarea و Select و SearchField ثلاثة أحجام وهي sm و md و lg، والتي تقابل 40px و 44px و 48px. تستخدم عناصر التحكم ذات السطر الواحد بشكل افتراضي شكل pill؛ بينما تستخدم Textarea دائمًا الزوايا المستديرة المشتركة متعددة الأسطر. تأتي جميع حالات التفاعل والخطأ من Token المشترك.

لا يزال يمكن استخدام عقد .qk-field القديم أثناء فترة الترحيل؛ ويجب على الدمج الجديد استخدام المكونات المشتركة وفتحات Skin المسماة.

تحديد القائمة

اعتبارًا من سبتمبر 2026، يمكن للقائمة استخدام useWorkspaceSelectionMode({ enabled, resetKey, onClear }) مع WorkspaceFilterToolbar.selection. هذا الـ Hook غير مفعّل في البداية، ويعاد تعيينه عند تغيير النطاق أو الصلاحيات، ويميز بين مسح معرفات التحديد المحددة والخروج من وضع الدفعات؛ ويجب أن تتضمن مفتاح النطاق المجموعة واللغة والترقيم والتصفية.

يتم تمرير WorkspaceDataTable.selection فقط عند تفعيل وضع الدفعات، وتستخدم عناصر التحكم في مربعات الاختيار للشبكة والهاتف المحمول نفس النمط. يتولى شريط الأدوات عمليات التحديد العامة، ويقدم المستخدم النصوص المحلية ومعرفات اختيارية وإجراءات مجال خاضعة لفحص الصلاحيات. يمكن للحقل الاختياري actionContent حمل دلالات ARIA إضافية، لكنه لا يحل محل العناصر العامة أو التأكيد. لا تعرض القوائم المقروءة فقط وضع الدفعات، وتحافظ محددات الملفات ومراجعات المقترحات على دلالاتها الخاصة.

هذه القدرات الإضافية اختيارية ومتوافقة مع الإصدارات السابقة؛ ولا يزال تحديد الجدول يخضع للتحكم الصريح من قبل المستخدم.

بطاقات المؤشرات

مراجع API إضافية (بالإنجليزية؛ الترجمة قيد الانتظار) · 2026-10

DataCard provides a title and optional headerAction, body content with an optional emphasized value, and optional footerText and footerAction. Pass other body content as children. density="default" has a 144px minimum height and 20px padding; density="compact" has a 112px minimum height and 16px padding. Cards grow when content needs more room. variant selects the shared Card surface: surface, muted, or state. Choose these shared sizes instead of overriding height, padding, or value typography in route CSS.

Use shared UI controls in action slots. Keep the card root non-interactive when it has actions; a whole-card action cannot contain nested buttons or links. MetricCard composes the same skeleton and retains label, detail, semantic tone, and optional visuals.

import { DataCard, MetricCard } from '@qokit/components/patterns';
import { Button } from '@qokit/components/ui';

<DataCard
  title="Published"
  value={24}
  headerAction={<Button size="sm" variant="ghost">View</Button>}
  footerText="Up 3 from last week"
  footerAction={<Button size="sm" variant="secondary">Details</Button>}
  density="compact"
/>;

<MetricCard density="compact" label="Published" value={24} tone="success" />;

هيدر وفوتر المنصة

يعرض Logo صورة ثابتة افتراضيًا. يحجز motion="breathe" الأبعاد أثناء الإخفاء، ثم يُظهر الشعار مرة واحدة بحركة تنفّس مدتها 4.8 ثانية بعد تحميل الصفحة وظهور نصفه على الأقل. لا يضيف الرأس والتذييل انتظارًا. يتيح motionVisibilityDelayMs إضافة مدة ظهور متصلة، وقيمته الافتراضية صفر. يشارك motionOnceKey سجل التشغيل بين مرات إعادة التركيب في المستند نفسه؛ ويستخدم الرأس والتذييل مفتاحين منفصلين. لا يعيد التنقل أو تغيير المظهر أو التمرير للعودة تشغيل الحركة؛ وإعادة تحميل الصفحة كاملة تعيد ضبط السجل. يظهر الشعار الثابت عند تقليل الحركة أو تعطيل JavaScript أو تعذر مراقبة الظهور. يبقى motion="reveal" اسمًا بديلًا.

القيمة الافتراضية لـPlatformHeader.autoHideOnScroll هي false؛ ويُفعّلها PublicPlatformHeader. يختفي الرأس عند التمرير لأسفل ويعود عند التمرير لأعلى أو قرب أعلى الصفحة. تبقيه قوائمه المفتوحة أو التركيز داخله ظاهرًا. تظل رؤوس مساحة العمل والمحرر ثابتة.

PlatformHeader هو هيكل Header بدون حالة أعمال. يقوم PublicPlatformHeader بتركيب مدخلات العلامة التجارية، والتنقل العام، واللغة، والموضوع، وتسجيل الدخول، و"جرب الآن"، وقائمة الجوال فوقه، وتعتمد المنصة في حالة الزائر غير المسجل وموقع الوثائق مباشرةً على هذا التركيب.

يتم إنشاء التنقل العام بشكل موحد عبر buildPublicHeaderNavItems(copy, links) لتضمين "الموارد / الأسعار / الأخبار". يجب على المتكاملين تحليل الروابط داخل الموقع للتطبيق الحالي، وموقع الوثائق، والمنصة فقط، ولا ينبغي لهم إعادة تعريف ترتيب القائمة أو النص. يستخدم هيدر المنصة بعد تسجيل الدخول أيضاً دالة التوليد نفسها.

<PublicPlatformHeader
  copy={headerCopy}
  links={{
    brandHref: '/',
    resourceCenterHref: '/resources',
    userManualHref: 'https://docs.qokit.com/manual',
    developerDocsHref: 'https://docs.qokit.com/developers',
    changelogHref: 'https://docs.qokit.com/changelog',
    pricingHref: '/pricing',
    newsHref: '/news',
    loginHref: '/login',
    studioHref: '/studio'
  }}
/>

لا يزال الهيكل الأساسي navItems يدعم link، وscroll، وmenu. يدعم menu على سطح المكتب الإغلاق بالنقر، ولوحة المفاتيح، وEscape، والنقر خارج العنصر، بينما يقوم MobileHeaderMenu بتوسيعه إلى مجموعات روابط على الجوال.

يُعد SiteFooter هيكل Footer؛ حيث تستخدم المنصة وموقع الوثائق PublicPlatformFooter لتوحيد تركيب القشرة الخارجية، ومدخلات العلامة التجارية، والروابط، وأدوات التحكم بالموضوع واللغة. يتم تحويل الروابط النسبية إلى عناوين مطلقة عبر resolveCompanyHref للتكامل عبر النطاقات.

<PublicPlatformFooter
  brandHref="https://qokit.com"
  copy={footerCopy}
  resolveCompanyHref={(href) => `https://qokit.com${href}`}
/>

لا يجوز للتطبيقات التجارية نسخ هيكل DOM الخاص بـ Header أو Footer أو مصفوفة التنقل العامة؛ وعند الحاجة إلى مظهر بصري مختلف، يجب استخدام PlatformHeaderSkin، أو SiteFooterSkin، أو Skin المنصة المقابل.

استراتيجية التوافق

  • يُعد إضافة خصائص اختيارية وخانات Skin اختيارية تغييراً متوافقاً مع الإصدارات السابقة؛
  • يُعد حذف الخصائص، أو تعديل الدلالة الافتراضية، أو تغيير سلوك DOM/لوحة المفاتيح تغييراً كاسراً للتوافق؛
  • يجب أن تدخل التغييرات الكاسرة في سجل التغيير (Changelog)، مع توفير أمثلة للترحيل؛
  • لا تعتمد على الفئات الداخلية غير المعلنة، أو الدلائل، أو هيكل التوجيه؛
  • عندما تتطلب نقطتا تكامل أو أكثر نفس التعديل، يجب رفع ذلك إلى Skin أو Token عام.

التحرير بملء الشاشة

يجمع EditorWorkspace بين مربع حوار بملء الشاشة وإدارة التركيز ولوحات متجاوبة. يطلب dirty تأكيد تجاهل التغييرات، ويمنع busy الإغلاق أثناء الحفظ، ويتولى onSave اختصار Ctrl/Cmd+S. يتولى التطبيق المضيف الصلاحيات والبيانات والحفظ والنشر.

تبدّل view / onViewChange بين edit وfocus وpreview دون استبدال المحرر. توفر preview المعاينة وتعيد previewPanel استخدام لوحة موجودة. تدعم layout القيم writing وstructure وcanvas. تحفظ storageKey عرض اللوحات وحالة طيها فقط، دون محتوى المستند.

تعيد onSaveAndClose القيمة true بعد تأكيد الحفظ، وfalse عند الفشل، وhandled إذا انتقل التطبيق بالفعل، وpending إذا احتاج التحقق إلى قرار. يبقى المحرر مفتوحًا عند الفشل. استخدم closeBehavior="collapse" فقط عندما يحتفظ التطبيق بالمسودة. تعرض EditorSaveStatus حالة مؤكدة. يمكن أيضًا تركيب EditorViewControls وEditorLeaveDialog وuseEditorLayout في مساحات العمل الحالية.

تغيير لوحة المفاتيح: لـSegmented نقطة Tab واحدة، ويستخدم الأسهم / Home / End. تحترم Dialog معالجة Escape في الطبقة الفرعية؛ ثم يخرج المحرر من التركيز أو المعاينة قبل الإغلاق. تقبل LivePreviewToolbar.exitControl أدوات العرض المشتركة. يظل الحفظ والنشر والصلاحيات من مسؤولية التطبيق.

import { EditorWorkspace } from '@qokit/components/patterns';

<EditorWorkspace
  open={open}
  title={title}
  dirty={dirty}
  busy={saving}
  onClose={closeEditor}
  onSave={saveDraft}
  onSaveAndClose={saveDraft}
  saveState={saveState}
  layout="writing"
  storageKey="article"
  preview={preview}
  navigation={structure}
  inspector={properties}
  actions={saveActions}
>
  {editor}
</EditorWorkspace>

SidebarToggleSlot

SidebarToggleSlot يضع زر الشريط الجانبي في رأس مساحة العمل. استخدم موضعًا واحدًا مع شريط جانبي أيسر واحد. يحتفظ SidebarNavigation بإدارة الحالة والاختصارات والدرج على الهاتف؛ وبدون الموضع تبقى الأزرار الأصلية. يغلق زر الرأس الدرج على الهاتف أيضًا، ويعود التركيز إلى الزر نفسه بعد الإغلاق.

EditorHeader

يحتفظ EditorHeader بشعار التطبيق والحساب والقائمة العامة داخل المحرر النشط. يتحكم startControl وendControl في اللوحتين الجانبيتين، ويضم center أوامر العرض وactions إجراءات الحفظ. يعيد PlatformHeader.editorActions استخدام التنقل المتجاوب واختيار اللغة والمظهر. يجب أن يعالج onNavigate التغييرات غير المحفوظة قبل تنفيذ دالة الاستدعاء. تستخدم الترويسة صفين على الشاشات الضيقة، وتعالج القوائم الفرعية Escape أولاً.

تضع WorkspaceHeaderPortal.startControl وendControl مفاتيح لوحة الصفحة المُدارة في فتحات المضيف المطابقة. تعرض المضيفون خيارات لـ startTarget وendTarget بجانب العنوان والحالة والإجراءات. يستخدم مكتبة الملفات ومساحة عمل الأصل الواحد workAreaControls؛ ويحتفظ معاينة الأصل بالرأس الكامل حتى تبقى هويته وإجراء العودة ووجهات اللوحة متاحة. تمتلك ProjectWorkspace خيارات التنقل/المحادثة اليسرى المشتركة للمحتوى والملفات. يسجل الملفات أبعاد لوحة الموارد المُذكرّة من خلال useProjectResourcePanel، وينقل التنقل عبر ProjectContentTools، ويوفر فقط عنصر تحكم مفتش اليمين الخاص به عبر ProjectToolbar.endControl. تستخدم المحادثة نفس المسار الأيسر ومؤلف مضمن عبر مناطق المشروع؛ والمهام الخاصة بالموارد المدمجة والمحادثات والمفتشين حصرية متبادلة.

EditorNavigationMenu

يعيد EditorNavigationMenu استخدام SidebarNavigation بالكامل في لوحة متراكبة تحفظ الصلاحيات وسياق المشروع دون تحريك مساحة التحرير. توجد اللغة والسمة في الأسفل، وتعالج القوائم الفرعية Escape أولاً. التركيز وملء شاشة المتصفح مستقلان. ينتظر التنقل اكتمال الحفظ الجاري ويحمي المسودات.

WorkspaceNavigationMenu / WorkspacePageHeader

يستخدم التنقل العام Command+\ على Mac أو Control+\ على Windows/Linux، ويعمل باستقلالية داخل Creator أيضًا. يحتفظ T وShift+T بوظائف تخطيط المحرر. تُتجاهل الحقول القابلة للتحرير وتركيب النص والتكرار والأحداث التي عولجت بالفعل. تعرض تلميحات الزر وaria-keyshortcuts تركيبة المفاتيح؛ ولم يعد التنقل العام يستخدم T منفردًا.

تستخدم مساحات العمل بعد تسجيل الدخول PlatformHeader.workspaceActions لتوحيد منطقة الحساب والتنقل في جميع العروض. يوحّد WorkspacePageHeader العناوين والإجراءات. يعرض WorkspaceNavigationMenu الشريط الجانبي الحالي مع صلاحياته وسياقه؛ ويبقى EditorNavigationMenu اسمًا بديلًا متوافقًا. يحتفظ Studio بشريط أدواته. تحتفظ الترويسات العامة بمظهرها الحالي.

يحمي WorkspaceNavigationGuard التنقل العام عبر dirty وbusy وerror وonSave الاختياري. لا تُسمح المغادرة إلا بعد تأكيد الحفظ وإرجاع true؛ ويحتفظ الفشل بالمسودة. يتيح Language.onBeforeChange(apply) تطبيق الحماية نفسها قبل تغيير اللغة. عطّل حقول النموذج أثناء الحفظ.

تحتفظ واجهة سطح المكتب بالشريط الموسع والأيقونات وتضيف الإخفاء التلقائي. يتشارك الشريط والدرج البحث وحالة المجموعات. يفتح المؤشر الدقيق معاينة مؤقتة بعد البقاء عند الحافة 300ms، وتغلق بعد المغادرة بـ320ms؛ النقر يبقيها مفتوحة. تبقى أزرار اللمس ولوحة المفاتيح متاحة. تستخدم Dialog افتراضيًا modal={true} وautoFocus={true}؛ تضبط المعاينة كليهما على false للحفاظ على تركيز الإدخال والتمرير.

EditorViewControls

يبدّل زر واحد في الاتجاهين: أثناء التحرير يعرض التركيز، وأثناء التركيز يعرض التحرير. انقر أو اضغط T؛ ويعيد E التحرير مباشرة. يبقى الزر ظاهرًا في الرأس الضيق، وتوضع المعاينة وملء الشاشة والإجراءات الإضافية في قائمة المزيد.

يفصل EditorViewControls بين التحرير والتركيز وبين ملء الشاشة الأصلي. المعاينة زر مستقل يعيد وضع التحرير السابق؛ وتحفظ useEditorWorkMode هذا الوضع لإجراءات الخروج المخصصة. تبقى قيم edit/focus/preview مدعومة. تستخدم المعاينة الآن button مع aria-pressed بدلاً من radio ضمن مجموعة الأوضاع. يتطلب ملء الشاشة نقرة ويشمل التنقل والحوارات داخل جذر التطبيق؛ ويُخفى الخيار عند غياب الدعم.

Language / Appearance

يدعم Language وAppearance variant="menu" الخيار layout="row" لعرض التسمية والقيمة الحالية والسهم. يبقى التخطيط المدمج الافتراضي وحماية تغيير اللغة دون تغيير. يحدد SiteHeaderCopy.helpResources وcontactSupport اختياريًا تسميات روابط المساعدة في مساحة العمل.

requestWorkspaceNavigation

تخفي الصفحات التي تتضمن زرًا للشريط الجانبي زر القائمة الإضافي في الترويسة، حتى عند الطي وعلى الهاتف. تحتفظ به المحررات والصفحات التي لا تتضمن شريطًا جانبيًا. استورد requestWorkspaceNavigation(returnFocusTarget?) وuseWorkspaceNavigationState() من @qokit/components/patterns/WorkspaceNavigation: يبدّل الطلب اللوحة المسجلة ويعيد false عند عدم توفرها. يستعيد العنصر الاختياري التركيز بعد الإغلاق. تحقق من .available قبل إظهار مدخل إضافي. استخدم الزر الموجود أو هذه الواجهة بدل الاعتماد على موضع زر القائمة المحذوف في DOM.

WorkspacePanelReveal

تستخدم الملاحة العامة رمز القائمة، وتستخدم الأدوات رموز لوحات حسب الجهة. يفتح useWorkspacePanelReveal({ temporary: true }) الأدوات مؤقتًا بالنقر أو لوحة المفاتيح في وضع التركيز. يحافظ toggle(trigger?) وclose(true) على التخطيط ووضع العمل ويعيدان التركيز عند الإغلاق. تفتح حافة الشاشة الملاحة العامة وتستجيب الأدوات قرب أزرارها. تخفي المعاينة أزرار اللوحات وتوفر إجراءً صريحًا للعودة إلى وضع التحرير السابق.

EditorViewControls / وضع العرض

EDITOR_VIEW_SHORTCUTS → Tooltip + aria-keyshortcuts

يدير EditorHeader أيضًا EDITOR_TOOLBAR_SHORTCUTS: يشغّل Command/Control+S عنصر EditorSaveButton الظاهر، ويفتح Shift+P عنصر EditorStatusAction shortcut="publish"، ويفتح Shift+M قائمة الأدوات. تستخدم الأوامر عناصر التحكم المفعّلة نفسها المستخدمة بالنقر؛ ويتطلب النشر إجراءً صريحًا داخل اللوحة. لا تستجيب إلا الترويسة النشطة الظاهرة. تمنع القوائم الفرعية ومربعات الحوار وتأليف النص والأحداث المتكررة الاختصارات؛ ولا يُسمح داخل حقول الإدخال إلا بالحفظ. تشترك التلميحات وaria-keyshortcuts في التعريفات. يضع toolsControl المخصص aria-keyshortcuts={EDITOR_TOOLBAR_SHORTCUTS.tools.aria} على زر التشغيل. يضيف ActionMenu.triggerKeyShortcuts السمة والتلميح دون تسجيل أمر عام.

أوامر اللوحات هي Shift+A للإضافة، وShift+L للصفحات والطبقات، وShift+K للمحادثة، وShift+C للمحتوى، وShift+D للتصميم، وShift+G للنمط العام. يضيف CMS عند التوفر Shift+S للإعدادات، وShift+E لتحسين البحث، وShift+H للسجل. تستخدم بيانات shortcut في EditorChoiceControl وEditorViewTabs وActionMenu تلميحات مشتركة. يحتفظ EditorPanelChoiceShortcuts وEditorViewControls.compactActions بالإجراءات عند طيّها في القوائم، بما فيها قوائم الهاتف. يسجّل EditorPanelShortcuts.commands الإجراءات القائمة دون تكرار عناصر التحكم. تبقى قيود الإخفاء وinert والتعطيل والمعاينة والطبقات العائمة سارية. تسمح أشرطة الهاتف الجانبية غير المشروطة في مساحة العمل نفسها بتبديل اللوحات؛ وتمنع القوائم ومربعات الحوار المشروطة الاختصارات. تحتفظ المفاتيح غير المعدّلة بسلوكها السابق.

وضع العرض
Eتحرير
Tتحرير ↔ تركيز
Vمعاينة / العودة إلى التحرير
Fالدخول إلى ملء الشاشة / الخروج من ملء الشاشة

يستجيب المحرر النشط فقط. لا تتغير الأوضاع أثناء إدخال النص أو تركيب أحرف IME أو الضغط المستمر على المفتاح أو فتح حوار أو قائمة فرعية.

PlatformHeader.workspaceNavigation

يضع PlatformHeader.workspaceNavigation التنقل العام قبل الشعار، بينما يحتفظ workspaceActions وeditorActions بإجراءات الحساب. تعيد مساحات العمل استخدام زر الشريط الجانبي الحالي، ويضع المحرر زر اللوحة اليمنى قبل الصورة الشخصية. في الشاشات الضيقة يظهر التنقل والعلامة والعنوان والصورة الشخصية فوق أدوات التحرير والحفظ. يتبع ترتيب DOM التخطيط مع الحفاظ على المظهر الزجاجي الضبابي بلا حدود.

2026-09-06 - EditorHeader.preview / EditorViewControls.returnView

يعرض EditorHeader.preview منطقة center فقط كشريط معاينة مختصر بلا حدود، مع إبقاء الشعار والحساب والحفظ واللوحات مركبة لكنها مخفية. عند استخدام LivePreviewToolbar منفصل يمكن إخفاء رأس المحرر وتمرير EditorViewControls.returnView بقيمة edit أو focus لاستعادة الوضع السابق. يبقى الرجوع والتحكم المستقل بملء الشاشة متاحين؛ يظل رأس الموقع نفسه ظاهرًا.

2026-09-06 · Builder / CMS

يشترك Builder وتحرير محتوى CMS في BuilderWorkspace وEditorCatalog وEditorComponentSettings للوحات ورسومات الإدراج وإعدادات العرض. تطبق الإعدادات المسبقة الخيارات المرتبطة معًا وتحافظ على المحتوى؛ ويتولى المضيف الحفظ والتراجع. تتبع أدوات مساحة العمل سمة المنصة، ويتبع المحتوى سمة الموقع.

تذييل يُعرض على الخادم · 2026-09-07

يتلقى SiteFooterLayout قيمة locale صريحة ومحتوى copy بلغة واحدة. تعرض مكونات الخادم بنية التذييل المشتركة، بينما تبقى أدوات المظهر واللغة ومربع حوار QR مكونات عميل. تظل الواجهتان الحاليتان SiteFooter وPublicPlatformFooter مدعومتين.

import { SiteFooterLayout } from '@qokit/components/patterns/SiteFooter';

<div className="qk-platform-footer-shell">
  <SiteFooterLayout locale={locale} copy={footerCopy} />
</div>

جهّز الروابط بين النطاقات في copy.companyLinks على الخادم. استخدم controls لتخصيص مساحة أدوات التحكم التفاعلية.

EditorHeader.titleControl / FloatingAssistant.presentation

يمكن لـ EditorHeader.titleControl وEditorWorkspace.titleControl استبدال العنوان بقائمة المشروع المشتركة. احتفظ بـ title الوصفي وحماية التغييرات غير المحفوظة عند التنقل. يعرض FloatingAssistant.presentation="embedded" منطقة مسماة داخل لوحة المضيف دون زر عائم أو خلفية حاجبة؛ يبقى floating هو الافتراضي. يدير المضيف الموضع والظهور، ويحتفظ المساعد بحالة المحادثة والصلاحيات.

2026-09-07 · WorkspaceAssembly

يحدد WorkspaceAssembly البطاقات المغادرة والأقسام القادمة دون إضافة حاوية تخطيط. عندما يتطلب التخطيط عناصر أبناء مباشرة، ضع workspaceAssemblyAttributes(part, index, phase) على عنصر DOM الموجود. يوفر EditorHeader.assemble وBuilderWorkspacePanels.assemble علامات المحرر.

استدعِ await startWorkspaceAssembly(navigate, destinationPathname) بعد نجاح الإنشاء فقط: يلتقط الأجزاء المرئية وينتقل مرة واحدة ويجمع الوجهة أو هيكل التحميل المطابق خلال 720 مللي ثانية كحد أقصى. تتطلب الوجهة علامة دخول canvas؛ ويحافظ useWorkspaceAssemblyPending() على واجهة التحميل حتى تستقر اللقطات، مع تحميل البيانات والشيفرة مسبقًا. عند تقليل الحركة أو غياب دعم المتصفح يحدث الانتقال مباشرة. تحرر الانتقالات البطيئة أو المتوقفة اللقطات وتتابع التنقل. لا تحرك العلامات وحدها التحرير أو إعادة التحميل أو سجل التنقل. يتولى النمط المشترك تنظيف الأنماط المؤقتة، وتبقى أخطاء الإنشاء وعدم تكرار الأثر وحالة التحميل لدى المضيف.

2026-09 · مساحات الإدارة

يدعم WorkspacePage وWorkspaceLayout الخاصية variant: overview أو list أو detail أو settings أو editor. يرتب WorkspaceFormFooter القيم actions وmessage وtone وbusy التي يوفرها المضيف؛ حفظ البيانات مسؤولية المضيف.

تعرض الجداول الضيقة (WorkspaceDataTable وAdminDataTable) سجلات بعناوين حقول مع التحديد والرؤوس المخصصة والإجراءات. استخدم mobileLayout="scroll" لمصفوفات المقارنة. يضع WorkspaceFilterToolbar البحث والتصفية قبل الترتيب والعرض. يستخدم الشريط الجانبي h2 وتستخدم الصفحة h1.

2026-09-08 · Task focus

يخفي useSidebarTaskFocus(active) التنقل مؤقتًا أثناء مهمة تتطلب التركيز، ويعيد العرض السابق عند الخروج ما لم يغيّر المستخدم الوضع بنفسه. لا يغيّر الإخفاء التلقائي التفضيل المحفوظ.

مراجع API إضافية (بالإنجليزية؛ الترجمة قيد الانتظار)

EditorHeader.contextMode="title" displays the editor's own titleControl instead of the host workspace picker. The default "host" behavior is unchanged; navigation, brand, account controls and leave guards retain their existing ownership. Hosts supply responsive placement for their title control.

EditorViewControls.focusInMenu shows a labelled preview action and moves focus mode into the shared menu. Its default remains false; view shortcuts and returning from preview keep the existing behavior.

EditorViewControls.toolsControl replaces the fallback menu with a host-owned tools control. Hosts retain its accessible trigger, menu state and actions; view buttons and keyboard shortcuts keep their existing behavior. Creator uses this slot for its complete editor tools menu beside Add, Layers and Preview.

EditorViewControls.responsiveLabels displays text beside focus and preview icons above 720px, reserving space for both focus labels. At phone widths the labels are hidden while accessible names and tooltips remain. EditorSaveButton.showStatusLabel displays saved/saving status or a retry action when state is provided; it reserves label space across states. Both options default to false.

ResizablePanels.middlePanelProps forwards section attributes such as inert to the middle panel, matching the existing side-panel attribute slots. An editor can keep its canvas mounted while preventing keyboard and pointer interaction when a compact conversation view covers it. Hosts still control panel visibility and restore focus when switching views; the prop does not unmount content.

ProjectSwitcher.currentWorkspaceId optionally marks the parent workspace independently of currentProjectId; only the current location receives the selected surface. IDs must match the supplied projects items. onActionSelect(action, event) lets the host guard shortcut navigation after the menu closes; omitted callbacks retain normal link behavior. Creation shortcuts use ordinary menu surfaces. Optional SiteHeaderCopy.projectSwitcherCreate and projectSwitcherWebsites label creation and the current workspace's website group without renaming the Creator product.

AccountDropdown.usageSummary is an optional slot below the account identity for host-supplied credit balances, plan usage and links to details. It also accepts ({ environmentInfo }) => ReactNode to place the shared ID disclosure and copy controls in the summary without duplicating them below. Links use role="menuitem" and retain menu keyboard behavior and navigation guards. The platform header shows credits and plan usage in two columns, with ID details expanding below; the sidebar account retains appearance and language. Failed reads never appear as zero, and reopening the menu refreshes the data.

PublicPlatformHeader.workspaceAction optionally supplies { href, label } for an authenticated visitor's return link. It replaces the desktop login icon and stays visible beside the mobile menu; the mobile menu then omits anonymous account actions. Session detection belongs to the host. The platform home uses a lightweight local session check, updates after focus/storage changes, and keeps ?view=public on its brand link so explicit website visits survive refresh.

contextAfter places editor-specific scope controls after the host project picker, preserving their DOM and keyboard order. The host retains project navigation and leave guards; the editor owns page and content-language selection. Hosts may adapt the responsive layout to put this context on its own row.

WorkspaceNavigationMenu.footerLinks supplies direct icon links alongside the sidebar display control. footerMenus accepts ordered WorkspaceNavigationFooterMenu entries, each with a label, icon and link items (with optional separatorBefore). The platform uses one menu for Website Home, Pricing, Templates and News, and a book-icon Help & Support menu for the user manual and contact support. The single footerMenu prop remains supported when footerMenus is omitted. Desktop menus open upward with ActionMenu placement="top" portal; mobile uses bottom sheets. The controls form one row when expanded and a column in icon mode; on mobile the sidebar control closes the navigation drawer. Each icon retains an accessible name and tooltip. profile adds the user name, plan and account menu without duplicating an existing sidebar account. Omitting footer links and menus retains the existing preferences and fullscreen actions.

Set a footer menu item's newTab to open a reference destination with target="_blank" and rel="noopener noreferrer". The skeleton adds a trailing arrow and localized screen-reader notice; other items keep current-page navigation. Website Home, Pricing, Templates, News, the manual and contact support use new tabs so the workspace stays open. An explicit public-home visit preserves ?view=public to bypass the signed-in landing redirect, including after refresh.

Editor tool palettes can use Dialog with keepMounted to preserve search and form state while closed. Closed dialogs immediately become inert, hidden from assistive technology, and leave the focus stack, including during a visual exit transition; the default still unmounts their content. Pair nonmodal palettes with DialogPanel to reuse the global overlay surface. Toolbar accepts a DOM ref for bounded positioning while retaining its shared arrow-key navigation.

useFloatingSurface from @qokit/components/patterns/FloatingTools supports defaultHeight: 'auto' for content-sized palettes. Keep the host body shrinkable with internal scrolling; the hook caps the surface to its workspace bounds and observes size changes. Moving an automatic palette stores its position without freezing the measured height. Resizing explicitly stores a fixed height, including across reloads; reset() or Home on a movement/resize handle restores automatic sizing. Numeric defaultHeight retains the existing fixed-height behavior.

FloatingToolPanel composes the shared DialogPanel, TreeToggle, pin button, tooltip and close button. Place it inside a nonmodal Dialog; the host controls pinned, collapsed, their callbacks and document operations. Pinning keeps the palette open after an operation; it does not lock its position. The title and header whitespace accept useFloatingSurface().dragHandle, while buttons, menus and inputs never initiate dragging or folding. Double-click the title or whitespace to fold; the explicit fold button supports keyboard and touch. Folding hides the body without unmounting it, preserving searches and tree state. Pass the same collapsed value to useFloatingSurface to retain the expanded height while moving the folded header. Optional actions and skin slots reuse the same structure; styles stay in the shared stylesheet.

Optional FloatingToolPanel.viewKey adds a short opacity transition when the active tool changes, without replacing its body instance. Ordinary parameter updates do not animate. Opening, closing, unfolding and pin feedback share the existing motion Tokens and respect reduced motion. Dragging stays direct; useFloatingSurface coalesces pointer movement to one geometry update per animation frame and saves the final position on release. Browsers without discrete display transitions close immediately.

Unified editors pass focus={false} to omit the separate Focus control. primaryActions accepts shared tool buttons before Preview; onTogglePanels handles T, and onToggleAllPanels handles Shift+T. Creator uses T to cycle from visible panels to floating launchers to fully hidden and back to the last visible layout; ordinary launcher clicks still open their panel. Shift+T directly hides everything and restores the exact preceding state. Both sidebar shortcuts are inactive in Preview and respect editable targets and active overlays. Existing hosts keep Edit/Focus behavior by default.

useWorkspacePanelVisibility().togglePanels hides the visible editor panels or restores their preceding layout. Desktop and compact layouts are remembered independently, and forceCollapsed (for example during Preview) does not overwrite that memory. The host owns global navigation visibility and any edge launchers.

For floating editor panels, pass skin: platformWorkspacePanelRevealSkin from @qokit/components/skins/platform and spread the returned panelProps onto the existing panel. The skin applies only while revealed; the docked panel and its mounted content remain intact. ResizablePanels merges startPanelProps, middlePanelProps, and endPanelProps class names with its own skin slots. Pair focus controls with Toolbar and platformFloatingToolbarSkin for shared keyboard navigation and compact spacing. Both skins share the global DialogPanel surface (background, shadow and blur); panel corners use the card radius and toolbar corners use the control radius. Hosts own positioning and available space, not a separate overlay palette.

useWorkspacePanelEdgeDrag is an opt-in hook for an existing workspace root ref. Mark its focusable borders with data-workspace-panel-edge="start" or "end"; ResizablePanels supplies these attributes on its own separators. The host provides each side's mode (expanded, icons, hidden), saved width and bounds through getState, applies onChange, and returns a rollback callback from onBegin. onResizing should suspend layout transitions; onFinish restores focus to the resulting control, and onReset restores the host's default width. One captured mouse or touch gesture crosses all three states, with RTL direction handling and cancellation on Escape, pointer cancellation or window changes. Arrow keys resize or step states, Shift increases the step, Home/double-click resets, and End expands to the allowed maximum. This hook adds no visual controls or stored content. Hosts can pair hidden borders with useWorkspacePanelReveal for temporary shortcut access while retaining their normal click actions; hosts without the hook keep existing resizer behavior.

FloatingAssistant.headerActionsTarget optionally accepts an HTMLElement in the host heading. The assistant portals its existing conversation history and new-conversation controls into that element and omits its internal header. Without a target, the original header remains. The host owns the heading and placement; the assistant retains action handlers, accessibility labels and conversation state. The Web adapter forwards this slot.

FeatureHint is exported from @qokit/components/patterns/FeatureHint. Use it for contextual first-use guidance attached to a real control. Provide a versioned id, a stable user scopeKey, an anchor: HTMLElement, an active eligibility signal, localized title, description, dismissLabel, and action: { label, onClick }. Set completed when the user discovers the capability independently. A null scope or unavailable anchor suppresses the hint.

The shared component allows one hint at a time, waits briefly for a visible target, follows scrolling and resizing, supports RTL, and keeps content inside the viewport. It does not add a backdrop, steal focus, or perform the action automatically. Escape, the close button, or clicking elsewhere dismisses it; Tab from the target reaches the action. The target receives a temporary highlight and accessible description. Seen hints are remembered in the current browser per scope and version, with an in-memory fallback if storage is unavailable; this is not cross-device progress. Hosts own permissions, review-state suppression and the actual action. skin, className and style adapt presentation.

AssistantContextCard is exported from @qokit/components/patterns/FloatingAssistant. Place it in composerContext to summarize the current editing target. Its typed contract includes title, description, scope, preview, parameters: { id, label, value }[], optional controls, status and notice, plus actions, onLocate and clearAction. Pass localized labels and formatted values, including units, from the host.

The card renders a read-only definition list, an optional controls slot for a few common adjustments, and a live status region. Reuse the host’s existing editing controls and commands in this slot; keep complete settings behind an explicit action that opens the existing inspector. Hosts retain ownership of selection, permissions, save, undo and AI requests. Conversation, canvas editing and inspector editing can operate together, with independent panel visibility. Selecting an object updates the card and an already open inspector without opening a closed panel or moving focus. Removing a conversation reference preserves canvas selection and direct editing; keep the conversation entry independent of this card and of floating-tool visibility. Changing the target or a parameter updates this live card without appending chat messages. Both draft and project conversations can use the same component. className, style and AssistantContextCardSkin support visual adaptation; styles are loaded with the component.

FloatingAssistantPanel.composerContext 接收输入框上方的实时上下文区域。提供此插槽时,顶部旧的 activeContext 摘要隐藏,activeContext.promptPlaceholder 仍供输入框使用。实时参数属于当前编辑状态,不应追加到历史消息列表;Web 适配器透传此插槽。

Hosts can set hoverReveal={false} to disable navigation previews from the trigger and window edge while retaining explicit controls and drag resizing; the default remains true.

WorkspaceNavigationDock prefetches same-origin destinations on mouse hover or keyboard focus, with bounded deduplication.

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

مكونات المحادثة المشتركة (مرجع إنجليزي، الترجمة لاحقًا)

@qokit/components/patterns/Conversation exports ConversationPanel, ConversationMessages, ConversationMessage, ConversationSuggestions and ConversationComposer. Creator generation, draft refinement and the embedded project assistant use these structures and the same token-based stylesheet. Hosts own requests, history, permissions, selected objects and review/apply actions.

يجمع ConversationFeedback مكوّن InlineNotice لعرض حالات المهام والإخفاقات والبدائل وتأكيدات الحفظ بشكل موجز داخل المحادثات. وفّر title مترجمًا، ومعه description وtone وaction عند الحاجة. يستخدم السطران حجم خط التعليقات ومسافة صغيرة وسطحًا شفافًا؛ تبرز النغمة الحالة بينما يبقى النص المساند خافتًا. تعلن القيمتان الافتراضيتان role="status" وaria-atomic="true" التحديث كاملًا معًا؛ استخدم role="alert" للإخفاقات التي تتطلب إجراءً. يبقى النص الذي يكتبه المساعد داخل ConversationText.

Place the scrollable ConversationMessages and the fixed ConversationComposer directly inside the panel. Supply a localized label for the messages region and inputProps for the controlled textarea. The composer accepts attachments, notice and actions slots, plus formProps and formRef; it creates the form, so do not nest it in another form. Enter inserts a newline; Cmd/Ctrl+Enter requests submission with composition and disabled/busy guards. Preserve user input while a request is running when the host supports it.

PromptPanel.presentation="conversation" reuses the composer while retaining reference reading, upload/menu controls and serialized form fields. The default "prompt" preserves the landing-page prompt behavior. FloatingAssistant.presentation="embedded" uses the shared panel, messages, suggestions and composer; floating assistants retain their compact presentation.

مراجع API إضافية (بالإنجليزية؛ الترجمة قيد الانتظار) · 2026-10

2026-10-10 · Pagination dot display

Pagination from @qokit/components/ui accepts pageDisplay="dots" for compact visual choosers. Combine it with layout="centered" for centered arrows and 6px indicators with 32px-wide click targets. Dot colors, hover and keyboard focus use shared theme Tokens; PaginationSkin.dot adapts the indicator slot. Hosts supply currentPage, totalPages, onPageChange and localized navigation labels. pageLabel names each dot; its fallback combines ariaLabel with the page and total. Browsing pages only invokes the host callback. The default "numbers" display retains numeric pagination and formatPageNumber.

2026-10-10 · ActionMenu search header

ActionMenu.dropdownHeader accepts host-owned content before the actions in both dropdown and mobile sheet presentations. onOpenChange reports opening and dismissal so hosts can reset transient search state. Search hosts supply localized copy, filtering and initial input focus; ArrowDown from the input should focus the first enabled result, then the shared menu handles result navigation, selection and Escape.

2026-10-09 · Inline ColorPicker

ColorPicker from @qokit/components/ui/ColorPicker accepts presentation="inline" to expand its editor beneath the field trigger. It renders a named group in the document flow, keeps the surrounding workspace available, and retains palette, HEX, opacity, gradient and reset capabilities. Hosts should reserve a full row for the field. Changes to the controlled value, including undo and reset, update the open inline editor; leaving the field finishes the current edit. The default "popover" presentation retains its portal, outside-click dismissal and Escape behavior.

2026-10-07 · WorkspacePanelGrid

WorkspacePanelGrid from @qokit/components/patterns/WorkspaceLayout places independent detail panels below the shortest available column. It responds to content and container size changes without moving or remounting child nodes; DOM and keyboard order remain unchanged. Narrow containers use one column. Keep continuous panels in one grid rather than separate rows. Metrics, tables, paired fields and ordered workflows retain their own layouts.

Each direct child is a panel. Use data-workspace-panel-span="full" or a numeric column span on that child's root for wider panels. The optional skin has a root slot and variables; --qk-workspace-panel-grid-gap controls shared spacing, and --qk-workspace-panel-grid-max-columns defaults to 2. Without JavaScript or ResizeObserver, panels retain the responsive ordinary grid.

2026-10-08 · Shared list toolbar groups

WorkspaceFilterToolbar now has one container-responsive contract across Projects, CMS and Admin:

  • query: search وfilters الحالة وsort وcontrols المجال وخيارات advanced وreset المشروط وresult المورد وsummary الإضافي.
  • presentation: view، يعرض controls وoptions مثل الأعمدة المرئية وحجم الصفحة. ينتمي تخصيص أدوات الصفحة إلى إجراءات رأس الصفحة.
  • actions: persistent operations, followed by the optional selection control at the logical end. Use ToolbarButtons with icon and localized compactLabel for refresh and other familiar actions.

The shared component measures its own available width. Controls show icons with labels above 960px and accessible icon buttons at or below 960px. At or below 640px, search occupies the first row and tool groups wrap in query → presentation → actions order. Routes must not override group widths or hide individual labels. ControlMenu and ViewMenu inherit this presentation without a route-specific responsive flag.

استخدم query.result={{ label, count, total?, locale? }} لاسم المورد وعدد النتائج. يعرض WorkspaceResultSummary «الاسم · العدد»، ويضيف «/ الإجمالي» فقط عندما يختلف إجمالي موثوق قبل التصفية؛ وتُنسّق الأرقام حسب لغة الواجهة وتُعزل في النص ثنائي الاتجاه. احذف result حتى يُعرف العدد؛ الصفر نتيجة صالحة. لا تضف صفاً آخر للاسم والعدد فوق القائمة نفسها. يقبل AdminFilterBar.result الكائن نفسه. تبقى عناوين الصفحات والأقسام المهمة وترقيم الصفحات وأعداد العناصر المحددة في أدوارها؛ واستخدم query.summary للوحدات الأخرى أو سياق الاستعلام أو حداثة البيانات.

Give overflow a localized label to move advanced and display options into More when compact. query.compactItems and presentation.compactItems supply complete menu choices replacing their corresponding controls; controlled values and callbacks remain in the host. Permanent menu actions use overflow.items. Selection and refresh stay outside More. Select and Done share the end slot, hit target and reserved idle toolbar height, including wrapped mobile rows.

This replaces the old flat toolbar API: migrate search, filters, sort, reset and secondaryControls into query; migrate view and display controls into presentation; move persistent endActions to actions. The former adaptive / inline-wrap CSS modes and WorkspaceFilterControlGroup capsule are removed; use these three semantic groups rather than compatibility aliases.

2026-10-10 · EditorItemDisclosure

EditorItemDisclosure from @qokit/components/patterns/EditorItemCollection accepts title, summary, open, onOpenChange, leading, actions and children for editing within a list. Sibling items remain visible. Escape collapses the item and restores trigger focus; opening does not scroll or autofocus. useEditorItemDisclosure scopes single-item expansion with scopeKey and restores adjacent focus after deletion. EditorItemCollection uses the same interaction; hosts still own content, ordering, persistence and undo. The existing EditorFocusedItem export remains available for flows that require a separate detail view.

مرجع API إضافي (بالإنجليزية؛ الترجمة قيد الانتظار) · 2026-10

2026-10-15 · Shared inspector choices

EditorStyleChoice uses the shared EditorChoiceControl for finite settings. In auto mode, two or three illustrated options use a segmented group; larger illustrated sets use a portalled ControlMenu showing the current icon and name. Text-only choices retain a native Select. Existing custom values remain selectable.

تدعم خيارات التحديد والقوائم annotation لإضافة نقطة بلون السمة وإدراج معناها المترجم في الاسم الميسّر. يعرض مشغّل ControlMenu نقطة الخيار النشط أيضًا، بينما يحصرها triggerAnnotation: null داخل القائمة. تؤدي إعادة اختيار عنصر محدد ومفعّل إلى استدعاء onReselect. تعرض الخيارات الأصلية الشرح بجانب التسمية، ويستبعد hidden العنصر النائب من قائمة الخيارات. يحدد المضيف القيمة المعلّمة وسلوك الاختيار؛ ولا يستنتج المكوّن المشترك الوراثة أو يكتب البيانات.

Use presentation="visual" for labeled diagram choices and presentation="toolbar" for familiar tools such as four-way text alignment. The toolbar has separate targets without a shared capsule. Native radios, shared menu keyboard handling, visible focus, disabled states and theme Tokens are retained. Hosts own labels, allowed values, persistence and undo. id identifies the control; ControlMenu also accepts triggerId and disabled.

Inspector menus, inputs, collapsed summaries and reset actions share a 32px mouse field height, restored to 40px on narrow screens and coarse pointers. Field icons use 16px and diagram choices keep an 8px gap. EditorComponentSettings reuses these choices for columns, density, image fit and aspect ratio, while composition layouts retain detailed previews. If saving briefly disables native radios, the shared skeleton restores focus to the selected option for continuous arrow-key editing.

Inspector labels and diagram captions use the 12px caption scale; values, actions and section titles use the 13px field scale. Visual choices have no decorative outer border: a soft selected surface and centered caption identify the current option, while keyboard focus retains its ring. Font specimens in the inspector use a compact, bounded scale.

2026-10-15 · Responsive workspace tables

WorkspaceDataTable reflows mobileLayout="records" into two columns of labeled facts, with the primary identity and sticky end actions spanning the record. Names and identifiers can use two lines. Column labels and selection remain accessible. Comparison tables using mobileLayout="scroll" retain their columns.

When a host toolbar already provides sorting or other header actions, set mobileHeader="labels" to remove duplicate header controls from the mobile layout and tab order. Column names remain available to assistive technology; desktop headers are unchanged. The default "controls" preserves custom header controls on mobile.

2026-10-14 · Independent editor panels

resolveWorkspaceResponsiveProfile and useWorkspaceResponsiveProfile from WorkspacePanels, and EditorWorkbenchChrome, accept the optional panelPolicy="independent". With BuilderWorkbenchFrame and the platform editor skin, both panels remain docked above the mobile threshold. Shared styles temporarily compress displayed widths while retaining remembered sizes, and the canvas fits the remaining space. Effective work areas at or below 720px retain mobile task switching.

Hosts own panel visibility. When supplying a measured profile, use the same policy for the measurement hook and Chrome. Omitting panelPolicy retains the default "adaptive" policy with its existing desktop, two-column and overlay layouts.

Editor workspace integration

workspaceNavigation connects the host's shared business navigation through EditorWorkbenchChrome: desktop navigation reserves space beside the content, while mobile uses the shared drawer. It is separate from the document structure panel navigation and retains the host's permissions and unsaved-change protection.

EditorSaveButton.showIcon keeps the save glyph beside its label. iconOnly reduces the control to an icon while retaining an accessible action and status name and tooltip. Editor hosts can use useCompactWorkspaceHeader() to show icons and labels in roomy layouts and icons alone in compact layouts. EditorStatusAction.iconOnly follows the same rule while retaining its issue count.

2026-10-15 · EditorControlGroup title actions

The headerActions slot on EditorControlGroup remains visible in both expanded and collapsed groups, for actions such as content visibility beside a group title. Pointer and keyboard interactions with these actions do not toggle the group. summaryActions still appears only when collapsed. Hosts own action names, state and persistence; icon actions must use the shared IconButton with a localized accessible name.

2026-10-14 · Management groups and summaries

WorkspaceSectionGroup, WorkspaceSection, WorkspaceFieldGrid and WorkspaceFacts are exported from @qokit/components/patterns/WorkspaceLayout. Headings and descriptions sit above their content panels on both desktop and mobile, sharing the starting edge. Use the default stacked layout; legacy layout="split" callers also render stacked. Apply qk-workspace-section-group__form to forms within a group to share spacing and save-area alignment. WorkspaceSection accepts optional icon, actions and description slots, keeping headings outside the content panel.

WorkspaceFieldGrid arranges independent short fields in at most two columns according to available width. WorkspaceFacts renders a semantic definition list with stable id, label, value, and optional unit, description, emphasis and tone. columns supports 2, 3 or 4 columns and adapts to narrow containers. Set mobileColumns={2} for short numeric summaries that should retain two columns on phones; the default is one. It is unboxed so summaries can share an existing content panel. Each component supports its named Skin, className and style. Hosts retain form state, permissions, submission, conflicts and recovery; these components do not make requests.

2026-10-14 · Management content panels and disclosures

WorkspaceContentPanel and WorkspaceSection.kind support summary, form, records, and actions. Section toolbar stays outside the content surface; supporting and footer provide compact metadata and end operations. titleId preserves existing heading anchors. The default panel container does not override a host's named container.

Use WorkspacePanelBlock, WorkspacePanelMeta, and WorkspaceRecordRow for subordinate groups, metadata, and repeated records. A record accepts title, description, meta, status, actions, and full-width detail children. Facts always align at the top. Hosts retain business fields, permissions, table columns, and submission boundaries.

WorkspaceActionRow accepts an optional action label or quiet empty/loading status, alongside description and actions. Action identity uses 14px semibold text, status uses 14px regular text, and descriptions use 12px. Copy and controls share a center line on desktop and stack at narrow widths. Card surfaces do not override descendant strong typography or spacing.

WorkspaceDisclosure accepts title, optional status, and children; WorkspaceDisclosureGroup accepts Accordion items and controlled expansion props. They start closed unless the host specifies an initial item, and open at most one sibling. Enter/Space toggles; Escape closes and returns focus to its trigger, handling inner disclosures before their parent. Hidden panels retain their DOM and input state. Optional headingLevel supplies section heading semantics; Skin and class slots only adapt appearance. Import these components from @qokit/components/patterns/WorkspaceLayout.

CustomizableWidgetLayoutControls / CustomizableWidgetLibrary

ضع CustomizableWidgetLayoutControls في إجراءات رأس الصفحة بعد المساعدة السياقية وقبل الإجراء الأساسي، بما في ذلك على الهاتف. استخدم copy.customize المحلي لتسمية الإجراء صراحةً (على سبيل المثال، "تخصيص الأدوات"). يكشف الإدخال الوحيد للأيقونة نفسه عن aria-pressed وaria-expanded، ويصبح copy.done أثناء التحرير. يعرض customizeButtonRef بشكل اختياري الزناد لاستعادة تركيز المضيف؛ ويعطل disabledCustomize الإدخال دون تغيير هندسته. زوّد بـ onCollapseToggle وareWidgetsCollapsed فقط للمضيفين الذين يدعمون طي الأدوات؛ وإخفاؤهما يرسم إدخال التخصيص وحده.

تمتلك CustomizableWidgetLibrary عنوان المكتبة الشائع، وإجراءات إعادة التعيين/الإغلاق، وتنسيق التمرير المستجيب، وتركيز زر الإغلاق الأولي والتعامل مع مفتاح الهروب. عند الإغلاق، يعود التركيز إلى عنصر التحكم الذي دعا المكتبة إذا كان التركيز لا يزال داخل المكتبة؛ ويحافظ النقر خارجها على تركيز الوجهة. تحتفظ المضيفون بتعريفات الأدوات وأوامر الإضافة/الإزالة/الترتيب/إعادة الحجم والاستمرارية ودلالات إعادة التعيين. تبقى فتحات فئة CMS وAdmin متاحة للخطافات المجال، ولكن يجب ألا تُعرّف أسطح مكتبة منفصلة أو تخطيطات للهاتف المحمول.

2026-10-17 · مشغلات Rich ActionMenu

يمكن لـ ActionMenu.renderTrigger إعادة استخدام عنصر تحكم غني مثل SelectableTile. يستقبل aria-expanded، وaria-haspopup، وdisabled، وonClick؛ ويتم نشرها على المشغل الفعلي. يحتفظ المضيف بسمات الاختيار والمظهر الخاصة بالعنصر. تظل إدارة تموضع البوابة، والتنقل بلوحة المفاتيح في القائمة، والإغلاق، وإرجاع التركيز، وأوراق الجوال الاختيارية تحت مسؤولية ActionMenu. لم يتغير المشغل الافتراضي للأزرار والأيقونات.

عناصر التحكم في نصف القطر والنطاق

يجمع RangeNumber من @qokit/components/ui/RangeNumber بين شريط نطاق أصلي وحقل رقمي دقيق Input. مرّر label وvalue وmin وmax، والخيارين step وunit، وonChange. تظهر القيمة غير المحددة بشرطة تدل على قيم مختلطة؛ ويضبط تعديل أي مدخل رقماً واحداً ضمن الحدود. يتيح onCommit تجميع التغييرات المتصلة في سجل التراجع القائم لدى التطبيق. تُشارك حالات disabled والتنقل بلوحة المفاتيح والكثافة المدمجة وRTL وأنماط التركيز؛ ويظل الحفظ مسؤولية التطبيق. يوفّر RangeNumberSkin مواضع للجذر والشريط والمدخل والوحدة.

يجمع EditorRadiusControl من @qokit/components/patterns/EditorRadiusControl بين معاينة مباشرة للشكل وأربعة مدخلات للزوايا الفعلية وRangeNumber وإعدادات أشكال اختيارية. يستخدم value وonChange الصيغة المختصرة CSS border-radius؛ ويترجم التطبيق cornerLabels وأسماء الإعدادات. يبقى ترتيب الزوايا في RTL: أعلى اليسار، أعلى اليمين، أسفل اليمين، أسفل اليسار. يقيّد max التحرير بقيم بكسل محدودة؛ وحذفه يحافظ على وحدات CSS وصيغة الزوايا البيضاوية. لا يعرض نصف القطر المختلط رقماً موحداً حتى تُضبط الزوايا الأربع معاً. يكيّف EditorRadiusControlSkin الاختياري مواضع الجذر والرسم والمعاينة والإعدادات دون تغيير الحالة أو الحفظ.

2026-10-22 · علامات التنقل النشطة على الشاشات الضيقة

يقبل PillTabs الخيار scrollActiveTabIntoView وقيمته الافتراضية false. في العلامات الأفقية، يُظهر الابن المباشر النشط PillTabLink أو PillTabButton عند الاختيار وتغيير الحجم. يتحرك شريط العلامات فقط، مع ثبات موضع الصفحة وتركيز لوحة المفاتيح. يدعم LTR وRTL بتصحيح فوري، حتى عند تقليل الحركة. تحتفظ العلامات الرأسية والاستدعاءات التي تحذف الخيار بسلوكها السابق.

في هذه الصفحة

تكامل المكونات2026-10-20 · إجراءات مستقلة لبطاقات الاختيار المرئي17-10-2026 · حركة لوحة العمل المشتركة17-10-2026 · افتراضيات المحرر المقاسة2026-09-30 · إمكانية الوصول في SelectionToolbar2026-09-10 · شارات هوية مساحة العمل2026-09-08 · EmptyState2026-09-08 · SidebarNavigation2026-09-07 - AccountDropdown / SidebarProfile2026-09-07 - FormField / AdminEntityDialog / EditorWorkspace2026-09-07 · WorkspaceLocationSync / ProjectSwitcher2026-09-07 · تنقل موحد وأسطح Qokit المستديرة2026-09-07 - ColumnLayoutنقاط الاستيرادحدود المسؤوليات العامةمحتوى العناصر المُولَّدةعناصر تحكم النموذجتحديد القائمةبطاقات المؤشراتمراجع API إضافية (بالإنجليزية؛ الترجمة قيد الانتظار) · 2026-10هيدر وفوتر المنصةاستراتيجية التوافقالتحرير بملء الشاشةSidebarToggleSlotEditorHeaderEditorNavigationMenuWorkspaceNavigationMenu / WorkspacePageHeaderEditorViewControlsLanguage / AppearancerequestWorkspaceNavigationWorkspacePanelRevealEditorViewControls / وضع العرضPlatformHeader.workspaceNavigation2026-09-06 - EditorHeader.preview / EditorViewControls.returnView2026-09-06 · Builder / CMSتذييل يُعرض على الخادم · 2026-09-07EditorHeader.titleControl / FloatingAssistant.presentation2026-09-07 · WorkspaceAssembly2026-09 · مساحات الإدارة2026-09-08 · Task focusمراجع API إضافية (بالإنجليزية؛ الترجمة قيد الانتظار)مكونات المحادثة المشتركة (مرجع إنجليزي، الترجمة لاحقًا)مراجع API إضافية (بالإنجليزية؛ الترجمة قيد الانتظار) · 2026-102026-10-10 · Pagination dot display2026-10-10 · ActionMenu search header2026-10-09 · Inline ColorPicker2026-10-07 · WorkspacePanelGrid2026-10-08 · Shared list toolbar groups2026-10-10 · EditorItemDisclosureمرجع API إضافي (بالإنجليزية؛ الترجمة قيد الانتظار) · 2026-102026-10-15 · Shared inspector choices2026-10-15 · Responsive workspace tables2026-10-14 · Independent editor panelsEditor workspace integration2026-10-15 · EditorControlGroup title actions2026-10-14 · Management groups and summaries2026-10-14 · Management content panels and disclosuresCustomizableWidgetLayoutControls / CustomizableWidgetLibrary2026-10-17 · مشغلات Rich ActionMenuعناصر التحكم في نصف القطر والنطاق2026-10-22 · علامات التنقل النشطة على الشاشات الضيقة