مربع الاختيار

نظرة عامة

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

يتوفر بشكلين: مربع (زاوية دائرية 4 بكسل) هو الشكل الافتراضي، ودائري كمعالجة بديلة. كلا الشكلين يدعمان كل الحالات أعلاه.

الخصائص

indeterminate يُستخدم فقط على مربع أب يلخّص تحديدا جزئيا لمجموعة أبناء، ويظل يحمل قيمة checked حقيقية عند إرسال النموذج.

الحالات

يعرّف مربع الاختيار سبع حالات: الافتراضية، والتحويم، والمحدد، وغير المحدد جزئيا، والتركيز، والمعطّل، والخطأ.

• التركيز: حلقة حول المربع مبنية من brand.primary، وليس من اللون البنفسجي الظاهر في تصميم فيغما.
• المعطّل: تعبئة رمادية باهتة، ولا يستجيب للمس.
• الخطأ: لون أحمر يُرافقه دائما نص خطأ مضمّن، لا اللون وحده.

السلوك

مربع الاختيار قابل للتركيز بلوحة المفاتيح ويبدّل حالته بمفتاح Space، وتُعلن حالته (محدد، وسطي، معطّل) عبر aria-checked لتقنية المساعدة. النقر يعمل على كامل الصف (المربع والتسمية والوصف) لا المربع وحده، فالنقر على التسمية يبدّل التحديد أيضا. عند التحويم أو التركيز تظهر حلقة واضحة مبنية من brand.primary، وتتبدّل التعبئة عبر رموز الحركة (feedback). عند التعطيل يفقد التفاعل ولا يستجيب للمس.

المحتوى

التسمية اسم قصير بلا علامات ترقيم، لا جملة كاملة أبدا. سطر المساعدة الاختياري عبارة قصيرة ثانوية لا تكرر التسمية. رسالة الخطأ تسمي المتطلب الدقيق الذي فشل، لا رسالة عامة.

إمكانية الوصول

• مساحة اللمس 44×44 بكسل على الأقل على كامل الصف (المربع والتسمية والوصف)، لا المربع وحده.
• تسمية وصول عربية مطلوبة، وتتضمن سطر الوصف إن وُجد أو تُنطق معه.
• المحدد وغير المحدد جزئيا والمعطّل والخطأ تُعلن كحالة لتقنية المساعدة، لا عبر اللون وحده.
• غير المحدد جزئيا يُعلن كحالة مستقلة (مختلطة/جزئية)، لا كمحدد ولا كغير محدد.

الاتجاه والتوطين

الاتجاه منطقي: يبقى المربع عند حافة البداية والتسمية بعده في كل من الاتجاهين، والمنصة تعكس الموضع تلقائيا. علامة الصح نفسها ثابتة ولا تُعكس أبدا.

افعل ولا تفعل

الرموز المستخدمة

أمثلة

<Checkbox label="تذكرني" />
<Checkbox label="تحديد الكل" indeterminate />
<Checkbox label="أوافق على الشروط" error>
  يجب الموافقة على الشروط للمتابعة
</Checkbox>
<Checkbox label="الطلبية رقم 1042" description="غير متوفر حاليا" disabled />

الشيفرة

مربع الاختيار يُستورد من حزمة المكوّنات. الاستخدام في React أولا، ثم منطق تنسيق الصندوق: كل تقاطع حالة وتحديد يُشتق من رمز دلالي، فالتحديد تعبئة primary والخطأ يحوّل الصندوق إلى danger-out.

import { Checkbox } from "@mercato/components";

<Checkbox label="تذكرني" />
<Checkbox label="تحديد الكل" indeterminate />
<Checkbox label="أوافق على الشروط" checked error description="يجب الموافقة على الشروط للمتابعة" />
<Checkbox label="الطلبية رقم 1042" description="غير متوفر حاليا" disabled />
<Checkbox label="خيار دائري" shape="circle" />

// Box styling per state x check, tokens only. Checked fills with the
// brand primary; error turns the box red; disabled dims it.
function boxClass(state, check) {
  const filled = check !== "unchecked";
  let base;
  if (state === "error")
    base = filled ? "border-danger-out bg-danger-out text-white"
                  : "border-danger-out bg-black-oud-50 dark:bg-black-oud-900";
  else if (state === "disabled")
    base = filled ? "border-hairline bg-surface text-faint" : "border-hairline bg-surface";
  else
    base = filled ? "border-primary bg-primary text-primary-on"
                  : "border-black-oud-300 bg-black-oud-50 dark:border-black-oud-600 dark:bg-black-oud-900";
  return `grid h-4 w-4 place-items-center rounded-full border ${base}`;
}

لا يحمل الصندوق قيمة لون خام: تبديل الوضع الداكن أو إعادة العلامة يسري تلقائيا لأن كل حالة تمرّ عبر رمز دلالي.

مكوّنات ذات صلة