kreftjs 0.0.17-beta → 0.0.20-beta

package/book/ar/04-router-data-forms.md

@@ -0,0 +1,333 @@
+# الفصل الرابع: الموجِّه والبيانات والنماذج
+
+## تعريف المسارات
+
+```js
+const router = Kreftjs.router({
+  routes: [
+    { path: '/', component: 'pages/Home.kreft', meta: { title: 'الرئيسية' } },
+    { path: '/users/:id', name: 'user', component: 'pages/User.kreft', props: true },
+    { path: '/posts/:slug?', component: 'pages/Posts.kreft' },
+    { path: '/old', redirect: '/' },
+    { path: '/admin', component: 'pages/Admin.kreft', guard: () => isAdmin() || '/login' },
+    { path: '*', component: 'pages/NotFound.kreft' },
+  ],
+})
+
+Kreftjs.app('App.kreft').use(router).mount('#app')
+```
+
+```html
+<!-- App.kreft -->
+<view>
+  <nav>
+    <kreft-link to="/">الرئيسية</kreft-link>
+    <kreft-link to="/users/{user.id}">الملف الشخصي</kreft-link>
+  </nav>
+  <kreft-view></kreft-view>
+</view>
+```
+
+مع `props: true` يصل المعامل `:id` كـ prop:
+
+```html
+<!-- pages/User.kreft -->
+prop id
+derive user = users.find(id)
+action back() { $router.back() }
+```
+
+| الميزة | الطريقة |
+|---|---|
+| المسار الحالي | `$route.path` و`$route.params.id` و`$route.query.tab` و`$route.meta` |
+| التنقل | `$router.go('/users/5?tab=info')` و`$router.replace(to)` و`$router.back()` |
+| الرابط النشط | الفئتان `kreft-link-active` و`kreft-link-exact` |
+| عنوان الصفحة | `meta: { title: '…' }` |
+| فحص قبل كل صفحة | `router.before((to, from) => …)`. أرجع `false` للإيقاف أو مسارًا للذهاب إليه. |
+| فحص مسار واحد | `guard: (to, from) => …` |
+| بعد كل صفحة | `router.after((to, from) => …)` |
+
+كل ملف صفحة يُحمَّل أول مرة يفتحها أحد.
+
+## ملفات المسارات
+
+المشاريع الجديدة تحفظ صفحاتها في `frontend/routes/web.kreft`، و`index.html` يشير إليه فقط:
+
+```js
+Kreftjs.router({
+  routes: ['routes/web.kreft', 'routes/shop.kreft'],
+  layout: 'app',
+  errors: 'errors',
+  middleware: {
+    auth: (to) => (auth.user ? true : '/login?redirect=' + encodeURIComponent(to.fullPath)),
+    guest: () => (auth.user ? '/dashboard' : true),
+  },
+})
+```
+
+```js
+// routes/web.kreft
+Route.view('/', 'pages/Home.kreft').name('home').title('الرئيسية')
+Route.view('/posts/:id', 'pages/Post.kreft')
+
+Route.middleware('auth').group(() => {
+  Route.view('/dashboard', 'pages/Dashboard.kreft').middleware('verified')
+})
+
+Route.layout('guest').middleware('guest').group(() => {
+  Route.view('/login', 'pages/auth/Login.kreft').title('تسجيل الدخول')
+})
+
+Route.prefix('/account').name('account.').middleware('auth').group(() => {
+  Route.view('/settings', 'pages/account/Settings.kreft').children(() => {
+    Route.view('', 'pages/account/General.kreft')       // /account/settings
+    Route.view('mail', 'pages/account/Mail.kreft')      // /account/settings/mail
+  })
+})
+
+Route.redirect('/home', '/')
+Route.fallback('pages/NotFound.kreft')
+```
+
+| على المسار | ماذا يفعل |
+|---|---|
+| `.name('home')` | `$router.go({ name: 'home' })` |
+| `.title('Home')` | عنوان الصفحة. |
+| `.layout('guest')` و`.layout('none')` | تخطيط آخر أو بلا تخطيط. |
+| `.middleware('auth', 'role:editor')` | ينفّذ هذه قبل الصفحة. |
+| `.meta({ … })` | أي شيء آخر، في `$route.meta`. |
+| `.children(() => …)` | صفحات متداخلة تظهر في `<kreft-view>` الخاص بالصفحة. |
+
+> **ملاحظة:** وسيط `auth` في المتصفح يقرر أي الشاشات تُعرض فقط. هو لا يحمي البيانات: كل مسار API يجب أن يفحص المستخدم على الخادم.
+
+## التخطيطات (Layouts)
+
+التخطيط هو الإطار حول صفحاتك: الشريط والقائمة والتذييل. ضعه في `layouts/` واستعمل `<slot>` حيث تذهب الصفحة.
+
+```html
+<!-- layouts/app.kreft -->
+state menuOpen = false
+
+<view>
+  <header>…</header>
+  <main><slot></slot></main>
+</view>
+```
+
+| أين | ماذا تكتب |
+|---|---|
+| كل الصفحات | `Kreftjs.router({ layout: 'app', routes })` |
+| مسار واحد وأبناؤه | `{ path: '/admin', component: …, layout: 'admin' }` |
+| داخل ملف صفحة | `layout admin` في سطر وحده |
+| بلا تخطيط | `layout: false` على المسار أو `layout none` في الصفحة |
+
+عند انطباق أكثر من واحد: المسار يغلب، ثم ملف الصفحة، ثم الموجِّه. التنقل بين صفحتين تستعملان التخطيط نفسه يُبقي التخطيط على الشاشة مع حالته.
+
+وللصفحة أن تملأ أماكن أخرى في تخطيطها:
+
+```html
+<!-- في التخطيط -->
+<kreft-yield name="actions">يظهر إن لم يكن للصفحة هذا القسم</kreft-yield>
+
+<!-- في الصفحة -->
+<kreft-section name="actions">
+  <button class="primary" @click="save()">حفظ</button>
+</kreft-section>
+```
+
+## صفحات الأخطاء
+
+لكل خطأ HTTP صفحته في `errors/`. فعّلها بـ `errors: 'errors'` في الموجِّه:
+
+```text
+errors/401.kreft 402.kreft 403.kreft 404.kreft 419.kreft 429.kreft 500.kreft 503.kreft
+errors/error.kreft      أي حالة أخرى
+errors/minimal.kreft    الإطار المشترك
+```
+
+عنوان غير معروف يعرض `errors/404.kreft`. ومن أي ملف `.kreft` يعرض `abort(404)` الصفحة المناسبة:
+
+```html
+prop id
+load post = api.get('/api/posts/' + id)
+watch post.error { if (post.error && post.error.status === 404) abort(404) }
+```
+
+## العناوين النظيفة
+
+يستعمل الموجِّه افتراضيًا عناوين بلا `#` (`/users/5`). ويلزم لذلك أمران:
+
+1. وسم `<base href="/">` في `index.html` (استعمل `<base href="/demo/">` إن كان التطبيق في مجلد).
+2. أن يرسل الخادم `index.html` لكل مسار صفحة، حتى لا يكون إعادة تحميل `/users/5` خطأ 404. الأمر `npm run dev` يفعل هذا عنك.
+
+> **تنبيه مهم عند النشر:** إن بنيت الموقع بقاعدة خاطئة (مثلًا `/demo/`) وهو في الجذر، ستظهر صفحة بيضاء لأن المتصفح يطلب الملفات من `/demo/app.js`. ابنِ بـ `kreft build --base /`. تفاصيل أكثر في فصل النشر.
+
+إن لم تستطع تغيير الخادم فاستعمل `mode: 'hash'`؛ فتصير العناوين `/#/users/5`.
+
+## جلب البيانات
+
+العميل العام `api` متاح في كل ملف `.kreft`، وكذلك `Kreftjs.api` في JavaScript العادي:
+
+```js
+const users = await api.get('/api/users', { query: { page: 2 } })
+const user  = await api.post('/api/users', { name: 'سارة أحمد' })
+await api.put('/api/users/1', user)
+await api.patch('/api/users/1', { status: 'active' })
+await api.delete('/api/users/1')
+```
+
+### load: تحميل البيانات
+
+`load` يعلن مصدرًا تفاعليًا. يتولى حالة التحميل والخطأ ويجلب من جديد إذا تغيّرت القيم التي يقرؤها:
+
+```html
+<!-- pages/Posts.kreft -->
+state query = ''
+state page = 1
+
+load posts = api.get('/api/posts', { query: { q: query || undefined, page } })
+
+<view>
+  <input type="search" k-model.lazy="query" placeholder="ابحث في المقالات…">
+
+  <p k-if="posts.loading">جارٍ تحميل المقالات…</p>
+  <div k-elif="posts.error">
+    فشل التحميل: {posts.error.message}
+    <button @click={posts.reload}>حاول مجددًا</button>
+  </div>
+  <div k-else>
+    {for post in posts.data || [] key post.id}
+      <article><h3>{post.title}</h3><p>{post.body}</p></article>
+    {empty}
+      <p>لا نتائج لـ "{query}".</p>
+    {/for}
+  </div>
+
+  <button @click={() => page++}>الصفحة التالية ({page})</button>
+</view>
+```
+
+| الخاصية | المعنى |
+|---|---|
+| `posts.data` | النتيجة (`null` حتى تُحمَّل). |
+| `posts.loading` | `true` أثناء الطلب. |
+| `posts.loaded` | `true` بعد وصول أول جواب. |
+| `posts.error` | الخطأ أو `null`. |
+| `posts.reload()` | اجلب الآن من جديد. |
+
+### الجداول
+
+للجداول التي يقدّمها `kreft dev --db` أو واجهة الجداول التلقائية، يعطيك `table(name)` استدعاءات جاهزة:
+
+```html
+const posts = table('posts')
+
+load list = posts.all({ q: search, _sort: '-created_at', _limit: 10 })
+
+action createPost() {
+  const created = await posts.create({ title: 'مقال جديد' })
+  list.data = [created, ...list.data]
+}
+```
+
+الدوال: `all(query)` و`find(id)` و`count(query)` و`create(data)` و`update(id, data)` (PUT) و`patch(id, data)` و`remove(id)`.
+
+### الأخطاء
+
+الطلب الفاشل يرمي `ApiError` فيه `status` و`message` و`data` و`errors` (رسائل التحقق). مشاكل الشبكة وانتهاء المهلة لها `status` يساوي 0.
+
+```html
+state errors = {}
+
+action save() {
+  try {
+    await api.post('/api/users', form)
+  } catch (e) {
+    errors = e.errors || {}      // { email: ['The email has already been taken.'] }
+  }
+}
+```
+
+### الإعدادات
+
+```js
+Kreftjs.api.setup({
+  base: '/api',                               // فيصير api.get('users') هو /api/users
+  token: () => Kreftjs.storage.get('token'),  // يُرسل كـ Authorization: Bearer …
+  headers: { 'Accept-Language': 'ar' },
+  timeout: 10000,
+})
+
+Kreftjs.api.onError((e) => { if (e.status === 401) location.href = '/login' })
+
+const github = Kreftjs.api.create({ base: 'https://api.github.com' })    // عميل ثانٍ
+```
+
+خيارات للطلب الواحد: `query` و`headers` و`timeout` و`signal` (للإلغاء) و`full: true` (يعيد `{ data, status, headers }`).
+
+الطلبات إلى خادمك تُرسل أيضًا `X-XSRF-TOKEN` من كوكي `XSRF-TOKEN` (و`X-CSRF-TOKEN` من `<meta name="csrf-token">`)، و`X-Requested-With`.
+
+### واجهة تجريبية للتدرّب
+
+```bash
+kreft dev --api db.json              # واجهة REST على /api من ملف JSON
+kreft dev --api db.json --delay 500  # أجب ببطء لترى حالات التحميل
+```
+
+> **تحذير:** `--api` و`--db` للتطوير فقط. لا تسجيل دخول فيهما. في الإنتاج اكتب مسارات حقيقية.
+
+## النماذج والتحقق
+
+أعطِ النموذج قواعده بأسلوب تصريحي. النموذج الذي فيه أخطاء لا يُرسل أبدًا:
+
+```html
+state post = form({ title: '', email: '' }, { title: 'required|min:3|max:120', email: 'required|email' })
+
+action save() {
+  const created = await post.$submit((values) => api.post('/api/posts', values))
+  if (created) post.$reset()
+}
+
+<view>
+  <form @submit.prevent={save}>
+    <input k-model="post.title">
+    <p k-if="post.$error('title')" class="error">{post.$error('title')}</p>
+    <button disabled={post.$busy}>حفظ</button>
+  </form>
+</view>
+```
+
+| على النموذج | ما هو |
+|---|---|
+| `post.title` و`post.email` | القيم، لـ `k-model`. |
+| `post.$error('title')` | أول رسالة للحقل أو `''`. |
+| `post.$errors` | كل الرسائل: `{ title: ['…'] }`. |
+| `post.$valid` و`post.$busy` | لا أخطاء / يُرسل الآن. |
+| `post.$submit(send)` | يفحص ثم يستدعي `send(values)`. وخطأ 422 من الخادم يملأ الأخطاء نفسها. يعيد `false` إن لم يُرسل. |
+| `post.$check()` و`post.$reset(values?)` و`post.$setErrors(e)` | افحص الآن / ابدأ من جديد / اعرض أخطاء من مكان آخر. |
+
+تظهر الأخطاء بعد أول إرسال، ثم تتبع كتابتك.
+
+بلا نموذج: `validate(values, rules)` يعطي `{}` أو `{ field: ['…'] }`. ورسائلك الخاصة في الوسيط الثالث:
+
+```js
+form(values, rules, { messages: { 'title.required': 'اكتب عنوانًا.' } })
+```
+
+أسماء القواعد نفسها تعمل على الخادم في `req.validate()`، فمجموعة قواعد واحدة تصف الطرفين.
+
+### كلمات المرور
+
+القاعدة `not_common_password` ترفض الكلمات الشائعة (`password` و`12345678` …) وحرفًا مكرّرًا (`aaaaaaaa`) وتسلسلًا بسيطًا (`abcdefgh`) وما يطابق البريد. تستعملها المشاريع الجديدة مع `min:8`:
+
+```js
+password: 'required|min:8|confirmed|not_common_password'
+```
+
+هي قائمة قصيرة تعمل دون اتصال، فتمسك أسوأ الاختيارات فقط. ارفع `min` لما هو أطول (عبارة من أربع كلمات خير من خليط قصير من الرموز).
+
+## تمارين
+
+1. اكتب صفحة `Posts` فيها بحث وترقيم صفحات بـ `load`، مع زر "حاول مجددًا" عند الخطأ.
+2. اكتب نموذج تسجيل بقواعد `required|email` و`required|min:8|confirmed`، وارسمه برسائل خطأ بالعربية.
+3. أنشئ مسارات متداخلة: `/account/settings` مع تبويبين `general` و`mail`.

package/book/ar/05-arabic-rtl.md

@@ -0,0 +1,175 @@
+# الفصل الخامس: العربية والترجمة والاتجاه (RTL)
+
+Kreft يترجم النصوص ويقلب الاتجاه للغات التي تُكتب من اليمين إلى اليسار: العربية والعبرية والفارسية والأردية. هذا الفصل مخصص لنا.
+
+## ملفات الترجمة
+
+المشروع الجديد يأتي بمجلد `lang/` في جذره، وفيه العربية والإنجليزية جاهزتان: `lang/ar.json` و`lang/ar/messages.json` و`lang/ar/validation.json` و`lang/ar/pagination.json` (ويُقرأ أيضًا `frontend/lang/` و`backend/lang/` و`resources/lang/`). استعمل `lang/ar.json` للنصوص البسيطة، أو `lang/ar/messages.json` للمفاتيح المجمّعة.
+
+```json
+// lang/ar/messages.json
+{
+  "welcome": "أهلًا بك في تطبيقي",
+  "hello": "مرحبًا، :name",
+  "items": "{0} لا توجد عناصر|{1} عنصر واحد|{2} عنصران|[3,10] :count عناصر|[11,*] :count عنصرًا"
+}
+```
+
+```json
+// lang/en/messages.json
+{
+  "welcome": "Welcome to my app",
+  "hello": "Hello, :name",
+  "items": "{0} No items|{1} One item|[2,*] :count items"
+}
+```
+
+وفي أي صفحة:
+
+```html
+<h1>{$t('messages.hello', { name: user.name })}</h1>
+<p>{$choice('messages.items', count)}</p>
+```
+
+- الرسالة تستعمل `:name` للقيم.
+- للجمع افصل الصيغ بـ `|`، وحدّد المجال بين `{}` للقيمة الواحدة (`{0}` و`{2}`) أو `[من,إلى]` (`[3,10]` و`[11,*]`). هذا يناسب العربية تمامًا: صفر، وواحد، واثنان، وجمع القلة (3–10)، وما فوق (11+) بصيغة التمييز المنصوب.
+
+## تبديل اللغة
+
+```js
+Kreftjs.locale('ar')          // يتبدّل <html lang> و dir وتُعاد رسم كل الصفحات
+Kreftjs.fallbackLocale('en')  // اللغة الاحتياطية
+Kreftjs.locales()             // اللغات المحمّلة
+Kreftjs.translations('ar', { 'app.title': 'تطبيقي' })  // نصوص إضافية من الشيفرة
+```
+
+## مبدّل لغة كامل (مع التذكّر)
+
+```html
+<!-- components/LangSwitch.kreft -->
+saved lang = 'ar' as 'app.lang'
+
+watch lang { Kreftjs.locale(value) }
+on start { Kreftjs.locale(lang) }
+
+<view>
+  <button class="lang" @click="lang = lang === 'ar' ? 'en' : 'ar'">
+    {lang === 'ar' ? 'English' : 'العربية'}
+  </button>
+</view>
+```
+
+- `saved` يتذكر الاختيار بعد إعادة التحميل.
+- `watch` يطبّق اللغة عند كل تغيير.
+- `on start` يطبّقها عند فتح الصفحة.
+
+## الاتجاه
+
+يُضبط `dir` تلقائيًا من اللغة، ويمكنك ربطه بيدك:
+
+```html
+<view dir={isArabic ? 'rtl' : 'ltr'}>…</view>
+```
+
+## اكتب CSS ينقلب وحده
+
+استعمل الخصائص المنطقية (logical properties) بدل left/right:
+
+| تجنّب | استعمل |
+|---|---|
+| `margin-left` / `margin-right` | `margin-inline-start` / `margin-inline-end` |
+| `padding-left` / `padding-right` | `padding-inline-start` / `padding-inline-end` |
+| `left: 0` / `right: 0` | `inset-inline-start: 0` / `inset-inline-end: 0` |
+| `text-align: left` / `right` | `text-align: start` / `end` |
+| `border-left` / `border-right` | `border-inline-start` / `border-inline-end` |
+
+```css
+.sidebar {
+  position: fixed;
+  inset-inline-start: 0;           /* يسار في LTR، يمين في RTL */
+  padding-inline-start: 24px;
+  border-inline-end: 1px solid var(--border);
+}
+
+[dir="rtl"] .back-arrow { transform: scaleX(-1); }    /* اقلب أيقونة */
+```
+
+## نصائح عملية للتطبيقات العربية
+
+1. **الأرقام:** استعمل `Intl.NumberFormat('ar-EG')` للأرقام الهندية أو `ar-SA`/`ar-MA` لما تفضله بلدك:
+   ```html
+   derive fmt = new Intl.NumberFormat(lang === 'ar' ? 'ar-EG' : 'en-US')
+   <p>{fmt.format(total)}</p>
+   ```
+2. **التواريخ:** `new Date().toLocaleDateString('ar', { dateStyle: 'long' })`. اختر التقويم بـ `ar-SA-u-ca-islamic` إذا أردت الهجري.
+3. **الخطوط:** اختر خطًا عربيًا (مثل Cairo أو Tajawal). في تطبيقات سطح المكتب لا تعتمد على تحميل خط من الإنترنت؛ ضمّن الخط محليًا.
+4. **الأيقونات الاتجاهية:** الأسهم والرجوع تحتاج `scaleX(-1)` في RTL كما في المثال.
+5. **النص المختلط:** اللاتينية داخل العربية قد تبدّل ترتيب علامات الترقيم. غلّف المقطع بـ `<bdi>` أو `unicode-bidi: isolate`.
+6. **حقول الإدخال:** للبريد والرقم السري وأرقام الهاتف أضف `dir="ltr"` حتى تُكتب صحيحة.
+
+```html
+<input type="email" dir="ltr" k-model="form.email" placeholder="name@example.com">
+```
+
+## على الخادم
+
+لغة الطلب تأتي من `?lang=` أو كوكي `lang` أو `Accept-Language`، ورسائل الخادم تُقرأ من `lang/<locale>/`، والعربية جاهزة في المشروع الجديد:
+
+```json
+// lang/ar/validation.json  (موجود أصلًا في المشروع الجديد)
+{
+  "required": "حقل :attribute مطلوب.",
+  "email": "يجب أن يكون :attribute عنوان بريد إلكتروني صالح.",
+  "min": { "string": "يجب أن يحتوي :attribute على :min أحرف على الأقل." },
+  "attributes": { "email": "البريد الإلكتروني", "password": "كلمة المرور" },
+  "not_common_password": "كلمة المرور شائعة جدًا أو سهلة التخمين. اختر غيرها."
+}
+```
+
+المفتاح `attributes` يترجم أسماء الحقول داخل الرسائل: فتظهر "حقل البريد الإلكتروني مطلوب" بدل "حقل email مطلوب".
+
+وللتخصيص الدقيق لنموذج بعينه استعمل `messages()` في `FormRequest`.
+
+## مثال: صفحة هبوط ثنائية اللغة مع SEO
+
+```html
+<!-- pages/Home.kreft -->
+import LangSwitch from '../components/LangSwitch.kreft'
+
+state count = 3
+
+<view>
+  <header class="top">
+    <h1>{$t('messages.hello', { name: 'الزائر' })}</h1>
+    <lang-switch></lang-switch>
+  </header>
+  <p>{$choice('messages.items', count)}</p>
+  <button @click="count++">+</button>
+</view>
+
+<style scoped>
+.top {
+  display: flex;
+  justify-content: space-between;
+  padding-inline: 24px;
+}
+</style>
+```
+
+ولظهور الصفحة صحيحة لمحركات البحث بلغتين، أعلن البدائل في `backend/routes/seo.js` (انظر فصل النشر):
+
+```js
+module.exports = {
+  '/': {
+    title: 'متجري',
+    description: 'كل ما يحتاجه بيتك',
+    alternates: { en: 'https://example.com/', ar: 'https://example.com/ar/' },
+  },
+}
+```
+
+## تمارين
+
+1. اجعل تطبيقك ثنائي اللغة (عربي/إنجليزي) واحفظ اللغة المختارة.
+2. حوّل كل `margin-left` و`padding-right` في CSS تطبيقك إلى خصائص منطقية وجرّب التبديل.
+3. اكتب مكوّن سعر يعرض المبلغ بالأرقام الهندية عند العربية.