@k2b/cloud 0.38.0 → 0.39.0

package/src/ssr/PanelRuntime.island.tsx

@@ -0,0 +1,87 @@
+import { installAppWorkspaceController, installInputModeController, keyboardPlatform } from "@k2b/ui";
+import { onCleanup, onMount } from "solid-js";
+import { syncTimezoneCookie } from "./timezone-cookie";
+
+export default function PanelRuntime(props: { provider?: string; scope?: string }) {
+  onMount(() => {
+    syncTimezoneCookie(true);
+    const disposeInput = installInputModeController();
+    // The SSR body hands workspace controller ownership to the page runtime, as Layout's ShellRuntime does. A panel
+    // page keeps no workspace layout cookie: the app's own layout must not follow the reader into a narrow panel.
+    const disposeWorkspace = installAppWorkspaceController();
+    const deferred = new Set<ReturnType<typeof setTimeout>>();
+    const embedded = window.parent !== window;
+    let disposeTheme = () => {};
+    let resumeTheme = () => {};
+    // A page kept in the back/forward cache keeps following the host; only a removed iframe lets go.
+    const pageHide = (event: PageTransitionEvent) => {
+      if (!event.persisted) disposeTheme();
+    };
+    const pageShow = (event: PageTransitionEvent) => {
+      if (event.persisted) resumeTheme();
+    };
+    const close = () => window.parent.postMessage({ type: "cloud.panel.close" }, location.origin);
+    const click = (event: MouseEvent) => {
+      if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.altKey || event.shiftKey) return;
+      const anchor = event.target instanceof Element ? event.target.closest<HTMLAnchorElement>("a[href]") : null;
+      if (!anchor || (anchor.target && anchor.target !== "_self") || anchor.hasAttribute("download")) return;
+      const url = new URL(anchor.getAttribute("href")!, document.baseURI);
+      if (url.origin !== location.origin) return;
+      const scope = props.scope?.replace(/\/$/, "");
+      if (scope !== undefined && (url.pathname === scope || url.pathname.startsWith(`${scope}/`))) return;
+      event.preventDefault();
+      window.parent.location.assign(url.href);
+    };
+    const key = (event: KeyboardEvent) => {
+      if (event.isComposing || event.defaultPrevented || event.altKey || event.shiftKey) return;
+      const apple = keyboardPlatform() === "apple";
+      if (event.key.toLowerCase() === "j" && event.metaKey === apple && event.ctrlKey === !apple) {
+        event.preventDefault();
+        if (!event.repeat) close();
+      } else if (event.key === "Escape" && !event.metaKey && !event.ctrlKey) {
+        // An open modal dialog takes Escape through its cancel event, without preventing this keydown.
+        if (document.querySelector("dialog[open], [aria-modal='true']")) return;
+        const timer = setTimeout(() => {
+          deferred.delete(timer);
+          if (!event.defaultPrevented) close();
+        }, 0);
+        deferred.add(timer);
+      }
+    };
+    if (embedded) {
+      try {
+        const parent = window.parent;
+        const parentRoot = parent.document.documentElement;
+        const syncTheme = () => {
+          for (const theme of ["light", "dark"]) {
+            document.documentElement.classList.toggle(theme, parentRoot.classList.contains(theme));
+          }
+        };
+        parent.addEventListener("cloud:theme-preference", syncTheme);
+        disposeTheme = () => parent.removeEventListener("cloud:theme-preference", syncTheme);
+        resumeTheme = syncTheme;
+        syncTheme();
+      } catch {
+        // A cross-origin parent cannot share its document or theme events.
+      }
+      window.addEventListener("pagehide", pageHide);
+      window.addEventListener("pageshow", pageShow);
+      // The shell reads this mark when its controller arrives after the message.
+      if (props.provider) document.documentElement.dataset.cloudPanelReady = props.provider;
+      window.parent.postMessage({ type: "cloud.panel.ready", v: 1, provider: props.provider }, location.origin);
+      window.addEventListener("keydown", key);
+      window.addEventListener("click", click);
+    }
+    onCleanup(() => {
+      disposeInput();
+      disposeWorkspace();
+      disposeTheme();
+      window.removeEventListener("pagehide", pageHide);
+      window.removeEventListener("pageshow", pageShow);
+      window.removeEventListener("keydown", key);
+      window.removeEventListener("click", click);
+      for (const timer of deferred) clearTimeout(timer);
+    });
+  });
+  return null;
+}

package/src/ssr/PanelSlot.tsx

@@ -0,0 +1,108 @@
+import { Button, IconButton, type KeyboardPlatform, Placeholder, ResizeSeparator, useLocale } from "@k2b/ui";
+import { PANEL_MAX_WIDTH_REM, PANEL_MIN_WIDTH_REM, type PanelCookieState } from "../_internal/panel-cookie";
+import { platformMessages } from "./platform-messages";
+import type { ShellData } from "./shell-data";
+
+/** Server markup only. The shell loads its controller on demand. */
+export default function PanelSlot(props: { panel: NonNullable<ShellData["panel"]>; state: PanelCookieState; platform?: KeyboardPlatform }) {
+  const locale = useLocale();
+  const t = platformMessages.resolve([locale()]).t;
+  const provider = props.panel.providers.find((provider) => provider.id === props.panel.provider) ?? props.panel.providers[0];
+  if (!provider) return null;
+  const tabs = props.panel.providers.length > 1;
+  return (
+    <aside
+      class="cloud-panel"
+      id="cloud-panel"
+      data-cloud-panel=""
+      aria-label={t.panel}
+      data-state={props.state.open ? "loading" : "closed"}
+      data-provider={provider.id}
+    >
+      <ResizeSeparator
+        class="cloud-panel__resize"
+        label={t.resizePanel}
+        orientation="vertical"
+        controls="cloud-panel"
+        min={PANEL_MIN_WIDTH_REM}
+        max={PANEL_MAX_WIDTH_REM}
+        value={props.state.widthRem ?? 26}
+        grow="start"
+        onResize={() => {}}
+      />
+      <div class="cloud-panel__card">
+        <button type="button" class="cloud-panel__grabber" data-cloud-panel-grow="" aria-label={t.enlargePanel}>
+          <span aria-hidden="true" />
+        </button>
+        <div class="cloud-panel__head">
+          {tabs ? (
+            <div class="cloud-panel__tabs" role="tablist" aria-label={t.panels}>
+              {props.panel.providers.map((item) => (
+                <button
+                  type="button"
+                  role="tab"
+                  class="cloud-panel__tab"
+                  data-cloud-panel-provider={item.id}
+                  aria-selected={item.id === provider.id}
+                  aria-controls="cloud-panel-body"
+                  tabindex={item.id === provider.id ? 0 : -1}
+                >
+                  <i class={item.icon} aria-hidden="true" />
+                  <span class="cloud-panel__tab-label">{item.label}</span>
+                </button>
+              ))}
+            </div>
+          ) : (
+            <h2 class="cloud-panel__title">
+              <i class={provider.icon} aria-hidden="true" />
+              <span>{provider.label}</span>
+            </h2>
+          )}
+          <IconButton
+            label={t.closePanel}
+            title={`${t.closePanel} (${props.platform === "apple" ? "⌘J" : "Ctrl+J"})`}
+            data-cloud-panel-close=""
+          >
+            <i class="ti ti-x" aria-hidden="true" />
+          </IconButton>
+        </div>
+        <div class="cloud-panel__body" id="cloud-panel-body" role={tabs ? "tabpanel" : undefined}>
+          <div class="cloud-panel__skeleton" aria-hidden="true">
+            <span />
+            <span />
+            <span />
+          </div>
+          {/* Lazy: below 768 px the open cookie leaves the slot hidden, and a hidden iframe must not load its provider. */}
+          {props.state.open && (
+            <iframe
+              class="cloud-panel__frame"
+              src={provider.href}
+              title={provider.label}
+              loading="lazy"
+              data-cloud-panel-frame={provider.id}
+            />
+          )}
+          <div class="cloud-panel__fallback">
+            <Placeholder
+              state="error"
+              variant="panel"
+              title={t.panelLoadFailed}
+              description={t.panelNotResponding({ label: provider.label })}
+              action={<Button data-cloud-panel-retry="">{t.retry}</Button>}
+            />
+          </div>
+          <div class="cloud-panel__shield" aria-hidden="true" />
+          <div class="cloud-panel__closing" aria-hidden="true">
+            <span>
+              <i class="ti ti-x" />
+              {t.releaseClosesPanel}
+            </span>
+          </div>
+        </div>
+      </div>
+      <div role="status" class="k2b-sr-only" data-cloud-panel-status="">
+        {props.state.open ? t.panelLoading({ label: provider.label }) : ""}
+      </div>
+    </aside>
+  );
+}

package/src/ssr/PanelTrigger.tsx

@@ -0,0 +1,49 @@
+import { IconButton, Tooltip, useLocale } from "@k2b/ui";
+import { isServer } from "solid-js/web";
+import type { PanelRequest } from "../browser/panel";
+import { platformMessages } from "./platform-messages";
+import { useShellData } from "./shell-data";
+
+export default function PanelTrigger(props: { variant: "rail" | "header"; open?: boolean }) {
+  const locale = useLocale();
+  const data = useShellData();
+  const t = () => platformMessages.resolve([locale()]).t;
+  const title = () => t().panelShortcut({ mod: data?.platform === "apple" ? "⌘" : "Ctrl+" });
+  // The lazy controller may have changed state before this island mounts.
+  const open = () =>
+    isServer
+      ? !!props.open
+      : document
+          .querySelector(".cloud-app-canvas")
+          ?.getAttribute(window.matchMedia("(min-width: 768px)").matches ? "data-panel" : "data-panel-sheet") === "open";
+  const toggle = () => window.dispatchEvent(new CustomEvent<PanelRequest>("cloud.panel.request", { detail: { action: "toggle" } }));
+  if (props.variant === "rail")
+    return (
+      <Tooltip.Trigger
+        type="button"
+        class="rail-item"
+        aria-label={t().openPanel}
+        aria-controls="cloud-panel"
+        aria-expanded={open()}
+        data-cloud-panel-toggle=""
+        content={title()}
+        placement="right"
+        delay={0}
+        onClick={toggle}
+      >
+        <i class="ti ti-layout-sidebar-right text-xl" aria-hidden="true" />
+      </Tooltip.Trigger>
+    );
+  return (
+    <IconButton
+      label={t().openPanel}
+      title={title()}
+      aria-controls="cloud-panel"
+      aria-expanded={open()}
+      data-cloud-panel-toggle=""
+      onClick={toggle}
+    >
+      <i class="ti ti-layout-sidebar-right text-base" aria-hidden="true" />
+    </IconButton>
+  );
+}

package/src/ssr/ShellRuntime.island.tsx

@@ -4,6 +4,7 @@ import {
   installAppWorkspaceController,
   installInputModeController,
   installPageTitleController,
+  keyboardPlatform,
   serializeAppWorkspaceLayoutState,
   useLocale,
 } from "@k2b/ui";
@@ -12,6 +13,7 @@ import { appWorkspaceCookieName, readAppWorkspaceLayoutCookie } from "../_intern
 import { registerContextAwareCommand } from "../browser/command-bridge";
 import { attachCommandShortcuts } from "../browser/command-shortcuts";
 import { navigationSearchItems } from "../browser/navigation-search";
+import type { PanelRequest } from "../browser/panel";
 import { importOnDemand } from "../browser/reload";
 import { registerGlobalSearchHost } from "../browser/search-bridge";
 import { attachShellFocusControls, readShellFocus, SHELL_FOCUS_CHANGE_EVENT, toggleShellFocus } from "../browser/shell-focus";
@@ -32,6 +34,8 @@ import { shellShortcuts } from "./shell-shortcuts";
 import { syncTimezoneCookie } from "./timezone-cookie";
 
 export type ShellRuntimeProps = {
+  /** This page has an authorized panel slot. */
+  panel?: boolean;
   /** Layout pages outside focus mode: keep the current app's workspace layout in its cookie. */
   workspace?: { appId?: string };
   /** Layout pages: page titles, the way up (Alt+Up) and its per-tab memory. */
@@ -70,6 +74,55 @@ export default function ShellRuntime(props: ShellRuntimeProps) {
   onMount(() => syncTimezoneCookie(true));
   onMount(() => onCleanup(installInputModeController()));
 
+  const togglePanel = () => {
+    window.dispatchEvent(new CustomEvent<PanelRequest>("cloud.panel.request", { detail: { action: "toggle" } }));
+  };
+  if (props.panel) {
+    onMount(() => {
+      let stopped = false;
+      let dispose: (() => void) | undefined;
+      const load = async (request?: PanelRequest) => {
+        const panel = await importOnDemand(() => import("../browser/panel-slot"));
+        if (!panel || stopped) return;
+        dispose ??= panel.installPanelSlot();
+        if (request) panel.handlePanelRequest(request);
+      };
+      const request = (event: CustomEvent<PanelRequest>) => {
+        const detail = event.detail;
+        if (detail.action === "open") {
+          if (detail.accepted || !readShellData()?.panel?.providers.some((provider) => provider.id === detail.provider)) return;
+          detail.accepted = true;
+        }
+        void load(event.detail);
+      };
+      const key = (event: KeyboardEvent) => {
+        const apple = keyboardPlatform() === "apple";
+        if (
+          event.defaultPrevented ||
+          event.isComposing ||
+          event.repeat ||
+          event.altKey ||
+          event.shiftKey ||
+          event.key.toLowerCase() !== "j" ||
+          event.metaKey !== apple ||
+          event.ctrlKey !== !apple
+        )
+          return;
+        event.preventDefault();
+        togglePanel();
+      };
+      window.addEventListener("cloud.panel.request", request);
+      if (!props.commands) window.addEventListener("keydown", key);
+      if (document.querySelector('.cloud-app-canvas[data-panel="open"]')) void load();
+      onCleanup(() => {
+        stopped = true;
+        dispose?.();
+        window.removeEventListener("cloud.panel.request", request);
+        window.removeEventListener("keydown", key);
+      });
+    });
+  }
+
   if (props.workspace) {
     onMount(() => {
       const appId = props.workspace?.appId;
@@ -146,15 +199,17 @@ export default function ShellRuntime(props: ShellRuntimeProps) {
       ),
     );
     createEffect(() => {
-      for (const command of shellShortcuts(t())) {
+      for (const command of shellShortcuts(t(), { panel: props.panel })) {
         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()),
+              command.id === "cloud.panel"
+                ? togglePanel
+                : 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()),
           }),
         );
       }

package/src/ssr/app-appearance.ts

@@ -1,4 +1,5 @@
 import type { AppAppearance } from "../contracts/app";
+import { appColorStyle } from "./app-color";
 import { resolveRuntimeRoute } from "./app-navigation";
 import { helpPageAppId } from "./layout-help-url";
 import type { RuntimeContext } from "./runtime";
@@ -15,11 +16,11 @@ export const appAppearanceStyle = (appearance: AppAppearance | undefined): strin
   const angle = Number.isFinite(appearance.background?.angle) ? Math.max(0, Math.min(360, appearance.background?.angle ?? 135)) : 135;
   const strength = clampStrength(appearance.background?.strength, 20);
   const darkStrength = Math.round(strength / 2);
-  return `--app-accent:${appearance.accent};--app-canvas-from:${from};--app-canvas-via:${via};--app-canvas-to:${to};--app-canvas-angle:${angle}deg;--app-canvas-strength:${strength}%;--app-canvas-dark-strength:${darkStrength}%`;
+  return `--app-accent:${appearance.accent};${appColorStyle(appearance.accent)};--app-canvas-from:${from};--app-canvas-via:${via};--app-canvas-to:${to};--app-canvas-angle:${angle}deg;--app-canvas-strength:${strength}%;--app-canvas-dark-strength:${darkStrength}%`;
 };
 
 export const appAccentStyle = (accent: string | undefined): string | undefined =>
-  isHexColor(accent) ? `--app-accent:${accent}` : undefined;
+  isHexColor(accent) ? `--app-accent:${accent};${appColorStyle(accent)}` : undefined;
 
 /** Core's full-page Help of an app belongs to that app. */
 export const resolveCurrentApp = (apps: RuntimeContext["apps"], pathname: string) => {

package/src/ssr/app-color.ts

@@ -0,0 +1,100 @@
+type HexColor = `#${string}`;
+
+const minimumContrast = 4.5;
+const fillShares = {
+  light: { selected: 0.07, selectedNav: 0.1 },
+  dark: { selected: 0.14, selectedNav: 0.17 },
+} as const;
+
+/**
+ * Opaque theme backgrounds checked for readable app ink; a test pins them to
+ * tokens.css and @k2b/ui. `sidebar` is the workspace sidebar
+ * (`--k2b-surface-muted`) and `sidebarHover` its row hover over it; `subtle`,
+ * `muted`, `hover`, and `platformSelected` are the `--ui-surface-subtle`,
+ * `--ui-surface-muted`, `--ui-hover`, and blue `--ui-selected` fills app ink
+ * also sits on.
+ */
+export const appColorSurfaces = {
+  light: {
+    canvas: "#fafafa",
+    surface: "#ffffff",
+    sidebar: "#f4f4f5",
+    sidebarHover: "#e8e8e9",
+    subtle: "#f8f8f8",
+    muted: "#f3f4f3",
+    raised: "#ffffff",
+    hover: "#f0f1f0",
+    platformSelected: "#f0f6ff",
+  },
+  dark: {
+    canvas: "#090d12",
+    surface: "#11151b",
+    sidebar: "#20242a",
+    sidebarHover: "#2b2f34",
+    subtle: "#161a20",
+    muted: "#20242a",
+    raised: "#181d24",
+    hover: "#252c35",
+    platformSelected: "#192636",
+  },
+} as const;
+
+const channels = (hex: HexColor) =>
+  [Number.parseInt(hex.slice(1, 3), 16), Number.parseInt(hex.slice(3, 5), 16), Number.parseInt(hex.slice(5, 7), 16)] as const;
+
+/** WCAG 2.x relative luminance from a six-digit sRGB hex color. */
+export const relativeLuminance = (hex: HexColor): number => {
+  const linearize = (value: number) => {
+    const c = value / 255;
+    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  };
+  const [r, g, b] = channels(hex);
+  return 0.2126 * linearize(r) + 0.7152 * linearize(g) + 0.0722 * linearize(b);
+};
+
+/** WCAG 2.x contrast ratio between two opaque hex colors. */
+export const contrastRatio = (a: HexColor, b: HexColor): number => {
+  const first = relativeLuminance(a);
+  const second = relativeLuminance(b);
+  return (Math.max(first, second) + 0.05) / (Math.min(first, second) + 0.05);
+};
+
+/** Rounded sRGB channel mix, with share indicating the fraction of a. */
+export const mixHex = (a: HexColor, b: HexColor, share: number): HexColor => {
+  const second = channels(b);
+  const fraction = Math.max(0, Math.min(1, share));
+  return `#${channels(a)
+    .map((value, index) =>
+      Math.round(value * fraction + second[index]! * (1 - fraction))
+        .toString(16)
+        .padStart(2, "0"),
+    )
+    .join("")}`;
+};
+
+/** Derive selection fills and the nearest AA-readable app ink in each theme. */
+export const appColors = (accent: HexColor) => {
+  const forTheme = (theme: keyof typeof appColorSurfaces) => {
+    const surfaces = appColorSurfaces[theme];
+    const selected = mixHex(accent, surfaces.surface, fillShares[theme].selected);
+    const selectedNav = mixHex(accent, surfaces.sidebar, fillShares[theme].selectedNav);
+    const backgrounds = [...Object.values(surfaces), selected, selectedNav];
+    const toward = theme === "light" ? "#000000" : "#ffffff";
+    let ink: HexColor = toward;
+    for (let i = 100; i >= 0; i--) {
+      const candidate = mixHex(accent, toward, i / 100);
+      if (backgrounds.every((background) => contrastRatio(candidate, background) >= minimumContrast)) {
+        ink = candidate;
+        break;
+      }
+    }
+    return { ink, selected, selectedNav };
+  };
+  return { light: forTheme("light"), dark: forTheme("dark") };
+};
+
+/** Plain hex declarations for server-rendered app appearance and accent scopes. */
+export const appColorStyle = (accent: HexColor): string => {
+  const { light, dark } = appColors(accent);
+  return `--app-ink-light:${light.ink};--app-ink-dark:${dark.ink};--app-selected-light:${light.selected};--app-selected-dark:${dark.selected};--app-selected-nav-light:${light.selectedNav};--app-selected-nav-dark:${dark.selectedNav}`;
+};

package/src/ssr/app-launchpad.tsx

@@ -66,7 +66,7 @@ export function AppLaunchpadProvider(props: AppLaunchpadContext) {
   return <span class="hidden" data-cloud-app-launchpad-provider />;
 }
 
-export function AppLaunchpadButton(props: AppLaunchpadContext & { variant: "rail" | "header" | "menu"; label?: string }) {
+export function AppLaunchpadButton(props: AppLaunchpadContext & { variant: "rail" | "header" | "title" | "menu"; label?: string }) {
   const locale = useLocale();
   const t = () => platformMessages.resolve([locale()]).t;
   const action = createBusyAction();
@@ -98,6 +98,23 @@ export function AppLaunchpadButton(props: AppLaunchpadContext & { variant: "rail
     );
   }
 
+  // The page title as the app menu's trigger on phones; global.css shows it only when the page has app navigation.
+  if (props.variant === "title") {
+    return (
+      <button
+        type="button"
+        class="layout-header-title-menu"
+        aria-haspopup="dialog"
+        onClick={open}
+        aria-busy={action.busy() ? "true" : undefined}
+      >
+        <span class="truncate font-semibold">{props.label}</span>
+        <span class="sr-only">{`, ${t().appMenu}`}</span>
+        <i class={action.busy() ? "ti ti-loader-2 animate-spin" : "ti ti-chevron-down"} aria-hidden="true" />
+      </button>
+    );
+  }
+
   if (props.variant === "header") {
     return (
       <IconButton label={props.label ?? t().openApps} onClick={open} aria-busy={action.busy() ? "true" : undefined}>

package/src/ssr/app-navigation.ts

@@ -1,3 +1,4 @@
+import { isOwnAppPath } from "../_internal/app-path";
 import { hasAnyAppRole } from "../_internal/app-roles";
 import type { RuntimeAppMeta } from "../contracts/app";
 import { isPwaPartId } from "../contracts/pwa-paths";
@@ -52,3 +53,17 @@ export const visiblePwaParts = (apps: readonly RuntimeAppMeta[], user: User | un
     .map((app) => resolveAppPresentation(app, locale))
     .sort((a, b) => a.name.localeCompare(b.name, locale) || a.id.localeCompare(b.id));
 };
+
+export type PanelProvider = { id: string; label: string; icon: string; href: string };
+
+/** Authorized presentation only: the panel route still authorizes every request. */
+export const visiblePanelProviders = (apps: readonly RuntimeAppMeta[], user: User | undefined, locale: string): PanelProvider[] => {
+  if (!user) return [];
+  return apps
+    .flatMap((app) => {
+      if (!app.panel || !isOwnAppPath(app.panel.href, app.routes) || !hasAnyAppRole(user, app.panel.requiresRoles)) return [];
+      const panel = resolveAppPresentation(app, locale).panel;
+      return panel ? [{ id: app.id, label: panel.label, icon: panel.icon, href: panel.href }] : [];
+    })
+    .sort((a, b) => a.label.localeCompare(b.label, locale) || a.id.localeCompare(b.id));
+};