jskelet 0.2.5 → 0.3.0

package/src/client/dom.js

@@ -1,95 +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;
-}
+/** 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/form.js

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

@@ -1,35 +1,35 @@
-/**
- * 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,
-  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,
-  on,
-  onClick,
-  qs,
-  qsa,
-  raf,
-  toggleClass,
-  getOverlayRoot,
-} from "./dom.js";
-export { startSafeImages } from "./safe-image.js";
+/**
+ * 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,
+  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,
+  on,
+  onClick,
+  qs,
+  qsa,
+  raf,
+  toggleClass,
+  getOverlayRoot,
+} from "./dom.js";
+export { startSafeImages } from "./safe-image.js";