kreftjs 0.0.20-beta → 0.0.22-beta

package/book/ar/16-virtual-list.md

@@ -0,0 +1,131 @@
+# الفصل السادس عشر (خبير): قوائم ضخمة بلا تباطؤ — النافذة الافتراضية
+
+عرض 1,000 صف سهل. عرض 100,000 صف في جدول واحد يغرق المتصفح: بناء عشرات آلاف العقد في الـ DOM يكلف وقتًا وذاكرة. الحل الذي تستعمله كل الجداول الاحترافية هو **النافذة الافتراضية (Virtualization)**: نرسم الصفوف المرئية فقط، وعند التمرير نستبدل الصفوف التي خرجت من الشاشة.
+
+سنبني هنا مكوّن `VirtualList` عامًا يتحمل أي عدد من العناصر ويبقى التمرير سلسًا. **كل الشيفرة جرِّبت في متصفح** مع 100,000 عنصر.
+
+## 1) الفكرة
+
+بدل أن نرسم القائمة كلها:
+
+1. نعرف ارتفاع الصف الواحد `itemHeight` (يجب أن يكون ثابتًا).
+2. من موضع التمرير `scrollTop` وارتفاع الحاوية نعرف **أي نطاق من العناصر ظاهر**.
+3. نرسم ذلك النطاق فقط، فوق نطاق صغير إضافي (`overscan`) كي لا يظهر فراغ عند التمرير السريع.
+4. نضبط ارتفاع "العمود الفارغ" على `items.length * itemHeight` ليبقى شريط التمرير صادقًا، ونزيح النافذة المرئية بـ `translateY`.
+
+## 2) المكوّن
+
+```html
+<!-- components/VirtualList.kreft -->
+prop items = []            // كل العناصر (قد تكون ملايين)
+prop itemHeight = 48       // ارتفاع الصف الواحد بالبكسل
+prop overscan = 6          // صفوف إضافية فوق وتحت النافذة المرئية
+
+state viewport = null      // يملؤه k-ref
+state scrollTop = 0
+state viewH = 0
+
+// ارتفاع العمود الكامل (شريط التمرير يعتمد عليه)
+derive total = items.length * itemHeight
+
+// النطاق المرئي + هامش الأمان
+derive start = Math.max(0, Math.floor(scrollTop / itemHeight) - overscan)
+derive end = Math.min(items.length, Math.ceil((scrollTop + viewH) / itemHeight) + overscan)
+derive visible = items.slice(start, end)
+derive offset = start * itemHeight
+
+action onScroll() {
+  scrollTop = viewport.scrollTop
+  viewH = viewport.clientHeight
+}
+
+// نراقب حجم الحاوية (نافذة صغرت أو كبرت) وننظف حين يزول المكوّن
+let ro
+on ready {
+  viewH = viewport.clientHeight
+  ro = new ResizeObserver(() => { viewH = viewport.clientHeight })
+  ro.observe(viewport)
+}
+on destroy { ro && ro.disconnect() }
+
+<view>
+  <div class="vlist" k-ref="viewport" @scroll="onScroll">
+    <div class="vlist__sizer" style="height: {total}px">
+      <div class="vlist__window" style="transform: translateY({offset}px)">
+        {for (item, i) in visible key item.id}
+          <div class="vlist__row" style="height: {itemHeight}px">
+            <slot item={item} index={start + i}>{item}</slot>
+          </div>
+        {/for}
+      </div>
+    </div>
+  </div>
+</view>
+
+<style scoped>
+.vlist { overflow-y: auto; height: 400px; border: 1px solid var(--border, #ddd); }
+.vlist__sizer { position: relative; }
+.vlist__window { position: absolute; inset-block-start: 0; inset-inline: 0; }
+.vlist__row { box-sizing: border-box; }
+</style>
+```
+
+لماذا يعمل هذا؟
+
+- **`derive visible`** يُعاد حسابه وحده كلما تغيّر `scrollTop` أو `viewH` أو `items`، فيرسم Kreft الصفوف الجديدة ويزيل الخارجة (وهو يعرف كيف يطابقها بمفتاح `key item.id`).
+- **`translateY`** على نافذة الصفوف أرخص من `padding-top` كبير: لا نعيد حساب التخطيط.
+- **`k-ref`** يضع عنصر التمرير في `state viewport`، فنقرؤه في `onScroll` بلا بحث في الـ DOM كل مرة.
+- **`ResizeObserver`** يلتقط تغيّر حجم الحاوية، و`on destroy` يقطع المراقبة.
+
+## 3) الاستعمال: 100,000 صف
+
+```html
+<!-- pages/BigTable.kreft -->
+import VirtualList from '../components/VirtualList.kreft'
+
+state rows = Array.from({ length: 100000 }, (_, i) => ({
+  id: i + 1,
+  name: 'الاسم ' + (i + 1),
+  price: (i % 100) + 1,
+}))
+
+<view>
+  <h1>100,000 صف، ورسم فوري</h1>
+  <virtual-list items={rows} itemHeight={44}>
+    <template k-slot="{ item, index }">
+      <div style="display:flex; gap:12px; align-items:center; height:100%; padding-inline:12px">
+        <b>{index + 1}</b>
+        <span>{item.name}</span>
+        <span style="margin-inline-start:auto">{item.price} $</span>
+      </div>
+    </template>
+  </virtual-list>
+</view>
+```
+
+- الفتحة الافتراضية هنا **بمعاملات**: `k-slot="{ item, index }"` يفكّك ما مرّره `<slot item={item} index={start + i}>`.
+- `index` هو الرقم الحقيقي في القائمة (لأننا أضفنا `start`) لا رقم الصف المرسوم.
+
+## 4) لمسات أداء تكميلية
+
+النافذة الافتراضية وحدها تكفي غالبًا. هذه أدوات إضافية للصفوف الثقيلة:
+
+| الأداة | متى تستعملها | مثال |
+|---|---|---|
+| `k-once` | صف/خلية لا تتغير أبدًا بعد أول رسم | `<td k-once>{row.id}</td>` |
+| `k-memo` | خلية تعتمد على قيمتين فقط | `<tr k-memo="[row.id === selected]">` |
+| `key item.id` | دائمًا مع الحلقات | `{for item in visible key item.id}` |
+| `derive` للقيم الغالية | احسب مرة لا في كل خلية | `derive priceLabel = (p) => p.toFixed(2) + ' $'` |
+| سكربت عادي لما لا تحتاجه الصفحة | ثوابت ودوال مساعدة | `const clamp = (n, a, b) => …` |
+
+تذكّر فخ الفصل الثالث عشر: ما تكتبه بـ `const`/`let` لا تراه الصفحة. كل ما يظهر في `view` يجب أن يكون `state` أو `derive` أو `action` أو `prop`.
+
+## 5) القياس
+
+جرّب الفرق بنفسك: اعرض 100,000 عنصر بدون النافذة الافتراضية (حلقة عادية) ثم معها، وراقب زمن أول رسم وذاكرة التبويب في أدوات المطوّر. في تجربتنا كانت الحلقة العادية تُرسم في مئات المللي ثانية وتشبع الذاكرة، بينما النافذة الافتراضية تُبقي في الـ DOM نحو 30 صفًا فقط مهما كان حجم القائمة.
+
+## تمارين
+
+1. أضف `prop itemKey` ليستعمل المفتاح `item[itemKey]` بدل `item.id` دائمًا.
+2. اجعل `itemHeight` متغيّرًا: صفوف بارتفاعات مختلفة تُجمَع في "أقسام" (Variable size virtualization).
+3. أضف تمريرًا إلى عنصر معيّن: دالة `scrollToIndex(i)` تضبط `viewport.scrollTop = i * itemHeight`.

package/book/ar/17-combobox.md

@@ -0,0 +1,169 @@
+# الفصل السابع عشر (خبير): مكوّن مركّب — قائمة اختيار ذكية (Combobox)
+
+المكوّنات البسيطة تأخذ `props` وتعرض HTML. المكوّنات **المركّبة** تحزم عدة قطع تتعاون معًا: زناد وفتحة منبثقة وحقل بحث وقائمة خيارات ولوحة مفاتيح. هنا نبني `Combobox` كاملًا قابلًا لإعادة الاستخدام: يختار من قائمة، يبحث، يتنقّل بالأسهم، يغلق بـ Esc أو بالنقر خارجه، ويعمل بـ `k-model`.
+
+**جرِّب هذه الشيفرة في المتصفح** كما هي.
+
+## 1) المكوّن
+
+```html
+<!-- components/Combobox.kreft -->
+prop modelValue = null        // القيمة المختارة (id)
+prop options = []             // [{ id, label }, …]
+prop placeholder = 'اختر…'
+prop searchable = false
+event update:modelValue
+
+state open = false
+state query = ''
+state active = 0              // فهرس الخيار المظلَّل
+state trigger = null          // يملؤه k-ref
+state rect = { top: 0, left: 0, width: 0 }
+
+derive selected = options.find((o) => o.id === modelValue) || null
+derive filtered = !searchable || !query ? options : options.filter((o) => o.label.includes(query))
+derive shown = filtered.slice(0, 50)      // لا نرسم أكثر من 50
+
+action toggle() {
+  if (!open && trigger) {
+    const r = trigger.getBoundingClientRect()
+    rect = { top: r.bottom, left: r.left, width: r.width }
+  }
+  open = !open
+  active = 0
+}
+
+action pick(o) {
+  send('update:modelValue', o.id)
+  open = false
+  query = ''
+}
+
+action onKey(e) {
+  if (e.key === 'Escape') { open = false; return }
+  if (!open && (e.key === 'ArrowDown' || e.key === 'Enter')) { toggle(); return }
+  if (!open) return
+  if (e.key === 'ArrowDown') active = Math.min(active + 1, shown.length - 1)
+  else if (e.key === 'ArrowUp') active = Math.max(active - 1, 0)
+  else if (e.key === 'Enter') { if (shown[active]) pick(shown[active]) }
+}
+
+<view>
+  <div class="combobox" tabindex="0" @keydown="onKey($event)" k-click-outside={() => open = false}>
+    <button type="button" class="combobox__trigger" k-ref="trigger" @click="toggle" aria-haspopup="listbox">
+      <span>{selected ? selected.label : placeholder}</span> <span>▾</span>
+    </button>
+
+    <kreft-portal to="body">
+      <div k-if="open" class="combobox__menu" role="listbox" k-animate="scale"
+           style="position:fixed; top:{rect.top}px; left:{rect.left}px; width:{rect.width}px">
+        <input k-if="searchable" class="combobox__search" k-model="query" placeholder="ابحث…">
+        <ul>
+          {for (o, i) in shown key o.id}
+            <li role="option" class={i === active ? 'active' : ''}
+                @mouseenter="active = i" @click="pick(o)">
+              <slot name="option" option={o}>{o.label}</slot>
+            </li>
+          {empty}
+            <li class="combobox__empty">لا نتائج</li>
+          {/for}
+        </ul>
+      </div>
+    </kreft-portal>
+  </div>
+</view>
+
+<style scoped>
+.combobox { position: relative; }
+.combobox__trigger { width: 100%; display: flex; justify-content: space-between; gap: 8px; }
+.combobox__menu { background: var(--background, #fff); color: var(--foreground, #111);
+  border: 1px solid var(--border, #ddd); max-height: 240px; overflow-y: auto; z-index: 200; }
+.combobox__search { width: 100%; border: 0; border-block-end: 1px solid var(--border, #ddd); padding: 8px; }
+.combobox__menu ul { list-style: none; margin: 0; padding: 4px; }
+.combobox__menu li { padding: 6px 8px; cursor: pointer; border-radius: 4px; }
+.combobox__menu li.active { background: var(--accent, #8883); }
+.combobox__empty { padding: 8px; opacity: .6; }
+</style>
+```
+
+النقاط المهمة:
+
+- **`k-model` على مكوّن** (كما في الفصل الثالث): المكوّن يملك `prop modelValue` ويرسل `update:modelValue`، فيكتب الأب `<combobox k-model="city">`.
+- **`k-click-outside`** توجيه مخصص من الفصل الثالث عشر يغلق القائمة عند النقر خارجها.
+- **`kreft-portal`** يرسم القائمة في `<body>` فلا يقتطعها `overflow` لآب؛ ولذلك نحسب موضعها يدويًا من `trigger.getBoundingClientRect()`.
+- **فتحة `option` بمعاملات**: من يستعمل المكوّن يقرر شكل كل خيار.
+- **`shown = filtered.slice(0, 50)`**: حد أقصى للرسم مهما كثرت النتائج (تكمّله البحث).
+- **`k-animate="scale"`** لحركة دخول وخروج خفيفة.
+
+## 2) الاستعمال
+
+```html
+<!-- pages/City.kreft -->
+import Combobox from '../components/Combobox.kreft'
+
+state cities = [
+  { id: 'mo', label: 'مقديشو' },
+  { id: 'hr', label: 'هرجيسا' },
+  { id: 'bos', label: 'بوصاصو' },
+  { id: 'ki', label: 'كيسمايو' },
+]
+
+state city = null
+
+<view>
+  <p>المدينة المختارة: {cities.find((c) => c.id === city)?.label || '—'}</p>
+  <combobox k-model="city" options={cities} searchable placeholder="اختر مدينة">
+    <template k-slot:option="{ option }">
+      <b>{option.label}</b> <small style="opacity:.6">{option.id.toUpperCase()}</small>
+    </template>
+  </combobox>
+</view>
+```
+
+## 3) خيارات تُحمَّل من الخادم (غير متزامن)
+
+لن تفيدك القائمة الثابتة في تطبيق حقيقي. حوّل البحث إلى طلب خادم بتأخير بسيط، كما فعلنا في بحث المدونة:
+
+```html
+<!-- components/AsyncCombobox.kreft -->
+prop modelValue = null
+event update:modelValue
+
+state open = false
+state text = ''
+state query = ''          // ما نبحث به فعلًا (بعد التأخير)
+
+let timer
+watch text {
+  clearTimeout(timer)
+  timer = setTimeout(() => { query = value }, 300)
+}
+on destroy { clearTimeout(timer) }
+
+// يعيد الجلب وحده كلما تغيّر query
+load results = api.get('/api/cities', { query: { q: query || undefined } })
+
+action pick(c) { send('update:modelValue', c.id); open = false; text = c.label }
+
+<view>
+  <input k-model="text" @focus="open = true" placeholder="ابحث عن مدينة…"
+         k-click-outside={() => open = false}>
+  <div k-if="open" class="menu">
+    <p k-if="results.loading">جارٍ البحث…</p>
+    {for c in results.data || [] key c.id}
+      <button @click="pick(c)">{c.label}</button>
+    {empty}
+      <p>لا نتائج لـ "{query}".</p>
+    {/for}
+  </div>
+</view>
+```
+
+- **`text` و`query`**: نفصل ما يكتبه المستخدم عمّا نطلبه، فيتجمع الإدخال السريع في طلب واحد.
+- **`load results`** يقرأ `query` فيجلب من جديد عند تغيّرها، ويعطيك `loading` و`error` و`reload()`.
+
+## تمارين
+
+1. أضف إلى `Combobox` خاصية `prop clearable` مع زر ✕ يفرغ الاختيار.
+2. اجعل القائمة تفتح للأعلى إذا لم يتسع أسفلها (قارن `rect.top` بارتفاع النافذة).
+3. حوّل `AsyncCombobox` ليدعم اختيارًا متعددًا: `modelValue` مصفوفة و`pick` يبدّل العنصر بدل اختياره وحيدًا.

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` كي لا تضيع عند الانتقال.