Merge pull request #330 from Point72/tkp/perspective-theme-layout-actions

Fix Perspective themes and layout actions

Author: timkpaine

TODO_SPADAY.md

@@ -0,0 +1,20 @@
+# Spaday follow-ups
+
+## Parallelize Perspective panel theme restores
+
+`spaday-perspective` 0.4.3 has the same panel-count-dependent theme lag as the legacy csp-gateway frontend had before its local fix.
+
+The `<perspective-panel>` theme path currently:
+
+1. calls `restore({theme})` for the element chrome and active panel;
+2. calls `saveWorkspace()` to enumerate panels;
+3. loops over every panel and awaits `restore({theme}, {panel})` sequentially.
+
+Each restore restyles a Perspective plugin, so total latency grows with the number of tabs. Browser profiling against Perspective 5.2 showed a visibly delayed transition with eight panels. In one run, sequential completion took about 300 ms; issuing the panel restores with `Promise.all()` reduced it to about 150 ms. Exact timings vary with panel contents and render state.
+
+Upstream action:
+
+- Keep the initial bare `restore({theme})`; it updates element chrome and the active panel.
+- After `saveWorkspace()`, restore background panel themes concurrently with `Promise.all()` rather than a serial `for ... of` loop.
+- Verify concurrent restores remain safe while live tables update and while a layout replacement is queued.
+- Add a multi-panel browser test that checks all saved panel themes after toggling the global theme.

csp_gateway/server/modules/web/perspective.py

@@ -9,14 +9,15 @@
     Literal,
     TypeVar,
 )
+from urllib.parse import parse_qs
 
 import csp
 import orjson
 import pyarrow
 import pyarrow.json
 import uvloop
 from csp import ts
-from fastapi import APIRouter, WebSocket
+from fastapi import APIRouter, HTTPException, Request, Response, WebSocket
 from perspective import Client, Server, Table
 from perspective.handlers.starlette import PerspectiveStarletteHandler
 from pydantic import BaseModel, Field, PrivateAttr, field_validator, model_validator
@@ -43,6 +44,8 @@
 
 log = getLogger(__name__)
 
+_MAX_LAYOUT_DOWNLOAD_BYTES = 16 * 1024 * 1024
+
 _PSP_ARROW_MAP = {
     int: pyarrow.int64(),
     float: pyarrow.float64(),
@@ -654,6 +657,36 @@ async def get_perspective_layouts():
             """
             return self._layouts
 
+        @api_router.post("{}/{}".format(self._route, "download-layout"), include_in_schema=False)
+        async def download_perspective_layout(request: Request) -> Response:
+            try:
+                content_length = int(request.headers.get("content-length", 0))
+                if content_length > _MAX_LAYOUT_DOWNLOAD_BYTES:
+                    raise HTTPException(status_code=413, detail="Layout is too large")
+                body = bytearray()
+                async for chunk in request.stream():
+                    body.extend(chunk)
+                    if len(body) > _MAX_LAYOUT_DOWNLOAD_BYTES:
+                        raise HTTPException(status_code=413, detail="Layout is too large")
+                fields = parse_qs(body.decode("utf-8"), strict_parsing=True, max_num_fields=1)
+                layout = fields["layout"][0]
+                parsed = orjson.loads(layout)
+                if not isinstance(parsed, dict) or not isinstance(parsed.get("layout"), dict) or not isinstance(parsed.get("panels"), dict):
+                    raise TypeError
+            except HTTPException:
+                raise
+            except (KeyError, TypeError, UnicodeDecodeError, ValueError, orjson.JSONDecodeError) as exc:
+                raise HTTPException(status_code=400, detail="Invalid layout") from exc
+            return Response(
+                content=layout,
+                media_type="application/json",
+                headers={
+                    "Cache-Control": "no-store",
+                    "Content-Disposition": 'attachment; filename="layout.json"',
+                    "X-Content-Type-Options": "nosniff",
+                },
+            )
+
         # add route to fetch layouts
         @api_router.get(
             "{}/{}".format(self._route, "meta"),
@@ -721,8 +754,13 @@ def ui(self, app: "GatewayUI") -> None:
         )
         default_view = self.default_layout or "__default__"
         app.seed_store(view=default_view)
-        if layouts:
-            app.add(Region.HEADER_RIGHT, app.layout_selector(layouts, value=default_view), order=90)
+        app.add(Region.HEADER_RIGHT, app.layout_selector(layouts, value=default_view), order=90)
+        app.add(Region.HEADER_RIGHT, app.save_layout_button(), order=100)
+        app.add(
+            Region.HEADER_RIGHT,
+            app.download_layout_button(f"{app.settings.API_STR}{self._route}/download-layout"),
+            order=101,
+        )
 
     def run_perspective(self):
         """Launch the perspective threads"""

csp_gateway/server/web/spaday_assets/actions.js

@@ -0,0 +1,58 @@
+import { registerHandler } from "../../js/cdn/index.js";
+
+const CUSTOM_LAYOUT_STORAGE_KEY = "csp_gateway_demo_config";
+const WORKSPACE_ID = "gateway-workspace";
+
+function stripTransientFields(layout) {
+  const cloned = structuredClone(layout);
+  for (const panel of Object.values(cloned.panels || {})) {
+    delete panel.theme;
+    for (const column of Object.values(panel.plugin_config?.columns || {})) {
+      delete column.column_size_override;
+    }
+  }
+  return cloned;
+}
+
+function workspace(currentTarget) {
+  return currentTarget.ownerDocument.getElementById(WORKSPACE_ID);
+}
+
+registerHandler("csp-gateway:save-layout", (_event, currentTarget) => {
+  void (async () => {
+    const layout = stripTransientFields(await workspace(currentTarget).save());
+    localStorage.setItem(CUSTOM_LAYOUT_STORAGE_KEY, JSON.stringify(layout));
+    const customLayout = globalThis.cspGatewayCustomLayout;
+    for (const key of Object.keys(customLayout)) {
+      delete customLayout[key];
+    }
+    Object.assign(customLayout, layout);
+  })().catch((error) =>
+    console.error("Failed to save Perspective layout:", error),
+  );
+});
+
+registerHandler("csp-gateway:download-layout", (_event, currentTarget) => {
+  void (async () => {
+    const layout = stripTransientFields(await workspace(currentTarget).save());
+    const json = JSON.stringify(layout).replace(
+      /PERSPECTIVE_GENERATED_/g,
+      "CSP_GATEWAY_GENERATED_",
+    );
+    const form = currentTarget.ownerDocument.createElement("form");
+    form.method = "POST";
+    form.action = currentTarget.dataset.downloadUrl;
+    form.target = "_blank";
+    form.hidden = true;
+    const input = currentTarget.ownerDocument.createElement("input");
+    input.type = "hidden";
+    input.name = "layout";
+    input.value = json;
+    form.appendChild(input);
+    currentTarget.ownerDocument.body.appendChild(form);
+    form.submit();
+    form.remove();
+  })().catch((error) =>
+    console.error("Failed to download Perspective layout:", error),
+  );
+});

csp_gateway/server/web/spaday_ui.py

@@ -17,6 +17,7 @@
 import json
 import logging
 from dataclasses import dataclass, field as _dc_field
+from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 from pydantic import TypeAdapter
@@ -33,9 +34,10 @@
         "dependency, which ships with csp-gateway. Reinstall it with: pip install csp-gateway."
     ) from exc
 
-from spaday import element
+from spaday import Js, element
 from spaday.actions import (
     CallEndpoint,
+    NamedJs,
     Sequence,
     SetField,
     Toggle,
@@ -51,6 +53,7 @@
 )
 from spaday.backends.starlette import mount as _spaday_mount
 from spaday.components.shell import AppShell, Column, Region, Row, Show
+from spaday.packages import ComponentPackage
 from spaday_perspective import PerspectivePanel
 from spaday_webawesome import (
     FormField,
@@ -78,6 +81,15 @@
 
 # The tenant every connection shares when no auth middleware can identify it.
 _ANONYMOUS_TENANT = "__anonymous__"
+_CUSTOM_LAYOUT_NAME = "Custom Layout"
+_CUSTOM_LAYOUT_STORAGE_KEY = "csp_gateway_demo_config"
+_SAVE_LAYOUT_HANDLER = "csp-gateway:save-layout"
+_DOWNLOAD_LAYOUT_HANDLER = "csp-gateway:download-layout"
+_GATEWAY_COMPONENT_PACKAGE = ComponentPackage(
+    name="csp-gateway",
+    assets_dir=Path(__file__).with_name("spaday_assets"),
+    assets=(("js", "actions.js"),),
+)
 
 
 # Page-level resets that spaday's document template does not ship. The palette is deliberately absent:
@@ -274,13 +286,27 @@ def perspective_panel(
         to all of ``tables``. Add it to `Region.MAIN`.
         """
         tables = list(tables or [])
-        layout_expr: Any = self._default_layout(list(default_tables) if default_tables is not None else tables)
+        default_layout = self._default_layout(list(default_tables) if default_tables is not None else tables)
+        layout_expr: Any = default_layout
         for name, layout_json in (layouts or {}).items():
             try:
                 parsed = json.loads(layout_json)
             except (TypeError, ValueError):
                 continue
             layout_expr = cond(eq(field("view"), name), parsed, layout_expr)
+        fallback = json.dumps(default_layout).replace("<", "\\u003c")
+        storage_key = json.dumps(_CUSTOM_LAYOUT_STORAGE_KEY)
+        self._store_seeds["custom_layout"] = Js(
+            "globalThis.cspGatewayCustomLayout = (() => { "
+            f"const fallback = {fallback}; "
+            f'try {{ const value = JSON.parse(localStorage.getItem({storage_key}) ?? "null"); '
+            'return value && typeof value === "object" && !Array.isArray(value) '
+            '&& value.layout && typeof value.layout === "object" && !Array.isArray(value.layout) '
+            '&& value.panels && typeof value.panels === "object" && !Array.isArray(value.panels) ? value : fallback; } '
+            "catch { return fallback; } "
+            "})()"
+        )
+        layout_expr = cond(eq(field("view"), _CUSTOM_LAYOUT_NAME), field("custom_layout"), layout_expr)
 
         return (
             PerspectivePanel()
@@ -291,15 +317,28 @@ def perspective_panel(
         )
 
     def layout_selector(self, layouts: dict[str, str], *, value: str | None = None) -> Any:
-        """A dropdown two-way bound to the `view` state, listing "All Tables" + each named layout.
+        """A dropdown bound to `view`, listing the generated, saved, and custom layouts.
 
         Add it to `Region.HEADER_RIGHT` (and `seed_store(view=...)`).
         """
         select = WaSelect(value=value, size="s").bind("value", "view", mode="two-way").style(width="220px")
         select = select.child(WaOption(value="__default__").text("All Tables"))
         for name in layouts:
             select = select.child(WaOption(value=name).text(name))
-        return select
+        return select.child(WaOption(value=_CUSTOM_LAYOUT_NAME).text(_CUSTOM_LAYOUT_NAME))
+
+    def save_layout_button(self) -> Any:
+        """A header button that saves the current Perspective workspace in the browser."""
+        return WaButton(appearance="plain", title="Save current layout").on("click", NamedJs(_SAVE_LAYOUT_HANDLER)).child(WaIcon(name="floppy-disk"))
+
+    def download_layout_button(self, url: str) -> Any:
+        """A header button that downloads the current Perspective workspace as JSON."""
+        return (
+            WaButton(appearance="plain", title="Download layout")
+            .prop("data-download-url", self.url(url))
+            .on("click", NamedJs(_DOWNLOAD_LAYOUT_HANDLER))
+            .child(WaIcon(name="download"))
+        )
 
     def link_button(self, label: str, href: str, *, target: str = "_blank", variant: str | None = None) -> Any:
         """A full-width link button (opens `href`), for a drawer/gutter. Add it to a region."""
@@ -715,7 +754,7 @@ def mount(self) -> None:
             scratch,
             self.build_page,
             # Component libraries ship as their own distributions and are resolved by entry point.
-            packages=["webawesome", "perspective"],
+            packages=["webawesome", "perspective", _GATEWAY_COMPONENT_PACKAGE],
             # spaday infers "source checkout" from a `js/` dir next to itself, which any distribution
             # shipping a top-level `js/` package (plotly does) satisfies -- serving assets we consume
             # from the wheel, never from a spaday checkout.

csp_gateway/tests/server/web/test_spaday_ui.py

@@ -1,5 +1,6 @@
 """Tests for the optional spaday UI provider (`Settings.UI_PROVIDER == "spaday"`)."""
 
+import json
 from datetime import timedelta
 from enum import Enum, auto
 
@@ -15,6 +16,7 @@
     GatewayModule,
     GatewaySettings,
     GatewayStruct,
+    MountPerspectiveTables,
     MountRestRoutes,
     MountSendForm,
 )
@@ -247,3 +249,65 @@ def test_one_datagrid_panel_per_table(self):
             "CSP_GATEWAY_0": {"table": "orders", "plugin": "Datagrid", "title": "orders"},
             "CSP_GATEWAY_1": {"table": "fills", "plugin": "Datagrid", "title": "fills"},
         }
+
+
+class TestSpadayPerspectiveLayoutActions:
+    @pytest.fixture(scope="class")
+    def gateway(self, free_port):
+        return Gateway(
+            modules=[ExampleModule(), MountPerspectiveTables()],
+            channels=ExampleChannels(),
+            settings=GatewaySettings(PORT=free_port, UI_PROVIDER="spaday"),
+        )
+
+    @pytest.fixture(scope="class")
+    def client(self, gateway):
+        gateway.start(rest=True, ui=True, _in_test=True)
+        try:
+            yield TestClient(gateway.web_app.get_fastapi())
+        finally:
+            gateway.stop()
+
+    def test_layout_actions_are_available_without_server_layouts(self, client: TestClient):
+        tree = client.get("/tree.json").text
+        assert "Custom Layout" in tree
+        assert "Save current layout" in tree
+        assert "csp-gateway:save-layout" in tree
+        assert "Download layout" in tree
+        assert "csp-gateway:download-layout" in tree
+
+    def test_layout_action_script_is_served(self, client: TestClient):
+        page = client.get("/").text
+        assert "/components/csp-gateway/actions.js" in page
+        assert "globalThis.cspGatewayCustomLayout" in page
+        assert '"gateway-workspace"' in client.get("/tree.json").text
+        script = client.get("/components/csp-gateway/actions.js")
+        assert script.status_code == 200
+        assert 'from "../../js/cdn/index.js"' in script.text
+        assert '"csp-gateway:save-layout"' in script.text
+        assert '"csp-gateway:download-layout"' in script.text
+        assert '"csp_gateway_demo_config"' in script.text
+        assert '"gateway-workspace"' in script.text
+        assert client.get("/js/cdn/index.js").status_code == 200
+
+    def test_layout_download_is_a_same_origin_attachment(self, client: TestClient):
+        layout = {"layout": {"type": "tab-layout", "tabs": []}, "panels": {}}
+
+        response = client.post("/api/v1/perspective/download-layout", data={"layout": json.dumps(layout)})
+
+        assert response.status_code == 200
+        assert response.json() == layout
+        assert response.headers["content-disposition"] == 'attachment; filename="layout.json"'
+        assert response.headers["cache-control"] == "no-store"
+        assert response.headers["x-content-type-options"] == "nosniff"
+
+    def test_layout_download_rejects_invalid_and_oversized_content(self, client: TestClient):
+        invalid = client.post("/api/v1/perspective/download-layout", data={"layout": "1"})
+        oversized = client.post(
+            "/api/v1/perspective/download-layout",
+            content=b"x",
+            headers={"content-length": str(16 * 1024 * 1024 + 1)},
+        )
+
+        assert invalid.status_code == 400
+        assert oversized.status_code == 413

js/package.json

@@ -10,9 +10,9 @@
   "scripts": {
     "build": "node build.mjs",
     "clean": "rimraf dist lib playwright-report ../csp_gateway/server/build",
-    "lint": "prettier --check \"src/**/*.{js,ts,jsx,tsx,css,html}\" \"*.mjs\" \"*.json\"",
-    "fix": "prettier  --write \"src/**/*.{js,ts,jsx,tsx,css,html}\" \"*.mjs\" \"*.json\"",
-    "test": "echo \"todo\"",
+    "lint": "prettier --check \"src/**/*.{js,ts,jsx,tsx,css,html}\" \"../csp_gateway/server/web/spaday_assets/*.js\" \"*.mjs\" \"*.json\"",
+    "fix": "prettier  --write \"src/**/*.{js,ts,jsx,tsx,css,html}\" \"../csp_gateway/server/web/spaday_assets/*.js\" \"*.mjs\" \"*.json\"",
+    "test": "node --test",
     "preinstall": "npx only-allow pnpm",
     "prepack": "pnpm run build"
   },

js/src/js/components/header.jsx

@@ -1,7 +1,7 @@
 import React, { useCallback, useEffect, useState } from "react";
 import { FaBars, FaDownload, FaMoon, FaSave, FaSun } from "react-icons/fa";
 import { CspGatewayLogo } from "./logo";
-import { getCurrentTheme } from "./perspective/theme";
+import { downloadLayout } from "./perspective/download";
 
 const ICON_SIZE = 20;
 
@@ -59,12 +59,7 @@ export function Header(props) {
   const onDownload = useCallback(async () => {
     const json = await workspaceRef?.current?.exportLayout();
     if (!json) return;
-    const link = document.createElement("a");
-    link.href = `data:application/json;base64,${btoa(json)}`;
-    link.download = "layout.json";
-    document.body.appendChild(link);
-    link.click();
-    document.body.removeChild(link);
+    downloadLayout(json);
   }, [workspaceRef]);
 
   return (