@decocms/blocks 7.3.0 → 7.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks",
-  "version": "7.3.0",
+  "version": "7.4.0",
   "type": "module",
   "description": "Deco framework-agnostic core: CMS block resolution, section registry, matchers, portable SDK utilities",
   "repository": {
@@ -46,6 +46,7 @@
     "./sdk/cookie": "./src/sdk/cookie.ts",
     "./sdk/crypto": "./src/sdk/crypto.ts",
     "./sdk/csp": "./src/sdk/csp.ts",
+    "./sdk/detectDevice": "./src/sdk/detectDevice.ts",
     "./sdk/djb2": "./src/sdk/djb2.ts",
     "./sdk/encoding": "./src/sdk/encoding.ts",
     "./sdk/env": "./src/sdk/env.ts",

package/src/cms/sectionMixins.ts

@@ -16,7 +16,7 @@
  * });
  * ```
  */
-import { detectDevice } from "../sdk/useDevice";
+import { detectDevice } from "../sdk/detectDevice";
 import type { SectionLoaderFn } from "./sectionLoaders";
 
 /**

package/src/hooks/Picture.tsx

@@ -1,5 +1,18 @@
+"use client";
+
+// `"use client"` added by @decocms/nextjs's next-smoke fixture build
+// (Picture is reachable from `DecoRootLayout`/`SectionRenderer` via the
+// `hooks/index.ts` barrel, so it is part of the react-server module graph
+// on any Next.js Server Component page even when a given page never
+// renders it): `createContext`/`useContext` are unavailable under React's
+// react-server condition, and Next statically flags any reachable module
+// that imports them without this directive ("You're importing a component
+// that needs createContext...") — same class of fix, same precedent, as
+// `SectionErrorFallback.tsx`'s `"use client"` (class component /
+// componentDidCatch, also client-only).
 import {
 	type ComponentPropsWithoutRef,
+	type Context,
 	createContext,
 	forwardRef,
 	type ReactNode,
@@ -12,13 +25,22 @@ import { type FitOptions, getOptimizedMediaUrl, getSrcSet } from "./Image";
 // Preload context — flows from <Picture preload> to child <Source> elements
 // so each source can inject its own <link rel="preload"> with the correct
 // media query for responsive art direction.
+//
+// Still created LAZILY (first render, not module scope) even under
+// `"use client"`: this keeps a single memoized context object regardless of
+// how many client bundle chunks end up importing this module, rather than
+// relying on module-instance identity across chunks.
 // -------------------------------------------------------------------------
 
 interface PreloadContextValue {
 	preload: boolean;
 }
 
-const PreloadContext = createContext<PreloadContextValue>({ preload: false });
+let _preloadContext: Context<PreloadContextValue> | null = null;
+function getPreloadContext(): Context<PreloadContextValue> {
+	_preloadContext ??= createContext<PreloadContextValue>({ preload: false });
+	return _preloadContext;
+}
 
 // -------------------------------------------------------------------------
 // Source — composable <source> with automatic srcSet optimization and
@@ -41,7 +63,7 @@ export const Source = forwardRef<HTMLSourceElement, SourceProps>(function Source
 	{ src, width, height, fetchPriority, fit = "cover", ...rest },
 	ref,
 ) {
-	const { preload } = useContext(PreloadContext);
+	const { preload } = useContext(getPreloadContext());
 
 	const optimizedSrc = getOptimizedMediaUrl({
 		originalSrc: src,
@@ -93,6 +115,7 @@ export const Picture = forwardRef<HTMLPictureElement, PictureProps>(function Pic
 	ref,
 ) {
 	const value = useMemo(() => ({ preload }), [preload]);
+	const PreloadContext = getPreloadContext();
 
 	return (
 		<PreloadContext.Provider value={value}>

package/src/sdk/detectDevice.ts

@@ -0,0 +1,45 @@
+/**
+ * Pure User-Agent device detection — no React, no RequestContext, no
+ * side effects. Import from HERE (not `./useDevice`) in any module that can
+ * end up in a Next.js App Router **route handler** graph.
+ *
+ * Why this file exists: `useDevice.ts` re-exports the `"use client"`
+ * context half (`./useDeviceContext`, which calls `createContext` at module
+ * scope) for backward compatibility. That re-export is harmless in Server
+ * Components — Next honors the `"use client"` boundary there — but route
+ * handlers (App Router route.ts files) have NO client graph: the directive
+ * is ignored, the module executes against Next's vendored **RSC** React
+ * (`vendored/rsc/react.js`), and that build has no `createContext`, so the
+ * whole route module crashes at evaluation time
+ * ("...createContext is not a function"). `@decocms/nextjs`'s admin route
+ * handlers reach device detection via `cms/sectionMixins.ts`
+ * (`detectDevice`) and `sdk/requestContext.ts` (`isMobileUA`) — both now
+ * import this leaf so their graphs never touch the client context file.
+ */
+
+export type Device = "mobile" | "tablet" | "desktop";
+
+// Android phones include "Mobile" in their UA; Android tablets do not.
+// Check TABLET_RE first so `android(?!.*mobile)` captures tablets before
+// the MOBILE_RE `android.*mobile` branch matches phones.
+export const MOBILE_RE = /mobile|android.*mobile|iphone|ipod|webos|blackberry|opera mini|iemobile/i;
+export const TABLET_RE = /ipad|tablet|kindle|silk|playbook|android(?!.*mobile)/i;
+
+/**
+ * Simple mobile-or-not check (mobile + tablet = true).
+ * Use this for cache key splitting or any context where you
+ * only need a mobile/desktop binary decision.
+ */
+export function isMobileUA(userAgent: string): boolean {
+  return MOBILE_RE.test(userAgent) || TABLET_RE.test(userAgent);
+}
+
+/**
+ * Detect device type from a User-Agent string.
+ * Pure function — no side effects, works anywhere.
+ */
+export function detectDevice(userAgent: string): Device {
+  if (TABLET_RE.test(userAgent)) return "tablet";
+  if (MOBILE_RE.test(userAgent)) return "mobile";
+  return "desktop";
+}

package/src/sdk/env.test.ts

@@ -0,0 +1,33 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+// isDevMode() memoises its result in module-level state after the first
+// call, so each case below resets modules and re-imports fresh to get an
+// unmemoised read for the NODE_ENV value it's stubbing.
+describe("isDevMode", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("is false when NODE_ENV is production", async () => {
+    vi.stubEnv("NODE_ENV", "production");
+    vi.stubEnv("DECO_PREVIEW", "");
+    vi.resetModules();
+    const { isDevMode } = await import("./env");
+    expect(isDevMode()).toBe(false);
+  });
+
+  it("is true when NODE_ENV is development", async () => {
+    vi.stubEnv("NODE_ENV", "development");
+    vi.resetModules();
+    const { isDevMode } = await import("./env");
+    expect(isDevMode()).toBe(true);
+  });
+
+  it("is true when DECO_PREVIEW=true even if NODE_ENV is production", async () => {
+    vi.stubEnv("NODE_ENV", "production");
+    vi.stubEnv("DECO_PREVIEW", "true");
+    vi.resetModules();
+    const { isDevMode } = await import("./env");
+    expect(isDevMode()).toBe(true);
+  });
+});

package/src/sdk/env.ts

@@ -7,12 +7,37 @@
 
 let _isDev: boolean | null = null;
 
+/**
+ * Reads `process.env.NODE_ENV` defensively.
+ *
+ * Wrapped in try/catch so the bare `process` reference can't throw in runtimes
+ * without a `process` global (workerd without `nodejs_compat`). Bundlers that
+ * statically define `process.env.NODE_ENV` (Vite/esbuild in Workers builds —
+ * the same role the old `import.meta.env.DEV` signal served) replace this
+ * expression with a string constant at build time, so no runtime `process`
+ * global is needed in that path at all.
+ */
+function readNodeEnv(): string | undefined {
+  try {
+    return process.env.NODE_ENV;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Returns `true` when running in a development environment.
  *
  * Detection order:
- *  1. `import.meta.env.DEV`  — Vite build-time constant (reliable in Workers/Miniflare)
- *  2. `NODE_ENV=development` — standard Node/Vite convention
+ *  1. `readNodeEnv() === "development"` — bundler-define-friendly read of
+ *     `process.env.NODE_ENV` (see `readNodeEnv` above). This replaces the
+ *     previous `import.meta.env.DEV` signal: `import.meta` is ESM-only syntax
+ *     and is a hard syntax error when CJS consumers (ts-jest) compile this
+ *     raw-TS package, and `env.ts` is reachable via the `@decocms/blocks/sdk`
+ *     barrel, so any such consumer importing the barrel would fail to compile.
+ *  2. `NODE_ENV=development` read off `globalThis.process.env` — standard
+ *     Node/Vite convention, for runtimes where `process` is a real global.
+ *  3. `DECO_PREVIEW=true` — explicit preview-mode override.
  *
  * The result is memoised after the first evaluation.
  */
@@ -21,11 +46,9 @@ export function isDevMode(): boolean {
 
   const env = typeof globalThis.process !== "undefined" ? globalThis.process.env : undefined;
 
-  // Vite statically replaces import.meta.env.DEV at build time (true in dev, false in prod).
-  // In Miniflare/Workers, process.env is unavailable, so this is the reliable signal.
-  const vitaDev = !!(import.meta as unknown as { env?: { DEV?: boolean } }).env?.DEV;
+  const nodeEnvDev = readNodeEnv() === "development";
 
-  _isDev = vitaDev || env?.NODE_ENV === "development" || env?.DECO_PREVIEW === "true";
+  _isDev = nodeEnvDev || env?.NODE_ENV === "development" || env?.DECO_PREVIEW === "true";
 
   return _isDev;
 }

package/src/sdk/requestContext.ts

@@ -87,7 +87,7 @@ export interface RequestContextData {
 // Storage
 // -------------------------------------------------------------------------
 
-import { isMobileUA } from "./useDevice";
+import { isMobileUA } from "./detectDevice";
 
 const BOT_RE =
   /bot|crawl|spider|slurp|bingpreview|facebookexternalhit|linkedinbot|twitterbot|whatsapp|telegram|googlebot|yandex|baidu|duckduck/i;

package/src/sdk/useDevice.ts

@@ -21,52 +21,32 @@
  * ```
  */
 
+import { detectDevice } from "./detectDevice";
 import { RequestContext } from "./requestContext";
 
-export type Device = "mobile" | "tablet" | "desktop";
+// The pure UA-parsing half (`Device`, `MOBILE_RE`, `TABLET_RE`,
+// `isMobileUA`, `detectDevice`) lives in `./detectDevice` — a leaf with no
+// React and no RequestContext — and is re-exported below for backward
+// compatibility. Modules that can land in a Next.js route-handler graph
+// (`cms/sectionMixins.ts`, `sdk/requestContext.ts`) MUST import that leaf
+// directly, not this file: this file also re-exports the `"use client"`
+// context half, which crashes route handlers (see ./detectDevice's doc
+// comment for the vendored-RSC-React mechanics).
+export { type Device, detectDevice, isMobileUA, MOBILE_RE, TABLET_RE } from "./detectDevice";
 
 // `DeviceContext`, the `useDevice()` hook, and `DeviceProvider` live in
 // `./useDeviceContext` (a `"use client"` file) and are re-exported below for
 // full backward compatibility with this module's public API — see that
-// file's doc comment for why the split exists. Everything that stays in
-// *this* file is a plain, hook-free function, safe to import from
-// server-only code (e.g. `cms/sectionMixins.ts`'s `withDevice()`/
-// `withMobile()` loader mixins) without dragging a client-only hook/context
-// boundary into a Server Component's module graph.
+// file's doc comment for why the split exists.
 export { DeviceContext, useDevice, DeviceProvider } from "./useDeviceContext";
 
-// Android phones include "Mobile" in their UA; Android tablets do not.
-// Check TABLET_RE first so `android(?!.*mobile)` captures tablets before
-// the MOBILE_RE `android.*mobile` branch matches phones.
-export const MOBILE_RE = /mobile|android.*mobile|iphone|ipod|webos|blackberry|opera mini|iemobile/i;
-export const TABLET_RE = /ipad|tablet|kindle|silk|playbook|android(?!.*mobile)/i;
-
-/**
- * Simple mobile-or-not check (mobile + tablet = true).
- * Use this for cache key splitting or any context where you
- * only need a mobile/desktop binary decision.
- */
-export function isMobileUA(userAgent: string): boolean {
-  return MOBILE_RE.test(userAgent) || TABLET_RE.test(userAgent);
-}
-
-/**
- * Detect device type from a User-Agent string.
- * Pure function — no side effects, works anywhere.
- */
-export function detectDevice(userAgent: string): Device {
-  if (TABLET_RE.test(userAgent)) return "tablet";
-  if (MOBILE_RE.test(userAgent)) return "mobile";
-  return "desktop";
-}
-
 /**
  * Resolve the current device from the ambient runtime (RequestContext on the
  * server, `navigator.userAgent` on the client) — no React hooks involved.
  * Used both by the plain `check*()` helpers below and by `useDevice()`/
  * `DeviceProvider` in `./useDeviceContext`.
  */
-export function resolveDeviceFromRuntime(): Device {
+export function resolveDeviceFromRuntime(): ReturnType<typeof detectDevice> {
   // Server: use RequestContext UA header
   if (typeof document === "undefined") {
     const ctx = RequestContext.current;