@decocms/start 2.2.0 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/src/routes/index.ts

@@ -1,3 +1,5 @@
+export type { PageSeo } from "../cms/resolve";
+export type { Device } from "../sdk/useDevice";
 export {
   decoInvokeRoute,
   decoMetaRoute,
@@ -15,5 +17,8 @@ export {
   setSectionChunkMap,
 } from "./cmsRoute";
 export { CmsPage, NotFoundPage } from "./components";
-export type { PageSeo } from "../cms/resolve";
-export type { Device } from "../sdk/useDevice";
+export {
+  resolveSiteGlobals,
+  type SiteGlobalsLoaderData,
+  withSiteGlobals,
+} from "./withSiteGlobals";

package/src/routes/withSiteGlobals.test.ts

@@ -0,0 +1,272 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { onChangeListeners } = vi.hoisted(() => ({
+  onChangeListeners: [] as Array<() => void>,
+}));
+
+vi.mock("../cms", () => ({
+  loadBlocks: vi.fn(),
+  onChange: vi.fn((listener: () => void) => {
+    onChangeListeners.push(listener);
+  }),
+  resolvePageSections: vi.fn(),
+}));
+
+import { loadBlocks, resolvePageSections } from "../cms";
+import { __resetSiteGlobalsCache, resolveSiteGlobals, withSiteGlobals } from "./withSiteGlobals";
+
+const mockedLoadBlocks = loadBlocks as unknown as ReturnType<typeof vi.fn>;
+const mockedResolvePageSections = resolvePageSections as unknown as ReturnType<typeof vi.fn>;
+
+describe("withSiteGlobals", () => {
+  beforeEach(() => {
+    __resetSiteGlobalsCache();
+    mockedLoadBlocks.mockReset();
+    mockedResolvePageSections.mockReset();
+  });
+
+  describe("resolveSiteGlobals", () => {
+    it("returns empty when there is no Site block", async () => {
+      mockedLoadBlocks.mockReturnValue({});
+      const result = await resolveSiteGlobals();
+      expect(result.resolvedSections).toEqual([]);
+      expect(result.rawRefs).toEqual([]);
+      expect(mockedResolvePageSections).not.toHaveBeenCalled();
+    });
+
+    it("returns empty when Site block has no globals", async () => {
+      mockedLoadBlocks.mockReturnValue({ site: { seo: { title: "x" } } });
+      const result = await resolveSiteGlobals();
+      expect(result.resolvedSections).toEqual([]);
+      expect(result.rawRefs).toEqual([]);
+      expect(mockedResolvePageSections).not.toHaveBeenCalled();
+    });
+
+    it("gathers theme + global + pageSections in order", async () => {
+      mockedLoadBlocks.mockReturnValue({
+        site: {
+          theme: { __resolveType: "Theme" },
+          global: [{ __resolveType: "Analytics" }, { __resolveType: "WishlistProvider" }],
+          pageSections: [{ __resolveType: "Session" }],
+        },
+      });
+      const resolved = [
+        { component: "Theme.tsx", props: {}, key: "k0" },
+        { component: "Analytics.tsx", props: {}, key: "k1" },
+        { component: "Wishlist.tsx", props: {}, key: "k2" },
+        { component: "Session.tsx", props: {}, key: "k3" },
+      ];
+      mockedResolvePageSections.mockResolvedValue(resolved);
+
+      const result = await resolveSiteGlobals();
+
+      expect(result.rawRefs).toEqual([
+        { __resolveType: "Theme" },
+        { __resolveType: "Analytics" },
+        { __resolveType: "WishlistProvider" },
+        { __resolveType: "Session" },
+      ]);
+      expect(result.resolvedSections).toEqual(resolved);
+      expect(mockedResolvePageSections).toHaveBeenCalledTimes(1);
+    });
+
+    it("accepts both `site` (lowercase) and `Site` (PascalCase) block keys", async () => {
+      mockedLoadBlocks.mockReturnValue({
+        Site: { theme: { __resolveType: "Theme" } },
+      });
+      mockedResolvePageSections.mockResolvedValue([
+        { component: "Theme.tsx", props: {}, key: "k0" },
+      ]);
+      const result = await resolveSiteGlobals();
+      expect(result.rawRefs).toEqual([{ __resolveType: "Theme" }]);
+      expect(result.resolvedSections).toHaveLength(1);
+    });
+
+    it("dedupes inflight requests (single resolvePageSections call for parallel callers)", async () => {
+      mockedLoadBlocks.mockReturnValue({
+        site: { global: [{ __resolveType: "Analytics" }] },
+      });
+      let resolveFn!: (v: unknown[]) => void;
+      mockedResolvePageSections.mockImplementation(
+        () =>
+          new Promise((res) => {
+            resolveFn = res as any;
+          }),
+      );
+
+      const a = resolveSiteGlobals();
+      const b = resolveSiteGlobals();
+      resolveFn([{ component: "A.tsx", props: {}, key: "k0" }]);
+      const [ra, rb] = await Promise.all([a, b]);
+
+      expect(ra).toEqual(rb);
+      expect(mockedResolvePageSections).toHaveBeenCalledTimes(1);
+    });
+
+    it("caches across calls within TTL", async () => {
+      mockedLoadBlocks.mockReturnValue({
+        site: { global: [{ __resolveType: "Analytics" }] },
+      });
+      mockedResolvePageSections.mockResolvedValue([{ component: "A.tsx", props: {}, key: "k0" }]);
+
+      await resolveSiteGlobals();
+      await resolveSiteGlobals();
+      await resolveSiteGlobals();
+
+      expect(mockedResolvePageSections).toHaveBeenCalledTimes(1);
+    });
+
+    it("invalidates cache when onChange fires", async () => {
+      mockedLoadBlocks.mockReturnValue({
+        site: { global: [{ __resolveType: "Analytics" }] },
+      });
+      mockedResolvePageSections.mockResolvedValue([{ component: "A.tsx", props: {}, key: "k0" }]);
+
+      await resolveSiteGlobals();
+      expect(mockedResolvePageSections).toHaveBeenCalledTimes(1);
+
+      // Simulate a CMS reload
+      for (const listener of onChangeListeners) listener();
+
+      await resolveSiteGlobals();
+      expect(mockedResolvePageSections).toHaveBeenCalledTimes(2);
+    });
+
+    it("does not cache failures (next call retries)", async () => {
+      mockedLoadBlocks.mockReturnValue({
+        site: { global: [{ __resolveType: "Analytics" }] },
+      });
+      mockedResolvePageSections
+        .mockRejectedValueOnce(new Error("boom"))
+        .mockResolvedValueOnce([{ component: "A.tsx", props: {}, key: "k0" }]);
+
+      const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+      const first = await resolveSiteGlobals();
+      expect(first.resolvedSections).toEqual([]);
+
+      const second = await resolveSiteGlobals();
+      expect(second.resolvedSections).toHaveLength(1);
+      expect(mockedResolvePageSections).toHaveBeenCalledTimes(2);
+      errSpy.mockRestore();
+    });
+  });
+
+  describe("withSiteGlobals wrapper", () => {
+    it("passes through null page (404) without merging globals", async () => {
+      mockedLoadBlocks.mockReturnValue({});
+      const baseLoader = vi.fn().mockResolvedValue(null);
+      const cfg = withSiteGlobals({ loader: baseLoader });
+      const result = await cfg.loader();
+      expect(result).toBeNull();
+    });
+
+    it("merges resolved globals BEFORE page sections", async () => {
+      mockedLoadBlocks.mockReturnValue({
+        site: { theme: { __resolveType: "Theme" } },
+      });
+      mockedResolvePageSections.mockResolvedValue([
+        { component: "Theme.tsx", props: {}, key: "g0" },
+      ]);
+      const baseLoader = vi.fn().mockResolvedValue({
+        resolvedSections: [
+          { component: "Header.tsx", props: {}, key: "p0" },
+          { component: "Hero.tsx", props: {}, key: "p1" },
+        ],
+        // arbitrary other route fields preserved
+        cacheProfile: "static",
+      });
+
+      const cfg = withSiteGlobals({ loader: baseLoader });
+      const result = await cfg.loader();
+
+      expect(result.resolvedSections.map((s: any) => s.component)).toEqual([
+        "Theme.tsx",
+        "Header.tsx",
+        "Hero.tsx",
+      ]);
+      expect(result.cacheProfile).toBe("static");
+    });
+
+    it("dedupes globals whose component already appears on the page", async () => {
+      mockedLoadBlocks.mockReturnValue({
+        site: {
+          global: [{ __resolveType: "Session" }, { __resolveType: "Theme" }],
+        },
+      });
+      mockedResolvePageSections.mockResolvedValue([
+        { component: "Session.tsx", props: {}, key: "g0" },
+        { component: "Theme.tsx", props: {}, key: "g1" },
+      ]);
+      const baseLoader = vi.fn().mockResolvedValue({
+        // Page already mounts Session — global Session should NOT duplicate.
+        resolvedSections: [{ component: "Session.tsx", props: { fromPage: true }, key: "p0" }],
+      });
+
+      const cfg = withSiteGlobals({ loader: baseLoader });
+      const result = await cfg.loader();
+
+      const components = result.resolvedSections.map((s: any) => s.component);
+      // Only one Session, taken from the page (page-level wins).
+      expect(components).toEqual(["Theme.tsx", "Session.tsx"]);
+      const session = result.resolvedSections.find((s: any) => s.component === "Session.tsx");
+      expect(session.props.fromPage).toBe(true);
+    });
+
+    it("dedupes within globals (Session in both site.global AND site.pageSections)", async () => {
+      mockedLoadBlocks.mockReturnValue({
+        site: {
+          global: [{ __resolveType: "Session" }],
+          pageSections: [{ __resolveType: "Session" }],
+        },
+      });
+      mockedResolvePageSections.mockResolvedValue([
+        { component: "Session.tsx", props: { from: "global" }, key: "g0" },
+        { component: "Session.tsx", props: { from: "pageSections" }, key: "g1" },
+      ]);
+      const baseLoader = vi.fn().mockResolvedValue({ resolvedSections: [] });
+
+      const cfg = withSiteGlobals({ loader: baseLoader });
+      const result = await cfg.loader();
+
+      // Only one Session ends up in the final tree (first-wins within globals).
+      expect(result.resolvedSections).toHaveLength(1);
+      expect(result.resolvedSections[0].props.from).toBe("global");
+    });
+
+    it("attaches siteGlobals.rawRefs for site to read head-injection data", async () => {
+      const analyticsRef = {
+        __resolveType: "website/sections/Analytics/Analytics.tsx",
+        trackingIds: ["GTM-ABC"],
+      };
+      mockedLoadBlocks.mockReturnValue({
+        site: { global: [analyticsRef] },
+      });
+      mockedResolvePageSections.mockResolvedValue([]);
+      const baseLoader = vi.fn().mockResolvedValue({ resolvedSections: [] });
+
+      const cfg = withSiteGlobals({ loader: baseLoader });
+      const result = await cfg.loader();
+
+      expect(result.siteGlobals).toEqual({ rawRefs: [analyticsRef] });
+    });
+
+    it("preserves wrapped loader's other return fields", async () => {
+      mockedLoadBlocks.mockReturnValue({});
+      const baseLoader = vi.fn().mockResolvedValue({
+        resolvedSections: [],
+        seo: { title: "Hello" },
+        cacheProfile: "product",
+        device: "mobile",
+        pageUrl: "https://store.com/x",
+      });
+
+      const cfg = withSiteGlobals({ loader: baseLoader });
+      const result = await cfg.loader();
+
+      expect(result.seo).toEqual({ title: "Hello" });
+      expect(result.cacheProfile).toBe("product");
+      expect(result.device).toBe("mobile");
+      expect(result.pageUrl).toBe("https://store.com/x");
+    });
+  });
+});

package/src/routes/withSiteGlobals.ts

@@ -0,0 +1,228 @@
+/**
+ * Site Globals Wrapper
+ *
+ * Opt-in helper that merges sections declared in the CMS `Site` block
+ * (`site.theme + site.global + site.pageSections`) into every page's
+ * `resolvedSections` array.
+ *
+ * Without this wrapper, only `site.seo` is consumed by `cmsRouteConfig` —
+ * the rest of the Site block is dormant CMS data. Sites that declare
+ * theme/analytics/wishlist/help-button blocks at the site level (rather
+ * than per-page) can opt in here to have them rendered automatically.
+ *
+ * @example Site's `src/routes/$.tsx`:
+ * ```ts
+ * import { createFileRoute, notFound } from "@tanstack/react-router";
+ * import { cmsRouteConfig, withSiteGlobals } from "@decocms/start/routes";
+ *
+ * export const Route = createFileRoute("/$")({
+ *   ...withSiteGlobals(cmsRouteConfig({
+ *     siteName: "Bagaggio",
+ *     defaultTitle: "Bagaggio",
+ *   })),
+ *   component: ...,
+ * });
+ * ```
+ */
+
+import type { ResolvedSection } from "../cms";
+import { loadBlocks, onChange, resolvePageSections } from "../cms";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Loader output additions when `withSiteGlobals` is applied. */
+export interface SiteGlobalsLoaderData {
+  /**
+   * Raw refs (before resolution) declared in `site.theme`, `site.global`, and
+   * `site.pageSections`. Includes refs for sections that don't resolve into
+   * the section tree (`SKIP_RESOLVE_TYPES`) — useful for sites that need to
+   * read site-level data (analytics IDs, manifest config, etc.) outside the
+   * normal section render path.
+   *
+   * Ordering: `theme`, then `global`, then `pageSections`.
+   */
+  rawRefs: unknown[];
+}
+
+interface SiteBlock {
+  theme?: unknown;
+  global?: unknown[];
+  pageSections?: unknown[];
+}
+
+interface CacheEntry {
+  resolvedSections: ResolvedSection[];
+  rawRefs: unknown[];
+  expiresAt: number;
+}
+
+// ---------------------------------------------------------------------------
+// Globals resolution (cached, with onChange invalidation)
+// ---------------------------------------------------------------------------
+
+const DEFAULT_CACHE_TTL_MS = 5 * 60_000;
+const cacheTtlMs = DEFAULT_CACHE_TTL_MS;
+
+let cache: CacheEntry | null = null;
+let inflight: Promise<CacheEntry> | null = null;
+
+onChange(() => {
+  cache = null;
+  inflight = null;
+});
+
+function readSiteBlock(): SiteBlock | null {
+  const blocks = loadBlocks();
+  // Block keys vary by site convention — try both common cases.
+  const site = (blocks.site ?? blocks.Site) as SiteBlock | undefined;
+  return site ?? null;
+}
+
+function gatherSectionRefs(site: SiteBlock): unknown[] {
+  const refs: unknown[] = [];
+  if (site.theme) refs.push(site.theme);
+  if (Array.isArray(site.global)) refs.push(...site.global);
+  if (Array.isArray(site.pageSections)) refs.push(...site.pageSections);
+  return refs;
+}
+
+const EMPTY_ENTRY: CacheEntry = {
+  resolvedSections: [],
+  rawRefs: [],
+  expiresAt: Number.POSITIVE_INFINITY, // empty entries don't need refresh
+};
+
+/**
+ * Resolve `site.theme + site.global + site.pageSections` into a list of
+ * `ResolvedSection`s, with in-flight dedup and 5-minute SWR caching.
+ *
+ * Cache is invalidated by `onChange()` from the CMS loader, so admin edits
+ * and decofile reloads are reflected on the next request.
+ *
+ * Exposed as a util so sites can call it directly if they need globals
+ * outside the route loader path (rare).
+ */
+export async function resolveSiteGlobals(): Promise<{
+  resolvedSections: ResolvedSection[];
+  rawRefs: unknown[];
+}> {
+  const now = Date.now();
+  if (cache && cache.expiresAt > now) return cache;
+  if (inflight) return inflight;
+
+  const site = readSiteBlock();
+  if (!site) return EMPTY_ENTRY;
+
+  const rawRefs = gatherSectionRefs(site);
+  if (rawRefs.length === 0) return EMPTY_ENTRY;
+
+  inflight = (async () => {
+    try {
+      const resolvedSections = await resolvePageSections(rawRefs);
+      const entry: CacheEntry = {
+        resolvedSections,
+        rawRefs,
+        expiresAt: Date.now() + cacheTtlMs,
+      };
+      cache = entry;
+      return entry;
+    } catch (err) {
+      console.error("[site-globals] failed to resolve:", err);
+      // Don't cache failures — let the next request retry.
+      return { resolvedSections: [], rawRefs, expiresAt: 0 };
+    } finally {
+      inflight = null;
+    }
+  })();
+
+  return inflight;
+}
+
+// ---------------------------------------------------------------------------
+// Dedupe — collapse global/pageSection components that also exist on the page
+// ---------------------------------------------------------------------------
+
+/**
+ * Filter `globals` to remove sections whose `component` already appears in
+ * `existing` (page-level sections). Page sections take precedence — globals
+ * that conflict are dropped.
+ *
+ * This collapses the common case where a section like `Session` is declared
+ * both in `site.global` and in a page's section list, which would otherwise
+ * render twice.
+ */
+function dedupeGlobals(globals: ResolvedSection[], existing: ResolvedSection[]): ResolvedSection[] {
+  if (globals.length === 0) return [];
+  const seenComponents = new Set<string>();
+  for (const s of existing) {
+    if (typeof s.component === "string") seenComponents.add(s.component);
+  }
+  const result: ResolvedSection[] = [];
+  for (const s of globals) {
+    if (typeof s.component === "string") {
+      if (seenComponents.has(s.component)) continue;
+      seenComponents.add(s.component); // also dedupe within globals (e.g. Session in both site.global AND site.pageSections)
+    }
+    result.push(s);
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Loader wrapper
+// ---------------------------------------------------------------------------
+
+type AnyLoader = (...args: any[]) => Promise<any>;
+
+function wrapLoader<L extends AnyLoader>(loader: L): L {
+  const wrapped: AnyLoader = async (...args: Parameters<L>) => {
+    const [page, globals] = await Promise.all([loader(...args), resolveSiteGlobals()]);
+    if (!page) return page;
+
+    const existing: ResolvedSection[] =
+      (page as { resolvedSections?: ResolvedSection[] }).resolvedSections ?? [];
+    const merged = [...dedupeGlobals(globals.resolvedSections, existing), ...existing];
+
+    return {
+      ...page,
+      resolvedSections: merged,
+      siteGlobals: { rawRefs: globals.rawRefs } satisfies SiteGlobalsLoaderData,
+    };
+  };
+  return wrapped as L;
+}
+
+// ---------------------------------------------------------------------------
+// Public wrapper API
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap a route config (from `cmsRouteConfig` or `cmsHomeRouteConfig`) so
+ * that its loader merges site globals into `resolvedSections` and exposes
+ * the raw site-block refs as `loaderData.siteGlobals.rawRefs`.
+ *
+ * Sites that don't declare `site.theme/site.global/site.pageSections` in
+ * the CMS see no behavior change (the wrapper short-circuits).
+ *
+ * Ordering: globals render BEFORE page sections (theme injects CSS first,
+ * fixed-position helpers mount as asides, etc.). Within globals, ordering
+ * is `theme → global → pageSections`.
+ */
+export function withSiteGlobals<T extends { loader: AnyLoader }>(routeConfig: T): T {
+  return {
+    ...routeConfig,
+    loader: wrapLoader(routeConfig.loader),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Test-only resets (not exported in public types — used by withSiteGlobals.test.ts)
+// ---------------------------------------------------------------------------
+
+/** @internal */
+export function __resetSiteGlobalsCache() {
+  cache = null;
+  inflight = null;
+}