kreftjs 0.0.20-beta → 0.0.21-beta

package/README.md

@@ -24,7 +24,7 @@ action add() { count++ }
 You need [Node.js](https://nodejs.org) 22.5 or newer.
 
 ```bash
-npm i -g kreftjs          # once: makes the `kreft` command available everywhere
+npm install -g kreftjs@latest   # once: makes the `kreft` command available everywhere
 kreft new my-app        # asks: JavaScript or TypeScript?
 cd my-app
 npm run dev
@@ -42,6 +42,15 @@ Open the address in the terminal (normally `http://localhost:8000`). A new proje
 | **Authentication** | Cookie sessions with CSRF protection, API tokens with permissions, device list, two-factor codes, email verification, account lockout. |
 | **Tooling** | `kreft dev` with hot reload, DevTools, an error monitor, `kreft build` (CSP-safe), prerendering, TypeScript, Vite and Electron support, a safer `kreft add`, an MCP server for AI agents. |
 
+## Put it online
+
+```bash
+npm install kreftjs@latest       # the newest version
+npm run build                    # the finished site, ready to upload
+```
+
+Upload what is inside the output folder (`dist/`; for this repository's own website, `dist/kreftjs-com`) to your host. The kreftjs.com steps, and releasing a new package version with `npm publish`, are in [Publish the website](docs/README.md#publish-the-website-kreftjscom).
+
 ## Desktop apps (Electron)
 
 ```bash

package/bin/backend/http.js

@@ -96,6 +96,8 @@ const cookieSecure = () => {
 function response(body, status = 200, headers = {}) { return new Response(body, status, headers); }
 response.json = (body, status = 200, headers = {}) => new Response(body, status, headers);
 response.noContent = () => new Response(undefined, 204);
+// response.stream('/path/video.mp4') - sends a file with byte-range support (seeking, Safari); { type, download, headers }
+response.stream = (file, opts = {}) => { const r = new Response(undefined, 200); r.streamFile = { file, ...opts }; return r; };
 const noContent = () => new Response(undefined, 204);
 const toResponse = (v) => (v instanceof Response ? v : v === undefined ? new Response(undefined, 204) : new Response(v, 200));
 
@@ -313,8 +315,10 @@ class Request {
         if (kind === 'unique' && ignore && ignore !== 'NULL') { sql += ` AND ${conn.q(idColumn)} != ?`; params.push(ignore); }
         const found = (await conn.query(sql + ' LIMIT 1', params)).length > 0;
         const label = (names && names[field]) || field.replace(/_/g, ' ');
-        if (kind === 'unique' && found) (errors[field] = errors[field] || []).push(`The ${label} has already been taken.`);
-        if (kind === 'exists' && !found) (errors[field] = errors[field] || []).push(`The selected ${label} is invalid.`);
+        // your own message for the rule: { 'title.unique': 'That title is already used.' }
+        const own = messages && (messages[`${field}.${kind}`] || messages[kind]);
+        if (kind === 'unique' && found) (errors[field] = errors[field] || []).push(own || `The ${label} has already been taken.`);
+        if (kind === 'exists' && !found) (errors[field] = errors[field] || []).push(own || `The selected ${label} is invalid.`);
       }
     }
     if (Object.keys(errors).length) throw new ValidationError(errors);

package/bin/backend/index.js

@@ -273,6 +273,10 @@ const SECURITY_HEADERS = {
   });
   const send = (res, r) => {
     if (res.headersSent || res.writableEnded) return;
+    if (r.streamFile) { // response.stream(file): byte ranges for video and audio
+      const { file, ...o } = r.streamFile;
+      return require('./stream.js').sendFile(res.req, res, file, { ...o, headers: { 'Cache-Control': 'no-store', ...SECURITY_HEADERS, ...r.headers, ...(o.headers || {}) } });
+    }
     const status = r.statusCode || 200;
     const noBody = status === 204 || status === 304 || r.body === undefined;
     const isHtml = typeof r.body === 'string' && (r.headers && r.headers['Content-Type'] && r.headers['Content-Type'].includes('text/html'));

package/bin/backend/stream.js

@@ -0,0 +1,74 @@
+// Sending a file the way a video player needs it: byte ranges (206), so the browser can seek and Safari plays at all.
+const fs = require('fs');
+const path = require('path');
+
+const MEDIA_TYPES = {
+  '.mp4': 'video/mp4', '.m4v': 'video/mp4', '.webm': 'video/webm', '.ogv': 'video/ogg', '.mov': 'video/quicktime', '.mkv': 'video/x-matroska',
+  '.mp3': 'audio/mpeg', '.m4a': 'audio/mp4', '.aac': 'audio/aac', '.ogg': 'audio/ogg', '.oga': 'audio/ogg', '.wav': 'audio/wav', '.opus': 'audio/ogg', '.flac': 'audio/flac',
+  '.m3u8': 'application/vnd.apple.mpegurl', '.ts': 'video/mp2t', '.m4s': 'video/iso.segment', '.mpd': 'application/dash+xml', '.vtt': 'text/vtt',
+};
+
+// "bytes=0-99", "bytes=100-", "bytes=-500" -> { start, end } | null (no range) | false (cannot be satisfied)
+function parseRange(header, size) {
+  if (!header) return null;
+  const m = /^bytes=(\d*)-(\d*)$/.exec(String(header).trim()); // one range only; several ranges are answered with the whole file
+  if (!m || (m[1] === '' && m[2] === '')) return null;
+  let start, end;
+  if (m[1] === '') { // the last N bytes
+    const n = Number(m[2]);
+    if (n === 0) return false;
+    start = Math.max(0, size - n); end = size - 1;
+  } else {
+    start = Number(m[1]);
+    end = m[2] === '' ? size - 1 : Math.min(Number(m[2]), size - 1);
+  }
+  if (!Number.isFinite(start) || !Number.isFinite(end) || start > end || start >= size) return false;
+  return { start, end };
+}
+
+// sendFile(req, res, file, { type, headers, status, download })
+function sendFile(req, res, file, opts = {}) {
+  req = req || res.req;
+  let stat;
+  try { stat = fs.statSync(file); if (!stat.isFile()) throw new Error('not a file'); } catch (_) {
+    if (!res.headersSent) res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+    return res.end('Not found');
+  }
+  const size = stat.size;
+  const type = opts.type || MEDIA_TYPES[path.extname(file).toLowerCase()] || 'application/octet-stream';
+  const etag = `W/"${size.toString(16)}-${Math.floor(stat.mtimeMs).toString(16)}"`;
+  const headers = {
+    'Content-Type': type,
+    'Accept-Ranges': 'bytes',
+    'Last-Modified': stat.mtime.toUTCString(),
+    ETag: etag,
+    'X-Content-Type-Options': 'nosniff',
+    ...(opts.download ? { 'Content-Disposition': `attachment; filename*=UTF-8''${encodeURIComponent(path.basename(file))}` } : {}),
+    ...(opts.headers || {}),
+  };
+  const method = (req && req.method) || 'GET';
+  const h = (req && req.headers) || {};
+
+  if (h['if-none-match'] === etag && !h.range) { res.writeHead(304, headers); return res.end(); }
+
+  let range = parseRange(h.range, size);
+  // If-Range: only honor the range when the file is still the one the client started with
+  if (range && h['if-range'] && h['if-range'] !== etag && h['if-range'] !== headers['Last-Modified']) range = null;
+  if (range === false) {
+    res.writeHead(416, { 'Content-Range': `bytes */${size}`, 'Content-Type': 'text/plain; charset=utf-8' });
+    return res.end('Range not satisfiable');
+  }
+
+  let status = opts.status || 200, start = 0, end = size - 1;
+  if (range) { status = 206; ({ start, end } = range); headers['Content-Range'] = `bytes ${start}-${end}/${size}`; }
+  headers['Content-Length'] = size === 0 ? 0 : end - start + 1;
+  res.writeHead(status, headers);
+  if (method === 'HEAD' || size === 0) return res.end();
+
+  const stream = fs.createReadStream(file, { start, end });
+  stream.on('error', () => res.destroy());
+  res.on('close', () => stream.destroy()); // the viewer seeked or left: stop reading
+  stream.pipe(res);
+}
+
+module.exports = { sendFile, parseRange, MEDIA_TYPES };

package/bin/build.js

@@ -25,7 +25,7 @@ const path = require('path');
 const Kreftjs = require('../kreftjs.js');
 
 const { expandBlocks, prepareTemplate, splitKreft, splitInterp, exactBrace, stripBrace, interpToExpr, quoteBraceAttrs, expandSelfClosing,
-  scopeCss, hashString, propType, simplePathRE, fnExpRE, forAliasRE, stripTypeScript } = Kreftjs.__internal;
+  scopeCss, hashString, propType, typeCheck, caseCond, simplePathRE, fnExpRE, forAliasRE, stripTypeScript } = Kreftjs.__internal;
 
 const deps = require('./deps.js');
 // component files: .kreft, or .kreftjs in a project from the 0.0.x betas
@@ -329,12 +329,16 @@ function compileFile(file, rel, root) {
 
   // props: keep the default as a function so every instance gets its own copy
   const props = Object.entries(sp.props).map(([p, expr]) => {
-    if (expr == null) return `${JSON.stringify(p)}: {}`;
+    // `prop size: 'sm' | 'lg'`: the type text is kept, so the built app warns about a wrong value too
+    const ti = sp.propTypes && sp.propTypes[p];
+    const simple = ti && { string: 'String', number: 'Number', boolean: 'Boolean' }[ti.type.trim()];
+    const typed = ti ? `, typeText: ${JSON.stringify(ti.type)}, check: Kreftjs.__typeCheck(${JSON.stringify(ti.type)})${ti.required ? ', required: true' : ''}` : '';
+    if (expr == null) return `${JSON.stringify(p)}: { ${simple ? `type: ${simple}` : ''}${typed} }`.replace('{ , ', '{ ').replace('{  }', '{}');
     let sample;
     try { sample = new Function(`return (${expr})`)(); } catch (_) { /* uses something only known at runtime */ }
-    if (typeof sample === 'function') return `${JSON.stringify(p)}: { type: Function, default: (${expr}) }`;
+    if (typeof sample === 'function') return `${JSON.stringify(p)}: { type: Function, default: (${expr})${typed} }`;
     const type = propType(sample);
-    return `${JSON.stringify(p)}: { ${type ? `type: ${type.name}, ` : ''}default: function () { return (${expr}); } }`;
+    return `${JSON.stringify(p)}: { ${type ? `type: ${type.name}, ` : ''}default: function () { return (${expr}); }${typed} }`;
   });
 
   // imports: other .kreft files become component references; .js modules load with import()
@@ -439,12 +443,15 @@ function addRouterTemplates(fns) {
   addHandler(fns, 'navigate($event)');
 }
 
-const STRUCTURAL = new Set(['if', 'elif', 'else', 'each', 'key', 'ref', 'skip', 'cloak', 'slot', 'empty', 'once', 'animate', 'waiting', 'failed']);
+const STRUCTURAL = new Set(['match', 'case', 'default', 'if', 'elif', 'else', 'each', 'key', 'ref', 'skip', 'cloak', 'slot', 'empty', 'once', 'animate', 'waiting', 'failed']);
 
 function collectExpressions(template, fns) {
   const html = prepareTemplate(template);
+  const subjects = []; // k-match subjects seen so far: a k-case is compared with one of them
   scanHtml(html, {
     attr(name, value) {
+      if (name === 'k-match') { const v = stripBrace(value); subjects.push(v); return addEval(fns, v); }
+      if (name === 'k-case') { const raw = stripBrace(value); for (const sub of subjects) addEval(fns, caseCond(sub, raw)); return; }
       if (name[0] === ':' || name === 'k-bind' || name.startsWith('k-bind:')) return addEval(fns, value);
       if (name[0] === '@' || name.startsWith('k-on:')) return addHandler(fns, stripBrace(value));
       if (name.startsWith('k-')) {

package/bin/kreftjs.js

@@ -583,6 +583,30 @@ function copyFolder(from, to) {
 }
 
 /* ------------------------------------------------------------------ kreft vscode */
+/* VS Code only loads extensions listed in extensions.json, and after "Uninstall" it keeps the folder in .obsolete and
+   deletes it on the next start. Copying the folder is not enough after an uninstall: list it again and clear .obsolete. */
+function registerExtension(dir, folder, version) {
+  const id = 'kreft.kreftjs';
+  const location = path.join(dir, folder);
+  try {
+    const file = path.join(dir, 'extensions.json');
+    let list = [];
+    if (fs.existsSync(file)) { try { list = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { list = []; } }
+    if (!Array.isArray(list)) list = [];
+    list = list.filter((e) => !(e && e.identifier && /^kreft\.kreft(js)?$/.test(e.identifier.id)));
+    list.push({ identifier: { id }, version, location: { $mid: 1, fsPath: location, external: 'file://' + location, path: location, scheme: 'file' }, relativeLocation: folder, metadata: { installedTimestamp: Date.now(), pinned: false, source: 'resource', isApplicationScoped: false, isMachineScoped: false, isBuiltin: false, targetPlatform: 'undefined' } });
+    fs.writeFileSync(file, JSON.stringify(list));
+  } catch {}
+  try {
+    const file = path.join(dir, '.obsolete');
+    if (fs.existsSync(file)) {
+      const o = JSON.parse(fs.readFileSync(file, 'utf8'));
+      for (const k of Object.keys(o)) if (k.startsWith('kreft.kreftjs-') || k.startsWith('kreft.kreft-')) delete o[k];
+      fs.writeFileSync(file, JSON.stringify(o));
+    }
+  } catch {}
+}
+
 function installVscode() {
   const os = require('os');
   const from = path.join(__dirname, '..', 'editors', 'vscode');
@@ -595,6 +619,7 @@ function installVscode() {
     fs.mkdirSync(dir, { recursive: true });
     fs.readdirSync(dir).filter((n) => n.startsWith('kreft.kreftjs-') || n.startsWith('kreft.kreft-')) /* the older extensions go too */.forEach((n) => fs.rmSync(path.join(dir, n), { recursive: true, force: true }));
     copyFolder(from, path.join(dir, `kreft.kreftjs-${ext.version}`));
+    registerExtension(dir, `kreft.kreftjs-${ext.version}`, ext.version);
     console.log(`  Installed in ${path.join(dir, `kreft.kreftjs-${ext.version}`)}`);
   }
   // Ensure current project .vscode/settings.json maps .kreft files to Kreft and configures formatter
@@ -736,7 +761,7 @@ async function devServer(args, { production = false } = {}) {
     '.html': 'text/html', '.js': 'text/javascript', '.mjs': 'text/javascript', '.kreft': 'text/plain', '.kreftjs': 'text/plain',
     '.css': 'text/css', '.json': 'application/json', '.svg': 'image/svg+xml', '.png': 'image/png',
     '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp',
-    '.ico': 'image/x-icon', '.woff2': 'font/woff2', '.woff': 'font/woff', '.txt': 'text/plain', '.md': 'text/markdown',
+    '.ico': 'image/x-icon', ...(({ '.ts': _ts, ...media }) => media)(require('./backend/stream.js').MEDIA_TYPES), '.woff2': 'font/woff2', '.woff': 'font/woff', '.txt': 'text/plain', '.md': 'text/markdown',
   };
   const isFile = (p) => { try { return fs.statSync(p).isFile(); } catch (_) { return false; } };
 
@@ -754,12 +779,15 @@ async function devServer(args, { production = false } = {}) {
       }
     }
     const type = types[path.extname(file).toLowerCase()] || 'application/octet-stream';
-    res.writeHead(opts.status || 200, {
+    const fileHeaders = {
       'Content-Type': type + (type.startsWith('text/') || type.endsWith('json') ? '; charset=utf-8' : ''),
       'Cache-Control': isProd ? 'no-cache' : 'no-store', // dev: always pick up your latest changes
       'X-Content-Type-Options': 'nosniff',
       ...prodHeaders,
-    });
+    };
+    // everything but pages is sent with byte ranges (video and audio seek, Safari plays)
+    if (type !== 'text/html') return require('./backend/stream.js').sendFile(res.req, res, file, { status: opts.status, type: fileHeaders['Content-Type'], headers: fileHeaders });
+    res.writeHead(opts.status || 200, fileHeaders);
     if (!production && type === 'text/html') {
       let html = fs.readFileSync(file, 'utf8');
       // PUBLIC_ values from .env, as Kreftjs.env (kreft build puts them in app.js)
@@ -794,12 +822,9 @@ async function devServer(args, { production = false } = {}) {
       return res.end(opts.seo ? require('./backend/seo-pages.js').inject(html, opts.seo) : html);
     }
     if (type === 'text/html' && opts.seo) return res.end(require('./backend/seo-pages.js').inject(fs.readFileSync(file, 'utf8'), opts.seo));
-    const stream = fs.createReadStream(file);
-    stream.on('error', () => {
-      if (!res.headersSent) res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
-      res.end('Not found');
-    });
-    stream.pipe(res);
+    const page = fs.createReadStream(file); // a page in production: headers are written, send it whole
+    page.on('error', () => res.end('Not found'));
+    page.pipe(res);
   }
 
   // ----- hot reload: watch the folder, tell open pages what changed -----
@@ -1109,8 +1134,7 @@ async function devServer(args, { production = false } = {}) {
         const realPub = real(pub), realF = real(f);
         if ((f.startsWith(pub + path.sep)) && !secret(urlPath) && isFile(f) && realPub && realF && realF.startsWith(realPub + path.sep)) {
           const type = types[path.extname(f).toLowerCase()] || 'application/octet-stream';
-          res.writeHead(200, { 'Content-Type': type, 'X-Content-Type-Options': 'nosniff', 'Content-Security-Policy': "default-src 'none'; img-src 'self'; style-src 'unsafe-inline'; sandbox", 'Cache-Control': 'public, max-age=3600' });
-          return fs.createReadStream(f).pipe(res);
+          return require('./backend/stream.js').sendFile(req, res, f, { type, headers: { 'Content-Security-Policy': "default-src 'none'; img-src 'self'; media-src 'self'; style-src 'unsafe-inline'; sandbox", 'Cache-Control': /\.(m3u8|mpd)$/i.test(f) ? 'no-cache' : 'public, max-age=3600' } }); // a live playlist changes every few seconds
         }
         res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
         return res.end('Not found: ' + urlPath);

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` يبدّل العنصر بدل اختياره وحيدًا.