@k2b/cloud 0.38.0 → 0.40.0

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

@@ -1,10 +1,10 @@
-import type { HelpKind } from "../shared/help";
+import { HELP_VIEW_LIMIT, 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 { HELP_VIEW_LIMIT } from "../shared/help";
 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 };
@@ -41,19 +41,42 @@ export const helpStart = <T extends HelpStartTopic>(topics: readonly T[], viewId
 };
 
 export type HelpShortcutScope = "everywhere" | "app" | "selection";
+// Three groups, each as scannable as HELP_START_TILE_LIMIT (8) task tiles: 3 x 8 rows.
+// Today's largest real page is well below this (shell 3 + Spaces about 8).
+export const HELP_START_SHORTCUT_LIMIT = 24;
+// Qualified command ids share CAPABILITY_QUALIFIED_ID_MAX_LENGTH.
+export const HELP_SHORTCUT_ID_MAX_LENGTH = 180;
+// One row label: the platform's CapabilityLink title / human-readable label bound.
+export const HELP_SHORTCUT_TITLE_MAX_LENGTH = 120;
+// Row tooltip: the platform's plain-text Action review message bound.
+export const HELP_SHORTCUT_DESCRIPTION_MAX_LENGTH = 1000;
+// command-shortcuts grammar: five distinct modifier tokens "ctrl+alt+shift+meta+mod+" (24 chars)
+// plus the longest standard KeyboardEvent.key name "TVAudioDescriptionMixDown" (25 chars).
+export const HELP_SHORTCUT_KEYS_MAX_LENGTH = 49;
+export type HelpShortcut = { id: string; title: string; description?: string; shortcut: string; scope?: "selection" | "page" };
 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.
+ * Commands without a shortcut, with empty ids/titles or exceeding the string bounds are dropped.
+ * Keep at most HELP_START_SHORTCUT_LIMIT rows across groups in group order.
  */
 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;
+    if (
+      !command.shortcut ||
+      !command.id ||
+      !command.title ||
+      command.id.length > HELP_SHORTCUT_ID_MAX_LENGTH ||
+      command.title.length > HELP_SHORTCUT_TITLE_MAX_LENGTH ||
+      (command.description?.length ?? 0) > HELP_SHORTCUT_DESCRIPTION_MAX_LENGTH ||
+      command.shortcut.length > HELP_SHORTCUT_KEYS_MAX_LENGTH
+    )
+      continue;
     const scope = command.scope === "selection" ? "selection" : command.id.startsWith("cloud.") ? "everywhere" : "app";
     groups[scope].push({ ...command, shortcut: command.shortcut });
   }
@@ -62,7 +85,10 @@ export const helpShortcutGroups = <T extends HelpShortcutCommand>(
     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] }] : [],
-  );
+  let remaining = HELP_START_SHORTCUT_LIMIT;
+  return (["everywhere", "app", "selection"] as const).flatMap((scope) => {
+    const shortcuts = groups[scope].slice(0, remaining);
+    remaining -= shortcuts.length;
+    return shortcuts.length ? [{ scope, shortcuts }] : [];
+  });
 };

package/src/ssr/panel-consent.ts

@@ -0,0 +1,29 @@
+import type { Context } from "hono";
+import { readPanelCookie } from "../_internal/panel-cookie";
+import { getLocale } from "../server/locale";
+import { panelContextConsent } from "../services/panel-context-consent";
+import { visiblePanelProviders } from "./app-navigation";
+import { getRuntimeContext } from "./runtime";
+
+/** One read, only for a host page with the slot open on a consent provider. Fail closed when the store is unavailable. */
+export async function preloadPanelConsent(c: Context): Promise<void> {
+  const user = c.get("user");
+  if (!user || !c.get("runtime")) return;
+  const providers = visiblePanelProviders(getRuntimeContext(c).apps, user, getLocale(c));
+  const state = readPanelCookie(
+    c.req.header("Cookie"),
+    providers.map((provider) => provider.id),
+  );
+  const provider = state.open && providers.find((provider) => provider.id === state.provider);
+  if (!provider || !provider.consent) return;
+  // The provider's own page below its panel path renders in PanelLayout, which has no slot and never asks.
+  const scope = new URL(provider.href, "https://panel.invalid").pathname.replace(/\/$/, "");
+  if (c.req.path === scope || c.req.path.startsWith(`${scope}/`)) return;
+  let answer: { allowed: boolean; revision: number } | null = null;
+  try {
+    answer = await panelContextConsent.get(user.id, provider.id);
+  } catch {
+    // The shell shows the unanswered question, without context in the URL or messages.
+  }
+  c.set("panelConsent", { provider: provider.id, allowed: answer?.allowed ?? null, revision: answer?.revision ?? 0 });
+}

package/src/ssr/panel-context.ts

@@ -0,0 +1,10 @@
+import { PANEL_CONTEXT_PARAM, type PanelPageContext, parsePanelContextParam } from "../contracts/panel-context";
+
+/** Untrusted URL input: a selector only. Read through your server using the session's actor/accessSubject. */
+export function readPanelContext(c: { req: { raw: { url: string } } }): PanelPageContext | null {
+  try {
+    return parsePanelContextParam(new URL(c.req.raw.url).searchParams.get(PANEL_CONTEXT_PARAM));
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,159 @@
+import { AppWorkspace } from "@k2b/ui";
+import { Hono } from "hono";
+import { defineApp } from "../_internal/define-app";
+import { person } from "../_internal/define-app.test-fixture";
+import { createMePanelConsentRoutes } from "../api/me-panel-consent";
+import type { RuntimeAppMeta } from "../contracts/app";
+import type { User } from "../contracts/shared";
+import Layout from "./Layout";
+import PanelLayout from "./PanelLayout";
+import { readPanelContext } from "./panel-context";
+import type { RuntimeContext } from "./runtime";
+
+type ConsentAnswer = { allowed: boolean; revision: number };
+export const consentAnswers = new Map<string, Map<string, ConsentAnswer>>();
+export const fixtureConsent = {
+  get: async (userId: string, provider: string) => consentAnswers.get(userId)?.get(provider) ?? null,
+  list: async (userId: string, providers: string[]) =>
+    Object.fromEntries(
+      providers.flatMap((id) => {
+        const answer = consentAnswers.get(userId)?.get(id);
+        return answer === undefined ? [] : [[id, answer]];
+      }),
+    ),
+  set: async (userId: string, provider: string, allowed: boolean, revision: number) => {
+    const answers = consentAnswers.get(userId) ?? new Map<string, ConsentAnswer>();
+    if ((answers.get(provider)?.revision ?? 0) !== revision) return null;
+    const saved = { allowed, revision: revision + 1 };
+    answers.set(provider, saved);
+    consentAnswers.set(userId, answers);
+    return saved;
+  },
+};
+
+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 });
+    const id = c.req
+      .header("cookie")
+      ?.split(";")
+      .map((value) => value.trim())
+      .find((value) => value.startsWith("fixture_person="))
+      ?.slice("fixture_person=".length);
+    c.set("user", { ...person, ...(id ? { id } : {}) });
+    await next();
+  })
+  .route("/api/me", createMePanelConsentRoutes(fixtureConsent))
+  .get(
+    "/app/:provider/panel",
+    ...probe.ssr<Environment>((c) => () => (
+      <PanelLayout c={c} title="Fixture panel">
+        <output id="panel-context-probe">{JSON.stringify(readPanelContext(c))}</output>
+        <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 context={{ scope: { type: "fixture.place", id: "place1" } }} 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 context={{ scope: { type: "fixture.place", id: "place1" } }} 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>
+              <button type="button" id="change-context">
+                Change place
+              </button>
+              <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",
+    ".k2b-app-workspace__main",
+    ".k2b-app-workspace__detail",
+    "[data-app-workspace-detail-toggle]",
+  ].map((selector) => {
+    const rect = document.querySelector(selector)?.getBoundingClientRect();
+    return rect && { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+  });
+}
+
+/** The question, provider frame and app area stay in the same reserved rectangles through hydration. */
+export function consentGeometry() {
+  return ["[data-cloud-panel-consent]", "[data-cloud-panel-frame]", "[data-cloud-app-area]"].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,30 @@ 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",
+      panelConsentTitle: ({ app }: { app: string }) => `May ${app} see where you are?`,
+      panelConsentBody: ({ app }: { app: string }) =>
+        `${app} only learns which place you are at. It can read only what you may read yourself. You can change this in the ⋯ menu at any time.`,
+      panelConsentAllow: "Allow",
+      panelConsentDeny: "Don't share",
+      panelMenu: "Panel menu",
+      panelFrom: ({ app }: { app: string }) => `Panel from ${app}`,
+      panelShareContext: "Share context",
+      panelConsentSaveError: "Not saved. Try again.",
       printFallbackTitle: "This view does not print well.",
       printFallbackHint: "Open the item you want to print, or use the app's export.",
       admin: "Admin",
@@ -78,6 +102,30 @@ 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",
+      panelConsentTitle: ({ app }: { app: string }) => `Darf ${app} sehen, wo du gerade bist?`,
+      panelConsentBody: ({ app }: { app: string }) =>
+        `${app} erfährt nur, an welchem Ort du gerade bist. Lesen kann es nur, was du selbst lesen darfst. Du kannst das im Menü ⋯ jederzeit ändern.`,
+      panelConsentAllow: "Erlauben",
+      panelConsentDeny: "Nicht teilen",
+      panelMenu: "Panel-Menü",
+      panelFrom: ({ app }: { app: string }) => `Panel von ${app}`,
+      panelShareContext: "Kontext teilen",
+      panelConsentSaveError: "Nicht gespeichert. Versuche es erneut.",
       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",

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,16 +1,21 @@
 import type { KeyboardPlatform } from "@k2b/ui";
 import { createContext, type JSX, useContext } from "solid-js";
 import type { AppSearchLink } from "../contracts/app";
+import type { PanelConsentSnapshot, PanelPageContext } from "../contracts/panel-context";
 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; context: PanelPageContext | null; consent?: PanelConsentSnapshot };
   /** 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 };

package/src/ssr/shell-shortcuts.ts

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