vite-plugin-nora 0.1.0

package/src/client/toolbar/use-draggable-bar.js

@@ -0,0 +1,204 @@
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+
+const KEY = "nora:bar-position";
+const MARGIN = 12;
+/** Pointer travel before a press becomes a drag rather than a click. */
+const THRESHOLD = 4;
+
+const DEFAULT = { hside: "right", vside: "bottom", dx: 20, dy: 20 };
+
+function read() {
+  try {
+    const raw = localStorage.getItem(KEY);
+    if (!raw) return DEFAULT;
+    const parsed = JSON.parse(raw);
+    if (!["left", "right"].includes(parsed.hside)) return DEFAULT;
+    if (!["top", "bottom"].includes(parsed.vside)) return DEFAULT;
+    return parsed;
+  } catch {
+    return DEFAULT;
+  }
+}
+
+function write(pos) {
+  try {
+    localStorage.setItem(KEY, JSON.stringify(pos));
+  } catch {
+    /* storage disabled — the bar just won't remember where you put it */
+  }
+}
+
+/**
+ * Turn a pill rectangle into offsets from whichever corner it now sits nearest.
+ *
+ * Anchoring to the nearest corner rather than always to the top-left is what
+ * makes the panels behave: the bar grows away from the edge it is pinned to, so
+ * a bar at the bottom opens its panels upward and one at the top opens them
+ * downward, with no measuring or repositioning after the fact.
+ */
+function toAnchor(rect) {
+  const { innerWidth: vw, innerHeight: vh } = window;
+  const hside = rect.left + rect.width / 2 < vw / 2 ? "left" : "right";
+  const vside = rect.top + rect.height / 2 < vh / 2 ? "top" : "bottom";
+  return {
+    hside,
+    vside,
+    dx: Math.round(hside === "left" ? rect.left : vw - (rect.left + rect.width)),
+    dy: Math.round(vside === "top" ? rect.top : vh - (rect.top + rect.height)),
+  };
+}
+
+/** Keep the bar reachable however the window is resized. */
+function clampAnchor(pos, size) {
+  const { innerWidth: vw, innerHeight: vh } = window;
+  const maxX = Math.max(MARGIN, vw - size.width - MARGIN);
+  const maxY = Math.max(MARGIN, vh - size.height - MARGIN);
+  return {
+    ...pos,
+    dx: Math.min(Math.max(pos.dx, MARGIN), maxX),
+    dy: Math.min(Math.max(pos.dy, MARGIN), maxY),
+  };
+}
+
+/**
+ * Drag the bar anywhere on screen.
+ *
+ * A press anywhere on the pill can start a drag, buttons included — moving a
+ * floating object by grabbing any part of it is the expected gesture, and
+ * restricting drags to a slim handle would leave most of an expanded pill
+ * undraggable. A press only becomes a drag past a few pixels of travel, and a
+ * drag swallows the click that would otherwise follow, so buttons still work
+ * exactly as before.
+ */
+export function useDraggableBar(pillRef, expanded) {
+  const [pos, setPos] = useState(read);
+  const [dragging, setDragging] = useState(false);
+  const start = useRef(null);
+  const first = useRef(true);
+
+  useEffect(() => {
+    if (!dragging) write(pos);
+  }, [pos, dragging]);
+
+  useEffect(() => {
+    const onResize = () => {
+      const rect = pillRef.current?.getBoundingClientRect();
+      if (rect) setPos((p) => clampAnchor(p, rect));
+    };
+    window.addEventListener("resize", onResize);
+    return () => window.removeEventListener("resize", onResize);
+  }, [pillRef]);
+
+  /**
+   * Hold the bar's right edge still when it opens and shuts.
+   *
+   * Collapse is the last control on the bar, so the circle the bar shuts into
+   * belongs underneath that button rather than at the far end from it: the
+   * shape should close toward the thing you just pressed, not away from it.
+   *
+   * A right-anchored bar gets that for nothing, because the edge being held is
+   * already the right one. A left-anchored bar is holding the wrong edge, so it
+   * shrinks leftward and leaves the circle 418px from the button that produced
+   * it. The anchor therefore moves across by exactly the width just given up,
+   * and moves back when the bar opens again.
+   *
+   * This is a real change of anchor rather than a transform, and deliberately
+   * so. Dragging and edge-clamping both reason about the pill's box; a purely
+   * visual offset would leave them reasoning about a box nobody can see, and
+   * the circle would jump the first time you picked it up. Because the offset
+   * is re-derived from `dx` on every toggle rather than remembered, a drag in
+   * between is absorbed for free — `toAnchor` has already rewritten `dx` from
+   * the box the user actually left it in.
+   */
+  useLayoutEffect(() => {
+    const pill = pillRef.current;
+    if (!pill) return;
+    if (first.current) {
+      first.current = false;
+      return;
+    }
+
+    const full = parseFloat(getComputedStyle(pill).getPropertyValue("--nora-bar-w"));
+    const shut = pill.offsetHeight;
+    const give = full - shut;
+    if (!Number.isFinite(give) || give <= 0) return;
+
+    setPos((p) =>
+      p.hside === "left"
+        ? clampAnchor(
+            { ...p, dx: p.dx + (expanded ? -give : give) },
+            { width: expanded ? full : shut, height: shut },
+          )
+        : p,
+    );
+  }, [expanded, pillRef]);
+
+  const onPointerDown = useCallback(
+    (event) => {
+      if (event.button !== 0) return;
+      const pill = pillRef.current;
+      if (!pill) return;
+
+      const rect = pill.getBoundingClientRect();
+      start.current = {
+        pointerX: event.clientX,
+        pointerY: event.clientY,
+        left: rect.left,
+        top: rect.top,
+        width: rect.width,
+        height: rect.height,
+        moved: false,
+      };
+
+      const onMove = (moveEvent) => {
+        const s = start.current;
+        if (!s) return;
+        const dx = moveEvent.clientX - s.pointerX;
+        const dy = moveEvent.clientY - s.pointerY;
+
+        if (!s.moved) {
+          if (Math.hypot(dx, dy) < THRESHOLD) return;
+          s.moved = true;
+          setDragging(true);
+        }
+
+        const { innerWidth: vw, innerHeight: vh } = window;
+        const left = Math.min(Math.max(s.left + dx, MARGIN), vw - s.width - MARGIN);
+        const top = Math.min(Math.max(s.top + dy, MARGIN), vh - s.height - MARGIN);
+        setPos(toAnchor({ left, top, width: s.width, height: s.height }));
+      };
+
+      const onUp = () => {
+        window.removeEventListener("pointermove", onMove);
+        window.removeEventListener("pointerup", onUp);
+        const moved = start.current?.moved;
+        start.current = null;
+        setDragging(false);
+
+        // Swallow the click this press would otherwise produce, so dragging
+        // from a button doesn't also press it.
+        if (moved) {
+          const swallow = (clickEvent) => {
+            clickEvent.stopPropagation();
+            clickEvent.preventDefault();
+          };
+          window.addEventListener("click", swallow, { capture: true, once: true });
+          setTimeout(() => window.removeEventListener("click", swallow, { capture: true }), 0);
+        }
+      };
+
+      window.addEventListener("pointermove", onMove);
+      window.addEventListener("pointerup", onUp);
+    },
+    [pillRef],
+  );
+
+  const style = {
+    [pos.hside]: `${pos.dx}px`,
+    [pos.vside]: `${pos.dy}px`,
+    [pos.hside === "left" ? "right" : "left"]: "auto",
+    [pos.vside === "top" ? "bottom" : "top"]: "auto",
+  };
+
+  return { pos, style, dragging, onPointerDown };
+}

package/src/client/viewports.js

@@ -0,0 +1,43 @@
+/**
+ * Viewport presets.
+ *
+ * These are real device widths, and they only mean anything because the
+ * component renders inside an iframe. A CSS width on a div would constrain the
+ * box but leave `@media (max-width: 767px)` unfired — media queries answer to
+ * the viewport, not to an element. The iframe *is* a viewport.
+ */
+/**
+ * A chosen viewport width.
+ *
+ * @typedef {object} NoraViewport
+ * @property {string} id
+ * @property {string} label     what the bar's width button shows
+ * @property {number | null} width  null fits the canvas instead of framing it
+ * @property {string | null} [note] the aside in the viewport menu
+ */
+
+/** @type {NoraViewport[]} */
+export const VIEWPORTS = [
+  { id: "fit", label: "Fit", width: null, note: null },
+  { id: "375", label: "375", width: 375, note: "Phone" },
+  { id: "768", label: "768", width: 768, note: "Tablet" },
+  { id: "1280", label: "1280", width: 1280, note: "Laptop" },
+  { id: "1440", label: "1440", width: 1440, note: "Desktop" },
+];
+
+export const DEFAULT_VIEWPORT = "fit";
+
+export function findViewport(id) {
+  return VIEWPORTS.find((v) => v.id === id) ?? VIEWPORTS[0];
+}
+
+/**
+ * Any width, not just a preset. A sweep finding is a width, and clicking one
+ * has to be able to send the frame there — 771px is exactly the number you
+ * care about and exactly the one no preset list would contain.
+ */
+export function customViewport(width) {
+  const preset = VIEWPORTS.find((v) => v.width === width);
+  if (preset) return preset;
+  return { id: `w${width}`, label: String(width), width, note: null };
+}

package/src/client/virtual.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The registry module the Vite plugin generates at dev time.
+ *
+ * It has no file on disk — `plugin.js` resolves and loads `virtual:nora/registry`
+ * itself — so this is the only place its shape is written down. Keep it in step
+ * with the `load()` hook there.
+ */
+declare module "virtual:nora/registry" {
+  export interface NoraEntry {
+    /** `<relative file>#<export name>` — stable across reloads. */
+    id: string;
+    name: string;
+    /** Path relative to the project root. */
+    file: string;
+    exportName: string;
+    /** Sub-path within the scanned folder, "" at its top level. */
+    group: string;
+    /** Why this cannot render, or null when it can. */
+    unsupported: string | null;
+    load: () => Promise<Record<string, unknown>>;
+  }
+
+  export const entries: NoraEntry[];
+  export const currentDir: string | null;
+  /** The folder's own top-level design, chosen by `pickEntry`. */
+  export const entryId: string | null;
+  export const config: Record<string, unknown>;
+}

package/src/index.js

@@ -0,0 +1,4 @@
+// Programmatic entry, for embedding the previewer in another tool's dev server.
+export { createPreviewServer, findProjectRoot } from "./server/create-server.js";
+export { nora } from "./server/plugin.js";
+export { scanDirectory, listDirectories } from "./server/scan.js";

package/src/server/create-server.js

@@ -0,0 +1,147 @@
+import path from "node:path";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import { createServer, loadConfigFromFile, mergeConfig } from "vite";
+import { nora } from "./plugin.js";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const CLIENT_DIR = path.resolve(here, "../client");
+
+/** Plugin arrays can be nested, async, or contain falsy entries. Flatten them. */
+async function flattenPlugins(plugins) {
+  const out = [];
+  for (const p of await Promise.all([plugins ?? []].flat(Infinity))) {
+    if (!p) continue;
+    if (Array.isArray(p)) out.push(...(await flattenPlugins(p)));
+    else out.push(p);
+  }
+  return out;
+}
+
+/** Does their config already transform JSX? If so, adding ours would double it. */
+function hasReactPlugin(plugins) {
+  return plugins.some((p) => typeof p?.name === "string" && /react/i.test(p.name));
+}
+
+/** Walk up from `start` looking for a package.json to treat as the project root. */
+export function findProjectRoot(start) {
+  let dir = path.resolve(start);
+  const { root } = path.parse(dir);
+  while (true) {
+    if (fs.existsSync(path.join(dir, "package.json"))) return dir;
+    if (dir === root) return path.resolve(start);
+    dir = path.dirname(dir);
+  }
+}
+
+/**
+ * Boot a Vite dev server rooted in the user's project, inheriting their config,
+ * and serve our client through it.
+ *
+ * @param {object} opts
+ * @param {string} opts.root
+ * @param {number} [opts.port]
+ * @param {string|null} [opts.dir] relative folder to open on boot
+ */
+export async function createPreviewServer({ root, port = 5199, dir = null }) {
+  const loaded = await loadConfigFromFile(
+    { command: "serve", mode: "development" },
+    undefined,
+    root,
+  );
+
+  const userConfig = loaded?.config ?? {};
+  const userPlugins = await flattenPlugins(userConfig.plugins);
+  const needsReactPlugin = !hasReactPlugin(userPlugins);
+
+  let reactPlugin = [];
+  if (needsReactPlugin) {
+    try {
+      const { default: react } = await import("@vitejs/plugin-react");
+      reactPlugin = [react()];
+    } catch {
+      // No React plugin anywhere. JSX will fail, but a non-React project may
+      // still be browsable, so warn rather than exit.
+      console.warn(
+        "[nora] no React plugin found in your Vite config and " +
+          "@vitejs/plugin-react is not installed — JSX will not compile.",
+      );
+    }
+  }
+
+  const ours = {
+    configFile: false,
+    root,
+    // `custom` because we serve our own index.html rather than the project's.
+    appType: "custom",
+    plugins: [...reactPlugin, nora({ root, initialDir: dir })],
+    resolve: {
+      // Two copies of React means two dispatchers, and the first useState in a
+      // previewed component throws "invalid hook call". This is the line that
+      // keeps our client and their components on one instance.
+      dedupe: ["react", "react-dom"],
+    },
+    optimizeDeps: {
+      include: ["react", "react-dom", "react-dom/client", "react/jsx-dev-runtime"],
+    },
+    server: {
+      port,
+      strictPort: false,
+      host: "localhost",
+      fs: {
+        // Our client lives outside the project root, so Vite has to be allowed
+        // to serve it. Workspace roots come along via `searchForWorkspaceRoot`
+        // in Vite's own defaults.
+        allow: [root, CLIENT_DIR, path.resolve(CLIENT_DIR, "..", "..")],
+      },
+    },
+  };
+
+  const config = mergeConfig(userConfig, ours);
+  const server = await createServer(config);
+
+  const clientUrl = "/@fs" + CLIENT_DIR.split(path.sep).join("/");
+
+  /** Serve one of our two HTML documents through Vite's transform pipeline. */
+  const sendHtml = async (req, res, next, template, entry) => {
+    try {
+      const raw = fs
+        .readFileSync(path.join(CLIENT_DIR, template), "utf8")
+        .replace("__CP_ENTRY__", `${clientUrl}/${entry}`);
+      const html = await server.transformIndexHtml(req.url ?? "/", raw);
+      res.statusCode = 200;
+      res.setHeader("Content-Type", "text/html");
+      res.end(html);
+    } catch (err) {
+      server.ssrFixStacktrace?.(err);
+      next(err);
+    }
+  };
+
+  // The preview document. Loaded into an iframe by the shell so the component
+  // inside gets a real viewport — media queries and `vw` units answer to the
+  // frame's width, which is the whole point of the viewport presets.
+  server.middlewares.use("/__nora/frame", async (req, res, next) => {
+    if (req.method !== "GET") return next();
+    await sendHtml(req, res, next, "frame.html", "frame.jsx");
+  });
+
+  // Last middleware: anything that isn't a module, asset, or /__cp route gets
+  // our shell. Vite's own middlewares run before this and win.
+  server.middlewares.use(async (req, res, next) => {
+    if (!req.url || req.method !== "GET") return next();
+    if (req.url.startsWith("/__nora/")) return next();
+    if (req.headers.accept && !req.headers.accept.includes("text/html")) return next();
+    await sendHtml(req, res, next, "index.html", "main.jsx");
+  });
+
+  await server.listen();
+
+  return {
+    server,
+    url: `http://localhost:${server.config.server.port}`,
+    inheritedConfig: Boolean(loaded?.path),
+    configPath: loaded?.path ?? null,
+    addedReactPlugin: needsReactPlugin && reactPlugin.length > 0,
+  };
+}

package/src/server/plugin.js

@@ -0,0 +1,207 @@
+import path from "node:path";
+import fs from "node:fs";
+import { clientEntry, scanDirectory, listDirectories } from "./scan.js";
+import { safeResolve, isLoopbackHost } from "./safe-path.js";
+
+const VIRTUAL_ID = "virtual:nora/registry";
+const RESOLVED_ID = "\0" + VIRTUAL_ID;
+
+const CONFIG_NAMES = ["nora.config.tsx", "nora.config.ts", "nora.config.jsx", "nora.config.js"];
+
+/** @param {string} root */
+function findConfigFile(root) {
+  for (const name of CONFIG_NAMES) {
+    const full = path.join(root, name);
+    if (fs.existsSync(full)) return full;
+  }
+  return null;
+}
+
+/** Read a JSON request body without pulling in a body-parser. */
+function readJson(req) {
+  return new Promise((resolve, reject) => {
+    let raw = "";
+    req.on("data", (chunk) => {
+      raw += chunk;
+      if (raw.length > 1e6) reject(new Error("Body too large"));
+    });
+    req.on("end", () => {
+      try {
+        resolve(raw ? JSON.parse(raw) : {});
+      } catch (err) {
+        reject(err);
+      }
+    });
+    req.on("error", reject);
+  });
+}
+
+function sendJson(res, status, body) {
+  res.statusCode = status;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify(body));
+}
+
+/**
+ * The Vite plugin: owns the virtual registry module and the /__nora/* control
+ * endpoints the toolbar talks to.
+ *
+ * @param {object} opts
+ * @param {string} opts.root       absolute project root
+ * @param {string} [opts.initialDir] relative dir to open on boot
+ */
+export function nora({ root, initialDir = null }) {
+  /** @type {string|null} relative path of the folder currently being previewed */
+  /**
+   * The folder being previewed. Server-wide, not per client, and that is a
+   * property rather than an oversight: the registry is a single Vite virtual
+   * module, and the module graph is keyed by id for the whole server, so there
+   * is no version of this that two clients could hold differently.
+   *
+   * What follows from it is that every open tab must agree. When this changes,
+   * every client's registry is stale at once, so the scan endpoint below tells
+   * all of them to reload rather than letting whoever reloads last win.
+   */
+  let currentDir = initialDir;
+  /**
+   * @type {{
+   *   include?: string[],
+   *   exclude?: string[],
+   *   defaultDir?: string,
+   *   entry?: Record<string, string>,
+   * }}
+   */
+  let userConfig = {};
+
+  const configFile = findConfigFile(root);
+
+  return {
+    name: "nora",
+
+    resolveId(id) {
+      if (id === VIRTUAL_ID) return RESOLVED_ID;
+      return null;
+    },
+
+    async load(id) {
+      if (id !== RESOLVED_ID) return null;
+
+      const configImport = configFile
+        ? `import __userConfig from ${JSON.stringify(
+            "/" + path.relative(root, configFile).split(path.sep).join("/"),
+          )};`
+        : "const __userConfig = {};";
+
+      if (!currentDir) {
+        return [
+          configImport,
+          "export const entries = [];",
+          "export const currentDir = null;",
+          "export const entryId = null;",
+          "export const config = __userConfig;",
+        ].join("\n");
+      }
+
+      const { entries, entryId } = await scanDirectory({
+        root,
+        dir: path.join(root, currentDir),
+        include: userConfig.include,
+        exclude: userConfig.exclude,
+        entry: userConfig.entry?.[currentDir],
+      });
+
+      // One explicit dynamic import per entry. A bare import.meta.glob here
+      // would only give us file paths — generating the imports ourselves is
+      // what lets the palette list every export by name before anything loads.
+      const body = entries
+        .map((e) => {
+          const meta = JSON.stringify(clientEntry(e));
+          return `  { ...${meta}, load: () => import(${JSON.stringify(e.url)}) },`;
+        })
+        .join("\n");
+
+      return [
+        configImport,
+        "export const entries = [",
+        body,
+        "];",
+        `export const currentDir = ${JSON.stringify(currentDir)};`,
+        `export const entryId = ${JSON.stringify(entryId)};`,
+        "export const config = __userConfig;",
+      ].join("\n");
+    },
+
+    configureServer(server) {
+      // Load the user config in Node too, so include/exclude/defaultDir can
+      // shape the scan. The client imports the same file separately for the
+      // `wrapper` component, which only exists in the browser.
+      const loadUserConfig = async () => {
+        if (!configFile) return;
+        try {
+          const mod = await server.ssrLoadModule(configFile);
+          userConfig = mod.default ?? {};
+          if (!currentDir && userConfig.defaultDir) {
+            currentDir = userConfig.defaultDir;
+          }
+        } catch (err) {
+          server.config.logger.warn(
+            `[nora] could not load ${path.basename(configFile)}: ${err.message}`,
+          );
+        }
+      };
+      const configReady = loadUserConfig();
+
+      const guard = (handler) => async (req, res, next) => {
+        if (!isLoopbackHost(req)) {
+          return sendJson(res, 403, { error: "Non-loopback Host header refused" });
+        }
+        try {
+          await configReady;
+          await handler(req, res, next);
+        } catch (err) {
+          sendJson(res, 400, { error: String(err.message ?? err) });
+        }
+      };
+
+      // Browse folders. `path` is untrusted and goes through safeResolve.
+      server.middlewares.use(
+        "/__nora/dirs",
+        guard(async (req, res) => {
+          const url = new URL(req.url ?? "/", "http://localhost");
+          const rel = url.searchParams.get("path") ?? "";
+          const abs = safeResolve(root, rel);
+          const dirs = await listDirectories(abs);
+          const relNorm = path.relative(root, abs).split(path.sep).join("/");
+          // No `parent`: the picker needs it synchronously to draw its up row,
+          // and derives it from the path it already holds with exactly this
+          // logic. Sending it only made the endpoint wider.
+          sendJson(res, 200, { path: relNorm, dirs });
+        }),
+      );
+
+      // Point the previewer at a folder: re-scan, invalidate, reload.
+      server.middlewares.use(
+        "/__nora/scan",
+        guard(async (req, res) => {
+          const body = await readJson(req);
+          const abs = safeResolve(root, body.path ?? "");
+          currentDir = path.relative(root, abs).split(path.sep).join("/");
+
+          const mod = server.moduleGraph.getModuleById(RESOLVED_ID);
+          if (mod) server.moduleGraph.invalidateModule(mod);
+
+          // Invalidating drops the cached module; it does not tell anyone. The
+          // client that asked for this is about to reload itself, but every
+          // other open tab is now listing components from a folder this server
+          // has stopped serving, and would go on doing so until something else
+          // reloaded it. `server.hot` on Vite 6+, `server.ws` before it.
+          (server.hot ?? server.ws)?.send?.({ type: "full-reload", path: "*" });
+
+          sendJson(res, 200, { currentDir });
+        }),
+      );
+    },
+  };
+}
+
+export { VIRTUAL_ID, RESOLVED_ID };

package/src/server/safe-path.js

@@ -0,0 +1,42 @@
+import path from "node:path";
+
+/**
+ * Resolve a caller-supplied path against the project root and refuse anything
+ * that escapes it.
+ *
+ * Both `/__nora/dirs` and `/__nora/scan` take a path straight off an HTTP request
+ * and hand it to `fs`. Without this clamp, `?path=../../../../etc` walks the
+ * whole disk of whoever is running the CLI.
+ *
+ * @param {string} root  absolute project root
+ * @param {string} [p]   untrusted relative path
+ * @returns {string}     absolute path guaranteed to sit inside root
+ */
+export function safeResolve(root, p) {
+  const abs = path.resolve(root, p ?? ".");
+  const rel = path.relative(root, abs);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) {
+    throw new Error(`Path escapes project root: ${p}`);
+  }
+  return abs;
+}
+
+/**
+ * Reject requests whose Host header is not a loopback address.
+ *
+ * A dev server bound to localhost is still reachable from any page in the
+ * user's browser via DNS rebinding — an attacker's site resolves their domain
+ * to 127.0.0.1 and then talks to us with their own Host header. Vite has
+ * shipped advisories for exactly this shape of bug.
+ *
+ * @param {import('node:http').IncomingMessage} req
+ * @returns {boolean}
+ */
+export function isLoopbackHost(req) {
+  const host = req.headers.host;
+  if (!host) return false;
+  const name = host.replace(/:\d+$/, "").replace(/^\[|\]$/g, "");
+  return (
+    name === "localhost" || name === "127.0.0.1" || name === "::1" || name.endsWith(".localhost")
+  );
+}