@zvndev/darkmown 1.1.0 → 1.2.0

package/src/api-runner.js

@@ -0,0 +1,219 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * The local-dev serverless API runner. Gives `darkmown dev` the SAME `/api/*`
+ * behavior a project gets on Vercel / Cloudflare in production, so a `:fetch
+ * /api/x` or a form POST works identically before you ever deploy.
+ *
+ * The convention is deliberately plain: a backend endpoint is a plain-JS file
+ * under the project's top-level `api/` directory that default-exports a
+ * Web-standard handler `(request: Request, context) => Response | Promise<Response>`.
+ * That is the exact signature Vercel Edge, Cloudflare Pages, Netlify Edge and
+ * Deno already run — Darkmown owns no server, it just emulates the host locally.
+ *
+ * File → route, rooted at the `/api` URL prefix (matching Vercel's `api/`):
+ *   api/echo.js          → /api/echo
+ *   api/users/index.js   → /api/users
+ *   api/users/list.js    → /api/users/list
+ *   api/users/[id].js    → /api/users/:id   (context.params.id)
+ *
+ * Nothing here mutates module state: routes are discovered per call so a newly
+ * added function is picked up without a restart, and each handler is imported
+ * with an mtime cache-buster so edits hot-reload.
+ */
+
+/**
+ * A discovered API route.
+ * @typedef {object} ApiRoute
+ * @property {string} file Absolute path to the handler module.
+ * @property {string[]} segments Route segments after `/api`; a dynamic segment
+ *   is stored as `[name]` (e.g. `["users", "[id]"]`).
+ */
+
+/**
+ * Walk `apiDir` and return every `.js`/`.mjs` handler as an {@link ApiRoute}.
+ * Files/dirs whose name starts with `.`, `_`, or `-` are treated as private
+ * (helpers, fixtures) and never routed, matching the router's hidden-path rule.
+ * Returns `[]` when `apiDir` does not exist.
+ * @param {string} apiDir Absolute path to the project's `api/` directory.
+ * @returns {ApiRoute[]}
+ */
+export function discoverApiRoutes(apiDir) {
+  if (!fs.existsSync(apiDir)) return [];
+  /** @type {ApiRoute[]} */
+  const routes = [];
+  /** @param {string} dir @param {string[]} trail */
+  const walk = (dir, trail) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (/^[._-]/.test(entry.name)) continue; // private: helpers, fixtures, drafts
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(abs, [...trail, entry.name]);
+        continue;
+      }
+      const ext = path.extname(entry.name);
+      if (ext !== ".js" && ext !== ".mjs") continue;
+      const base = entry.name.slice(0, -ext.length);
+      // `index` collapses onto its directory: api/users/index.js → /api/users.
+      const segments = base === "index" ? trail : [...trail, base];
+      routes.push({ file: abs, segments });
+    }
+  };
+  walk(apiDir, []);
+  // Static routes before dynamic ones so an exact file always beats a `[param]`.
+  return routes.sort((a, b) => dynamicCount(a.segments) - dynamicCount(b.segments));
+}
+
+/**
+ * @param {string[]} segments
+ * @returns {number} How many segments are dynamic (`[param]`).
+ */
+function dynamicCount(segments) {
+  return segments.filter((s) => s.startsWith("[")).length;
+}
+
+/**
+ * Match a request pathname against discovered routes. The pathname is expected
+ * to start with `/api`; anything else returns `null` (caller serves static).
+ * @param {ApiRoute[]} routes
+ * @param {string} pathname Request pathname (no query string).
+ * @returns {{ file: string, params: Record<string, string> } | null}
+ */
+export function matchApiRoute(routes, pathname) {
+  if (pathname !== "/api" && !pathname.startsWith("/api/")) return null;
+  const parts = pathname.split("/").filter(Boolean).slice(1); // drop leading "api"
+  for (const route of routes) {
+    if (route.segments.length !== parts.length) continue;
+    /** @type {Record<string, string>} */
+    const params = {};
+    let ok = true;
+    for (let i = 0; i < parts.length; i++) {
+      const seg = route.segments[i];
+      if (seg.startsWith("[") && seg.endsWith("]")) {
+        params[seg.slice(1, -1)] = decodeURIComponent(parts[i]);
+      } else if (seg !== parts[i]) {
+        ok = false;
+        break;
+      }
+    }
+    if (ok) return { file: route.file, params };
+  }
+  return null;
+}
+
+/**
+ * Build a Web-standard `Request` from a Node `IncomingMessage`. The body (for
+ * methods that carry one) is buffered fully — dev endpoints are small and this
+ * avoids the `duplex: "half"` streaming dance.
+ * @param {import("node:http").IncomingMessage} req
+ * @returns {Promise<Request>}
+ */
+export async function nodeRequestToWeb(req) {
+  const host = req.headers.host || "localhost";
+  const url = new URL(req.url || "/", `http://${host}`);
+  /** @type {RequestInit} */
+  const init = { method: req.method, headers: /** @type {HeadersInit} */ (req.headers) };
+  const method = (req.method || "GET").toUpperCase();
+  if (method !== "GET" && method !== "HEAD") {
+    // A Node Buffer is a valid BodyInit at runtime; the DOM lib's narrower type
+    // doesn't list it, so widen at the assignment.
+    init.body = /** @type {BodyInit} */ (/** @type {unknown} */ (await readBody(req)));
+  }
+  return new Request(url, init);
+}
+
+/**
+ * @param {import("node:http").IncomingMessage} req
+ * @returns {Promise<Buffer>}
+ */
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    /** @type {Buffer[]} */
+    const chunks = [];
+    req.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+    req.on("end", () => resolve(Buffer.concat(chunks)));
+    req.on("error", reject);
+  });
+}
+
+/**
+ * Write a Web-standard `Response` back onto a Node `ServerResponse`.
+ * @param {Response} response
+ * @param {import("node:http").ServerResponse} res
+ * @returns {Promise<void>}
+ */
+export async function writeWebResponse(response, res) {
+  /** @type {Record<string, string | string[]>} */
+  const headers = {};
+  // `Headers.forEach` folds multiple Set-Cookie into one comma-joined value, which
+  // corrupts cookies. Collect every other header here and emit Set-Cookie as a
+  // discrete array (Node writeHead emits one header line per array element) so the
+  // dev runner preserves the multi-cookie behavior the production hosts give.
+  response.headers.forEach((value, key) => {
+    if (key.toLowerCase() === "set-cookie") return;
+    headers[key] = value;
+  });
+  const cookies =
+    typeof response.headers.getSetCookie === "function" ? response.headers.getSetCookie() : [];
+  if (cookies.length > 0) headers["set-cookie"] = cookies;
+  res.writeHead(response.status, headers);
+  const buffer = Buffer.from(await response.arrayBuffer());
+  res.end(buffer);
+}
+
+/**
+ * Handle a request as an API call if its pathname matches a function under
+ * `apiDir`. Returns `true` when it owned the request (a route matched, whether
+ * the handler succeeded or threw), `false` when nothing matched so the caller
+ * should fall through to static serving.
+ *
+ * @param {object} io
+ * @param {string} io.apiDir Absolute path to the project's `api/` directory.
+ * @param {import("node:http").IncomingMessage} io.req
+ * @param {import("node:http").ServerResponse} io.res
+ * @returns {Promise<boolean>}
+ */
+export async function handleApiRequest({ apiDir, req, res }) {
+  const pathname = new URL(req.url || "/", "http://localhost").pathname;
+  const match = matchApiRoute(discoverApiRoutes(apiDir), pathname);
+  if (!match) return false;
+
+  try {
+    const handler = await importHandler(match.file);
+    const request = await nodeRequestToWeb(req);
+    const context = { params: match.params, env: process.env };
+    const response = await handler(request, context);
+    if (!(response instanceof Response)) {
+      throw new TypeError(
+        `api/${path.relative(apiDir, match.file)} must return a Response (got ${typeof response}). ` +
+          "Use: return Response.json({ ... })"
+      );
+    }
+    await writeWebResponse(response, res);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    res.writeHead(500, { "content-type": "application/json" });
+    res.end(JSON.stringify({ ok: false, error: message }));
+  }
+  return true;
+}
+
+/**
+ * Import a handler module fresh (mtime cache-buster) and return its default
+ * export, validating it is callable.
+ * @param {string} file Absolute path to the handler module.
+ * @returns {Promise<(request: Request, context: { params: Record<string, string>, env: NodeJS.ProcessEnv }) => Response | Promise<Response>>}
+ */
+async function importHandler(file) {
+  const mtime = fs.statSync(file).mtimeMs;
+  const module = await import(`${pathToFileURL(file).href}?v=${mtime}`);
+  const handler = module.default;
+  if (typeof handler !== "function") {
+    throw new TypeError(
+      `${path.basename(file)} must \`export default\` a function (request) => Response.`
+    );
+  }
+  return handler;
+}

package/src/behaviors/carousel.js

@@ -0,0 +1,153 @@
+// Behavior: a lightweight, accessible carousel.
+//
+// Native CSS scroll-snap (from the page skin) does the layout + touch swiping; this
+// module adds prev/next buttons, dot navigation, active-state syncing, optional
+// autoplay (`data-wd-carousel-autoplay="3000"`), and mouse drag-to-scroll. It needs
+// NO reactive runtime — emitted only on pages that use `:carousel`, as a standalone
+// `/__wd/behaviors/carousel.js` module.
+
+for (const root of document.querySelectorAll("[data-wd-carousel]")) {
+  initCarousel(/** @type {HTMLElement} */ (root));
+}
+
+/**
+ * @param {HTMLElement} root The `:carousel` region.
+ * @returns {void}
+ */
+function initCarousel(root) {
+  const found = root.querySelector("[data-wd-carousel-track]");
+  if (!found) return;
+  const track = /** @type {HTMLElement} */ (found);
+  const slides = /** @type {HTMLElement[]} */ ([...track.children]);
+  if (slides.length === 0) return;
+
+  // Honor the OS "reduce motion" setting: jump instead of smooth-scroll, and
+  // never auto-advance (motion the user didn't initiate).
+  const reduceMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+  root.setAttribute("role", "region");
+  root.setAttribute("aria-roledescription", "carousel");
+
+  const prev = controlButton("‹", "Previous slide", "wd-carousel-prev");
+  const next = controlButton("›", "Next slide", "wd-carousel-next");
+  prev.addEventListener("click", () => go(currentIndex() - 1));
+  next.addEventListener("click", () => go(currentIndex() + 1));
+
+  // Plain buttons (not an ARIA tablist — there are no tabpanels to wire to);
+  // the active dot is marked with aria-current="true".
+  const dots = document.createElement("div");
+  dots.className = "wd-carousel-dots";
+  dots.setAttribute("role", "group");
+  dots.setAttribute("aria-label", "Choose slide to display");
+  const dotButtons = slides.map((_, i) => {
+    const dot = controlButton("", `Go to slide ${i + 1}`, "wd-carousel-dot");
+    dot.addEventListener("click", () => go(i));
+    dots.appendChild(dot);
+    return dot;
+  });
+
+  root.append(prev, next, dots);
+
+  /** @returns {number} Index of the slide nearest the track's scroll center. */
+  function currentIndex() {
+    const mid = track.scrollLeft + track.clientWidth / 2;
+    let best = 0;
+    let bestDist = Number.POSITIVE_INFINITY;
+    slides.forEach((slide, i) => {
+      const center = slide.offsetLeft + slide.clientWidth / 2;
+      const dist = Math.abs(center - mid);
+      if (dist < bestDist) {
+        bestDist = dist;
+        best = i;
+      }
+    });
+    return best;
+  }
+
+  /** @param {number} i @returns {void} */
+  function go(i) {
+    const clamped = Math.max(0, Math.min(slides.length - 1, i));
+    slides[clamped].scrollIntoView({
+      behavior: reduceMotion ? "auto" : "smooth",
+      inline: "start",
+      block: "nearest"
+    });
+  }
+
+  function sync() {
+    const i = currentIndex();
+    dotButtons.forEach((dot, n) => {
+      if (n === i) dot.setAttribute("aria-current", "true");
+      else dot.removeAttribute("aria-current");
+    });
+    prev.disabled = i === 0;
+    next.disabled = i === slides.length - 1;
+  }
+  track.addEventListener("scroll", () => requestAnimationFrame(sync), { passive: true });
+  sync();
+
+  const interval = Number(root.getAttribute("data-wd-carousel-autoplay") || 0);
+  if (interval > 0 && !reduceMotion) {
+    /** @type {ReturnType<typeof setInterval> | null} */
+    let timer = null;
+    const advance = () => go(currentIndex() >= slides.length - 1 ? 0 : currentIndex() + 1);
+    // start/stop are idempotent so stacked pointerleave/visibility events can't
+    // spin up duplicate timers.
+    const start = () => {
+      if (timer === null) timer = setInterval(advance, interval);
+    };
+    const stop = () => {
+      if (timer !== null) {
+        clearInterval(timer);
+        timer = null;
+      }
+    };
+    start();
+    root.addEventListener("pointerenter", stop);
+    root.addEventListener("pointerleave", start);
+    document.addEventListener("visibilitychange", () => {
+      if (document.hidden) stop();
+      else start();
+    });
+  }
+
+  // Mouse drag-to-scroll; touch already swipes natively via scroll-snap.
+  let dragging = false;
+  let startX = 0;
+  let startScroll = 0;
+  track.addEventListener("pointerdown", (event) => {
+    if (event.pointerType === "touch") return;
+    dragging = true;
+    startX = event.clientX;
+    startScroll = track.scrollLeft;
+    try {
+      track.setPointerCapture(event.pointerId);
+    } catch {
+      /* not capturable */
+    }
+  });
+  track.addEventListener("pointermove", (event) => {
+    if (!dragging) return;
+    track.scrollLeft = startScroll - (event.clientX - startX);
+  });
+  const release = () => {
+    dragging = false;
+  };
+  track.addEventListener("pointerup", release);
+  track.addEventListener("pointercancel", release);
+}
+
+/**
+ * @param {string} label
+ * @param {string} aria
+ * @param {string} className
+ * @returns {HTMLButtonElement}
+ */
+function controlButton(label, aria, className) {
+  const button = document.createElement("button");
+  button.type = "button";
+  button.className = className;
+  button.textContent = label;
+  button.setAttribute("aria-label", aria);
+  return button;
+}

package/src/behaviors/sortable.js

@@ -0,0 +1,175 @@
+// Behavior: drag-to-reorder for a `@loop … into … sortable` region.
+//
+// Pointer Events (mouse + touch) reorder the rows live for feedback; on drop the
+// underlying :state/:store list is rewritten through the public `window.wd` API,
+// so the keyed-loop reconciler repaints. Keyboard users reorder a focused row with
+// Arrow Up/Down, with a polite live-region announcement. Pay-for-what-you-use:
+// emitted only on pages that use `sortable`, as a standalone module.
+//
+// The compiler forbids where/sort/reverse/offset/limit on a sortable loop, so the
+// visible row order always equals the array order: DOM indices map 1:1 to the list.
+
+const wd = /** @type {any} */ (window).wd;
+let helpSeq = 0;
+if (wd) {
+  for (const container of document.querySelectorAll("[data-wd-sortable]")) {
+    initSortable(/** @type {HTMLElement} */ (container));
+  }
+}
+
+/**
+ * @param {HTMLElement} container The `data-wd-loop` region carrying data-wd-sortable.
+ * @returns {void}
+ */
+function initSortable(container) {
+  const key = container.getAttribute("data-wd-sortable") || "";
+  const out = /** @type {HTMLElement} */ (
+    container.querySelector("[data-wd-loop-out]") || container
+  );
+  const usesHandles = Boolean(out.querySelector("[data-wd-drag-handle]"));
+
+  // Off-screen helpers: a shared instructions node (referenced via aria-describedby)
+  // and a polite live region that announces the new position after a reorder.
+  const help = offscreen("Press Arrow Up or Arrow Down to reorder this item.");
+  help.id = `wd-sortable-help-${++helpSeq}`;
+  const live = offscreen("");
+  live.setAttribute("aria-live", "polite");
+  container.append(help, live);
+
+  /** @type {HTMLElement | null} */
+  let dragRow = null;
+  let startIndex = -1;
+
+  /** @returns {HTMLElement[]} Row elements (keyed nodes) in current DOM order. */
+  const rows = () =>
+    /** @type {HTMLElement[]} */ (
+      [...out.children].filter((c) => c.hasAttribute("data-wd-loop-key"))
+    );
+
+  // The keyed node is sometimes a `data-wd-loop-piece` wrapper the compiler adds
+  // around a non-<li> row template; the author's styled element is then its child.
+  // Visual feedback (dragging state), focus, and a11y must land on THAT element.
+  /** @param {HTMLElement} row @returns {HTMLElement} */
+  const visual = (row) =>
+    row.hasAttribute("data-wd-loop-piece")
+      ? /** @type {HTMLElement} */ (row.firstElementChild || row)
+      : row;
+  /** @param {HTMLElement} row @returns {HTMLElement} */
+  const grip = (row) =>
+    /** @type {HTMLElement} */ (visual(row).querySelector("[data-wd-drag-handle]") || visual(row));
+
+  // Keep rows focusable + announced for assistive tech across every re-render, and
+  // disable touch panning on the grip so a touch-drag reorders instead of scrolling.
+  const decorate = () => {
+    out.setAttribute("role", "list");
+    const list = rows();
+    list.forEach((row, i) => {
+      const v = visual(row);
+      const g = grip(row);
+      v.setAttribute("role", "listitem");
+      v.setAttribute("aria-roledescription", "sortable item");
+      g.setAttribute("tabindex", "0");
+      g.setAttribute("aria-keyshortcuts", "ArrowUp ArrowDown");
+      g.setAttribute("aria-describedby", help.id);
+      g.setAttribute("aria-posinset", String(i + 1));
+      g.setAttribute("aria-setsize", String(list.length));
+      g.style.touchAction = "none";
+    });
+  };
+  wd.subscribe(key, decorate);
+
+  out.addEventListener("pointerdown", (event) => {
+    const target = /** @type {Element} */ (event.target);
+    if (usesHandles && !target.closest("[data-wd-drag-handle]")) return;
+    const row = /** @type {HTMLElement | null} */ (target.closest("[data-wd-loop-key]"));
+    if (!row || !out.contains(row)) return;
+    dragRow = row;
+    startIndex = rows().indexOf(row);
+    visual(row).setAttribute("data-wd-dragging", "");
+    try {
+      row.setPointerCapture(event.pointerId);
+    } catch {
+      /* element not capturable — drag still works via document hit-testing */
+    }
+    event.preventDefault();
+  });
+
+  out.addEventListener("pointermove", (event) => {
+    if (!dragRow) return;
+    const over = rowFromPoint(event.clientX, event.clientY);
+    if (!over || over === dragRow) return;
+    const list = rows();
+    if (list.indexOf(dragRow) < list.indexOf(over)) over.after(dragRow);
+    else over.before(dragRow);
+  });
+
+  const drop = () => {
+    if (!dragRow) return;
+    visual(dragRow).removeAttribute("data-wd-dragging");
+    const endIndex = rows().indexOf(dragRow);
+    dragRow = null;
+    if (endIndex !== -1 && endIndex !== startIndex) reorder(startIndex, endIndex);
+  };
+  out.addEventListener("pointerup", drop);
+  out.addEventListener("pointercancel", drop);
+
+  out.addEventListener("keydown", (event) => {
+    if (event.key !== "ArrowUp" && event.key !== "ArrowDown") return;
+    const row = /** @type {HTMLElement | null} */ (
+      /** @type {Element} */ (event.target).closest("[data-wd-loop-key]")
+    );
+    if (!row) return;
+    const list = rows();
+    const from = list.indexOf(row);
+    const to = event.key === "ArrowUp" ? from - 1 : from + 1;
+    if (to < 0 || to >= list.length) return;
+    event.preventDefault();
+    reorder(from, to);
+    // Re-focus the moved row's grip after the reconcile re-render, and announce it.
+    requestAnimationFrame(() => {
+      const moved = rows()[to];
+      if (moved) {
+        grip(moved).focus();
+        live.textContent = `Moved to position ${to + 1} of ${rows().length}.`;
+      }
+    });
+  });
+
+  /**
+   * @param {number} x
+   * @param {number} y
+   * @returns {HTMLElement | null}
+   */
+  function rowFromPoint(x, y) {
+    const el = document.elementFromPoint(x, y);
+    return el ? /** @type {HTMLElement | null} */ (el.closest("[data-wd-loop-key]")) : null;
+  }
+
+  /**
+   * Move the underlying list item from `from` to `to` and let the runtime repaint.
+   * @param {number} from
+   * @param {number} to
+   * @returns {void}
+   */
+  function reorder(from, to) {
+    const list = wd.get(key);
+    if (!Array.isArray(list) || from < 0 || from >= list.length) return;
+    const next = list.slice();
+    const [moved] = next.splice(from, 1);
+    next.splice(to, 0, moved);
+    wd.set(key, next);
+  }
+}
+
+/**
+ * A visually-hidden element (kept in the a11y tree) for instructions / live region.
+ * @param {string} text
+ * @returns {HTMLElement}
+ */
+function offscreen(text) {
+  const node = document.createElement("div");
+  node.textContent = text;
+  node.style.cssText =
+    "position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap;border:0";
+  return node;
+}