# أدوات الأصناف

يعني إنشاء `class` في القوالب ضم السلاسل النصية، وتبديل الأصناف حسب الشروط، ومنع الأدوات اللاحقة من التعارض مع السابقة (يجب ألا يبقى كل من `p-2` و`p-4`). في JavaScript، يُقسّم هذا العمل بين [clsx](https://github.com/lukeed/clsx) و[tailwind-merge](https://github.com/dcastil/tailwind-merge). يتضمن TailwindPHP نسخًا PHP من كليهما، لتحصل على السلوك نفسه دون سلسلة أدوات Node.js أو حزم Composer إضافية.

تغطي ثلاث دوال النطاق كله: تنشئ `cn()` وتزيل التعارضات، وتزيل `merge()` التعارضات فقط، بينما تكتفي `join()` بالضم.

## cn()

الأداة الموصى بها. تنشئ الأصناف الشرطية بأسلوب clsx أولًا، ثم تحل تعارضات Tailwind باستخدام tailwind-merge، بحيث تسود الأداة المتعارضة الأخيرة.

```php
use function TailwindPHP\cn;

// Conflicts are resolved — px-4 overrides px-2
cn('px-2 py-1', 'px-4');
// => 'py-1 px-4'

// Conditional classes via a key => bool array
cn('btn', ['btn-primary' => true, 'btn-disabled' => false]);
// => 'btn btn-primary'
```

### الوسائط المقبولة

تقبل `cn()` أي عدد من الوسائط. وتُسطّح كل وسيطة وتُصفّى وفق دلالات clsx:

| الوسيطة | السلوك |
|----------|----------|
| `string` | تُضاف كما هي. |
| `int` / `float` | تُحوّل إلى سلسلة نصية ثم تُضاف. |
| مصفوفة متسلسلة | تُعالَج عناصرها بالتكرار. |
| مصفوفة `key => bool` | يُضاف كل مفتاح إذا كانت قيمته صادقة. |
| `null` و`false` و`0` و`''` | تُتجاهل. |

```php
cn('flex', ['items-center' => true], ['p-4', ['gap-2']], null);
// => 'flex items-center p-4 gap-2'
```

### نمط المكوّنات

تتيح `cn()` إمكانية تجاوز إعدادات المكوّن: ادمج أصنافه مع ما يمرره المستدعي، وستُحسم التعارضات لصالح المستدعي.

```php
use function TailwindPHP\cn;

function Card(array $props = []): string {
    $class = cn(
        'rounded-lg border bg-card text-card-foreground shadow-sm',
        $props['class'] ?? null
    );
    return "<div class=\"{$class}\">" . ($props['children'] ?? '') . "</div>";
}

Card(['class' => 'p-6', 'children' => 'Content']);
// <div class="rounded-lg border bg-card text-card-foreground shadow-sm p-6">Content</div>
```

لأنماط المكوّنات التعريفية متعددة المحاور، اجمع `cn()` مع [variants()](https://tailwindphp.inline0.dev/ar/docs/class-utilities/variants).

## merge()

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

```php
use function TailwindPHP\merge;

merge('px-2 py-1 bg-red-500', 'px-4 bg-blue-500');
// => 'py-1 px-4 bg-blue-500'

// Conflict resolution is variant-aware
merge('hover:bg-red-500', 'hover:bg-blue-500');
// => 'hover:bg-blue-500'
```

إن `cn()` مبنية فوق clsx باستخدام `merge()`؛ لذا استخدم `merge()` مباشرةً فقط عندما لا تحتاج إلى صياغة المصفوفة الشرطية.

## join()

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

```php
use function TailwindPHP\join;

join('foo', 'bar', null, 'baz');
// => 'foo bar baz'
```

## أيّها أستخدم؟

| الدالة | تنشئ (الشروط والمصفوفات) | تحلّ التعارضات | متى تُستخدم |
|----------|:---:|:---:|----------|
| `cn()`    | نعم | نعم | الخيار الافتراضي — لإنشاء سلاسل أصناف قد تتعارض. |
| `merge()` | لا  | نعم | عندما تكون المدخلات سلاسل نصية عادية وتحتاج فقط إلى إزالة التعارضات. |
| `join()`  | نعم | لا  | عندما تعرف عدم وجود تعارضات وتريد أقل قدر من العمل. |

## الاستيرادات

```php
use function TailwindPHP\cn;
use function TailwindPHP\merge;
use function TailwindPHP\join;
```

توجد الدوال الثلاث في مساحة الأسماء الرئيسية `TailwindPHP`، وهي مضمنة مع الحزمة. إنها نسخ PHP من clsx (لـ Luke Edwards) وtailwind-merge (لـ Dany Castillo).