@k2b/cloud 0.38.0 → 0.40.0

package/src/ssr/Layout.tsx

@@ -2,26 +2,31 @@ import type { DateContext } from "@k2b/stdlib";
 import { AppWorkspace, appWorkspaceLayoutStyle, keyboardPlatform, LocaleProvider, NoticeCard, PageTrailProvider } from "@k2b/ui";
 import type { JSX } from "solid-js/jsx-runtime";
 import { readAppWorkspaceLayoutCookie, resolveAppWorkspaceLayoutForSidebar } from "../_internal/app-workspace-state";
+import { readPanelCookie } from "../_internal/panel-cookie";
 import { readShellFocusCookie } from "../_internal/shell-focus";
 import { resolveNavMatch } from "../contracts/app"; // ==========================
+import { type CloudResourceRef, CloudResourceRefSchema } from "../contracts/capabilities";
+import { PANEL_HELP_ID_MAX_LENGTH, PanelPageContextSchema } from "../contracts/panel-context";
 import { isPwaShellAvailable } from "../contracts/pwa";
 import { defaultRailPreferences } from "../contracts/rail-preferences";
 import { hasRole, type User } from "../contracts/shared";
 import { getLocale } from "../server/locale";
 import { getDateConfig } from "../server/time";
-import { dates } from "../shared";
+import { dates, resolveHomePath } from "../shared";
 import { readThemePreferenceFromCookieHeader } from "../shared/theme";
 import AnnouncementBanners from "./AnnouncementBanners";
 import { appAppearanceStyle, resolveCurrentApp } from "./app-appearance";
-import { resolveRuntimeRoute, visibleNavigationApps } from "./app-navigation";
+import { resolveRuntimeRoute, visibleNavigationApps, visiblePanelProviders } from "./app-navigation";
 import { getLayoutHelp, layoutHelpFailed } from "./help";
 import LayoutFooter from "./LayoutFooter";
 import LayoutHeader from "./LayoutHeader";
 import LayoutRail, { type LayoutAppLink } from "./LayoutRail";
+import LayoutTabBar from "./LayoutTabBar";
 import type { LayoutContext } from "./layout-context";
 import { HELP_VIEW_LIMIT } from "./layout-help-start";
 import type { LayoutBreadcrumb } from "./layout-runtime";
 import PageTrailRow from "./PageTrailRow";
+import PanelSlot from "./PanelSlot";
 import { derivePageTrail } from "./page-trail";
 import { platformMessages } from "./platform-messages";
 import { sortRailApps } from "./rail-navigation";
@@ -39,8 +44,12 @@ type LayoutProps = {
   title?: string | Breadcrumb[];
   /** Up to three ids of the current app's Help articles that fit this page; Help lists them first under "For this view". Unknown ids and articles the reader may not see are ignored. */
   help?: readonly string[];
+  /** Share only the current place with the visible panel; false disables context for this document. */
+  context?: { scope?: CloudResourceRef } | false;
   fullPage?: boolean /** Keep the shell viewport-bound and suppress its footer. */;
   fullWidth?: boolean /** Delegate scrolling and clipping to the page's work surface. */;
+  /** Hide the panel slot on this page (sign-in, print, presentation, public pages). */
+  panel?: false;
   focusMode?: boolean /** Render only the app canvas and content for dedicated editors or pop-out windows. */;
   flushCanvas?: boolean /** Remove app-canvas spacing for edge-to-edge focus surfaces such as pop-out windows. */;
   /** Final localized app-specific export or printing guidance, shown when no data-print-region exists. */
@@ -155,6 +164,11 @@ export default function Layout(props: LayoutProps) {
   const lang = getLocale(c);
   const t = platformMessages.resolve([lang]).t;
   const user = c.get("user");
+  const providers = user && props.panel !== false ? visiblePanelProviders(runtime.apps, user, lang) : [];
+  const panelState = readPanelCookie(
+    providers.length ? cookie : undefined,
+    providers.map((provider) => provider.id),
+  );
   const pathname = new URL(c.req.raw.url).pathname;
   const currentRoute = resolveRuntimeRoute(runtime.apps, pathname);
   const currentApp = resolveCurrentApp(runtime.apps, pathname);
@@ -185,6 +199,7 @@ export default function Layout(props: LayoutProps) {
   const page = c.get("page") as Record<string, unknown>;
   const pageTitle = typeof title === "string" ? title : (title?.at(-1)?.title ?? appName);
   if (!page.title) page.title = pageTitle;
+  page.appAccent = currentApp?.appearance?.accent;
   const breadcrumbs: Breadcrumb[] = !title ? [{ title: appName }] : typeof title === "string" ? [{ title }] : title;
   // The way up is derived from the title array by one rule (see `derivePageTrail`). Anonymous pages keep their
   // header breadcrumbs, and focus surfaces such as pop-out editors have no way up; both show the title alone. The
@@ -207,19 +222,48 @@ export default function Layout(props: LayoutProps) {
   // keeps short and long pages at the same width where scrollbars take space.
   const mainLayoutClass = fullPage || fullWidth ? "flex flex-col" : "md:overflow-auto md:[scrollbar-gutter:stable]";
   const canvasStyle =
-    [appAppearanceStyle(currentApp?.appearance), appWorkspaceLayoutStyle(workspaceLayout), focusMode && flushCanvas ? "padding:0" : ""]
+    [
+      appAppearanceStyle(currentApp?.appearance),
+      appWorkspaceLayoutStyle(workspaceLayout),
+      panelState.widthRem !== undefined ? `--cloud-panel-width-set:${panelState.widthRem}rem` : "",
+      focusMode && flushCanvas ? "padding:0" : "",
+    ]
       .filter(Boolean)
       .join(";") || undefined;
   const appLabel = currentApp?.name ?? (pathname.startsWith("/admin") ? t.admin : undefined);
   const helpIds = new Set(registeredHelp?.documents.map((topic) => topic.id));
-  const viewHelp = [...new Set(props.help)].filter((id) => helpIds.has(id)).slice(0, HELP_VIEW_LIMIT);
+  const viewHelp = [...new Set(props.help)]
+    .filter((id) => helpIds.has(id) && id.length <= PANEL_HELP_ID_MAX_LENGTH)
+    .slice(0, HELP_VIEW_LIMIT);
+  const scope = props.context && CloudResourceRefSchema.safeParse(props.context.scope);
+  // Fail closed: a page whose place does not validate shares nothing rather than failing to render.
+  const pageContext =
+    (providers.length &&
+      props.context !== false &&
+      PanelPageContextSchema.safeParse({
+        v: 1,
+        seq: 0,
+        pageId: crypto.randomUUID(),
+        app: currentApp?.id,
+        ...(scope && scope.success ? { scope: scope.data } : {}),
+        ...(viewHelp.length ? { help: viewHelp } : {}),
+      }).data) ||
+    null;
+  const panel: ShellData["panel"] = providers.length
+    ? { providers, provider: panelState.provider ?? providers[0]?.id, context: pageContext, consent: c.get("panelConsent") }
+    : undefined;
   const shellData: ShellData = {
+    ...(panel ? { panel } : {}),
     platform: keyboardPlatform(c.req.raw.headers.get("User-Agent") ?? ""),
     ...(viewHelp.length ? { help: viewHelp } : {}),
     ...(layoutHelpFailed(c) ? { helpFailed: true as const } : {}),
     apps: allApps,
     ...(user
-      ? { rail: c.get("railPreferences") ?? defaultRailPreferences(), profile: { name: profileName, avatarSrc: profileAvatarSrc, appHref } }
+      ? {
+          rail: c.get("railPreferences") ?? defaultRailPreferences(),
+          home: resolveHomePath(settings?.app?.home_path),
+          profile: { name: profileName, avatarSrc: profileAvatarSrc, appHref },
+        }
       : {}),
     legalLinks,
     theme,
@@ -231,20 +275,27 @@ export default function Layout(props: LayoutProps) {
     return (
       <LocaleProvider locale={lang}>
         <div
-          class="cloud-app-canvas flex h-dvh w-full overflow-hidden"
+          class="cloud-app-canvas relative flex h-dvh w-full overflow-hidden"
           style={canvasStyle}
+          data-panel-transient=""
           data-app-id={currentApp?.id}
           data-app-base={currentRoute?.prefix}
           data-page-trail-title-only=""
           data-layout-full-page="true"
           data-workspace-sidebar-collapsed={workspaceLayout?.sidebarCollapsed ? "true" : undefined}
         >
-          <ShellRuntime pageTrail help={runtimeHelp} />
+          <ShellRuntime pageTrail help={runtimeHelp} panel={panel ? true : undefined} />
           <PageTrailProvider trail={pageTrail}>
-            <main class="min-h-0 min-w-0 flex-1">
+            <main class="min-h-0 min-w-0 flex-1" data-cloud-app-area="">
               <AppWorkspace.LayoutStateProvider state={workspaceLayout}>{props.children}</AppWorkspace.LayoutStateProvider>
             </main>
           </PageTrailProvider>
+          {/* Focus pages carry shell data only for their panel providers. */}
+          {panel && (
+            <ShellDataProvider data={{ panel, platform: shellData.platform, theme, apps: [], legalLinks: [], searchLinks: {} }}>
+              <PanelSlot panel={panel} state={{ ...panelState, open: false }} platform={shellData.platform} />
+            </ShellDataProvider>
+          )}
           <div data-print-fallback="">
             <p>{t.printFallbackTitle}</p>
             <p>{props.printHint ?? t.printFallbackHint}</p>
@@ -261,6 +312,7 @@ export default function Layout(props: LayoutProps) {
       <div
         class={`cloud-app-canvas relative flex w-full ${fullPage ? "h-dvh overflow-hidden" : "min-h-dvh md:h-dvh md:overflow-hidden"}`}
         style={canvasStyle}
+        data-panel={panelState.open ? "open" : undefined}
         data-app-id={currentApp?.id}
         data-app-base={currentRoute?.prefix}
         data-page-trail-title-only={titleOnly ? "" : undefined}
@@ -270,6 +322,7 @@ export default function Layout(props: LayoutProps) {
         data-workspace-sidebar-collapsed={workspaceLayout?.sidebarCollapsed ? "true" : undefined}
       >
         <ShellRuntime
+          panel={panel ? true : undefined}
           workspace={{ appId: currentApp?.id }}
           pageTrail
           focus={showRail}
@@ -284,11 +337,12 @@ export default function Layout(props: LayoutProps) {
           banners={user && announcements?.banners.length ? true : undefined}
         />
         <ShellDataProvider data={shellData}>
-          {showRail && <LayoutRail currentPath={requestPath(c)} />}
+          {showRail && <LayoutRail currentPath={requestPath(c)} panelOpen={panel ? panelState.open : undefined} />}
           {showRail && <ShellFocusToggle variant="float" />}
           {showRail && <div class="cloud-shell-reveal" data-cloud-shell-reveal="" aria-hidden="true" />}
-          <div class="layout-shell-content flex min-h-0 min-w-0 flex-1 flex-col">
+          <div class="layout-shell-content flex min-h-0 min-w-0 flex-1 flex-col" data-cloud-app-area="">
             <LayoutHeader
+              panelOpen={panel ? panelState.open : undefined}
               authenticated={showRail}
               title={appLabel ?? breadcrumbs.at(-1)?.title}
               launchpad={!!(user || appLabel)}
@@ -305,6 +359,8 @@ export default function Layout(props: LayoutProps) {
             </PageTrailProvider>
             {!fullPage && !showRail && <LayoutFooter appName={settings?.app?.copyright || appName} legalLinks={legalLinks} />}
           </div>
+          {panel && <PanelSlot panel={panel} state={panelState} platform={shellData.platform} />}
+          {showRail && <LayoutTabBar currentPath={requestPath(c)} />}
         </ShellDataProvider>
         <div data-print-fallback="">
           <p>{t.printFallbackTitle}</p>

package/src/ssr/LayoutHeader.tsx

@@ -5,6 +5,7 @@ import { platformMessages } from "./platform-messages";
 
 type LayoutHeaderProps = {
   authenticated: boolean;
+  panelOpen?: boolean;
   title?: string;
   launchpad: boolean;
   breadcrumbs?: LayoutBreadcrumb[];
@@ -14,10 +15,12 @@ type LayoutHeaderProps = {
  * Phones (below `md`) always get this header. From `md` it remains only on
  * anonymous pages; signed-in people reach Home, search, help, the app grid,
  * and their profile through the rail, so the app area starts at the top edge.
- * Anonymous pages have no rail: up to `lg` their header keeps the app name,
- * help, search, and the app grid, and from `lg` it shows the breadcrumbs.
- * Home and Sign in stay server markup, so focus on them survives the shell's
- * mount; the shell renders the title and the controls between them.
+ * On a signed-in phone it is the title row on the app gradient: Home moves to
+ * the bottom bar's Start, so the row holds the title, search, help, and the
+ * app menu. Anonymous pages have no rail: up to `lg` their header keeps Home,
+ * the app name, help, search, and the app grid, and from `lg` it shows the
+ * breadcrumbs. Home and Sign in stay server markup, so focus on them survives
+ * the shell's mount; the shell renders the title and the controls between them.
  */
 export default function LayoutHeader(props: LayoutHeaderProps) {
   const locale = useLocale();
@@ -29,13 +32,16 @@ export default function LayoutHeader(props: LayoutHeaderProps) {
     >
       {/* A long title must not squeeze the button; `shrink-0` sits on a wrapper because the button's own
           styles would win over a utility on the link. */}
-      <div class="flex shrink-0">
-        <IconButtonLink href="/" label={t().home}>
-          <img src="/branding/logo" alt="" class={props.authenticated ? "h-4 w-4" : "h-6 w-6"} />
-        </IconButtonLink>
-      </div>
+      {!props.authenticated && (
+        <div class="flex shrink-0">
+          <IconButtonLink href="/" label={t().home}>
+            <img src="/branding/logo" alt="" class="h-6 w-6" />
+          </IconButtonLink>
+        </div>
+      )}
       <CloudShell
         slot="header"
+        panelOpen={props.panelOpen}
         authenticated={props.authenticated}
         title={props.title}
         launchpad={props.launchpad}

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

@@ -75,6 +75,8 @@ window.fetch = Object.assign(
       const ids = params.has("start")
         ? documents.filter((document) => document.title.toLocaleLowerCase().includes(query)).map((document) => document.id)
         : ["topic-0", "topic-1"];
+      // Tests wait for an answered search by this count, not for a spinner that can come and go between two polls (#1403).
+      document.documentElement.dataset.helpSearches = String(Number(document.documentElement.dataset.helpSearches ?? 0) + 1);
       return Response.json({ locale: "en", ids });
     }
     const id = path.split("/").at(-1) ?? "topic-0";