@decocms/blocks 7.0.0

package/src/hooks/RenderSection.tsx

@@ -0,0 +1,91 @@
+import { type ComponentType, lazy, Suspense } from "react";
+import { getSection, getSyncComponent } from "../cms/registry";
+
+const componentCache = new Map<string, ComponentType<any>>();
+
+function getOrCreateLazy(resolveType: string): ComponentType<any> | null {
+  if (componentCache.has(resolveType)) {
+    return componentCache.get(resolveType)!;
+  }
+
+  const loader = getSection(resolveType);
+  if (!loader) return null;
+
+  const LazyComponent = lazy(async () => {
+    const mod = await loader();
+    return { default: mod.default };
+  });
+
+  componentCache.set(resolveType, LazyComponent);
+  return LazyComponent;
+}
+
+interface SectionLike {
+  __resolveType?: string;
+  Component?: ComponentType<any>;
+  props?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * Renders a Section-type prop from the CMS.
+ *
+ * Handles both the old Deco format ({ Component, props }) and
+ * the new @decocms/start format ({ __resolveType, ...props }).
+ *
+ * Sync-first: sections registered as sync (`export const sync = true`,
+ * bundled in the main chunk) render DIRECTLY — no React.lazy / Suspense.
+ * This mirrors DecoPageRenderer's sync-first path and matters twice:
+ *
+ * - SSR streaming: React 19 omits the `<!--$-->` markers when a Suspense
+ *   boundary resolves synchronously, which triggers a hydration mismatch
+ *   (minified #418) — same reason DecoPageRenderer bifurcates.
+ * - SPA commit: the lazy path suspends with `fallback ?? null` while the
+ *   section chunk loads, so a route commit that renders content through
+ *   RenderSection (e.g. a gate section like NotFoundChallenge) paints the
+ *   page with a BLANK middle until the chunk resolves.
+ *
+ * Sites without registered sync components are unaffected:
+ * `getSyncComponent()` returns undefined and the lazy path runs as before.
+ */
+export default function RenderSection({
+  section,
+  fallback,
+}: {
+  section: SectionLike | null | undefined;
+  fallback?: React.ReactNode;
+}) {
+  if (!section) return null;
+
+  if (section.Component) {
+    const { Component, props = {}, ...overrides } = section;
+    const mergedProps = { ...(props as Record<string, unknown>), ...overrides };
+    if (typeof Component === "string") {
+      const Sync = getSyncComponent(Component);
+      if (Sync) return <Sync {...mergedProps} />;
+      const Comp = getOrCreateLazy(Component);
+      if (!Comp) return <>{fallback ?? null}</>;
+      return (
+        <Suspense fallback={fallback ?? null}>
+          <Comp {...mergedProps} />
+        </Suspense>
+      );
+    }
+    return <Component {...mergedProps} />;
+  }
+
+  if (section.__resolveType) {
+    const { __resolveType: _, ...props } = section;
+    const Sync = getSyncComponent(section.__resolveType);
+    if (Sync) return <Sync {...props} />;
+    const Comp = getOrCreateLazy(section.__resolveType);
+    if (!Comp) return <>{fallback ?? null}</>;
+    return (
+      <Suspense fallback={fallback ?? null}>
+        <Comp {...props} />
+      </Suspense>
+    );
+  }
+
+  return null;
+}

package/src/hooks/SectionErrorFallback.tsx

@@ -0,0 +1,97 @@
+"use client";
+
+// `"use client"` added by Phase 2 Task 9 (@decocms/nextjs's next-smoke
+// fixture): `SectionErrorBoundary` is a class component with
+// `componentDidCatch`/`getDerivedStateFromError` — error boundaries require
+// a Client Component in Next's App Router. `SectionRenderer.tsx` wraps
+// every rendered section in this boundary, so without the directive, any
+// Server Component that ends up importing `@decocms/blocks/hooks`
+// transitively fails Next's build. Server Component children passed via
+// `props.children` still render fine — passing already-rendered Server
+// Component output into a Client Component's `children` is a supported RSC
+// composition pattern.
+import { Component, type ErrorInfo, type ReactNode } from "react";
+
+interface ErrorBoundaryProps {
+  sectionKey: string;
+  fallback?: ReactNode;
+  children: ReactNode;
+}
+
+interface ErrorBoundaryState {
+  error: Error | null;
+}
+
+/**
+ * Per-section error boundary that prevents a single broken section
+ * from crashing the entire page.
+ *
+ * In development, shows the error message + stack trace.
+ * In production, renders a silent empty placeholder.
+ */
+export class SectionErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = { error: null };
+  }
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { error };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    console.error(`[CMS] Section "${this.props.sectionKey}" crashed:`, error, info.componentStack);
+  }
+
+  render() {
+    if (this.state.error) {
+      if (this.props.fallback) return this.props.fallback;
+      return (
+        <DefaultSectionErrorFallback error={this.state.error} sectionKey={this.props.sectionKey} />
+      );
+    }
+    return this.props.children;
+  }
+}
+
+function DefaultSectionErrorFallback({ error, sectionKey }: { error: Error; sectionKey: string }) {
+  const isDev = typeof process !== "undefined" && process.env.NODE_ENV === "development";
+
+  if (!isDev) {
+    return <div data-section-error={sectionKey} className="hidden" />;
+  }
+
+  return (
+    <div
+      data-section-error={sectionKey}
+      style={{
+        padding: "16px",
+        margin: "8px 0",
+        border: "2px solid #ef4444",
+        borderRadius: "8px",
+        background: "#fef2f2",
+        fontFamily: "monospace",
+        fontSize: "13px",
+      }}
+    >
+      <div style={{ fontWeight: "bold", color: "#dc2626", marginBottom: "8px" }}>
+        Section Error: {sectionKey}
+      </div>
+      <div style={{ color: "#991b1b" }}>{error.message}</div>
+      {error.stack && (
+        <pre
+          style={{
+            marginTop: "8px",
+            fontSize: "11px",
+            color: "#6b7280",
+            whiteSpace: "pre-wrap",
+            overflow: "auto",
+            maxHeight: "200px",
+          }}
+        >
+          {error.stack}
+        </pre>
+      )}
+    </div>
+  );
+}

package/src/hooks/index.ts

@@ -0,0 +1,4 @@
+export { isBelowFold, LazySection, type LazySectionProps } from "./LazySection";
+export { LiveControls } from "./LiveControls";
+export { SectionErrorBoundary } from "./SectionErrorFallback";
+export { default as RenderSection } from "./RenderSection";

package/src/index.ts

@@ -0,0 +1,8 @@
+// @decocms/blocks — framework-agnostic core
+export * from "./cms/index";
+export * from "./hooks/index";
+export * from "./middleware/index";
+// Observability surface — logger + instrumentWorker live behind their own
+// granular imports too (see `@decocms/blocks/sdk/logger`, `.../observability`).
+export { type Logger, type LogLevel, logger, setLogLevel } from "./sdk/logger";
+export * from "./types/index";

package/src/matchers/builtins.test.ts

@@ -0,0 +1,251 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import type { MatcherContext } from "../cms/resolve";
+import { evaluateMatcher } from "../cms/resolve";
+import { registerBuiltinMatchers } from "./builtins";
+
+const LOCATION_KEY = "website/matchers/location.ts";
+
+beforeEach(() => {
+  registerBuiltinMatchers();
+});
+
+function ctxFromCookies(cookies: Record<string, string>): MatcherContext {
+  return { cookies };
+}
+
+function ctxFromCf(cf: Record<string, unknown>): MatcherContext {
+  const request = new Request("https://example.com/");
+  Object.defineProperty(request, "cf", { value: cf, configurable: true });
+  return { request };
+}
+
+function ctxFromHeaders(headers: Record<string, string>): MatcherContext {
+  return {
+    request: new Request("https://example.com/", { headers }),
+  };
+}
+
+function match(rule: Record<string, unknown>, ctx: MatcherContext): boolean {
+  return evaluateMatcher({ ...rule, __resolveType: LOCATION_KEY }, ctx);
+}
+
+describe("locationMatcher — typed mode (Location)", () => {
+  it("matches when regionCode equals Cloudflare's cf-region-code (SP)", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP", "cf-ipcountry": "BR" });
+    expect(match({ includeLocations: [{ regionCode: "SP" }] }, ctx)).toBe(true);
+  });
+
+  it("matches a raw numeric regionCode (e.g. '47') for parity with deco-cx/apps", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "47", "cf-ipcountry": "BR" });
+    expect(match({ includeLocations: [{ regionCode: "47" }] }, ctx)).toBe(true);
+  });
+
+  it("is case-insensitive on regionCode", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP" });
+    expect(match({ includeLocations: [{ regionCode: "sp" }] }, ctx)).toBe(true);
+  });
+
+  it("does NOT match a region NAME against cf-region-code (parity with original)", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP" });
+    expect(
+      match({ includeLocations: [{ regionCode: "São Paulo" }] }, ctx),
+    ).toBe(false);
+  });
+
+  it("does not match when the region differs", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP" });
+    expect(match({ includeLocations: [{ regionCode: "RJ" }] }, ctx)).toBe(false);
+  });
+
+  it("AND's multiple fields on the same entry (regionCode + country)", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP", "cf-ipcountry": "BR" });
+    expect(
+      match(
+        { includeLocations: [{ regionCode: "SP", country: "BR" }] },
+        ctx,
+      ),
+    ).toBe(true);
+    expect(
+      match(
+        { includeLocations: [{ regionCode: "SP", country: "AR" }] },
+        ctx,
+      ),
+    ).toBe(false);
+  });
+
+  it("resolves country aliases (Brasil → BR)", () => {
+    const ctx = ctxFromHeaders({ "cf-ipcountry": "BR", "cf-region-code": "SP" });
+    expect(
+      match({ includeLocations: [{ country: "Brasil" }] }, ctx),
+    ).toBe(true);
+  });
+
+  it("OR's across multiple include entries", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "RJ" });
+    expect(
+      match(
+        {
+          includeLocations: [{ regionCode: "SP" }, { regionCode: "RJ" }],
+        },
+        ctx,
+      ),
+    ).toBe(true);
+  });
+});
+
+describe("locationMatcher — empty / shape edge cases", () => {
+  it("empty includeLocations array → match (no constraint)", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP" });
+    expect(match({ includeLocations: [] }, ctx)).toBe(true);
+  });
+
+  it("missing includeLocations → match", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP" });
+    expect(match({}, ctx)).toBe(true);
+  });
+
+  it("entry {} inside includeLocations matches everyone (parity with original)", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP", "cf-ipcountry": "BR" });
+    expect(match({ includeLocations: [{}] }, ctx)).toBe(true);
+  });
+
+  it("entry {} inside excludeLocations does NOT exclude anyone (parity)", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP", "cf-ipcountry": "BR" });
+    expect(match({ excludeLocations: [{}] }, ctx)).toBe(true);
+  });
+
+  it("excludeLocations short-circuits over includeLocations", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP" });
+    expect(
+      match(
+        {
+          includeLocations: [{ regionCode: "SP" }],
+          excludeLocations: [{ regionCode: "SP" }],
+        },
+        ctx,
+      ),
+    ).toBe(false);
+  });
+
+  it("includeLocations with [{regionCode}] fails when geo is empty", () => {
+    expect(
+      match({ includeLocations: [{ regionCode: "SP" }] }, {}),
+    ).toBe(false);
+  });
+});
+
+describe("locationMatcher — Map mode (haversine)", () => {
+  it("matches when source coords are within target radius", () => {
+    // Target: São Paulo center, 5km. Source: ~500m away.
+    const ctx = ctxFromHeaders({
+      "cf-iplatitude": "-23.5510",
+      "cf-iplongitude": "-46.6340",
+    });
+    expect(
+      match(
+        { includeLocations: [{ coordinates: "-23.5505,-46.6333,5000" }] },
+        ctx,
+      ),
+    ).toBe(true);
+  });
+
+  it("does NOT match when source coords are outside the radius", () => {
+    // Target: São Paulo, 5km. Source: Rio (~360km away).
+    const ctx = ctxFromHeaders({
+      "cf-iplatitude": "-22.9068",
+      "cf-iplongitude": "-43.1729",
+    });
+    expect(
+      match(
+        { includeLocations: [{ coordinates: "-23.5505,-46.6333,5000" }] },
+        ctx,
+      ),
+    ).toBe(false);
+  });
+
+  it("Map-only rule does NOT match when source has no coordinates", () => {
+    // Deliberate divergence from deco-cx/apps: upstream lets coord-only rules
+    // vacuously pass when the visitor has no lat/lng, which matches every
+    // such visitor — a footgun in production. We require both sides to have
+    // coordinates before the haversine check passes.
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP" });
+    expect(
+      match(
+        { includeLocations: [{ coordinates: "-23.5505,-46.6333,5000" }] },
+        ctx,
+      ),
+    ).toBe(false);
+  });
+
+  it("AND's coordinates with regionCode on the same entry", () => {
+    // Source: SP coords, region=SP.
+    const ctx = ctxFromHeaders({
+      "cf-region-code": "SP",
+      "cf-iplatitude": "-23.5510",
+      "cf-iplongitude": "-46.6340",
+    });
+    // Entry asks for region=SP AND within 5km of SP center — matches.
+    expect(
+      match(
+        {
+          includeLocations: [
+            { regionCode: "SP", coordinates: "-23.5505,-46.6333,5000" },
+          ],
+        },
+        ctx,
+      ),
+    ).toBe(true);
+    // Entry asks for region=SP AND within 5km of Rio — fails on coords.
+    expect(
+      match(
+        {
+          includeLocations: [
+            { regionCode: "SP", coordinates: "-22.9068,-43.1729,5000" },
+          ],
+        },
+        ctx,
+      ),
+    ).toBe(false);
+  });
+});
+
+describe("locationMatcher — data source fallbacks", () => {
+  it("reads from request.cf when headers are absent", () => {
+    const ctx = ctxFromCf({ country: "BR", regionCode: "SP" });
+    expect(match({ includeLocations: [{ regionCode: "SP" }] }, ctx)).toBe(true);
+  });
+
+  it("reads from __cf_geo_* cookies as fallback", () => {
+    const ctx = ctxFromCookies({
+      __cf_geo_country: "BR",
+      __cf_geo_region_code: "SP",
+    });
+    expect(match({ includeLocations: [{ regionCode: "SP" }] }, ctx)).toBe(true);
+  });
+
+  it("decodes URL-encoded cookie values (e.g. city with accent)", () => {
+    const ctx = ctxFromCookies({
+      __cf_geo_country: "BR",
+      __cf_geo_city: encodeURIComponent("São Paulo"),
+    });
+    expect(
+      match({ includeLocations: [{ city: "São Paulo" }] }, ctx),
+    ).toBe(true);
+  });
+
+  it("headers take precedence over request.cf and cookies", () => {
+    const request = new Request("https://example.com/", {
+      headers: { "cf-region-code": "SP" },
+    });
+    Object.defineProperty(request, "cf", {
+      value: { regionCode: "RJ", country: "BR" },
+      configurable: true,
+    });
+    const ctx: MatcherContext = {
+      request,
+      cookies: { __cf_geo_region_code: "MG" },
+    };
+    expect(match({ includeLocations: [{ regionCode: "SP" }] }, ctx)).toBe(true);
+    expect(match({ includeLocations: [{ regionCode: "RJ" }] }, ctx)).toBe(false);
+  });
+});