@ozsarman/clarityjs 0.6.0

package/src/islands.js

@@ -0,0 +1,284 @@
+/**
+ * Clarity.js — Islands Architecture
+ *
+ * Statik HTML sayfa üzerinde seçici hidrasyon (selective hydration).
+ * Astro Islands / React Server Components benzeri model.
+ *
+ * Çalışma prensibi:
+ *  1. Tüm sayfa sunucuda statik HTML olarak render edilir
+ *  2. Sadece `island:client` direktifi olan bileşenler client JS yükler
+ *  3. Diğer bileşenler sıfır JavaScript gönderir
+ *
+ * ── Kullanım (.clarity içinde) ────────────────────────────────────────────────
+ *
+ *   component App() {
+ *     render {
+ *       <div>
+ *         <StaticHeader />                    // Server-only — sıfır JS
+ *         <Counter island:client />           // İnteraktif adacık — JS yüklenir
+ *         <StaticFooter />                    // Server-only — sıfır JS
+ *
+ *         // Yükleme stratejisi seçimi:
+ *         <HeavyWidget island:client="visible" />   // Görünür olunca
+ *         <Analytics island:client="idle" />        // Tarayıcı boştayken
+ *         <Modal island:client="load" />            // Sayfa yüklenir yüklenmez
+ *         <Tooltip island:client="hover" />         // Hover'da
+ *       </div>
+ *     }
+ *   }
+ *
+ * ── Programatik API ───────────────────────────────────────────────────────────
+ *
+ *   import { createIsland, hydrateIslands } from '@ozsarman/clarityjs/islands';
+ *
+ *   // Server: adacık HTML'i oluştur + hidrasyon şeridi göm
+ *   const html = createIsland(Counter, { initialCount: 0 }, { strategy: 'visible' });
+ *
+ *   // Client: sayfadaki tüm adacıkları bul ve hidrate et
+ *   hydrateIslands();
+ *
+ * Author: Claude (Anthropic) + Özdemir Sarman
+ */
+
+import { renderToString } from './ssr.js';
+
+// ─── Adacık stratejileri ──────────────────────────────────────────────────────
+
+/**
+ * @typedef {'load' | 'idle' | 'visible' | 'hover' | 'none'} IslandStrategy
+ *
+ *   load    – sayfa yüklenince hemen hidrate et (varsayılan)
+ *   idle    – requestIdleCallback ile boş anında
+ *   visible – IntersectionObserver ile görünür olunca
+ *   hover   – fareyle üzerine gelince
+ *   none    – hiçbir zaman (sadece statik HTML)
+ */
+
+// ─── Server-side: adacık oluştur ──────────────────────────────────────────────
+
+/**
+ * Bir bileşeni sunucuda render et + client hidrasyon bilgisini göm.
+ *
+ * @param {Function}      ComponentFn   – Clarity component fonksiyonu
+ * @param {object}        [props={}]    – bileşen prop'ları
+ * @param {object}        [opts={}]
+ * @param {IslandStrategy} [opts.strategy='load']  – hidrasyon stratejisi
+ * @param {string}        [opts.id]     – benzersiz adacık kimliği (otomatik üretilir)
+ * @param {string}        [opts.import] – client bundle'da bileşenin import yolu
+ * @returns {string}  HTML string (hidrasyon metadata'sı gömülü)
+ */
+export function createIsland(ComponentFn, props = {}, opts = {}) {
+  const {
+    strategy = 'load',
+    id       = `island-${Math.random().toString(36).slice(2, 8)}`,
+    importPath = null,
+  } = opts;
+
+  // Bileşeni sunucuda render et
+  const innerHTML = renderToString(ComponentFn, { props });
+
+  // Hidrasyon verisi — JSON olarak data attribute'a gömülür
+  const islandData = JSON.stringify({
+    component: ComponentFn.name || ComponentFn.displayName || 'Unknown',
+    props,
+    strategy,
+    importPath,
+  });
+
+  return `<clarity-island
+  id="${id}"
+  data-strategy="${strategy}"
+  data-island='${_escapeAttr(islandData)}'
+  style="display:contents"
+>${innerHTML}</clarity-island>`;
+}
+
+// ─── Client-side: adacıkları hidrate et ──────────────────────────────────────
+
+/**
+ * Sayfadaki tüm `<clarity-island>` elementlerini bulup hidrate eder.
+ * Client entry point'te çağrılır.
+ *
+ * @param {object} [componentMap={}]  – bileşen adı → ComponentFn eşlemesi
+ *                                       (dinamik import desteklenmiyorsa)
+ */
+export function hydrateIslands(componentMap = {}) {
+  if (typeof document === 'undefined') return; // SSR ortamda çalışmasın
+
+  const islands = document.querySelectorAll('clarity-island');
+  if (islands.length === 0) return;
+
+  console.log(`[clarity/islands] ${islands.length} adacık bulundu`);
+
+  for (const el of islands) {
+    _scheduleHydration(el, componentMap);
+  }
+}
+
+function _scheduleHydration(el, componentMap) {
+  const strategy = el.dataset.strategy || 'load';
+  const data     = _parseIslandData(el);
+  if (!data) return;
+
+  switch (strategy) {
+    case 'load':
+      _hydrateElement(el, data, componentMap);
+      break;
+
+    case 'idle':
+      if ('requestIdleCallback' in window) {
+        requestIdleCallback(() => _hydrateElement(el, data, componentMap));
+      } else {
+        setTimeout(() => _hydrateElement(el, data, componentMap), 200);
+      }
+      break;
+
+    case 'visible': {
+      const observer = new IntersectionObserver((entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            observer.unobserve(el);
+            _hydrateElement(el, data, componentMap);
+          }
+        }
+      }, { rootMargin: '50px' });
+      observer.observe(el);
+      break;
+    }
+
+    case 'hover':
+      el.addEventListener('mouseenter', () => _hydrateElement(el, data, componentMap), { once: true });
+      el.addEventListener('touchstart', () => _hydrateElement(el, data, componentMap), { once: true, passive: true });
+      break;
+
+    case 'none':
+      // Statik — hidrasyonsuz
+      break;
+
+    default:
+      _hydrateElement(el, data, componentMap);
+  }
+}
+
+async function _hydrateElement(el, data, componentMap) {
+  if (el.dataset.hydrated) return;
+  el.dataset.hydrated = 'true';
+
+  let ComponentFn = componentMap[data.component];
+
+  // Dinamik import denemeleri
+  if (!ComponentFn && data.importPath) {
+    try {
+      const mod = await import(data.importPath);
+      ComponentFn = mod[data.component] ?? mod.default;
+    } catch (err) {
+      console.error(`[clarity/islands] import hatası (${data.importPath}): ${err.message}`);
+      return;
+    }
+  }
+
+  if (!ComponentFn) {
+    console.warn(`[clarity/islands] Bileşen bulunamadı: ${data.component}`);
+    return;
+  }
+
+  try {
+    const { hydrateRoot } = await import('./hydrate.js');
+    hydrateRoot(ComponentFn, el, data.props);
+    console.log(`[clarity/islands] ✅ ${data.component} (${data.strategy})`);
+  } catch (err) {
+    console.error(`[clarity/islands] hidrasyon hatası (${data.component}): ${err.message}`);
+  }
+}
+
+function _parseIslandData(el) {
+  try {
+    return JSON.parse(el.dataset.island || '{}');
+  } catch {
+    return null;
+  }
+}
+
+// ─── defineServerComponent ────────────────────────────────────────────────────
+
+/**
+ * Bir bileşeni sunucu bileşeni olarak işaretle.
+ * Bu bileşenler client bundle'a dahil edilmez.
+ *
+ * @param {Function} ComponentFn
+ * @returns {Function}  Aynı fonksiyon + __clarity_server__ = true işareti
+ */
+export function defineServerComponent(ComponentFn) {
+  ComponentFn.__clarity_server_only__ = true;
+  return ComponentFn;
+}
+
+/**
+ * Bir bileşen sunucu bileşeni mi?
+ */
+export function isServerComponent(ComponentFn) {
+  return !!ComponentFn.__clarity_server_only__;
+}
+
+// ─── Vite plugin: islands dönüşümü ───────────────────────────────────────────
+
+/**
+ * Vite transform hook'u — `island:client` direktifini işler.
+ * clarityPlugin() içinde otomatik kullanılır.
+ *
+ * `island:client` direktifi olan JSX elementini:
+ *   <Counter island:client="visible" initialCount={0} />
+ *
+ * Buna dönüştürür (server):
+ *   createIsland(Counter, { initialCount: 0 }, { strategy: 'visible' })
+ *
+ * @internal
+ */
+export function transformIslandDirective(code, id) {
+  // island:client direktifini tara — basit regex tabanlı dönüşüm
+  // CodeGenerator'dan geçtikten sonra üretilen JS'e uygulanır
+  return code.replace(
+    /(\w+)\(\{\s*([^}]*)"island:client"\s*:\s*"([^"]*)"([^}]*)\}\)/g,
+    (match, fnName, beforeProps, strategy, afterProps) => {
+      const props = (beforeProps + afterProps).replace(/,\s*,/g, ',').trim().replace(/^,|,$/g, '');
+      return `createIsland(${fnName}, {${props}}, { strategy: '${strategy || 'load'}' })`;
+    }
+  );
+}
+
+// ─── SSR helper: adacıkları HTML'e göm ───────────────────────────────────────
+
+/**
+ * SSR sırasında bir sayfanın adacıklarını render et.
+ * renderToDocument() ile birlikte kullanım içindir.
+ *
+ * @param {Function}   PageComponent
+ * @param {object}     props
+ * @param {object}     islandDefs   – { ComponentName: { ComponentFn, strategy } }
+ * @returns {string}   HTML
+ */
+export function renderPageWithIslands(PageComponent, props = {}, islandDefs = {}) {
+  // Server ortamında adacıkları statik HTML + hidrasyon metadata'sı ile render et
+  // global'e adacık factory'leri kaydet — ssr.js render sırasında bunları kullanır
+  if (typeof globalThis !== 'undefined') {
+    globalThis.__clarity_islands__ = islandDefs;
+  }
+
+  try {
+    return renderToString(PageComponent, { props });
+  } finally {
+    if (typeof globalThis !== 'undefined') {
+      delete globalThis.__clarity_islands__;
+    }
+  }
+}
+
+// ─── Util ─────────────────────────────────────────────────────────────────────
+
+function _escapeAttr(str) {
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/'/g, '&#39;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}

package/src/isr.js

@@ -0,0 +1,306 @@
+/**
+ * Clarity.js — Incremental Static Regeneration (ISR)
+ *
+ * Belirli aralıklarla veya istek üzerine statik sayfaları yeniler.
+ * Next.js revalidate / Nuxt routeRules ISR eşdeğeri.
+ *
+ * ── Kullanım (getStaticProps içinde) ─────────────────────────────────────────
+ *
+ *   // pages/blog/[slug].js
+ *   export async function getStaticProps({ params }) {
+ *     const post = await db.posts.findBySlug(params.slug);
+ *     return {
+ *       props: { post },
+ *       revalidate: 60,   // 60 saniyede bir arka planda yeniden üret
+ *     };
+ *   }
+ *
+ * ── On-demand revalidation ────────────────────────────────────────────────────
+ *
+ *   // pages/api/revalidate.js
+ *   import { revalidatePath, revalidateTag } from '@ozsarman/clarityjs/isr';
+ *
+ *   export async function POST(req, res) {
+ *     const { path, secret } = req.body;
+ *     if (secret !== process.env.REVALIDATE_SECRET) return res.status(401).json({ error: 'Unauthorized' });
+ *
+ *     await revalidatePath(path, { pagesDir: './pages', outDir: './dist' });
+ *     res.json({ revalidated: true });
+ *   }
+ *
+ * ── Express middleware ────────────────────────────────────────────────────────
+ *
+ *   import { createISRMiddleware } from '@ozsarman/clarityjs/isr';
+ *
+ *   const isr = createISRMiddleware({ outDir: './dist', pagesDir: './pages' });
+ *   app.use(isr);  // Her istekte: bayat mı? → arka planda yenile → statik dosyayı sun
+ *
+ * Author: Claude (Anthropic) + Özdemir Sarman
+ */
+
+import { readFile, writeFile, mkdir, stat } from 'node:fs/promises';
+import { existsSync }                        from 'node:fs';
+import { join, dirname, resolve }            from 'node:path';
+import { pathToFileURL }                     from 'node:url';
+
+// ─── ISR Metadata Store ───────────────────────────────────────────────────────
+
+const ISR_META_FILE = '_clarity_isr.json';
+
+/**
+ * ISR metadata'yı diskten yükle.
+ * @param {string} outDir
+ * @returns {Promise<object>}
+ */
+async function _loadMeta(outDir) {
+  const metaPath = join(resolve(outDir), ISR_META_FILE);
+  if (!existsSync(metaPath)) return {};
+  try {
+    const raw = await readFile(metaPath, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * ISR metadata'yı diske kaydet.
+ */
+async function _saveMeta(outDir, data) {
+  const metaPath = join(resolve(outDir), ISR_META_FILE);
+  await writeFile(metaPath, JSON.stringify(data, null, 2), 'utf8');
+}
+
+// ─── On-demand revalidation ───────────────────────────────────────────────────
+
+/**
+ * Belirli bir yolu anında yeniden üret.
+ *
+ * @param {string}  path     – yenilenecek route (örn: '/blog/my-post')
+ * @param {object}  opts
+ * @param {string}  opts.pagesDir
+ * @param {string}  opts.outDir
+ * @param {string}  [opts.baseUrl]
+ * @param {string}  [opts.clientScript]
+ * @param {string}  [opts.title]
+ * @returns {Promise<boolean>}  – başarıyla yenilendiyse true
+ */
+export async function revalidatePath(path, opts = {}) {
+  const { pagesDir = 'pages', outDir = 'dist', baseUrl = '', clientScript = null, title = '' } = opts;
+
+  const meta = await _loadMeta(outDir);
+  const entry = meta[path];
+
+  if (!entry) {
+    console.warn(`[clarity/isr] revalidatePath: '${path}' ISR metadata bulunamadı`);
+    return false;
+  }
+
+  const success = await _regeneratePage(path, entry, { outDir, baseUrl, clientScript, title });
+
+  if (success) {
+    meta[path] = {
+      ...entry,
+      generatedAt: Date.now(),
+      expiresAt:   Date.now() + entry.revalidate * 1000,
+    };
+    await _saveMeta(outDir, meta);
+  }
+
+  return success;
+}
+
+/**
+ * Tag'e göre birden fazla yolu yenile.
+ * getStaticProps'ta `tags: ['posts']` ile etiketlenmiş sayfaları yeniler.
+ *
+ * @param {string}  tag
+ * @param {object}  opts
+ */
+export async function revalidateTag(tag, opts = {}) {
+  const { outDir = 'dist' } = opts;
+  const meta = await _loadMeta(outDir);
+  const paths = Object.entries(meta)
+    .filter(([, entry]) => Array.isArray(entry.tags) && entry.tags.includes(tag))
+    .map(([p]) => p);
+
+  console.log(`[clarity/isr] Tag '${tag}' için ${paths.length} sayfa yenileniyor...`);
+  const results = await Promise.all(paths.map(p => revalidatePath(p, opts)));
+  return results.every(Boolean);
+}
+
+// ─── Express ISR Middleware ───────────────────────────────────────────────────
+
+/**
+ * Express middleware factory — stale-while-revalidate pattern.
+ *
+ * Çalışma prensibi:
+ *  1. İstek gelir
+ *  2. Statik HTML dosyası var mı? → Varsa hemen sun
+ *  3. Dosya bayat mı (expiresAt geçti)? → Arka planda yenile (kullanıcıyı beklettirme)
+ *  4. Statik dosya yoksa → SSR ile üret, hem sun hem kaydet
+ *
+ * @param {object} opts
+ * @param {string}  opts.outDir
+ * @param {string}  opts.pagesDir
+ * @param {string}  [opts.baseUrl]
+ * @param {string}  [opts.clientScript]
+ * @param {string}  [opts.title]
+ * @param {boolean} [opts.verbose]
+ * @returns {Function}  Express middleware
+ */
+export function createISRMiddleware(opts = {}) {
+  const {
+    outDir       = 'dist',
+    pagesDir     = 'pages',
+    baseUrl      = '',
+    clientScript = null,
+    title        = '',
+    verbose      = false,
+  } = opts;
+
+  const log = (...args) => verbose && console.log('[clarity/isr]', ...args);
+
+  // Arka planda yenileme kuyrukta mı? Duplicate önlemek için
+  const _revalidating = new Set();
+
+  return async function isrMiddleware(req, res, next) {
+    // Sadece GET isteklerini yönet
+    if (req.method !== 'GET') return next();
+
+    const urlPath = req.path === '/' ? '/' : req.path.replace(/\/$/, '');
+    const outDirAbs = resolve(outDir);
+
+    // Statik HTML dosyasını ara
+    const htmlFile = urlPath === '/'
+      ? join(outDirAbs, 'index.html')
+      : join(outDirAbs, urlPath.slice(1), 'index.html');
+
+    const fileExists = existsSync(htmlFile);
+
+    if (fileExists) {
+      // Dosya var — hemen sun
+      res.setHeader('Content-Type', 'text/html; charset=utf-8');
+      res.setHeader('X-Clarity-SSG', 'hit');
+
+      // Bayatlık kontrolü — arka planda yenile
+      const meta = await _loadMeta(outDir);
+      const entry = meta[urlPath];
+      if (entry && Date.now() > entry.expiresAt && !_revalidating.has(urlPath)) {
+        _revalidating.add(urlPath);
+        log(`stale → arka planda yenileniyor: ${urlPath}`);
+        _regeneratePage(urlPath, entry, { outDir, baseUrl, clientScript, title })
+          .then(async (ok) => {
+            if (ok) {
+              meta[urlPath] = {
+                ...entry,
+                generatedAt: Date.now(),
+                expiresAt:   Date.now() + entry.revalidate * 1000,
+              };
+              await _saveMeta(outDir, meta);
+              log(`✅ arka planda yenilendi: ${urlPath}`);
+            }
+          })
+          .finally(() => _revalidating.delete(urlPath));
+      }
+
+      return res.sendFile(htmlFile);
+    }
+
+    // Dosya yok — SSR ile üret ve kaydet
+    log(`miss → SSR ile üretiliyor: ${urlPath}`);
+    try {
+      const { renderToDocument } = await import('./ssr.js');
+      const { FileRouter }       = await import('../packages/clarity-ssr/file-router.js');
+
+      const router = new FileRouter(resolve(pagesDir));
+      await router.scan();
+      const match = router.match(urlPath);
+
+      if (!match) return next();
+
+      const { route, params } = match;
+      let pageProps = params;
+
+      if (route.loader) {
+        const loaderData = await route.loader({ params, query: req.query, req });
+        pageProps = { ...params, loaderData };
+      }
+
+      const html = renderToDocument(route.component, {
+        props: pageProps, title: route.meta?.title ?? title, clientScript,
+      });
+
+      await mkdir(dirname(htmlFile), { recursive: true });
+      await writeFile(htmlFile, html, 'utf8');
+
+      res.setHeader('Content-Type', 'text/html; charset=utf-8');
+      res.setHeader('X-Clarity-SSG', 'generated');
+      res.send(html);
+    } catch (err) {
+      console.error(`[clarity/isr] SSR hata: ${err.message}`);
+      next(err);
+    }
+  };
+}
+
+// ─── Periyodik revalidation scheduler ────────────────────────────────────────
+
+/**
+ * Tüm bayat ISR sayfalarını periyodik olarak yenile.
+ * Sunucu başlatılırken bir kez çağrıl.
+ *
+ * @param {object} opts
+ * @param {string}  opts.outDir
+ * @param {number}  [opts.interval=30000]  – kontrol aralığı (ms)
+ * @returns {{ stop: Function }}
+ */
+export function startISRScheduler(opts = {}) {
+  const { outDir = 'dist', interval = 30_000, ...rest } = opts;
+
+  const timer = setInterval(async () => {
+    const meta  = await _loadMeta(outDir);
+    const stale = Object.entries(meta).filter(([, e]) => Date.now() > e.expiresAt);
+
+    if (stale.length === 0) return;
+    console.log(`[clarity/isr] ${stale.length} bayat sayfa yenileniyor...`);
+
+    for (const [path, entry] of stale) {
+      await revalidatePath(path, { outDir, ...rest });
+    }
+  }, interval);
+
+  return { stop: () => clearInterval(timer) };
+}
+
+// ─── Internal: single page regen ─────────────────────────────────────────────
+
+async function _regeneratePage(routePath, entry, { outDir, baseUrl, clientScript, title }) {
+  try {
+    const { renderToDocument } = await import('./ssr.js');
+    const pageFile = resolve(entry.file);
+    const mod      = await import(pathToFileURL(pageFile).href + `?t=${Date.now()}`);
+
+    let pageProps = entry.params ?? {};
+    if (typeof mod.getStaticProps === 'function') {
+      const result = await mod.getStaticProps({ params: entry.params ?? {} });
+      if (result?.notFound) return false;
+      pageProps = { ...pageProps, ...(result?.props ?? {}) };
+    }
+
+    const html = renderToDocument(mod.default, {
+      props: pageProps, title: mod.meta?.title ?? title, clientScript,
+    });
+
+    const htmlFile = routePath === '/'
+      ? join(resolve(outDir), 'index.html')
+      : join(resolve(outDir), routePath.slice(1), 'index.html');
+
+    await mkdir(dirname(htmlFile), { recursive: true });
+    await writeFile(htmlFile, html, 'utf8');
+    return true;
+  } catch (err) {
+    console.error(`[clarity/isr] regen hata (${routePath}): ${err.message}`);
+    return false;
+  }
+}