elowen-plugin-ui-kit 0.1.0

package/README.md

@@ -0,0 +1,27 @@
+# elowen-plugin-ui-kit
+
+Contract types and build toolchain for [Elowen](https://github.com/dragocz95/elowen) plugin browser
+UIs. A plugin ships ONE built same-origin ESM bundle; the Elowen web app loads it and hands it the
+host runtime on `window.ElowenUiRuntime` (React, curated UI components, an authenticated `api` fetch,
+SPA `navigate`). The bundle registers its pages and settings panels with
+`window.__elowenRegisterPluginUi(pluginName, registration)`.
+
+## Types
+
+`index.d.ts` is the single source of truth for the contract: `ElowenUiRuntime`,
+`PluginUiRegistration`, `PluginPageProps` and the `PLUGIN_UI_API_VERSION` constant. It also augments
+`Window`, so plugin sources typecheck against the real surface.
+
+## Building a bundle
+
+```js
+import { buildPluginUiBundle } from 'elowen-plugin-ui-kit/build';
+await buildPluginUiBundle({ entry: 'web-src/index.tsx', outfile: 'web/index.js' });
+```
+
+or from a script: `elowen-plugin-ui-build web-src/index.tsx web/index.js`.
+
+The build bundles everything into one ESM file and aliases `react`, `react-dom` and
+`react/jsx-runtime` imports to shims reading the HOST's instances from `window.ElowenUiRuntime` — a
+bundle can never ship a second React. Content-hashing of the output URL is the daemon's job; the
+build just emits the file the plugin manifest's `web.entry` points at.

package/bin.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { buildPluginUiBundle } from './build.js';
+
+const [entry, outfile] = process.argv.slice(2);
+if (!entry || !outfile) {
+  console.error('usage: elowen-plugin-ui-build <entry> <outfile>');
+  process.exit(2);
+}
+await buildPluginUiBundle({ entry, outfile });

package/build.d.ts

@@ -0,0 +1,14 @@
+export interface BuildPluginUiBundleOptions {
+  /** The bundle entry point (index.tsx/ts/jsx/js of the plugin's web sources). */
+  entry: string;
+  /** Where to write the single built ESM file (the plugin manifest's `web.entry`). */
+  outfile: string;
+  /** Minify the output (default false — the daemon serves it immutably either way). */
+  minify?: boolean;
+  /** Extra module resolution roots (NODE_PATH-style) for dependencies that live outside the plugin's
+   *  own tree — e.g. the host web app's node_modules for icon libraries. */
+  nodePaths?: string[];
+}
+
+/** Bundle `entry` into the ESM file at `outfile`. Throws on any build error. */
+export declare function buildPluginUiBundle(options: BuildPluginUiBundleOptions): Promise<void>;

package/build.js

@@ -0,0 +1,34 @@
+/** esbuild toolchain for plugin browser-UI bundles: one TS/TSX/JS entry → one self-contained
+ *  same-origin ESM file the daemon serves on a content-hash URL (the daemon hashes it — the build
+ *  emits a plain `index.js`). React imports are aliased to shims that read the HOST's instance from
+ *  `window.ElowenUiRuntime`, so a bundle can never ship a second React (two copies break hooks). */
+import { build } from 'esbuild';
+import { fileURLToPath } from 'node:url';
+
+const shim = (name) => fileURLToPath(new URL(`./shims/${name}.cjs`, import.meta.url));
+
+/** Bundle `entry` into the ESM file at `outfile`. Throws on any build error. */
+export async function buildPluginUiBundle({ entry, outfile, minify = false, nodePaths }) {
+  await build({
+    entryPoints: [entry],
+    outfile,
+    // Extra module resolution roots — e.g. the host web app's node_modules, so a bundle may use the
+    // SAME icon/library versions the app ships without duplicating them in the repo root.
+    ...(nodePaths && nodePaths.length > 0 ? { nodePaths } : {}),
+    bundle: true,
+    format: 'esm',
+    platform: 'browser',
+    // Modern evergreen browsers — the web app itself targets the same class of engines.
+    target: ['es2022'],
+    jsx: 'automatic',
+    minify,
+    legalComments: 'none',
+    alias: {
+      // esbuild picks the LONGEST matching alias, so the jsx-runtime entries win over plain `react`.
+      react: shim('react'),
+      'react-dom': shim('react-dom'),
+      'react/jsx-runtime': shim('jsx-runtime'),
+      'react/jsx-dev-runtime': shim('jsx-runtime'),
+    },
+  });
+}

package/index.d.ts

@@ -0,0 +1,69 @@
+/** Contract types for Elowen plugin browser UIs — the ONE source of truth shared by the web app
+ *  (which installs `window.ElowenUiRuntime` and consumes registrations) and plugin bundles (which
+ *  read the runtime and call `window.__elowenRegisterPluginUi`). The web app's `web/lib/pluginUi.tsx`
+ *  imports these types; keep the two sides in lockstep by editing THIS file only. */
+import type * as React from 'react';
+import type * as ReactDom from 'react-dom';
+import type * as JsxRuntime from 'react/jsx-runtime';
+import type { ComponentType } from 'react';
+
+/** See index.js — bump on incompatible changes to `ElowenUiRuntime`. Deliberately a LITERAL type:
+ *  the web app re-declares the value and annotates it with `typeof PLUGIN_UI_API_VERSION`, so a kit
+ *  bump that forgets the host fails the web typecheck instead of drifting silently. */
+export declare const PLUGIN_UI_API_VERSION: 1;
+
+/** Props every plugin page/settings component receives. */
+export interface PluginPageProps {
+  plugin: string;
+  /** Path params captured by `:name` segments of the matched route pattern. */
+  params: Record<string, string>;
+  /** The raw path segments under /p/<plugin>/. */
+  rest: string[];
+  /** Where this component is mounted. A settings component renders in BOTH places: inside the Settings
+   *  deck, where the surrounding panel already names the section, and as a standalone page at
+   *  /p/<plugin>, where nothing else does — so on a page it owes the reader a page header of its own
+   *  (`components.PluginPageHeader`) and must not repeat the section title inside its card. */
+  surface: 'page' | 'deck';
+  /** Report an autosave state to the surrounding surface, which owns the shared indicator (status plus
+   *  the Retry a failed save needs): the page masthead for a section reached at /p/<plugin>, the deck
+   *  header for a host that mounts sections in a settings deck. A section that renders its own indicator
+   *  inside a group header can ignore it; a section declaring `layout: 'orbital'` cannot — the orbital
+   *  group is a field of pods with no header to hold one, so this channel is the only place its user
+   *  ever learns that a save failed. */
+  onSaveState?: (status: 'idle' | 'saving' | 'saved' | 'error', retry?: () => void) => void;
+}
+
+/** What a bundle hands to window.__elowenRegisterPluginUi. Routes are `/`-joined segment patterns
+ *  (`''` = the root page, `detail/:id` captures params). `settings` components are keyed by the
+ *  manifest's `web.settings[].id` and render inside the Settings page's control deck. */
+export interface PluginUiRegistration {
+  requiresApiVersion: number;
+  pages?: Record<string, ComponentType<PluginPageProps>>;
+  settings?: Record<string, ComponentType<PluginPageProps>>;
+}
+
+/** The host API surface a bundle finds on `window.ElowenUiRuntime`: the HOST's React instance (a
+ *  bundle must never ship its own — the build aliases `react` imports here), a curated set of the
+ *  app's UI components, an authenticated same-origin `api` fetch, and SPA navigation. */
+export interface ElowenUiRuntime {
+  apiVersion: number;
+  react: typeof React;
+  reactDom: typeof ReactDom;
+  jsxRuntime: typeof JsxRuntime;
+  components: Record<string, ComponentType<never>>;
+  /** Curated React hooks (i18n, toasts, the app's react-query data hooks). Safe across the boundary:
+   *  the bundle runs on the HOST's React instance, so the rules of hooks hold. A bundle narrows each
+   *  entry to the signature it expects; an absent name means the host predates the bundle. */
+  hooks: Record<string, unknown>;
+  /** Curated pure helpers (formatting, session/task mapping, error shaping) shared with bundles. */
+  utils: Record<string, unknown>;
+  api: (path: string, init?: RequestInit) => Promise<unknown>;
+  navigate: (href: string) => void;
+}
+
+declare global {
+  interface Window {
+    ElowenUiRuntime?: ElowenUiRuntime;
+    __elowenRegisterPluginUi?: (plugin: string, registration: PluginUiRegistration) => void;
+  }
+}

package/index.js

@@ -0,0 +1,5 @@
+/** The single source of truth for the plugin browser-UI contract version. The web app installs
+ *  `window.ElowenUiRuntime` stamped with this number; a bundle whose `requiresApiVersion` is NEWER
+ *  renders a placeholder instead of executing against a contract it was not built for. Bump on
+ *  incompatible changes to the `ElowenUiRuntime` surface (see index.d.ts). */
+export const PLUGIN_UI_API_VERSION = 1;

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "elowen-plugin-ui-kit",
+  "version": "0.1.0",
+  "description": "Contract types and esbuild toolchain for building Elowen plugin browser-UI bundles.",
+  "license": "MIT",
+  "type": "module",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./build": {
+      "types": "./build.d.ts",
+      "default": "./build.js"
+    }
+  },
+  "bin": {
+    "elowen-plugin-ui-build": "./bin.js"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "build.js",
+    "build.d.ts",
+    "bin.js",
+    "shims/",
+    "README.md"
+  ],
+  "dependencies": {
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "esbuild": "^0.28.2"
+  }
+}

package/shims/jsx-runtime.cjs

@@ -0,0 +1,5 @@
+// See shims/react.cjs — same trick for `react/jsx-runtime` (and jsx-dev-runtime), which esbuild's
+// `jsx: 'automatic'` mode imports from every file containing JSX.
+const runtime = typeof window !== 'undefined' ? window.ElowenUiRuntime : undefined;
+if (!runtime) throw new Error('elowen-plugin-ui-kit: window.ElowenUiRuntime is missing — plugin bundles only run inside the Elowen web app');
+module.exports = runtime.jsxRuntime;

package/shims/react-dom.cjs

@@ -0,0 +1,6 @@
+// See shims/react.cjs — same trick for `react-dom`. Note there is deliberately NO shim for
+// `react-dom/client`: a plugin never owns a root (the host renders its components), so an import of
+// createRoot should fail the build loudly instead of resolving to undefined at runtime.
+const runtime = typeof window !== 'undefined' ? window.ElowenUiRuntime : undefined;
+if (!runtime) throw new Error('elowen-plugin-ui-kit: window.ElowenUiRuntime is missing — plugin bundles only run inside the Elowen web app');
+module.exports = runtime.reactDom;

package/shims/react.cjs

@@ -0,0 +1,7 @@
+// Compiled INTO every plugin bundle in place of `react` (see build.js): the plugin must render with
+// the HOST's React instance — a second copy breaks hooks and context. CJS on purpose: esbuild turns
+// named ESM imports from a CJS module into property accesses, so `import { useState } from 'react'`
+// works without enumerating React's exports here.
+const runtime = typeof window !== 'undefined' ? window.ElowenUiRuntime : undefined;
+if (!runtime) throw new Error('elowen-plugin-ui-kit: window.ElowenUiRuntime is missing — plugin bundles only run inside the Elowen web app');
+module.exports = runtime.react;