@skillcdn/console 0.4.0 → 0.4.2

package/src/plugin/web.ts

@@ -0,0 +1,403 @@
+// The frame's side of the bridge (docs/specs/plugins.md, "The bridge"): what a plugin's page
+// bundles to speak to the console's page. It depends on nothing, speaks to the origin the frame
+// document names alone, performs its plugin's own calls and nothing else, applies the console's
+// tokens to the document, and says its height. A framework is the plugin's choice; this is below
+// any.
+import {
+  BRIDGE_METHODS,
+  type BridgeCommandResult,
+  type BridgeError,
+  type BridgeEventKind,
+  type BridgeFile,
+  type BridgeInit,
+  type BridgeMethod,
+  type BridgeToPage,
+  isBridgePath,
+  isBridgeToFrame,
+  MAX_BRIDGE_TITLE_LENGTH,
+  PLUGIN_BRIDGE_VERSION,
+} from "./bridge.js";
+import type { PluginRecord, RecordPage, RecordVersion } from "./context.js";
+
+/** What the console told the frame: who looks, at what, in which words. */
+export type PluginFrameContext = Omit<BridgeInit, "v" | "t">;
+
+/** A refusal from the console, with its stable code, as the page relayed it. */
+export class PluginBridgeError extends Error {
+  readonly code: string;
+  readonly data: unknown;
+
+  constructor(error: BridgeError) {
+    super(error.message);
+    this.name = "PluginBridgeError";
+    this.code = error.code;
+    this.data = error.data;
+  }
+}
+
+export interface FrameMessageEvent {
+  readonly data: unknown;
+  readonly origin: string;
+  readonly source: unknown;
+}
+
+/** As much of `window` as the bridge uses; a test hands one of its own. */
+export interface FrameWindow {
+  readonly parent: {
+    postMessage(message: unknown, targetOrigin: string, transfer?: Transferable[]): void;
+  };
+  addEventListener(type: "message", listener: (event: FrameMessageEvent) => void): void;
+  removeEventListener(type: "message", listener: (event: FrameMessageEvent) => void): void;
+}
+
+/** As much of `document` as the bridge uses. */
+export interface FrameDocument {
+  readonly documentElement: {
+    readonly dataset: Readonly<Record<string, string | undefined>>;
+    readonly style: { setProperty(name: string, value: string): void };
+    lang: string;
+  };
+  readonly body: { readonly scrollHeight: number } | null;
+  title: string;
+}
+
+export interface ConnectOptions {
+  readonly window?: FrameWindow;
+  readonly document?: FrameDocument;
+  /** How long to wait for the console's `init`; ten seconds unless said. */
+  readonly timeoutMs?: number;
+  /** Whether the frame says its height as it changes; on unless said otherwise. */
+  readonly resize?: boolean;
+}
+
+export interface FrameRecordsQuery {
+  readonly where?: Readonly<Record<string, unknown>>;
+  /** A field of the collection's indexes, `-` before it for descending. */
+  readonly order?: string;
+  readonly limit?: number;
+  readonly after?: string;
+  readonly q?: string;
+  readonly project?: string;
+}
+
+/** The frame's connection to the console's page. */
+export interface PluginFrame {
+  readonly context: PluginFrameContext;
+  /** A call as the bridge carries one; the typed methods below are the usual way. */
+  call(method: BridgeMethod, params: Readonly<Record<string, unknown>>): Promise<unknown>;
+  command(name: string, args?: Readonly<Record<string, unknown>>): Promise<BridgeCommandResult>;
+  query(name: string, args?: Readonly<Record<string, unknown>>): Promise<unknown>;
+  readonly records: {
+    list<T = Record<string, unknown>>(
+      collection: string,
+      query?: FrameRecordsQuery,
+    ): Promise<RecordPage<T>>;
+    get<T = Record<string, unknown>>(
+      collection: string,
+      id: string,
+      version?: number,
+    ): Promise<PluginRecord<T>>;
+    versions<T = Record<string, unknown>>(
+      collection: string,
+      id: string,
+    ): Promise<readonly RecordVersion<T>[]>;
+  };
+  readonly files: {
+    get(id: string): Promise<BridgeFile>;
+    /** Uploads bytes for a command; answers the handle, good for an hour. */
+    put(
+      bytes: ArrayBuffer | Uint8Array,
+      name: string,
+      type: string,
+    ): Promise<{ readonly handle: string }>;
+  };
+  /** The console's page follows a path of the console's in place; a URL is refused. */
+  navigate(path: string): void;
+  /** The console's page downloads a file of this plugin. */
+  download(id: string): void;
+  setTitle(text: string): void;
+  /** Something of this plugin changed; subscribes to the kinds named. The function returned stops listening. */
+  onEvent(
+    kinds: readonly BridgeEventKind[],
+    handler: (kind: BridgeEventKind, data: unknown) => void,
+  ): () => void;
+  /** The console's look changed; the tokens are applied before the handler runs. */
+  onTheme(handler: (theme: Readonly<Record<string, string>>) => void): () => void;
+  /** The console navigated within this page's address. */
+  onPath(handler: (path: string) => void): () => void;
+  /** Stops listening to the console's page. */
+  close(): void;
+}
+
+const DEFAULT_CONNECT_MS = 10_000;
+
+function globalWindow(): FrameWindow {
+  const candidate = (globalThis as { window?: FrameWindow }).window;
+  if (candidate === undefined) {
+    throw new PluginBridgeError({
+      code: "plugin.no_window",
+      message: "connect() runs in a plugin's frame, where window is",
+    });
+  }
+  return candidate;
+}
+
+function globalDocument(): FrameDocument {
+  const candidate = (globalThis as { document?: FrameDocument }).document;
+  if (candidate === undefined) {
+    throw new PluginBridgeError({
+      code: "plugin.no_window",
+      message: "connect() runs in a plugin's frame, where document is",
+    });
+  }
+  return candidate;
+}
+
+/** Sets the console's tokens on the document's root, `--sc-*` and nothing else. */
+export function applyTheme(document: FrameDocument, theme: Readonly<Record<string, string>>): void {
+  for (const [token, value] of Object.entries(theme)) {
+    if (token.startsWith("--sc-")) {
+      document.documentElement.style.setProperty(token, value);
+    }
+  }
+}
+
+function startHeightWatch(document: FrameDocument, post: (height: number) => void): () => void {
+  const body = document.body;
+  if (body === null) {
+    return () => {};
+  }
+  let last = -1;
+  const say = () => {
+    const height = Math.ceil(body.scrollHeight);
+    if (height !== last) {
+      last = height;
+      post(height);
+    }
+  };
+  say();
+  const observerClass = (
+    globalThis as {
+      ResizeObserver?: new (
+        callback: () => void,
+      ) => { observe(target: unknown): void; disconnect(): void };
+    }
+  ).ResizeObserver;
+  const elementClass = (globalThis as { Element?: abstract new () => unknown }).Element;
+  if (observerClass !== undefined && elementClass !== undefined && body instanceof elementClass) {
+    const observer = new observerClass(say);
+    observer.observe(body);
+    return () => observer.disconnect();
+  }
+  const timer = setInterval(say, 500);
+  return () => clearInterval(timer);
+}
+
+/**
+ * Connects the frame to the console's page: says `ready`, waits for `init`, applies the tokens,
+ * and answers the connection. Call it once, when the bundle starts.
+ */
+export function connect(options: ConnectOptions = {}): Promise<PluginFrame> {
+  const win = options.window ?? globalWindow();
+  const doc = options.document ?? globalDocument();
+  const origin = doc.documentElement.dataset.console;
+  if (origin === undefined || origin.length === 0) {
+    return Promise.reject(
+      new PluginBridgeError({
+        code: "plugin.no_console",
+        message: "the document names no console in data-console; this is not a plugin's frame",
+      }),
+    );
+  }
+  const post = (message: BridgeToPage, transfer?: Transferable[]) => {
+    win.parent.postMessage(message, origin, transfer);
+  };
+  const pending = new Map<
+    string,
+    { resolve: (value: unknown) => void; reject: (error: Error) => void }
+  >();
+  const eventHandlers = new Set<(kind: BridgeEventKind, data: unknown) => void>();
+  const themeHandlers = new Set<(theme: Readonly<Record<string, string>>) => void>();
+  const pathHandlers = new Set<(path: string) => void>();
+  const subscribed = new Set<BridgeEventKind>();
+  let counter = 0;
+  let stopHeight: (() => void) | undefined;
+
+  return new Promise<PluginFrame>((resolveConnect, rejectConnect) => {
+    let connected = false;
+    const timer = setTimeout(() => {
+      if (!connected) {
+        win.removeEventListener("message", listener);
+        rejectConnect(
+          new PluginBridgeError({
+            code: "plugin.no_init",
+            message: `the console's page did not answer within ${options.timeoutMs ?? DEFAULT_CONNECT_MS} ms`,
+          }),
+        );
+      }
+    }, options.timeoutMs ?? DEFAULT_CONNECT_MS);
+
+    const call = (
+      method: BridgeMethod,
+      params: Readonly<Record<string, unknown>>,
+      transfer?: Transferable[],
+    ): Promise<unknown> => {
+      if (!(BRIDGE_METHODS as readonly string[]).includes(method)) {
+        return Promise.reject(
+          new PluginBridgeError({
+            code: "plugin.forbidden",
+            message: `${method} is not a method of the bridge`,
+          }),
+        );
+      }
+      counter += 1;
+      const id = String(counter);
+      return new Promise((resolve, reject) => {
+        pending.set(id, { resolve, reject });
+        post({ v: PLUGIN_BRIDGE_VERSION, t: "call", id, method, params }, transfer);
+      });
+    };
+
+    const listener = (event: FrameMessageEvent) => {
+      if (event.source !== win.parent || event.origin !== origin || !isBridgeToFrame(event.data)) {
+        return;
+      }
+      const message = event.data;
+      switch (message.t) {
+        case "init": {
+          if (connected) {
+            return;
+          }
+          connected = true;
+          clearTimeout(timer);
+          applyTheme(doc, message.theme);
+          doc.documentElement.lang = message.language;
+          const { v: _v, t: _t, ...context } = message;
+          const frame: PluginFrame = {
+            context,
+            call: (method, params) => call(method, params),
+            command: (name, args = {}) =>
+              call("command", { name, args }) as Promise<BridgeCommandResult>,
+            query: (name, args = {}) => call("query", { name, args }),
+            records: {
+              list: <T>(collection: string, query: FrameRecordsQuery = {}) =>
+                call("records.list", { collection, ...query }) as Promise<RecordPage<T>>,
+              get: <T>(collection: string, id: string, version?: number) =>
+                call(
+                  "records.get",
+                  version === undefined ? { collection, id } : { collection, id, version },
+                ) as Promise<PluginRecord<T>>,
+              versions: <T>(collection: string, id: string) =>
+                call("records.versions", { collection, id }) as Promise<
+                  readonly RecordVersion<T>[]
+                >,
+            },
+            files: {
+              get: (id) => call("files.get", { id }) as Promise<BridgeFile>,
+              put: (bytes, name, type) => {
+                const buffer = bytes instanceof Uint8Array ? bytes.slice().buffer : bytes;
+                return call("files.put", { bytes: buffer, name, type }, [buffer]) as Promise<{
+                  handle: string;
+                }>;
+              },
+            },
+            navigate: (path) => {
+              if (!isBridgePath(path)) {
+                throw new PluginBridgeError({
+                  code: "plugin.forbidden",
+                  message: "navigate takes a path of the console's, never a URL",
+                });
+              }
+              post({ v: PLUGIN_BRIDGE_VERSION, t: "navigate", path });
+            },
+            download: (id) => post({ v: PLUGIN_BRIDGE_VERSION, t: "download", id }),
+            setTitle: (text) => {
+              const title = text.slice(0, MAX_BRIDGE_TITLE_LENGTH).replace(/[\r\n]+/g, " ");
+              doc.title = title;
+              post({ v: PLUGIN_BRIDGE_VERSION, t: "title", text: title });
+            },
+            onEvent: (kinds, handler) => {
+              eventHandlers.add(handler);
+              let added = false;
+              for (const kind of kinds) {
+                if (!subscribed.has(kind)) {
+                  subscribed.add(kind);
+                  added = true;
+                }
+              }
+              if (added) {
+                post({ v: PLUGIN_BRIDGE_VERSION, t: "subscribe", kinds: [...subscribed] });
+              }
+              return () => eventHandlers.delete(handler);
+            },
+            onTheme: (handler) => {
+              themeHandlers.add(handler);
+              return () => themeHandlers.delete(handler);
+            },
+            onPath: (handler) => {
+              pathHandlers.add(handler);
+              return () => pathHandlers.delete(handler);
+            },
+            close: () => {
+              win.removeEventListener("message", listener);
+              stopHeight?.();
+              for (const { reject } of pending.values()) {
+                reject(
+                  new PluginBridgeError({
+                    code: "plugin.closed",
+                    message: "the frame closed its connection",
+                  }),
+                );
+              }
+              pending.clear();
+            },
+          };
+          if (options.resize !== false) {
+            stopHeight = startHeightWatch(doc, (height) =>
+              post({ v: PLUGIN_BRIDGE_VERSION, t: "resize", height }),
+            );
+          }
+          resolveConnect(frame);
+          return;
+        }
+        case "result": {
+          const waiting = pending.get(message.id);
+          if (waiting === undefined) {
+            return;
+          }
+          pending.delete(message.id);
+          if (message.ok) {
+            waiting.resolve(message.value);
+          } else {
+            waiting.reject(
+              new PluginBridgeError(
+                message.error ?? { code: "plugin.failed", message: "the call failed" },
+              ),
+            );
+          }
+          return;
+        }
+        case "event":
+          for (const handler of eventHandlers) {
+            handler(message.kind, message.data);
+          }
+          return;
+        case "theme":
+          applyTheme(doc, message.theme);
+          for (const handler of themeHandlers) {
+            handler(message.theme);
+          }
+          return;
+        case "path":
+          for (const handler of pathHandlers) {
+            handler(message.path);
+          }
+          return;
+        default:
+          return;
+      }
+    };
+    win.addEventListener("message", listener);
+    post({ v: PLUGIN_BRIDGE_VERSION, t: "ready" });
+  });
+}

package/src/plugin-nav.ts

@@ -0,0 +1,132 @@
+import type { NavItem } from "./components/shell.js";
+import type { Messages } from "./i18n/en.js";
+import { pluginHref } from "./router.js";
+import type { RestPlugin, RestRulesPlugin } from "./schemas.js";
+
+// The tabs of the plugins (ADR-0054, docs/specs/plugins.md, "Tabs, sub-tabs and addresses"):
+// after the console's own tabs, the groups that hold a plugin the person has a role in. A group
+// with one plugin is a tab with the plugin's name; one with several is a tab with the group's
+// name that opens the list of them. Groups and plugins are ordered by `menu.order`, then by key.
+// Pure: what the tabs are, from what the console was told, for the composition and its tests.
+
+/** A text in the person's language, else in English, else the first the manifest has. */
+export function pluginWordOf(
+  texts: Readonly<Record<string, string>> | null | undefined,
+  language: string,
+): string {
+  if (texts === null || texts === undefined) {
+    return "";
+  }
+  return (
+    texts[language] ??
+    texts[language.split("-")[0] ?? language] ??
+    texts.en ??
+    Object.values(texts)[0] ??
+    ""
+  );
+}
+
+/** The pages of a plugin at a level, in the manifest's order: what the person may see of them. */
+export function pluginPagesAt(
+  plugin: RestPlugin,
+  level: "workspace" | "project",
+): RestPlugin["pages"] {
+  return plugin.pages.filter((page) => page.level === level);
+}
+
+/** Where a plugin's tab leads: its first page at the level. */
+function firstPageHref(
+  plugin: RestPlugin,
+  level: "workspace" | "project",
+  project: string | undefined,
+): string | undefined {
+  const [first] = pluginPagesAt(plugin, level);
+  return first === undefined ? undefined : pluginHref(plugin.key, first.key, project);
+}
+
+/** What the current address names, for the tabs to say which is current. */
+export interface PluginRouteFacts {
+  readonly plugin: string | undefined;
+}
+
+/**
+ * The tabs of the plugins at a level: on the workspace, every enabled plugin with a page there the
+ * person may see; on a project, those bound to it (as the project's rules name them) with a
+ * project page. Grouped by `menu.group`, named in the person's language.
+ */
+export function pluginNavItems(input: {
+  readonly plugins: readonly RestPlugin[];
+  readonly level: "workspace" | "project";
+  /** The project the tabs are on, with the plugins bound to it; nothing on the workspace. */
+  readonly project?:
+    | { readonly key: string; readonly plugins: readonly RestRulesPlugin[] }
+    | undefined;
+  readonly current: PluginRouteFacts;
+  readonly words: Messages;
+  readonly language: string;
+}): NavItem[] {
+  const { plugins, level, project, current, words, language } = input;
+  const bound = project === undefined ? undefined : new Set(project.plugins.map((p) => p.key));
+  const shown = plugins
+    .filter((plugin) => plugin.state === "enabled")
+    .filter((plugin) => bound === undefined || bound.has(plugin.key))
+    .filter((plugin) => pluginPagesAt(plugin, level).length > 0);
+  const groups = new Map<string, { order: number; name: string; plugins: RestPlugin[] }>();
+  for (const plugin of shown) {
+    const group = plugin.menu?.group ?? "operations";
+    const known = words.nav.pluginGroups[group];
+    const name =
+      known ??
+      (plugin.menu?.name === null || plugin.menu?.name === undefined
+        ? group
+        : pluginWordOf(plugin.menu.name, language));
+    const order = plugin.menu?.order ?? 100;
+    const held = groups.get(group);
+    if (held === undefined) {
+      groups.set(group, { order, name, plugins: [plugin] });
+    } else {
+      held.plugins.push(plugin);
+      held.order = Math.min(held.order, order);
+    }
+  }
+  const byOrder = (a: { order: number; key: string }, b: { order: number; key: string }) =>
+    a.order - b.order || a.key.localeCompare(b.key);
+  return [...groups.entries()]
+    .map(([key, group]) => ({ key, ...group }))
+    .sort(byOrder)
+    .flatMap((group) => {
+      const members = [...group.plugins].sort((a, b) =>
+        byOrder(
+          { order: a.menu?.order ?? 100, key: a.key },
+          { order: b.menu?.order ?? 100, key: b.key },
+        ),
+      );
+      const items = members.flatMap((plugin): NavItem[] => {
+        const href = firstPageHref(plugin, level, project?.key);
+        return href === undefined
+          ? []
+          : [
+              {
+                href,
+                label: pluginWordOf(plugin.name, language),
+                current: current.plugin === plugin.key,
+              },
+            ];
+      });
+      if (items.length === 0) {
+        return [];
+      }
+      if (items.length === 1) {
+        return items;
+      }
+      const first = items[0] as NavItem;
+      return [
+        {
+          href: first.href,
+          label: group.name,
+          current: items.some((item) => item.current),
+          children: items,
+        },
+      ];
+    });
+}

package/src/plugin-testing.ts

@@ -0,0 +1,10 @@
+// A context for a plugin's own tests: records in memory, the console refusing what the test did
+// not provide, everything emitted and logged kept for assertions.
+
+export {
+  createTestContext,
+  type LoggedLine,
+  type TestConsoleOptions,
+  type TestContext,
+  type TestContextOptions,
+} from "./plugin/testing.js";

package/src/plugin-web-react.ts

@@ -0,0 +1,4 @@
+// The bridge as a React hook, for a plugin that chooses React: `usePlugin()`.
+
+export type { PluginFrame, PluginFrameContext } from "./plugin/web.js";
+export { sharedConnection, type UsePlugin, usePlugin } from "./plugin/web-react.js";

package/src/plugin-web.ts

@@ -0,0 +1,35 @@
+// The frame's side of the bridge (docs/specs/plugins.md, "The bridge"), for a plugin's web bundle:
+// `connect()` and the messages. Depends on nothing; runs in a browser.
+
+export {
+  BRIDGE_EVENT_KINDS,
+  BRIDGE_METHODS,
+  type BridgeCommandResult,
+  type BridgeError,
+  type BridgeEventKind,
+  type BridgeFile,
+  type BridgeInit,
+  type BridgeMethod,
+  type BridgePerson,
+  type BridgeToFrame,
+  type BridgeToPage,
+  isBridgePath,
+  isBridgeToFrame,
+  isBridgeToPage,
+  MAX_BRIDGE_PATH_LENGTH,
+  MAX_BRIDGE_TITLE_LENGTH,
+  PLUGIN_BRIDGE_VERSION,
+} from "./plugin/bridge.js";
+export type { LinkTarget, PluginRecord, RecordPage, RecordVersion } from "./plugin/context.js";
+export {
+  applyTheme,
+  type ConnectOptions,
+  connect,
+  type FrameDocument,
+  type FrameMessageEvent,
+  type FrameRecordsQuery,
+  type FrameWindow,
+  PluginBridgeError,
+  type PluginFrame,
+  type PluginFrameContext,
+} from "./plugin/web.js";