# التوجيهات

التوجيهات هي قواعد at-rule مسبوقة بـ`@` تكتبها في ملف الإدخال CSS لتركيب مخرجات Tailwind وتوسيعها وترتيبها. تغطي هذه الصفحة `@apply` و`@utility` و`@variant` و`@custom-variant` و`@layer`. يُشرح `@theme` في [النسق](https://tailwindphp.inline0.dev/ar/docs/usage/theme)؛ و`@plugin` في [الإضافات](https://tailwindphp.inline0.dev/ar/docs/plugins)؛ و`@source` في [@source](https://tailwindphp.inline0.dev/ar/docs/usage/source).

## `@apply`

تدرج `@apply` تصريحات الأدوات الموجودة ضمن المحدد الخاص بك. استخدمها لإضافة أنماط الأدوات إلى فئة دلالية، بما في ذلك داخل المحددات المتداخلة واستعلامات الوسائط.

```php
use TailwindPHP\tw;

$css = tw::generate('<div class="btn">', '
    @import "tailwindcss";

    @theme { --color-brand: #3b82f6; }

    .btn {
        @apply px-4 py-2 rounded-lg bg-brand text-white;
    }
');
```

تعمل المتغيرات ضمن قائمة `@apply` — إذ يوسّع `@apply bg-blue-500 hover:bg-blue-600;` حالة `:hover`، وتنتج البادئات المتجاوبة مثل `@apply px-4 md:px-6 lg:px-8;` قواعد `@media` المناسبة. ويُطبّق أيضًا المعدّل المهم (`@apply !flex;`). كما تدعم المحددات المتداخلة، لذا تطبق قاعدة مثل `.card { h2 { @apply text-xl font-bold; } }` الأدوات على `h2` المتداخل.

`@apply` عبارة: `@apply px-4 { … }` مع جسم تؤدي إلى خطأ. أما `@apply` التي تسرد معرّفات بشرطات فقط (`@apply --my-mixin;`)، فهي مزيج CSS من مسودة المزائج [CSS](https://drafts.csswg.org/css-mixins-1/#apply-rule)، وليست قائمة أدوات مساعدة؛ لذلك لا تحل TailwindPHP هذه المشكلة. ويؤدي وضع مزيج وأدوات مساعدة في `@apply` واحدة إلى خطأ (`You cannot use @apply with both mixins and utilities…`). تُسقط قواعد المزج حاليًا من المخرجات بدلًا من تمريرها ([#12](https://github.com/inline0/tailwindphp/issues/12)).

## `@utility`

يسجل `@utility` أداة مخصصة تشارك في محرك Tailwind — فتُرتب ضمن طبقة `utilities` وتقبل المتغيرات مثل الأدوات المدمجة. للأداة الثابتة متن ثابت:

```css
@utility content-auto {
    content-visibility: auto;
}
```

بما أنها أداة فعلية، تُركّب المتغيرات تلقائيًا (`hover:content-auto` و`md:content-auto`). ويمكن أن يستخدم المتن نفسه `@apply` ومحددات متداخلة:

```css
@utility btn-primary {
    @apply px-4 py-2 bg-blue-500 text-white rounded;
}

@utility card {
    color: red;
    &:hover { color: blue; }
}
```

تستخدم الأداة الوظيفية لاحقة `-*` في الاسم، وتقرأ القيمة المطابقة باستخدام `--value()`:

```css
@theme {
    --gutter-wide: 3rem;
}

@utility gutter-* {
    padding-inline: --value(--gutter-*, [length]);
    padding-inline: --spacing(--value(integer));
}
```

يحل `--value()` قيمة المرشح بمقارنتها بكل مصدر بالتتابع: مساحة أسماء في النسق (`--gutter-*`)، أو قيمة اعتباطية بنوع بيانات (`[length]`)، أو نوع قيمة مجردة (`integer` و`number` و`percentage` و`ratio`). يُحذف التصريح إذا تعذر حل `--value()` الخاص به، لذا يؤدي تكديس التصريحات إلى سلسلة بدائل احتياطية:

| الفئة | المخرج |
|---|---|
| `gutter-wide` | `padding-inline: var(--gutter-wide);` |
| `gutter-[5px]` | `padding-inline: 5px;` |
| `gutter-4` | `padding-inline: calc(var(--spacing) * 4);` |

تحل `--modifier()` الجزء الذي يلي `/` بالطريقة نفسها: باستخدام `line-height: --modifier(integer);` في النص، تُصدر `gutter-4/7` أيضًا `line-height: 7`. تتبع أسماء الأدوات المساعدة قواعد TailwindCSS v4.3.3: بحد أقصى `/` واحد، ولا يأتي `%` إلا في النهاية بعد رقم، ولا تُستخدم النقاط إلا بين الأرقام.

## `@variant`

تطبّق `@variant` متغيرًا على التصريحات داخل CSS الخاص بك، من دون تعريف أداة مساعدة:

```css
.card {
    color: red;

    @variant hover {
        color: blue;
    }

    @variant dark {
        color: white;
    }
}
```

```css
.card {
  color: red;
}
@media (hover: hover) {
  .card:hover {
    color: #00f;
  }
}
@media (prefers-color-scheme: dark) {
  .card {
    color: #fff;
  }
}
```

يمكن تكديس المتغيرات (`@variant hover:focus`)، وإدراجها مفصولة بفواصل، وتضمين بعضها داخل بعض، كما يمكنها تسمية `@custom-variant` الخاصة بك. ويُعامل `@variant` على المستوى الأعلى، إذا لم يتضمن متنًا أو تضمن `@slot`، على أنه `@custom-variant` لضمان التوافق مع الإصدارات السابقة.

## `@custom-variant`

تعرّف `@custom-variant` متغيرًا جديدًا يمكنك إضافته كبادئة إلى أي أداة مساعدة. يحدد الشكل المختصر اسم المتغير ويقدم محددًا أو قاعدة at-rule بين قوسين.

يستخدم متغير قائمة المحددات `&` للإشارة إلى العنصر:

```css
@custom-variant hocus (&:hover, &:focus);
```

ثم تُصدر `hocus:bg-blue-500` قاعدتي `:hover` و`:focus`. ويعمل شكل السمة بالطريقة نفسها:

```css
@custom-variant loading (&[data-loading="true"]);
```

يُغلّف متغير قاعدة at-rule الأدوات المساعدة المطابقة داخل تلك القاعدة:

```css
@custom-variant tablet (@media (min-width: 600px));
```

تتراكم المتغيرات المخصصة مع المتغيرات المضمنة — إذ يضمّن `sm:hocus:bg-blue-500` محدد `hocus` داخل استعلام الوسائط `sm`. للحالات الأكثر تعقيدًا، استخدم صيغة الكتلة مع `@slot` لتحديد موضع إدراج تصريحات الأداة المساعدة:

```css
@custom-variant child {
    & > * {
        @slot;
    }
}

@custom-variant sidebar-open {
    .sidebar-open & {
        @slot;
    }
}
```

## `@layer`

تتحكم `@layer` في ترتيب التتابع باستخدام طبقات التتابع الأصلية في CSS. يعلن تصريح `@layer` وحده ترتيب الطبقات؛ وتكون الغلبة للطبقات اللاحقة بصرف النظر عن خصوصية المحدد. والترتيب المعتمد في Tailwind هو:

```css
@layer theme, base, components, utilities;
```

هذا بالضبط ما تُعدّه `@import "tailwindcss"` داخليًا. يمكنك إعلان ترتيبك الخاص، أو تقسيمه على عدة تصريحات (`@layer reset, base;` ثم `@layer components, utilities;`)، وإسناد القواعد إلى طبقة مسماة باستخدام كتلة:

```php
use TailwindPHP\tw;

$css = tw::generate('<article><h1>Title</h1></article>', '
    @import "tailwindcss";

    @layer base {
        h1 { font-size: var(--text-2xl); }
        a  { color: var(--color-blue-600); text-decoration-line: underline; }
    }
');
```

تُبقي إضافة الأنماط الأساسية عبر `@layer base` هذه الأنماط أسفل `components` و`utilities`، لذا تتغلب فئة الأداة المساعدة دائمًا على الإعدادات الافتراضية للعنصر. وينطبق الأمر نفسه على `@layer components { … }` لفئات المكونات التي ينبغي أن تكون أسفل الأدوات المساعدة. وتتناول [Imports](https://tailwindphp.inline0.dev/ar/docs/usage/imports) الطبقات المجهولة والمعدّلات `layer()` على `@import`.

## الخطوات التالية

- [Theme](https://tailwindphp.inline0.dev/ar/docs/usage/theme) — رموز `@theme` ودوال السمة.
- [Imports](https://tailwindphp.inline0.dev/ar/docs/usage/imports) — `@import` والوحدات الافتراضية والمعدّلات `layer()`.
- [Plugins](https://tailwindphp.inline0.dev/ar/docs/plugins) — التوجيه `@plugin` وAPI الإضافات.
- [@source](https://tailwindphp.inline0.dev/ar/docs/usage/source) — تحكّم في الملفات والفئات التي يجري فحصها.