@bygghammar/cms-platform 0.80.0 → 0.90.0-m7.1

package/src/modules/public-runtime.tsx

@@ -0,0 +1,159 @@
+/**
+ * Lazy public-site contributions from enabled modules.
+ *
+ * A module registers a *loader*, never a component. Two consequences that are
+ * the whole point:
+ *
+ * 1. Defining a module costs nothing. Registration does not import the module's
+ *    implementation, so a site that has popups switched off never evaluates the
+ *    popup runtime and never asks the browser for its chunk.
+ * 2. Loading happens after hydration, on the client only. The server renders
+ *    nothing here and so does the first client render, so there is nothing for
+ *    hydration to disagree about.
+ *
+ * The loaders are ordinary local `import()` calls that the host's bundler turns
+ * into chunks. Nothing is ever fetched from a remote origin.
+ */
+import { useEffect, useState } from "react";
+import type { ComponentType, ReactNode } from "react";
+import type { CmsModuleKey, SiteFeatureFlags } from "../config/modules";
+import { CMS_MODULE_LIST } from "../config/modules";
+import { siteConfig } from "../config/site-config";
+
+/** What a loader must resolve to: a module with a default-exported component. */
+export type ModuleComponentLoader = () => Promise<{ default: ComponentType }>;
+
+const publicLoaders = new Map<CmsModuleKey, ModuleComponentLoader>();
+const adminLoaders = new Map<CmsModuleKey, ModuleComponentLoader>();
+
+/**
+ * Register a module's public component loader.
+ *
+ * Idempotent by key: bundlers evaluate a module once, but a site may call this
+ * from more than one entry, and mounting the same runtime twice would double
+ * every impression it records.
+ */
+export function registerModuleRuntime(key: CmsModuleKey, load: ModuleComponentLoader): void {
+  const declared = CMS_MODULE_LIST.find((module) => module.key === key);
+  if (declared?.hasPublicRuntime !== true) {
+    throw new Error(
+      `@bygghammar/cms-platform: module "${key}" did not declare hasPublicRuntime, so it cannot contribute to the public site.`,
+    );
+  }
+  publicLoaders.set(key, load);
+}
+
+/** Register a module's backoffice screen loader. */
+export function registerModuleAdmin(key: CmsModuleKey, load: ModuleComponentLoader): void {
+  adminLoaders.set(key, load);
+}
+
+/** Test helper. Not part of the site-facing contract. */
+export function clearModuleRuntimes(): void {
+  publicLoaders.clear();
+  adminLoaders.clear();
+}
+
+/** Which registered public runtimes the given feature set enables, in table order. */
+export function enabledModuleRuntimes(
+  features: SiteFeatureFlags,
+): readonly { key: CmsModuleKey; load: ModuleComponentLoader }[] {
+  return CMS_MODULE_LIST.flatMap((module) => {
+    if (features[module.key] !== true) return [];
+    const load = publicLoaders.get(module.key);
+    return load === undefined ? [] : [{ key: module.key, load }];
+  });
+}
+
+export function moduleAdminLoader(key: CmsModuleKey): ModuleComponentLoader | undefined {
+  return adminLoaders.get(key);
+}
+
+/**
+ * Loads one module's component after hydration and renders it.
+ *
+ * The loader runs in an effect, never during render, so it cannot execute on
+ * the server. `cancelled` guards a module that unmounts before its chunk
+ * arrives, which is ordinary on a fast navigation.
+ */
+function LazyModule({ load }: { load: ModuleComponentLoader }): ReactNode {
+  // Null until the chunk arrives. That is what makes this safe under SSR and
+  // hydration alike: the server renders nothing, the first client pass renders
+  // nothing, and the component only appears once an effect has resolved it. No
+  // separate "hydrated" flag is needed — the effect is the gate.
+  const [Component, setComponent] = useState<ComponentType | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    load().then(
+      (module) => {
+        if (!cancelled) setComponent(() => module.default);
+      },
+      () => {
+        // A module that fails to load must not take the site down with it.
+      },
+    );
+    return () => {
+      cancelled = true;
+    };
+  }, [load]);
+
+  return Component === null ? null : <Component />;
+}
+
+export type CmsModuleRuntimesProps = {
+  /**
+   * Resolved feature flags. Defaults to the registered site config, which is
+   * the code-level answer — deployable and reviewable. A host that already has
+   * database overrides in hand may pass them instead; the public root
+   * deliberately does not fetch them itself, because a blocking read there
+   * would sit on the server-render path of every page.
+   */
+  readonly features?: SiteFeatureFlags;
+};
+
+export function CmsModuleRuntimes({ features }: CmsModuleRuntimesProps): ReactNode {
+  let resolved: SiteFeatureFlags | null = null;
+  try {
+    resolved = features ?? siteConfig().features;
+  } catch {
+    // No site config registered yet: render nothing rather than throwing from
+    // a site's root layout.
+    resolved = null;
+  }
+
+  if (resolved === null) return null;
+
+  return (
+    <>
+      {enabledModuleRuntimes(resolved).map(({ key, load }) => (
+        <LazyModule key={key} load={load} />
+      ))}
+    </>
+  );
+}
+
+export type CmsModuleAdminProps = {
+  readonly moduleKey: CmsModuleKey;
+  /** Rendered while the chunk is in flight. */
+  readonly fallback?: ReactNode;
+};
+
+/**
+ * Mounts a module's backoffice screen, loading its chunk on first visit.
+ *
+ * Kept separate from the public runtime registry so the two are independently
+ * lazy: a public page never asks for the admin chunk, and an administrator
+ * opening the screen never pulls in anything the public site uses.
+ */
+export function CmsModuleAdmin({ moduleKey, fallback = null }: CmsModuleAdminProps): ReactNode {
+  const load = moduleAdminLoader(moduleKey);
+  if (load === undefined) {
+    return (
+      <div className="p-8 text-sm text-ink/50">
+        This module has no backoffice screen registered.
+      </div>
+    );
+  }
+  return <LazyModule load={load} />;
+}

package/src/popups/admin.tsx

@@ -0,0 +1,72 @@
+/**
+ * The Popups backoffice screen.
+ *
+ * Its own module with its own subpath export, not part of `backoffice/routes`:
+ * that barrel eagerly imports every admin view, so listing popups there would
+ * pull the builder and the statistics screen into any chunk that touches the
+ * backoffice. The module host loads this lazily on first visit, and a public
+ * bundle never reaches it.
+ *
+ * The screen itself belongs to the popup package. What this file adds is the
+ * CMS half: the site's forms and pages, discovered through the platform's own
+ * host contract rather than reimplemented per site.
+ */
+import { useMemo } from "react";
+import type { ReactNode } from "react";
+import { PopupAdminApp } from "@bygghammar/lightweight-popup/admin";
+// The backoffice styling ships with the popup package but must be imported by
+// whoever mounts the screen. Importing it HERE — inside the lazily loaded
+// admin module — makes the consumer's bundler attach it to the admin chunk, so
+// a public bundle never carries a byte of it.
+import "@bygghammar/lightweight-popup/admin.css";
+import type { AdminAdapters } from "@bygghammar/lightweight-popup/adapters";
+
+import { useFeatureGate } from "../backoffice/shell/use-resolved-config";
+import { cmsMediaPicker } from "./media-bridge";
+import { ManagedForm } from "../forms/FormRenderer";
+import {
+  cmsFormDirectory,
+  cmsOptInDestinations,
+  cmsPageDirectory,
+} from "./cms-bridges";
+import { popupAdminHost } from "./host";
+
+function PopupsRouteInner(): ReactNode {
+  const host = popupAdminHost();
+
+  const adapters = useMemo<AdminAdapters>(
+    () => ({
+      popups: host.popups,
+      statistics: host.statistics,
+      // The CMS knows its own forms and pages; a host only overrides these when
+      // its content model differs from the platform's.
+      formDirectory: host.formDirectory ?? cmsFormDirectory(),
+      pages: host.pages ?? cmsPageDirectory(),
+      // Only offered when the site actually has destinations: the popup editor
+      // shows no picker at all otherwise, rather than an empty control.
+      optInDestinations: cmsOptInDestinations(),
+      // THE line that makes "Choose from media library" appear. Without it the
+      // popup editor falls back to typing an address, which is what an
+      // administrator was left with before.
+      media: cmsMediaPicker(),
+      forms: {
+        // The builder preview renders the site's real form, so what an editor
+        // checks is what a visitor will see.
+        renderForm: ({ formKey }) => <ManagedForm formKey={formKey} />,
+      },
+    }),
+    [host],
+  );
+
+  return <PopupAdminApp adapters={adapters} />;
+}
+
+/** PopupsRoute guarded by the "popups" module switch. */
+export function PopupsRoute(): ReactNode {
+  const gate = useFeatureGate("popups", "Popups");
+  if (gate) return <>{gate}</>;
+  return <PopupsRouteInner />;
+}
+
+// Default export so the module host can load this screen lazily.
+export default PopupsRoute;

package/src/popups/cms-bridges.ts

@@ -0,0 +1,200 @@
+/**
+ * CMS-side discovery for the popup builder.
+ *
+ * The popup package has no idea what a form or a page is beyond a key and a
+ * path. These adapt what the CMS already knows into those neutral shapes, so
+ * every site using this platform gets working pickers without writing any of
+ * this itself.
+ */
+import type {
+  FormDirectoryPort,
+  HostFormField,
+  HostFormSchema,
+  HostIntegrationTarget,
+  HostPage,
+  OptInDestinationPort,
+  PageDirectoryPort,
+} from "@bygghammar/lightweight-popup/adapters";
+import { fieldTypes } from "../forms/field-sets";
+import { DEFAULT_LOCALE, t } from "../i18n";
+import { backofficeHost } from "../backoffice/routes/host";
+
+type UnknownRecord = Record<string, unknown>;
+
+function asRecords(value: unknown): UnknownRecord[] {
+  return Array.isArray(value)
+    ? (value.filter(
+        (row) => typeof row === "object" && row !== null,
+      ) as UnknownRecord[])
+    : [];
+}
+
+function text(row: UnknownRecord, ...keys: string[]): string | undefined {
+  for (const key of keys) {
+    const value = row[key];
+    if (typeof value === "string" && value.trim() !== "") return value;
+  }
+  return undefined;
+}
+
+/**
+ * The site's forms, from the backoffice host's own `listForms`.
+ *
+ * Only the key and a display name cross the boundary. The full row carries
+ * private settings — notification recipients, webhook secrets — that a popup
+ * builder has no business seeing.
+ */
+/**
+ * Field keys that are never a visitor's answer.
+ *
+ * The spam trap is the one that matters: it is a real field on a real form, and
+ * forwarding it would send a receiver evidence of the trap rather than anything
+ * anyone typed. The rest are identifiers and bookkeeping the form system owns.
+ */
+const NEVER_SENDABLE: ReadonlySet<string> = new Set([
+  "hp",
+  "honeypot",
+  "spam_honeypot",
+  "id",
+  "form_key",
+  "created_at",
+  "updated_at",
+  "ip",
+  "ip_address",
+  "user_agent",
+  "referrer",
+  "locale",
+  "client_token",
+  "submission_id",
+]);
+
+/** The human name for a field type, or nothing rather than a raw enum value. */
+function typeLabel(type: unknown): string | undefined {
+  if (typeof type !== "string") return undefined;
+  return fieldTypes().find((entry) => entry.value === type)?.label;
+}
+
+/**
+ * One stored field definition, as the popup builder needs to show it.
+ *
+ * Returns `null` for anything that is not a real, current answer: a field the
+ * editor disabled, one it removed (the key survives as a tombstone so old
+ * submissions still resolve a label), and anything on the list above.
+ */
+function toHostField(field: UnknownRecord): HostFormField | null {
+  const key = text(field, "key");
+  if (key === undefined) return null;
+  if (field["enabled"] === false) return null;
+  if (field["removed"] === true) return null;
+
+  const label = t(
+    (field["label"] ?? null) as never,
+    DEFAULT_LOCALE,
+  );
+  const type = typeLabel(field["type"]);
+  return {
+    key,
+    label: label.trim() === "" ? key : label,
+    ...(type === undefined ? {} : { type }),
+    sendable: !NEVER_SENDABLE.has(key),
+  };
+}
+
+export function cmsFormDirectory(): FormDirectoryPort {
+  const rows = async (): Promise<UnknownRecord[]> =>
+    asRecords(await backofficeHost().fns.listForms());
+
+  return {
+    listForms: async () => {
+      return (await rows()).flatMap((row) => {
+        const key = text(row, "key");
+        if (key === undefined) return [];
+        return [{ key, name: text(row, "name") ?? key }];
+      });
+    },
+
+    /*
+     * The same listing, read for its fields. No second host contract and no
+     * second query: `listForms` already returns each form's merged field
+     * definitions, which is what the forms screen itself renders from.
+     */
+    describeForms: async (keys): Promise<readonly HostFormSchema[]> => {
+      const wanted = new Set(keys);
+      return (await rows()).flatMap((row) => {
+        const key = text(row, "key");
+        if (key === undefined || !wanted.has(key)) return [];
+        const fields = asRecords(row["fields"])
+          .map(toHostField)
+          .filter((field): field is HostFormField => field !== null);
+        return [{ key, name: text(row, "name") ?? key, fields }];
+      });
+    },
+  };
+}
+
+/**
+ * The site's pages, for targeting.
+ *
+ * Returns an empty list rather than throwing when the host has no page module
+ * registered: a missing picker is a smaller problem than a backoffice screen
+ * that will not render.
+ */
+export function cmsPageDirectory(): PageDirectoryPort {
+  return {
+    listPages: async (): Promise<readonly HostPage[]> => {
+      // Read through an index rather than a named property: the host contract
+      // is a closed type that does not currently declare a page listing, and a
+      // site is free to supply one. A host without it simply has no picker.
+      const host = backofficeHost() as unknown as {
+        pages?: { fns?: Record<string, unknown> };
+        fns: Record<string, unknown>;
+      };
+      const listPages = host.pages?.fns?.["listPages"] ?? host.fns["listPages"];
+      if (typeof listPages !== "function") return [];
+      const rows = asRecords(await (listPages as () => Promise<unknown>)());
+      return rows.flatMap((row) => {
+        const key = text(row, "path", "slug", "key");
+        if (key === undefined) return [];
+        const path = key.startsWith("/") ? key : `/${key}`;
+        return [{ path, title: text(row, "title", "name") ?? path }];
+      });
+    },
+  };
+}
+
+/**
+ * The site's opt-in destinations, for the popup editor's picker.
+ *
+ * Only an id, a name and a warning cross the boundary. The endpoint and the
+ * signing secret stay on the server: a popup's configuration is readable by
+ * anyone who can read active popups, so anything more would be published.
+ *
+ * A host with no destination integration gets an empty list rather than an
+ * error, and the popup editor then shows no picker at all.
+ */
+export function cmsOptInDestinations(): OptInDestinationPort {
+  return {
+    listDestinations: async (): Promise<readonly HostIntegrationTarget[]> => {
+      const host = backofficeHost() as unknown as {
+        fns: Record<string, unknown>;
+      };
+      const list = host.fns["listWebhookDestinations"];
+      if (typeof list !== "function") return [];
+
+      const rows = asRecords(await (list as () => Promise<unknown>)());
+      return rows.flatMap((row) => {
+        const id = text(row, "id");
+        if (id === undefined) return [];
+        const name = text(row, "name") ?? id;
+        // A destination whose secret is missing from this environment will fail
+        // at delivery time. Saying so in the picker beats a silent failure.
+        const configured = row["secretConfigured"];
+        const warning =
+          configured === false
+            ? "its signing secret is not set in this environment"
+            : undefined;
+        return [{ id, name, ...(warning === undefined ? {} : { warning }) }];
+      });
+    },
+  };
+}

package/src/popups/destinations.tsx

@@ -0,0 +1,141 @@
+/**
+ * The opt-in destinations screen, bound to the host's server functions.
+ *
+ * The screen itself belongs to the popup package and is provider-neutral;
+ * this is the thin adapter that turns its port into the host's own calls.
+ * Every one of those calls is staff-guarded on the server — nothing here
+ * grants access, it only routes.
+ */
+import type { ReactNode } from "react";
+
+import { DestinationsAdmin } from "@bygghammar/lightweight-popup/admin";
+// The same stylesheet the popup builder imports. This screen is a sibling
+// route, not a child of it, so it loads on its own and has to ask for its own
+// styling — without this it renders as unstyled text, which is exactly what it
+// did the first time anyone could reach it.
+import "@bygghammar/lightweight-popup/admin.css";
+import type {
+  DeliveryRecord,
+  DestinationDraft,
+  DestinationRecord,
+  OptInDestinationAdminPort,
+  TestDeliveryOutcome,
+} from "@bygghammar/lightweight-popup/adapters";
+
+import { backofficeHost } from "../backoffice/routes/host";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+type Fn = (...args: any[]) => Promise<any>;
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+function hostFn(name: string): Fn | undefined {
+  const host = backofficeHost() as unknown as { fns: Record<string, unknown> };
+  const fn = host.fns[name];
+  return typeof fn === "function" ? (fn as Fn) : undefined;
+}
+
+/**
+ * A host that has not registered these functions gets an empty, honest
+ * screen rather than a crash: the site simply has no delivery integration.
+ */
+export function cmsDestinationAdmin(): OptInDestinationAdminPort {
+  return {
+    list: async (): Promise<readonly DestinationRecord[]> => {
+      const fn = hostFn("listWebhookDestinations");
+      if (fn === undefined) return [];
+      return (await fn()) as DestinationRecord[];
+    },
+
+    save: async (draft: DestinationDraft) => {
+      const fn = hostFn("saveWebhookDestination");
+      if (fn === undefined)
+        return {
+          ok: false as const,
+          error: "This site cannot save destinations.",
+        };
+      return (await fn({ data: draft })) as
+        { ok: true; id: string } | { ok: false; error: string };
+    },
+
+    setEnabled: async (id: string, enabled: boolean): Promise<void> => {
+      // Enabling is an ordinary save of one field, so there is no second
+      // server contract to keep in step with the first.
+      const list = hostFn("listWebhookDestinations");
+      const save = hostFn("saveWebhookDestination");
+      if (list === undefined || save === undefined) return;
+      const rows = (await list()) as DestinationRecord[];
+      const row = rows.find((candidate) => candidate.id === id);
+      if (row === undefined) return;
+      await save({
+        data: {
+          id,
+          name: row.name,
+          // Empty means "keep the stored endpoint": the display value has its
+          // query string removed and must never be written back as the real one.
+          endpoint: "",
+          secretRefName: row.secretRefName ?? "",
+          fields: [...row.fields],
+          isActive: enabled,
+          description: row.description,
+        },
+      });
+    },
+
+    remove: async (id: string): Promise<void> => {
+      const fn = hostFn("deleteWebhookDestination");
+      if (fn === undefined) return;
+      await fn({ data: { id } });
+    },
+
+    sendTest: async (id: string): Promise<TestDeliveryOutcome> => {
+      const fn = hostFn("sendTestWebhook");
+      if (fn === undefined) return { ok: false, category: "config-error" };
+      const result = (await fn({ data: { destinationId: id } })) as {
+        ok?: unknown;
+        category?: unknown;
+      };
+      if (result.ok === true) return { ok: true };
+      /*
+       * A host that names no category has told us nothing about where this
+       * failed. Defaulting to "http-error" claimed the endpoint refused the
+       * request — which sent administrators to debug a receiver that had never
+       * been contacted, because a missing signing secret arrives this way.
+       * "config-error" is the honest answer to "something went wrong here".
+       */
+      return {
+        ok: false,
+        category:
+          typeof result.category === "string" && result.category !== ""
+            ? result.category
+            : "config-error",
+      };
+    },
+
+    listDeliveries: async (): Promise<readonly DeliveryRecord[]> => {
+      const fn = hostFn("listWebhookDeliveries");
+      if (fn === undefined) return [];
+      const rows = (await fn({ data: {} })) as Record<string, unknown>[];
+      return rows.map((row) => ({
+        id: String(row["id"]),
+        popupKey: String(row["popup_key"] ?? ""),
+        status: String(row["status"] ?? "pending"),
+        attempts: Number(row["attempts"] ?? 0),
+        httpStatus:
+          typeof row["last_status"] === "number" ? row["last_status"] : null,
+        errorCategory:
+          typeof row["last_error_category"] === "string"
+            ? row["last_error_category"]
+            : null,
+        isTest: row["is_test"] === true,
+        createdAt: String(row["created_at"] ?? ""),
+      }));
+    },
+  };
+}
+
+/** The screen, ready to mount on a route. */
+export function PopupDestinationsView(): ReactNode {
+  return <DestinationsAdmin destinations={cmsDestinationAdmin()} />;
+}
+
+export default PopupDestinationsView;

package/src/popups/host.ts

@@ -0,0 +1,82 @@
+/**
+ * What a site must supply for the Popups module.
+ *
+ * Deliberately small and provider-neutral: the CMS integration knows nothing
+ * about Supabase, PostgREST, RLS or a connection string. A site registers
+ * repositories that speak the popup package's own contracts, and everything
+ * provider-specific stays on the site's side of this boundary.
+ */
+import type {
+  AnalyticsEventRepository,
+  FormDirectoryPort,
+  PageDirectoryPort,
+  PopupAdminRepository,
+  PopupConfigRepository,
+  PopupStatisticsRepository,
+} from "@bygghammar/lightweight-popup/adapters";
+
+/** Repositories the public runtime needs. Read and append only. */
+export type PopupPublicHost = {
+  readonly configs: PopupConfigRepository;
+  readonly analytics: AnalyticsEventRepository;
+};
+
+/**
+ * Repositories the backoffice needs, in addition to the public ones.
+ *
+ * Form and page discovery are optional here because the CMS supplies them
+ * itself — a host only overrides them if its content model differs from the
+ * platform's.
+ */
+export type PopupAdminHost = {
+  readonly popups: PopupAdminRepository;
+  readonly statistics: PopupStatisticsRepository;
+  readonly formDirectory?: FormDirectoryPort;
+  readonly pages?: PageDirectoryPort;
+};
+
+let publicHost: PopupPublicHost | null = null;
+let adminHost: PopupAdminHost | null = null;
+
+/**
+ * Register the site's public popup repositories.
+ *
+ * Called from a site's public bundle. Keeping this separate from the admin
+ * registration is what lets the public site avoid importing anything the
+ * backoffice needs.
+ */
+export function registerPopupPublicHost(
+  host: PopupPublicHost,
+): PopupPublicHost {
+  publicHost = host;
+  return host;
+}
+
+export function registerPopupAdminHost(host: PopupAdminHost): PopupAdminHost {
+  adminHost = host;
+  return host;
+}
+
+export function popupPublicHost(): PopupPublicHost {
+  if (publicHost === null) {
+    throw new Error(
+      "@bygghammar/cms-platform: the Popups module is enabled but no public host is registered. Call registerPopupPublicHost() during site startup.",
+    );
+  }
+  return publicHost;
+}
+
+export function popupAdminHost(): PopupAdminHost {
+  if (adminHost === null) {
+    throw new Error(
+      "@bygghammar/cms-platform: the Popups backoffice is mounted but no admin host is registered. Call registerPopupAdminHost() from the backoffice entry.",
+    );
+  }
+  return adminHost;
+}
+
+/** Test helper. */
+export function clearPopupHosts(): void {
+  publicHost = null;
+  adminHost = null;
+}