@k2b/cloud 0.30.0 → 0.31.0

package/src/ssr/AdminLayout.tsx

@@ -33,13 +33,10 @@ export default function AdminLayout(props: Props) {
   const url = new URL(c.req.raw.url);
   const currentPath = `${url.pathname}${url.search}`;
   const runtime = getLocalizedRuntimeContext(c);
-  const breadcrumbs: Breadcrumb[] = [
-    { title: t.start, href: "/" },
-    { title: t.admin, href: "/admin" },
-  ];
-  if (title !== "Overview" && title !== t.overview) {
-    breadcrumbs.push({ title });
-  }
+  // Admin is the area's root, as an app's root is: the rail and the admin sidebar lead there. So it is no level
+  // above an admin page, and every admin page shows its title alone, whichever app owns it.
+  const overview = title === "Overview" || title === t.overview;
+  const breadcrumbs: Breadcrumb[] = [{ title: t.start, href: "/" }, { title: overview ? t.admin : title }];
   return (
     <Layout c={c} fullWidth fullPage title={breadcrumbs}>
       <AppWorkspace mobileSurface="flush" class="min-h-0 flex-1" resizable={false}>

package/src/ssr/AppLaunchpad.island.tsx

@@ -60,7 +60,7 @@ export function openAppLaunchpad(apps?: AppLaunchpadApp[], legalLinks?: AppLaunc
   const context = apps ? { apps, legalLinks: legalLinks ?? [], profile } : (window.__cloudAppLaunchpad ?? readEmbeddedContext());
   if (!context) return;
   window.__cloudAppLaunchpad = context;
-  if (window.matchMedia("(max-width: 1023px)").matches) {
+  if (window.matchMedia("(max-width: 767px)").matches) {
     void openCloudMobileMenu(context);
     return;
   }

package/src/ssr/Layout.tsx

@@ -1,5 +1,5 @@
 import type { DateContext } from "@k2b/stdlib";
-import { AppWorkspace, appWorkspaceLayoutStyle, LocaleProvider, NoticeCard } from "@k2b/ui";
+import { AppWorkspace, appWorkspaceLayoutStyle, LocaleProvider, NoticeCard, PageTrailProvider } from "@k2b/ui";
 import type { JSX } from "solid-js/jsx-runtime";
 import { readAppWorkspaceLayoutCookie, resolveAppWorkspaceLayoutForSidebar } from "../_internal/app-workspace-state";
 import { navigationSearchItems } from "../browser/navigation-search";
@@ -13,8 +13,8 @@ import { dates } from "../shared";
 import { readThemeFromCookieHeader } from "../shared/theme";
 import type { AppLaunchpadApp } from "./AppLaunchpad.island";
 import AppWorkspaceController from "./AppWorkspaceController.island";
-import { appAppearanceStyle, resolveCurrentApp } from "./app-appearance";
-import { visibleNavigationApps } from "./app-navigation";
+import { appAppearanceStyle } from "./app-appearance";
+import { resolveRuntimeRoute, visibleNavigationApps } from "./app-navigation";
 import BrowserPushRegistration from "./BrowserPushRegistration.island";
 import GlobalAnnouncements from "./GlobalAnnouncements.island";
 import type { GlobalSearchHelpApp } from "./GlobalSearchHelpDialog";
@@ -24,6 +24,9 @@ import LayoutHeader from "./LayoutHeader";
 import LayoutRail, { type LayoutAppLink } from "./LayoutRail";
 import type { LayoutContext } from "./layout-context";
 import type { LayoutBreadcrumb } from "./layout-runtime";
+import PageTrailRow from "./PageTrailRow.island";
+import PageTrailRuntime from "./PageTrailRuntime.island";
+import { derivePageTrail } from "./page-trail";
 import { platformMessages } from "./platform-messages";
 import RegisteredHelpDocuments from "./RegisteredHelpDocuments.island";
 import { sortRailApps } from "./rail-navigation";
@@ -153,7 +156,8 @@ export default function Layout(props: LayoutProps) {
   const t = platformMessages.resolve([lang]).t;
   const user = c.get("user");
   const pathname = new URL(c.req.raw.url).pathname;
-  const currentApp = resolveCurrentApp(runtime.apps, pathname);
+  const currentRoute = resolveRuntimeRoute(runtime.apps, pathname);
+  const currentApp = currentRoute?.app;
   const registeredHelp = getLayoutHelp(c);
   const workspaceLayout = resolveAppWorkspaceLayoutForSidebar(
     readAppWorkspaceLayoutCookie(cookie, currentApp?.id),
@@ -201,6 +205,13 @@ export default function Layout(props: LayoutProps) {
   const pageTitle = typeof title === "string" ? title : (title?.at(-1)?.title ?? appName);
   if (!page.title) page.title = pageTitle;
   const breadcrumbs: Breadcrumb[] = !title ? [{ title: appName }] : typeof title === "string" ? [{ title }] : title;
+  // The way up is derived from the title array by one rule (see `derivePageTrail`). Anonymous pages keep their
+  // header breadcrumbs, and focus surfaces such as pop-out editors have no way up; both show the title alone. The
+  // canvas carries this for `layout.update()`.
+  const titleOnly = !user || focusMode;
+  const pageTrail = titleOnly
+    ? { title: pageTitle, ancestors: [] }
+    : derivePageTrail(title ?? appName, currentRoute?.prefix, appName, `${pathname}${new URL(c.req.raw.url).search}`);
   const showRail = !!user;
   // The profile menu offers the mobile app only while the installation runs it.
   const appHref = user && isPwaShellAvailable(runtime.apps) ? "/me/app" : undefined;
@@ -209,9 +220,9 @@ export default function Layout(props: LayoutProps) {
     user?.avatarHash && user.id
       ? `/api/accounts/users/${encodeURIComponent(user.id)}/avatar?rev=${encodeURIComponent(user.avatarHash)}`
       : undefined;
-  // From lg, `main` is the page scroller of regular pages. Its stable gutter
+  // From md, `main` is the page scroller of regular pages. Its stable gutter
   // keeps short and long pages at the same width where scrollbars take space.
-  const mainLayoutClass = fullPage || fullWidth ? "flex flex-col" : "lg:overflow-auto lg:[scrollbar-gutter:stable]";
+  const mainLayoutClass = fullPage || fullWidth ? "flex flex-col" : "md:overflow-auto md:[scrollbar-gutter:stable]";
   const canvasStyle =
     [appAppearanceStyle(currentApp?.appearance), appWorkspaceLayoutStyle(workspaceLayout), focusMode && flushCanvas ? "padding:0" : ""]
       .filter(Boolean)
@@ -223,24 +234,34 @@ export default function Layout(props: LayoutProps) {
           class="cloud-app-canvas flex h-dvh w-full overflow-hidden"
           style={canvasStyle}
           data-app-id={currentApp?.id}
+          data-app-base={currentRoute?.prefix}
+          data-page-trail-title-only=""
           data-layout-full-page="true"
           data-workspace-sidebar-collapsed={workspaceLayout?.sidebarCollapsed ? "true" : undefined}
         >
           <TimezoneCookie />
           {registeredHelp && <RegisteredHelpDocuments documents={registeredHelp.documents} pageBase={registeredHelp.pageBase} />}
-          <main class="min-h-0 min-w-0 flex-1">
-            <AppWorkspace.LayoutStateProvider state={workspaceLayout}>{props.children}</AppWorkspace.LayoutStateProvider>
-          </main>
+          <PageTrailProvider trail={pageTrail}>
+            <PageTrailRuntime />
+            <main class="min-h-0 min-w-0 flex-1">
+              <AppWorkspace.LayoutStateProvider state={workspaceLayout}>{props.children}</AppWorkspace.LayoutStateProvider>
+            </main>
+          </PageTrailProvider>
         </div>
       </LocaleProvider>
     );
   }
+  // The canvas takes the window's visible height. `vh` follows the large
+  // viewport, which is taller than the window while a browser shows its
+  // toolbar, and would let a viewport-bound page scroll by that difference.
   return (
     <LocaleProvider locale={lang}>
       <div
-        class={`cloud-app-canvas relative flex w-full ${fullPage ? "h-dvh overflow-hidden" : "min-h-screen lg:h-screen lg:overflow-hidden"}`}
+        class={`cloud-app-canvas relative flex w-full ${fullPage ? "h-dvh overflow-hidden" : "min-h-dvh md:h-dvh md:overflow-hidden"}`}
         style={canvasStyle}
         data-app-id={currentApp?.id}
+        data-app-base={currentRoute?.prefix}
+        data-page-trail-title-only={titleOnly ? "" : undefined}
         data-layout-full-page={fullPage ? "true" : undefined}
         data-layout-authenticated={showRail ? "true" : undefined}
         data-workspace-sidebar-collapsed={workspaceLayout?.sidebarCollapsed ? "true" : undefined}
@@ -279,7 +300,6 @@ export default function Layout(props: LayoutProps) {
             launchpadApps={launchpadApps}
             legalLinks={legalLinks}
             openAppsLabel={t.openApps}
-            profileAvatarSrc={profileAvatarSrc}
             profileName={profileName}
             searchHelpApps={searchHelpApps}
             searchLinks={searchLinks}
@@ -296,9 +316,13 @@ export default function Layout(props: LayoutProps) {
           )}
           {user && <ProfileWarnings user={user} locale={lang} />}
           {user && <ExpiryWarnings user={user} dateConfig={dateConfig} locale={lang} />}
-          <main class={`layout-content-main min-h-0 min-w-0 flex-1 ${mainLayoutClass}`}>
-            <AppWorkspace.LayoutStateProvider state={workspaceLayout}>{props.children}</AppWorkspace.LayoutStateProvider>
-          </main>
+          <PageTrailProvider trail={pageTrail}>
+            <PageTrailRuntime />
+            <PageTrailRow />
+            <main class={`layout-content-main min-h-0 min-w-0 flex-1 ${mainLayoutClass}`}>
+              <AppWorkspace.LayoutStateProvider state={workspaceLayout}>{props.children}</AppWorkspace.LayoutStateProvider>
+            </main>
+          </PageTrailProvider>
           {!fullPage && !showRail && <LayoutFooter appName={settings?.app?.copyright || appName} legalLinks={legalLinks} />}
         </div>
       </div>

package/src/ssr/LayoutFooter.tsx

@@ -5,7 +5,7 @@ type LayoutFooterProps = {
 
 export default function LayoutFooter(props: LayoutFooterProps) {
   return (
-    <footer class="hidden shrink-0 flex-wrap items-center justify-center gap-x-4 gap-y-1 px-3 py-2 text-xs text-dimmed lg:flex">
+    <footer class="hidden shrink-0 flex-wrap items-center justify-center gap-x-4 gap-y-1 px-3 py-2 text-xs text-dimmed md:flex">
       {props.legalLinks.map((link) => (
         <a href={link.href} class="flex items-center gap-1 transition-colors hover:text-primary">
           {link.icon && <i class={`${link.icon} text-xs`} />}

package/src/ssr/LayoutHeader.tsx

@@ -8,7 +8,6 @@ import LayoutBreadcrumbs from "./LayoutBreadcrumbs.island";
 import LayoutHelpTrigger from "./LayoutHelpTrigger.island";
 import LayoutPreferences from "./LayoutPreferences.island";
 import type { LayoutBreadcrumb } from "./layout-runtime";
-import ProfilePreferences from "./ProfilePreferences.island";
 
 type LayoutHeaderProps = {
   accent?: string;
@@ -21,7 +20,6 @@ type LayoutHeaderProps = {
   launchpadApps: AppLaunchpadApp[];
   legalLinks: Array<{ label: string; href: string; icon?: string }>;
   openAppsLabel: string;
-  profileAvatarSrc?: string;
   profileName: string;
   searchHelpApps: GlobalSearchHelpApp[];
   searchLinks?: NavigationSearchItem[];
@@ -29,23 +27,32 @@ type LayoutHeaderProps = {
   theme: CloudTheme;
 };
 
+/**
+ * Phones (below `md`) always get this header. From `md` it remains only on
+ * anonymous pages; signed-in people reach Home, search, help, the app grid,
+ * and their profile through the rail, so the app area starts at the top edge.
+ * Anonymous pages have no rail: up to `lg` their header keeps the app name,
+ * help, search, and the app grid, and from `lg` it shows the breadcrumbs.
+ */
 export default function LayoutHeader(props: LayoutHeaderProps) {
   return (
     <header
-      class="layout-header paper flex min-h-[2.875rem] shrink-0 items-center justify-between px-2 py-1.5 lg:px-3 lg:py-2"
+      class={`layout-header paper flex min-h-[2.875rem] shrink-0 items-center justify-between px-2 py-1.5 md:px-3 md:py-2 ${props.authenticated ? "md:hidden" : ""}`}
       style="box-shadow: var(--ui-shadow-surface)"
     >
       <div class="flex min-w-0 items-center gap-2">
-        {/* Signed-in desktops reach Home through the rail. `lg:hidden` sits on a wrapper because the button's
-            own display would win over the utility on the link. */}
-        <div class={props.authenticated ? "flex shrink-0 lg:hidden" : "flex shrink-0"}>
+        {/* A long title must not squeeze the button; `shrink-0` sits on a wrapper because the button's own
+            styles would win over a utility on the link. */}
+        <div class="flex shrink-0">
           <IconButtonLink href="/" label={props.homeLabel}>
             <img src="/branding/logo" alt="" class={props.authenticated ? "h-4 w-4" : "h-6 w-6"} />
           </IconButtonLink>
         </div>
-        <div class="hidden min-w-0 items-center lg:flex">
-          <LayoutBreadcrumbs breadcrumbs={props.breadcrumbs} />
-        </div>
+        {!props.authenticated && (
+          <div class="hidden min-w-0 items-center lg:flex">
+            <LayoutBreadcrumbs breadcrumbs={props.breadcrumbs} />
+          </div>
+        )}
         <div class="flex min-w-0 items-center lg:hidden">
           <span class="truncate font-semibold">{props.appLabel ?? props.breadcrumbs.at(-1)?.title}</span>
         </div>
@@ -78,17 +85,7 @@ export default function LayoutHeader(props: LayoutHeaderProps) {
             />
           )}
         </div>
-        {props.authenticated ? (
-          <div class="hidden lg:block">
-            <ProfilePreferences
-              appHref={props.appHref}
-              avatarSrc={props.profileAvatarSrc}
-              initialTheme={props.theme}
-              name={props.profileName}
-              placement="header"
-            />
-          </div>
-        ) : (
+        {!props.authenticated && (
           <>
             <LayoutPreferences initialTheme={props.theme} position="bottom-left" />
             <ButtonLink href="/auth/login" size="sm" variant="primary">

package/src/ssr/LayoutHelp.tsx

@@ -534,7 +534,7 @@ const HelpShell = (props: {
         props.surface === "modal"
           ? "h-[min(48rem,var(--ui-dialog-available-height))] overflow-hidden panel-dialog-shell [box-shadow:var(--ui-shadow-float)]"
           : props.surface === "page"
-            ? "min-h-screen"
+            ? "min-h-dvh"
             : "h-full"
       }`}
       style={appAccentStyle(props.accent)}

package/src/ssr/LayoutRail.tsx

@@ -43,7 +43,7 @@ export default function LayoutRail(props: LayoutRailProps) {
       <script id="cloud-rail-data" type="application/json">
         {jsonScript({ apps: props.apps, settings: props.railSettings })}
       </script>
-      <aside class="layout-rail hidden w-10 shrink-0 flex-col lg:flex">
+      <aside class="layout-rail hidden w-10 shrink-0 flex-col md:flex">
         <div class="layout-rail-logo flex h-[2.875rem] shrink-0 items-center justify-center">
           <a href="/" aria-label={props.homeLabel}>
             <img src="/branding/logo" alt="Logo" class="h-5 w-5" />
@@ -66,7 +66,6 @@ export default function LayoutRail(props: LayoutRailProps) {
               avatarSrc={props.profileAvatarSrc}
               initialTheme={props.theme}
               name={props.profileName}
-              placement="rail"
             />
           </div>
         </nav>

package/src/ssr/PageTrail.tsx

@@ -0,0 +1,23 @@
+import { PageTitle, usePageTrail } from "@k2b/ui";
+import { type JSX, Show } from "solid-js";
+
+export type PageTrailProps = {
+  /** Quiet text after the title, for example a count. */
+  subtitle?: JSX.Element;
+  /** Defaults to `"h1"`. */
+  as?: "h1" | "h2" | "p";
+  class?: string;
+};
+
+/**
+ * The page's title with its way up, for an app that draws its own header.
+ * It shows what the shell would show, from the same title array (`Layout`'s
+ * `title`, kept current by `layout.update()`), and takes the shell's place:
+ * workspace heads and the shell's row step back while it is on the page.
+ */
+export default function PageTrail(props: PageTrailProps) {
+  const trail = usePageTrail();
+  return (
+    <Show when={trail()}>{(current) => <PageTitle trail={current()} subtitle={props.subtitle} as={props.as} class={props.class} />}</Show>
+  );
+}

package/src/ssr/PageTrailRow.island.tsx

@@ -0,0 +1,20 @@
+import { PageTitle, usePageTrail } from "@k2b/ui";
+import { Show } from "solid-js";
+
+/**
+ * The shell's own place for the way up, above pages without a workspace. It
+ * shows only on a page with a page above it, and steps back when the page
+ * renders a workspace (whose head shows it) or its own `PageTrail`.
+ */
+export default function PageTrailRow() {
+  const trail = usePageTrail();
+  const deep = () => {
+    const current = trail();
+    return current?.ancestors.length ? current : undefined;
+  };
+  return (
+    <div class="layout-page-head" data-trail={deep() ? "up" : undefined}>
+      <Show when={deep()}>{(current) => <PageTitle trail={current()} as="p" fallback />}</Show>
+    </div>
+  );
+}

package/src/ssr/PageTrailRuntime.island.tsx

@@ -0,0 +1,26 @@
+import { followPageTrail, installPageTitleController, useLocale } from "@k2b/ui";
+import { onCleanup, onMount } from "solid-js";
+import { installPageTrailRuntime } from "./page-trail-runtime";
+import { platformMessages } from "./platform-messages";
+
+/**
+ * One owner per document for the way up: it collapses every page title path
+ * to its space, keeps server-rendered workspace heads current after
+ * `layout.update()`, runs the per-tab memory behind up links, and offers
+ * "One level up" (Alt+↑) while the page has a page above it.
+ */
+export default function PageTrailRuntime() {
+  const locale = useLocale();
+  onMount(() => {
+    const t = platformMessages.resolve([locale()]).t;
+    const disposeTitles = installPageTitleController(document);
+    const disposeFollow = followPageTrail(document);
+    const disposeRuntime = installPageTrailRuntime((page) => ({ title: t.pageUp({ page }), description: t.pageUpDescription }));
+    onCleanup(() => {
+      disposeTitles();
+      disposeFollow();
+      disposeRuntime();
+    });
+  });
+  return null;
+}

package/src/ssr/ProfilePreferences.island.tsx

@@ -8,16 +8,20 @@ type ProfilePreferencesProps = {
   avatarSrc?: string;
   initialTheme: CloudTheme;
   name: string;
-  placement: "header" | "rail";
 };
 
+/**
+ * The avatar at the bottom of the rail. Its menu opens beside the rail and,
+ * because the avatar is the rail's last control, grows upward from the window's
+ * bottom edge.
+ */
 export default function ProfilePreferences(props: ProfilePreferencesProps) {
   const { preferences, items, signOut, signingOut } = createProfileActions(props.initialTheme, props.appHref);
 
   const avatar = () => <Avatar name={props.name} src={props.avatarSrc} size="xs" />;
 
   return (
-    <div class="layout-profile-preferences" data-placement={props.placement}>
+    <div class="layout-profile-preferences">
       <button type="button" class="layout-profile-preferences__link" aria-label={preferences.messages().menuLabel}>
         {avatar()}
       </button>
@@ -49,7 +53,7 @@ export default function ProfilePreferences(props: ProfilePreferencesProps) {
         class="layout-profile-preferences__dropdown"
         items={items()}
         label={preferences.messages().menuLabel}
-        position={props.placement === "rail" ? "right-start" : "bottom-left"}
+        position="right-start"
         width="14rem"
       >
         <Dropdown.Trigger

package/src/ssr/islands/index.ts

@@ -1,3 +1,4 @@
+export { default as PageTrail, type PageTrailProps } from "../PageTrail";
 export { default as WorkspaceNavigationProvider } from "../WorkspaceNavigationProvider";
 export { provideWorkspaceNavigation } from "../workspace-navigation";
 export { default as SearchBar } from "./SearchBar";

package/src/ssr/layout-runtime.ts

@@ -1,3 +1,6 @@
+import { readPageTrail, setPageTrail } from "@k2b/ui";
+import { derivePageTrail, dropSelfLinks } from "./page-trail";
+
 export type LayoutBreadcrumb = {
   title: string;
   href?: string;
@@ -10,13 +13,70 @@ export type LayoutUpdate = {
 
 export const LAYOUT_UPDATE_EVENT = "cloud:layout:update";
 
+/** The canvas attribute that carries the current app's base path, for the trail rule in the browser. */
+export const APP_BASE_ATTRIBUTE = "data-app-base";
+/** Set on the canvas of a page that shows its title without a way up: anonymous and focus-mode pages. */
+const TITLE_ONLY_ATTRIBUTE = "data-page-trail-title-only";
+
+/**
+ * Window event before the way up (a trail link or Alt+↑) loads a page. Its
+ * `detail.href` is where it leads: the page above, as this tab left it.
+ * Cancelling it keeps the document; the listener then navigates itself.
+ */
+export const PAGE_UP_EVENT = "cloud:page-up";
+export type PageUpDetail = { href: string };
+
+const here = () => `${location.pathname}${location.search}`;
+
 export const layout = {
+  /**
+   * Updates the page after an in-page navigation: the document title, and the
+   * page title with its way up wherever the shell or `PageTrail` shows it.
+   * `breadcrumbs` is the same title array `Layout` takes, under the same rule;
+   * `title` alone renames the current page and keeps the levels above it.
+   */
   update(update: LayoutUpdate) {
     if (typeof window === "undefined") return;
 
     const title = update.title ?? update.breadcrumbs?.at(-1)?.title;
     if (title) document.title = title;
+    const canvas = document.querySelector(".cloud-app-canvas");
+    const base = canvas?.getAttribute(APP_BASE_ATTRIBUTE) ?? undefined;
+    const current = readPageTrail();
+    const derived = update.breadcrumbs?.length
+      ? derivePageTrail(update.breadcrumbs, base, title ?? current?.title ?? document.title)
+      : title && current
+        ? { ...current, title }
+        : undefined;
+    if (!derived) return;
+    const trail = update.title ? { ...derived, title: update.title } : derived;
+    setPageTrail(canvas?.hasAttribute(TITLE_ONLY_ATTRIBUTE) ? { ...trail, ancestors: [] } : trail);
+    if (update.breadcrumbs?.length) {
+      // An island may change the address right after this call, in the same task, so the link to the page itself
+      // is known only then. Comparing earlier would drop the page the island has just left.
+      queueMicrotask(() => {
+        const published = readPageTrail();
+        if (!published) return;
+        const settled = dropSelfLinks(published, here());
+        if (settled !== published) setPageTrail(settled);
+      });
+    }
 
     window.dispatchEvent(new CustomEvent<LayoutUpdate>(LAYOUT_UPDATE_EVENT, { detail: update }));
   },
+
+  /**
+   * Lets an island that navigates in place, such as a file browser, take the
+   * way up itself instead of a page load that would end its running work.
+   * `go` gets the destination and returns `true` when it goes there in place.
+   * Returns the disposer.
+   */
+  handleUp(go: (href: string) => boolean): () => void {
+    if (typeof window === "undefined") return () => {};
+    const listener = (event: Event) => {
+      if (!event.defaultPrevented && go((event as CustomEvent<PageUpDetail>).detail.href)) event.preventDefault();
+    };
+    window.addEventListener(PAGE_UP_EVENT, listener);
+    return () => window.removeEventListener(PAGE_UP_EVENT, listener);
+  },
 };

package/src/ssr/mobile-menu-history.ts

@@ -18,7 +18,7 @@ export function openMobileMenu(view: (beforeSelect: () => Promise<boolean>) => D
     history.pushState({ ...previous, [marker]: id }, "");
     const abort = new AbortController();
     let leavingPage = false;
-    const mobile = window.matchMedia("(max-width: 1023px)");
+    const mobile = window.matchMedia("(max-width: 767px)");
     const pop = () => {
       if (history.state?.[marker] !== id) abort.abort();
     };