@k2b/cloud 0.36.0 → 0.38.0

package/src/ssr/Layout.tsx

@@ -1,7 +1,8 @@
 import type { DateContext } from "@k2b/stdlib";
-import { AppWorkspace, appWorkspaceLayoutStyle, LocaleProvider, NoticeCard, PageTrailProvider } from "@k2b/ui";
+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 { readShellFocusCookie } from "../_internal/shell-focus";
 import { resolveNavMatch } from "../contracts/app"; // ==========================
 import { isPwaShellAvailable } from "../contracts/pwa";
 import { defaultRailPreferences } from "../contracts/rail-preferences";
@@ -13,11 +14,12 @@ import { readThemePreferenceFromCookieHeader } from "../shared/theme";
 import AnnouncementBanners from "./AnnouncementBanners";
 import { appAppearanceStyle, resolveCurrentApp } from "./app-appearance";
 import { resolveRuntimeRoute, visibleNavigationApps } from "./app-navigation";
-import { getLayoutHelp } from "./help";
+import { getLayoutHelp, layoutHelpFailed } from "./help";
 import LayoutFooter from "./LayoutFooter";
 import LayoutHeader from "./LayoutHeader";
 import LayoutRail, { type LayoutAppLink } from "./LayoutRail";
 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 { derivePageTrail } from "./page-trail";
@@ -25,6 +27,7 @@ import { platformMessages } from "./platform-messages";
 import { sortRailApps } from "./rail-navigation";
 import { requestPath } from "./request-path";
 import { getLocalizedRuntimeContext, type RuntimeContext } from "./runtime";
+import ShellFocusToggle from "./ShellFocusToggle";
 import ShellRuntime from "./ShellRuntime.island";
 import { type ShellData, ShellDataProvider } from "./shell-data";
 
@@ -34,10 +37,14 @@ type LayoutProps = {
   children: JSX.Element;
   c: LayoutContext;
   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[];
   fullPage?: boolean /** Keep the shell viewport-bound and suppress its footer. */;
   fullWidth?: boolean /** Delegate scrolling and clipping to the page's work surface. */;
   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. */
+  printHint?: string;
   workspaceSidebarCollapsible?: boolean /** Resolve persisted sidebar geometry for the page's sidebar policy during SSR. */;
 }; // ==========================
 // Helpers
@@ -187,6 +194,8 @@ export default function Layout(props: LayoutProps) {
     ? { title: pageTitle, ancestors: [] }
     : derivePageTrail(title ?? appName, currentRoute?.prefix, appName, `${pathname}${new URL(c.req.raw.url).search}`);
   const showRail = !!user;
+  // The app bar and the app's navigation hidden with Cmd/Ctrl+\ or the sidebar buttons; phones ignore it in CSS.
+  const shellFocus = showRail && readShellFocusCookie(cookie);
   // The profile menu offers the mobile app only while the installation runs it.
   const appHref = user && isPwaShellAvailable(runtime.apps) ? "/me/app" : undefined;
   const profileName = user?.displayName || user?.uid || "?";
@@ -202,7 +211,12 @@ export default function Layout(props: LayoutProps) {
       .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 shellData: ShellData = {
+    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 } }
@@ -231,6 +245,10 @@ export default function Layout(props: LayoutProps) {
               <AppWorkspace.LayoutStateProvider state={workspaceLayout}>{props.children}</AppWorkspace.LayoutStateProvider>
             </main>
           </PageTrailProvider>
+          <div data-print-fallback="">
+            <p>{t.printFallbackTitle}</p>
+            <p>{props.printHint ?? t.printFallbackHint}</p>
+          </div>
         </div>
       </LocaleProvider>
     );
@@ -248,11 +266,13 @@ export default function Layout(props: LayoutProps) {
         data-page-trail-title-only={titleOnly ? "" : undefined}
         data-layout-full-page={fullPage ? "true" : undefined}
         data-layout-authenticated={showRail ? "true" : undefined}
+        data-shell-focus={shellFocus ? "true" : undefined}
         data-workspace-sidebar-collapsed={workspaceLayout?.sidebarCollapsed ? "true" : undefined}
       >
         <ShellRuntime
           workspace={{ appId: currentApp?.id }}
           pageTrail
+          focus={showRail}
           help={runtimeHelp}
           commands={{ searchResources: !!user }}
           push={!!user}
@@ -265,6 +285,8 @@ export default function Layout(props: LayoutProps) {
         />
         <ShellDataProvider data={shellData}>
           {showRail && <LayoutRail currentPath={requestPath(c)} />}
+          {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">
             <LayoutHeader
               authenticated={showRail}
@@ -284,6 +306,10 @@ export default function Layout(props: LayoutProps) {
             {!fullPage && !showRail && <LayoutFooter appName={settings?.app?.copyright || appName} legalLinks={legalLinks} />}
           </div>
         </ShellDataProvider>
+        <div data-print-fallback="">
+          <p>{t.printFallbackTitle}</p>
+          <p>{props.printHint ?? t.printFallbackHint}</p>
+        </div>
       </div>
     </LocaleProvider>
   );

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

@@ -1,43 +1,146 @@
-import { LocaleProvider } from "@k2b/ui";
+import { AppWorkspace, LocaleProvider } from "@k2b/ui";
 import { render } from "solid-js/web";
+import { registerContextAwareCommand } from "../browser/command-bridge";
 import type { HelpDocumentManifest, HelpDocumentPayload } from "../shared/help";
-import { LayoutHelpPage } from "./LayoutHelp";
+import { LayoutHelpPage, openLayoutHelpDialog } from "./LayoutHelp";
+import { registry } from "./layout-help-registry";
 
-const documents: HelpDocumentManifest[] = Array.from({ length: 8 }, (_, index) => ({
-  id: `topic-${index}`,
-  title: `Topic ${index}`,
+const params = new URL(location.href).searchParams;
+const fixture = (id: string, title: string, order: number, kind?: HelpDocumentManifest["kind"], icon?: string): HelpDocumentManifest => ({
+  id,
+  title,
   description: "Help browser fixture",
-  order: index,
-  url: `/api/help/topic-${index}`,
+  order,
+  ...(kind ? { kind } : {}),
+  ...(icon ? { icon } : {}),
+  url: `/api/help/${id}`,
   searchUrl: "/api/help/search",
-}));
-const html = Array.from(
-  { length: 8 },
-  (_, index) =>
-    `<h2 id="section-${index}" class="help-section-title" data-help-icon="ti ti-point">Section ${index}</h2>${Array.from({ length: 18 }, () => "<p>Read this guidance to finish the task and understand how the app works.</p>").join("")}`,
-).join("");
+});
+// `?start`: an app with every kind and more tasks than the start shows as tiles.
+const startDocuments: HelpDocumentManifest[] = [
+  fixture("share-space", "Share a Space", 10, "task", "ti ti-share"),
+  fixture("claim-task", "Claim a task", 20, "task", "ti ti-hand-grab"),
+  fixture("statuses", "Create and order statuses", 30, "task", "ti ti-arrows-sort"),
+  fixture("calendar-feed", "See dates in your own calendar", 40, "task", "ti ti-calendar-share"),
+  fixture("templates", "Start from a template", 50, undefined, "ti ti-template"),
+  fixture("filters", "Filter and find items", 60, "task", "ti ti-filter"),
+  fixture("handoffs", "Hand work over", 70, "task", "ti ti-arrows-exchange"),
+  fixture("archive", "Archive a Space", 80, "task", "ti ti-archive"),
+  fixture("import", "Import tasks from a spreadsheet with a very long title that wraps", 90, "task", "ti ti-table-import"),
+  fixture("recurring", "Repeat a task", 100, "task", "ti ti-repeat"),
+  fixture("start", "Start with Spaces", 5, "start", "ti ti-rocket"),
+  fixture("access-levels", "Access levels", 110, "reference", "ti ti-key"),
+  fixture("troubleshoot", "Fix problems in Spaces", 120, "troubleshoot", "ti ti-lifebuoy"),
+];
+const documents: HelpDocumentManifest[] = params.has("start")
+  ? startDocuments
+  : Array.from({ length: 8 }, (_, index) => fixture(`topic-${index}`, `Topic ${index}`, index));
+// `?commands`: what the shell and an app register on a real page.
+if (params.has("commands")) {
+  for (const command of [
+    { id: "cloud.shell.focus", title: "Hide sidebar", description: "", shortcut: "mod+\\" },
+    { id: "cloud.search", title: "Open global search", description: "", shortcut: "mod+k" },
+    { id: "cloud.help", title: "Open shortcut help", description: "", shortcut: "shift+/" },
+    { id: "spaces.new", title: "New task", description: "", shortcut: "n" },
+    { id: "spaces.filter", title: "Filter tasks", description: "", shortcut: "f" },
+    { id: "spaces.complete", title: "Complete selected", description: "", shortcut: "x", scope: "selection" as const },
+  ])
+    registerContextAwareCommand({ ...command, action: () => {} });
+}
+const lead = "<p>Share a Space so that other people can see and change its tasks.</p>";
+const longHtml =
+  lead +
+  Array.from(
+    { length: 8 },
+    (_, index) =>
+      `<h2 id="section-${index}" class="help-section-title">Section ${index}</h2>${Array.from({ length: 18 }, () => "<p>Read this guidance to finish the task and understand how the app works.</p>").join("")}`,
+  ).join("");
+// A short task article: the short answer, one section, four steps.
+const taskHtml = `${lead}<h2 id="invite-people" class="help-section-title">Invite people</h2><div class="help-steps"><ol class="k2b-steps"><li>Open <span class="k2b-label-chip">Space settings</span>.</li><li>Choose <span class="k2b-label-chip">Add person</span>.</li><li>Enter a name or a group.</li><li>Choose the access level.</li></ol></div><p>Spaces saves the change at once.</p><div class="help-compare"><ul><li><strong>Add a person</strong> Gives one named person access to every task in this Space.</li><li><strong>Add a group</strong> Gives everyone in the group access, including people who join later.</li></ul></div>`;
+const link = (id: string, title: string, appId = "spaces", appName = "Spaces") => ({
+  appId,
+  appName,
+  accent: appId === "spaces" ? "#16a34a" : "#2563eb",
+  documentId: id,
+  title,
+  description: "Help browser fixture",
+  url: `/help/apps/${appId}/${id}`,
+});
 window.fetch = Object.assign(
   async (input: URL | RequestInfo) => {
     await new Promise((resolve) => setTimeout(resolve, 80));
     const path = String(input);
-    if (path.includes("/search")) return Response.json({ locale: "en", ids: ["topic-0", "topic-1"] });
+    if (path.includes("/search")) {
+      const query = new URL(path, location.href).searchParams.get("q") ?? "";
+      const ids = params.has("start")
+        ? documents.filter((document) => document.title.toLocaleLowerCase().includes(query)).map((document) => document.id)
+        : ["topic-0", "topic-1"];
+      return Response.json({ locale: "en", ids });
+    }
     const id = path.split("/").at(-1) ?? "topic-0";
-    const payload: HelpDocumentPayload = { id, locale: "en", title: id, markdown: "Help", html };
+    const payload: HelpDocumentPayload = {
+      id,
+      locale: "en",
+      title: id,
+      markdown: "Help",
+      html: id === "topic-1" ? taskHtml : longHtml,
+      kind: "task",
+      needs: "manage",
+      next: link("topic-2", "Topic 2"),
+      related: [link("topic-3", "Topic 3"), link("mail-share", "Share a mailbox", "mail", "Mail")],
+    };
     return Response.json(payload);
   },
   { preconnect: () => {} },
 );
 const main = document.querySelector<HTMLElement>(".layout-content-main");
 if (!main) throw new Error("Missing Layout main");
-const embedded = new URL(location.href).searchParams.has("embedded");
-const host = document.createElement("div");
-if (embedded) host.style.cssText = "width:360px;height:700px";
-main.append(host);
-render(
-  () => (
-    <LocaleProvider locale="en">
-      <LayoutHelpPage documents={documents} embedded={embedded} pageBase="/app/spaces/help" />
-    </LocaleProvider>
-  ),
-  host,
-);
+const embedded = params.has("embedded");
+const referenceHost = params.get("host");
+if (referenceHost === "grids" || referenceHost === "pulse") {
+  // The Grids and Pulse query reference windows: one article beside the reference sidebar, without the Cloud shell.
+  const host = document.createElement("div");
+  host.className = "h-dvh";
+  document.body.replaceChildren(host);
+  const reader = () => <LayoutHelpPage documents={documents.slice(0, 1)} initialTopic="topic-0" includeShortcuts={false} embedded />;
+  render(
+    () => (
+      <LocaleProvider locale="en">
+        <AppWorkspace>
+          <AppWorkspace.Sidebar>
+            <AppWorkspace.SidebarDesktop>
+              <AppWorkspace.SidebarBody>Reference</AppWorkspace.SidebarBody>
+            </AppWorkspace.SidebarDesktop>
+          </AppWorkspace.Sidebar>
+          <AppWorkspace.Content>
+            {referenceHost === "grids" ? (
+              <AppWorkspace.Main class="p-[var(--ui-space-shell)]" scroll={false}>
+                <div class="flex min-h-0 flex-1 flex-col overflow-auto">{reader()}</div>
+              </AppWorkspace.Main>
+            ) : (
+              <AppWorkspace.Main class="overflow-y-auto">{reader()}</AppWorkspace.Main>
+            )}
+          </AppWorkspace.Content>
+        </AppWorkspace>
+      </LocaleProvider>
+    ),
+    host,
+  );
+} else if (params.has("modal")) {
+  // The dialog reads the topics the page registered, as Layout.HelpDocuments does.
+  for (const manifest of documents) registry()?.set(manifest.id, manifest);
+  window.__cloudLayoutHelpPageBase = "/app/spaces/help";
+  openLayoutHelpDialog();
+} else {
+  const host = document.createElement("div");
+  if (embedded) host.style.cssText = "width:360px;height:700px";
+  main.append(host);
+  render(
+    () => (
+      <LocaleProvider locale="en">
+        <LayoutHelpPage documents={documents} embedded={embedded} pageBase="/app/spaces/help" />
+      </LocaleProvider>
+    ),
+    host,
+  );
+}