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

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

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

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

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

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

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

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

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

@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(). يقبل مسارًا واحدًا أو مجلدًا أو مصفوفة من أي منهما.

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/:

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

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

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

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

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

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

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. يخفف التباينات بين المتصفحات كي تعمل الأدوات المساعدة بسلوك متوقع. ومن بين أمور أخرى، يزيل الهوامش الافتراضية، ويلغي التنسيق الافتراضي للعناوين والقوائم، ويجعل الصور على مستوى الكتلة، ويعيد ضبط أنماط الحدود بحيث يرسم border-width الحد وحده، ويسمح للأزرار بوراثة الخطوط.

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

use TailwindPHP\tw;

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

توسيع Preflight

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

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:

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 كلٌّ على حدة، أضف المعدّلات إلى الاستيرادات التي تؤثر فيها:

/* 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 { … }، ويمكنك كتابتها مباشرةً أيضًا:

@import "tailwindcss/utilities.css";

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

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

هناك قيدان في الإصدار الحالي (#14):

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

تابع إلى Theme لمتغيرات السمة، أو @source للتحكم في الملفات التي يجري فحصها بحثًا عن أسماء الفئات.