@wular/pnext 0.0.1

package/src/api/dynamic.tsx

@@ -0,0 +1,102 @@
+import { h, type ComponentType } from 'preact';
+import { useEffect, useRef, useState } from 'preact/hooks';
+
+export type DynamicModule<Props> = ComponentType<Props> | { default: ComponentType<Props> };
+export type DynamicLoader<Props> = string | (() => Promise<DynamicModule<Props>>);
+export const dynamicReferenceSymbol = Symbol.for('pnext.dynamic');
+
+export interface DynamicTarget {
+  file: string;
+  exportName: string;
+}
+
+export interface DynamicReference<Props extends object = object> {
+  load: () => Promise<ComponentType<Props>>;
+  target?: DynamicTarget;
+}
+
+export interface DynamicOptions<Props> {
+  loading?: ComponentType<Props>;
+  load?: 'render' | 'visible';
+  rootMargin?: string;
+  ssr?: boolean;
+  threshold?: number | number[];
+}
+
+export function dynamic<Props extends object = object>(
+  loader: DynamicLoader<Props>,
+  options: DynamicOptions<Props> = {},
+  // Injected by the server compile (rewriteDynamicCallTargets); app code
+  // never passes this.
+  target?: DynamicTarget,
+) {
+  let loaded: ComponentType<Props> | null = null;
+  let pending: Promise<ComponentType<Props>> | null = null;
+  const loadModule = typeof loader === 'string'
+    ? () => {
+        throw new Error(`dynamic(${JSON.stringify(loader)}) was not compiled by PNext.`);
+      }
+    : loader;
+
+  const load = () => {
+    pending ??= Promise.resolve(loadModule()).then(module => {
+      loaded = typeof module === 'function' ? module : module.default;
+      return loaded;
+    });
+    return pending;
+  };
+
+  function DynamicComponent(props: Props) {
+    const [Component, setComponent] = useState<ComponentType<Props> | null>(() => loaded);
+    const [shouldLoad, setShouldLoad] = useState(() => options.load !== 'visible');
+    const visibleRef = useRef<HTMLDivElement>(null);
+
+    useEffect(() => {
+      if (Component || shouldLoad) return;
+      const node = visibleRef.current;
+      if (!node || typeof IntersectionObserver === 'undefined') {
+        setShouldLoad(true);
+        return;
+      }
+
+      const observer = new IntersectionObserver(
+        entries => {
+          if (!entries.some(entry => entry.isIntersecting)) return;
+          observer.disconnect();
+          setShouldLoad(true);
+        },
+        {
+          rootMargin: options.rootMargin,
+          threshold: options.threshold,
+        },
+      );
+
+      observer.observe(node);
+      return () => observer.disconnect();
+    }, [Component, shouldLoad]);
+
+    useEffect(() => {
+      if (Component || !shouldLoad) return;
+      let cancelled = false;
+      void load().then(next => {
+        if (!cancelled) setComponent(() => next);
+      });
+      return () => {
+        cancelled = true;
+      };
+    }, [Component, shouldLoad]);
+
+    if (Component) return h(Component, props);
+    const Loading = options.loading;
+    if (options.load === 'visible') {
+      return h('div', { ref: visibleRef }, Loading ? h(Loading, props) : null);
+    }
+    return Loading ? h(Loading, props) : null;
+  }
+
+  (DynamicComponent as typeof DynamicComponent & {
+    [dynamicReferenceSymbol]: DynamicReference<Props>;
+  })[dynamicReferenceSymbol] = { load, target };
+
+  return DynamicComponent;
+}

package/src/api/link.tsx

@@ -0,0 +1,119 @@
+import { h, type ComponentChildren, type JSX } from 'preact';
+import { useEffect, useRef } from 'preact/hooks';
+import type {
+  AnchorHTMLAttributes,
+  MouseEvent,
+  ReactNode,
+} from 'react';
+import { routeHref, type SearchInput } from '../routing/href';
+import type { PrefetchMode, RouteParams, RoutePath } from '../types';
+
+export interface NavigateEvent {
+  preventDefault(): void;
+}
+
+type LinkMouseEvent = MouseEvent<HTMLAnchorElement>;
+
+type BaseLinkProps = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href' | 'onClick'> & {
+  prefetch?: PrefetchMode;
+  replace?: boolean;
+  scroll?: boolean;
+  search?: SearchInput;
+  hash?: string;
+  onClick?: (event: LinkMouseEvent) => void;
+  onNavigate?: (event: NavigateEvent) => void;
+  onPrefetchStart?: () => void;
+  onPrefetchFinish?: () => void;
+  children?: ReactNode;
+};
+
+type ParamsProp<Route extends RoutePath> = RouteParams<Route> extends Record<string, never>
+  ? { params?: never }
+  : { params: RouteParams<Route> };
+
+export type LinkProps<Route extends RoutePath = RoutePath> = BaseLinkProps &
+  ParamsProp<Route> & {
+    href: Route;
+  };
+
+export function Link<Route extends RoutePath>({
+  href,
+  params,
+  prefetch = 'intent',
+  replace,
+  scroll,
+  search,
+  hash,
+  onClick,
+  onNavigate,
+  onPrefetchStart,
+  onPrefetchFinish,
+  children,
+  ...anchorProps
+}: LinkProps<Route>): ReactNode {
+  const resolvedHref = routeHref(href, { params: params ?? {}, search, hash });
+  const anchorRef = usePrefetchLifecycle(onPrefetchStart, onPrefetchFinish);
+  return h(
+    'a',
+    {
+      ...anchorProps,
+      ref: anchorRef,
+      href: resolvedHref,
+      'data-pnext-link': true,
+      'data-prefetch': prefetch === false ? 'false' : prefetch,
+      'data-pnext-replace': replace ? 'true' : undefined,
+      'data-pnext-scroll': scroll === false ? 'false' : undefined,
+      onClick: event => {
+        const clickEvent = event as unknown as LinkMouseEvent;
+        onClick?.(clickEvent);
+        if (clickEvent.defaultPrevented || !onNavigate || !isPlainLeftClick(clickEvent)) return;
+        const navEvent = navigationEvent();
+        onNavigate(navEvent);
+        if (navEvent.defaultPrevented) clickEvent.preventDefault();
+      },
+    } as JSX.HTMLAttributes<HTMLAnchorElement>,
+    children as ComponentChildren,
+  ) as unknown as ReactNode;
+}
+
+// The prefetch runtime dispatches lifecycle events on the anchor that
+// triggered a prefetch, for every mode (intent, visible, load).
+export function usePrefetchLifecycle(onStart?: () => void, onFinish?: () => void) {
+  const anchorRef = useRef<HTMLAnchorElement | null>(null);
+
+  useEffect(() => {
+    const node = anchorRef.current;
+    if (!node || (!onStart && !onFinish)) return;
+    const handleStart = () => onStart?.();
+    const handleFinish = () => onFinish?.();
+    node.addEventListener('pnext:prefetchstart', handleStart);
+    node.addEventListener('pnext:prefetchfinish', handleFinish);
+    return () => {
+      node.removeEventListener('pnext:prefetchstart', handleStart);
+      node.removeEventListener('pnext:prefetchfinish', handleFinish);
+    };
+  }, [onStart, onFinish]);
+
+  return anchorRef;
+}
+
+function navigationEvent() {
+  return {
+    defaultPrevented: false,
+    preventDefault() {
+      this.defaultPrevented = true;
+    },
+  };
+}
+
+function isPlainLeftClick(event: LinkMouseEvent) {
+  return (
+    event.button === 0 &&
+    !event.altKey &&
+    !event.ctrlKey &&
+    !event.metaKey &&
+    !event.shiftKey &&
+    !event.currentTarget.target &&
+    !event.currentTarget.download
+  );
+}

package/src/api/navigation.ts

@@ -0,0 +1,198 @@
+import { routeHref, type SearchInput } from '../routing/href';
+import type { RouteParams, RoutePath } from '../types';
+
+export type { SearchInput, SearchValue } from '../routing/href';
+
+const notFoundDigest = 'PNEXT_NOT_FOUND';
+const redirectDigest = 'PNEXT_REDIRECT';
+const forbiddenDigest = 'PNEXT_FORBIDDEN';
+const unauthorizedDigest = 'PNEXT_UNAUTHORIZED';
+const nextNotFoundDigest = 'NEXT_HTTP_ERROR_FALLBACK;404';
+const nextForbiddenDigest = 'NEXT_HTTP_ERROR_FALLBACK;403';
+const nextUnauthorizedDigest = 'NEXT_HTTP_ERROR_FALLBACK;401';
+
+export type RedirectStatus = 303 | 307 | 308;
+
+class ReadonlyURLSearchParamsError extends Error {
+  constructor() {
+    super(
+      'Method unavailable on `ReadonlyURLSearchParams`. Read more: https://nextjs.org/docs/app/api-reference/functions/use-search-params#updating-searchparams',
+    );
+  }
+}
+
+/**
+ * A read-only `URLSearchParams`: mutation methods throw. Returned by
+ * `useSearchParams()` so search params rendered from the URL cannot be
+ * mutated in place (matches Next's `ReadonlyURLSearchParams`).
+ */
+export class ReadonlyURLSearchParams extends URLSearchParams {
+  /** @deprecated Method unavailable on `ReadonlyURLSearchParams`. */
+  append(): never {
+    throw new ReadonlyURLSearchParamsError();
+  }
+  /** @deprecated Method unavailable on `ReadonlyURLSearchParams`. */
+  delete(): never {
+    throw new ReadonlyURLSearchParamsError();
+  }
+  /** @deprecated Method unavailable on `ReadonlyURLSearchParams`. */
+  set(): never {
+    throw new ReadonlyURLSearchParamsError();
+  }
+  /** @deprecated Method unavailable on `ReadonlyURLSearchParams`. */
+  sort(): never {
+    throw new ReadonlyURLSearchParamsError();
+  }
+}
+
+type ParamsProp<Route extends RoutePath> = RouteParams<Route> extends Record<string, never>
+  ? { params?: never }
+  : { params: RouteParams<Route> };
+
+export type HrefOptions<Route extends RoutePath> = ParamsProp<Route> & {
+  search?: SearchInput;
+  hash?: string;
+};
+
+export type RedirectOptions<Route extends RoutePath> = HrefOptions<Route> & {
+  status?: RedirectStatus;
+};
+
+export function href<Route extends RoutePath>(
+  route: Route,
+  ...[options]: RouteParams<Route> extends Record<string, never>
+    ? [options?: HrefOptions<Route>]
+    : [options: HrefOptions<Route>]
+) {
+  return routeHref(route, options);
+}
+
+export class PNextNotFoundError extends Error {
+  digest = notFoundDigest;
+
+  constructor() {
+    super('not found');
+  }
+}
+
+export function notFound(): never {
+  throw new PNextNotFoundError();
+}
+
+export class PNextForbiddenError extends Error {
+  digest = forbiddenDigest;
+
+  constructor() {
+    super('forbidden');
+  }
+}
+
+/**
+ * COMPAT (Next authInterrupts): stop rendering and serve the nearest
+ * `forbidden.{tsx,...}` boundary with a 403. Only active when compat.next is on.
+ */
+export function forbidden(): never {
+  throw new PNextForbiddenError();
+}
+
+export class PNextUnauthorizedError extends Error {
+  digest = unauthorizedDigest;
+
+  constructor() {
+    super('unauthorized');
+  }
+}
+
+/**
+ * COMPAT (Next authInterrupts): stop rendering and serve the nearest
+ * `unauthorized.{tsx,...}` boundary with a 401. Only active when compat.next is on.
+ */
+export function unauthorized(): never {
+  throw new PNextUnauthorizedError();
+}
+
+export class PNextRedirectError extends Error {
+  digest = redirectDigest;
+
+  constructor(
+    public location: string,
+    public status: RedirectStatus = 307,
+  ) {
+    super(`redirect to ${location}`);
+  }
+}
+
+export function redirect<Route extends RoutePath>(
+  route: Route,
+  options: RedirectOptions<Route>,
+): never;
+export function redirect(location: string, status?: RedirectStatus): never;
+export function redirect<Route extends RoutePath>(
+  location: Route | string,
+  optionsOrStatus: RedirectOptions<Route> | RedirectStatus = 307,
+): never {
+  if (typeof optionsOrStatus === 'number') {
+    if (redirectInBrowser(location, 'replace')) return undefined as never;
+    throw new PNextRedirectError(location, optionsOrStatus);
+  }
+  const href = routeHref(location, optionsOrStatus);
+  if (redirectInBrowser(href, 'replace')) return undefined as never;
+  throw new PNextRedirectError(href, optionsOrStatus.status ?? 307);
+}
+
+export function permanentRedirect<Route extends RoutePath>(
+  route: Route,
+  options: HrefOptions<Route>,
+): never;
+export function permanentRedirect(location: string): never;
+export function permanentRedirect<Route extends RoutePath>(
+  location: Route | string,
+  options?: HrefOptions<Route>,
+): never {
+  const href = options ? routeHref(location, options) : location;
+  if (redirectInBrowser(href, 'replace')) return undefined as never;
+  throw new PNextRedirectError(href, 308);
+}
+
+export function isNotFoundError(error: unknown) {
+  return (
+    error instanceof PNextNotFoundError ||
+    errorDigest(error) === notFoundDigest ||
+    errorDigest(error) === nextNotFoundDigest
+  );
+}
+
+export function isRedirectError(error: unknown): error is PNextRedirectError {
+  return error instanceof PNextRedirectError || errorDigest(error) === redirectDigest;
+}
+
+export function isForbiddenError(error: unknown): error is PNextForbiddenError {
+  return (
+    error instanceof PNextForbiddenError ||
+    errorDigest(error) === forbiddenDigest ||
+    errorDigest(error) === nextForbiddenDigest
+  );
+}
+
+export function isUnauthorizedError(error: unknown): error is PNextUnauthorizedError {
+  return (
+    error instanceof PNextUnauthorizedError ||
+    errorDigest(error) === unauthorizedDigest ||
+    errorDigest(error) === nextUnauthorizedDigest
+  );
+}
+
+function errorDigest(error: unknown) {
+  return typeof error === 'object' && error !== null && 'digest' in error
+    ? (error as { digest?: unknown }).digest
+    : undefined;
+}
+
+function redirectInBrowser(location: string, mode: 'push' | 'replace') {
+  if (!process.browser && typeof window === 'undefined') return false;
+
+  const href = new URL(location, window.location.href).href;
+  if (mode === 'push') window.location.assign(href);
+  else window.location.replace(href);
+  return true;
+}

package/src/api/router/events.ts

@@ -0,0 +1,53 @@
+// Router event seams: the location-change, navigation-start and navigation-commit listener sets
+// compat hooks subscribe to, plus the post-navigation scroll action. All share one tier - an entry
+// that reads router state pulls this in at first paint, one that only has a <Link> gets it with the
+// runtime chunk - and none may sit in ./hub, which is a chunk shared with the runtime.
+import { locationKey, routerState } from './hub';
+import type { NavigationScrollAction, NavigationScrollOptions } from './types';
+
+export let navigationScrollAction: NavigationScrollAction | undefined;
+
+export function setNavigationScrollAction(action: NavigationScrollAction | undefined) {
+  navigationScrollAction = action;
+}
+
+export function scheduleNavigationScroll(url: URL, options: NavigationScrollOptions = {}) {
+  navigationScrollAction?.(url, options);
+}
+
+export function locationListeners() {
+  window.__PNEXT_LOCATION_LISTENERS__ ??= new Set();
+  return window.__PNEXT_LOCATION_LISTENERS__;
+}
+
+export function emitLocationChange() {
+  routerState.observedLocationKey = locationKey();
+  for (const listener of [...locationListeners()]) listener();
+}
+
+// Fires at the start of every soft navigation (link click, router.push,
+// refresh). Compat's link-status uses it to end a link's pending state when a
+// different navigation supersedes it.
+// Annotated pure so an entry that subscribes to nothing (a link-only page)
+// shakes the whole seam out of its first-paint closure.
+export const navigationStartListeners = /* @__PURE__ */ new Set<() => void>();
+
+export function onNavigationStart(listener: () => void) {
+  navigationStartListeners.add(listener);
+  return () => navigationStartListeners.delete(listener);
+}
+
+export function emitNavigationStart() {
+  for (const listener of [...navigationStartListeners]) listener();
+}
+
+export const navigationCommitListeners = /* @__PURE__ */ new Set<() => void>();
+
+export function onNavigationCommit(listener: () => void) {
+  navigationCommitListeners.add(listener);
+  return () => navigationCommitListeners.delete(listener);
+}
+
+export function emitNavigationCommit() {
+  for (const listener of [...navigationCommitListeners]) listener();
+}

package/src/api/router/history.ts

@@ -0,0 +1,70 @@
+// History entry identity: the ids pnext stamps on `history.state`, and the seed
+// that puts them there for the hard-loaded document.
+//
+// Its own module because its tier is decided by the app, not by the router: a
+// page whose client graph reads router state (`api/client-navigation`) seeds at
+// first paint and pulls this in; a page that only has a <Link> never reads an id
+// before the navigation runtime lands, so this rides the idle chunk with it.
+import { routerState } from './hub';
+
+export const HISTORY_BFCACHE_ID_KEY = '__pnextBfcacheId';
+
+export function historyState(): Record<string, unknown> {
+  const state = history.state as Record<string, unknown> | null;
+  return state && typeof state === 'object' ? state : {};
+}
+
+export function historyBfcacheId(
+  state: Record<string, unknown> = historyState(),
+): string | undefined {
+  const value = state[HISTORY_BFCACHE_ID_KEY];
+  return typeof value === 'string' ? value : undefined;
+}
+
+function newHistoryId(prefix: string) {
+  return `${prefix}${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+export function newBfcacheId() {
+  return newHistoryId('b_');
+}
+
+export function newEntryId() {
+  return newHistoryId('e');
+}
+
+/**
+ * Stamp the hard-loaded entry's ids onto `history.state` and record which entry is on screen. Called
+ * at module scope by `api/client-navigation` - the module that reads them - rather than from the
+ * hub's install, so a page whose client graph never touches router state does not pay for them:
+ *
+ *  - `useRouter().bfcacheId` keys client subtrees, so the id must be stable from the first client
+ *    render; waiting for the runtime's load-event snapshot would flip it from '' to a real value on
+ *    the first navigation and remount every keyed subtree.
+ *  - an entry with no id is indistinguishable from an app-created (shallow) one, and `patchHistory`
+ *    carries the ids forward onto an app pushState.
+ *
+ * The runtime seeds the same fields when it installs, so a page without this call still gets ids
+ * before it can navigate away.
+ */
+export function seedHistoryEntry() {
+  if (!process.browser && typeof window === 'undefined') return;
+  const state = historyState();
+  const entryId = state.__pnextEntry;
+  const hasEntryId = typeof entryId === 'string';
+  routerState.renderedEntryId = hasEntryId ? entryId : newEntryId();
+  if (historyBfcacheId(state) && hasEntryId) return;
+  try {
+    history.replaceState(
+      {
+        ...state,
+        __pnextEntry: routerState.renderedEntryId,
+        [HISTORY_BFCACHE_ID_KEY]: historyBfcacheId(state) ?? newBfcacheId(),
+      },
+      '',
+      location.href,
+    );
+  } catch {
+    // Without a stable id, bfcache-keyed subtrees fall back to remounting.
+  }
+}