@panyam/tsappkit 0.0.5 → 0.1.1

package/dist/index.d.mts

@@ -760,6 +760,93 @@ declare class MobileBottomDrawer extends BaseComponent implements LCMComponent {
     getContentContainer(): HTMLElement;
 }
 
+/**
+ * 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. */
+declare const SPEC_ELEMENT_ID = "page-spec";
+/** One island: `name` picks its factory, `slot` the element it mounts in (`[data-slot]`). */
+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>;
+}
+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.
+ */
+type SpecExtension<Ext> = (raw: Record<string, unknown>) => Ext;
+/**
+ * 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.
+ */
+declare function readSpec(text: string | null | undefined): PageSpec | null;
+declare function readSpec<Ext extends object>(text: string | null | undefined, extend: SpecExtension<Ext>): (PageSpec & Ext) | null;
+
+/**
+ * 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.
+ */
+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. */
+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.
+ */
+declare 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[];
+
+/**
+ * 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.
+ */
+declare 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;
+    protected initializeSpecificComponents(): LCMComponent[];
+}
+
 /**
  * Common DOM utility functions for consistent behavior across components
  */
@@ -863,4 +950,4 @@ declare class KeyboardShortcutManager {
     getCurrentArgs(): string;
 }
 
-export { BaseComponent, BasePage, type Component, type ComponentEventType, ComponentEventTypes, type ComponentLifecycleEvent, EventBus, type EventHandler, type EventSubscriber, KeyboardShortcutManager, KeyboardState, type LCMComponent, type LCMComponentConfig, type LCMComponentEvent, LifecycleController, type LifecycleEventType, LifecycleEventTypes, MobileBottomDrawer, Modal, type ShortcutConfig, type ShortcutManagerConfig, SplashScreen, TemplateLoader, ThemeManager, ToastManager, hasModifierKeys, isInInputContext, shouldIgnoreShortcut };
+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, LifecycleController, type LifecycleEventType, LifecycleEventTypes, MobileBottomDrawer, Modal, type PageSpec, type Registry, SPEC_ELEMENT_ID, type ShortcutConfig, type ShortcutManagerConfig, type SpecExtension, SplashScreen, TemplateLoader, ThemeManager, ToastManager, hasModifierKeys, isInInputContext, mountIslands, readSpec, shouldIgnoreShortcut };

package/dist/index.d.ts

@@ -760,6 +760,93 @@ declare class MobileBottomDrawer extends BaseComponent implements LCMComponent {
     getContentContainer(): HTMLElement;
 }
 
+/**
+ * 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. */
+declare const SPEC_ELEMENT_ID = "page-spec";
+/** One island: `name` picks its factory, `slot` the element it mounts in (`[data-slot]`). */
+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>;
+}
+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.
+ */
+type SpecExtension<Ext> = (raw: Record<string, unknown>) => Ext;
+/**
+ * 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.
+ */
+declare function readSpec(text: string | null | undefined): PageSpec | null;
+declare function readSpec<Ext extends object>(text: string | null | undefined, extend: SpecExtension<Ext>): (PageSpec & Ext) | null;
+
+/**
+ * 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.
+ */
+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. */
+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.
+ */
+declare 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[];
+
+/**
+ * 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.
+ */
+declare 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;
+    protected initializeSpecificComponents(): LCMComponent[];
+}
+
 /**
  * Common DOM utility functions for consistent behavior across components
  */
@@ -863,4 +950,4 @@ declare class KeyboardShortcutManager {
     getCurrentArgs(): string;
 }
 
-export { BaseComponent, BasePage, type Component, type ComponentEventType, ComponentEventTypes, type ComponentLifecycleEvent, EventBus, type EventHandler, type EventSubscriber, KeyboardShortcutManager, KeyboardState, type LCMComponent, type LCMComponentConfig, type LCMComponentEvent, LifecycleController, type LifecycleEventType, LifecycleEventTypes, MobileBottomDrawer, Modal, type ShortcutConfig, type ShortcutManagerConfig, SplashScreen, TemplateLoader, ThemeManager, ToastManager, hasModifierKeys, isInInputContext, shouldIgnoreShortcut };
+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, LifecycleController, type LifecycleEventType, LifecycleEventTypes, MobileBottomDrawer, Modal, type PageSpec, type Registry, SPEC_ELEMENT_ID, type ShortcutConfig, type ShortcutManagerConfig, type SpecExtension, SplashScreen, TemplateLoader, ThemeManager, ToastManager, hasModifierKeys, isInInputContext, mountIslands, readSpec, shouldIgnoreShortcut };

package/dist/index.js

@@ -1373,6 +1373,93 @@ var MobileBottomDrawer = class extends BaseComponent {
   }
 };
 
+// src/page/mount.ts
+function mountIslands(spec, registry, findSlot, context, bus, log) {
+  const out = [];
+  let ctx;
+  for (const island of spec.islands) {
+    const factory = Object.prototype.hasOwnProperty.call(registry, island.name) ? registry[island.name] : void 0;
+    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 ?? (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;
+}
+
+// src/page/spec.ts
+var SPEC_ELEMENT_ID = "page-spec";
+var SLOT = /^[a-z][a-z0-9-]*$/;
+function readSpec(text, extend) {
+  if (!text) return null;
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!isObject(raw) || typeof raw.layout !== "string" || !Array.isArray(raw.islands)) return null;
+  const islands = [];
+  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 = { layout: raw.layout, islands };
+  if (!extend) return spec;
+  let ext;
+  try {
+    ext = extend(raw);
+  } catch {
+    return null;
+  }
+  return { ...ext, ...spec };
+}
+function isObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+// src/page/IslandPage.ts
+var IslandPage = class extends BasePage {
+  /**
+   * The app's own fields from the parsed spec. The default reads none.
+   * Throwing makes the spec unreadable, so nothing mounts.
+   */
+  readExtension(raw) {
+    return {};
+  }
+  initializeSpecificComponents() {
+    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(`[data-slot="${slot}"]`),
+      () => this.makeContext(spec),
+      this.eventBus,
+      (message) => console.warn(message)
+    );
+  }
+};
+
 // src/DOMUtils.ts
 function isInInputContext(element) {
   if (!element) return false;
@@ -1719,18 +1806,22 @@ exports.BaseComponent = BaseComponent;
 exports.BasePage = BasePage;
 exports.ComponentEventTypes = ComponentEventTypes;
 exports.EventBus = EventBus;
+exports.IslandPage = IslandPage;
 exports.KeyboardShortcutManager = KeyboardShortcutManager;
 exports.KeyboardState = KeyboardState;
 exports.LifecycleController = LifecycleController;
 exports.LifecycleEventTypes = LifecycleEventTypes;
 exports.MobileBottomDrawer = MobileBottomDrawer;
 exports.Modal = Modal;
+exports.SPEC_ELEMENT_ID = SPEC_ELEMENT_ID;
 exports.SplashScreen = SplashScreen;
 exports.TemplateLoader = TemplateLoader;
 exports.ThemeManager = ThemeManager;
 exports.ToastManager = ToastManager;
 exports.hasModifierKeys = hasModifierKeys;
 exports.isInInputContext = isInInputContext;
+exports.mountIslands = mountIslands;
+exports.readSpec = readSpec;
 exports.shouldIgnoreShortcut = shouldIgnoreShortcut;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map