@panyam/tsappkit 0.0.5 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panyam/tsappkit",
-  "version": "0.0.5",
+  "version": "0.1.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",
@@ -22,6 +22,7 @@
   "files": [
     "dist",
     "src",
+    "!src/**/*.test.ts",
     "styles"
   ],
   "scripts": {
@@ -30,7 +31,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 +47,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.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.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.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);
+}