gantry-web 0.3.6 → 0.4.0

package/src/bridge.ts

@@ -1,94 +1,95 @@
-// 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),
-  };
-}
+// 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;
+  /**
+   * Frameless windows: start an interactive resize from an edge
+   * ("n","s","e","w","ne","nw","se","sw"). Bound on both Windows and
+   * Linux; on Windows it posts WM_NCLBUTTONDOWN (the native hit-test
+   * margin remains only as a backstop).
+   */
+  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/index.ts

@@ -1,32 +1,32 @@
-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, GantryAppModule, GantryPage, GantryPageModule } 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 { resourceURL } from "./resources";
-export { useAppInfo, fetchAppInfo } from "./appinfo";
-export type { AppInfo } from "./appinfo";
-export { useEnv, useMode, useArg, fetchEnv } from "./env";
-export type { AppEnv, AppMode } from "./env";
-export { reportError, addBreadcrumb, useGantryErrors, dismissNotice, clearFatal } from "./errors";
-export type { GantryErrorInfo, GantryCrumb, ErrorHandlingOptions } from "./errors";
-export { ErrorScreen } from "./ErrorScreen";
-export type { ErrorScreenProps } from "./ErrorScreen";
-export { GantryCallError } from "./socket";
-export { Await, Skeleton } from "./Await";
-export type { AwaitProps, SkeletonProps } from "./Await";
-export { TeaView } from "./tea/Runtime";
-export type { TeaComponentProps, ComponentRegistry } from "./tea/Runtime";
+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, GantryAppModule, GantryPage, GantryPageModule } from "./app";
+export { navigate, redirect, goBack, goForward, useRoute, isActive, useParams, Link, ExternalLink } from "./router";
+export type { LinkProps, ExternalLinkProps, RouteParams } 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 { resourceURL } from "./resources";
+export { useAppInfo, fetchAppInfo } from "./appinfo";
+export type { AppInfo } from "./appinfo";
+export { useEnv, useMode, useArg, fetchEnv } from "./env";
+export type { AppEnv, AppMode } from "./env";
+export { reportError, addBreadcrumb, useGantryErrors, dismissNotice, clearFatal } from "./errors";
+export type { GantryErrorInfo, GantryCrumb, ErrorHandlingOptions } from "./errors";
+export { ErrorScreen } from "./ErrorScreen";
+export type { ErrorScreenProps } from "./ErrorScreen";
+export { GantryCallError } from "./socket";
+export { Await, Skeleton } from "./Await";
+export type { AwaitProps, SkeletonProps } from "./Await";
+export { TeaView } from "./tea/Runtime";
+export type { TeaComponentProps, ComponentRegistry } from "./tea/Runtime";

package/src/router.tsx

@@ -1,160 +1,180 @@
-// 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";
-
-// Subscriptions go through a window-scoped event, NOT a module-local
-// set: if bundling ever instantiates this module twice (it happened -
-// Vite served excluded node_modules source under ?v=hash and bare URLs
-// at once), a local set splits the subscribers and navigation silently
-// stops re-rendering half the app. The window survives any number of
-// module copies; the route itself already lives in location.pathname.
-const NAV_EVENT = "gantry:navigate";
-
-function notify() {
-  window.dispatchEvent(new Event(NAV_EVENT));
-}
-
-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 {
-  window.addEventListener(NAV_EVENT, fn);
-  return () => window.removeEventListener(NAV_EVENT, 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>
-  );
-}
+// 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 {
+  createContext,
+  useContext,
+  useSyncExternalStore,
+  type AnchorHTMLAttributes,
+  type ReactNode,
+} from "react";
+import { getShell } from "./bridge";
+
+/** Params captured from a dynamic route: a string for a [id] segment, a
+ * string[] for a [...slug] catch-all. */
+export type RouteParams = Record<string, string | string[]>;
+
+// The active page's captured params, provided by createApp around the
+// page. Empty for static routes.
+export const ParamsContext = createContext<RouteParams>({});
+
+/**
+ * useParams returns the params captured from the current dynamic route.
+ * For pages/examples/page1/[id] on /examples/page1/7 it is { id: "7" };
+ * for a [...slug] catch-all the value is a string[]. Empty on static
+ * pages. Type it with the shape you expect: useParams<{ id: string }>().
+ */
+export function useParams<T extends RouteParams = RouteParams>(): T {
+  return useContext(ParamsContext) as T;
+}
+
+// Subscriptions go through a window-scoped event, NOT a module-local
+// set: if bundling ever instantiates this module twice (it happened -
+// Vite served excluded node_modules source under ?v=hash and bare URLs
+// at once), a local set splits the subscribers and navigation silently
+// stops re-rendering half the app. The window survives any number of
+// module copies; the route itself already lives in location.pathname.
+const NAV_EVENT = "gantry:navigate";
+
+function notify() {
+  window.dispatchEvent(new Event(NAV_EVENT));
+}
+
+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 {
+  window.addEventListener(NAV_EVENT, fn);
+  return () => window.removeEventListener(NAV_EVENT, 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>
+  );
+}