kreftjs 0.0.19-beta → 0.0.20-beta

package/book/ar/03-components-and-state.md

@@ -0,0 +1,258 @@
+# الفصل الثالث: المكوّنات ومشاركة الحالة
+
+## استخدام مكوّن
+
+سجّله مرة واحدة بمساره، أو استورده حيث تحتاجه:
+
+```js
+Kreftjs.app('App.kreft')
+  .component('UserCard', 'components/UserCard.kreft')
+  .mount('#app')
+```
+
+```html
+import UserCard from './UserCard.kreft'
+
+<view>
+  <user-card name="سارة أحمد" age={30}></user-card>
+</view>
+```
+
+في الصفحة (`view`) اكتب أسماء المكوّنات بنمط **kebab-case** (`<user-card>`).
+
+## Props: من الأب إلى الابن
+
+```html
+<!-- UserCard.kreft -->
+prop name
+prop age = 0
+prop admin = false
+
+<view>
+  <div class="card">{name} ({age}) <b k-if="admin">مدير</b></div>
+</view>
+```
+
+```html
+<user-card name="سارة أحمد" age={30} admin></user-card>
+```
+
+نوع القيمة الافتراضية يحدد كيف تُقرأ الخصائص النصية: `age="30"` تصير الرقم `30`، و`admin` بلا قيمة تصير `true`. الابن لا يستطيع تغيير prop؛ أرسل حدثًا بدلًا من ذلك.
+
+## الأحداث: من الابن إلى الأب
+
+```html
+<!-- TodoItem.kreft -->
+prop todo
+event remove
+
+<view>
+  <li>{todo.text} <button @click="send('remove', todo.id)">✕</button></li>
+</view>
+```
+
+```html
+<!-- الأب -->
+action removeTodo(id) { todos = todos.filter((t) => t.id !== id) }
+
+<view>
+  <todo-item k-each="t in todos" k-key="t.id" todo={t} @remove={removeTodo}></todo-item>
+</view>
+```
+
+## k-model على مكوّن
+
+```html
+<!-- Toggle.kreft -->
+prop modelValue = false
+event update:modelValue
+
+<view>
+  <button @click="send('update:modelValue', !modelValue)">{modelValue ? 'مفعّل' : 'معطّل'}</button>
+</view>
+```
+
+```html
+<toggle k-model="darkMode"></toggle>
+```
+
+النماذج المسمّاة: `k-model:title="pageTitle"` يستعمل `prop title` والحدث `update:title`.
+
+## الفتحات (Slots)
+
+```html
+<!-- Card.kreft -->
+prop items = []
+
+<view>
+  <div class="card">
+    <header><slot name="header">عنوان افتراضي</slot></header>
+    <slot></slot>
+    <li k-each="item in items"><slot name="item" item={item}>{item}</slot></li>
+  </div>
+</view>
+```
+
+```html
+<card items={users}>
+  <template k-slot:header>المستخدمون</template>
+  <p>محتوى الجسم</p>
+  <template k-slot:item="{ item }"><b>{item.name}</b></template>
+</card>
+```
+
+## الأنماط (Styles)
+
+- `<style>` يسري على الصفحة كلها.
+- `<style scoped>` يسري على هذا المكوّن فقط.
+- `.parent :deep(.child)` يصل إلى المكوّنات الأبناء من CSS محصور.
+- الخصائص مثل `class` التي تضعها على وسم المكوّن تنتقل إلى عنصره الجذر.
+
+## الاحتفاظ والانتظار (Keep و Wait)
+
+**Keep** يضع المكوّن جانبًا بدل أن يزيله. النص المكتوب وموضع التمرير والحالة كلها تبقى حين يعود:
+
+```html
+<kreft-component :is="tab" keep></kreft-component>
+<kreft-view keep></kreft-view>
+<kreft-view keep="5"></kreft-view>   <!-- احتفظ بخمسة على الأكثر؛ الأقدم استعمالًا يذهب -->
+```
+
+```html
+on show { timer.start() }   <!-- عاد (وكذلك أول مرة) -->
+on hide { timer.stop() }    <!-- وُضع جانبًا -->
+```
+
+**Wait** يعرض بديلًا إلى أن يجهز كل ما بداخله (المكوّنات الكسولة، وكل `load`، وكل `on start` ينتظر):
+
+```html
+<kreft-wait>
+  <user-profile id={5}></user-profile>
+  <p k-waiting>جارٍ التحميل…</p>
+  <p k-failed="error">تعذر التحميل: {error.message}</p>
+</kreft-wait>
+```
+
+## مشاركة الحالة
+
+| الحاجة | الأداة |
+|---|---|
+| من الأب إلى الابن | `prop` |
+| من الابن إلى الأب | `event` + `send()` أو `k-model` |
+| مكوّنات كثيرة في أي مكان | المخازن: `Kreftjs.store()` + `use` |
+| أب إلى كل ما بداخله | `share` / `receive` |
+| رسائل "حدث شيء ما" | `bus.send()` / `bus.on()` |
+
+### المخازن (Stores)
+
+أنشئ المخزن مرة واحدة:
+
+```js
+Kreftjs.store('cart', {
+  items: [],
+  get count() { return this.items.length },
+  get total() { return this.items.reduce((s, p) => s + p.price, 0) },
+  add(product) { this.items.push(product) },
+})
+```
+
+استعمله في أي ملف `.kreft`. كل المكوّنات ترى البيانات نفسها:
+
+```html
+use cart
+
+<view>
+  <span>السلة: {cart.count} · {cart.total}</span>
+  <button @click="cart.add(product)">أضف</button>
+</view>
+```
+
+لكل مخزن أيضًا `$patch` (يغيّر عدة قيم دفعة واحدة) و`$reset()` (يعود للبداية) و`$watch(fn)` (يعمل عند كل تغيير ويتوقف وحده حين يزول المكوّن).
+
+### المنطق المشترك
+
+المنطق الذي تحتاجه مكوّنات كثيرة يوضع في ملف `.js` كدالة. يمكنه استعمال `Kreftjs.state` و`Kreftjs.watch` و`Kreftjs.onDestroy` وغيرها:
+
+```js
+// logic/mouse.js
+export function trackMouse() {
+  const pos = Kreftjs.state({ x: 0, y: 0 })
+  const move = (e) => { pos.x = e.clientX; pos.y = e.clientY }
+  window.addEventListener('pointermove', move)
+  Kreftjs.onDestroy(() => window.removeEventListener('pointermove', move))
+  return pos
+}
+```
+
+```html
+import { trackMouse } from '../logic/mouse.js'
+use mouse = trackMouse()
+
+<view><p>{mouse.x}, {mouse.y}</p></view>
+```
+
+### share و receive
+
+```html
+<!-- Layout.kreft -->
+state settings = { theme: 'dark', lang: 'ar' }
+share settings = settings
+
+<!-- أي مكوّن بداخله مهما كان عمقه -->
+receive settings
+
+<view><p>السمة: {settings.theme}</p></view>
+```
+
+شارك كائن `state` فيتحدث كل المستقبِلين حين يتغير. و`Kreftjs.app(…).share('key', value)` يشارك مع التطبيق كله.
+
+### ناقل الأحداث (Event bus)
+
+```html
+<!-- الإرسال -->
+action save() { bus.send('toast', 'تم الحفظ!') }
+
+<!-- الاستماع -->
+state message = ''
+on ready { bus.on('toast', (text) => (message = text)) }
+```
+
+المستمعون المضافون في `on start` أو `on ready` يُزالون تلقائيًا حين يزول المكوّن. والآخرون يبقون حتى تستدعي `bus.off('toast', fn)`.
+
+## الحفظ في المتصفح: saved
+
+اكتب `saved` بدل `state` فتُحفظ القيمة في localStorage، وتنجو من إعادة التحميل وإغلاق المتصفح.
+
+```html
+saved todos = []
+saved theme = 'light'
+saved token = '' as 'auth.token'    <!-- اختر مفتاح التخزين بنفسك -->
+```
+
+- كل تغيير يُحفظ وحده، حتى العميق منه: `todos.push(…)` و`todo.done = true`.
+- المفتاح الافتراضي `<Component>.<name>`، مثل `Home.todos`. استعمل `as '…'` لتشارك قيمة واحدة بين مكوّنات.
+- تغيير في تبويب آخر من الموقع نفسه يظهر في هذا التبويب أيضًا.
+
+المخزن يحتفظ بقيمه البسيطة إذا أضفت `saved`:
+
+```js
+Kreftjs.store('cart', { items: [] }, { saved: true })            // أو { saved: ['items'] } لبعض الحقول
+```
+
+ومن JavaScript:
+
+```js
+const theme = Kreftjs.saved('theme', 'light')    // signal: theme.value = 'dark' تُحفظ
+Kreftjs.storage.set('user', { name: 'سارة' })
+Kreftjs.storage.get('user')
+Kreftjs.storage.remove('user')
+Kreftjs.storage.clear()                          // يزيل ما حفظه Kreft فقط
+```
+
+> **تحذير:** localStorage يخص متصفحًا واحدًا وموقعًا واحدًا، وسعته نحو 5 ميغابايت، ويقرؤه أي شخص يستعمل ذلك المتصفح وأي سكربت يعمل في صفحتك. لا تخزّن فيه كلمات مرور أو أسرارًا طويلة الأمد.
+
+## تمارين
+
+1. اصنع مكوّن `Rating` له `prop value` وحدث `update:value`، واستعمله بـ `k-model`.
+2. اصنع مخزن `toast` وعرض رسائل من أي مكوّن، بدل الـ bus.
+3. اصنع مكوّن `Modal` بفتحات `header` و`footer`، يظهر بـ `kreft-portal`.

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`.