gantry-web 0.1.0

package/src/styles.css

@@ -0,0 +1,309 @@
+/* Gantry chrome + Tea built-in styles. Theme everything from the app's
+   root index.css by overriding these variables - the components read
+   them live, so a retheme is just new values, no component changes. */
+
+:root {
+  --gantry-bg: #101012;
+  --gantry-fg: #e8e8ea;
+  --gantry-fg-dim: #9a9aa0;
+  --gantry-accent: #6ea8fe;
+  --gantry-border: #2a2a2e;
+  --gantry-titlebar-h: 40px;
+  --gantry-titlebar-bg: transparent;
+  --gantry-titlebar-fg: var(--gantry-fg);
+  --gantry-btn-hover: rgba(255, 255, 255, 0.08);
+  --gantry-close-hover: #c42b1c;
+  --gantry-control-bg: #1a1a1e;
+  --gantry-control-border: #34343a;
+  --gantry-radius: 6px;
+  --gantry-font:
+    "Segoe UI", system-ui, -apple-system, sans-serif;
+}
+
+/* ---- window chrome ---- */
+
+.gantry-titlebar {
+  position: relative;
+  display: flex;
+  align-items: center;
+  flex: none;
+  background: var(--gantry-titlebar-bg);
+  color: var(--gantry-titlebar-fg);
+  font-family: var(--gantry-font);
+  user-select: none;
+}
+
+.gantry-dragstrip {
+  position: absolute;
+  top: 0;
+  z-index: 30;
+}
+
+/* The custom slots sit flush against the window edges; space them
+   with your own padding/margins if you want inset. */
+.gantry-titlebar-left {
+  display: flex;
+  align-items: stretch;
+  height: 100%;
+  position: relative;
+  z-index: 31;
+}
+
+.gantry-titlebar-right {
+  display: flex;
+  align-items: stretch;
+  height: 100%;
+}
+
+/* Titlebar buttons for YOUR controls (back/forward, menus, actions) -
+   styled independently of the window buttons via their own variables. */
+.gantry-tbbtn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: var(--gantry-tbbtn-w, 40px);
+  height: 100%;
+  padding: 0;
+  border: none;
+  border-radius: 0;
+  outline: none;
+  background: var(--gantry-tbbtn-bg, transparent);
+  color: var(--gantry-tbbtn-fg, var(--gantry-titlebar-fg));
+  cursor: default;
+}
+
+.gantry-tbbtn:hover {
+  background: var(--gantry-tbbtn-hover, var(--gantry-btn-hover));
+}
+
+.gantry-titlebar-title {
+  position: absolute;
+  left: 0;
+  right: 0;
+  text-align: center;
+  font-size: 13px;
+  color: var(--gantry-fg-dim);
+  pointer-events: none; /* stays part of the drag band */
+}
+
+/* Left/right-aligned title text (inside the flex sections). */
+.gantry-titlebar-text {
+  display: flex;
+  align-items: center;
+  font-size: 13px;
+  color: var(--gantry-fg-dim);
+  padding: 0 8px;
+  pointer-events: none;
+  white-space: nowrap;
+}
+
+.gantry-titlebar-end {
+  display: flex;
+  align-items: stretch;
+  height: 100%;
+  margin-left: auto;
+  position: relative;
+  z-index: 31;
+}
+
+.gantry-winbtn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 46px;
+  height: 100%; /* follows the bar's height, thin or tall */
+  padding: 0;
+  border: none;
+  border-radius: 0;
+  outline: none;
+  background: transparent;
+  color: var(--gantry-titlebar-fg);
+  cursor: default;
+}
+
+.gantry-winbtn:hover {
+  background: var(--gantry-btn-hover);
+}
+
+.gantry-winbtn-close:hover {
+  background: var(--gantry-close-hover);
+  color: #fff;
+}
+
+/* ---- Tea built-ins ---- */
+
+.gantry-tea-column {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  min-height: 0;
+}
+
+.gantry-tea-row {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  gap: 8px;
+  min-width: 0;
+}
+
+.gantry-tea-text {
+  font-family: var(--gantry-font);
+  color: var(--gantry-fg);
+  font-size: 14px;
+}
+
+.gantry-tea-heading {
+  font-family: var(--gantry-font);
+  color: var(--gantry-fg);
+  font-size: 18px;
+  font-weight: 600;
+  margin: 0;
+}
+
+.gantry-tea-button {
+  font-family: var(--gantry-font);
+  font-size: 13px;
+  color: var(--gantry-fg);
+  background: var(--gantry-control-bg);
+  border: 1px solid var(--gantry-control-border);
+  border-radius: var(--gantry-radius);
+  padding: 6px 14px;
+}
+
+.gantry-tea-button:hover {
+  border-color: var(--gantry-accent);
+}
+
+.gantry-tea-button:active {
+  transform: translateY(1px);
+}
+
+.gantry-tea-input,
+.gantry-tea-select {
+  font-family: var(--gantry-font);
+  font-size: 13px;
+  color: var(--gantry-fg);
+  background: var(--gantry-control-bg);
+  border: 1px solid var(--gantry-control-border);
+  border-radius: var(--gantry-radius);
+  padding: 6px 10px;
+  outline: none;
+}
+
+.gantry-tea-input:focus,
+.gantry-tea-select:focus {
+  border-color: var(--gantry-accent);
+}
+
+.gantry-tea-checkbox {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  font-family: var(--gantry-font);
+  font-size: 13px;
+  color: var(--gantry-fg);
+}
+
+.gantry-tea-divider {
+  border: none;
+  border-top: 1px solid var(--gantry-border);
+  margin: 4px 0;
+  width: 100%;
+}
+
+.gantry-tea-spacer {
+  flex: 1;
+}
+
+.gantry-tea-progress {
+  height: 6px;
+  border-radius: 3px;
+  background: var(--gantry-control-bg);
+  overflow: hidden;
+  min-width: 80px;
+  flex: 1;
+}
+
+.gantry-tea-progress-fill {
+  height: 100%;
+  background: var(--gantry-accent);
+}
+
+.gantry-tea-unknown {
+  font-family: var(--gantry-font);
+  font-size: 12px;
+  color: #ff8080;
+  border: 1px dashed #ff8080;
+  border-radius: var(--gantry-radius);
+  padding: 4px 8px;
+}
+
+/* ---- themed defaults for plain elements ----
+   Pages write ordinary <input>/<button>/<select> and get the app look
+   without any per-page css; the Tea built-ins carry the same values. */
+
+.gantry-app input[type="text"],
+.gantry-app input[type="password"],
+.gantry-app input[type="number"],
+.gantry-app input[type="search"],
+.gantry-app input:not([type]),
+.gantry-app textarea,
+.gantry-app select {
+  font-family: var(--gantry-font);
+  font-size: 13px;
+  color: var(--gantry-fg);
+  background: var(--gantry-control-bg);
+  border: 1px solid var(--gantry-control-border);
+  border-radius: var(--gantry-radius);
+  padding: 6px 10px;
+  outline: none;
+}
+
+.gantry-app input:focus,
+.gantry-app textarea:focus,
+.gantry-app select:focus {
+  border-color: var(--gantry-accent);
+}
+
+.gantry-app button:not(.gantry-winbtn):not(.gantry-tbbtn) {
+  font-family: var(--gantry-font);
+  font-size: 13px;
+  color: var(--gantry-fg);
+  background: var(--gantry-control-bg);
+  border: 1px solid var(--gantry-control-border);
+  border-radius: var(--gantry-radius);
+  padding: 6px 14px;
+}
+
+.gantry-app button:not(.gantry-winbtn):not(.gantry-tbbtn):hover {
+  border-color: var(--gantry-accent);
+}
+
+.gantry-app input[type="checkbox"] {
+  accent-color: var(--gantry-accent);
+}
+
+/* Link renders anchors without href (no status bubble); keep the
+   pointer cursor they would otherwise lose. */
+.gantry-app a[role="link"] {
+  cursor: pointer;
+}
+
+/* ---- app scaffold ---- */
+
+.gantry-app {
+  display: flex;
+  flex-direction: column;
+  height: 100vh;
+  background: var(--gantry-bg);
+  color: var(--gantry-fg);
+  font-family: var(--gantry-font);
+  overflow: hidden;
+}
+
+.gantry-page {
+  flex: 1;
+  min-height: 0;
+  overflow: auto;
+}

package/src/tea/Runtime.tsx

@@ -0,0 +1,195 @@
+import {
+  createElement,
+  useEffect,
+  useRef,
+  useState,
+  type FC,
+  type ReactNode,
+} from "react";
+import { connect, onRender, sendTeaEvent, type WireNode } from "../socket";
+
+/** Props every Tea-rendered component receives. */
+export interface TeaComponentProps {
+  node: WireNode;
+  /** emit fires one of the node's Go handlers by event name. */
+  emit: (event: string, payload?: unknown) => void;
+  children?: ReactNode;
+}
+
+export type ComponentRegistry = Record<string, FC<TeaComponentProps>>;
+
+// extraComponents lets createApp add explicitly-registered components on
+// top of the paired components/ folders.
+let appRegistry: ComponentRegistry = {};
+
+export function setRegistry(reg: ComponentRegistry): void {
+  appRegistry = reg;
+}
+
+function emitFor(node: WireNode) {
+  return (event: string, payload?: unknown) => {
+    const id = node.handlers?.[event];
+    if (id) sendTeaEvent(id, payload);
+  };
+}
+
+function styleHints(props: Record<string, unknown> | undefined): {
+  style: Record<string, string | number>;
+  className: string;
+} {
+  const style: Record<string, string | number> = {};
+  let className = "";
+  if (props) {
+    if (typeof props.gap === "number") style.gap = props.gap;
+    if (typeof props.pad === "number") style.padding = props.pad;
+    if (props.grow === true) style.flexGrow = 1;
+    if (typeof props.class === "string") className = props.class;
+  }
+  return { style, className };
+}
+
+function renderChildren(children: WireNode[] | undefined): ReactNode[] {
+  return (children ?? []).map((c, i) => <NodeView key={c.key ?? i} node={c} />);
+}
+
+// TeaInput is semi-controlled: keystrokes echo locally at once and
+// stream to Go; the Go value only overrides the field when it differs
+// from what we last sent (a real remote change, not our own echo
+// arriving late). A pure controlled input over a websocket round trip
+// drops and jumbles fast typing.
+function TeaInput({ node }: { node: WireNode }) {
+  const server = String(node.props?.value ?? "");
+  const [local, setLocal] = useState(server);
+  const lastSent = useRef<string | null>(null);
+  const emit = emitFor(node);
+
+  useEffect(() => {
+    if (lastSent.current === null || server !== lastSent.current) {
+      setLocal(server);
+      lastSent.current = null;
+    } else if (server === lastSent.current) {
+      lastSent.current = null;
+    }
+  }, [server]);
+
+  return (
+    <input
+      className="gantry-tea-input"
+      type="text"
+      value={local}
+      placeholder={typeof node.props?.placeholder === "string" ? node.props.placeholder : undefined}
+      onChange={(e) => {
+        setLocal(e.target.value);
+        lastSent.current = e.target.value;
+        emit("change", e.target.value);
+      }}
+    />
+  );
+}
+
+function NodeView({ node }: { node: WireNode }) {
+  const { style, className } = styleHints(node.props);
+  const cls = (base: string) => base + (className ? " " + className : "");
+  const emit = emitFor(node);
+
+  switch (node.type) {
+    case "column":
+      return (
+        <div className={cls("gantry-tea-column")} style={style}>
+          {renderChildren(node.children)}
+        </div>
+      );
+    case "row":
+      return (
+        <div className={cls("gantry-tea-row")} style={style}>
+          {renderChildren(node.children)}
+        </div>
+      );
+    case "text":
+      return (
+        <span className={cls("gantry-tea-text")} style={style}>
+          {String(node.props?.text ?? "")}
+        </span>
+      );
+    case "heading":
+      return (
+        <h2 className={cls("gantry-tea-heading")} style={style}>
+          {String(node.props?.text ?? "")}
+        </h2>
+      );
+    case "button":
+      return (
+        <button
+          type="button"
+          className={cls("gantry-tea-button")}
+          style={style}
+          onClick={() => emit("click")}
+        >
+          {String(node.props?.label ?? "")}
+        </button>
+      );
+    case "input":
+      return <TeaInput node={node} />;
+    case "checkbox":
+      return (
+        <label className={cls("gantry-tea-checkbox")} style={style}>
+          <input
+            type="checkbox"
+            checked={node.props?.checked === true}
+            onChange={(e) => emit("change", e.target.checked)}
+          />
+          <span>{String(node.props?.label ?? "")}</span>
+        </label>
+      );
+    case "select":
+      return (
+        <select
+          className={cls("gantry-tea-select")}
+          style={style}
+          value={String(node.props?.value ?? "")}
+          onChange={(e) => emit("change", e.target.value)}
+        >
+          {((node.props?.options as string[]) ?? []).map((o) => (
+            <option key={o} value={o}>
+              {o}
+            </option>
+          ))}
+        </select>
+      );
+    case "divider":
+      return <hr className="gantry-tea-divider" />;
+    case "spacer":
+      return <div className="gantry-tea-spacer" />;
+    case "progress": {
+      const v = Math.min(1, Math.max(0, Number(node.props?.value ?? 0)));
+      return (
+        <div className={cls("gantry-tea-progress")} style={style}>
+          <div className="gantry-tea-progress-fill" style={{ width: (v * 100).toFixed(1) + "%" }} />
+        </div>
+      );
+    }
+    default: {
+      const Custom = appRegistry[node.type];
+      if (Custom) {
+        return createElement(Custom, { node, emit }, renderChildren(node.children));
+      }
+      return <div className="gantry-tea-unknown">[unknown component: {node.type}]</div>;
+    }
+  }
+}
+
+/**
+ * TeaView renders the Go-driven tree for the current page. Put one in
+ * any page whose .go half has a Model; pages without a Model simply do
+ * not use it.
+ */
+export function TeaView() {
+  const [tree, setTree] = useState<WireNode | null>(null);
+  useEffect(() => {
+    connect();
+    onRender(setTree);
+    return () => onRender(null);
+  }, []);
+  if (!tree) return null;
+  return <NodeView node={tree} />;
+}

package/src/tea/index.ts

@@ -0,0 +1,5 @@
+export { TeaView, setRegistry } from "./Runtime";
+export type { TeaComponentProps, ComponentRegistry } from "./Runtime";
+export { usePaired } from "../paired";
+export type { Paired } from "../paired";
+export type { WireNode } from "../socket";

package/src/vite/index.js

@@ -0,0 +1,203 @@
+// The Gantry Vite plugin. Plain JavaScript on purpose: vite.config is
+// executed by Node, which cannot load TypeScript out of node_modules.
+//
+// What it does:
+//   - scans <appRoot>/pages/** and <appRoot>/components/** for paired
+//     <name>/<name>.tsx files and generates the virtual:gantry-app
+//     module (route table + component registry, keyed by folder path)
+//   - auto-imports <appRoot>/index.css and every colocated same-name
+//     .css (root css first, so per-pair css can override variables)
+//   - injects the pairing key into bare usePaired() calls, derived from
+//     the file's folder path, so the tsx never repeats it
+//   - proxies /api and /gantry/ws to the Go server during gantry dev
+//   - watches pages/ and components/ so adding or removing a pair
+//     regenerates the app without restarting the dev server
+
+import fs from "node:fs";
+import path from "node:path";
+
+const VIRTUAL_ID = "virtual:gantry-app";
+const RESOLVED_ID = "\0" + VIRTUAL_ID;
+
+/**
+ * @param {{ appRoot?: string, goPort?: number }} [opts]
+ * @returns {import("vite").Plugin}
+ */
+export function gantry(opts = {}) {
+  /** @type {string} */
+  let appRoot = "";
+  let goPort = opts.goPort ?? 0;
+
+  function scanKind(kind) {
+    const dir = path.join(appRoot, kind);
+    const out = [];
+    if (!fs.existsSync(dir)) return out;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const name = entry.name;
+      const tsx = path.join(dir, name, name + ".tsx");
+      if (!fs.existsSync(tsx)) continue;
+      const css = path.join(dir, name, name + ".css");
+      out.push({
+        key: kind + "/" + name,
+        name,
+        tsx: tsx.split(path.sep).join("/"),
+        css: fs.existsSync(css) ? css.split(path.sep).join("/") : null,
+      });
+    }
+    out.sort((a, b) => a.key.localeCompare(b.key));
+    return out;
+  }
+
+  function generate() {
+    const pages = scanKind("pages");
+    const components = scanKind("components");
+    const lines = [];
+
+    const layouts = scanKind("layouts");
+
+    const rootCss = path.join(appRoot, "index.css");
+    if (fs.existsSync(rootCss)) {
+      lines.push(`import ${JSON.stringify(rootCss.split(path.sep).join("/"))};`);
+    }
+    for (const item of [...layouts, ...pages, ...components]) {
+      if (item.css) lines.push(`import ${JSON.stringify(item.css)};`);
+    }
+
+    layouts.forEach((l, i) => {
+      lines.push(`import * as l${i} from ${JSON.stringify(l.tsx)};`);
+    });
+
+    // Optional root app.tsx: default-exports CreateAppOptions so apps
+    // customize createApp (TitleBar slots, title placement, extra
+    // components) without owning the synthesized entry file.
+    const appTsx = path.join(appRoot, "app.tsx");
+    if (fs.existsSync(appTsx)) {
+      lines.push(`import * as appMod from ${JSON.stringify(appTsx.split(path.sep).join("/"))};`);
+      lines.push(`export const appConfig = appMod;`);
+    } else {
+      lines.push(`export const appConfig = null;`);
+    }
+
+    pages.forEach((p, i) => {
+      lines.push(`import * as p${i} from ${JSON.stringify(p.tsx)};`);
+    });
+    components.forEach((c, i) => {
+      lines.push(`import * as c${i} from ${JSON.stringify(c.tsx)};`);
+    });
+
+    const pageEntries = pages.map((p, i) => {
+      // The derived route only; an optional "export const route" on the
+      // page module overrides it at runtime (createApp checks mod.route
+      // there - referencing it here would make rollup warn on every
+      // page that does not export it).
+      const route = p.name === "index" ? "/" : "/" + p.name;
+      return `{ key: ${JSON.stringify(p.key)}, route: ${JSON.stringify(route)}, mod: p${i} }`;
+    });
+    lines.push(`export const pages = [${pageEntries.join(", ")}];`);
+
+    const compEntries = components.map((c, i) => `${JSON.stringify(c.key)}: c${i}`);
+    lines.push(`export const components = { ${compEntries.join(", ")} };`);
+
+    // Layouts are keyed by their short name: layouts/main -> "main",
+    // which is what pages reference in "export const layout".
+    const layoutEntries = layouts.map((l, i) => `${JSON.stringify(l.name)}: l${i}`);
+    lines.push(`export const layouts = { ${layoutEntries.join(", ")} };`);
+    lines.push(`export const singlePage = ${pages.length <= 1};`);
+    return lines.join("\n");
+  }
+
+  /** Derive the pairing key when id is a paired tsx/css file. */
+  function keyFor(id) {
+    const file = id.split("?")[0].split(path.sep).join("/");
+    const root = appRoot.split(path.sep).join("/");
+    if (!file.startsWith(root + "/")) return null;
+    const rel = file.slice(root.length + 1);
+    const m = rel.match(/^(pages|components|layouts)\/([^/]+)\/([^/]+)\.tsx$/);
+    if (!m || m[2] !== m[3]) return null;
+    return m[1] + "/" + m[2];
+  }
+
+  return {
+    name: "gantry",
+
+    config(userConfig, { command }) {
+      const cfgRoot = userConfig.root
+        ? path.resolve(userConfig.root)
+        : process.cwd();
+      appRoot = path.resolve(cfgRoot, opts.appRoot ?? "..");
+
+      if (!goPort) {
+        try {
+          const cfg = JSON.parse(fs.readFileSync(path.join(appRoot, "gantry.json"), "utf8"));
+          goPort = cfg.port ?? 8330;
+        } catch {
+          goPort = 8330;
+        }
+      }
+      const target = "http://127.0.0.1:" + goPort;
+
+      return {
+        // gantry-web ships TypeScript source through an npm file: link;
+        // excluding it from prebundling keeps it in the normal
+        // transform pipeline (plugin-react handles its tsx), and
+        // deduping react avoids a second copy through the symlink.
+        optimizeDeps: { exclude: ["gantry-web"] },
+        // dedupe makes imports inside the symlinked gantry-web source
+        // resolve from the APP's node_modules (the package itself has
+        // none) and guarantees a single React instance.
+        resolve: { dedupe: ["react", "react-dom", "lucide-react"] },
+        server:
+          command === "serve"
+            ? {
+                proxy: {
+                  "/api": { target },
+                  "/gantry/ws": { target, ws: true },
+                },
+              }
+            : undefined,
+      };
+    },
+
+    resolveId(id) {
+      if (id === VIRTUAL_ID) return RESOLVED_ID;
+      return null;
+    },
+
+    load(id) {
+      if (id === RESOLVED_ID) return generate();
+      return null;
+    },
+
+    transform(code, id) {
+      const key = keyFor(id);
+      if (key && code.includes("usePaired()")) {
+        return code.replaceAll("usePaired()", `usePaired(${JSON.stringify(key)})`);
+      }
+      return null;
+    },
+
+    configureServer(server) {
+      server.watcher.add(appRoot);
+      const refresh = (file) => {
+        const f = file.split(path.sep).join("/");
+        const root = appRoot.split(path.sep).join("/");
+        if (!f.startsWith(root)) return;
+        if (
+          !/\/(pages|components|layouts)\/[^/]+\/[^/]+\.(tsx|css)$/.test(f) &&
+          !f.endsWith("/index.css") &&
+          !f.endsWith("/app.tsx")
+        ) {
+          return;
+        }
+        const mod = server.moduleGraph.getModuleById(RESOLVED_ID);
+        if (mod) server.moduleGraph.invalidateModule(mod);
+        server.ws.send({ type: "full-reload" });
+      };
+      server.watcher.on("add", refresh);
+      server.watcher.on("unlink", refresh);
+    },
+  };
+}
+
+export default gantry;