@k2b/cloud 0.37.0 → 0.38.0

package/src/ssr/ShellRuntime.island.tsx

@@ -2,6 +2,7 @@ import type { HelpDocumentManifest } from "@k2b/cloud/shared";
 import {
   followPageTrail,
   installAppWorkspaceController,
+  installInputModeController,
   installPageTitleController,
   serializeAppWorkspaceLayoutState,
   useLocale,
@@ -27,6 +28,7 @@ import { LayoutHelpDocuments } from "./layout-help-registry";
 import { installPageTrailRuntime } from "./page-trail-runtime";
 import { platformMessages } from "./platform-messages";
 import { readShellData } from "./shell-data";
+import { shellShortcuts } from "./shell-shortcuts";
 import { syncTimezoneCookie } from "./timezone-cookie";
 
 export type ShellRuntimeProps = {
@@ -66,6 +68,7 @@ export default function ShellRuntime(props: ShellRuntimeProps) {
   const locale = useLocale();
   const t = () => platformMessages.resolve([locale()]).t;
   onMount(() => syncTimezoneCookie(true));
+  onMount(() => onCleanup(installInputModeController()));
 
   if (props.workspace) {
     onMount(() => {
@@ -142,31 +145,20 @@ export default function ShellRuntime(props: ShellRuntimeProps) {
         ),
       ),
     );
-    createEffect(() =>
-      onCleanup(
-        registerContextAwareCommand({
-          id: "cloud.search",
-          title: t().openGlobalSearch,
-          description: t().globalSearchDescription,
-          icon: "ti ti-search",
-          shortcut: "mod+k",
-          action: { search: {} },
-        }),
-      ),
-    );
-    createEffect(() =>
-      onCleanup(
-        registerContextAwareCommand({
-          id: "cloud.help",
-          title: t().openShortcutHelp,
-          description: t().shortcutHelpDescription,
-          icon: "ti ti-help-circle",
-          shortcut: "shift+/",
-          // Returning the load keeps the Command busy until the dialog is open; a second press opens no second dialog.
-          action: () => importOnDemand(() => import("./LayoutHelp")).then((help) => help?.openLayoutHelpDialog()),
-        }),
-      ),
-    );
+    createEffect(() => {
+      for (const command of shellShortcuts(t())) {
+        onCleanup(
+          registerContextAwareCommand({
+            ...command,
+            action:
+              command.id === "cloud.search"
+                ? { search: {} }
+                : // Returning the load keeps the Command busy until the dialog is open; a second press opens no second dialog.
+                  () => importOnDemand(() => import("./LayoutHelp")).then((help) => help?.openLayoutHelpDialog()),
+          }),
+        );
+      }
+    });
   }
   onMount(() => {
     if (props.push) {

package/src/ssr/help-messages.ts

@@ -5,38 +5,50 @@ export const helpMessages = i18n.define({
   baseLocale: "en",
   messages: {
     en: {
-      shortcuts: "Shortcuts",
-      shortcutsDescription: "Keyboard actions for the current page.",
-      shortcutsIntro: "Shortcuts follow the current app and view. This list updates automatically.",
+      helpFor: ({ app }: { app: string }) => `Help for ${app}`,
+      moreActions: "More Help actions",
+      copyAsMarkdown: "Copy as Markdown",
+      openAsPage: "Open as page",
+      copyFailed: ({ message }: { message: string }) => `Could not copy the article: ${message}`,
+      forThisView: "For this view",
+      whatToDo: "What do you want to do?",
+      groupStart: "Get started",
+      groupReference: "Look up",
+      groupTroubleshoot: "Solve problems",
+      keyboardShortcuts: "Keyboard shortcuts",
+      shortcutsEverywhere: "Everywhere",
+      shortcutsInApp: ({ app }: { app: string }) => `In ${app}`,
+      shortcutsInThisApp: "In this app",
+      shortcutsWithSelection: "With a selection",
+      noArticles: "No Help articles here yet",
+      reload: "Reload",
+      noArticlesDetail: "This app has not published Help yet.",
+      helpUnavailable: "Help could not be loaded",
+      helpUnavailableDetail: "Reload the page to try again.",
+      titlesOnly: "Titles only",
+      searchTitlesOnly: "Full-text search is not available right now. These results match titles and descriptions only.",
       searchHelp: "Search help",
-      section: "Section",
       help: "Help",
-      description: "Guides, workflows, and shortcuts",
-      searchDescription: "Find a task, concept, or shortcut.",
-      previousTopic: "Previous topic",
-      nextTopic: "Next topic",
-      topicNavigation: "Help topic navigation",
+      youNeed: "You need",
+      accessView: "View",
+      accessEdit: "Edit",
+      accessManage: "Manage",
+      steps: ({ count }: { count: number }) => `${count} ${count === 1 ? "step" : "steps"}`,
+      articleFacts: "About this article",
+      next: "Next",
+      related: "Related",
       back: "Back",
-      backToHelp: "Back to help",
       backToTopics: "Back to help topics",
       actions: "Help actions",
       copied: "Copied",
       helpCopied: "Help copied as Markdown",
-      copyAllHelp: "Copy all help as Markdown",
       articleCopied: "Article copied as Markdown",
       copyArticle: "Copy article as Markdown",
-      openWindow: "Open help in a new browser window",
-      openFullPage: "Open full-page help",
       closeHelp: "Close help",
       close: "Close",
-      heading: "How can we help?",
-      headingDescription: "Find a task, concept, or shortcut for the current app.",
       preparing: "Preparing…",
-      copyAllShort: "Copy all as Markdown",
       copyAllFailed: ({ message }: { message: string }) => `Could not copy all help: ${message}`,
       searchPlaceholder: "Search help…",
-      startHere: "Start here",
-      allTopics: "All topics",
       results: ({ count }: { count: number }) => `${count} ${count === 1 ? "result" : "results"}`,
       noResults: "No help topic matches this search.",
       copyMarkdown: "Copy Markdown",
@@ -45,7 +57,6 @@ export const helpMessages = i18n.define({
       tryAgain: "Try again",
       onThisPage: "On this page",
       articleCopiedAnnouncement: "Article copied as Markdown.",
-      allCopiedAnnouncement: "All help copied as Markdown.",
       searchFailed: "Help could not be searched. Try again.",
       requestFailed: "Help could not be loaded. Try again.",
       invalidDocument: "Help server returned an invalid document",
@@ -53,38 +64,50 @@ export const helpMessages = i18n.define({
       copyFallback: "Could not copy help",
     },
     de: {
-      shortcuts: "Tastaturkürzel",
-      shortcutsDescription: "Tastaturaktionen für die aktuelle Seite.",
-      shortcutsIntro: "Die Tastaturkürzel richten sich nach der aktuellen App und Ansicht. Diese Liste wird automatisch aktualisiert.",
+      helpFor: ({ app }) => `Hilfe zu ${app}`,
+      moreActions: "Weitere Hilfeaktionen",
+      copyAsMarkdown: "Als Markdown kopieren",
+      openAsPage: "Als Seite öffnen",
+      copyFailed: ({ message }) => `Der Artikel konnte nicht kopiert werden: ${message}`,
+      forThisView: "Für diese Ansicht",
+      whatToDo: "Was möchtest du tun?",
+      groupStart: "Loslegen",
+      groupReference: "Nachschlagen",
+      groupTroubleshoot: "Probleme lösen",
+      keyboardShortcuts: "Tastaturkürzel",
+      shortcutsEverywhere: "Überall",
+      shortcutsInApp: ({ app }) => `In ${app}`,
+      shortcutsInThisApp: "In dieser App",
+      shortcutsWithSelection: "Mit Auswahl",
+      noArticles: "Hier gibt es noch keine Hilfeartikel",
+      reload: "Neu laden",
+      noArticlesDetail: "Diese App hat noch keine Hilfe veröffentlicht.",
+      helpUnavailable: "Die Hilfe konnte nicht geladen werden",
+      helpUnavailableDetail: "Lade die Seite neu, um es erneut zu versuchen.",
+      titlesOnly: "Nur Titel",
+      searchTitlesOnly: "Die Volltextsuche ist gerade nicht verfügbar. Diese Treffer passen nur zu Titeln und Beschreibungen.",
       searchHelp: "Hilfe durchsuchen",
-      section: "Abschnitt",
       help: "Hilfe",
-      description: "Anleitungen, Abläufe und Tastaturkürzel",
-      searchDescription: "Finde eine Aufgabe, ein Konzept oder ein Tastaturkürzel.",
-      previousTopic: "Vorheriges Thema",
-      nextTopic: "Nächstes Thema",
-      topicNavigation: "Navigation durch Hilfethemen",
+      youNeed: "Du brauchst",
+      accessView: "Ansehen",
+      accessEdit: "Bearbeiten",
+      accessManage: "Verwalten",
+      steps: ({ count }) => i18n.plural(count, "de", { one: "1 Schritt", other: `${count} Schritte` }),
+      articleFacts: "Zu diesem Artikel",
+      next: "Als Nächstes",
+      related: "Passt dazu",
       back: "Zurück",
-      backToHelp: "Zurück zur Hilfe",
       backToTopics: "Zurück zu den Hilfethemen",
       actions: "Hilfeaktionen",
       copied: "Kopiert",
       helpCopied: "Hilfe als Markdown kopiert",
-      copyAllHelp: "Gesamte Hilfe als Markdown kopieren",
       articleCopied: "Artikel als Markdown kopiert",
       copyArticle: "Artikel als Markdown kopieren",
-      openWindow: "Hilfe in einem neuen Browserfenster öffnen",
-      openFullPage: "Hilfe als ganze Seite öffnen",
       closeHelp: "Hilfe schließen",
       close: "Schließen",
-      heading: "Wobei brauchst du Hilfe?",
-      headingDescription: "Finde eine Aufgabe, ein Konzept oder ein Tastaturkürzel für die aktuelle App.",
       preparing: "Wird vorbereitet…",
-      copyAllShort: "Alles als Markdown kopieren",
       copyAllFailed: ({ message }) => `Die gesamte Hilfe konnte nicht kopiert werden: ${message}`,
       searchPlaceholder: "Hilfe durchsuchen…",
-      startHere: "Hier starten",
-      allTopics: "Alle Themen",
       results: ({ count }) => i18n.plural(count, "de", { one: "1 Ergebnis", other: `${count} Ergebnisse` }),
       noResults: "Kein Hilfethema passt zu dieser Suche.",
       copyMarkdown: "Markdown kopieren",
@@ -93,7 +116,6 @@ export const helpMessages = i18n.define({
       tryAgain: "Erneut versuchen",
       onThisPage: "Auf dieser Seite",
       articleCopiedAnnouncement: "Artikel als Markdown kopiert.",
-      allCopiedAnnouncement: "Gesamte Hilfe als Markdown kopiert.",
       searchFailed: "Die Hilfe konnte nicht durchsucht werden. Versuche es erneut.",
       requestFailed: "Die Hilfe konnte nicht geladen werden. Versuche es erneut.",
       invalidDocument: "Der Hilfeserver hat ein ungültiges Dokument zurückgegeben",

package/src/ssr/help.ts

@@ -7,8 +7,10 @@ import { resolveCurrentApp } from "./app-appearance";
 import { getRuntimeContext } from "./runtime";
 
 const manifests = new WeakMap<object, HelpManifestResult | null>();
+const failedContexts = new WeakSet<object>();
 const log = logger("help:ssr");
 export const getLayoutHelp = (c: object): HelpManifestResult | null => manifests.get(c) ?? null;
+export const layoutHelpFailed = (c: object): boolean => failedContexts.has(c);
 
 /** Help metadata for the current or an explicit app; `null` without a user or when the user may not see the app. */
 export const preloadLayoutHelp = async (c: Context, appId?: string): Promise<HelpManifestResult | null> => {
@@ -22,6 +24,7 @@ export const preloadLayoutHelp = async (c: Context, appId?: string): Promise<Hel
     return manifest;
   } catch (error) {
     // An unavailable Help store must not prevent an unrelated application page from rendering.
+    failedContexts.add(c);
     log.warn("Help metadata unavailable", { appId: id, error: error instanceof Error ? error.message : String(error) });
     manifests.set(c, null);
     return null;

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

@@ -0,0 +1,41 @@
+/** What the article head, the table of contents, and the step count read from the rendered Help HTML. */
+export type HelpArticleParts = {
+  /** The first paragraph: the article's short answer. */
+  lead?: string;
+  body: string;
+  sections: { id: string; label: string }[];
+  steps: number;
+};
+
+/** The text a screen reader reads: key names instead of key caps, no icons or decorative separators. */
+const spokenText = (element: Element): string => {
+  const copy = element.cloneNode(true) as Element;
+  for (const hidden of copy.querySelectorAll('[aria-hidden="true"]')) hidden.remove();
+  return copy.textContent?.replace(/\s+/g, " ").trim() ?? "";
+};
+
+/**
+ * Splits trusted Help HTML before it renders, so the head shows the short answer, the step count, and the
+ * section menu in the same frame as the body and nothing moves afterwards.
+ */
+export const helpArticleParts = (html: string): HelpArticleParts => {
+  // A template parses inert markup: nothing in it loads or runs.
+  const template = document.createElement("template");
+  template.innerHTML = html;
+  const body = template.content;
+  const first = body.firstElementChild;
+  // A bold-only paragraph is an eyebrow (`help-eyebrow`), not the short answer.
+  const lead = first?.tagName === "P" && !first.className ? first.outerHTML : undefined;
+  if (lead) first?.remove();
+  return {
+    lead,
+    body: template.innerHTML,
+    // A heading inside collapsed details is not a section of the page.
+    sections: Array.from(body.querySelectorAll("h2[id]"))
+      .filter((heading) => !heading.closest("details"))
+      .map((heading) => ({ id: heading.id, label: spokenText(heading) }))
+      .filter((section) => section.label),
+    // Steps inside a collapsed `details` block are an aside, not the task.
+    steps: Array.from(body.querySelectorAll(".help-steps > ol > li")).filter((step) => !step.closest("details")).length,
+  };
+};

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/platform-messages.ts

@@ -4,6 +4,8 @@ export const platformMessages = i18n.define({
   baseLocale: "en",
   messages: {
     en: {
+      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 +78,8 @@ export const platformMessages = i18n.define({
       clearSearch: "Clear search",
     },
     de: {
+      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/shell-data.tsx

@@ -1,3 +1,4 @@
+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";
@@ -20,6 +21,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,8 @@
+import type { platformMessages } from "./platform-messages";
+
+export const SHELL_SHORTCUT_ORDER = ["cloud.search", "cloud.help"] 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"]) => [
+  { 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+/" },
+];