gantry-web 0.1.0

package/README.md

@@ -0,0 +1,47 @@
+# gantry-web
+
+The frontend half of [Gantry](https://github.com/B-Commissions/Gantry),
+a Go framework for building native desktop apps with React interfaces.
+This package provides the window chrome, the bridge to the native
+window, the Tea runtime, the router, and the Vite plugin that powers
+Gantry's paired-file convention.
+
+You normally do not install this by hand - `gantry new` scaffolds an
+app with it wired up. See the
+[Gantry documentation](https://github.com/B-Commissions/Gantry/tree/main/docs)
+or run `gantry docs` for the full story.
+
+## What it exports
+
+From `gantry-web`:
+
+- `TitleBar`, `DragStrip`, `ResizeFrame` - the custom window chrome
+- `getShell` / `useShell` / `useShellCaps` - the typed native bridge
+  (close, minimize, maximize, drag, attention, always-on-top), with
+  feature detection so the same app runs in a plain browser tab
+- `createApp` - boots a Gantry frontend (router, layouts, registry)
+- `Link`, `ExternalLink`, `navigate`, `goBack`, `goForward`,
+  `useRoute`, `isActive` - navigation with active-state styling
+- `usePaired` - the channel between a .tsx file and the .go file next
+  to it (send events, await calls, receive pushes)
+- `useService`, `useCall`, `service` - awaited calls into Go services
+- `useGoState` - useState whose value lives in Go, synced both ways
+- `installZoomGuard` - suppress browser zoom gestures
+
+From `gantry-web/tea`:
+
+- `TeaView` - renders a page whose UI logic lives in Go
+  (Model/Update/View)
+- `TeaComponentProps`, `setRegistry` - custom component integration
+
+From `gantry-web/vite`:
+
+- `gantry()` - the Vite plugin: discovers pages/, components/ and
+  layouts/ folders, auto-imports colocated css, injects pairing keys,
+  and proxies to the Go server during development
+
+## Peer dependencies
+
+react and react-dom (18+), lucide-react for the chrome icons, and vite
+(only when using the plugin). The package ships TypeScript source
+directly; Vite consumes it as-is.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "gantry-web",
+  "version": "0.1.0",
+  "description": "Frontend half of the Gantry desktop app framework: window chrome, native bridge, Tea runtime, Vite plugin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/B-Commissions/Gantry.git",
+    "directory": "web"
+  },
+  "homepage": "https://github.com/B-Commissions/Gantry",
+  "keywords": [
+    "gantry",
+    "desktop",
+    "webview",
+    "go",
+    "react",
+    "vite-plugin"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./tea": "./src/tea/index.ts",
+    "./vite": "./src/vite/index.js",
+    "./styles.css": "./src/styles.css",
+    "./types": "./types/index.d.ts"
+  },
+  "files": [
+    "src",
+    "types"
+  ],
+  "peerDependencies": {
+    "lucide-react": "*",
+    "react": ">=18",
+    "react-dom": ">=18",
+    "vite": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  }
+}

package/src/DragStrip.tsx

@@ -0,0 +1,36 @@
+import { useShell } from "./hooks";
+
+export interface DragStripProps {
+  /** Height in px; must match the Go window's CaptionHeight (default 40). */
+  height?: number;
+  /** Dead zone on the left; match CaptionLeftReserve (default 8). */
+  leftInset?: number;
+  /** Dead zone on the right for the window buttons; match CaptionRightReserve (default 150). */
+  rightInset?: number;
+  prefix?: string;
+}
+
+/**
+ * DragStrip is the invisible band along the top of the window that
+ * starts a native drag on mousedown - the frameless window's "title
+ * bar surface". TitleBar renders one for you; use this directly only
+ * for fully custom chrome.
+ *
+ * Ignores double-clicks so a quick double-tap cannot trigger the OS
+ * caption double-click maximize.
+ */
+export function DragStrip({ height = 40, leftInset = 8, rightInset = 150, prefix }: DragStripProps) {
+  const shell = useShell(prefix);
+  if (!shell.available) return null;
+  return (
+    <div
+      className="gantry-dragstrip"
+      style={{ height, left: leftInset, right: rightInset }}
+      onMouseDown={(e) => {
+        if (e.button !== 0 || e.detail > 1) return;
+        e.preventDefault();
+        shell.drag();
+      }}
+    />
+  );
+}

package/src/ResizeFrame.tsx

@@ -0,0 +1,40 @@
+import { useShell, useShellCaps } from "./hooks";
+
+const EDGES = [
+  { edge: "n", style: { top: 0, left: 8, right: 8, height: 5, cursor: "ns-resize" } },
+  { edge: "s", style: { bottom: 0, left: 8, right: 8, height: 5, cursor: "ns-resize" } },
+  { edge: "w", style: { left: 0, top: 8, bottom: 8, width: 5, cursor: "ew-resize" } },
+  { edge: "e", style: { right: 0, top: 8, bottom: 8, width: 5, cursor: "ew-resize" } },
+  { edge: "nw", style: { top: 0, left: 0, width: 10, height: 10, cursor: "nwse-resize" } },
+  { edge: "ne", style: { top: 0, right: 0, width: 10, height: 10, cursor: "nesw-resize" } },
+  { edge: "sw", style: { bottom: 0, left: 0, width: 10, height: 10, cursor: "nesw-resize" } },
+  { edge: "se", style: { bottom: 0, right: 0, width: 10, height: 10, cursor: "nwse-resize" } },
+] as const;
+
+/**
+ * ResizeFrame renders invisible edge strips that start a native
+ * interactive resize - needed on Linux, where a frameless window has
+ * no OS hit-test to re-implement edges (Windows handles this natively,
+ * so there the component renders nothing). createApp adds one
+ * automatically on frameless Linux windows.
+ */
+export function ResizeFrame({ prefix }: { prefix?: string }) {
+  const shell = useShell(prefix);
+  const caps = useShellCaps(prefix);
+  if (caps?.platform !== "linux" || !caps.frameless) return null;
+  return (
+    <>
+      {EDGES.map(({ edge, style }) => (
+        <div
+          key={edge}
+          style={{ position: "fixed", zIndex: 40, ...style }}
+          onMouseDown={(e) => {
+            if (e.button !== 0) return;
+            e.preventDefault();
+            shell.resizeEdge(edge);
+          }}
+        />
+      ))}
+    </>
+  );
+}

package/src/TitleBar.tsx

@@ -0,0 +1,137 @@
+import { useEffect, useState, type ReactNode } from "react";
+import { Minus, Square, Copy, X } from "lucide-react";
+import { useShell, useShellCaps } from "./hooks";
+import { DragStrip } from "./DragStrip";
+
+export interface TitleBarProps {
+  /** Title content. Pointer-transparent so the bar stays draggable. */
+  title?: ReactNode;
+  /** Where the title sits: "center" (default), "left" or "right". */
+  titleAlign?: "left" | "center" | "right";
+  /** Extra content on the left (back/forward buttons, a menu, an icon). */
+  left?: ReactNode;
+  /** Extra content on the right, before the window buttons. */
+  right?: ReactNode;
+  /** Bar height in px; MUST match the Go window's CaptionHeight (default 40). */
+  height?: number;
+  /**
+   * Width reserved for the button cluster; MUST match the Go window's
+   * CaptionRightReserve (default 150). The Go side keeps this zone
+   * clickable instead of draggable.
+   */
+  rightReserve?: number;
+  /**
+   * Width of the clickable zone on the left; MUST match the Go window's
+   * CaptionLeftReserve when you put buttons in the left slot (default
+   * 8 - bump it, e.g. 90, so left-slot buttons receive clicks).
+   */
+  leftReserve?: number;
+  /** Override the Caps()-driven visibility per button. */
+  showMinimize?: boolean;
+  showMaximize?: boolean;
+  showClose?: boolean;
+  /** Tooltip for the close button, e.g. "Keeps running in the tray". */
+  closeHint?: string;
+  /** Replace the default close action (shell.close). */
+  onClose?: () => void;
+  prefix?: string;
+  className?: string;
+}
+
+/**
+ * TitleBar draws the custom window chrome: a drag strip, a title
+ * (left, center or right), your own controls in the left/right slots,
+ * and the window buttons. Which window buttons appear comes from the
+ * Go window's Caps() - configure buttons once, in Go. In a plain
+ * browser the window buttons hide themselves.
+ *
+ * Apps customize it app-wide from app.tsx:
+ *
+ *	export default {
+ *	  title: "Myapp",
+ *	  titleBar: { titleAlign: "left", left: <NavButtons />, leftReserve: 90 },
+ *	} satisfies CreateAppOptions;
+ */
+export function TitleBar(props: TitleBarProps) {
+  const {
+    title,
+    titleAlign = "center",
+    left,
+    right,
+    height = 40,
+    rightReserve = 150,
+    leftReserve = 8,
+    closeHint,
+    onClose,
+    prefix,
+    className,
+  } = props;
+  const shell = useShell(prefix);
+  const caps = useShellCaps(prefix);
+  const [maximized, setMaximized] = useState(false);
+
+  const showMin = props.showMinimize ?? caps?.minimize ?? false;
+  const showMax = props.showMaximize ?? caps?.maximize ?? false;
+  const showClose = props.showClose ?? caps?.close ?? false;
+
+  useEffect(() => {
+    if (showMax) void shell.isMaximized().then(setMaximized);
+  }, [shell, showMax]);
+
+  const titleEl =
+    title != null ? <div className="gantry-titlebar-text">{title}</div> : null;
+
+  return (
+    <div className={"gantry-titlebar " + (className ?? "")} style={{ height }}>
+      <DragStrip height={height} leftInset={leftReserve} rightInset={rightReserve} prefix={prefix} />
+      <div className="gantry-titlebar-left">
+        {left}
+        {titleAlign === "left" && titleEl}
+      </div>
+      {titleAlign === "center" && title != null && (
+        <div className="gantry-titlebar-title" style={{ lineHeight: height + "px" }}>
+          {title}
+        </div>
+      )}
+      <div className="gantry-titlebar-end">
+        {titleAlign === "right" && titleEl}
+        {right != null && <div className="gantry-titlebar-right">{right}</div>}
+        {showMin && (
+          <button
+            type="button"
+            className="gantry-winbtn"
+            aria-label="Minimize"
+            onClick={() => shell.minimize()}
+          >
+            <Minus size={16} />
+          </button>
+        )}
+        {showMax && (
+          <button
+            type="button"
+            className="gantry-winbtn"
+            aria-label={maximized ? "Restore" : "Maximize"}
+            onClick={() => {
+              if (maximized) shell.restore();
+              else shell.maximize();
+              setMaximized(!maximized);
+            }}
+          >
+            {maximized ? <Copy size={14} /> : <Square size={14} />}
+          </button>
+        )}
+        {showClose && (
+          <button
+            type="button"
+            className="gantry-winbtn gantry-winbtn-close"
+            aria-label="Close"
+            title={closeHint}
+            onClick={() => (onClose ? onClose() : shell.close())}
+          >
+            <X size={16} />
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/app.tsx

@@ -0,0 +1,155 @@
+/// <reference path="../types/index.d.ts" />
+import { StrictMode, useEffect, type FC, type ReactNode } from "react";
+import { createRoot } from "react-dom/client";
+import { pages, components as pairedComponents, layouts, appConfig, type GantryPage } from "virtual:gantry-app";
+import { TitleBar, type TitleBarProps } from "./TitleBar";
+import { ResizeFrame } from "./ResizeFrame";
+import { installZoomGuard } from "./zoom";
+import { connect, ready } from "./socket";
+import { useRoute, redirect } from "./router";
+import { setRegistry, type ComponentRegistry, type TeaComponentProps } from "./tea/Runtime";
+import "./styles.css";
+
+export interface CreateAppOptions {
+  /** Title shown in the TitleBar (default: none). */
+  title?: ReactNode;
+  /**
+   * TitleBar customization: title placement (titleAlign), your own
+   * controls in the left/right slots (back/forward buttons, menus),
+   * heights and reserves. The usual home for this is the optional
+   * app.tsx at the app root, default-exporting CreateAppOptions.
+   */
+  titleBar?: Partial<TitleBarProps>;
+  /** Extra Tea components beyond the paired components/ folders. */
+  components?: ComponentRegistry;
+  /** Binding prefix when the Go side changed it from "gantry". */
+  prefix?: string;
+  /** Websocket URL override (default ws://<host>/gantry/ws). */
+  socketURL?: string;
+  /** Hide the TitleBar on every page (pages can also export chrome = false). */
+  chrome?: boolean;
+}
+
+function keyClass(key: string): string {
+  return "gantry-" + key.replace(/[^a-zA-Z0-9]+/g, "-");
+}
+
+function routeOf(p: GantryPage): string {
+  return p.mod.route ?? p.route;
+}
+
+function match(path: string): GantryPage | undefined {
+  const clean = path !== "/" && path.endsWith("/") ? path.slice(0, -1) : path;
+  return pages.find((p) => routeOf(p) === clean) ?? pages.find((p) => routeOf(p) === "/");
+}
+
+function PageHost({ page }: { page: GantryPage }) {
+  useEffect(() => {
+    ready(page.key);
+  }, [page.key]);
+  const Page = page.mod.default;
+  return (
+    <div className={"gantry-page " + keyClass(page.key)}>
+      <Page />
+    </div>
+  );
+}
+
+// layoutsFor resolves a page's layout selection to component functions,
+// outermost first.
+//
+//   (nothing)            -> "main" if it exists (chromeless pages skip)
+//   layout = false       -> none
+//   layout = "compact"   -> that one
+//   layout = ["main","compact"] -> nested: <Main><Compact><Page/>...
+function layoutsFor(page: GantryPage, chrome: boolean): FC<{ children?: ReactNode }>[] {
+  const sel = page.mod.layout;
+  let names: string[];
+  if (sel === false) {
+    names = [];
+  } else if (typeof sel === "string") {
+    names = [sel];
+  } else if (Array.isArray(sel)) {
+    names = sel;
+  } else if (sel === true) {
+    names = layouts.main ? ["main"] : [];
+  } else {
+    // Default: the "main" layout on normal pages; chromeless pages
+    // (widgets, popups) are their own surfaces and skip it.
+    names = chrome && layouts.main ? ["main"] : [];
+  }
+  const out: FC<{ children?: ReactNode }>[] = [];
+  for (const n of names) {
+    const mod = layouts[n];
+    if (mod?.default) {
+      out.push(mod.default);
+    } else {
+      console.warn(`gantry: page ${page.key} wants unknown layout "${n}" (have: ${Object.keys(layouts).join(", ") || "none"})`);
+    }
+  }
+  return out;
+}
+
+function AppRoot({ options }: { options: CreateAppOptions }) {
+  const path = useRoute();
+  const page = match(path);
+  // A URL whose page no longer exists (deleted during dev, stale
+  // bookmark) falls back to the index page - normalize the address so
+  // Links light up correctly.
+  const target = page ? routeOf(page) : null;
+  const clean = path !== "/" && path.endsWith("/") ? path.slice(0, -1) : path;
+  useEffect(() => {
+    if (target !== null && target !== clean) {
+      redirect(target);
+    }
+  }, [target, clean]);
+  if (!page) {
+    return <div className="gantry-app">No pages found - add pages/index/index.tsx</div>;
+  }
+  const chrome = options.chrome !== false && page.mod.chrome !== false;
+  let content = <PageHost page={page} />;
+  for (const Layout of layoutsFor(page, chrome).reverse()) {
+    content = <Layout>{content}</Layout>;
+  }
+  return (
+    <div className="gantry-app">
+      <ResizeFrame prefix={options.prefix} />
+      {chrome && <TitleBar title={options.title} prefix={options.prefix} {...options.titleBar} />}
+      {content}
+    </div>
+  );
+}
+
+/**
+ * createApp boots a Gantry frontend: zoom guard, websocket, component
+ * registry, TitleBar, the root layout (layout.tsx at the app root, if
+ * present), and the page router (single-page mode when only pages/index
+ * exists). The synthesized .gantry/main.tsx calls this; an app only
+ * touches it to pass options.
+ */
+export function createApp(options: CreateAppOptions = {}): void {
+  // The optional root app.tsx wins over the synthesized defaults, so
+  // apps customize everything without owning the entry file.
+  if (appConfig?.default) {
+    options = { ...options, ...appConfig.default };
+  }
+  installZoomGuard();
+  connect(options.socketURL);
+
+  const registry: ComponentRegistry = {};
+  for (const [key, mod] of Object.entries(pairedComponents)) {
+    if (typeof mod.default === "function") {
+      registry[key] = mod.default as FC<TeaComponentProps>;
+    }
+  }
+  Object.assign(registry, options.components);
+  setRegistry(registry);
+
+  const container = document.getElementById("root");
+  if (!container) throw new Error("gantry: no #root element");
+  createRoot(container).render(
+    <StrictMode>
+      <AppRoot options={options} />
+    </StrictMode>,
+  );
+}

package/src/bridge.ts

@@ -0,0 +1,94 @@
+// The native bridge: typed access to the window.<prefix>* functions the
+// Go appshell binds. In a plain browser tab none of them exist, so
+// every method is safe to call anywhere - it just does nothing outside
+// the native window - and `available` tells you which world you are in.
+
+export interface ShellCaps {
+  minimize: boolean;
+  maximize: boolean;
+  close: boolean;
+  alwaysOnTop: boolean;
+  /** "windows" | "linux" - which native host is running. */
+  platform?: string;
+  /** True when the window is frameless (custom chrome active). */
+  frameless?: boolean;
+}
+
+export interface ShellBridge {
+  /** True when running inside a Gantry native window. */
+  available: boolean;
+  close(): void;
+  minimize(): void;
+  /** Start the native window drag loop (call on mousedown). */
+  drag(): void;
+  /** System notification sound + taskbar flash. */
+  attention(): void;
+  maximize(): void;
+  restore(): void;
+  isMaximized(): Promise<boolean>;
+  /** Which window buttons the Go side enabled (all false in a browser). */
+  caps(): Promise<ShellCaps>;
+  /** Widgets and popups: show or hide the native window. */
+  setVisible(show: boolean): void;
+  /** Widgets: resize the native window in place. */
+  resize(width: number, height: number): void;
+  setAlwaysOnTop(on: boolean): void;
+  /** Open a URL in the user's default browser (never in the app). */
+  openExternal(url: string): void;
+  /**
+   * Linux frameless windows: start an interactive resize from an edge
+   * ("n","s","e","w","ne","nw","se","sw"). No-op on Windows, where the
+   * native hit-test handles edges.
+   */
+  resizeEdge(edge: string): void;
+}
+
+type AnyFn = (...args: unknown[]) => unknown;
+
+function fn(prefix: string, name: string): AnyFn | undefined {
+  const w = window as unknown as Record<string, unknown>;
+  const f = w[prefix + name];
+  return typeof f === "function" ? (f as AnyFn) : undefined;
+}
+
+const NO_CAPS: ShellCaps = {
+  minimize: false,
+  maximize: false,
+  close: false,
+  alwaysOnTop: false,
+};
+
+/**
+ * getShell returns the bridge for the given binding prefix. The prefix
+ * must match the Go side's BindingPrefix; both default to "gantry".
+ */
+export function getShell(prefix = "gantry"): ShellBridge {
+  const call = (name: string, ...args: unknown[]) => {
+    const f = fn(prefix, name);
+    if (f) void f(...args);
+  };
+  return {
+    // Minimize is bound on every main window unless disabled, and Close
+    // exists on every window kind, so either marks a native host.
+    available: !!(fn(prefix, "Minimize") ?? fn(prefix, "Close")),
+    close: () => call("Close"),
+    minimize: () => call("Minimize"),
+    drag: () => call("Drag"),
+    attention: () => call("Attention"),
+    maximize: () => call("Maximize"),
+    restore: () => call("Restore"),
+    isMaximized: async () => {
+      const f = fn(prefix, "IsMaximized");
+      return f ? ((await f()) as boolean) : false;
+    },
+    caps: async () => {
+      const f = fn(prefix, "Caps");
+      return f ? ((await f()) as ShellCaps) : NO_CAPS;
+    },
+    setVisible: (show) => call("Visible", show),
+    resize: (w, h) => call("Resize", w, h),
+    setAlwaysOnTop: (on) => call("SetAlwaysOnTop", on),
+    openExternal: (url) => call("OpenExternal", url),
+    resizeEdge: (edge) => call("ResizeEdge", edge),
+  };
+}

package/src/gostate.ts

@@ -0,0 +1,29 @@
+import { useCallback, useSyncExternalStore } from "react";
+import { connect, getGoState, hasGoState, onGoState, setGoState } from "./socket";
+
+/**
+ * useGoState is useState whose value lives in Go. Declare the variable
+ * on the Go side once:
+ *
+ *	volume := ui.NewState(app, "volume", 0.5)
+ *
+ * then use it anywhere in React exactly like useState:
+ *
+ *	const [volume, setVolume] = useGoState("volume", 0.5);
+ *
+ * Every component using the same key shares the value. setVolume
+ * updates locally at once and writes through to Go; Go-side Set()
+ * calls re-render every subscriber instantly. Until the first sync
+ * arrives the hook returns `fallback`.
+ */
+export function useGoState<T>(key: string, fallback: T): [T, (v: T) => void] {
+  const subscribe = useCallback((fn: () => void) => {
+    connect();
+    return onGoState(key, fn);
+  }, [key]);
+  const value = useSyncExternalStore(subscribe, () =>
+    hasGoState(key) ? (getGoState(key) as T) : fallback,
+  );
+  const set = useCallback((v: T) => setGoState(key, v), [key]);
+  return [value, set];
+}

package/src/hooks.ts

@@ -0,0 +1,31 @@
+import { useEffect, useMemo, useState } from "react";
+import { getShell, type ShellBridge, type ShellCaps } from "./bridge";
+
+/** useShell memoizes the native bridge for components. */
+export function useShell(prefix = "gantry"): ShellBridge {
+  return useMemo(() => getShell(prefix), [prefix]);
+}
+
+/**
+ * useShellCaps resolves which window buttons the Go window enabled.
+ * Returns null while resolving (render nothing yet to avoid a button
+ * flicker), then the caps - all false in a plain browser.
+ */
+export function useShellCaps(prefix = "gantry"): ShellCaps | null {
+  const shell = useShell(prefix);
+  const [caps, setCaps] = useState<ShellCaps | null>(null);
+  useEffect(() => {
+    let alive = true;
+    if (!shell.available) {
+      setCaps({ minimize: false, maximize: false, close: false, alwaysOnTop: false });
+      return;
+    }
+    void shell.caps().then((c) => {
+      if (alive) setCaps(c);
+    });
+    return () => {
+      alive = false;
+    };
+  }, [shell]);
+  return caps;
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+export { getShell } from "./bridge";
+export type { ShellBridge, ShellCaps } from "./bridge";
+export { useShell, useShellCaps } from "./hooks";
+export { installZoomGuard } from "./zoom";
+export { TitleBar } from "./TitleBar";
+export type { TitleBarProps } from "./TitleBar";
+export { DragStrip } from "./DragStrip";
+export type { DragStripProps } from "./DragStrip";
+export { ResizeFrame } from "./ResizeFrame";
+export { createApp } from "./app";
+export type { CreateAppOptions } from "./app";
+export { navigate, redirect, goBack, goForward, useRoute, isActive, Link, ExternalLink } from "./router";
+export type { LinkProps, ExternalLinkProps } from "./router";
+export { usePaired } from "./paired";
+export type { Paired } from "./paired";
+export { service, useService, useCall } from "./service";
+export type { Service, CallResult } from "./service";
+export { useGoState } from "./gostate";
+export { TeaView } from "./tea/Runtime";
+export type { TeaComponentProps, ComponentRegistry } from "./tea/Runtime";