@panyam/tsappkit 0.0.5 → 0.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panyam/tsappkit",
-  "version": "0.0.5",
+  "version": "0.1.0",
   "description": "TypeScript application toolkit with component lifecycle management, event system, UI utilities, and documentation site components",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -30,7 +30,9 @@
     "dev": "tsup --watch",
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run build",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "keywords": [
     "typescript",
@@ -44,10 +46,13 @@
   "author": "panyam",
   "license": "MIT",
   "devDependencies": {
+    "@types/node": "^22.20.5",
     "ace-builds": "^1.43.0",
+    "jsdom": "^29.1.1",
     "sass": "^1.77.0",
     "tsup": "^8.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.11"
   },
   "peerDependencies": {
     "ace-builds": "^1.0.0"

package/src/index.ts

@@ -27,6 +27,13 @@ export { TemplateLoader } from './TemplateLoader';
 export { SplashScreen } from './SplashScreen';
 export { MobileBottomDrawer } from './MobileBottomDrawer';
 
+// Island pages (islands mounted from a server-written page spec)
+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';
+
 // Utilities
 export { isInInputContext, hasModifierKeys, shouldIgnoreShortcut } from './DOMUtils';
 export {

package/src/page/IslandPage.test.ts

@@ -0,0 +1,83 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { LCMComponent } from "../LCMComponent";
+import { IslandPage } from "./IslandPage";
+import type { PageSpec } from "./spec";
+
+type Ctx = { built: number };
+type Ext = { things: string[] };
+
+const mounted: { name: string; el: HTMLElement; config: unknown; ctx: Ctx }[] = [];
+const contexts: (PageSpec & Ext)[] = [];
+
+const island = (name: string) => (el: HTMLElement, spec: { config: unknown }, ctx: Ctx) => {
+  mounted.push({ name, el, config: spec.config, ctx });
+  return { name } as unknown as LCMComponent;
+};
+
+class TestPage extends IslandPage<Ctx, Ext> {
+  protected registry() {
+    return { player: island("player"), chat: island("chat") };
+  }
+  protected readExtension(raw: Record<string, unknown>): Ext {
+    return { things: Array.isArray(raw.things) ? raw.things.map(String) : [] };
+  }
+  protected makeContext(spec: PageSpec & Ext): Ctx {
+    contexts.push(spec);
+    return { built: contexts.length };
+  }
+  mount() {
+    return this.initializeSpecificComponents();
+  }
+}
+
+function page(spec: string | null, slots: string[]) {
+  document.body.innerHTML =
+    (spec === null ? "" : `<script type="application/json" id="page-spec">${spec}</script>`) +
+    slots.map((s) => `<section data-slot="${s}"></section>`).join("");
+  return new TestPage("test");
+}
+
+describe("IslandPage", () => {
+  let warn: ReturnType<typeof vi.spyOn>;
+  beforeEach(() => {
+    // jsdom has no matchMedia, and BasePage's ThemeManager asks it for the colour scheme.
+    window.matchMedia ??= ((query: string) => ({ matches: false, media: query, addEventListener() {}, removeEventListener() {} })) as unknown as typeof window.matchMedia;
+    mounted.length = 0;
+    contexts.length = 0;
+    warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+  afterEach(() => warn.mockRestore());
+
+  it("mounts each island from the spec into its data-slot, sharing one context", () => {
+    const spec = JSON.stringify({
+      layout: "drawer",
+      islands: [
+        { name: "player", slot: "main", config: { a: 1 } },
+        { name: "nobody", slot: "side" },
+        { name: "chat", slot: "drawer" },
+      ],
+      things: ["x"],
+    });
+    const out = page(spec, ["main", "side", "drawer"]).mount();
+    expect(out).toHaveLength(2);
+    expect(mounted.map((m) => [m.name, m.el.dataset.slot, m.config])).toEqual([
+      ["player", "main", { a: 1 }],
+      ["chat", "drawer", {}],
+    ]);
+    expect(mounted[0].ctx).toBe(mounted[1].ctx);
+    expect(contexts).toHaveLength(1);
+    expect(contexts[0].things).toEqual(["x"]);
+    expect(warn.mock.calls.flat().join("\n")).toMatch(/nobody/);
+  });
+
+  it("mounts nothing, and builds no context, without a readable spec", () => {
+    for (const spec of [null, "not json"]) {
+      const p = page(spec, ["main"]);
+      warn.mockClear();
+      expect(p.mount()).toEqual([]);
+      expect(warn).toHaveBeenCalledOnce();
+      expect(String(warn.mock.calls[0][0])).toMatch(/page-spec/);
+    }
+    expect(contexts).toHaveLength(0);
+  });
+});

package/src/page/IslandPage.ts

@@ -0,0 +1,49 @@
+import { BasePage } from "../BasePage";
+import type { EventBus } from "../EventBus";
+import type { LCMComponent } from "../LCMComponent";
+import { mountIslands, type Registry } from "./mount";
+import { readSpec, SPEC_ELEMENT_ID, type PageSpec } from "./spec";
+
+/**
+ * A page whose islands come from the page spec. A subclass says which
+ * islands it can mount (`registry`) and builds the services they share
+ * (`makeContext`); the spec says which islands this page gets and where.
+ *
+ * `makeContext` is called once with the spec, before the first island
+ * mounts, and not at all on a page with no islands to mount. An app whose
+ * spec carries more than islands (its Go type embeds page.Spec) reads those
+ * fields in `readExtension`, and they arrive typed as `Ext` on the spec
+ * `makeContext` gets.
+ *
+ * A page with no readable `#page-spec` mounts nothing and warns. Subclasses
+ * that override initializeSpecificComponents call super and add to what it
+ * returns.
+ */
+export abstract class IslandPage<Ctx, Ext extends object = {}> extends BasePage {
+  protected abstract registry(): Registry<Ctx, HTMLElement, LCMComponent, EventBus>;
+  protected abstract makeContext(spec: PageSpec & Ext): Ctx;
+
+  /**
+   * The app's own fields from the parsed spec. The default reads none.
+   * Throwing makes the spec unreadable, so nothing mounts.
+   */
+  protected readExtension(raw: Record<string, unknown>): Ext {
+    return {} as Ext;
+  }
+
+  protected override initializeSpecificComponents(): LCMComponent[] {
+    const spec = readSpec(document.getElementById(SPEC_ELEMENT_ID)?.textContent, (raw) => this.readExtension(raw));
+    if (!spec) {
+      console.warn(`page spec: no readable #${SPEC_ELEMENT_ID} on this page, so nothing is mounted`);
+      return [];
+    }
+    return mountIslands(
+      spec,
+      this.registry(),
+      (slot) => document.querySelector<HTMLElement>(`[data-slot="${slot}"]`),
+      () => this.makeContext(spec),
+      this.eventBus,
+      (message) => console.warn(message),
+    );
+  }
+}

package/src/page/mount.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest";
+import { mountIslands, type Registry } from "./mount";
+import type { PageSpec } from "./spec";
+
+type El = { slot: string };
+const ctx = { tag: "ctx" };
+const bus = { tag: "bus" };
+
+const spec: PageSpec = {
+  layout: "drawer",
+  islands: [
+    { name: "player", slot: "main", presentation: "page", config: { a: 1 } },
+    { name: "unknown", slot: "side", config: {} },
+    { name: "chat", slot: "missing", config: {} },
+    { name: "chat", slot: "drawer", presentation: "drawer", config: {} },
+  ],
+};
+
+describe("mountIslands", () => {
+  it("mounts each island in its slot with its config and the page's context, in spec order", () => {
+    const calls: unknown[][] = [];
+    const registry: Registry<typeof ctx, El, string, typeof bus> = {
+      player: (el, island, c, b) => (calls.push([el, island, c, b]), "player-component"),
+      chat: (el, island) => (calls.push([el, island.presentation]), "chat-component"),
+    };
+    const logs: string[] = [];
+    const out = mountIslands(spec, registry, (slot) => (slot === "missing" ? null : { slot }), () => ctx, bus, (m) => logs.push(m));
+    expect(out).toEqual(["player-component", "chat-component"]);
+    expect(calls).toEqual([
+      [{ slot: "main" }, spec.islands[0], ctx, bus],
+      [{ slot: "drawer" }, "drawer"],
+    ]);
+    // The unknown island and the missing slot are logged and skipped.
+    expect(logs).toHaveLength(2);
+    expect(logs.join("\n")).toMatch(/unknown/);
+    expect(logs.join("\n")).toMatch(/missing/);
+  });
+
+  it("doesn't take an island name from the registry's prototype", () => {
+    const logs: string[] = [];
+    const out = mountIslands({ layout: "a", islands: [{ name: "toString", slot: "main", config: {} }] }, {}, (slot) => ({ slot }), () => ctx, bus, (m) => logs.push(m));
+    expect(out).toEqual([]);
+    expect(logs).toHaveLength(1);
+  });
+
+  it("carries on when a factory throws", () => {
+    const logs: string[] = [];
+    const out = mountIslands(
+      spec,
+      {
+        player: () => {
+          throw new Error("boom");
+        },
+        chat: () => "ok",
+      },
+      (slot) => ({ slot }),
+      () => ctx,
+      bus,
+      (m) => logs.push(m),
+    );
+    expect(out).toEqual(["ok", "ok"]);
+    expect(logs.some((m) => m.includes("boom"))).toBe(true);
+  });
+
+  it("builds the page's context once, and only when there's an island to mount", () => {
+    let built = 0;
+    const context = () => (built++, ctx);
+    mountIslands({ layout: "index", islands: [] }, {}, () => ({ slot: "" }), context, bus, () => {});
+    expect(built).toBe(0);
+    mountIslands(spec, { player: () => "a", chat: () => "b" }, (slot) => ({ slot }), context, bus, () => {});
+    expect(built).toBe(1);
+  });
+});

package/src/page/mount.ts

@@ -0,0 +1,54 @@
+import type { IslandSpec, PageSpec } from "./spec";
+
+/**
+ * Builds one island in `el`. `ctx` is the page's shared services, whatever
+ * the app says they are; `bus` is the page's event bus.
+ */
+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>>;
+
+/**
+ * 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.
+ *
+ * Plain types throughout (no DOM), so it runs under node in tests and on a
+ * bare page without BasePage.
+ */
+export function mountIslands<Ctx, El, C, B>(
+  spec: PageSpec,
+  registry: Registry<Ctx, El, C, B>,
+  findSlot: (slot: string) => El | null,
+  context: () => Ctx,
+  bus: B,
+  log: (message: string) => void,
+): 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) {
+      log(`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`);
+      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)}`);
+    }
+  }
+  return out;
+}

package/src/page/spec.test.ts

@@ -0,0 +1,65 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { readSpec } from "./spec";
+
+describe("readSpec", () => {
+  it("reads the spec goapplib's page.Spec writes (page/testdata/spec.json)", () => {
+    const text = readFileSync(join(__dirname, "../../../page/testdata/spec.json"), "utf8");
+    expect(readSpec(text)).toEqual({
+      layout: "drawer",
+      islands: [
+        { name: "player", slot: "main", presentation: "page", config: { note: "</script>", urls: ["/a.json"] } },
+        { name: "chat", slot: "side", config: {} },
+      ],
+    });
+  });
+
+  it("is null when there's no spec or it isn't one", () => {
+    for (const bad of [null, undefined, "", "not json", "null", "[]", '{"islands":[]}', '{"layout":"drawer"}', '{"layout":3,"islands":[]}']) {
+      expect(readSpec(bad), String(bad)).toBeNull();
+    }
+  });
+
+  it("drops islands it couldn't mount and cleans the rest", () => {
+    const spec = readSpec(
+      JSON.stringify({
+        layout: "drawer",
+        islands: [
+          { name: "player", slot: "main" },
+          { slot: "orphan" },
+          { name: "x", slot: 'main"] , body' },
+          { name: "chat", slot: "drawer", presentation: 7, config: "nope" },
+          "junk",
+        ],
+      }),
+    );
+    expect(spec).toEqual({
+      layout: "drawer",
+      islands: [
+        { name: "player", slot: "main", config: {} },
+        { name: "chat", slot: "drawer", config: {} },
+      ],
+    });
+  });
+
+  it("leaves an app's own fields out unless it reads them", () => {
+    expect(readSpec('{"layout":"a","islands":[],"things":[1]}')).toEqual({ layout: "a", islands: [] });
+  });
+
+  it("merges in what an extension reads, without letting it replace layout or islands", () => {
+    const text = JSON.stringify({ layout: "a", islands: [{ name: "p", slot: "main" }], things: [1, "x", 2] });
+    const spec = readSpec(text, (raw) => ({
+      things: Array.isArray(raw.things) ? raw.things.filter((t): t is number => typeof t === "number") : [],
+      layout: "overridden",
+    }));
+    expect(spec).toEqual({ layout: "a", islands: [{ name: "p", slot: "main", config: {} }], things: [1, 2] });
+  });
+
+  it("is null when the extension throws", () => {
+    const spec = readSpec('{"layout":"a","islands":[]}', () => {
+      throw new Error("bad things");
+    });
+    expect(spec).toBeNull();
+  });
+});

package/src/page/spec.ts

@@ -0,0 +1,79 @@
+/**
+ * The page spec: which islands a page mounts, where, and with what config.
+ * The server writes it into the page as JSON (goapplib's page.Spec, through
+ * templates/page/Islands.html); this reads it back.
+ */
+
+/** The id of the script element the server writes the spec into. */
+export const SPEC_ELEMENT_ID = "page-spec";
+
+/** One island: `name` picks its factory, `slot` the element it mounts in (`[data-slot]`). */
+export interface IslandSpec {
+  name: string;
+  slot: string;
+  /** How the layout shows it (the app's own words: "page", "panel", "drawer"), when it draws differently in each. */
+  presentation?: string;
+  /** Handed to the factory as is. Always an object. */
+  config: Record<string, unknown>;
+}
+
+export interface PageSpec {
+  /** The arrangement of slots, for state kept per layout. */
+  layout: string;
+  islands: IslandSpec[];
+}
+
+/**
+ * Reads an app's own fields from the parsed spec, the ones its Go type adds
+ * by embedding page.Spec. Gets the whole object; returns what the app wants
+ * kept, already checked.
+ */
+export type SpecExtension<Ext> = (raw: Record<string, unknown>) => Ext;
+
+// Slot names go into an attribute selector, so they must stay plain (as Go checks).
+const SLOT = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * The spec in `text`, or null when there is none or it isn't one. Islands
+ * without a name or with a slot name that isn't plain are dropped, and a
+ * config that isn't an object becomes {}, so what comes back can be mounted.
+ *
+ * `extend`, when given, reads the app's own fields; they're merged into the
+ * result, but `layout` and `islands` always come from this reading. If it
+ * throws, the spec is unreadable and the result is null.
+ */
+export function readSpec(text: string | null | undefined): PageSpec | null;
+export function readSpec<Ext extends object>(text: string | null | undefined, extend: SpecExtension<Ext>): (PageSpec & Ext) | null;
+export function readSpec<Ext extends object>(text: string | null | undefined, extend?: SpecExtension<Ext>): PageSpec | (PageSpec & Ext) | null {
+  if (!text) return null;
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!isObject(raw) || typeof raw.layout !== "string" || !Array.isArray(raw.islands)) return null;
+  const islands: IslandSpec[] = [];
+  for (const is of raw.islands) {
+    if (!isObject(is) || typeof is.name !== "string" || !is.name || typeof is.slot !== "string" || !SLOT.test(is.slot)) continue;
+    islands.push({
+      name: is.name,
+      slot: is.slot,
+      ...(typeof is.presentation === "string" && { presentation: is.presentation }),
+      config: isObject(is.config) ? is.config : {},
+    });
+  }
+  const spec: PageSpec = { layout: raw.layout, islands };
+  if (!extend) return spec;
+  let ext: Ext;
+  try {
+    ext = extend(raw);
+  } catch {
+    return null;
+  }
+  return { ...ext, ...spec };
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}