gantry-web 0.1.0

package/src/paired.ts

@@ -0,0 +1,57 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { callGo, connect, onPush, sendPaired } from "./socket";
+
+export interface Paired {
+  /** send fires a named event on this file's .go half (ui.Handlers). */
+  send: (event: string, payload?: unknown) => void;
+  /** call awaits a function on the .go half (ui.Calls). */
+  call: <T = unknown>(name: string, payload?: unknown) => Promise<T>;
+  /** on subscribes to pushes from Go (App.Push); returns unsubscribe. */
+  on: (event: string, fn: (payload: unknown) => void) => () => void;
+  /**
+   * state is the latest payload Go pushed with the event name "state" -
+   * the simple way to mirror Go-side data into the component.
+   */
+  state: unknown;
+}
+
+/**
+ * usePaired is the channel between a .tsx file and the .go file sitting
+ * next to it. Inside pages/ and components/ call it with no argument -
+ * the Gantry Vite plugin fills the key in from the folder path at build
+ * time. Anywhere else, pass the key explicitly: usePaired("pages/index").
+ */
+export function usePaired(key?: string): Paired {
+  if (!key) {
+    throw new Error(
+      "usePaired(): no key. Inside pages/ or components/ the Gantry Vite " +
+        "plugin injects it - make sure the file is under the app root and " +
+        "the gantry() plugin is in vite.config. Elsewhere pass the key " +
+        'explicitly, e.g. usePaired("pages/index").',
+    );
+  }
+  const k = key;
+  const [state, setState] = useState<unknown>(undefined);
+
+  useEffect(() => {
+    connect();
+    return onPush(k, (event, payload) => {
+      if (event === "state") setState(payload);
+    });
+  }, [k]);
+
+  const send = useCallback((event: string, payload?: unknown) => sendPaired(k, event, payload), [k]);
+  const call = useCallback(
+    <T,>(name: string, payload?: unknown) => callGo(k, name, payload) as Promise<T>,
+    [k],
+  );
+  const on = useCallback(
+    (event: string, fn: (payload: unknown) => void) =>
+      onPush(k, (e, payload) => {
+        if (e === event) fn(payload);
+      }),
+    [k],
+  );
+
+  return useMemo(() => ({ send, call, on, state }), [send, call, on, state]);
+}

package/src/router.tsx

@@ -0,0 +1,154 @@
+// Tiny pathname router shared by createApp, Link and useRoute. No
+// dependency, history-API based: navigate() pushes, back/forward work,
+// and every subscriber re-renders on change.
+
+import {
+  useSyncExternalStore,
+  type AnchorHTMLAttributes,
+  type ReactNode,
+} from "react";
+import { getShell } from "./bridge";
+
+const listeners = new Set<() => void>();
+
+function notify() {
+  for (const fn of listeners) fn();
+}
+
+if (typeof window !== "undefined") {
+  window.addEventListener("popstate", notify);
+}
+
+/** navigate switches pages without a full reload. */
+export function navigate(path: string): void {
+  if (location.pathname !== path) {
+    history.pushState(null, "", path);
+  }
+  notify();
+}
+
+/** redirect replaces the current URL (no history entry) - used when a
+ * route no longer exists and the app falls back to another page. */
+export function redirect(path: string): void {
+  if (location.pathname !== path) {
+    history.replaceState(null, "", path);
+  }
+  notify();
+}
+
+/** goBack navigates back through the page history (popstate re-renders). */
+export function goBack(): void {
+  history.back();
+}
+
+/** goForward navigates forward through the page history. */
+export function goForward(): void {
+  history.forward();
+}
+
+function subscribe(fn: () => void): () => void {
+  listeners.add(fn);
+  return () => listeners.delete(fn);
+}
+
+/** useRoute returns the current pathname; re-renders on navigation. */
+export function useRoute(): string {
+  return useSyncExternalStore(subscribe, () => location.pathname);
+}
+
+/** isActive: exact match, or prefix match when exact is false. */
+export function isActive(path: string, to: string, exact = true): boolean {
+  const clean = path !== "/" && path.endsWith("/") ? path.slice(0, -1) : path;
+  if (exact || to === "/") return clean === to;
+  return clean === to || clean.startsWith(to + "/");
+}
+
+export interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+  /** Route to navigate to, e.g. "/settings". */
+  to: string;
+  /** Extra class applied while the link's route is current. */
+  activeClassName?: string;
+  /** Match route prefixes too ("/docs" active on "/docs/intro"). */
+  matchPrefix?: boolean;
+  children?: ReactNode;
+}
+
+/**
+ * Link navigates between pages and knows when it is the current one:
+ * it sets data-active="true"/"false" (style with
+ * [data-active="true"] in css, or data-[active=true]: variants in
+ * Tailwind), aria-current="page", and appends activeClassName when
+ * given.
+ */
+export interface ExternalLinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+  /** The external URL to open. */
+  href: string;
+  prefix?: string;
+  children?: ReactNode;
+}
+
+/**
+ * ExternalLink opens a URL in the user's DEFAULT BROWSER instead of
+ * navigating the app's webview, and (in the native window) renders
+ * without an href so no URL-preview bubble ever appears. In a plain
+ * browser tab it falls back to a normal new-tab link.
+ */
+export function ExternalLink({ href, prefix, children, onClick, ...rest }: ExternalLinkProps) {
+  const shell = getShell(prefix);
+  if (!shell.available) {
+    return (
+      <a href={href} target="_blank" rel="noreferrer" onClick={onClick} {...rest}>
+        {children}
+      </a>
+    );
+  }
+  return (
+    <a
+      role="link"
+      tabIndex={0}
+      onClick={(e) => {
+        onClick?.(e);
+        if (!e.defaultPrevented) shell.openExternal(href);
+      }}
+      onKeyDown={(e) => {
+        if (e.key === "Enter") shell.openExternal(href);
+      }}
+      {...rest}
+    >
+      {children}
+    </a>
+  );
+}
+
+export function Link({ to, activeClassName, matchPrefix, className, children, onClick, ...rest }: LinkProps) {
+  const path = useRoute();
+  const active = isActive(path, to, !matchPrefix);
+  const cls = [className, active ? activeClassName : undefined].filter(Boolean).join(" ");
+  // Deliberately NO href: navigation is client-side anyway, and an
+  // href makes the webview show the URL preview bubble in the bottom
+  // corner on hover - a browser artifact that looks wrong in a
+  // desktop app. role/tabIndex/keyboard keep it accessible.
+  return (
+    <a
+      role="link"
+      tabIndex={0}
+      className={cls || undefined}
+      data-active={active ? "true" : "false"}
+      aria-current={active ? "page" : undefined}
+      onClick={(e) => {
+        onClick?.(e);
+        if (e.defaultPrevented || e.button !== 0) return;
+        navigate(to);
+      }}
+      onKeyDown={(e) => {
+        if (e.key === "Enter" || e.key === " ") {
+          e.preventDefault();
+          navigate(to);
+        }
+      }}
+      {...rest}
+    >
+      {children}
+    </a>
+  );
+}

package/src/service.ts

@@ -0,0 +1,82 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { callGo, connect } from "./socket";
+
+export interface Service {
+  /** call awaits a Go function registered on this service (ui.Calls). */
+  call: <T = unknown>(name: string, payload?: unknown) => Promise<T>;
+}
+
+/** service returns a plain (non-hook) handle usable anywhere. */
+export function service(name: string): Service {
+  connect();
+  return {
+    call: <T,>(fn: string, payload?: unknown) => callGo(name, fn, payload) as Promise<T>,
+  };
+}
+
+/**
+ * useService is the hook form - the building block for app hooks like
+ * useAuth():
+ *
+ *	function useAuth() {
+ *	  const auth = useService("auth");
+ *	  const me = useCall<User>("auth", "me");
+ *	  return { ...me, login: (u: string, p: string) => auth.call("login", { u, p }) };
+ *	}
+ *
+ * The Go side registers the functions once:
+ *
+ *	app.Service("auth", ui.Calls{ "me": ..., "login": ... })
+ */
+export function useService(name: string): Service {
+  return useMemo(() => service(name), [name]);
+}
+
+export interface CallResult<T> {
+  data: T | undefined;
+  error: string | null;
+  loading: boolean;
+  /** reload re-runs the call. */
+  reload: () => void;
+}
+
+/**
+ * useCall runs a Go call on mount (and when key/name/payload change)
+ * and hands back { data, error, loading, reload } - the fetch-shaped
+ * companion to useService for read paths.
+ */
+export function useCall<T = unknown>(key: string, name: string, payload?: unknown): CallResult<T> {
+  const [data, setData] = useState<T | undefined>(undefined);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [tick, setTick] = useState(0);
+  const alive = useRef(true);
+  const payloadKey = JSON.stringify(payload ?? null);
+
+  useEffect(() => {
+    alive.current = true;
+    setLoading(true);
+    setError(null);
+    callGo(key, name, payload)
+      .then((v) => {
+        if (alive.current) {
+          setData(v as T);
+          setLoading(false);
+        }
+      })
+      .catch((e: Error) => {
+        if (alive.current) {
+          setError(e.message);
+          setLoading(false);
+        }
+      });
+    return () => {
+      alive.current = false;
+    };
+    // payloadKey stands in for payload identity.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key, name, payloadKey, tick]);
+
+  const reload = useCallback(() => setTick((t) => t + 1), []);
+  return { data, error, loading, reload };
+}

package/src/socket.ts

@@ -0,0 +1,187 @@
+// One websocket connects the frontend to the Go ui.App: Tea renders
+// come down, events go up, paired pushes fan out. Reconnects with
+// backoff (webview reloads, dev server restarts, HMR) and re-announces
+// the active page on every connect so the server always re-renders.
+
+export type WireNode = {
+  type: string;
+  key?: string;
+  props?: Record<string, unknown>;
+  handlers?: Record<string, string>;
+  children?: WireNode[];
+};
+
+type RenderListener = (tree: WireNode) => void;
+type PushListener = (event: string, payload: unknown) => void;
+type StateListener = () => void;
+
+let ws: WebSocket | null = null;
+let url = "";
+let activePage = "";
+let backoff = 300;
+let renderListener: RenderListener | null = null;
+const pushListeners = new Map<string, Set<PushListener>>();
+const sendQueue: string[] = [];
+
+// Awaited calls: id -> resolver, with a timeout so a dead server
+// cannot leak promises forever.
+let nextCallId = 0;
+const pending = new Map<string, { resolve: (v: unknown) => void; reject: (e: Error) => void; timer: number }>();
+
+// Shared Go state (useGoState): the latest value per key + subscribers.
+const stateValues = new Map<string, unknown>();
+const stateListeners = new Map<string, Set<StateListener>>();
+
+function defaultURL(): string {
+  const proto = location.protocol === "https:" ? "wss:" : "ws:";
+  return proto + "//" + location.host + "/gantry/ws";
+}
+
+/** connect opens (or reuses) the app socket. createApp calls this. */
+export function connect(customURL?: string): void {
+  if (ws) return;
+  url = customURL ?? url ?? "";
+  if (!url) url = defaultURL();
+  open();
+}
+
+function open(): void {
+  const sock = new WebSocket(url);
+  ws = sock;
+  sock.onopen = () => {
+    backoff = 300;
+    if (activePage) sock.send(JSON.stringify({ t: "ready", page: activePage }));
+    while (sendQueue.length > 0) sock.send(sendQueue.shift() as string);
+  };
+  sock.onmessage = (e) => {
+    let msg: {
+      t: string;
+      tree?: WireNode;
+      key?: string;
+      name?: string;
+      p?: unknown;
+      id?: string;
+      ok?: boolean;
+      err?: string;
+    };
+    try {
+      msg = JSON.parse(e.data as string);
+    } catch {
+      return;
+    }
+    if (msg.t === "render" && msg.tree) {
+      renderListener?.(msg.tree);
+    } else if (msg.t === "push" && msg.key && msg.name) {
+      pushListeners.get(msg.key)?.forEach((fn) => fn(msg.name as string, msg.p));
+    } else if (msg.t === "reply" && msg.id) {
+      const p = pending.get(msg.id);
+      if (p) {
+        pending.delete(msg.id);
+        clearTimeout(p.timer);
+        if (msg.ok) p.resolve(msg.p);
+        else p.reject(new Error(msg.err ?? "call failed"));
+      }
+    } else if (msg.t === "state" && msg.key) {
+      stateValues.set(msg.key, msg.p);
+      stateListeners.get(msg.key)?.forEach((fn) => fn());
+    }
+  };
+  sock.onclose = () => {
+    if (ws !== sock) return; // superseded
+    ws = null;
+    setTimeout(() => {
+      if (!ws) open();
+    }, backoff);
+    backoff = Math.min(backoff * 2, 5000);
+  };
+  sock.onerror = () => sock.close();
+}
+
+function send(obj: unknown): void {
+  const data = JSON.stringify(obj);
+  if (ws && ws.readyState === WebSocket.OPEN) {
+    ws.send(data);
+  } else {
+    sendQueue.push(data);
+    connect();
+  }
+}
+
+/** ready announces the mounted page; the server activates its Model. */
+export function ready(pageKey: string): void {
+  activePage = pageKey;
+  send({ t: "ready", page: pageKey });
+}
+
+/** sendTeaEvent fires a Tea handler by its render-generation id. */
+export function sendTeaEvent(handlerId: string, payload?: unknown): void {
+  send({ t: "event", h: handlerId, p: payload });
+}
+
+/** sendPaired fires a named event on a page/component's Go half. */
+export function sendPaired(key: string, name: string, payload?: unknown): void {
+  send({ t: "event", key, name, p: payload });
+}
+
+/** onRender subscribes the (single) Tea tree consumer. */
+export function onRender(fn: RenderListener | null): void {
+  renderListener = fn;
+}
+
+/** onPush subscribes to pushes for one paired key; returns unsubscribe. */
+export function onPush(key: string, fn: PushListener): () => void {
+  let set = pushListeners.get(key);
+  if (!set) {
+    set = new Set();
+    pushListeners.set(key, set);
+  }
+  set.add(fn);
+  return () => {
+    set.delete(fn);
+    if (set.size === 0) pushListeners.delete(key);
+  };
+}
+
+/** callGo awaits a Go function: a pair's Call entry or a service's. */
+export function callGo(key: string, name: string, payload?: unknown, timeoutMs = 30_000): Promise<unknown> {
+  const id = "c" + ++nextCallId;
+  return new Promise((resolve, reject) => {
+    const timer = window.setTimeout(() => {
+      pending.delete(id);
+      reject(new Error(`call ${key}.${name} timed out`));
+    }, timeoutMs);
+    pending.set(id, { resolve, reject, timer });
+    send({ t: "call", key, name, id, p: payload });
+  });
+}
+
+/** getGoState reads the latest synced value for a state key. */
+export function getGoState(key: string): unknown {
+  return stateValues.get(key);
+}
+
+/** hasGoState reports whether the server has sent this key yet. */
+export function hasGoState(key: string): boolean {
+  return stateValues.has(key);
+}
+
+/** setGoState applies a local write and sends it to Go (no echo). */
+export function setGoState(key: string, value: unknown): void {
+  stateValues.set(key, value);
+  stateListeners.get(key)?.forEach((fn) => fn());
+  send({ t: "setstate", key, p: value });
+}
+
+/** onGoState subscribes to changes of one state key. */
+export function onGoState(key: string, fn: StateListener): () => void {
+  let set = stateListeners.get(key);
+  if (!set) {
+    set = new Set();
+    stateListeners.set(key, set);
+  }
+  set.add(fn);
+  return () => {
+    set.delete(fn);
+    if (set.size === 0) stateListeners.delete(key);
+  };
+}