@panyam/tsappkit 0.6.1 → 0.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panyam/tsappkit",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "TypeScript application toolkit with component lifecycle management, event system, UI utilities, and documentation site components",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -59,7 +59,7 @@
     "sass": "^1.77.0",
     "tsup": "^8.0.0",
     "typescript": "^5.0.0",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.3"
   },
   "peerDependencies": {
     "ace-builds": "^1.0.0"

package/src/index.ts

@@ -32,6 +32,7 @@ export { IslandPage } from './page/IslandPage';
 export { readSpec, SPEC_ELEMENT_ID } from './page/spec';
 export type { IslandSpec, PageSpec, SpecExtension } from './page/spec';
 export { lazy, mountIslands } from './page/mount';
+export { IslandOverlay } from './page/overlay';
 export type { IslandFactory, LazyIsland, MountOptions, Registry } from './page/mount';
 export { parseLoad, scheduleMount } from './page/load';
 export type { LoadEnv, LoadStrategy } from './page/load';

package/src/page/IslandPage.ts

@@ -4,6 +4,7 @@ import type { LCMComponent } from "../LCMComponent";
 import { LifecycleController } from "../LifecycleController";
 import { parseLoad, scheduleMount, type LoadStrategy } from "./load";
 import { mountIslands, type Registry } from "./mount";
+import { IslandOverlay } from "./overlay";
 import { readSpec, SPEC_ELEMENT_ID, type PageSpec } from "./spec";
 
 /**
@@ -24,6 +25,10 @@ import { readSpec, SPEC_ELEMENT_ID, type PageSpec } from "./spec";
  * setupDependencies and activate. A deferred island mustn't be something
  * another island or the page needs at startup: nothing waits for it.
  *
+ * With `?islands` in the URL (or showIslandOverlay overridden), each slot is
+ * outlined and labelled with its island's name, load strategy and state; see
+ * IslandOverlay.
+ *
  * A page with no readable `#page-spec` mounts nothing and warns. Subclasses
  * that override initializeSpecificComponents call super and add to what it
  * returns.
@@ -46,10 +51,18 @@ export abstract class IslandPage<Ctx, Ext extends object = {}> extends BasePage
       console.warn(`page spec: no readable #${SPEC_ELEMENT_ID} on this page, so nothing is mounted`);
       return [];
     }
+    const findSlot = (slot: string) => document.querySelector<HTMLElement>(`[data-slot="${slot}"]`);
+    const overlay = this.showIslandOverlay() ? new IslandOverlay() : undefined;
+    if (overlay) {
+      for (const island of spec.islands) {
+        const el = findSlot(island.slot);
+        if (el) overlay.waiting(island, el);
+      }
+    }
     return mountIslands(
       spec,
       this.registry(),
-      (slot) => document.querySelector<HTMLElement>(`[data-slot="${slot}"]`),
+      findSlot,
       () => this.makeContext(spec),
       this.eventBus,
       (message) => console.warn(message),
@@ -60,10 +73,26 @@ export abstract class IslandPage<Ctx, Ext extends object = {}> extends BasePage
             .initializeFromRoot(component)
             .catch((err) => console.warn(`page spec: island "${island.name}" failed to start: ${err instanceof Error ? err.message : String(err)}`));
         },
+        onMount: overlay && ((_c, island, el) => overlay.mounted(island, el)),
+        onSkip:
+          overlay &&
+          ((island, reason) => {
+            const el = findSlot(island.slot);
+            if (el) overlay.failed(island, el, reason);
+          }),
       },
     );
   }
 
+  /**
+   * Whether to draw the island overlay. The default is true when the URL has
+   * an `islands` query parameter (`/game?islands`); a subclass can tie it to
+   * its own debug setting instead.
+   */
+  protected showIslandOverlay(): boolean {
+    return new URLSearchParams(window.location.search).has("islands");
+  }
+
   /**
    * Waits for `strategy` and then calls `mount`. Defaults to scheduleMount
    * against the window; a subclass or test can replace how the waiting is done.

package/src/page/mount.ts

@@ -48,6 +48,18 @@ export interface MountOptions<El, C> {
   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;
+  /**
+   * Gets every island that mounts, eager or late, with its slot, as it
+   * mounts (before onLateMount for a late one). IslandPage's debug overlay
+   * uses it to show when each island arrived.
+   */
+  onMount?: (component: C, island: IslandSpec, el: El) => void;
+  /**
+   * Gets every island that won't mount, with a short reason ("not in the
+   * registry", "no slot", "failed to load", "no factory", "factory threw"),
+   * alongside the message `log` gets.
+   */
+  onSkip?: (island: IslandSpec, reason: string) => void;
 }
 
 /**
@@ -80,16 +92,20 @@ export function mountIslands<Ctx, El, C, B>(
   options: MountOptions<El, C> = {},
 ): C[] {
   const out: C[] = [];
+  const skip = (island: IslandSpec, reason: string, message: string) => {
+    log(message);
+    options.onSkip?.(island, reason);
+  };
   let ctx: Ctx | undefined;
   for (const island of spec.islands) {
     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`);
+      skip(island, "not in the registry", `page spec: no island called "${island.name}" in this page's registry`);
       continue;
     }
     const el = findSlot(island.slot);
     if (el === null) {
-      log(`page spec: island "${island.name}" wants slot "${island.slot}", which isn't on the page`);
+      skip(island, "no slot", `page spec: island "${island.name}" wants slot "${island.slot}", which isn't on the page`);
       continue;
     }
     const build = (factory: IslandFactory<Ctx, El, C, B>): C | undefined => {
@@ -97,14 +113,16 @@ export function mountIslands<Ctx, El, C, B>(
         ctx ??= context();
         return factory(el, island, ctx, bus);
       } catch (err) {
-        log(`page spec: island "${island.name}" failed to mount: ${message(err)}`);
+        skip(island, "factory threw", `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 (c === undefined) return;
+        options.onMount?.(c, island, el);
+        options.onLateMount?.(c, island);
       };
       if (typeof entry === "function") {
         late(entry);
@@ -115,9 +133,9 @@ export function mountIslands<Ctx, El, C, B>(
         (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)`);
+          else skip(island, "no factory", `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)}`),
+        (err) => skip(island, "failed to load", `page spec: island "${island.name}" failed to load: ${message(err)}`),
       );
     };
     const strategy = parseLoad(island.load);
@@ -133,7 +151,10 @@ export function mountIslands<Ctx, El, C, B>(
       continue;
     }
     const c = build(entry);
-    if (c !== undefined) out.push(c);
+    if (c !== undefined) {
+      out.push(c);
+      options.onMount?.(c, island, el);
+    }
   }
   return out;
 }

package/src/page/overlay.ts

@@ -0,0 +1,63 @@
+import type { IslandSpec } from "./spec";
+
+const STYLE_ID = "island-overlay-style";
+
+// The label is drawn by ::after from an attribute, so the overlay adds no
+// children to a slot the island owns, and an island clearing its slot on
+// mount (SolidIsland does) doesn't take the label with it.
+const CSS = `
+[data-island-debug] { position: relative; outline: 2px dashed #1565c0; outline-offset: -2px; }
+[data-island-debug]::after {
+  content: attr(data-island-debug); position: absolute; top: 0; right: 0; z-index: 2147483647;
+  font: 11px/1.4 ui-monospace, monospace; padding: 1px 6px; background: #1565c0; color: #fff; pointer-events: none;
+}
+[data-island-state="mounted"] { outline-color: #2e7d32; }
+[data-island-state="mounted"]::after { background: #2e7d32; }
+[data-island-state="failed"] { outline-color: #c62828; }
+[data-island-state="failed"]::after { background: #c62828; }
+`;
+
+/**
+ * Outlines each island's slot and labels it with its name, slot, load
+ * strategy and state: `hero · top · eager · mounted 212 ms`,
+ * `below · bottom · visible · waiting`, or `ghost · foot · eager · not in the
+ * registry`. Times are from navigation start (performance.now()).
+ *
+ * IslandPage turns it on with `?islands` in the URL (see
+ * showIslandOverlay). It's a development aid: while it's on, every labelled
+ * slot is `position: relative`, which can move an island's absolutely
+ * positioned content.
+ */
+export class IslandOverlay {
+  constructor(
+    private readonly doc: Document = document,
+    private readonly now: () => number = () => performance.now(),
+  ) {
+    if (!doc.getElementById(STYLE_ID)) {
+      const style = doc.createElement("style");
+      style.id = STYLE_ID;
+      style.textContent = CSS;
+      doc.head.appendChild(style);
+    }
+  }
+
+  /** The island has a slot and hasn't mounted yet. */
+  waiting(island: IslandSpec, el: HTMLElement): void {
+    this.label(island, el, "waiting", "waiting");
+  }
+
+  /** The island has just mounted. */
+  mounted(island: IslandSpec, el: HTMLElement): void {
+    this.label(island, el, "mounted", `mounted ${Math.round(this.now())} ms`);
+  }
+
+  /** The island won't mount, for `reason`. */
+  failed(island: IslandSpec, el: HTMLElement, reason: string): void {
+    this.label(island, el, "failed", reason);
+  }
+
+  private label(island: IslandSpec, el: HTMLElement, state: string, text: string): void {
+    el.dataset.islandState = state;
+    el.dataset.islandDebug = [island.name, island.slot, island.load || "eager", text].join(" · ");
+  }
+}