# الاستيرادات والوحدات الافتراضية

تحل TailwindPHP قواعد `@import` قبل التجميع. يمكن أن تشير الاستيرادات إلى وحدات افتراضية مدمجة (`tailwindcss` وما شابهها)، أو إلى ملفات على القرص عبر الخيار `importPaths`، أو إلى أي شيء تُعيده من محلّل مخصص.

## الوحدات الافتراضية

تُعد `@import "tailwindcss"` نقطة الدخول التي تستخدمها معظم المشاريع. وتتوسع إلى الأسطر الأربعة أدناه — تصريح ترتيب الطبقات والاستيرادات الفرعية الثلاثة، مع إسناد كل منها إلى طبقة التتابع الخاصة بها:

```css
@layer theme, base, components, utilities;
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "tailwindcss/utilities.css" layer(utilities);
```

كل استيراد فرعي هو بحد ذاته وحدة افتراضية يمكنك استيرادها منفردة. الوحدات الافتراضية المتاحة هي:

| الوحدة | المحتويات |
|--------|----------|
| `tailwindcss` | الحزمة الكاملة: السمة + Preflight + الأدوات المساعدة. |
| `tailwindcss/theme.css` | متغيرات السمة فقط (الألوان، وأساس التباعد، ونقاط التوقف، وغيرها). |
| `tailwindcss/preflight.css` | إعادة الضبط الأساسية في Preflight. |
| `tailwindcss/utilities.css` | طبقة الأدوات المساعدة. |
| `tw-animate-css` | أدوات المساعدة الخاصة بالرسوم المتحركة `tw-animate-css`. |

يتيح لك استيراد الأجزاء منفردة تخطي Preflight أو إعادة ترتيب الطبقات (انظر أدناه).

## الرسوم المتحركة باستخدام tw-animate-css

[tw-animate-css](https://github.com/Wombosvideo/tw-animate-css) مكتبة رسوم متحركة لـ TailwindCSS v4 — بديل مباشر لـ `tailwindcss-animate`. وهي متوفرة كوحدة افتراضية مدمجة، لذا فإن استيرادها إلى جانب طبقة الأدوات المساعدة يجعل فئات رسوم الدخول والخروج تُجمّع مثل أي أداة مساعدة أخرى:

```css
@import "tw-animate-css";
@import "tailwindcss/utilities.css";
```

تشمل أدوات الرسوم المتحركة المساعدة ما يلي:

- **الدخول / الخروج** — `animate-in`، `animate-out`
- **التلاشي** — `fade-in`، `fade-out`
- **التكبير** — `zoom-in`، `zoom-out`
- **الدوران** — `spin-in`، `spin-out`
- **التمويه** — `blur-in`، `blur-out`
- **الانزلاق** — `slide-in-from-top` / `-bottom` / `-left` / `-right` وما يقابلها من `slide-out-to-*`، إضافة إلى `-start` / `-end` المتوافقين مع RTL
- **التوقيت** — `duration-*`، `delay-*`، `repeat-1` / `repeat-infinite`، `direction-normal` / `-reverse` / `-alternate`، و`fill-mode-none` / `-forwards` / `-backwards` / `-both`
- **حالة التشغيل** — `running`، `paused`
- **رسوم المكونات المتحركة** — `accordion-down` / `accordion-up`، `collapsible-down` / `collapsible-up`، و`caret-blink`

تتراكم هذه الفئات مع متغيرات Tailwind مثل أي أداة مساعدة أخرى، ما يجعلها مناسبة مباشرة لأنماط مربعات الحوار والقوائم المنسدلة في shadcn/ui.

## الخيار `importPaths`

لحل `@import` باستخدام نظام الملفات، مرّر `importPaths` في صيغة المصفوفة من `generate()`. يقبل مسارًا واحدًا أو مجلدًا أو مصفوفة من أي منهما.

```php
use TailwindPHP\tw;

// Single file
$css = tw::generate([
    'content'     => '<div class="flex btn">Hello</div>',
    'importPaths' => '/path/to/styles.css',
]);

// Directory (loads all .css files alphabetically)
$css = tw::generate([
    'content'     => '<div class="flex btn">Hello</div>',
    'importPaths' => '/path/to/css/',
]);

// Multiple paths — files and directories
$css = tw::generate([
    'content'     => '<div class="flex btn card">Hello</div>',
    'importPaths' => [
        '/path/to/base.css',
        '/path/to/components/',
    ],
]);

// Combine with inline css
$css = tw::generate([
    'content'     => '<div class="flex btn custom">Hello</div>',
    'css'         => '.custom { color: red; }',
    'importPaths' => '/path/to/styles.css',
]);
```

### الاستيرادات المتداخلة

تُحل الاستيرادات داخل الملف المُحمّل نسبةً إلى ذلك الملف. إذا احتوى `/path/to/styles.css` على `@import "./components/buttons.css"`، فسيُحل المسار نسبةً إلى `/path/to/`:

```css
/* /path/to/styles.css */
@import "tailwindcss";
@import "./components/buttons.css";
@import "./components/cards.css";

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

### إزالة التكرار

لا يؤدي استيراد الملف أو الوحدة الافتراضية نفسها أكثر من مرة إلى أي أثر بعد الاستيراد الأول — إذ تُزال تلقائيًا الأسطر المتكررة من `@import "tailwindcss"`، أو الملفات التي تستورد المكوّن الجزئي نفسه. كما يحمي ذلك من الاستيرادات الدائرية.

## المحلّل المخصص

لأنظمة الملفات الافتراضية أو قواعد البيانات أو أي مصدر غير قائم على نظام الملفات، مرّر دالة قابلة للاستدعاء إلى `importPaths`. تتلقى الدالة URI الاستيراد والمجلد الأساسي الذي يُحل الاستيراد نسبةً إليه، وتُعيد CSS أو `null`:

```php
use TailwindPHP\tw;

$css = tw::generate([
    'content'     => '<div class="flex virtual-class">Hello</div>',
    'importPaths' => function (?string $uri, ?string $fromFile): ?string {
        if ($uri === null) {
            // Entry CSS — returned when no file is supplied
            return '@import "tailwindcss"; @import "custom.css";';
        }
        if ($uri === 'custom.css') {
            return '.virtual-class { color: purple; }';
        }
        return null; // Unknown imports are silently skipped
    },
]);
```

عندما تكون `$uri` هي `null` (في الاستدعاء الأول، ومع وسيط ثانٍ قيمته `null` أيضًا)، أعدّ CSS الرئيسي. أما أي URI آخر، فأعدّ محتوى CSS الخاص به، أو `null` للرجوع إلى البحث في نظام الملفات، الذي يتخطى الاستيراد بصمت إذا لم يعثر على شيء.

## ما قبل الطباعة

Preflight هو إعادة الضبط الأساسية ذات الرأي المحدد في Tailwind، المبنية على [modern-normalize](https://github.com/sindresorhus/modern-normalize). يخفف التباينات بين المتصفحات كي تعمل الأدوات المساعدة بسلوك متوقع. ومن بين أمور أخرى، يزيل الهوامش الافتراضية، ويلغي التنسيق الافتراضي للعناوين والقوائم، ويجعل الصور على مستوى الكتلة، ويعيد ضبط أنماط الحدود بحيث يرسم `border-width` الحد وحده، ويسمح للأزرار بوراثة الخطوط.

تأتي Preflight ضمن `@import "tailwindcss"` — فإذا استوردت الحزمة الكاملة، فهي متاحة لديك بالفعل:

```php
use TailwindPHP\tw;

$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'css'     => '@import "tailwindcss";',
]);
```

### توسيع Preflight

أضف أنماطك الأساسية فوق Preflight باستخدام `@layer base`:

```php
use TailwindPHP\tw;

$css = tw::generate([
    'content' => '<article><h1>Title</h1><p>Content</p></article>',
    'css'     => '
        @import "tailwindcss";
        @layer base {
            h1 { font-size: var(--text-2xl); }
            h2 { font-size: var(--text-xl); }
            a  { color: var(--color-blue-600); text-decoration-line: underline; }
        }
    ',
]);
```

### تعطيل Preflight

عند الدمج في مشروع موجود، استورد الأجزاء التي تحتاج إليها فقط واحذف سطر Preflight:

```php
use TailwindPHP\tw;

$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'css'     => '
        @layer theme, base, components, utilities;
        @import "tailwindcss/theme.css" layer(theme);
        @import "tailwindcss/utilities.css" layer(utilities);
    ',
]);
```

## معدّلات الاستيراد

عند استيراد ملفات Tailwind كلٌّ على حدة، أضف المعدّلات إلى الاستيرادات التي تؤثر فيها:

```css
/* Assign the import to a cascade layer */
@import "tailwindcss/utilities.css" layer(utilities);

/* prefix affects both theme variables and utilities */
@import "tailwindcss/theme.css" layer(theme) prefix(tw);
@import "tailwindcss/utilities.css" layer(utilities) prefix(tw);

/* important affects utilities */
@import "tailwindcss/utilities.css" layer(utilities) important;

/* theme(static) or theme(inline) affects theme variables */
@import "tailwindcss/theme.css" layer(theme) theme(static);

/* theme(reference): utilities use the variables with a fallback, no :root block */
@import "tailwindcss/theme.css" layer(theme) theme(reference);
```

## الاستيرادات المرجعية

يحمّل `@import "…" reference` ملفًا لاستخدام تعريفاته فقط: يمكن استخدام قيم `@theme` وتعريفات `@utility` و`@custom-variant` داخله، لكن الملف لا يُصدر أي CSS خاص به. وهذا يعادل تغليف محتويات الملف ضمن `@media reference { … }`، ويمكنك كتابتها مباشرةً أيضًا:

```css
@import "tailwindcss/utilities.css";

@media reference {
    @theme {
        --color-brand: #f00;
    }
}
```

ثم يُجمّع `bg-brand` إلى `background-color: var(--color-brand, #f00);`، ولا يُصدر أي تصريح `--color-brand`.

هناك قيدان في الإصدار الحالي ([#14](https://github.com/inline0/tailwindphp/issues/14)):

- ضع الاستيرادات المرجعية وكتل `@media reference` **بعد** `@import` الخاص بـ `tailwindcss` أو `tailwindcss/utilities.css`. إذا وُضعت قبله، فستكون النتيجة فارغة بالكامل.
- لا تأثير لـ `reference` على الوحدات الافتراضية المدمجة (`@import "tailwindcss" reference;`) حتى الآن: إذ يظل كل من السمة وPreflight والأدوات المساعدة مُصدرًا.

تابع إلى [Theme](https://tailwindphp.inline0.dev/ar/docs/usage/theme) لمتغيرات السمة، أو [@source](https://tailwindphp.inline0.dev/ar/docs/usage/source) للتحكم في الملفات التي يجري فحصها بحثًا عن أسماء الفئات.