gantry-web 0.3.5 → 0.4.0

package/package.json

@@ -1,43 +1,43 @@
-{
-  "name": "gantry-web",
-  "version": "0.3.5",
-  "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
-    }
-  }
-}
+{
+  "name": "gantry-web",
+  "version": "0.4.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/Await.tsx

@@ -0,0 +1,85 @@
+// Loading states for Go calls. useCall() already exposes { loading,
+// error, data }; Await is the declarative wrapper: show a developer-
+// defined fallback (a spinner, <Skeleton/>, anything) while the call
+// is in flight, an error card with retry when it fails, and the
+// children once data is there.
+//
+//	const users = useCall<User[]>("api", "listUsers");
+//	return (
+//	  <Await call={users} fallback={<Skeleton lines={4} />}>
+//	    {(list) => <ul>{list.map(...)}</ul>}
+//	  </Await>
+//	);
+
+import type { CSSProperties, ReactNode } from "react";
+import type { CallResult } from "./service";
+
+export interface AwaitProps<T> {
+  /** The in-flight call (from useCall, or anything CallResult-shaped). */
+  call: CallResult<T>;
+  /** What to show while loading: a spinner, <Skeleton/>, custom JSX.
+   * Default: <Skeleton lines={3}/>. */
+  fallback?: ReactNode;
+  /** Custom error rendering; default is a small card with a Retry
+   * button. */
+  renderError?: (error: string, code: string | null, reload: () => void) => ReactNode;
+  /** Renders the loaded data. */
+  children: (data: T) => ReactNode;
+}
+
+export function Await<T>({ call, fallback, renderError, children }: AwaitProps<T>) {
+  if (call.loading) {
+    return <>{fallback ?? <Skeleton lines={3} />}</>;
+  }
+  if (call.error !== null) {
+    if (renderError) return <>{renderError(call.error, call.code, call.reload)}</>;
+    return (
+      <div className="gantry-await-error">
+        <span className="gantry-await-error-message">{call.error}</span>
+        {call.code && <span className="gantry-await-error-code">{call.code}</span>}
+        <button className="gantry-await-retry" onClick={call.reload}>
+          Retry
+        </button>
+      </div>
+    );
+  }
+  return <>{children(call.data as T)}</>;
+}
+
+export interface SkeletonProps {
+  /** Placeholder text lines (the last one renders shorter). */
+  lines?: number;
+  /** Explicit size for a single block (a chart area, an avatar). */
+  width?: number | string;
+  height?: number | string;
+  /** Round the block fully (avatars). */
+  circle?: boolean;
+  className?: string;
+  style?: CSSProperties;
+}
+
+/**
+ * Skeleton renders shimmering placeholder blocks sized like the
+ * content they stand in for: <Skeleton lines={4}/> for text,
+ * <Skeleton width={240} height={120}/> for a block, circle for
+ * avatars.
+ */
+export function Skeleton({ lines, width, height, circle, className, style }: SkeletonProps) {
+  if (lines === undefined && (width !== undefined || height !== undefined || circle)) {
+    const s: CSSProperties = {
+      width: width ?? (circle ? 40 : "100%"),
+      height: height ?? (circle ? 40 : 16),
+      borderRadius: circle ? "50%" : undefined,
+      ...style,
+    };
+    return <div className={"gantry-skeleton" + (className ? " " + className : "")} style={s} />;
+  }
+  const n = Math.max(1, lines ?? 3);
+  return (
+    <div className={"gantry-skeleton-lines" + (className ? " " + className : "")} style={style}>
+      {Array.from({ length: n }, (_, i) => (
+        <div key={i} className="gantry-skeleton" style={{ width: i === n - 1 && n > 1 ? "60%" : "100%" }} />
+      ))}
+    </div>
+  );
+}

package/src/ErrorScreen.tsx

@@ -0,0 +1,98 @@
+// The built-in error UI: a full-screen overlay for fatal render
+// crashes and dismissible banners for non-fatal errors (Go panics,
+// unhandled rejections). Development shows the full story - message,
+// stack, the page, and the "what led here" action trail; production
+// shows a friendly minimal card. Replace it per app via
+// createApp({ errors: { screen: MyScreen } }).
+
+import type { FC } from "react";
+import type { GantryCrumb, GantryErrorInfo } from "./errors";
+
+export interface ErrorScreenProps {
+  error: GantryErrorInfo;
+  /** Resolved app mode; null while unknown (treated as development). */
+  mode: "development" | "production" | null;
+  /** "fatal" = render crash overlay, "notice" = dismissible banner. */
+  variant: "fatal" | "notice";
+  onDismiss: () => void;
+}
+
+function ago(iso: string, now: number): string {
+  const t = Date.parse(iso);
+  if (Number.isNaN(t)) return "";
+  const s = Math.max(0, Math.round((now - t) / 1000));
+  if (s < 1) return "now";
+  if (s < 60) return `${s}s ago`;
+  return `${Math.floor(s / 60)}m${s % 60 ? ` ${s % 60}s` : ""} ago`;
+}
+
+function Trail({ trail }: { trail: GantryCrumb[] }) {
+  const now = Date.now();
+  return (
+    <div className="gantry-error-trail">
+      <div className="gantry-error-heading">What led here</div>
+      {trail.map((c, i) => (
+        <div key={i} className={"gantry-error-crumb" + (c.ok ? "" : " gantry-error-crumb-failed")}>
+          <span className="gantry-error-crumb-time">{ago(c.time, now)}</span>
+          <span className="gantry-error-crumb-type">{c.type}</span>
+          <span className="gantry-error-crumb-detail">{c.detail}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function Detail({ error }: { error: GantryErrorInfo }) {
+  return (
+    <>
+      <div className="gantry-error-meta">
+        <span className="gantry-error-kind">{error.kind}</span>
+        {error.code && <span className="gantry-error-code">{error.code}</span>}
+        {error.page && <span className="gantry-error-page">on {error.page}</span>}
+        {error.source && <span className="gantry-error-source">{error.source}</span>}
+        <span className="gantry-error-origin">{error.origin === "go" ? "Go" : "JS"}</span>
+      </div>
+      {error.stack && <pre className="gantry-error-stack">{error.stack}</pre>}
+      {error.componentStack && (
+        <>
+          <div className="gantry-error-heading">Component stack</div>
+          <pre className="gantry-error-stack">{error.componentStack}</pre>
+        </>
+      )}
+      {error.trail && error.trail.length > 0 && <Trail trail={error.trail} />}
+    </>
+  );
+}
+
+export const ErrorScreen: FC<ErrorScreenProps> = ({ error, mode, variant, onDismiss }) => {
+  const dev = mode !== "production";
+  if (variant === "fatal") {
+    return (
+      <div className="gantry-error-overlay">
+        <div className="gantry-error-card">
+          <div className="gantry-error-title">{dev ? "The page crashed" : "Something went wrong"}</div>
+          {dev ? <div className="gantry-error-message">{error.message}</div> : <div className="gantry-error-message">The app hit an unexpected error. Reloading usually fixes it.</div>}
+          {dev && <Detail error={error} />}
+          <div className="gantry-error-actions">
+            <button className="gantry-error-button" onClick={() => location.reload()}>
+              Reload
+            </button>
+          </div>
+        </div>
+      </div>
+    );
+  }
+  return (
+    <div className="gantry-error-banner">
+      <div className="gantry-error-banner-head">
+        <span className="gantry-error-banner-title">
+          {error.origin === "go" ? "Go error" : "Error"}: {error.message}
+        </span>
+        <button className="gantry-error-dismiss" onClick={onDismiss} aria-label="Dismiss">
+          ×
+        </button>
+      </div>
+      {dev && <Detail error={error} />}
+    </div>
+  );
+};

package/src/ResizeFrame.tsx

@@ -1,40 +1,43 @@
-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);
-          }}
-        />
-      ))}
-    </>
-  );
-}
+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 and carry the resize cursor. A frameless window has
+ * no draggable OS frame: on Linux the compositor offers no hit-test, and
+ * on Windows the WebView2 child covers the client area and swallows the
+ * parent's WM_NCHITTEST resize margin - so on both the frontend draws the
+ * strips and calls the ResizeEdge binding on mousedown. Framed windows
+ * (and the browser) render nothing.
+ */
+export function ResizeFrame({ prefix }: { prefix?: string }) {
+  const shell = useShell(prefix);
+  const caps = useShellCaps(prefix);
+  const native = caps?.platform === "linux" || caps?.platform === "windows";
+  if (!native || !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);
+          }}
+        />
+      ))}
+    </>
+  );
+}