@decocms/blocks 7.0.0

package/src/sdk/useDevice.ts

@@ -0,0 +1,109 @@
+/**
+ * Server-side device detection via RequestContext.
+ *
+ * @example
+ * ```tsx
+ * // In a section loader or server function:
+ * import { detectDevice } from "@decocms/start/sdk/useDevice";
+ *
+ * export function loader(props: Props, req: Request) {
+ *   const device = detectDevice(req.headers.get("user-agent") ?? "");
+ *   return { ...props, device };
+ * }
+ *
+ * // Or via RequestContext (no request argument needed):
+ * import { useDevice } from "@decocms/start/sdk/useDevice";
+ *
+ * export function loader(props: Props) {
+ *   const device = useDevice();
+ *   return { ...props, isMobile: device === "mobile" };
+ * }
+ * ```
+ */
+
+import { RequestContext } from "./requestContext";
+
+export type Device = "mobile" | "tablet" | "desktop";
+
+// `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.
+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 {
+  // Server: use RequestContext UA header
+  if (typeof document === "undefined") {
+    const ctx = RequestContext.current;
+    if (!ctx) return "desktop";
+    const ua = ctx.request.headers.get("user-agent") ?? "";
+    return detectDevice(ua);
+  }
+  // Client: use navigator.userAgent for consistency with server-side UA detection.
+  // Using viewport width would produce different results between SSR and
+  // hydration (server sees UA, client sees pixels), causing hydration mismatch.
+  const ua = typeof navigator !== "undefined" ? navigator.userAgent : "";
+  return detectDevice(ua);
+}
+
+/**
+ * Check if the current request is from a mobile device.
+ */
+export function checkMobile(): boolean {
+  const ctx = RequestContext.current;
+  if (!ctx) return false;
+  return detectDevice(ctx.request.headers.get("user-agent") ?? "") === "mobile";
+}
+
+/**
+ * Check if the current request is from a tablet device.
+ */
+export function checkTablet(): boolean {
+  const ctx = RequestContext.current;
+  if (!ctx) return false;
+  return detectDevice(ctx.request.headers.get("user-agent") ?? "") === "tablet";
+}
+
+/**
+ * Check if the current request is from a desktop device.
+ */
+export function checkDesktop(): boolean {
+  const ctx = RequestContext.current;
+  if (!ctx) return true;
+  return detectDevice(ctx.request.headers.get("user-agent") ?? "") === "desktop";
+}

package/src/sdk/useDeviceContext.tsx

@@ -0,0 +1,108 @@
+"use client";
+
+/**
+ * The hook/context half of device detection — split out of `useDevice.ts`
+ * because it uses `createContext`/`useContext`, which Next.js's App Router
+ * (unlike the Vite-based `@decocms/tanstack` binding, and unlike this
+ * package's own Vitest/jsdom unit tests) statically rejects unless the
+ * *file* that calls them carries a `"use client"` directive — Next's RSC
+ * webpack loader errors ("This React Hook only works in a Client
+ * Component") on ANY file reachable from a Server Component's module graph
+ * that calls a client-only hook, even if the actual call site is never
+ * invoked along that particular path.
+ *
+ * That's exactly what happened here: `packages/blocks/src/cms/sectionMixins.ts`
+ * imports only the plain, hook-free `detectDevice()` from `useDevice.ts` for
+ * its `withDevice()`/`withMobile()` section-loader mixins — a 100%
+ * server-side call path (loaders receive a `Request`, never render). But
+ * because `sectionMixins.ts` is pulled in by `cms/index.ts`, which
+ * `createSiteSetup()` (runtime/setup.ts) imports, and a site's `setup.ts` is
+ * typically imported for its side effects from `app/layout.tsx` (a Server
+ * Component under `@decocms/nextjs`), the *whole* `useDevice.ts` file used to
+ * ride along into the server compilation graph — including the
+ * `createContext`/`useContext` calls now isolated in this file, which had no
+ * "use client" directive of their own. `@decocms/nextjs`'s next-smoke fixture
+ * (this plan's Task 9) is the first consumer to hit Next's real RSC
+ * compiler, so this split was never needed before.
+ *
+ * `detectDevice`, `isMobileUA`, `checkMobile/Tablet/Desktop`, and the
+ * `Device` type stay in `useDevice.ts` (no directive, safe to import from
+ * server-only code); `useDevice.ts` re-exports `DeviceContext`/`useDevice`/
+ * `DeviceProvider` from here so the public `@decocms/blocks/sdk/useDevice`
+ * entry point (and every existing consumer, e.g.
+ * `packages/tanstack/src/hooks/DecoPageRenderer.tsx`) is unchanged.
+ */
+import { createContext, createElement, type ReactNode, useContext } from "react";
+import { type Device, resolveDeviceFromRuntime } from "./useDevice";
+
+/**
+ * React context for the resolved device. Populated by `<DeviceProvider>` at
+ * the top of the framework tree (DecoPageRenderer mounts it for sites that
+ * use the standard wiring). Once set, `useDevice()` reads from here in
+ * preference to `AsyncLocalStorage`, which is known to be unreliable across
+ * streaming SSR Suspense boundaries on Cloudflare Workers.
+ */
+export const DeviceContext = createContext<Device | null>(null);
+
+/**
+ * Get the current device type. Works everywhere:
+ * - Server (loader, middleware, server function): reads User-Agent from RequestContext.
+ * - Client (component, event handler): uses `window.innerWidth` breakpoints.
+ *
+ * @example
+ * ```tsx
+ * import { useDevice } from "@decocms/start/sdk/useDevice";
+ *
+ * // In a component:
+ * const device = useDevice(); // "mobile" | "tablet" | "desktop"
+ * ```
+ */
+export function useDevice(): Device {
+  // Prefer the value resolved by <DeviceProvider> at the framework root —
+  // safe across streaming-SSR Suspense boundaries where AsyncLocalStorage
+  // can lose the request context. The try/catch keeps backward compat with
+  // callers outside a React render (loaders, server functions, tests
+  // without the framework root), where useContext throws "Invalid hook
+  // call" — those callers fall through to the original runtime resolution.
+  //
+  // Rules-of-hooks note: `useContext` is called *unconditionally* inside the
+  // try block — exactly once per `useDevice()` invocation. The catch only
+  // fires when there is no React dispatcher at all (outside a render),
+  // never *between* hooks in the same render. Hook order within a component
+  // therefore remains consistent. Callers that conditionally call
+  // `useDevice()` itself were already violating rules of hooks; this PR
+  // doesn't change that.
+  try {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const fromContext = useContext(DeviceContext);
+    if (fromContext) return fromContext;
+  } catch {
+    // Not in a React render — fall through.
+  }
+  return resolveDeviceFromRuntime();
+}
+
+/**
+ * Wraps children in a `DeviceContext` populated by resolving the device once
+ * here, at a point in the React tree where `AsyncLocalStorage` is reliable.
+ * Any descendant calling `useDevice()` reads from this context instead of
+ * re-resolving through ALS — preventing the "wrong device value cached at
+ * the edge" failure mode that produces React #418 hydration mismatches.
+ *
+ * Mount this near the top of the React tree. `DecoPageRenderer` already
+ * mounts it automatically; sites with custom roots can mount it explicitly:
+ *
+ * @example
+ * ```tsx
+ * <DeviceProvider>
+ *   <App />
+ * </DeviceProvider>
+ * ```
+ *
+ * Pass an explicit `value` to override detection (useful for tests or
+ * admin preview where the runtime UA isn't meaningful).
+ */
+export function DeviceProvider(props: { children: ReactNode; value?: Device }): ReactNode {
+  const device = props.value ?? resolveDeviceFromRuntime();
+  return createElement(DeviceContext.Provider, { value: device }, props.children);
+}

package/src/sdk/useId.ts

@@ -0,0 +1,7 @@
+import { useId as useReactId } from "react";
+
+/** Wraps React's useId, stripping colons for safe DOM usage */
+export const useId = () => {
+  const id = useReactId();
+  return id.replace(/:/g, "");
+};

package/src/sdk/useScript.test.ts

@@ -0,0 +1,128 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  HTMX_LEGACY_URL,
+  inlineScript,
+  usePartialSection,
+  useScript,
+  useSection,
+} from "./useScript";
+
+describe("inlineScript", () => {
+  it("returns dangerouslySetInnerHTML with the provided string", () => {
+    const result = inlineScript('alert("hello")');
+    expect(result).toEqual({
+      dangerouslySetInnerHTML: { __html: 'alert("hello")' },
+    });
+  });
+
+  it("handles empty string", () => {
+    const result = inlineScript("");
+    expect(result).toEqual({
+      dangerouslySetInnerHTML: { __html: "" },
+    });
+  });
+
+  it("handles multiline scripts", () => {
+    const js = `
+      const el = document.getElementById("btn");
+      el.addEventListener("click", () => { console.log("clicked"); });
+    `;
+    const result = inlineScript(js);
+    expect(result.dangerouslySetInnerHTML.__html).toBe(js);
+  });
+});
+
+describe("useScript", () => {
+  it("serializes a function into an IIFE string", () => {
+    function greet(name: string) {
+      console.log(name);
+    }
+    const result = useScript(greet, "world");
+    expect(result).toContain("(");
+    expect(result).toContain('"world"');
+    expect(result).toContain("console.log");
+  });
+
+  it("serializes multiple arguments", () => {
+    function add(a: number, b: number) {
+      return a + b;
+    }
+    const result = useScript(add, 1, 2);
+    expect(result).toContain("1,2");
+  });
+
+  it("handles functions with no arguments", () => {
+    function noop() {}
+    const result = useScript(noop);
+    expect(result).toMatch(/^\(.*\)\(\)$/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Legacy HTMX stubs — useSection / usePartialSection
+// ---------------------------------------------------------------------------
+
+describe("useSection / usePartialSection (legacy HTMX stubs)", () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+  let prevNodeEnv: string | undefined;
+
+  beforeEach(() => {
+    // Reset the dedup set so each test sees a fresh warning fire.
+    delete (globalThis as any).__DECO_LEGACY_HTMX_WARNED;
+    prevNodeEnv = process.env.NODE_ENV;
+    process.env.NODE_ENV = "development";
+    warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+    if (prevNodeEnv === undefined) delete process.env.NODE_ENV;
+    else process.env.NODE_ENV = prevNodeEnv;
+  });
+
+  it("useSection returns a stable placeholder URL instead of throwing", () => {
+    expect(useSection()).toBe(HTMX_LEGACY_URL);
+    expect(useSection({ props: { x: 1 } })).toBe(HTMX_LEGACY_URL);
+  });
+
+  it("usePartialSection returns the same placeholder URL", () => {
+    expect(usePartialSection()).toBe(HTMX_LEGACY_URL);
+  });
+
+  it("warns on first call (in development)", () => {
+    useSection();
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy.mock.calls[0][0]).toMatch(/useSection/);
+    expect(warnSpy.mock.calls[0][0]).toMatch(/were removed/);
+    expect(warnSpy.mock.calls[0][0]).toMatch(/htmx-residue/);
+  });
+
+  it("dedups warnings: a second call to the same stub is silent", () => {
+    useSection();
+    useSection();
+    useSection();
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("tracks warnings per-stub: useSection and usePartialSection warn independently", () => {
+    useSection();
+    usePartialSection();
+    expect(warnSpy).toHaveBeenCalledTimes(2);
+    const messages = warnSpy.mock.calls.map((c) => c[0] as string);
+    expect(messages.some((m) => m.includes("useSection"))).toBe(true);
+    expect(messages.some((m) => m.includes("usePartialSection"))).toBe(true);
+  });
+
+  it("does NOT warn in production", () => {
+    process.env.NODE_ENV = "production";
+    useSection();
+    usePartialSection();
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("returns the placeholder URL even in production (still safe to embed)", () => {
+    process.env.NODE_ENV = "production";
+    expect(useSection()).toBe(HTMX_LEGACY_URL);
+    expect(usePartialSection()).toBe(HTMX_LEGACY_URL);
+  });
+});

package/src/sdk/useScript.ts

@@ -0,0 +1,210 @@
+/**
+ * Serializes functions into inline script strings for SSR output.
+ *
+ * Includes lightweight minification (whitespace + comment removal)
+ * with an LRU cache to avoid re-processing the same function bodies.
+ */
+
+// ---------------------------------------------------------------------------
+// LRU cache for minified function bodies
+// ---------------------------------------------------------------------------
+
+const MAX_CACHE_SIZE = 200;
+const minifyCache = new Map<string, string>();
+
+function cacheGet(key: string): string | undefined {
+  const value = minifyCache.get(key);
+  if (value !== undefined) {
+    // Move to end (most recently used)
+    minifyCache.delete(key);
+    minifyCache.set(key, value);
+  }
+  return value;
+}
+
+function cacheSet(key: string, value: string) {
+  if (minifyCache.size >= MAX_CACHE_SIZE) {
+    // Delete oldest entry (first key in insertion order)
+    const oldest = minifyCache.keys().next().value;
+    if (oldest !== undefined) minifyCache.delete(oldest);
+  }
+  minifyCache.set(key, value);
+}
+
+// ---------------------------------------------------------------------------
+// Lightweight minification (no external deps)
+// ---------------------------------------------------------------------------
+
+function minifyJs(code: string): string {
+  return (
+    code
+      // Remove block comments only — line-comment stripping and operator-spacing
+      // collapse are unsafe: they can corrupt string literals containing "//"
+      // or operators, and regex literals whose delimiters look like operators.
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      // Collapse runs of whitespace (spaces, tabs, newlines) to a single space.
+      // This is safe because whitespace inside string/template literals is
+      // preserved as a single space, which is semantically identical.
+      .replace(/\s+/g, " ")
+      .trim()
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Serializes a function and its arguments into a self-executing inline script.
+ *
+ * @deprecated `fn.toString()` produces different output in SSR vs client Vite
+ * builds (React Compiler transforms differ), causing hydration mismatches on
+ * `dangerouslySetInnerHTML.__html`. Use {@link inlineScript} with a plain
+ * string constant instead.
+ *
+ * @example
+ * ```tsx
+ * // BEFORE (causes hydration mismatch):
+ * <script dangerouslySetInnerHTML={{ __html: useScript(onLoad, elementId) }} />
+ *
+ * // AFTER (safe):
+ * <script {...inlineScript(`(${MY_SCRIPT_STRING})("${elementId}")`)} />
+ * ```
+ */
+export function useScript<T extends (...args: any[]) => void>(
+  fn: T,
+  ...args: Parameters<T>
+): string {
+  if (typeof (globalThis as any).__DECO_USE_SCRIPT_WARNED === "undefined") {
+    (globalThis as any).__DECO_USE_SCRIPT_WARNED = new Set<string>();
+  }
+  const warnedSet = (globalThis as any).__DECO_USE_SCRIPT_WARNED as Set<string>;
+  const fnName = fn.name || "anonymous";
+  if (
+    typeof process !== "undefined" &&
+    process.env?.NODE_ENV !== "production" &&
+    !warnedSet.has(fnName)
+  ) {
+    warnedSet.add(fnName);
+    console.warn(
+      `[useScript] Using fn.toString() for "${fnName}". ` +
+        `This may produce different output in SSR vs client builds, causing hydration mismatch. ` +
+        `Consider using inlineScript() with a plain string constant instead.`,
+    );
+  }
+
+  const fnStr = fn.toString();
+  let minified = cacheGet(fnStr);
+  if (minified === undefined) {
+    minified = minifyJs(fnStr);
+    cacheSet(fnStr, minified);
+  }
+
+  const serializedArgs = args.map((a) => JSON.stringify(a)).join(",");
+  return `(${minified})(${serializedArgs})`;
+}
+
+/**
+ * Like useScript, but returns a data: URI suitable for `<script src="...">`.
+ *
+ * @deprecated Same hydration issues as {@link useScript}. Use {@link inlineScript} instead.
+ */
+export function useScriptAsDataURI<T extends (...args: any[]) => void>(
+  fn: T,
+  ...args: Parameters<T>
+): string {
+  const code = useScript(fn, ...args);
+  return `data:text/javascript;charset=utf-8,${encodeURIComponent(code)}`;
+}
+
+/**
+ * Returns props for a `<script>` element with safe inline JavaScript.
+ * Unlike {@link useScript}, this accepts a plain string — no `fn.toString()`
+ * means no SSR/client divergence and no hydration mismatch.
+ *
+ * @example
+ * ```tsx
+ * const SCROLL_SCRIPT = `document.getElementById("btn").addEventListener("click", () => { ... })`;
+ * <script {...inlineScript(SCROLL_SCRIPT)} />
+ *
+ * // With arguments:
+ * const INIT_SCRIPT = (id: string) => `document.getElementById("${id}").dataset.ready = "true"`;
+ * <script {...inlineScript(INIT_SCRIPT("my-element"))} />
+ * ```
+ */
+export function inlineScript(js: string) {
+  return { dangerouslySetInnerHTML: { __html: js } } as const;
+}
+
+/**
+ * @deprecated Removed in TanStack Start.
+ *
+ * The Fresh/Deno HTMX-based partial-section pattern (`useSection` /
+ * `usePartialSection` + `sections/Component.tsx`) does not apply on
+ * Cloudflare Workers and React. Replace call-sites with one of:
+ *
+ *   1. Local React state (`useState` + event handlers) for client-side toggles.
+ *   2. `createServerFn` + `useMutation` for server actions.
+ *   3. Direct `invoke` calls (`~/server/invoke`) for ad-hoc loaders.
+ *
+ * See: deco-to-tanstack-migration skill, "useComponent / partial sections"
+ * section, for the per-pattern recipes.
+ *
+ * ## SSR-safe stub behavior (since 2.27)
+ *
+ * Earlier versions threw on call. That broke SSR for the *entire page* if a
+ * single section still imported `useSection` — even sections that the user
+ * never interacts with (e.g. legacy login form on the homepage). React's
+ * error boundary would catch the throw and degrade the whole route to
+ * client rendering.
+ *
+ * The current behavior:
+ *   - returns a stable placeholder URL (`HTMX_LEGACY_URL`) so it can be
+ *     embedded in `hx-get` / `hx-post` attributes without crashing the
+ *     SSR pass,
+ *   - logs a deduped `console.warn` (in dev only) per call site so the
+ *     migration signal stays loud,
+ *   - the `htmx-residue` audit rule still catalogues every call site for
+ *     systematic rewrite.
+ *
+ * This is a deliberate trade-off: SSR success > strict-throw enforcement.
+ * Audit + skill docs do the enforcement instead.
+ */
+const DEPRECATION_MESSAGE =
+  "[@decocms/start] useSection / usePartialSection were removed. " +
+  "The Fresh/Deno HTMX partial-section pattern does not apply on " +
+  "TanStack Start / Cloudflare Workers. Replace call-sites with " +
+  "createServerFn + useMutation, or local React state. See the " +
+  "deco-to-tanstack-migration skill for per-pattern recipes. " +
+  "Run `deco-post-cleanup` and look for rule [9] htmx-residue to find " +
+  "every site call-site that still depends on this.";
+
+/**
+ * Stable placeholder URL returned by the legacy `useSection` /
+ * `usePartialSection` stubs. Hitting this URL surfaces a clear error.
+ * Exported so frameworks/tests can match against it.
+ */
+export const HTMX_LEGACY_URL = "/__deco_legacy_htmx_section__";
+
+function warnLegacyHtmx(name: string) {
+  if (typeof process !== "undefined" && process.env?.NODE_ENV === "production") {
+    return;
+  }
+  if (typeof (globalThis as any).__DECO_LEGACY_HTMX_WARNED === "undefined") {
+    (globalThis as any).__DECO_LEGACY_HTMX_WARNED = new Set<string>();
+  }
+  const set = (globalThis as any).__DECO_LEGACY_HTMX_WARNED as Set<string>;
+  if (set.has(name)) return;
+  set.add(name);
+  console.warn(`[${name}] ${DEPRECATION_MESSAGE}`);
+}
+
+export function usePartialSection(_props?: Record<string, unknown>): string {
+  warnLegacyHtmx("usePartialSection");
+  return HTMX_LEGACY_URL;
+}
+
+export function useSection(_props?: Record<string, unknown>): string {
+  warnLegacyHtmx("useSection");
+  return HTMX_LEGACY_URL;
+}