كان لـ Button الذي أطلقته Northwind عام 2021 تسعة props: primary، secondary، danger، small، large، outline، block، icon، وonPress. والقيم المنطقية (boolean) السبع منها وحدها تسمح بـ 128 تركيبة، ووجدت الفرق معظمها. كان في التطبيق الإنتاجي <Button primary danger small large>. كان يعرض شيئًا ما، ولم يستطع أحد أن يقول ماذا كان يُفترض أن يكون. الـ component API عقدٌ مع كل فريق يستخدم المكوّن، وكأي عقد، الجزء الصعب هو ما يسمح به.
القاعدة الأولى تخصّ شكل الـ props. إن كانت الخيارات متنافية، فمكانها prop واحد من نوع enum. وإن كان الشيء يعمل أو لا يعمل، فهو قيمة منطقية (boolean).
\ntype ButtonProps = React.ComponentProps<'button'> & {\n variant?: 'primary' | 'secondary' | 'danger';\n size?: 'sm' | 'md' | 'lg';\n loading?: boolean;\n startIcon?: React.ReactNode;\n endIcon?: React.ReactNode;\n};حين يكون variant من نوع enum، لا يمكن أن يكون primary وdanger صحيحين معًا؛ ونظام الأنواع يرفض ذلك قبل مراجعة الكود. أما loading فيبقى قيمة منطقية، لأن الزر إما في حالة تحميل أو لا، بشكل مستقل عن الـ variant الخاص به.
القاعدة الثانية هي الاتّساق بين المكوّنات. إن استخدم Button القيمة size="sm"، فكذلك يفعل Input وSelect وTabs وBadge، بالقيم الثلاث نفسها. وإن سمّى أحد المكوّنات معالج التغيير onChange ومرّر إليه القيمة الجديدة، فكلها تفعل ذلك. تحتفظ Northwind بمسرد API من صفحة واحدة لأسماء الـ props المشتركة، والمكوّنات الجديدة تعيد استخدام هذه الأسماء ما لم يوجد سبب قوي للخروج عنها.
وهذا أهمّ من أي قرار منفرد بشأن prop. المهندس الذي استخدم ثلاثة مكوّنات من Northwind يجب أن يستطيع تخمين API المكوّن الرابع بشكل صحيح. وكل تناقض ضريبة صغيرة يدفعها الجميع، كل يوم.
\nالقاعدة الثالثة: يجب ألا يسلب المكوّن أبدًا ما يقدّمه HTML أصلًا. الـ Button هو <button>، لذا يجب أن يقبل كل ما يقبله <button>، بما في ذلك سمات aria-*، وأن يمرّره:
export function Button({\n variant = 'secondary',\n size = 'md',\n loading = false,\n startIcon,\n endIcon,\n type = 'button',\n children,\n ...rest\n}: ButtonProps) {\n return (\n <button\n {...rest}\n type={type}\n className={['nw-button', rest.className].filter(Boolean).join(' ')}\n data-variant={variant}\n data-size={size}\n aria-busy={loading || undefined}\n >\n {startIcon}\n <span className=\"nw-button__label\">{children}</span>\n {endIcon}\n </button>\n );\n}لأن ref صار prop عاديًا في مكوّنات الدوال في React 19، فإنه يمرّ عبر ...rest مع كل شيء آخر، فتعمل إدارة التركيز (focus) والـ tooltips دون تغليف إضافي. وللسبب نفسه تعمل onClick وdisabled وform وaria-describedby.
الـ slot (الفتحة) مكان يمرّر فيه المستخدم محتوى بدل الإعدادات. children هو الـ slot الرئيسي؛ وstartIcon وendIcon هما slots مسمّاة. قارن بين طريقتين لإضافة أيقونة:
<Button icon=\"truck\" iconPosition=\"left\">Assign</Button> // configuration\n<Button startIcon={<TruckIcon />}>Assign</Button> // slotنسخة الإعدادات تحتاج أن يعرف الـ Button كل اسم أيقونة وكل موضع، ويُضاف إليها prop كلما أراد أحد شيئًا جديدًا. أما نسخة الـ slot فتقبل أي عنصر، فتستطيع الفرق تمرير مجموعة أيقونات مختلفة أو صورة رمزية صغيرة دون إصدار جديد. والدرس التالي يأخذ هذه الفكرة أبعد بكثير.
\nيكتب الـ Button قيم الـ props الخاصة به في السمتين data-variant وdata-size، فيعكس الـ CSS الـ API واحدًا لواحد. وكل variant يغيّر الـ component tokens وحدها:
.nw-button[data-variant=\"primary\"] {\n --nw-button-bg: var(--nw-color-action-bg);\n --nw-button-text: var(--nw-color-action-text);\n --nw-button-border: transparent;\n}الـ data attributes تُبقي نقاط ربط الأنماط مقروءة في DevTools، حيث ترى data-variant="primary" بدل اسم class مولَّد بالـ hash لا يُقرأ، ولا يمكن جمعها في تركيبة عبثية كما يمكن مع classes مثل .primary.danger.
تكتب Northwind كود الاستخدام قبل كود المكوّن. كل اقتراح مكوّن جديد يبدأ بثلاثة مقاطع: الاستخدام الأكثر شيوعًا، والاستخدام الأعقد الذي طلبه أحد، واستخدام واحد يجب أن يكون مستحيلًا. ثم تطرح المراجعة أربعة أسئلة. هل تطابق أسماء الـ props مسرد الـ API؟ هل يمكن لأي تركيبة من الـ props أن تصف شيئًا بلا معنى؟ هل يمرّر المكوّن كل ما يدعمه عنصره الأصلي؟ وما الذي سيحتاجه الفريقان الثاني والثالث اللذان سيستخدمانه ولم يحتجه الفريق الأول؟
\nتستغرق هذه المراجعة نحو ثلاثين دقيقة. أما تغيير الـ API بعد أن يعتمد عليه عشرون فريقًا فيتطلّب إصدارًا رئيسيًا (major)، ودليل انتقال، وشهورًا من المتابعة، وهذا موضوع القسم 4.
\nفي التمرين تكتب قواعد الـ variant والحجم لهذا الـ Button باستخدام الـ component tokens وحدها. وبعدها ترى ما يحدث حين يتجاوز المكوّن حدود الـ props كليًا.
\n","toc":[{"id":"sec-1","text":"الـ enums للاختيارات، والقيم المنطقية للحالات","level":2},{"id":"sec-2","text":"مفردات واحدة عبر النظام","level":2},{"id":"sec-3","text":"لا تحجب المنصّة","level":2},{"id":"sec-4","text":"الـ slots للمحتوى","level":2},{"id":"sec-5","text":"الـ variants في CSS: حوّل الـ props إلى سمات","level":2},{"id":"sec-6","text":"راجع الـ API قبل أن تبنيه","level":2}],"takeaways":["استخدم prop واحدًا من نوع enum مثلvariant للخيارات المتنافية؛ فالقيم المنطقية المنفصلة تسمح بتركيبات لا معنى لها.","اجعل أسماء الـ props وقيمها متطابقة عبر المكوّنات، حتى يعني size="sm" الشيء نفسه على Button وInput وSelect.","مرّر السمات الأصلية والـ ref إلى العنصر الأساسي، حتى لا يحجب المكوّن أبدًا ما يقدّمه HTML أصلًا.","القيم الافتراضية قرارات تصميم؛ اختر الخيار الآمن والشائع، مثل type="button" والـ variant الثانوي."],"further":[{"title":"