@k2b/cloud 0.6.0-rc.0

package/src/shared/theme.ts

@@ -0,0 +1,68 @@
+export type CloudTheme = "light" | "dark";
+
+const THEME_COOKIE = "theme";
+const COOKIE_MAX_AGE_SECONDS = 31536000;
+
+const isCloudTheme = (value: string): value is CloudTheme => value === "light" || value === "dark";
+
+const decodeCookieValue = (value: string): string => {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+};
+
+/**
+ * Resolve the persisted theme from a Cookie header.
+ *
+ * Browsers can send duplicate cookie names when legacy path-specific cookies
+ * exist. RFC ordering puts more specific paths first, so the root preference
+ * written by the current app is usually the last valid `theme` entry.
+ */
+export const readThemeFromCookieHeader = (cookieHeader: string | null | undefined): CloudTheme => {
+  let resolved: CloudTheme = "light";
+  for (const part of (cookieHeader ?? "").split(";")) {
+    const trimmed = part.trim();
+    const separatorIndex = trimmed.indexOf("=");
+    if (separatorIndex <= 0) continue;
+    if (trimmed.slice(0, separatorIndex) !== THEME_COOKIE) continue;
+
+    const value = decodeCookieValue(trimmed.slice(separatorIndex + 1));
+    if (isCloudTheme(value)) resolved = value;
+  }
+  return resolved;
+};
+
+export const themeBootstrapScript = `!function(){var e=document.documentElement;if(!e.hasAttribute("data-theme-fixed")){var t="light";document.cookie.split(";").forEach(function(e){var r=e.trim(),i=r.indexOf("=");if(i>0&&r.slice(0,i)==="theme"){var o;try{o=decodeURIComponent(r.slice(i+1))}catch(e){o=r.slice(i+1)}(o==="light"||o==="dark")&&(t=o)}});e.classList.remove("light","dark");e.classList.add(t)}}();`;
+
+const legacyThemeCookiePaths = (pathname: string): string[] => {
+  const paths = new Set(["/", "/me", "/app", "/admin"]);
+  if (pathname) paths.add(pathname);
+  const parts = pathname.split("/").filter(Boolean);
+  let current = "";
+  for (const part of parts) {
+    current += `/${part}`;
+    paths.add(current);
+  }
+  return [...paths];
+};
+
+export const setThemePreference = (mode: CloudTheme): CloudTheme => {
+  if (typeof document === "undefined") return mode;
+
+  document.documentElement.classList.remove("light", "dark");
+  document.documentElement.classList.add(mode);
+
+  const secure = location.protocol === "https:" ? "; Secure" : "";
+  for (const path of legacyThemeCookiePaths(location.pathname)) {
+    document.cookie = `${THEME_COOKIE}=; path=${path}; max-age=0; expires=Thu, 01 Jan 1970 00:00:00 GMT; SameSite=Lax${secure}`;
+  }
+  document.cookie = `${THEME_COOKIE}=${encodeURIComponent(mode)}; path=/; max-age=${COOKIE_MAX_AGE_SECONDS}; SameSite=Lax${secure}`;
+  return mode;
+};
+
+export const getCurrentThemePreference = (): CloudTheme => {
+  if (typeof document === "undefined") return "light";
+  return document.documentElement.classList.contains("dark") ? "dark" : "light";
+};

package/src/shared/time.ts

@@ -0,0 +1,13 @@
+export const TIMEZONE_COOKIE = "cloud.timezone";
+
+export const normalizeTimeZone = (value: string | null | undefined, fallback = "UTC"): string => {
+  const candidate = typeof value === "string" ? value.trim() : "";
+  if (!candidate) return fallback;
+
+  try {
+    new Intl.DateTimeFormat(undefined, { timeZone: candidate }).format(new Date());
+    return candidate;
+  } catch {
+    return fallback;
+  }
+};

package/src/ssr/AdminLayout.tsx

@@ -0,0 +1,53 @@
+import { AppWorkspace } from "@k2b/ui";
+import type { JSX } from "solid-js/jsx-runtime";
+import type { RailPreferences } from "../contracts/rail-preferences";
+import { getLocale } from "../server/locale";
+import type { LayoutAnnouncementsState } from "../server/middleware/settings";
+import AdminSidebar from "./AdminSidebar";
+import Layout from "./Layout";
+import { platformMessages } from "./platform-messages";
+import { getLocalizedRuntimeContext, type RuntimeContext } from "./runtime";
+
+type Breadcrumb = { title: string; href?: string };
+type AdminLayoutContext = {
+  get(key: "railPreferences"): RailPreferences | undefined;
+  get(key: "user"): any;
+  get(key: "page"): any;
+  get(key: "runtime"): RuntimeContext;
+  get(key: "settings"): Record<string, any>;
+  get(key: "announcements"): LayoutAnnouncementsState | undefined;
+  req: { raw: { headers: Headers; url: string } };
+};
+type Props = {
+  children: JSX.Element;
+  c: AdminLayoutContext;
+  title: string;
+  /** Disable when a bounded child such as SettingsPage owns scrolling. */
+  scroll?: boolean;
+};
+export default function AdminLayout({ children, c, title, scroll = true }: Props) {
+  const locale = getLocale(c);
+  const t = platformMessages.resolve([locale]).t;
+  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 });
+  }
+  return (
+    <Layout c={c} fullWidth fullPage title={breadcrumbs}>
+      <AppWorkspace class="min-h-0 flex-1" resizable={false}>
+        <AdminSidebar currentPath={currentPath} apps={runtime.apps} />
+        <AppWorkspace.Content>
+          <AppWorkspace.Main scroll={scroll} class={scroll ? "p-[var(--ui-space-shell)]" : undefined}>
+            {children}
+          </AppWorkspace.Main>
+        </AppWorkspace.Content>
+      </AppWorkspace>
+    </Layout>
+  );
+}

package/src/ssr/AdminSidebar.tsx

@@ -0,0 +1,50 @@
+import { AppWorkspace, useLocale } from "@k2b/ui";
+import { activeAdminHref } from "./admin-active-link";
+import { type AdminLink, buildAdminGroups } from "./admin-navigation";
+import type { RuntimeContext } from "./runtime";
+import { platformMessages } from "./platform-messages";
+
+const AdminNavigation = (props: { currentPath: string; groups: ReturnType<typeof buildAdminGroups> }) => {
+  const activeHref = activeAdminHref(
+    props.currentPath,
+    props.groups.flatMap((group) => group.links.map((link: AdminLink) => link.href)),
+  );
+  return (
+    <>
+      {props.groups.map((group) => (
+        <AppWorkspace.SidebarSection title={group.label}>
+          {group.links.map((link: AdminLink) => (
+            <AppWorkspace.SidebarItem href={link.href} navigation="document" active={link.href === activeHref} title={link.label}>
+              <AppWorkspace.SidebarItemIcon icon={`ti ${link.icon}`} />
+              <AppWorkspace.SidebarItemLabel>{link.label}</AppWorkspace.SidebarItemLabel>
+            </AppWorkspace.SidebarItem>
+          ))}
+        </AppWorkspace.SidebarSection>
+      ))}
+    </>
+  );
+};
+
+export default function AdminSidebar({ currentPath, apps }: { currentPath: string; apps: readonly RuntimeContext["apps"][number][] }) {
+  const locale = useLocale();
+  const t = () => platformMessages.resolve([locale()]).t;
+  const groups = () => buildAdminGroups(apps, locale());
+
+  return (
+    <AppWorkspace.Sidebar resizable={false}>
+      <AppWorkspace.SidebarMobileTrigger label={t().admin} />
+
+      <AppWorkspace.SidebarMobile>
+        <AppWorkspace.SidebarMobileBody scrollPreserveKey="admin-sidebar-mobile">
+          <AdminNavigation currentPath={currentPath} groups={groups()} />
+        </AppWorkspace.SidebarMobileBody>
+      </AppWorkspace.SidebarMobile>
+
+      <AppWorkspace.SidebarDesktop>
+        <AppWorkspace.SidebarBody scrollPreserveKey="admin-sidebar">
+          <AdminNavigation currentPath={currentPath} groups={groups()} />
+        </AppWorkspace.SidebarBody>
+      </AppWorkspace.SidebarDesktop>
+    </AppWorkspace.Sidebar>
+  );
+}

package/src/ssr/AppLaunchpad.island.tsx

@@ -0,0 +1,236 @@
+import { dialogCore, IconButton, ScrollArea, Tooltip, useLocale } from "@k2b/ui";
+import { createEffect, For, Show } from "solid-js";
+import { platformMessages } from "./platform-messages";
+import { openRailEditor } from "./RailEditor";
+import { readRailContext } from "./rail-context";
+import { railMessages } from "./rail-messages";
+import { projectRailNavigation } from "./rail-navigation";
+
+export type AppLaunchpadApp = {
+  id: string;
+  iconClass: string;
+  label: string;
+  href: string;
+  description?: string;
+  accent?: string;
+};
+
+export type AppLaunchpadLegalLink = {
+  label: string;
+  href: string;
+  icon?: string;
+};
+
+type AppLaunchpadContext = {
+  apps: AppLaunchpadApp[];
+  legalLinks: AppLaunchpadLegalLink[];
+};
+
+type AppIconPaletteEntry = { from: string };
+
+const appIconPalette: readonly [AppIconPaletteEntry, ...AppIconPaletteEntry[]] = [
+  { from: "#2563eb" },
+  { from: "#059669" },
+  { from: "#7c3aed" },
+  { from: "#d97706" },
+  { from: "#e11d48" },
+  { from: "#0891b2" },
+  { from: "#52525b" },
+];
+
+declare global {
+  interface Window {
+    __cloudAppLaunchpad?: AppLaunchpadContext;
+    cloud?: {
+      openAppLaunchpad?: () => void;
+    };
+  }
+}
+
+const paletteForId = (id: string) => {
+  let hash = 0;
+  for (let i = 0; i < id.length; i++) hash = (hash + id.charCodeAt(i)) % appIconPalette.length;
+  return appIconPalette[hash] ?? appIconPalette[0];
+};
+
+const appIconStyle = (app: AppLaunchpadApp) => {
+  const tone = /^#[0-9a-f]{6}$/i.test(app.accent ?? "") ? app.accent! : paletteForId(app.id).from;
+  return `--app-icon-color:${tone}`;
+};
+
+const readEmbeddedContext = (): AppLaunchpadContext | undefined => {
+  if (typeof document === "undefined") return undefined;
+  const element = document.getElementById("cloud-app-launchpad-data");
+  const text = element?.textContent;
+  if (!text) return undefined;
+
+  try {
+    const parsed = JSON.parse(text) as Partial<AppLaunchpadContext>;
+    if (!Array.isArray(parsed.apps)) return undefined;
+    return {
+      apps: parsed.apps,
+      legalLinks: Array.isArray(parsed.legalLinks) ? parsed.legalLinks : [],
+    };
+  } catch {
+    return undefined;
+  }
+};
+
+const AppLaunchpadPanel = (props: AppLaunchpadContext & { close: () => void }) => {
+  const locale = useLocale();
+  const t = () => railMessages.resolve([locale()]).t;
+  const rail = readRailContext();
+  const shortcuts = () => (rail ? projectRailNavigation(rail.apps, rail.settings, locale()).shortcuts : []);
+  return (
+    <ScrollArea class="launchpad-panel mx-auto max-h-[min(86vh,var(--ui-dialog-available-height))] w-[var(--ui-dialog-available-width)] max-w-[var(--ui-dialog-available-width)] overscroll-contain p-4 text-primary sm:w-fit sm:p-6 md:p-7 dark:text-white">
+      <Show when={rail}>
+        <div class="mb-2 flex justify-end">
+          <IconButton
+            variant="ghost"
+            size="sm"
+            label={t().customize}
+            tooltip={t().customize}
+            tooltipDelay={0}
+            onClick={() => {
+              props.close();
+              openRailEditor(locale());
+            }}
+          >
+            <i class="ti ti-adjustments-horizontal" aria-hidden="true" />
+          </IconButton>
+        </div>
+      </Show>
+      <Show when={shortcuts().length > 0}>
+        <section class="mb-5 flex flex-col gap-3" aria-label={t().shortcuts}>
+          <h3 class="text-center text-sm font-medium">{t().shortcuts}</h3>
+          <div class="flex flex-wrap justify-center gap-2">
+            <For each={shortcuts()}>
+              {(shortcut) => (
+                <a
+                  href={shortcut.href}
+                  class="inline-flex items-center gap-2 rounded-lg border border-[var(--ui-border)] px-3 py-2 text-sm"
+                >
+                  <i class={shortcut.iconClass} aria-hidden="true" />
+                  {shortcut.label}
+                </a>
+              )}
+            </For>
+          </div>
+        </section>
+      </Show>
+      <div class="flex flex-wrap justify-center gap-x-4 gap-y-4 sm:gap-x-7 sm:gap-y-6">
+        <For each={props.apps}>
+          {(app) => (
+            <a
+              href={app.href}
+              class="group flex w-[4.75rem] min-w-0 flex-col items-center gap-1.5 rounded-2xl p-1 text-center outline-none focus-visible:ring-2 focus-visible:ring-white/60 sm:w-[6.25rem] sm:gap-2 sm:p-2"
+            >
+              <span
+                class="app-icon grid h-12 w-12 place-items-center rounded-[0.95rem] text-[1.25rem] sm:h-16 sm:w-16 sm:rounded-[1.25rem] sm:text-[1.7rem]"
+                style={appIconStyle(app)}
+              >
+                <i class={app.iconClass} />
+              </span>
+              <span class="max-w-full truncate text-[11px] font-medium text-primary sm:text-xs dark:text-white">{app.label}</span>
+            </a>
+          )}
+        </For>
+      </div>
+      <Show when={props.legalLinks.length > 0}>
+        <div class="mt-7 flex flex-wrap justify-center text-[11px] text-dimmed dark:text-white/56">
+          <For each={props.legalLinks}>
+            {(link) => (
+              <a
+                href={link.href}
+                class="inline-flex items-center gap-1.5 rounded-md px-2 py-1 transition-colors hover:text-primary dark:hover:text-white"
+              >
+                <i class={link.icon ?? "ti ti-file-text"} />
+                {link.label}
+              </a>
+            )}
+          </For>
+        </div>
+      </Show>
+    </ScrollArea>
+  );
+};
+
+export function setAppLaunchpadContext(apps: AppLaunchpadApp[], legalLinks: AppLaunchpadLegalLink[] = []) {
+  if (typeof window === "undefined") return;
+  window.__cloudAppLaunchpad = { apps, legalLinks };
+  window.cloud ??= {};
+  window.cloud.openAppLaunchpad = () => {
+    openAppLaunchpad();
+  };
+}
+
+export function openAppLaunchpad(apps?: AppLaunchpadApp[], legalLinks?: AppLaunchpadLegalLink[]) {
+  if (typeof window === "undefined") return;
+  const context = apps ? { apps, legalLinks: legalLinks ?? [] } : (window.__cloudAppLaunchpad ?? readEmbeddedContext());
+  if (!context || context.apps.length === 0) return;
+  window.__cloudAppLaunchpad = context;
+  void dialogCore.open<void>((close) => <AppLaunchpadPanel apps={context.apps} legalLinks={context.legalLinks} close={close} />, {
+    panelClassName: "k2b-dialog k2b-dialog--large is-bare",
+    contentClassName: "k2b-dialog__viewport is-bare",
+    initialFocus: (dialog) => dialog.querySelector<HTMLAnchorElement>("a[href]"),
+  });
+}
+
+export function AppLaunchpadProvider(props: AppLaunchpadContext) {
+  createEffect(() => {
+    setAppLaunchpadContext(props.apps, props.legalLinks);
+  });
+
+  return <span class="hidden" data-cloud-app-launchpad-provider />;
+}
+
+export function AppLaunchpadButton(props: AppLaunchpadContext & { variant: "rail" | "header" | "menu"; label?: string }) {
+  const locale = useLocale();
+  const t = () => platformMessages.resolve([locale()]).t;
+  const open = () => openAppLaunchpad(props.apps, props.legalLinks);
+
+  if (props.variant === "rail") {
+    return (
+      <Tooltip.Trigger
+        type="button"
+        class="rail-item shrink-0"
+        content={props.label ?? t().apps}
+        placement="right"
+        delay={0}
+        aria-label={props.label ?? t().openApps}
+        onClick={open}
+      >
+        <i class="ti ti-grid-dots text-base" aria-hidden="true" />
+      </Tooltip.Trigger>
+    );
+  }
+
+  if (props.variant === "header") {
+    return (
+      <IconButton label={props.label ?? t().openApps} onClick={open}>
+        <i class="ti ti-grid-dots text-lg" />
+      </IconButton>
+    );
+  }
+
+  return (
+    <button
+      type="button"
+      class="flex w-full items-center gap-3 px-4 py-2 text-sm transition-colors hover:bg-white/30 dark:hover:bg-white/10 text-zinc-700 dark:text-zinc-300"
+      onClick={open}
+    >
+      <i class="ti ti-grid-dots" />
+      <span>{props.label ?? t().apps}</span>
+    </button>
+  );
+}
+
+export function AppLaunchpad(props: AppLaunchpadContext & { variant?: "provider" | "rail" | "header" | "menu"; label?: string }) {
+  if (!props.variant || props.variant === "provider") {
+    return <AppLaunchpadProvider apps={props.apps} legalLinks={props.legalLinks} />;
+  }
+
+  return <AppLaunchpadButton apps={props.apps} legalLinks={props.legalLinks} variant={props.variant} label={props.label} />;
+}
+
+export default AppLaunchpad;

package/src/ssr/AppWorkspaceController.island.tsx

@@ -0,0 +1,21 @@
+import { installAppWorkspaceController, serializeAppWorkspaceLayoutState } from "@k2b/ui";
+import { onCleanup, onMount } from "solid-js";
+import { appWorkspaceCookieName, readAppWorkspaceLayoutCookie } from "../_internal/app-workspace-state";
+
+const writeLayoutCookie = (appId: string | null | undefined, state: Parameters<typeof serializeAppWorkspaceLayoutState>[0]) => {
+  if (!appId) return;
+  const secure = window.location.protocol === "https:" ? "; Secure" : "";
+  document.cookie = `${appWorkspaceCookieName(appId)}=${serializeAppWorkspaceLayoutState(state)}; Path=/; Max-Age=31536000; SameSite=Lax${secure}`;
+};
+
+export default function AppWorkspaceController(props: { appId?: string | null }) {
+  let dispose = () => {};
+  onMount(() => {
+    dispose = installAppWorkspaceController({
+      readState: () => readAppWorkspaceLayoutCookie(document.cookie, props.appId),
+      writeState: (state) => writeLayoutCookie(props.appId, state),
+    });
+  });
+  onCleanup(() => dispose());
+  return null;
+}

package/src/ssr/BrowserNotifications.island.tsx

@@ -0,0 +1,135 @@
+import { IconButton, useLocale } from "@k2b/ui";
+import { createSignal, onCleanup, onMount, Show } from "solid-js";
+import { createLiveWebSocket } from "../browser/live-websocket";
+import { notificationTargetMatchesLocation } from "../browser/notification-target";
+import { browserNotificationClient } from "../browser/notifications";
+import {
+  NOTIFICATION_LIVE_WS_TYPE,
+  type NotificationLiveClientMessage,
+  type NotificationLiveEvent,
+  NotificationLiveEventSchema,
+  type NotificationLiveServerMessage,
+  NotificationStreamCursorSchema,
+  parseNotificationLiveServerMessage,
+} from "../contracts/notification-live";
+import { platformMessages } from "./platform-messages";
+
+const cursorStorageKey = (userId: string): string => `cloud.notifications.live-cursor:${userId}`;
+
+const readStoredCursor = (userId: string): string | null => {
+  try {
+    const cursor = sessionStorage.getItem(cursorStorageKey(userId));
+    return NotificationStreamCursorSchema.safeParse(cursor).success ? cursor : null;
+  } catch {
+    return null;
+  }
+};
+
+const storeCursor = (userId: string, cursor: string) => {
+  try {
+    sessionStorage.setItem(cursorStorageKey(userId), cursor);
+  } catch {
+    // Private or restricted browsing may disable storage; in-memory resume still works.
+  }
+};
+
+export default function BrowserNotifications(props: { userId: string }) {
+  const locale = useLocale();
+  const t = () => platformMessages.resolve([locale()]).t;
+  const [notification, setNotification] = createSignal<NotificationLiveEvent | null>(null);
+  const seen = new Set<string>();
+
+  onMount(() => {
+    const receive = (value: NotificationLiveEvent) => {
+      if (seen.has(value.eventId)) return true;
+      seen.add(value.eventId);
+      if (seen.size > 500) seen.delete(seen.values().next().value ?? "");
+      if (value.targetHref && notificationTargetMatchesLocation(value.targetHref, window.location.href)) return true;
+      setNotification(value);
+      return true;
+    };
+
+    void browserNotificationClient.refreshExisting().catch((error) => {
+      console.warn("[notifications] Failed to refresh the browser endpoint", error);
+    });
+
+    const onMessage = (event: MessageEvent<unknown>) => {
+      const parsed = NotificationLiveEventSchema.safeParse(event.data);
+      if (!parsed.success) return;
+      receive(parsed.data);
+      event.ports[0]?.postMessage({ received: true });
+    };
+    navigator.serviceWorker?.addEventListener("message", onMessage);
+
+    const initialCursor = readStoredCursor(props.userId);
+    const connection = createLiveWebSocket<NotificationLiveServerMessage>({
+      url: "/api/me/notifications/ws",
+      initialCursor,
+      activity: "visible",
+      subscribe: (cursor) =>
+        ({
+          type: NOTIFICATION_LIVE_WS_TYPE.subscribe,
+          payload: { fromCursor: cursor },
+        }) satisfies NotificationLiveClientMessage,
+      parse: parseNotificationLiveServerMessage,
+      onMessage: (message, controls) => {
+        if (message.type === NOTIFICATION_LIVE_WS_TYPE.ready) {
+          controls.markApplied(message.payload.cursor);
+          storeCursor(props.userId, message.payload.cursor);
+          return;
+        }
+        if (message.type === NOTIFICATION_LIVE_WS_TYPE.event) {
+          receive(message.payload.event);
+          controls.markApplied(message.payload.cursor);
+          storeCursor(props.userId, message.payload.cursor);
+          return;
+        }
+        if (message.type === NOTIFICATION_LIVE_WS_TYPE.revoked) {
+          controls.terminate({ code: message.payload.code, message: message.payload.message });
+        }
+      },
+      onFatal: (error) => {
+        if (error.code === "login_required" || error.code === "access_denied") window.location.reload();
+        else console.warn("[notifications] Foreground updates stopped", error);
+      },
+    });
+    connection.connect();
+
+    onCleanup(() => {
+      navigator.serviceWorker?.removeEventListener("message", onMessage);
+      connection.dispose();
+    });
+  });
+
+  return (
+    <Show when={notification()} keyed>
+      {(item) => (
+        <aside
+          class="paper fixed bottom-3 left-3 right-3 z-40 flex items-start gap-3 p-3 shadow-lg sm:left-auto sm:w-96"
+          aria-live="polite"
+          aria-label={t().newNotification}
+        >
+          <span class="flex h-8 w-8 shrink-0 items-center justify-center rounded-md bg-blue-500/10 text-blue-600 dark:bg-blue-400/15 dark:text-blue-400">
+            <i class="ti ti-bell" />
+          </span>
+          <div class="min-w-0 flex-1">
+            <p class="truncate text-sm font-medium text-primary">{item.title}</p>
+            <p class="mt-0.5 text-xs text-dimmed">{t().relatedItemReady}</p>
+            {item.targetHref && (
+              <a
+                href={item.targetHref}
+                class="mt-2 inline-flex items-center gap-1 text-xs font-medium text-blue-600 hover:underline dark:text-blue-400"
+              >
+                {t().open}
+                <i class="ti ti-arrow-right" />
+              </a>
+            )}
+          </div>
+          <IconButton size="xs" class="shrink-0" label={t().dismissNotification} onClick={() => setNotification(null)}>
+            <i class="ti ti-x" />
+          </IconButton>
+        </aside>
+      )}
+    </Show>
+  );
+}