@k2b/cloud 0.37.0 → 0.39.0

package/src/ssr/layout-help-navigation.ts

@@ -1,19 +1,7 @@
-import type { HelpDocumentManifest } from "@k2b/cloud/shared";
-
 type HelpArticleSession = { articleScrollTop: number };
 type HelpArticleScroller = { scrollTop: number };
 type HelpArticleHeading = { focus: (options?: FocusOptions) => void };
 
-export const adjacentHelpDocuments = (documents: readonly HelpDocumentManifest[], activeId: string | null) => {
-  const index = documents.findIndex((document) => document.id === activeId);
-  if (index < 0) return { previous: null, next: null };
-
-  return {
-    previous: documents[index - 1] ?? null,
-    next: documents[index + 1] ?? null,
-  };
-};
-
 export const resetHelpArticleScroll = (session: HelpArticleSession, scroller?: HelpArticleScroller) => {
   session.articleScrollTop = 0;
   if (scroller) scroller.scrollTop = 0;

package/src/ssr/layout-help-registry.tsx

@@ -1,20 +1,13 @@
 import type { HelpDocumentManifest } from "@k2b/cloud/shared";
-import { type JSX, onCleanup, onMount } from "solid-js";
-
-type HelpTopicBase = {
-  id: string;
-  title: string;
-  icon?: string;
-  description?: string;
-  order?: number;
-};
+import { onCleanup, onMount } from "solid-js";
 
 export type LayoutHelpDocumentsProps = {
   documents: readonly HelpDocumentManifest[];
   /** Canonical standalone Help route owned by the current app. */
   pageBase: string;
 };
-export type HelpTopic = (HelpTopicBase & { kind: "content"; children: JSX.Element }) | (HelpDocumentManifest & { kind: "document" });
+/** One article of the current app's Help, as the page registered it. */
+export type HelpTopic = HelpDocumentManifest;
 
 export const HELP_TOPICS_EVENT = "cloud:layout-help-topics";
 
@@ -50,7 +43,7 @@ export function LayoutHelpDocuments(props: LayoutHelpDocumentsProps) {
     // Cleanup runs while this unmounts, when a parent `<Show>` may already have dropped the props' source.
     const pageBase = props.pageBase;
     window.__cloudLayoutHelpPageBase = pageBase;
-    const disposers = props.documents.map((document) => registerTopic({ ...document, kind: "document" }));
+    const disposers = props.documents.map((document) => registerTopic(document));
     onCleanup(() => {
       disposers.forEach((dispose) => dispose());
       if (window.__cloudLayoutHelpPageBase === pageBase) delete window.__cloudLayoutHelpPageBase;

package/src/ssr/layout-help-search.ts

@@ -1,15 +1,12 @@
-type SearchTopic = { id: string; title: string; description?: string; kind: "document" | "content" };
+type SearchTopic = { id: string; title: string; description?: string };
 
-/** Use server ranking for documents; metadata remains usable during loading or outages. */
+/** Use server ranking for articles; metadata matches remain usable during loading or outages. */
 export const searchHelpTopics = <T extends SearchTopic>(topics: readonly T[], query: string, remoteIds: readonly string[] | null): T[] => {
-  const local = topics.filter((topic) => [topic.title, topic.description].some((part) => part?.toLocaleLowerCase().includes(query)));
-  if (remoteIds === null) return local;
-  const documents = new Map(topics.filter((topic) => topic.kind === "document").map((topic) => [topic.id, topic]));
-  return [
-    ...remoteIds.flatMap((id) => {
-      const topic = documents.get(id);
-      return topic ? [topic] : [];
-    }),
-    ...local.filter((topic) => topic.kind === "content"),
-  ];
+  if (remoteIds === null)
+    return topics.filter((topic) => [topic.title, topic.description].some((part) => part?.toLocaleLowerCase().includes(query)));
+  const byId = new Map(topics.map((topic) => [topic.id, topic]));
+  return remoteIds.flatMap((id) => {
+    const topic = byId.get(id);
+    return topic ? [topic] : [];
+  });
 };

package/src/ssr/layout-help-start.ts

@@ -0,0 +1,68 @@
+import type { HelpKind } from "../shared/help";
+import { SHELL_SHORTCUT_ORDER } from "./shell-shortcuts";
+
+/** The concept asks for at most eight tasks as tiles; more task articles follow as a list. */
+export const HELP_START_TILE_LIMIT = 8;
+/** "For this view" shows two or three articles the page names. */
+export const HELP_VIEW_LIMIT = 3;
+export const HELP_START_GROUP_KINDS = ["start", "reference", "troubleshoot"] as const;
+export type HelpStartGroupKind = (typeof HELP_START_GROUP_KINDS)[number];
+export type HelpStartTopic = { id: string; title: string; order?: number; kind?: HelpKind };
+export type HelpStart<T> = {
+  /** Declared ids in declared order: only ids of known topics, without duplicates, at most HELP_VIEW_LIMIT. */
+  view: T[];
+  /** Articles of kind task (missing kind = task), by order (missing = 100) then title, at most HELP_START_TILE_LIMIT. */
+  tiles: T[];
+  /** The remaining task articles in the same order, so no task becomes unreachable. */
+  moreTasks: T[];
+  /** Fixed order start, reference, troubleshoot; a kind without articles is absent. Each list sorted like tiles. */
+  groups: { kind: HelpStartGroupKind; topics: T[] }[];
+};
+
+export const helpStart = <T extends HelpStartTopic>(topics: readonly T[], viewIds: readonly string[] = []): HelpStart<T> => {
+  const byId = new Map(topics.map((topic) => [topic.id, topic]));
+  const view = [...new Set(viewIds)]
+    .flatMap((id) => {
+      const topic = byId.get(id);
+      return topic ? [topic] : [];
+    })
+    .slice(0, HELP_VIEW_LIMIT);
+  const sorted = [...topics].sort((a, b) => (a.order ?? 100) - (b.order ?? 100) || a.title.localeCompare(b.title));
+  const tasks = sorted.filter((topic) => (topic.kind ?? "task") === "task");
+  return {
+    view,
+    tiles: tasks.slice(0, HELP_START_TILE_LIMIT),
+    moreTasks: tasks.slice(HELP_START_TILE_LIMIT),
+    groups: HELP_START_GROUP_KINDS.flatMap((kind) => {
+      const topics = sorted.filter((topic) => topic.kind === kind);
+      return topics.length ? [{ kind, topics }] : [];
+    }),
+  };
+};
+
+export type HelpShortcutScope = "everywhere" | "app" | "selection";
+export type HelpShortcutCommand = { id: string; title: string; description?: string; shortcut?: string; scope?: "selection" | "page" };
+/**
+ * Group commands with a shortcut: scope "selection" -> "selection"; id starting with "cloud." -> "everywhere"; the rest -> "app".
+ * Group order everywhere, app, selection; empty groups are absent. Inside "everywhere", the ids of SHELL_SHORTCUT_ORDER come first in that
+ * order (so rows rendered on the server keep their place when the browser adds more), then the rest in input order; other groups keep input order.
+ * Commands without a shortcut are dropped.
+ */
+export const helpShortcutGroups = <T extends HelpShortcutCommand>(
+  commands: readonly T[],
+): { scope: HelpShortcutScope; shortcuts: (T & { shortcut: string })[] }[] => {
+  const groups: Record<HelpShortcutScope, (T & { shortcut: string })[]> = { everywhere: [], app: [], selection: [] };
+  for (const command of commands) {
+    if (!command.shortcut) continue;
+    const scope = command.scope === "selection" ? "selection" : command.id.startsWith("cloud.") ? "everywhere" : "app";
+    groups[scope].push({ ...command, shortcut: command.shortcut });
+  }
+  const rank = (id: string) => {
+    const index = SHELL_SHORTCUT_ORDER.findIndex((shellId) => shellId === id);
+    return index < 0 ? SHELL_SHORTCUT_ORDER.length : index;
+  };
+  groups.everywhere.sort((a, b) => rank(a.id) - rank(b.id));
+  return (["everywhere", "app", "selection"] as const).flatMap((scope) =>
+    groups[scope].length ? [{ scope, shortcuts: groups[scope] }] : [],
+  );
+};

package/src/ssr/panel-slot.browser-harness.tsx

@@ -0,0 +1,110 @@
+import { AppWorkspace } from "@k2b/ui";
+import { Hono } from "hono";
+import { defineApp } from "../_internal/define-app";
+import { person } from "../_internal/define-app.test-fixture";
+import type { RuntimeAppMeta } from "../contracts/app";
+import type { User } from "../contracts/shared";
+import Layout from "./Layout";
+import PanelLayout from "./PanelLayout";
+import type { RuntimeContext } from "./runtime";
+
+const apps: RuntimeAppMeta[] = ["fixture", "second"].map((id) => ({
+  id,
+  name: id === "fixture" ? "Fixture" : "Second",
+  icon: "ti ti-box",
+  description: "Panel browser fixture",
+  routes: [`/app/${id}`],
+  nav: { href: `/app/${id}`, section: "primary" },
+  panel: { href: `/app/${id}/panel`, label: id === "fixture" ? "Fixture" : "Second", icon: "ti ti-box" },
+}));
+const probe = defineApp({
+  id: "fixture",
+  name: "Fixture",
+  icon: "ti ti-box",
+  description: "Panel browser fixture",
+  baseUrl: "http://fixture:3000",
+  routes: ["/app/fixture", "/app/second"],
+});
+type Environment = { Variables: { runtime: RuntimeContext; user: User } };
+export const server = new Hono<Environment>()
+  .use(async (c, next) => {
+    c.set("runtime", { apps });
+    c.set("user", person);
+    await next();
+  })
+  .get(
+    "/app/:provider/panel",
+    ...probe.ssr<Environment>((c) => () => (
+      <PanelLayout c={c} title="Fixture panel">
+        <label>
+          Panel input
+          <input aria-label="Panel input" />
+        </label>
+        <button type="button" id="prevent-escape">
+          Keep Escape
+        </button>
+        <a href="/app/fixture/next" id="leave-panel">
+          Open in the app
+        </a>
+      </PanelLayout>
+    )),
+  )
+  .get(
+    "/app/fixture/long",
+    ...probe.ssr<Environment>((c) => () => (
+      <Layout c={c} title="Long fixture">
+        <button type="button" id="open-panel">
+          Open fixture
+        </button>
+        <button type="button" id="open-silent-panel">
+          Open silent fixture
+        </button>
+        <div style="height:150vh">Long content</div>
+        <p id="last-row">Last row</p>
+      </Layout>
+    )),
+  )
+  .get(
+    "/app/fixture/:page?",
+    ...probe.ssr<Environment>((c) => () => (
+      <Layout c={c} fullWidth fullPage title="Panel fixture">
+        <AppWorkspace mobileSurface="flush" class="min-h-0 flex-1">
+          <AppWorkspace.Sidebar id="panel-navigation" label="Navigation">
+            <AppWorkspace.SidebarDesktop>
+              <AppWorkspace.SidebarItem href="/app/fixture" active>
+                Workspace
+              </AppWorkspace.SidebarItem>
+            </AppWorkspace.SidebarDesktop>
+          </AppWorkspace.Sidebar>
+          <AppWorkspace.Content>
+            <AppWorkspace.Main>
+              <button type="button" id="open-panel">
+                Open fixture
+              </button>
+              <button type="button" id="open-silent-panel">
+                Open silent fixture
+              </button>
+              <a href="/app/fixture/next" id="next-page">
+                Next page
+              </a>
+              <textarea aria-label="App editor" />
+            </AppWorkspace.Main>
+            <AppWorkspace.Detail id="panel-fixture-detail" width="lg" open>
+              <h2>Selected item</h2>
+              <button type="button" data-workspace-detail-close>
+                Close detail
+              </button>
+            </AppWorkspace.Detail>
+          </AppWorkspace.Content>
+        </AppWorkspace>
+      </Layout>
+    )),
+  );
+
+/** Runs inline during parsing and again immediately after mounting the real runtime. */
+export function panelGeometry() {
+  return [".layout-shell-content", "#cloud-panel", ".k2b-app-workspace"].map((selector) => {
+    const rect = document.querySelector(selector)?.getBoundingClientRect();
+    return rect && { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+  });
+}

package/src/ssr/platform-messages.ts

@@ -4,6 +4,23 @@ export const platformMessages = i18n.define({
   baseLocale: "en",
   messages: {
     en: {
+      panel: "Panel",
+      panels: "Panels",
+      openPanel: "Open panel",
+      closePanel: "Close panel",
+      togglePanel: "Open or close the panel",
+      togglePanelDescription: "Shows a panel beside the app.",
+      panelShortcut: ({ mod }: { mod: string }) => `Panel (${mod}J)`,
+      resizePanel: "Resize panel",
+      releaseClosesPanel: "Release to close the panel",
+      panelLoadFailed: "The panel did not load",
+      panelNotResponding: ({ label }: { label: string }) => `${label} is not responding.`,
+      retry: "Try again",
+      panelLoading: ({ label }: { label: string }) => `${label} is loading`,
+      enlargePanel: "Enlarge panel",
+      shrinkPanel: "Shrink panel",
+      printFallbackTitle: "This view does not print well.",
+      printFallbackHint: "Open the item you want to print, or use the app's export.",
       admin: "Admin",
       platformAdministration: "Platform administration.",
       start: "Start",
@@ -76,6 +93,23 @@ export const platformMessages = i18n.define({
       clearSearch: "Clear search",
     },
     de: {
+      panel: "Panel",
+      panels: "Panels",
+      openPanel: "Panel öffnen",
+      closePanel: "Panel schließen",
+      togglePanel: "Panel öffnen oder schließen",
+      togglePanelDescription: "Zeigt ein Panel neben der App.",
+      panelShortcut: ({ mod }: { mod: string }) => `Panel (${mod}J)`,
+      resizePanel: "Panelbreite ändern",
+      releaseClosesPanel: "Loslassen schließt das Panel",
+      panelLoadFailed: "Das Panel lädt nicht",
+      panelNotResponding: ({ label }: { label: string }) => `${label} antwortet nicht.`,
+      retry: "Erneut versuchen",
+      panelLoading: ({ label }: { label: string }) => `${label} lädt`,
+      enlargePanel: "Panel vergrößern",
+      shrinkPanel: "Panel verkleinern",
+      printFallbackTitle: "Diese Ansicht lässt sich nicht gut drucken.",
+      printFallbackHint: "Öffne den Eintrag, den du drucken möchtest, oder nutze den Export der App.",
       admin: "Administration",
       platformAdministration: "Plattform verwalten.",
       start: "Start",

package/src/ssr/rail-navigation.ts

@@ -1,3 +1,4 @@
+import type { TabBarItem } from "@k2b/ui";
 import type { RailPreferences, RailSnapshot } from "../contracts/rail-preferences";
 import { helpPageAppId } from "./layout-help-url";
 
@@ -66,3 +67,46 @@ export const railLinkActive = (link: RailLink, currentPath: string): boolean =>
     (target.pathname !== "/" && current.pathname.startsWith(`${target.pathname.replace(/\/$/, "")}/`))
   );
 };
+
+/**
+ * The phone bar's apps: the rail's links in the person's order, at most `limit`. The current page's link stays in the
+ * bar; when it comes later in the rail, it takes the last place, so the bar always marks where the person is.
+ */
+export const phoneBarLinks = (navigation: { shortcuts: RailLink[]; apps: RailLink[] }, currentPath: string, limit: number): RailLink[] => {
+  const links = [...navigation.shortcuts, ...navigation.apps];
+  const current = links.findIndex((link) => railLinkActive(link, currentPath));
+  if (current < limit) return links.slice(0, limit);
+  return [...links.slice(0, limit - 1), links[current]!];
+};
+
+/** Start and four apps fill the phone bar's five places. */
+const PHONE_BAR_APPS = 4;
+
+const underPath = (pathname: string, path: string) => pathname === path || pathname.startsWith(`${path.replace(/\/$/, "")}/`);
+
+/**
+ * The phone bar: Home, then the person's first apps in their rail order. Home leads to `/`, which opens the
+ * installation's start page (`home`), so it is the open item on `/` and on that start page, unless an app in the bar
+ * is open there.
+ */
+export const phoneBarItems = (
+  navigation: { shortcuts: RailLink[]; apps: RailLink[] },
+  currentPath: string,
+  home: { label: string; path: string },
+): TabBarItem[] => {
+  const links = phoneBarLinks(navigation, currentPath, PHONE_BAR_APPS);
+  const items = links.map((link) => ({
+    id: link.id,
+    label: link.label,
+    icon: link.iconClass,
+    href: link.href,
+    current: railLinkActive(link, currentPath),
+  }));
+  const pathname = new URL(currentPath, "https://cloud.invalid").pathname;
+  const start = new URL(home.path, "https://cloud.invalid").pathname;
+  const atHome = pathname === "/" || (!items.some((item) => item.current) && underPath(pathname, start));
+  return [
+    { id: "home", label: home.label, icon: "ti ti-home", href: "/", current: atHome },
+    ...items.map((item) => ({ ...item, current: !atHome && item.current })),
+  ];
+};

package/src/ssr/shell-data.tsx

@@ -1,15 +1,20 @@
+import type { KeyboardPlatform } from "@k2b/ui";
 import { createContext, type JSX, useContext } from "solid-js";
 import type { AppSearchLink } from "../contracts/app";
 import type { RailSnapshot } from "../contracts/rail-preferences";
 import type { CloudThemePreference } from "../shared/theme";
 import type { AppLaunchpadLegalLink } from "./app-launchpad";
+import type { PanelProvider } from "./app-navigation";
 import type { RailApp } from "./rail-navigation";
 
 export type ShellData = {
+  panel?: { providers: PanelProvider[]; provider?: string };
   /** The authorized navigation catalog, sorted for the request locale: the rail, the app grid and the phone menu show it. */
   apps: RailApp[];
   /** Signed-in pages: the person's rail preferences. */
   rail?: RailSnapshot;
+  /** Signed-in pages: the start page that `/` opens, for the phone bar's Home. */
+  home?: string;
   legalLinks: AppLaunchpadLegalLink[];
   /** Signed-in pages: the person, for the profile menu and the phone menu's profile actions. */
   profile?: { name: string; avatarSrc?: string; appHref?: string };
@@ -20,6 +25,12 @@ export type ShellData = {
   searchLinks: Record<string, readonly AppSearchLink[]>;
   /** The current app, for links inside its Help. */
   appId?: string;
+  /** The reader's keyboard platform, resolved from the request User-Agent for server-rendered key caps. */
+  platform?: KeyboardPlatform;
+  /** "For this view" article ids, already filtered for the reader. */
+  help?: string[];
+  /** The current app's Help metadata could not be read for this request; Help offers a reload. */
+  helpFailed?: true;
 };
 
 const ShellDataContext = createContext<() => ShellData>();

package/src/ssr/shell-shortcuts.ts

@@ -0,0 +1,19 @@
+import type { platformMessages } from "./platform-messages";
+
+export const SHELL_SHORTCUT_ORDER = ["cloud.search", "cloud.help", "cloud.panel"] as const;
+/** The shell's always-present shortcuts, without their actions; ShellRuntime adds the actions, Help renders them before the browser reports commands. */
+export const shellShortcuts = (t: ReturnType<typeof platformMessages.resolve>["t"], options: { panel?: boolean } = {}) => [
+  { id: "cloud.search", title: t.openGlobalSearch, description: t.globalSearchDescription, icon: "ti ti-search", shortcut: "mod+k" },
+  { id: "cloud.help", title: t.openShortcutHelp, description: t.shortcutHelpDescription, icon: "ti ti-help-circle", shortcut: "shift+/" },
+  ...(options.panel
+    ? [
+        {
+          id: "cloud.panel",
+          title: t.togglePanel,
+          description: t.togglePanelDescription,
+          icon: "ti ti-layout-sidebar-right",
+          shortcut: "mod+j",
+        },
+      ]
+    : []),
+];