@k2b/cloud 0.6.0-rc.0

package/src/ssr/preference-controller.ts

@@ -0,0 +1,44 @@
+import type { DropdownItem } from "@k2b/ui";
+import { createMemo, createSignal, onCleanup, onMount } from "solid-js";
+import { profilePreferenceLocale, setLocalePreference } from "../browser/locale-preference";
+import { type CloudTheme, getCurrentThemePreference, setThemePreference } from "../shared/theme";
+import { profilePreferencesMessages } from "./profile-preferences-messages";
+
+const THEME_PREFERENCE_EVENT = "cloud:theme-preference";
+
+export const createPreferenceController = (initialTheme: CloudTheme, locale: () => string) => {
+  const [theme, setTheme] = createSignal(initialTheme);
+  const messages = () => profilePreferencesMessages.resolve([locale()]).t;
+  const language = () => profilePreferenceLocale(locale());
+  const nextLanguage = () => (language() === "de" ? "en" : "de");
+  const themeLabel = () => (theme() === "light" ? messages().switchToDark : messages().switchToLight);
+  const languageLabel = () => (nextLanguage() === "de" ? messages().switchToGerman : messages().switchToEnglish);
+
+  const toggleTheme = () => {
+    setTheme(setThemePreference(theme() === "dark" ? "light" : "dark"));
+    window.dispatchEvent(new Event(THEME_PREFERENCE_EVENT));
+  };
+  const toggleLanguage = () => setLocalePreference(nextLanguage());
+
+  onMount(() => {
+    const syncTheme = () => setTheme(getCurrentThemePreference());
+    syncTheme();
+    window.addEventListener(THEME_PREFERENCE_EVENT, syncTheme);
+    onCleanup(() => window.removeEventListener(THEME_PREFERENCE_EVENT, syncTheme));
+  });
+
+  const items = createMemo<DropdownItem[]>(() => [
+    {
+      action: toggleTheme,
+      icon: theme() === "light" ? "ti ti-moon" : "ti ti-sun-high",
+      label: themeLabel(),
+    },
+    {
+      action: toggleLanguage,
+      icon: "ti ti-language",
+      label: languageLabel(),
+    },
+  ]);
+
+  return { items, languageLabel, messages, theme, themeLabel, toggleLanguage, toggleTheme };
+};

package/src/ssr/profile-preferences-messages.ts

@@ -0,0 +1,29 @@
+import { i18n } from "@k2b/stdlib";
+
+export const profilePreferencesMessages = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: {
+      menuLabel: "Profile and preferences",
+      preferencesMenuLabel: "Appearance and language",
+      profileSettings: "Profile settings",
+      signOut: "Sign out",
+      signOutFailed: "Sign out failed. Please try again.",
+      switchToDark: "Dark mode",
+      switchToLight: "Light mode",
+      switchToGerman: "Deutsch",
+      switchToEnglish: "English",
+    },
+    de: {
+      menuLabel: "Profil und Einstellungen",
+      preferencesMenuLabel: "Darstellung und Sprache",
+      profileSettings: "Profileinstellungen",
+      signOut: "Abmelden",
+      signOutFailed: "Abmelden fehlgeschlagen. Bitte versuche es erneut.",
+      switchToDark: "Dunkler Modus",
+      switchToLight: "Heller Modus",
+      switchToGerman: "Deutsch",
+      switchToEnglish: "English",
+    },
+  },
+});

package/src/ssr/rail-context.ts

@@ -0,0 +1,21 @@
+import { type RailPreferences, RailPreferencesSchema } from "../contracts/rail-preferences";
+import type { RailApp } from "./rail-navigation";
+
+export type RailContext = { apps: RailApp[]; settings: RailPreferences };
+export const RAIL_PREFERENCES_EVENT = "cloud:rail-preferences";
+
+export const readRailContext = (): RailContext | undefined => {
+  if (typeof document === "undefined") return undefined;
+  const text = document.getElementById("cloud-rail-data")?.textContent;
+  if (!text) return undefined;
+  // Framework-generated, escaped SSR data; never loaded from localStorage.
+  const value: RailContext = JSON.parse(text);
+  return { apps: value.apps, settings: RailPreferencesSchema.parse(value.settings) };
+};
+
+export const publishRailPreferences = (settings: RailPreferences) => {
+  const context = readRailContext();
+  const element = document.getElementById("cloud-rail-data");
+  if (context && element) element.textContent = JSON.stringify({ ...context, settings }).replace(/</g, "\\u003c");
+  window.dispatchEvent(new CustomEvent(RAIL_PREFERENCES_EVENT));
+};

package/src/ssr/rail-messages.ts

@@ -0,0 +1,66 @@
+import { i18n } from "@k2b/stdlib";
+
+export const railMessages = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: {
+      customize: "Customize app bar",
+      apps: "Visible apps",
+      shortcuts: "App bar shortcuts",
+      description: "Choose the apps in your app bar. Shortcuts appear above them and are separate from your dashboard shortcuts.",
+      pinned: "Pinned above the app list",
+      unavailable: "App currently unavailable",
+      empty: "No app bar shortcuts yet.",
+      addApp: "Add app shortcut",
+      addLink: "Add link shortcut",
+      app: "App",
+      title: "Title",
+      url: "Link",
+      icon: "Icon",
+      urlHint: "Use /app/… or a complete https:// address.",
+      up: "Move up",
+      down: "Move down",
+      remove: "Remove shortcut",
+      save: "Save",
+      saving: "Saving…",
+      reset: "Reset app bar",
+      unsaved: "Unsaved changes",
+      loading: "Loading app bar settings…",
+      retry: "Reload",
+      loadFailed: "Could not load app bar settings.",
+      saveFailed: "Could not save app bar settings. Your edits are still here.",
+      conflict: "The app bar changed in another editor. Cancel and reopen this editor to load the latest settings.",
+      invalid: "Check shortcut titles, links and icons. Each app can be pinned once; settings must fit within 16 KiB.",
+    },
+    de: {
+      customize: "App-Leiste anpassen",
+      apps: "Sichtbare Apps",
+      shortcuts: "Shortcuts der App-Leiste",
+      description: "Wähle die Apps für deine App-Leiste. Shortcuts stehen darüber und sind unabhängig von deinen Dashboard-Shortcuts.",
+      pinned: "Über der App-Liste angeheftet",
+      unavailable: "App derzeit nicht verfügbar",
+      empty: "Noch keine Shortcuts in der App-Leiste.",
+      addApp: "App-Shortcut hinzufügen",
+      addLink: "Link-Shortcut hinzufügen",
+      app: "App",
+      title: "Titel",
+      url: "Link",
+      icon: "Icon",
+      urlHint: "Verwende /app/… oder eine vollständige https://-Adresse.",
+      up: "Nach oben",
+      down: "Nach unten",
+      remove: "Shortcut entfernen",
+      save: "Speichern",
+      saving: "Wird gespeichert…",
+      reset: "App-Leiste zurücksetzen",
+      unsaved: "Ungespeicherte Änderungen",
+      loading: "App-Leiste wird geladen…",
+      retry: "Erneut laden",
+      loadFailed: "App-Leiste konnte nicht geladen werden.",
+      saveFailed: "App-Leiste konnte nicht gespeichert werden. Deine Änderungen sind noch vorhanden.",
+      conflict:
+        "Die App-Leiste wurde in einem anderen Editor geändert. Brich ab und öffne den Editor erneut, um den aktuellen Stand zu laden.",
+      invalid: "Prüfe Titel, Links und Icons. Jede App kann einmal angeheftet werden; die Einstellungen dürfen höchstens 16 KiB belegen.",
+    },
+  },
+});

package/src/ssr/rail-navigation.ts

@@ -0,0 +1,60 @@
+import type { RailPreferences } from "../contracts/rail-preferences";
+
+export type RailApp = {
+  id: string;
+  iconClass: string;
+  label: string;
+  href: string;
+  match: string;
+  defaultVisible: boolean;
+  description?: string;
+  accent?: string;
+};
+export type RailLink = Omit<RailApp, "defaultVisible"> & { exact?: boolean };
+
+export const isRailAppVisible = (app: RailApp, settings: RailPreferences): boolean =>
+  Object.hasOwn(settings.visibility, app.id) ? (settings.visibility[app.id] ?? app.defaultVisible) : app.defaultVisible;
+
+export const sortRailApps = (apps: readonly RailApp[], locale: string): RailApp[] => {
+  const collator = new Intl.Collator(locale, { sensitivity: "base", numeric: true });
+  return [...apps].sort((a, b) => collator.compare(a.label, b.label) || a.id.localeCompare(b.id, "en"));
+};
+
+/** Input is the authorized navigation catalog, never the unfiltered registry. */
+export const projectRailNavigation = (apps: readonly RailApp[], settings: RailPreferences, locale: string) => {
+  const catalog = new Map(apps.map((app) => [app.id, app]));
+  const pinned = new Set<string>();
+  const shortcuts: RailLink[] = [];
+  for (const shortcut of settings.shortcuts) {
+    if (shortcut.kind === "app") {
+      const app = catalog.get(shortcut.appId);
+      if (!app || pinned.has(app.id)) continue;
+      pinned.add(app.id);
+      shortcuts.push({ ...app, id: shortcut.id });
+    } else {
+      shortcuts.push({
+        id: shortcut.id,
+        href: shortcut.href,
+        label: shortcut.title,
+        iconClass: shortcut.icon,
+        match: shortcut.href,
+        exact: true,
+      });
+    }
+  }
+  return {
+    shortcuts,
+    apps: sortRailApps(apps, locale).filter((app) => !pinned.has(app.id) && isRailAppVisible(app, settings)),
+  };
+};
+
+export const railLinkActive = (link: RailLink, currentUrl: string): boolean => {
+  const current = new URL(currentUrl, "https://cloud.invalid");
+  const target = new URL(link.match, current);
+  if (target.origin !== current.origin) return false;
+  if (link.exact) return target.pathname === current.pathname && target.search === current.search && target.hash === current.hash;
+  return (
+    current.pathname === target.pathname ||
+    (target.pathname !== "/" && current.pathname.startsWith(`${target.pathname.replace(/\/$/, "")}/`))
+  );
+};

package/src/ssr/runtime.ts

@@ -0,0 +1,31 @@
+/**
+ * Runtime context helpers for SSR components.
+ * Extracted from _core/runtime-helpers.ts — only the generic parts.
+ */
+import type { CloudRuntime } from "../contracts/app";
+import { getLocale } from "../server/locale";
+import { resolveAppPresentations } from "../shared/app-presentation";
+
+export type RuntimeContext = CloudRuntime;
+
+type RuntimeCarrier = {
+  get: (key: any) => unknown;
+};
+
+/**
+ * Reads the runtime context from a Hono request context.
+ */
+export const getRuntimeContext = (carrier: RuntimeCarrier): RuntimeContext => {
+  const runtime = carrier.get("runtime");
+  if (!runtime || typeof runtime !== "object" || !Array.isArray((runtime as RuntimeContext).apps)) {
+    throw new Error("Runtime context is missing on request context");
+  }
+  return runtime as RuntimeContext;
+};
+
+/** Request-scoped runtime projection with only app-owned human presentation localized. */
+export const getLocalizedRuntimeContext = (carrier: RuntimeCarrier & { req: { raw: { headers: Headers } } }): RuntimeContext => {
+  const runtime = getRuntimeContext(carrier);
+  const locale = getLocale(carrier as Parameters<typeof getLocale>[0]);
+  return { ...runtime, apps: resolveAppPresentations(runtime.apps, locale) };
+};

package/src/ssr/url-filter.ts

@@ -0,0 +1,127 @@
+/**
+ * URL-backed filter state for server-rendered pages.
+ *
+ * Every admin page reimplemented the same triple — parse the query string,
+ * rebuild it with a patch, decide whether anything is active — and the copies
+ * diverged in ways that leaked into behaviour: some baked the path in and some
+ * took it as a parameter, some reset pagination and some did not, one dropped
+ * the time window when clearing filters, and several rebuilt the pagination
+ * base URL a second time by hand.
+ *
+ * The URL stays the single source of truth: filtering, sorting and paging are
+ * server concerns, and a page that keeps them in the address bar is reloadable
+ * and shareable by construction.
+ */
+
+export type UrlFilterField<T> = {
+  /** Query parameter name. */
+  param: string;
+  /** Value when the parameter is absent or invalid. Omitted from built URLs. */
+  fallback: T;
+  /** Rejects hand-edited values before they reach SQL. */
+  parse: (raw: string | null, all: string[]) => T;
+  /** Omit the parameter entirely by returning an empty array. */
+  serialize?: (value: T) => string[];
+};
+
+// biome-ignore lint/suspicious/noExplicitAny: each field carries its own value type; `any` is the only constraint that preserves them through inference.
+type FieldMap = Record<string, UrlFilterField<any>>;
+
+type StateOf<F extends FieldMap> = { [K in keyof F]: F[K] extends UrlFilterField<infer T> ? T : never };
+
+const defaultSerialize = (value: unknown): string[] => {
+  if (value === null || value === undefined || value === "" || value === false) return [];
+  if (Array.isArray(value)) return value.map(String);
+  return [String(value)];
+};
+
+/** A string field constrained to a known set — the common case for enums. */
+export const oneOf = <T extends string>(param: string, values: readonly T[], fallback: T): UrlFilterField<T> => ({
+  param,
+  fallback,
+  parse: (raw) => (raw !== null && (values as readonly string[]).includes(raw) ? (raw as T) : fallback),
+});
+
+export const text = (param: string, fallback = ""): UrlFilterField<string> => ({
+  param,
+  fallback,
+  parse: (raw) => raw?.trim() ?? fallback,
+});
+
+/** Present-means-true, so the parameter disappears when switched off. */
+export const flag = (param: string): UrlFilterField<boolean> => ({
+  param,
+  fallback: false,
+  parse: (raw) => raw === "1",
+  serialize: (value) => (value ? ["1"] : []),
+});
+
+export const list = (param: string): UrlFilterField<string[]> => ({
+  param,
+  fallback: [],
+  parse: (_raw, all) => [...new Set(all.map((value) => value.trim()).filter(Boolean))],
+});
+
+export const page = (param = "page"): UrlFilterField<number> => ({
+  param,
+  fallback: 1,
+  parse: (raw) => {
+    const parsed = Number(raw ?? "1");
+    return Number.isFinite(parsed) && parsed > 0 ? Math.trunc(parsed) : 1;
+  },
+  serialize: (value) => (value > 1 ? [String(value)] : []),
+});
+
+export const createUrlFilter = <F extends FieldMap>(basePath: string, fields: F) => {
+  const entries = Object.entries(fields) as [keyof F & string, UrlFilterField<unknown>][];
+
+  const parse = (url: URL): StateOf<F> => {
+    const state = {} as Record<string, unknown>;
+    for (const [key, field] of entries) {
+      state[key] = field.parse(url.searchParams.get(field.param), url.searchParams.getAll(field.param));
+    }
+    return state as StateOf<F>;
+  };
+
+  /** Values equal to the fallback are omitted, so the common URL stays clean. */
+  const build = (current: StateOf<F>, updates: Partial<StateOf<F>> = {}): string => {
+    const next = { ...current, ...updates } as Record<string, unknown>;
+    const params = new URLSearchParams();
+    for (const [key, field] of entries) {
+      const value = next[key];
+      if (JSON.stringify(value) === JSON.stringify(field.fallback)) continue;
+      for (const serialized of (field.serialize ?? defaultSerialize)(value as never)) params.append(field.param, serialized);
+    }
+    const query = params.toString();
+    return query ? `${basePath}?${query}` : basePath;
+  };
+
+  /**
+   * Pagination components append the page number to this, so it must always
+   * end in a usable separator. Eight pages derived it by hand before.
+   */
+  const paginationBase = (current: StateOf<F>, pageKey: keyof F & string): string => {
+    const field = fields[pageKey] as UrlFilterField<unknown> | undefined;
+    if (!field) return basePath;
+    const url = build({ ...current, [pageKey]: field.fallback } as StateOf<F>);
+    return url.includes("?") ? `${url}&${field.param}=` : `${url}?${field.param}=`;
+  };
+
+  /** Whether anything differs from the defaults — drives the clear affordance. */
+  const isActive = (current: StateOf<F>, ignore: (keyof F & string)[] = []): boolean =>
+    entries.some(
+      ([key, field]) =>
+        !ignore.includes(key) && JSON.stringify((current as Record<string, unknown>)[key]) !== JSON.stringify(field.fallback),
+    );
+
+  /** Resets to defaults, optionally keeping fields that are not really filters. */
+  const clear = (current: StateOf<F>, keep: (keyof F & string)[] = []): string => {
+    const next = {} as Record<string, unknown>;
+    for (const [key, field] of entries) {
+      next[key] = keep.includes(key) ? (current as Record<string, unknown>)[key] : field.fallback;
+    }
+    return build(next as StateOf<F>);
+  };
+
+  return { basePath, parse, build, paginationBase, isActive, clear };
+};

package/src/styles/base-popover.css

@@ -0,0 +1,36 @@
+/* Popover and island base behavior */
+/* Make solid-island transparent in layout */
+solid-island {
+  display: contents;
+}
+
+/* Popover positioning. Strip the UA-default white box only when a
+   popover has not opted into one of the shared floating surfaces. */
+:where([popover]:not(.paper):not(.popup):not(.tooltip-surface):not(.dropdown-menu-surface):not(.context-menu-surface)) {
+  background: transparent;
+  border: none;
+}
+
+[popover] {
+  margin: 0;
+  inset: unset;
+}
+
+/* Popovers are interaction primitives, not one animation family. A global
+   display/overlay transition keeps a closing popover painted after
+   `hidePopover()` and strips its `:popover-open` layout during that frame.
+   Surfaces that benefit from motion opt in below. */
+.tooltip-surface[popover] {
+  transform: none;
+  transition:
+    opacity 0.12s,
+    overlay 0.12s allow-discrete,
+    display 0.12s allow-discrete;
+}
+
+.tooltip-surface[popover]:popover-open {
+  @starting-style {
+    opacity: 0;
+    transform: none;
+  }
+}