@decocms/start 2.26.0 → 2.28.0

package/src/cms/sectionMixins.ts

@@ -74,3 +74,58 @@ export function compose(...mixins: SectionLoaderFn[]): SectionLoaderFn {
     return result;
   };
 }
+
+/**
+ * Wraps a section module's exported `loader` so it can be composed alongside
+ * mixins like {@link withDevice}, {@link withMobile}, {@link withSearchParam}.
+ *
+ * The `modImport` argument is a lazy factory (typically `() => import("~/sections/...")`)
+ * — the module is loaded on first call. If the module does not export a
+ * `loader`, the original `props` are returned unchanged (no-op).
+ *
+ * Why this exists: the migrator and many sites lifted from Fresh declare a
+ * `loader` export on the section file (often re-exported from the inner
+ * component). That loader sets things like `url: req.url`, runs platform
+ * invocations, or calls the section's domain logic. If the section is wired
+ * in `registerSectionLoaders` with mixin-only (e.g. `withSearchParam()`),
+ * the section's own loader is silently *replaced* — its work never runs and
+ * its returned props are dropped.
+ *
+ * Compose this helper FIRST in the chain so mixin-injected props
+ * (`device`, `currentSearchParam`, …) are available to the section's loader,
+ * then the section's loader has the final word over what is returned.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   compose,
+ *   withMobile,
+ *   withSearchParam,
+ *   withSectionLoader,
+ * } from "@decocms/start/cms";
+ *
+ * registerSectionLoaders({
+ *   "site/sections/Product/SearchContainerV2.tsx": compose(
+ *     withMobile(),
+ *     withSearchParam(),
+ *     withSectionLoader(() => import("~/sections/Product/SearchContainerV2")),
+ *   ),
+ * });
+ * ```
+ */
+export function withSectionLoader(
+  modImport: () => Promise<unknown>,
+): SectionLoaderFn {
+  return async (props, req) => {
+    const mod = (await modImport()) as { loader?: unknown } | undefined;
+    const loader = mod?.loader;
+    if (typeof loader !== "function") return props;
+    try {
+      const result = await (loader as SectionLoaderFn)(props, req);
+      return result ?? props;
+    } catch (error) {
+      console.error("[withSectionLoader] section loader threw:", error);
+      return props;
+    }
+  };
+}

package/src/sdk/cn.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { clx, cn } from "./cn";
+
+describe("cn", () => {
+  it("joins strings", () => {
+    expect(cn("a", "b", "c")).toBe("a b c");
+  });
+
+  it("supports conditional objects", () => {
+    expect(cn("a", { b: true, c: false }, "d")).toBe("a b d");
+  });
+
+  it("filters out falsy values", () => {
+    expect(cn("a", null, undefined, false, 0 as any, "b")).toBe("a b");
+  });
+
+  it("merges conflicting Tailwind utilities (last one wins)", () => {
+    expect(cn("p-2", "p-4")).toBe("p-4");
+  });
+
+  it("merges hover variants independently from base utilities", () => {
+    expect(cn("p-2", "hover:p-4")).toBe("p-2 hover:p-4");
+  });
+});
+
+describe("clx (re-exported)", () => {
+  it("filters falsy and joins with single spaces", () => {
+    expect(clx("a", null, "b", undefined, "c")).toBe("a b c");
+  });
+
+  it("does NOT merge conflicting utilities (that's cn's job)", () => {
+    expect(clx("p-2", "p-4")).toBe("p-2 p-4");
+  });
+});

package/src/sdk/cn.ts

@@ -0,0 +1,28 @@
+/**
+ * `cn(...inputs)` — the canonical Tailwind class-name combinator
+ * (clsx + tailwind-merge). Every storefront we audited shipped a
+ * site-local copy of this; we promote it to the framework so sites
+ * can drop the duplicate.
+ *
+ * Behaviour:
+ *   - Accepts the full `clsx` input format (strings, objects, arrays,
+ *     conditionals, falsy values).
+ *   - De-duplicates conflicting Tailwind utilities via `tailwind-merge`
+ *     (e.g. `cn("p-2", "p-4")` → `"p-4"`).
+ *
+ * The simpler `clx` (no tailwind-merge, just `filter+join`) is still
+ * exported from `@decocms/start/sdk/clx` for cases where you want to
+ * keep the literal class string. Re-exported here so a single import
+ * covers both.
+ */
+
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export { clx } from "./clx";
+
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}
+
+export type { ClassValue };

package/src/sdk/cookie.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vitest";
+import {
+  deleteResponseCookie,
+  getCookies,
+  setResponseCookie,
+} from "./cookie";
+
+describe("getCookies", () => {
+  it("returns an empty object when no Cookie header is present", () => {
+    expect(getCookies(new Headers())).toEqual({});
+  });
+
+  it("parses a single cookie", () => {
+    const h = new Headers({ cookie: "session=abc" });
+    expect(getCookies(h)).toEqual({ session: "abc" });
+  });
+
+  it("parses multiple cookies separated by '; '", () => {
+    const h = new Headers({ cookie: "a=1; b=2; c=3" });
+    expect(getCookies(h)).toEqual({ a: "1", b: "2", c: "3" });
+  });
+
+  it("URL-decodes values", () => {
+    const h = new Headers({ cookie: "u=hello%20world" });
+    expect(getCookies(h)).toEqual({ u: "hello world" });
+  });
+
+  it("falls back to the raw value when decoding fails", () => {
+    // Lone '%' is invalid in URL encoding.
+    const h = new Headers({ cookie: "x=100%" });
+    expect(getCookies(h)).toEqual({ x: "100%" });
+  });
+
+  it("ignores entries without an '='", () => {
+    const h = new Headers({ cookie: "garbage; ok=yes" });
+    expect(getCookies(h)).toEqual({ ok: "yes" });
+  });
+
+  it("trims whitespace around names", () => {
+    const h = new Headers({ cookie: " a=1; b=2 " });
+    expect(getCookies(h)).toEqual({ a: "1", b: "2" });
+  });
+});
+
+describe("setResponseCookie", () => {
+  it("appends a Set-Cookie header with the cookie name and value", () => {
+    const h = new Headers();
+    setResponseCookie(h, { name: "session", value: "abc" });
+    expect(h.get("set-cookie")).toBe("session=abc");
+  });
+
+  it("serializes maxAge, path, secure, httpOnly, sameSite, domain", () => {
+    const h = new Headers();
+    setResponseCookie(h, {
+      name: "session",
+      value: "abc",
+      maxAge: 3600,
+      path: "/",
+      domain: "example.com",
+      secure: true,
+      httpOnly: true,
+      sameSite: "Lax",
+    });
+    const value = h.get("set-cookie")!;
+    expect(value).toContain("session=abc");
+    expect(value).toContain("Max-Age=3600");
+    expect(value).toContain("Domain=example.com");
+    expect(value).toContain("Path=/");
+    expect(value).toContain("Secure");
+    expect(value).toContain("HttpOnly");
+    expect(value).toContain("SameSite=Lax");
+  });
+
+  it("serializes expires as a UTC string", () => {
+    const h = new Headers();
+    const date = new Date("2030-01-01T00:00:00Z");
+    setResponseCookie(h, { name: "x", value: "y", expires: date });
+    expect(h.get("set-cookie")).toContain(`Expires=${date.toUTCString()}`);
+  });
+
+  it("appends multiple cookies (does not overwrite the first)", () => {
+    const h = new Headers();
+    setResponseCookie(h, { name: "a", value: "1" });
+    setResponseCookie(h, { name: "b", value: "2" });
+    // Headers.getAll isn't standard; getSetCookie() is the modern API.
+    const all = (h as any).getSetCookie?.() as string[] | undefined;
+    if (all) {
+      expect(all).toEqual(["a=1", "b=2"]);
+    } else {
+      // Fallback: the combined header value should mention both.
+      const v = h.get("set-cookie")!;
+      expect(v).toContain("a=1");
+      expect(v).toContain("b=2");
+    }
+  });
+});
+
+describe("deleteResponseCookie", () => {
+  it("emits a Set-Cookie that expires immediately", () => {
+    const h = new Headers();
+    deleteResponseCookie(h, "session", { path: "/" });
+    const value = h.get("set-cookie")!;
+    expect(value).toContain("session=");
+    expect(value).toContain("Max-Age=0");
+    expect(value).toContain(`Expires=${new Date(0).toUTCString()}`);
+    expect(value).toContain("Path=/");
+  });
+});

package/src/sdk/cookie.ts

@@ -37,3 +37,93 @@ export function decodeCookie(cookieValue: string): any {
     return null;
   }
 }
+
+// ---------------------------------------------------------------------------
+// Server-side cookie helpers — Web-platform / Workers-friendly.
+//
+// These mirror the surface area of Deno's `@std/http/cookie`, which deco
+// storefronts depended on heavily before TanStack/Workers migration. Sites
+// can now import from "@decocms/start/sdk/cookie" instead of shipping a
+// per-site shim or pulling JSR.
+// ---------------------------------------------------------------------------
+
+export interface Cookie {
+  name: string;
+  value: string;
+  expires?: Date | number;
+  maxAge?: number;
+  domain?: string;
+  path?: string;
+  secure?: boolean;
+  httpOnly?: boolean;
+  sameSite?: "Strict" | "Lax" | "None";
+}
+
+/**
+ * Parse all cookies from a Request's `Cookie` header into a plain object.
+ * Returns `{}` when no cookies are present. Values are URL-decoded.
+ *
+ * Equivalent to `getCookies(req.headers)` from `@std/http/cookie`.
+ */
+export function getCookies(headers: Headers): Record<string, string> {
+  const cookie = headers.get("cookie");
+  if (!cookie) return {};
+  const out: Record<string, string> = {};
+  for (const pair of cookie.split(/;\s*/)) {
+    const eq = pair.indexOf("=");
+    if (eq === -1) continue;
+    const name = pair.slice(0, eq).trim();
+    if (!name) continue;
+    const value = pair.slice(eq + 1).trim();
+    try {
+      out[name] = decodeURIComponent(value);
+    } catch {
+      out[name] = value;
+    }
+  }
+  return out;
+}
+
+/**
+ * Serialize a cookie spec and append a `Set-Cookie` header to a Response's
+ * `Headers`. Equivalent to `setCookie(headers, cookie)` from `@std/http/cookie`.
+ *
+ * Note: this uses `headers.append`, not `set`, so multiple cookies stack
+ * correctly (a single `Set-Cookie` header cannot represent multiple cookies).
+ */
+export function setResponseCookie(headers: Headers, cookie: Cookie): void {
+  const parts = [`${cookie.name}=${cookie.value}`];
+  if (cookie.expires !== undefined) {
+    const date = cookie.expires instanceof Date
+      ? cookie.expires
+      : new Date(cookie.expires);
+    parts.push(`Expires=${date.toUTCString()}`);
+  }
+  if (cookie.maxAge !== undefined) parts.push(`Max-Age=${cookie.maxAge}`);
+  if (cookie.domain) parts.push(`Domain=${cookie.domain}`);
+  if (cookie.path) parts.push(`Path=${cookie.path}`);
+  if (cookie.secure) parts.push("Secure");
+  if (cookie.httpOnly) parts.push("HttpOnly");
+  if (cookie.sameSite) parts.push(`SameSite=${cookie.sameSite}`);
+  headers.append("Set-Cookie", parts.join("; "));
+}
+
+/**
+ * Append a delete instruction (`Max-Age=0` + epoch `Expires`) for a cookie.
+ * `path` and `domain` should match the original `setResponseCookie` call to
+ * actually clear the cookie in the browser.
+ */
+export function deleteResponseCookie(
+  headers: Headers,
+  name: string,
+  attributes: { path?: string; domain?: string } = {},
+): void {
+  setResponseCookie(headers, {
+    name,
+    value: "",
+    expires: new Date(0),
+    maxAge: 0,
+    path: attributes.path,
+    domain: attributes.domain,
+  });
+}

package/src/sdk/encoding.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+import {
+  decodeBase64,
+  decodeBase64Url,
+  encodeBase64,
+  encodeBase64Url,
+} from "./encoding";
+
+describe("encodeBase64 / decodeBase64", () => {
+  it("round-trips ASCII strings", () => {
+    const data = "hello, world";
+    const b64 = encodeBase64(data);
+    expect(b64).toBe("aGVsbG8sIHdvcmxk");
+    const decoded = new TextDecoder().decode(decodeBase64(b64));
+    expect(decoded).toBe(data);
+  });
+
+  it("round-trips multi-byte UTF-8", () => {
+    const data = "São Paulo — café ☕";
+    const b64 = encodeBase64(data);
+    const decoded = new TextDecoder().decode(decodeBase64(b64));
+    expect(decoded).toBe(data);
+  });
+
+  it("accepts Uint8Array input", () => {
+    const bytes = new Uint8Array([1, 2, 3, 4, 5]);
+    const b64 = encodeBase64(bytes);
+    expect(decodeBase64(b64)).toEqual(bytes);
+  });
+
+  it("accepts ArrayBuffer input", () => {
+    const buf = new Uint8Array([255, 254, 253]).buffer;
+    const b64 = encodeBase64(buf);
+    expect(Array.from(decodeBase64(b64))).toEqual([255, 254, 253]);
+  });
+
+  it("handles inputs larger than the chunking window", () => {
+    // 0x8000 + 7 bytes — forces the chunking branch.
+    const bytes = new Uint8Array(0x8000 + 7);
+    for (let i = 0; i < bytes.length; i++) bytes[i] = i & 0xff;
+    const b64 = encodeBase64(bytes);
+    expect(decodeBase64(b64)).toEqual(bytes);
+  });
+});
+
+describe("encodeBase64Url / decodeBase64Url", () => {
+  it("uses URL-safe alphabet and strips padding", () => {
+    // Inputs that produce '+', '/', and padding under standard base64.
+    const bytes = new Uint8Array([251, 255, 191, 251, 239, 254]);
+    const standard = encodeBase64(bytes);
+    const url = encodeBase64Url(bytes);
+    // Every '+' becomes '-', '/' becomes '_', trailing '=' is stripped.
+    expect(url).toBe(
+      standard.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""),
+    );
+    expect(url).not.toContain("+");
+    expect(url).not.toContain("/");
+    expect(url).not.toContain("=");
+  });
+
+  it("round-trips through the URL-safe pair", () => {
+    const data = new Uint8Array(64);
+    for (let i = 0; i < data.length; i++) data[i] = (i * 7) & 0xff;
+    expect(decodeBase64Url(encodeBase64Url(data))).toEqual(data);
+  });
+
+  it("decodes inputs missing their padding", () => {
+    // 'a' = 0x61. encodeBase64('a') = 'YQ==', URL form drops to 'YQ'.
+    expect(new TextDecoder().decode(decodeBase64Url("YQ"))).toBe("a");
+  });
+});

package/src/sdk/encoding.ts

@@ -0,0 +1,47 @@
+/**
+ * Web-platform base64 / base64url helpers.
+ *
+ * Replaces the surface area of Deno's `@std/encoding/base64` so deco
+ * storefronts on TanStack/Workers can drop the per-site shim.
+ *
+ * All implementations use the global `btoa` / `atob` (available in Workers,
+ * browsers, and Node 16+) so there is zero runtime dependency.
+ */
+
+function toBytes(data: ArrayBuffer | Uint8Array | string): Uint8Array {
+  if (typeof data === "string") return new TextEncoder().encode(data);
+  if (data instanceof ArrayBuffer) return new Uint8Array(data);
+  return data;
+}
+
+export function encodeBase64(data: ArrayBuffer | Uint8Array | string): string {
+  const bytes = toBytes(data);
+  // Build the binary string in chunks to avoid blowing the call stack on
+  // large inputs (`String.fromCharCode(...bytes)` spreads the entire array).
+  let bin = "";
+  const CHUNK = 0x8000;
+  for (let i = 0; i < bytes.byteLength; i += CHUNK) {
+    bin += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+  }
+  return btoa(bin);
+}
+
+export function decodeBase64(b64: string): Uint8Array {
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+export function encodeBase64Url(data: ArrayBuffer | Uint8Array | string): string {
+  return encodeBase64(data)
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+export function decodeBase64Url(b64url: string): Uint8Array {
+  const padded = b64url.replace(/-/g, "+").replace(/_/g, "/");
+  const padLen = (4 - (padded.length % 4)) % 4;
+  return decodeBase64(padded + "=".repeat(padLen));
+}

package/src/sdk/http.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+import { HttpError, STATUS_CODE, UserAgent } from "./http";
+
+describe("STATUS_CODE", () => {
+  it("exposes common codes with the IANA-canonical names", () => {
+    expect(STATUS_CODE.OK).toBe(200);
+    expect(STATUS_CODE.MovedPermanently).toBe(301);
+    expect(STATUS_CODE.NotFound).toBe(404);
+    expect(STATUS_CODE.TooManyRequests).toBe(429);
+    expect(STATUS_CODE.InternalServerError).toBe(500);
+  });
+
+  it("is readonly at the type level", () => {
+    // @ts-expect-error — assigning into the const map should not type-check.
+    STATUS_CODE.OK = 999;
+    // Even though the assignment is allowed at runtime (frozen-by-convention),
+    // we just want the type to flag it. The value is whatever JS allows.
+    expect(typeof STATUS_CODE.OK).toBe("number");
+  });
+});
+
+describe("UserAgent", () => {
+  it("accepts a string and exposes it via toString", () => {
+    const ua = new UserAgent("Mozilla/5.0 (test)");
+    expect(ua.toString()).toBe("Mozilla/5.0 (test)");
+  });
+
+  it("treats null as an empty UA string", () => {
+    const ua = new UserAgent(null);
+    expect(ua.toString()).toBe("");
+  });
+
+  it("exposes empty browser/os/cpu/device/engine accessors", () => {
+    const ua = new UserAgent("anything");
+    expect(ua.browser).toEqual({});
+    expect(ua.os).toEqual({});
+    expect(ua.cpu).toEqual({});
+    expect(ua.device).toEqual({});
+    expect(ua.engine).toEqual({});
+  });
+});
+
+describe("HttpError", () => {
+  it("captures status and message", () => {
+    const err = new HttpError(404, "Missing");
+    expect(err).toBeInstanceOf(Error);
+    expect(err.name).toBe("HttpError");
+    expect(err.status).toBe(404);
+    expect(err.message).toBe("Missing");
+  });
+
+  it("defaults the message from the status when not provided", () => {
+    const err = new HttpError(503);
+    expect(err.message).toBe("HTTP 503");
+  });
+
+  it("preserves an optional body payload for downstream handling", () => {
+    const body = { code: "rate_limited" };
+    const err = new HttpError(429, "Too Many Requests", body);
+    expect(err.body).toEqual(body);
+  });
+
+  it("supports `instanceof` discrimination", () => {
+    const err = new HttpError(304);
+    function isNotModified(e: unknown): e is HttpError {
+      return e instanceof HttpError && e.status === 304;
+    }
+    expect(isNotModified(err)).toBe(true);
+    expect(isNotModified(new Error("nope"))).toBe(false);
+  });
+});

package/src/sdk/http.ts

@@ -0,0 +1,124 @@
+/**
+ * HTTP constants and small typed helpers — replaces the parts of Deno's
+ * `@std/http` (other than cookies, which live in `./cookie.ts`) that deco
+ * storefronts touch.
+ *
+ * Currently exposes:
+ *   - `STATUS_CODE` — full IANA status-code map (parity with @std/http).
+ *   - `UserAgent`   — minimal class with the same shape; does not parse
+ *                     the UA string (sites only used `.toString()` and
+ *                     basic browser/os accessors in dev). Replace with a
+ *                     real parser like `ua-parser-js` if you actually
+ *                     depend on the parsed fields.
+ */
+
+export const STATUS_CODE = {
+  Continue: 100,
+  SwitchingProtocols: 101,
+  Processing: 102,
+  EarlyHints: 103,
+  OK: 200,
+  Created: 201,
+  Accepted: 202,
+  NonAuthoritativeInfo: 203,
+  NoContent: 204,
+  ResetContent: 205,
+  PartialContent: 206,
+  MultiStatus: 207,
+  AlreadyReported: 208,
+  IMUsed: 226,
+  MultipleChoices: 300,
+  MovedPermanently: 301,
+  Found: 302,
+  SeeOther: 303,
+  NotModified: 304,
+  UseProxy: 305,
+  TemporaryRedirect: 307,
+  PermanentRedirect: 308,
+  BadRequest: 400,
+  Unauthorized: 401,
+  PaymentRequired: 402,
+  Forbidden: 403,
+  NotFound: 404,
+  MethodNotAllowed: 405,
+  NotAcceptable: 406,
+  ProxyAuthRequired: 407,
+  RequestTimeout: 408,
+  Conflict: 409,
+  Gone: 410,
+  LengthRequired: 411,
+  PreconditionFailed: 412,
+  ContentTooLarge: 413,
+  URITooLong: 414,
+  UnsupportedMediaType: 415,
+  RangeNotSatisfiable: 416,
+  ExpectationFailed: 417,
+  Teapot: 418,
+  MisdirectedRequest: 421,
+  UnprocessableEntity: 422,
+  Locked: 423,
+  FailedDependency: 424,
+  TooEarly: 425,
+  UpgradeRequired: 426,
+  PreconditionRequired: 428,
+  TooManyRequests: 429,
+  RequestHeaderFieldsTooLarge: 431,
+  UnavailableForLegalReasons: 451,
+  InternalServerError: 500,
+  NotImplemented: 501,
+  BadGateway: 502,
+  ServiceUnavailable: 503,
+  GatewayTimeout: 504,
+  HTTPVersionNotSupported: 505,
+  VariantAlsoNegotiates: 506,
+  InsufficientStorage: 507,
+  LoopDetected: 508,
+  NotExtended: 510,
+  NetworkAuthenticationRequired: 511,
+} as const;
+
+export type StatusCode = typeof STATUS_CODE[keyof typeof STATUS_CODE];
+
+/**
+ * Minimal stand-in for Deno's `@std/http`'s `UserAgent`. Captures the raw
+ * UA string and exposes the same field shape; does NOT parse. Replace with
+ * a real parser when you start depending on parsed fields.
+ */
+export class UserAgent {
+  ua: string;
+  browser: { name?: string; version?: string };
+  os: { name?: string; version?: string };
+  device: { vendor?: string; model?: string; type?: string };
+  cpu: { architecture?: string };
+  engine: { name?: string; version?: string };
+
+  constructor(ua: string | null) {
+    this.ua = ua ?? "";
+    this.browser = {};
+    this.os = {};
+    this.device = {};
+    this.cpu = {};
+    this.engine = {};
+  }
+
+  toString(): string {
+    return this.ua;
+  }
+}
+
+/**
+ * Lightweight HTTP error class. Drop-in for the `HttpError` shape that
+ * `deco-cx/apps` exposes — sites use it as `error instanceof HttpError &&
+ * error.status === 304` and similar.
+ */
+export class HttpError extends Error {
+  status: number;
+  body?: unknown;
+
+  constructor(status: number, message?: string, body?: unknown) {
+    super(message ?? `HTTP ${status}`);
+    this.name = "HttpError";
+    this.status = status;
+    this.body = body;
+  }
+}