@antelopejs/dms-frontend 0.9.1 → 0.9.3

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

@@ -0,0 +1,361 @@
+import { type InertiaLinkProps } from "@inertiajs/vue3";
+import { type FetchOptions, ofetch } from "ofetch";
+import {
+  type App,
+  type ComputedRef,
+  type MaybeRefOrGetter,
+  type Ref,
+  watch,
+} from "vue";
+import type { Composer } from "vue-i18n";
+import { type $fetch } from "./fetch";
+
+export interface DmsPageRoute {
+  displayName?: string;
+  description?: string;
+  fullSlug?: string;
+  icon?: string;
+  layoutUrl?: string;
+}
+export interface DmsPagePayload {
+  route?: DmsPageRoute;
+  componentName?: string;
+  layoutUrl?: string;
+  layout?: DmsPageLayout;
+  [key: string]: unknown;
+}
+export interface DmsSharedPagePayload {
+  siteLayout?: unknown;
+  siteLayoutTree?: unknown;
+  quickActions?: unknown;
+  modules?: unknown;
+  isOwner?: boolean;
+}
+export interface DmsLayoutDefinition {
+  componentName?: string;
+  options?: Record<string, unknown>;
+}
+export interface DmsPageLayout {
+  componentName?: string;
+  layout?: DmsLayoutDefinition;
+  [key: string]: unknown;
+}
+export interface DmsPageProps {
+  path: string;
+  page: DmsPagePayload;
+  /**
+   * The site layout. An Inertia once prop: a visit carries it over from the
+   * previous page until it expires, unless the server sends a newer one.
+   */
+  shared?: DmsSharedPagePayload;
+  user?: DmsUser;
+  session?: DmsSession;
+  error?: DmsErrorData;
+}
+export interface PublicRuntimeConfig extends Record<string, unknown> {}
+export interface RuntimeConfig extends Record<string, unknown> {}
+export interface DmsAppConfig extends Record<string, unknown> {}
+export interface DmsUser extends Record<string, unknown> {}
+export interface DmsSession {
+  accountId: string;
+  activeTenantId?: string;
+  /**
+   * When the frontend server last wrote this session, in milliseconds since
+   * the epoch. A page restored from history or from the prefetch cache
+   * carries an older session than the one the app already holds, and does not
+   * replace it.
+   */
+  updatedAt?: number;
+}
+export interface DmsRuntimeConfig extends RuntimeConfig {
+  public: PublicRuntimeConfig;
+}
+export interface DmsModuleOptions {
+  public: Record<string, unknown>;
+}
+export type DmsLocaleLoader = (
+  locale: string,
+) => Promise<Record<string, unknown>>;
+export type DmsNavigationOptions = Pick<
+  InertiaLinkProps,
+  | "async"
+  | "component"
+  | "data"
+  | "except"
+  | "headers"
+  | "method"
+  | "onBefore"
+  | "onCancel"
+  | "onCancelToken"
+  | "onError"
+  | "onFinish"
+  | "onProgress"
+  | "onStart"
+  | "onSuccess"
+  | "only"
+  | "preserveScroll"
+  | "preserveState"
+  | "preserveUrl"
+  | "queryStringArrayFormat"
+  | "replace"
+  | "viewTransition"
+>;
+export interface RouteLocationObject {
+  path?: string;
+  query?: Record<string, unknown>;
+  hash?: string;
+}
+export type LocationQueryValue = string | null;
+export type LocationQuery = Record<
+  string,
+  LocationQueryValue | LocationQueryValue[]
+>;
+export type LocationQueryRaw = Record<
+  string,
+  | LocationQueryValue
+  | number
+  | undefined
+  | (LocationQueryValue | number | undefined)[]
+>;
+export type RouteLocationRaw = string | RouteLocationObject;
+export interface DmsRoute {
+  name?: string;
+  fullPath: string;
+  path: string;
+  query: Record<string, string>;
+  params: Record<string, string>;
+  meta: Record<string, unknown>;
+  matched: unknown[];
+}
+export interface DmsRouter {
+  currentRoute: Ref<DmsRoute>;
+  push(to: RouteLocationRaw, options?: DmsNavigationOptions): Promise<void>;
+  replace(to: RouteLocationRaw, options?: DmsNavigationOptions): Promise<void>;
+  back(): void;
+}
+export type DmsAsyncDataStatus = "idle" | "pending" | "success" | "error";
+/**
+ * What a new run does with the one still in flight: `cancel` aborts it and
+ * starts over, `defer` waits for it instead.
+ */
+export type DmsAsyncDataDedupe = "cancel" | "defer";
+export interface DmsAsyncDataRefreshOptions {
+  dedupe?: DmsAsyncDataDedupe;
+}
+export interface DmsAsyncData<T> {
+  data: Ref<T | null>;
+  /**
+   * The key the data is loaded under, a reactive key's current one; none for
+   * a call without a key.
+   */
+  key: Readonly<Ref<string | undefined>>;
+  /**
+   * `true` while `data` is still the previous key's, shown in place of the
+   * default until the current key's first answer (a reactive key only).
+   */
+  placeholder: Readonly<Ref<boolean>>;
+  /**
+   * The last run's failure. It stays while the next run is in flight, and
+   * goes back to `null` once a run answers.
+   */
+  error: Ref<unknown>;
+  pending: Ref<boolean>;
+  status: Ref<DmsAsyncDataStatus>;
+  execute(options?: DmsAsyncDataRefreshOptions): Promise<void>;
+  refresh(options?: DmsAsyncDataRefreshOptions): Promise<void>;
+  /** Aborts the run in flight and puts the data back to its default. */
+  clear(): void;
+}
+/** Usable at once, or awaited until its data is there. */
+export type DmsAsyncDataResult<T> = DmsAsyncData<T> & Promise<DmsAsyncData<T>>;
+export interface DmsAsyncDataContext {
+  /**
+   * Aborted once the result is no longer wanted: a newer run replaced it, it
+   * was cleared, or no component shows its key any more.
+   */
+  signal: AbortSignal;
+}
+export type DmsAsyncDataHandler<T> = (
+  context: DmsAsyncDataContext,
+) => Promise<T>;
+/** A key, or `null` (or `undefined`) while there is nothing to load. */
+export type DmsAsyncDataKey = string | null | undefined;
+/** What `useDmsData` gives of a key's data. */
+export interface DmsData<T> {
+  /**
+   * The data loaded under the key, shared with every caller showing it:
+   * `undefined` while the key has none of its own (no caller loaded it yet,
+   * or it shows the previous key's data meanwhile). Assigning it replaces the
+   * key's data; a key nobody loaded keeps none.
+   */
+  data: Ref<T | undefined>;
+}
+/** What `transform` knows of the run whose result it transforms. */
+export interface DmsAsyncDataTransformContext {
+  /** The key the data is loaded under; none for a call without a key. */
+  key: string | undefined;
+}
+/** What `useDmsFetch`'s `transform` knows of the request it answers. */
+export interface DmsFetchTransformContext extends DmsAsyncDataTransformContext {
+  /**
+   * The URL requested, as given (before the base URL and the query), even
+   * when a reactive URL changed since.
+   */
+  url: string;
+}
+/**
+ * The request options a ref or a getter may stand for: read again for each
+ * request, and part of the key the response is shared under.
+ */
+type DmsFetchRequestSources = "method" | "query" | "params" | "body";
+export interface UseAsyncDataOptions<T> {
+  default?: () => T;
+  /** `false` waits for `execute()` (a dialog, a drawer) before the first run. */
+  immediate?: boolean;
+  /**
+   * A client navigation does not wait for the data. A server render still
+   * does: its HTML shows the data, and the browser takes it over.
+   */
+  lazy?: boolean;
+  /** `false` leaves the data to the browser: the server renders the default. */
+  server?: boolean;
+  watch?: false | unknown[];
+  transform?: (
+    value: unknown,
+    context: DmsAsyncDataTransformContext,
+  ) => T | Promise<T>;
+  pick?: string[];
+  /**
+   * `true` tracks changes inside the value too. By default only the
+   * replacement of the whole value triggers, as in Nuxt 4.
+   */
+  deep?: boolean;
+  dedupe?: DmsAsyncDataDedupe;
+  /**
+   * `false` leaves the data out of `refreshDmsPageData()`, which reads again
+   * the data of the components on screen once the page changed (a save, a
+   * realtime event).
+   */
+  refreshOnPageRefresh?: boolean;
+  /**
+   * Reads again every this many milliseconds, in the browser, while the
+   * caller shows the data and the page is visible. A ref or a getter changes
+   * the interval as it changes; `0`, `null` or `undefined` stops the polling
+   * until it has a value again. A call outside a component (a plugin, a
+   * callback) polls for as long as the application runs.
+   */
+  refreshInterval?: MaybeRefOrGetter<number | null | undefined>;
+}
+/**
+ * `useDmsFetch`'s options: ofetch's request options, of which the method, the
+ * query, the params and the body may be refs or getters, and the async data
+ * options.
+ */
+export interface UseFetchOptions<T>
+  extends
+    Omit<FetchOptions, DmsFetchRequestSources>,
+    Omit<UseAsyncDataOptions<T>, "transform"> {
+  /**
+   * The key the response is shared and transferred under, in place of the
+   * one the request gives: its method, base URL, URL, query and body. A ref
+   * or a getter moves the caller to the data of each key it takes; `null` or
+   * `undefined` requests nothing until it has a value.
+   */
+  key?: MaybeRefOrGetter<DmsAsyncDataKey>;
+  method?: MaybeRefOrGetter<FetchOptions["method"]>;
+  query?: MaybeRefOrGetter<FetchOptions["query"]>;
+  params?: MaybeRefOrGetter<FetchOptions["params"]>;
+  body?: MaybeRefOrGetter<FetchOptions["body"]>;
+  transform?: (
+    value: unknown,
+    context: DmsFetchTransformContext,
+  ) => T | Promise<T>;
+  /** Replaces the fetch function; it receives the run's signal. */
+  $fetch?: typeof ofetch;
+}
+export interface DmsErrorData {
+  statusCode?: number;
+  statusMessage?: string;
+  message?: string;
+  data?: unknown;
+  fatal?: boolean;
+}
+/** What a server render hands the browser along with its HTML. */
+export interface DmsPayload {
+  data: Record<string, unknown>;
+  errors: Record<string, DmsErrorData>;
+  state: Record<string, unknown>;
+}
+export interface DmsStateOptions {
+  /**
+   * Hands the server's value to the browser, which then starts from it
+   * instead of calling `init` again. Never for tokens or secrets: the value
+   * is written into the page.
+   */
+  transfer?: boolean;
+}
+export interface DmsUserSession<TUser = DmsUser, TSession = DmsSession> {
+  user: Ref<TUser | null>;
+  session: Ref<TSession | null>;
+  loggedIn: Ref<boolean>;
+  fetch(): Promise<void>;
+  clear(): Promise<void>;
+}
+export interface DmsCookieOptions<T> {
+  default?: () => T;
+  maxAge?: number;
+  path?: string;
+  sameSite?: "strict" | "lax" | "none";
+  secure?: boolean;
+}
+type DmsLinkPrefetchMode = "mount" | "hover" | "click";
+export type DmsLinkPrefetch =
+  | boolean
+  | DmsLinkPrefetchMode
+  | DmsLinkPrefetchMode[];
+export interface DmsAppContext {
+  provide<T>(key: string, value: T): void;
+  vueApp: App;
+  runWithContext<T>(callback: () => T): T;
+  hook(name: string, callback: () => void | Promise<void>): void;
+  $i18n: DmsI18n;
+}
+export interface DmsLocale {
+  code: string;
+  name?: string;
+}
+export type DmsI18n = Composer & {
+  locales: ComputedRef<DmsLocale[]>;
+  setLocale(locale: string): Promise<void>;
+};
+export type DmsPluginSetup = (context: DmsAppContext) => void | Promise<void>;
+export interface DmsMiddlewareRegistrationOptions {
+  global?: boolean;
+  /**
+   * Runs at the same time as the parallel middlewares next to it, for one
+   * that reads nothing another middleware sets (a check against the backend,
+   * say). Their results still apply in registration order: the first that
+   * redirects or aborts wins, and the next middlewares wait for all of them.
+   */
+  parallel?: boolean;
+}
+export interface DmsPluginRegistrationOptions {
+  clientOnly?: boolean;
+  /**
+   * When the plugin runs, as Nuxt's `enforce`: every module's `"pre"`
+   * plugins first, then the `"default"` ones, then the `"post"` ones, each
+   * group in the modules' priority order. A plugin that the others depend on
+   * whatever their module's priority, such as the one setting the async data
+   * scope (`setDmsAsyncDataScope`), is `"pre"`.
+   */
+  enforce?: "pre" | "default" | "post";
+}
+export type DmsComponentPreloader = () => Promise<unknown>;
+export interface DmsComponentRegistrationOptions {
+  /**
+   * Registers the component under `name` as given, without the module's
+   * `componentPrefix`: the way to replace a component another module
+   * registers, from a module of higher priority. Defaults to `true`.
+   */
+  prefix?: boolean;
+}

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

@@ -0,0 +1,247 @@
+import { Link as InertiaLink } from "@inertiajs/vue3";
+import {
+  useHead as useUnhead,
+  useSeoMeta as useUnheadSeoMeta,
+} from "@unhead/vue";
+import {
+  type App,
+  type Component,
+  type ComponentInternalInstance,
+  type ComputedRef,
+  defineComponent,
+  getCurrentInstance,
+  h,
+  type InjectionKey,
+  inject,
+  onMounted,
+  type PropType,
+  type Ref,
+  ref,
+} from "vue";
+import { useI18n as useVueI18n } from "vue-i18n";
+import { type DmsFrontendRuntime } from "./module-registration";
+import {
+  type DmsAppContext,
+  type DmsI18n,
+  type DmsLinkPrefetch,
+  type DmsNavigationOptions,
+  type DmsPluginSetup,
+  type RouteLocationRaw,
+} from "./types";
+import { useDmsRuntime } from "./state";
+import { locationToUrl, visit } from "./route";
+
+/**
+ * What Vue's development build passes `errorHandler` for an error thrown by a
+ * component's `setup`, sync or async (production passes a link instead; it has
+ * no warnings to scope either).
+ */
+export const SETUP_FUNCTION_ERROR = "setup function";
+/**
+ * Whether a Vue warning comes from a component whose `setup` failed, or from
+ * under it. Vue still renders such a component, against the setup state that
+ * never came: in development, where a single-file component's template is
+ * compiled apart from its setup, the template reads the missing bindings, and
+ * every component it uses becomes `undefined` ("Invalid vnode type when
+ * creating vnode: undefined", then "Component <Anonymous> is missing template
+ * or render function" for the comment Vue renders in its place). The error
+ * page replaces that output (a server renders the page again, the browser
+ * swaps it), and the failure itself is already reported.
+ *
+ * Walks internal instances: a `<script setup>` component exposes itself, so
+ * its children's `$parent` is an expose proxy, not the proxy `errorHandler`
+ * received.
+ */
+export function withinFailedSetup(
+  instance: ComponentInternalInstance | null,
+  failedSetups: WeakSet<ComponentInternalInstance>,
+): boolean {
+  for (let current = instance; current; current = current.parent)
+    if (failedSetups.has(current)) return true;
+  return false;
+}
+/** Shows the error page in place of the page, keeping the first failure. */
+export function failPage(runtime: DmsFrontendRuntime, reason: unknown): void {
+  runtime.currentError.value ??=
+    reason instanceof Error ? reason : new Error(String(reason));
+}
+export function abortDmsNavigation(): false {
+  return false;
+}
+export const useHead = useUnhead;
+export const useSeoMeta = useUnheadSeoMeta;
+export function useI18n(): DmsI18n {
+  return useVueI18n() as DmsI18n;
+}
+
+function shouldNavigateDmsLink(event: MouseEvent): boolean {
+  const element = event.currentTarget;
+  return !(
+    event.defaultPrevented ||
+    event.button !== 0 ||
+    event.altKey ||
+    event.ctrlKey ||
+    event.metaKey ||
+    event.shiftKey ||
+    (element instanceof HTMLAnchorElement &&
+      Boolean(element.target) &&
+      element.target !== "_self")
+  );
+}
+
+function dmsLinkNavigationOptions(
+  attributes: Record<string, unknown>,
+): DmsNavigationOptions {
+  const options = attributes as DmsNavigationOptions;
+  return {
+    async: options.async,
+    component: options.component,
+    data: options.data,
+    except: options.except,
+    headers: options.headers,
+    method: options.method,
+    onBefore: options.onBefore,
+    onCancel: options.onCancel,
+    onCancelToken: options.onCancelToken,
+    onError: options.onError,
+    onFinish: options.onFinish,
+    onProgress: options.onProgress,
+    onStart: options.onStart,
+    onSuccess: options.onSuccess,
+    only: options.only,
+    preserveScroll: options.preserveScroll,
+    preserveState: options.preserveState,
+    preserveUrl: options.preserveUrl,
+    queryStringArrayFormat: options.queryStringArrayFormat,
+    replace: options.replace,
+    viewTransition: options.viewTransition,
+  };
+}
+
+export const DmsLink: Component = defineComponent({
+  name: "DmsLink",
+  inheritAttrs: false,
+  props: {
+    to: {
+      type: [String, Object] as PropType<RouteLocationRaw>,
+      required: true,
+    },
+  },
+  setup(props, { attrs, slots }) {
+    const runtime = useDmsRuntime();
+    const prefetch = attrs.prefetch as DmsLinkPrefetch | undefined;
+    const onClick = (event: MouseEvent) => {
+      if (typeof attrs.onClick === "function") attrs.onClick(event);
+      if (!shouldNavigateDmsLink(event)) return;
+      event.preventDefault();
+      void visit(runtime, props.to, dmsLinkNavigationOptions(attrs));
+    };
+    return (): ReturnType<typeof h> =>
+      h(
+        InertiaLink,
+        {
+          ...attrs,
+          href: locationToUrl(runtime, props.to),
+          onClick,
+          prefetch: prefetch ?? "hover",
+        },
+        slots,
+      );
+  },
+});
+
+/** How a keyboard hint prints its modifiers: macOS symbols, or PC key names. */
+export type DmsKbdPlatform = "mac" | "other";
+/**
+ * Where Nuxt UI's key hints read the platform: called in the setup of each
+ * component that prints one, it returns the platform that component renders.
+ * It must read on the server the platform it renders there, and keep it while
+ * its caller hydrates, so the browser's first render matches the server's.
+ */
+export type DmsKbdPlatformSource = () => Readonly<Ref<DmsKbdPlatform>>;
+
+const KBD_PLATFORM_KEY: InjectionKey<DmsKbdPlatformSource> =
+  Symbol("dms:kbd-platform");
+const MODIFIER_KBD_KEYS: Record<
+  DmsKbdPlatform,
+  Record<"meta" | "ctrl" | "alt", string>
+> = {
+  mac: { meta: "⌘", ctrl: "⌃", alt: "⌥" },
+  other: { meta: "Ctrl", ctrl: "Ctrl", alt: "Alt" },
+};
+const isModifierKbdKey = (value: string): value is "meta" | "ctrl" | "alt" =>
+  value === "meta" || value === "ctrl" || value === "alt";
+
+/**
+ * Gives Nuxt UI's key hints (`UKbd`, the `kbds` of its menus, the dashboard
+ * search button) the application's keyboard platform, so the server prints
+ * `meta` as "⌘" or "Ctrl" from the first render instead of a blank the
+ * browser fills in after mounting.
+ */
+export function provideDmsKbdPlatform(
+  app: App,
+  source: DmsKbdPlatformSource,
+): void {
+  app.provide(KBD_PLATFORM_KEY, source);
+}
+
+interface NuxtUiKbd {
+  macOS: ComputedRef<unknown>;
+  getKbdKey: (value?: string) => string | undefined;
+}
+
+/**
+ * Nuxt UI's `useKbd` as the DMS runs it (`ui-kbd.mjs` routes it here): a hint
+ * renders the same on the server and in the hydrating browser. Nuxt UI prints
+ * `meta`, `ctrl` and `alt` from a map shared by every hint and filled by the
+ * first one's `onMounted`, so a hint hydrating after that (in an async
+ * component) printed "⌘" over the server's blank. Each hint now keeps the
+ * server's value until its own `onMounted`; with a platform provided
+ * (`provideDmsKbdPlatform`), that value is the platform's from the start.
+ *
+ * @internal
+ */
+export function useDmsKbd(
+  shared: () => NuxtUiKbd,
+  keys: Readonly<Record<string, string>>,
+): NuxtUiKbd {
+  const { macOS } = shared();
+  const instance = getCurrentInstance();
+  const source = instance ? inject(KBD_PLATFORM_KEY, null) : null;
+  const platform = source ? source() : null;
+  // A hydrating component's vnode is bound to its server node before setup.
+  const hydrating = ref(!!instance?.vnode.el);
+  if (hydrating.value) onMounted(() => (hydrating.value = false));
+  return {
+    macOS,
+    getKbdKey(value) {
+      if (!value) return undefined;
+      if (!isModifierKbdKey(value)) return keys[value] || value;
+      if (platform) return MODIFIER_KBD_KEYS[platform.value][value];
+      if (typeof window === "undefined" || hydrating.value) return " ";
+      return MODIFIER_KBD_KEYS[macOS.value ? "mac" : "other"][value];
+    },
+  };
+}
+
+export const DmsClientOnly = defineComponent({
+  name: "DmsClientOnly",
+  setup(_, { slots }) {
+    const isMounted = ref(false);
+    onMounted(() => {
+      isMounted.value = true;
+    });
+    return () =>
+      isMounted.value ? slots.default?.() : (slots.fallback?.() ?? null);
+  },
+});
+
+export function defineDmsPlugin(setup: DmsPluginSetup): DmsPluginSetup {
+  return setup;
+}
+export function useDmsApp(): DmsAppContext {
+  const instance = getCurrentInstance();
+  const contextual = instance?.appContext.config.globalProperties
+    .$dms as DmsAppContext;
+  return contextual ?? (useDmsRuntime().appContext as DmsAppContext);
+}

package/templates/vue/globals.d.ts

@@ -1 +1,6 @@
 declare const defineDmsAppConfig: typeof import("./frontend-module").defineDmsAppConfig;
+declare module "virtual:nuxt-ui-icons" {
+  export function init(
+    add: (name: string, data: import("@iconify/vue").IconifyIcon) => boolean,
+  ): void;
+}

package/templates/vue/head-order.mjs

@@ -1,16 +1,3 @@
-// Restoring "paint before hydrate" in the built document.
-//
-// The source index.html marks the entry script `fetchpriority="low"` so the
-// browser spends its bandwidth on the render-blocking stylesheet first. Vite
-// rewrites that script tag when it builds and drops the attribute, and it emits
-// the script *before* the stylesheet — so the production document did the
-// opposite of what the template asked: it discovered a 250 kB hydration bundle
-// first and let it compete with the 27 kB the first paint actually waits on,
-// over the plain HTTP/1.1 the generated server speaks.
-//
-// Kept beside vite.config.ts rather than inside it so the transform can be
-// exercised on its own, the way client-manifest.mjs is.
-
 const SCRIPT = /<script[^>]*\stype="module"[^>]*><\/script>/;
 const STYLESHEET = /[ \t]*<link rel="stylesheet"[^>]*>\n?/;
 
@@ -26,6 +13,17 @@ function deprioritize(html) {
  * Give the entry script back its low fetch priority and move the stylesheet
  * ahead of it. A document that already has them in that order is returned
  * unchanged, so the transform is safe to run twice.
+ *
+ * Restores "paint before hydrate" in the built document. The source index.html
+ * marks the entry script `fetchpriority="low"` so the browser spends its
+ * bandwidth on the render-blocking stylesheet first. Vite rewrites that script
+ * tag when it builds and drops the attribute, and it emits the script before
+ * the stylesheet, so the production document did the opposite of what the
+ * template asked: it discovered a 250 kB hydration bundle first and let it
+ * compete with the 27 kB the first paint actually waits on, over the plain
+ * HTTP/1.1 the generated server speaks. Kept beside vite.config.ts rather than
+ * inside it so the transform can be exercised on its own, the way
+ * client-manifest.mjs is.
  */
 export function orderHeadForFirstPaint(html) {
   const prioritized = deprioritize(html);

package/templates/vue/icon-bundle.ts

@@ -0,0 +1,31 @@
+import { addIcon, type IconifyIcon } from "@iconify/vue";
+
+function register(name: string, data: IconifyIcon): boolean {
+  const colon = name.indexOf(":");
+  if (colon !== -1 && name.slice(0, colon).includes("-")) {
+    addIcon(name.replace(":", "-"), data);
+  }
+  return addIcon(name, data);
+}
+
+let loading: Promise<void> | undefined;
+
+/**
+ * Loads the icons Nuxt UI bundles for the client, once: every icon the
+ * application's sources name. A server render has them from the start (Nuxt
+ * UI's own plugin, left in place by `ui-lazy-icons.mjs`), so there is nothing
+ * to load.
+ *
+ * A failed load is forgotten and resolves: an icon the bundle would have
+ * held is then fetched from the icon API, as one outside the bundle always is.
+ */
+export function loadIconBundle(): Promise<void> {
+  if (import.meta.env.SSR) return Promise.resolve();
+  loading ??= import("virtual:nuxt-ui-icons").then(
+    ({ init }) => init(register),
+    () => {
+      loading = undefined;
+    },
+  );
+  return loading;
+}