kreftjs 0.0.20-beta → 0.0.21-beta

package/book/ar/18-tabs-offline.md

@@ -0,0 +1,168 @@
+# الفصل الثامن عشر (خبير): مزامنة بين التبويبات والعمل دون اتصال
+
+Kreft يحفظ الحالة المشتركة بين التبويبات **تلقائيًا** (راجع `saved` في الفصل الثالث): غيّر قيمة في تبويب فتراها في الآخر. هنا نبني فوق ذلك طبقتين احترافيتين:
+
+1. **حضور (Presence):** من المفتوح الآن؟ رسائل حيّة بين التبويبات عبر `BroadcastChannel`.
+2. **طابور دون اتصال (Offline queue):** الأوامر تُحفظ وتُرسل عند عودة الاتصال، دون أن يفقد المستخدم ما كتبه.
+
+**الشيفرة جُرِّبت** بفتح تبويبين وحجب الشبكة.
+
+## 1) المنطق المشترك: الحضور بين التبويبات
+
+```js
+// logic/tabs.js — من مفتوح الآن في "الغرفة"؟
+export function usePresence(room = 'default') {
+  const channel = new BroadcastChannel('kreft-' + room)
+  const me = Math.random().toString(36).slice(2, 8)
+  const s = Kreftjs.state({ peers: [] })
+
+  const ping = () => channel.postMessage({ type: 'ping', id: me, at: Date.now() })
+
+  channel.onmessage = (e) => {
+    if (e.data.id === me) return                     // رسالتنا نحن
+    if (e.data.type === 'ping') {
+      s.peers = [...s.peers.filter((p) => p.id !== e.data.id), { id: e.data.id, at: e.data.at }]
+    } else if (e.data.type === 'bye') {
+      s.peers = s.peers.filter((p) => p.id !== e.data.id)
+    }
+  }
+
+  ping()
+  const timer = setInterval(() => {
+    ping()
+    s.peers = s.peers.filter((p) => Date.now() - p.at < 6000)   // نسقط الصامت منذ 6 ثوانٍ
+  }, 3000)
+
+  window.addEventListener('beforeunload', () => channel.postMessage({ type: 'bye', id: me }))
+  Kreftjs.onDestroy(() => {
+    clearInterval(timer)
+    channel.postMessage({ type: 'bye', id: me })
+    channel.close()
+  })
+
+  return {
+    get peers() { return s.peers },
+    get count() { return s.peers.length },
+  }
+}
+```
+
+- كل تبويب يبثّ `ping` كل 3 ثوانٍ، والآخرون يجدّدون وجوده.
+- التبويب الصامت (أُغلق أو جُمّد) يختفي بعد 6 ثوانٍ.
+- `Kreftjs.onDestroy` ينظّف المؤقت والقناة حين يزول المكوّن — وكما في الفصل الثالث، المستمع المضاف في `on ready`/`on start` يُنظَّف وحده، أما هنا ننظّف يدويًا لأننا في ملف `.js`.
+
+## 2) المنطق المشترك: طابور دون اتصال
+
+```js
+// logic/offline.js — الأمر يُحفظ ويُرسل عند عودة الاتصال
+export function useOfflineQueue() {
+  const s = Kreftjs.state({
+    online: navigator.onLine,
+    pending: Kreftjs.storage.get('offline-queue') || [],
+  })
+
+  async function flush() {
+    const list = s.pending
+    if (!list.length) return
+    const done = []
+    for (const item of list) {
+      try {
+        await api.post(item.url, item.body)
+        done.push(item)
+      } catch (e) {
+        break                       // ما زلنا دون اتصال: توقف وأبقِ الباقي
+      }
+    }
+    s.pending = list.filter((x) => !done.includes(x))
+    Kreftjs.storage.set('offline-queue', s.pending)
+  }
+
+  function enqueue(url, body) {
+    s.pending = [...s.pending, { url, body }]
+    Kreftjs.storage.set('offline-queue', s.pending)
+    if (s.online) flush()
+  }
+
+  window.addEventListener('online', () => { s.online = true; flush() })
+  window.addEventListener('offline', () => { s.online = false })
+
+  return {
+    get online() { return s.online },
+    get pending() { return s.pending },
+    enqueue, flush,
+  }
+}
+```
+
+- الطابور محفوظ في `Kreftjs.storage`، فينجو من إغلاق التبويب والجهاز.
+- `flush` يرسل بالترتيب ويتوقف عند أول فشل (لا يرسل ما بعده خارج الترتيب).
+- لا نرسل في كل مرة مباشرة: الأوامر تتكدس ثم تُغسل دفعة عند عودة الشبكة.
+
+## 3) تطبيق ملاحظات يجمع الاثنين
+
+```html
+<!-- pages/Sync.kreft -->
+import { usePresence } from '../logic/tabs.js'
+import { useOfflineQueue } from '../logic/offline.js'
+
+use presence = usePresence('notes')
+use queue = useOfflineQueue()
+
+// saved يتزامن بين التبويبات وحده (الفصل الثالث)
+saved notes = []
+saved draft = ''
+
+action add() {
+  if (!draft.trim()) return
+  const text = draft
+  notes = [{ id: Date.now(), text }, ...notes]
+  draft = ''
+  queue.enqueue('/api/notes', { text })
+}
+
+<view>
+  <h1>مزامنة حيّة</h1>
+
+  <p>
+    التبويبات المفتوحة الآن: <b>{presence.count}</b>
+    <span k-if="!queue.online" class="offline">· دون اتصال، ستُرسل لاحقًا</span>
+  </p>
+
+  <div class="row">
+    <input k-model="draft" @keydown.enter="add()" placeholder="اكتب ملاحظة…">
+    <button @click="add">أضف</button>
+  </div>
+
+  {for n in notes key n.id}
+    <p class="note">{n.text}</p>
+  {empty}
+    <p>لا ملاحظات بعد.</p>
+  {/for}
+
+  <p k-if="queue.pending.length" class="pending">في الانتظار: {queue.pending.length} عنصر</p>
+</view>
+
+<style scoped>
+.row { display: flex; gap: 8px; }
+.offline { color: var(--danger, #b33); }
+.pending { opacity: .7; }
+</style>
+```
+
+## 4) ما لاحظناه أثناء الاختبار
+
+- فتحنا التبويب نفسه مرتين: إضافة ملاحظة في الأول ظهرت في الثاني **فورًا** (بفضل `saved`).
+- عدّاد "التبويبات المفتوحة" أصبح 1 ثم عاد 0 عند إغلاق التبويب الثاني (بعد 6 ثوانٍ كحد أقصى).
+- بحجب الشبكة (DevTools › Network › Offline) ثم الإضافة: ظهرت الملاحظة محليًا وعداد "في الانتظار" = 1، وعند إعادة الاتصال أُرسل الطلب واختفى العداد.
+
+## تنبيهات
+
+- `BroadcastChannel` يعمل بين تبويبات **نفس الموقع** فقط، ولا يعمل بين متصفحين مختلفين.
+- مزامنة `saved` بين التبويبات تقوم على حدث `storage` القياسي، فلا تغيّر القيمة المفتاحية (`as '…'`) إلا بقصد.
+- الطابور هنا يحفظ الطلبات بلا مصادقة إضافية: في تطبيق حقيقي أضف رمز المستخدم ورتّب الأوامر، وفكّر في تعارض "آخر من يكتب يفوز".
+
+## تمارين
+
+1. أضف إلى `usePresence` اسم المستخدم ليعرض "سارة تعدّل الآن" بدل معرّف عشوائي.
+2. اجعل الطابور يرسل أيضًا الأوامر المحذوفة (`DELETE`) بترتيبها مع الإنشاء.
+3. أضف مؤشر "قيد المزامنة" دوّارًا يظهر أثناء `flush` وزر "أعد المحاولة الآن".

package/book/ar/19-wizard.md

@@ -0,0 +1,196 @@
+# الفصل التاسع عشر (خبير): معالج إعداد متعدد الخطوات مع استئناف وحراسة المسارات
+
+المعالج (Wizard) يجمع كل مهارات هذا الكتاب في مثال واحد: مخزن محفوظ للاستئناف، ومكوّنات متعددة تتبدل بـ `keep`، وتحقق لكل خطوة قبل الانتقال، وحراسة للمسارات تمنع القفز، وحركة خفيفة. سنبني "إعداد الحساب" من ثلاث خطوات.
+
+**جُرِّبت الشيفرة** خطوة خطوة في المتصفح.
+
+## 1) المخزن المحفوظ (القلب النابض)
+
+حالة المعالج تعيش في مخزن واحد محفوظ، فتنجو من إعادة التحميل وتُشارك بين الصفحات:
+
+```js
+// logic/wizard.js — أنشئه مرة قبل الموجِّه
+Kreftjs.store('wizard', {
+  step: 1,
+  data: { name: '', email: '', plan: 'basic' },
+  completed: false,
+  next() { if (this.step < 3) this.step++ },
+  prev() { if (this.step > 1) this.step-- },
+  finish() { this.completed = true },
+}, { saved: true })
+```
+
+- `saved: true` يحفظ `step` و`data` و`completed` في `localStorage` (الدوال لا تُحفظ).
+- كل مكوّن يكتب `use wizard` فيرى الحالة نفسها ويغيّرها، وكل تغيير يحدّث كل من يقرؤها.
+
+## 2) الخطوات الثلاث
+
+كل خطوة مكوّن مستقل يربط حقوله مباشرة بالمخزن:
+
+```html
+<!-- pages/wizard/Step1.kreft -->
+use wizard
+
+<view>
+  <h2>١) معلوماتك</h2>
+  <label>الاسم
+    <input k-model="wizard.data.name" placeholder="اسمك الكامل">
+  </label>
+  <label>البريد
+    <input type="email" k-model="wizard.data.email" placeholder="you@example.com">
+  </label>
+</view>
+```
+
+```html
+<!-- pages/wizard/Step2.kreft -->
+use wizard
+
+<view>
+  <h2>٢) خطتك</h2>
+  <label><input type="radio" value="basic" k-model="wizard.data.plan"> أساسية</label>
+  <label><input type="radio" value="pro" k-model="wizard.data.plan"> احترافية</label>
+</view>
+```
+
+```html
+<!-- pages/wizard/Step3.kreft -->
+use wizard
+
+<view>
+  <h2>٣) راجع بياناتك</h2>
+  <dl>
+    <dt>الاسم</dt><dd>{wizard.data.name}</dd>
+    <dt>البريد</dt><dd>{wizard.data.email}</dd>
+    <dt>الخطة</dt><dd>{wizard.data.plan}</dd>
+  </dl>
+</view>
+```
+
+## 3) صفحة المعالج
+
+```html
+<!-- pages/wizard/Wizard.kreft -->
+use wizard
+
+state errors = {}
+
+const stepRules = {
+  1: { name: 'required|min:2', email: 'required|email' },
+  2: { plan: 'required' },
+  3: {},
+}
+
+action next() {
+  errors = validate(wizard.data, stepRules[wizard.step] || {})
+  if (Object.keys(errors).length) return      // أبقِ المستخدم في خطوته
+  wizard.next()
+}
+action prev() { wizard.prev() }
+action finish() { wizard.finish(); $router.go('/wizard/done') }
+
+derive pct = Math.round(((wizard.step - 1) / 2) * 100)
+
+<view>
+  <h1>إعداد الحساب</h1>
+
+  <div class="progress" aria-hidden="true">
+    <div class="bar" style="width: {pct}%"></div>
+  </div>
+
+  <!-- keep يبقي حالة كل خطوة حين نعود إليها -->
+  <kreft-component :is="'Step' + wizard.step" keep></kreft-component>
+
+  <p k-if="Object.keys(errors).length" class="errors">
+    {Object.values(errors).flat().join(' · ')}
+  </p>
+
+  <div class="actions">
+    <button k-if="wizard.step > 1" @click="prev">السابق</button>
+    <button k-if="wizard.step < 3" class="primary" @click="next">التالي</button>
+    <button k-if="wizard.step === 3" class="primary" @click="finish">إنهاء</button>
+  </div>
+</view>
+
+<style scoped>
+.progress { height: 8px; background: var(--border, #ddd); border-radius: 4px; overflow: hidden; }
+.bar { height: 100%; background: var(--accent, #4a7); transition: width .25s ease; }
+.actions { display: flex; gap: 8px; margin-block-start: 16px; }
+.errors { color: var(--danger, #b33); }
+</style>
+```
+
+- **`validate`** قبل `wizard.next()`: لا ينتقل المستخدم إلا بعد أن تسلم حقول خطوته.
+- **`keep`** على `<kreft-component :is>` يبقي ما كتبه المستخدم في الخطوة 1 حين يعود إليها من الخطوة 2.
+- **`derive pct`** يحرّك شريط التقدم وحده.
+
+## 4) التسجيل والحراسة
+
+سجّل مكوّنات الخطوات وأنشئ الموجّه (أنشئ المخزن أولًا):
+
+```js
+Kreftjs.store('wizard', { /* كما أعلاه */ }, { saved: true })
+
+const wizard = Kreftjs.store('wizard')   // نقرؤه في الحراسة
+
+const router = Kreftjs.router({
+  routes: [
+    { path: '/wizard', component: 'pages/wizard/Wizard.kreft', guard: () => auth.user ? true : '/login' },
+    { path: '/wizard/done', component: 'pages/wizard/Done.kreft', guard: () => wizard.completed ? true : '/wizard' },
+  ],
+})
+
+Kreftjs.app('App.kreft')
+  .component('Step1', 'pages/wizard/Step1.kreft')
+  .component('Step2', 'pages/wizard/Step2.kreft')
+  .component('Step3', 'pages/wizard/Step3.kreft')
+  .use(router)
+  .mount('#app')
+```
+
+- حراسة `/wizard` تتطلب الدخول، وحراسة `/wizard/done` تمنع فتح صفحة الإنجاز قبل `finish()`: من يكتب العنوان مباشرة يُعاد إلى `/wizard`.
+- `guard` يعيد `true` للمرور أو مسارًا للذهاب إليه (راجع الفصل الرابع).
+
+## 5) صفحة الإنجاز
+
+```html
+<!-- pages/wizard/Done.kreft -->
+use wizard
+
+action startOver() { wizard.$reset(); $router.go('/wizard') }
+
+<view>
+  <div k-animate="pop">
+    <h2>اكتمل الإعداد 🎉</h2>
+    <p>مرحبًا {wizard.data.name} — خطتك {wizard.data.plan}.</p>
+    <button @click="startOver">ابدأ من جديد</button>
+  </div>
+</view>
+```
+
+`wizard.$reset()` يعيد المخزن إلى قيمه الأولى (الخطوة 1 وبيانات فارغة)، فتُحذف كل الآثار المحفوظة.
+
+## 6) لمسة حركة: انتقال بين الخطوات
+
+`keep` يُبقي الخطوة ولا يزيلها، فلا تصلح له حركة الدخول/الخروج مباشرة. إن أردت انتقالًا متحركًا استبدل `keep` بـ `k-if` مع `k-animate.after` (ينتظر خروج القديم قبل دخول الجديد):
+
+```html
+<div k-if="wizard.step === 1" k-animate.after="slide"><step1></step1></div>
+<div k-if="wizard.step === 2" k-animate.after="slide"><step2></step2></div>
+<div k-if="wizard.step === 3" k-animate.after="slide"><step3></step3></div>
+```
+
+التضحية أنك تفقد `keep` (لا يُحفظ ما كتبته في الخطوة 1 حين تنتقل). اختر حسب حاجتك: **الاحتفاظ** (keep) أو **الحركة** (k-animate.after).
+
+## 7) جرّب الاستئناف بنفسك
+
+1. افتح `/wizard` واملأ الخطوة 1 وانتقل للثانية.
+2. حدّث الصفحة (F5) — ستجد نفسك في الخطوة 2 وبياناتك محفوظة (بفضل `saved`).
+3. اكتب `/wizard/done` مباشرة — يعيدك الحارس إلى `/wizard` لأنك لم تُنهِ بعد.
+4. أنهِ الخطوات ثم افتح `/wizard/done` — تمر هذه المرة.
+
+## تمارين
+
+1. أضف خطوة رابعة "صورة" ترفع ملفًا وتخزّن مساره في `wizard.data`.
+2. اجعل الحارس يمنع أيضًا العودة إلى خطوة سابقة بعد الإنهاء (أعد التوجيه إلى `/wizard/done`).
+3. استبدل `keep` بنسخة `k-animate.after` واحفظ البيانات المؤقتة في `saved` كي لا تضيع عند الانتقال.

package/book/ar/20-pipes-match-props.md

@@ -0,0 +1,75 @@
+# الفصل العشرون: الأنابيب و`k-match` وأنواع الخصائص
+
+ثلاث إضافات تجعل القوالب أقصر وأوضح. كلها تعمل مع `kreft dev` ومع `kreft build` ومع سياسة CSP الصارمة، والصيغة القديمة لا تتأثر.
+
+## 1) الأنابيب (Pipes)
+
+بدل استدعاء دوال مساعدة داخل القالب، مرّر القيمة عبر أنبوب بعلامة `|`:
+
+```html
+<p>{ price | currency:'EUR' }</p>
+<p>{ createdAt | ago }</p>
+<p>{ title | capitalize | truncate:30 }</p>
+<a title={name | upper}>{ tags | join:' · ' }</a>
+```
+
+- الوسائط بعد نقطتين: `truncate:30` و`currency:'EUR'`، أو بين قوسين: `number(2)`.
+- تُسلسل الأنابيب من اليسار إلى اليمين.
+- `||` و`|=` ليستا أنبوبًا، وكذلك `|` داخل نص أو تعبير نمطي أو قوسين.
+- الأرقام والتواريخ تتبع لغة التطبيق الحالية (`Kreftjs.locale`)، فيتغير شكل العملة والتاريخ مع اللغة.
+
+**الأنابيب الجاهزة:** `upper` و`lower` و`capitalize` و`trim` و`truncate:n` و`currency:'USD'` و`number:digits` و`percent:digits` و`date:'short'|'medium'|'long'` و`time` و`ago` و`bytes` و`json` و`fallback:'قيمة'` و`join:sep` و`first` و`last` و`slice:a:b` و`reverse` و`sortBy:'key':'desc'` و`count`.
+
+**أنبوبك الخاص:** أي دالة في المكوّن تصلح أنبوبًا، وتتقدّم على الجاهز عند تطابق الاسم:
+
+```js
+// في سكربت المكوّن
+state name = 'ali'
+const wrap = (v, left = '«', right = '»') => left + v + right
+```
+```html
+<p>{ name | wrap }</p>        <!-- «ali» -->
+<p>{ name | wrap:'[':']' }</p> <!-- [ali] -->
+```
+
+ولتعريف أنبوب لكل التطبيق: `Kreftjs.pipe('shout', (v) => String(v).toUpperCase() + '!')`.
+
+> **تنبيه:** `a | b` كانت تعني عملية OR على مستوى البتات. إن كنت تستخدمها في قالب فاكتبها `(a | b)` داخل دالة، فالقالب الآن يفسّرها أنبوبًا.
+
+## 2) `k-match` و`k-case` و`k-default`
+
+بدل سلسلة `k-if` و`k-elif`:
+
+```html
+<div k-match="status">
+  <b k-case="'ok'">تم</b>
+  <i k-case="'wait', 'queued'">بالانتظار</i>   <!-- أكثر من قيمة -->
+  <u k-default>غير معروف</u>
+</div>
+```
+
+- المقارنة صارمة (`===`).
+- تُعرض أول حالة مطابقة فقط، و`k-default` للحالة التي لا يطابقها شيء (يوضع آخرًا).
+- الأبناء المباشرون فقط هم الحالات، ويعملون كما يعمل `k-if`: مكوّنات و`<template>` و`k-animate`.
+
+## 3) خصائص بأنواع
+
+اكتب النوع بصيغة TypeScript، وتحصل على تحذير أثناء التطوير عند قيمة خاطئة أو خاصية مطلوبة غائبة:
+
+```html
+prop tone: 'info' | 'warn' = 'info'   // قيم محددة، والافتراضي info
+prop label: string                     // مطلوبة: غيابها يحذّر
+prop count?: number                    // اختيارية
+prop items: string[] = []
+prop onSave: (id: number) => void
+```
+
+يُتحقق من: `string` و`number` و`boolean` و`null` و`undefined` و`object` و`Date` و`T[]` والدوال والقيم الحرفية (`'sm'` و`3` و`true`) والاتحاد بينها. أما أسماء أنواعك (`User`) و`any` و`unknown` فلا تُفحص.
+
+الخصائص التي لها قيمة افتراضية أو `?` أو تقبل `null`/`undefined` ليست مطلوبة. والنوع `number` أو `boolean` أو `string` يحوّل أيضًا القيمة المكتوبة نصًا في الوسم (`count="5"` تصبح `5`).
+
+## تمارين
+
+1. اعرض سعرًا بالدينار الكويتي وتاريخ إنشاء بصيغة `ago` في صفحة طلبات.
+2. حوّل سلسلة `k-if` من أربع حالات لحالة الطلب إلى `k-match`.
+3. أضف إلى مكوّن `Badge` الخاصية `prop tone: 'info' | 'warn' | 'danger' = 'info'` وجرّب `tone="loud"` لترى التحذير.

package/book/ar/README.md

@@ -2,7 +2,7 @@
 
 كتاب عملي لتتعلم **Kreft (`kreftjs`)**، الإطار التفاعلي ذو لغة المكوّنات `.kreft` والواجهة الخلفية المتكاملة على Node.js، وبناء تطبيقات الويب وسطح المكتب به.
 
-> **ملاحظة عن الدقة:** الأمثلة المتقدمة (الفصول 11 إلى 14) **جُرِّبت فعلًا**: شُغّل خادم Kreft، وأُرسلت طلبات حقيقية، وفُتحت الصفحات في متصفح. وما لم نستطع التحقق منه ذكرناه صراحة في موضعه. الإطار ما زال تجريبيًا (`0.0.x-beta`)، فراجع `docs/README.md` (بالإنجليزية) عند أي اختلاف مع إصدارك.
+> **ملاحظة عن الدقة:** الأمثلة المتقدمة (الفصول 11 إلى 20) **جُرِّبت فعلًا**: شُغّل خادم Kreft، وأُرسلت طلبات حقيقية، وفُتحت الصفحات في متصفح. وما لم نستطع التحقق منه ذكرناه صراحة في موضعه. الإطار ما زال تجريبيًا (`0.0.x-beta`)، فراجع `docs/README.md` (بالإنجليزية) عند أي اختلاف مع إصدارك.
 
 ## الفهرس
 
@@ -33,12 +33,21 @@
 
 15. [مرجع سريع وأخطاء شائعة ومصطلحات](15-appendix.md).
 
+### الجزء الرابع: أمثلة الخبراء
+
+16. [قوائم ضخمة بلا تباطؤ](16-virtual-list.md): النافذة الافتراضية لعرض 100,000 صف فما فوق.
+17. [مكوّن مركّب: قائمة اختيار ذكية](17-combobox.md): Combobox ببحث ولوحة مفاتيح وبوابة و`k-model`.
+18. [مزامنة بين التبويبات ودون اتصال](18-tabs-offline.md): حضور حيّ وطابور أوامر يرسل عند عودة الاتصال.
+19. [معالج متعدد الخطوات مع استئناف](19-wizard.md): مخزن محفوظ وتحقق لكل خطوة وحراسة للمسارات.
+20. [الأنابيب و`k-match` وأنواع الخصائص](20-pipes-match-props.md): صيغة أقصر وأوضح للقوالب والمكوّنات.
+
 ## كيف تقرأ هذا الكتاب؟
 
 - **مبتدئ:** الفصول 1 إلى 5 بالترتيب، ونفّذ التمارين في نهاية كل فصل.
 - **تعرف JavaScript وتريد تطبيقًا كاملًا:** 4 ثم 6 ثم 7 ثم 11 و12.
 - **تريد النشر:** 9 (وانتبه إلى قسم `<base>`).
 - **تريد سطح المكتب:** 10.
+- **تريد مستوى الخبير في الواجهة:** 16 إلى 20 بعد أن تتقن الفصول 2 و3 و4.
 
 ## ما الذي سنبنيه؟
 
@@ -48,6 +57,8 @@
 - متجر بسلة ودفع آمن لا يكرر الطلبات ولا يبيع ما نفد.
 - مكتبة مكوّنات (نافذة وجدول وتوجيهات).
 - لوحة أرقام حيّة وتقرير يومي مجدول.
+- قائمة افتراضية تعرض 100,000 صف بلا تباطؤ.
+- قائمة اختيار ذكية، ومزامنة حيّة بين التبويبات، ومعالج إعداد يستأنف بعد التحديث.
 
 ## تشغيل أمثلة الكتاب