@panyam/tsappkit 0.3.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panyam/tsappkit",
-  "version": "0.3.0",
+  "version": "0.6.1",
   "description": "TypeScript application toolkit with component lifecycle management, event system, UI utilities, and documentation site components",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/index.ts

@@ -31,8 +31,10 @@ export { MobileBottomDrawer } from './MobileBottomDrawer';
 export { IslandPage } from './page/IslandPage';
 export { readSpec, SPEC_ELEMENT_ID } from './page/spec';
 export type { IslandSpec, PageSpec, SpecExtension } from './page/spec';
-export { mountIslands } from './page/mount';
-export type { IslandFactory, Registry } from './page/mount';
+export { lazy, mountIslands } from './page/mount';
+export type { IslandFactory, LazyIsland, MountOptions, Registry } from './page/mount';
+export { parseLoad, scheduleMount } from './page/load';
+export type { LoadEnv, LoadStrategy } from './page/load';
 
 // Utilities
 export { isInInputContext, hasModifierKeys, shouldIgnoreShortcut } from './DOMUtils';

package/src/page/IslandPage.ts

@@ -1,6 +1,8 @@
 import { BasePage } from "../BasePage";
 import type { EventBus } from "../EventBus";
 import type { LCMComponent } from "../LCMComponent";
+import { LifecycleController } from "../LifecycleController";
+import { parseLoad, scheduleMount, type LoadStrategy } from "./load";
 import { mountIslands, type Registry } from "./mount";
 import { readSpec, SPEC_ELEMENT_ID, type PageSpec } from "./spec";
 
@@ -15,6 +17,13 @@ import { readSpec, SPEC_ELEMENT_ID, type PageSpec } from "./spec";
  * fields in `readExtension`, and they arrive typed as `Ext` on the spec
  * `makeContext` gets.
  *
+ * Each island mounts when its `load` says (`eager`, `idle`, `visible`,
+ * `media:<query>`; see scheduleMount), and a `lazy` registry entry loads its
+ * chunk then. One that mounts later, a lazy eager one included, goes through
+ * its own LifecycleController, so it still gets performLocalInit,
+ * setupDependencies and activate. A deferred island mustn't be something
+ * another island or the page needs at startup: nothing waits for it.
+ *
  * A page with no readable `#page-spec` mounts nothing and warns. Subclasses
  * that override initializeSpecificComponents call super and add to what it
  * returns.
@@ -44,6 +53,22 @@ export abstract class IslandPage<Ctx, Ext extends object = {}> extends BasePage
       () => this.makeContext(spec),
       this.eventBus,
       (message) => console.warn(message),
+      {
+        defer: (island, el, mount) => this.scheduleLoad(parseLoad(island.load) ?? { kind: "eager" }, el, mount),
+        onLateMount: (component, island) => {
+          new LifecycleController(this.eventBus, LifecycleController.DefaultConfig)
+            .initializeFromRoot(component)
+            .catch((err) => console.warn(`page spec: island "${island.name}" failed to start: ${err instanceof Error ? err.message : String(err)}`));
+        },
+      },
     );
   }
+
+  /**
+   * Waits for `strategy` and then calls `mount`. Defaults to scheduleMount
+   * against the window; a subclass or test can replace how the waiting is done.
+   */
+  protected scheduleLoad(strategy: LoadStrategy, el: HTMLElement, mount: () => void): void {
+    scheduleMount(strategy, el, mount);
+  }
 }

package/src/page/load.ts

@@ -0,0 +1,86 @@
+/**
+ * When an island mounts: its `load` in the page spec (goapplib's
+ * page.Island.Load), read and waited for. Every strategy mounts once; an
+ * island isn't unmounted when its media query stops matching.
+ */
+
+/** A parsed `load`. An empty or missing one is eager. */
+export type LoadStrategy =
+  | { kind: "eager" }
+  | { kind: "idle" }
+  | { kind: "visible" }
+  | { kind: "media"; query: string };
+
+/**
+ * The strategy `load` names, or null when it isn't one of the forms Go's
+ * Validate accepts (`eager`, `idle`, `visible`, `media:<query>`), compared
+ * exactly.
+ */
+export function parseLoad(load: string | undefined): LoadStrategy | null {
+  switch (load ?? "") {
+    case "":
+    case "eager":
+      return { kind: "eager" };
+    case "idle":
+      return { kind: "idle" };
+    case "visible":
+      return { kind: "visible" };
+  }
+  const query = load!.startsWith("media:") ? load!.slice("media:".length) : "";
+  return query.trim() ? { kind: "media", query } : null;
+}
+
+/**
+ * The browser APIs scheduleMount waits on, so tests can stand them in.
+ * `requestIdleCallback` is optional because Safari doesn't have it.
+ */
+export interface LoadEnv {
+  requestIdleCallback?: (cb: () => void) => unknown;
+  setTimeout: (cb: () => void, ms?: number) => unknown;
+  IntersectionObserver: typeof IntersectionObserver;
+  matchMedia: (query: string) => MediaQueryList;
+}
+
+/**
+ * Calls `mount` once, when `strategy` says the island in `el` should mount:
+ * at once for eager; when the browser is idle (or on the next task, without
+ * requestIdleCallback) for idle; the first time any of `el` enters the
+ * viewport for visible; and at once if the query matches, or else on the
+ * first change that makes it match, for media.
+ */
+export function scheduleMount(strategy: LoadStrategy, el: Element, mount: () => void, env: LoadEnv = window): void {
+  switch (strategy.kind) {
+    case "eager":
+      mount();
+      return;
+    case "idle":
+      if (env.requestIdleCallback) env.requestIdleCallback(mount);
+      else env.setTimeout(mount, 1);
+      return;
+    case "visible": {
+      let done = false;
+      const observer = new env.IntersectionObserver((entries) => {
+        if (done || !entries.some((e) => e.isIntersecting)) return;
+        done = true;
+        observer.disconnect();
+        mount();
+      });
+      observer.observe(el);
+      return;
+    }
+    case "media": {
+      const mq = env.matchMedia(strategy.query);
+      if (mq.matches) {
+        mount();
+        return;
+      }
+      const onChange = (e: { matches: boolean }) => {
+        if (!e.matches) return;
+        mq.removeEventListener("change", onChange);
+        mount();
+      };
+      mq.addEventListener("change", onChange);
+      return;
+    }
+  }
+}

package/src/page/mount.ts

@@ -1,3 +1,4 @@
+import { parseLoad } from "./load";
 import type { IslandSpec, PageSpec } from "./spec";
 
 /**
@@ -6,18 +7,65 @@ import type { IslandSpec, PageSpec } from "./spec";
  */
 export type IslandFactory<Ctx, El, C, B> = (el: El, island: IslandSpec, ctx: Ctx, bus: B) => C;
 
-/** The islands an entry can mount, by name. An entry bundles only what its registry names. */
-export type Registry<Ctx, El, C, B> = Record<string, IslandFactory<Ctx, El, C, B>>;
+const LAZY: unique symbol = Symbol("lazy island");
+
+/** A registry entry whose factory is loaded when the island mounts. Made by lazy. */
+export interface LazyIsland<Ctx, El, C, B> {
+  readonly [LAZY]: () => Promise<IslandFactory<Ctx, El, C, B> | { default: IslandFactory<Ctx, El, C, B> }>;
+}
+
+/**
+ * A registry entry that loads its island's module only when the island
+ * mounts: `hero: lazy(() => import("./islands/hero"))`. With esbuild's
+ * --splitting each such module is its own chunk, so a page downloads only the
+ * islands its spec names, each when its `load` says. `load` resolves to the
+ * factory or to a module whose default export is the factory.
+ *
+ * A lazy island always mounts late, even an eager one, since its chunk
+ * arrives after the page has started; goapplib's page.Assets writes
+ * modulepreload links for the eager ones so that wait is short.
+ */
+export function lazy<Ctx, El, C, B>(
+  load: () => Promise<IslandFactory<Ctx, El, C, B> | { default: IslandFactory<Ctx, El, C, B> }>,
+): LazyIsland<Ctx, El, C, B> {
+  return { [LAZY]: load };
+}
+
+/**
+ * The islands an entry can mount, by name: a factory, bundled with the entry,
+ * or a lazy entry, loaded as its own chunk when the island mounts.
+ */
+export type Registry<Ctx, El, C, B> = Record<string, IslandFactory<Ctx, El, C, B> | LazyIsland<Ctx, El, C, B>>;
+
+/** How mountIslands handles islands that shouldn't mount at once. */
+export interface MountOptions<El, C> {
+  /**
+   * Gets each island whose `load` isn't eager, with the slot it will mount
+   * in; call `mount` when it's time (IslandPage passes scheduleMount). An
+   * island with a `load` parseLoad doesn't know is logged and mounted at once
+   * instead, so it still shows up.
+   */
+  defer?: (island: IslandSpec, el: El, mount: () => void) => void;
+  /** Gets what the factory built for each island mounted later: through `defer`, or from a lazy entry. */
+  onLateMount?: (component: C, island: IslandSpec) => void;
+}
 
 /**
  * Mounts every island in `spec` into the element `findSlot` gives for its
- * slot, and returns what the factories built, in spec order. `context` builds
- * the page's shared services; it's called once, before the first island
- * mounts, and not at all on a page with nothing to mount, so a page without
- * islands doesn't start what they'd share. An island the registry doesn't
- * know, a slot that isn't on the page, or a factory that throws is reported
- * through `log` and skipped, so one bad entry doesn't take the rest of the
- * page down with it.
+ * slot, and returns what the factories built at once, in spec order. With
+ * `options.defer`, an island whose `load` isn't eager is handed to it instead
+ * and reported through `options.onLateMount` when it mounts; without it,
+ * every island mounts now whatever its `load` says. A lazy entry is loaded
+ * when its island would mount and is reported through `onLateMount` too, so
+ * it's never in the returned list.
+ *
+ * `context` builds the page's shared services; it's called once, before the
+ * first island mounts (eager or late), and not at all on a page with nothing
+ * to mount, so a page without islands doesn't start what they'd share. An
+ * island the registry doesn't know, a slot that isn't on the page, or a
+ * factory that throws (now or later), or a lazy entry that fails to load, is
+ * reported through `log` and skipped,
+ * so one bad entry doesn't take the rest of the page down with it.
  *
  * Plain types throughout (no DOM), so it runs under node in tests and on a
  * bare page without BasePage.
@@ -29,12 +77,13 @@ export function mountIslands<Ctx, El, C, B>(
   context: () => Ctx,
   bus: B,
   log: (message: string) => void,
+  options: MountOptions<El, C> = {},
 ): C[] {
   const out: C[] = [];
   let ctx: Ctx | undefined;
   for (const island of spec.islands) {
-    const factory = Object.prototype.hasOwnProperty.call(registry, island.name) ? registry[island.name] : undefined;
-    if (!factory) {
+    const entry = Object.prototype.hasOwnProperty.call(registry, island.name) ? registry[island.name] : undefined;
+    if (!entry) {
       log(`page spec: no island called "${island.name}" in this page's registry`);
       continue;
     }
@@ -43,12 +92,52 @@ export function mountIslands<Ctx, El, C, B>(
       log(`page spec: island "${island.name}" wants slot "${island.slot}", which isn't on the page`);
       continue;
     }
-    try {
-      ctx ??= context();
-      out.push(factory(el, island, ctx, bus));
-    } catch (err) {
-      log(`page spec: island "${island.name}" failed to mount: ${err instanceof Error ? err.message : String(err)}`);
+    const build = (factory: IslandFactory<Ctx, El, C, B>): C | undefined => {
+      try {
+        ctx ??= context();
+        return factory(el, island, ctx, bus);
+      } catch (err) {
+        log(`page spec: island "${island.name}" failed to mount: ${message(err)}`);
+        return undefined;
+      }
+    };
+    const mountLate = () => {
+      const late = (factory: IslandFactory<Ctx, El, C, B>) => {
+        const c = build(factory);
+        if (c !== undefined) options.onLateMount?.(c, island);
+      };
+      if (typeof entry === "function") {
+        late(entry);
+        return;
+      }
+      // The executor turns a loader that throws into a rejection, logged like any other.
+      new Promise<Awaited<ReturnType<(typeof entry)[typeof LAZY]>>>((resolve) => resolve(entry[LAZY]())).then(
+        (m) => {
+          const factory = typeof m === "function" ? m : m?.default;
+          if (typeof factory === "function") late(factory);
+          else log(`page spec: island "${island.name}" loaded, but its module has no factory (a default export or the function itself)`);
+        },
+        (err) => log(`page spec: island "${island.name}" failed to load: ${message(err)}`),
+      );
+    };
+    const strategy = parseLoad(island.load);
+    if (strategy === null) {
+      log(`page spec: island "${island.name}" has load "${island.load}", which isn't eager, idle, visible or media:<query>; mounting it now`);
+    }
+    if (options.defer && strategy !== null && strategy.kind !== "eager") {
+      options.defer(island, el, mountLate);
+      continue;
     }
+    if (typeof entry !== "function") {
+      mountLate();
+      continue;
+    }
+    const c = build(entry);
+    if (c !== undefined) out.push(c);
   }
   return out;
 }
+
+function message(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/src/page/spec.ts

@@ -15,6 +15,12 @@ export interface IslandSpec {
   presentation?: string;
   /** Handed to the factory as is. Always an object. */
   config: Record<string, unknown>;
+  /**
+   * When it mounts: `eager` (also when absent), `idle`, `visible` or
+   * `media:<query>` (see parseLoad). IslandPage waits for it; mountIslands
+   * does when given a `defer`.
+   */
+  load?: string;
 }
 
 export interface PageSpec {
@@ -61,6 +67,7 @@ export function readSpec<Ext extends object>(text: string | null | undefined, ex
       slot: is.slot,
       ...(typeof is.presentation === "string" && { presentation: is.presentation }),
       config: isObject(is.config) ? is.config : {},
+      ...(typeof is.load === "string" && { load: is.load }),
     });
   }
   const spec: PageSpec = { layout: raw.layout, islands };