jskelet 0.2.4 → 0.2.5

package/src/client/safe-image.js

@@ -1,91 +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);
-  }
-}
+/**
+ * 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

@@ -1,36 +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);
-    },
-  };
-}
+/**
+ * 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/client/swap.js

@@ -1,188 +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);
-}
+/**
+ * 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);
+}