@k2b/cloud 0.40.0 → 0.42.0

package/src/ssr/LayoutHelpPanel.browser-harness.tsx

@@ -7,7 +7,8 @@ import type { User } from "../contracts/shared";
 import type { HelpDocumentManifest, HelpDocumentPayload } from "../shared/help";
 import { appAppearanceStyle } from "./app-appearance";
 import Layout from "./Layout";
-import { LayoutHelpPage, type LayoutHelpPageProps, LayoutHelpPanel, type LayoutHelpPanelProps } from "./LayoutHelp";
+import { LayoutHelpPage, type LayoutHelpPageProps } from "./LayoutHelp";
+import { LayoutHelpPanel, type LayoutHelpPanelProps } from "./LayoutHelpPanel.server";
 import { helpArticlePartsServer } from "./layout-help-article.server";
 import PanelLayout from "./PanelLayout";
 import { readPanelContext } from "./panel-context";
@@ -34,7 +35,8 @@ export const fixtureDocument: HelpDocumentPayload = {
   // A lead, the facts chips, and a section: everything the article head reads from the article.
   html: '<p>Share a Space so other people can see and edit its tasks.</p><h2 id="share">Share</h2><div class="help-steps"><ol><li>Open Space settings.</li><li>Add a person.</li></ol></div>',
 };
-const initialArticle = { payload: fixtureDocument, parts: helpArticlePartsServer(fixtureDocument.html) };
+const { html, ...payload } = fixtureDocument;
+const initialArticle = { payload, parts: helpArticlePartsServer(html) };
 const appearance: AppAppearance = { accent: "#16a34a", background: { from: "#16a34a", to: "#0284c7" } };
 const apps: CloudRuntime["apps"] = [
   {
@@ -65,7 +67,7 @@ const app = defineApp({
   routes: ["/"],
 });
 type Environment = { Variables: { runtime: CloudRuntime; user: User } };
-const PropsSnapshot = (props: { value: LayoutHelpPanelProps | LayoutHelpPageProps }) => (
+const PropsSnapshot = (props: { value: LayoutHelpPageProps }) => (
   <script id="help-fixture-props" type="application/json" innerHTML={JSON.stringify(props.value).replace(/</g, "\\u003c")} />
 );
 export const server = new Hono<Environment>()
@@ -98,10 +100,7 @@ export const server = new Hono<Environment>()
       };
       return () => (
         <PanelLayout c={c} title="Help">
-          <div id="help-fixture-root" class="flex h-full min-h-0 flex-1 flex-col">
-            <LayoutHelpPanel {...props} />
-          </div>
-          <PropsSnapshot value={props} />
+          <LayoutHelpPanel {...props} />
         </PanelLayout>
       );
     }),

package/src/ssr/LayoutHelpPanel.server.browser-harness.tsx

@@ -0,0 +1,131 @@
+import { basename, resolve } from "node:path";
+import tailwind from "bun-plugin-tailwind";
+import { Hono } from "hono";
+import { toJSON } from "seroval";
+import { createPanelRenderer, panelFixtureProps, panelIslandEntries } from "../../../../scripts/fixtures/help-panel";
+import { buildIslandClosure } from "../../../../scripts/fixtures/island-closure";
+import { islandIdFromFile } from "../../../ssr/src/island-id";
+import { helpArticlePartsServer } from "./layout-help-article.server";
+
+/**
+ * Build the real islands together, with the production mount runtime and shared ESM chunks. One module script imports
+ * every island at once, as @k2b/ssr's loader does, so a held island does not hold the others.
+ */
+export async function helpPanelServerBrowserFixture() {
+  const root = resolve(import.meta.dir, "../../../..");
+  const renderer = await createPanelRenderer();
+  const files: Record<string, string> = {};
+  const entrypoints = panelIslandEntries.map((entry) => {
+    const id = islandIdFromFile(entry, root);
+    const virtual = resolve(import.meta.dir, `${id}.ts`);
+    files[virtual] =
+      `import { mount } from ${JSON.stringify(resolve(root, "packages/ssr/src/mount.ts"))}; import C from ${JSON.stringify(entry)}; mount(C, 'solid-island[data-id="${id}"]'); document.documentElement.dataset[${JSON.stringify(`mounted${id}`)}] = "true";`;
+    return virtual;
+  });
+  try {
+    const build = await buildIslandClosure(entrypoints, files);
+    if (!build.metafile) throw new Error("Missing browser fixture metafile");
+    const outputMeta = new Map(Object.entries(build.metafile.outputs).map(([path, output]) => [basename(path), output]));
+    const eager = new Set<string>();
+    const visit = (name: string) => {
+      if (eager.has(name)) return;
+      eager.add(name);
+      for (const edge of outputMeta.get(name)?.imports ?? []) if (edge.kind !== "dynamic-import") visit(basename(edge.path));
+    };
+    const scripts = entrypoints.map((entry) => {
+      const output = [...outputMeta].find(([, meta]) => meta.entryPoint && resolve(meta.entryPoint) === entry);
+      if (!output) throw new Error(`Missing browser island entry ${entry}`);
+      visit(output[0]);
+      return output[0];
+    });
+    const outputs = new Map(await Promise.all(build.outputs.map(async (output) => [basename(output.path), await output.text()] as const)));
+    const dynamicChunks = [...outputMeta.keys()].filter((name) => !eager.has(name));
+    const chunkFor = (suffix: string) => {
+      const found = [...outputMeta]
+        .filter(([, meta]) => Object.entries(meta.inputs).some(([input, details]) => input.endsWith(suffix) && details.bytesInOutput > 0))
+        .map(([name]) => name);
+      if (!found.length) throw new Error(`Missing chunk for ${suffix}`);
+      return found;
+    };
+    const styles = await Bun.build({ entrypoints: [resolve(root, "styles.css")], plugins: [tailwind] });
+    if (!styles.success) throw new AggregateError(styles.logs, "Could not compile panel styles");
+    const css = await styles.outputs[0]!.text();
+    const initialArticle = {
+      payload: {
+        id: "share",
+        title: "Share a Space",
+        locale: "en",
+        kind: "task" as const,
+        needs: "edit" as const,
+        markdown: "Share a Space.\n\n## Invite\n\nInvite people.",
+        related: [],
+      },
+      parts: helpArticlePartsServer(
+        '<p>Share a Space.</p><h2 id="invite">Invite</h2><p>Invite people.</p><a href="/help/apps/spaces/roles">Roles</a>',
+      ),
+    };
+    const runtimeId = islandIdFromFile(panelIslandEntries.at(-1)!, root);
+    const runtimeProps = JSON.stringify(toJSON({ provider: "fixture", scope: "/panel" }))
+      .replaceAll("&", "&amp;")
+      .replaceAll('"', "&quot;");
+    const app = new Hono()
+      // Split chunks import each other by relative paths from the build's output layout; serve every file by name.
+      .get("/:path{.+\\.js}", (c) => {
+        const content = outputs.get(basename(c.req.path));
+        return content === undefined ? c.notFound() : c.body(content, 200, { "content-type": "text/javascript" });
+      })
+      .get("/", (c) =>
+        c.html(
+          `<!doctype html><html lang="en"${themeClass(c.req.query("theme"))}><head><style>${css}</style></head><body class="k2b-ui" style="margin:0"><div class="cloud-app-canvas" data-panel="open" data-panel-sheet="open" style="position:relative;display:flex;height:100dvh"><main data-cloud-app-area style="flex:1">Host app</main><aside class="cloud-panel" data-state="ready"><div class="cloud-panel__card"><header class="cloud-panel__head">Help</header><div class="cloud-panel__body"><iframe class="cloud-panel__frame" title="Help" src="/panel?${new URLSearchParams({ ...(c.req.query("topic") ? { topic: "share" } : {}), theme: c.req.query("theme") ?? "light" })}"></iframe></div></div></aside></div></body></html>`,
+        ),
+      )
+      .get("/panel", (c) =>
+        c.html(
+          `<!doctype html><html lang="en"${themeClass(c.req.query("theme"))}><head><style>${css}</style><style>html,body{margin:0;height:100%}*,*::before,*::after{animation:none!important;transition:none!important}</style></head><body class="k2b-ui"><div class="cloud-panel-page" data-cloud-panel-page><script id="cloud-panel-context" type="application/json">{"v":1,"seq":0,"pageId":"22222222-2222-4222-8222-222222222222","app":"spaces","help":["share"]}</script><solid-island data-id="${runtimeId}" data-props="${runtimeProps}"></solid-island>${renderer.render({ ...panelFixtureProps, ...(c.req.query("topic") ? { initialTopic: "share", initialArticle } : {}) })}</div><script>document.documentElement.dataset.serverGeometry=JSON.stringify((${panelGeometry.toString()})());</script><script type="module">${JSON.stringify(scripts)}.forEach((file)=>import("/assets/"+file))</script></body></html>`,
+        ),
+      )
+      .get("/api/help/search", (c) => c.json({ ids: ["share"] }))
+      .get("/api/help/:id", (c) =>
+        c.json({
+          ...initialArticle.payload,
+          id: c.req.param("id"),
+          html: '<p>Fixture.</p><h2 id="invite">Invite</h2><p>Invite people.</p>',
+        }),
+      );
+    const server = Bun.serve({ port: 0, fetch: app.fetch });
+    return {
+      origin: `http://localhost:${server.port}`,
+      dynamicChunks,
+      searchChunks: chunkFor("/layout-help-panel-search.tsx"),
+      menuChunks: chunkFor("/layout-help-panel-menu.tsx"),
+      islandChunks: new Map(panelIslandEntries.map((entry, index) => [basename(entry), scripts[index]!])),
+      ids: panelIslandEntries.map((entry) => islandIdFromFile(entry, root)),
+      cleanup: () => {
+        server.stop(true);
+        renderer.cleanup();
+      },
+    };
+  } catch (error) {
+    renderer.cleanup();
+    throw error;
+  }
+}
+
+/** Cloud's theme script sets `dark` on the root; the fixture renders that class on the server for both documents. */
+const themeClass = (theme: string | undefined) => (theme === "dark" ? ' class="dark"' : "");
+
+/** First-frame geometry is the assertion subject, so callers also take it while action chunks are held. */
+export function panelGeometry() {
+  return [
+    "[data-help-head]",
+    "[data-help-search]",
+    "[data-help-results]",
+    "[data-help-tiles] button",
+    "[data-help-server-article] [data-help-article-head]",
+  ].map((selector) => {
+    const element = document.querySelector<HTMLElement>(selector);
+    if (!element || element.closest("[hidden]")) return null;
+    const rect = element.getBoundingClientRect();
+    return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+  });
+}

package/src/ssr/LayoutHelpPanel.server.tsx

@@ -0,0 +1,115 @@
+import { MarkdownView, ScrollArea, TableOfContents, useLocale } from "@k2b/ui";
+import { Show } from "solid-js";
+import HelpPanelArticle from "./HelpPanelArticle.island";
+import HelpPanelBack from "./HelpPanelBack.island";
+import HelpPanelMenu from "./HelpPanelMenu.island";
+import HelpPanelSearch from "./HelpPanelSearch.island";
+import HelpPanelShortcuts from "./HelpPanelShortcuts.island";
+import HelpPanelView from "./HelpPanelView.island";
+import { helpMessages } from "./help-messages";
+import { HelpPanelSectionTrigger } from "./layout-help-panel-controls";
+import type { HelpPanelData } from "./layout-help-panel-state";
+import type { LayoutHelpPanelProps } from "./layout-help-panel-types";
+import { helpStart } from "./layout-help-start";
+import { HelpArticleView, HelpHead, HelpNotAvailableView, HelpStartView } from "./layout-help-views";
+
+export type { LayoutHelpPanelProps } from "./layout-help-panel-types";
+
+/** Static provider content survives island mounting; only the controls own browser state. */
+export function LayoutHelpPanel(props: LayoutHelpPanelProps) {
+  const locale = useLocale();
+  const t = () => helpMessages.resolve([locale()]).t;
+  const topic = props.documents.find((topic) => topic.id === props.initialTopic);
+  const article = topic && props.initialArticle?.payload.id === topic.id ? props.initialArticle : undefined;
+  const start = helpStart(props.documents, props.view);
+  const data: HelpPanelData = {
+    // The legacy reader searched and copied its topics in start order; keep that order for every manifest.
+    documents: [...props.documents]
+      .sort((a, b) => (a.order ?? 100) - (b.order ?? 100) || a.title.localeCompare(b.title))
+      .map(({ id, title, description, icon, kind, order, url, searchUrl, locale }) => ({
+        id,
+        title,
+        description,
+        icon,
+        kind,
+        order,
+        url,
+        searchUrl,
+        locale,
+      })),
+    appId: props.app?.id,
+    pageBase: props.pageBase,
+    article: article?.payload,
+  };
+  return (
+    <div
+      class="help-shell app-accent-scope flex h-full min-h-0 flex-col"
+      data-surface="panel"
+      style={props.appearance}
+      data-help-initial-topic={topic?.id}
+    >
+      <Show when={props.state !== "unavailable"}>
+        <HelpHead
+          row
+          back={!!topic}
+          tile={props.app?.icon ?? "ti ti-help-circle"}
+          title={props.app?.name ?? t().help}
+          lead={<HelpPanelBack back={!!topic} tile={props.app?.icon ?? "ti ti-help-circle"} />}
+          menu={<HelpPanelMenu />}
+          closable={false}
+          onBack={() => {}}
+          onClose={() => {}}
+          query=""
+          onQuery={() => {}}
+          searchRef={() => {}}
+        />
+      </Show>
+      <ScrollArea class="min-h-0 flex-1 p-4 sm:p-5">
+        <Show when={props.state !== "unavailable"} fallback={<HelpNotAvailableView />}>
+          <div class="help-start help-measure" data-help-results="" hidden={!!topic}>
+            <div data-help-start-content="">
+              <HelpPanelView topics={start.view} />
+              <HelpStartView
+                start={{ ...start, view: [] }}
+                empty={props.documents.length === 0}
+                failed={props.state === "failed"}
+                onOpen={() => {}}
+                onReload={() => {}}
+                shortcuts={<HelpPanelShortcuts appName={props.app?.name} platform={props.platform} />}
+              />
+            </div>
+            <HelpPanelSearch />
+          </div>
+          <Show when={article && topic}>
+            {article && topic && (
+              <article class="help-article" data-surface="panel" data-help-server-article="">
+                <HelpArticleView
+                  surface="panel"
+                  topic={topic}
+                  appName={props.app?.name}
+                  appId={props.app?.id}
+                  parts={article.parts}
+                  document={{ ...article.payload, html: "" }}
+                  Markdown={MarkdownView}
+                  showTools={article.parts.sections.length > 0}
+                  sectionMenu={article.parts.sections.length ? <HelpPanelSectionTrigger label={t().onThisPage} /> : null}
+                  copyButton={null}
+                  loading={null}
+                  failure={null}
+                  toc={<TableOfContents items={article.parts.sections} title={t().onThisPage} />}
+                  copyAction={null}
+                  headingRef={() => {}}
+                  contentRef={() => {}}
+                  onBack={() => {}}
+                />
+              </article>
+            )}
+          </Show>
+          <HelpPanelArticle topic={article ? undefined : topic} />
+        </Show>
+        <span class="sr-only" aria-live="polite" data-help-announcement="" />
+      </ScrollArea>
+      <script type="application/json" data-help-panel-data="" innerHTML={JSON.stringify(data).replace(/</g, "\\u003c")} />
+    </div>
+  );
+}

package/src/ssr/PanelRuntime.island.tsx

@@ -1,6 +1,7 @@
 import { installAppWorkspaceController, installInputModeController, keyboardPlatform } from "@k2b/ui";
 import { onCleanup, onMount } from "solid-js";
 import { installPanelContextReceiver } from "../browser/panel-context-receiver";
+import { hasPanelLeaveGuard, panelLinkDestination } from "../browser/panel-leave";
 import { syncTimezoneCookie } from "./timezone-cookie";
 
 export default function PanelRuntime(props: { provider?: string; scope?: string }) {
@@ -24,15 +25,18 @@ export default function PanelRuntime(props: { provider?: string; scope?: string
     };
     const close = () => window.parent.postMessage({ type: "cloud.panel.close" }, location.origin);
     const click = (event: MouseEvent) => {
-      if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.altKey || event.shiftKey) return;
-      const anchor = event.target instanceof Element ? event.target.closest<HTMLAnchorElement>("a[href]") : null;
-      if (!anchor || (anchor.target && anchor.target !== "_self") || anchor.hasAttribute("download")) return;
-      const url = new URL(anchor.getAttribute("href")!, document.baseURI);
-      if (url.origin !== location.origin) return;
+      const url = panelLinkDestination(event);
+      if (!url) return;
       const scope = props.scope?.replace(/\/$/, "");
-      if (scope !== undefined && (url.pathname === scope || url.pathname.startsWith(`${scope}/`))) return;
+      const internal = scope !== undefined && (url.pathname === scope || url.pathname.startsWith(`${scope}/`));
+      if (!hasPanelLeaveGuard()) {
+        if (internal) return;
+        event.preventDefault();
+        window.parent.location.assign(url.href);
+        return;
+      }
       event.preventDefault();
-      window.parent.location.assign(url.href);
+      window.parent.postMessage({ type: "cloud.panel.navigate", v: 1, href: url.href }, location.origin);
     };
     const key = (event: KeyboardEvent) => {
       if (event.isComposing || event.defaultPrevented || event.altKey || event.shiftKey) return;

package/src/ssr/PwaLayout.tsx

@@ -6,7 +6,7 @@ import { visiblePwaParts } from "./app-navigation";
 import type { LayoutContext } from "./layout-context";
 import PwaRuntime from "./PwaRuntime.island";
 import { pwaMessages } from "./pwa-messages";
-import { getRuntimeContext } from "./runtime";
+import { getDisplayRuntimeContext } from "./runtime";
 import TimezoneCookie from "./TimezoneCookie.island";
 
 /** Parts with their own tab; Start lists every part and doubles as "More". */
@@ -42,7 +42,7 @@ export default function PwaLayout(props: PwaLayoutProps) {
   c.header("Referrer-Policy", "no-referrer");
   c.header("Content-Security-Policy", "frame-ancestors 'none'");
 
-  const parts = visiblePwaParts(getRuntimeContext(c).apps, user, locale);
+  const parts = visiblePwaParts(getDisplayRuntimeContext(c).apps, user, locale);
   const path = new URL(c.req.raw.url).pathname;
   const tabs = parts.slice(0, TAB_PARTS);
   const currentTab = tabs.find((part) => path === part.pwa.href || path.startsWith(`${part.pwa.href}/`));

package/src/ssr/RailApps.tsx

@@ -44,11 +44,17 @@ export default function RailApps(props: { apps: RailApp[]; settings: RailSnapsho
     const stopBadges = watchAppBadges(props.apps.flatMap((app) => (app.badge ? [app.badge] : [])));
     window.addEventListener(RAIL_PREFERENCES_EVENT, sync);
     window.addEventListener("popstate", syncLocation);
+    window.addEventListener("ssr:nav-popstate", syncLocation);
+    window.addEventListener("ssr:nav-swapped", sync);
+    window.addEventListener("ssr:nav-swapped", syncLocation);
     window.addEventListener("hashchange", syncLocation);
     onCleanup(() => {
       stopBadges();
       window.removeEventListener(RAIL_PREFERENCES_EVENT, sync);
       window.removeEventListener("popstate", syncLocation);
+      window.removeEventListener("ssr:nav-popstate", syncLocation);
+      window.removeEventListener("ssr:nav-swapped", sync);
+      window.removeEventListener("ssr:nav-swapped", syncLocation);
       window.removeEventListener("hashchange", syncLocation);
     });
   });

package/src/ssr/ShellRuntime.island.tsx

@@ -1,4 +1,5 @@
 import type { HelpDocumentManifest } from "@k2b/cloud/shared";
+import { installPageSwap } from "@k2b/ssr/nav";
 import {
   followPageTrail,
   installAppWorkspaceController,
@@ -9,6 +10,7 @@ import {
   useLocale,
 } from "@k2b/ui";
 import { createEffect, createSignal, onCleanup, onMount } from "solid-js";
+import { isServer } from "solid-js/web";
 import { appWorkspaceCookieName, readAppWorkspaceLayoutCookie } from "../_internal/app-workspace-state";
 import { registerContextAwareCommand } from "../browser/command-bridge";
 import { attachCommandShortcuts } from "../browser/command-shortcuts";
@@ -58,10 +60,13 @@ export type ShellRuntimeProps = {
 const searchItems = () => {
   const data = readShellData();
   if (!data) return [];
-  const apps = Object.entries(data.searchLinks).flatMap(([id, searchLinks]) => {
-    const app = data.apps.find((candidate) => candidate.id === id);
-    return app ? [{ id, name: app.label, icon: app.iconClass, searchLinks }] : [];
-  });
+  const apps = data.apps.map((app) => ({
+    id: app.id,
+    name: app.label,
+    icon: app.iconClass,
+    nav: { href: app.href },
+    searchLinks: data.searchLinks[app.id],
+  }));
   return navigationSearchItems(
     apps,
     apps.map((app) => app.id),
@@ -69,6 +74,7 @@ const searchItems = () => {
 };
 
 export default function ShellRuntime(props: ShellRuntimeProps) {
+  if (!isServer && document.querySelector(".cloud-app-canvas[data-nav-shell]")) onCleanup(installPageSwap());
   const locale = useLocale();
   const t = () => platformMessages.resolve([locale()]).t;
   onMount(() => syncTimezoneCookie(true));
@@ -132,7 +138,7 @@ export default function ShellRuntime(props: ShellRuntimeProps) {
   if (props.workspace) {
     onMount(() => {
       const appId = props.workspace?.appId;
-      onCleanup(
+      const install = () =>
         installAppWorkspaceController({
           readState: () => readAppWorkspaceLayoutCookie(document.cookie, appId),
           writeState: (state) => {
@@ -140,8 +146,18 @@ export default function ShellRuntime(props: ShellRuntimeProps) {
             const secure = window.location.protocol === "https:" ? "; Secure" : "";
             document.cookie = `${appWorkspaceCookieName(appId)}=${serializeAppWorkspaceLayoutState(state)}; Path=/; Max-Age=31536000; SameSite=Lax${secure}`;
           },
-        }),
-      );
+        });
+      let dispose = install();
+      // The controller reads the saved layout once; a swapped page may carry sizes another tab saved since.
+      const swapped = () => {
+        dispose();
+        dispose = install();
+      };
+      window.addEventListener("ssr:nav-swapped", swapped);
+      onCleanup(() => {
+        window.removeEventListener("ssr:nav-swapped", swapped);
+        dispose();
+      });
     });
   }
   if (props.pageTrail) {