A web page
The page’s side
A web view reaches the program through the bridge of §9.4, which @pencere/sdk/page is, as
functions: a browser ES module with no dependency that does nothing until it is used.
import { call, close, onContext, openLink, subscribe } from "@pencere/sdk/page";
onContext((context) => document.documentElement.setAttribute("data-theme", context.mode));
const { containers } = await call("list");
const abort = new AbortController();
await call(
"pull",
{ image: "nginx" },
{
onProgress: ({ done, total, note }) => draw(done, total, note),
signal: abort.signal, // aborting sends `cancel`, and the promise rejects
},
);
const stop = subscribe(
"stats",
{ every: 1000 },
{
onPush: (value) => draw(value),
onError: (error) => console.warn(`the readings stopped: ${error.message}`),
onEnd: () => hideSpinner(), // whoever ended it: the program, or `stop()`
},
);
stop(); // or stop.cancel()
call(method, params?, { onProgress?, signal? })resolves with the result, or rejects with aCallError(code, andmessage, which is the code when the program gave no words). A page that nothing embeds has no host: its calls are rejected with the codeno-host.subscribe(topic, params, handlers)takes a function in place ofhandlerswhen only the values matter. The program ends a subscription with an error, whichonErrorhears; no push follows. The page ends it with the function that is returned (also calledcancel).onContext(listener)calls the listener with the terminal’s context now, when the page has it, and on each change: the mode, the roles of the theme, the font, the size, the locale and the time zone,reduceMotionand what the person allowed (§9.5).context()is the last one.close()asks the host to close the view; the program is told, and decides.openLink(url)asks it to open anhttp:orhttps:link in the person’s browser.createBridge(channel)is the same on a channel of your own, for a host that embeds the page in some other way, or for a test.
A page has no node_modules, so the module goes in the bundle beside the page, and an import map
in the page’s HTML says where the name is. bundleFromDirectory takes the file with its files
option:
const bridge = readFileSync(new URL(import.meta.resolve("@pencere/sdk/page")));
const bundle = await bundleFromDirectory(new URL("./view/", import.meta.url), {
files: [{ path: "pencere-page.js", data: bridge }],
});
<script type="importmap">
{ "imports": { "@pencere/sdk/page": "./pencere-page.js" } }
</script>
<script type="module" src="app.js"></script>
A page that is built with a bundler imports the module like any other, and needs none of this.
This page is a part of sdk/typescript/README.md of the repository.