@antelopejs/dms-frontend 0.9.1 → 0.9.3

package/templates/vue/frontend-runtime/paged-data.ts

@@ -0,0 +1,191 @@
+import {
+  computed,
+  getCurrentScope,
+  type MaybeRefOrGetter,
+  onScopeDispose,
+  type Ref,
+  readonly,
+  ref,
+  watch,
+} from "vue";
+import {
+  type DmsAsyncData,
+  type DmsAsyncDataContext,
+  type DmsAsyncDataKey,
+  type UseAsyncDataOptions,
+} from "./types";
+import { useDmsAsyncData } from "./async-data";
+
+/** What a paged read keeps under its key: the pages loaded, in order. */
+export interface DmsPagedDataValue<TPage, TCursor> {
+  pages: TPage[];
+  /** The cursor of the page after the last one; `null` once there is none. */
+  next: TCursor | null;
+}
+/** What a paged read's handler receives. */
+export interface DmsPagedDataContext<TCursor> extends DmsAsyncDataContext {
+  /** The page to read: `initialCursor` for the first one. */
+  cursor: TCursor | undefined;
+  /** Its position, from `0`. */
+  index: number;
+}
+export type DmsPagedDataHandler<TPage, TCursor> = (
+  context: DmsPagedDataContext<TCursor>,
+) => Promise<TPage>;
+export interface UseDmsPagedDataOptions<TPage, TCursor> extends Omit<
+  UseAsyncDataOptions<DmsPagedDataValue<TPage, TCursor>>,
+  "default" | "transform" | "pick"
+> {
+  /** The cursor of the page after `page`, or `null` (or `undefined`) for none. */
+  nextCursor(page: TPage, pages: TPage[]): TCursor | null | undefined;
+  /** The first page's cursor; none by default. */
+  initialCursor?: TCursor;
+}
+export interface DmsPagedData<TPage, TCursor> extends DmsAsyncData<
+  DmsPagedDataValue<TPage, TCursor>
+> {
+  /** The pages loaded so far, in order; none before the first answer. */
+  pages: Readonly<Ref<TPage[]>>;
+  /** Whether `loadMore()` has a page to read. */
+  hasMore: Readonly<Ref<boolean>>;
+  /** `true` while `loadMore()` reads its page. */
+  loadingMore: Readonly<Ref<boolean>>;
+  /**
+   * Reads the next page and appends it under the same key. It waits for a
+   * read in flight first, does nothing once there is no next page, and puts
+   * a failure in `error`, keeping the pages loaded.
+   */
+  loadMore(): Promise<void>;
+}
+export type DmsPagedDataResult<TPage, TCursor> = DmsPagedData<TPage, TCursor> &
+  Promise<DmsPagedData<TPage, TCursor>>;
+
+type PagedValue<TPage, TCursor> = DmsPagedDataValue<TPage, TCursor>;
+
+/** Reads `count` pages from the first, as long as each has a next one. */
+async function readPages<TPage, TCursor>(
+  handler: DmsPagedDataHandler<TPage, TCursor>,
+  options: UseDmsPagedDataOptions<TPage, TCursor>,
+  count: number,
+  signal: AbortSignal,
+): Promise<PagedValue<TPage, TCursor>> {
+  const pages: TPage[] = [];
+  let cursor: TCursor | undefined = options.initialCursor;
+  for (let index = 0; index < count; index++) {
+    const page = await handler({ cursor, index, signal });
+    pages.push(page);
+    const next = options.nextCursor(page, pages);
+    if (next == null) return { pages, next: null };
+    cursor = next;
+  }
+  return { pages, next: cursor ?? null };
+}
+
+/** Resolves once `result` has no run in flight. */
+function untilSettled<T>(result: DmsAsyncData<T>): Promise<void> {
+  if (!result.pending.value) return Promise.resolve();
+  return new Promise((resolve) => {
+    const stop = watch(result.pending, (pending) => {
+      if (pending) return;
+      stop();
+      resolve();
+    });
+  });
+}
+
+/**
+ * A list read page by page under one key: "load more", an infinite list.
+ * The first page loads as `useDmsAsyncData` loads its data (a server render
+ * waits for it and transfers it), and `loadMore()` appends the next one to
+ * the same key, so the pages a component loaded show at once on a return to
+ * it. A revalidation (a mount, `refresh()`, `refreshDmsPageData()`, the
+ * polling) reads every page loaded so far again, from the first, and
+ * replaces them once all are in. Put what filters the list in the key: a new
+ * key starts again from its first page.
+ *
+ * @param key The key, or a ref or getter for it
+ * @param handler Reads one page, from the cursor it receives
+ * @param options `nextCursor`, `initialCursor` and the async data options
+ */
+export function useDmsPagedData<TPage, TCursor = unknown>(
+  key: MaybeRefOrGetter<DmsAsyncDataKey>,
+  handler: DmsPagedDataHandler<TPage, TCursor>,
+  options: UseDmsPagedDataOptions<TPage, TCursor>,
+): DmsPagedDataResult<TPage, TCursor> {
+  const {
+    nextCursor: _next,
+    initialCursor: _initial,
+    ...asyncOptions
+  } = options;
+  let shown: DmsAsyncData<PagedValue<TPage, TCursor>> | undefined;
+  const loadedCount = () =>
+    shown && !shown.placeholder.value
+      ? Math.max(1, shown.data.value?.pages.length ?? 0)
+      : 1;
+  const call = useDmsAsyncData<PagedValue<TPage, TCursor>>(
+    key,
+    ({ signal }) => readPages(handler, options, loadedCount(), signal),
+    asyncOptions,
+  );
+  shown = call;
+  const result: DmsPagedData<TPage, TCursor> = Object.assign(
+    {},
+    call as DmsAsyncData<PagedValue<TPage, TCursor>>,
+    pagedControls(call, handler, options),
+  );
+  return Object.assign(
+    call.then(() => result),
+    result,
+  );
+}
+
+function pagedControls<TPage, TCursor>(
+  call: DmsAsyncData<PagedValue<TPage, TCursor>>,
+  handler: DmsPagedDataHandler<TPage, TCursor>,
+  options: UseDmsPagedDataOptions<TPage, TCursor>,
+) {
+  const loadingMore = ref(false);
+  let controller: AbortController | undefined;
+  const abort = () => {
+    controller?.abort();
+    controller = undefined;
+    loadingMore.value = false;
+  };
+  watch(call.key, abort);
+  if (getCurrentScope()) onScopeDispose(abort);
+  const hasMore = computed(
+    () => !call.placeholder.value && (call.data.value?.next ?? null) !== null,
+  );
+  const loadMore = async (): Promise<void> => {
+    if (call.pending.value) await untilSettled(call);
+    const before = call.data.value;
+    if (!before) return call.execute();
+    if (before.next === null || controller) return;
+    const current = new AbortController();
+    controller = current;
+    loadingMore.value = true;
+    try {
+      const page = await handler({
+        cursor: before.next,
+        index: before.pages.length,
+        signal: current.signal,
+      });
+      if (controller !== current || call.data.value !== before) return;
+      const pages = [...before.pages, page];
+      call.data.value = {
+        pages,
+        next: options.nextCursor(page, pages) ?? null,
+      };
+    } catch (reason) {
+      if (controller === current) call.error.value = reason;
+    } finally {
+      if (controller === current) abort();
+    }
+  };
+  return {
+    pages: computed(() => call.data.value?.pages ?? []),
+    hasMore,
+    loadingMore: readonly(loadingMore),
+    loadMore,
+  };
+}

package/templates/vue/frontend-runtime/payload.ts

@@ -0,0 +1,172 @@
+import {
+  getCurrentInstance,
+  onServerPrefetch,
+  type Ref,
+  ref,
+  toRaw,
+} from "vue";
+import {
+  type DmsAppConfig,
+  type DmsErrorData,
+  type DmsPayload,
+  type DmsRuntimeConfig,
+  type DmsStateOptions,
+} from "./types";
+import {
+  type DmsFrontendRuntime,
+  type DmsMiddleware,
+} from "./module-registration";
+import { serializeDmsAsyncData } from "./data-access";
+import { appConfig, runtimeConfig, useDmsRuntime } from "./state";
+import { runMiddleware, visit } from "./route";
+import { failPage } from "./ui";
+
+const HTTP_ERROR_STATUS = { min: 400, max: 599 };
+const SERVER_FAILURE_STATUS = 500;
+const FETCH_ERROR_NAME = "FetchError";
+
+/** The fields of a failure, under the names `createDmsError` and ofetch use. */
+interface DmsFailure extends DmsErrorData {
+  name?: string;
+  status?: number;
+  statusText?: string;
+}
+
+/**
+ * What of a failure a page may carry, by the rule the error page follows: an
+ * HTTP failure keeps its status, status text and message, and its body if it
+ * is a 4xx, anything else
+ * is a server failure whose cause only reaches the server log. A fetch error
+ * names the URL it requested, which on a server is the backend's own address:
+ * its status text stands for it.
+ */
+function transferredError(key: string, reason: unknown): DmsErrorData {
+  const failure = (reason ?? {}) as DmsFailure;
+  const statusCode = failure.statusCode ?? failure.status;
+  if (
+    statusCode === undefined ||
+    !Number.isInteger(statusCode) ||
+    statusCode < HTTP_ERROR_STATUS.min ||
+    statusCode > HTTP_ERROR_STATUS.max
+  ) {
+    console.error(`DMS async data "${key}" failed`, reason);
+    return { statusCode: SERVER_FAILURE_STATUS };
+  }
+  const statusMessage = failure.statusMessage ?? failure.statusText;
+  const transferred: DmsErrorData = {
+    statusCode,
+    statusMessage,
+    message:
+      failure.name === FETCH_ERROR_NAME ? statusMessage : failure.message,
+  };
+  // A 5xx body is the backend's own account of its failure, a stack or a
+  // query at times: only a 4xx body, written for the client, is transferred.
+  if (statusCode < SERVER_FAILURE_STATUS) transferred.data = failure.data;
+  return transferred;
+}
+
+/**
+ * What a page's error page shows of an expected failure (a 4xx or 5xx): its
+ * status code, status text and message. A fetch error's message names the URL
+ * it requested, on a server the backend's own address: its status text
+ * stands for it.
+ */
+export function pageErrorData(failure: Error & DmsErrorData): DmsErrorData {
+  return {
+    statusCode: failure.statusCode,
+    message:
+      failure.name === FETCH_ERROR_NAME
+        ? failure.statusMessage
+        : failure.message,
+    statusMessage: failure.statusMessage,
+  };
+}
+
+/**
+ * Everything a server render hands the browser: the data and the failures of
+ * its keys, and the state keys opted into. Read as the HTML is complete.
+ */
+export function serializeDmsPayload(runtime: DmsFrontendRuntime): DmsPayload {
+  const errors = [...runtime.asyncData.entries()]
+    .filter(([, entry]) => entry.status.value === "error")
+    .map(([key, entry]): [string, DmsErrorData] => [
+      key,
+      transferredError(key, entry.error.value),
+    ]);
+  const state = [...runtime.transferredState]
+    .map((key): [string, unknown] => [
+      key,
+      toRaw(runtime.sharedState.get(key)?.value),
+    ])
+    .filter(([, value]) => value !== undefined);
+  return {
+    data: serializeDmsAsyncData(runtime),
+    errors: Object.fromEntries(errors),
+    state: Object.fromEntries(state),
+  };
+}
+
+/** Starts a browser runtime from what the server rendered. */
+export function restoreDmsPayload(
+  runtime: DmsFrontendRuntime,
+  payload: Partial<DmsPayload>,
+): void {
+  runtime.hydrating = true;
+  for (const [key, value] of Object.entries(payload.data ?? {}))
+    runtime.hydratedAsyncData.set(key, value);
+  for (const [key, failure] of Object.entries(payload.errors ?? {}))
+    runtime.hydratedAsyncErrors.set(key, failure);
+  for (const [key, value] of Object.entries(payload.state ?? {}))
+    runtime.sharedState.set(key, ref(value));
+}
+
+export function useDmsState<T>(
+  key: string,
+  init?: () => T,
+  options: DmsStateOptions = {},
+): Ref<T> {
+  const runtime = useDmsRuntime();
+  if (options.transfer) runtime.transferredState.add(key);
+  if (!runtime.sharedState.has(key))
+    runtime.sharedState.set(key, ref(init?.()));
+  return runtime.sharedState.get(key) as Ref<T>;
+}
+export function useDmsRuntimeConfig(): DmsRuntimeConfig {
+  return runtimeConfig.value;
+}
+export function useDmsAppConfig(): DmsAppConfig {
+  return appConfig.value as DmsAppConfig;
+}
+export function defineDmsAppConfig<T extends Record<string, unknown>>(
+  config: T,
+): T {
+  return config;
+}
+export function defineDmsMiddleware(handler: DmsMiddleware): DmsMiddleware {
+  return handler;
+}
+export function defineDmsPageMeta(meta: Record<string, unknown>): void {
+  const runtime = useDmsRuntime();
+  Object.assign(runtime.route.meta, meta);
+  // A middleware that throws fails the page, as in Nuxt: the error page
+  // shows in its place with the error's status code, which a server render
+  // answers with. A redirect another navigation decided still wins.
+  const navigation = runMiddleware(runtime, runtime.route)
+    .then(async (result) => {
+      if (result !== undefined && result !== false)
+        await visit(runtime, result);
+    })
+    .catch((reason) => failPage(runtime, reason));
+  runtime.pendingNavigation = runtime.pendingNavigation
+    ? Promise.all([runtime.pendingNavigation, navigation]).then(() => undefined)
+    : navigation;
+  void runtime.pendingNavigation;
+  // A server renders the page's subtree once its middleware is done, so the
+  // state a middleware sets is the one the HTML shows and the payload carries.
+  // A failure shows the error page in its place (`failPage`). Registered
+  // in the browser too, where only a server calls it: both sides must agree
+  // on the async boundaries `useId()` counts.
+  if (getCurrentInstance())
+    onServerPrefetch(() => navigation.then(ignoreSettlement, ignoreSettlement));
+}
+function ignoreSettlement(): void {}

package/templates/vue/frontend-runtime/route.ts

@@ -0,0 +1,328 @@
+import { router as inertiaRouter, usePage } from "@inertiajs/vue3";
+import { computed, watch } from "vue";
+import {
+  type DmsFrontendRuntime,
+  type DmsInertiaPage,
+  type DmsMiddleware,
+  type DmsMiddlewareResult,
+} from "./module-registration";
+import {
+  type DmsNavigationOptions,
+  type DmsRoute,
+  type DmsRouter,
+  type RouteLocationRaw,
+} from "./types";
+import { registry, runtimeContexts, useDmsRuntime } from "./state";
+
+function extractRouteParams(
+  pattern: string | undefined,
+  path: string,
+): Record<string, string> {
+  if (!pattern) return {};
+  const patternSegments = pattern.split("/").filter(Boolean);
+  const pathSegments = path.split("/").filter(Boolean);
+  if (patternSegments.length !== pathSegments.length) return {};
+  const params: Record<string, string> = {};
+  const matches = patternSegments.every((segment, index) => {
+    if (!segment.startsWith(":")) return segment === pathSegments[index];
+    params[segment.slice(1)] = decodeURIComponent(pathSegments[index] ?? "");
+    return true;
+  });
+  return matches ? params : {};
+}
+
+function parseRoute(runtime: DmsFrontendRuntime, url: string): DmsRoute {
+  const parsed = new URL(
+    url,
+    typeof window === "undefined"
+      ? "http://frontend.local"
+      : window.location.origin,
+  );
+  return {
+    name: parsed.pathname,
+    fullPath: `${parsed.pathname}${parsed.search}${parsed.hash}`,
+    path: parsed.pathname,
+    query: Object.fromEntries(parsed.searchParams),
+    params: extractRouteParams(runtime.currentRoutePattern, parsed.pathname),
+    meta: {},
+    matched: [{}],
+  };
+}
+
+function hasSameEntries(
+  left: Record<string, string>,
+  right: Record<string, string>,
+): boolean {
+  const keys = Object.keys(left);
+  return (
+    keys.length === Object.keys(right).length &&
+    keys.every((key) => right[key] === left[key])
+  );
+}
+
+// Every parse builds a new query, params and matched: assigning them as they
+// come would re-run each watcher of the route on every call of useDmsRoute,
+// though the URL did not change. They are only replaced when their content did.
+export function updateRoute(runtime: DmsFrontendRuntime, url: string): void {
+  // The meta is the page's, not the URL's: a page declares it, then reads its
+  // route, and the middleware the meta selected must still find it.
+  const {
+    meta: _pageMeta,
+    query,
+    params,
+    matched,
+    ...location
+  } = parseRoute(runtime, url);
+  const route = runtime.route;
+  if (!hasSameEntries(query, route.query)) route.query = query;
+  if (!hasSameEntries(params, route.params)) route.params = params;
+  if (matched.length !== route.matched.length) route.matched = matched;
+  Object.assign(route, location);
+}
+
+const URL_BASE = "http://frontend.local";
+
+// The URL the browser shows: it may be ahead of the route, which follows
+// Inertia's page, when a component wrote it in place (history.replaceState).
+function currentUrl(runtime: DmsFrontendRuntime): string {
+  if (runtime.isServer || typeof window === "undefined")
+    return new URL(runtime.route.fullPath, URL_BASE).href;
+  return window.location.href;
+}
+
+// One spelling per URL: `a b`, `a+b` and `a%20b` are the same query, as are
+// `:` and `%3A`. The origin is kept, so a URL of another site never matches
+// the current one, whatever its path.
+function normalizeUrl(url: string, base: string): string {
+  const parsed = new URL(url, base);
+  const search = parsed.searchParams.toString();
+  return `${parsed.origin}${parsed.pathname}${search ? `?${search}` : ""}${parsed.hash}`;
+}
+
+export function locationToUrl(
+  runtime: DmsFrontendRuntime,
+  to: RouteLocationRaw,
+): string {
+  if (typeof to === "string") return to;
+  const origin =
+    typeof window === "undefined"
+      ? "http://frontend.local"
+      : window.location.origin;
+  const parsed = new URL(to.path ?? runtime.route.path, origin);
+  if (to.query !== undefined) {
+    parsed.search = Object.entries(to.query)
+      .flatMap(([key, value]) =>
+        (Array.isArray(value) ? value : [value])
+          .filter((item) => item !== undefined)
+          .map((item) =>
+            item === null
+              ? encodeURIComponent(key)
+              : `${encodeURIComponent(key)}=${encodeURIComponent(String(item))}`,
+          ),
+      )
+      .join("&");
+  }
+  parsed.hash = to.hash ?? "";
+  return `${parsed.pathname}${parsed.search}${parsed.hash}`;
+}
+
+export async function runMiddleware(
+  runtime: DmsFrontendRuntime,
+  to: DmsRoute,
+): Promise<DmsMiddlewareResult> {
+  const declared = Array.isArray(to.meta.middleware) ? to.meta.middleware : [];
+  const metadataNames = Object.keys(to.meta).filter((name) => to.meta[name]);
+  const declaredHandlers = [...declared, ...metadataNames]
+    .map((name) => registry.namedMiddleware.get(String(name)))
+    .filter((handler): handler is DmsMiddleware => !!handler);
+  const run = (handler: DmsMiddleware) => {
+    const runWithContext = runtimeContexts.get(runtime);
+    return runWithContext
+      ? runWithContext(() => handler(to, runtime.route))
+      : handler(to, runtime.route);
+  };
+  for (const group of middlewareGroups([
+    ...registry.middleware,
+    ...declaredHandlers,
+  ])) {
+    // A group of parallel middlewares starts together; its results apply in
+    // order, as a sequence's would.
+    const results = await Promise.all(group.map(run));
+    const result = results.find((value) => value !== undefined);
+    if (result !== undefined) return result;
+  }
+}
+
+/** The middlewares in order, each run of parallel ones as one group. */
+function middlewareGroups(handlers: DmsMiddleware[]): DmsMiddleware[][] {
+  const groups: DmsMiddleware[][] = [];
+  for (const handler of handlers) {
+    const last = groups.at(-1);
+    const parallel = registry.parallelMiddleware.has(handler);
+    if (parallel && last && registry.parallelMiddleware.has(last[0]))
+      last.push(handler);
+    else groups.push([handler]);
+  }
+  return groups;
+}
+
+// What only a request to the server can honour: a client-side visit sends
+// none and has none of these events.
+const SERVER_VISIT_OPTIONS = [
+  "async",
+  "component",
+  "data",
+  "except",
+  "headers",
+  "method",
+  "onBefore",
+  "onCancel",
+  "onCancelToken",
+  "onProgress",
+  "onStart",
+  "only",
+  "preserveUrl",
+  "queryStringArrayFormat",
+] as const satisfies readonly (keyof DmsNavigationOptions)[];
+
+/**
+ * Whether a visit to another query or hash of the page on screen can stay in
+ * the browser. The page props depend on the path alone: the server would
+ * answer with the same page, the site layout included. An error page is left
+ * through the server, which renders the page in its place, and so is the
+ * same path on another site.
+ */
+function staysOnPage(
+  runtime: DmsFrontendRuntime,
+  url: string,
+  options: DmsNavigationOptions,
+): boolean {
+  return (
+    new URL(url, currentUrl(runtime)).origin ===
+      new URL(currentUrl(runtime)).origin &&
+    !runtime.pageKey?.startsWith("error:") &&
+    runtime.currentError.value === null &&
+    SERVER_VISIT_OPTIONS.every((name) => options[name] === undefined)
+  );
+}
+
+/**
+ * An Inertia client-side visit: the URL and the history entry change, the
+ * page keeps its props, and no request is made.
+ */
+function visitInBrowser(
+  url: string,
+  options: DmsNavigationOptions,
+): Promise<void> {
+  const clientVisit = options.replace
+    ? inertiaRouter.replace
+    : inertiaRouter.push;
+  return new Promise<void>((resolve) => {
+    clientVisit.call(inertiaRouter, {
+      url,
+      preserveScroll: options.preserveScroll ?? true,
+      preserveState: options.preserveState ?? true,
+      viewTransition: options.viewTransition,
+      onSuccess: options.onSuccess,
+      onError: options.onError,
+      onFinish: (visit) => {
+        (options.onFinish as ((visit: unknown) => void) | undefined)?.(visit);
+        resolve();
+      },
+    } as Parameters<typeof inertiaRouter.push>[0]);
+  });
+}
+
+export async function visit(
+  runtime: DmsFrontendRuntime,
+  to: RouteLocationRaw,
+  options: DmsNavigationOptions = {},
+): Promise<void> {
+  const url = locationToUrl(runtime, to);
+  const target = parseRoute(runtime, url);
+  const result = await runMiddleware(runtime, target);
+  if (result === false) return;
+  if (result !== undefined) return visit(runtime, result, options);
+  if (runtime.isServer) {
+    runtime.serverRedirect = url;
+    return;
+  }
+  // Like Vue Router, a navigation that only changes the query or hash keeps
+  // the page mounted: without preserveState, Inertia remounts the page
+  // component on every visit and its local state (open tabs, selection,
+  // inputs) is lost.
+  const samePath = target.path === runtime.route.path;
+  if (samePath && staysOnPage(runtime, url, options)) {
+    await visitInBrowser(url, options);
+    return;
+  }
+  await new Promise<void>((resolve) =>
+    inertiaRouter.visit(url, {
+      ...options,
+      preserveState: options.preserveState ?? samePath,
+      preserveScroll: options.preserveScroll ?? samePath,
+      onFinish: (completedVisit) => {
+        options.onFinish?.(completedVisit);
+        resolve();
+      },
+    }),
+  );
+}
+
+export function useDmsRoute(pattern?: string): DmsRoute {
+  const runtime = useDmsRuntime();
+  runtime.currentRoutePattern = pattern;
+  // A server render answers one request, whose URL the runtime was given with
+  // its page, and never changes it. Inertia's page is one ref for the whole
+  // process, written by each render as it starts: after an await it may hold
+  // another request's URL, and while the plugins set up, the previous one's.
+  if (runtime.isServer) {
+    updateRoute(runtime, runtime.route.fullPath);
+    return runtime.route;
+  }
+  const page = usePage();
+  // The browser's plugins set up before Inertia has a page: until then the
+  // runtime's route is the initial page's.
+  if (page.url !== undefined) updateRoute(runtime, page.url);
+  watch(
+    () => page.url,
+    (url) => updateRoute(runtime, url),
+  );
+  return runtime.route;
+}
+
+/**
+ * Inertia's page, as `usePage()` returns it, for the request being rendered.
+ * Inertia keeps a single page for the whole process, written by each server
+ * render as it starts: read after an await, it may be another request's. Nuxt
+ * UI's Link and route stub read this one instead (see `vite.config.ts`).
+ */
+export function useDmsInertiaPage(): DmsInertiaPage {
+  const runtime = useDmsRuntime();
+  if (runtime.isServer && runtime.inertiaPage) return runtime.inertiaPage;
+  return usePage();
+}
+
+export function useDmsRouter(): DmsRouter {
+  const runtime = useDmsRuntime();
+  const navigate = (to: RouteLocationRaw, options?: DmsNavigationOptions) => {
+    const current = currentUrl(runtime);
+    return normalizeUrl(locationToUrl(runtime, to), current) ===
+      normalizeUrl(current, current)
+      ? Promise.resolve()
+      : visit(runtime, to, options);
+  };
+  return {
+    currentRoute: computed(() => runtime.route),
+    push: navigate,
+    replace: (to, options) => navigate(to, { ...options, replace: true }),
+    back: () => window.history.back(),
+  };
+}
+
+export function navigateDms(
+  to: RouteLocationRaw,
+  options?: DmsNavigationOptions,
+): Promise<void> {
+  return visit(useDmsRuntime(), to, options);
+}