@heswell/vuu-portal 2.2.3 → 2.2.5

package/195.js

@@ -1,4 +1,4 @@
-import { MODULE_ADMIN_RPC, executeModuleAdminRpc, managedModuleColumnValues, managedModulePermissionValues, splitNotificationTopics, validateModuleConfig } from "@heswell/module-admin";
+import { MODULE_ADMIN_RPC, deserializeModuleWorkspace, executeModuleAdminRpc, managedModuleColumnValues, managedModulePermissionValues, normalizeModuleWorkspace, splitNotificationTopics, validateModuleConfig } from "@heswell/module-admin";
 import { ConfigFactory, EditSessionRpcHandler, ModuleFactory, NotificationModule, NullProvider, PermissionFilter, Provider, TableDef, VUU_DEFAULT_COLUMNS, ViewPortDef, createConfiguredAuthProviders, createVuuServerApplication, getLogger } from "@heswell/vuu-server";
 import node_fs from "node:fs";
 import node_path from "node:path";
@@ -32,7 +32,8 @@ function readModules(table) {
             mfScope: stringValue(table, row, "mfScope"),
             mfUrl: stringValue(table, row, "mfUrl"),
             ...navIcon(table, row),
-            ...navMetadata(table, row)
+            ...navMetadata(table, row),
+            ...workspaceMetadata(table, row)
         };
     });
 }
@@ -55,6 +56,12 @@ function navMetadata(table, row) {
     }
     return metadata;
 }
+function workspaceMetadata(table, row) {
+    const workspace = deserializeModuleWorkspace(optionalValue(table, row, "workspace"));
+    return workspace ? {
+        workspace
+    } : {};
+}
 function optionalValue(table, row, column) {
     const index = table.tableDef.columns.findIndex(({ name })=>name === column);
     return -1 === index ? void 0 : row[index];
@@ -188,6 +195,10 @@ const modulesTable = TableDef({
             name: "notificationTopics",
             dataType: "string"
         },
+        {
+            name: "workspace",
+            dataType: "string"
+        },
         ...VUU_DEFAULT_COLUMNS
     ],
     keyField: "id",
@@ -370,11 +381,17 @@ function readModulesFile(filePath) {
 function cloneModules(modules) {
     return modules.map((module)=>Object.fromEntries(Object.entries(module).filter(([, value])=>void 0 !== value).map(([key, value])=>[
                 key,
-                Array.isArray(value) ? [
-                    ...value
-                ] : value
+                cloneValue(value)
             ])));
 }
+function cloneValue(value) {
+    if (Array.isArray(value)) return value.map(cloneValue);
+    if (isRecord(value)) return Object.fromEntries(Object.entries(value).map(([key, item])=>[
+            key,
+            cloneValue(item)
+        ]));
+    return value;
+}
 const managedModuleKeys = [
     "id",
     "version",
@@ -396,7 +413,8 @@ const managedModuleKeys = [
 const optionalModuleKeys = [
     "navOrder",
     "navBadge",
-    "notificationTopics"
+    "notificationTopics",
+    "workspace"
 ];
 const retiredModuleKeys = [
     "vuuConnectionId",
@@ -424,6 +442,11 @@ function parseManagedModule(value, index) {
     for (const key of optionalModuleKeys){
         const fieldValue = value[key];
         if (null == fieldValue) continue;
+        if ("workspace" === key) {
+            if (!isRecord(fieldValue)) throw new Error(`Modules file entry ${index} field 'workspace' must be an object`);
+            module[key] = cloneValue(normalizeModuleWorkspace(fieldValue));
+            continue;
+        }
         const valid = "navOrder" === key ? "number" == typeof fieldValue : "navBadge" === key ? "string" == typeof fieldValue : Array.isArray(fieldValue) && fieldValue.every((topic)=>"string" == typeof topic);
         if (!valid) {
             const expected = "navOrder" === key ? "a number" : "navBadge" === key ? "a string" : "a list of strings";

package/README.md

@@ -138,3 +138,80 @@ absolute paths and `~/` paths are also accepted.
   start.
 - `vuu.portal.defaultModulesFile` is the seed catalogue. See
   [`default-modules.yaml`](./default-modules.yaml) for the format.
+
+## Workspaces and the Panels palette
+
+`@vuu-ui/*` 4.0.0-alpha.26 adds named workspaces to the portal UI: a
+**Workspaces** section in the nav with **+ New workspace**, the
+`/workspaces/:id` route, **Reset to default**, and an **Add panel** button that
+opens the **Panels** palette (tabs Modules, Tables and Recent) inline beside
+the workspace grid. Tables › Browse lists the Vuu servers; each server page is
+an unsaved workspace with the Tables palette pinned, which **Save as
+workspace** keeps.
+
+This package is the portal *server*. It doesn't render the UI; it supplies the
+module records the palette is built from.
+
+### What the server provides
+
+A module record with a `workspace` descriptor is listed in the palette's
+Modules tab, grouped by `workspace.paletteGroup`. A module without one isn't.
+See [Workspace metadata](../../docs/requirements/vuu-portal-module-discovery.md#workspace-metadata)
+for the field. In [`default-modules.yaml`](./default-modules.yaml):
+
+| Module | `workspace` | Why |
+| --- | --- | --- |
+| `moduleAdmin`, `userAdmin` | `{ paletteGroup: "Admin", defaultSize: { cols: 12, rows: 6 } }` | Standalone pages |
+| `basket-trading` | `{ paletteGroup: "Trading", defaultSize: { cols: 12, rows: 8 } }` | Standalone page |
+| `vuu-table-browser` | none | It is itself a workspace page; its tables are in the palette's Tables tab |
+| `vuu-table-viewer` | none | Nested module; it only works inside the table browser |
+
+The seed only applies when `modules.yaml` is first created. To change an
+existing deployment, edit `modules.yaml` or use the module admin
+(`updateModule` with `workspace`, or `workspace: null` to remove a module from
+the palette).
+
+### Portal host requirements
+
+The host is the `PortalShell` application, for example finos/vuu
+`vuu-ui/portal-examples/portal-host`. See its
+`docs/module-federation-architecture.md`. Workspaces are opt in:
+
+```tsx
+import {
+  AddPanelButton,
+  createPortalComponentRegistries,
+  PortalShell,
+  type PortalWorkspacesOptions,
+} from "@vuu-ui/core/portal";
+
+const { renderers, settingsCodecs } = createPortalComponentRegistries();
+
+const workspaces: PortalWorkspacesOptions = {
+  componentRenderers: renderers,
+  headerActions: <AddPanelButton />,
+  settingsCodecs,
+};
+
+<PortalShell contextPanel={{ placement: "inline" }} workspaces={workspaces} ...>
+```
+
+- `PortalShell` renders the single `GridLayoutProvider` above both the palette
+  and the workspace. Don't add another one in the host or in a remote.
+- `contextPanel={{ placement: "inline" }}` shows the palette beside the grid
+  instead of over it.
+- Module Federation must share these as strict singletons
+  (`singleton: true, strictVersion: true`) in the host *and* every remote:
+  `react`, `react-dom`, `react-router-dom`, `@vuu-ui/core`,
+  `@vuu-ui/core/portal`, `@vuu-ui/grid-layout` and
+  `@vuu-ui/vuu-notifications`. A second copy of grid-layout breaks dragging
+  from the palette into the workspace; a second React or router breaks
+  rendering.
+- Workspaces are saved by `workspaces.persistenceService`. By default that is
+  browser local storage, scoped to the `PortalShell` id and the signed-in
+  user. Servers added under Tables › Browse are kept in the per-user portal
+  state (`servers/manual`). This server doesn't store either.
+
+To turn workspaces off, leave the `workspaces` prop off `PortalShell`. To
+keep workspaces but hide a module from the palette, remove its `workspace`
+descriptor.

package/config/default-modules.yaml

@@ -12,7 +12,7 @@
 #     title: "Manage remote modules"
 #     description: "Create new remote module, update existing modules"
 #     enabled: true
-#     location: "/Modules/Manage Modules"
+#     location: "/Admin/Manage Modules"
 #     path: "/modules/admin"
 #     mfComponent: "ModuleAdmin"
 #     mfScope: "moduleAdmin"
@@ -23,4 +23,9 @@
 #     navOrder: 1
 #     navBadge: "modules.pending"
 #     notificationTopics: ["modules"]
+#     # Optional: list the module in the workspace Panels palette.
+#     workspace:
+#       paletteGroup: "Admin"
+#       iconUrl: ""            # optional; data:image/... or http(s) URL
+#       defaultSize: { cols: 6, rows: 4 }  # optional; positive integers
 modules: []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heswell/vuu-portal",
-  "version": "2.2.3",
+  "version": "2.2.5",
   "description": "VUU portal server with remote module discovery",
   "type": "module",
   "main": "./index.js",
@@ -26,12 +26,12 @@
   "author": "heswell",
   "license": "MIT",
   "dependencies": {
-    "@heswell/module-admin": "^2.1.0"
+    "@heswell/module-admin": "^2.2.0"
   },
   "peerDependencies": {
     "@heswell/vuu-server": "^3.1.0 || ^4.0.0",
     "@heswell/vuu-table": "^1.0.1",
-    "@vuu-ui/vuu-protocol-types": "^4.0.0-alpha.25"
+    "@vuu-ui/vuu-protocol-types": "^4.0.0-alpha.26"
   },
   "repository": {
     "type": "git",