@panyam/tsappkit 0.6.0 → 0.6.2

package/dist/index.d.mts

@@ -888,6 +888,18 @@ 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;
 }
 /**
  * Mounts every island in `spec` into the element `findSlot` gives for its
@@ -929,6 +941,10 @@ declare function mountIslands<Ctx, El, C, B>(spec: PageSpec, registry: Registry<
  * 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.
@@ -942,6 +958,12 @@ declare abstract class IslandPage<Ctx, Ext extends object = {}> extends BasePage
      */
     protected readExtension(raw: Record<string, unknown>): Ext;
     protected initializeSpecificComponents(): LCMComponent[];
+    /**
+     * 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;
     /**
      * Waits for `strategy` and then calls `mount`. Defaults to scheduleMount
      * against the window; a subclass or test can replace how the waiting is done.
@@ -949,6 +971,30 @@ declare abstract class IslandPage<Ctx, Ext extends object = {}> extends BasePage
     protected scheduleLoad(strategy: LoadStrategy, el: HTMLElement, mount: () => void): void;
 }
 
+/**
+ * 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.
+ */
+declare class IslandOverlay {
+    private readonly doc;
+    private readonly now;
+    constructor(doc?: Document, now?: () => number);
+    /** The island has a slot and hasn't mounted yet. */
+    waiting(island: IslandSpec, el: HTMLElement): void;
+    /** The island has just mounted. */
+    mounted(island: IslandSpec, el: HTMLElement): void;
+    /** The island won't mount, for `reason`. */
+    failed(island: IslandSpec, el: HTMLElement, reason: string): void;
+    private label;
+}
+
 /**
  * Common DOM utility functions for consistent behavior across components
  */
@@ -1052,4 +1098,4 @@ declare class KeyboardShortcutManager {
     getCurrentArgs(): string;
 }
 
-export { BaseComponent, BasePage, type Component, type ComponentEventType, ComponentEventTypes, type ComponentLifecycleEvent, EventBus, type EventHandler, type EventSubscriber, type IslandFactory, IslandPage, type IslandSpec, KeyboardShortcutManager, KeyboardState, type LCMComponent, type LCMComponentConfig, type LCMComponentEvent, type LazyIsland, LifecycleController, type LifecycleEventType, LifecycleEventTypes, type LoadEnv, type LoadStrategy, MobileBottomDrawer, Modal, type MountOptions, type PageSpec, type Registry, SPEC_ELEMENT_ID, type ShortcutConfig, type ShortcutManagerConfig, type SpecExtension, SplashScreen, TemplateLoader, ThemeManager, ToastManager, hasModifierKeys, isInInputContext, lazy, mountIslands, parseLoad, readSpec, scheduleMount, shouldIgnoreShortcut };
+export { BaseComponent, BasePage, type Component, type ComponentEventType, ComponentEventTypes, type ComponentLifecycleEvent, EventBus, type EventHandler, type EventSubscriber, type IslandFactory, IslandOverlay, IslandPage, type IslandSpec, KeyboardShortcutManager, KeyboardState, type LCMComponent, type LCMComponentConfig, type LCMComponentEvent, type LazyIsland, LifecycleController, type LifecycleEventType, LifecycleEventTypes, type LoadEnv, type LoadStrategy, MobileBottomDrawer, Modal, type MountOptions, type PageSpec, type Registry, SPEC_ELEMENT_ID, type ShortcutConfig, type ShortcutManagerConfig, type SpecExtension, SplashScreen, TemplateLoader, ThemeManager, ToastManager, hasModifierKeys, isInInputContext, lazy, mountIslands, parseLoad, readSpec, scheduleMount, shouldIgnoreShortcut };

package/dist/index.d.ts

@@ -888,6 +888,18 @@ 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;
 }
 /**
  * Mounts every island in `spec` into the element `findSlot` gives for its
@@ -929,6 +941,10 @@ declare function mountIslands<Ctx, El, C, B>(spec: PageSpec, registry: Registry<
  * 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.
@@ -942,6 +958,12 @@ declare abstract class IslandPage<Ctx, Ext extends object = {}> extends BasePage
      */
     protected readExtension(raw: Record<string, unknown>): Ext;
     protected initializeSpecificComponents(): LCMComponent[];
+    /**
+     * 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;
     /**
      * Waits for `strategy` and then calls `mount`. Defaults to scheduleMount
      * against the window; a subclass or test can replace how the waiting is done.
@@ -949,6 +971,30 @@ declare abstract class IslandPage<Ctx, Ext extends object = {}> extends BasePage
     protected scheduleLoad(strategy: LoadStrategy, el: HTMLElement, mount: () => void): void;
 }
 
+/**
+ * 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.
+ */
+declare class IslandOverlay {
+    private readonly doc;
+    private readonly now;
+    constructor(doc?: Document, now?: () => number);
+    /** The island has a slot and hasn't mounted yet. */
+    waiting(island: IslandSpec, el: HTMLElement): void;
+    /** The island has just mounted. */
+    mounted(island: IslandSpec, el: HTMLElement): void;
+    /** The island won't mount, for `reason`. */
+    failed(island: IslandSpec, el: HTMLElement, reason: string): void;
+    private label;
+}
+
 /**
  * Common DOM utility functions for consistent behavior across components
  */
@@ -1052,4 +1098,4 @@ declare class KeyboardShortcutManager {
     getCurrentArgs(): string;
 }
 
-export { BaseComponent, BasePage, type Component, type ComponentEventType, ComponentEventTypes, type ComponentLifecycleEvent, EventBus, type EventHandler, type EventSubscriber, type IslandFactory, IslandPage, type IslandSpec, KeyboardShortcutManager, KeyboardState, type LCMComponent, type LCMComponentConfig, type LCMComponentEvent, type LazyIsland, LifecycleController, type LifecycleEventType, LifecycleEventTypes, type LoadEnv, type LoadStrategy, MobileBottomDrawer, Modal, type MountOptions, type PageSpec, type Registry, SPEC_ELEMENT_ID, type ShortcutConfig, type ShortcutManagerConfig, type SpecExtension, SplashScreen, TemplateLoader, ThemeManager, ToastManager, hasModifierKeys, isInInputContext, lazy, mountIslands, parseLoad, readSpec, scheduleMount, shouldIgnoreShortcut };
+export { BaseComponent, BasePage, type Component, type ComponentEventType, ComponentEventTypes, type ComponentLifecycleEvent, EventBus, type EventHandler, type EventSubscriber, type IslandFactory, IslandOverlay, IslandPage, type IslandSpec, KeyboardShortcutManager, KeyboardState, type LCMComponent, type LCMComponentConfig, type LCMComponentEvent, type LazyIsland, LifecycleController, type LifecycleEventType, LifecycleEventTypes, type LoadEnv, type LoadStrategy, MobileBottomDrawer, Modal, type MountOptions, type PageSpec, type Registry, SPEC_ELEMENT_ID, type ShortcutConfig, type ShortcutManagerConfig, type SpecExtension, SplashScreen, TemplateLoader, ThemeManager, ToastManager, hasModifierKeys, isInInputContext, lazy, mountIslands, parseLoad, readSpec, scheduleMount, shouldIgnoreShortcut };

package/dist/index.js

@@ -1431,16 +1431,20 @@ function lazy(load) {
 }
 function mountIslands(spec, registry, findSlot, context, bus, log, options = {}) {
   const out = [];
+  const skip = (island, reason, message2) => {
+    log(message2);
+    options.onSkip?.(island, reason);
+  };
   let ctx;
   for (const island of spec.islands) {
     const entry = Object.prototype.hasOwnProperty.call(registry, island.name) ? registry[island.name] : void 0;
     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) => {
@@ -1448,14 +1452,16 @@ function mountIslands(spec, registry, findSlot, context, bus, log, options = {})
         ctx ?? (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 void 0;
       }
     };
     const mountLate = () => {
       const late = (factory) => {
         const c2 = build(factory);
-        if (c2 !== void 0) options.onLateMount?.(c2, island);
+        if (c2 === void 0) return;
+        options.onMount?.(c2, island, el);
+        options.onLateMount?.(c2, island);
       };
       if (typeof entry === "function") {
         late(entry);
@@ -1465,9 +1471,9 @@ function mountIslands(spec, registry, findSlot, context, bus, log, options = {})
         (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);
@@ -1483,7 +1489,10 @@ function mountIslands(spec, registry, findSlot, context, bus, log, options = {})
       continue;
     }
     const c = build(entry);
-    if (c !== void 0) out.push(c);
+    if (c !== void 0) {
+      out.push(c);
+      options.onMount?.(c, island, el);
+    }
   }
   return out;
 }
@@ -1491,6 +1500,48 @@ function message(err) {
   return err instanceof Error ? err.message : String(err);
 }
 
+// src/page/overlay.ts
+var STYLE_ID = "island-overlay-style";
+var 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; }
+`;
+var IslandOverlay = class {
+  constructor(doc = document, now = () => performance.now()) {
+    this.doc = doc;
+    this.now = 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, el) {
+    this.label(island, el, "waiting", "waiting");
+  }
+  /** The island has just mounted. */
+  mounted(island, el) {
+    this.label(island, el, "mounted", `mounted ${Math.round(this.now())} ms`);
+  }
+  /** The island won't mount, for `reason`. */
+  failed(island, el, reason) {
+    this.label(island, el, "failed", reason);
+  }
+  label(island, el, state, text) {
+    el.dataset.islandState = state;
+    el.dataset.islandDebug = [island.name, island.slot, island.load || "eager", text].join(" \xB7 ");
+  }
+};
+
 // src/page/spec.ts
 var SPEC_ELEMENT_ID = "page-spec";
 var SLOT = /^[a-z][a-z0-9-]*$/;
@@ -1543,10 +1594,18 @@ var IslandPage = class extends BasePage {
       console.warn(`page spec: no readable #${SPEC_ELEMENT_ID} on this page, so nothing is mounted`);
       return [];
     }
+    const findSlot = (slot) => document.querySelector(`[data-slot="${slot}"]`);
+    const overlay = this.showIslandOverlay() ? new IslandOverlay() : void 0;
+    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(`[data-slot="${slot}"]`),
+      findSlot,
       () => this.makeContext(spec),
       this.eventBus,
       (message2) => console.warn(message2),
@@ -1554,10 +1613,23 @@ var IslandPage = class extends BasePage {
         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)}`));
-        }
+        },
+        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.
+   */
+  showIslandOverlay() {
+    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.
@@ -1913,6 +1985,7 @@ exports.BaseComponent = BaseComponent;
 exports.BasePage = BasePage;
 exports.ComponentEventTypes = ComponentEventTypes;
 exports.EventBus = EventBus;
+exports.IslandOverlay = IslandOverlay;
 exports.IslandPage = IslandPage;
 exports.KeyboardShortcutManager = KeyboardShortcutManager;
 exports.KeyboardState = KeyboardState;