jskelet 0.1.1

package/src/client/dom.js

@@ -0,0 +1,95 @@
+/** Island'ların paylaştığı küçük DOM yardımcıları. */
+
+/**
+ * @param {ParentNode} root
+ * @param {string} selector
+ * @returns {HTMLElement | null}
+ */
+export function qs(root, selector) {
+  return /** @type {HTMLElement | null} */ (root.querySelector(selector));
+}
+
+/**
+ * @param {ParentNode} root
+ * @param {string} selector
+ * @returns {HTMLElement[]}
+ */
+export function qsa(root, selector) {
+  return /** @type {HTMLElement[]} */ ([...root.querySelectorAll(selector)]);
+}
+
+/**
+ * Otomatik temizlenebilir listener.
+ * @param {EventTarget} target
+ * @param {string} type
+ * @param {EventListenerOrEventListenerObject} handler
+ * @param {AddEventListenerOptions | boolean} [options]
+ * @returns {() => void}
+ */
+export function on(target, type, handler, options) {
+  target.addEventListener(type, handler, options);
+  return () => target.removeEventListener(type, handler, options);
+}
+
+/**
+ * `data-*` üzerinden delege edilmiş click.
+ * @param {HTMLElement} root
+ * @param {string} selector
+ * @param {(event: MouseEvent, target: HTMLElement) => void} handler
+ * @returns {() => void}
+ */
+export function onClick(root, selector, handler) {
+  return on(root, "click", (event) => {
+    const target = /** @type {HTMLElement} */ (event.target)?.closest(selector);
+    if (!target || !root.contains(target)) return;
+    handler(/** @type {MouseEvent} */ (event), /** @type {HTMLElement} */ (target));
+  });
+}
+
+/**
+ * @param {number} ms
+ * @param {(...args: any[]) => void} fn
+ * @returns {(...args: any[]) => void}
+ */
+export function debounce(ms, fn) {
+  let timer = null;
+  return (...args) => {
+    clearTimeout(timer);
+    timer = setTimeout(() => fn(...args), ms);
+  };
+}
+
+/**
+ * requestAnimationFrame ile birleştirilmiş çağrı.
+ * @param {() => void} fn
+ * @returns {() => void}
+ */
+export function raf(fn) {
+  let frame = 0;
+  return () => {
+    if (frame) return;
+    frame = requestAnimationFrame(() => {
+      frame = 0;
+      fn();
+    });
+  };
+}
+
+/**
+ * @param {HTMLElement} element
+ * @param {string} name
+ * @param {boolean} active
+ */
+export function toggleClass(element, name, active) {
+  element.classList.toggle(name, active);
+}
+
+/**
+ * Overlay portal hedefi: layout'ta `<div id="jskelet-overlays">` varsa
+ * modal/drawer içeriği oraya taşınır, yoksa `body`ye. Portal, `overflow`
+ * ya da `transform` taşıyan bir ata elementin `position: fixed` overlay'i
+ * kırpmasını engeller.
+ */
+export function getOverlayRoot() {
+  return document.getElementById("jskelet-overlays") ?? document.body;
+}

package/src/client/index.js

@@ -0,0 +1,26 @@
+/**
+ * JSkelet island runtime'ının tarayıcı tarafı API'si.
+ *
+ * `client/entries/main.js` içinde:
+ *
+ *   import { registerAll, start } from "jskelet/client";
+ *
+ *   registerAll({
+ *     counter: () => import("../islands/counter.js"),
+ *   });
+ *
+ *   start();
+ */
+export { register, registerAll, hydrate, observeDocument, start } from "./registry.js";
+export { createStore } from "./store.js";
+export {
+  debounce,
+  on,
+  onClick,
+  qs,
+  qsa,
+  raf,
+  toggleClass,
+  getOverlayRoot,
+} from "./dom.js";
+export { startSafeImages } from "./safe-image.js";

package/src/client/registry.js

@@ -0,0 +1,223 @@
+/**
+ * Island registry.
+ *
+ * Sunucu HTML'i tamdır; JS yalnızca davranış ekler. Bir element
+ * `data-island="ad"` taşıdığında ilgili modül dinamik import edilir ve
+ * `mount(element, props)` çağrılır.
+ *
+ * Hidrasyon **varsayılan olarak görünürlüğe bağlıdır**: her island bir
+ * IntersectionObserver'a verilir, ekranda olanlar zaten ilk gözlemde tetiklenir,
+ * ekran dışındakiler kaydırılana kadar hiç indirilmez. Ana sayfadaki grafik
+ * kütüphanesi gibi ağır modüller böylece ilk yükten tamamen çıkar.
+ *
+ * `data-island-eager` görünürlükten bağımsız, hemen bağlanmayı zorlar
+ * (header, çerez bandı gibi global davranışlar için).
+ *
+ * `data-island-idle` görünür olsa bile sayfa sakinleşene (load + boş zaman)
+ * kadar bekletir. İlk ekranda görünen ama kritik olmayan ağır modüller
+ * (ör. grafik kütüphanesi çeken mini grafik) LCP ile yarışmasın diye.
+ *
+ * `data-island-props` JSON ise parse edilip props olarak geçer.
+ */
+
+/** @typedef {(element: HTMLElement, props: object) => void | (() => void)} MountFn */
+
+/** @type {Map<string, () => Promise<{ mount: MountFn }>>} */
+const loaders = new Map();
+
+/** @type {WeakMap<HTMLElement, Set<string>>} */
+const mounted = new WeakMap();
+
+/**
+ * @param {string} name
+ * @param {() => Promise<{ mount: MountFn }>} loader
+ */
+export function register(name, loader) {
+  loaders.set(name, loader);
+}
+
+/** @param {Record<string, () => Promise<{ mount: MountFn }>>} entries */
+export function registerAll(entries) {
+  for (const [name, loader] of Object.entries(entries)) {
+    register(name, loader);
+  }
+}
+
+/**
+ * @param {HTMLElement} element
+ * @returns {object}
+ */
+function readProps(element) {
+  const raw = element.dataset.islandProps;
+  if (!raw) return {};
+
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    console.error(
+      `[island] ${element.dataset.island}: geçersiz data-island-props`,
+      error,
+    );
+    return {};
+  }
+}
+
+/**
+ * @param {HTMLElement} element
+ * @returns {boolean}
+ */
+function isMounted(element) {
+  const name = element.dataset.island;
+  if (!name) return true;
+  return mounted.get(element)?.has(name) ?? false;
+}
+
+/** @param {HTMLElement} element */
+function markMounted(element) {
+  const name = element.dataset.island;
+  if (!name) return;
+
+  let names = mounted.get(element);
+  if (!names) {
+    names = new Set();
+    mounted.set(element, names);
+  }
+  names.add(name);
+}
+
+/** @param {HTMLElement} element */
+async function mountIsland(element) {
+  const name = element.dataset.island;
+  if (!name || isMounted(element)) return;
+
+  const loader = loaders.get(name);
+  if (!loader) {
+    console.warn(`[island] kayıtlı değil: ${name}`);
+    return;
+  }
+
+  markMounted(element);
+
+  try {
+    const module = await loader();
+    module.mount(element, readProps(element));
+    element.dataset.islandReady = "true";
+  } catch (error) {
+    console.error(`[island] ${name} yüklenemedi`, error);
+  }
+}
+
+/** @type {IntersectionObserver | null} */
+let lazyObserver = null;
+
+function getLazyObserver() {
+  if (lazyObserver) return lazyObserver;
+
+  lazyObserver = new IntersectionObserver(
+    (entries) => {
+      for (const entry of entries) {
+        if (!entry.isIntersecting) continue;
+        lazyObserver.unobserve(entry.target);
+        mountWhenReady(/** @type {HTMLElement} */ (entry.target));
+      }
+    },
+    { rootMargin: "200px 0px" },
+  );
+
+  return lazyObserver;
+}
+
+/**
+ * Bağlama işini boş zamana kaydır: aynı anda görünen çok sayıda island'ın
+ * tek bir uzun task'a dönüşmesini engeller (TBT/INP).
+ *
+ * @param {() => void} fn
+ */
+function schedule(fn) {
+  if (typeof requestIdleCallback === "function") {
+    requestIdleCallback(fn, { timeout: 500 });
+    return;
+  }
+  setTimeout(fn, 0);
+}
+
+/**
+ * `load` tamamlanıp ana iş parçacığı boşalana kadar bekletir.
+ *
+ * @param {() => void} fn
+ */
+function afterLoad(fn) {
+  if (document.readyState === "complete") {
+    schedule(fn);
+    return;
+  }
+  window.addEventListener("load", () => schedule(fn), { once: true });
+}
+
+/**
+ * @param {HTMLElement} node
+ */
+function mountWhenReady(node) {
+  if ("islandIdle" in node.dataset) {
+    afterLoad(() => mountIsland(node));
+    return;
+  }
+  schedule(() => mountIsland(node));
+}
+
+/** @param {ParentNode} [root] */
+export function hydrate(root = document) {
+  /** @type {HTMLElement[]} */
+  const pending = [];
+
+  for (const element of root.querySelectorAll("[data-island]")) {
+    const node = /** @type {HTMLElement} */ (element);
+    if (!isMounted(node)) pending.push(node);
+  }
+
+  if (!pending.length) return;
+
+  // Ölçümler tek seferde okunur; araya yazma girmediği için tek reflow olur.
+  const boxed = pending.map((node) => node.getClientRects().length > 0);
+
+  pending.forEach((node, i) => {
+    // `hidden` bir drawer/dialog'un düzen kutusu yoktur ve IntersectionObserver
+    // onu asla bildirmez; bu yüzden gizli olanlar doğrudan bağlanır.
+    if ("islandEager" in node.dataset || !boxed[i]) {
+      mountIsland(node);
+      return;
+    }
+
+    getLazyObserver().observe(node);
+  });
+}
+
+/** Sonradan DOM'a eklenen island'ları da yakalar (infinite scroll, portal). */
+export function observeDocument() {
+  const observer = new MutationObserver((mutations) => {
+    for (const mutation of mutations) {
+      for (const node of mutation.addedNodes) {
+        if (node.nodeType !== Node.ELEMENT_NODE) continue;
+        const element = /** @type {HTMLElement} */ (node);
+        if (element.dataset?.island) hydrate(element.parentNode ?? document);
+        if (element.querySelector?.("[data-island]")) hydrate(element);
+      }
+    }
+  });
+
+  observer.observe(document.body, { childList: true, subtree: true });
+  return observer;
+}
+
+export function start() {
+  const run = () => {
+    hydrate();
+    observeDocument();
+  };
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", run, { once: true });
+  } else {
+    run();
+  }
+}

package/src/client/safe-image.js

@@ -0,0 +1,91 @@
+/**
+ * Yüklenemeyen görseller için tek bir belge dinleyicisi.
+ *
+ * Bu iş bilinçli olarak **island değil**. Görsel ağırlıklı bir sayfada 80+
+ * `<img>` olabiliyor ve her birine ayrı island bağlamak (gözlemci + dinamik
+ * import + mount) sırf hata ihtimali için ciddi bir hidrasyon yükü. `error`
+ * olayı kabarmaz ama yakalama fazında görülebilir, bu yüzden tek dinleyici
+ * hepsini karşılar ve sonradan DOM'a eklenen görseller de kendiliğinden
+ * kapsanır.
+ *
+ * Kullanım: görsele `data-safe-image` ekleyin. Kendi hata görünümünüzü
+ * vermek için görseli `data-safe-image-host` taşıyan bir sarmalayıcıya alın
+ * ve içine `<template data-safe-image-fallback>` koyun — framework hiçbir
+ * stil dayatmaz, yalnızca değiştirme işini yapar.
+ */
+
+const MARKER = "data-safe-image";
+
+/**
+ * Şablon verilmemişse yerine geçen minimal blok: görselin ölçülerini korur
+ * ki değiştirme sırasında düzen kaymasın (CLS).
+ *
+ * @param {HTMLImageElement} img
+ * @returns {HTMLElement}
+ */
+function buildFallback(img) {
+  const element = document.createElement("div");
+  const label = img.dataset.fallbackLabel || img.getAttribute("alt") || "";
+
+  element.className = [img.className, img.dataset.fallbackClass ?? ""]
+    .filter(Boolean)
+    .join(" ");
+  element.dataset.safeImageFallback = "";
+
+  if (img.width && img.height) {
+    element.style.width = `${img.width}px`;
+    element.style.height = `${img.height}px`;
+  }
+
+  element.setAttribute("role", "img");
+  if (label) element.setAttribute("aria-label", label);
+
+  return element;
+}
+
+/**
+ * @param {HTMLImageElement} img
+ */
+function replace(img) {
+  if (!img.isConnected) return;
+
+  const host = img.closest("[data-safe-image-host]");
+  const template = host?.querySelector("template[data-safe-image-fallback]");
+
+  if (host && template) {
+    host.replaceWith(template.content.cloneNode(true));
+    return;
+  }
+
+  img.replaceWith(buildFallback(img));
+}
+
+/**
+ * @returns {void}
+ */
+export function startSafeImages() {
+  document.addEventListener(
+    "error",
+    (event) => {
+      const target = /** @type {HTMLElement} */ (event.target);
+      if (target?.tagName !== "IMG" || !target.hasAttribute(MARKER)) return;
+      replace(/** @type {HTMLImageElement} */ (target));
+    },
+    // `error` kabarmaz; yalnızca yakalama fazında görülür.
+    true,
+  );
+
+  // JS çalışmadan önce başarısız olmuş görseller olay üretmez; bir kez taranır.
+  const sweep = () => {
+    for (const img of document.querySelectorAll(`img[${MARKER}]`)) {
+      const image = /** @type {HTMLImageElement} */ (img);
+      if (image.complete && image.naturalWidth === 0) replace(image);
+    }
+  };
+
+  if (typeof requestIdleCallback === "function") {
+    requestIdleCallback(sweep, { timeout: 2000 });
+  } else {
+    setTimeout(sweep, 0);
+  }
+}

package/src/client/store.js

@@ -0,0 +1,36 @@
+/**
+ * React Context yerine kullanılan minimal pub/sub store.
+ * `useSyncExternalStore` köprüsünün yerini alır: doğrudan `subscribe`.
+ */
+
+/**
+ * @param {T} initial
+ * @returns {{
+ *   get: () => T,
+ *   set: (next: T | ((prev: T) => T)) => void,
+ *   subscribe: (listener: (value: T) => void) => () => void,
+ * }}
+ * @template T
+ */
+export function createStore(initial) {
+  let value = initial;
+  /** @type {Set<(value: T) => void>} */
+  const listeners = new Set();
+
+  return {
+    get: () => value,
+
+    set(next) {
+      const resolved =
+        typeof next === "function" ? /** @type {Function} */ (next)(value) : next;
+      if (resolved === value) return;
+      value = resolved;
+      for (const listener of listeners) listener(value);
+    },
+
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}

package/src/config/defaults.js

@@ -0,0 +1,102 @@
+/**
+ * Framework varsayılanları.
+ *
+ * Buradaki hiçbir değer domain bilgisi taşımaz: uygulamaya özel her şey
+ * `jskelet.config.mjs` üzerinden gelir. Varsayılanların ayrı dosyada olması,
+ * "framework ne yapıyor, uygulama ne ekliyor" ayrımını okunur tutar.
+ */
+
+/** Uzun süre cache'lenecek hash'li çıktı dizini. */
+export const IMMUTABLE_CACHE = "public, max-age=31536000, immutable";
+
+/**
+ * Proje kökündeki dizin adları. `jskelet.config.mjs` içinde `paths` ile
+ * tek tek ezilebilir.
+ */
+export const DEFAULT_DIRS = {
+  /** EJS layout + sayfalar + bileşenler. */
+  views: "views",
+  /** Statik dosyalar; build çıktısı da buraya yazılır. */
+  public: "public",
+  /** Island runtime ve entry'ler. */
+  client: "client",
+  /** Route modülleri. */
+  routes: "routes",
+  /** Tailwind/PostCSS giriş dosyası. */
+  styles: "styles/globals.css",
+  /** Build ara çıktıları (manifest, metafile, images). */
+  generated: ".jskelet",
+};
+
+/**
+ * Uzantı ve önek bazlı statik dosya tespiti. Bu listeye uyan yollara
+ * `IMMUTABLE_CACHE` yazılır.
+ */
+export const DEFAULT_STATIC = {
+  extensions: [".svg", ".png", ".webp", ".avif", ".ico", ".woff2"],
+  prefixes: ["/assets/", "/fonts/"],
+};
+
+/** Dev gate'in hiçbir koşulda kapatmadığı yollar. */
+export const DEFAULT_DEV_GATE_BYPASS = [
+  "/api/healthcheck",
+  "/robots.txt",
+  "/sitemap.xml",
+  "/site.webmanifest",
+  "/favicon.ico",
+];
+
+/** Prewarm ayarlarının kod içi varsayılanları. */
+export const DEFAULT_PREWARM = {
+  enabled: true,
+  max: 400,
+  intervalSeconds: 0,
+  /** Paralel ısıtma isteği; dev'de sunucu tek süreç olduğu için düşürülür. */
+  concurrency: 4,
+  /** İki tur arasında beklenen süre: upstream'e ani yük binmesin. */
+  delayMs: 0,
+};
+
+/** Oturuma bağlı sayfalar ısıtılmaz; uygulama kendi listesini verebilir. */
+export const DEFAULT_PREWARM_SKIP = ["/api/", "/_fragment/", "/__jskelet/"];
+
+/**
+ * Site içi gezinme ipuçları (Speculation Rules + view transition).
+ *
+ * Varsayılan bilinçli olarak ölçülü: `prefetch` açık, çünkü yalnızca belgeyi
+ * indirir ve sayfanın JS'ini çalıştırmaz — yanlış tahmin edilse bile tek
+ * maliyeti bir istektir. `prerender` kapalı, çünkü hedef sayfanın script'leri
+ * gerçekten çalışır; ölçüm kodunu `prerenderingchange` olayına bağlamayan bir
+ * uygulamada ziyaret sayıları şişer. `viewTransition` kapalı, çünkü uygulamanın
+ * kendi geçiş animasyonlarıyla çakışabilir.
+ */
+export const DEFAULT_NAVIGATION = {
+  /** `false` ya da eagerness: "conservative" | "moderate" | "eager". */
+  prefetch: /** @type {false | "conservative" | "moderate" | "eager"} */ ("moderate"),
+  /** @type {false | "conservative" | "moderate" | "eager"} */
+  prerender: false,
+  /** `@view-transition { navigation: auto }` basılsın mı. */
+  viewTransition: false,
+};
+
+/**
+ * Hiçbir koşulda önden getirilmeyecek yollar. Yan etkisi olan ya da gezinme
+ * hedefi olmayan uçların spekülatif istekle tetiklenmesi gerçek bir hata
+ * kaynağı; uygulama kendi listesini `navigation.exclude` ile ekler.
+ */
+export const DEFAULT_NAVIGATION_EXCLUDE = ["/api/*", "/_fragment/*"];
+
+/**
+ * Markalama. Header adı ve dev overlay yolu tek yerden değişsin diye
+ * config'ten okunur — fork eden proje kendi adını verebilir.
+ */
+export const DEFAULT_BRAND = {
+  name: "JSkelet",
+  /** `<html lang>`; uygulama kendi dilini config'te bildirir. */
+  lang: "en",
+  poweredBy: "JSkelet",
+  cacheHeader: "X-JSkelet-Cache",
+  devBasePath: "/__jskelet/dev",
+  prewarmUserAgent: "jskelet-prewarm",
+  devTokenCookie: "dev_token",
+};