jskelet 0.1.1 → 0.1.3

package/src/client/form.js

@@ -0,0 +1,192 @@
+/**
+ * Form gönderimini sayfa yenilemeden yürütür — ama yenilemeyi de bozmadan.
+ *
+ * Sözleşme bilinçli olarak "progressive enhancement": form normal bir
+ * `<form method="post" action="…">`. JS yüklenmemişse, hata verdiyse ya da
+ * kullanıcı kapattıysa tarayıcı formu kendisi gönderir ve sunucu yönlendirme
+ * ile cevap verir. Bu dosya yalnızca aradaki tam sayfa turunu kaldırıyor.
+ *
+ * Sunucudan üç cevaptan biri beklenir:
+ *   - yönlendirme  → `location.assign` ile izlenir (başarılı mutasyon)
+ *   - 4xx + parça  → formun yerine takılır (alan bazlı doğrulama hataları)
+ *   - 2xx + parça  → hedef bölgeye takılır (güncellenen liste, kart)
+ *
+ * CSRF token'ı `csrfField()` tarafından basılan gizli alanda; `FormData`
+ * onu kendiliğinden taşıdığı için burada ek bir iş yok.
+ */
+import { hydrate, unmount } from "./registry.js";
+
+/**
+ * @param {HTMLFormElement} form
+ * @param {boolean} busy
+ */
+function setBusy(form, busy) {
+  form.toggleAttribute("data-submitting", busy);
+
+  for (const element of form.elements) {
+    if (
+      element instanceof HTMLButtonElement ||
+      (element instanceof HTMLInputElement && element.type === "submit")
+    ) {
+      element.disabled = busy;
+    }
+  }
+}
+
+/**
+ * @param {HTMLElement} element
+ * @param {string} html
+ */
+function replaceContent(element, html) {
+  unmount(element);
+  element.innerHTML = html;
+  hydrate(element);
+}
+
+/**
+ * @param {HTMLFormElement} form
+ * @param {string} html
+ */
+function replaceForm(form, html) {
+  const holder = document.createElement("div");
+  holder.innerHTML = html;
+
+  const replacement = holder.firstElementChild;
+  if (!replacement) return;
+
+  unmount(form);
+  form.replaceWith(replacement);
+  hydrate(replacement);
+
+  // Doğrulama hatasında odak ilk hatalı alana gitmeli; klavye kullanıcısı
+  // aksi hâlde hatanın nerede olduğunu bulmak için baştan geziyor.
+  const invalid = replacement.querySelector("[aria-invalid='true'], [data-field-error]");
+  if (invalid instanceof HTMLElement) invalid.focus();
+}
+
+/**
+ * @param {HTMLFormElement} form
+ * @param {HTMLElement | null} submitter
+ */
+async function submitForm(form, submitter) {
+  setBusy(form, true);
+
+  const method = (form.method || "post").toUpperCase();
+  const action = form.action || location.href;
+  const data = new FormData(form);
+
+  // Gönderen butonun `name`/`value`'su `FormData`'ya girmez; hangi eylemin
+  // tetiklendiğini ayırt eden formlar (kaydet / sil) buna güveniyor.
+  if (
+    (submitter instanceof HTMLButtonElement ||
+      submitter instanceof HTMLInputElement) &&
+    submitter.name
+  ) {
+    data.append(submitter.name, submitter.value);
+  }
+
+  try {
+    const isGet = method === "GET";
+    const query = new URLSearchParams();
+    if (isGet) {
+      for (const [key, value] of data.entries()) {
+        if (typeof value === "string") query.append(key, value);
+      }
+    }
+
+    const response = await fetch(isGet ? `${action.split("?")[0]}?${query}` : action, {
+      method,
+      body: isGet ? null : data,
+      headers: { "X-Requested-With": "fragment" },
+      credentials: "same-origin",
+    });
+
+    if (response.redirected) {
+      location.assign(response.url);
+      return;
+    }
+
+    const html = await response.text();
+    const target = form.dataset.target
+      ? document.querySelector(form.dataset.target)
+      : null;
+
+    if (!response.ok || !target) {
+      replaceForm(form, html);
+    } else {
+      replaceContent(/** @type {HTMLElement} */ (target), html);
+      form.reset();
+    }
+
+    form.dispatchEvent(
+      new CustomEvent("jskelet:submitted", {
+        bubbles: true,
+        detail: { ok: response.ok, status: response.status },
+      }),
+    );
+  } catch (error) {
+    console.error("[form] submit failed", error);
+    // Ağ hatasında formu kilitli bırakmıyoruz: kullanıcı tekrar denesin.
+    form.dispatchEvent(
+      new CustomEvent("jskelet:submit-error", { bubbles: true, detail: { error } }),
+    );
+  } finally {
+    setBusy(form, false);
+  }
+}
+
+/**
+ * @param {SubmitEvent} event
+ * @param {HTMLFormElement} form
+ */
+function onSubmit(event, form) {
+  // Tarayıcının kendi doğrulaması geçmediyse hiç ağa çıkmıyoruz; hata
+  // balonlarını da tarayıcı gösterir.
+  if (!form.checkValidity()) return;
+  if (form.hasAttribute("data-submitting")) {
+    event.preventDefault();
+    return;
+  }
+
+  event.preventDefault();
+  void submitForm(form, /** @type {HTMLElement | null} */ (event.submitter));
+}
+
+/**
+ * Tek bir formu bağlar.
+ *
+ * `data-target` verilirse başarılı yanıtın gövdesi o bölgeye takılır; yoksa
+ * yanıt formun kendisini değiştirir (doğrulama hatalarının geldiği yol).
+ *
+ * @param {HTMLFormElement} form
+ * @returns {() => void} Dinleyiciyi söken fonksiyon.
+ */
+export function enhanceForm(form) {
+  /** @param {Event} event */
+  const listener = (event) => onSubmit(/** @type {SubmitEvent} */ (event), form);
+
+  form.addEventListener("submit", listener);
+  return () => form.removeEventListener("submit", listener);
+}
+
+/**
+ * `data-enhance` taşıyan formları tek bir delege dinleyiciyle bağlar.
+ * `submit` olayı köpürdüğü için sonradan DOM'a giren (fragment ile gelen)
+ * formlar da kapsanır ve her takastan sonra yeniden bağlama gerekmez.
+ *
+ * @param {ParentNode} [root]
+ * @returns {() => void}
+ */
+export function startForms(root = document) {
+  /** @param {Event} event */
+  const listener = (event) => {
+    const form = event.target;
+    if (!(form instanceof HTMLFormElement)) return;
+    if (!("enhance" in form.dataset)) return;
+
+    onSubmit(/** @type {SubmitEvent} */ (event), form);
+  };
+
+  root.addEventListener("submit", listener);
+  return () => root.removeEventListener("submit", listener);
+}

package/src/client/index.js

@@ -11,7 +11,16 @@
  *
  *   start();
  */
-export { register, registerAll, hydrate, observeDocument, start } from "./registry.js";
+export {
+  register,
+  registerAll,
+  hydrate,
+  unmount,
+  observeDocument,
+  start,
+} from "./registry.js";
+export { swap, startSwapLinks } from "./swap.js";
+export { enhanceForm, startForms } from "./form.js";
 export { createStore } from "./store.js";
 export {
   debounce,

package/src/client/registry.js

@@ -28,6 +28,18 @@ const loaders = new Map();
 /** @type {WeakMap<HTMLElement, Set<string>>} */
 const mounted = new WeakMap();
 
+/**
+ * `mount()` bir temizlik fonksiyonu döndürebiliyor; DOM'dan çıkan island'ın
+ * dinleyicilerini ve zamanlayıcılarını sökmek için saklanır.
+ *
+ * WeakMap: sökülmeden çöpe giden bir element (ör. tüm sayfa gezinmesi)
+ * burada referans bırakmasın. Alt ağacı gezme işi DOM üzerinden yapılıyor,
+ * bu yüzden ayrı bir element listesine gerek yok.
+ *
+ * @type {WeakMap<HTMLElement, (() => void)[]>}
+ */
+const cleanups = new WeakMap();
+
 /**
  * @param {string} name
  * @param {() => Promise<{ mount: MountFn }>} loader
@@ -55,7 +67,7 @@ function readProps(element) {
     return JSON.parse(raw);
   } catch (error) {
     console.error(
-      `[island] ${element.dataset.island}: geçersiz data-island-props`,
+      `[island] ${element.dataset.island}: invalid data-island-props`,
       error,
     );
     return {};
@@ -92,7 +104,7 @@ async function mountIsland(element) {
 
   const loader = loaders.get(name);
   if (!loader) {
-    console.warn(`[island] kayıtlı değil: ${name}`);
+    console.warn(`[island] not registered: ${name}`);
     return;
   }
 
@@ -100,10 +112,72 @@ async function mountIsland(element) {
 
   try {
     const module = await loader();
-    module.mount(element, readProps(element));
+    const cleanup = module.mount(element, readProps(element));
+
+    if (typeof cleanup === "function") {
+      // Island bağlanırken DOM'dan çıkarılmış olabilir (hızlı bir fragment
+      // takası). Temizliği saklamak yerine hemen çalıştırmak gerekiyor;
+      // aksi hâlde artık görünmeyen bir elementin dinleyicileri hiç sökülmez.
+      if (element.isConnected) {
+        const list = cleanups.get(element) ?? [];
+        list.push(cleanup);
+        cleanups.set(element, list);
+      } else {
+        runCleanups(element, cleanup);
+      }
+    }
+
     element.dataset.islandReady = "true";
   } catch (error) {
-    console.error(`[island] ${name} yüklenemedi`, error);
+    console.error(`[island] ${name} failed to load`, error);
+  }
+}
+
+/**
+ * @param {HTMLElement} element
+ * @param {() => void} [extra] Henüz saklanmamış temizlik.
+ */
+function runCleanups(element, extra) {
+  const stored = cleanups.get(element) ?? [];
+  cleanups.delete(element);
+  mounted.delete(element);
+  delete element.dataset.islandReady;
+
+  for (const cleanup of extra ? [...stored, extra] : stored) {
+    try {
+      cleanup();
+    } catch (error) {
+      console.error(`[island] ${element.dataset.island} cleanup failed`, error);
+    }
+  }
+}
+
+/**
+ * Bir alt ağaçtaki island'ları söker.
+ *
+ * Fragment takasında çağrılması zorunlu: `innerHTML` ile değiştirilen bir
+ * bölgenin island'ları DOM'dan çıkar ama `document`/`window` üzerine
+ * kurdukları dinleyiciler ve `setInterval`'ları yaşamaya devam eder. Birkaç
+ * takastan sonra aynı olay birden fazla kez işlenmeye başlar.
+ *
+ * Sökülen element yeniden bağlanabilir hâle gelir: `mounted` kaydı da
+ * temizlenir, böylece aynı düğüm tekrar DOM'a girerse `hydrate()` onu
+ * yeniden görür.
+ *
+ * @param {ParentNode} [root] Kökün kendisi de island olabilir.
+ */
+export function unmount(root = document) {
+  const element = /** @type {HTMLElement} */ (root);
+
+  if (element.dataset?.island) {
+    lazyObserver?.unobserve(element);
+    runCleanups(element);
+  }
+
+  for (const node of root.querySelectorAll?.("[data-island]") ?? []) {
+    const child = /** @type {HTMLElement} */ (node);
+    lazyObserver?.unobserve(child);
+    runCleanups(child);
   }
 }
 

package/src/client/swap.js

@@ -0,0 +1,188 @@
+/**
+ * Sunucudan gelen bir parçayı DOM'a takar.
+ *
+ * Dashboard'un can damarı bu: tablo sayfası, filtre sonucu, yeniden hesaplanan
+ * kart — hepsi sunucuda render edilip yerine konur, böylece işaretlemenin tek
+ * kaynağı sunucuda kalır ve istemci ikinci bir şablon taşımaz.
+ *
+ * Taşıma katmanından bağımsız. Verinin ne zaman değiştiğini nasıl öğrendiğin
+ * (SSE, WebSocket, aralıklı sorgu, kullanıcı tıklaması) uygulamanın kararı;
+ * burada yalnızca "şu parçayı tazele" adımı var.
+ *
+ * Sırası önemli olan üç iş yapıyor:
+ *   1. eski alt ağacın island'larını söker (yoksa dinleyici sızar),
+ *   2. içeriği değiştirir,
+ *   3. yeni alt ağacı hidre eder ve odağı kaybolmuşsa geri getirir.
+ */
+import { hydrate, unmount } from "./registry.js";
+
+/**
+ * @param {Element | string} target
+ * @returns {HTMLElement | null}
+ */
+function resolveTarget(target) {
+  if (typeof target === "string") {
+    return /** @type {HTMLElement | null} */ (document.querySelector(target));
+  }
+  return /** @type {HTMLElement} */ (target);
+}
+
+/**
+ * Odak takas edilen bölgenin içindeyse kaybolur ve klavye kullanıcısı
+ * sayfanın başına düşer. Yeni içerikte aynı `id`'li bir element varsa oraya,
+ * yoksa bölgenin kendisine dönüyoruz.
+ *
+ * @param {HTMLElement} element
+ * @param {string | null} previousId
+ */
+function restoreFocus(element, previousId) {
+  if (previousId) {
+    const next = element.querySelector(`#${CSS.escape(previousId)}`);
+    if (next instanceof HTMLElement) {
+      next.focus();
+      return;
+    }
+  }
+
+  if (!element.hasAttribute("tabindex")) {
+    element.setAttribute("tabindex", "-1");
+  }
+  element.focus({ preventScroll: true });
+}
+
+/**
+ * @typedef {object} SwapOptions
+ * @property {string} [method] Varsayılan `GET`.
+ * @property {BodyInit | null} [body]
+ * @property {Record<string, string>} [headers]
+ * @property {AbortSignal} [signal]
+ * @property {boolean} [history] `true` → adres çubuğu `url` ile güncellenir.
+ * @property {"replace" | "append"} [mode] Varsayılan `replace`.
+ */
+
+/**
+ * @param {Element | string} target Takas edilecek bölge.
+ * @param {string} url Parçayı döndüren uç.
+ * @param {SwapOptions} [options]
+ * @returns {Promise<boolean>} Başarılıysa `true`; hata durumunda mevcut
+ *   içerik korunur ve `false` döner.
+ */
+export async function swap(target, url, options = {}) {
+  const element = resolveTarget(target);
+  if (!element) {
+    console.warn(`[swap] target not found: ${String(target)}`);
+    return false;
+  }
+
+  const activeId =
+    document.activeElement instanceof HTMLElement &&
+    element.contains(document.activeElement)
+      ? document.activeElement.id || null
+      : null;
+
+  element.setAttribute("aria-busy", "true");
+
+  try {
+    const response = await fetch(url, {
+      method: options.method ?? "GET",
+      body: options.body ?? null,
+      headers: {
+        // Sunucu tam sayfa yerine parça döndürmeyi seçebilsin.
+        "X-Requested-With": "fragment",
+        ...(options.headers ?? {}),
+      },
+      // Oturum cookie'si olmadan kişiye özel parça gelmez.
+      credentials: "same-origin",
+      signal: options.signal,
+    });
+
+    // Sunucu yönlendirdiyse (ör. oturum düştü, login'e gidiliyor) parça değil
+    // sayfa beklenir; alt ağaca bir login formu takmak anlamsız olurdu.
+    if (response.redirected && response.url !== new URL(url, location.href).href) {
+      location.assign(response.url);
+      return false;
+    }
+
+    if (!response.ok) {
+      element.dispatchEvent(
+        new CustomEvent("jskelet:swap-error", {
+          bubbles: true,
+          detail: { url, status: response.status },
+        }),
+      );
+      return false;
+    }
+
+    const html = await response.text();
+
+    if (options.mode === "append") {
+      const holder = document.createElement("div");
+      holder.innerHTML = html;
+      const added = [...holder.childNodes];
+      element.append(...added);
+      for (const node of added) {
+        if (node instanceof HTMLElement) hydrate(node);
+      }
+    } else {
+      unmount(element);
+      element.innerHTML = html;
+      hydrate(element);
+      restoreFocus(element, activeId);
+    }
+
+    if (options.history) {
+      history.pushState({}, "", url);
+    }
+
+    element.dispatchEvent(
+      new CustomEvent("jskelet:swap", { bubbles: true, detail: { url } }),
+    );
+
+    return true;
+  } catch (error) {
+    // İptal edilen istek hata değil: kullanıcı hızlı yazıyor ya da sayfadan
+    // ayrıldı.
+    if (!(error instanceof DOMException && error.name === "AbortError")) {
+      console.error(`[swap] ${url}`, error);
+      element.dispatchEvent(
+        new CustomEvent("jskelet:swap-error", {
+          bubbles: true,
+          detail: { url, error },
+        }),
+      );
+    }
+    return false;
+  } finally {
+    element.removeAttribute("aria-busy");
+  }
+}
+
+/**
+ * `data-swap` taşıyan bağlantı ve butonları otomatik bağlar.
+ *
+ *   <a href="/_fragment/rows?page=2" data-swap="#rows" data-swap-history>…</a>
+ *
+ * Tek bir delege dinleyici: sonradan DOM'a giren bağlantılar da çalışır ve
+ * her takastan sonra yeniden bağlama gerekmez.
+ *
+ * @param {ParentNode} [root]
+ * @returns {() => void} Dinleyiciyi söken fonksiyon.
+ */
+export function startSwapLinks(root = document) {
+  /** @param {Event} event */
+  const onClick = (event) => {
+    const origin = /** @type {HTMLElement | null} */ (event.target);
+    const trigger = origin?.closest?.("[data-swap]");
+    if (!(trigger instanceof HTMLElement)) return;
+
+    const selector = trigger.dataset.swap;
+    const url = trigger.getAttribute("href") ?? trigger.dataset.swapUrl;
+    if (!selector || !url) return;
+
+    event.preventDefault();
+    void swap(selector, url, { history: "swapHistory" in trigger.dataset });
+  };
+
+  root.addEventListener("click", onClick);
+  return () => root.removeEventListener("click", onClick);
+}

package/src/config/defaults.js

@@ -55,6 +55,55 @@ export const DEFAULT_PREWARM = {
   concurrency: 4,
   /** İki tur arasında beklenen süre: upstream'e ani yük binmesin. */
   delayMs: 0,
+  /**
+   * Saniyedeki en fazla ısıtma isteği. 0 → sınırsız (yalnızca `concurrency`
+   * frenler). Upstream'i kota sınırının altında tutmanın en doğrudan yolu bu:
+   * paralellik ne kadar yükselse de tur bu hızın üstüne çıkmaz.
+   */
+  rps: 0,
+  /**
+   * Tekrar turundan önce beklenen süre. Rate limit pencereleri saniye
+   * mertebesinde; hemen tekrar denemek aynı 429'u almak demek.
+   */
+  retryDelayMs: 2000,
+  /**
+   * Liste `max`'tan uzunsa periyodik turlar kaldığı yerden devam eder.
+   * Böylece 10.000 yolluk bir site tek turda değil, turlar boyunca ısınır.
+   * `priority` eşleşen yollar her turda ısıtıldığı için rotasyon yalnızca
+   * kuyruğu dolaşır.
+   */
+  rotate: true,
+  /**
+   * Isıtma sırasını belirleyen desenler. String (`/haber/:slug`) ya da
+   * `RegExp` kabul eder; önce yazılan önce ısınır.
+   * @type {(string | RegExp)[]}
+   */
+  priority: [],
+};
+
+/**
+ * HTML önbelleğinin girdi sınırı. 500 girdi ortalama bir sayfa boyutunda
+ * yaklaşık 100-200 MB tutar; uzun kuyruklu siteler bunu yükseltmek yerine
+ * veri önbelleğine yaslanmalı (bkz. `DEFAULT_DATA_CACHE`).
+ */
+export const DEFAULT_HTML_CACHE_MAX_ENTRIES = 500;
+
+/**
+ * Upstream veri önbelleği.
+ *
+ * HTML önbelleğinden bilinçli olarak çok daha büyük: JSON, aynı sayfanın
+ * HTML'ine göre onlarca kat küçük. Uzun kuyruğu (on binlerce haber/etiket)
+ * HTML olarak tutmak imkânsız, verisini tutmak ise ucuz — ve API kotasını
+ * koruyan katman burası.
+ */
+export const DEFAULT_DATA_CACHE = {
+  maxEntries: 10000,
+  /**
+   * TTL dolduktan sonra girdinin kaç TTL boyunca daha kullanılabileceği.
+   * HTML'deki 1 katsayısından yüksek: bayat veri, eksik sayfadan iyidir ve
+   * upstream düştüğünde tek elde kalan şey budur.
+   */
+  staleFactor: 10,
 };
 
 /** Oturuma bağlı sayfalar ısıtılmaz; uygulama kendi listesini verebilir. */
@@ -86,6 +135,40 @@ export const DEFAULT_NAVIGATION = {
  */
 export const DEFAULT_NAVIGATION_EXCLUDE = ["/api/*", "/_fragment/*"];
 
+/**
+ * Güvenlik ayarları.
+ *
+ * `trustProxy` varsayılan olarak açık, çünkü JSkelet uygulamaları neredeyse
+ * her zaman bir ters proxy arkasında koşuyor ve doğru protokol/IP buna bağlı.
+ * Ama doğrudan internete açık bir sunucuda bu, istemcinin `X-Forwarded-For`
+ * uydurabilmesi demek — rate limit ve audit log girdiğinde kapatılmalı.
+ *
+ * `csrf.enabled` açık: framework gövdeyi kendisi ayrıştırdığı için bu yüzey
+ * onun sorumluluğu. Kontrol yalnızca **çapraz site olduğu belli** istekleri
+ * reddeder (`Origin` uyuşmuyor ya da `Sec-Fetch-Site: cross-site`); başlık
+ * hiç yoksa geçer, böylece webhook ve sunucudan sunucuya çağrılar bozulmaz.
+ *
+ * `csrf.token` kapalı: çift gönderim token'ı `Origin` göndermeyen eski
+ * tarayıcılar için ikinci katman ve formlara `csrfField()` eklenmesini
+ * gerektiriyor, yani açılması bilinçli bir karar olmalı.
+ */
+export const DEFAULT_SECURITY = {
+  trustProxy: true,
+  /** @type {string | null} */
+  cookieSecret: null,
+  csrf: {
+    enabled: true,
+    token: false,
+    /** Ek olarak kabul edilen origin'ler (ör. ayrı bir admin alan adı). */
+    allowedOrigins: /** @type {string[]} */ ([]),
+    /** Kontrolden muaf yollar — webhook uçları buraya yazılır. */
+    exclude: /** @type {string[]} */ ([]),
+    cookieName: "csrf_token",
+    fieldName: "_csrf",
+    headerName: "x-csrf-token",
+  },
+};
+
 /**
  * Markalama. Header adı ve dev overlay yolu tek yerden değişsin diye
  * config'ten okunur — fork eden proje kendi adını verebilir.