التثبيت

1. هيّئ فاصلة مرة واحدة في كل مشروع. يكتب هذا الأمر الملف components.json، الذي يقرؤه كل أمر add:

npx @smicolon/fasla-ui@latest init

هل أعددت مشروعك بالحزمة @smicolon/cli؟ إذا أعددته بالإصدار 0.4 أو أحدث، فتابع العمل بهذا الأمر في المشروع نفسه، ولا تحتاج إلى إعادة تشغيل أي أمر. وإذا أعددته بالإصدار 0.3 أو أقدم، فشغّل الأمر npx @smicolon/fasla-ui@latest init مرة واحدة أولًا. يُصلح هذا الأمر الملف components.json، الذي لا تستطيع أداة الأوامر في shadcn/ui قراءته قبل ذلك، وينقل الملفات التي وضعتها تلك الإصدارات في مجلد خاطئ.

يكتب الأمر init أيضًا الدالة المساعدة cn، ويثبّت الحزمتين اللتين تستوردهما بمدير الحزم (package manager) في مشروعك. إذا فشل التثبيت، يطبع الأمر init الأمر الذي تشغّله، وهو أحد هذه الأوامر:

npm install clsx tailwind-merge

في Tailwind 3، يثبّت الأمر tailwind-merge@^2، لأن الإصدار 3 من tailwind-merge يدعم Tailwind 4 وحده. ويستبدل الأمر init والأمر add أيضًا أي tailwind-merge إصداره 3، أو قد يصير 3:

npm install clsx tailwind-merge@^2

2. أضف مكوّنًا:

npx @smicolon/fasla-ui@latest add button

أو أضف عدة مكوّنات دفعة واحدة:

npx @smicolon/fasla-ui@latest add card input badge

ثم يثبّت الأمر add الحزم التي تستوردها المكوّنات بمدير الحزم (package manager) في مشروعك، ويتخطى أي حزمة مثبّتة فيه أصلًا بإصدار متوافق. إذا فشل التثبيت، يُبقي الأمر add الملفات التي كتبها ويطبع الأمر الذي تشغّله. لطباعة الأمر بدل التثبيت، أضف الخيار --no-install.

اعرض كل ما يقدّمه السجل (registry):

npx @smicolon/fasla-ui@latest list

بلا أسئلة: لوكلاء الذكاء الاصطناعي وأنظمة التكامل المستمر (CI)

لا يطرح الأمر init أسئلة إلا إذا كان يعمل في طرفية (terminal) يتفاعل معها مستخدم. وإذا شُغّل دونها، كما يفعل وكيل ذكاء اصطناعي أو مهمة تكامل مستمر، فلن ينتظر: مرّر --yes لقبول كل القيم الافتراضية، أو مرّر الخيارات الثلاثة كلها: --path، --style، --theme. وإذا غاب أيٌّ منها، يعرض الأمر init الخيارات الناقصة، ولا يكتب شيئًا، وينتهي بخطأ.

• --yes (-y) يقبل كل القيم الافتراضية ولا يطرح أي سؤال.
• --path هو المجلد الذي توضع فيه المكوّنات، مثل src/components. تضعها الأداة في مجلد ui تحته، فيعطي src/components/ui النتيجة نفسها.
• --style هو نمط shadcn الذي يُكتب في components.json: default أو new-york.
• --theme هو طبقة المظهر: fasla لألوان فاصلة، أو brand للإبقاء على ألوانك.
• --no-install يطبع أوامر التثبيت بدلًا من تنفيذها.

أمثلة:

npx @smicolon/fasla-ui@latest init --yes
npx @smicolon/fasla-ui@latest init --path src/components --style default --theme fasla
npx @smicolon/fasla-ui@latest add button --yes

وعند الانتهاء يعرض الأمر init كل ملف أنشأه أو غيّره، والأمر الذي تشغّله بعده. ويحتاج الأمر add أيضًا إلى --yes حين لا توجد طرفية.

تبدأ من الصفر: استخدم ألوان فاصلة. تحصل على ألوان فاصلة للوضعين الفاتح والداكن، مع نصف قطر الزوايا (radius) والخط Geist، فوق الطبقة الأساسية:

npx shadcn@latest add https://fasla.smicolon.com/r/theme.json https://fasla.smicolon.com/r/font-geist.json

في Next.js 14، أعِدّ المشروع بالأمر npx @smicolon/fasla-ui@latest init، لا بالأمر shadcn init: يكتب إعداد shadcn/ui أنماط Tailwind 4 ويحمّل الخط Geist من next/font، ولا يتوفر أيٌّ منهما في Next.js 14، فيفشل البناء. ثم احذف الرابط font-geist.json من الأمر، لأن قالب Next.js 14 يحمّل الخط Geist أصلًا:

npx shadcn@latest add https://fasla.smicolon.com/r/theme.json

لديك هوية بصرية: احتفظ بألوانك. تحصل على الطبقة الأساسية وحدها: الـ tokens غير الموجودة في shadcn/ui، مثل النجاح، التحذير، المعلومات، ألوان Soft الخفيفة، مع سلّم أحجام النص بارتفاعات أسطر عربية، وقواعد الكتابة العربية، والخط Cairo. لا تغيّر أي لون موجود في مشروعك:

npx shadcn@latest add https://fasla.smicolon.com/r/theme-base.json

1. ثبّت الاعتماديات (dependency):

npm install class-variance-authority clsx tailwind-merge framer-motion

في Tailwind 3، ثبّت tailwind-merge@^2 بدلًا منها. يدعم الإصدار 3 من tailwind-merge إطار Tailwind 4 وحده، ويحذف في Tailwind 3 الأصناف (classes) التي لا يعرفها، مثل outline:

npm install class-variance-authority clsx tailwind-merge@^2 framer-motion

2. أضف الدالة المساعدة cn إلى مشروعك:

// lib/utils.ts
import { type ClassValue, clsx } from "clsx"
import { extendTailwindMerge } from "tailwind-merge"

const twMerge = extendTailwindMerge({
  extend: { classGroups: { "font-size": [{ text: ["xxs", "link", "list-header"] }] } },
})

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

3. انسخ كل مكوّن من ملفه في السجل (registry)، مثل https://fasla.smicolon.com/r/button.json للمكوّن Button. يسرد الملف https://fasla.smicolon.com/r/registry.json المكوّنات كلها.

في كل ملف، يحمل files الشيفرة المصدرية في content، والمسار الذي تحفظها فيه في target. يسرد dependencies الحزم التي تثبّتها، ويسرد registryDependencies مكوّنات فاصلة الأخرى التي يحتاجها المكوّن، فتنسخها بالطريقة نفسها.