kreftjs 0.0.19-beta → 0.0.20-beta

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,258 @@
1
+ # الفصل العاشر: تطبيقات سطح المكتب مع Electron
2
+
3
+ يمكن لـ Kreft أن يحزم تطبيقك كبرنامج سطح مكتب لـ Windows وmacOS وLinux. الصفحات هي ملفات `.kreft` نفسها؛ وElectron يقدّم النافذة فقط.
4
+
5
+ ## البداية السريعة
6
+
7
+ ```bash
8
+ kreft new my-app --electron # تطبيق جديد بدعم سطح المكتب
9
+ # أو في تطبيق موجود:
10
+ kreft electron:init # اسم بديل: kreft make:electron
11
+ npm install # يثبّت electron و electron-builder
12
+ kreft electron # يفتح التطبيق في نافذته: بلا متصفح وبلا عنوان
13
+ kreft electron:build # مثبّت في dist-electron/
14
+ ```
15
+
16
+ للمساعدة في الطرفية في أي وقت:
17
+
18
+ ```bash
19
+ kreft electron:help
20
+ ```
21
+
22
+ ## الأوامر
23
+
24
+ | الأمر | ماذا يفعل |
25
+ |---|---|
26
+ | `kreft electron:init` | يكتب `electron/main.js` و`electron/preload.js` وأيقونة التطبيق `build/icon.png`، ويضيف السكربتات واعتماديات `electron` و`electron-builder` وكتلة `build` إلى `package.json`. الملفات الموجودة لا تُستبدل أبدًا. ويزيل أيضًا روابط Google Fonts من `index.html` ليبدأ التطبيق بلا شبكة. |
27
+ | `kreft electron` | يفتح التطبيق في نافذة سطح مكتب فقط: لا متصفح ولا عنوان يُطبع. خادم التطوير يعمل مخفيًا على منفذ خاص بحاسوبك لا تستعمله إلا النافذة (إعادة التحميل الفورية تعمل). إغلاق النافذة يوقف الخادم. |
28
+ | `kreft electron:build` | يشغّل `kreft build --base ./` ثم `electron-builder`. |
29
+ | `npm run electron:build:mac` | `.dmg` و`.zip`. |
30
+ | `npm run electron:build:win` | مثبّت NSIS و`.exe` محمول. |
31
+ | `npm run electron:build:linux` | AppImage و`.deb` و`.rpm`. |
32
+ | `npm run electron:build:all` | الثلاثة. |
33
+ | `kreft electron:help` | دليل مختصر في الطرفية. |
34
+
35
+ ## مرجع سريع
36
+
37
+ | أريد أن… | افعل هذا |
38
+ |---|---|
39
+ | أضيف دعم سطح المكتب | `kreft new my-app --electron`، أو `kreft electron:init` ثم `npm install` |
40
+ | أفتح التطبيق في نافذته | `kreft electron` |
41
+ | أفتح DevTools | `kreft electron --devtools=bottom` أو `ELECTRON_DEVTOOLS=right` أو F12 |
42
+ | أظهر القائمة أو أخفيها | `ELECTRON_MENU=show` أو `auto` أو `hide`؛ و`kreftDesktop.setMenu('hide')` |
43
+ | أغيّر الأيقونة | استبدل `build/icon.png` (PNG مربعة 512×512 أو أكبر) |
44
+ | أغيّر اسم التطبيق | `build.productName` و`build.appId` في `package.json` |
45
+ | أصنع مثبّتًا | `npm run electron:build:mac` أو `:win` أو `:linux` أو `:all` |
46
+
47
+ ## بنية المشروع
48
+
49
+ ```text
50
+ my-app/
51
+ ├── electron/
52
+ │ ├── main.js النافذة والقائمة وجسر النظام
53
+ │ └── preload.js ما تراه صفحاتك من النظام (window.kreftDesktop)
54
+ ├── build/icon.png أيقونة التطبيق
55
+ ├── dist/ البناء الثابت (kreft build --base ./)
56
+ ├── dist-electron/ المثبّتات التي يكتبها electron-builder
57
+ └── package.json "main": "electron/main.js" وكتلة "build"
58
+ ```
59
+
60
+ ## كيف يعمل
61
+
62
+ - أثناء التطوير: خادم Kreft المخفي يخدّم الصفحات، والنافذة تفتحه. لا متصفح يُفتح ولا عنوان يُطبع.
63
+ - في التطبيق المحزوم: النافذة تحمّل `dist/index.html` مباشرة من الملفات، بلا خادم.
64
+
65
+ ## اكتشاف تطبيق سطح المكتب
66
+
67
+ ```js
68
+ if (Kreftjs.isElectron) {
69
+ const info = await kreftDesktop.getInfo() // { name, version, platform, arch, isPackaged }
70
+ }
71
+ ```
72
+
73
+ ```html
74
+ <!-- components/Titlebar.kreft -->
75
+ state info = null
76
+ on start { if (Kreftjs.isElectron) info = await kreftDesktop.getInfo() }
77
+
78
+ <view>
79
+ <footer k-if="info">{info.name} v{info.version} · {info.platform}</footer>
80
+ </view>
81
+ ```
82
+
83
+ ## جسر سطح المكتب
84
+
85
+ `window.kreftDesktop` (وكذلك `Kreftjs.desktop`) هو الطريقة الوحيدة التي تصل بها صفحاتك إلى النظام. لا شيء آخر من Node.js أو Electron مكشوف.
86
+
87
+ | الدالة | ماذا تفعل |
88
+ |---|---|
89
+ | `getInfo()` | اسم التطبيق والإصدار والنظام. |
90
+ | `minimize()` و`maximize()` و`close()` | التحكم بالنافذة. |
91
+ | `getMenu()` و`setMenu('show' \| 'auto' \| 'hide')` | قائمة النافذة. |
92
+ | `openDevTools(mode)` و`closeDevTools()` و`toggleDevTools()` | أدوات المطوّر. |
93
+ | `showMessageBox(options)` | مربع رسالة أصلي. |
94
+ | `showOpenDialog(options)` و`showSaveDialog(options)` | نوافذ اختيار الملفات. |
95
+
96
+ ```html
97
+ action confirmDelete() {
98
+ const r = await kreftDesktop.showMessageBox({
99
+ type: 'warning',
100
+ buttons: ['حذف', 'إلغاء'],
101
+ defaultId: 1,
102
+ cancelId: 1,
103
+ title: 'تأكيد',
104
+ message: 'هل تريد حذف هذا العنصر؟',
105
+ })
106
+ if (r.response === 0) await remove()
107
+ }
108
+ ```
109
+
110
+ ## إضافة دالة سطح مكتب خاصة بك
111
+
112
+ 1. في `electron/main.js` أضف معالجًا: `ipcMain.handle('app:ping', () => 'pong')`.
113
+ 2. في `electron/preload.js` أضفه إلى كائن `desktop`: `ping: () => ipcRenderer.invoke('app:ping')`.
114
+ 3. استعمله من الصفحة: `await kreftDesktop.ping()`.
115
+
116
+ > **تنبيه أمني:** مرّر الحد الأدنى من البيانات، وتحقق منها في `main.js`. هذا جسر بين صفحة (قد تُحقن فيها شيفرة) ونظام التشغيل.
117
+
118
+ ## أدوات المطوّر
119
+
120
+ ```bash
121
+ kreft electron --devtools # على اليمين
122
+ kreft electron --devtools=bottom # أسفل أو left أو detach
123
+ kreft electron --no-devtools
124
+ ELECTRON_DEVTOOLS=bottom kreft electron
125
+ ```
126
+
127
+ والمفتاح F12 (أو Ctrl+Shift+I) يبدّل اللوحة.
128
+
129
+ ## قائمة النافذة
130
+
131
+ اضبط شريط القائمة عند بدء التطبيق:
132
+
133
+ ```bash
134
+ ELECTRON_MENU=show kreft electron # الافتراضي: الشريط ظاهر
135
+ ELECTRON_MENU=auto kreft electron # مخفي، اضغط Alt لإظهاره (Windows وLinux)
136
+ ELECTRON_MENU=hide kreft electron # بلا قائمة
137
+ ```
138
+
139
+ أو غيّرها والتطبيق يعمل من صفحة:
140
+
141
+ ```js
142
+ window.kreftDesktop.setMenu('hide') // 'show' | 'auto' | 'hide'
143
+ window.kreftDesktop.getMenu() // الوضع الحالي
144
+ ```
145
+
146
+ على macOS تعيش القائمة في الشريط العلوي للشاشة، فـ `show` و`auto` متشابهان، و`hide` يُبقي قائمة اسم التطبيق (فيها Quit) لأن macOS يحتاج واحدة. ولقائمتك الخاصة (File, Edit…) استعمل `Menu.buildFromTemplate([...])` و`Menu.setApplicationMenu(...)` في `electron/main.js`.
147
+
148
+ > **للتطبيقات التي أُنشئت قبل 0.0.18:** ملف `electron/main.js` القديم بلا هذه الميزة. انسخ تعديلاتك احتياطيًا، واحذف الملف، وشغّل `kreft electron:init`.
149
+
150
+ ## أيقونة التطبيق
151
+
152
+ يضع `kreft electron:init` شعار Kreft في `build/icon.png`. استبدله بأيقونتك: PNG مربعة 512×512 أو أكبر. تستعملها النافذة، ويصنع electron-builder منها `.icns` (macOS) و`.ico` (Windows). واسم التطبيق في `build.productName` و`build.appId` داخل `package.json`.
153
+
154
+ يحتاج electron-builder أيضًا إلى `description` و`homepage` و`author` (مع بريد) و`build.linux.maintainer` (لـ `.deb` و`.rpm`). الأمران `kreft electron:init` و`kreft electron:build` يملآن الناقص منها من اسمك وبريدك في git؛ راجعها قبل الإصدار.
155
+
156
+ ## المثبّتات
157
+
158
+ ```bash
159
+ npm run electron:build:mac # .dmg و .zip
160
+ npm run electron:build:win # مثبّت NSIS و .exe محمول
161
+ npm run electron:build:linux # AppImage و .deb و .rpm
162
+ npm run electron:build:all # الثلاثة
163
+ ```
164
+
165
+ تُكتب في `dist-electron/`. والوسائط تذهب إلى electron-builder، مثل `kreft electron:build --mac --arm64`. الإعدادات الافتراضية في كتلة `build` من `package.json`:
166
+
167
+ | النظام | الأهداف |
168
+ |---|---|
169
+ | Windows | مثبّت `nsis` (تختار المجلد) و`portable` |
170
+ | macOS | `dmg` و`zip` |
171
+ | Linux | `AppImage` و`deb` و`rpm` |
172
+
173
+ - ابنِ كل نظام على نظامه. على Mac تُبنى AppImage ومثبّتات Windows، لكن `.deb` و`.rpm` تفشل: ابنهما على Linux، أو احذفهما من `build.linux.target`.
174
+ - توقيع الشيفرة (code signing) يُضبط عبر electron-builder (electron.build/code-signing) ولازم قبل تسليم التطبيق للناس؛ تطبيقات macOS غير الموقّعة تعرض تحذير Gatekeeper.
175
+ - **التطبيق المحزوم لا يشغّل واجهة خلفية.** يحمّل `dist/index.html` فقط. تطبيق الواجهة وحدها يعمل كما هو؛ أما التطبيق المتكامل (تسجيل دخول وقاعدة بيانات) فلا يعمل بعد التثبيت ما لم تشغّل خادمًا في مكان ما وتوجّه `api.setup({ base })` إليه.
176
+
177
+ ## `npm run build` أم `electron:build`؟
178
+
179
+ إضافة Electron لا تغيّر `npm run build`. الأمران يصنعان شيئين مختلفين:
180
+
181
+ | الأمر | ماذا يصنع | استعمله لـ |
182
+ |---|---|---|
183
+ | `npm run build` | الموقع في `dist/`، بمسارات تبدأ بـ `/` (ومجلد `docs/` مضمَّن). | نشر التطبيق على خادم ويب. |
184
+ | `npm run electron:build` | الموقع نفسه مبنيًا بـ `--base ./` ليُفتح من ملف، ثم مثبّت في `dist-electron/`. | تسليم التطبيق كبرنامج سطح مكتب. |
185
+
186
+ `dist/` الناتج عن `npm run build` يعرض نافذة بيضاء إن فتحته في Electron لأن مساراته تبدأ بـ `/`. شغّل `electron:build` (أو `kreft build --base ./`) أولًا. ولا مانع من الاثنين: `electron:build` يعيد كتابة `dist/`، فشغّل `npm run build` من جديد قبل نشر الموقع.
187
+
188
+ ## الأمان
189
+
190
+ النافذة تتبع إرشادات Electron الأمنية:
191
+
192
+ - `contextIsolation: true` و`nodeIntegration: false` و`sandbox: true`: صفحتك لا ترى Node.js.
193
+ - الروابط الخارجية تُفتح في المتصفح الافتراضي للنظام، لا داخل النافذة.
194
+ - التنقل بعيدًا عن أصل التطبيق ممنوع.
195
+ - الجسر يمرر حقولًا مسموحة فقط إلى نوافذ الحوار.
196
+
197
+ ## استكشاف الأخطاء
198
+
199
+ | الرسالة أو العَرَض | الحل |
200
+ |---|---|
201
+ | `Electron is not installed locally` | `kreft add -D electron` |
202
+ | `electron-builder is not installed` | `kreft add -D electron-builder` |
203
+ | نافذة بيضاء في التطبيق المحزوم | أعد تشغيل `electron:build` (يلزمه `--base ./`) وتأكد من وجود `dist/index.html` |
204
+ | `.deb` أو `.rpm` تفشل على Mac | ابنهما على Linux أو احذفهما من `build.linux.target` |
205
+ | خطأ author/maintainer/homepage عند بناء Linux | أضف `author` ببريد و`homepage` و`build.linux.maintainer` في `package.json` |
206
+ | لا أستطيع إخفاء القائمة | استعمل `ELECTRON_MENU=hide`؛ وللتطبيقات القديمة أعد توليد `electron/main.js` |
207
+
208
+ ## مثال: تطبيق ملاحظات لسطح المكتب (واجهة فقط)
209
+
210
+ تطبيق لا يحتاج خادمًا: الملاحظات تُحفظ بـ `saved` في الجهاز، وأوامر النظام عبر الجسر.
211
+
212
+ ```html
213
+ <!-- pages/Notes.kreft -->
214
+ saved notes = [] // تبقى بعد إغلاق التطبيق
215
+ state text = ''
216
+ state info = null
217
+
218
+ on start { if (Kreftjs.isElectron) info = await kreftDesktop.getInfo() }
219
+
220
+ action add() {
221
+ if (!text.trim()) return
222
+ notes.unshift({ id: Date.now(), text: text.trim() })
223
+ text = ''
224
+ }
225
+
226
+ action removeNote(n) {
227
+ if (Kreftjs.isElectron) {
228
+ const r = await kreftDesktop.showMessageBox({
229
+ type: 'question', buttons: ['حذف', 'إلغاء'], defaultId: 1, cancelId: 1,
230
+ message: 'حذف هذه الملاحظة؟',
231
+ })
232
+ if (r.response !== 0) return
233
+ }
234
+ notes = notes.filter((x) => x.id !== n.id)
235
+ }
236
+
237
+ action hideMenu() { kreftDesktop.setMenu('hide') }
238
+
239
+ <view>
240
+ <h1>ملاحظاتي</h1>
241
+ <form novalidate @submit.prevent={add}>
242
+ <input k-model="text" placeholder="اكتب ملاحظة…">
243
+ </form>
244
+
245
+ <ul>
246
+ <li k-each="n in notes" k-key="n.id">{n.text} <button @click="removeNote(n)">✕</button></li>
247
+ </ul>
248
+
249
+ <p k-if="info">{info.name} {info.version} · {info.platform}</p>
250
+ <button k-if="Kreftjs.isElectron" @click="hideMenu">أخفِ القائمة</button>
251
+ </view>
252
+ ```
253
+
254
+ ## تمارين
255
+
256
+ 1. أنشئ تطبيق سطح مكتب بـ `kreft new notes --electron`، وغيّر الأيقونة، وابنِ `.dmg` أو `.exe`.
257
+ 2. أضف دالة `ping` خاصة بك عبر `ipcMain` و`preload.js`.
258
+ 3. ابنِ للنظامين وقارن حجم المثبّتين.
@@ -0,0 +1,370 @@
1
+ # الفصل الحادي عشر (متقدم): مدونة كاملة
2
+
3
+ نبني مدونة بمقالات وتعليقات ووسوم، بحث وترقيم صفحات، تحقق متقدم، ووصلات عربية، وSEO للزواحف. **كل شيفرة هنا جُرِّبت فعلًا**: شُغّل الخادم وأُرسلت طلبات حقيقية، وفُتحت الصفحات في المتصفح.
4
+
5
+ ما ستتعلمه: علاقات متعددة لمتعدد (many-to-many)، وscopes، وخطّافات النماذج، وFormRequest، وResource، وقواعد تحقق خاصة، وبحث بتأخير (debounce)، وSEO من قاعدة البيانات.
6
+
7
+ ## الخطوة 1: الجداول
8
+
9
+ أربعة جداول: المقالات والتعليقات والوسوم وجدول الربط `post_tag`.
10
+
11
+ ```js
12
+ module.exports = {
13
+ up(schema) {
14
+ schema.create('posts', (table) => {
15
+ table.id()
16
+ table.string('title', 200).unique()
17
+ table.string('slug', 220).unique()
18
+ table.text('body').nullable()
19
+ table.boolean('published').default(false)
20
+ table.integer('views').default(0)
21
+ table.json('meta').nullable()
22
+ table.timestamps()
23
+ })
24
+
25
+ schema.create('comments', (table) => {
26
+ table.id()
27
+ table.foreignId('post_id').constrained().cascadeOnDelete()
28
+ table.string('author', 80)
29
+ table.text('body')
30
+ table.boolean('approved').default(false)
31
+ table.timestamps()
32
+ })
33
+
34
+ schema.create('tags', (table) => {
35
+ table.id()
36
+ table.string('name', 60).unique()
37
+ table.timestamps()
38
+ })
39
+
40
+ schema.create('post_tag', (table) => {
41
+ table.id()
42
+ table.foreignId('post_id').constrained().cascadeOnDelete()
43
+ table.foreignId('tag_id').constrained().cascadeOnDelete()
44
+ })
45
+ },
46
+
47
+ down(schema) {
48
+ schema.dropIfExists('post_tag')
49
+ schema.dropIfExists('tags')
50
+ schema.dropIfExists('comments')
51
+ schema.dropIfExists('posts')
52
+ },
53
+ }
54
+ ```
55
+
56
+ بعد إضافة ترحيل جديد شغّل `kreft migrate` (خادم التطوير يرحّل عند بدئه فقط). وإن نسيت ستجد الخطأ المفيد: `no such table: posts. Hint: Run kreft migrate`.
57
+
58
+ ## الخطوة 2: النماذج
59
+
60
+ ```js
61
+ const { Model } = require('kreftjs/server')
62
+
63
+ // Str.slug مناسب للاتينية. للعربية نبني الوصلة بأنفسنا ونُبقي الحروف العربية
64
+ const slugify = (text) => String(text).trim().toLowerCase()
65
+ .replace(/[\u064B-\u065F\u0670\u0640]/g, '') // التشكيل والتطويل
66
+ .replace(/\s+/g, '-')
67
+ .replace(/[^\p{L}\p{N}-]+/gu, '')
68
+ .replace(/-+/g, '-')
69
+
70
+ class Post extends Model {
71
+ static fillable = ['title', 'slug', 'body', 'published', 'meta']
72
+ static casts = { published: 'boolean', meta: 'json' }
73
+
74
+ comments() { return this.hasMany(require('./Comment')) }
75
+ tags() { return this.belongsToMany(require('./Tag'), 'post_tag') }
76
+
77
+ // scopes: تُسلسل كأنها دوال: Post.query().published().search('kreft')
78
+ static scopePublished(q) { q.where('published', true) }
79
+ static scopeSearch(q, text) {
80
+ if (text) q.where((w) => w.where('title', 'like', `%${text}%`).orWhere('body', 'like', `%${text}%`))
81
+ }
82
+
83
+ // خطّاف: يعمل قبل الإنشاء
84
+ static async creating(post) { post.slug ??= slugify(post.title) }
85
+ }
86
+
87
+ module.exports = Post
88
+ ```
89
+
90
+ نقاط مهمة:
91
+
92
+ - **`scopePublished` و`scopeSearch`**: دوال استعلام قابلة لإعادة الاستخدام: `Post.query().published().search('كلمة')`.
93
+ - **`creating`**: خطّاف يعمل قبل الإنشاء ويملأ `slug`.
94
+ - **وصلات عربية:** `Str.slug` مصمم للاتينية؛ جرّبته فحوّل "أول" إلى `ا-ول`. لذلك كتبنا `slugify` يُبقي الحروف العربية (`\p{L}`) ويحذف التشكيل. النتيجة: `أول-مقال-في-kreft`.
95
+ - **`casts`**: `published` منطقي و`meta` JSON.
96
+
97
+ ```js
98
+ const { Model } = require('kreftjs/server')
99
+
100
+ class Comment extends Model {
101
+ static fillable = ['post_id', 'author', 'body', 'approved']
102
+ static casts = { approved: 'boolean' }
103
+
104
+ post() { return this.belongsTo(require('./Post')) }
105
+ }
106
+
107
+ module.exports = Comment
108
+ ```
109
+
110
+ ```js
111
+ const { Model } = require('kreftjs/server')
112
+
113
+ class Tag extends Model {
114
+ static fillable = ['name']
115
+ posts() { return this.belongsToMany(require('./Post'), 'post_tag') }
116
+ }
117
+
118
+ module.exports = Tag
119
+ ```
120
+
121
+ ## الخطوة 3: التحقق والاستجابة
122
+
123
+ ```js
124
+ const { FormRequest } = require('kreftjs/server')
125
+
126
+ class StorePostRequest extends FormRequest {
127
+ authorize(req) { return true } // في مشروع بمصادقة: return req.user != null
128
+ rules() {
129
+ return {
130
+ title: 'required|min:3|max:200|unique:posts,title',
131
+ body: 'required',
132
+ published: 'boolean',
133
+ }
134
+ }
135
+ messages() {
136
+ return { 'title.required': 'أعطِ المقال عنوانًا.', 'title.unique': 'هذا العنوان مستعمل من قبل.' }
137
+ }
138
+ }
139
+
140
+ module.exports = StorePostRequest
141
+ ```
142
+
143
+ ```js
144
+ const { JsonResource } = require('kreftjs/server')
145
+
146
+ class PostResource extends JsonResource {
147
+ toArray(req) {
148
+ return {
149
+ id: this.id,
150
+ title: this.title,
151
+ slug: this.slug,
152
+ excerpt: String(this.body || '').slice(0, 140),
153
+ views: this.views,
154
+ published: this.published,
155
+ created_at: this.created_at,
156
+ }
157
+ }
158
+ }
159
+
160
+ module.exports = PostResource
161
+ ```
162
+
163
+ الـ Resource يتحكم بما يخرج من الـ API: هنا نخرج مقتطفًا من النص لا النص كله.
164
+
165
+ ### قاعدة تحقق خاصة بالعربية
166
+
167
+ ```bash
168
+ kreft make:rule ArabicName
169
+ ```
170
+
171
+ ```js
172
+ // قاعدة تحقق خاصة: اسم بالحروف العربية والمسافات فقط
173
+ class ArabicName {
174
+ passes(attribute, value, data) {
175
+ return /^[ء-يٱ-ۓ\s]{2,60}$/.test(String(value || '').trim())
176
+ }
177
+
178
+ message() {
179
+ return 'اكتب :attribute بالحروف العربية فقط.'
180
+ }
181
+ }
182
+
183
+ module.exports = ArabicName
184
+ ```
185
+
186
+ وتُستعمل في مصفوفة مع القواعد النصية: `author: ['required', new ArabicName()]` (انظر المتحكم أدناه).
187
+
188
+ ## الخطوة 4: المتحكم والمسارات
189
+
190
+ ```js
191
+ const { response } = require('kreftjs/server')
192
+ const Post = require('../../Models/Post')
193
+ const Tag = require('../../Models/Tag')
194
+ const PostResource = require('../Resources/PostResource')
195
+ const ArabicName = require('../../Rules/ArabicName')
196
+ const StorePostRequest = require('../Requests/StorePostRequest')
197
+
198
+ class PostController {
199
+ // GET /api/posts?q=كلمة&tag=kreft&page=2
200
+ async index(req) {
201
+ const query = Post.query().published().search(req.string('q')).latest('id')
202
+ if (req.filled('tag')) query.whereHas('tags', (q) => q.where('name', req.string('tag')))
203
+ return PostResource.collection(await query.paginate(5, req.integer('page', 1)))
204
+ }
205
+
206
+ // GET /api/posts/{slug}: يزيد المشاهدات ويحمّل العلاقات
207
+ async show(req, slug) {
208
+ const post = await Post.query().published().where('slug', slug).with('tags').firstOrFail()
209
+ await post.increment('views')
210
+ const comments = await post.comments().where('approved', true).get()
211
+ return { ...post.toJSON(), comments }
212
+ }
213
+
214
+ // POST /api/posts
215
+ async store(req) {
216
+ const data = await StorePostRequest.validate(req)
217
+ const post = await Post.create(data)
218
+ const names = req.input('tags', [])
219
+ const tags = []
220
+ for (const name of names) tags.push((await Tag.where('name', name).first()) || (await Tag.create({ name })))
221
+ await post.tags().sync(tags.map((t) => t.id))
222
+ return response(new PostResource(post), 201)
223
+ }
224
+
225
+ // POST /api/posts/{id}/comments: تنتظر الموافقة
226
+ async comment(req, id) {
227
+ const post = await Post.findOrFail(id)
228
+ const data = await req.validate({ author: ['required', new ArabicName()], body: 'required|min:2|max:1000' })
229
+ return response(await post.comments().create({ ...data, approved: false }), 201)
230
+ }
231
+ }
232
+
233
+ module.exports = PostController
234
+ ```
235
+
236
+ وفي `routes/api.js`:
237
+
238
+ ```js
239
+ const PostController = require('../app/Http/Controllers/PostController')
240
+ Route.get('/posts', [PostController, 'index'])
241
+ Route.post('/posts', [PostController, 'store'])
242
+ Route.get('/posts/{slug}', [PostController, 'show'])
243
+ Route.post('/posts/{id}/comments', [PostController, 'comment']).middleware('throttle:10,1')
244
+ ```
245
+
246
+ ملاحظات:
247
+
248
+ - `index` يبحث ويرشّح بالوسم ويرقّم: `paginate(5, page)` تعيد `{ data, meta }`.
249
+ - `show` يزيد المشاهدات بـ `increment` ويجلب الوسوم والتعليقات الموافَق عليها فقط.
250
+ - `store` ينشئ الوسوم الجديدة ويربطها بـ `sync([...ids])`.
251
+ - `comment` محدود بـ `throttle:10,1` (10 في الدقيقة) والتعليق ينتظر الموافقة (`approved: false`).
252
+
253
+ > **تنبيه الصلاحيات:** هذا المشروع التجريبي بلا تسجيل دخول، فمسار `POST /posts` مفتوح. في مشروع حقيقي ضعه تحت `Route.middleware('auth')` واجعل `authorize()` في `StorePostRequest` تُرجع `req.user != null`، وللتعديل والحذف استعمل سياسة (`req.authorize('update', post)`) كما في الفصل السابع.
254
+
255
+ ## جرّبه بنفسك
256
+
257
+ ```bash
258
+ curl -H 'Content-Type: application/json' -d '{"title":"أول مقال في Kreft","body":"هذا نص المقال الأول","published":true,"tags":["kreft","js"]}' localhost:8000/api/posts
259
+ curl -H 'Content-Type: application/json' -d '{"title":"أول مقال في Kreft","body":"x"}' localhost:8000/api/posts # 422: العنوان مستعمل
260
+ curl -G --data-urlencode 'q=مقال' localhost:8000/api/posts
261
+ curl 'localhost:8000/api/posts?tag=kreft'
262
+ ```
263
+
264
+ نتائج حقيقية من تجربتنا:
265
+
266
+ - إنشاء مقال: `201` وشكله `{"data":{"id":…,"slug":"أول-مقال-في-kreft",…}}`.
267
+ - تكرار العنوان: `422` مع `"The title has already been taken."`.
268
+ - البحث والتصفية بالوسم يعيدان المقالات المطابقة فقط مع `meta` (`total`, `per_page`, `current_page`, `last_page`).
269
+ - تعليق باسم لاتيني: `422`، وباسم عربي: `201`.
270
+
271
+ > **رسالة بالاسم الخام:** رسالة القاعدة الخاصة أظهرت "اكتب author…" لأن اسم الحقل لم يُترجم. أضف `"attributes": { "author": "الاسم" }` إلى `lang/ar/validation.json` فتظهر "اكتب الاسم بالحروف العربية فقط".
272
+
273
+ ## الخطوة 5: SEO من قاعدة البيانات
274
+
275
+ ```js
276
+ const Post = require('../app/Models/Post')
277
+
278
+ module.exports = {
279
+ '/': { title: 'مدونتي', description: 'مقالات عن البرمجة' },
280
+ '/blog/:slug': async ({ slug }) => {
281
+ const post = await Post.query().published().where('slug', slug).first()
282
+ if (!post) return null // 404 حقيقي مع noindex
283
+ return {
284
+ title: post.title,
285
+ description: String(post.body || '').slice(0, 150),
286
+ schema: { '@type': 'Article', headline: post.title },
287
+ }
288
+ },
289
+ urls: async () => (await Post.query().published().get()).map((p) => ({ path: '/blog/' + p.slug, lastmod: p.updated_at })),
290
+ }
291
+ ```
292
+
293
+ اختبرناه بطلب يحاكي زاحفًا:
294
+
295
+ ```bash
296
+ curl -A Googlebot "localhost:8000/blog/أول-مقال-في-kreft"
297
+ ```
298
+
299
+ والنتيجة تحوي `<title>أول مقال في Kreft</title>` ووسم `description` من نص المقال. ومقال غير موجود يعيد 404 حقيقيًا مع `noindex` لأن الدالة أعادت `null`.
300
+
301
+ ## الخطوة 6: صفحة القائمة مع بحث بتأخير
302
+
303
+ ```html
304
+ <!-- pages/Blog.kreft -->
305
+ state text = '' // ما يكتبه المستخدم
306
+ state query = '' // ما نبحث به فعلًا (بعد التأخير)
307
+ state tag = ''
308
+ state page = 1
309
+
310
+ // تأخير البحث 300 مللي ثانية: لا طلب مع كل حرف
311
+ let timer
312
+ watch text {
313
+ clearTimeout(timer)
314
+ timer = setTimeout(() => { query = value; page = 1 }, 300)
315
+ }
316
+ on destroy { clearTimeout(timer) }
317
+
318
+ load posts = api.get('/api/posts', { query: { q: query || undefined, tag: tag || undefined, page } })
319
+
320
+ derive meta = posts.data ? posts.data.meta : null
321
+
322
+ action pick(name) { tag = tag === name ? '' : name; page = 1 }
323
+
324
+ <view>
325
+ <h1>المدونة</h1>
326
+
327
+ <input type="search" k-model="text" placeholder="ابحث…">
328
+ <p>
329
+ <button k-each="t in ['kreft', 'js']" k-key="t" class={tag === t ? 'primary' : ''} @click="pick(t)">#{t}</button>
330
+ </p>
331
+
332
+ <p k-if="posts.loading && !posts.loaded">جارٍ التحميل…</p>
333
+ <section k-else>
334
+ {for p in posts.data ? posts.data.data : [] key p.id}
335
+ <article>
336
+ <h3><kreft-link to={'/blog/' + p.slug}>{p.title}</kreft-link></h3>
337
+ <p>{p.excerpt} · {p.views} مشاهدة</p>
338
+ </article>
339
+ {empty}
340
+ <p>لا مقالات تطابق بحثك.</p>
341
+ {/for}
342
+ </section>
343
+
344
+ <p k-if="meta">
345
+ <button disabled={page <= 1} @click="page--">السابق</button>
346
+ {page} / {meta.last_page}
347
+ <button disabled={page >= meta.last_page} @click="page++">التالي</button>
348
+ </p>
349
+ </view>
350
+ ```
351
+
352
+ ثلاثة أفكار في هذا الملف:
353
+
354
+ 1. **`text` و`query`:** نفصل ما يكتبه المستخدم عمّا نطلبه فعلًا. `watch text` يؤجل تحديث `query` 300 مللي ثانية، فتتجمع الضغطات.
355
+ 2. **`load posts`** يقرأ `query` و`tag` و`page` فيعيد الجلب تلقائيًا عند تغيّر أي منها.
356
+ 3. **`on destroy`** ينظّف المؤقت.
357
+
358
+ وفي اختبارنا بالمتصفح: كتابة أربعة أحرف متتالية بسرعة أنتجت **طلبًا واحدًا** فقط.
359
+
360
+ ضع المسار في `routes/web.kreft`:
361
+
362
+ ```js
363
+ Route.view('/blog', 'pages/Blog.kreft').name('blog').title('المدونة')
364
+ ```
365
+
366
+ ## تمارين
367
+
368
+ 1. أضف صفحة `/blog/:slug` تعرض المقال والتعليقات ونموذج تعليق بـ `form()` يطبّق القاعدة العربية على الواجهة أيضًا.
369
+ 2. أضف عدّادًا لمشاهدات اليوم بتخزين العدّاد في الذاكرة المؤقتة (`Cache`) وحفظه في قاعدة البيانات دفعة واحدة كل دقيقة بمهمة مجدولة.
370
+ 3. أضف لوحة إدارة لموافقة التعليقات `PATCH /comments/{id}` تحت `auth` و`admin`.