@squadbase/vantage 0.1.0 → 0.1.1

package/dist/{define-page-B6y9TOfZ.d.ts → define-page-BfhrK99G.d.ts}

@@ -9,6 +9,11 @@ interface PageConfig {
     title?: string;
     /** Description metadata for the page. */
     description?: string;
+    /**
+     * Short label for navigation built from `useRoutes()`. Defaults to `title`,
+     * which is often too long for a nav ("Overview · Acme Analytics").
+     */
+    navLabel?: string;
     /**
      * Component rendered while the route is loading.
      * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { P as PageComponent, a as PageConfig, d as definePage } from './define-page-B6y9TOfZ.js';
+export { P as PageComponent, a as PageConfig, d as definePage } from './define-page-BfhrK99G.js';
 import 'react';
 
 /**
@@ -10,6 +10,6 @@ import 'react';
  */
 
 /** Framework version, kept in sync with package.json at build time. */
-declare const VERSION = "0.1.0";
+declare const VERSION = "0.1.1";
 
 export { VERSION };

package/dist/index.js

@@ -6,7 +6,7 @@ function definePage(config) {
 }
 
 // src/index.ts
-var VERSION = "0.1.0";
+var VERSION = "0.1.1";
 
 export { VERSION, definePage };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/runtime/define-page.ts","../src/index.ts"],"names":[],"mappings":";;;AAoCO,SAAS,WAAW,MAAA,EAAgC;AACzD,EAAA,OAAO,MAAA;AACT;;;AC3BO,IAAM,OAAA,GAAU","file":"index.js","sourcesContent":["import type { ComponentType, ReactNode } from \"react\"\n\n/**\n * Optional per-page configuration. The only required part of a page module is\n * its default-exported component; `definePage` covers everything else.\n */\nexport interface PageConfig {\n  /** Document title applied when this route is active. */\n  title?: string\n  /** Description metadata for the page. */\n  description?: string\n  /**\n   * Component rendered while the route is loading.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  pendingComponent?: ComponentType\n  /**\n   * Component rendered when the route throws.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  errorComponent?: ComponentType<{ error: unknown }>\n  /**\n   * Validate/transform the URL search params for this route.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  validateSearch?: (search: Record<string, unknown>) => Record<string, unknown>\n}\n\n/**\n * Declare optional page configuration.\n *\n * ```tsx\n * export const page = definePage({ title: \"Monthly Analysis\" })\n * export default function MonthlyAnalysis() { return <div/> }\n * ```\n */\nexport function definePage(config: PageConfig): PageConfig {\n  return config\n}\n\n/** Convenience type for a Vantage page component. */\nexport type PageComponent = ComponentType & { (): ReactNode }\n","/**\n * `@squadbase/vantage` — public runtime surface.\n *\n * The only import most pages need. Server state lives in\n * `@squadbase/vantage/query`, navigation in `@squadbase/vantage/router`,\n * UI in `@squadbase/vantage/ui`, and API types in `@squadbase/vantage/server`.\n */\nexport { definePage } from \"./runtime/define-page.js\"\nexport type { PageConfig, PageComponent } from \"./runtime/define-page.js\"\n\n/** Framework version, kept in sync with package.json at build time. */\nexport const VERSION = \"0.1.0\"\n"]}
+{"version":3,"sources":["../src/runtime/define-page.ts","../src/index.ts"],"names":[],"mappings":";;;AAyCO,SAAS,WAAW,MAAA,EAAgC;AACzD,EAAA,OAAO,MAAA;AACT;;;AChCO,IAAM,OAAA,GAAU","file":"index.js","sourcesContent":["import type { ComponentType, ReactNode } from \"react\"\n\n/**\n * Optional per-page configuration. The only required part of a page module is\n * its default-exported component; `definePage` covers everything else.\n */\nexport interface PageConfig {\n  /** Document title applied when this route is active. */\n  title?: string\n  /** Description metadata for the page. */\n  description?: string\n  /**\n   * Short label for navigation built from `useRoutes()`. Defaults to `title`,\n   * which is often too long for a nav (\"Overview · Acme Analytics\").\n   */\n  navLabel?: string\n  /**\n   * Component rendered while the route is loading.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  pendingComponent?: ComponentType\n  /**\n   * Component rendered when the route throws.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  errorComponent?: ComponentType<{ error: unknown }>\n  /**\n   * Validate/transform the URL search params for this route.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  validateSearch?: (search: Record<string, unknown>) => Record<string, unknown>\n}\n\n/**\n * Declare optional page configuration.\n *\n * ```tsx\n * export const page = definePage({ title: \"Monthly Analysis\" })\n * export default function MonthlyAnalysis() { return <div/> }\n * ```\n */\nexport function definePage(config: PageConfig): PageConfig {\n  return config\n}\n\n/** Convenience type for a Vantage page component. */\nexport type PageComponent = ComponentType & { (): ReactNode }\n","/**\n * `@squadbase/vantage` — public runtime surface.\n *\n * The only import most pages need. Server state lives in\n * `@squadbase/vantage/query`, navigation in `@squadbase/vantage/router`,\n * UI in `@squadbase/vantage/ui`, and API types in `@squadbase/vantage/server`.\n */\nexport { definePage } from \"./runtime/define-page.js\"\nexport type { PageConfig, PageComponent } from \"./runtime/define-page.js\"\n\n/** Framework version, kept in sync with package.json at build time. */\nexport const VERSION = \"0.1.1\"\n"]}

package/dist/query/index.d.ts

@@ -1,4 +1,4 @@
-import { QueryClient } from '@tanstack/react-query';
+import { QueryClient, UseMutationOptions, UseQueryOptions, QueryKey, UseMutationResult, UseQueryResult } from '@tanstack/react-query';
 export { QueryClient, QueryKey, UseInfiniteQueryOptions, UseMutationOptions, UseMutationResult, UseQueryOptions, UseQueryResult, keepPreviousData, useInfiniteQuery, useIsFetching, useIsMutating, useMutation, useQueries, useQuery, useQueryClient } from '@tanstack/react-query';
 
 /**
@@ -33,5 +33,72 @@ declare function apiUrl(path: string): string;
  * existing `queryFn` style.
  */
 declare function apiFetch(path: string, init?: RequestInit): Promise<Response>;
+/** Query-string values accepted by the API helpers. */
+type ApiSearch = Record<string, string | number | boolean | null | undefined | (string | number)[]>;
+/**
+ * Append a query string to an API path. `undefined`/`null` entries are dropped
+ * so an unset filter leaves the URL — and the query key — unchanged. Array
+ * values repeat the key, matching `URLSearchParams.getAll` on the server.
+ */
+declare function apiPath(path: string, search?: ApiSearch): string;
+/**
+ * A non-2xx response from `server/api`. `message` is the server's `HttpError`
+ * message when there was one; anything else surfaces as a generic status text,
+ * mirroring what the server chose to disclose.
+ */
+declare class ApiError extends Error {
+    /** HTTP status of the response. */
+    readonly status: number;
+    /** Parsed response body, when there was one. */
+    readonly body: unknown;
+    /** `x-vantage-request-id`, to correlate with the server's terminal log. */
+    readonly requestId: string | undefined;
+    constructor(message: string, status: number, body: unknown, requestId?: string);
+}
+/**
+ * Fetch an API route and parse its JSON, throwing `ApiError` on a non-2xx.
+ * This is what the API hooks call; use it directly in a loader or an event
+ * handler where a hook doesn't fit.
+ */
+declare function apiJson<T = unknown>(path: string, init?: RequestInit): Promise<T>;
+
+interface ApiQueryOptions<TData> extends Omit<UseQueryOptions<TData, ApiError>, "queryKey" | "queryFn"> {
+    /** Query-string values; `undefined` entries are omitted. */
+    search?: ApiSearch;
+    /** Extra `fetch` init (headers, credentials, …). */
+    init?: RequestInit;
+    /** Override the derived `["api", url]` key. */
+    queryKey?: QueryKey;
+}
+/**
+ * GET an API route.
+ *
+ * ```tsx
+ * const { data, isPending, error } = useApiQuery<Monthly>("/api/monthly-analysis")
+ * const filtered = useApiQuery<Row[]>("/api/customers", { search: { segment } })
+ * ```
+ *
+ * The key defaults to `["api", <url with query string>]`, so changing `search`
+ * refetches and `invalidateQueries({ queryKey: ["api"] })` clears everything.
+ */
+declare function useApiQuery<TData = unknown>(path: string, options?: ApiQueryOptions<TData>): UseQueryResult<TData, ApiError>;
+interface ApiMutationOptions<TData, TVariables> extends Omit<UseMutationOptions<TData, ApiError, TVariables>, "mutationFn"> {
+    /** HTTP method (default `"POST"`). */
+    method?: "POST" | "PUT" | "PATCH" | "DELETE";
+    /** Extra `fetch` init (headers, credentials, …). */
+    init?: RequestInit;
+}
+/**
+ * Write to an API route. The mutation variables are sent as the JSON body.
+ *
+ * ```tsx
+ * const save = useApiMutation<Customer, { id: string; name: string }>(
+ *   (vars) => `/api/customers/${vars.id}`,
+ *   { method: "PUT" },
+ * )
+ * save.mutate({ id: "1", name: "Northwind" })
+ * ```
+ */
+declare function useApiMutation<TData = unknown, TVariables = void>(path: string | ((variables: TVariables) => string), options?: ApiMutationOptions<TData, TVariables>): UseMutationResult<TData, ApiError, TVariables>;
 
-export { apiBaseUrl, apiFetch, apiUrl, createQueryClient };
+export { ApiError, type ApiMutationOptions, type ApiQueryOptions, type ApiSearch, apiBaseUrl, apiFetch, apiJson, apiPath, apiUrl, createQueryClient, useApiMutation, useApiQuery };

package/dist/query/index.js

@@ -1,4 +1,5 @@
-export { createQueryClient } from '../chunk-ATYZ45XL.js';
+export { createQueryClient } from '../chunk-DTDVSFRY.js';
+import { useQuery, useMutation } from '@tanstack/react-query';
 export { QueryClient, keepPreviousData, useInfiniteQuery, useIsFetching, useIsMutating, useMutation, useQueries, useQuery, useQueryClient } from '@tanstack/react-query';
 
 // @squadbase/vantage — generated build. Do not edit.
@@ -16,7 +17,89 @@ function apiUrl(path) {
 function apiFetch(path, init) {
   return fetch(apiUrl(path), init);
 }
+function apiPath(path, search) {
+  if (!search) return path;
+  const params = new URLSearchParams();
+  for (const key of Object.keys(search).sort()) {
+    const value = search[key];
+    if (value === void 0 || value === null) continue;
+    if (Array.isArray(value)) {
+      for (const item of value) params.append(key, String(item));
+    } else {
+      params.append(key, String(value));
+    }
+  }
+  const qs = params.toString();
+  if (!qs) return path;
+  return path + (path.includes("?") ? "&" : "?") + qs;
+}
+var ApiError = class extends Error {
+  /** HTTP status of the response. */
+  status;
+  /** Parsed response body, when there was one. */
+  body;
+  /** `x-vantage-request-id`, to correlate with the server's terminal log. */
+  requestId;
+  constructor(message, status, body, requestId) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.body = body;
+    this.requestId = requestId;
+  }
+};
+async function apiJson(path, init) {
+  const res = await apiFetch(path, init);
+  const requestId = res.headers.get("x-vantage-request-id") ?? void 0;
+  const text = await res.text();
+  let body;
+  if (text) {
+    try {
+      body = JSON.parse(text);
+    } catch {
+      body = text;
+    }
+  }
+  if (!res.ok) {
+    const serverMessage = typeof body === "object" && body !== null && typeof body.error === "string" ? body.error : void 0;
+    throw new ApiError(
+      serverMessage ?? `${res.status} ${res.statusText || "Request failed"}`,
+      res.status,
+      body,
+      requestId
+    );
+  }
+  return body;
+}
+var API_KEY = "api";
+function useApiQuery(path, options = {}) {
+  const { search, init, queryKey, ...rest } = options;
+  const url = apiPath(path, search);
+  return useQuery({
+    queryKey: queryKey ?? [API_KEY, url],
+    // The signal comes from TanStack so an unmounted/refetched query aborts;
+    // a caller-supplied signal wins.
+    queryFn: ({ signal }) => apiJson(url, { ...init, signal: init?.signal ?? signal }),
+    ...rest
+  });
+}
+function useApiMutation(path, options = {}) {
+  const { method = "POST", init, ...rest } = options;
+  return useMutation({
+    mutationFn: (variables) => {
+      const url = typeof path === "function" ? path(variables) : path;
+      const hasBody = variables !== void 0 && variables !== null;
+      return apiJson(url, {
+        method,
+        ...init,
+        headers: hasBody ? { "content-type": "application/json", ...init?.headers } : init?.headers,
+        ...hasBody ? { body: JSON.stringify(variables) } : {}
+      });
+    },
+    ...rest
+  });
+}
 
-export { apiBaseUrl, apiFetch, apiUrl };
+export { ApiError, apiBaseUrl, apiFetch, apiJson, apiPath, apiUrl, useApiMutation, useApiQuery };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/query/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/query/api.ts"],"names":[],"mappings":";;;;;;AAaO,SAAS,UAAA,GAAqB;AAEnC,EAAA,MAAM,MAAO,MAAA,CAAA,IAAA,CAA6D,GAAA;AAC1E,EAAA,MAAM,GAAA,GAAM,KAAK,mBAAA,IAAuB,EAAA;AACxC,EAAA,OAAO,GAAA,CAAI,OAAA,CAAQ,MAAA,EAAQ,EAAE,CAAA;AAC/B;AAOO,SAAS,OAAO,IAAA,EAAsB;AAC3C,EAAA,MAAM,MAAM,IAAA,CAAK,UAAA,CAAW,GAAG,CAAA,GAAI,IAAA,GAAO,IAAI,IAAI,CAAA,CAAA;AAClD,EAAA,OAAO,YAAW,GAAI,GAAA;AACxB;AAOO,SAAS,QAAA,CAAS,MAAc,IAAA,EAAuC;AAC5E,EAAA,OAAO,KAAA,CAAM,MAAA,CAAO,IAAI,CAAA,EAAG,IAAI,CAAA;AACjC","file":"index.js","sourcesContent":["/**\n * The one seam for calling the API from client code. All `/api/*` requests go\n * through here so a split deployment (client on S3/CloudFront, server on Lambda)\n * can point the client at a different origin without touching page code.\n *\n * The base is read from `import.meta.env.PUBLIC_API_BASE_URL` — a `PUBLIC_`\n * prefixed var so it is inlined into the client bundle (see envPrefix in the\n * Vite plugin). It can be set in `.env` or injected at build time via\n * `vantage build --api-base-url <url>`. When unset it is empty, so requests stay\n * same-origin relative paths — identical to hand-written `fetch(\"/api/...\")`.\n */\n\n/** The configured API base URL (no trailing slash), or \"\" for same-origin. */\nexport function apiBaseUrl(): string {\n  // `import.meta.env` is typed in the generated .vantage/types, not here.\n  const env = (import.meta as { env?: Record<string, string | undefined> }).env\n  const raw = env?.PUBLIC_API_BASE_URL ?? \"\"\n  return raw.replace(/\\/+$/, \"\")\n}\n\n/**\n * Build a full API URL. Pass the path exactly as it maps to `server/api/**`,\n * including the `/api` prefix — e.g. `apiUrl(\"/api/customers\")`. With no base\n * configured this returns the relative path unchanged.\n */\nexport function apiUrl(path: string): string {\n  const rel = path.startsWith(\"/\") ? path : `/${path}`\n  return apiBaseUrl() + rel\n}\n\n/**\n * Thin `fetch` wrapper that resolves the path against the API base. Returns the\n * raw `Response` — parsing and error handling stay with the caller, matching the\n * existing `queryFn` style.\n */\nexport function apiFetch(path: string, init?: RequestInit): Promise<Response> {\n  return fetch(apiUrl(path), init)\n}\n"]}
+{"version":3,"sources":["../../src/query/api.ts","../../src/query/hooks.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * The one seam for calling the API from client code. All `/api/*` requests go\n * through here so a split deployment (client on S3/CloudFront, server on Lambda)\n * can point the client at a different origin without touching page code.\n *\n * The base is read from `import.meta.env.PUBLIC_API_BASE_URL` — a `PUBLIC_`\n * prefixed var so it is inlined into the client bundle (see envPrefix in the\n * Vite plugin). It can be set in `.env` or injected at build time via\n * `vantage build --api-base-url <url>`. When unset it is empty, so requests stay\n * same-origin relative paths — identical to hand-written `fetch(\"/api/...\")`.\n */\n\n/** The configured API base URL (no trailing slash), or \"\" for same-origin. */\nexport function apiBaseUrl(): string {\n  // `import.meta.env` is typed in the generated .vantage/types, not here.\n  const env = (import.meta as { env?: Record<string, string | undefined> }).env\n  const raw = env?.PUBLIC_API_BASE_URL ?? \"\"\n  return raw.replace(/\\/+$/, \"\")\n}\n\n/**\n * Build a full API URL. Pass the path exactly as it maps to `server/api/**`,\n * including the `/api` prefix — e.g. `apiUrl(\"/api/customers\")`. With no base\n * configured this returns the relative path unchanged.\n */\nexport function apiUrl(path: string): string {\n  const rel = path.startsWith(\"/\") ? path : `/${path}`\n  return apiBaseUrl() + rel\n}\n\n/**\n * Thin `fetch` wrapper that resolves the path against the API base. Returns the\n * raw `Response` — parsing and error handling stay with the caller, matching the\n * existing `queryFn` style.\n */\nexport function apiFetch(path: string, init?: RequestInit): Promise<Response> {\n  return fetch(apiUrl(path), init)\n}\n\n/** Query-string values accepted by the API helpers. */\nexport type ApiSearch = Record<\n  string,\n  string | number | boolean | null | undefined | (string | number)[]\n>\n\n/**\n * Append a query string to an API path. `undefined`/`null` entries are dropped\n * so an unset filter leaves the URL — and the query key — unchanged. Array\n * values repeat the key, matching `URLSearchParams.getAll` on the server.\n */\nexport function apiPath(path: string, search?: ApiSearch): string {\n  if (!search) return path\n  const params = new URLSearchParams()\n  // Sorted so two calls with the same filters produce the same query key.\n  for (const key of Object.keys(search).sort()) {\n    const value = search[key]\n    if (value === undefined || value === null) continue\n    if (Array.isArray(value)) {\n      for (const item of value) params.append(key, String(item))\n    } else {\n      params.append(key, String(value))\n    }\n  }\n  const qs = params.toString()\n  if (!qs) return path\n  return path + (path.includes(\"?\") ? \"&\" : \"?\") + qs\n}\n\n/**\n * A non-2xx response from `server/api`. `message` is the server's `HttpError`\n * message when there was one; anything else surfaces as a generic status text,\n * mirroring what the server chose to disclose.\n */\nexport class ApiError extends Error {\n  /** HTTP status of the response. */\n  readonly status: number\n  /** Parsed response body, when there was one. */\n  readonly body: unknown\n  /** `x-vantage-request-id`, to correlate with the server's terminal log. */\n  readonly requestId: string | undefined\n\n  constructor(message: string, status: number, body: unknown, requestId?: string) {\n    super(message)\n    this.name = \"ApiError\"\n    this.status = status\n    this.body = body\n    this.requestId = requestId\n  }\n}\n\n/**\n * Fetch an API route and parse its JSON, throwing `ApiError` on a non-2xx.\n * This is what the API hooks call; use it directly in a loader or an event\n * handler where a hook doesn't fit.\n */\nexport async function apiJson<T = unknown>(path: string, init?: RequestInit): Promise<T> {\n  const res = await apiFetch(path, init)\n  const requestId = res.headers.get(\"x-vantage-request-id\") ?? undefined\n\n  // Read as text first: an error response may be HTML from a proxy, and a 204\n  // has no body at all — neither should throw a JSON parse error at the caller.\n  const text = await res.text()\n  let body: unknown\n  if (text) {\n    try {\n      body = JSON.parse(text)\n    } catch {\n      body = text\n    }\n  }\n\n  if (!res.ok) {\n    const serverMessage =\n      typeof body === \"object\" && body !== null && typeof (body as { error?: unknown }).error === \"string\"\n        ? (body as { error: string }).error\n        : undefined\n    throw new ApiError(\n      serverMessage ?? `${res.status} ${res.statusText || \"Request failed\"}`,\n      res.status,\n      body,\n      requestId,\n    )\n  }\n\n  return body as T\n}\n","/**\n * Hooks for the app's own `server/api` routes. They are `useQuery`/`useMutation`\n * with the parts every page was repeating — base URL, JSON parsing, non-2xx to\n * `ApiError`, a query key derived from the URL — moved into the framework.\n * Everything else about TanStack Query stays available through the options.\n */\nimport { useMutation, useQuery } from \"@tanstack/react-query\"\nimport type {\n  QueryKey,\n  UseMutationOptions,\n  UseMutationResult,\n  UseQueryOptions,\n  UseQueryResult,\n} from \"@tanstack/react-query\"\nimport { apiJson, apiPath, type ApiError, type ApiSearch } from \"./api.js\"\n\n/** Query-key namespace, so `invalidateQueries({ queryKey: [\"api\"] })` works. */\nconst API_KEY = \"api\"\n\nexport interface ApiQueryOptions<TData>\n  extends Omit<UseQueryOptions<TData, ApiError>, \"queryKey\" | \"queryFn\"> {\n  /** Query-string values; `undefined` entries are omitted. */\n  search?: ApiSearch\n  /** Extra `fetch` init (headers, credentials, …). */\n  init?: RequestInit\n  /** Override the derived `[\"api\", url]` key. */\n  queryKey?: QueryKey\n}\n\n/**\n * GET an API route.\n *\n * ```tsx\n * const { data, isPending, error } = useApiQuery<Monthly>(\"/api/monthly-analysis\")\n * const filtered = useApiQuery<Row[]>(\"/api/customers\", { search: { segment } })\n * ```\n *\n * The key defaults to `[\"api\", <url with query string>]`, so changing `search`\n * refetches and `invalidateQueries({ queryKey: [\"api\"] })` clears everything.\n */\nexport function useApiQuery<TData = unknown>(\n  path: string,\n  options: ApiQueryOptions<TData> = {},\n): UseQueryResult<TData, ApiError> {\n  const { search, init, queryKey, ...rest } = options\n  const url = apiPath(path, search)\n  return useQuery<TData, ApiError>({\n    queryKey: queryKey ?? [API_KEY, url],\n    // The signal comes from TanStack so an unmounted/refetched query aborts;\n    // a caller-supplied signal wins.\n    queryFn: ({ signal }) => apiJson<TData>(url, { ...init, signal: init?.signal ?? signal }),\n    ...rest,\n  })\n}\n\nexport interface ApiMutationOptions<TData, TVariables>\n  extends Omit<UseMutationOptions<TData, ApiError, TVariables>, \"mutationFn\"> {\n  /** HTTP method (default `\"POST\"`). */\n  method?: \"POST\" | \"PUT\" | \"PATCH\" | \"DELETE\"\n  /** Extra `fetch` init (headers, credentials, …). */\n  init?: RequestInit\n}\n\n/**\n * Write to an API route. The mutation variables are sent as the JSON body.\n *\n * ```tsx\n * const save = useApiMutation<Customer, { id: string; name: string }>(\n *   (vars) => `/api/customers/${vars.id}`,\n *   { method: \"PUT\" },\n * )\n * save.mutate({ id: \"1\", name: \"Northwind\" })\n * ```\n */\nexport function useApiMutation<TData = unknown, TVariables = void>(\n  path: string | ((variables: TVariables) => string),\n  options: ApiMutationOptions<TData, TVariables> = {},\n): UseMutationResult<TData, ApiError, TVariables> {\n  const { method = \"POST\", init, ...rest } = options\n  return useMutation<TData, ApiError, TVariables>({\n    mutationFn: (variables: TVariables) => {\n      const url = typeof path === \"function\" ? path(variables) : path\n      const hasBody = variables !== undefined && variables !== null\n      return apiJson<TData>(url, {\n        method,\n        ...init,\n        headers: hasBody\n          ? { \"content-type\": \"application/json\", ...(init?.headers as Record<string, string>) }\n          : init?.headers,\n        ...(hasBody ? { body: JSON.stringify(variables) } : {}),\n      })\n    },\n    ...rest,\n  })\n}\n"]}

package/dist/router/index.d.ts

@@ -1,6 +1,91 @@
 export { Outlet, notFound, redirect, useRouterState } from '@tanstack/react-router';
 import { ReactNode } from 'react';
 
+/**
+ * The app's route list, published once by the client bootstrap and read by the
+ * route hooks. A module-level store rather than React context: the list is
+ * fixed for the lifetime of the bundle — the generated route tree is imported
+ * by `.vantage/client-entry.tsx`, which accepts no HMR update, so adding a page
+ * full-reloads the dev server — and pages can read it without a provider.
+ *
+ * `client/bootstrap` and `router/` are separate published subpaths but tsup
+ * hoists this module into a shared chunk, so both see the same instance.
+ */
+
+/** One page route, as described by the generated manifest. */
+interface RouteInfo {
+    /** Display path with `:param` placeholders — e.g. `/sales/:customerId`. */
+    path: string;
+    /** The same path in `Link`'s token form — e.g. `/sales/$customerId`. */
+    to: string;
+    /** Dynamic parameter names in order; a catch-all is reported as `_splat`. */
+    params: string[];
+    /** True when the route carries at least one dynamic parameter. */
+    dynamic: boolean;
+    /** True for a directory's index route (`index.tsx`). */
+    index: boolean;
+    /**
+     * Ready-to-render nav label: `navLabel`, else `title`, else the path. Always
+     * a string, so a nav needs no fallback of its own.
+     */
+    label: string;
+    /** `definePage({ title })`, extracted statically at generate time. */
+    title?: string;
+    /** `definePage({ description })`. */
+    description?: string;
+    /** `definePage({ navLabel })`. */
+    navLabel?: string;
+}
+
+/**
+ * Every page route in the app, in the framework's scan order (shallow before
+ * deep, static before dynamic, alphabetical) — the order a nav wants.
+ *
+ * ```tsx
+ * // Dynamic routes have no single URL, so a nav lists only static ones.
+ * const routes = useRoutes().filter((route) => !route.dynamic)
+ * routes.map((route) => <Link key={route.path} to={route.to}>{route.label}</Link>)
+ * ```
+ */
+declare function useRoutes(): readonly RouteInfo[];
+/**
+ * The route currently rendered, or `undefined` on the 404 route (no page
+ * matched). Use it for breadcrumbs or a page header that mirrors `definePage`.
+ */
+declare function useCurrentRoute(): RouteInfo | undefined;
+
+interface SearchStateOptions {
+    /**
+     * Replace the current history entry instead of pushing a new one.
+     * Defaults to `true` so dragging a slider doesn't fill the back button.
+     */
+    replace?: boolean;
+}
+/**
+ * A string search param, as `useState`. The value is always a string —
+ * TanStack parses `?year=2024` into a number, and this hook normalizes it back.
+ *
+ * ```tsx
+ * const [region, setRegion] = useSearchParam("region", "all")
+ * <SegmentedControl value={region} onValueChange={setRegion} options={REGIONS} />
+ * ```
+ *
+ * Writing the default value (or `null`) drops the key from the URL.
+ */
+declare function useSearchParam(key: string, defaultValue?: string, options?: SearchStateOptions): [string, (value: string | null) => void];
+/**
+ * Any JSON-serializable search param, as `useState` — arrays for a multi-select,
+ * an object for a whole filter bar. Supports a functional update.
+ *
+ * ```tsx
+ * const [segments, setSegments] = useSearchState<string[]>("segments", [])
+ * setSegments((prev) => [...prev, "enterprise"])
+ * ```
+ *
+ * Writing a value deep-equal to the default drops the key from the URL.
+ */
+declare function useSearchState<T>(key: string, defaultValue: T, options?: SearchStateOptions): [T, (value: T | ((prev: T) => T)) => void];
+
 /**
  * Vantage's thin router API. Users depend on `@squadbase/vantage/router`
  * instead of `@tanstack/react-router`, so the underlying router can evolve
@@ -33,4 +118,4 @@ declare function useNavigate(): (opts: {
     replace?: boolean;
 }) => void;
 
-export { Link, type LinkProps, useNavigate, useParams, useSearch };
+export { Link, type LinkProps, type RouteInfo, type SearchStateOptions, useCurrentRoute, useNavigate, useParams, useRoutes, useSearch, useSearchParam, useSearchState };

package/dist/router/index.js

@@ -1,9 +1,73 @@
-import { Link as Link$1, useParams as useParams$1, useSearch as useSearch$1, useNavigate as useNavigate$1 } from '@tanstack/react-router';
+import { getRoutes, findRoute } from '../chunk-7IPAXPPY.js';
+import { useRouterState, Link as Link$1, useParams as useParams$1, useSearch, useNavigate } from '@tanstack/react-router';
 export { Outlet, notFound, redirect, useRouterState } from '@tanstack/react-router';
-import { createElement } from 'react';
+import { useCallback, createElement } from 'react';
 
 // @squadbase/vantage — generated build. Do not edit.
+function useRoutes() {
+  return getRoutes();
+}
+function useCurrentRoute() {
+  const path = useRouterState({
+    select: (state) => {
+      const matches = state.matches;
+      const leaf = matches[matches.length - 1];
+      return leaf?.staticData?.routePath;
+    }
+  });
+  return path ? findRoute(path) : void 0;
+}
+function useRawSearch() {
+  return useSearch({ strict: false });
+}
+function useSearchWriter(key, options) {
+  const navigate = useNavigate();
+  const replace = options.replace ?? true;
+  return useCallback(
+    (next) => {
+      navigate({
+        search: (prev) => {
+          const merged = { ...prev };
+          if (next === void 0) delete merged[key];
+          else merged[key] = next;
+          return merged;
+        },
+        replace
+      });
+    },
+    [navigate, key, replace]
+  );
+}
+function useSearchParam(key, defaultValue = "", options = {}) {
+  const search = useRawSearch();
+  const write = useSearchWriter(key, options);
+  const raw = search[key];
+  const value = raw === void 0 || raw === null ? defaultValue : String(raw);
+  const set = useCallback(
+    (next) => {
+      write(next === null || next === defaultValue ? void 0 : next);
+    },
+    [write, defaultValue]
+  );
+  return [value, set];
+}
+function useSearchState(key, defaultValue, options = {}) {
+  const search = useRawSearch();
+  const write = useSearchWriter(key, options);
+  const raw = search[key];
+  const value = raw === void 0 || raw === null ? defaultValue : raw;
+  const set = useCallback(
+    (next) => {
+      const resolved = typeof next === "function" ? next(value) : next;
+      const isDefault = JSON.stringify(resolved) === JSON.stringify(defaultValue);
+      write(isDefault ? void 0 : resolved);
+    },
+    [write, value, defaultValue]
+  );
+  return [value, set];
+}
 
+// src/router/index.ts
 function Link({ activeClassName, className, ...props }) {
   const anyLink = Link$1;
   return createElement(anyLink, {
@@ -15,13 +79,13 @@ function Link({ activeClassName, className, ...props }) {
 function useParams() {
   return useParams$1({ strict: false });
 }
-function useSearch() {
-  return useSearch$1({ strict: false });
+function useSearch2() {
+  return useSearch({ strict: false });
 }
-function useNavigate() {
-  return useNavigate$1();
+function useNavigate2() {
+  return useNavigate();
 }
 
-export { Link, useNavigate, useParams, useSearch };
+export { Link, useCurrentRoute, useNavigate2 as useNavigate, useParams, useRoutes, useSearch2 as useSearch, useSearchParam, useSearchState };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/router/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/router/index.ts"],"names":["TanstackLink","useParamsBase","useSearchBase","useNavigateBase"],"mappings":";;;;;;AAiCO,SAAS,KAAK,EAAE,eAAA,EAAiB,SAAA,EAAW,GAAG,OAAM,EAAyB;AAEnF,EAAA,MAAM,OAAA,GAAUA,MAAA;AAChB,EAAA,OAAO,cAAc,OAAA,EAAS;AAAA,IAC5B,GAAG,KAAA;AAAA,IACH,SAAA;AAAA,IACA,WAAA,EAAa,eAAA,GAAkB,EAAE,SAAA,EAAW,CAAA,EAAG,SAAA,IAAa,EAAE,CAAA,CAAA,EAAI,eAAe,CAAA,CAAA,CAAG,IAAA,EAAK,EAAE,GAAI;AAAA,GAChG,CAAA;AACH;AAGO,SAAS,SAAA,GAAoC;AAElD,EAAA,OAAOC,WAAA,CAAc,EAAE,MAAA,EAAQ,KAAA,EAAO,CAAA;AACxC;AAGO,SAAS,SAAA,GAAqC;AAEnD,EAAA,OAAOC,WAAA,CAAc,EAAE,MAAA,EAAQ,KAAA,EAAO,CAAA;AACxC;AAGO,SAAS,WAAA,GAAoI;AAElJ,EAAA,OAAOC,aAAA,EAAgB;AACzB","file":"index.js","sourcesContent":["/**\n * Vantage's thin router API. Users depend on `@squadbase/vantage/router`\n * instead of `@tanstack/react-router`, so the underlying router can evolve\n * without touching user code. Only the ergonomic, SPA-relevant surface is\n * exposed; typed-route generics are intentionally relaxed to plain strings.\n */\nimport {\n  Link as TanstackLink,\n  Outlet,\n  useNavigate as useNavigateBase,\n  useParams as useParamsBase,\n  useSearch as useSearchBase,\n  useRouterState,\n  redirect,\n  notFound,\n} from \"@tanstack/react-router\"\nimport { createElement, type ReactNode } from \"react\"\n\nexport { Outlet, useRouterState, redirect, notFound }\n\nexport interface LinkProps {\n  to: string\n  params?: Record<string, string>\n  search?: Record<string, unknown>\n  hash?: string\n  replace?: boolean\n  className?: string\n  activeClassName?: string\n  children?: ReactNode\n  [key: string]: unknown\n}\n\n/** Client-side navigation link. */\nexport function Link({ activeClassName, className, ...props }: LinkProps): ReactNode {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const anyLink = TanstackLink as any\n  return createElement(anyLink, {\n    ...props,\n    className,\n    activeProps: activeClassName ? { className: `${className ?? \"\"} ${activeClassName}`.trim() } : undefined,\n  })\n}\n\n/** Route params for the current route (e.g. `{ customerId: \"42\" }`). */\nexport function useParams(): Record<string, string> {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  return useParamsBase({ strict: false }) as any\n}\n\n/** Validated/raw search params for the current route. */\nexport function useSearch(): Record<string, unknown> {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  return useSearchBase({ strict: false }) as any\n}\n\n/** Imperative navigation. `navigate({ to: \"/sales/42\" })`. */\nexport function useNavigate(): (opts: { to: string; params?: Record<string, string>; search?: Record<string, unknown>; replace?: boolean }) => void {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  return useNavigateBase() as any\n}\n"]}
+{"version":3,"sources":["../../src/router/routes.ts","../../src/router/search.ts","../../src/router/index.ts"],"names":["TanstackLink","useParamsBase","useSearch","useSearchBase","useNavigate","useNavigateBase"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Route-introspection hooks. The route list comes from the generated manifest,\n * so a nav built on `useRoutes()` picks up a new page file the moment it is\n * created — no hand-maintained link array.\n */\nimport { useRouterState } from \"@tanstack/react-router\"\nimport { findRoute, getRoutes, type RouteInfo } from \"./registry.js\"\n\n/**\n * Every page route in the app, in the framework's scan order (shallow before\n * deep, static before dynamic, alphabetical) — the order a nav wants.\n *\n * ```tsx\n * // Dynamic routes have no single URL, so a nav lists only static ones.\n * const routes = useRoutes().filter((route) => !route.dynamic)\n * routes.map((route) => <Link key={route.path} to={route.to}>{route.label}</Link>)\n * ```\n */\nexport function useRoutes(): readonly RouteInfo[] {\n  return getRoutes()\n}\n\n/**\n * The route currently rendered, or `undefined` on the 404 route (no page\n * matched). Use it for breadcrumbs or a page header that mirrors `definePage`.\n */\nexport function useCurrentRoute(): RouteInfo | undefined {\n  // Selecting the path string (not the match object) keeps the subscription\n  // stable — the component re-renders on navigation, not on every router tick.\n  const path = useRouterState({\n    select: (state) => {\n      const matches = state.matches\n      const leaf = matches[matches.length - 1] as\n        | { staticData?: { routePath?: string } }\n        | undefined\n      return leaf?.staticData?.routePath\n    },\n  })\n  return path ? findRoute(path) : undefined\n}\n","/**\n * URL-backed component state. A dashboard's filters belong in the URL: the view\n * survives a reload and can be pasted to a colleague. These hooks read and write\n * a single search-param key with a `useState`-shaped API.\n */\nimport { useCallback } from \"react\"\nimport { useNavigate, useSearch } from \"@tanstack/react-router\"\n\nexport interface SearchStateOptions {\n  /**\n   * Replace the current history entry instead of pushing a new one.\n   * Defaults to `true` so dragging a slider doesn't fill the back button.\n   */\n  replace?: boolean\n}\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\n\nfunction useRawSearch(): Record<string, unknown> {\n  return useSearch({ strict: false }) as any\n}\n\n/**\n * Writer for one key. Passing `undefined` removes the key so defaults never\n * show up in the URL.\n */\nfunction useSearchWriter(key: string, options: SearchStateOptions): (next: unknown) => void {\n  const navigate = useNavigate() as any\n  const replace = options.replace ?? true\n  return useCallback(\n    (next: unknown) => {\n      // No `to`: TanStack keeps the current route and its path params, so this\n      // works unchanged on a dynamic route like `/sales/$customerId`.\n      navigate({\n        search: (prev: Record<string, unknown>) => {\n          const merged = { ...prev }\n          if (next === undefined) delete merged[key]\n          else merged[key] = next\n          return merged\n        },\n        replace,\n      })\n    },\n    [navigate, key, replace],\n  )\n}\n\n/**\n * A string search param, as `useState`. The value is always a string —\n * TanStack parses `?year=2024` into a number, and this hook normalizes it back.\n *\n * ```tsx\n * const [region, setRegion] = useSearchParam(\"region\", \"all\")\n * <SegmentedControl value={region} onValueChange={setRegion} options={REGIONS} />\n * ```\n *\n * Writing the default value (or `null`) drops the key from the URL.\n */\nexport function useSearchParam(\n  key: string,\n  defaultValue = \"\",\n  options: SearchStateOptions = {},\n): [string, (value: string | null) => void] {\n  const search = useRawSearch()\n  const write = useSearchWriter(key, options)\n\n  const raw = search[key]\n  const value = raw === undefined || raw === null ? defaultValue : String(raw)\n\n  const set = useCallback(\n    (next: string | null) => {\n      write(next === null || next === defaultValue ? undefined : next)\n    },\n    [write, defaultValue],\n  )\n\n  return [value, set]\n}\n\n/**\n * Any JSON-serializable search param, as `useState` — arrays for a multi-select,\n * an object for a whole filter bar. Supports a functional update.\n *\n * ```tsx\n * const [segments, setSegments] = useSearchState<string[]>(\"segments\", [])\n * setSegments((prev) => [...prev, \"enterprise\"])\n * ```\n *\n * Writing a value deep-equal to the default drops the key from the URL.\n */\nexport function useSearchState<T>(\n  key: string,\n  defaultValue: T,\n  options: SearchStateOptions = {},\n): [T, (value: T | ((prev: T) => T)) => void] {\n  const search = useRawSearch()\n  const write = useSearchWriter(key, options)\n\n  const raw = search[key]\n  const value = raw === undefined || raw === null ? defaultValue : (raw as T)\n\n  const set = useCallback(\n    (next: T | ((prev: T) => T)) => {\n      const resolved = typeof next === \"function\" ? (next as (prev: T) => T)(value) : next\n      // Structural comparison: the parsed value is plain JSON, so stringify is\n      // both sufficient and cheap at filter sizes.\n      const isDefault = JSON.stringify(resolved) === JSON.stringify(defaultValue)\n      write(isDefault ? undefined : resolved)\n    },\n    [write, value, defaultValue],\n  )\n\n  return [value, set]\n}\n","/**\n * Vantage's thin router API. Users depend on `@squadbase/vantage/router`\n * instead of `@tanstack/react-router`, so the underlying router can evolve\n * without touching user code. Only the ergonomic, SPA-relevant surface is\n * exposed; typed-route generics are intentionally relaxed to plain strings.\n */\nimport {\n  Link as TanstackLink,\n  Outlet,\n  useNavigate as useNavigateBase,\n  useParams as useParamsBase,\n  useSearch as useSearchBase,\n  useRouterState,\n  redirect,\n  notFound,\n} from \"@tanstack/react-router\"\nimport { createElement, type ReactNode } from \"react\"\n\nexport { Outlet, useRouterState, redirect, notFound }\n\nexport { useRoutes, useCurrentRoute } from \"./routes.js\"\nexport type { RouteInfo } from \"./registry.js\"\n\nexport { useSearchParam, useSearchState } from \"./search.js\"\nexport type { SearchStateOptions } from \"./search.js\"\n\nexport interface LinkProps {\n  to: string\n  params?: Record<string, string>\n  search?: Record<string, unknown>\n  hash?: string\n  replace?: boolean\n  className?: string\n  activeClassName?: string\n  children?: ReactNode\n  [key: string]: unknown\n}\n\n/** Client-side navigation link. */\nexport function Link({ activeClassName, className, ...props }: LinkProps): ReactNode {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const anyLink = TanstackLink as any\n  return createElement(anyLink, {\n    ...props,\n    className,\n    activeProps: activeClassName ? { className: `${className ?? \"\"} ${activeClassName}`.trim() } : undefined,\n  })\n}\n\n/** Route params for the current route (e.g. `{ customerId: \"42\" }`). */\nexport function useParams(): Record<string, string> {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  return useParamsBase({ strict: false }) as any\n}\n\n/** Validated/raw search params for the current route. */\nexport function useSearch(): Record<string, unknown> {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  return useSearchBase({ strict: false }) as any\n}\n\n/** Imperative navigation. `navigate({ to: \"/sales/42\" })`. */\nexport function useNavigate(): (opts: { to: string; params?: Record<string, string>; search?: Record<string, unknown>; replace?: boolean }) => void {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  return useNavigateBase() as any\n}\n"]}

package/dist/vite/index.js

@@ -1,4 +1,4 @@
-export { vantagePlugin } from '../chunk-PRFBSQA4.js';
+export { vantagePlugin } from '../chunk-5L2MH2NG.js';
 import '../chunk-YLAB6UQS.js';
 import '../chunk-B7LLBNLV.js';
 //# sourceMappingURL=index.js.map

package/docs/en/components.md

@@ -124,6 +124,7 @@ Dashboard parts composed from `ui/`.
 | [`DataTable`](parts/data-table) | Sorting, search, pagination, selection |
 | [`EChart`](parts/echart) | The Apache ECharts wrapper |
 | [`FunnelSteps`](parts/funnel-steps) | A funnel drawn as bars |
+| [`Sparkline`](parts/sparkline) | An inline trend chart for cells and tiles |
 | [`FilterBar`](parts/filter-bar) | A row of filters driven by one value |
 | [`DateRangePicker`](parts/date-range-picker) | Date range with presets |
 | [`SegmentedControl`](parts/segmented-control) | Single-choice segments |
@@ -132,6 +133,7 @@ Dashboard parts composed from `ui/`.
 | [`MetricValue`](parts/metric-value) | A KPI's number and unit |
 | [`TrendIndicator`](parts/trend-indicator) | An arrow and a percentage |
 | [`StatusBadge`](parts/status-badge) | A dot-and-label status badge |
+| [`Placeholder`](parts/placeholder) | An inline marker for sample data |
 
 ## `@squadbase/vantage/markdown`
 

package/docs/en/data-fetching.md

@@ -3,7 +3,8 @@
 > Handle server state with a managed TanStack Query (useQuery).
 
 Vantage ships a **managed TanStack Query** for server state. There is no `QueryClient` to set up —
-just import `useQuery` and friends from `@squadbase/vantage/query`.
+just import `useQuery` and friends from `@squadbase/vantage/query`. To call your own `server/api`,
+[`useApiQuery`](#call-your-own-api--useapiquery) below is the shortcut.
 
 ```tsx
 import { useQuery } from "@squadbase/vantage/query";
@@ -39,6 +40,12 @@ Vantage provides exactly one `QueryClient` with these defaults:
 | `staleTime` | 30 seconds |
 | `retry` | 1 |
 | `refetchOnWindowFocus` | `false` |
+| `networkMode` | `"always"` (queries and mutations) |
+
+`networkMode: "always"` requests and retries regardless of the browser's offline heuristic. Under
+the default `"online"`, a failed query is *paused* the moment that heuristic reads offline — no
+error, just a loading state that never resolves. A dashboard talks to its own origin (or the
+configured API base), where that heuristic says nothing useful.
 
 Customize by **overriding per query**. Swapping the whole `QueryClient` is intentionally not exposed,
 to keep the stack managed.
@@ -57,21 +64,78 @@ useQuery({
 > Do not import `@tanstack/react-query` directly. Using the curated re-exports from
 > `@squadbase/vantage/query` lets Vantage evolve the underlying library safely.
 
-## Pairing with the API
+## Call your own API — useApiQuery
+
+For routes under `server/api`, use `useApiQuery`. It is `useQuery` plus the boilerplate every page
+was repeating: base-URL resolution, JSON parsing, non-2xx to an error, and a query key.
+
+```tsx
+import { useApiQuery } from "@squadbase/vantage/query";
+
+interface Monthly {
+  monthly: { month: string; revenue: number }[];
+}
+
+export default function MonthlyAnalysis() {
+  const { data, isPending, error } = useApiQuery<Monthly>("/api/monthly-analysis");
+
+  if (isPending) return <p>Loading…</p>;
+  if (error) return <p>{error.message}</p>;
+  return <Chart data={data.monthly} />;
+}
+```
+
+Pass the query string as `search`. `undefined` entries are dropped, so an unset filter appears
+neither in the URL nor in the query key.
+
+```tsx
+const query = useApiQuery<Row[]>("/api/customers", {
+  search: { segment, from: range.from, to: range.to },
+  enabled: Boolean(segment), // any useQuery option still works
+});
+```
+
+The query key defaults to `["api", <url with query string>]`, so changing `search` refetches, and
+`invalidateQueries({ queryKey: ["api"] })` drops everything that came from the API.
+
+### Errors arrive as ApiError
+
+A non-2xx response is thrown as an `ApiError`. Its `message` is what the API chose to disclose with
+[`HttpError`](api-and-server); anything else surfaces as generic status text.
+
+| Property | Contents |
+|---|---|
+| `message` | The message the server set with `HttpError` |
+| `status` | HTTP status |
+| `body` | Parsed response body |
+| `requestId` | `x-vantage-request-id`, to correlate with the dev terminal log |
+
+### Writes with useApiMutation
+
+The mutation variables are sent as the JSON body. The path may be a function.
+
+```tsx
+import { useApiMutation, useQueryClient } from "@squadbase/vantage/query";
+
+const queryClient = useQueryClient();
+const save = useApiMutation<Customer, { id: string; name: string }>(
+  (vars) => `/api/customers/${vars.id}`,
+  {
+    method: "PUT",
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["api"] }),
+  },
+);
+
+save.mutate({ id: "1", name: "Northwind" });
+```
 
-Calling `/api/*` inside `queryFn` connects naturally to the [optional server](api-and-server).
-Even a client-only app without `server/` can `fetch` an external API the same way.
+Where a hook doesn't fit (an event handler, say), call `apiJson(path, init)` directly. For the raw
+`Response`, use `apiFetch`.
 
 > [!TIP]
-> When calling the built-in `/api`, use `apiFetch` from `@squadbase/vantage/query` so the base URL can
-> be switched via env (for deploying the client and server on different origins). See
-> [Build & deploy](build-and-deploy) for details.
->
-> ```tsx
-> import { apiFetch } from "@squadbase/vantage/query";
->
-> queryFn: () => apiFetch("/api/customers").then((r) => r.json());
-> ```
+> For an external API, keep using `useQuery` + `fetch`. `useApiQuery` goes through `apiFetch`, so
+> setting [`PUBLIC_API_BASE_URL`](build-and-deploy) lets you deploy the client and server on
+> different origins without touching page code.
 
 ## What to read next
 

package/docs/en/pages-and-metadata.md

@@ -22,7 +22,8 @@ To add a title or description, use `definePage`. It is optional.
 import { definePage } from "@squadbase/vantage";
 
 export const page = definePage({
-  title: "Monthly analysis",
+  title: "Monthly analysis · Acme Analytics",
+  navLabel: "Monthly analysis",
   description: "A monthly summary of revenue and key metrics",
 });
 
@@ -33,8 +34,10 @@ export default function MonthlyAnalysis() {
 
 - `title` drives `document.title` (the deepest route match's title wins; otherwise it falls back to
   the document's initial `<title>`).
-- `title`/`description` are **read statically at generation time**. Vantage parses the source rather
-  than executing your page, so keep the values **literal**.
+- `navLabel` is the name a nav built with [`useRoutes()`](routing#build-a-nav-from-the-route-list)
+  renders. It defaults to `title`; set it separately when `title` carries the site name.
+- `title`/`description`/`navLabel` are **read statically at generation time**. Vantage parses the
+  source rather than executing your page, so keep the values **literal**.
 
 > [!WARNING]
 > The **export name must be `page`** in `export const page = definePage({...})`. A different name means