@decocms/start 0.19.0

package/src/sdk/urlUtils.ts

@@ -0,0 +1,117 @@
+/**
+ * URL utility functions.
+ *
+ * Handles UTM parameter stripping for cache-friendly URLs,
+ * canonical URL generation, and other URL manipulation.
+ */
+
+const UTM_PARAMS = new Set([
+  "utm_source",
+  "utm_medium",
+  "utm_campaign",
+  "utm_term",
+  "utm_content",
+  "utmi_campaign",
+  "utmi_page",
+  "utmi_part",
+  "fbclid",
+  "gclid",
+  "gclsrc",
+  "dclid",
+  "msclkid",
+  "twclid",
+  "li_fat_id",
+  "mc_cid",
+  "mc_eid",
+  "ttclid",
+  "srsltid",
+]);
+
+/**
+ * Strip UTM and tracking parameters from a URL.
+ *
+ * Used to normalize URLs for caching -- two requests that differ
+ * only in UTM params should hit the same cache entry.
+ *
+ * @example
+ * ```ts
+ * stripTrackingParams("https://example.com/shoes?color=red&utm_source=google")
+ * // => "https://example.com/shoes?color=red"
+ * ```
+ */
+export function stripTrackingParams(urlString: string): string {
+  try {
+    const url = new URL(urlString);
+    let changed = false;
+
+    for (const param of [...url.searchParams.keys()]) {
+      if (UTM_PARAMS.has(param.toLowerCase())) {
+        url.searchParams.delete(param);
+        changed = true;
+      }
+    }
+
+    return changed ? url.toString() : urlString;
+  } catch {
+    return urlString;
+  }
+}
+
+/**
+ * Strip tracking params from a URL and return just the pathname + non-UTM search.
+ * Useful for cache key generation.
+ */
+export function cleanPathForCacheKey(urlString: string): string {
+  try {
+    const url = new URL(urlString);
+
+    for (const param of [...url.searchParams.keys()]) {
+      if (UTM_PARAMS.has(param.toLowerCase())) {
+        url.searchParams.delete(param);
+      }
+    }
+
+    const search = url.searchParams.toString();
+    return search ? `${url.pathname}?${search}` : url.pathname;
+  } catch {
+    return urlString;
+  }
+}
+
+/**
+ * Build a canonical URL from a request, stripping tracking params
+ * and normalizing the protocol/host.
+ *
+ * @param request - The incoming request
+ * @param baseUrl - Override origin (useful when behind a proxy)
+ */
+export function canonicalUrl(request: Request, baseUrl?: string): string {
+  const url = new URL(request.url);
+  const origin = baseUrl ?? url.origin;
+
+  for (const param of [...url.searchParams.keys()]) {
+    if (UTM_PARAMS.has(param.toLowerCase())) {
+      url.searchParams.delete(param);
+    }
+  }
+
+  const search = url.searchParams.toString();
+  const path = search ? `${url.pathname}?${search}` : url.pathname;
+
+  return `${origin}${path}`;
+}
+
+/**
+ * Check if a URL has any tracking/UTM parameters.
+ */
+export function hasTrackingParams(urlString: string): boolean {
+  try {
+    const url = new URL(urlString);
+    for (const param of url.searchParams.keys()) {
+      if (UTM_PARAMS.has(param.toLowerCase())) return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}

package/src/sdk/useDevice.ts

@@ -0,0 +1,82 @@
+/**
+ * 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";
+
+// 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.
+const MOBILE_RE = /mobile|android.*mobile|iphone|ipod|webos|blackberry|opera mini|iemobile/i;
+const TABLET_RE = /ipad|tablet|kindle|silk|playbook|android(?!.*mobile)/i;
+
+/**
+ * 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";
+}
+
+/**
+ * Get the current device type via RequestContext.
+ *
+ * Must be called within a `RequestContext.run()` scope (i.e., during
+ * request handling). Falls back to "desktop" outside request scope.
+ */
+export function useDevice(): Device {
+  const ctx = RequestContext.current;
+  if (!ctx) return "desktop";
+  const ua = ctx.request.headers.get("user-agent") ?? "";
+  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/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.ts

@@ -0,0 +1,101 @@
+/**
+ * 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.
+ *
+ * @example
+ * ```tsx
+ * <script dangerouslySetInnerHTML={{ __html: useScript(onLoad, elementId, config) }} />
+ * ```
+ */
+export function useScript<T extends (...args: any[]) => void>(
+  fn: T,
+  ...args: Parameters<T>
+): string {
+  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="...">`.
+ */
+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)}`;
+}
+
+/**
+ * Stub -- Deco partial sections don't apply in TanStack Start.
+ * Returns the provided props as-is.
+ */
+export function usePartialSection(props?: Record<string, unknown>) {
+  return props || {};
+}
+
+export function useSection(_props?: Record<string, unknown>) {
+  return "";
+}