npm - smaoog - Versions diffs - 0.0.1 - Mend

smaoog 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (32) hide show

package/LICENSE +21 -0
package/README.md +102 -0
package/package.json +50 -0
package/src/assets.js +118 -0
package/src/build.js +216 -0
package/src/cli.js +58 -0
package/src/client/index.d.ts +6 -0
package/src/client/index.js +12 -0
package/src/client/navigation.js +209 -0
package/src/client/runtime.js +47 -0
package/src/client/store.js +31 -0
package/src/conventions.js +47 -0
package/src/dev.js +84 -0
package/src/dispatch.js +75 -0
package/src/errors.js +11 -0
package/src/form.js +121 -0
package/src/index.d.ts +120 -0
package/src/index.js +95 -0
package/src/link.js +22 -0
package/src/meta.js +87 -0
package/src/protocol.js +14 -0
package/src/render.js +55 -0
package/src/request.js +133 -0
package/src/response.js +256 -0
package/src/router.js +497 -0
package/src/routes.js +175 -0
package/src/serialize.js +17 -0
package/src/server-only.js +122 -0
package/src/server.js +42 -0
package/src/start.js +60 -0
package/src/tailwind.js +20 -0
package/src/vite.js +69 -0

package/src/client/navigation.js ADDED Viewed

@@ -0,0 +1,209 @@
+import { HEAD_MARKER, metaToTags } from "../meta.js";
+// The endpoint that returns navigation payloads (see router.js).
+const NAV_ENDPOINT = "/_smaoog/nav";
+// Installed by hydrate(): the route store to swap pages through, and the module
+// loader used to import page modules. Until then (and during SSR) navigation
+// falls back to a full page load.
+let store = null;
+let loadModule = null;
+// Wire navigation to the hydrated app. Called once, from hydrate().
+export function installNavigation({ store: routeStore, load }) {
+  store = routeStore;
+  loadModule = load;
+  if (typeof window !== "undefined") {
+    // Back/forward: re-render the destination without pushing a new entry. The
+    // browser has already moved the URL (hash included), so we pass it through.
+    window.addEventListener("popstate", () => {
+      const { pathname, search, hash } = window.location;
+      void navigate(pathname + search + hash, { history: "none" });
+    });
+  }
+}
+function isModifiedEvent(event) {
+  return (
+    event.defaultPrevented ||
+    event.button !== 0 ||
+    event.metaKey ||
+    event.ctrlKey ||
+    event.shiftKey ||
+    event.altKey
+  );
+}
+// Same document (same path + query)? Used to leave in-page hash links alone.
+function isSameDocument(url) {
+  return url.pathname === window.location.pathname && url.search === window.location.search;
+}
+// Whether a click on an `<a href>` should be handled by client navigation rather
+// than the browser. Used by <Link>. External origins and non-navigational hrefs
+// (mailto:, other origins) are left to the browser, as are same-document hash
+// links so native anchor scrolling keeps working.
+export function shouldInterceptClick(event, href, target) {
+  if (isModifiedEvent(event)) return false;
+  if (target && target !== "_self") return false;
+  if (typeof href !== "string" || href === "") return false;
+  let url;
+  try {
+    url = new URL(href, window.location.href);
+  } catch {
+    return false;
+  }
+  if (url.origin !== window.location.origin) return false;
+  if (url.hash && isSameDocument(url)) return false;
+  return true;
+}
+// Replace the framework-managed head tags with the ones for this route's meta.
+// The marker (HEAD_MARKER) identifies the tags the framework owns — both the
+// ones the server rendered and the ones added here — so the user's own <head>
+// is never touched.
+function applyHead(meta) {
+  if (typeof document === "undefined") return;
+  let tags;
+  try {
+    tags = metaToTags(meta ?? {});
+  } catch {
+    return; // bad meta shouldn't break navigation
+  }
+  for (const node of document.head.querySelectorAll(`[${HEAD_MARKER}]`)) {
+    node.remove();
+  }
+  for (const tag of tags) {
+    const el = document.createElement(tag.tag);
+    el.setAttribute(HEAD_MARKER, "");
+    if (tag.tag === "title") {
+      el.textContent = tag.text ?? "";
+    } else {
+      for (const [name, value] of Object.entries(tag.attrs)) el.setAttribute(name, String(value));
+    }
+    document.head.appendChild(el);
+  }
+}
+function fullLoad(target) {
+  if (typeof window !== "undefined") window.location.assign(target);
+}
+// After a page swap, mirror the browser's anchor behavior: scroll to the
+// hash target if there is a resolvable one, otherwise scroll to the top.
+function scrollToHashOrTop(hash) {
+  if (hash && hash.length > 1) {
+    const raw = hash.slice(1);
+    // A malformed escape (e.g. "#%E0%A4%A") would throw; fall back to the raw id.
+    let id;
+    try {
+      id = decodeURIComponent(raw);
+    } catch {
+      id = raw;
+    }
+    const el = document.getElementById(id);
+    if (el) {
+      el.scrollIntoView();
+      return;
+    }
+  }
+  window.scrollTo(0, 0);
+}
+// Navigate to `href` without a full reload: fetch the navigation payload, swap
+// the page in the store, update history and head, and scroll to top. Any
+// uncertainty (cross-origin, a non-page response, a transport or import failure)
+// falls back to a full browser navigation so the user always gets somewhere.
+//
+// `history`: "push" (default) adds an entry, "replace" replaces the current one,
+// "none" updates in place (used by popstate, where the browser already moved).
+export async function navigate(href, { history: historyMode = "push", load = loadModule } = {}) {
+  if (!store || typeof window === "undefined") {
+    fullLoad(href);
+    return;
+  }
+  const url = new URL(href, window.location.href);
+  if (url.origin !== window.location.origin) {
+    fullLoad(href);
+    return;
+  }
+  // The server only routes on path + query; the hash is client-only, but it is
+  // preserved in the history entry and used to scroll after the swap.
+  const path = url.pathname + url.search;
+  const historyTarget = path + url.hash;
+  let payload;
+  try {
+    const res = await fetch(`${NAV_ENDPOINT}?to=${encodeURIComponent(path)}`, {
+      headers: { accept: "application/json" },
+    });
+    if (!(res.headers.get("content-type") || "").includes("application/json")) {
+      fullLoad(historyTarget);
+      return;
+    }
+    payload = await res.json();
+  } catch {
+    fullLoad(historyTarget);
+    return;
+  }
+  if (payload.kind === "redirect") {
+    // The redirecting URL was never added to history (only the final page is),
+    // so there is nothing to skip: the destination inherits this navigation's
+    // history mode. A popstate ("none") replaces so the URL bar reflects where
+    // we actually landed.
+    const mode = historyMode === "none" ? "replace" : historyMode;
+    await navigate(payload.location, { history: mode, load });
+    return;
+  }
+  if (payload.kind !== "render") {
+    fullLoad(historyTarget);
+    return;
+  }
+  await applyRenderPayload(payload, { url: historyTarget, history: historyMode, load });
+}
+// Swap the page to a render payload that the caller already has in hand: import
+// the page module, update history to `url`, replace the page and managed head in
+// the store, and scroll. Shared by client navigation (which fetched the payload
+// from /_smaoog/nav) and enhanced <Form> mutations (whose own response was a
+// render envelope). On a failure to import the page it falls back to a full
+// load. `scroll` defaults on; an in-place form swap (validation errors) passes
+// false to keep the user where they are.
+export async function applyRenderPayload(
+  payload,
+  { url, history: historyMode = "push", scroll = true, load = loadModule } = {},
+) {
+  if (!store || typeof window === "undefined") {
+    fullLoad(url);
+    return false;
+  }
+  let mod;
+  try {
+    mod = await load(payload.module);
+  } catch {
+    fullLoad(url);
+    return false;
+  }
+  const Page = mod?.default;
+  if (typeof Page !== "function") {
+    fullLoad(url);
+    return false;
+  }
+  if (historyMode === "push") {
+    window.history.pushState(null, "", url);
+  } else if (historyMode === "replace") {
+    window.history.replaceState(null, "", url);
+  }
+  store.set({ Page, props: payload.props ?? {}, routeId: payload.routeId });
+  applyHead(payload.meta);
+  if (scroll) scrollToHashOrTop(new URL(url, window.location.href).hash);
+  return true;
+}

package/src/client/runtime.js ADDED Viewed

@@ -0,0 +1,47 @@
+import React from "react";
+import { hydrateRoot } from "react-dom/client";
+import { PROPS_SCRIPT_ID, ROUTE_SCRIPT_ID } from "../serialize.js";
+import { createRouteStore, Root } from "./store.js";
+import { installNavigation } from "./navigation.js";
+// The element the server renders the page into (Document's `<main id="root">`).
+const ROOT_ID = "root";
+function readJsonScript(id) {
+  const el = document.getElementById(id);
+  const text = el?.textContent;
+  return text ? JSON.parse(text) : null;
+}
+// Hydrate the server-rendered page in place: read the route bootstrap, import the
+// page module, and attach React to the existing DOM with the SSR props. The page
+// is rendered through a route store so client navigation can later swap it
+// without a reload; the store is wired into the navigation runtime here.
+//
+// `load` imports a page module by URL — injectable so the runtime can be driven
+// in tests (and by client navigation) without a bundler. It defaults to a native
+// dynamic import, which Vite (dev) / the hashed asset (prod) resolves.
+export async function hydrate({ load = (url) => import(/* @vite-ignore */ url) } = {}) {
+  const route = readJsonScript(ROUTE_SCRIPT_ID);
+  // No bootstrap -> nothing to hydrate (e.g. a static/error page). Quietly do
+  // nothing rather than treat a deliberately-static page as an error.
+  if (!route?.module) return null;
+  const container = document.getElementById(ROOT_ID);
+  if (!container) {
+    console.error(`[smaoog] cannot hydrate: no #${ROOT_ID} element found`);
+    return null;
+  }
+  const mod = await load(route.module);
+  const Page = mod?.default;
+  if (typeof Page !== "function") {
+    console.error(`[smaoog] cannot hydrate "${route.id}": its module has no default export`);
+    return null;
+  }
+  const props = readJsonScript(PROPS_SCRIPT_ID) ?? {};
+  const store = createRouteStore({ Page, props, routeId: route.id });
+  installNavigation({ store, load });
+  return hydrateRoot(container, React.createElement(Root, { store }));
+}

package/src/client/store.js ADDED Viewed

@@ -0,0 +1,31 @@
+import React from "react";
+// A tiny external store holding the currently displayed route — its page
+// component, props, and route id. Hydration seeds it from the server-rendered
+// page; client navigation replaces its value to swap the page in place. It is
+// deliberately framework-agnostic state (no React inside) so navigation can live
+// outside the React tree.
+export function createRouteStore(initial) {
+  let state = initial;
+  const listeners = new Set();
+  return {
+    get: () => state,
+    set(next) {
+      state = next;
+      for (const listener of listeners) listener();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}
+// The root component React renders into #root. It subscribes to the route store
+// and renders whatever page is current, so a store update (from navigation)
+// re-renders the whole page without a reload. It adds no DOM of its own, so the
+// hydrated markup matches the server's exactly.
+export function Root({ store }) {
+  const state = React.useSyncExternalStore(store.subscribe, store.get, store.get);
+  return React.createElement(state.Page, state.props);
+}

package/src/conventions.js ADDED Viewed

@@ -0,0 +1,47 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+// Candidate locations for the user-owned document, in precedence order.
+export const DOCUMENT_FILES = [
+  "src/document.tsx",
+  "src/document.jsx",
+  "src/document.ts",
+  "src/document.js",
+];
+// Candidate locations for the user-owned error pages, in precedence order.
+export const ERROR_PAGE_FILES = {
+  notFound: [
+    "src/routes/_404.tsx",
+    "src/routes/_404.jsx",
+    "src/routes/_404.ts",
+    "src/routes/_404.js",
+  ],
+  error: [
+    "src/routes/_500.tsx",
+    "src/routes/_500.jsx",
+    "src/routes/_500.ts",
+    "src/routes/_500.js",
+  ],
+};
+// Conventional browser entry and global stylesheet locations. The helpers in
+// Document can opt into them without requiring a user config file.
+export const CLIENT_ENTRY_FILES = [
+  "src/client-entry.tsx",
+  "src/client-entry.jsx",
+  "src/client-entry.ts",
+  "src/client-entry.js",
+];
+export const STYLESHEET_FILES = ["src/app.css"];
+// The first of `files` (root-relative paths) that exists, returned as a
+// root-relative path, or null. Callers turn it into a Vite id or an absolute
+// path as needed.
+export function findFirst(root, files) {
+  for (const rel of files) {
+    if (existsSync(join(root, rel))) return rel;
+  }
+  return null;
+}

package/src/dev.js ADDED Viewed

@@ -0,0 +1,84 @@
+import { existsSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { DOCUMENT_FILES, ERROR_PAGE_FILES, findFirst } from "./conventions.js";
+import { createRequestHandler } from "./router.js";
+import { scanRoutes } from "./routes.js";
+import { createServer, listen } from "./server.js";
+import { createViteServer, loadModule } from "./vite.js";
+// Turn an absolute route file path into a Vite root-relative module id
+// ("/src/routes/posts/[id].tsx"), with forward slashes on every platform.
+function toViteId(root, file) {
+  return "/" + relative(root, file).split(sep).join("/");
+}
+// A module loader backed by Vite's SSR pipeline: route modules, the document,
+// and error pages are all transformed and loaded on demand in dev.
+export function createDevLoader({ vite, root }) {
+  const documentRel = findFirst(root, DOCUMENT_FILES);
+  const errorRel = {
+    notFound: findFirst(root, ERROR_PAGE_FILES.notFound),
+    error: findFirst(root, ERROR_PAGE_FILES.error),
+  };
+  const id = (rel) => (rel ? loadModule(vite, `/${rel}`) : Promise.resolve(null));
+  return {
+    route: (route) => loadModule(vite, toViteId(root, route.file)),
+    document: () => id(documentRel),
+    errorPage: (kind) => id(errorRel[kind]),
+  };
+}
+// Wire the dev loader and source/public roots into the framework request
+// handler. Tests use this directly; startDev uses it below.
+export function createDevRequestHandler({ vite, root, routes, options = {} }) {
+  return createRequestHandler({
+    routes,
+    loader: createDevLoader({ vite, root }),
+    publicRoot: join(root, "public"),
+    srcRoot: join(root, "src"),
+    // Vite serves transformed browser modules (the client entry, page modules)
+    // and its own dev endpoints; the framework keeps routing and serves CSS
+    // through Vite's transform (so Tailwind/PostCSS/@import run in dev too).
+    viteMiddlewares: vite.middlewares,
+    transformStylesheet: (id) => vite.transformRequest(id),
+    dev: true,
+    options,
+  });
+}
+// Orchestrate `smaoog dev`: scan the file routes, boot the internal Vite module
+// boundary, and start the node:http server with the framework request handler.
+// Vite is created internally — the user only ever runs `smaoog dev`.
+export async function startDev({ root = process.cwd(), port = 3000 } = {}) {
+  // A brand-new project may not have a routes dir yet; treat that as no routes.
+  const routesDir = join(root, "src", "routes");
+  const routes = existsSync(routesDir) ? await scanRoutes(routesDir) : [];
+  // The server is created before Vite so it can be shared with Vite's HMR
+  // WebSocket; the request handler (which needs Vite's middlewares) is attached
+  // afterwards, and we only listen once everything is wired. HMR upgrades and
+  // ordinary requests are separate events on the server, so the order is safe.
+  const server = createServer();
+  const vite = await createViteServer({ root, server });
+  const requestHandler = createDevRequestHandler({ vite, root, routes });
+  server.on("request", requestHandler);
+  try {
+    await listen(server, port);
+  } catch (err) {
+    // Don't leak the Vite server if the HTTP server can't bind.
+    await vite.close();
+    throw err;
+  }
+  return {
+    server,
+    vite,
+    routes,
+    async close() {
+      await new Promise((resolve) => server.close(resolve));
+      await vite.close();
+    },
+  };
+}

package/src/dispatch.js ADDED Viewed

@@ -0,0 +1,75 @@
+import { HttpError } from "./errors.js";
+import { createRequest } from "./request.js";
+import { createResponse, isTerminal, sendResult } from "./response.js";
+// Run a single route handler against a Node request/response: build the
+// wrappers, invoke the handler, and apply whatever it returns. This is the
+// seam route dispatch reuses. `options`:
+//   - bodyLimit, params -> request wrapper
+//   - canRender         -> response wrapper (whether res.render() is allowed)
+//   - renderInfo        -> response wrapper (route id + page component)
+//   - head              -> send the result without a body (HEAD from GET)
+//   - notFoundHandler   -> router-owned renderer for res.notFound()
+//   - errorHandler      -> router-owned renderer for ordinary thrown errors
+export async function runHandler(handler, nodeReq, nodeRes, options = {}) {
+  const {
+    head = false,
+    mode = "html",
+    canRender,
+    renderInfo,
+    notFoundHandler,
+    errorHandler,
+    ...requestOptions
+  } = options;
+  const req = createRequest(nodeReq, requestOptions);
+  const res = createResponse(nodeRes, { canRender, renderInfo });
+  let result;
+  try {
+    result = await handler(req, res);
+  } catch (err) {
+    // Framework HTTP errors (malformed JSON -> 400, body too large -> 413, ...)
+    // become that status. Other errors propagate to error pages (Phase 11).
+    if (err instanceof HttpError) {
+      if (!nodeRes.headersSent) {
+        nodeRes.statusCode = err.status;
+        nodeRes.setHeader("content-type", "text/plain; charset=utf-8");
+        nodeRes.end(err.message);
+      } else if (!nodeRes.writableEnded) {
+        // Headers already flushed (handler wrote through res.raw): end the
+        // response so the client isn't left hanging.
+        nodeRes.end();
+      }
+      return;
+    }
+    if (errorHandler && !nodeRes.headersSent) {
+      await errorHandler(err, { head });
+      return;
+    }
+    throw err;
+  }
+  if (isTerminal(result)) {
+    if (result.kind === "notFound" && notFoundHandler) {
+      await notFoundHandler(result, { head });
+      return;
+    }
+    sendResult(nodeRes, result, { head, mode });
+    return;
+  }
+  // Handler responded directly through the res.raw / req.raw escape hatch.
+  if (nodeRes.headersSent || nodeRes.writableEnded) {
+    return;
+  }
+  // Handler returned nothing terminal and wrote nothing: a missing return.
+  if (errorHandler) {
+    await errorHandler(new Error("Handler did not return a response"), { head });
+    return;
+  }
+  nodeRes.statusCode = 500;
+  nodeRes.setHeader("content-type", "text/plain; charset=utf-8");
+  nodeRes.end("Handler did not return a response");
+}

package/src/errors.js ADDED Viewed

@@ -0,0 +1,11 @@
+// A framework-level HTTP error that maps directly to a status code (e.g. a
+// malformed JSON body -> 400, an over-limit body -> 413). The dispatcher
+// turns these into that status; ordinary thrown errors are handled by the
+// router's error-page path.
+export class HttpError extends Error {
+  constructor(status, message) {
+    super(message ?? `HTTP ${status}`);
+    this.name = "HttpError";
+    this.status = status;
+  }
+}

package/src/form.js ADDED Viewed

@@ -0,0 +1,121 @@
+import React from "react";
+import { applyRenderPayload, navigate } from "./client/navigation.js";
+import { RESPONSE_HEADER, SUBMIT_HEADER } from "./protocol.js";
+// Whether this form carries a file upload, which v0 does not support over the
+// enhanced fetch path (FormData files can't be url-encoded). Such forms should
+// use a plain <form>.
+function isMultipart(form) {
+  if ((form.getAttribute("enctype") || "").toLowerCase() === "multipart/form-data") return true;
+  return Array.from(form.elements).some((el) => el.type === "file");
+}
+async function readJson(response) {
+  if (!(response.headers.get("content-type") || "").includes("application/json")) return null;
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+// A client-enhanced form for route mutations and GET search/navigation. It
+// renders a real <form> (so it works before hydration), then once hydrated takes
+// over submission:
+//
+//   method="get"  -> build a query URL and client-navigate, like <Link>.
+//   mutations     -> submit with fetch; the response decides what happens:
+//                      redirect envelope -> navigate
+//                      render envelope   -> swap the page in place (validation)
+//                      2xx JSON          -> onSuccess(data, response)
+//                      4xx/5xx JSON      -> onError(data, response)
+//
+// `action` defaults to the current route. There is no hidden `_method` field;
+// the real method goes out on the fetch.
+export function Form({ action, method = "get", onSuccess, onError, children, ...rest }) {
+  const normalizedMethod = String(method).toLowerCase();
+  const isGet = normalizedMethod === "get";
+  const [submitting, setSubmitting] = React.useState(false);
+  // Synchronous in-flight guard: state updates are async, so a ref is what
+  // actually blocks a second submit landing before the first finishes.
+  const inFlight = React.useRef(false);
+  async function handleSubmit(event) {
+    event.preventDefault();
+    if (inFlight.current) return;
+    const form = event.currentTarget;
+    const here = window.location.pathname + window.location.search;
+    // File uploads aren't supported over the enhanced path (GET or mutation):
+    // FormData files can't be url-encoded. Bow out clearly; use a plain <form>.
+    if (isMultipart(form)) {
+      console.error(
+        "[smaoog] <Form> does not support file uploads in v0; use a plain <form> for multipart submissions.",
+      );
+      return;
+    }
+    if (isGet) {
+      // Search/navigation form: fold the fields into the query and navigate.
+      const url = new URL(action ?? window.location.pathname, window.location.href);
+      url.search = new URLSearchParams(new FormData(form)).toString();
+      await navigate(url.pathname + url.search);
+      return;
+    }
+    const submitUrl = action ?? here;
+    inFlight.current = true;
+    setSubmitting(true);
+    try {
+      const response = await fetch(submitUrl, {
+        method: normalizedMethod.toUpperCase(),
+        headers: {
+          [SUBMIT_HEADER]: "1",
+          "content-type": "application/x-www-form-urlencoded",
+          accept: "application/json",
+        },
+        body: new URLSearchParams(new FormData(form)).toString(),
+      });
+      const envelope = response.headers.get(RESPONSE_HEADER);
+      if (envelope === "redirect") {
+        const { location } = await response.json();
+        await navigate(location);
+        return;
+      }
+      if (envelope === "render") {
+        // Validation/mutation render: swap the current page in place (no scroll,
+        // no new history entry) so the URL stays put with the new props.
+        await applyRenderPayload(await response.json(), {
+          url: submitUrl,
+          history: "replace",
+          scroll: false,
+        });
+        return;
+      }
+      const data = await readJson(response);
+      if (response.ok) onSuccess?.(data, response);
+      else onError?.(data, response);
+    } catch (error) {
+      // Transport failure (offline, aborted, etc.) — no response to pass.
+      onError?.(null, undefined);
+    } finally {
+      inFlight.current = false;
+      setSubmitting(false);
+    }
+  }
+  // The native method attribute only understands get/post; mutations go out as
+  // POST without JS (the real verb rides the fetch after hydration). This is the
+  // documented v0 limitation, not a hidden field.
+  const nativeMethod = isGet ? "get" : "post";
+  const content = typeof children === "function" ? children({ submitting }) : children;
+  return React.createElement(
+    "form",
+    { ...rest, action, method: nativeMethod, onSubmit: handleSubmit },
+    content,
+  );
+}