@k2b/cloud 0.40.0 → 0.41.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>
+  );
+}