void 1.4.0 → 1.6.0

package/dist/pages/client.d.mts

@@ -1,9 +1,8 @@
-import { t as interpolateRouteParams } from "../route-url-BgPja1GS.mjs";
-import { t as PageObject } from "../protocol-D5XDySYu.mjs";
-import { n as CacheForInput, r as CacheForResult } from "../prefetch-Ce6la4EI.mjs";
+import { f as toUrlString, u as interpolateRouteParams } from "../route-url-C_YIH_zO.mjs";
+import { t as PageObject } from "../protocol-CkwjASep.mjs";
+import { a as LinkPrefetchValue, i as LinkPrefetchStrategy, n as CacheForInput, r as CacheForResult } from "../prefetch-NdNeubbH.mjs";
 import { UsageLimitData } from "@void/edge";
-import { ActionUrl, ResolveActionBody, ResolveActionParams } from "void/routes";
-//#region src/pages/action-result.d.ts
+import { ActionUrl, Href, ResolveActionBody, ResolveActionParams, RouteUrlInput } from "void/routes";
 type ActionErrorHandlingScope = "callSite" | "boundary";
 type ActionResult<T = PageObject | undefined> = {
   ok: true;
@@ -18,8 +17,9 @@ export declare class VoidActionError extends Error {
   readonly status: number;
   readonly statusText: string;
   readonly url: string;
-  constructor({ body, status, statusText, url }: {
+  constructor({ body, message, status, statusText, url }: {
     body: unknown;
+    message?: string;
     status: number;
     statusText: string;
     url: string;
@@ -28,8 +28,6 @@ export declare class VoidActionError extends Error {
 export declare function categorizeActionError(status: number): ActionErrorHandlingScope;
 export declare function isCallSiteActionError(error: unknown): error is VoidActionError;
 export declare function isAbortError(error: unknown): boolean;
-//#endregion
-//#region src/pages/navigation-engine.d.ts
 type PageComponentModule = {
   default: unknown;
 };
@@ -41,6 +39,8 @@ type VisitOptions = {
   preserveState?: boolean;
   replace?: boolean;
   viewTransition?: boolean;
+  /** React navigation completion: page data readiness or UI commit (default). */
+  resolveOn?: "data" | "commit";
   /** @internal Used by React Actions to avoid waiting for a commit blocked by the action itself. */
   _resolveOnShell?: boolean;
   /** @internal Used by popstate handler to pass saved scroll position */
@@ -78,6 +78,8 @@ type PageNavigationEngineConfig = {
   viewTransitions: boolean;
   prefetchHoverDelay: number;
   prefetchDefaultCacheFor: CacheForResult;
+  /** How Links without a `prefetch` prop prefetch. Defaults to `false`. */
+  prefetchDefaultStrategy?: LinkPrefetchValue;
   /** Reuse successful GET page shells on later visits, refreshing stale shells in the background. */
   cacheVisitedPageData?: boolean;
 };
@@ -102,6 +104,7 @@ type PageNavigationResource = {
 };
 type PageNavigationEngine = {
   _hoverDelay: number;
+  _prefetchDefaultStrategy: LinkPrefetchValue;
   initialPageData: PageData;
   initialComponent: unknown;
   initialLayouts: Array<unknown>;
@@ -118,13 +121,83 @@ export declare function isFile(value: unknown): boolean;
 export declare function hasFiles(data: unknown): boolean;
 export declare function objectToFormData(source: Record<string, unknown>, form?: FormData, parentKey?: string): FormData;
 export declare function createPageNavigationEngine(config: PageNavigationEngineConfig): Promise<PageNavigationEngine>;
-//#endregion
-//#region src/pages/adapter-helpers.d.ts
 export declare function getValidationErrors(body: unknown): Record<string, string> | null;
-export declare function mergeDataIntoHref(href: string, data?: Record<string, unknown>): string;
+export declare function mergeDataIntoHref(href: Href, data?: Record<string, unknown>): Href;
 export declare function isModifiedEvent(e: Pick<MouseEvent, "currentTarget" | "ctrlKey" | "metaKey" | "shiftKey" | "altKey" | "button">): boolean;
-//#endregion
-//#region src/pages/island-action.d.ts
+type LinkNavigateEvent = {
+  preventDefault(): void;
+};
+type LinkActiveMatch = "exact" | "prefix";
+/** Present only when the link matches the current URL. */
+type LinkActiveAttributes = {
+  "aria-current"?: "page";
+  "data-void-active"?: "";
+};
+/** Present only while a visit to the link's destination is loading. */
+type LinkPendingAttributes = {
+  "data-void-pending"?: "";
+};
+/** Props every adapter's Link accepts. Adapters add element attributes and children. */
+type BaseLinkProps = {
+  href: Href;
+  method?: NavigationMethod | Lowercase<NavigationMethod>;
+  data?: Record<string, unknown>;
+  preserveScroll?: boolean;
+  preserveState?: boolean;
+  replace?: boolean;
+  reloadDocument?: boolean;
+  viewTransition?: boolean;
+  /** If omitted, the Link uses the app's `prefetch.defaultStrategy`. */
+  prefetch?: LinkPrefetchValue;
+  cacheFor?: CacheForInput;
+  activeMatch?: LinkActiveMatch;
+  onNavigate?: (event: LinkNavigateEvent) => void;
+};
+type ResolvedLink = {
+  method: NavigationMethod;
+  isGet: boolean;
+  /** The destination, with GET data merged into its query. */
+  href: Href;
+};
+type LinkClickEvent = Pick<MouseEvent, "currentTarget" | "ctrlKey" | "metaKey" | "shiftKey" | "altKey" | "button" | "defaultPrevented" | "preventDefault">;
+type LinkClickProps = Pick<BaseLinkProps, "data" | "preserveScroll" | "preserveState" | "replace" | "reloadDocument" | "viewTransition" | "onNavigate">;
+/** Normalizes the method and destination, rejecting options that only GET links support. */
+export declare function resolveLink(props: Pick<BaseLinkProps, "href" | "method" | "data" | "prefetch" | "reloadDocument">): ResolvedLink;
+/**
+ * The events that prefetch a Link. A Link without a `prefetch` prop uses the app's
+ * `defaultStrategy`, but only when it is a GET link, the only kind that can prefetch.
+ */
+export declare function linkPrefetchStrategies(props: Pick<BaseLinkProps, "prefetch" | "reloadDocument">, link: Pick<ResolvedLink, "isGet">, defaultStrategy?: LinkPrefetchValue): ReadonlyArray<LinkPrefetchStrategy>;
+/**
+ * Marks a GET link to the current page. Pathnames compare the way the server
+ * matches pages: case-sensitive, trailing slash significant, decoded like Hono's
+ * getPath. The query and hash are ignored. `prefix` also matches nested pages by
+ * whole segment, except for `/`, but only an exact match is `aria-current`.
+ * Spread the result before the user's attributes so theirs win.
+ */
+export declare function linkActiveAttributes(router: VoidRouter | null | undefined, link: ResolvedLink, match?: LinkActiveMatch): LinkActiveAttributes;
+/**
+ * Marks a link while a visit to its destination is loading: the visit uses the link's
+ * method and goes to its path, query and hash. Unlike active links, the query counts,
+ * so `?page=2` isn't pending during a visit to `?page=3`. Every link to the destination
+ * is marked, not only the one that was clicked.
+ * Spread the result before the user's attributes so theirs win.
+ */
+export declare function linkPendingAttributes(router: VoidRouter | null | undefined, navigation: NavigationState | null | undefined, link: ResolvedLink): LinkPendingAttributes;
+/** Link's automatic prefetch. `router.prefetch()` called directly is not limited by the connection. */
+export declare function prefetchLink(router: VoidRouter | null | undefined, href: Href, cacheFor: CacheForInput | undefined): void;
+/**
+ * Runs a client-side visit for a plain same-origin click. Modified clicks, downloads,
+ * cross-origin destinations and `reloadDocument` links are left to the browser.
+ * Call it after the user's own click handler so its `preventDefault()` is respected.
+ */
+export declare function handleLinkClick(event: LinkClickEvent, router: VoidRouter | null | undefined, link: ResolvedLink, props: LinkClickProps): void;
+/**
+ * Calls `onVisible` once, after `element` has stayed in the viewport for
+ * `LINK_VISIBLE_PREFETCH_DELAY` ms. Leaving the viewport cancels the wait and entering
+ * again restarts it. Returns a cleanup that also cancels a pending wait.
+ */
+export declare function observeLinkVisible(element: Element, onVisible: () => void): () => void;
 type IslandActionResult = {
   kind: "redirect";
   url: string;
@@ -138,11 +211,7 @@ type IslandActionResult = {
   error: VoidActionError;
 };
 export declare function submitIslandAction(url: string, method: string, data: Record<string, unknown>): Promise<IslandActionResult>;
-//#endregion
-//#region src/pages/form-value-equality.d.ts
 export declare function isEqualFormValue(a: unknown, b: unknown): boolean;
-//#endregion
-//#region src/pages/form-reset.d.ts
 type FormResetOptions = {
   initial?: boolean;
 };
@@ -152,21 +221,66 @@ export declare function parseFormResetArgs(args: ReadonlyArray<string | FormRese
   initial: boolean;
   fields: ReadonlyArray<string>;
 };
-//#endregion
-//#region src/pages/form-presentation.d.ts
 type FormMethod = "post" | "put" | "patch" | "delete";
-type FormModel<Args extends Array<unknown> = []> = {
-  readonly pending: boolean;
-  readonly error: VoidActionError | null;
+type FormModel<Args extends Array<unknown> = []> = Pick<FormStatus, "pending" | "error"> & {
   readonly errors: Readonly<Record<string, string | undefined>>;
 } & { [K in FormMethod]: (...args: Args) => void | Promise<void>; };
+/** Router options a `useForm()` submission accepts in adapters whose submit methods take options. */
+type FormSubmitOptions = Omit<VisitOptions, "method" | "data"> & {
+  data?: Record<string, unknown>;
+};
+/** Submission state that `useForm()` and `useIslandForm()` report in every adapter. */
+type FormStatus = {
+  readonly error: VoidActionError | null;
+  readonly pending: boolean;
+  readonly hasChanges: boolean;
+  readonly wasSuccessful: boolean;
+  readonly recentlySuccessful: boolean;
+};
+/** Field-keyed validation messages; a field without an error is absent. */
+type FormErrors<TData> = Partial<Record<keyof TData & string, string>>;
+/**
+ * How an adapter's apps change `data` and `errors`, following its framework's idiom.
+ * `'in-place'`: apps edit them directly (Vue, Svelte).
+ * `'setters'`: they are read-only and change through adapter setters such as `setData` (React, Solid).
+ */
+type FormEditing = "in-place" | "setters";
+type FormFields<TData, TErrors, TEditing extends FormEditing> = [TEditing] extends ["setters"] ? {
+  readonly data: Readonly<TData>;
+  readonly errors: Readonly<TErrors>;
+} : {
+  readonly data: TData;
+  readonly errors: TErrors;
+};
+/**
+ * The `useForm()` contract every adapter shares. Field names are typed from the action body.
+ * Adapters add their submit methods.
+ */
+type FormState<TData, TEditing extends FormEditing> = FormStatus & FormFields<TData, FormErrors<TData>, TEditing> & Readonly<{
+  reset(options: FormResetOptions, ...fields: ReadonlyArray<keyof TData & string>): void;
+  reset(...fields: ReadonlyArray<keyof TData & string>): void;
+  setError(field: keyof TData & string, message: string): void;
+  clearErrors(...fields: ReadonlyArray<keyof TData & string>): void;
+  clearError(): void;
+}>;
+/**
+ * The `useIslandForm()` contract every adapter shares. Errors are keyed by whatever names the
+ * action returns, not only the default fields. Submit methods take the action URL.
+ */
+type IslandFormState<TData, TEditing extends FormEditing> = FormStatus & FormFields<TData, Partial<Record<string, string>>, TEditing> & Readonly<{
+  reset(...fields: ReadonlyArray<keyof TData & string>): void;
+  clearErrors(...fields: ReadonlyArray<string>): void;
+  clearError(): void;
+  post(url: string): Promise<void>;
+  put(url: string): Promise<void>;
+  patch(url: string): Promise<void>;
+  delete(url: string): Promise<void>;
+}>;
 export declare function formErrorMessage(form: Pick<FormModel, "error" | "errors">): string | null;
 export declare function formRetryMessage(error: VoidActionError | null): string | null;
 export declare function formSubmissionBlocked(form: Pick<FormModel, "pending" | "error">, now?: number): boolean;
 /** One deadline, capped for browser timers; no polling and no automatic submission. */
 export declare function scheduleFormRetry(error: VoidActionError | null, ready: () => void): () => void;
-//#endregion
-//#region src/pages/client.d.ts
 export type NavigationStateType = "idle" | "loading" | "submitting";
 export type NavigationMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 export type NavigationState = {
@@ -176,14 +290,16 @@ export type NavigationState = {
 };
 export type VoidRouter = {
   _hoverDelay: number;
+  /** How Links without a `prefetch` prop prefetch. Absent during SSR. */
+  _prefetchDefaultStrategy?: LinkPrefetchValue;
   readonly url: URL;
   readonly path: string;
   readonly query: URLSearchParams;
   readonly params: Record<string, string>;
-  visit(url: string | URL, options?: VisitOptions): Promise<unknown>;
+  visit(url: RouteUrlInput, options?: VisitOptions): Promise<unknown>;
   refresh(options?: VisitOptions): Promise<unknown>;
-  prefetch(url: string | URL, options?: PrefetchOptions): Promise<unknown>;
-  flush(url: string | URL, method?: string): void;
+  prefetch(url: RouteUrlInput, options?: PrefetchOptions): Promise<unknown>;
+  flush(url: RouteUrlInput, method?: string): void;
   flushAll(): void;
 };
 export type VoidRouterAdapter = VoidRouterAdapter$1 & {
@@ -198,7 +314,7 @@ export type VoidRouterConfig = Omit<PageNavigationEngineConfig, "adapter"> & {
 };
 export declare function idleNavigationState(): NavigationState;
 export declare function createRouterFacade(router: VoidRouter, getCurrentUrl: () => string, getCurrentParams?: () => Record<string, string>): VoidRouter;
-export declare function createSsrRouter(url?: string, params?: Record<string, string>): VoidRouter;
+export declare function createSsrRouter(url?: string, params?: Record<string, string>, requestUrl?: string): VoidRouter;
 export declare const ssrProxy: VoidRouter;
 /** Refetch the current page in place: same history entry, URL hash, state and scroll. */
 export declare function refreshPage(router: Pick<VoidRouter, "visit">, options?: VisitOptions): Promise<unknown>;
@@ -208,6 +324,7 @@ type HasParams<U extends string> = [ResolveActionParams<U>] extends [never] ? fa
 type ActionOptions<U extends string> = {
   data?: ResolveActionBody<U>;
   method?: ActionMethod;
+  preserveScroll?: boolean;
 } & (HasParams<U> extends true ? {
   params: ResolveActionParams<U>;
 } : {
@@ -218,7 +335,7 @@ export type ActionClient = {
   action<U extends ActionUrl & string>(url: U, ...args: HasParams<U> extends true ? [options: ActionOptions<U>] : [options?: ActionOptions<U>]): Promise<ActionResult>;
 };
 /** Creates an action client with its own router for each framework adapter. */
-export declare function createActionClient(): ActionClient;
+export declare function createActionClient(defaults?: Pick<VisitOptions, "_resolveOnShell">): ActionClient;
 export declare function createVoidRouter(config: VoidRouterConfig): Promise<{
   router: VoidRouter;
   initialPageData: PageData;
@@ -229,5 +346,4 @@ export declare function createVoidRouter(config: VoidRouterConfig): Promise<{
 }>;
 export declare function scheduleHydration(el: Element, loader: () => Promise<unknown>, props: Record<string, unknown>, strategy: string, hydrateFn: (el: Element, mod: unknown, props: Record<string, unknown>) => void | Promise<void>): void;
 export declare function initIslands(islands: Record<string, () => Promise<unknown>>, hydrateFn: (el: Element, mod: unknown, props: Record<string, unknown>, frontmatter: Record<string, unknown>) => void | Promise<void>): void;
-//#endregion
-export { type ActionErrorHandlingScope, type ActionResult, type FormMethod, type FormModel, type FormResetOptions, type IslandActionResult, type PageNavigationEngine, type PageNavigationResource, type PageNavigationResult, type PrefetchOptions, type VisitOptions, interpolateRouteParams };
+export { type ActionErrorHandlingScope, type ActionResult, type BaseLinkProps, type FormMethod, type FormModel, type FormResetOptions, type FormState, type FormSubmitOptions, type IslandActionResult, type IslandFormState, type LinkActiveAttributes, type LinkActiveMatch, type LinkNavigateEvent, type LinkPendingAttributes, type LinkPrefetchStrategy, type LinkPrefetchValue, type PageNavigationEngine, type PageNavigationResource, type PageNavigationResult, type PrefetchOptions, type ResolvedLink, type VisitOptions, interpolateRouteParams, toUrlString };