ruact 0.0.2 → 0.0.4

data/vendor/javascript/ruact-server-functions-runtime/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "ruact-server-functions-runtime",
+  "version": "0.3.0",
+  "description": "Server-functions runtime for ruact gem (Stories 8.1 + 8.2 + 9.5). Provides `_makeRef(name)` / `_makeServerFunction(descriptor)` (mutations: POST/PUT/PATCH/DELETE with CSRF + JSON / FormData), `revalidate(path?)` (Flight refetch), and `_makeQuery(descriptor)` + `useQuery(ref, params?)` (reads: GET /q/<jsId>, CSRF-free, FR88 primitive params → { data, loading, error }).",
+  "type": "module",
+  "main": "index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "license": "MIT",
+  "private": true,
+  "scripts": {
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "jsdom": "^25.0.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "vitest": "^2.1.9"
+  }
+}

data/vendor/javascript/ruact-server-functions-runtime/usequery.test.mjs

@@ -0,0 +1,181 @@
+// @vitest-environment jsdom
+//
+// Story 9.5 — vitest coverage for the read-side runtime: the `useQuery` React
+// hook (loading/data/error transitions, param passing, value-stable refetch)
+// and the `_makeQuery` GET wire format (query-string encoding, FR88 primitive
+// allowlist, CSRF-free init). Runs under jsdom so `@testing-library/react`'s
+// `renderHook` can drive the hook through React's effect lifecycle.
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+
+import { useQuery, _makeQuery, RuactActionError, __internals } from "./index.js";
+
+let originalFetch;
+
+beforeEach(() => {
+  originalFetch = globalThis.fetch;
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  vi.restoreAllMocks();
+});
+
+function mockFetchOk(jsonBody, { status = 200, contentType = "application/json" } = {}) {
+  const response = {
+    ok: true,
+    status,
+    headers: { get: (n) => (n.toLowerCase() === "content-type" ? contentType : null) },
+    text: vi.fn().mockResolvedValue(typeof jsonBody === "string" ? jsonBody : JSON.stringify(jsonBody)),
+  };
+  globalThis.fetch = vi.fn().mockResolvedValue(response);
+  return response;
+}
+
+function mockFetchError(status, bodyText) {
+  const response = {
+    ok: false,
+    status,
+    headers: { get: () => "text/plain" },
+    text: vi.fn().mockResolvedValue(bodyText),
+  };
+  globalThis.fetch = vi.fn().mockResolvedValue(response);
+  return response;
+}
+
+describe("Story 9.5 — useQuery hook contract", () => {
+  it("starts loading, then resolves to { data, loading: false, error: null }", async () => {
+    const ref = vi.fn().mockResolvedValue({ items: [1, 2] });
+    const { result } = renderHook(() => useQuery(ref));
+
+    expect(result.current.loading).toBe(true);
+    expect(result.current.data).toBeUndefined();
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.data).toEqual({ items: [1, 2] });
+    expect(result.current.error).toBe(null);
+  });
+
+  it("transitions loading → error on a rejected reference", async () => {
+    const err = new RuactActionError({ name: "/q/categories", status: 500, body: "boom", response: {} });
+    const ref = vi.fn().mockRejectedValue(err);
+    const { result } = renderHook(() => useQuery(ref));
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.error).toBe(err);
+    expect(result.current.data).toBeUndefined();
+  });
+
+  it("passes params to the query reference", async () => {
+    const ref = vi.fn().mockResolvedValue("ok");
+    const params = { q: "ruby", limit: 5 };
+    renderHook(() => useQuery(ref, params));
+
+    await waitFor(() => expect(ref).toHaveBeenCalledTimes(1));
+    expect(ref).toHaveBeenCalledWith(params);
+  });
+
+  it("does not refetch when params are value-equal across renders", async () => {
+    const ref = vi.fn().mockResolvedValue("ok");
+    const { rerender } = renderHook(({ p }) => useQuery(ref, p), {
+      initialProps: { p: { q: "a" } },
+    });
+    await waitFor(() => expect(ref).toHaveBeenCalledTimes(1));
+
+    rerender({ p: { q: "a" } }); // fresh object literal, identical value
+    await Promise.resolve();
+    expect(ref).toHaveBeenCalledTimes(1);
+  });
+
+  it("refetches when params change by value", async () => {
+    const ref = vi.fn().mockResolvedValue("ok");
+    const { rerender } = renderHook(({ p }) => useQuery(ref, p), {
+      initialProps: { p: { q: "a" } },
+    });
+    await waitFor(() => expect(ref).toHaveBeenCalledTimes(1));
+
+    rerender({ p: { q: "b" } });
+    await waitFor(() => expect(ref).toHaveBeenCalledTimes(2));
+    expect(ref).toHaveBeenLastCalledWith({ q: "b" });
+  });
+
+  it("surfaces a synchronous throw from the reference as an error (not an unhandled rejection)", async () => {
+    const ref = () => {
+      throw new TypeError("params must be a plain object");
+    };
+    const { result } = renderHook(() => useQuery(ref, [1, 2]));
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.error).toBeInstanceOf(TypeError);
+  });
+});
+
+describe("Story 9.5 — useQuery against _makeQuery end-to-end (GET wire)", () => {
+  it("issues GET /q/<id>?<params> and resolves the JSON body through the hook", async () => {
+    mockFetchOk([{ value: 1, label: "Books" }]);
+    const categories = _makeQuery({ path: "/q/categories", kind: "query" });
+
+    const { result } = renderHook(() => useQuery(categories, { q: "bo" }));
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+    const [url, init] = globalThis.fetch.mock.calls[0];
+    expect(url).toBe("/q/categories?q=bo");
+    expect(init.method).toBe("GET");
+    expect(result.current.data).toEqual([{ value: 1, label: "Books" }]);
+  });
+
+  it("carries the structured RuactActionError into the hook's error on a 4xx", async () => {
+    mockFetchError(400, "bad");
+    const search = _makeQuery({ path: "/q/search", kind: "query" });
+
+    const { result } = renderHook(() => useQuery(search));
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.error).toBeInstanceOf(RuactActionError);
+    expect(result.current.error.status).toBe(400);
+  });
+});
+
+describe("Story 9.5 — _makeQuery / buildQueryUrl wire format (FR88)", () => {
+  const { buildQueryUrl, buildQueryFetchInit } = __internals;
+
+  it("omits the query string entirely when no params are given", () => {
+    expect(buildQueryUrl("/q/categories", undefined)).toBe("/q/categories");
+    expect(buildQueryUrl("/q/categories", null)).toBe("/q/categories");
+    expect(buildQueryUrl("/q/categories", {})).toBe("/q/categories");
+  });
+
+  it("encodes string / number / boolean primitives", () => {
+    expect(buildQueryUrl("/q/search", { q: "a b", limit: 5, active: true })).toBe(
+      "/q/search?q=a+b&limit=5&active=true",
+    );
+  });
+
+  it("encodes null as a BARE key (Rack parses `?q` as nil, distinct from `?q=` empty string)", () => {
+    expect(buildQueryUrl("/q/search", { q: null })).toBe("/q/search?q");
+    // value-bearing params keep `key=value`; a null alongside is a bare key
+    expect(buildQueryUrl("/q/search", { limit: 5, q: null })).toBe("/q/search?limit=5&q");
+  });
+
+  it("rejects an array value (FR88 — arrays are not primitives)", () => {
+    expect(() => buildQueryUrl("/q/search", { q: [1, 2] })).toThrow(/arrays and objects are rejected/);
+  });
+
+  it("rejects an object value", () => {
+    expect(() => buildQueryUrl("/q/search", { q: { deep: 1 } })).toThrow(/arrays and objects are rejected/);
+  });
+
+  it("rejects a top-level array of params", () => {
+    expect(() => buildQueryUrl("/q/search", [1, 2])).toThrow(/plain object/);
+  });
+
+  it("builds a GET init with Accept JSON, no body, no CSRF, redirect: error", () => {
+    const init = buildQueryFetchInit();
+    expect(init.method).toBe("GET");
+    expect(init.body).toBeUndefined();
+    expect(init.headers.Accept).toBe("application/json");
+    expect(init.headers["X-CSRF-Token"]).toBeUndefined();
+    expect(init.redirect).toBe("error");
+  });
+});

data/vendor/javascript/vite-plugin-ruact/index.js

@@ -0,0 +1,164 @@
+import fs from "node:fs";
+import path from "node:path";
+import { installServerFunctionsHooks } from "./server-functions-codegen.mjs";
+
+/**
+ * vite-plugin-ruact
+ *
+ * Scans app/javascript/components for files with "use client" directives and
+ * emits public/react-client-manifest.json so the Rails gem can resolve
+ * component names to chunk URLs.
+ *
+ * Manifest format:
+ * {
+ *   "LikeButton": {
+ *     "id":     "/assets/LikeButton-abc123.js",
+ *     "name":   "LikeButton",
+ *     "chunks": ["/assets/LikeButton-abc123.js"]
+ *   }
+ * }
+ */
+export default function ruact(options = {}) {
+  const {
+    componentsDir = "app/javascript/components",
+    manifestOutput = "public/react-client-manifest.json",
+  } = options;
+
+  let root;
+  let manifest = {};
+
+  return installServerFunctionsHooks({
+    name: "vite-plugin-ruact",
+
+    configResolved(config) {
+      root = config.root;
+    },
+
+    // During dev: build the manifest from source files
+    buildStart() {
+      manifest = buildManifest(path.resolve(root, componentsDir));
+      writeManifest(path.resolve(root, manifestOutput), manifest);
+    },
+
+    // During build: update with hashed chunk URLs from the bundle
+    generateBundle(_options, bundle) {
+      const updated = {};
+
+      for (const [chunkFileName, chunk] of Object.entries(bundle)) {
+        if (chunk.type !== "chunk") continue;
+
+        const facadeId = chunk.facadeModuleId;
+        if (!facadeId) continue;
+
+        // Find manifest entries whose source file matches this chunk
+        for (const [name, entry] of Object.entries(manifest)) {
+          if (facadeId === entry._sourceFile) {
+            const url = "/" + chunkFileName;
+            updated[name] = {
+              id: url,
+              name,
+              chunks: [url],
+            };
+          }
+        }
+      }
+
+      // Merge: keep entries that didn't get a hashed URL (dev mode)
+      const final = { ...manifest, ...updated };
+      // Strip internal _sourceFile field
+      for (const entry of Object.values(final)) {
+        delete entry._sourceFile;
+      }
+
+      writeManifest(path.resolve(root, manifestOutput), final);
+    },
+
+    // Dev server: watch components dir and rebuild manifest on change
+    configureServer(server) {
+      const dir = path.resolve(root, componentsDir);
+      server.watcher.add(dir);
+      server.watcher.on("change", (file) => {
+        if (file.startsWith(dir)) {
+          manifest = buildManifest(dir);
+          writeManifest(path.resolve(root, manifestOutput), manifest);
+        }
+      });
+    },
+  }, options);
+}
+
+function buildManifest(componentsDir) {
+  const manifest = {};
+
+  if (!fs.existsSync(componentsDir)) return manifest;
+
+  const files = walkDir(componentsDir).filter((f) =>
+    /\.(jsx?|tsx?)$/.test(f)
+  );
+
+  for (const file of files) {
+    const content = fs.readFileSync(file, "utf8");
+    if (!hasUseClient(content)) continue;
+
+    const exports = extractExportNames(content);
+    const relUrl = "/" + path.relative(componentsDir, file);
+
+    for (const name of exports) {
+      manifest[name] = {
+        id: relUrl,
+        name,
+        chunks: [relUrl],
+        _sourceFile: file, // used during build to match hashed chunks
+      };
+    }
+  }
+
+  return manifest;
+}
+
+function hasUseClient(content) {
+  // "use client" must appear as a directive at the top of the file
+  return /^\s*["']use client["']/m.test(content);
+}
+
+function extractExportNames(content) {
+  const names = new Set();
+
+  // export function Foo
+  // export const Foo
+  // export class Foo
+  const namedRe = /export\s+(?:default\s+)?(?:function|const|class|let|var)\s+([A-Z][A-Za-z0-9]*)/g;
+  let m;
+  while ((m = namedRe.exec(content)) !== null) {
+    names.add(m[1]);
+  }
+
+  // export { Foo, Bar }
+  const bracedRe = /export\s+\{([^}]+)\}/g;
+  while ((m = bracedRe.exec(content)) !== null) {
+    for (const part of m[1].split(",")) {
+      const name = part.trim().split(/\s+as\s+/).pop().trim();
+      if (/^[A-Z]/.test(name)) names.add(name);
+    }
+  }
+
+  return Array.from(names);
+}
+
+function writeManifest(outputPath, manifest) {
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, JSON.stringify(manifest, null, 2));
+}
+
+function walkDir(dir) {
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkDir(full));
+    } else {
+      results.push(full);
+    }
+  }
+  return results;
+}