@pylonsync/react 0.3.245 → 0.3.247

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.245",
+  "version": "0.3.247",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -12,8 +12,8 @@
     "check": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@pylonsync/sdk": "0.3.245",
-    "@pylonsync/sync": "0.3.245"
+    "@pylonsync/sdk": "0.3.247",
+    "@pylonsync/sync": "0.3.247"
   },
   "peerDependencies": {
     "react": ">=19.0.0"

package/src/Link.tsx

@@ -30,7 +30,10 @@ declare global {
   interface Window {
     __pylon?: {
       prefetch: (href: string) => Promise<void>;
-      navigate: (href: string, opts?: { push?: boolean }) => Promise<void>;
+      navigate: (
+        href: string,
+        opts?: { push?: boolean; replace?: boolean },
+      ) => Promise<void>;
     };
   }
 }

package/src/index.ts

@@ -8,6 +8,22 @@ export type { LinkProps } from "./Link";
 export { Image } from "./Image";
 export type { ImageProps } from "./Image";
 
+// SSR page-author types — the contract every `app/**/page.tsx` is handed
+// in props, plus `metadata` / `generateMetadata`. Type-only.
+export type {
+  PageProps,
+  PageAuth,
+  ServerData,
+  SsrResponse,
+  SsrCookieOptions,
+  Metadata,
+  GenerateMetadata,
+} from "./ssr";
+
+// Client navigation hooks for SSR pages (Next-style).
+export { useRouter, useSearchParams, usePathname } from "./useRouter";
+export type { PylonRouter } from "./useRouter";
+
 import {
   defaultStorage,
   pylonFetch,

package/src/ssr.ts

@@ -0,0 +1,207 @@
+// SSR page-author types.
+//
+// These describe the contract the Pylon SSR runtime hands every
+// `app/**/page.tsx` (and `layout.tsx`) component in props, plus the
+// `metadata` / `generateMetadata` exports. They are TYPE-ONLY — no runtime
+// — so a page author writes:
+//
+//   import type { PageProps, Metadata } from "@pylonsync/react";
+//
+//   export const metadata: Metadata = { title: "Blog" };
+//   export default function Page({ params, serverData, response }: PageProps) { ... }
+//
+// The source of truth for the shape is the runtime in
+// `@pylonsync/functions` (`ssr-runtime.ts`); these mirror it. Keep them in
+// sync when the runtime props change.
+
+/**
+ * The resolved Pylon auth context for the request that rendered the page.
+ * Safe to read in the component body — it is serialized into the hydration
+ * payload, so the server render and the client hydration see the same
+ * values (no hydration mismatch).
+ */
+export interface PageAuth {
+  /** The signed-in user's id, or null for an anonymous request. */
+  user_id: string | null;
+  /** True when the session is an admin session (PYLON_ADMIN_EMAILS). */
+  is_admin: boolean;
+  /** The active tenant/org id, or null. */
+  tenant_id: string | null;
+  /** Role slugs granted to the session. */
+  roles: string[];
+}
+
+/** Options for `response.setCookie`. Defaults: HttpOnly + SameSite=Lax. */
+export interface SsrCookieOptions {
+  path?: string;
+  domain?: string;
+  maxAge?: number;
+  expires?: Date | string;
+  /** Defaults to true (secure default). Pass false for a client-readable cookie. */
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: "Strict" | "Lax" | "None";
+}
+
+/**
+ * The per-render `response` controller. Pylon already has a backend for
+ * data + mutations, so SSR's job is just the HTTP response envelope:
+ * status, redirects, 404, and the occasional Set-Cookie.
+ *
+ * IMPORTANT — call these during the SYNCHRONOUS shell render (the component
+ * body, before any `await` / Suspense boundary). The HTTP head is committed
+ * when the shell is ready; status/headers/cookies set from a suspended
+ * subtree that streams in later are lost, and a `redirect()` / `notFound()`
+ * thrown below a Suspense boundary is swallowed by React's error handling
+ * rather than turned into a 3xx / 404.
+ */
+export interface SsrResponse {
+  /** Set the HTTP status (100–599). Default 200. */
+  setStatus(code: number): void;
+  /** Set a response header (name must be a token; value CR/LF/NUL-free). */
+  setHeader(name: string, value: string): void;
+  /** Append a Set-Cookie. Defaults: HttpOnly + SameSite=Lax. */
+  setCookie(name: string, value: string, opts?: SsrCookieOptions): void;
+  /** Throw to send a 3xx (default 307) + Location, no body. Shell-render only. */
+  redirect(url: string, status?: number): never;
+  /**
+   * Throw to send a 404. Renders the nearest `not-found.tsx` (walking up
+   * from the page's directory, wrapped in the route's layout chain), or a
+   * minimal framework body if none is defined. Shell-render only.
+   */
+  notFound(): never;
+}
+
+/**
+ * Read-only database handle a page reaches during render via React 19
+ * `use()` + `<Suspense>`. Reads run through the same store + policy gate as
+ * a query function's `ctx.db`; writes are rejected. Resolved values are
+ * cached and replayed into the hydration payload, so the client does not
+ * re-fetch on hydration.
+ *
+ * ```tsx
+ * export default function Page({ serverData }: PageProps) {
+ *   const posts = use(serverData.list<Post>("Post"));
+ *   return <ul>{posts.map((p) => <li key={p.id}>{p.title}</li>)}</ul>;
+ * }
+ * ```
+ */
+export interface ServerData {
+  /** Get a single row by id. Resolves to null if not found. */
+  get<T = Record<string, unknown>>(entity: string, id: string): Promise<T | null>;
+  /** List all (policy-visible) rows for an entity. */
+  list<T = Record<string, unknown>>(entity: string): Promise<T[]>;
+  /** Look up a row by a field value (e.g. email). Null if not found. */
+  lookup<T = Record<string, unknown>>(
+    entity: string,
+    field: string,
+    value: string,
+  ): Promise<T | null>;
+  /** Query with filters ($gt, $lt, $in, $like, $order, $limit, …). */
+  query<T = Record<string, unknown>>(
+    entity: string,
+    filter: Record<string, unknown>,
+  ): Promise<T[]>;
+  /** Execute a graph query with nested relation includes. */
+  queryGraph<T = Record<string, unknown>>(
+    query: Record<string, unknown>,
+  ): Promise<T>;
+  /** Cursor-paginated list. Pass `cursor` from a previous page's result. */
+  paginate<T = Record<string, unknown>>(
+    entity: string,
+    opts: { numItems: number; cursor?: string | null },
+  ): Promise<{ rows?: T[]; page?: T[]; nextCursor?: string | null }>;
+  /** Faceted full-text search against an entity with a `search:` config. */
+  search<T = Record<string, unknown>>(
+    entity: string,
+    query: Record<string, unknown>,
+  ): Promise<{
+    hits: T[];
+    facetCounts?: Record<string, Record<string, number>>;
+    total: number;
+    tookMs?: number;
+  }>;
+}
+
+/**
+ * Props every `page.tsx` / `layout.tsx` receives. Generic over the dynamic
+ * route params and the parsed query string, so a route like
+ * `app/blog/[slug]/page.tsx` can type them:
+ *
+ * ```tsx
+ * export default function Post({ params }: PageProps<{ slug: string }>) {
+ *   return <article>{params.slug}</article>;
+ * }
+ * ```
+ *
+ * Note: the incoming request's headers + cookies are intentionally NOT on
+ * this type. They are available only during the server render and are
+ * stripped from the hydration payload (a session cookie must never reach
+ * client JS), so reading them in the component body would hydrate-mismatch.
+ * Read request-derived data through `serverData` or a server function.
+ */
+export interface PageProps<
+  TParams extends Record<string, string> = Record<string, string>,
+  TSearchParams extends Record<string, string> = Record<string, string>,
+> {
+  /** The incoming URL path (e.g. `/blog/hello-world`). */
+  url: string;
+  /** Dynamic-segment matches keyed by name (e.g. `{ slug: "hello-world" }`). */
+  params: TParams;
+  /** Parsed query string (e.g. `?start=10` → `{ start: "10" }`). */
+  searchParams: TSearchParams;
+  /** The resolved auth context for the request. */
+  auth: PageAuth;
+  /** The HTTP response controller (status / headers / cookies / redirect). */
+  response: SsrResponse;
+  /** Read-only database handle for in-render data (use with `use()`). */
+  serverData: ServerData;
+}
+
+/**
+ * Page SEO metadata. Export `const metadata` (static) or
+ * `async function generateMetadata(props)` (dynamic, e.g. param-derived
+ * titles) from a `page.tsx` / `layout.tsx`. React 19 hoists the resulting
+ * `<title>` / `<meta>` / `<link>` into `<head>`.
+ */
+export interface Metadata {
+  title?: string;
+  description?: string;
+  keywords?: string | string[];
+  canonical?: string;
+  robots?: string;
+  openGraph?: {
+    title?: string;
+    description?: string;
+    image?: string;
+    imageSecureUrl?: string;
+    imageType?: string;
+    imageWidth?: number;
+    imageHeight?: number;
+    imageAlt?: string;
+    url?: string;
+    type?: string;
+  };
+  twitter?: {
+    card?: string;
+    title?: string;
+    description?: string;
+    image?: string;
+  };
+  icons?: {
+    icon?: { url: string; type?: string; sizes?: string };
+    apple?: { url: string; type?: string; sizes?: string };
+  };
+}
+
+/**
+ * Signature of a dynamic `generateMetadata` export. Receives the same props
+ * as the page; return (or resolve to) the page's `Metadata`. Awaited before
+ * the first byte, so keep it to cheap derivations.
+ */
+export type GenerateMetadata<
+  TParams extends Record<string, string> = Record<string, string>,
+  TSearchParams extends Record<string, string> = Record<string, string>,
+> = (
+  props: PageProps<TParams, TSearchParams>,
+) => Metadata | Promise<Metadata>;

package/src/useRouter.ts

@@ -0,0 +1,136 @@
+// Client navigation hooks for Pylon SSR pages — useRouter / useSearchParams
+// / usePathname. They drive (and read) the same client runtime that <Link>
+// uses: `window.__pylon.navigate` for programmatic nav, and the
+// `pylon:navigation` event (dispatched by the runtime after every nav) +
+// native `popstate` for reactivity.
+//
+// SSR note: useSearchParams / usePathname are CLIENT-reactive. During the
+// server render (and the matching first hydration pass) they return defaults
+// (empty params / "/") so there's never a hydration mismatch — React's
+// useSyncExternalStore uses the server snapshot for both, then re-renders
+// with the live value. For SSR-time access to the URL, read the `url` /
+// `searchParams` PROPS the runtime already hands every page (see PageProps);
+// the hooks exist for deep children that need to react to client navigation
+// without prop-drilling.
+import { useMemo, useSyncExternalStore } from "react";
+
+// `Window.__pylon` is globally augmented in ./Link (same package, ambient).
+
+function subscribe(onChange: () => void): () => void {
+  if (typeof window === "undefined") return () => {};
+  window.addEventListener("popstate", onChange);
+  window.addEventListener("pylon:navigation", onChange);
+  return () => {
+    window.removeEventListener("popstate", onChange);
+    window.removeEventListener("pylon:navigation", onChange);
+  };
+}
+
+// useSyncExternalStore compares snapshots with Object.is, so the getSnapshot
+// must return a STABLE reference until the underlying value changes — a fresh
+// URLSearchParams every call would loop forever. Cache by the raw search
+// string.
+let cachedSearch: string | null = null;
+let cachedParams = new URLSearchParams();
+function searchClientSnapshot(): URLSearchParams {
+  const s = typeof window !== "undefined" ? window.location.search : "";
+  if (s !== cachedSearch) {
+    cachedSearch = s;
+    cachedParams = new URLSearchParams(s);
+  }
+  return cachedParams;
+}
+const EMPTY_PARAMS = new URLSearchParams();
+function searchServerSnapshot(): URLSearchParams {
+  return EMPTY_PARAMS;
+}
+
+/**
+ * The current query string as a reactive `URLSearchParams`. Re-renders on
+ * client navigation. Returns empty params during SSR / first hydration —
+ * use the `searchParams` page prop for server-side values.
+ *
+ * ```tsx
+ * const params = useSearchParams();
+ * const tab = params.get("tab") ?? "overview";
+ * ```
+ */
+export function useSearchParams(): URLSearchParams {
+  return useSyncExternalStore(
+    subscribe,
+    searchClientSnapshot,
+    searchServerSnapshot,
+  );
+}
+
+function pathClientSnapshot(): string {
+  return typeof window !== "undefined" ? window.location.pathname : "/";
+}
+function pathServerSnapshot(): string {
+  return "/";
+}
+
+/**
+ * The current pathname (no query/hash), reactive to client navigation.
+ * Returns "/" during SSR / first hydration — use the `url` page prop for
+ * server-side values.
+ */
+export function usePathname(): string {
+  return useSyncExternalStore(subscribe, pathClientSnapshot, pathServerSnapshot);
+}
+
+/** Imperative navigation handle (Next-style `useRouter`). */
+export interface PylonRouter {
+  /** Navigate to `href`, pushing a new history entry. */
+  push(href: string): void;
+  /** Navigate to `href`, replacing the current history entry. */
+  replace(href: string): void;
+  /** Go back one history entry. */
+  back(): void;
+  /** Go forward one history entry. */
+  forward(): void;
+  /** Re-fetch + re-render the current route (fresh server data). */
+  refresh(): void;
+  /** Warm the SSR HTML + chunks for `href` ahead of a navigation. */
+  prefetch(href: string): void;
+}
+
+/**
+ * Programmatic client navigation. Methods are no-ops before hydration /
+ * during SSR (there's no client runtime yet), so they're safe to call from
+ * effects and event handlers.
+ *
+ * ```tsx
+ * const router = useRouter();
+ * <button onClick={() => router.push("/dashboard")}>Go</button>
+ * ```
+ */
+export function useRouter(): PylonRouter {
+  return useMemo<PylonRouter>(
+    () => ({
+      push(href) {
+        void window.__pylon?.navigate(href, { push: true });
+      },
+      replace(href) {
+        void window.__pylon?.navigate(href, { replace: true });
+      },
+      back() {
+        if (typeof window !== "undefined") window.history.back();
+      },
+      forward() {
+        if (typeof window !== "undefined") window.history.forward();
+      },
+      refresh() {
+        if (typeof window === "undefined") return;
+        void window.__pylon?.navigate(
+          window.location.pathname + window.location.search,
+          { replace: true },
+        );
+      },
+      prefetch(href) {
+        void window.__pylon?.prefetch(href);
+      },
+    }),
+    [],
+  );
+}